`json.md`

516 строк · 45.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.8/library/json.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`json`](https://python-all.ru/3.8/library/json.html#module-json) – кодировщик и декодировщик JSON89**Исходный код:** [Lib/json/\_\_init\_\_.py](https://python-all.ru/src/3.8/Lib/json/__init__.py)1011---1213[JSON (JavaScript Object Notation)](https://python-all.ru/3.8/library/json.html), описанный в [**RFC 7159**](https://python-all.ru/3.8/library/json.html) (который заменяет [**RFC 4627**](https://python-all.ru/3.8/library/json.html)) и в [ECMA-404](https://python-all.ru/3.8/library/json.html), является легковесным форматом обмена данными, вдохновлённым синтаксисом литералов объектов [JavaScript](https://python-all.ru/3.8/library/json.html) (хотя он не является строгим подмножеством JavaScript [1](https://python-all.ru/3.8/library/json.html#rfc-errata)).1415> **Предупреждение**16>17> Соблюдайте осторожность при разборе JSON-данных из ненадёжных источников. Злонамеренная JSON-строка может заставить декодер потреблять значительные ресурсы CPU и памяти. Рекомендуется ограничивать размер разбираемых данных.1819[`json`](https://python-all.ru/3.8/library/json.html#module-json) предоставляет API, знакомый пользователям модулей стандартной библиотеки [`marshal`](https://python-all.ru/3.8/library/marshal.html#module-marshal) и [`pickle`](https://python-all.ru/3.8/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.8/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 json.JSONEncoder.default(self, 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.8/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.8/library/json.html#json-commandline) для подробной документации.123124> **Примечание**125>126> JSON является подмножеством [YAML](https://python-all.ru/3.8/library/json.html) 1.2. JSON, создаваемый настройками модуля по умолчанию (в частности, значением *separators* по умолчанию), также является подмножеством YAML 1.0 и 1.1. Таким образом, этот модуль можно использовать как сериализатор YAML.127128> **Примечание**129>130> Кодировщики и декодировщики этого модуля по умолчанию сохраняют порядок ввода и вывода. Порядок теряется только в том случае, если основные контейнеры неупорядочены.131>132> До Python 3.7 [`dict`](https://python-all.ru/3.8/library/stdtypes.html#dict) не гарантировал упорядоченность, поэтому входные и выходные данные обычно были перемешаны, если только [`collections.OrderedDict`](https://python-all.ru/3.8/library/collections.html#collections.OrderedDict) не был явно запрошен. Начиная с Python 3.7, обычный [`dict`](https://python-all.ru/3.8/library/stdtypes.html#dict) стал сохранять порядок, так что больше нет необходимости указывать [`collections.OrderedDict`](https://python-all.ru/3.8/library/collections.html#collections.OrderedDict) для генерации и разбора JSON.133134## Основное использование135136#### `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)`137138Сериализует *obj* в поток в формате JSON в *fp* (с поддержкой `.write()` [объекта, похожего на файл](https://python-all.ru/3.8/glossary.html#term-file-like-object)) с помощью этой [таблицы преобразования](https://python-all.ru/3.8/library/json.html#py-to-json-table).139140Если *skipkeys* имеет значение true (по умолчанию `False`), то ключи словаря, не являющиеся базовыми типами ([`str`](https://python-all.ru/3.8/library/stdtypes.html#str), [`int`](https://python-all.ru/3.8/library/functions.html#int), [`float`](https://python-all.ru/3.8/library/functions.html#float), [`bool`](https://python-all.ru/3.8/library/functions.html#bool), `None`), будут пропущены вместо возбуждения [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError).141142Модуль [`json`](https://python-all.ru/3.8/library/json.html#module-json) всегда создаёт объекты [`str`](https://python-all.ru/3.8/library/stdtypes.html#str), а не [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes). Поэтому `fp.write()` должен поддерживать ввод [`str`](https://python-all.ru/3.8/library/stdtypes.html#str).143144Если *ensure\_ascii* равен true (по умолчанию), то выходные данные гарантированно содержат все входящие не-ASCII-символы экранированными. Если *ensure\_ascii* равен false, эти символы выводятся как есть.145146Если *check\_circular* равен false (по умолчанию: `True`), то проверка циклических ссылок для контейнерных типов будет пропущена, и циклическая ссылка приведёт к [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError) (или хуже).147148Если *allow\_nan* имеет значение false (по умолчанию `True`), то будет [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) сериализовать значения [`float`](https://python-all.ru/3.8/library/functions.html#float), выходящие за пределы (`nan`, `inf`, `-inf`), в строгом соответствии со спецификацией JSON. Если *allow\_nan* имеет значение true, будут использоваться их эквиваленты из JavaScript (`NaN`, `Infinity`, `-Infinity`).149150Если *indent* – неотрицательное целое число или строка, то элементы JSON-массивов и члены объектов выводятся с отступами, соответствующими указанному уровню. Уровень отступа 0, отрицательное значение или `""` вставляет только переводы строк. `None` (по умолчанию) выбирает наиболее компактное представление. Положительное целое значение отступа задаёт количество пробелов на уровень. Если *indent* является строкой (например, `"\t"`), эта строка используется для отступа каждого уровня.151152Изменено в версии 3.2: Разрешено использование строк для *indent* в дополнение к целым числам.153154Если указан, то *separators* должен быть кортежем `(item_separator, key_separator)`. По умолчанию используется `(', ', ': ')`, если *indent* равно `None`, и `(',', ': ')` в противном случае. Для получения наиболее компактного JSON-представления укажите `(',', ':')`, чтобы убрать пробелы.155156Изменено в версии 3.4: Используйте `(',', ': ')` по умолчанию, если *indent* не равно `None`.157158Если указан, *default* должен быть функцией, которая вызывается для объектов, которые не могут быть сериализованы иным способом. Она должна возвращать версию объекта, пригодную для JSON-кодирования, или возбуждать [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError). Если не указано, возбуждается [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError).159160Если *sort\_keys* имеет значение true (по умолчанию `False`), то вывод словарей будет отсортирован по ключам.161162Чтобы использовать пользовательский подкласс [`JSONEncoder`](https://python-all.ru/3.8/library/json.html#json.JSONEncoder) (например, переопределяющий метод `default()` для сериализации дополнительных типов), укажите его с помощью именованного аргумента *cls*; в противном случае используется [`JSONEncoder`](https://python-all.ru/3.8/library/json.html#json.JSONEncoder).163164Изменено в версии 3.6: Все необязательные параметры теперь являются [только ключевыми](https://python-all.ru/3.8/glossary.html#keyword-only-parameter).165166> **Примечание**167>168> В отличие от [`pickle`](https://python-all.ru/3.8/library/pickle.html#module-pickle) и [`marshal`](https://python-all.ru/3.8/library/marshal.html#module-marshal), JSON не является фреймовым протоколом, поэтому попытка сериализовать несколько объектов с повторными вызовами [`dump()`](https://python-all.ru/3.8/library/json.html#json.dump) с использованием одного и того же *fp* приведёт к созданию недопустимого JSON-файла.169170#### `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)`171172Сериализует *obj* в JSON-форматированную [`str`](https://python-all.ru/3.8/library/stdtypes.html#str), используя эту [таблицу преобразования](https://python-all.ru/3.8/library/json.html#py-to-json-table). Аргументы имеют тот же смысл, что и в [`dump()`](https://python-all.ru/3.8/library/json.html#json.dump).173174> **Примечание**175>176> Ключи в парах ключ-значение JSON всегда имеют тип [`str`](https://python-all.ru/3.8/library/stdtypes.html#str). При преобразовании словаря в JSON все его ключи приводятся к строкам. В результате, если словарь преобразовать в JSON, а затем обратно в словарь, полученный словарь может не совпадать с исходным. То есть `loads(dumps(x)) != x`, если x имеет нестроковые ключи.177178#### `json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)`179180Десериализует *fp* (с поддержкой `.read()` [текстовый файл](https://python-all.ru/3.8/glossary.html#term-text-file) или [двоичный файл](https://python-all.ru/3.8/glossary.html#term-binary-file), содержащий документ JSON) в объект Python с помощью этой [таблицы преобразования](https://python-all.ru/3.8/library/json.html#json-to-py-table).181182*object\_hook* – необязательная функция, которая будет вызвана с результатом декодирования любого литерала объекта ([`dict`](https://python-all.ru/3.8/library/stdtypes.html#dict)). Возвращаемое значение *object\_hook* будет использовано вместо [`dict`](https://python-all.ru/3.8/library/stdtypes.html#dict). Эту возможность можно использовать для реализации пользовательских декодеров (например, [JSON-RPC](https://python-all.ru/3.8/library/json.html) подсказки класса).183184*object\_pairs\_hook* – необязательная функция, которая будет вызвана с результатом декодирования любого литерала объекта с упорядоченным списком пар. Возвращаемое значение *object\_pairs\_hook* будет использовано вместо [`dict`](https://python-all.ru/3.8/library/stdtypes.html#dict). Эту возможность можно использовать для реализации пользовательских декодеров. Если также определён *object\_hook*, то *object\_pairs\_hook* имеет приоритет.185186Изменено в версии 3.1: Добавлена поддержка *object\_pairs\_hook*.187188*parse\_float*, если указан, будет вызван со строкой каждого декодируемого JSON-числа с плавающей запятой. По умолчанию это эквивалентно `float(num_str)`. Это может быть использовано для использования другого типа данных или парсера для JSON-чисел с плавающей запятой (например, [`decimal.Decimal`](https://python-all.ru/3.8/library/decimal.html#decimal.Decimal)).189190*parse\_int*, если указан, будет вызван со строкой каждого декодируемого JSON-целого числа. По умолчанию это эквивалентно `int(num_str)`. Это может быть использовано для использования другого типа данных или парсера для JSON-целых чисел (например, [`float`](https://python-all.ru/3.8/library/functions.html#float)).191192Изменено в версии 3.8.14: По умолчанию *parse\_int* из [`int()`](https://python-all.ru/3.8/library/functions.html#int) теперь ограничивает максимальную длину строки целого числа через [ограничение длины строки целого числа при преобразовании](https://python-all.ru/3.8/library/stdtypes.html#int-max-str-digits) интерпретатора, чтобы помочь избежать атак типа «отказ в обслуживании».193194*parse\_constant*, если указан, будет вызван с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`. Это может быть использовано для генерации исключения при обнаружении некорректных чисел JSON.195196Изменено в версии 3.1: *parse\_constant* больше не вызывается для ‘null’, ‘true’, ‘false’.197198Чтобы использовать пользовательский подкласс [`JSONDecoder`](https://python-all.ru/3.8/library/json.html#json.JSONDecoder), укажите его с помощью именованного аргумента `cls`; в противном случае используется [`JSONDecoder`](https://python-all.ru/3.8/library/json.html#json.JSONDecoder). Дополнительные именованные аргументы будут переданы конструктору класса.199200Если десериализуемые данные не являются корректным JSON-документом, будет вызвано [`JSONDecodeError`](https://python-all.ru/3.8/library/json.html#json.JSONDecodeError).201202Изменено в версии 3.6: Все необязательные параметры теперь являются [только ключевыми](https://python-all.ru/3.8/glossary.html#keyword-only-parameter).203204Изменено в версии 3.6: *fp* теперь может быть [двоичным файлом](https://python-all.ru/3.8/glossary.html#term-binary-file). Кодировка ввода должна быть UTF-8, UTF-16 или UTF-32.205206#### `json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)`207208Десериализует *s* ([`str`](https://python-all.ru/3.8/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.8/library/stdtypes.html#bytearray) экземпляр, содержащий документ JSON) в объект Python с помощью этой [таблицы преобразования](https://python-all.ru/3.8/library/json.html#json-to-py-table).209210Остальные аргументы имеют тот же смысл, что и в [`load()`](https://python-all.ru/3.8/library/json.html#json.load), за исключением *encoding*, который игнорируется и устарел с Python 3.1.211212Если десериализуемые данные не являются корректным JSON-документом, будет вызвано [`JSONDecodeError`](https://python-all.ru/3.8/library/json.html#json.JSONDecodeError).213214Устарело с версии 3.1, будет удалено в версии 3.9: аргумент-ключевое слово *encoding*.215216Изменено в версии 3.6: *s* теперь может быть типа [`bytes`](https://python-all.ru/3.8/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.8/library/stdtypes.html#bytearray). Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.217218## Кодировщики и декодеры219220#### `class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)`221222Простой JSON-декодер.223224По умолчанию выполняет следующие преобразования при декодировании:225226| JSON | Python |227| --- | --- |228| объект | dict |229| массив | list |230| строка | str |231| число (int) | int |232| число (вещественное) | float |233| true | True |234| false | False |235| null | None |236237Также `NaN`, `Infinity` и `-Infinity` распознаются как соответствующие значения `float`, что выходит за рамки спецификации JSON.238239*object\_hook*, если указан, будет вызываться с результатом декодирования каждого JSON объекта, и его возвращаемое значение будет использоваться вместо полученного [`dict`](https://python-all.ru/3.8/library/stdtypes.html#dict). Это может использоваться для предоставления пользовательской десериализации (например, для поддержки подсказок классов JSON-RPC).240241*object\_pairs\_hook*, если указан, будет вызван с результатом каждого декодированного объекта JSON с упорядоченным списком пар. Возвращаемое значение *object\_pairs\_hook* будет использовано вместо [`dict`](https://python-all.ru/3.8/library/stdtypes.html#dict). Эта функция может быть использована для реализации пользовательских декодеров. Если также определен *object\_hook*, то *object\_pairs\_hook* имеет больший приоритет.242243Изменено в версии 3.1: Добавлена поддержка *object\_pairs\_hook*.244245*parse\_float*, если указан, будет вызван со строкой каждого декодируемого JSON-числа с плавающей запятой. По умолчанию это эквивалентно `float(num_str)`. Это может быть использовано для использования другого типа данных или парсера для JSON-чисел с плавающей запятой (например, [`decimal.Decimal`](https://python-all.ru/3.8/library/decimal.html#decimal.Decimal)).246247*parse\_int*, если указан, будет вызван со строкой каждого декодируемого JSON-целого числа. По умолчанию это эквивалентно `int(num_str)`. Это может быть использовано для использования другого типа данных или парсера для JSON-целых чисел (например, [`float`](https://python-all.ru/3.8/library/functions.html#float)).248249*parse\_constant*, если указан, будет вызван с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`. Это может быть использовано для генерации исключения при обнаружении некорректных чисел JSON.250251Если *strict* равно false (по умолчанию `True`), то управляющие символы допускаются внутри строк. Под управляющими символами здесь понимаются символы с кодами в диапазоне 0–31, включая `'\t'` (табуляция), `'\n'`, `'\r'` и `'\0'`.252253Если десериализуемые данные не являются корректным JSON-документом, будет вызвано [`JSONDecodeError`](https://python-all.ru/3.8/library/json.html#json.JSONDecodeError).254255Изменено в версии 3.6: Все параметры теперь [только ключевые](https://python-all.ru/3.8/glossary.html#keyword-only-parameter).256257#### `decode(s)`258259Возвращает представление *s* в Python (экземпляр [`str`](https://python-all.ru/3.8/library/stdtypes.html#str), содержащий JSON-документ).260261[`JSONDecodeError`](https://python-all.ru/3.8/library/json.html#json.JSONDecodeError) будет вызвано, если переданный JSON-документ не является корректным.262263#### `raw_decode(s)`264265Декодирует JSON-документ из *s* ([`str`](https://python-all.ru/3.8/library/stdtypes.html#str), начинающийся с JSON-документа) и возвращает кортеж из двух элементов: представления в Python и индекса в *s*, на котором документ заканчивается.266267Это можно использовать для декодирования JSON-документа из строки, в конце которой могут быть лишние данные.268269#### `class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)`270271Расширяемый JSON-кодировщик для структур данных Python.272273По умолчанию поддерживает следующие объекты и типы:274275| Python | JSON |276| --- | --- |277| dict | объект |278| list, tuple | массив |279| str | строка |280| int, float, перечисления, производные от int и float | число |281| True | true |282| False | false |283| None | null |284285Изменено в версии 3.4: Добавлена поддержка классов Enum, производных от int и float.286287Чтобы расширить функциональность на другие объекты, создайте подкласс и реализуйте метод [`default()`](https://python-all.ru/3.8/library/json.html#json.JSONEncoder.default) с другим методом, который возвращает сериализуемый объект для `o`, если это возможно; в противном случае следует вызвать реализацию суперкласса (для возбуждения [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError)).288289Если *skipkeys* имеет значение false (по умолчанию), то попытка кодирования ключей, не являющихся [`str`](https://python-all.ru/3.8/library/stdtypes.html#str), [`int`](https://python-all.ru/3.8/library/functions.html#int), [`float`](https://python-all.ru/3.8/library/functions.html#float) или `None`, вызовет [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError). Если *skipkeys* равно true, такие элементы просто пропускаются.290291Если *ensure\_ascii* равен true (по умолчанию), то выходные данные гарантированно содержат все входящие не-ASCII-символы экранированными. Если *ensure\_ascii* равен false, эти символы выводятся как есть.292293Если *check\_circular* равен true (по умолчанию), то списки, словари и пользовательские закодированные объекты проверяются на наличие циклических ссылок во время кодирования, чтобы предотвратить бесконечную рекурсию (которая привела бы к [`OverflowError`](https://python-all.ru/3.8/library/exceptions.html#OverflowError)). В противном случае такая проверка не выполняется.294295Если *allow\_nan* равно true (по умолчанию), то значения `NaN`, `Infinity` и `-Infinity` кодируются как есть. Такое поведение не соответствует спецификации JSON, но согласуется с большинством кодировщиков и декодировщиков на JavaScript. В противном случае при кодировании таких чисел с плавающей запятой возбуждается [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError).296297Если *sort\_keys* равно true (по умолчанию `False`), то вывод словарей сортируется по ключам; это полезно для регрессионных тестов, чтобы обеспечить возможность сравнения JSON-сериализаций день ото дня.298299Если *indent* – неотрицательное целое число или строка, то элементы JSON-массивов и члены объектов выводятся с отступами, соответствующими указанному уровню. Уровень отступа 0, отрицательное значение или `""` вставляет только переводы строк. `None` (по умолчанию) выбирает наиболее компактное представление. Положительное целое значение отступа задаёт количество пробелов на уровень. Если *indent* является строкой (например, `"\t"`), эта строка используется для отступа каждого уровня.300301Изменено в версии 3.2: Разрешено использование строк для *indent* в дополнение к целым числам.302303Если указан, то *separators* должен быть кортежем `(item_separator, key_separator)`. По умолчанию используется `(', ', ': ')`, если *indent* равно `None`, и `(',', ': ')` в противном случае. Для получения наиболее компактного JSON-представления укажите `(',', ':')`, чтобы убрать пробелы.304305Изменено в версии 3.4: Используйте `(',', ': ')` по умолчанию, если *indent* не равно `None`.306307Если указан, *default* должен быть функцией, которая вызывается для объектов, которые не могут быть сериализованы иным способом. Она должна возвращать версию объекта, пригодную для JSON-кодирования, или возбуждать [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError). Если не указано, возбуждается [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError).308309Изменено в версии 3.6: Все параметры теперь [только ключевые](https://python-all.ru/3.8/glossary.html#keyword-only-parameter).310311#### `default(o)`312313В подклассе этот метод должен возвращать сериализуемый объект для *o* или вызывать базовую реализацию (для возбуждения [`TypeError`](https://python-all.ru/3.8/library/exceptions.html#TypeError)).314315Например, чтобы поддерживать произвольные итераторы, можно реализовать default следующим образом:316317```python318def default(self, o):319   try:320       iterable = iter(o)321   except TypeError:322       pass323   else:324       return list(iterable)325   # Пусть метод базового класса по умолчанию возбуждает TypeError326   return json.JSONEncoder.default(self, o)327```328329#### `encode(o)`330331Возвращает строковое представление структуры данных Python в формате JSON, *o*. Например:332333```python334>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})335'{"foo": ["bar", "baz"]}'336```337338#### `iterencode(o)`339340Кодирует заданный объект *o* и выдаёт каждое строковое представление по мере готовности. Например:341342```python343for chunk in json.JSONEncoder().iterencode(bigobject):344    mysocket.write(chunk)345```346347## Исключения348349#### `exception json.JSONDecodeError(msg, doc, pos)`350351Подкласс [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) со следующими дополнительными атрибутами:352353#### `msg`354355Неформатированное сообщение об ошибке.356357#### `doc`358359Разбираемый JSON-документ.360361#### `pos`362363Начальный индекс *doc*, в котором произошла ошибка разбора.364365#### `lineno`366367Строка, соответствующая *pos*.368369#### `colno`370371Столбец, соответствующий *pos*.372373Новое в версии 3.5.374375## Соответствие стандартам и интероперабельность376377Формат JSON определяется [**RFC 7159**](https://python-all.ru/3.8/library/json.html) и [ECMA-404](https://python-all.ru/3.8/library/json.html). В этом разделе подробно описывается степень соответствия модуля RFC. Для простоты [`JSONEncoder`](https://python-all.ru/3.8/library/json.html#json.JSONEncoder) и [`JSONDecoder`](https://python-all.ru/3.8/library/json.html#json.JSONDecoder) подклассы, а также параметры, не указанные явно, не рассматриваются.378379Этот модуль не полностью соответствует RFC, реализуя некоторые расширения, которые являются допустимым JavaScript, но недопустимым JSON. В частности:380381- Бесконечные и NaN числовые значения принимаются и выводятся;382- Повторяющиеся имена в объекте принимаются, и используется только значение последней пары.383384Поскольку RFC разрешает совместимым с RFC анализаторам принимать входные тексты, которые не соответствуют RFC, десериализатор этого модуля технически соответствует RFC при настройках по умолчанию.385386### Кодировки символов387388RFC требует, чтобы JSON был представлен с использованием UTF-8, UTF-16 или UTF-32, причём UTF-8 рекомендуется по умолчанию для максимальной интероперабельности.389390Согласно RFC это допускается, но не требуется; сериализатор данного модуля по умолчанию использует *ensure\_ascii=True*, экранируя вывод так, чтобы результирующие строки содержали только ASCII-символы.391392Помимо параметра *ensure\_ascii*, этот модуль строго определён в терминах преобразования между объектами Python и [`Unicode strings`](https://python-all.ru/3.8/library/stdtypes.html#str), и таким образом напрямую не затрагивает вопрос кодировок символов.393394RFC запрещает добавление метки порядка байтов (BOM) в начало JSON-текста, и сериализатор этого модуля не добавляет BOM в свой вывод. RFC разрешает, но не требует, чтобы десериализаторы JSON игнорировали начальный BOM во входных данных. Десериализатор этого модуля возбуждает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError), когда присутствует начальный BOM.395396RFC явно не запрещает строки JSON, содержащие последовательности байтов, которые не соответствуют допустимым символам Unicode (например, непарные суррогаты UTF-16), но отмечает, что они могут вызывать проблемы совместимости. По умолчанию этот модуль принимает и выводит (когда они присутствуют в исходном [`str`](https://python-all.ru/3.8/library/stdtypes.html#str)) кодовые точки таких последовательностей.397398### Бесконечные и NaN числовые значения399400RFC не допускает представления бесконечных или NaN числовых значений. Несмотря на это, по умолчанию этот модуль принимает и выводит `Infinity`, `-Infinity` и `NaN`, как если бы они были допустимыми числовыми литералами JSON:401402```python403>>> # Ни один из этих вызовов не возбуждает исключение, но результаты не являются корректным JSON404>>> json.dumps(float('-inf'))405'-Infinity'406>>> json.dumps(float('nan'))407'NaN'408>>> # То же самое при десериализации409>>> json.loads('-Infinity')410-inf411>>> json.loads('NaN')412nan413```414415В сериализаторе параметр *allow\_nan* можно использовать для изменения этого поведения. В десериализаторе параметр *parse\_constant* можно использовать для изменения этого поведения.416417### Повторяющиеся имена внутри объекта418419RFC указывает, что имена внутри JSON-объекта должны быть уникальными, но не предписывает, как обрабатывать повторяющиеся имена в JSON-объектах. По умолчанию этот модуль не вызывает исключение; вместо этого он игнорирует все, кроме последней пары имя-значение для данного имени:420421```python422>>> weird_json = '{"x": 1, "x": 2, "x": 3}'423>>> json.loads(weird_json)424{'x': 3}425```426427Параметр *object\_pairs\_hook* можно использовать для изменения этого поведения.428429### Значения верхнего уровня, не являющиеся объектами или массивами430431Старая версия JSON, определённая устаревшим [**RFC 4627**](https://python-all.ru/3.8/library/json.html), требовала, чтобы значение верхнего уровня JSON-текста было либо JSON-объектом, либо массивом (Python [`dict`](https://python-all.ru/3.8/library/stdtypes.html#dict) или [`list`](https://python-all.ru/3.8/library/stdtypes.html#list)), и не могло быть null, boolean, числом или строкой. [**RFC 7159**](https://python-all.ru/3.8/library/json.html) снял это ограничение, и этот модуль не реализует и никогда не реализовывал это ограничение ни в своём сериализаторе, ни в десериализаторе.432433Тем не менее, для максимальной совместимости можно добровольно придерживаться этого ограничения.434435### Ограничения реализации436437Некоторые реализации JSON-десериализаторов могут устанавливать ограничения на:438439- размер принимаемых JSON-текстов440- максимальный уровень вложенности JSON-объектов и массивов441- диапазон и точность JSON-чисел442- содержимое и максимальную длину JSON-строк443444Этот модуль не накладывает никаких подобных ограничений, кроме тех, что присущи соответствующим типам данных Python или самому интерпретатору Python.445446При сериализации в JSON учитывайте подобные ограничения в приложениях, которые могут потреблять ваш JSON. В частности, JSON-числа часто десериализуются в числа двойной точности IEEE 754 и, следовательно, подчиняются ограничениям диапазона и точности этого представления. Это особенно актуально при сериализации значений Python [`int`](https://python-all.ru/3.8/library/functions.html#int) чрезвычайно большой величины или при сериализации экземпляров «экзотических» числовых типов, таких как [`decimal.Decimal`](https://python-all.ru/3.8/library/decimal.html#decimal.Decimal).447448## Интерфейс командной строки449450**Исходный код:** [Lib/json/tool.py](https://python-all.ru/src/3.8/Lib/json/tool.py)451452---453454Модуль [`json.tool`](https://python-all.ru/3.8/library/json.html#module-json.tool) предоставляет простой интерфейс командной строки для проверки и форматированного вывода JSON-объектов.455456Если необязательные аргументы `infile` и `outfile` не указаны, будут использоваться [`sys.stdin`](https://python-all.ru/3.8/library/sys.html#sys.stdin) и [`sys.stdout`](https://python-all.ru/3.8/library/sys.html#sys.stdout) соответственно:457458```console459$ echo '{"json": "obj"}' | python -m json.tool460{461    "json": "obj"462}463$ echo '{1.2:3.4}' | python -m json.tool464Expecting property name enclosed in double quotes: line 1 column 2 (char 1)465```466467Изменено в версии 3.5: Вывод теперь располагается в том же порядке, что и входные данные. Используйте параметр [`--sort-keys`](https://python-all.ru/3.8/library/json.html#cmdoption-json-tool-sort-keys) для сортировки вывода словарей по ключу в алфавитном порядке.468469### Параметры командной строки470471#### `infile`472473JSON-файл для проверки или красивого вывода:474475```console476$ python -m json.tool mp_films.json477[478    {479        "title": "And Now for Something Completely Different",480        "year": 1971481    },482    {483        "title": "Monty Python and the Holy Grail",484        "year": 1975485    }486]487```488489Если *infile* не указан, читать из [`sys.stdin`](https://python-all.ru/3.8/library/sys.html#sys.stdin).490491#### `outfile`492493Записать вывод *infile* в указанный *outfile*. В противном случае записать его в [`sys.stdout`](https://python-all.ru/3.8/library/sys.html#sys.stdout).494495#### `--sort-keys`496497Сортировать вывод словарей по ключу в алфавитном порядке.498499Новое в версии 3.5.500501#### `--json-lines`502503Анализировать каждую входную строку как отдельный JSON-объект.504505Новое в версии 3.8.506507#### `-h, --help`508509Показывает справочное сообщение.510511Сноски512513**[1](https://python-all.ru/3.8/library/json.html#id1)**514515Как отмечено в [списке ошибок RFC 7159](https://python-all.ru/3.8/library/json.html), JSON допускает символы U+2028 (LINE SEPARATOR) и U+2029 (PARAGRAPH SEPARATOR) в строках, тогда как JavaScript (начиная с ECMAScript Edition 5.1) – нет.516