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() подобный файлу), используя эту таблицу преобразований.

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

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

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

Если check_circular равно false (по умолчанию: True), то проверка циклической ссылки для контейнерных типов будет пропущена, и циклическая ссылка приведет к RecursionError (или худшему).

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

Если 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.

Если sort_keys равно true (по умолчанию: False), то выходные данные словарей будут отсортированы по ключам.

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

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

Примечание

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

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 (текстовый файл или бинарный файл, поддерживающий .read(), содержащий документ JSON) в объект Python, используя эту таблицу преобразования.

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

object_pairs_hook – это необязательная функция, которая будет вызываться с результатом любого декодированного объекта литерала с упорядоченным списком пар. Возвращаемое значение 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).

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

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

Изменено в версии 3.1: parse_constant больше не вызывается для «null», «true», «false».

Для использования пользовательского подкласса JSONDecoder, укажите его с помощью параметра cls; в противном случае используется JSONDecoder. Дополнительные ключевые параметры будут переданы в конструктор класса.

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

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

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

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

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

Другие аргументы имеют то же значение, что и в load().

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

Изменено в версии 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
объект	словарь
массив	список
строка	строка
число (целое)	целое число
число (вещественное)	вещественное число
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)

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

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

raw_decode(s)

Декодирует JSON-документ из s (объект str, начинающийся с JSON-документа) и возвращает кортеж из 2 элементов: представление данных 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
словарь	объект
список, кортеж	массив
строка	строка
int, float, целые и вещественные Enum	число
True	true
False	false
None	null

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

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

Если skipkeys имеет значение false (по умолчанию), будет вызвано исключение TypeError при попытке закодировать ключи, которые не являются str, int, float или 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 вставляет отступ на это количество пробелов на каждом уровне. Если indent является строкой (например, "\t"), эта строка используется для отступа каждого уровня.

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

Если указаны, separators должны быть кортежем из 2 элементов. По умолчанию это (', ', ': ') если 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 json.JSONEncoder.default(self, o)

encode(o)

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

>>> 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. Этот раздел описывает уровень соответствия модуля данной спецификации. Для простоты, подклассы 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)