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-сериализатор.

Примечание

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

Основные примеры использования

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 символы, закодированные в escape-последовательности. Если 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 является строкой (например, "\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.10.7: Значение по умолчанию 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.

END_OF_DOCUMENT_MARKER

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 ложно (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
словарь	объект
список, кортеж	массив
строка	строка
целое, число с плавающей точкой, целые и числа с плавающей точкой, производные от перечислений	число
True	true
False	false
None	null

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

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

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

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

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

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

Если sort_keys истинно (по умолчанию: False), то выход словарей будет отсортирован по ключу; это полезно для регрессионных тестов, чтобы убедиться, что JSON-сериализации можно сравнивать ежедневно.

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

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

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

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

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

--indent, --tab, --no-indent, --compact: Взаимоисключающие опции для управления отступами.

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

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

Примечания

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