json – кодировщик и декодировщик JSON¶json – JSON encoder and decoder

Основное использование¶Basic Usage

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)¶

Сериализует obj в поток в формате JSON в fp (.write()-поддерживающий файлоподобный объект), используя таблицу преобразования Python в JSON.

Примечание

В отличие от pickle и marshal, JSON не является фреймовым протоколом, поэтому попытка сериализовать несколько объектов с повторными вызовами dump() с использованием одного и того же fp приведёт к созданию недопустимого JSON-файла.

Параметры:

• obj (object) – Сериализуемый объект Python.

• fp (файлоподобный объект) – Файлоподобный объект, в который будет сериализован obj. Модуль json всегда создаёт объекты str, а не bytes, поэтому fp.write() должен поддерживать ввод str.

• skipkeys (bool) – Если True, ключи, не являющиеся базовым типом (str, int, float, bool, None), будут пропущены вместо возбуждения TypeError. По умолчанию False.

• ensure_ascii (bool) – Если True (по умолчанию), выходные данные гарантированно будут содержать все не-ASCII символы экранированными. Если False, эти символы будут выводиться как есть.

• check_circular (bool) – Если False, проверка циклических ссылок для контейнерных типов пропускается, и циклическая ссылка приведёт к RecursionError (или хуже). По умолчанию True.

• allow_nan (bool) – Если False, сериализация значений float вне допустимого диапазона (nan, inf, -inf) вызовет ValueError в строгом соответствии со спецификацией JSON. Если True (по умолчанию), используются их эквиваленты в JavaScript (NaN, Infinity, -Infinity).

• cls (подкласс JSONEncoder) – Если задан, пользовательский кодировщик JSON с переопределённым методом default(), для сериализации в пользовательские типы данных. Если None (по умолчанию), используется JSONEncoder.

• indent (int | str | None) – Если положительное целое число или строка, элементы массива JSON и члены объекта будут отформатированы с отступом этого уровня. Положительное целое число задаёт количество пробелов на уровень; строка (например, "\t") используется для отступа каждого уровня. Если ноль, отрицательное или "" (пустая строка), вставляются только переводы строк. Если None (по умолчанию), используется наиболее компактное представление.

• separators (tuple | None) – Кортеж из двух элементов: (item_separator, key_separator). Если None (по умолчанию), separators по умолчанию равен (', ', ': '), если indent равен None, и (',', ': ') в противном случае. Для максимально компактного JSON укажите (',', ':'), чтобы убрать пробелы.

• default (callable | None) – Функция, вызываемая для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта, кодируемую в JSON, или возбуждать TypeError. Если None (по умолчанию), возбуждается TypeError.

• sort_keys (bool) – если True, словари будут выводиться отсортированными по ключам. По умолчанию False.

Изменено в версии 3.2: Разрешено использование строк для indent в дополнение к целым числам.

Изменено в версии 3.4: Используйте (',', ': ') по умолчанию, если indent не равно None.

Изменено в версии 3.6: Все необязательные параметры теперь являются только ключевыми.

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)¶

Сериализует obj в JSON-форматированную str, используя эту таблицу преобразования. Аргументы имеют тот же смысл, что и в dump().

Примечание

Ключи в парах ключ-значение JSON всегда имеют тип str. При преобразовании словаря в JSON все его ключи приводятся к строкам. В результате, если словарь преобразовать в JSON, а затем обратно в словарь, полученный словарь может не совпадать с исходным. То есть loads(dumps(x)) != x, если x имеет нестроковые ключи.

json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)¶

Десериализует fp в объект Python, используя таблицу преобразования JSON в Python.

Параметры:

• fp (файлоподобный объект) – поддерживающий .read() текстовый файл или двоичный файл, содержащий JSON-документ для десериализации.

• cls (подкласс JSONDecoder) – если задан, пользовательский JSON-декодер. Дополнительные именованные аргументы для load() будут переданы конструктору cls. Если None (по умолчанию), используется JSONDecoder.

• object_hook (callable | None) – Если задано, функция, которая вызывается с результатом декодирования любого объектного литерала (dict). Возвращаемое значение этой функции будет использовано вместо dict. Эту возможность можно использовать для реализации пользовательских декодеров, например, для подсказки класса JSON-RPC. По умолчанию None.

• object_pairs_hook (callable | None) – Если задано, функция, которая вызывается с результатом декодирования любого объектного литерала в виде упорядоченного списка пар. Возвращаемое значение этой функции будет использовано вместо dict. Эту возможность можно использовать для реализации пользовательских декодеров. Если также задан object_hook, приоритет имеет object_pairs_hook. По умолчанию None.

• parse_float (вызываемый объект | None) – если задан, функция, вызываемая со строкой каждого JSON-числа с плавающей точкой для декодирования. Если None (по умолчанию), это эквивалентно float(num_str). Это может использоваться для парсинга JSON-чисел с плавающей точкой в пользовательские типы данных, например, decimal.Decimal.

• parse_int (вызываемый объект | None) – если задан, функция, вызываемая со строкой каждого JSON-целого для декодирования. Если None (по умолчанию), это эквивалентно int(num_str). Это может использоваться для парсинга JSON-целых чисел в пользовательские типы данных, например, float.

• parse_constant (вызываемый объект | None) – если задан, функция, вызываемая с одной из следующих строк: '-Infinity', 'Infinity' или 'NaN'. Это может использоваться для возбуждения исключения при обнаружении некорректных JSON-чисел. По умолчанию None.

Возбуждает:

• JSONDecodeError – когда десериализуемые данные не являются корректным JSON-документом.

• UnicodeDecodeError – когда десериализуемые данные не содержат данные в кодировке UTF-8, UTF-16 или UTF-32.

Изменено в версии 3.1:

• Добавлен необязательный параметр object_pairs_hook.

• parse_constant больше не вызывается для 'null', 'true', 'false'.

Изменено в версии 3.6:

• Все необязательные параметры теперь являются только ключевыми.

• fp теперь может быть двоичным файлом. Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.

Изменено в версии 3.11: Значение parse_int по умолчанию в int() теперь ограничивает максимальную длину строки целого числа через ограничение длины преобразования строки целого числа интерпретатора, чтобы помочь избежать атак типа «отказ в обслуживании».

json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)¶

Идентично load(), но вместо файлоподобного объекта десериализует s (экземпляр str, bytes или bytearray, содержащий JSON-документ) в объект Python, используя эту таблицу преобразования.

Изменено в версии 3.6: s теперь может быть типа bytes или bytearray. Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.

Изменено в версии 3.9: Именованный аргумент encoding удален.

Кодировщики и декодеры¶Encoders and Decoders

class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)¶

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

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

JSON	Python
объект	dict
массив	list
строка	str
число (int)	int
число (вещественное)	float
true	True
false	False
null	None

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

object_hook – необязательная функция, которая вызывается с результатом декодирования каждого JSON-объекта; её возвращаемое значение используется вместо переданного dict. Это позволяет задавать собственную десериализацию (например, для поддержки подсказок классов JSON-RPC).

object_pairs_hook – необязательная функция, которая вызывается с результатом декодирования каждого JSON-объекта в виде упорядоченного списка пар. Возвращаемое значение object_pairs_hook будет использоваться вместо dict. Этот механизм позволяет реализовывать собственные декодеры. Если также определён object_hook, приоритет имеет object_pairs_hook.

Изменено в версии 3.1: Добавлена поддержка object_pairs_hook.

parse_float – необязательная функция, которая вызывается со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию она эквивалентна float(num_str). Это позволяет использовать другой тип данных или синтаксический анализатор для чисел с плавающей точкой (например, decimal.Decimal).

parse_int – необязательная функция, которая вызывается со строкой каждого декодируемого JSON-целого числа. По умолчанию она эквивалентна int(num_str). Это позволяет использовать другой тип данных или синтаксический анализатор для целых чисел JSON (например, float).

parse_constant – необязательная функция, которая вызывается с одной из следующих строк: '-Infinity', 'Infinity', 'NaN'. Это позволяет вызывать исключение при обнаружении недопустимых чисел JSON.

Если strict равно false (по умолчанию True), то управляющие символы допускаются внутри строк. Под управляющими символами здесь понимаются символы с кодами в диапазоне 0–31, включая '\t' (табуляция), '\n', '\r' и '\0'.

Если десериализуемые данные не являются корректным JSON-документом, будет вызвано JSONDecodeError.

Изменено в версии 3.6: Все параметры теперь только ключевые.

decode(s)¶

Возвращает представление s в Python (экземпляр str, содержащий JSON-документ).

JSONDecodeError будет вызвано, если переданный JSON-документ не является корректным.

raw_decode(s)¶

Декодирует JSON-документ из s (str, начинающийся с JSON-документа) и возвращает кортеж из двух элементов: представления в Python и индекса в s, на котором документ заканчивается.

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

class json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶

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

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

Python	JSON
dict	объект
list, tuple	массив
str	строка
int, float, перечисления, производные от int и float	число
True	true
False	false
None	null

Изменено в версии 3.4: Добавлена поддержка классов Enum, производных от int и float.

Чтобы расширить функциональность на другие объекты, создайте подкласс и реализуйте метод default() с другим методом, который возвращает сериализуемый объект для o, если это возможно; в противном случае следует вызвать реализацию суперкласса (для возбуждения TypeError).

Если skipkeys имеет значение false (по умолчанию), возбуждается TypeError при попытке кодировать ключи, не являющиеся str, int, float, bool или None. Если skipkeys равно true, такие элементы просто пропускаются.

Если ensure_ascii равен true (по умолчанию), то выходные данные гарантированно содержат все входящие не-ASCII-символы экранированными. Если ensure_ascii равен false, эти символы выводятся как есть.

Если check_circular равно true (по умолчанию), то списки, словари и пользовательские объекты проверяются на циклические ссылки во время кодирования для предотвращения бесконечной рекурсии (которая вызвала бы RecursionError). В противном случае такая проверка не выполняется.

Если allow_nan равно true (по умолчанию), то значения NaN, Infinity и -Infinity кодируются как есть. Такое поведение не соответствует спецификации JSON, но согласуется с большинством кодировщиков и декодировщиков на JavaScript. В противном случае при кодировании таких чисел с плавающей запятой возбуждается ValueError.

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

Если indent – неотрицательное целое число или строка, то элементы JSON-массивов и члены объектов выводятся с отступами, соответствующими указанному уровню. Уровень отступа 0, отрицательное значение или "" вставляет только переводы строк. None (по умолчанию) выбирает наиболее компактное представление. Положительное целое значение отступа задаёт количество пробелов на уровень. Если indent является строкой (например, "\t"), эта строка используется для отступа каждого уровня.

Изменено в версии 3.2: Разрешено использование строк для indent в дополнение к целым числам.

Если указан, то separators должен быть кортежем (item_separator, key_separator). По умолчанию используется (', ', ': '), если indent равно None, и (',', ': ') в противном случае. Для получения наиболее компактного JSON-представления укажите (',', ':'), чтобы убрать пробелы.

Изменено в версии 3.4: Используйте (',', ': ') по умолчанию, если indent не равно None.

Если указан, default должен быть функцией, которая вызывается для объектов, которые не могут быть сериализованы иным способом. Она должна возвращать версию объекта, пригодную для JSON-кодирования, или возбуждать TypeError. Если не указано, возбуждается TypeError.

Изменено в версии 3.6: Все параметры теперь только ключевые.

default(o)¶

В подклассе этот метод должен возвращать сериализуемый объект для o или вызывать базовую реализацию (для возбуждения TypeError).

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

def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   # Пусть метод базового класса по умолчанию возбуждает TypeError
   return super().default(o)

encode(o)¶

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

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

iterencode(o)¶

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

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

Исключения¶Exceptions

exception json.JSONDecodeError(msg, doc, pos)¶

Подкласс ValueError со следующими дополнительными атрибутами:

msg¶

Неформатированное сообщение об ошибке.

doc¶

Разбираемый JSON-документ.

pos¶

Начальный индекс doc, в котором произошла ошибка разбора.

lineno¶

Строка, соответствующая pos.

colno¶

Столбец, соответствующий pos.

Добавлено в версии 3.5.

Соответствие стандартам и интероперабельность¶Standard Compliance and Interoperability

Формат JSON определяется RFC 7159 и ECMA-404. В этом разделе подробно описывается степень соответствия модуля RFC. Для простоты JSONEncoder и JSONDecoder подклассы, а также параметры, не указанные явно, не рассматриваются.

Этот модуль не полностью соответствует RFC, реализуя некоторые расширения, которые являются допустимым JavaScript, но недопустимым JSON. В частности:

• Бесконечные и NaN числовые значения принимаются и выводятся;

• Повторяющиеся имена в объекте принимаются, и используется только значение последней пары.

Поскольку RFC разрешает совместимым с RFC анализаторам принимать входные тексты, которые не соответствуют RFC, десериализатор этого модуля технически соответствует RFC при настройках по умолчанию.

>>> # Ни один из этих вызовов не возбуждает исключение, но результаты не являются корректным JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # То же самое при десериализации
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan

>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json)
{'x': 3}

Интерфейс командной строки¶Command Line Interface

Исходный код: Lib/json/tool.py

Модуль json.tool предоставляет простой интерфейс командной строки для проверки и форматированного вывода JSON-объектов.

Если необязательные аргументы infile и outfile не указаны, будут использоваться sys.stdin и sys.stdout соответственно:

$ echo '{"json": "obj"}' | python -m json.tool
{
    "json": "obj"
}
$ echo '{1.2:3.4}' | python -m json.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)