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

2.6 版的新Function。

_7 由 RFC 7159(取代 RFC 4627)和ECMA-404指定,是一种轻量级的数据交换格式,受JavaScript对象 Literals 语法的启发(尽管它不是 JavaScript [1]的严格子集)。

json公开了标准库marshalpickle模块的用户熟悉的 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()的__)。

如果* skipkeys *为 true(默认值:False),那么将跳过不是基本类型(strunicodeintlongfloatboolNone)的字典键,而不是引发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值(naninf-inf)之外的值将是ValueError。如果 allow_nan *为 true,则将使用它们的 JavaScript 等效项(NaNInfinity-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

Note

picklemarshal不同,JSON 不是框架协议,因此trypass重复调用dump()来序列化更多对象,并且相同的* fp *将导致生成无效的 JSON 文件。

  • 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 *]] ]]]]]]))

如果* 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 *]] ]]]]]]))

如果* 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 解码器。

默认情况下在解码中执行以下转换:

JSONPython
objectdict
arraylist
stringunicode
number (int)int, long
number (real)float
trueTrue
falseFalse
nullNone

它还将NaNInfinity-Infinity理解为它们对应的float值,这在 JSON 规范之外。

  • encoding *确定用于解释此实例解码的任何str对象的编码(默认为 UTF-8)。解码unicode个对象时无效。

请注意,当前只有 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 *)

    • 返回* s *(包含 JSON 文档的strunicode实例)的 Python 表示形式。
  • raw_decode(* s *)

    • 从* s 解码 JSON 文档(以 JSON 文档开头的strunicode),并返回 2 位 Tuples 的 Python 表示形式和 s *中的索引(文档结束处)。

这可用于从结尾可能有无关数据的字符串中解码 JSON 文档。

    • class * json. JSONEncoder(([* skipkeys * [,* ensure_ascii * [,* check_circular * [,* allow_nan * [,* sort_keys * [,* indent * [,* separators * [,* encoding * [,* default *]]]]]]]]]]))
    • 用于 Python 数据结构的可扩展 JSON 编码器。

默认情况下支持以下对象和类型:

PythonJSON
dictobject
list, tuplearray
str, unicodestring
整数,长,浮点数number
Truetrue
Falsefalse
Nonenull

为了将其扩展为识别其他对象,请子类化并实现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(默认设置),则NaNInfinity-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 7159ECMA-404指定。本节详细介绍了此模块与 RFC 的符合性级别。为简单起见,不考虑JSONEncoderJSONDecoder子类以及未明确提及的参数。

该模块不严格遵循 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-InfinityNaN,就像它们是有效的 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 dictlist),并且不能为 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 起)不允许。