`json` — JSON encoder and decoder¶

Вихідний код: Lib/json/__init__.py

JSON (JavaScript Object Notation), specified by RFC 7159 (which obsoletes RFC 4627) and by ECMA-404, is a lightweight data interchange format inspired by JavaScript object literal syntax (although it is not a strict subset of JavaScript [1] ).

Попередження

Be cautious when parsing JSON data from untrusted sources. A malicious JSON string may cause the decoder to consume considerable CPU and memory resources. Limiting the size of data to be parsed is recommended.

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 is a subset of YAML 1.2. The JSON produced by this module’s default settings (in particular, the default separators value) is also a subset of YAML 1.0 and 1.1. This module can thus also be used as a YAML serializer.

Примітка

Кодери та декодери цього модуля зберігають порядок введення та виведення за замовчуванням. Порядок втрачається, лише якщо базові контейнери не впорядковані.

Основне використання¶

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), використовуючи цю таблицю перетворення.

Якщо skipkeys має значення true (за замовчуванням: False), тоді ключі dict не мають базового типу (str, int, float, bool, None) буде пропущено замість виклику TypeError.

Модуль json завжди створює об’єкти str, а не об’єкти bytes. Тому fp.write() має підтримувати введення str.

Якщо ensure_ascii має значення true (за замовчуванням), вивід гарантовано матиме екранування всіх вхідних символів, які не є ASCII. Якщо ensure_ascii має значення false, ці символи виводитимуться як є.

If check_circular is false (default: True), then the circular reference check for container types will be skipped and a circular reference will result in a RecursionError (or worse).

Якщо 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). Типовим значенням є (', ', ': '), якщо indent має значення None, і (',', ': ') в іншому випадку. Щоб отримати найбільш компактне представлення JSON, ви повинні вказати (',', ':'), щоб усунути пробіли.

Змінено в версії 3.4: Використовуйте (',', ': ') за умовчанням, якщо indent не є None.

Якщо вказано, default має бути функцією, яка викликається для об’єктів, які не можуть бути серіалізовані інакше. Він має повертати кодовану JSON версію об’єкта або викликати TypeError. Якщо не вказано, виникає TypeError.

Якщо sort_keys має значення true (за замовчуванням: False), тоді вихідні дані словників будуть відсортовані за ключем.

To use a custom JSONEncoder subclass (e.g. one that overrides the default() method to serialize additional types), specify it with the cls kwarg; otherwise JSONEncoder is used.

Змінено в версії 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 (text file із підтримкою .read() або binary file, що містить документ JSON) в об’єкт Python за допомогою цієї таблиці перетворення .

object_hook is an optional function that will be called with the result of any object literal decoded (a dict). The return value of object_hook will be used instead of the dict. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

Змінено в версії 3.1: Додано підтримку object_pairs_hook.

parse_float is an optional function that will be called with the string of every JSON float to be decoded. By default, this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).

parse_int is an optional function that will be called with the string of every JSON int to be decoded. By default, this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).

Змінено в версії 3.11: The default parse_int of int() now limits the maximum length of the integer string via the interpreter’s integer string conversion length limitation to help avoid denial of service attacks.

parse_constant is an optional function that will be called with one of the following strings: '-Infinity', 'Infinity', 'NaN'. This can be used to raise an exception if invalid JSON numbers are encountered.

Змінено в версії 3.1: parse_constant більше не викликається на „null“, „true“, „false“.

Щоб використовувати спеціальний підклас JSONDecoder, вкажіть його за допомогою cls kwarg; інакше JSONDecoder використовується. Додаткові ключові аргументи будуть передані конструктору класу.

Якщо дані, які десеріалізуються, не є дійсним документом JSON, виникне JSONDecodeError.

Змінено в версії 3.6: Усі додаткові параметри тепер лише для ключових слів.

Змінено в версії 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 за допомогою цієї таблиці перетворення.

Інші аргументи мають те саме значення, що й у load().

Якщо дані, які десеріалізуються, не є дійсним документом JSON, виникне JSONDecodeError.

Змінено в версії 3.6: s тепер може бути типу bytes або bytearray. Вхідне кодування має бути UTF-8, UTF-16 або UTF-32.

Змінено в версії 3.9: Аргумент ключового слова кодування видалено.

Кодери та декодери¶

class json.JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)¶

Простий декодер JSON.

Виконує такі переклади в декодуванні за замовчуванням:

JSON	Python
об’єкт	дикт
масив	список
рядок	вул
число (ціле)	внутр
число (дійсне)	плавати
правда	правда
помилковий	помилковий
нуль	Жодного

Він також розуміє NaN, Infinity і -Infinity як їхні відповідні значення float, що виходить за межі специфікації JSON.

object_hook is an optional function that will be called with the result of every JSON object decoded and its return value will be used in place of the given dict. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

Змінено в версії 3.1: Додано підтримку object_pairs_hook.

parse_float is an optional function that will be called with the string of every JSON float to be decoded. By default, this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).

parse_int is an optional function that will be called with the string of every JSON int to be decoded. By default, this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).

parse_constant is an optional function that will be called with one of the following strings: '-Infinity', 'Infinity', 'NaN'. This can be used to raise an exception if invalid JSON numbers are encountered.

Якщо strict має значення false (True є значенням за замовчуванням), то керуючі символи будуть дозволені всередині рядків. Контрольні символи в цьому контексті — це символи з кодами символів у діапазоні 0–31, включаючи '\t' (табуляція), '\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
дикт	об’єкт
список, кортеж	масив
вул	рядок
int, float, int- & float-derived Enums	номер
правда	правда
помилковий	помилковий
Жодного	нуль

Змінено в версії 3.4: Додано підтримку класів Enum, похідних від int і float.

To extend this to recognize other objects, subclass and implement a default() method with another method that returns a serializable object for o if possible, otherwise it should call the superclass implementation (to raise TypeError).

Якщо skipkeys має значення false (за замовчуванням), TypeError буде викликано під час спроби закодувати ключі, які не є str, int, float або Жодного. Якщо skipkeys має значення true, такі елементи просто пропускаються.

Якщо ensure_ascii має значення true (за замовчуванням), вивід гарантовано матиме екранування всіх вхідних символів, які не є ASCII. Якщо ensure_ascii має значення false, ці символи виводитимуться як є.

If check_circular is true (the default), then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause a RecursionError). Otherwise, no such check takes place.

Якщо 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). Типовим значенням є (', ', ': '), якщо indent має значення None, і (',', ': ') в іншому випадку. Щоб отримати найбільш компактне представлення JSON, ви повинні вказати (',', ':'), щоб усунути пробіли.

Змінено в версії 3.4: Використовуйте (',', ': ') за умовчанням, якщо indent не є None.

Якщо вказано, default має бути функцією, яка викликається для об’єктів, які не можуть бути серіалізовані інакше. Він має повертати кодовану JSON версію об’єкта або викликати TypeError. Якщо не вказано, виникає TypeError.

Змінено в версії 3.6: Усі параметри тепер лише для ключових слів.

default(o)¶

Реалізуйте цей метод у підкласі так, щоб він повертав серіалізований об’єкт для o або викликав базову реалізацію (щоб викликати TypeError).

For example, to support arbitrary iterators, you could implement default() like this:

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.

Added in version 3.5.

Відповідність стандартам і сумісність¶

The JSON format is specified by RFC 7159 and by ECMA-404. This section details this module’s level of compliance with the RFC. For simplicity, JSONEncoder and JSONDecoder subclasses, and parameters other than those explicitly mentioned, are not considered.

Цей модуль не повністю відповідає 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, і, отже, іншим чином безпосередньо не вирішує проблему кодування символів.

RFC забороняє додавати позначку порядку байтів (BOM) на початок тексту JSON, а серіалізатор цього модуля не додає BOM до свого виводу. 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.

If the optional infile and outfile arguments are not specified, sys.stdin and sys.stdout will be used respectively:

$ 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
    }
]

If infile is not specified, read from sys.stdin.

outfile¶: Write the output of the infile to the given outfile. Otherwise, write it to sys.stdout.

--sort-keys¶: Сортувати вихідні дані словників за алфавітом за ключем.

Added in version 3.5.

--no-ensure-ascii¶: Вимкніть екранування символів, відмінних від ASCII, див. json.dumps() для отримання додаткової інформації.

Added in version 3.9.

--json-lines¶: Проаналізуйте кожен рядок введення як окремий об’єкт JSON.

Added in version 3.8.

--indent, --tab, --no-indent, --compact¶: Взаємовиключні параметри керування пробілами.

Added in version 3.9.

-h, --help¶: Показати довідкове повідомлення.

Виноски

`json` — JSON encoder and decoder¶

Основне використання¶

Кодери та декодери¶

Винятки¶

Відповідність стандартам і сумісність¶

Кодування символів¶

Нескінченні значення чисел NaN¶

Повторювані імена в межах об’єкта¶

Необ’єктні та немасивні значення верхнього рівня¶

Обмеження реалізації¶

Інтерфейс командного рядка¶

Параметри командного рядка¶

Table of Contents

Попередній розділ

Наступна тема

Ця сторінка

json — JSON encoder and decoder¶

Основне використання¶

Кодери та декодери¶

Винятки¶

Відповідність стандартам і сумісність¶

Кодування символів¶

Нескінченні значення чисел NaN¶

Повторювані імена в межах об’єкта¶

Необ’єктні та немасивні значення верхнього рівня¶

Обмеження реалізації¶

Інтерфейс командного рядка¶

Параметри командного рядка¶

`json` — JSON encoder and decoder¶