json — кодировщик и декодировщик JSON

Основы использования

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, все символы выводятся как есть, за исключением символов, которые необходимо экранировать: кавычки, обратной косой черты и управляющих символов U+0000–U+001F.
• 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 (вызываемый объект | 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 в строку str в формате JSON, используя эту таблицу преобразования. Аргументы имеют тот же смысл, что и в 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 (вызываемый объект | None) – Если задана, функция вызывается с результатом декодирования каждого литерала объекта JSON (значением dict). Возвращаемое значение этой функции будет использовано вместо dict. Эта возможность позволяет реализовывать пользовательские декодировщики, например для обработки подсказок о классах JSON-RPC. По умолчанию None.
• object_pairs_hook (вызываемый объект | None) – Если задана, функция вызывается с результатом декодирования каждого литерала объекта JSON в виде упорядоченного списка пар. Возвращаемое значение этой функции будет использовано вместо 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: Функция int(), используемая по умолчанию для parse_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 удалён.

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

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
число (вещественное)	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). Её можно использовать, чтобы задействовать для чисел с плавающей точкой JSON другой тип данных или анализатор (например, 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).

Если заданный документ JSON недопустим, будет вызвано исключение JSONDecodeError.

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)

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

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

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

Изменено в версии 3.4: Добавлена поддержка классов перечислений на основе int и float.

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

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

Если ensure_ascii имеет значение true (значение по умолчанию), гарантируется, что все входящие символы, отличные от ASCII, и непечатаемые символы будут экранированы. Если ensure_ascii имеет значение false, все символы выводятся как есть, за исключением символов, которые необходимо экранировать: кавычки, обратной косой черты и управляющих символов U+0000–U+001F.

Если 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)
   # Let the base class default method raise the TypeError
   return super().default(o)

encode(o)

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

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

iterencode(o)

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

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

Исключения

exception json.JSONDecodeError(msg, doc, pos)

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

msg

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

doc

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

pos

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

lineno

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

colno

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

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

Соответствие стандартам и взаимодействие

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

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

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

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

>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan

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

Интерфейс командной строки

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

Модуль json можно запустить как скрипт с помощью python -m json для проверки и форматированного вывода объектов JSON. Подмодуль json.tool реализует этот интерфейс.

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

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