基本使用?

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è) 轉換表 將 obj 序列化為 JSON 格式化流形式的 fp (支持 .write() 的 file-like object)。

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

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

如果 ensure_ascii 是 true （即默認值），輸出保證將所有輸入的非 ASCII 字符轉義。如果 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（默認為 True），那么在對嚴格 JSON 規格范圍外的 float 類(lèi)型值（nan、inf 和 -inf）進(jìn)行序列化時(shí)會(huì )引發(fā)一個(gè) ValueError。如果 allow_nan 是 true，則使用它們的 JavaScript 等價(jià)形式（NaN、Infinity 和 -Infinity）。

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

在 3.2 版更改: 現允許使用字符串作為 indent 而不再僅僅是整數。

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

在 3.4 版更改: 現當 indent 不是 None 時(shí)，采用 (',', ': ') 作為默認值。

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

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

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

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

備注

與 pickle 和 marshal 不同，JSON 不是一個(gè)具有框架的協(xié)議，所以嘗試多次使用同一個(gè) fp 調用 dump() 來(lái)序列化多個(gè)對象會(huì )產(chǎn)生一個(gè)不合規的 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è) 轉換表 將 obj 序列化為 JSON 格式的 str。 其參數的含義與 dump() 中的相同。

備注

JSON 中的鍵-值對中的鍵永遠是 str 類(lèi)型的。當一個(gè)對象被轉化為 JSON 時(shí)，字典中所有的鍵都會(huì )被強制轉換為字符串。這所造成的結果是字典被轉換為 JSON 然后轉換回字典時(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è) 轉換表 將 fp (一個(gè)支持 .read() 并包含一個(gè) JSON 文檔的 text file 或者 binary file) 反序列化為一個(gè) Python 對象。

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

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

在 3.1 版更改: 添加了對 object_pairs_hook 的支持。

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

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

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

在 3.1 版更改: parse_constant 不再調用 'null' ， 'true' ， 'false' 。

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

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

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

在 3.6 版更改: fp 現在可以是 binary file 。輸入編碼應當是 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è) 轉換表 將 s (一個(gè)包含 JSON 文檔的 str, bytes 或 bytearray 實(shí)例) 反序列化為 Python 對象。

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

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

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

在 3.9 版更改: 關(guān)鍵字參數 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解碼器。

默認情況下，解碼執行以下翻譯:

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

它還將“NaN”、“Infinity”和“-Infinity”理解為它們對應的“float”值，這超出了JSON規范。

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

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

在 3.1 版更改: 添加了對 object_pairs_hook 的支持。

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

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

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

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

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

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

decode(s)?

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

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

raw_decode(s)?

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

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

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編碼器。

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

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

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

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

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

如果 ensure_ascii 是 true （即默認值），輸出保證將所有輸入的非 ASCII 字符轉義。如果 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 （默認），那么 NaN ， Infinity ，和 -Infinity 進(jìn)行編碼。此行為不符合 JSON 規范，但與大多數的基于 Javascript 的編碼器和解碼器一致。否則，它將是一個(gè) ValueError 來(lái)編碼這些浮點(diǎn)數。

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

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

在 3.2 版更改: 現允許使用字符串作為 indent 而不再僅僅是整數。

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

在 3.4 版更改: 現當 indent 不是 None 時(shí)，采用 (',', ': ') 作為默認值。

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

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

default(o)?

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

例如，為了支持任意的迭代器，你可以這樣來(lái)實(shí)現 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 數據結構的 JSON 字符串表達方式。例如:

>>>

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

iterencode(o)?

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

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

異常?

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

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

msg?

未格式化的錯誤消息。

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 新版功能.

標準符合性和互操作性?

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.

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

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

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

自從 RFC 允許符合 RFC 的語(yǔ)法分析程序接收 不符合 RFC 的輸入文本以來(lái)，這個(gè)模塊的解串器在默認狀態(tài)下默認符合 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 參數，則將分別使用 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)