json — Кодировщик и декодировщик JSON

Введено в версии 2.6.

JSON (JavaScript Object Notation), определённый в RFC 7159 (который устарел RFC 4627) и ECMA-404, является лёгким форматом обмена данными, вдохновлённым синтаксисом объектов JavaScript (хотя он не является строгим подмножеством JavaScript 1 ).

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(u'\u1234')
"\u1234"
>>> print json.dumps('\\')
"\\"
>>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
{"a": 0, "b": 0, "c": 0}
>>> from StringIO 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, separators=(',', ': '))
{
    "4": 5,
    "6": 7
}

Декодирование JSON:

>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
[u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
u'"foo\x08ar'
>>> from StringIO import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
[u'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 json.JSONEncoder.default(self, 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 -mjson.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.

1. Базовое использование

json.dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, encoding="utf-8", default=None, sort_keys=False, **kw)

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

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

Если ensure_ascii равно True (по умолчанию), все символы, не являющиеся ASCII, в выводе экранируются \uXXXX последовательностями, и результат представляет собой экземпляр str, состоящий только из символов ASCII. Если ensure_ascii равно false, некоторые части, записанные в fp, могут быть экземплярами unicode. Это обычно происходит, потому что вход содержит строки unicode или используется параметр encoding. Если fp.write() не понимает unicode (как в codecs.getwriter()), это, вероятно, вызовет ошибку.

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

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

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

Примечание

Поскольку разделитель элементов по умолчанию — ', ', на выводе может быть конечный пробел, когда задан indent. Вы можете использовать separators=(',', ': ') для избежания этого.

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

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

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

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

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

Примечание

В отличие от 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, encoding="utf-8", default=None, sort_keys=False, **kw)

Сериализует obj в JSON-форматированный str с использованием этой таблицы преобразования. Если ensure_ascii равно false, результат может содержать символы, не являющиеся ASCII, и возвращаемое значение может быть экземпляром unicode.

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

Примечание

Ключи в парах ключ/значение JSON всегда имеют тип str. Когда словарь преобразуется в JSON, все ключи словаря принудительно преобразуются в строки. В результате этого, если словарь преобразуется в JSON, а затем обратно в словарь, словарь может не совпадать с исходным, то есть loads(dumps(x)) != x если у x есть ключи, не являющиеся строками.

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

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

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

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

object_pairs_hook — необязательная функция, которая вызывается с результатом декодирования любого объекта со списком пар (с указанием порядка ключей и значений). Значение, возвращаемое object_pairs_hook, будет использоваться вместо dict. Это позволяет реализовать пользовательские декодеры, которые зависят от порядка декодирования пар «ключ-значение» (например, collections.OrderedDict() сохраняет порядок вставки). Если задана object_hook, то object_pairs_hook имеет приоритет.

Изменено в версии 2.7: Добавлена поддержка 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-чисел.

Изменено в версии 2.7: parse_constant больше не вызывается для «null», «true», «false».

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

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

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

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

Другие аргументы имеют то же значение, что и в load().

2. Кодировщики и Декодировщики

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

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

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

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

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

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

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

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

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

Изменено в версии 2.7: Добавлена поддержка 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 равно false (по умолчанию True), то управляющие символы будут разрешены внутри строк. Управляющие символы в данном контексте — это символы с кодами в диапазоне от 0 до 31, включая '\t' (табуляцию), '\n', '\r' и '\0'.

Если данные, подлежащие десериализации, не являются допустимым JSON-документом, будет возбуждено исключение ValueError.

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

raw_decode(s)

Декодирует JSON-документ из s (строка str или unicode, начинающаяся с JSON-документа) и возвращает кортеж из 2 элементов: 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	true
False	false
None	null

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

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

Если ensure_ascii имеет значение true (по умолчанию), все не-ASCII символы в выводе экранируются с помощью \uXXXX последовательностей, а результаты являются str экземплярами, состоящими только из ASCII символов. Если ensure_ascii имеет значение false, результатом может быть unicode экземпляр. Это обычно происходит, если входные данные содержат строки unicode или используется параметр encoding.

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

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

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

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

Примечание

Поскольку разделитель элементов по умолчанию является ', ', в выводе может быть добавлен конечный пробел, когда указан indent. Вы можете использовать separators=(',', ': ') для предотвращения этого.

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

Если указано, default должен быть функцией, которая вызывается для объектов, которые нельзя сериализовать иным образом. Она должна вернуть JSON-кодируемую версию объекта или поднять TypeError. Если не указано, поднимается 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)
   # Let the base class default method raise the TypeError
   return JSONEncoder.default(self, o)

encode(o)

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

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

iterencode(o)

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

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

3. Соответствие стандарту и межплатформенная совместимость

Формат JSON определен в RFC 7159 и ECMA-404. В этом разделе подробно описывается уровень соответствия этого модуля RFC. Для простоты JSONEncoder и JSONDecoder подклассы, а также параметры, кроме явно указанных, не рассматриваются.

Этот модуль не строго соответствует RFC, реализуя некоторые расширения, которые являются допустимыми в JavaScript, но не допустимы в JSON. В частности:

Бесконечные и NaN значения чисел принимаются и выводятся;
Повторные имена внутри объекта принимаются, и используется только значение последней пары имя-значение.

Поскольку RFC разрешает RFC-совместимым парсерам принимать тексты, которые не соответствуют RFC, этот модуль-десериализатор технически RFC-совместим при стандартных настройках.

3.1. Кодировки символов

RFC требует, чтобы JSON представлялся с помощью UTF-8, UTF-16 или UTF-32, при этом UTF-8 является рекомендуемым по умолчанию для максимальной межплатформенной совместимости. Соответственно, этот модуль использует UTF-8 в качестве параметра по умолчанию для параметра encoding.

Десериализатор этого модуля работает только с совместимыми с ASCII кодировками; UTF-16, UTF-32 и другие несовместимые с ASCII кодировки требуют использования решений, описанных в документации к параметру десериализатора encoding.

Как разрешено, хотя и не обязательно, RFC, кодировщик этого модуля устанавливает ensure_ascii=True по умолчанию, тем самым экранируя вывод так, что результирующие строки содержат только символы ASCII.

RFC запрещает добавление отметки порядка байтов (BOM) в начало текста JSON, и кодировщик этого модуля не добавляет BOM в свой вывод. RFC разрешает, но не требует, чтобы десериализаторы JSON игнорировали начальную BOM в своем входе. Этот модуль-десериализатор поднимает ValueError, когда присутствует начальная BOM.

RFC не запрещает явно JSON-строки, которые содержат последовательности байтов, не соответствующие допустимым символам Unicode (например, неспаренные суррогаты UTF-16), но отмечает, что они могут вызвать проблемы совместимости. По умолчанию этот модуль принимает и выводит (при наличии в исходной str) кодовые точки для таких последовательностей.

3.2. Бесконечные и 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 может быть использован для изменения этого поведения.

3.3. Повторные имена внутри объекта

RFC указывает, что имена внутри объекта JSON должны быть уникальными, но не предписывает, как должны обрабатываться повторяющиеся имена в объектах JSON. По умолчанию этот модуль не генерирует исключение; вместо этого он игнорирует все, кроме последней пары имя-значение для данного имени:

>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json)
{u'x': 3}

Параметр object_pairs_hook может быть использован для изменения этого поведения.

3.4. Значения верхнего уровня, не являющиеся объектами или массивами

Старая версия JSON, определенная устаревшим RFC 4627, требовала, чтобы значение верхнего уровня текста JSON должно быть либо JSON-объектом, либо массивом (Python dict или list), и не могло быть JSON-null, boolean, числом или строкой. RFC 7159 убрало это ограничение, и этот модуль не реализовывал и никогда не реализовывал это ограничение ни в своем сериализаторе, ни в своем десериализаторе.

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

3.5. Ограничения реализации

Некоторые реализации десериализаторов JSON могут устанавливать ограничения на:

размер принимаемых текстов JSON
максимальный уровень вложенности JSON-объектов и массивов
диапазон и точность JSON-чисел
содержимое и максимальную длину JSON-строк

Этот модуль не накладывает никаких ограничений, кроме тех, что уже наложены соответствующими типами данных Python или самим интерпретатором Python.

При сериализации в JSON будьте осторожны с такими ограничениями в приложениях, которые могут использовать ваш JSON. В частности, часто JSON-числа десериализуются в числа двойной точности IEEE 754 и, следовательно, подчиняются ограничениям этого представления по диапазону и точности. Это особенно актуально при сериализации значений Python int чрезвычайно большой величины или при сериализации экземпляров «экзотических» числовых типов, таких как decimal.Decimal.

Примечания

1: Как указано в ошибках RFC 7159, JSON допускает использование символов U+2028 (РАЗДЕЛИТЕЛЬ СТРОК) и U+2029 (РАЗДЕЛИТЕЛЬ АБЗАЦОВ) в строках, тогда как JavaScript (по состоянию на ECMAScript Edition 5.1) — нет.