`json.md`

545 строк · 48.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/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/main/Lib/json/__init__.py)1011---1213[JSON (JavaScript Object Notation)](https://python-all.ru/3.16/library/json.html), описанный в [**RFC 7159**](https://python-all.ru/3.16/library/json.html) (который заменяет [**RFC 4627**](https://python-all.ru/3.16/library/json.html)) и в [ECMA-404](https://python-all.ru/3.16/library/json.html), является легковесным форматом обмена данными, вдохновлённым синтаксисом литералов объектов [JavaScript](https://python-all.ru/3.16/library/json.html) (хотя он не является строгим подмножеством JavaScript [\[1\]](https://python-all.ru/3.16/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.16/library/marshal.html#module-marshal) и [`pickle`](https://python-all.ru/3.16/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.16/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` из командной оболочки для проверки и красивого вывода:129130```console131$ echo '{"json":"obj"}' | python -m json132{133    "json": "obj"134}135$ echo '{1.2:3.4}' | python -m json136Expecting property name enclosed in double quotes: line 1 column 2 (char 1)137```138139Подробнее см. в [интерфейсе командной строки](https://python-all.ru/3.16/library/json.html#json-commandline).140141> **Примечание**142>143> JSON является подмножеством [YAML](https://python-all.ru/3.16/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.16/glossary.html#term-file-like-object)), используя [таблицу преобразования Python в JSON](https://python-all.ru/3.16/library/json.html#py-to-json-table).154155> **Примечание**156>157> В отличие от [`pickle`](https://python-all.ru/3.16/library/pickle.html#module-pickle) и [`marshal`](https://python-all.ru/3.16/library/marshal.html#module-marshal), JSON не является фреймовым протоколом, поэтому попытка сериализовать несколько объектов с повторными вызовами `dump()` с использованием одного и того же *fp* приведёт к созданию недопустимого JSON-файла.158159**Параметры:**160161- **obj** ([*object*](https://python-all.ru/3.16/library/functions.html#object)) – Сериализуемый объект Python.162- **fp** ([файлоподобный объект](https://python-all.ru/3.16/glossary.html#term-file-like-object)) – Файлоподобный объект, в который будет сериализован *obj*. Модуль `json` всегда создаёт объекты [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), а не [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes), поэтому `fp.write()` должен поддерживать ввод `str`.163- **skipkeys** ([*bool*](https://python-all.ru/3.16/library/functions.html#bool)) – Если `True`, ключи, не являющиеся базовым типом ([`str`](https://python-all.ru/3.16/library/stdtypes.html#str), [`int`](https://python-all.ru/3.16/library/functions.html#int), [`float`](https://python-all.ru/3.16/library/functions.html#float), `bool`, `None`), будут пропущены вместо возбуждения [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). По умолчанию `False`.164- **ensure\_ascii** ([*bool*](https://python-all.ru/3.16/library/functions.html#bool)) – Если `True` (по умолчанию), выходные данные гарантированно содержат экранированными все не-ASCII и непечатаемые символы. Если `False`, все символы выводятся как есть, за исключением символов, которые необходимо экранировать: кавычка, обратная косая черта и управляющие символы U+0000–U+001F.165- **check\_circular** ([*bool*](https://python-all.ru/3.16/library/functions.html#bool)) – Если `False`, проверка циклических ссылок для контейнерных типов пропускается, и циклическая ссылка приведёт к [`RecursionError`](https://python-all.ru/3.16/library/exceptions.html#RecursionError) (или хуже). По умолчанию `True`.166- **allow\_nan** ([*bool*](https://python-all.ru/3.16/library/functions.html#bool)) – Если `False`, сериализация значений [`float`](https://python-all.ru/3.16/library/functions.html#float) вне допустимого диапазона (`nan`, `inf`, `-inf`) вызовет [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) в строгом соответствии со спецификацией JSON. Если `True` (по умолчанию), используются их эквиваленты в JavaScript (`NaN`, `Infinity`, `-Infinity`).167- **cls** (подкласс [`JSONEncoder`](https://python-all.ru/3.16/library/json.html#json.JSONEncoder)) – Если задан, пользовательский кодировщик JSON с переопределённым методом [`default()`](https://python-all.ru/3.16/library/json.html#json.JSONEncoder.default), для сериализации в пользовательские типы данных. Если `None` (по умолчанию), используется `JSONEncoder`.168- **indent** ([*int*](https://python-all.ru/3.16/library/functions.html#int) *|* [*str*](https://python-all.ru/3.16/library/stdtypes.html#str) *|* *None*) – Если положительное целое число или строка, элементы массива JSON и члены объекта будут выводиться с отступом этого уровня. Положительное целое число добавляет указанное количество пробелов на уровень; строка (например, `"\t"`) используется для отступа каждого уровня. Если ноль, отрицательное значение или `""` (пустая строка), вставляются только символы новой строки. Если `None` (по умолчанию), символы новой строки не вставляются.169- **separators** ([*tuple*](https://python-all.ru/3.16/library/stdtypes.html#tuple) *|* *None*) – Кортеж из двух элементов: `(item_separator, key_separator)`. Если `None` (по умолчанию), *separators* по умолчанию равен `(', ', ': ')`, если *indent* равен `None`, и `(',', ': ')` в противном случае. Для максимально компактного JSON укажите `(',', ':')`, чтобы убрать пробелы.170- **default** ([callable](https://python-all.ru/3.16/glossary.html#term-callable) | None) – Функция, вызываемая для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта, кодируемую в JSON, или возбуждать [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). Если `None` (по умолчанию), возбуждается `TypeError`.171- **sort\_keys** ([*bool*](https://python-all.ru/3.16/library/functions.html#bool)) – если `True`, словари будут выводиться отсортированными по ключам. По умолчанию `False`.172173Изменено в версии 3.2: Разрешено использование строк для *indent* в дополнение к целым числам.174175Изменено в версии 3.4: Используйте `(',', ': ')` по умолчанию, если *indent* не равно `None`.176177Изменено в версии 3.6: Все необязательные параметры теперь являются [только ключевыми](https://python-all.ru/3.16/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.16/library/stdtypes.html#str), используя эту [таблицу преобразования](https://python-all.ru/3.16/library/json.html#py-to-json-table). Аргументы имеют тот же смысл, что и в [`dump()`](https://python-all.ru/3.16/library/json.html#json.dump).182183> **Примечание**184>185> Ключи в парах ключ-значение JSON всегда имеют тип [`str`](https://python-all.ru/3.16/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, array_hook=None, **kw)`188189Десериализует *fp* в объект Python, используя [таблицу преобразования JSON в Python](https://python-all.ru/3.16/library/json.html#json-to-py-table).190191**Параметры:**192193- **fp** ([файлоподобный объект](https://python-all.ru/3.16/glossary.html#term-file-like-object)) – поддерживающий `.read()` [текстовый файл](https://python-all.ru/3.16/glossary.html#term-text-file) или [двоичный файл](https://python-all.ru/3.16/glossary.html#term-binary-file), содержащий JSON-документ для десериализации.194- **cls** (подкласс [`JSONDecoder`](https://python-all.ru/3.16/library/json.html#json.JSONDecoder)) – если задан, пользовательский JSON-декодер. Дополнительные именованные аргументы для `load()` будут переданы конструктору *cls*. Если `None` (по умолчанию), используется `JSONDecoder`.195- **object\_hook** ([вызываемый объект](https://python-all.ru/3.16/glossary.html#term-callable) | None) – если задан, функция, которая вызывается с результатом декодирования любого литерала JSON-объекта ([`dict`](https://python-all.ru/3.16/library/stdtypes.html#dict)). Возвращаемое значение этой функции будет использовано вместо `dict`. Эта возможность используется для реализации пользовательских декодеров, например, для подсказок класса [JSON-RPC](https://python-all.ru/3.16/library/json.html). По умолчанию `None`.196- **object\_pairs\_hook** ([вызываемый объект](https://python-all.ru/3.16/glossary.html#term-callable) | None) – если задан, функция, которая вызывается с результатом декодирования любого литерала JSON-объекта с упорядоченным списком пар. Возвращаемое значение этой функции будет использовано вместо [`dict`](https://python-all.ru/3.16/library/stdtypes.html#dict). Эта возможность используется для реализации пользовательских декодеров. Если также задан *object\_hook*, приоритет имеет *object\_pairs\_hook*. По умолчанию `None`.197- **array\_hook** ([callable](https://python-all.ru/3.16/glossary.html#term-callable) | None) – если задан, то функция, которая вызывается с результатом любого JSON-массива, декодированного в виде списка Python. Вместо [`list`](https://python-all.ru/3.16/library/stdtypes.html#list) будет использовано возвращаемое значение этой функции. Эту возможность можно использовать для реализации собственных декодеров. По умолчанию `None`.198- **parse\_float** ([вызываемый объект](https://python-all.ru/3.16/glossary.html#term-callable) | None) – если задан, функция, вызываемая со строкой каждого JSON-числа с плавающей точкой для декодирования. Если `None` (по умолчанию), это эквивалентно `float(num_str)`. Это может использоваться для парсинга JSON-чисел с плавающей точкой в пользовательские типы данных, например, [`decimal.Decimal`](https://python-all.ru/3.16/library/decimal.html#decimal.Decimal).199- **parse\_int** ([вызываемый объект](https://python-all.ru/3.16/glossary.html#term-callable) | None) – если задан, функция, вызываемая со строкой каждого JSON-целого для декодирования. Если `None` (по умолчанию), это эквивалентно `int(num_str)`. Это может использоваться для парсинга JSON-целых чисел в пользовательские типы данных, например, [`float`](https://python-all.ru/3.16/library/functions.html#float).200- **parse\_constant** ([вызываемый объект](https://python-all.ru/3.16/glossary.html#term-callable) | None) – если задан, функция, вызываемая с одной из следующих строк: `'-Infinity'`, `'Infinity'` или `'NaN'`. Это может использоваться для возбуждения исключения при обнаружении некорректных JSON-чисел. По умолчанию `None`.201202**Возбуждает:**203204- [**JSONDecodeError**](https://python-all.ru/3.16/library/json.html#json.JSONDecodeError) – когда десериализуемые данные не являются корректным JSON-документом.205- [**UnicodeDecodeError**](https://python-all.ru/3.16/library/exceptions.html#UnicodeDecodeError) – когда десериализуемые данные не содержат данные в кодировке UTF-8, UTF-16 или UTF-32.206207Изменено в версии 3.1:208209- Добавлен необязательный параметр *object\_pairs\_hook*.210- *parse\_constant* больше не вызывается для 'null', 'true', 'false'.211212Изменено в версии 3.6:213214- Все необязательные параметры теперь являются [только ключевыми](https://python-all.ru/3.16/glossary.html#keyword-only-parameter).215- *fp* теперь может быть [двоичным файлом](https://python-all.ru/3.16/glossary.html#term-binary-file). Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.216217Изменено в версии 3.11: Значение *parse\_int* по умолчанию в [`int()`](https://python-all.ru/3.16/library/functions.html#int) теперь ограничивает максимальную длину строки целого числа через [ограничение длины преобразования строки целого числа](https://python-all.ru/3.16/library/stdtypes.html#int-max-str-digits) интерпретатора, чтобы помочь избежать атак типа «отказ в обслуживании».218219Изменено в версии 3.15: Добавлен необязательный параметр *array\_hook*.220221#### `json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, array_hook=None, **kw)`222223Идентично [`load()`](https://python-all.ru/3.16/library/json.html#json.load), но вместо файлоподобного объекта десериализует *s* (экземпляр [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.16/library/stdtypes.html#bytearray), содержащий JSON-документ) в объект Python, используя эту [таблицу преобразования](https://python-all.ru/3.16/library/json.html#json-to-py-table).224225Изменено в версии 3.6: *s* теперь может быть типа [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.16/library/stdtypes.html#bytearray). Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.226227Изменено в версии 3.9: Именованный аргумент *encoding* удален.228229## Кодировщики и декодеры230231#### `class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None, array_hook=None)`232233Простой JSON-декодер.234235По умолчанию выполняет следующие преобразования при декодировании:236237| JSON | Python |238| --- | --- |239| объект | dict |240| массив | list |241| строка | str |242| число (int) | int |243| число (вещественное) | float |244| true | True |245| false | False |246| null | None |247248Также `NaN`, `Infinity` и `-Infinity` распознаются как соответствующие значения `float`, что выходит за рамки спецификации JSON.249250*object\_hook* – необязательная функция, которая вызывается с результатом декодирования каждого JSON-объекта; её возвращаемое значение используется вместо переданного [`dict`](https://python-all.ru/3.16/library/stdtypes.html#dict). Это позволяет задавать собственную десериализацию (например, для поддержки подсказок классов [JSON-RPC](https://python-all.ru/3.16/library/json.html)).251252*object\_pairs\_hook* – необязательная функция, которая вызывается с результатом декодирования каждого JSON-объекта в виде упорядоченного списка пар. Возвращаемое значение *object\_pairs\_hook* будет использоваться вместо [`dict`](https://python-all.ru/3.16/library/stdtypes.html#dict). Этот механизм позволяет реализовывать собственные декодеры. Если также определён *object\_hook*, приоритет имеет *object\_pairs\_hook*.253254Изменено в версии 3.1: Добавлена поддержка *object\_pairs\_hook*.255256*array\_hook* – необязательная функция, которая вызывается с результатом каждого JSON-массива, декодированного в виде списка. Возвращаемое значение *array\_hook* будет использовано вместо [`list`](https://python-all.ru/3.16/library/stdtypes.html#list). Эту возможность можно использовать для реализации собственных декодеров.257258Изменено в версии 3.15: Добавлена поддержка *array\_hook*.259260*parse\_float* – необязательная функция, которая вызывается со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию она эквивалентна `float(num_str)`. Это позволяет использовать другой тип данных или синтаксический анализатор для чисел с плавающей точкой (например, [`decimal.Decimal`](https://python-all.ru/3.16/library/decimal.html#decimal.Decimal)).261262*parse\_int* – необязательная функция, которая вызывается со строкой каждого декодируемого JSON-целого числа. По умолчанию она эквивалентна `int(num_str)`. Это позволяет использовать другой тип данных или синтаксический анализатор для целых чисел JSON (например, [`float`](https://python-all.ru/3.16/library/functions.html#float)).263264*parse\_constant* – необязательная функция, которая вызывается с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`. Это позволяет вызывать исключение при обнаружении недопустимых чисел JSON.265266Если *strict* равно false (по умолчанию `True`), то управляющие символы допускаются внутри строк. Под управляющими символами здесь понимаются символы с кодами в диапазоне 0–31, включая `'\t'` (табуляция), `'\n'`, `'\r'` и `'\0'`.267268Если десериализуемые данные не являются корректным JSON-документом, будет вызвано [`JSONDecodeError`](https://python-all.ru/3.16/library/json.html#json.JSONDecodeError).269270Изменено в версии 3.6: Все параметры теперь [только ключевые](https://python-all.ru/3.16/glossary.html#keyword-only-parameter).271272#### `decode(s)`273274Возвращает представление *s* в Python (экземпляр [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), содержащий JSON-документ).275276[`JSONDecodeError`](https://python-all.ru/3.16/library/json.html#json.JSONDecodeError) будет вызвано, если переданный JSON-документ не является корректным.277278#### `raw_decode(s)`279280Декодирует JSON-документ из *s* ([`str`](https://python-all.ru/3.16/library/stdtypes.html#str), начинающийся с JSON-документа) и возвращает кортеж из двух элементов: представления в Python и индекса в *s*, на котором документ заканчивается.281282Это можно использовать для декодирования JSON-документа из строки, в конце которой могут быть лишние данные.283284#### `class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)`285286Расширяемый JSON-кодировщик для структур данных Python.287288По умолчанию поддерживает следующие объекты и типы:289290| Python | JSON |291| --- | --- |292| dict | объект |293| list, tuple | массив |294| str | строка |295| int, float, int- & float-derived Enums | число |296| True | true |297| False | false |298| None | null |299300Изменено в версии 3.4: Добавлена поддержка классов Enum, производных от int и float.301302Чтобы расширить функциональность на другие объекты, создайте подкласс и реализуйте метод [`default()`](https://python-all.ru/3.16/library/json.html#json.JSONEncoder.default) с другим методом, который возвращает сериализуемый объект для `o`, если это возможно; в противном случае следует вызвать реализацию суперкласса (для возбуждения [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError)).303304Если *skipkeys* имеет значение false (по умолчанию), возбуждается [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError) при попытке кодировать ключи, не являющиеся [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), [`int`](https://python-all.ru/3.16/library/functions.html#int), [`float`](https://python-all.ru/3.16/library/functions.html#float), [`bool`](https://python-all.ru/3.16/library/functions.html#bool) или `None`. Если *skipkeys* равно true, такие элементы просто пропускаются.305306Если *ensure\_ascii* равно true (по умолчанию), выходные данные гарантированно содержат экранированные не-ASCII и непечатаемые символы. Если *ensure\_ascii* равно false, все символы выводятся как есть, за исключением символов, которые необходимо экранировать: кавычки, обратная косая черта и управляющие символы U+0000–U+001F.307308Если *check\_circular* равно true (по умолчанию), то списки, словари и пользовательские объекты проверяются на циклические ссылки во время кодирования для предотвращения бесконечной рекурсии (которая вызвала бы [`RecursionError`](https://python-all.ru/3.16/library/exceptions.html#RecursionError)). В противном случае такая проверка не выполняется.309310Если *allow\_nan* равно true (по умолчанию), то значения `NaN`, `Infinity` и `-Infinity` кодируются как есть. Такое поведение не соответствует спецификации JSON, но согласуется с большинством кодировщиков и декодировщиков на JavaScript. В противном случае при кодировании таких чисел с плавающей запятой возбуждается [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError).311312Если *sort\_keys* равно true (по умолчанию `False`), то вывод словарей сортируется по ключам; это полезно для регрессионных тестов, чтобы обеспечить возможность сравнения JSON-сериализаций день ото дня.313314Если *indent* – неотрицательное целое число или строка, то элементы JSON-массивов и члены объектов выводятся с отступами, соответствующими указанному уровню. Уровень отступа 0, отрицательное значение или `""` вставляет только переводы строк. `None` (по умолчанию) выбирает наиболее компактное представление. Положительное целое значение отступа задаёт количество пробелов на уровень. Если *indent* является строкой (например, `"\t"`), эта строка используется для отступа каждого уровня.315316Изменено в версии 3.2: Разрешено использование строк для *indent* в дополнение к целым числам.317318Если указан, то *separators* должен быть кортежем `(item_separator, key_separator)`. По умолчанию используется `(', ', ': ')`, если *indent* равно `None`, и `(',', ': ')` в противном случае. Для получения наиболее компактного JSON-представления укажите `(',', ':')`, чтобы убрать пробелы.319320Изменено в версии 3.4: Используйте `(',', ': ')` по умолчанию, если *indent* не равно `None`.321322Если указан, *default* должен быть функцией, которая вызывается для объектов, которые не могут быть сериализованы иным способом. Она должна возвращать версию объекта, пригодную для JSON-кодирования, или возбуждать [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). Если не указано, возбуждается `TypeError`.323324Изменено в версии 3.6: Все параметры теперь [только ключевые](https://python-all.ru/3.16/glossary.html#keyword-only-parameter).325326#### `default(o)`327328В подклассе этот метод должен возвращать сериализуемый объект для *o* или вызывать базовую реализацию (для возбуждения [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError)).329330Например, для поддержки произвольных итераторов можно реализовать `default()` следующим образом:331332```python333def default(self, o):334   try:335       iterable = iter(o)336   except TypeError:337       pass338   else:339       return list(iterable)340   # Пусть метод базового класса по умолчанию возбуждает TypeError341   return super().default(o)342```343344#### `encode(o)`345346Возвращает строковое представление структуры данных Python в формате JSON, *o*. Например:347348```python349>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})350'{"foo": ["bar", "baz"]}'351```352353#### `iterencode(o)`354355Кодирует заданный объект *o* и выдаёт каждое строковое представление по мере готовности. Например:356357```python358for chunk in json.JSONEncoder().iterencode(bigobject):359    mysocket.write(chunk)360```361362## Исключения363364#### `exception json.JSONDecodeError(msg, doc, pos)`365366Подкласс [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) со следующими дополнительными атрибутами:367368#### `msg`369370Неформатированное сообщение об ошибке.371372#### `doc`373374Разбираемый JSON-документ.375376#### `pos`377378Начальный индекс *doc*, в котором произошла ошибка разбора.379380#### `lineno`381382Строка, соответствующая *pos*.383384#### `colno`385386Столбец, соответствующий *pos*.387388Добавлено в версии 3.5.389390## Соответствие стандартам и интероперабельность391392Формат JSON определяется [**RFC 7159**](https://python-all.ru/3.16/library/json.html) и [ECMA-404](https://python-all.ru/3.16/library/json.html). В этом разделе подробно описывается степень соответствия модуля RFC. Для простоты [`JSONEncoder`](https://python-all.ru/3.16/library/json.html#json.JSONEncoder) и [`JSONDecoder`](https://python-all.ru/3.16/library/json.html#json.JSONDecoder) подклассы, а также параметры, не указанные явно, не рассматриваются.393394Этот модуль не полностью соответствует RFC, реализуя некоторые расширения, которые являются допустимым JavaScript, но недопустимым JSON. В частности:395396- Бесконечные и NaN числовые значения принимаются и выводятся;397- Повторяющиеся имена в объекте принимаются, и используется только значение последней пары.398399Поскольку RFC разрешает совместимым с RFC анализаторам принимать входные тексты, которые не соответствуют RFC, десериализатор этого модуля технически соответствует RFC при настройках по умолчанию.400401### Кодировки символов402403RFC требует, чтобы JSON был представлен с использованием UTF-8, UTF-16 или UTF-32, причём UTF-8 рекомендуется по умолчанию для максимальной интероперабельности.404405Как разрешено (хотя и не требуется) RFC, сериализатор этого модуля по умолчанию устанавливает *ensure\_ascii=True*, таким образом экранируя вывод, так что результирующие строки содержат только печатные символы ASCII.406407Помимо параметра *ensure\_ascii*, этот модуль строго определён в терминах преобразования между объектами Python и [`Unicode strings`](https://python-all.ru/3.16/library/stdtypes.html#str), и таким образом напрямую не затрагивает вопрос кодировок символов.408409RFC запрещает добавление метки порядка байтов (BOM) в начало JSON-текста, и сериализатор этого модуля не добавляет BOM в свой вывод. RFC разрешает, но не требует, чтобы десериализаторы JSON игнорировали начальный BOM во входных данных. Десериализатор этого модуля возбуждает [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError), когда присутствует начальный BOM.410411RFC явно не запрещает строки JSON, содержащие последовательности байтов, которые не соответствуют допустимым символам Unicode (например, непарные суррогаты UTF-16), но отмечает, что они могут вызывать проблемы совместимости. По умолчанию этот модуль принимает и выводит (когда они присутствуют в исходном [`str`](https://python-all.ru/3.16/library/stdtypes.html#str)) кодовые точки таких последовательностей.412413### Бесконечные и NaN числовые значения414415RFC не допускает представления бесконечных или NaN числовых значений. Несмотря на это, по умолчанию этот модуль принимает и выводит `Infinity`, `-Infinity` и `NaN`, как если бы они были допустимыми числовыми литералами JSON:416417```python418>>> # Ни один из этих вызовов не возбуждает исключение, но результаты не являются корректным JSON419>>> json.dumps(float('-inf'))420'-Infinity'421>>> json.dumps(float('nan'))422'NaN'423>>> # То же самое при десериализации424>>> json.loads('-Infinity')425-inf426>>> json.loads('NaN')427nan428```429430В сериализаторе параметр *allow\_nan* можно использовать для изменения этого поведения. В десериализаторе параметр *parse\_constant* можно использовать для изменения этого поведения.431432### Повторяющиеся имена внутри объекта433434RFC указывает, что имена внутри JSON-объекта должны быть уникальными, но не предписывает, как обрабатывать повторяющиеся имена в JSON-объектах. По умолчанию этот модуль не вызывает исключение; вместо этого он игнорирует все, кроме последней пары имя-значение для данного имени:435436```python437>>> weird_json = '{"x": 1, "x": 2, "x": 3}'438>>> json.loads(weird_json)439{'x': 3}440```441442Параметр *object\_pairs\_hook* можно использовать для изменения этого поведения.443444### Значения верхнего уровня, не являющиеся объектами или массивами445446Старая версия JSON, определённая устаревшим [**RFC 4627**](https://python-all.ru/3.16/library/json.html), требовала, чтобы значение верхнего уровня JSON-текста было либо JSON-объектом, либо массивом (Python [`dict`](https://python-all.ru/3.16/library/stdtypes.html#dict) или [`list`](https://python-all.ru/3.16/library/stdtypes.html#list)), и не могло быть null, boolean, числом или строкой. [**RFC 7159**](https://python-all.ru/3.16/library/json.html) снял это ограничение, и этот модуль не реализует и никогда не реализовывал это ограничение ни в своём сериализаторе, ни в десериализаторе.447448Тем не менее, для максимальной совместимости можно добровольно придерживаться этого ограничения.449450### Ограничения реализации451452Некоторые реализации JSON-десериализаторов могут устанавливать ограничения на:453454- размер принимаемых JSON-текстов455- максимальный уровень вложенности JSON-объектов и массивов456- диапазон и точность JSON-чисел457- содержимое и максимальную длину JSON-строк458459Этот модуль не накладывает никаких подобных ограничений, кроме тех, что присущи соответствующим типам данных Python или самому интерпретатору Python.460461При сериализации в JSON учитывайте подобные ограничения в приложениях, которые могут потреблять ваш JSON. В частности, JSON-числа часто десериализуются в числа двойной точности IEEE 754 и, следовательно, подчиняются ограничениям диапазона и точности этого представления. Это особенно актуально при сериализации значений Python [`int`](https://python-all.ru/3.16/library/functions.html#int) чрезвычайно большой величины или при сериализации экземпляров «экзотических» числовых типов, таких как [`decimal.Decimal`](https://python-all.ru/3.16/library/decimal.html#decimal.Decimal).462463## Интерфейс командной строки464465**Исходный код:** [Lib/json/tool.py](https://python-all.ru/src/main/Lib/json/tool.py)466467---468469Модуль `json` можно вызвать как скрипт через `python -m json`, чтобы проверять и красиво выводить JSON-объекты. Подмодуль `json.tool` реализует этот интерфейс.470471Если необязательные аргументы `infile` и `outfile` не указаны, будут использоваться [`sys.stdin`](https://python-all.ru/3.16/library/sys.html#sys.stdin) и [`sys.stdout`](https://python-all.ru/3.16/library/sys.html#sys.stdout) соответственно:472473```console474$ echo '{"json": "obj"}' | python -m json475{476    "json": "obj"477}478$ echo '{1.2:3.4}' | python -m json479Expecting property name enclosed in double quotes: line 1 column 2 (char 1)480```481482Изменено в версии 3.5: Вывод теперь располагается в том же порядке, что и входные данные. Используйте параметр [`--sort-keys`](https://python-all.ru/3.16/library/json.html#cmdoption-json-sort-keys) для сортировки вывода словарей по ключу в алфавитном порядке.483484Изменено в версии 3.14: Модуль `json` теперь может быть напрямую выполнен как `python -m json`. Для обратной совместимости вызов CLI как `python -m json.tool` по-прежнему поддерживается.485486### Параметры командной строки487488#### `infile`489490JSON-файл для проверки или красивого вывода:491492```console493$ python -m json mp_films.json494[495    {496        "title": "And Now for Something Completely Different",497        "year": 1971498    },499    {500        "title": "Monty Python and the Holy Grail",501        "year": 1975502    }503]504```505506Если *infile* не указан, читать из [`sys.stdin`](https://python-all.ru/3.16/library/sys.html#sys.stdin).507508#### `outfile`509510Записать вывод *infile* в указанный *outfile*. В противном случае записать его в [`sys.stdout`](https://python-all.ru/3.16/library/sys.html#sys.stdout).511512#### `--sort-keys`513514Сортировать вывод словарей по ключу в алфавитном порядке.515516Добавлено в версии 3.5.517518#### `--no-ensure-ascii`519520Отключает экранирование не-ASCII символов; подробнее см. [`json.dumps()`](https://python-all.ru/3.16/library/json.html#json.dumps).521522Добавлено в версии 3.9.523524#### `--json-lines`525526Анализировать каждую входную строку как отдельный JSON-объект.527528Добавлено в версии 3.8.529530#### `--indent, --tab, --no-indent, --compact`531532Взаимоисключающие опции для управления пробелами.533534Добавлено в версии 3.9.535536#### `-h, --help`537538Показывает справочное сообщение.539540Сноски541542\[[1](https://python-all.ru/3.16/library/json.html#id1)\]543544Как отмечено в [списке ошибок RFC 7159](https://python-all.ru/3.16/library/json.html), JSON допускает символы U+2028 (LINE SEPARATOR) и U+2029 (PARAGRAPH SEPARATOR) в строках, тогда как JavaScript (начиная с ECMAScript Edition 5.1) – нет.545