`json` — JSON encoder and decoderJSON编码器和解码器¶

Source code: Lib/json/__init__.py

JSON (JavaScript Object Notation), specified by RFC 7159 (which obsoletes RFC 4627) and by ECMA-404, is a lightweight data interchange format inspired by JavaScript object literal syntax (although it is not a strict subset of JavaScript 1 ).JSON（JavaScript对象表示法）由RFC 7159（取代了RFC 4627）和ECMA-404指定，是一种受JavaScript对象字面语法启发的轻量级数据交换格式（尽管它不是JavaScript 1的严格子集）。

json ~~exposes an API familiar to users of the standard library marshal and pickle modules.~~公开了标准库marshal和pickle模块的用户熟悉的API。

~~Encoding basic Python object hierarchies:~~编码基本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"]'

~~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))
{
    "4": 5,
    "6": 7
}

~~Decoding JSON:~~解码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']

~~Specializing JSON object decoding:~~专门进行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:~~扩展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:~~使用shell中的json.tool进行验证并漂亮地打印：

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

~~See Command Line Interface for detailed documentation.~~有关详细文档，请参阅命令行界面。

Note

~~JSON is a subset of YAML 1.2.~~ JSON是YAML 1.2的一个子集。~~The JSON produced by this module’s default settings (in particular, the default separators value) is also a subset of YAML 1.0 and 1.1.~~ 该模块的默认设置（特别是默认分隔符值）生成的JSON也是YAML1.0和1.1的子集。~~This module can thus also be used as a YAML serializer.~~因此，该模块也可以用作YAML序列化程序。

Note

~~This module’s encoders and decoders preserve input and output order by default.~~ 该模块的编码器和解码器默认保留输入和输出顺序。~~Order is only lost if the underlying containers are unordered.~~只有当基础容器无序时，订单才会丢失。

~~Prior to Python 3.7, dict was not guaranteed to be ordered, so inputs and outputs were typically scrambled unless collections.OrderedDict was specifically requested.~~ 在Python3.7之前，dict不能保证是有序的，所以除非特别请求collections.OrderedDict，否则输入和输出通常是加扰的。~~Starting with Python 3.7, the regular dict became order preserving, so it is no longer necessary to specify collections.OrderedDict for JSON generation and parsing.~~从Python3.7开始，正则dict变成了保序dict，因此不再需要为JSON生成和解析指定collections.OrderedDict。

Basic Usage基本用途¶

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

~~Serialize obj as a JSON formatted stream to fp (a .write()-supporting file-like object) using this conversion table.~~使用此转换表将obj作为JSON格式的流序列化为fp（.write()-支持类似文件的对象）。

If skipkeys is true (default: False), then dict keys that are not of a basic type (str, int, float, bool, None) will be skipped instead of raising a TypeError.

The json module always produces str objects, not bytes objects. Therefore, fp.write() must support str input.

If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped. If ensure_ascii is false, these characters will be output as-is.

If check_circular is false (default: True), then the circular reference check for container types will be skipped and a circular reference will result in an RecursionError (or worse).

If allow_nan is false (default: True), then it will be a ValueError to serialize out of range float values (nan, inf, -inf) in strict compliance of the JSON specification. If allow_nan is true, their JavaScript equivalents (NaN, Infinity, -Infinity) will be used.

If indent is a non-negative integer or string, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0, negative, or "" will only insert newlines. None (the default) selects the most compact representation. Using a positive integer indent indents that many spaces per level. If indent is a string (such as "\t"), that string is used to indent each level.

~~Changed in version 3.2:~~版本3.2中更改： Allow strings for indent in addition to integers.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (', ', ': ') if indent is None and (',', ': ') otherwise. To get the most compact JSON representation, you should specify (',', ':') to eliminate whitespace.

~~Changed in version 3.4:~~版本3.4中更改： Use (',', ': ') as default if indent is not None.

If specified, default should be a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError. If not specified, TypeError is raised.

If sort_keys is true (default: False), then the output of dictionaries will be sorted by key.

To use a custom JSONEncoder subclass (e.g. one that overrides the default() method to serialize additional types), specify it with the cls kwarg; otherwise JSONEncoder is used.

~~Changed in version 3.6:~~版本3.6中更改： All optional parameters are now keyword-only.

Note

Unlike pickle and marshal, JSON is not a framed protocol, so trying to serialize multiple objects with repeated calls to dump() using the same fp will result in an invalid JSON file.

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)¶: Serialize obj to a JSON formatted str using this conversion table. The arguments have the same meaning as in dump().

Note

Keys in key/value pairs of JSON are always of the type str. When a dictionary is converted into JSON, all the keys of the dictionary are coerced to strings. As a result of this, if a dictionary is converted into JSON and then back into a dictionary, the dictionary may not equal the original one. That is, loads(dumps(x)) != x if x has non-string keys.

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

Deserialize fp (a .read()-supporting text file or binary file containing a JSON document) to a Python object using this conversion table.

object_hook is an optional function that will be called with the result of any object literal decoded (a dict). The return value of object_hook will be used instead of the dict. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

~~Changed in version 3.1:~~版本3.1中更改： Added support for object_pairs_hook.

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default, this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).

parse_int, if specified, will be called with the string of every JSON int to be decoded. By default, this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).

parse_constant, if specified, will be called with one of the following strings: '-Infinity', 'Infinity', 'NaN'. This can be used to raise an exception if invalid JSON numbers are encountered.

~~Changed in version 3.1:~~版本3.1中更改： parse_constant doesn’t get called on ‘null’, ‘true’, ‘false’ anymore.

To use a custom JSONDecoder subclass, specify it with the cls kwarg; otherwise JSONDecoder is used. Additional keyword arguments will be passed to the constructor of the class.

If the data being deserialized is not a valid JSON document, a JSONDecodeError will be raised.

~~Changed in version 3.6:~~版本3.6中更改： All optional parameters are now keyword-only.

~~Changed in version 3.6:~~版本3.6中更改： fp can now be a binary file. The input encoding should be UTF-8, UTF-16 or UTF-32.

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

Deserialize s (a str, bytes or bytearray instance containing a JSON document) to a Python object using this conversion table.

The other arguments have the same meaning as in load().

If the data being deserialized is not a valid JSON document, a JSONDecodeError will be raised.

~~Changed in version 3.6:~~版本3.6中更改： s can now be of type bytes or bytearray. The input encoding should be UTF-8, UTF-16 or UTF-32.

~~Changed in version 3.9:~~版本3.9中更改： The keyword argument encoding has been removed.

Encoders and Decoders编码器和解码器¶

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

~~Simple JSON decoder.~~简单的JSON解码器。

~~Performs the following translations in decoding by default:~~默认情况下，在解码中执行以下翻译：

JSON	Python
object	dict
array	list
string	str
number (int)	int
number (real)	float
true	True
false	False
null	None

It also understands NaN, Infinity, and -Infinity as their corresponding float values, which is outside the JSON spec.

object_hook, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the given dict. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting).

object_pairs_hook, if specified will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

~~Changed in version 3.1:~~版本3.1中更改： Added support for object_pairs_hook.

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default, this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).

parse_int, if specified, will be called with the string of every JSON int to be decoded. By default, this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).

parse_constant, if specified, will be called with one of the following strings: '-Infinity', 'Infinity', 'NaN'. This can be used to raise an exception if invalid JSON numbers are encountered.

If strict is false (True is the default), then control characters will be allowed inside strings. Control characters in this context are those with character codes in the 0–31 range, including '\t' (tab), '\n', '\r' and '\0'.

If the data being deserialized is not a valid JSON document, a JSONDecodeError will be raised.

~~Changed in version 3.6:~~版本3.6中更改： All parameters are now keyword-only.

decode(s)¶

Return the Python representation of s (a str instance containing a JSON document).

JSONDecodeError will be raised if the given JSON document is not valid.

raw_decode(s)¶

Decode a JSON document from s (a str beginning with a JSON document) and return a 2-tuple of the Python representation and the index in s where the document ended.

This can be used to decode a JSON document from a string that may have extraneous data at the end.

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

~~Extensible JSON encoder for Python data structures.~~用于Python数据结构的可扩展JSON编码器。

~~Supports the following objects and types by default:~~默认情况下支持以下对象和类型：

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

~~Changed in version 3.4:~~版本3.4中更改： ~~Added support for int- and float-derived Enum classes.~~增加了对int和float派生枚举类的支持。

To extend this to recognize other objects, subclass and implement a default() method with another method that returns a serializable object for o if possible, otherwise it should call the superclass implementation (to raise TypeError).

If skipkeys is false (the default), a TypeError will be raised when trying to encode keys that are not str, int, float or None. If skipkeys is true, such items are simply skipped.

If ensure_ascii is true (the default), the output is guaranteed to have all incoming non-ASCII characters escaped. If ensure_ascii is false, these characters will be output as-is.

If 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 RecursionError). Otherwise, no such check takes place.

If allow_nan is true (the default), then NaN, Infinity, and -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.

If sort_keys is true (default: 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.

If indent is a non-negative integer or string, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0, negative, or "" will only insert newlines. None (the default) selects the most compact representation. Using a positive integer indent indents that many spaces per level. If indent is a string (such as "\t"), that string is used to indent each level.

~~Changed in version 3.2:~~版本3.2中更改： Allow strings for indent in addition to integers.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (', ', ': ') if indent is None and (',', ': ') otherwise. To get the most compact JSON representation, you should specify (',', ':') to eliminate whitespace.

~~Changed in version 3.4:~~版本3.4中更改： Use (',', ': ') as default if indent is not None.

If specified, default should be a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError. If not specified, TypeError is raised.

~~Changed in version 3.6:~~版本3.6中更改： All parameters are now keyword-only.

default(o)¶

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default() like this:

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

Return a JSON string representation of a Python data structure, o. For example:

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

iterencode(o)¶

Encode the given object, o, and yield each string representation as available. For example:

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

Exceptions异常¶

exceptionjson.JSONDecodeError(msg, doc, pos)¶

Subclass of ValueError with the following additional attributes:

msg¶: The unformatted error message.

doc¶: The JSON document being parsed.

pos¶: The start index of doc where parsing failed.

lineno¶: The line corresponding to pos.

colno¶: The column corresponding to pos.

~~New in version 3.5.~~版本3.5中新增。

Standard Compliance and Interoperability标准合规性和互操作性¶

The JSON format is specified by RFC 7159 and by 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:

~~Infinite and NaN number values are accepted and output;~~接受并输出无穷大数值和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.~~由于RFC允许符合RFC的解析器接受不符合RFC的输入文本，因此在默认设置下，该模块的解串器在技术上符合RFC。

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.~~RFC要求JSON使用UTF-8、UTF-16或UTF-32表示，建议将UTF-8作为最大互操作性的默认值。

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. RFC并没有明确禁止包含与有效Unicode字符不对应的字节序列的JSON字符串（例如，不成对的UTF-16代理），但它确实注意到它们可能会导致互操作性问题。By default, this module accepts and outputs (when present in the original str) code points for such sequences.

Infinite and NaN Number Values无穷和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, and 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

In the serializer, the allow_nan parameter can be used to alter this behavior. In the deserializer, the parse_constant parameter can be used to alter this behavior.

Repeated Names Within an Object对象中的重复名称¶

~~The RFC specifies that the names within a JSON object should be unique, but does not mandate how repeated names in JSON objects should be handled.~~ RFC规定JSON对象中的名称应该是唯一的，但没有规定如何处理JSON对象中重复的名称。~~By default, this module does not raise an exception; instead, it ignores all but the last name-value pair for a given name:~~默认情况下，此模块不会引发异常；相反，它会忽略给定名称的除姓氏值对之外的所有值：

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

The object_pairs_hook parameter can be used to alter this behavior.

Top-level Non-Object, Non-Array Values顶级非对象、非数组值¶

The old version of JSON specified by the obsolete RFC 4627 required that the top-level value of a JSON text must be either a JSON object or array (Python dict or list), and could not be a JSON null, boolean, number, or string value. RFC 7159 removed that restriction, and this module does not and has never implemented that restriction in either its serializer or its deserializer.

Regardless, for maximum interoperability, you may wish to voluntarily adhere to the restriction yourself.

Implementation Limitations实施限制¶

~~Some JSON deserializer implementations may set limits on:~~某些JSON反序列化程序实现可能会对以下内容设置限制：

~~the size of accepted JSON texts~~接受的JSON文本的大小
the maximum level of nesting of JSON objects and arrays
the range and precision of JSON numbers
the content and maximum length of JSON strings

This module does not impose any such limits beyond those of the relevant Python datatypes themselves or the Python interpreter itself.

When serializing to JSON, beware any such limitations in applications that may consume your JSON. In particular, it is common for JSON numbers to be deserialized into IEEE 754 double precision numbers and thus subject to that representation’s range and precision limitations. This is especially relevant when serializing Python int values of extremely large magnitude, or when serializing instances of “exotic” numerical types such as decimal.Decimal.

Command Line Interface命令行接口¶

Source code: Lib/json/tool.py

~~The json.tool module provides a simple command line interface to validate and pretty-print JSON objects.~~json.tool模块提供了一个简单的命令行接口来验证和漂亮地打印JSON对象。

If the optional infile and outfile arguments are not specified, sys.stdin and sys.stdout will be used respectively:

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

~~Changed in version 3.5:~~版本3.5中更改： The output is now in the same order as the input. Use the --sort-keys option to sort the output of dictionaries alphabetically by key.

Command line options命令行选项¶

infile¶

~~The JSON file to be validated or pretty-printed:~~要验证或漂亮打印的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
    }
]

If infile is not specified, read from sys.stdin.

outfile¶: Write the output of the infile to the given outfile. Otherwise, write it to sys.stdout.

--sort-keys¶: ~~Sort the output of dictionaries alphabetically by key.~~按关键字的字母顺序对词典的输出进行排序。

~~New in version 3.5.~~版本3.5中新增。

--no-ensure-ascii¶: Disable escaping of non-ascii characters, see json.dumps() for more information.

~~New in version 3.9.~~版本3.9中新增。

--json-lines¶: ~~Parse every input line as separate JSON object.~~将每个输入行解析为单独的JSON对象。

~~New in version 3.8.~~版本3.8中新增。

--indent,--tab,--no-indent,--compact¶: ~~Mutually exclusive options for whitespace control.~~空格控制的互斥选项。

~~New in version 3.9.~~版本3.9中新增。

-h,--help¶: Show the help message.

Footnotes

1: As noted in 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.

`json` — JSON encoder and decoderJSON编码器和解码器¶

Basic Usage基本用途¶

Encoders and Decoders编码器和解码器¶

Exceptions异常¶

Standard Compliance and Interoperability标准合规性和互操作性¶

Character Encodings字符编码¶

Infinite and NaN Number Values无穷和NaN数值¶

Repeated Names Within an Object对象中的重复名称¶

Top-level Non-Object, Non-Array Values顶级非对象、非数组值¶

Implementation Limitations实施限制¶

Command Line Interface命令行接口¶

Command line options命令行选项¶

Table of Contents目录

Previous topic上一个主题

Next topic下一个主题

json — JSON encoder and decoderJSON编码器和解码器¶

Basic Usage基本用途¶

Encoders and Decoders编码器和解码器¶

Exceptions异常¶

Standard Compliance and Interoperability标准合规性和互操作性¶

Character Encodings字符编码¶

Infinite and NaN Number Values无穷和NaN数值¶

Repeated Names Within an Object对象中的重复名称¶

Top-level Non-Object, Non-Array Values顶级非对象、非数组值¶

Implementation Limitations实施限制¶

Command Line Interface命令行接口¶

Command line options命令行选项¶

`json` — JSON encoder and decoderJSON编码器和解码器¶