`json.md`

519 строк · 46.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.12/library/json.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `json` – кодировщик и декодировщик JSON89**Исходный код:** [Lib/json/\_\_init\_\_.py](https://python-all.ru/src/3.12/Lib/json/__init__.py)1011---1213[JSON (JavaScript Object Notation)](https://python-all.ru/3.12/library/json.html), описанный в [**RFC 7159**](https://python-all.ru/3.12/library/json.html) (который заменяет [**RFC 4627**](https://python-all.ru/3.12/library/json.html)) и в [ECMA-404](https://python-all.ru/3.12/library/json.html), является легковесным форматом обмена данными, вдохновлённым синтаксисом литералов объектов [JavaScript](https://python-all.ru/3.12/library/json.html) (хотя он не является строгим подмножеством JavaScript [\[1\]](https://python-all.ru/3.12/library/json.html#rfc-errata)).1415> **Предупреждение**16>17> Соблюдайте осторожность при разборе JSON-данных из ненадёжных источников. Злонамеренная JSON-строка может заставить декодер потреблять значительные ресурсы CPU и памяти. Рекомендуется ограничивать размер разбираемых данных.1819[`json`](https://python-all.ru/3.12/library/json.html#module-json) предоставляет API, знакомый пользователям модулей стандартной библиотеки [`marshal`](https://python-all.ru/3.12/library/marshal.html#module-marshal) и [`pickle`](https://python-all.ru/3.12/library/pickle.html#module-pickle).2021Кодирование иерархий базовых объектов Python:2223```python24>>> import json25>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])26'["foo", {"bar": ["baz", null, 1.0, 2]}]'27>>> print(json.dumps("\"foo\bar"))28"\"foo\bar"29>>> print(json.dumps('\u1234'))30"\u1234"31>>> print(json.dumps('\\'))32"\\"33>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))34{"a": 0, "b": 0, "c": 0}35>>> from io import StringIO36>>> io = StringIO()37>>> json.dump(['streaming API'], io)38>>> io.getvalue()39'["streaming API"]'40```4142Компактное кодирование:4344```python45>>> import json46>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))47'[1,2,3,{"4":5,"6":7}]'48```4950Красивое форматирование:5152```python53>>> import json54>>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))55{56    "4": 5,57    "6": 758}59```6061Декодирование JSON:6263```python64>>> import json65>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')66['foo', {'bar': ['baz', None, 1.0, 2]}]67>>> json.loads('"\\"foo\\bar"')68'"foo\x08ar'69>>> from io import StringIO70>>> io = StringIO('["streaming API"]')71>>> json.load(io)72['streaming API']73```7475Специализированное декодирование объектов JSON:7677```python78>>> import json79>>> def as_complex(dct):80...     if '__complex__' in dct:81...         return complex(dct['real'], dct['imag'])82...     return dct83...84>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',85...     object_hook=as_complex)86(1+2j)87>>> import decimal88>>> json.loads('1.1', parse_float=decimal.Decimal)89Decimal('1.1')90```9192Расширение [`JSONEncoder`](https://python-all.ru/3.12/library/json.html#json.JSONEncoder):9394```python95>>> import json96>>> class ComplexEncoder(json.JSONEncoder):97...     def default(self, obj):98...         if isinstance(obj, complex):99...             return [obj.real, obj.imag]100...         # Пусть метод базового класса по умолчанию возбуждает TypeError101...         return super().default(obj)102...103>>> json.dumps(2 + 1j, cls=ComplexEncoder)104'[2.0, 1.0]'105>>> ComplexEncoder().encode(2 + 1j)106'[2.0, 1.0]'107>>> list(ComplexEncoder().iterencode(2 + 1j))108['[2.0', ', 1.0', ']']109```110111Использование [`json.tool`](https://python-all.ru/3.12/library/json.html#module-json.tool) из командной оболочки для проверки и красивого вывода:112113```console114$ echo '{"json":"obj"}' | python -m json.tool115{116    "json": "obj"117}118$ echo '{1.2:3.4}' | python -m json.tool119Expecting property name enclosed in double quotes: line 1 column 2 (char 1)120```121122Смотрите [интерфейс командной строки](https://python-all.ru/3.12/library/json.html#json-commandline) для подробной документации.123124> **Примечание**125>126> JSON является подмножеством [YAML](https://python-all.ru/3.12/library/json.html) 1.2. JSON, создаваемый настройками модуля по умолчанию (в частности, значением *separators* по умолчанию), также является подмножеством YAML 1.0 и 1.1. Таким образом, этот модуль можно использовать как сериализатор YAML.127128> **Примечание**129>130> Кодировщики и декодировщики этого модуля по умолчанию сохраняют порядок ввода и вывода. Порядок теряется только в том случае, если основные контейнеры неупорядочены.131132## Основное использование133134#### `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)`135136Сериализует *obj* в поток в формате JSON в *fp* (`.write()`-поддерживающий [файлоподобный объект](https://python-all.ru/3.12/glossary.html#term-file-like-object)), используя [таблицу преобразования Python в JSON](https://python-all.ru/3.12/library/json.html#py-to-json-table).137138> **Примечание**139>140> В отличие от [`pickle`](https://python-all.ru/3.12/library/pickle.html#module-pickle) и [`marshal`](https://python-all.ru/3.12/library/marshal.html#module-marshal), JSON не является фреймовым протоколом, поэтому попытка сериализовать несколько объектов с повторными вызовами [`dump()`](https://python-all.ru/3.12/library/json.html#json.dump) с использованием одного и того же *fp* приведёт к созданию недопустимого JSON-файла.141142**Параметры:**143144- **obj** ([*object*](https://python-all.ru/3.12/library/functions.html#object)) – Сериализуемый объект Python.145- **fp** ([файлоподобный объект](https://python-all.ru/3.12/glossary.html#term-file-like-object)) – Файлоподобный объект, в который будет сериализован *obj*. Модуль `json` всегда создаёт объекты [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), а не [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes), поэтому `fp.write()` должен поддерживать ввод [`str`](https://python-all.ru/3.12/library/stdtypes.html#str).146- **skipkeys** ([*bool*](https://python-all.ru/3.12/library/functions.html#bool)) – Если `True`, ключи, не являющиеся базовым типом ([`str`](https://python-all.ru/3.12/library/stdtypes.html#str), [`int`](https://python-all.ru/3.12/library/functions.html#int), [`float`](https://python-all.ru/3.12/library/functions.html#float), [`bool`](https://python-all.ru/3.12/library/functions.html#bool), `None`), будут пропущены вместо возбуждения [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError). По умолчанию `False`.147- **ensure\_ascii** ([*bool*](https://python-all.ru/3.12/library/functions.html#bool)) – Если `True` (по умолчанию), выходные данные гарантированно будут содержать все не-ASCII символы экранированными. Если `False`, эти символы будут выводиться как есть.148- **check\_circular** ([*bool*](https://python-all.ru/3.12/library/functions.html#bool)) – Если `False`, проверка циклических ссылок для контейнерных типов пропускается, и циклическая ссылка приведёт к [`RecursionError`](https://python-all.ru/3.12/library/exceptions.html#RecursionError) (или хуже). По умолчанию `True`.149- **allow\_nan** ([*bool*](https://python-all.ru/3.12/library/functions.html#bool)) – Если `False`, сериализация значений [`float`](https://python-all.ru/3.12/library/functions.html#float) вне допустимого диапазона (`nan`, `inf`, `-inf`) вызовет [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError) в строгом соответствии со спецификацией JSON. Если `True` (по умолчанию), используются их эквиваленты в JavaScript (`NaN`, `Infinity`, `-Infinity`).150- **cls** (подкласс [`JSONEncoder`](https://python-all.ru/3.12/library/json.html#json.JSONEncoder)) – Если задан, пользовательский кодировщик JSON с переопределённым методом [`default()`](https://python-all.ru/3.12/library/json.html#json.JSONEncoder.default), для сериализации в пользовательские типы данных. Если `None` (по умолчанию), используется `JSONEncoder`.151- **indent** ([*int*](https://python-all.ru/3.12/library/functions.html#int) *|* [*str*](https://python-all.ru/3.12/library/stdtypes.html#str) *|* *None*) – Если положительное целое число или строка, элементы массива JSON и члены объекта будут отформатированы с отступом этого уровня. Положительное целое число задаёт количество пробелов на уровень; строка (например, `"\t"`) используется для отступа каждого уровня. Если ноль, отрицательное или `""` (пустая строка), вставляются только переводы строк. Если `None` (по умолчанию), используется наиболее компактное представление.152- **separators** ([*tuple*](https://python-all.ru/3.12/library/stdtypes.html#tuple) *|* *None*) – Кортеж из двух элементов: `(item_separator, key_separator)`. Если `None` (по умолчанию), *separators* по умолчанию равен `(', ', ': ')`, если *indent* равен `None`, и `(',', ': ')` в противном случае. Для максимально компактного JSON укажите `(',', ':')`, чтобы убрать пробелы.153- **default** ([callable](https://python-all.ru/3.12/glossary.html#term-callable) | None) – Функция, вызываемая для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта, кодируемую в JSON, или возбуждать [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError). Если `None` (по умолчанию), возбуждается `TypeError`.154- **sort\_keys** ([*bool*](https://python-all.ru/3.12/library/functions.html#bool)) – если `True`, словари будут выводиться отсортированными по ключам. По умолчанию `False`.155156Изменено в версии 3.2: Разрешено использование строк для *indent* в дополнение к целым числам.157158Изменено в версии 3.4: Используйте `(',', ': ')` по умолчанию, если *indent* не равно `None`.159160Изменено в версии 3.6: Все необязательные параметры теперь являются [только ключевыми](https://python-all.ru/3.12/glossary.html#keyword-only-parameter).161162#### `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)`163164Сериализует *obj* в JSON-форматированную [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), используя эту [таблицу преобразования](https://python-all.ru/3.12/library/json.html#py-to-json-table). Аргументы имеют тот же смысл, что и в [`dump()`](https://python-all.ru/3.12/library/json.html#json.dump).165166> **Примечание**167>168> Ключи в парах ключ-значение JSON всегда имеют тип [`str`](https://python-all.ru/3.12/library/stdtypes.html#str). При преобразовании словаря в JSON все его ключи приводятся к строкам. В результате, если словарь преобразовать в JSON, а затем обратно в словарь, полученный словарь может не совпадать с исходным. То есть `loads(dumps(x)) != x`, если x имеет нестроковые ключи.169170#### `json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)`171172Десериализует *fp* в объект Python, используя [таблицу преобразования JSON в Python](https://python-all.ru/3.12/library/json.html#json-to-py-table).173174**Параметры:**175176- **fp** ([файлоподобный объект](https://python-all.ru/3.12/glossary.html#term-file-like-object)) – поддерживающий `.read()` [текстовый файл](https://python-all.ru/3.12/glossary.html#term-text-file) или [двоичный файл](https://python-all.ru/3.12/glossary.html#term-binary-file), содержащий JSON-документ для десериализации.177- **cls** (подкласс [`JSONDecoder`](https://python-all.ru/3.12/library/json.html#json.JSONDecoder)) – если задан, пользовательский JSON-декодер. Дополнительные именованные аргументы для `load()` будут переданы конструктору *cls*. Если `None` (по умолчанию), используется `JSONDecoder`.178- **object\_hook** ([callable](https://python-all.ru/3.12/glossary.html#term-callable) | None) – Если задано, функция, которая вызывается с результатом декодирования любого объектного литерала ([`dict`](https://python-all.ru/3.12/library/stdtypes.html#dict)). Возвращаемое значение этой функции будет использовано вместо [`dict`](https://python-all.ru/3.12/library/stdtypes.html#dict). Эту возможность можно использовать для реализации пользовательских декодеров, например, для подсказки класса [JSON-RPC](https://python-all.ru/3.12/library/json.html). По умолчанию `None`.179- **object\_pairs\_hook** ([callable](https://python-all.ru/3.12/glossary.html#term-callable) | None) – Если задано, функция, которая вызывается с результатом декодирования любого объектного литерала в виде упорядоченного списка пар. Возвращаемое значение этой функции будет использовано вместо [`dict`](https://python-all.ru/3.12/library/stdtypes.html#dict). Эту возможность можно использовать для реализации пользовательских декодеров. Если также задан *object\_hook*, приоритет имеет *object\_pairs\_hook*. По умолчанию `None`.180- **parse\_float** ([вызываемый объект](https://python-all.ru/3.12/glossary.html#term-callable) | None) – если задан, функция, вызываемая со строкой каждого JSON-числа с плавающей точкой для декодирования. Если `None` (по умолчанию), это эквивалентно `float(num_str)`. Это может использоваться для парсинга JSON-чисел с плавающей точкой в пользовательские типы данных, например, [`decimal.Decimal`](https://python-all.ru/3.12/library/decimal.html#decimal.Decimal).181- **parse\_int** ([вызываемый объект](https://python-all.ru/3.12/glossary.html#term-callable) | None) – если задан, функция, вызываемая со строкой каждого JSON-целого для декодирования. Если `None` (по умолчанию), это эквивалентно `int(num_str)`. Это может использоваться для парсинга JSON-целых чисел в пользовательские типы данных, например, [`float`](https://python-all.ru/3.12/library/functions.html#float).182- **parse\_constant** ([вызываемый объект](https://python-all.ru/3.12/glossary.html#term-callable) | None) – если задан, функция, вызываемая с одной из следующих строк: `'-Infinity'`, `'Infinity'` или `'NaN'`. Это может использоваться для возбуждения исключения при обнаружении некорректных JSON-чисел. По умолчанию `None`.183184**Возбуждает:**185186- [**JSONDecodeError**](https://python-all.ru/3.12/library/json.html#json.JSONDecodeError) – когда десериализуемые данные не являются корректным JSON-документом.187- [**UnicodeDecodeError**](https://python-all.ru/3.12/library/exceptions.html#UnicodeDecodeError) – когда десериализуемые данные не содержат данные в кодировке UTF-8, UTF-16 или UTF-32.188189Изменено в версии 3.1:190191- Добавлен необязательный параметр *object\_pairs\_hook*.192- *parse\_constant* больше не вызывается для 'null', 'true', 'false'.193194Изменено в версии 3.6:195196- Все необязательные параметры теперь являются [только ключевыми](https://python-all.ru/3.12/glossary.html#keyword-only-parameter).197- *fp* теперь может быть [двоичным файлом](https://python-all.ru/3.12/glossary.html#term-binary-file). Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.198199Изменено в версии 3.11: Значение *parse\_int* по умолчанию в [`int()`](https://python-all.ru/3.12/library/functions.html#int) теперь ограничивает максимальную длину строки целого числа через [ограничение длины преобразования строки целого числа](https://python-all.ru/3.12/library/stdtypes.html#int-max-str-digits) интерпретатора, чтобы помочь избежать атак типа «отказ в обслуживании».200201#### `json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)`202203Идентично [`load()`](https://python-all.ru/3.12/library/json.html#json.load), но вместо файлоподобного объекта десериализует *s* (экземпляр [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.12/library/stdtypes.html#bytearray), содержащий JSON-документ) в объект Python, используя эту [таблицу преобразования](https://python-all.ru/3.12/library/json.html#json-to-py-table).204205Изменено в версии 3.6: *s* теперь может быть типа [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.12/library/stdtypes.html#bytearray). Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.206207Изменено в версии 3.9: Именованный аргумент *encoding* удален.208209## Кодировщики и декодеры210211#### `class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)`212213Простой JSON-декодер.214215По умолчанию выполняет следующие преобразования при декодировании:216217| JSON | Python |218| --- | --- |219| объект | dict |220| массив | list |221| строка | str |222| число (int) | int |223| число (вещественное) | float |224| true | True |225| false | False |226| null | None |227228Также `NaN`, `Infinity` и `-Infinity` распознаются как соответствующие значения `float`, что выходит за рамки спецификации JSON.229230*object\_hook* – необязательная функция, которая вызывается с результатом декодирования каждого JSON-объекта; её возвращаемое значение используется вместо переданного [`dict`](https://python-all.ru/3.12/library/stdtypes.html#dict). Это позволяет задавать собственную десериализацию (например, для поддержки подсказок классов [JSON-RPC](https://python-all.ru/3.12/library/json.html)).231232*object\_pairs\_hook* – необязательная функция, которая вызывается с результатом декодирования каждого JSON-объекта в виде упорядоченного списка пар. Возвращаемое значение *object\_pairs\_hook* будет использоваться вместо [`dict`](https://python-all.ru/3.12/library/stdtypes.html#dict). Этот механизм позволяет реализовывать собственные декодеры. Если также определён *object\_hook*, приоритет имеет *object\_pairs\_hook*.233234Изменено в версии 3.1: Добавлена поддержка *object\_pairs\_hook*.235236*parse\_float* – необязательная функция, которая вызывается со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию она эквивалентна `float(num_str)`. Это позволяет использовать другой тип данных или синтаксический анализатор для чисел с плавающей точкой (например, [`decimal.Decimal`](https://python-all.ru/3.12/library/decimal.html#decimal.Decimal)).237238*parse\_int* – необязательная функция, которая вызывается со строкой каждого декодируемого JSON-целого числа. По умолчанию она эквивалентна `int(num_str)`. Это позволяет использовать другой тип данных или синтаксический анализатор для целых чисел JSON (например, [`float`](https://python-all.ru/3.12/library/functions.html#float)).239240*parse\_constant* – необязательная функция, которая вызывается с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`. Это позволяет вызывать исключение при обнаружении недопустимых чисел JSON.241242Если *strict* равно false (по умолчанию `True`), то управляющие символы допускаются внутри строк. Под управляющими символами здесь понимаются символы с кодами в диапазоне 0–31, включая `'\t'` (табуляция), `'\n'`, `'\r'` и `'\0'`.243244Если десериализуемые данные не являются корректным JSON-документом, будет вызвано [`JSONDecodeError`](https://python-all.ru/3.12/library/json.html#json.JSONDecodeError).245246Изменено в версии 3.6: Все параметры теперь [только ключевые](https://python-all.ru/3.12/glossary.html#keyword-only-parameter).247248#### `decode(s)`249250Возвращает представление *s* в Python (экземпляр [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), содержащий JSON-документ).251252[`JSONDecodeError`](https://python-all.ru/3.12/library/json.html#json.JSONDecodeError) будет вызвано, если переданный JSON-документ не является корректным.253254#### `raw_decode(s)`255256Декодирует JSON-документ из *s* ([`str`](https://python-all.ru/3.12/library/stdtypes.html#str), начинающийся с JSON-документа) и возвращает кортеж из двух элементов: представления в Python и индекса в *s*, на котором документ заканчивается.257258Это можно использовать для декодирования JSON-документа из строки, в конце которой могут быть лишние данные.259260#### `class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)`261262Расширяемый JSON-кодировщик для структур данных Python.263264По умолчанию поддерживает следующие объекты и типы:265266| Python | JSON |267| --- | --- |268| dict | объект |269| list, tuple | массив |270| str | строка |271| int, float, перечисления, производные от int и float | число |272| True | true |273| False | false |274| None | null |275276Изменено в версии 3.4: Добавлена поддержка классов Enum, производных от int и float.277278Чтобы расширить функциональность на другие объекты, создайте подкласс и реализуйте метод [`default()`](https://python-all.ru/3.12/library/json.html#json.JSONEncoder.default) с другим методом, который возвращает сериализуемый объект для `o`, если это возможно; в противном случае следует вызвать реализацию суперкласса (для возбуждения [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError)).279280Если *skipkeys* имеет значение false (по умолчанию), возбуждается [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError) при попытке кодировать ключи, не являющиеся [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), [`int`](https://python-all.ru/3.12/library/functions.html#int), [`float`](https://python-all.ru/3.12/library/functions.html#float), [`bool`](https://python-all.ru/3.12/library/functions.html#bool) или `None`. Если *skipkeys* равно true, такие элементы просто пропускаются.281282Если *ensure\_ascii* равен true (по умолчанию), то выходные данные гарантированно содержат все входящие не-ASCII-символы экранированными. Если *ensure\_ascii* равен false, эти символы выводятся как есть.283284Если *check\_circular* равно true (по умолчанию), то списки, словари и пользовательские объекты проверяются на циклические ссылки во время кодирования для предотвращения бесконечной рекурсии (которая вызвала бы [`RecursionError`](https://python-all.ru/3.12/library/exceptions.html#RecursionError)). В противном случае такая проверка не выполняется.285286Если *allow\_nan* равно true (по умолчанию), то значения `NaN`, `Infinity` и `-Infinity` кодируются как есть. Такое поведение не соответствует спецификации JSON, но согласуется с большинством кодировщиков и декодировщиков на JavaScript. В противном случае при кодировании таких чисел с плавающей запятой возбуждается [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).287288Если *sort\_keys* равно true (по умолчанию `False`), то вывод словарей сортируется по ключам; это полезно для регрессионных тестов, чтобы обеспечить возможность сравнения JSON-сериализаций день ото дня.289290Если *indent* – неотрицательное целое число или строка, то элементы JSON-массивов и члены объектов выводятся с отступами, соответствующими указанному уровню. Уровень отступа 0, отрицательное значение или `""` вставляет только переводы строк. `None` (по умолчанию) выбирает наиболее компактное представление. Положительное целое значение отступа задаёт количество пробелов на уровень. Если *indent* является строкой (например, `"\t"`), эта строка используется для отступа каждого уровня.291292Изменено в версии 3.2: Разрешено использование строк для *indent* в дополнение к целым числам.293294Если указан, то *separators* должен быть кортежем `(item_separator, key_separator)`. По умолчанию используется `(', ', ': ')`, если *indent* равно `None`, и `(',', ': ')` в противном случае. Для получения наиболее компактного JSON-представления укажите `(',', ':')`, чтобы убрать пробелы.295296Изменено в версии 3.4: Используйте `(',', ': ')` по умолчанию, если *indent* не равно `None`.297298Если указан, *default* должен быть функцией, которая вызывается для объектов, которые не могут быть сериализованы иным способом. Она должна возвращать версию объекта, пригодную для JSON-кодирования, или возбуждать [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError). Если не указано, возбуждается [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError).299300Изменено в версии 3.6: Все параметры теперь [только ключевые](https://python-all.ru/3.12/glossary.html#keyword-only-parameter).301302#### `default(o)`303304В подклассе этот метод должен возвращать сериализуемый объект для *o* или вызывать базовую реализацию (для возбуждения [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError)).305306Например, для поддержки произвольных итераторов можно реализовать [`default()`](https://python-all.ru/3.12/library/json.html#json.JSONEncoder.default) следующим образом:307308```python309def default(self, o):310   try:311       iterable = iter(o)312   except TypeError:313       pass314   else:315       return list(iterable)316   # Пусть метод базового класса по умолчанию возбуждает TypeError317   return super().default(o)318```319320#### `encode(o)`321322Возвращает строковое представление структуры данных Python в формате JSON, *o*. Например:323324```python325>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})326'{"foo": ["bar", "baz"]}'327```328329#### `iterencode(o)`330331Кодирует заданный объект *o* и выдаёт каждое строковое представление по мере готовности. Например:332333```python334for chunk in json.JSONEncoder().iterencode(bigobject):335    mysocket.write(chunk)336```337338## Исключения339340#### `exception json.JSONDecodeError(msg, doc, pos)`341342Подкласс [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError) со следующими дополнительными атрибутами:343344#### `msg`345346Неформатированное сообщение об ошибке.347348#### `doc`349350Разбираемый JSON-документ.351352#### `pos`353354Начальный индекс *doc*, в котором произошла ошибка разбора.355356#### `lineno`357358Строка, соответствующая *pos*.359360#### `colno`361362Столбец, соответствующий *pos*.363364Добавлено в версии 3.5.365366## Соответствие стандартам и интероперабельность367368Формат JSON определяется [**RFC 7159**](https://python-all.ru/3.12/library/json.html) и [ECMA-404](https://python-all.ru/3.12/library/json.html). В этом разделе подробно описывается степень соответствия модуля RFC. Для простоты [`JSONEncoder`](https://python-all.ru/3.12/library/json.html#json.JSONEncoder) и [`JSONDecoder`](https://python-all.ru/3.12/library/json.html#json.JSONDecoder) подклассы, а также параметры, не указанные явно, не рассматриваются.369370Этот модуль не полностью соответствует RFC, реализуя некоторые расширения, которые являются допустимым JavaScript, но недопустимым JSON. В частности:371372- Бесконечные и NaN числовые значения принимаются и выводятся;373- Повторяющиеся имена в объекте принимаются, и используется только значение последней пары.374375Поскольку RFC разрешает совместимым с RFC анализаторам принимать входные тексты, которые не соответствуют RFC, десериализатор этого модуля технически соответствует RFC при настройках по умолчанию.376377### Кодировки символов378379RFC требует, чтобы JSON был представлен с использованием UTF-8, UTF-16 или UTF-32, причём UTF-8 рекомендуется по умолчанию для максимальной интероперабельности.380381Согласно RFC это допускается, но не требуется; сериализатор данного модуля по умолчанию использует *ensure\_ascii=True*, экранируя вывод так, чтобы результирующие строки содержали только ASCII-символы.382383Помимо параметра *ensure\_ascii*, этот модуль строго определён в терминах преобразования между объектами Python и [`Unicode strings`](https://python-all.ru/3.12/library/stdtypes.html#str), и таким образом напрямую не затрагивает вопрос кодировок символов.384385RFC запрещает добавление метки порядка байтов (BOM) в начало JSON-текста, и сериализатор этого модуля не добавляет BOM в свой вывод. RFC разрешает, но не требует, чтобы десериализаторы JSON игнорировали начальный BOM во входных данных. Десериализатор этого модуля возбуждает [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError), когда присутствует начальный BOM.386387RFC явно не запрещает строки JSON, содержащие последовательности байтов, которые не соответствуют допустимым символам Unicode (например, непарные суррогаты UTF-16), но отмечает, что они могут вызывать проблемы совместимости. По умолчанию этот модуль принимает и выводит (когда они присутствуют в исходном [`str`](https://python-all.ru/3.12/library/stdtypes.html#str)) кодовые точки таких последовательностей.388389### Бесконечные и NaN числовые значения390391RFC не допускает представления бесконечных или NaN числовых значений. Несмотря на это, по умолчанию этот модуль принимает и выводит `Infinity`, `-Infinity` и `NaN`, как если бы они были допустимыми числовыми литералами JSON:392393```python394>>> # Ни один из этих вызовов не возбуждает исключение, но результаты не являются корректным JSON395>>> json.dumps(float('-inf'))396'-Infinity'397>>> json.dumps(float('nan'))398'NaN'399>>> # То же самое при десериализации400>>> json.loads('-Infinity')401-inf402>>> json.loads('NaN')403nan404```405406В сериализаторе параметр *allow\_nan* можно использовать для изменения этого поведения. В десериализаторе параметр *parse\_constant* можно использовать для изменения этого поведения.407408### Повторяющиеся имена внутри объекта409410RFC указывает, что имена внутри JSON-объекта должны быть уникальными, но не предписывает, как обрабатывать повторяющиеся имена в JSON-объектах. По умолчанию этот модуль не вызывает исключение; вместо этого он игнорирует все, кроме последней пары имя-значение для данного имени:411412```python413>>> weird_json = '{"x": 1, "x": 2, "x": 3}'414>>> json.loads(weird_json)415{'x': 3}416```417418Параметр *object\_pairs\_hook* можно использовать для изменения этого поведения.419420### Значения верхнего уровня, не являющиеся объектами или массивами421422Старая версия JSON, определённая устаревшим [**RFC 4627**](https://python-all.ru/3.12/library/json.html), требовала, чтобы значение верхнего уровня JSON-текста было либо JSON-объектом, либо массивом (Python [`dict`](https://python-all.ru/3.12/library/stdtypes.html#dict) или [`list`](https://python-all.ru/3.12/library/stdtypes.html#list)), и не могло быть null, boolean, числом или строкой. [**RFC 7159**](https://python-all.ru/3.12/library/json.html) снял это ограничение, и этот модуль не реализует и никогда не реализовывал это ограничение ни в своём сериализаторе, ни в десериализаторе.423424Тем не менее, для максимальной совместимости можно добровольно придерживаться этого ограничения.425426### Ограничения реализации427428Некоторые реализации JSON-десериализаторов могут устанавливать ограничения на:429430- размер принимаемых JSON-текстов431- максимальный уровень вложенности JSON-объектов и массивов432- диапазон и точность JSON-чисел433- содержимое и максимальную длину JSON-строк434435Этот модуль не накладывает никаких подобных ограничений, кроме тех, что присущи соответствующим типам данных Python или самому интерпретатору Python.436437При сериализации в JSON учитывайте подобные ограничения в приложениях, которые могут потреблять ваш JSON. В частности, JSON-числа часто десериализуются в числа двойной точности IEEE 754 и, следовательно, подчиняются ограничениям диапазона и точности этого представления. Это особенно актуально при сериализации значений Python [`int`](https://python-all.ru/3.12/library/functions.html#int) чрезвычайно большой величины или при сериализации экземпляров «экзотических» числовых типов, таких как [`decimal.Decimal`](https://python-all.ru/3.12/library/decimal.html#decimal.Decimal).438439## Интерфейс командной строки440441**Исходный код:** [Lib/json/tool.py](https://python-all.ru/src/3.12/Lib/json/tool.py)442443---444445Модуль [`json.tool`](https://python-all.ru/3.12/library/json.html#module-json.tool) предоставляет простой интерфейс командной строки для проверки и форматированного вывода JSON-объектов.446447Если необязательные аргументы `infile` и `outfile` не указаны, будут использоваться [`sys.stdin`](https://python-all.ru/3.12/library/sys.html#sys.stdin) и [`sys.stdout`](https://python-all.ru/3.12/library/sys.html#sys.stdout) соответственно:448449```console450$ echo '{"json": "obj"}' | python -m json.tool451{452    "json": "obj"453}454$ echo '{1.2:3.4}' | python -m json.tool455Expecting property name enclosed in double quotes: line 1 column 2 (char 1)456```457458Изменено в версии 3.5: Вывод теперь располагается в том же порядке, что и входные данные. Используйте параметр [`--sort-keys`](https://python-all.ru/3.12/library/json.html#cmdoption-json.tool-sort-keys) для сортировки вывода словарей по ключу в алфавитном порядке.459460### Параметры командной строки461462#### `infile`463464JSON-файл для проверки или красивого вывода:465466```console467$ python -m json.tool mp_films.json468[469    {470        "title": "And Now for Something Completely Different",471        "year": 1971472    },473    {474        "title": "Monty Python and the Holy Grail",475        "year": 1975476    }477]478```479480Если *infile* не указан, читать из [`sys.stdin`](https://python-all.ru/3.12/library/sys.html#sys.stdin).481482#### `outfile`483484Записать вывод *infile* в указанный *outfile*. В противном случае записать его в [`sys.stdout`](https://python-all.ru/3.12/library/sys.html#sys.stdout).485486#### `--sort-keys`487488Сортировать вывод словарей по ключу в алфавитном порядке.489490Добавлено в версии 3.5.491492#### `--no-ensure-ascii`493494Отключает экранирование не-ASCII символов; подробнее см. [`json.dumps()`](https://python-all.ru/3.12/library/json.html#json.dumps).495496Добавлено в версии 3.9.497498#### `--json-lines`499500Анализировать каждую входную строку как отдельный JSON-объект.501502Добавлено в версии 3.8.503504#### `--indent, --tab, --no-indent, --compact`505506Взаимоисключающие опции для управления пробелами.507508Добавлено в версии 3.9.509510#### `-h, --help`511512Показывает справочное сообщение.513514Сноски515516\[[1](https://python-all.ru/3.12/library/json.html#id1)\]517518Как отмечено в [списке ошибок RFC 7159](https://python-all.ru/3.12/library/json.html), JSON допускает символы U+2028 (LINE SEPARATOR) и U+2029 (PARAGRAPH SEPARATOR) в строках, тогда как JavaScript (начиная с ECMAScript Edition 5.1) – нет.519