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

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('\u1234'))
"\u1234"
>>> print(json.dumps('\\'))
"\\"
>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
{"a": 0, "b": 0, "c": 0}
>>> from io 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))
{
    "4": 5,
    "6": 7
}

解码 JSON：

>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
['foo', {'bar': ['baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
'"foo\x08ar'
>>> from io import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
['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', ']']

Using json.tool from the shell to validate and pretty-print:

$ echo '{"json":"obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json.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 序列化器。

19.2.1. 基本用法 ¶

json. dump ( obj , fp , skipkeys=False , ensure_ascii=True , check_circular=True , allow_nan=True , cls=None , indent=None , separators=None , 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 , default=None , sort_keys=False , **kw ) ¶

json. load ( fp , cls=None , object_hook=None , parse_float=None , parse_int=None , parse_constant=None , object_pairs_hook=None , **kw ) ¶

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

19.2.2. 编码器和解码器 ¶

class json. JSONDecoder ( object_hook=None , parse_float=None , parse_int=None , parse_constant=None , strict=True , object_pairs_hook=None ) ¶

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

decode ( s ) ¶: 返回 Python 表示对于 s ( str 实例包含 JSON 文档)。

raw_decode ( s ) ¶

解码 JSON 文档从 s ( str 开头采用 JSON 文档) 并返回 2 元素元组的 Python 表示和索引在 s 在哪里结束文档。

这可以用于从末尾可能拥有外来数据的字符串解码 JSON 文档。

class json. JSONEncoder ( skipkeys=False , ensure_ascii=True , check_circular=True , allow_nan=True , sort_keys=False , indent=None , separators=None , default=None ) ¶

Python	JSON
dict	对象
list, tuple	array
str	string
int、float、int- & float-派生 Enums	编号
True	true
False	false
None	null

19.2.3. Standard Compliance and Interoperability ¶

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.

19.2.3.1. Character Encodings ¶

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.

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.

Other than the ensure_ascii parameter, this module is defined strictly in terms of conversion between Python objects and Unicode strings , and thus does not otherwise directly address the issue of character encodings.

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.

19.2.3.2. Infinite and NaN Number Values ¶

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 参数可用于更改此行为。

19.2.3.3. Repeated Names Within an Object ¶

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

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

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

19.2.3.4. Top-level Non-Object, Non-Array Values ¶

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

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

19.2.3.5. Implementation Limitations ¶

某些 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.

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

19.2.1. 基本用法 ¶

19.2.2. 编码器和解码器 ¶

19.2.3. Standard Compliance and Interoperability ¶

19.2.3.1. Character Encodings ¶

19.2.3.2. Infinite and NaN Number Values ¶

19.2.3.3. Repeated Names Within an Object ¶

19.2.3.4. Top-level Non-Object, Non-Array Values ¶

19.2.3.5. Implementation Limitations ¶

内容表

上一话题

下一话题

本页

快速搜索

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

19.2.1. 基本用法 ¶

19.2.2. 编码器和解码器 ¶

19.2.3. Standard Compliance and Interoperability ¶

19.2.3.1. Character Encodings ¶

19.2.3.2. Infinite and NaN Number Values ¶

19.2.3.3. Repeated Names Within an Object ¶

19.2.3.4. Top-level Non-Object, Non-Array Values ¶

19.2.3.5. Implementation Limitations ¶

内容表

上一话题

下一话题

本页

快速搜索

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