`json` --- bộ mã hóa và giải mã JSON¶

Source code: Lib/json/__init__.py

JSON (JavaScript Object Notation), được chỉ định bởi RFC 7159 (đã lỗi thời RFC 4627) và bởi ECMA-404, là một định dạng trao đổi dữ liệu nhẹ lấy cảm hứng từ cú pháp chữ của đối tượng JavaScript (mặc dù nó không phải là một tập hợp con nghiêm ngặt của JavaScript [1] ).

Ghi chú

Thuật ngữ "đối tượng" trong ngữ cảnh xử lý JSON trong Python có thể không rõ ràng. Tất cả các giá trị trong Python đều là đối tượng. Trong JSON, một đối tượng đề cập đến bất kỳ dữ liệu nào được gói trong dấu ngoặc nhọn, tương tự như từ điển Python.

Cảnh báo

Hãy thận trọng khi phân tích dữ liệu JSON từ các nguồn không đáng tin cậy. Chuỗi JSON độc hại có thể khiến bộ giải mã tiêu tốn đáng kể tài nguyên bộ nhớ và CPU. Nên giới hạn kích thước của dữ liệu được phân tích cú pháp.

Mô-đun này hiển thị một API quen thuộc với người dùng mô-đun thư viện marshal và pickle tiêu chuẩn.

Mã hóa phân cấp đối tượng Python cơ bản:

>>> nhập 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}
>>> từ io nhập StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["đang phát trực tuyến API"]'

Mã hóa nhỏ gọn:

>>> nhập json
>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], Separators=(',', ':'))
'[1,2,3,{"4":5,"6":7}]'

In ấn đẹp:

>>> nhập json
>>> print(json.dumps({'6': 7, '4': 5}, Sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}

Tùy chỉnh mã hóa đối tượng JSON:

>>> nhập json
>>> def custom_json(obj):
... if isinstance(obj, complex):
... return {'__complex__': Đúng, 'thực': obj.real, 'hình ảnh': obj.imag}
... raise TypeError(f'Không thể tuần tự hóa đối tượng của {type(obj)}')
...
>>> json.dumps(1 + 2j, default=custom_json)
'{"__complex__": đúng, "thực": 1.0, "hình ảnh": 2.0}'

Giải mã JSON:

>>> nhập json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
['foo', {'bar': ['baz', Không, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
'"foo\x08ar'
>>> từ io nhập StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
['đang phát trực tuyến API']

Tùy chỉnh giải mã đối tượng JSON:

>>> nhập json
>>> def as_complex(dct):
... nếu '__complex__' trong dct:
... trả về phức tạp(dct['real'], dct['imag'])
... trả lại dct
...
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
... object_hook=as_complex)
(1+2j)
>>> nhập số thập phân
>>> json.loads('1.1', parse_float=decimal.Decimal)
Thập phân('1.1')

Mở rộng JSONEncoder:

>>> nhập json
>>> lớp ComplexEncode(json.JSONEncode):
... mặc định mặc định(self, obj):
... if isinstance(obj, complex):
... trả về [obj.real, obj.image]
... # Let phương thức mặc định của lớp cơ sở gây ra TypeError
... trả về super().default(obj)
...
>>> json.dumps(2 + 1j, cls=ComplexEncoding)
'[2.0, 1.0]'
>>> ComplexEncode().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncode().iterencode(2 + 1j))
['[2.0', ', 1.0', ']']

Sử dụng json từ shell để xác thực và in đẹp:

$ echo '{"json://obj"}' | trăn -m json
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | trăn -m json
Yêu cầu tên thuộc tính được đặt trong dấu ngoặc kép: dòng 1 cột 2 (char 1)

Xem Giao diện dòng lệnh để biết tài liệu chi tiết.

Ghi chú

JSON là tập hợp con của YAML 1.2. Zz003zz được tạo bởi cài đặt mặc định của mô-đun này (cụ thể là giá trị separators mặc định) cũng là tập hợp con của YAML 1.0 và 1.1. Do đó, mô-đun này cũng có thể được sử dụng làm bộ nối tiếp YAML.

Ghi chú

Bộ mã hóa và giải mã của mô-đun này duy trì thứ tự đầu vào và đầu ra theo mặc định. Đơn hàng chỉ bị mất nếu các vùng chứa bên dưới không có thứ tự.

Cách sử dụng cơ bản¶

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

Tuần tự hóa obj dưới dạng luồng được định dạng JSON thành fp (file-like object hỗ trợ .write()) bằng cách sử dụng Python-to-JSON conversion table này.

Ghi chú

Không giống như pickle và marshal, JSON không phải là một giao thức được đóng khung, vì vậy việc cố gắng tuần tự hóa nhiều đối tượng bằng các lệnh gọi lặp lại tới dump() bằng cùng một fp sẽ dẫn đến một tệp JSON không hợp lệ.

Tham số:

obj (object) -- Đối tượng Python được tuần tự hóa.
fp (file-like object) -- Đối tượng giống như tệp obj sẽ được tuần tự hóa. Mô-đun json luôn tạo ra các đối tượng str chứ không phải đối tượng bytes, do đó fp.write() phải hỗ trợ đầu vào str.
skipkeys (bool) -- Nếu True, các phím không thuộc loại cơ bản (str, int, float, bool, None) sẽ bị bỏ qua thay vì tăng TypeError. Mặc định False.
ensure_ascii (bool) -- Nếu True (mặc định), đầu ra được đảm bảo có tất cả các ký tự không phải ASCII và không thể in được thoát ra. Nếu False, tất cả các ký tự sẽ được xuất nguyên trạng, ngoại trừ các ký tự phải thoát: dấu ngoặc kép, dấu gạch chéo ngược và các ký tự điều khiển từ U+0000 đến U+001F.
check_circular (bool) -- Nếu False, việc kiểm tra tham chiếu vòng cho các loại vùng chứa bị bỏ qua và tham chiếu vòng sẽ dẫn đến RecursionError (hoặc tệ hơn). Mặc định True.
allow_nan (bool) -- Nếu False, việc tuần tự hóa các giá trị float ngoài phạm vi (nan, inf, -inf) sẽ tạo ra ValueError, tuân thủ nghiêm ngặt thông số kỹ thuật JSON. Nếu True (mặc định), các JavaScript tương đương của chúng (NaN, Infinity, -Infinity) sẽ được sử dụng.
cls (a JSONEncoder subclass) -- Nếu được đặt, một bộ mã hóa JSON tùy chỉnh có phương thức default() được ghi đè để tuần tự hóa thành các kiểu dữ liệu tùy chỉnh. Nếu None (mặc định), JSONEncoder sẽ được sử dụng.
indent (int | str | None) -- Nếu một số nguyên hoặc chuỗi dương, các phần tử mảng và thành phần đối tượng JSON sẽ được in đẹp với mức thụt lề đó. Một số nguyên dương thụt vào nhiều khoảng trắng trên mỗi cấp độ; một chuỗi (chẳng hạn như "\t") được sử dụng để thụt lề từng cấp độ. Nếu bằng 0, âm hoặc "" (chuỗi trống), chỉ các dòng mới được chèn vào. Nếu None (mặc định), cách biểu diễn nhỏ gọn nhất sẽ được sử dụng.
separators (tuple | None) -- Một bộ hai: (item_separator, key_separator). Nếu None (mặc định), separators mặc định là (', ', ': ') nếu indent là None và (',', ': ') nếu ngược lại. Đối với JSON nhỏ gọn nhất, hãy chỉ định (',', ':') để loại bỏ khoảng trắng.
default (callable | None) -- Một hàm được gọi cho các đối tượng không thể được sắp xếp theo thứ tự. Nó sẽ trả về phiên bản mã hóa JSON của đối tượng hoặc tăng TypeError. Nếu None (mặc định), TypeError được nâng lên.
sort_keys (bool) -- Nếu True, từ điển sẽ được xuất ra được sắp xếp theo khóa. Mặc định False.

Thay đổi trong phiên bản 3.2: Cho phép chuỗi cho indent ngoài số nguyên.

Thay đổi trong phiên bản 3.4: Sử dụng (',', ': ') làm mặc định nếu indent không phải là None.

Thay đổi trong phiên bản 3.6: Tất cả các tham số tùy chọn bây giờ là keyword-only.

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)¶: Nối tiếp obj thành str được định dạng JSON bằng cách sử dụng conversion table này. Các đối số có cùng ý nghĩa như trong dump().

Ghi chú

Các khóa trong cặp khóa/giá trị của JSON luôn thuộc loại str. Khi một từ điển được chuyển đổi thành JSON, tất cả các khóa của từ điển sẽ bị ép buộc thành chuỗi. Kết quả của việc này là nếu một từ điển được chuyển đổi thành JSON rồi quay trở lại từ điển, từ điển có thể không bằng từ điển gốc. Nghĩa là, loads(dumps(x)) != x nếu x có khóa không phải chuỗi.

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

Giải tuần tự hóa fp thành đối tượng Python bằng JSON-to-Python conversion table.

Tham số:

fp (file-like object) -- Một text file hoặc binary file hỗ trợ .read() chứa tài liệu JSON sẽ được giải tuần tự hóa.
cls (a JSONDecoder subclass) -- Nếu được đặt, bộ giải mã JSON tùy chỉnh. Các đối số từ khóa bổ sung cho load() sẽ được chuyển tới hàm tạo của cls. Nếu None (mặc định), JSONDecoder sẽ được sử dụng.
object_hook (callable | None) -- Nếu được đặt, một hàm được gọi với kết quả của bất kỳ đối tượng JSON nào được giải mã theo nghĩa đen (dict). Giá trị trả về của hàm này sẽ được sử dụng thay cho dict. Tính năng này có thể được sử dụng để triển khai bộ giải mã tùy chỉnh, ví dụ như gợi ý lớp JSON-RPC. Mặc định None.
object_pairs_hook (callable | None) -- Nếu được đặt, một hàm được gọi với kết quả của bất kỳ đối tượng JSON nào được giải mã bằng danh sách các cặp có thứ tự. Giá trị trả về của hàm này sẽ được sử dụng thay cho dict. Tính năng này có thể được sử dụng để triển khai bộ giải mã tùy chỉnh. Nếu object_hook cũng được đặt thì object_pairs_hook sẽ được ưu tiên. Mặc định None.
parse_float (callable | None) -- Nếu được đặt, một hàm được gọi với chuỗi của mỗi float JSON sẽ được giải mã. Nếu None (mặc định) thì tương đương với float(num_str). Điều này có thể được sử dụng để phân tích các float JSON thành các kiểu dữ liệu tùy chỉnh, ví dụ: decimal.Decimal.
parse_int (callable | None) -- Nếu được đặt, một hàm được gọi với chuỗi mỗi int JSON sẽ được giải mã. Nếu None (mặc định) thì tương đương với int(num_str). Điều này có thể được sử dụng để phân tích các số nguyên JSON thành các kiểu dữ liệu tùy chỉnh, ví dụ: float.
parse_constant (callable | None) -- Nếu được đặt, hàm sẽ được gọi bằng một trong các chuỗi sau: '-Infinity', 'Infinity' hoặc 'NaN'. Điều này có thể được sử dụng để đưa ra một ngoại lệ nếu gặp phải số JSON không hợp lệ. Mặc định None.

Đưa ra:

JSONDecodeError -- Khi dữ liệu được giải tuần tự hóa không phải là tài liệu JSON hợp lệ.
UnicodeDecodeError -- Khi dữ liệu được giải tuần tự hóa không chứa dữ liệu được mã hóa UTF-8, UTF-16 hoặc UTF-32.

Thay đổi trong phiên bản 3.1:

Đã thêm tham số object_pairs_hook tùy chọn.
parse_constant không còn được gọi là 'null', 'true', 'false' nữa.

Thay đổi trong phiên bản 3.6:

Tất cả các tham số tùy chọn bây giờ là keyword-only.
fp bây giờ có thể là binary file. Mã hóa đầu vào phải là UTF-8, UTF-16 hoặc UTF-32.

Thay đổi trong phiên bản 3.11: parse_int mặc định của int() hiện giới hạn độ dài tối đa của chuỗi số nguyên thông qua integer string conversion length limitation của trình thông dịch để giúp tránh các cuộc tấn công từ chối dịch vụ.

json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)¶: Giống hệt với load(), nhưng thay vì đối tượng giống như tệp, hãy giải tuần tự hóa s (một phiên bản str, bytes hoặc bytearray chứa tài liệu JSON) thành đối tượng Python bằng cách sử dụng conversion table này.

Thay đổi trong phiên bản 3.6: s bây giờ có thể thuộc loại bytes hoặc bytearray. Mã hóa đầu vào phải là UTF-8, UTF-16 hoặc UTF-32.

Thay đổi trong phiên bản 3.9: Đối số từ khóa encoding đã bị xóa.

Bộ mã hóa và giải mã¶

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

Bộ giải mã JSON đơn giản.

Thực hiện các bản dịch sau trong quá trình giải mã theo mặc định:

JSON	Python
vật thể	mệnh lệnh
mảng	danh sách
chuỗi	str
số (int)	int
số (thực)	phao
đúng	đúng
sai	sai
vô giá trị	không có

Nó cũng hiểu NaN, Infinity và -Infinity là các giá trị float tương ứng, nằm ngoài thông số JSON.

object_hook là một hàm tùy chọn sẽ được gọi với kết quả của mọi đối tượng JSON được giải mã và giá trị trả về của nó sẽ được sử dụng thay cho dict đã cho. Điều này có thể được sử dụng để cung cấp khả năng khử lưu lượng tùy chỉnh (ví dụ: để hỗ trợ gợi ý lớp JSON-RPC).

object_pairs_hook là một hàm tùy chọn sẽ được gọi với kết quả của mọi đối tượng JSON được giải mã bằng danh sách các cặp có thứ tự. Giá trị trả về của object_pairs_hook sẽ được sử dụng thay vì dict. Tính năng này có thể được sử dụng để triển khai bộ giải mã tùy chỉnh. Nếu object_hook cũng được xác định thì object_pairs_hook sẽ được ưu tiên.

Thay đổi trong phiên bản 3.1: Đã thêm hỗ trợ cho object_pairs_hook.

parse_float là một hàm tùy chọn sẽ được gọi cùng với chuỗi của mỗi float JSON được giải mã. Theo mặc định, điều này tương đương với float(num_str). Điều này có thể được sử dụng để sử dụng kiểu dữ liệu hoặc trình phân tích cú pháp khác cho các số float JSON (ví dụ: decimal.Decimal).

parse_int là một hàm tùy chọn sẽ được gọi cùng với chuỗi của mỗi JSON int cần được giải mã. Theo mặc định, điều này tương đương với int(num_str). Điều này có thể được sử dụng để sử dụng kiểu dữ liệu hoặc trình phân tích cú pháp khác cho số nguyên JSON (ví dụ: float).

parse_constant là một hàm tùy chọn sẽ được gọi bằng một trong các chuỗi sau: '-Infinity', 'Infinity', 'NaN'. Điều này có thể được sử dụng để đưa ra một ngoại lệ nếu gặp phải số JSON không hợp lệ.

Nếu strict sai (True là mặc định), thì các ký tự điều khiển sẽ được phép bên trong chuỗi. Ký tự điều khiển trong ngữ cảnh này là những ký tự có mã ký tự trong phạm vi 0--31, bao gồm '\t' (tab), '\n', '\r' và '\0'.

Nếu dữ liệu được giải tuần tự hóa không phải là tài liệu JSON hợp lệ thì JSONDecodeError sẽ được nâng lên.

Thay đổi trong phiên bản 3.6: Tất cả các thông số bây giờ là keyword-only.

decode(s)¶

Trả về biểu diễn Python của s (một phiên bản str chứa tài liệu JSON).

JSONDecodeError sẽ được nâng lên nếu tài liệu JSON đã cho không hợp lệ.

raw_decode(s)¶

Giải mã tài liệu JSON từ s (str bắt đầu bằng tài liệu JSON) và trả về 2 bộ dữ liệu biểu diễn Python và chỉ mục trong s nơi tài liệu kết thúc.

Điều này có thể được sử dụng để giải mã tài liệu JSON từ một chuỗi có thể có dữ liệu không liên quan ở cuối.

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

Bộ mã hóa JSON mở rộng cho cấu trúc dữ liệu Python.

Hỗ trợ các đối tượng và loại sau theo mặc định:

Python	JSON
mệnh lệnh	vật thể
danh sách, bộ dữ liệu	mảng
str	chuỗi
Enums có nguồn gốc từ int, float, int & float	con số
đúng	đúng
sai	sai
không có	vô giá trị

Thay đổi trong phiên bản 3.4: Đã thêm hỗ trợ cho các lớp Enum có nguồn gốc từ int và float.

Để mở rộng điều này để nhận dạng các đối tượng khác, hãy phân lớp và triển khai phương thức default() bằng một phương thức khác trả về một đối tượng có thể tuần tự hóa cho o nếu có thể, nếu không thì nên gọi triển khai siêu lớp (để nâng cao TypeError).

Nếu skipkeys là sai (mặc định), TypeError sẽ được nâng lên khi cố mã hóa các khóa không phải là str, int, float, bool hoặc None. Nếu skipkeys là đúng, những mục đó sẽ bị bỏ qua.

Nếu ensure_ascii là đúng (mặc định), đầu ra được đảm bảo có tất cả các ký tự không phải ASCII và không thể in được thoát ra. Nếu ensure_ascii là sai, tất cả các ký tự sẽ được xuất ra nguyên trạng, ngoại trừ các ký tự phải thoát: dấu ngoặc kép, dấu gạch chéo ngược và các ký tự điều khiển từ U+0000 đến U+001F.

Nếu check_circular là đúng (mặc định), thì danh sách, ký tự và đối tượng được mã hóa tùy chỉnh sẽ được kiểm tra để tìm tham chiếu vòng tròn trong quá trình mã hóa nhằm ngăn chặn đệ quy vô hạn (có thể gây ra RecursionError). Nếu không, việc kiểm tra như vậy sẽ không diễn ra.

Nếu allow_nan là đúng (mặc định) thì NaN, Infinity và -Infinity sẽ được mã hóa như vậy. Hành vi này không tuân thủ thông số kỹ thuật JSON nhưng phù hợp với hầu hết các bộ mã hóa và giải mã dựa trên JavaScript. Nếu không, sẽ rất khó để mã hóa các số float như vậy.

Nếu sort_keys là true (mặc định: False), thì đầu ra của từ điển sẽ được sắp xếp theo khóa; điều này rất hữu ích cho các thử nghiệm hồi quy để đảm bảo rằng các sê-ri JSON có thể được so sánh hàng ngày.

Nếu indent là một số nguyên hoặc chuỗi không âm thì các phần tử mảng và thành phần đối tượng JSON sẽ được in đẹp với mức thụt lề đó. Mức thụt lề bằng 0, âm hoặc "" sẽ chỉ chèn dòng mới. None (mặc định) chọn cách biểu diễn nhỏ gọn nhất. Sử dụng số nguyên dương thụt lề để thụt nhiều khoảng trắng cho mỗi cấp độ. Nếu indent là một chuỗi (chẳng hạn như "\t"), chuỗi đó được dùng để thụt lề từng cấp độ.

Thay đổi trong phiên bản 3.2: Cho phép chuỗi cho indent ngoài số nguyên.

Nếu được chỉ định, separators phải là một bộ (item_separator, key_separator). Mặc định là (', ', ': ') nếu indent là None và (',', ': ') nếu không. Để có được cách biểu diễn JSON nhỏ gọn nhất, bạn nên chỉ định (',', ':') để loại bỏ khoảng trắng.

Thay đổi trong phiên bản 3.4: Sử dụng (',', ': ') làm mặc định nếu indent không phải là None.

Nếu được chỉ định, default sẽ là một hàm được gọi cho các đối tượng không thể được tuần tự hóa. Nó sẽ trả về phiên bản mã hóa JSON của đối tượng hoặc tăng TypeError. Nếu không được chỉ định, TypeError sẽ được nâng lên.

Thay đổi trong phiên bản 3.6: Tất cả các thông số bây giờ là keyword-only.

default(o)¶

Triển khai phương thức này trong một lớp con sao cho nó trả về một đối tượng có thể tuần tự hóa cho o hoặc gọi triển khai cơ sở (để nâng cao TypeError).

Ví dụ: để hỗ trợ các trình vòng lặp tùy ý, bạn có thể triển khai default() như thế này

mặc định mặc định (tự, o):
   thử:
       lặp lại được = iter(o)
   ngoại trừ Lỗi Loại:
       vượt qua
   khác:
       danh sách trả về (lặp lại)
   # Let phương thức mặc định của lớp cơ sở gây ra TypeError
   trả về super().default(o)

encode(o)¶

Trả về biểu diễn chuỗi JSON của cấu trúc dữ liệu Python, o. Ví dụ:

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

iterencode(o)¶

Mã hóa đối tượng đã cho, o và mang lại từng biểu diễn chuỗi nếu có. Ví dụ:

cho đoạn trong json.JSONEncode().iterencode(bigobject):
    mysocket.write(chunk)

Ngoại lệ¶

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

Lớp con của ValueError với các thuộc tính bổ sung sau:

msg¶: Thông báo lỗi không được định dạng.

doc¶: Tài liệu JSON đang được phân tích cú pháp.

pos¶: Chỉ mục bắt đầu của doc nơi phân tích cú pháp không thành công.

lineno¶: Dòng tương ứng với pos.

colno¶: Cột tương ứng với pos.

Added in version 3.5.

Tuân thủ tiêu chuẩn và khả năng tương tác¶

Định dạng JSON được chỉ định bởi RFC 7159 và ECMA-404. Phần này nêu chi tiết mức độ tuân thủ của mô-đun này với RFC. Để đơn giản, các lớp con JSONEncoder và JSONDecoder cũng như các tham số khác ngoài những tham số được đề cập rõ ràng sẽ không được xem xét.

Mô-đun này không tuân thủ RFC một cách nghiêm ngặt, triển khai một số tiện ích mở rộng là JavaScript hợp lệ nhưng không hợp lệ JSON. Đặc biệt:

Giá trị số vô hạn và NaN được chấp nhận và xuất ra;
Các tên lặp lại trong một đối tượng được chấp nhận và chỉ sử dụng giá trị của cặp giá trị tên cuối cùng.

Vì RFC cho phép các trình phân tích cú pháp tuân thủ RFC chấp nhận văn bản đầu vào không tuân thủ RFC, nên trình giải tuần tự của mô-đun này tuân thủ về mặt kỹ thuật RFC trong cài đặt mặc định.

Mã hóa ký tự¶

RFC yêu cầu JSON phải được thể hiện bằng UTF-8, UTF-16 hoặc UTF-32, với UTF-8 là mặc định được đề xuất để có khả năng tương tác tối đa.

Như được RFC cho phép, mặc dù không bắt buộc, bộ tuần tự hóa của mô-đun này đặt ensure_ascii=True theo mặc định, do đó thoát khỏi đầu ra để các chuỗi kết quả chỉ chứa các ký tự ASCII có thể in được.

Khác với tham số ensure_ascii, mô-đun này được xác định nghiêm ngặt về mặt chuyển đổi giữa các đối tượng Python và Unicode strings và do đó không trực tiếp giải quyết vấn đề mã hóa ký tự.

RFC cấm thêm dấu thứ tự byte (BOM) vào đầu văn bản JSON và bộ tuần tự hóa của mô-đun này không thêm BOM vào đầu ra của nó. RFC cho phép, nhưng không yêu cầu, bộ giải tuần tự JSON bỏ qua BOM ban đầu trong đầu vào của chúng. Trình giải tuần tự của mô-đun này tăng ValueError khi có BOM ban đầu.

RFC không cấm rõ ràng các chuỗi JSON chứa các chuỗi byte không tương ứng với các ký tự Unicode hợp lệ (ví dụ: các đại diện thay thế UTF-16 không ghép đôi), nhưng lưu ý rằng chúng có thể gây ra các vấn đề về khả năng tương tác. Theo mặc định, mô-đun này chấp nhận và xuất ra các điểm mã (khi có trong str gốc) cho các chuỗi như vậy.

Giá trị số vô hạn và NaN¶

Zz003zz không cho phép biểu diễn các giá trị số vô hạn hoặc NaN. Mặc dù vậy, theo mặc định, mô-đun này chấp nhận và xuất ra Infinity, -Infinity và NaN như thể chúng là các giá trị chữ số JSON hợp lệ:

>>> # Neither trong số các cuộc gọi này đưa ra một ngoại lệ, nhưng kết quả không hợp lệ JSON
>>> json.dumps(float('-inf'))
'-Vô cực'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same khi giải tuần tự hóa
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan

Trong bộ nối tiếp, tham số allow_nan có thể được sử dụng để thay đổi hành vi này. Trong trình giải tuần tự, tham số parse_constant có thể được sử dụng để thay đổi hành vi này.

Tên lặp đi lặp lại trong một đối tượng¶

RFC chỉ định rằng các tên trong đối tượng JSON phải là duy nhất, nhưng không bắt buộc cách xử lý các tên lặp lại trong đối tượng JSON. Theo mặc định, mô-đun này không đưa ra ngoại lệ; thay vào đó, nó bỏ qua tất cả ngoại trừ cặp tên-giá trị cuối cùng cho một tên đã cho:

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

Tham số object_pairs_hook có thể được sử dụng để thay đổi hành vi này.

Giá trị không phải đối tượng, không phải mảng cấp cao nhất¶

Phiên bản cũ của JSON được chỉ định bởi RFC 4627 lỗi thời yêu cầu giá trị cấp cao nhất của văn bản JSON phải là đối tượng hoặc mảng JSON (Python dict hoặc list) và không được là giá trị null, boolean, số hoặc chuỗi JSON. RFC 7159 đã loại bỏ hạn chế đó và mô-đun này không và chưa bao giờ triển khai hạn chế đó trong bộ tuần tự hóa hoặc bộ giải tuần tự của nó.

Bất chấp điều đó, để có khả năng tương tác tối đa, bạn có thể muốn tự mình tuân thủ hạn chế.

Hạn chế thực hiện¶

Một số triển khai trình giải tuần tự JSON có thể đặt giới hạn cho:

kích thước của văn bản JSON được chấp nhận
mức lồng nhau tối đa của các đối tượng và mảng JSON
phạm vi và độ chính xác của số JSON
nội dung và độ dài tối đa của chuỗi JSON

Mô-đun này không áp đặt bất kỳ giới hạn nào như vậy ngoài các giới hạn của chính các kiểu dữ liệu Python có liên quan hoặc chính trình thông dịch Python.

Khi tuần tự hóa thành JSON, hãy cẩn thận với mọi hạn chế như vậy trong các ứng dụng có thể tiêu tốn JSON của bạn. Đặc biệt, thông thường các số JSON sẽ được giải tuần tự hóa thành các số có độ chính xác kép IEEE 754 và do đó phải tuân theo các giới hạn về phạm vi và độ chính xác của biểu diễn đó. Điều này đặc biệt có liên quan khi tuần tự hóa các giá trị int của Python có cường độ cực lớn hoặc khi tuần tự hóa các phiên bản của các loại số "kỳ lạ" như decimal.Decimal.

Giao diện dòng lệnh¶

Source code: Lib/json/tool.py

Mô-đun json có thể được gọi dưới dạng tập lệnh thông qua python -m json để xác thực và in các đối tượng JSON đẹp mắt. Mô-đun con json.tool thực hiện giao diện này.

Nếu các đối số infile và outfile tùy chọn không được chỉ định, sys.stdin và sys.stdout sẽ được sử dụng tương ứng:

$ echo '{"json": "obj"}' | trăn -m json
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | trăn -m json
Yêu cầu tên thuộc tính được đặt trong dấu ngoặc kép: dòng 1 cột 2 (char 1)

Thay đổi trong phiên bản 3.5: Đầu ra bây giờ có cùng thứ tự với đầu vào. Sử dụng tùy chọn --sort-keys để sắp xếp đầu ra của từ điển theo thứ tự bảng chữ cái theo khóa.

Thay đổi trong phiên bản 3.14: Mô-đun json hiện có thể được thực thi trực tiếp dưới dạng python -m json. Để tương thích ngược, việc gọi CLI là python -m json.tool vẫn được hỗ trợ.

Tùy chọn dòng lệnh¶

infile¶

Tệp JSON cần được xác thực hoặc được in đẹp:

$ python -m json mp_films.json
[
    {
        "title": "Và bây giờ là điều gì đó hoàn toàn khác",
        "năm": 1971
    },
    {
        "title": "Monty Python và Chén Thánh",
        "năm": 1975
    }
]

Nếu infile không được chỉ định, hãy đọc từ sys.stdin.

outfile¶: Viết đầu ra của infile vào outfile đã cho. Nếu không, hãy ghi nó vào sys.stdout.

--sort-keys¶: Sắp xếp đầu ra của từ điển theo thứ tự bảng chữ cái theo khóa.

Added in version 3.5.

--no-ensure-ascii¶: Tắt tính năng thoát các ký tự không phải mã ascii, xem json.dumps() để biết thêm thông tin.

Added in version 3.9.

--json-lines¶: Phân tích từng dòng đầu vào dưới dạng đối tượng JSON riêng biệt.

Added in version 3.8.

--indent, --tab, --no-indent, --compact¶: Các tùy chọn loại trừ lẫn nhau để kiểm soát khoảng trắng.

Added in version 3.9.

-h, --help¶: Hiển thị thông báo trợ giúp.

Chú thích cuối trang

`json` --- bộ mã hóa và giải mã JSON¶

Cách sử dụng cơ bản¶

Bộ mã hóa và giải mã¶

Ngoại lệ¶

Tuân thủ tiêu chuẩn và khả năng tương tác¶

Mã hóa ký tự¶

Giá trị số vô hạn và NaN¶

Tên lặp đi lặp lại trong một đối tượng¶

Giá trị không phải đối tượng, không phải mảng cấp cao nhất¶

Hạn chế thực hiện¶

Giao diện dòng lệnh¶

Tùy chọn dòng lệnh¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này

json --- bộ mã hóa và giải mã JSON¶

Cách sử dụng cơ bản¶

Bộ mã hóa và giải mã¶

Ngoại lệ¶

Tuân thủ tiêu chuẩn và khả năng tương tác¶

Mã hóa ký tự¶

Giá trị số vô hạn và NaN¶

Tên lặp đi lặp lại trong một đối tượng¶

Giá trị không phải đối tượng, không phải mảng cấp cao nhất¶

Hạn chế thực hiện¶

Giao diện dòng lệnh¶

Tùy chọn dòng lệnh¶

`json` --- bộ mã hóa và giải mã JSON¶