Содержание страницы

`json` – JSON кодировщик и декодировщик¶json – JSON encoder and decoder

JSON (JavaScript Object Notation) <http://json.org> – это подмножество синтаксиса JavaScript (ECMA-262, 3-е издание), используемое в качестве легковесного формата обмена данными.

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]
...         return json.JSONEncoder.default(self, obj)
...
>>> 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 -mjson.tool
{
    "json": "obj"
}
$ echo '{ 1.2:3.4}' | python -mjson.tool
Expecting property name: line 1 column 2 (char 2)

Примечание

JSON, создаваемый стандартными настройками этого модуля, является подмножеством YAML, поэтому его также можно использовать в качестве сериализатора для YAML.

Основное использование¶Basic Usage

json.dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])¶

Сериализует obj в поток в формате JSON и записывает его в fp (поддерживающий .write() объект, похожий на файл).

Если skipkeys равно True (по умолчанию: False), то ключи словаря, не являющиеся базовыми типами (str, unicode, int, long, float, bool, None) будут пропущены вместо возбуждения TypeError.

Если ensure_ascii равно False (по умолчанию: True), то некоторые фрагменты, записанные в fp, могут быть экземплярами unicode в соответствии с обычными правилами приведения str к unicode в Python. Если fp.write() явно не поддерживает unicode (как, например, codecs.getwriter()), это скорее всего приведёт к ошибке.

Если check_circular равно False (по умолчанию: True), то проверка циклических ссылок для контейнерных типов будет пропущена, и циклическая ссылка приведет к OverflowError (или хуже).

Если allow_nan равно False (по умолчанию: True), то сериализация значений float вне допустимого диапазона (nan, inf, -inf) будет вызывать ValueError в строгом соответствии со спецификацией JSON, вместо использования JavaScript-эквивалентов (NaN, Infinity, -Infinity).

Если indent – неотрицательное целое число, то элементы массивов и члены объектов JSON будут выводиться с отступами этого уровня. Уровень отступа 0 будет вставлять только новые строки. None (по умолчанию) выбирает наиболее компактное представление.

Если separators является кортежем (item_separator, dict_separator), то он будет использоваться вместо разделителей по умолчанию (', ', ': '). (',', ':') – это наиболее компактное представление JSON.

encoding – это кодировка символов для экземпляров str, по умолчанию UTF-8.

default(obj) – это функция, которая должна возвращать сериализуемую версию obj или возбуждать TypeError. По умолчанию просто возбуждается TypeError.

Чтобы использовать пользовательский подкласс JSONEncoder (например, переопределяющий метод default() для сериализации дополнительных типов), укажите его с помощью аргумента cls.

json.dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])¶

Сериализует obj в строку str в формате JSON.

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

json.load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])¶

Десериализует fp (объект, похожий на файл, поддерживающий .read() и содержащий JSON-документ) в объект Python.

Если содержимое fp закодировано в ASCII-совместимой кодировке, отличной от UTF-8 (например, latin-1), необходимо указать соответствующее имя encoding. Кодировки, не основанные на ASCII (такие как UCS-2), не допускаются, и их следует обернуть с помощью codecs.getreader(fp)(encoding), или просто декодировать в объект unicode и передать в loads().

object_hook – это необязательная функция, которая будет вызвана с результатом декодирования любого объектного литерала (dict). Возвращаемое значение object_hook будет использоваться вместо dict. Эта возможность может использоваться для реализации пользовательских декодировщиков (например, подсказки классов JSON-RPC).

parse_float, если указан, будет вызван со строкой каждого декодируемого JSON-числа с плавающей точкой. По умолчанию это эквивалентно float(num_str). Это можно использовать для применения другого типа данных или парсера для JSON чисел с плавающей точкой (например, decimal.Decimal).

parse_int, если указан, будет вызван со строкой каждого декодируемого JSON-целого числа. По умолчанию это эквивалентно int(num_str). Это можно использовать для применения другого типа данных или парсера для JSON целых чисел (например, float).

parse_constant, если указан, будет вызван с одной из следующих строк: '-Infinity', 'Infinity', 'NaN', 'null', 'true', 'false'. Это может быть использовано для возбуждения исключения при обнаружении недопустимых JSON чисел.

Чтобы использовать пользовательский подкласс JSONDecoder, укажите его с помощью аргумента cls именованный аргумент. Дополнительные именованные аргументы будут переданы конструктору класса.

json.loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])¶

Десериализует s (экземпляр str или unicode, содержащий JSON- документ) в объект Python.

Если s является экземпляром str и закодирован в ASCII-совместимой кодировке, отличной от UTF-8 (например, latin-1), необходимо указать соответствующее имя encoding. Кодировки, не основанные на ASCII (такие как UCS-2), не допускаются и должны быть сначала декодированы в unicode.

Остальные аргументы имеют тот же смысл, что и в dump().

Кодировщики и декодировщики¶Encoders and decoders

class json.JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict]]]]]])¶

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

По умолчанию выполняет следующие преобразования при декодировании:

JSON	Python
объект	dict
массив	список
строка	unicode
число (int)	int, long
число (вещественное)	float
истина	True
ложь	False
null	None

Он также понимает NaN, Infinity и -Infinity как соответствующие значения float, что выходит за рамки спецификации JSON.

encoding определяет кодировку, используемую для интерпретации любых объектов str, декодированных этим экземпляром (по умолчанию UTF-8). Он не влияет на декодирование объектов unicode.

Обратите внимание, что сейчас работают только кодировки, являющиеся надмножеством ASCII. Строки других кодировок нужно передавать как unicode.

object_hook, если указан, будет вызван с результатом декодирования каждого JSON-объекта, и его возвращаемое значение будет использовано вместо переданного dict. Это может быть использовано для предоставления пользовательских десериализаций (например, для поддержки JSON-RPC подсказок классов).

decode(s)¶: Возвращает Python-представление s (экземпляра str или unicode, содержащего документ JSON).

raw_decode(s)¶

Декодирует документ JSON из s (str или unicode, начинающегося с документа JSON) и возвращает кортеж из двух элементов: представление Python и индекс в s, по которому заканчивается документ.

Это можно использовать для декодирования JSON-документа из строки, в конце которой могут быть лишние данные.

class json.JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]])¶

Расширяемый JSON-кодировщик для структур данных Python.

По умолчанию поддерживает следующие объекты и типы:

Python	JSON
dict	объект
list, tuple	массив
str, unicode	строка
int, long, float	число
True	истина
False	ложь
None	null

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

Если skipkeys равен False (по умолчанию), то попытка кодировать ключи, не являющиеся str, int, long, float или None, приводит к TypeError. Если skipkeys равен True, такие элементы просто пропускаются.

Если ensure_ascii равен True (по умолчанию), результат гарантированно будет объектом str со всеми входящими символами unicode, экранированными. Если ensure_ascii равен False, результатом будет объект unicode.

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

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

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

Если indent – неотрицательное целое число (по умолчанию оно равно None), то элементы JSON-массива и члены объекта будут выводиться с форматированием и отступами этого уровня. Уровень отступа 0 будет только вставлять новые строки. None – это наиболее компактное представление.

Если указано, separators должны быть кортежем вида (item_separator, key_separator). По умолчанию – (', ', ': '). Чтобы получить наиболее компактное представление JSON, укажите (',', ':'), чтобы убрать пробелы.

Если указан, default – это функция, которая вызывается для объектов, которые иначе не могут быть сериализованы. Она должна возвращать версию объекта, пригодную для кодирования в JSON, или возбуждать TypeError.

Если encoding не равен None, то все входные строки будут преобразованы в unicode с использованием этой кодировки перед JSON-кодированием. По умолчанию – UTF-8.

default(o)¶

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

Например, чтобы поддерживать произвольные итераторы, можно реализовать default следующим образом:

def default(self, o):
   try:
       iterable = iter(o)
   except TypeError:
       pass
   else:
       return list(iterable)
   return JSONEncoder.default(self, o)

encode(o)¶

Возвращает строковое представление структуры данных Python в формате JSON, o. Например:

>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

iterencode(o)¶

Кодирует заданный объект o и выдаёт каждое строковое представление по мере готовности. Например:

for chunk in JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

json – JSON кодировщик и декодировщик¶json – JSON encoder and decoder

Основное использование¶Basic Usage

Кодировщики и декодировщики¶Encoders and decoders

`json` – JSON кодировщик и декодировщик¶json – JSON encoder and decoder