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) – Если задана, функция вызывается с результатом декодирования каждого литерала объекта (значением типа dict). Возвращаемое этой функцией значение используется вместо dict. Эту возможность можно использовать для создания пользовательских декодировщиков, например для сопоставления классов в JSON-RPC. Значение по умолчанию — None.
• object_pairs_hook (вызываемый объект | 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 удалён.

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

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)

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

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

Python	JSON
dict	object
list, tuple	array
str	string
int, float, int- & float-derived Enums	number
True	true
False	false
None	null

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

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

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

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