python模块学习之json

更多信息请参考官网地址：

https://docs.python.org/3.6/library/json.html

19.2. json - JSON编码器和解码器

Source code: Lib/json/__init__.py

由RFC 7159（其中删除RFC 4627）和ECMA-404指定的JSON（JavaScript对象表示法）是一种轻量级数据交换格式，灵感来自JavaScript对象文字语法（尽管它不是JavaScript的严格子集[1]）。

json公开了标准库元组和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('\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({'4': 5, '6': 7}, sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}

解码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 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 -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)

有关详细文档，请参阅命令行界面。

注意JSON是YAML 1.2的一个子集。 由该模块的默认设置（特别是默认分隔符值）生成的JSON也是YAML 1.0和1.1的子集。 因此，该模块也可以用作YAML串行器。

19.2.1. 基本的使用

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格式化流序列化为fp（一个.write（） - 支持类似文件的对象）。

如果skipkeys为true（默认值为False），则将跳过不是基本类型（str，int，float，bool，None）的dict键，而不是引发TypeError。

json模块总是生成str对象，而不是字节对象。因此，fp.write（）必须支持str输入。

如果ensure_ascii为true（默认值），输出将保证转义所有传入的非ASCII字符。如果ensure_ascii为false，这些字符将按原样输出。

如果check_circular为false（默认值为True），则会跳过容器类型的循环引用检查，循环引用将导致溢出错误（或更坏）。

如果allow_nan为false（默认值为True），那么在严格遵守JSON规范的情况下，它将是一个ValueError序列化超出范围的float值（nan，inf，-inf）。如果allow_nan为真，则将使用其JavaScript等效项（NaN，Infinity，-Infinity）。

如果缩进是非负整数或字符串，则JSON数组元素和对象成员将以该缩进级别打印。缩进级别为0，负数或“”只会插入换行符。无（默认）选择最紧凑的表示。使用正整数缩进缩进每个级别的许多空格。如果缩进是一个字符串（例如“\ t”），则该字符串用于缩进每个级别。

在版本3.2中更改：允许字符串缩进除整数外。

如果指定，分隔符应该是（item_separator，key_separator）元组。如果indent为None，则为（'，'，'：'），否则为（'，'，'：'）。要获得最紧凑的JSON表示，您应该指定（'，'，'：'）以消除空格。

在版本3.4中更改：如果缩进不为无，则使用（'，'，'：'）作为默认值。

如果指定，默认值应该是一个函数，被调用的对象不能被序列化。它应该返回对象的JSON编码版本或引发TypeError。如果未指定，则引发TypeError。

如果sort_keys为true（默认值为False），那么字典的输出将按键排序。

要使用自定义JSONEncoder子类（例如覆盖default（）方法以序列化其他类型的子类），请使用cls kwarg指定它;否则使用JSONEncoder。

版本3.6更改：所有可选参数现在都是关键字。

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（）中的含义相同。

注意与pickle和marshal不一样，JSON不是一个框架协议，所以尝试使用相同的fp重复调用dump（）来对多个对象进行序列化将导致无效的JSON文件。
注意JSON的键/值对中的键始终是str类型。 当字典转换为JSON时，字典的所有键都被强制转换为字符串。 因此，如果将字典转换为JSON，然后转换为字典，则字典可能不等于原始字典。 也就是说，如果x具有非字符串键，则load（dumps（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（） - 支持包含JSON文档的类似文件的对象）解析为Python对象。

object_hook是一个可选函数，它将被任意对象字面解码（一个dict）的结果调用。将使用object_hook的返回值而不是dict。此功能可用于实现自定义解码器（例如JSON-RPC类提示）。

object_pairs_hook是一个可选的函数，将被调用的任何对象字面解码的结果与有序的成对列表。将使用object_pairs_hook的返回值而不是dict。该功能可用于实现依赖于键和值对解码顺序的自定义解码器（例如，collections.OrderedDict（）将记住插入顺序）。如果object_hook也被定义，则object_pairs_hook优先。

在版本3.1中更改：添加了对object_pairs_hook的支持。

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

将使用要解码的每个JSON int的字符串调用parse_int（如果指定）。默认情况下，这相当于int（num_str）。这可以用于为JSON整数使用另一个数据类型或解析器（例如浮点数）。

将使用以下字符串之一调用parse_constant（如果指定）：'-Infinity'，'Infinity'，'NaN'。如果遇到无效的JSON数字，则可以用于引发异常。

3.1版中更改：parse_constant不再被调用'null'，'true'，'false'了。

要使用自定义JSONDecoder子类，请使用cls kwarg指定它;否则使用JSONDecoder。其他关键字参数将被传递给类的构造函数。

如果反序列化的数据不是有效的JSON文档，则会引发JSONDecodeError。

版本3.6更改：所有可选参数现在都是关键字。

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

将使用此转换表的s对象（包含JSON文档的str，bytes或bytearray实例）反序列化为Python对象。

其他参数与load（）具有相同的含义，除了被忽略和不推荐使用的编码。

如果反序列化的数据不是有效的JSON文档，则会引发JSONDecodeError。

版本3.6更改：现在可以是字节或字节。 输入编码应为UTF-8，UTF-16或UTF-32。

19.2.2 编码器和解码器

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
number (int)    int
number (real)    float
true    True
false    False
null    None

它也了解NaN，Infinity和-Infinity作为其相应的浮点值，这在JSON规范之外。

object_hook（如果指定）将被调用，每个JSON对象的解码结果都将被使用，并且返回值将被替换为给定的dict。这可以用于提供自定义反序列化（例如，以支持JSON-RPC类提示）。

object_pairs_hook（如果指定的话）将被调用，每个JSON对象的结果都是使用有序的对列表进行解码的。将使用object_pairs_hook的返回值而不是dict。该功能可用于实现依赖于键和值对解码顺序的自定义解码器（例如，collections.OrderedDict（）将记住插入顺序）。如果object_hook也被定义，则object_pairs_hook优先。

在版本3.1中更改：添加了对object_pairs_hook的支持。

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

将使用要解码的每个JSON int的字符串调用parse_int（如果指定）。默认情况下，这相当于int（num_str）。这可以用于为JSON整数使用另一个数据类型或解析器（例如浮点数）。

将使用以下字符串之一调用parse_constant（如果指定）：'-Infinity'，'Infinity'，'NaN'。如果遇到无效的JSON数字，则可以用于引发异常。

如果strict为false（True为默认值），则控制字符将被允许在字符串内。在这种情况下，控制字符是0-31范围内的字符代码，包括'\ t'（标签），'\ n'，'\ r'和'\ 0'。

如果反序列化的数据不是有效的JSON文档，则会引发JSONDecodeError。

版本3.6更改：所有参数现在都是关键字。

decode(s)

返回s（包含JSON文档的str实例）的Python表示形式。

如果给定的JSON文档无效，将引发JSONDecodeError。

raw_decode(s)

从s（以JSON文档开始的一个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（）方法，如果可能，返回一个可序列化的对象，否则它应该调用超类实现（引发TypeError）。

如果skipkeys为false（默认值），那么它是一个TypeError来尝试对不是str，int，float或None的键进行编码。如果skipkeys为true，则这些项目被简单地跳过。

如果ensure_ascii为true（默认值），输出将保证转义所有传入的非ASCII字符。如果ensure_ascii为false，这些字符将按原样输出。

如果check_circular为true（默认值），那么在编码期间，列表，dicts和自定义编码对象将被检查循环引用，以防止无限递归（这将导致OverflowError）。否则，不进行此类检查。

如果allow_nan为true（默认值），则NaN，Infinity和-Infinity将被编码。此行为不符合JSON规范，但与大多数基于JavaScript的编码器和解码器一致。否则，它将是一个ValueError来编码这样的浮点数。

如果sort_keys为true（默认值为False），则字典的输出将按键排序;这对回归测试是有用的，以确保可以在日常的基础上比较JSON序列化。

如果缩进是非负整数或字符串，则JSON数组元素和对象成员将以该缩进级别打印。缩进级别为0，负数或“”只会插入换行符。无（默认）选择最紧凑的表示。使用正整数缩进缩进每个级别的许多空格。如果缩进是一个字符串（例如“\ t”），则该字符串用于缩进每个级别。

在版本3.2中更改：允许字符串缩进除整数外。

如果指定，分隔符应该是（item_separator，key_separator）元组。如果indent为None，则为（'，'，'：'），否则为（'，'，'：'）。要获得最紧凑的JSON表示，您应该指定（'，'，'：'）以消除空格。

在版本3.4中更改：如果缩进不为无，则使用（'，'，'：'）作为默认值。

如果指定，默认值应该是一个函数，被调用的对象不能被序列化。它应该返回对象的JSON编码版本或引发TypeError。如果未指定，则引发TypeError。

版本3.6更改：所有参数现在都是关键字。

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 json.JSONEncoder.default(self, o)

encode(o)

返回Python数据结构的JSON字符串表示形式，o。 例如：

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

iterencode(o)¶

对给定的对象进行编码，o，并产生每个字符串表示形式。 例如：

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

19.2.3. 异常

exception json.JSONDecodeError(msg, doc, pos)　　

ValueError的子类包含以下附加属性：

msg

未格式化的错误消息。

doc
要解析的JSON文档。

pos
解析失败的doc的起始索引。

lineno
对应于pos的行

colno
与pos对应的列

3.5版新功能。

19.2.4. 标准合规性和互操作性

JSON格式由RFC 7159和ECMA-404指定。 本节详细介绍了该模块与RFC的一致性。 为了简单起见，不考虑JSONEncoder和JSONDecoder子类以及除了明确提到的子类之外的参数。

该模块不严格遵守RFC，实施一些有效的JavaScript而不是有效的JSON的扩展。 尤其是：

无限和NaN数值被接受并输出;
接受对象中的重复名称，只使用最后一个名称 - 值对的值。
由于RFC允许符合RFC的解析器接受不符合RFC标准的输入文本，因此在默认设置下，该模块的解串器在技术上符合RFC。

19.2.4.1. 字符编码

RFC要求使用UTF-8，UTF-16或UTF-32来表示JSON，UTF-8是最大互操作性的推荐默认值。

如RFC所允许的，虽然不是必需的，但是该模块的串行器默认设置ensure_ascii = True，从而转义输出，以便生成的字符串只包含ASCII字符。

除了ensure_ascii参数之外，该模块严格按照Python对象和Unicode字符串之间的转换进行定义，因此不会直接解决字符编码问题。

RFC禁止在JSON文本的开始添加字节顺序标记（BOM），并且此模块的序列化程序不向其输出添加BOM。 RFC允许，但不要求JSON解串器忽略其输入中的初始BOM。当初始BOM存在时，此模块的解串器会引发ValueError。

RFC没有明确禁止包含不符合有效Unicode字符的字节序列（例如不成对的UTF-16代理）的JSON字符串，但它确实注意到它们可能导致互操作性问题。默认情况下，该模块接受并输出（当存在于原始的str中时）这些序列的代码点。

19.2.4.2. 无限和NaN数值

RFC不允许表示无限或NaN数值。 尽管如此，默认情况下，此模块接受并输出Infinity，-Infinity和NaN，就好像它们是有效的JSON数字字面值：

>>> # 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_none参数可用于更改此行为。 在解串器中，parse常数参数可用于更改此行为。

19.2.4.3. 对象内重复的名称　　

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

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

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

19.2.4.4. 顶级非对象，非数组值

由过时的RFC 4627指定的旧版本的JSON要求JSON文本的顶级值必须是JSON对象或数组（Python dict或list），并且不能是JSON null，boolean，number或字符串值。 RFC 7159删除了该限制，并且该模块没有并且从未在其序列化程序或其解串器中实现该限制。

无论如何，为了实现最大的互操作性，您可能希望自行遵守限制。

19.2.4.5. 实施限制

一些JSON解串器实现可能会限制：

接受的JSON文本的大小
JSON对象和数组的最大嵌套级别
JSON数字的范围和精度
JSON字符串的内容和最大长度
该模块不会超出相关Python数据类型本身或Python解释器本身的任何限制。

当序列化到JSON时，请注意可能会消耗JSON的应用程序中的任何此类限制。特别是，JSON数字通常被反序列化为IEEE 754双精度数字，因此受制于该表示的范围和精度限制。当串行化非常大的Python int值时，或者当序列化“异国情调”数字类型的实例（如decimal.Decimal）时，这一点尤为重要。

19.2.5. 命令行界面　　

json.tool模块提供了一个简单的命令行界面来验证和漂亮打印JSON对象。

如果未指定可选的infile和outfile参数，则将分别使用sys.stdin和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选项按字母顺序排列字典的输出。

19.2.5.1. 命令行选项

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密钥
按字母顺序排列词典的输出。

3.5版新功能

-h，--help
显示帮助信息。

脚注

[1]如RFC 7159的勘误中所述，JSON允许字符串中的文字U + 2028（LINE SEPARATOR）和U + 2029（PARAGRAPH SEPARATOR）字符，而JavaScript（作为ECMAScript版本5.1）不支持。