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

源代码： Lib/json/__init__.py

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

警告

要谨慎，当剖析来自不可信源的 JSON 数据时。恶意 JSON 字符串可能导致解码器消耗相当多 CPU 和内存资源。推荐限制要剖析的数据大小。

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({'6': 7, '4': 5}, sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}

Specializing JSON object encoding:

>>> import json
>>> def custom_json(obj):
...     if isinstance(obj, complex):
...         return {'__complex__': True, 'real': obj.real, 'imag': obj.imag}
...     raise TypeError(f'Cannot serialize object of {type(obj)}')
...
>>> json.dumps(1 + 2j, default=custom_json)
'{"__complex__": true, "real": 1.0, "imag": 2.0}'

解码 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 super().default(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 -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 序列化器。

注意

默认情况下，此模块的编码器和解码器保留输入和输出的次序。次序才丢失若底层容器是无序的。

基本用法 ¶

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 ) ¶

序列化 obj 作为 JSON (JavaScript 对象表示法) 格式化流到 fp ( .write() 支持像文件对象 ) 使用此转换表 .

若 skipkeys 为 true (默认： False )，则不是基本类型的字典键 ( str , int , float , bool , None ) 会被跳过而不是引发 TypeError .

The json 模块始终产生 str 对象，不是 bytes 对象。因此， fp.write() 必须支持 str 输入。

若 ensure_ascii 为 true (默认)，输出保证所有传入的非 ASCII 字符都会被转义。若 ensure_ascii 为 False，将按原样输出这些字符。

若 check_circular 为 False (默认： True )，那么将跳过容器类型的循环引用校验，且循环引用会导致 RecursionError (或更糟)。

若 allow_nan 为 False (默认： True )，那么它将是 ValueError 序列化超出范围的 float 值 ( nan , inf , -inf ) 按严格合规 JSON 规范。若 allow_nan 为 True，它们的 JavaScript 等价物 ( NaN , Infinity , -Infinity ) 会被使用。

若 indent 是非负整数 (或字符串)，那么将按该缩进级别美化打印 JSON 数组元素和对象成员。缩进级别为 0、负数或 "" 将仅插入换行符。 None (默认) 选择最紧凑表示。使用正整数 indent，每级就缩进多少空格。若 indent 是字符串 (譬如 "\t" )，使用该字符串缩进每个级别。

3.2 版改变：允许字符串对于 indent 除整数个。

若指定， separators 应该为 (item_separator, key_separator) 元组。默认为 (', ', ': ') if indent is None and (',', ': ') 否则。要获得最紧凑 JSON 表示，应指定 (',', ':') 以消除空白。

3.4 版改变：使用 (',', ': ') 作为默认若 indent 不是 None .

若指定， default 应该是要调用函数对于无法被序列化的对象。它应该返回对象的 JSON 可编码版本或引发 TypeError 。若未指定， TypeError 被引发。

若 sort_keys 为 true (默认： False )，那么将按键排序字典的输出。

要使用自定义 JSONEncoder 子类 (如：覆写 default() 方法以序列化额外类型)，指定它采用 cls 关键词自变量；否则 JSONEncoder 被使用。

3.6 版改变：现在所有可选参数是仅关键词 .

注意

不像 pickle and marshal ，JSON 不是框架协议，因此试着序列化多个对象采用重复调用 dump() 使用相同 fp 将导致无效 JSON 文件。

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 ) ¶: 序列化 obj 到 JSON 格式化 str 使用此转换表。自变量拥有相同含义如在 dump() .

注意

JSON 键/值对中的键始终是类型 str 。当将字典转换成 JSON 时，字典的所有键都被强迫为字符串。因此，若字典被转换成 JSON 然后再转换回字典，字典可能不等于原始字典。也就是说， loads(dumps(x)) != x 若 x 拥有非字符串键。

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

反序列化 fp ( .read() 支持文本文件 or 二进制文件包含 JSON 文档) 成 Python 对象使用此转换表 .

object_hook 是将被调用的可选函数采用任何对象文字解码结果 ( dict )。返回值的 object_hook 将被使用而不是 dict 。可以使用此特征实现自定义解码器 (如 JSON-RPC 类提示)。

object_pairs_hook 是将被调用的可选函数采用任何对象文字按有序对列表解码的结果。返回值的 object_pairs_hook 将被使用而不是 dict 。可以使用此特征实现自定义解码器。若 object_hook 也有定义， object_pairs_hook 优先。

3.1 版改变：添加支持 object_pairs_hook .

parse_float is an optional function that will be called with the string of every JSON float to be decoded. By default, this is equivalent to float(num_str) 。可以使用这对 JSON 浮点使用另一数据类型或剖析器 (如 decimal.Decimal ).

parse_int is an optional function that will be called with the string of every JSON int to be decoded. By default, this is equivalent to int(num_str) 。可以使用这对 JSON 整数使用另一数据类型或剖析器 (如 float ).

3.11 版改变：默认 parse_int of int() now limits the maximum length of the integer string via the interpreter’s 整数字符串转换长度局限性 to help avoid denial of service attacks.

parse_constant is an optional function that will be called with one of the following strings: '-Infinity' , 'Infinity' , 'NaN' 。可以使用这引发异常，若遭遇无效 JSON 数字。

3.1 版改变： parse_constant 不再按 null、True、False 被调用。

要使用自定义 JSONDecoder 子类，指定它采用 cls 关键词自变量；否则 JSONDecoder 被使用。额外关键词自变量将被传递给类构造函数。

若要反序列化的数据不是有效 JSON 文档， JSONDecodeError 会被引发。

3.6 版改变：现在所有可选参数是仅关键词 .

3.6 版改变： fp 现在可以是二进制文件。输入编码应该是 UTF-8、UTF-16 或 UTF-32。

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

反序列化 s ( str , bytes or bytearray 实例包含 JSON 文档) 成 Python 对象使用此转换表 .

其它自变量拥有相同含义如在 load() .

若要反序列化的数据不是有效 JSON 文档， JSONDecodeError 会被引发。

3.6 版改变： s 现在可以为类型 bytes or bytearray 。输入编码应该是 UTF-8、UTF-16 或 UTF-32。

3.9 版改变：关键词自变量 encoding 已被移除。

编码器和解码器 ¶

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

简单 JSON 解码器。

默认情况下，当解码时履行下列翻译：

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

它还理解 NaN , Infinity ，和 -Infinity 作为其相应 float 值，这有超出 JSON 规范。

object_hook is an optional function that will be called with the result of every JSON object decoded and its return value will be used in place of the given dict 。可以使用这提供自定义反序列化 (如：支持 JSON-RPC 类提示)。

object_pairs_hook is an optional function that will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook 将被使用而不是 dict 。可以使用此特征实现自定义解码器。若 object_hook 也有定义， object_pairs_hook 优先。

3.1 版改变：添加支持 object_pairs_hook .

parse_constant is an optional function that will be called with one of the following strings: '-Infinity' , 'Infinity' , 'NaN' 。可以使用这引发异常，若遭遇无效 JSON 数字。

若 strict 为 False ( True 是默认)，那么控制字符将被允许在字符串内。在此上下文中的控制字符是字符代码在 0-31 范围的那些字符，包括 '\t' (tab), '\n' , '\r' and '\0' .

若要反序列化的数据不是有效 JSON 文档， JSONDecodeError 会被引发。

3.6 版改变：现在所有参数是仅关键词 .

decode ( s ) ¶

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

JSONDecodeError 会被引发若给定的 JSON 文档无效。

raw_decode ( s ) ¶

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 编码器。

默认情况下，支持下列对象和类型：

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

3.4 版改变：添加支持 int 和 float 派生的枚举类。

要扩展这以识别其它对象，子类并实现 default() 方法采用另一方法返回可序列化对象对于 o 若可能的话，否则，应该调用超类实现 (会引发 TypeError ).

若 skipkeys 为 False (默认)， TypeError will be raised when trying to encode keys that are not str , int , float or None 。若 skipkeys 为 True，简单跳过这样的项。

若 ensure_ascii 为 true (默认)，输出保证所有传入的非 ASCII 字符都会被转义。若 ensure_ascii 为 False，将按原样输出这些字符。

若 check_circular is true (the default), then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause a RecursionError )。否则，不发生这种校验。

若 allow_nan 为 True (默认)，那么 NaN , Infinity ，和 -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

若 sort_keys 为 true (默认： False ), then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

3.2 版改变：允许字符串对于 indent 除整数个。

3.4 版改变：使用 (',', ': ') 作为默认若 indent 不是 None .

若指定， default 应该是要调用函数对于无法被序列化的对象。它应该返回对象的 JSON 可编码版本或引发 TypeError 。若未指定， TypeError 被引发。

3.6 版改变：现在所有参数是仅关键词 .

default ( o ) ¶

encode ( o ) ¶

返回 JSON 字符串表示为 Python 数据结构 o 。例如：

>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

iterencode ( o ) ¶

编码给定对象 o ，并产生可用的每个字符串表示。例如：

for chunk in json.JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

异常 ¶

exception json. JSONDecodeError ( msg , doc , pos ) ¶

子类化的 ValueError 具有下列额外属性：

msg ¶: 未格式化的错误消息。

doc ¶: 正剖析的 JSON 文档。

pos ¶: 起始索引对于 doc 在哪里剖析失败。

lineno ¶: 行对应 pos .

colno ¶: 列对应 pos .

Added in version 3.5.

标准合规和互操作性 ¶

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.

字符编码 ¶

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.

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

对象内的重复名称 ¶

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

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

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

顶层非对象、非数组值 ¶

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

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

实现局限性 ¶

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

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

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

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

命令行接口 ¶

源代码： Lib/json/tool.py

The json.tool 模块提供简单命令行接口来验证和美化打印 JSON 对象。

若可选 infile and outfile 自变量未指定， sys.stdin and sys.stdout 将分别使用：

$ 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)

3.5 版改变：输出现在与输入次序相同。使用 --sort-keys 选项按键的字母顺序对字典输出排序。

命令行选项 ¶

infile ¶

验证 (或美化打印) JSON 文件：

$ python -m json.tool mp_films.json
[
    {
        "title": "And Now for Something Completely Different",
        "year": 1971
    },
    {
        "title": "Monty Python and the Holy Grail",
        "year": 1975
    }
]

若 infile 未指定，读取自 sys.stdin .

outfile ¶: 写入输出为 infile 到给定 outfile 。否则，将它写入 sys.stdout .

--sort-keys ¶

通过键按字母顺序排序字典输出。

Added in version 3.5.

--no-ensure-ascii ¶

禁用非 ASCII 字符的转义，见 json.dumps() 了解更多信息。

Added in version 3.9.

--json-lines ¶

将每一输入行剖析成单独 JSON 对象。

Added in version 3.8.

--indent , --tab , --no-indent , --compact ¶

用于空白控制的相互排斥选项。

Added in version 3.9.

-h , --help ¶: 展示帮助消息。

脚注

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

基本用法 ¶

编码器和解码器 ¶

异常 ¶

标准合规和互操作性 ¶

字符编码 ¶

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

对象内的重复名称 ¶

顶层非对象、非数组值 ¶

实现局限性 ¶

命令行接口 ¶

命令行选项 ¶

内容表

上一话题

下一话题

本页

内容表

上一话题

下一话题

本页

json — JSON 编码器和解码器 ¶

基本用法 ¶

编码器和解码器 ¶

异常 ¶

标准合规和互操作性 ¶

字符编码 ¶

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

对象内的重复名称 ¶

顶层非对象、非数组值 ¶

实现局限性 ¶

命令行接口 ¶

命令行选项 ¶

内容表

上一话题

下一话题

本页

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