`json.md`

536 строк · 47.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/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.13/Lib/json/__init__.py)1011---1213[JSON (JavaScript Object Notation)](https://python-all.ru/3.13/library/json.html), описанный в [**RFC 7159**](https://python-all.ru/3.13/library/json.html) (который заменяет [**RFC 4627**](https://python-all.ru/3.13/library/json.html)) и в [ECMA-404](https://python-all.ru/3.13/library/json.html), является легковесным форматом обмена данными, вдохновлённым синтаксисом литералов объектов [JavaScript](https://python-all.ru/3.13/library/json.html) (хотя он не является строгим подмножеством JavaScript [\[1\]](https://python-all.ru/3.13/library/json.html#rfc-errata)).1415> **Примечание**16>17> Термин «объект» в контексте обработки JSON в Python может быть неоднозначным. Все значения в Python – это объекты. В JSON объектом называют любые данные, заключённые в фигурные скобки, как в словаре Python.1819> **Предупреждение**20>21> Соблюдайте осторожность при разборе JSON-данных из ненадёжных источников. Злонамеренная JSON-строка может заставить декодер потреблять значительные ресурсы CPU и памяти. Рекомендуется ограничивать размер разбираемых данных.2223Этот модуль предоставляет API, знакомый пользователям модулей стандартной библиотеки [`marshal`](https://python-all.ru/3.13/library/marshal.html#module-marshal) и [`pickle`](https://python-all.ru/3.13/library/pickle.html#module-pickle).2425Кодирование иерархий базовых объектов Python:2627```python28>>> import json29>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])30'["foo", {"bar": ["baz", null, 1.0, 2]}]'31>>> print(json.dumps("\"foo\bar"))32"\"foo\bar"33>>> print(json.dumps('\u1234'))34"\u1234"35>>> print(json.dumps('\\'))36"\\"37>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))38{"a": 0, "b": 0, "c": 0}39>>> from io import StringIO40>>> io = StringIO()41>>> json.dump(['streaming API'], io)42>>> io.getvalue()43'["streaming API"]'44```4546Компактное кодирование:4748```python49>>> import json50>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))51'[1,2,3,{"4":5,"6":7}]'52```5354Красивое форматирование:5556```python57>>> import json58>>> print(json.dumps({'6': 7, '4': 5}, sort_keys=True, indent=4))59{60    "4": 5,61    "6": 762}63```6465Настройка кодирования JSON-объектов:6667```python68>>> import json69>>> def custom_json(obj):70...     if isinstance(obj, complex):71...         return {'__complex__': True, 'real': obj.real, 'imag': obj.imag}72...     raise TypeError(f'Cannot serialize object of {type(obj)}')73...74>>> json.dumps(1 + 2j, default=custom_json)75'{"__complex__": true, "real": 1.0, "imag": 2.0}'76```7778Декодирование JSON:7980```python81>>> import json82>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')83['foo', {'bar': ['baz', None, 1.0, 2]}]84>>> json.loads('"\\"foo\\bar"')85'"foo\x08ar'86>>> from io import StringIO87>>> io = StringIO('["streaming API"]')88>>> json.load(io)89['streaming API']90```9192Настройка декодирования JSON-объектов:9394```python95>>> import json96>>> def as_complex(dct):97...     if '__complex__' in dct:98...         return complex(dct['real'], dct['imag'])99...     return dct100...101>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',102...     object_hook=as_complex)103(1+2j)104>>> import decimal105>>> json.loads('1.1', parse_float=decimal.Decimal)106Decimal('1.1')107```108109Расширение [`JSONEncoder`](https://python-all.ru/3.13/library/json.html#json.JSONEncoder):110111```python112>>> import json113>>> class ComplexEncoder(json.JSONEncoder):114...     def default(self, obj):115...         if isinstance(obj, complex):116...             return [obj.real, obj.imag]117...         # Пусть метод базового класса по умолчанию возбуждает TypeError118...         return super().default(obj)119...120>>> json.dumps(2 + 1j, cls=ComplexEncoder)121'[2.0, 1.0]'122>>> ComplexEncoder().encode(2 + 1j)123'[2.0, 1.0]'124>>> list(ComplexEncoder().iterencode(2 + 1j))125['[2.0', ', 1.0', ']']126```127128Использование [`json.tool`](https://python-all.ru/3.13/library/json.html#module-json.tool) из командной оболочки для проверки и красивого вывода:129130```console131$ echo '{"json":"obj"}' | python -m json.tool132{133    "json": "obj"134}135$ echo '{1.2:3.4}' | python -m json.tool136Expecting property name enclosed in double quotes: line 1 column 2 (char 1)137```138139Смотрите [интерфейс командной строки](https://python-all.ru/3.13/library/json.html#json-commandline) для подробной документации.140141> **Примечание**142>143> JSON является подмножеством [YAML](https://python-all.ru/3.13/library/json.html) 1.2. JSON, создаваемый настройками модуля по умолчанию (в частности, значением *separators* по умолчанию), также является подмножеством YAML 1.0 и 1.1. Таким образом, этот модуль можно использовать как сериализатор YAML.144145> **Примечание**146>147> Кодировщики и декодировщики этого модуля по умолчанию сохраняют порядок ввода и вывода. Порядок теряется только в том случае, если основные контейнеры неупорядочены.148149## Основное использование150151#### `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)`152153Сериализует *obj* в поток в формате JSON в *fp* (`.write()`-поддерживающий [файлоподобный объект](https://python-all.ru/3.13/glossary.html#term-file-like-object)), используя [таблицу преобразования Python в JSON](https://python-all.ru/3.13/library/json.html#py-to-json-table).154155> **Примечание**156>157> В отличие от [`pickle`](https://python-all.ru/3.13/library/pickle.html#module-pickle) и [`marshal`](https://python-all.ru/3.13/library/marshal.html#module-marshal), JSON не является фреймовым протоколом, поэтому попытка сериализовать несколько объектов с повторными вызовами `dump()` с использованием одного и того же *fp* приведёт к созданию недопустимого JSON-файла.158159**Параметры:**160161- **obj** ([*object*](https://python-all.ru/3.13/library/functions.html#object)) – Сериализуемый объект Python.162- **fp** ([файлоподобный объект](https://python-all.ru/3.13/glossary.html#term-file-like-object)) – Файлоподобный объект, в который будет сериализован *obj*. Модуль `json` всегда создаёт объекты [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), а не [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes), поэтому `fp.write()` должен поддерживать ввод `str`.163- **skipkeys** ([*bool*](https://python-all.ru/3.13/library/functions.html#bool)) – Если `True`, ключи, не являющиеся базовым типом ([`str`](https://python-all.ru/3.13/library/stdtypes.html#str), [`int`](https://python-all.ru/3.13/library/functions.html#int), [`float`](https://python-all.ru/3.13/library/functions.html#float), `bool`, `None`), будут пропущены вместо возбуждения [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError). По умолчанию `False`.164- **ensure\_ascii** ([*bool*](https://python-all.ru/3.13/library/functions.html#bool)) – Если `True` (по умолчанию), выходные данные гарантированно содержат экранированными все не-ASCII и непечатаемые символы. Если `False`, все символы выводятся как есть, за исключением символов, которые необходимо экранировать: кавычка, обратная косая черта и управляющие символы U+0000–U+001F.165- **check\_circular** ([*bool*](https://python-all.ru/3.13/library/functions.html#bool)) – Если `False`, проверка циклических ссылок для контейнерных типов пропускается, и циклическая ссылка приведёт к [`RecursionError`](https://python-all.ru/3.13/library/exceptions.html#RecursionError) (или хуже). По умолчанию `True`.166- **allow\_nan** ([*bool*](https://python-all.ru/3.13/library/functions.html#bool)) – Если `False`, сериализация значений [`float`](https://python-all.ru/3.13/library/functions.html#float) вне допустимого диапазона (`nan`, `inf`, `-inf`) вызовет [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError) в строгом соответствии со спецификацией JSON. Если `True` (по умолчанию), используются их эквиваленты в JavaScript (`NaN`, `Infinity`, `-Infinity`).167- **cls** (подкласс [`JSONEncoder`](https://python-all.ru/3.13/library/json.html#json.JSONEncoder)) – Если задан, пользовательский кодировщик JSON с переопределённым методом [`default()`](https://python-all.ru/3.13/library/json.html#json.JSONEncoder.default), для сериализации в пользовательские типы данных. Если `None` (по умолчанию), используется `JSONEncoder`.168- **indent** ([*int*](https://python-all.ru/3.13/library/functions.html#int) *|* [*str*](https://python-all.ru/3.13/library/stdtypes.html#str) *|* *None*) – Если положительное целое число или строка, элементы массива JSON и члены объекта будут выводиться с отступом этого уровня. Положительное целое число добавляет указанное количество пробелов на уровень; строка (например, `"\t"`) используется для отступа каждого уровня. Если ноль, отрицательное значение или `""` (пустая строка), вставляются только символы новой строки. Если `None` (по умолчанию), символы новой строки не вставляются.169- **separators** ([*tuple*](https://python-all.ru/3.13/library/stdtypes.html#tuple) *|* *None*) – Кортеж из двух элементов: `(item_separator, key_separator)`. Если `None` (по умолчанию), *separators* по умолчанию равен `(', ', ': ')`, если *indent* равен `None`, и `(',', ': ')` в противном случае. Для максимально компактного JSON укажите `(',', ':')`, чтобы убрать пробелы.170- **default** ([callable](https://python-all.ru/3.13/glossary.html#term-callable) | None) – Функция, вызываемая для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта, кодируемую в JSON, или возбуждать [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError). Если `None` (по умолчанию), возбуждается `TypeError`.171- **sort\_keys** ([*bool*](https://python-all.ru/3.13/library/functions.html#bool)) – если `True`, словари будут выводиться отсортированными по ключам. По умолчанию `False`.172173Изменено в версии 3.2: Разрешено использование строк для *indent* в дополнение к целым числам.174175Изменено в версии 3.4: Используйте `(',', ': ')` по умолчанию, если *indent* не равно `None`.176177Изменено в версии 3.6: Все необязательные параметры теперь являются [только ключевыми](https://python-all.ru/3.13/glossary.html#keyword-only-parameter).178179#### `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)`180181Сериализует *obj* в JSON-форматированную [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), используя эту [таблицу преобразования](https://python-all.ru/3.13/library/json.html#py-to-json-table). Аргументы имеют тот же смысл, что и в [`dump()`](https://python-all.ru/3.13/library/json.html#json.dump).182183> **Примечание**184>185> Ключи в парах ключ-значение JSON всегда имеют тип [`str`](https://python-all.ru/3.13/library/stdtypes.html#str). При преобразовании словаря в JSON все его ключи приводятся к строкам. В результате, если словарь преобразовать в JSON, а затем обратно в словарь, полученный словарь может не совпадать с исходным. То есть `loads(dumps(x)) != x`, если x имеет нестроковые ключи.186187#### `json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)`188189Десериализует *fp* в объект Python, используя [таблицу преобразования JSON в Python](https://python-all.ru/3.13/library/json.html#json-to-py-table).190191**Параметры:**192193- **fp** ([файлоподобный объект](https://python-all.ru/3.13/glossary.html#term-file-like-object)) – поддерживающий `.read()` [текстовый файл](https://python-all.ru/3.13/glossary.html#term-text-file) или [двоичный файл](https://python-all.ru/3.13/glossary.html#term-binary-file), содержащий JSON-документ для десериализации.194- **cls** (подкласс [`JSONDecoder`](https://python-all.ru/3.13/library/json.html#json.JSONDecoder)) – если задан, пользовательский JSON-декодер. Дополнительные именованные аргументы для `load()` будут переданы конструктору *cls*. Если `None` (по умолчанию), используется `JSONDecoder`.195- **object\_hook** ([вызываемый объект](https://python-all.ru/3.13/glossary.html#term-callable) | None) – если задан, функция, которая вызывается с результатом декодирования любого литерала JSON-объекта ([`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict)). Возвращаемое значение этой функции будет использовано вместо `dict`. Эта возможность используется для реализации пользовательских декодеров, например, для подсказок класса [JSON-RPC](https://python-all.ru/3.13/library/json.html). По умолчанию `None`.196- **object\_pairs\_hook** ([вызываемый объект](https://python-all.ru/3.13/glossary.html#term-callable) | None) – если задан, функция, которая вызывается с результатом декодирования любого литерала JSON-объекта с упорядоченным списком пар. Возвращаемое значение этой функции будет использовано вместо [`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict). Эта возможность используется для реализации пользовательских декодеров. Если также задан *object\_hook*, приоритет имеет *object\_pairs\_hook*. По умолчанию `None`.197- **parse\_float** ([вызываемый объект](https://python-all.ru/3.13/glossary.html#term-callable) | None) – если задан, функция, вызываемая со строкой каждого JSON-числа с плавающей точкой для декодирования. Если `None` (по умолчанию), это эквивалентно `float(num_str)`. Это может использоваться для парсинга JSON-чисел с плавающей точкой в пользовательские типы данных, например, [`decimal.Decimal`](https://python-all.ru/3.13/library/decimal.html#decimal.Decimal).198- **parse\_int** ([вызываемый объект](https://python-all.ru/3.13/glossary.html#term-callable) | None) – если задан, функция, вызываемая со строкой каждого JSON-целого для декодирования. Если `None` (по умолчанию), это эквивалентно `int(num_str)`. Это может использоваться для парсинга JSON-целых чисел в пользовательские типы данных, например, [`float`](https://python-all.ru/3.13/library/functions.html#float).199- **parse\_constant** ([вызываемый объект](https://python-all.ru/3.13/glossary.html#term-callable) | None) – если задан, функция, вызываемая с одной из следующих строк: `'-Infinity'`, `'Infinity'` или `'NaN'`. Это может использоваться для возбуждения исключения при обнаружении некорректных JSON-чисел. По умолчанию `None`.200201**Возбуждает:**202203- [**JSONDecodeError**](https://python-all.ru/3.13/library/json.html#json.JSONDecodeError) – когда десериализуемые данные не являются корректным JSON-документом.204- [**UnicodeDecodeError**](https://python-all.ru/3.13/library/exceptions.html#UnicodeDecodeError) – когда десериализуемые данные не содержат данные в кодировке UTF-8, UTF-16 или UTF-32.205206Изменено в версии 3.1:207208- Добавлен необязательный параметр *object\_pairs\_hook*.209- *parse\_constant* больше не вызывается для 'null', 'true', 'false'.210211Изменено в версии 3.6:212213- Все необязательные параметры теперь являются [только ключевыми](https://python-all.ru/3.13/glossary.html#keyword-only-parameter).214- *fp* теперь может быть [двоичным файлом](https://python-all.ru/3.13/glossary.html#term-binary-file). Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.215216Изменено в версии 3.11: Значение *parse\_int* по умолчанию в [`int()`](https://python-all.ru/3.13/library/functions.html#int) теперь ограничивает максимальную длину строки целого числа через [ограничение длины преобразования строки целого числа](https://python-all.ru/3.13/library/stdtypes.html#int-max-str-digits) интерпретатора, чтобы помочь избежать атак типа «отказ в обслуживании».217218#### `json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)`219220Идентично [`load()`](https://python-all.ru/3.13/library/json.html#json.load), но вместо файлоподобного объекта десериализует *s* (экземпляр [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray), содержащий JSON-документ) в объект Python, используя эту [таблицу преобразования](https://python-all.ru/3.13/library/json.html#json-to-py-table).221222Изменено в версии 3.6: *s* теперь может быть типа [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray). Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.223224Изменено в версии 3.9: Именованный аргумент *encoding* удален.225226## Кодировщики и декодеры227228#### `class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)`229230Простой JSON-декодер.231232По умолчанию выполняет следующие преобразования при декодировании:233234| JSON | Python |235| --- | --- |236| объект | dict |237| массив | list |238| строка | str |239| число (int) | int |240| число (вещественное) | float |241| true | True |242| false | False |243| null | None |244245Также `NaN`, `Infinity` и `-Infinity` распознаются как соответствующие значения `float`, что выходит за рамки спецификации JSON.246247*object\_hook* – необязательная функция, которая вызывается с результатом декодирования каждого JSON-объекта; её возвращаемое значение используется вместо переданного [`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict). Это позволяет задавать собственную десериализацию (например, для поддержки подсказок классов [JSON-RPC](https://python-all.ru/3.13/library/json.html)).248249*object\_pairs\_hook* – необязательная функция, которая вызывается с результатом декодирования каждого JSON-объекта в виде упорядоченного списка пар. Возвращаемое значение *object\_pairs\_hook* будет использоваться вместо [`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict). Этот механизм позволяет реализовывать собственные декодеры. Если также определён *object\_hook*, приоритет имеет *object\_pairs\_hook*.250251Изменено в версии 3.1: Добавлена поддержка *object\_pairs\_hook*.252253*parse\_float* – необязательная функция, которая вызывается со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию она эквивалентна `float(num_str)`. Это позволяет использовать другой тип данных или синтаксический анализатор для чисел с плавающей точкой (например, [`decimal.Decimal`](https://python-all.ru/3.13/library/decimal.html#decimal.Decimal)).254255*parse\_int* – необязательная функция, которая вызывается со строкой каждого декодируемого JSON-целого числа. По умолчанию она эквивалентна `int(num_str)`. Это позволяет использовать другой тип данных или синтаксический анализатор для целых чисел JSON (например, [`float`](https://python-all.ru/3.13/library/functions.html#float)).256257*parse\_constant* – необязательная функция, которая вызывается с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`. Это позволяет вызывать исключение при обнаружении недопустимых чисел JSON.258259Если *strict* равно false (по умолчанию `True`), то управляющие символы допускаются внутри строк. Под управляющими символами здесь понимаются символы с кодами в диапазоне 0–31, включая `'\t'` (табуляция), `'\n'`, `'\r'` и `'\0'`.260261Если десериализуемые данные не являются корректным JSON-документом, будет вызвано [`JSONDecodeError`](https://python-all.ru/3.13/library/json.html#json.JSONDecodeError).262263Изменено в версии 3.6: Все параметры теперь [только ключевые](https://python-all.ru/3.13/glossary.html#keyword-only-parameter).264265#### `decode(s)`266267Возвращает представление *s* в Python (экземпляр [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), содержащий JSON-документ).268269[`JSONDecodeError`](https://python-all.ru/3.13/library/json.html#json.JSONDecodeError) будет вызвано, если переданный JSON-документ не является корректным.270271#### `raw_decode(s)`272273Декодирует JSON-документ из *s* ([`str`](https://python-all.ru/3.13/library/stdtypes.html#str), начинающийся с JSON-документа) и возвращает кортеж из двух элементов: представления в Python и индекса в *s*, на котором документ заканчивается.274275Это можно использовать для декодирования JSON-документа из строки, в конце которой могут быть лишние данные.276277#### `class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)`278279Расширяемый JSON-кодировщик для структур данных Python.280281По умолчанию поддерживает следующие объекты и типы:282283| Python | JSON |284| --- | --- |285| dict | объект |286| list, tuple | массив |287| str | строка |288| int, float, перечисления, производные от int и float | число |289| True | true |290| False | false |291| None | null |292293Изменено в версии 3.4: Добавлена поддержка классов Enum, производных от int и float.294295Чтобы расширить функциональность на другие объекты, создайте подкласс и реализуйте метод [`default()`](https://python-all.ru/3.13/library/json.html#json.JSONEncoder.default) с другим методом, который возвращает сериализуемый объект для `o`, если это возможно; в противном случае следует вызвать реализацию суперкласса (для возбуждения [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError)).296297Если *skipkeys* имеет значение false (по умолчанию), возбуждается [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError) при попытке кодировать ключи, не являющиеся [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), [`int`](https://python-all.ru/3.13/library/functions.html#int), [`float`](https://python-all.ru/3.13/library/functions.html#float), [`bool`](https://python-all.ru/3.13/library/functions.html#bool) или `None`. Если *skipkeys* равно true, такие элементы просто пропускаются.298299Если *ensure\_ascii* равно true (по умолчанию), выходные данные гарантированно содержат экранированные не-ASCII и непечатаемые символы. Если *ensure\_ascii* равно false, все символы выводятся как есть, за исключением символов, которые необходимо экранировать: кавычки, обратная косая черта и управляющие символы U+0000–U+001F.300301Если *check\_circular* равно true (по умолчанию), то списки, словари и пользовательские объекты проверяются на циклические ссылки во время кодирования для предотвращения бесконечной рекурсии (которая вызвала бы [`RecursionError`](https://python-all.ru/3.13/library/exceptions.html#RecursionError)). В противном случае такая проверка не выполняется.302303Если *allow\_nan* равно true (по умолчанию), то значения `NaN`, `Infinity` и `-Infinity` кодируются как есть. Такое поведение не соответствует спецификации JSON, но согласуется с большинством кодировщиков и декодировщиков на JavaScript. В противном случае при кодировании таких чисел с плавающей запятой возбуждается [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).304305Если *sort\_keys* равно true (по умолчанию `False`), то вывод словарей сортируется по ключам; это полезно для регрессионных тестов, чтобы обеспечить возможность сравнения JSON-сериализаций день ото дня.306307Если *indent* – неотрицательное целое число или строка, то элементы JSON-массивов и члены объектов выводятся с отступами, соответствующими указанному уровню. Уровень отступа 0, отрицательное значение или `""` вставляет только переводы строк. `None` (по умолчанию) выбирает наиболее компактное представление. Положительное целое значение отступа задаёт количество пробелов на уровень. Если *indent* является строкой (например, `"\t"`), эта строка используется для отступа каждого уровня.308309Изменено в версии 3.2: Разрешено использование строк для *indent* в дополнение к целым числам.310311Если указан, то *separators* должен быть кортежем `(item_separator, key_separator)`. По умолчанию используется `(', ', ': ')`, если *indent* равно `None`, и `(',', ': ')` в противном случае. Для получения наиболее компактного JSON-представления укажите `(',', ':')`, чтобы убрать пробелы.312313Изменено в версии 3.4: Используйте `(',', ': ')` по умолчанию, если *indent* не равно `None`.314315Если указан, *default* должен быть функцией, которая вызывается для объектов, которые не могут быть сериализованы иным способом. Она должна возвращать версию объекта, пригодную для JSON-кодирования, или возбуждать [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError). Если не указано, возбуждается `TypeError`.316317Изменено в версии 3.6: Все параметры теперь [только ключевые](https://python-all.ru/3.13/glossary.html#keyword-only-parameter).318319#### `default(o)`320321В подклассе этот метод должен возвращать сериализуемый объект для *o* или вызывать базовую реализацию (для возбуждения [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError)).322323Например, для поддержки произвольных итераторов можно реализовать `default()` следующим образом:324325```python326def default(self, o):327   try:328       iterable = iter(o)329   except TypeError:330       pass331   else:332       return list(iterable)333   # Пусть метод базового класса по умолчанию возбуждает TypeError334   return super().default(o)335```336337#### `encode(o)`338339Возвращает строковое представление структуры данных Python в формате JSON, *o*. Например:340341```python342>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})343'{"foo": ["bar", "baz"]}'344```345346#### `iterencode(o)`347348Кодирует заданный объект *o* и выдаёт каждое строковое представление по мере готовности. Например:349350```python351for chunk in json.JSONEncoder().iterencode(bigobject):352    mysocket.write(chunk)353```354355## Исключения356357#### `exception json.JSONDecodeError(msg, doc, pos)`358359Подкласс [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError) со следующими дополнительными атрибутами:360361#### `msg`362363Неформатированное сообщение об ошибке.364365#### `doc`366367Разбираемый JSON-документ.368369#### `pos`370371Начальный индекс *doc*, в котором произошла ошибка разбора.372373#### `lineno`374375Строка, соответствующая *pos*.376377#### `colno`378379Столбец, соответствующий *pos*.380381Добавлено в версии 3.5.382383## Соответствие стандартам и интероперабельность384385Формат JSON определяется [**RFC 7159**](https://python-all.ru/3.13/library/json.html) и [ECMA-404](https://python-all.ru/3.13/library/json.html). В этом разделе подробно описывается степень соответствия модуля RFC. Для простоты [`JSONEncoder`](https://python-all.ru/3.13/library/json.html#json.JSONEncoder) и [`JSONDecoder`](https://python-all.ru/3.13/library/json.html#json.JSONDecoder) подклассы, а также параметры, не указанные явно, не рассматриваются.386387Этот модуль не полностью соответствует RFC, реализуя некоторые расширения, которые являются допустимым JavaScript, но недопустимым JSON. В частности:388389- Бесконечные и NaN числовые значения принимаются и выводятся;390- Повторяющиеся имена в объекте принимаются, и используется только значение последней пары.391392Поскольку RFC разрешает совместимым с RFC анализаторам принимать входные тексты, которые не соответствуют RFC, десериализатор этого модуля технически соответствует RFC при настройках по умолчанию.393394### Кодировки символов395396RFC требует, чтобы JSON был представлен с использованием UTF-8, UTF-16 или UTF-32, причём UTF-8 рекомендуется по умолчанию для максимальной интероперабельности.397398Как разрешено (хотя и не требуется) RFC, сериализатор этого модуля по умолчанию устанавливает *ensure\_ascii=True*, таким образом экранируя вывод, так что результирующие строки содержат только печатные символы ASCII.399400Помимо параметра *ensure\_ascii*, этот модуль строго определён в терминах преобразования между объектами Python и [`Unicode strings`](https://python-all.ru/3.13/library/stdtypes.html#str), и таким образом напрямую не затрагивает вопрос кодировок символов.401402RFC запрещает добавление метки порядка байтов (BOM) в начало JSON-текста, и сериализатор этого модуля не добавляет BOM в свой вывод. RFC разрешает, но не требует, чтобы десериализаторы JSON игнорировали начальный BOM во входных данных. Десериализатор этого модуля возбуждает [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError), когда присутствует начальный BOM.403404RFC явно не запрещает строки JSON, содержащие последовательности байтов, которые не соответствуют допустимым символам Unicode (например, непарные суррогаты UTF-16), но отмечает, что они могут вызывать проблемы совместимости. По умолчанию этот модуль принимает и выводит (когда они присутствуют в исходном [`str`](https://python-all.ru/3.13/library/stdtypes.html#str)) кодовые точки таких последовательностей.405406### Бесконечные и NaN числовые значения407408RFC не допускает представления бесконечных или NaN числовых значений. Несмотря на это, по умолчанию этот модуль принимает и выводит `Infinity`, `-Infinity` и `NaN`, как если бы они были допустимыми числовыми литералами JSON:409410```python411>>> # Ни один из этих вызовов не возбуждает исключение, но результаты не являются корректным JSON412>>> json.dumps(float('-inf'))413'-Infinity'414>>> json.dumps(float('nan'))415'NaN'416>>> # То же самое при десериализации417>>> json.loads('-Infinity')418-inf419>>> json.loads('NaN')420nan421```422423В сериализаторе параметр *allow\_nan* можно использовать для изменения этого поведения. В десериализаторе параметр *parse\_constant* можно использовать для изменения этого поведения.424425### Повторяющиеся имена внутри объекта426427RFC указывает, что имена внутри JSON-объекта должны быть уникальными, но не предписывает, как обрабатывать повторяющиеся имена в JSON-объектах. По умолчанию этот модуль не вызывает исключение; вместо этого он игнорирует все, кроме последней пары имя-значение для данного имени:428429```python430>>> weird_json = '{"x": 1, "x": 2, "x": 3}'431>>> json.loads(weird_json)432{'x': 3}433```434435Параметр *object\_pairs\_hook* можно использовать для изменения этого поведения.436437### Значения верхнего уровня, не являющиеся объектами или массивами438439Старая версия JSON, определённая устаревшим [**RFC 4627**](https://python-all.ru/3.13/library/json.html), требовала, чтобы значение верхнего уровня JSON-текста было либо JSON-объектом, либо массивом (Python [`dict`](https://python-all.ru/3.13/library/stdtypes.html#dict) или [`list`](https://python-all.ru/3.13/library/stdtypes.html#list)), и не могло быть null, boolean, числом или строкой. [**RFC 7159**](https://python-all.ru/3.13/library/json.html) снял это ограничение, и этот модуль не реализует и никогда не реализовывал это ограничение ни в своём сериализаторе, ни в десериализаторе.440441Тем не менее, для максимальной совместимости можно добровольно придерживаться этого ограничения.442443### Ограничения реализации444445Некоторые реализации JSON-десериализаторов могут устанавливать ограничения на:446447- размер принимаемых JSON-текстов448- максимальный уровень вложенности JSON-объектов и массивов449- диапазон и точность JSON-чисел450- содержимое и максимальную длину JSON-строк451452Этот модуль не накладывает никаких подобных ограничений, кроме тех, что присущи соответствующим типам данных Python или самому интерпретатору Python.453454При сериализации в JSON учитывайте подобные ограничения в приложениях, которые могут потреблять ваш JSON. В частности, JSON-числа часто десериализуются в числа двойной точности IEEE 754 и, следовательно, подчиняются ограничениям диапазона и точности этого представления. Это особенно актуально при сериализации значений Python [`int`](https://python-all.ru/3.13/library/functions.html#int) чрезвычайно большой величины или при сериализации экземпляров «экзотических» числовых типов, таких как [`decimal.Decimal`](https://python-all.ru/3.13/library/decimal.html#decimal.Decimal).455456## Интерфейс командной строки457458**Исходный код:** [Lib/json/tool.py](https://python-all.ru/src/3.13/Lib/json/tool.py)459460---461462Модуль `json.tool` предоставляет простой интерфейс командной строки для проверки и форматированного вывода JSON-объектов.463464Если необязательные аргументы `infile` и `outfile` не указаны, будут использоваться [`sys.stdin`](https://python-all.ru/3.13/library/sys.html#sys.stdin) и [`sys.stdout`](https://python-all.ru/3.13/library/sys.html#sys.stdout) соответственно:465466```console467$ echo '{"json": "obj"}' | python -m json.tool468{469    "json": "obj"470}471$ echo '{1.2:3.4}' | python -m json.tool472Expecting property name enclosed in double quotes: line 1 column 2 (char 1)473```474475Изменено в версии 3.5: Вывод теперь располагается в том же порядке, что и входные данные. Используйте параметр [`--sort-keys`](https://python-all.ru/3.13/library/json.html#cmdoption-json.tool-sort-keys) для сортировки вывода словарей по ключу в алфавитном порядке.476477### Параметры командной строки478479#### `infile`480481JSON-файл для проверки или красивого вывода:482483```console484$ python -m json.tool mp_films.json485[486    {487        "title": "And Now for Something Completely Different",488        "year": 1971489    },490    {491        "title": "Monty Python and the Holy Grail",492        "year": 1975493    }494]495```496497Если *infile* не указан, читать из [`sys.stdin`](https://python-all.ru/3.13/library/sys.html#sys.stdin).498499#### `outfile`500501Записать вывод *infile* в указанный *outfile*. В противном случае записать его в [`sys.stdout`](https://python-all.ru/3.13/library/sys.html#sys.stdout).502503#### `--sort-keys`504505Сортировать вывод словарей по ключу в алфавитном порядке.506507Добавлено в версии 3.5.508509#### `--no-ensure-ascii`510511Отключает экранирование не-ASCII символов; подробнее см. [`json.dumps()`](https://python-all.ru/3.13/library/json.html#json.dumps).512513Добавлено в версии 3.9.514515#### `--json-lines`516517Анализировать каждую входную строку как отдельный JSON-объект.518519Добавлено в версии 3.8.520521#### `--indent, --tab, --no-indent, --compact`522523Взаимоисключающие опции для управления пробелами.524525Добавлено в версии 3.9.526527#### `-h, --help`528529Показывает справочное сообщение.530531Сноски532533\[[1](https://python-all.ru/3.13/library/json.html#id1)\]534535Как отмечено в [списке ошибок RFC 7159](https://python-all.ru/3.13/library/json.html), JSON допускает символы U+2028 (LINE SEPARATOR) и U+2029 (PARAGRAPH SEPARATOR) в строках, тогда как JavaScript (начиная с ECMAScript Edition 5.1) – нет.536