18.2. `json` — JSON 编码器和解码器 ¶

2.6 版新增。

JSON (JavaScript 对象表示法) ，指定通过 RFC 7159 (过时 RFC 4627 ) 和通过 ECMA-404 ，是轻量数据互换格式启发自 JavaScript 对象文字句法 (尽管不是严格子集的 JavaScript 1 ).

json 暴露用户熟悉的 API 标准库 marshal and pickle 模块。

编码基本 Python 对象层次结构：

>>> import json
>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
'["foo", {"bar": ["baz", null, 1.0, 2]}]'
>>> print json.dumps("\"foo\bar")
"\"foo\bar"
>>> print json.dumps(u'\u1234')
"\u1234"
>>> print json.dumps('\\')
"\\"
>>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
{"a": 0, "b": 0, "c": 0}
>>> from StringIO import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'

紧凑编码：

>>> import json
>>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
'[1,2,3,{"4":5,"6":7}]'

美化打印：

>>> import json
>>> print json.dumps({'4': 5, '6': 7}, sort_keys=True,
...                  indent=4, separators=(',', ': '))
{
    "4": 5,
    "6": 7
}

解码 JSON：

>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
[u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
u'"foo\x08ar'
>>> from StringIO import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
[u'streaming API']

专攻 JSON 对象解码：

>>> import json
>>> def as_complex(dct):
...     if '__complex__' in dct:
...         return complex(dct['real'], dct['imag'])
...     return dct
...
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
...     object_hook=as_complex)
(1+2j)
>>> import decimal
>>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1')

延伸 JSONEncoder :

>>> import json
>>> class ComplexEncoder(json.JSONEncoder):
...     def default(self, obj):
...         if isinstance(obj, complex):
...             return [obj.real, obj.imag]
...         # Let the base class default method raise the TypeError
...         return json.JSONEncoder.default(self, obj)
...
>>> json.dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'
>>> ComplexEncoder().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncoder().iterencode(2 + 1j))
['[', '2.0', ', ', '1.0', ']']

使用 json.tool 从 Shell 到验证和美化打印：

$ echo '{"json":"obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -mjson.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

注意

JSON 是子集对于 YAML 1.2。由此模块的默认设置产生的 JSON (尤其，默认 separators 值) 还是 YAML 1.0 和 1.1 的子集。因此，此模块也可以用作 YAML 序列化器。

18.2.1. 基本用法 ¶

json. dump ( obj , fp , skipkeys=False , ensure_ascii=True , check_circular=True , allow_nan=True , cls=None , indent=None , separators=None , encoding="utf-8" , default=None , sort_keys=False , **kw ) ¶

json. dumps ( obj , skipkeys=False , ensure_ascii=True , check_circular=True , allow_nan=True , cls=None , indent=None , separators=None , encoding="utf-8" , default=None , sort_keys=False , **kw ) ¶

json. load ( fp [ , encoding [ , cls [ , object_hook [ , parse_float [ , parse_int [ , parse_constant [ , object_pairs_hook [ , **kw ] ] ] ] ] ] ] ] ) ¶

json. loads ( s [ , encoding [ , cls [ , object_hook [ , parse_float [ , parse_int [ , parse_constant [ , object_pairs_hook [ , **kw ] ] ] ] ] ] ] ] ) ¶

18.2.2. 编码器和解码器 ¶

class json. JSONDecoder ( [ encoding [ , object_hook [ , parse_float [ , parse_int [ , parse_constant [ , strict [ , object_pairs_hook ] ] ] ] ] ] ] ) ¶

JSON	Python
对象	dict
array	list
string	unicode
数字 (int)	int, long
数字 (real)	float
true	True
false	False
null	None

decode ( s ) ¶

raw_decode ( s ) ¶

class json. JSONEncoder ( [ skipkeys [ , ensure_ascii [ , check_circular [ , allow_nan [ , sort_keys [ , indent [ , separators [ , encoding [ , default ] ] ] ] ] ] ] ] ] ) ¶

Python	JSON
dict	对象
list, tuple	array
str, unicode	string
int, long, float	编号
True	true
False	false
None	null

default ( o ) ¶

encode ( o ) ¶

iterencode ( o ) ¶

18.2.3. 标准合规和互操作性 ¶

JSON 格式的指定通过 RFC 7159 和通过 ECMA-404 . This section details this module’s level of compliance with the RFC. For simplicity, JSONEncoder and JSONDecoder subclasses, and parameters other than those explicitly mentioned, are not considered.

This module does not comply with the RFC in a strict fashion, implementing some extensions that are valid JavaScript but not valid JSON. In particular:

接受无限和 NaN (非数字) 数值并输出；
Repeated names within an object are accepted, and only the value of the last name-value pair is used.

Since the RFC permits RFC-compliant parsers to accept input texts that are not RFC-compliant, this module’s deserializer is technically RFC-compliant under default settings.

18.2.3.1. 字符编码 ¶

The RFC requires that JSON be represented using either UTF-8, UTF-16, or UTF-32, with UTF-8 being the recommended default for maximum interoperability. Accordingly, this module uses UTF-8 as the default for its encoding 参数。

This module’s deserializer only directly works with ASCII-compatible encodings; UTF-16, UTF-32, and other ASCII-incompatible encodings require the use of workarounds described in the documentation for the deserializer’s encoding 参数。

As permitted, though not required, by the RFC, this module’s serializer sets ensure_ascii=True by default, thus escaping the output so that the resulting strings only contain ASCII characters.

The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text, and this module’s serializer does not add a BOM to its output. The RFC permits, but does not require, JSON deserializers to ignore an initial BOM in their input. This module’s deserializer raises a ValueError when an initial BOM is present.

The RFC does not explicitly forbid JSON strings which contain byte sequences that don’t correspond to valid Unicode characters (e.g. unpaired UTF-16 surrogates), but it does note that they may cause interoperability problems. By default, this module accepts and outputs (when present in the original str ) code points for such sequences.

18.2.3.2. 无限和 NaN (非数字) 数值 ¶

The RFC does not permit the representation of infinite or NaN number values. Despite that, by default, this module accepts and outputs Infinity , -Infinity ，和 NaN as if they were valid JSON number literal values:

>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan

在序列化器中， allow_nan 参数可用于更改此行为。在反序列化器中， parse_constant 参数可用于更改此行为。

18.2.3.3. 对象内的重复名称 ¶

RFC 指定 JSON 对象中的名称应该是唯一的，但未规定如何处理 JSON 对象中的重复名称。默认情况下，此模块不引发异常；相反，它忽略所有除给定名称最后名称-值对外：

>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json)
{u'x': 3}

The object_pairs_hook 参数可用于更改此行为。

18.2.3.4. 顶层非对象、非数组值 ¶

旧版 JSON 的指定通过过时 RFC 4627 要求 JSON 文本顶层值必须是 JSON 对象或数组 (Python dict or list )，且不可以是 JSON null、布尔、数字或字符串值。 RFC 7159 有移除该限定，且此模块没有也从未在其序列化器 (或反序列化器) 中实现该限定。

不管怎样，为最大化互操作，可能希望自己自愿遵守限定。

18.2.3.5. 实现局限性 ¶

某些 JSON 反序列化器实现可能设置以下限制：

接受 JSON 文本的大小
JSON 对象和数组的最大嵌套级别
JSON 数字的范围和精度
JSON 字符串的内容和最大长度

此模块未施加任何此类限制，除相关 Python 数据类型本身或 Python 解释器本身的那些外。

当序列化为 JSON 时，当心可能消耗 JSON 的应用程序中的任何此类局限性。尤其，将 JSON 数字反序列化成 IEEE 754 双精度数字很常见，因此受制于该表示的范围和精度的局限性。这尤其相关当序列化 Python int 值按非常大的幅度，或当序列化 exotic (外来) 数值类型实例，譬如 decimal.Decimal .

脚注

1: 注意 the errata for RFC 7159 , JSON permits literal U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript (as of ECMAScript Edition 5.1) does not.

18.2. json — JSON 编码器和解码器 ¶