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

使用這個(gè) 轉(zhuǎn)換表 將 obj 序列化為 JSON 格式化流形式的 fp (支持 .write() 的 file-like object)。

如果 skipkeys 是 true （默認(rèn)為 False），那么那些不是基本對(duì)象（包括 str, int、float、bool、None）的字典的鍵會(huì)被跳過(guò)；否則引發(fā)一個(gè) TypeError。

json 模塊始終產(chǎn)生 str 對(duì)象而非 bytes 對(duì)象。因此，fp.write() 必須支持 str 輸入。

如果 ensure_ascii 是 true （即默認(rèn)值），輸出保證將所有輸入的非 ASCII 字符轉(zhuǎn)義。如果 ensure_ascii 是 false，這些字符會(huì)原樣輸出。

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 a RecursionError (or worse).

如果 allow_nan 是 false（默認(rèn)為 True），那么在對(duì)嚴(yán)格 JSON 規(guī)格范圍外的 float 類(lèi)型值（nan、inf 和 -inf）進(jìn)行序列化時(shí)會(huì)引發(fā)一個(gè) ValueError。如果 allow_nan 是 true，則使用它們的 JavaScript 等價(jià)形式（NaN、Infinity 和 -Infinity）。

如果 indent 是一個(gè)非負(fù)整數(shù)或者字符串，那么 JSON 數(shù)組元素和對(duì)象成員會(huì)被美化輸出為該值指定的縮進(jìn)等級(jí)。 如果縮進(jìn)等級(jí)為零、負(fù)數(shù)或者 ""，則只會(huì)添加換行符。 None (默認(rèn)值) 選擇最緊湊的表達(dá)。 使用一個(gè)正整數(shù)會(huì)讓每一層縮進(jìn)同樣數(shù)量的空格。 如果 indent 是一個(gè)字符串 (比如 "\t")，那個(gè)字符串會(huì)被用于縮進(jìn)每一層。

在 3.2 版更改: 現(xiàn)允許使用字符串作為 indent 而不再僅僅是整數(shù)。

當(dāng)被指定時(shí)，separators 應(yīng)當(dāng)是一個(gè) (item_separator, key_separator) 元組。當(dāng) indent 為 None 時(shí)，默認(rèn)值取 (', ', ': ')，否則取 (',', ': ')。為了得到最緊湊的 JSON 表達(dá)式，你應(yīng)該指定其為 (',', ':') 以消除空白字符。

在 3.4 版更改: 現(xiàn)當(dāng) indent 不是 None 時(shí)，采用 (',', ': ') 作為默認(rèn)值。

當(dāng) default 被指定時(shí)，其應(yīng)該是一個(gè)函數(shù)，每當(dāng)某個(gè)對(duì)象無(wú)法被序列化時(shí)它會(huì)被調(diào)用。它應(yīng)該返回該對(duì)象的一個(gè)可以被 JSON 編碼的版本或者引發(fā)一個(gè) TypeError。如果沒(méi)有被指定，則會(huì)直接引發(fā) TypeError。

如果 sort_keys 是 true（默認(rèn)為 False），那么字典的輸出會(huì)以鍵的順序排序。

為了使用一個(gè)自定義的 JSONEncoder 子類(lèi)（比如：覆蓋了 default() 方法來(lái)序列化額外的類(lèi)型）， 通過(guò) cls 關(guān)鍵字參數(shù)來(lái)指定；否則將使用 JSONEncoder。

在 3.6 版更改: 所有可選形參現(xiàn)在都是 僅限關(guān)鍵字參數(shù)。

備注

與 pickle 和 marshal 不同，JSON 不是一個(gè)具有框架的協(xié)議，所以嘗試多次使用同一個(gè) fp 調(diào)用 dump() 來(lái)序列化多個(gè)對(duì)象會(huì)產(chǎn)生一個(gè)不合規(guī)的 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)?

使用這個(gè) 轉(zhuǎn)換表 將 obj 序列化為 JSON 格式的 str。 其參數(shù)的含義與 dump() 中的相同。

備注

JSON 中的鍵-值對(duì)中的鍵永遠(yuǎn)是 str 類(lèi)型的。當(dāng)一個(gè)對(duì)象被轉(zhuǎn)化為 JSON 時(shí)，字典中所有的鍵都會(huì)被強(qiáng)制轉(zhuǎn)換為字符串。這所造成的結(jié)果是字典被轉(zhuǎn)換為 JSON 然后轉(zhuǎn)換回字典時(shí)可能和原來(lái)的不相等。換句話(huà)說(shuō)，如果 x 具有非字符串的鍵，則有 loads(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)?

使用這個(gè) 轉(zhuǎn)換表 將 fp (一個(gè)支持 .read() 并包含一個(gè) JSON 文檔的 text file 或者 binary file) 反序列化為一個(gè) Python 對(duì)象。

object_hook 是一個(gè)可選的函數(shù)，它會(huì)被調(diào)用于每一個(gè)解碼出的對(duì)象字面量（即一個(gè) dict）。object_hook 的返回值會(huì)取代原本的 dict。這一特性能夠被用于實(shí)現(xiàn)自定義解碼器（如 JSON-RPC 的類(lèi)型提示)。

object_pairs_hook 是一個(gè)可選的函數(shù)，它會(huì)被調(diào)用于每一個(gè)有序列表對(duì)解碼出的對(duì)象字面量。 object_pairs_hook 的返回值將會(huì)取代原本的 dict 。這一特性能夠被用于實(shí)現(xiàn)自定義解碼器。如果 object_hook 也被定義， object_pairs_hook 優(yōu)先。

在 3.1 版更改: 添加了對(duì) object_pairs_hook 的支持。

parse_float ，如果指定，將與每個(gè)要解碼 JSON 浮點(diǎn)數(shù)的字符串一同調(diào)用。默認(rèn)狀態(tài)下，相當(dāng)于 float(num_str) 。可以用于對(duì) JSON 浮點(diǎn)數(shù)使用其它數(shù)據(jù)類(lèi)型和語(yǔ)法分析程序 （比如 decimal.Decimal ）。

parse_int ，如果指定，將與每個(gè)要解碼 JSON 整數(shù)的字符串一同調(diào)用。默認(rèn)狀態(tài)下，相當(dāng)于 int(num_str) ?？梢杂糜趯?duì) JSON 整數(shù)使用其它數(shù)據(jù)類(lèi)型和語(yǔ)法分析程序 （比如 float ）。

parse_constant ，如果指定，將要與以下字符串中的一個(gè)一同調(diào)用： '-Infinity' ， 'Infinity' ， 'NaN' 。如果遇到無(wú)效的 JSON 數(shù)字則可以使用它引發(fā)異常。

在 3.1 版更改: parse_constant 不再調(diào)用 'null' ， 'true' ， 'false' 。

要使用自定義的 JSONDecoder 子類(lèi)，用 cls 指定他；否則使用 JSONDecoder 。額外的關(guān)鍵詞參數(shù)會(huì)通過(guò)類(lèi)的構(gòu)造函數(shù)傳遞。

如果反序列化的數(shù)據(jù)不是有效 JSON 文檔，引發(fā) JSONDecodeError 錯(cuò)誤。

在 3.6 版更改: 所有可選形參現(xiàn)在都是 僅限關(guān)鍵字參數(shù)。

在 3.6 版更改: fp 現(xiàn)在可以是 binary file 。輸入編碼應(yīng)當(dāng)是 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)?

使用這個(gè) 轉(zhuǎn)換表 將 s (一個(gè)包含 JSON 文檔的 str, bytes 或 bytearray 實(shí)例) 反序列化為 Python 對(duì)象。

其他參數(shù)的含義與 load() 中的相同。

如果反序列化的數(shù)據(jù)不是有效 JSON 文檔，引發(fā) JSONDecodeError 錯(cuò)誤。

在 3.6 版更改: s 現(xiàn)在可以為 bytes 或 bytearray 類(lèi)型。 輸入編碼應(yīng)為 UTF-8, UTF-16 或 UTF-32。

在 3.9 版更改: 關(guān)鍵字參數(shù) encoding 已被移除。

編碼器和解碼器?

class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)?

簡(jiǎn)單的JSON解碼器。

默認(rèn)情況下，解碼執(zhí)行以下翻譯:

JSON	Python
object -- 對(duì)象	dict
array	list -- 列表
string	str
number (int)	int
number (real)	float
true	True
false	False
null	None

它還將“NaN”、“Infinity”和“-Infinity”理解為它們對(duì)應(yīng)的“float”值，這超出了JSON規(guī)范。

如果指定了 object_hook，它將被調(diào)用并傳入每個(gè)已解碼 JSON 對(duì)象的結(jié)果，并且其返回值將被用來(lái)替代給定的 dict。 它可被用于提供自定義的反序列化操作（例如支持 JSON-RPC 類(lèi)提示）。

如果指定了 object_pairs_hook 則它將被調(diào)用并傳入以對(duì)照值有序列表進(jìn)行解碼的每個(gè) JSON 對(duì)象的結(jié)果。 object_pairs_hook 的結(jié)果值將被用來(lái)替代 dict。 這一特性可被用于實(shí)現(xiàn)自定義解碼器。 如果還定義了 object_hook，則 object_pairs_hook 的優(yōu)先級(jí)更高。

在 3.1 版更改: 添加了對(duì) object_pairs_hook 的支持。

parse_float ，如果指定，將與每個(gè)要解碼 JSON 浮點(diǎn)數(shù)的字符串一同調(diào)用。默認(rèn)狀態(tài)下，相當(dāng)于 float(num_str) ?？梢杂糜趯?duì) JSON 浮點(diǎn)數(shù)使用其它數(shù)據(jù)類(lèi)型和語(yǔ)法分析程序 （比如 decimal.Decimal ）。

parse_int ，如果指定，將與每個(gè)要解碼 JSON 整數(shù)的字符串一同調(diào)用。默認(rèn)狀態(tài)下，相當(dāng)于 int(num_str) 。可以用于對(duì) JSON 整數(shù)使用其它數(shù)據(jù)類(lèi)型和語(yǔ)法分析程序 （比如 float ）。

parse_constant ，如果指定，將要與以下字符串中的一個(gè)一同調(diào)用： '-Infinity' ， 'Infinity' ， 'NaN' 。如果遇到無(wú)效的 JSON 數(shù)字則可以使用它引發(fā)異常。

如果 strict 為 false （默認(rèn)為 True ），那么控制字符將被允許在字符串內(nèi)。在此上下文中的控制字符編碼在范圍 0--31 內(nèi)的字符，包括 '\t' (制表符）， '\n' ， '\r' 和 '\0' 。

如果反序列化的數(shù)據(jù)不是有效 JSON 文檔，引發(fā) JSONDecodeError 錯(cuò)誤。

在 3.6 版更改: 所有形參現(xiàn)在都是 僅限關(guān)鍵字參數(shù)。

decode(s)?

返回 s 的 Python 表示形式（包含一個(gè) JSON 文檔的 str 實(shí)例）。

如果給定的 JSON 文檔無(wú)效則將引發(fā) JSONDecodeError。

raw_decode(s)?

從 s 中解碼出 JSON 文檔（以 JSON 文檔開(kāi)頭的一個(gè) str 對(duì)象）并返回一個(gè) Python 表示形式為 2 元組以及指明該文檔在 s 中結(jié)束位置的序號(hào)。

這可以用于從一個(gè)字符串解碼JSON文檔，該字符串的末尾可能有無(wú)關(guān)的數(shù)據(jù)。

class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)?

用于Python數(shù)據(jù)結(jié)構(gòu)的可擴(kuò)展JSON編碼器。

默認(rèn)支持以下對(duì)象和類(lèi)型：

Python	JSON
dict	object -- 對(duì)象
list, tuple	array
str	string
int, float, int 和 float 派生的枚舉	number
True	true
False	false
None	null

在 3.4 版更改: 添加了對(duì) int 和 float 派生的枚舉類(lèi)的支持

為了將其拓展至識(shí)別其他對(duì)象，需要子類(lèi)化并實(shí)現(xiàn) default() 方法于另一種返回 o 的可序列化對(duì)象的方法如果可行，否則它應(yīng)該調(diào)用超類(lèi)實(shí)現(xiàn)（來(lái)引發(fā) TypeError ）。

如果 skipkeys 為假值（默認(rèn)），則當(dāng)嘗試對(duì)非 str, int, float 或 None 的鍵進(jìn)行編碼時(shí)將會(huì)引發(fā) TypeError。 如果 skipkeys 為真值，這些條目將被直接跳過(guò)。

如果 ensure_ascii 是 true （即默認(rèn)值），輸出保證將所有輸入的非 ASCII 字符轉(zhuǎn)義。如果 ensure_ascii 是 false，這些字符會(huì)原樣輸出。

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

如果 allow_nan 為 true （默認(rèn)），那么 NaN ， Infinity ，和 -Infinity 進(jìn)行編碼。此行為不符合 JSON 規(guī)范，但與大多數(shù)的基于 Javascript 的編碼器和解碼器一致。否則，它將是一個(gè) ValueError 來(lái)編碼這些浮點(diǎn)數(shù)。

如果 sort_keys 為 true （默認(rèn)為： False ），那么字典的輸出是按照鍵排序；這對(duì)回歸測(cè)試很有用，以確?？梢悦刻毂容^ JSON 序列化。

如果 indent 是一個(gè)非負(fù)整數(shù)或者字符串，那么 JSON 數(shù)組元素和對(duì)象成員會(huì)被美化輸出為該值指定的縮進(jìn)等級(jí)。 如果縮進(jìn)等級(jí)為零、負(fù)數(shù)或者 ""，則只會(huì)添加換行符。 None (默認(rèn)值) 選擇最緊湊的表達(dá)。 使用一個(gè)正整數(shù)會(huì)讓每一層縮進(jìn)同樣數(shù)量的空格。 如果 indent 是一個(gè)字符串 (比如 "\t")，那個(gè)字符串會(huì)被用于縮進(jìn)每一層。

在 3.2 版更改: 現(xiàn)允許使用字符串作為 indent 而不再僅僅是整數(shù)。

當(dāng)被指定時(shí)，separators 應(yīng)當(dāng)是一個(gè) (item_separator, key_separator) 元組。當(dāng) indent 為 None 時(shí)，默認(rèn)值取 (', ', ': ')，否則取 (',', ': ')。為了得到最緊湊的 JSON 表達(dá)式，你應(yīng)該指定其為 (',', ':') 以消除空白字符。

在 3.4 版更改: 現(xiàn)當(dāng) indent 不是 None 時(shí)，采用 (',', ': ') 作為默認(rèn)值。

當(dāng) default 被指定時(shí)，其應(yīng)該是一個(gè)函數(shù)，每當(dāng)某個(gè)對(duì)象無(wú)法被序列化時(shí)它會(huì)被調(diào)用。它應(yīng)該返回該對(duì)象的一個(gè)可以被 JSON 編碼的版本或者引發(fā)一個(gè) TypeError。如果沒(méi)有被指定，則會(huì)直接引發(fā) TypeError。

在 3.6 版更改: 所有形參現(xiàn)在都是 僅限關(guān)鍵字參數(shù)。

default(o)?

在子類(lèi)中實(shí)現(xiàn)這種方法使其返回 o 的可序列化對(duì)象，或者調(diào)用基礎(chǔ)實(shí)現(xiàn)（引發(fā) TypeError ）。

例如，為了支持任意的迭代器，你可以這樣來(lái)實(shí)現(xiàn) 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)?

返回 Python o 數(shù)據(jù)結(jié)構(gòu)的 JSON 字符串表達(dá)方式。例如:

>>>

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

iterencode(o)?

編碼給定對(duì)象 o ，并且讓每個(gè)可用的字符串表達(dá)方式。例如:

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

異常?

exception json.JSONDecodeError(msg, doc, pos)?

擁有以下附加屬性的 ValueError 的子類(lèi)：

msg?

未格式化的錯(cuò)誤消息。

doc?

正在解析的 JSON 文檔。

pos?

The start index of doc where parsing failed.

lineno?

The line corresponding to pos.

colno?

The column corresponding to pos.

3.5 新版功能.

標(biāo)準(zhǔn)符合性和互操作性?

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.

此模塊不嚴(yán)格遵循于 RFC ，它實(shí)現(xiàn)了一些擴(kuò)展是有效的 Javascript 但不是有效的 JSON。尤其是：

• 無(wú)限和 NaN 數(shù)值是被接受并輸出；

• 對(duì)象內(nèi)的重復(fù)名稱(chēng)是接受的，并且僅使用最后一對(duì)屬性-值對(duì)的值。

自從 RFC 允許符合 RFC 的語(yǔ)法分析程序接收 不符合 RFC 的輸入文本以來(lái)，這個(gè)模塊的解串器在默認(rèn)狀態(tài)下默認(rèn)符合 RFC 。

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

The json.tool module provides a simple command line interface to validate and pretty-print JSON objects.

如果未指定可選的 infile 和 outfile 參數(shù)，則將分別使用 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)