18.2. json — JSON 编码器和解码器
2.6 版的新Function。
_7 由 RFC 7159(取代 RFC 4627)和ECMA-404指定,是一种轻量级的数据交换格式,受JavaScript对象 Literals 语法的启发(尽管它不是 JavaScript [1]的严格子集)。
json公开了标准库marshal和pickle模块的用户熟悉的 API。
编码基本的 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"]'
Compact encoding:
>>> import json
>>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
'[1,2,3,{"4":5,"6":7}]'
Pretty printing:
>>> import json
>>> print json.dumps({'4': 5, '6': 7}, sort_keys=True,
... indent=4, separators=(',', ': '))
{
"4": 5,
"6": 7
}
Decoding 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')
Extending 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', ']']
从 Shell 使用json.tool
进行验证并进行漂亮的打印:
$ 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)
Note
JSON 是YAML 1.2 的子集。该模块的默认设置(特别是默认的* separators *值)产生的 JSON 也是 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 =无*,* encoding =“ utf-8” ,默认=无, sort_keys = False ,** kw *)- 使用此conversion table将* obj 作为 JSON 格式的流序列化为 fp *(支持
.write()
的__)。
- 使用此conversion table将* obj 作为 JSON 格式的流序列化为 fp *(支持
如果* skipkeys *为 true(默认值:False
),那么将跳过不是基本类型(str,unicode,int,long,float,bool,None
)的字典键,而不是引发TypeError。
如果* ensure_ascii 为 true(默认值),则输出中的所有非 ASCII 字符都以\uXXXX
序列进行转义,并且结果是仅由 ASCII 字符组成的str实例。如果 ensure_ascii 为 false,则写入 fp 的某些块可能是unicode个实例。这通常是因为 Importing 包含 unicode 字符串或使用了 encoding *参数。除非fp.write()
明确理解unicode(如codecs.getwriter()一样),否则很可能会导致错误。
如果* check_circular *为 false(默认值:True
),那么将跳过对容器类型的循环引用检查,而循环引用将导致OverflowError(或更糟)。
如果* allow_nan 为 false(默认值:True
),则严格遵循 JSON 规范,序列化范围float值(nan
,inf
,-inf
)之外的值将是ValueError。如果 allow_nan *为 true,则将使用它们的 JavaScript 等效项(NaN
,Infinity
,-Infinity
)。
如果* indent *是一个非负整数,那么 JSON 数组元素和对象成员将以该缩进级别进行漂亮打印。缩进级别 0 或负数将仅插入换行符。 None
(默认设置)选择最紧凑的表示形式。
Note
由于默认的项目分隔符为', '
,所以当指定* indent *时,输出可能包含尾随空格。您可以使用separators=(',', ': ')
来避免这种情况。
如果指定,* separators *应该是(item_separator, key_separator)
Tuples。默认情况下,使用(', ', ': ')
。为了获得最紧凑的 JSON 表示形式,您应该指定(',', ':')
以消除空格。
- encoding *是 str 实例的字符编码,默认为 UTF-8.
如果指定,则* default *应该是一个调用本来无法序列化的对象的函数。它应该返回该对象的 JSON 可编码版本或引发TypeError。如果未指定,则引发TypeError。
如果* sort_keys *为 true(默认值:False
),则字典的输出将按键排序。
要使用自定义的JSONEncoder子类(例如,覆盖default()
方法以序列化其他类型的子类),请使用* cls * kwarg 进行指定;否则使用JSONEncoder。
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 *)- 使用conversion table将* obj 序列化为str格式的 JSON。如果 ensure_ascii *为 false,则结果可能包含非 ASCII 字符,并且返回值可能是unicode实例。
自变量与dump()中的含义相同。
Note
JSON 的键/值对中的键始终为str类型。当字典转换为 JSON 时,字典的所有键都被强制转换为字符串。结果,如果将字典转换为 JSON,然后又转换回字典,则该字典可能不等于原始字典。也就是说,如果 x 具有非字符串键,则为loads(dumps(x)) != x
。
json.
load
(* fp * [,* encoding * [,* cls * [,* object_hook * [,* parse_float * [,* parse_int * [,* parse_constant * [,* object_pairs_hook * [,*** kw *]] ]]]]]]))- 使用此conversion table将* fp *(支持
.read()
的file-like object包含 JSON 文档)反序列化为 Python 对象。
- 使用此conversion table将* fp *(支持
如果* fp 的内容使用 UTF-8 以外的基于 ASCII 的编码进行编码(例如 latin-1),则必须指定适当的 encoding *名称。不允许使用非基于 ASCII 的编码(例如 UCS-2),并且应使用codecs.getreader(encoding)(fp)
包装,或将其简单解码为unicode对象并传递给loads()。
-
object_hook 是一个可选函数,它将被解码的任何对象常量(dict)的结果调用。将使用 object_hook *的返回值代替dict。此Function可用于实现自定义解码器(例如JSON-RPC类提示)。
-
object_pairs_hook 是一个可选函数,将使用对的有序列表解码的任何对象 Literals 的结果调用该函数。将使用 object_pairs_hook 的返回值代替dict。此Function可用于实现依赖于键和值对的解码 Sequences 的自定义解码器(例如collections.OrderedDict()将记住插入 Sequences)。如果还定义了 object_hook ,则 object_pairs_hook *优先。
在 2.7 版中进行了更改:添加了对* object_pairs_hook *的支持。
-
parse_float *(如果指定)将与每个要解码的 JSON float 的字符串一起调用。默认情况下,它等效于
float(num_str)
。这可用于将其他数据类型或解析器用于 JSON 浮点数(例如decimal.Decimal)。 -
parse_int *(如果指定)将与每个要解码的 JSON int 的字符串一起调用。默认情况下,它等效于
int(num_str)
。可以用于将其他数据类型或解析器用于 JSON 整数(例如float)。 -
parse_constant *(如果已指定)将使用以下字符串之一调用:
'-Infinity'
,'Infinity'
,'NaN'
。如果遇到无效的 JSON 数字,则可以使用此方法引发异常。
在 2.7 版中进行了更改:* parse_constant *不再在'null','true','false'上被调用。
要使用自定义的JSONDecoder子类,请使用cls
kwarg 指定它;否则使用JSONDecoder。其他关键字参数将传递给该类的构造函数。
json.
loads
(* s * [,* encoding * [,* cls * [,* object_hook * [,* parse_float * [,* parse_int * [,* parse_constant * [,* object_pairs_hook * [,*** kw *]] ]]]]]]))- 使用此conversion table将* s *(包含 JSON 文档的str或unicode实例)反序列化为 Python 对象。
如果* s 是str实例,并且使用 UTF-8(例如 latin-1)以外的基于 ASCII 的编码进行编码,则必须指定适当的 encoding *名称。不允许使用非基于 ASCII 的编码(例如 UCS-2),并且应首先将其解码为unicode。
其他参数的含义与load()相同。
18.2.2. 编码器和解码器
-
- class *
json.
JSONDecoder
([* encoding * [,* object_hook * [,* parse_float * [,* parse_int * [,* parse_constant * [,* strict * [,* object_pairs_hook *]]]]]]]]]]]]))
- 简单的 JSON 解码器。
- class *
默认情况下在解码中执行以下转换:
JSON | Python |
---|---|
object | dict |
array | list |
string | unicode |
number (int) | int, long |
number (real) | float |
true | True |
false | False |
null | None |
它还将NaN
,Infinity
和-Infinity
理解为它们对应的float
值,这在 JSON 规范之外。
请注意,当前只有 ASCII 工作的超集编码,其他编码的字符串应作为unicode传入。
-
object_hook *(如果指定)将被解码的每个 JSON 对象的结果调用,并且其返回值将代替给定的dict。这可用于提供自定义反序列化(例如,支持 JSON-RPC 类提示)。
-
object_pairs_hook ,如果指定的话,将以对每个有序列对的列表解码的 JSON 对象的结果进行调用。将使用 object_pairs_hook 的返回值代替dict。此Function可用于实现依赖于键和值对的解码 Sequences 的自定义解码器(例如collections.OrderedDict()将记住插入 Sequences)。如果还定义了 object_hook ,则 object_pairs_hook *优先。
在 2.7 版中进行了更改:添加了对* object_pairs_hook *的支持。
-
parse_float *(如果指定)将与每个要解码的 JSON float 的字符串一起调用。默认情况下,它等效于
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'
(制表符),'\n'
,'\r'
和'\0'
。
如果要反序列化的数据不是有效的 JSON 文档,则将引发ValueError。
-
decode
(* s *) -
raw_decode
(* s *)
这可用于从结尾可能有无关数据的字符串中解码 JSON 文档。
-
- class *
json.
JSONEncoder
(([* skipkeys * [,* ensure_ascii * [,* check_circular * [,* allow_nan * [,* sort_keys * [,* indent * [,* separators * [,* encoding * [,* default *]]]]]]]]]]))
- 用于 Python 数据结构的可扩展 JSON 编码器。
- class *
默认情况下支持以下对象和类型:
Python | JSON |
---|---|
dict | object |
list, tuple | array |
str, unicode | string |
整数,长,浮点数 | number |
True | true |
False | false |
None | null |
为了将其扩展为识别其他对象,请子类化并实现default()方法,并使用另一个方法(如果可能的话)为o
返回可序列化的对象,否则应调用超类实现(引发TypeError)。
如果* skipkeys 为 false(默认值),则try对非 str,int,long,float 或None
的键进行编码是TypeError。如果 skipkeys *为 true,则仅跳过此类项目。
如果* ensure_ascii 为 true(默认值),则输出中的所有非 ASCII 字符都以\uXXXX
序列转义,并且结果是str个实例,仅由 ASCII 字符组成。如果 ensure_ascii 为 false,则结果可能是unicode实例。如果 Importing 包含 Unicode 字符串或使用 encoding *参数,通常会发生这种情况。
如果* check_circular *为 true(默认设置),则将在编码过程中检查列表,字典和自定义编码对象的循环引用,以防止无限递归(这将导致OverflowError)。否则,将不会进行此类检查。
如果* allow_nan *为 true(默认设置),则NaN
,Infinity
和-Infinity
将会被编码为此类。此行为不符合 JSON 规范,但与大多数基于 JavaScript 的编码器和解码器一致。否则,对此类浮点数进行编码将是ValueError。
如果* sort_keys *为 true(默认值:False
),则字典的输出将按 key 排序;这对于进行回归测试以确保可以每天比较 JSON 序列化很有用。
如果* indent *是非负整数(默认情况下为None
),则 JSON 数组元素和对象成员将使用该缩进级别进行漂亮打印。缩进级别 0 将仅插入换行符。 None
是最紧凑的表示形式。
Note
由于默认的项目分隔符为', '
,所以当指定* indent *时,输出可能包含尾随空格。您可以使用separators=(',', ': ')
来避免这种情况。
如果指定,* separators *应该是(item_separator, key_separator)
Tuples。默认情况下,使用(', ', ': ')
。为了获得最紧凑的 JSON 表示形式,您应该指定(',', ':')
以消除空格。
如果指定,则* default *应该是一个调用本来无法序列化的对象的函数。它应该返回该对象的 JSON 可编码版本或引发TypeError。如果未指定,则引发TypeError。
如果* encoding *不是None
,那么所有 Importing 字符串将在 JSON 编码之前使用该编码转换为 unicode。默认值为 UTF-8.
default
(* o *)- 在子类中实现此方法,使其返回* o *的可序列化对象,或调用基本实现(引发TypeError)。
例如,要支持任意迭代器,可以实现如下所示的默认值:
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 JSONEncoder.default(self, o)
encode
(* o *)- 返回 Python 数据结构* o *的 JSON 字符串表示形式。例如:
>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'
iterencode
(* o *)- 编码给定的对象* o *,并产生每个可用的字符串表示形式。例如:
for chunk in JSONEncoder().iterencode(bigobject):
mysocket.write(chunk)
18.2.3. 标准符合性和互操作性
JSON 格式由 RFC 7159和ECMA-404指定。本节详细介绍了此模块与 RFC 的符合性级别。为简单起见,不考虑JSONEncoder和JSONDecoder子类以及未明确提及的参数。
该模块不严格遵循 RFC,而是实现了一些扩展,这些扩展是有效的 JavaScript,但不是有效的 JSON。特别是:
-
无限和 NaN 数值被接受并输出;
-
接受对象中的重复名称,并且仅使用姓氏/值对的值。
由于 RFC 允许符合 RFC 的解析器接受不符合 RFC 的 Importing 文本,因此该模块的反序列化器在默认设置下在技术上符合 RFC。
18.2.3.1. 字符编码
RFC 要求使用 UTF-8,UTF-16 或 UTF-32 表示 JSON,建议使用 UTF-8 作为默认值,以实现最大的互操作性。因此,此模块使用 UTF-8 作为其* encoding *参数的默认值。
该模块的解串器仅可直接与 ASCII 兼容的编码一起使用。 UTF-16,UTF-32 和其他与 ASCII 不兼容的编码要求使用反序列化器的* encoding *参数的文档中描述的解决方法。
在 RFC 允许(尽管不是必需的)下,此模块的序列化程序默认情况下设置* ensure_ascii = True *,从而转义输出,以便结果字符串仅包含 ASCII 字符。
RFC 禁止在 JSON 文本的开头添加字节 Sequences 标记(BOM),并且此模块的序列化程序不会在其输出中添加 BOM。 RFC 允许但不要求 JSON 解串器忽略其 Importing 中的初始 BOM。存在初始 BOM 表时,此模块的反序列化器将引发ValueError。
RFC 并未明确禁止 JSON 字符串包含不与有效 Unicode 字符相对应的字节序列(例如,未配对的 UTF-16 替代),但它确实指出它们可能会导致互操作性问题。默认情况下,此模块接受并输出此类序列的代码点(如果存在于原始str中)。
18.2.3.2. 无限和 NaN 数值
RFC 不允许表示无限或 NaN 数字值。尽管如此,默认情况下,此模块仍接受并输出Infinity
,-Infinity
和NaN
,就像它们是有效的 JSON 数字 Literals 值一样:
>>> # 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}
- object_pairs_hook *参数可用于更改此行为。
18.2.3.4. 顶级非对象,非数组值
过时的 RFC 4627指定的 JSON 旧版本要求 JSON 文本的顶级值必须是 JSON 对象或数组(Python dict或list
),并且不能为 JSON 空,布尔值,数字或字符串值。 RFC 7159删除了该限制,并且该模块没有并且从未在其序列化器或反序列化器中实现该限制。
无论如何,为了获得最大的互操作性,您可能希望自己自愿遵守该限制。
18.2.3.5. 实施局限性
某些 JSON 反序列化器实现可能会在以下方面设置限制:
-
可接受的 JSON 文本的大小
-
JSON 对象和数组的最大嵌套级别
-
JSON 数字的范围和精度
-
JSON 字符串的内容和最大长度
除了相关的 Python 数据类型本身或 Python 解释器本身的限制外,此模块没有施加任何此类限制。
序列化为 JSON 时,请注意可能会占用 JSON 的应用程序中的任何此类限制。特别是,通常将 JSON 数字反序列化为 IEEE 754 双精度数字,并因此受到该表示形式的范围和精度限制。当序列化非常大的 Python int值或序列化“外来”数字类型(例如decimal.Decimal)的实例时,这一点尤其重要。
Footnotes
- [1]
- 如RFC 7159 的勘误表中所述,JSON 允许字符串中的原义 U 2028(LINE SEPARATOR)和 U 2029(PARAGRAPH SEPARATOR)字符,而 JavaScript(自 ECMAScript Edition 5.1 起)不允许。