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

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

JSON (JavaScript Object Notation), определённый RFC 7159 (который устарел RFC 4627) и ECMA-404, представляет собой лёгкий формат обмена данными, вдохновлённый синтаксисом литералов объектов JavaScript (хотя он не является строгой подмножеством синтаксиса JavaScript 1 ).

Предупреждение

Будьте осторожны при парсинге данных JSON из ненадежных источников. Злонамеренный JSON-строка может привести к существенному потреблению ресурсов процессора и памяти декодером. Рекомендуется ограничивать размер данных для парсинга.

json предоставляет API, знакомое пользователям модулей стандартной библиотеки marshal и pickle.

Кодирование базовых иерархий объектов Python:

>>> import json
>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
'["foo", {"bar": ["baz", null, 1.0, 2]}]'
>>> print(json.dumps("\"foo\bar"))
"\"foo\bar"
>>> print(json.dumps('\u1234'))
"\u1234"
>>> print(json.dumps('\\'))
"\\"
>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
{"a": 0, "b": 0, "c": 0}
>>> from io import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'

Компактная кодировка:

>>> import json
>>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
'[1,2,3,{"4":5,"6":7}]'

Красивая печать:

>>> import json
>>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))
{
    "4": 5,
    "6": 7
}

Декодирование JSON:

>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
['foo', {'bar': ['baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
'"foo\x08ar'
>>> from io import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
['streaming API']

Специализация декодирования объектов JSON:

>>> import json
>>> def as_complex(dct):
...     if '__complex__' in dct:
...         return complex(dct['real'], dct['imag'])
...     return dct
...
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
...     object_hook=as_complex)
(1+2j)
>>> import decimal
>>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1')

Расширение JSONEncoder:

>>> import json
>>> class ComplexEncoder(json.JSONEncoder):
...     def default(self, obj):
...         if isinstance(obj, complex):
...             return [obj.real, obj.imag]
...         # Let the base class default method raise the TypeError
...         return json.JSONEncoder.default(self, obj)
...
>>> json.dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'
>>> ComplexEncoder().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncoder().iterencode(2 + 1j))
['[2.0', ', 1.0', ']']

Использование json.tool из командной строки для валидации и красивой печати:

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

См. Командная строка для подробной документации.

Примечание

JSON является подмножеством YAML 1.2. JSON, сгенерированный по умолчанию этим модулем (в частности, значение по умолчанию separators), также является подмножеством YAML 1.0 и 1.1. Таким образом, этот модуль также может быть использован как YAML сериализатор.

Примечание

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

До Python 3.7, dict не гарантировалось упорядоченным, поэтому ввод и вывод часто перемешивались, если не был явно указан collections.OrderedDict. Начиная с Python 3.7, стандартный dict стал сохранять порядок, поэтому нет необходимости указывать collections.OrderedDict для генерации и парсинга 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 истинно (по умолчанию: False), то ключи словарей, которые не являются базовыми типами (str, int, float, bool, None) будут пропущены вместо повышения TypeError.

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

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

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

Если allow_nan ложно (по умолчанию: True), то сериализация значений float вне диапазона (nan, inf, -inf) будет вызывать ValueError в строгом соответствии со спецификацией JSON. Если allow_nan истинно, будут использоваться их 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 истинно (по умолчанию: 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.8.14: По умолчанию 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(), за исключением encoding, который игнорируется и устарел с Python 3.1.

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

Устарело начиная с версии 3.1, будет удалено в версии 3.9: ключевой аргумент encoding.

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

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

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 ложно (True по умолчанию), тогда управляющие символы будут разрешены внутри строк. Управляющие символы в данном контексте — это те, у которых коды символов находятся в диапазоне 0–31, включая '\t' (табуляцию), '\n', '\r' и '\0'.

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

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

decode(s)

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

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

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
dict	object
list, tuple	array
str	string
int, float, Enum, производные от int и float	number
True	true
False	false
None	null

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

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

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

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

Если check_circular истинно (по умолчанию), тогда списки, словари и объекты, закодированные пользовательскими методами, будут проверяться на циклические ссылки во время кодирования для предотвращения бесконечной рекурсии (что приведет к OverflowError). В противном случае такая проверка не выполняется.

Если allow_nan истинно (по умолчанию), то NaN, Infinity, и -Infinity будут закодированы как таковые. Это поведение не соответствует спецификации JSON, но согласуется с большинством JavaScript-кодировщиков и декодеров. В противном случае, кодирование таких чисел с плавающей точкой будет вызывать ValueError.

Если sort_keys истинно (по умолчанию: 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 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. В этом разделе подробно описано соответствие модуля данному RFC. Для упрощения, классы-подклассы JSONEncoder и JSONDecoder, а также параметры, не указанные явно, не рассматриваются.

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

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

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

Кодировки символов

RFC требует, чтобы JSON представлялся с помощью UTF-8, UTF-16 или UTF-32, при этом UTF-8 рекомендуется по умолчанию для максимальной межплатформенной совместимости.

В соответствии с разрешённым, но не обязательным, пунктом RFC, сериализатор этого модуля по умолчанию устанавливает ensure_ascii=True, тем самым экранируя вывод, чтобы результирующие строки содержали только символы ASCII.

За исключением параметра ensure_ascii, этот модуль строго определён в терминах преобразования между объектами Python и Unicode strings, и поэтому не рассматривает непосредственно вопрос кодировок символов.

RFC запрещает добавление метки порядка байтов (BOM) в начало JSON-текста, и сериализатор этого модуля не добавляет BOM в свой вывод. RFC разрешает, но не требует, чтобы JSON-десериализаторы игнорировали начальную BOM в своём входе. Этот модуль-десериализатор генерирует ValueError при наличии начальной BOM.

RFC не запрещает явно JSON-строки, которые содержат последовательности байтов, не соответствующие допустимым символам Unicode (например, неспаренные суррогаты UTF-16), но отмечает, что они могут вызвать проблемы с межплатформенной совместимостью. По умолчанию этот модуль принимает и выводит (если они присутствуют в исходной str) кодовые точки для таких последовательностей.

Бесконечные и NaN числовые значения

RFC не допускает представление бесконечных или NaN числовых значений. Несмотря на это, по умолчанию этот модуль принимает и выводит Infinity, -Infinity, и NaN как будто они являются допустимыми числовыми литералами JSON:

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

В сериализаторе параметр allow_nan может быть использован для изменения этого поведения. В десериализаторе параметр parse_constant может быть использован для изменения этого поведения.

Повторяющиеся имена в объекте

RFC указывает, что имена в JSON-объекте должны быть уникальными, но не предписывает, как следует обрабатывать повторяющиеся имена в JSON-объектах. По умолчанию этот модуль не генерирует исключение; вместо этого он игнорирует все, кроме последней пары имя-значение для данного имени:

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

Параметр object_pairs_hook может быть использован для изменения этого поведения.

Значения верхнего уровня, не являющиеся объектами и массивами

Старая версия JSON, определённая устаревшим RFC 4627, требовала, чтобы значение верхнего уровня JSON-текста должно быть либо JSON-объектом, либо массивом (Python dict или list), и не могло быть JSON-null, boolean, числом или строкой. RFC 7159 отменил это ограничение, и этот модуль не реализовывал и никогда не реализовывал это ограничение ни в своём сериализаторе, ни в своём десериализаторе.

Тем не менее, для максимальной совместимости вы можете добровольно придерживаться этого ограничения.

Ограничения реализации

Некоторые реализации JSON-десериализаторов могут устанавливать ограничения:

на размер принимаемых JSON-текстов
на максимальную вложенность JSON-объектов и массивов
на диапазон и точность JSON-чисел
на содержимое и максимальную длину JSON-строк

Этот модуль не накладывает таких ограничений, кроме тех, которые уже существуют для соответствующих типов данных Python или самого интерпретатора Python.

При сериализации в JSON следует учитывать такие ограничения в приложениях, которые могут использовать ваш JSON. В частности, JSON-числа обычно десериализуются в числа двойной точности IEEE 754, и поэтому подвержены ограничениям в диапазоне и точности. Это особенно важно при сериализации значений Python int с очень большой величиной или при сериализации экземпляров «экзотических» числовых типов, таких как decimal.Decimal.

Командная строка

Исходный код: 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)

Изменено в версии 3.5: Выходной поток теперь имеет тот же порядок, что и входной. Используйте опцию --sort-keys для сортировки вывода словарей по ключам в алфавитном порядке.

Параметры командной строки

infile

JSON-файл для проверки или форматирования:

$ python -m json.tool mp_films.json
[
    {
        "title": "And Now for Something Completely Different",
        "year": 1971
    },
    {
        "title": "Monty Python and the Holy Grail",
        "year": 1975
    }
]

Если infile не указан, считывается из sys.stdin.

outfile: Записывает вывод из infile в заданный outfile. В противном случае записывает в sys.stdout.

--sort-keys: Сортирует вывод словарей по ключам в алфавитном порядке.

Введено в версии 3.5.

--json-lines: Разбирает каждую строку ввода как отдельный JSON-объект.

Введено в версии 3.8.

-h, --help: Показать сообщение справки.

Примечания

1: Как отмечается в исправлениях к RFC 7159, JSON допускает символы U+2028 (РАЗДЕЛИТЕЛЬ СТРОК) и U+2029 (РАЗДЕЛИТЕЛЬ АБЗАЦОВ) в строках, в то время как JavaScript (по состоянию на ECMAScript Edition 5.1) — нет.