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

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

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

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

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

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 規(guī)格范圍外的 float 類型值（nan、inf 和 -inf）進行序列化時會引發(fā)一個 ValueError。如果 allow_nan 是 true，則使用它們的 JavaScript 等價形式（NaN、Infinity 和 -Infinity）。

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

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

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

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

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

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

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

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

備注

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

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

備注

JSON 中的鍵-值對中的鍵永遠是 str 類型的。當(dāng)一個對象被轉(zhuǎn)化為 JSON 時，字典中所有的鍵都會被強制轉(zhuǎn)換為字符串。這所造成的結(jié)果是字典被轉(zhuǎn)換為 JSON 然后轉(zhuǎn)換回字典時可能和原來的不相等。換句話說，如果 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)?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

在 3.6 版更改: s 現(xiàn)在可以為 bytes 或 bytearray 類型。 輸入編碼應(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)?

簡單的JSON解碼器。

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

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

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

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

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

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

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

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

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

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

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

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

decode(s)?

返回 s 的 Python 表示形式（包含一個 JSON 文檔的 str 實例）。

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

raw_decode(s)?

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

這可以用于從一個字符串解碼JSON文檔，該字符串的末尾可能有無關(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)的可擴展JSON編碼器。

默認支持以下對象和類型：

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

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

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

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

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

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 進行編碼。此行為不符合 JSON 規(guī)范，但與大多數(shù)的基于 Javascript 的編碼器和解碼器一致。否則，它將是一個 ValueError 來編碼這些浮點數(shù)。

如果 sort_keys 為 true （默認為： False ），那么字典的輸出是按照鍵排序；這對回歸測試很有用，以確保可以每天比較 JSON 序列化。

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

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

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

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

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

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

default(o)?

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

例如，為了支持任意的迭代器，你可以這樣來實現(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 字符串表達方式。例如:

>>>

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

iterencode(o)?

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

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

異常?

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

擁有以下附加屬性的 ValueError 的子類：

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

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

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 ，它實現(xiàn)了一些擴展是有效的 Javascript 但不是有效的 JSON。尤其是：

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

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

自從 RFC 允許符合 RFC 的語法分析程序接收 不符合 RFC 的輸入文本以來，這個模塊的解串器在默認狀態(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 參數(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)