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 — целое число больше или равно 0 или строка, то элементы массива JSON и члены объекта будут красиво отформатированы с указанным уровнем отступа. Уровень отступа 0, отрицательный или "" будет добавлять только переводы строк. None (по умолчанию) выбирает наиболее компактное представление. Использование положительного целого числа для indent добавляет столько пробелов на каждый уровень. Если 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 — необязательная функция, которая будет вызываться с результатом любого декодированного объекта-литерала (словарем 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 (по умолчанию), то управляющие символы внутри строк будут разрешены. Управляющие символы в данном контексте — это те, у которых коды символов находятся в диапазоне от 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
словарь	объект
список, кортеж	массив
строка	строка
целое, вещественное, целые и вещественные перечисления	число
True	true
False	false
None	null

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

Чтобы расширить это, чтобы он распознавал другие объекты, создайте подкласс и реализуйте метод 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-массивов и члены JSON-объектов будут отформатированы с указанным уровнем отступа. Уровень отступа 0, отрицательное число или "" будут вставлять только новые строки. None (по умолчанию) выбирает наиболее компактное представление. Использование положительного целого числа indent вставляет отступы на столько пробелов на каждый уровень. Если indent — это строка (например, "\t"), эта строка используется для отступа каждого уровня.

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

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

Возвращает 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)