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({'6': 7, '4': 5}, sort_keys=True, indent=4))
{
"4": 5,
"6": 7
}
Специализация кодирования объектов JSON:
>>> import json
>>> def custom_json(obj):
... if isinstance(obj, complex):
... return {'__complex__': True, 'real': obj.real, 'imag': obj.imag}
... raise TypeError(f'Cannot serialize object of {type(obj)}')
...
>>> json.dumps(1 + 2j, default=custom_json)
'{"__complex__": true, "real": 1.0, "imag": 2.0}'
Декодирование 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()подобный файлу) используя эту таблицу преобразования.Если skipkeys имеет значение True (по умолчанию:
False), ключи словарей, не являющиеся основными типами (str,int,float,bool,None) будут пропущены вместо повышенияTypeError.Модуль
jsonвсегда генерирует объектыstr, а неbytes. Поэтомуfp.write()должен поддерживать входные данные типаstr.Если ensure_ascii имеет значение True (по умолчанию), все входящие не-ASCII символы гарантированно будут экранированы в выводе. Если ensure_ascii имеет значение False, эти символы будут выведены как есть.
Если check_circular имеет значение False (по умолчанию:
True), то проверка циклических ссылок для контейнерных типов будет пропущена, и циклическая ссылка приведет кRecursionError(или худшему).Если allow_nan имеет значение False (по умолчанию:
True), то сериализация значенийfloatза пределами диапазона (nan,inf,-inf) приведет кValueErrorв строгом соответствии со спецификацией JSON. Если allow_nan имеет значение True, будут использоваться их JavaScript-эквиваленты (NaN,Infinity,-Infinity) .Если indent является положительным целым числом или строкой, элементы массива JSON и члены объекта будут отформатированы с указанным уровнем отступа. Уровень отступа 0, отрицательный или
""будет вставлять только новые строки.None(по умолчанию) выбирает наиболее компактное представление. Использование положительного целого числа в качестве indent добавляет столько пробелов на каждый уровень. Если indent — строка (например,"\t"), эта строка используется для отступа каждого уровня.Изменено в версии 3.2: Разрешены строки для indent помимо целых чисел.
Если указано, separators должно быть
(item_separator, key_separator)кортежем. По умолчанию это(', ', ': ')если indentNoneи(',', ': ')в противном случае. Для получения наиболее компактного представления JSON вы должны указать(',', ':')для удаления пробелов.Изменено в версии 3.4: Используется
(',', ': ')в качестве значения по умолчанию, если indent неNone.Если указано, default должна быть функция, которая вызывается для объектов, которые не могут быть сериализованы другими способами. Она должна возвращать JSON-кодируемую версию объекта или поднимать
TypeError. Если не указано, то поднимаетсяTypeError.Если sort_keys имеет значение True (по умолчанию:
False), то вывод словарей будет отсортирован по ключам.Для использования пользовательского подкласса
JSONEncoder(например, подкласса, переопределяющего методdefault()для сериализации дополнительных типов), укажите его с помощью параметра cls; в противном случае используетсяJSONEncoder.Изменено в версии 3.6: Все необязательные параметры теперь являются параметрами только с ключевыми словами.
-
json.dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw) -
Сериализует obj в строку формата JSON
strс помощью этой таблицы преобразования. Аргументы имеют то же значение, что и вdump().Примечание
Ключи в парах ключ/значение JSON всегда имеют тип
str. При преобразовании словаря в JSON все ключи словаря неявно преобразуются в строки. В результате, если словарь преобразуется в JSON, а затем обратно в словарь, полученный словарь может не совпадать с исходным. Этоloads(dumps(x)) != xесли у x есть ключи, не являющиеся строками.
-
json.load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw) -
Десериализует fp (файл, поддерживающий
.read()текстовый файл или бинарный файл содержащий JSON-документ) в объект Python с помощью этой таблицы преобразования.object_hook — необязательная функция, которая будет вызвана с результатом декодирования любого объекта литерала (словарь
dict). Значение возвращаемое object_hook будет использовано вместоdict. Эта возможность может быть использована для реализации пользовательских декодеров (например, JSON-RPC подсказки типов).object_pairs_hook — необязательная функция, которая будет вызвана с результатом декодирования любого объекта литерала с упорядоченным списком пар. Значение возвращаемое object_pairs_hook будет использовано вместо
dict. Эта возможность может быть использована для реализации пользовательских декодеров. Если object_hook также определен, то object_pairs_hook имеет приоритет.Изменено в версии 3.1: Добавлена поддержка object_pairs_hook.
parse_float — необязательная функция, которая будет вызвана со строкой каждого значения с плавающей точкой JSON для декодирования. По умолчанию, это эквивалентно
float(num_str). Это может быть использовано для использования другого типа данных или парсера для чисел с плавающей точкой JSON (например,decimal.Decimal).parse_int — необязательная функция, которая будет вызвана со строкой каждого целого числа JSON для декодирования. По умолчанию, это эквивалентно
int(num_str). Это может быть использовано для использования другого типа данных или парсера для целых чисел JSON (например,float).Изменено в версии 3.11: Значение по умолчанию parse_int
int()теперь ограничивает максимальную длину строки целого числа через ограничение длины преобразования строки целого числа интерпретатора, чтобы избежать атак с отказом от обслуживания.parse_constant — необязательная функция, которая будет вызвана с одной из следующих строк:
'-Infinity','Infinity','NaN'. Это можно использовать для поднятия исключения, если встречены некорректные числовые значения JSON.Изменено в версии 3.1: parse_constant больше не вызывается для «null», «true», «false».
Для использования пользовательского подкласса
JSONDecoder, укажите его с помощью параметраcls; в противном случае используетсяJSONDecoder. Дополнительные ключевые параметры будут переданы в конструктор класса.Если данные, которые десериализуются, не являются корректным JSON-документом, будет поднято исключение
JSONDecodeError.Изменено в версии 3.6: Все необязательные параметры теперь являются параметрами только с ключевыми словами.
Изменено в версии 3.6: fp теперь может быть бинарным файлом. Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.
-
json.loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw) -
Десериализовать s (объект типа
str,bytesилиbytearray, содержащий JSON-документ) в объект Python, используя эту таблицу преобразования.Другие аргументы имеют то же значение, что и в
load().Если данные, которые десериализуются, не являются допустимым JSON-документом, будет поднято исключение
JSONDecodeError.Изменено в версии 3.6: s теперь может быть типа
bytesилиbytearray. Кодировка входных данных должна быть UTF-8, UTF-16 или UTF-32.Изменено в версии 3.9: Ключевой аргумент encoding был удален.
Кодировщики и декодировщики
-
class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None) -
Простой декодер JSON.
По умолчанию выполняет следующие преобразования при декодировании:
JSON
Python
объект
словарь
массив
список
строка
строка
число (целое)
целое число
число (вещественное)
число с плавающей точкой
true
True
false
False
null
None
Он также понимает
NaN,Infinity, и-Infinityкак соответствующие имfloatзначения, что выходит за рамки спецификации JSON.object_hook — это необязательная функция, которая будет вызываться с результатом декодирования каждого JSON-объекта, а её возвращаемое значение будет использоваться вместо заданного
dict. Это может быть использовано для предоставления пользовательских десериализаций (например, для поддержки JSON-RPC с указанием типов классов).object_pairs_hook — это необязательная функция, которая будет вызываться с результатом декодирования каждого JSON-объекта со списком пар. Возвращаемое значение object_pairs_hook будет использовано вместо
dict. Эта функция может использоваться для реализации пользовательских декодеров. Если также определена object_hook, object_pairs_hook имеет приоритет.Изменено в версии 3.1: Добавлена поддержка object_pairs_hook.
parse_float — это необязательная функция, которая будет вызываться со строкой каждого JSON-числа с плавающей точкой, подлежащего декодированию. По умолчанию это эквивалентно
float(num_str). Это может быть использовано для использования другого типа данных или парсера для JSON-чисел с плавающей точкой (например,decimal.Decimal).parse_int — это необязательная функция, которая будет вызываться со строкой каждого JSON-целого числа, подлежащего декодированию. По умолчанию это эквивалентно
int(num_str). Это может быть использовано для использования другого типа данных или парсера для JSON-целых чисел (например,float).parse_constant — это необязательная функция, которая будет вызываться со строками:
'-Infinity','Infinity','NaN'. Это можно использовать для создания исключения, если встречаются некорректные JSON-числа.Если strict ложно (
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-документа) и возвращает кортеж из двух элементов: представление данных 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
словарь
объект
список, кортеж
массив
строка
строка
целое, вещественное, целые и вещественные Enum
число
True
true
False
false
None
null
Изменено в версии 3.4: Добавлена поддержка целых и вещественных классов Enum.
Для расширения поддержки других объектов, создайте подкласс и реализуйте метод
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 и члены объектов будут отформатированы с этим уровнем отступа. Уровень отступа 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 super().default(o)
-
encode(o) -
Возвращает JSON-строковое представление структуры данных Python, o. Например:
>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]}) '{"foo": ["bar", "baz"]}'
-
iterencode(o) -
Кодирует указанный объект, o, и генерирует каждое строковое представление по мере его доступности. Например:
for chunk in json.JSONEncoder().iterencode(bigobject): mysocket.write(chunk)
-
Исключения
-
exception json.JSONDecodeError(msg, doc, pos) -
Подкласс
ValueErrorсо следующими дополнительными атрибутами:-
msg -
Неформализованное сообщение об ошибке.
-
doc -
Парсируемый JSON-документ.
-
pos -
Начальный индекс в doc, где произошёл сбой парсинга.
-
lineno -
Строка, соответствующая pos.
-
colno -
Столбец, соответствующий pos.
Добавлен в версии 3.5.
-
Соответствие стандартам и взаимозаменяемость
Формат JSON определён в RFC 7159 и ECMA-404. Этот раздел описывает уровень соответствия данного модуля 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, number или string. 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 -
Показать сообщение справки.
Примечания
© 2001–2024 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.13/library/json.html