`json.md`

292 строк · 24.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/json.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 18.2. `json` – кодировщик и декодировщик JSON89JSON (JavaScript Object Notation) \<[http://json.org](https://python-all.ru/3.1/library/json.html)\> – это подмножество синтаксиса JavaScript (ECMA-262, 3-е издание), используемое в качестве легковесного формата обмена данными.1011`json` предоставляет API, знакомый пользователям модулей стандартной библиотеки [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal) и [`pickle`](https://python-all.ru/3.1/library/pickle.html#module-pickle).1213Кодирование иерархий базовых объектов Python:1415```python16>>> import json17>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])18'["foo", {"bar": ["baz", null, 1.0, 2]}]'19>>> print(json.dumps("\"foo\bar"))20"\"foo\bar"21>>> print(json.dumps('\u1234'))22"\u1234"23>>> print(json.dumps('\\'))24"\\"25>>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))26{"a": 0, "b": 0, "c": 0}27>>> from io import StringIO28>>> io = StringIO()29>>> json.dump(['streaming API'], io)30>>> io.getvalue()31'["streaming API"]'32```3334Компактное кодирование:3536```python37>>> import json38>>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',', ':'))39'[1,2,3,{"4":5,"6":7}]'40```4142Красивое форматирование:4344```python45>>> import json46>>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))47{48    "4": 5,49    "6": 750}51```5253Декодирование JSON:5455```python56>>> import json57>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')58['foo', {'bar': ['baz', None, 1.0, 2]}]59>>> json.loads('"\\"foo\\bar"')60'"foo\x08ar'61>>> from io import StringIO62>>> io = StringIO('["streaming API"]')63>>> json.load(io)64['streaming API']65```6667Специализированное декодирование объектов JSON:6869```python70>>> import json71>>> def as_complex(dct):72...     if '__complex__' in dct:73...         return complex(dct['real'], dct['imag'])74...     return dct75...76>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',77...     object_hook=as_complex)78(1+2j)79>>> import decimal80>>> json.loads('1.1', parse_float=decimal.Decimal)81Decimal('1.1')82```8384Расширение [`JSONEncoder`](https://python-all.ru/3.1/library/json.html#json.JSONEncoder):8586```python87>>> import json88>>> class ComplexEncoder(json.JSONEncoder):89...     def default(self, obj):90...         if isinstance(obj, complex):91...             return [obj.real, obj.imag]92...         return json.JSONEncoder.default(self, obj)93...94>>> json.dumps(2 + 1j, cls=ComplexEncoder)95'[2.0, 1.0]'96>>> ComplexEncoder().encode(2 + 1j)97'[2.0, 1.0]'98>>> list(ComplexEncoder().iterencode(2 + 1j))99['[2.0', ', 1.0', ']']100```101102Использование json.tool из командной оболочки для проверки и форматирования:103104```text105$ echo '{"json":"obj"}' | python -mjson.tool106{107    "json": "obj"108}109$ echo '{ 1.2:3.4}' | python -mjson.tool110Expecting property name: line 1 column 2 (char 2)111```112113> **Примечание**114>115> JSON, создаваемый стандартными настройками этого модуля, является подмножеством YAML, поэтому его также можно использовать в качестве сериализатора для YAML.116117## 18.2.1. Основное использование118119#### `json.dump(obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, **kw**kw)`120121Сериализует *obj* в поток в формате JSON и записывает его в *fp* (поддерживающий `.write()` объект, похожий на файл).122123Если *skipkeys* равно `True` (по умолчанию: `False`), то ключи словаря, не являющиеся базовыми типами ([`str`](https://python-all.ru/3.1/library/functions.html#str), [`int`](https://python-all.ru/3.1/library/functions.html#int), [`float`](https://python-all.ru/3.1/library/functions.html#float), [`bool`](https://python-all.ru/3.1/library/functions.html#bool), `None`), будут пропущены вместо возбуждения исключения [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError).124125Модуль `json` всегда создаёт объекты [`str`](https://python-all.ru/3.1/library/functions.html#str), а не [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes). Поэтому `fp.write()` должен поддерживать ввод [`str`](https://python-all.ru/3.1/library/functions.html#str) .126127Если *check\_circular* равно `False` (по умолчанию: `True`), то проверка циклических ссылок для контейнерных типов будет пропущена, и циклическая ссылка приведет к [`OverflowError`](https://python-all.ru/3.1/library/exceptions.html#OverflowError) (или хуже).128129Если *allow\_nan* равно `False` (по умолчанию: `True`), то сериализация значений [`float`](https://python-all.ru/3.1/library/functions.html#float) вне допустимого диапазона (`nan`, `inf`, `-inf`) будет вызывать [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError) в строгом соответствии со спецификацией JSON, вместо использования JavaScript-эквивалентов (`NaN`, `Infinity`, `-Infinity`).130131Если *indent* – неотрицательное целое число, то элементы массива JSON и члены объекта будут выводиться с отступами заданного уровня. Уровень отступа 0 или отрицательное значение будет вставлять только переносы строк. `None` (по умолчанию) выбирает наиболее компактное представление.132133Если *separators* является кортежем `(item_separator, dict_separator)`, то он будет использоваться вместо разделителей по умолчанию `(', ', ': ')`. `(',', ':')` – это наиболее компактное представление JSON.134135*default(obj)* – это функция, которая должна возвращать сериализуемую версию *obj* или возбуждать [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError). По умолчанию просто возбуждается [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError).136137Чтобы использовать пользовательский подкласс [`JSONEncoder`](https://python-all.ru/3.1/library/json.html#json.JSONEncoder) (например, переопределяющий метод `default()` для сериализации дополнительных типов), укажите его в аргументе *cls*; в противном случае используется [`JSONEncoder`](https://python-all.ru/3.1/library/json.html#json.JSONEncoder).138139#### `json.dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, **kw)`140141Сериализует *obj* в строку [`str`](https://python-all.ru/3.1/library/functions.html#str) в формате JSON. Аргументы имеют тот же смысл, что и в [`dump()`](https://python-all.ru/3.1/library/json.html#json.dump).142143> **Примечание**144>145> В отличие от [`pickle`](https://python-all.ru/3.1/library/pickle.html#module-pickle) и [`marshal`](https://python-all.ru/3.1/library/marshal.html#module-marshal), JSON не является протоколом с обрамлением, поэтому попытка сериализовать несколько объектов с помощью повторных вызовов [`dump()`](https://python-all.ru/3.1/library/json.html#json.dump) с одним и тем же *fp* приведет к созданию недопустимого JSON-файла.146147#### `json.load(fp, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)`148149Десериализует *fp* (объект, похожий на файл, поддерживающий `.read()` и содержащий JSON-документ) в объект Python.150151*object\_hook* – необязательная функция, которая будет вызвана с результатом декодирования любого литерала объекта (то есть [`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict)). Возвращаемое значение *object\_hook* будет использовано вместо [`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict). Эта возможность может использоваться для реализации пользовательских декодировщиков (например, подсказки класса JSON-RPC).152153*object\_pairs\_hook* – необязательная функция, которая будет вызвана с результатом декодирования любого объектного литерала в виде упорядоченного списка пар. Возвращаемое значение *object\_pairs\_hook* будет использовано вместо [`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict). Эта возможность может использоваться для реализации собственных декодеров, которые полагаются на порядок декодирования пар ключ-значение (например, [`collections.OrderedDict()`](https://python-all.ru/3.1/library/collections.html#collections.OrderedDict) запомнит порядок вставки). Если также определен *object\_hook*, *object\_pairs\_hook* имеет приоритет.154155Изменено в версии 3.1: Добавлена поддержка *object\_pairs\_hook*.156157*parse\_float*, если указан, будет вызван со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию это эквивалентно `float(num_str)`. Это можно использовать для применения другого типа данных или парсера для JSON чисел с плавающей точкой (например, [`decimal.Decimal`](https://python-all.ru/3.1/library/decimal.html#decimal.Decimal)).158159*parse\_int*, если указан, будет вызван со строкой каждого декодируемого JSON-целого числа. По умолчанию это эквивалентно `int(num_str)`. Это можно использовать для применения другого типа данных или парсера для JSON целых чисел (например, [`float`](https://python-all.ru/3.1/library/functions.html#float)).160161*parse\_constant*, если указан, будет вызван с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`, `'null'`, `'true'`, `'false'`. Это может быть использовано для возбуждения исключения при обнаружении недопустимых JSON чисел.162163Чтобы использовать пользовательский подкласс [`JSONDecoder`](https://python-all.ru/3.1/library/json.html#json.JSONDecoder), укажите его в аргументе `cls`; в противном случае используется [`JSONDecoder`](https://python-all.ru/3.1/library/json.html#json.JSONDecoder). Дополнительные ключевые аргументы будут переданы конструктору класса.164165#### `json.loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)`166167Десериализует *s* (экземпляр [`str`](https://python-all.ru/3.1/library/functions.html#str), содержащий JSON-документ) в объект Python.168169Остальные аргументы имеют тот же смысл, что и в [`load()`](https://python-all.ru/3.1/library/json.html#json.load), за исключением *encoding*, который игнорируется и является устаревшим.170171## 18.2.2. Кодировщики и декодировщики172173#### `class json.JSONDecoder(object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)`174175Простой JSON-декодер.176177По умолчанию выполняет следующие преобразования при декодировании:178179| JSON | Python |180| --- | --- |181| объект | dict |182| массив | список |183| строка | str |184| число (int) | int |185| число (вещественное) | float |186| истина | True |187| ложь | False |188| null | None |189190Он также понимает `NaN`, `Infinity` и `-Infinity` как соответствующие значения `float`, что выходит за рамки спецификации JSON.191192*object\_hook*, если указан, будет вызван с результатом декодирования каждого JSON-объекта, и его возвращаемое значение будет использовано вместо переданного [`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict). Это может быть использовано для предоставления пользовательских десериализаций (например, для поддержки JSON-RPC подсказок классов).193194*object\_pairs\_hook*, если указан, будет вызван с результатом декодирования каждого JSON-объекта, представленным в виде упорядоченного списка пар. Возвращаемое значение *object\_pairs\_hook* будет использовано вместо [`dict`](https://python-all.ru/3.1/library/stdtypes.html#dict). Эта возможность может быть использована для реализации пользовательских декодеров, которые полагаются на порядок декодирования пар ключ-значение (например, [`collections.OrderedDict()`](https://python-all.ru/3.1/library/collections.html#collections.OrderedDict) запомнит порядок вставки). Если *object\_hook* также определён, то *object\_pairs\_hook* имеет приоритет.195196Изменено в версии 3.1: Добавлена поддержка *object\_pairs\_hook*.197198*parse\_float*, если указан, будет вызван со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию это эквивалентно `float(num_str)`. Это можно использовать для применения другого типа данных или парсера для JSON чисел с плавающей точкой (например, [`decimal.Decimal`](https://python-all.ru/3.1/library/decimal.html#decimal.Decimal)).199200*parse\_int*, если указан, будет вызван со строкой каждого декодируемого JSON-целого числа. По умолчанию это эквивалентно `int(num_str)`. Это можно использовать для применения другого типа данных или парсера для JSON целых чисел (например, [`float`](https://python-all.ru/3.1/library/functions.html#float)).201202*parse\_constant*, если указан, будет вызван с одной из следующих строк: `'-Infinity'`, `'Infinity'`, `'NaN'`, `'null'`, `'true'`, `'false'`. Это может быть использовано для возбуждения исключения при обнаружении недопустимых JSON чисел.203204Если *strict* равен `False` (`True` – значение по умолчанию), то управляющие символы будут разрешены внутри строк. Управляющие символы в данном контексте – это символы с кодами в диапазоне 0–31, включая `'\t'` (табуляция), `'\n'` (новая строка), `'\r'` (возврат каретки) и `'\0'`.205206#### `decode(s)`207208Возвращает представление209210*s*211212в Python (экземпляр213214[`str`](https://python-all.ru/3.1/library/functions.html#str)215216, содержащий JSON-документ)217218#### `raw_decode(s)`219220Декодирует JSON-документ из *s* (экземпляр [`str`](https://python-all.ru/3.1/library/functions.html#str), начинающийся с JSON-документа) и возвращает кортеж из двух элементов: представление Python и индекс в *s*, на котором документ заканчивается.221222Это можно использовать для декодирования JSON-документа из строки, в конце которой могут быть лишние данные.223224#### `class json.JSONEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)`225226Расширяемый JSON-кодировщик для структур данных Python.227228По умолчанию поддерживает следующие объекты и типы:229230| Python | JSON |231| --- | --- |232| dict | объект |233| list, tuple | массив |234| str | строка |235| int, float | число |236| True | истина |237| False | ложь |238| None | null |239240Чтобы расширить это для распознавания других объектов, создайте подкласс и реализуйте метод [`default()`](https://python-all.ru/3.1/library/json.html#json.JSONEncoder.default): с помощью другого метода он должен возвращать сериализуемый объект для `o`, если это возможно; в противном случае следует вызвать реализацию суперкласса (чтобы возбудить [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)).241242Если *skipkeys* равен `False` (значение по умолчанию), то попытка кодирования ключей, не являющихся str, int, float или None, приводит к [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError). Если *skipkeys* равен `True`, такие элементы просто пропускаются.243244Если *ensure\_ascii* равен `True` (по умолчанию), то гарантируется, что все входящие не-ASCII символы будут экранированы. Если *ensure\_ascii* равен `False`, эти символы будут выводиться как есть.245246Если *check\_circular* равен `True` (по умолчанию), то списки, словари и пользовательские кодированные объекты будут проверяться на циклические ссылки во время кодирования, чтобы предотвратить бесконечную рекурсию (которая привела бы к [`OverflowError`](https://python-all.ru/3.1/library/exceptions.html#OverflowError)). В противном случае такая проверка не производится.247248Если *allow\_nan* равен `True` (по умолчанию), то `NaN`, `Infinity` и `-Infinity` будут кодироваться как есть. Это поведение не соответствует спецификации JSON, но согласовано с большинством кодировщиков и декодировщиков на JavaScript. В противном случае кодирование таких чисел с плавающей точкой приведёт к [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError).249250Если *sort\_keys* равен `True` (по умолчанию `False`), то вывод словарей будет отсортирован по ключам; это полезно для регрессионного тестирования, чтобы гарантировать, что JSON-сериализации можно сравнивать изо дня в день.251252Если *indent* – неотрицательное целое число (по умолчанию оно равно `None`), то элементы JSON-массива и члены объекта будут выводиться с форматированием и отступами этого уровня. Уровень отступа 0 будет только вставлять новые строки. `None` – это наиболее компактное представление.253254Если указано, *separators* должны быть кортежем вида `(item_separator, key_separator)`. По умолчанию – `(', ', ': ')`. Чтобы получить наиболее компактное представление JSON, укажите `(',', ':')`, чтобы убрать пробелы.255256Если указан, *default* – это функция, которая вызывается для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта, пригодную для кодирования в JSON, или возбуждать [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError).257258#### `default(o)`259260Реализуйте этот метод в подклассе так, чтобы он возвращал сериализуемый объект для *o* или вызывал базовую реализацию (чтобы возбудить [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)).261262Например, чтобы поддерживать произвольные итераторы, можно реализовать default следующим образом:263264```python265def default(self, o):266   try:267       iterable = iter(o)268   except TypeError:269       pass270   else:271       return list(iterable)272   return json.JSONEncoder.default(self, o)273```274275#### `encode(o)`276277Возвращает строковое представление структуры данных Python в формате JSON, *o*. Например:278279```python280>>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})281'{"foo": ["bar", "baz"]}'282```283284#### `iterencode(o)`285286Кодирует заданный объект *o* и выдаёт каждое строковое представление по мере готовности. Например:287288```python289for chunk in json.JSONEncoder().iterencode(bigobject):290    mysocket.write(chunk)291```292