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, эти символы будут выведены без изменений.
• 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: Теперь значение 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 удалён.

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

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

Простой декодировщик JSON.

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

JSON	Python
object	dict
array	list
string	str
number (int)	int
number (real)	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)

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

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

Python	JSON
dict	object
list, tuple	array
str	string
int, float, перечисления на основе int и float	number
True	true
False	false
None	null

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

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

Если skipkeys имеет значение false (значение по умолчанию), при попытке кодирования ключей, тип которых не является str, int, float, bool или None, будет вызвано исключение TypeError. Если 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)
   # 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.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)