`json` — Кодер и декодер JSON¶

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

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

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]
...         # Пусть базовый класс по умолчанию вызывает метод 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, произведенный настройками по умолчанию этого модуля (в частности, разделители значения по умолчанию), является также подмножеством 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 имеет значение true (по умолчанию False), то ключи словарь, которые не относятся к базовому типу (str, int, float, bool, None) будут пропущены вместо того, чтобы поднимать TypeError.

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

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

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

Если allow_nan имеет значение false (по умолчанию True), то это будет ValueError для сериализации вне диапазона float значения (nan, inf, -inf) в строгом соответствии со спецификацией 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 должна быть функцией, вызываемой для объектов, которые в противном случае не могут быть сериализованы. Это должно возвращает encodable версия JSON объекта или поднимать TypeError. Если не определенный, TypeError поднят.

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

Чтобы использовать пользовательский JSONEncoder подкласс (например, тот, который отвергает метод default(), чтобы преобразовать в последовательную форму дополнительные типы), определите его с cls kwarg; в противном случае 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, который будет расшифрован. По умолчанию это эквивалентно float(num_str). Это может быть используемый для использования другого типа данных или парсер для floats JSON (например, decimal.Decimal).

parse_int, если указано, вызывается с строкой каждого JSON int, подлежащего декодированию. По умолчанию это эквивалентно int(num_str). Это может быть используемый, чтобы использовать другой тип данных или парсер для целых чисел JSON (например, float).

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

Изменено в версии 3.1: parse_constant не становится обращенным „null“, „true“, „true“ больше.

Чтобы использовать пользовательскую JSONDecoder подкласс, укажите ее вместе с cls kwarg; в противном случае 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.

Deprecated since version 3.1, will be removed in version 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 spec.

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, который будет расшифрован. По умолчанию это эквивалентно float(num_str). Это может быть используемый для использования другого типа данных или парсер для floats JSON (например, decimal.Decimal).

parse_int, если указано, вызывается с строка каждого JSON int, подлежащего декодированию. По умолчанию это эквивалентно int(num_str). Это может быть используемый, чтобы использовать другой тип данных или парсер для целых чисел JSON (например, float).

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

Если strict имеет значение false (True - значение по умолчанию), то внутри строки будут разрешены управляющие символы. Управляющие символы в этом контекст - это символы с символ коды в диапазоне 0-31, включая '\t' (tab), '\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, int- & float-derived Enums	number
True	true
False	false
None	null

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

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

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

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

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

Если allow_nan имеет значение true (значение по умолчанию), то 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 должна быть функцией, вызываемой для объектов, которые в противном случае не могут быть сериализованы. Это должно возвращает encodable версия JSON объекта или поднимать TypeError. Если не определенный, TypeError поднят.

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

default(o)¶

Осуществите этот метод в подкласс, таким образом, что это возвращает сериализуемый объект для o, или называет основное внедрение (чтобы поднять TypeError).

Например, для поддержки произвольных итераторов можно реализовать такие значения по умолчанию:

def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   # Пусть базовый класс по умолчанию метод поднимает TypeError
   return json.JSONEncoder.default(self, o)

encode(o)¶

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

>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

iterencode(o)¶

Кодировать данный объект, o и yield каждое представление строка как доступное. Например:

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 объектами и Юникод строки и, таким образом, не затрагивает напрямую проблему кодировок символ.

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

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

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

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

>>> # Ни один из этих вызовов не поднимет исключение, но результаты не являются допустимыми JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # То же самое при десериализации
>>> 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, булевым, числом или строковое значение. 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 (LINE SEPARATOR) и U+2029 (PARAGRAPH SEPARATOR) символов в строках, то время как JavaScript (начиная с ECMAScript Edition 5.1) - нет.

`json` — Кодер и декодер JSON¶

Основное использование¶

Кодирующие устройства и декодеры¶

Исключения¶

Соответствие стандартам и совместимость¶

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

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

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

Необъектные, неархивные значения верхнего уровня¶

Ограничения внедрения¶

Интерфейс командной строки¶

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

Содержание

Предыдущий раздел

Следующий раздел

Эта страница

json — Кодер и декодер JSON¶

Основное использование¶

Кодирующие устройства и декодеры¶

Исключения¶

Соответствие стандартам и совместимость¶

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

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

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

Необъектные, неархивные значения верхнего уровня¶

Ограничения внедрения¶

Интерфейс командной строки¶

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

`json` — Кодер и декодер JSON¶