# `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)

  Serialize obj as a JSON formatted stream to fp (a `.write()`-supporting file-like object) using this conversion table.

  If skipkeys is true (default: `False`), then dict keys that are not of a basic type (`str`, `int`, `float`, `bool`, `None`) will be skipped instead of raising a `TypeError`.

  The `json` module always produces `str` objects, not `bytes` objects. Therefore, `fp.write()` must support `str` input.

  Якщо 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).

  If allow_nan is false (default: `True`), then it will be a `ValueError` to serialize out of range `float` values (`nan`, `inf`, `-inf`) in strict compliance of the JSON specification. If allow_nan is true, their JavaScript equivalents (`NaN`, `Infinity`, `-Infinity`) will be used.

  Якщо indent є невід’ємним цілим числом або рядком, елементи масиву JSON і члени об’єкта будуть надруковані з таким рівнем відступу. Рівень відступу 0, негативний або `""` вставлятиме лише нові рядки. `None` (за замовчуванням) вибирає найбільш компактне представлення. Використання додатного цілого відступу робить стільки відступів на рівень. Якщо indent є рядком (наприклад, `"\t"`), цей рядок використовується для відступу кожного рівня.

  Змінено в версії 3.2: Дозволити рядки для відступу на додаток до цілих чисел.

  Якщо вказано, роздільники мають бути кортежем `(item_separator, key_separator)`. Типовим значенням є `(', ', ': ')`, якщо indent має значення `None`, і `(',', ': ')` в іншому випадку. Щоб отримати найбільш компактне представлення JSON, ви повинні вказати `(',', ':')`, щоб усунути пробіли.

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

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

  If sort_keys is true (default: `False`), then the output of dictionaries will be sorted by key.

  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)

  Deserialize fp (a `.read()`-supporting text file or binary file containing a JSON document) to a Python object using this conversion table.

  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, if specified, 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, if specified, 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, if specified, 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“.

  To use a custom `JSONDecoder` subclass, specify it with the `cls` kwarg; otherwise `JSONDecoder` is used. Additional keyword arguments will be passed to the constructor of the class.

  Якщо дані, які десеріалізуються, не є дійсним документом 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)

  Deserialize s (a `str`, `bytes` or `bytearray` instance containing a JSON document) to a Python object using this conversion table.

  The other arguments have the same meaning as in `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, if specified, 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, if specified 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, if specified, 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, if specified, 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, if specified, 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`).

  If skipkeys is false (the default), a `TypeError` will be raised when trying to encode keys that are not `str`, `int`, `float` or `None`. If skipkeys is true, such items are simply skipped.

  Якщо 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.

  Нове в версії 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

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

  Нове в версії 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) не допускає.