> **Источник:** https://python-all.ru/3.0/library/json.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# `json` – JSON кодировщик и декодировщик

JSON (JavaScript Object Notation) \<[http://json.org](https://python-all.ru/3.0/library/json.html)\> – это подмножество синтаксиса JavaScript (ECMA-262, 3-е издание), используемое в качестве легковесного формата обмена данными.

`json` предоставляет API, знакомый пользователям модулей стандартной библиотеки [`marshal`](https://python-all.ru/3.0/library/marshal.html#module-marshal) и [`pickle`](https://python-all.ru/3.0/library/pickle.html#module-pickle).

Кодирование иерархий базовых объектов Python:

```python
>>> import json
>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
'["foo", {"bar": ["baz", null, 1.0, 2]}]'
>>> print(json.dumps("\"foo\bar"))
"\"foo\bar"
>>> print(json.dumps('\u1234'))
"\u1234"
>>> print(json.dumps('\\'))
"\\"
>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
{"a": 0, "b": 0, "c": 0}
>>> from io import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'
```

Компактное кодирование:

```python
>>> import json
>>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
'[1,2,3,{"4":5,"6":7}]'
```

Красивое форматирование:

```python
>>> import json
>>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}
```

Декодирование JSON:

```python
>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
['foo', {'bar': ['baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
'"foo\x08ar'
>>> from io import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
['streaming API']
```

Специализированное декодирование объектов JSON:

```python
>>> import json
>>> def as_complex(dct):
...     if '__complex__' in dct:
...         return complex(dct['real'], dct['imag'])
...     return dct
...
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
...     object_hook=as_complex)
(1+2j)
>>> import decimal
>>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1')
```

Расширение [`JSONEncoder`](https://python-all.ru/3.0/library/json.html#json.JSONEncoder):

```python
>>> import json
>>> class ComplexEncoder(json.JSONEncoder):
...     def default(self, obj):
...         if isinstance(obj, complex):
...             return [obj.real, obj.imag]
...         return json.JSONEncoder.default(self, obj)
...
>>> dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'
>>> ComplexEncoder().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncoder().iterencode(2 + 1j))
['[', '2.0', ', ', '1.0', ']']
```

Использование json.tool из командной оболочки для проверки и форматирования:

```text
$ echo '{"json":"obj"}' | python -mjson.tool
{
    "json": "obj"
}
$ echo '{ 1.2:3.4}' | python -mjson.tool
Expecting property name: line 1 column 2 (char 2)
```

> **Примечание**
>
> JSON, создаваемый стандартными настройками этого модуля, является подмножеством YAML, поэтому его также можно использовать в качестве сериализатора для YAML.

## Основное использование

#### `[json.dump]json.dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])`

Сериализует *obj* в поток в формате JSON и записывает его в *fp* (поддерживающий `.write()` объект, похожий на файл).

Если *skipkeys* равно `True` (по умолчанию: `False`), то ключи словаря, не являющиеся базовыми типами ([`str`](https://python-all.ru/3.0/library/functions.html#str), `unicode`, [`int`](https://python-all.ru/3.0/library/functions.html#int), `long`, [`float`](https://python-all.ru/3.0/library/functions.html#float), [`bool`](https://python-all.ru/3.0/library/functions.html#bool), `None`) будут пропущены вместо возбуждения [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError).

Если *ensure\_ascii* равно `False` (по умолчанию: `True`), то некоторые фрагменты, записанные в *fp*, могут быть экземплярами `unicode` в соответствии с обычными правилами приведения [`str`](https://python-all.ru/3.0/library/functions.html#str) к `unicode` в Python. Если `fp.write()` явно не поддерживает `unicode` (как, например, [`codecs.getwriter()`](https://python-all.ru/3.0/library/codecs.html#codecs.getwriter)), это скорее всего приведёт к ошибке.

Если *check\_circular* равно `False` (по умолчанию: `True`), то проверка циклических ссылок для контейнерных типов будет пропущена, и циклическая ссылка приведет к [`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError) (или хуже).

Если *allow\_nan* равно `False` (по умолчанию: `True`), то сериализация значений [`float`](https://python-all.ru/3.0/library/functions.html#float) вне допустимого диапазона (`nan`, `inf`, `-inf`) будет вызывать [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) в строгом соответствии со спецификацией JSON, вместо использования JavaScript-эквивалентов (`NaN`, `Infinity`, `-Infinity`).

Если *indent* – неотрицательное целое число, то элементы массивов и члены объектов JSON будут выводиться с отступами этого уровня. Уровень отступа 0 будет вставлять только новые строки. `None` (по умолчанию) выбирает наиболее компактное представление.

Если *separators* является кортежем `(item_separator, dict_separator)`, то он будет использоваться вместо разделителей по умолчанию `(', ', ': ')`. `(',', ':')` – это наиболее компактное представление JSON.

*encoding* – это кодировка символов для экземпляров str, по умолчанию UTF-8.

*default(obj)* – это функция, которая должна возвращать сериализуемую версию *obj* или возбуждать [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError). По умолчанию просто возбуждается [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError).

Чтобы использовать пользовательский подкласс [`JSONEncoder`](https://python-all.ru/3.0/library/json.html#json.JSONEncoder) (например, переопределяющий метод `default()` для сериализации дополнительных типов), укажите его с помощью аргумента *cls*.

#### `[json.dumps]json.dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])`

Сериализует *obj* в строку [`str`](https://python-all.ru/3.0/library/functions.html#str) в формате JSON.

Если *ensure\_ascii* равно `False`, то возвращаемое значение будет экземпляром `unicode`. Остальные аргументы имеют тот же смысл, что и в [`dump()`](https://python-all.ru/3.0/library/json.html#json.dump).

#### `[json.load]json.load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])`

Десериализует *fp* (объект, похожий на файл, поддерживающий `.read()` и содержащий JSON-документ) в объект Python.

Если содержимое *fp* закодировано в ASCII-совместимой кодировке, отличной от UTF-8 (например, latin-1), необходимо указать соответствующее имя *encoding*. Кодировки, не основанные на ASCII (такие как UCS-2), не допускаются, и их следует обернуть с помощью `codecs.getreader(fp)(encoding)`, или просто декодировать в объект `unicode` и передать в [`loads()`](https://python-all.ru/3.0/library/json.html#json.loads).

*object\_hook* – это необязательная функция, которая будет вызвана с результатом декодирования любого объектного литерала ([`dict`](https://python-all.ru/3.0/library/stdtypes.html#dict)). Возвращаемое значение *object\_hook* будет использоваться вместо [`dict`](https://python-all.ru/3.0/library/stdtypes.html#dict). Эта возможность может использоваться для реализации пользовательских декодировщиков (например, подсказки классов JSON-RPC).

*parse\_float*, если указан, будет вызван со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию это эквивалентно `float(num_str)`. Это можно использовать для применения другого типа данных или парсера для JSON чисел с плавающей точкой (например, [`decimal.Decimal`](https://python-all.ru/3.0/library/decimal.html#decimal.Decimal)).

*parse\_int*, если указан, будет вызван со строкой каждого декодируемого JSON-целого числа. По умолчанию это эквивалентно `int(num_str)`. Это можно использовать для применения другого типа данных или парсера для JSON целых чисел (например, [`float`](https://python-all.ru/3.0/library/functions.html#float)).

*parse\_constant*, если указан, будет вызван с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`, `'null'`, `'true'`, `'false'`. Это может быть использовано для возбуждения исключения при обнаружении недопустимых JSON чисел.

Чтобы использовать пользовательский подкласс [`JSONDecoder`](https://python-all.ru/3.0/library/json.html#json.JSONDecoder), укажите его с помощью аргумента `cls` именованный аргумент. Дополнительные именованные аргументы будут переданы конструктору класса.

#### `[json.loads]json.loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])`

Десериализует *s* (экземпляр [`str`](https://python-all.ru/3.0/library/functions.html#str) или `unicode`, содержащий JSON- документ) в объект Python.

Если *s* является экземпляром [`str`](https://python-all.ru/3.0/library/functions.html#str) и закодирован в ASCII-совместимой кодировке, отличной от UTF-8 (например, latin-1), необходимо указать соответствующее имя *encoding*. Кодировки, не основанные на ASCII (такие как UCS-2), не допускаются и должны быть сначала декодированы в `unicode`.

Остальные аргументы имеют тот же смысл, что и в [`dump()`](https://python-all.ru/3.0/library/json.html#json.dump).

## Кодировщики и декодировщики

#### `[json.JSONDecoder]class json.JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict]]]]]])`

Простой JSON-декодер.

По умолчанию выполняет следующие преобразования при декодировании:

| JSON | Python |
| --- | --- |
| объект | dict |
| массив | список |
| строка | unicode |
| число (int) | int, long |
| число (вещественное) | float |
| истина | True |
| ложь | False |
| null | None |

Он также понимает `NaN`, `Infinity` и `-Infinity` как соответствующие значения `float`, что выходит за рамки спецификации JSON.

*encoding* определяет кодировку, используемую для интерпретации любых объектов [`str`](https://python-all.ru/3.0/library/functions.html#str), декодированных этим экземпляром (по умолчанию UTF-8). Он не влияет на декодирование объектов `unicode`.

Обратите внимание, что сейчас работают только кодировки, являющиеся надмножеством ASCII. Строки других кодировок нужно передавать как `unicode`.

*object\_hook*, если указан, будет вызван с результатом декодирования каждого JSON-объекта, и его возвращаемое значение будет использовано вместо переданного [`dict`](https://python-all.ru/3.0/library/stdtypes.html#dict). Это может быть использовано для предоставления пользовательских десериализаций (например, для поддержки JSON-RPC подсказок классов).

*parse\_float*, если указан, будет вызван со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию это эквивалентно `float(num_str)`. Это можно использовать для применения другого типа данных или парсера для JSON чисел с плавающей точкой (например, [`decimal.Decimal`](https://python-all.ru/3.0/library/decimal.html#decimal.Decimal)).

*parse\_int*, если указан, будет вызван со строкой каждого декодируемого JSON-целого числа. По умолчанию это эквивалентно `int(num_str)`. Это можно использовать для применения другого типа данных или парсера для JSON целых чисел (например, [`float`](https://python-all.ru/3.0/library/functions.html#float)).

*parse\_constant*, если указан, будет вызван с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`, `'null'`, `'true'`, `'false'`. Это может быть использовано для возбуждения исключения при обнаружении недопустимых JSON чисел.

#### `[json.JSONDecoder.decode]decode(s)`

Возвращает Python-представление

*s*

(экземпляра

[`str`](https://python-all.ru/3.0/library/functions.html#str)

или

`unicode`

, содержащего документ JSON).

#### `[json.JSONDecoder.raw_decode]raw_decode(s)`

Декодирует документ JSON из *s* ([`str`](https://python-all.ru/3.0/library/functions.html#str) или `unicode`, начинающегося с документа JSON) и возвращает кортеж из двух элементов: представление Python и индекс в *s*, по которому заканчивается документ.

Это можно использовать для декодирования JSON-документа из строки, в конце которой могут быть лишние данные.

#### `[json.JSONEncoder]class json.JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]])`

Расширяемый JSON-кодировщик для структур данных Python.

По умолчанию поддерживает следующие объекты и типы:

| Python | JSON |
| --- | --- |
| dict | объект |
| list, tuple | массив |
| str, unicode | строка |
| int, long, float | число |
| True | истина |
| False | ложь |
| None | null |

Чтобы расширить это для распознавания других объектов, создайте подкласс и реализуйте метод [`default()`](https://python-all.ru/3.0/library/json.html#json.JSONEncoder.default): с помощью другого метода он должен возвращать сериализуемый объект для `o`, если это возможно; в противном случае следует вызвать реализацию суперкласса (чтобы возбудить [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)).

Если *skipkeys* равен `False` (по умолчанию), то попытка кодировать ключи, не являющиеся str, int, long, float или None, приводит к [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError). Если *skipkeys* равен `True`, такие элементы просто пропускаются.

Если *ensure\_ascii* равен `True` (по умолчанию), результат гарантированно будет объектом [`str`](https://python-all.ru/3.0/library/functions.html#str) со всеми входящими символами unicode, экранированными. Если *ensure\_ascii* равен `False`, результатом будет объект unicode.

Если *check\_circular* равен `True` (по умолчанию), то списки, словари и пользовательские кодированные объекты будут проверяться на циклические ссылки во время кодирования, чтобы предотвратить бесконечную рекурсию (которая привела бы к [`OverflowError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OverflowError)). В противном случае такая проверка не производится.

Если *allow\_nan* равен `True` (по умолчанию), то `NaN`, `Infinity` и `-Infinity` будут кодироваться как есть. Это поведение не соответствует спецификации JSON, но согласовано с большинством кодировщиков и декодировщиков на JavaScript. В противном случае кодирование таких чисел с плавающей точкой приведёт к [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError).

Если *sort\_keys* равен `True` (по умолчанию), то вывод словарей будет отсортирован по ключам; это полезно для регрессионных тестов, чтобы обеспечить возможность сравнивать JSON-сериализации на постоянной основе.

Если *indent* – неотрицательное целое число (по умолчанию оно равно `None`), то элементы JSON-массива и члены объекта будут выводиться с форматированием и отступами этого уровня. Уровень отступа 0 будет только вставлять новые строки. `None` – это наиболее компактное представление.

Если указано, *separators* должны быть кортежем вида `(item_separator, key_separator)`. По умолчанию – `(', ', ': ')`. Чтобы получить наиболее компактное представление JSON, укажите `(',', ':')`, чтобы убрать пробелы.

Если указан, *default* – это функция, которая вызывается для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта, пригодную для кодирования в JSON, или возбуждать [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError).

Если *encoding* не равен `None`, то все входные строки будут преобразованы в unicode с использованием этой кодировки перед JSON-кодированием. По умолчанию – UTF-8.

#### `[json.JSONEncoder.default]default(o)`

Реализуйте этот метод в подклассе так, чтобы он возвращал сериализуемый объект для *o* или вызывал базовую реализацию (чтобы возбудить [`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)).

Например, чтобы поддерживать произвольные итераторы, можно реализовать default следующим образом:

```python
def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   return JSONEncoder.default(self, o)
```

#### `[json.JSONEncoder.encode]encode(o)`

Возвращает строковое представление структуры данных Python в формате JSON, *o*. Например:

```python
>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'
```

#### `[json.JSONEncoder.iterencode]iterencode(o)`

Кодирует заданный объект *o* и выдаёт каждое строковое представление по мере готовности. Например:

```python
for chunk in JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)
```