json — JSON 编码器和解码器 ¶

基本用法 ¶

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 .

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

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

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

若 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 若指定，将被调用采用每个要解码的 JSON 浮点字符串。默认情况下，这相当于 float(num_str) 。可以使用这对 JSON 浮点使用另一数据类型或剖析器 (如 decimal.Decimal ).

parse_int 若指定，将被调用采用要被解码的每个 JSON int 字符串。默认情况下，这相当于 int(num_str) 。可以使用这对 JSON 整数使用另一数据类型或剖析器 (如 float ).

parse_constant 若指定，将被调用采用下列字符串之一： '-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
object	dict
array	list
string	str
数字 (int)	int
数字 (real)	float
true	True
false	False
null	None

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

object_hook 若指定，将被调用采用每个 JSON 对象的解码结果，且会使用其返回值替代给定 dict 。可以使用这提供自定义反序列化 (如：支持 JSON-RPC 类提示)。

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

3.1 版改变： 添加支持 object_pairs_hook .

parse_float 若指定，将被调用采用每个要解码的 JSON 浮点字符串。默认情况下，这相当于 float(num_str) 。可以使用这对 JSON 浮点使用另一数据类型或剖析器 (如 decimal.Decimal ).

parse_int 若指定，将被调用采用要被解码的每个 JSON int 字符串。默认情况下，这相当于 int(num_str) 。可以使用这对 JSON 整数使用另一数据类型或剖析器 (如 float ).

parse_constant 若指定，将被调用采用下列字符串之一： '-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 ) ¶

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

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

Python	JSON
dict	object
list, tuple	array
str	string
int, float, int- & float-derived Enums	number
True	true
False	false
None	null

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

要扩展这以识别其它对象，子类并实现 default() method with another method that returns a serializable object for o if possible, otherwise it should call the superclass implementation (to raise 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 an OverflowError ). Otherwise, no such check takes place.

若 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.

若 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 被引发。

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

default ( o ) ¶

Implement this method in a subclass such that it returns a serializable object for o ，或调用基实现 (以引发 TypeError ).

例如，要支持任意迭代器，可以实现 default() 像这样：

def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   # Let the base class default method raise the TypeError
   return json.JSONEncoder.default(self, 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 .

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.

>>> # 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
									

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

命令行接口 ¶

源代码： Lib/json/tool.py

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)