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 super().default(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.

Примечание

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

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

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()-поддерживающий file-like object), используя этот conversion table.

Если значение skipkeys равно true (по умолчанию: False), , то клавиши dict, которые не относятся к типу basic (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),, то это будет ValueError для сериализации значений, выходящих за пределы диапазона float (nan, inf, -inf) в строгом соответствии со спецификацией JSON. Если значение allow_nan равно true, то будут использоваться их эквиваленты в JavaScript (NaN, Infinity, -Infinity).

Если indent является неотрицательным целым числом или строкой, то элементы массива JSON и элементы объекта будут напечатаны с таким уровнем отступа. Уровень отступа, равный 0, отрицательный или "", приведет только к вставке новых строк. None (по умолчанию) выбирает наиболее компактное представление. При использовании целочисленного положительного отступа для каждого уровня используется определенное количество пробелов. Если indent - это строка (например, "\t"), то эта строка используется для отступа на каждом уровне.

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

Если указано, то разделители должны быть (item_separator, key_separator). По умолчанию используется (', ', ': '), если отступ равен None и (',', ': ') в противном случае. Чтобы получить наиболее компактное представление в формате JSON, вам следует указать (',', ':'), чтобы исключить пробелы.

Изменено в версии 3.4: Используйте (',', ': ') по умолчанию, если отступ не равен None.

Если указано, то по умолчанию должна быть функция, которая вызывается для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта в формате JSON или выдавать значение TypeError. Если не указано, то выводится значение TypeError.

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

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

Изменено в версии 3.6: Все необязательные параметры теперь равны keyword-only.

Примечание

В отличие от 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, используя этот conversion table. Аргументы имеют то же значение, что и в 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(), поддерживающий text file или binary file, содержащий документ в формате JSON) в объект Python, используя этот conversion table.

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

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

Изменено в версии 3.1: Добавлена поддержка object_pairs_hook.

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

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

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

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

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

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

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

Изменено в версии 3.6: Все необязательные параметры теперь равны keyword-only.

Изменено в версии 3.6: fp теперь может быть binary file. Входная кодировка должна быть 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, используя этот conversion table.

Остальные аргументы имеют то же значение, что и в 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)

Декодер SimpleJSON.

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

JSON-файл

Питон

объект

диктовать

массив

список

строка

ул

число (int)

инт

число (реальное)

плыть

истинный

Правда

ложный

Ложный

нулевой

Никто

Он также воспринимает NaN, Infinity, и -Infinity как соответствующие им значения float, что выходит за рамки спецификации JSON.

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

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

Изменено в версии 3.1: Добавлена поддержка object_pairs_hook.

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

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

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

Если значение strict равно false (True по умолчанию), то управляющие символы будут разрешены внутри строк. Управляющими символами в данном контексте являются символы с кодами символов в диапазоне от 0 до 31, включая '\t' (табуляция), '\n', '\r' и '\0'.

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

Изменено в версии 3.6: Теперь все параметры равны keyword-only.

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.

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

Питон

JSON-файл

диктовать

объект

список, кортеж

массив

ул

строка

перечисления int, float, int- и производные от float

номер

Правда

истинный

Ложный

ложный

Никто

нулевой

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

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

Если указано, то разделители должны быть (item_separator, key_separator). По умолчанию используется (', ', ': '), если отступ равен None и (',', ': ') в противном случае. Чтобы получить наиболее компактное представление в формате JSON, вам следует указать (',', ':'), чтобы исключить пробелы.

Изменено в версии 3.4: Используйте (',', ': ') по умолчанию, если отступ не равен None.

Если указано, то по умолчанию должна быть функция, которая вызывается для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта в формате JSON или выдавать значение TypeError. Если не указано, то выводится значение TypeError.

Изменено в версии 3.6: Теперь все параметры равны keyword-only.

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 в формате JSON, 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, и сериализатор этого модуля не добавляет «бомбу» к своим выводам. RFC разрешает, но не требует, чтобы десериализаторы JSON игнорировали исходную спецификацию при вводе данных. Десериализатор этого модуля генерирует ValueError при наличии исходной спецификации.

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 нулевое, логическое, числовое или строковое значение. 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.

--no-ensure-ascii

Отключите экранирование символов, отличных от ascii, см. json.dumps() для получения дополнительной информации.

Добавлено в версии 3.9.

--json-lines

Проанализируйте каждую строку ввода как отдельный объект JSON.

Добавлено в версии 3.8.

--indent, --tab, --no-indent, --compact

Взаимоисключающие опции для управления пробелами.

Добавлено в версии 3.9.

-h, --help

Отобразите справочное сообщение.

Сноски

email.iterators: Итераторы
mailbox — Манипулирование почтовыми ящиками в различных форматах
Вернуться на верх