14adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaor"""JSON (JavaScript Object Notation) <http://json.org> is a subset of 24adfde8bc82dd39f59e0445588c3e599ada477dJosh GaoJavaScript syntax (ECMA-262 3rd edition) used as a lightweight data 34adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaointerchange format. 44adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 54adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao:mod:`json` exposes an API familiar to users of the standard library 64adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao:mod:`marshal` and :mod:`pickle` modules. It is the externally maintained 74adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaoversion of the :mod:`json` library contained in Python 2.6, but maintains 84adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaocompatibility with Python 2.4 and Python 2.5 and (currently) has 94adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaosignificant performance advantages, even without using the optional C 104adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaoextension for speedups. 114adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 124adfde8bc82dd39f59e0445588c3e599ada477dJosh GaoEncoding basic Python object hierarchies:: 134adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 144adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> import json 154adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) 164adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao '["foo", {"bar": ["baz", null, 1.0, 2]}]' 174adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> print json.dumps("\"foo\bar") 184adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao "\"foo\bar" 194adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> print json.dumps(u'\u1234') 204adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao "\u1234" 214adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> print json.dumps('\\') 224adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao "\\" 234adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True) 244adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao {"a": 0, "b": 0, "c": 0} 254adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> from StringIO import StringIO 264adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> io = StringIO() 274adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.dump(['streaming API'], io) 284adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> io.getvalue() 294adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao '["streaming API"]' 304adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 314adfde8bc82dd39f59e0445588c3e599ada477dJosh GaoCompact encoding:: 324adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 334adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> import json 344adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.dumps([1,2,3,{'4': 5, '6': 7}], sort_keys=True, separators=(',',':')) 354adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao '[1,2,3,{"4":5,"6":7}]' 364adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 374adfde8bc82dd39f59e0445588c3e599ada477dJosh GaoPretty printing:: 384adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 394adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> import json 404adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> print json.dumps({'4': 5, '6': 7}, sort_keys=True, 414adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... indent=4, separators=(',', ': ')) 424adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao { 434adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao "4": 5, 444adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao "6": 7 454adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao } 464adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 474adfde8bc82dd39f59e0445588c3e599ada477dJosh GaoDecoding JSON:: 484adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 494adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> import json 504adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] 514adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj 524adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao True 534adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar' 544adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao True 554adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> from StringIO import StringIO 564adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> io = StringIO('["streaming API"]') 574adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.load(io)[0] == 'streaming API' 584adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao True 594adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 604adfde8bc82dd39f59e0445588c3e599ada477dJosh GaoSpecializing JSON object decoding:: 614adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 624adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> import json 634adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> def as_complex(dct): 644adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... if '__complex__' in dct: 654adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... return complex(dct['real'], dct['imag']) 664adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... return dct 674adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... 684adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', 694adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... object_hook=as_complex) 704adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao (1+2j) 714adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> from decimal import Decimal 724adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.loads('1.1', parse_float=Decimal) == Decimal('1.1') 734adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao True 744adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 754adfde8bc82dd39f59e0445588c3e599ada477dJosh GaoSpecializing JSON object encoding:: 764adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 774adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> import json 784adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> def encode_complex(obj): 794adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... if isinstance(obj, complex): 804adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... return [obj.real, obj.imag] 814adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... raise TypeError(repr(o) + " is not JSON serializable") 824adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ... 834adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.dumps(2 + 1j, default=encode_complex) 844adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao '[2.0, 1.0]' 854adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j) 864adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao '[2.0, 1.0]' 874adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) 884adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao '[2.0, 1.0]' 894adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 904adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 914adfde8bc82dd39f59e0445588c3e599ada477dJosh GaoUsing json.tool from the shell to validate and pretty-print:: 924adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 934adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao $ echo '{"json":"obj"}' | python -m json.tool 944adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao { 954adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao "json": "obj" 964adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao } 974adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao $ echo '{ 1.2:3.4}' | python -m json.tool 984adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao Expecting property name enclosed in double quotes: line 1 column 3 (char 2) 994adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao""" 1004adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao__version__ = '2.0.9' 1014adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao__all__ = [ 1024adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 'dump', 'dumps', 'load', 'loads', 1034adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 'JSONDecoder', 'JSONEncoder', 1044adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao] 1054adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1064adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao__author__ = 'Bob Ippolito <bob@redivi.com>' 1074adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1084adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaofrom .decoder import JSONDecoder 1094adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaofrom .encoder import JSONEncoder 1104adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1114adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao_default_encoder = JSONEncoder( 1124adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao skipkeys=False, 1134adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ensure_ascii=True, 1144adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao check_circular=True, 1154adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao allow_nan=True, 1164adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao indent=None, 1174adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao separators=None, 1184adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao encoding='utf-8', 1194adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao default=None, 1204adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao) 1214adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1224adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaodef dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, 1234adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao allow_nan=True, cls=None, indent=None, separators=None, 1244adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao encoding='utf-8', default=None, sort_keys=False, **kw): 1254adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a 1264adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``.write()``-supporting file-like object). 1274adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1284adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``skipkeys`` is true then ``dict`` keys that are not basic types 1294adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) 1304adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao will be skipped instead of raising a ``TypeError``. 1314adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1324adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``ensure_ascii`` is true (the default), all non-ASCII characters in the 1334adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao output are escaped with ``\uXXXX`` sequences, and the result is a ``str`` 1344adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao instance consisting of ASCII characters only. If ``ensure_ascii`` is 1354adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``False``, some chunks written to ``fp`` may be ``unicode`` instances. 1364adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao This usually happens because the input contains unicode strings or the 1374adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``encoding`` parameter is used. Unless ``fp.write()`` explicitly 1384adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao understands ``unicode`` (as in ``codecs.getwriter``) this is likely to 1394adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao cause an error. 1404adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1414adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``check_circular`` is false, then the circular reference check 1424adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao for container types will be skipped and a circular reference will 1434adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao result in an ``OverflowError`` (or worse). 1444adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1454adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``allow_nan`` is false, then it will be a ``ValueError`` to 1464adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) 1474adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao in strict compliance of the JSON specification, instead of using the 1484adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 1494adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1504adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``indent`` is a non-negative integer, then JSON array elements and 1514adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao object members will be pretty-printed with that indent level. An indent 1524adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao level of 0 will only insert newlines. ``None`` is the most compact 1534adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao representation. Since the default item separator is ``', '``, the 1544adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao output might include trailing whitespace when ``indent`` is specified. 1554adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao You can use ``separators=(',', ': ')`` to avoid this. 1564adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1574adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``separators`` is an ``(item_separator, dict_separator)`` tuple 1584adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao then it will be used instead of the default ``(', ', ': ')`` separators. 1594adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``(',', ':')`` is the most compact JSON representation. 1604adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1614adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``encoding`` is the character encoding for str instances, default is UTF-8. 1624adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1634adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``default(obj)`` is a function that should return a serializable version 1644adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao of obj or raise TypeError. The default simply raises TypeError. 1654adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1664adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If *sort_keys* is ``True`` (default: ``False``), then the output of 1674adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao dictionaries will be sorted by key. 1684adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1694adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 1704adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``.default()`` method to serialize additional types), specify it with 1714adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao the ``cls`` kwarg; otherwise ``JSONEncoder`` is used. 1724adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1734adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao """ 1744adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao # cached encoder 1754adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if (not skipkeys and ensure_ascii and 1764adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao check_circular and allow_nan and 1774adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao cls is None and indent is None and separators is None and 1784adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao encoding == 'utf-8' and default is None and not sort_keys and not kw): 1794adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao iterable = _default_encoder.iterencode(obj) 1804adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao else: 1814adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if cls is None: 1824adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao cls = JSONEncoder 1834adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii, 1844adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao check_circular=check_circular, allow_nan=allow_nan, indent=indent, 1854adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao separators=separators, encoding=encoding, 1864adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao default=default, sort_keys=sort_keys, **kw).iterencode(obj) 1874adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao # could accelerate with writelines in some versions of Python, at 1884adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao # a debuggability cost 1894adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao for chunk in iterable: 1904adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao fp.write(chunk) 1914adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1924adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1934adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaodef dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, 1944adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao allow_nan=True, cls=None, indent=None, separators=None, 1954adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao encoding='utf-8', default=None, sort_keys=False, **kw): 1964adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao """Serialize ``obj`` to a JSON formatted ``str``. 1974adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 1984adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``skipkeys`` is false then ``dict`` keys that are not basic types 1994adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) 2004adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao will be skipped instead of raising a ``TypeError``. 2014adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2024adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``ensure_ascii`` is false, all non-ASCII characters are not escaped, and 2034adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao the return value may be a ``unicode`` instance. See ``dump`` for details. 2044adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2054adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``check_circular`` is false, then the circular reference check 2064adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao for container types will be skipped and a circular reference will 2074adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao result in an ``OverflowError`` (or worse). 2084adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2094adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``allow_nan`` is false, then it will be a ``ValueError`` to 2104adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in 2114adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao strict compliance of the JSON specification, instead of using the 2124adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 2134adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2144adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``indent`` is a non-negative integer, then JSON array elements and 2154adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao object members will be pretty-printed with that indent level. An indent 2164adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao level of 0 will only insert newlines. ``None`` is the most compact 2174adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao representation. Since the default item separator is ``', '``, the 2184adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao output might include trailing whitespace when ``indent`` is specified. 2194adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao You can use ``separators=(',', ': ')`` to avoid this. 2204adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2214adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``separators`` is an ``(item_separator, dict_separator)`` tuple 2224adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao then it will be used instead of the default ``(', ', ': ')`` separators. 2234adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``(',', ':')`` is the most compact JSON representation. 2244adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2254adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``encoding`` is the character encoding for str instances, default is UTF-8. 2264adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2274adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``default(obj)`` is a function that should return a serializable version 2284adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao of obj or raise TypeError. The default simply raises TypeError. 2294adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2304adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If *sort_keys* is ``True`` (default: ``False``), then the output of 2314adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao dictionaries will be sorted by key. 2324adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2334adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 2344adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``.default()`` method to serialize additional types), specify it with 2354adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao the ``cls`` kwarg; otherwise ``JSONEncoder`` is used. 2364adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2374adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao """ 2384adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao # cached encoder 2394adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if (not skipkeys and ensure_ascii and 2404adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao check_circular and allow_nan and 2414adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao cls is None and indent is None and separators is None and 2424adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao encoding == 'utf-8' and default is None and not sort_keys and not kw): 2434adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao return _default_encoder.encode(obj) 2444adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if cls is None: 2454adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao cls = JSONEncoder 2464adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao return cls( 2474adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao skipkeys=skipkeys, ensure_ascii=ensure_ascii, 2484adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao check_circular=check_circular, allow_nan=allow_nan, indent=indent, 2494adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao separators=separators, encoding=encoding, default=default, 2504adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao sort_keys=sort_keys, **kw).encode(obj) 2514adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2524adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2534adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao_default_decoder = JSONDecoder(encoding=None, object_hook=None, 2544adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao object_pairs_hook=None) 2554adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2564adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2574adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaodef load(fp, encoding=None, cls=None, object_hook=None, parse_float=None, 2584adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao parse_int=None, parse_constant=None, object_pairs_hook=None, **kw): 2594adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing 2604adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao a JSON document) to a Python object. 2614adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2624adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If the contents of ``fp`` is encoded with an ASCII based encoding other 2634adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must 2644adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao be specified. Encodings that are not ASCII based (such as UCS-2) are 2654adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao not allowed, and should be wrapped with 2664adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode`` 2674adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao object and passed to ``loads()`` 2684adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2694adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``object_hook`` is an optional function that will be called with the 2704adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao result of any object literal decode (a ``dict``). The return value of 2714adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``object_hook`` will be used instead of the ``dict``. This feature 2724adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao can be used to implement custom decoders (e.g. JSON-RPC class hinting). 2734adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2744adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``object_pairs_hook`` is an optional function that will be called with the 2754adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao result of any object literal decoded with an ordered list of pairs. The 2764adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao return value of ``object_pairs_hook`` will be used instead of the ``dict``. 2774adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao This feature can be used to implement custom decoders that rely on the 2784adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao order that the key and value pairs are decoded (for example, 2794adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao collections.OrderedDict will remember the order of insertion). If 2804adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority. 2814adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2824adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 2834adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao kwarg; otherwise ``JSONDecoder`` is used. 2844adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2854adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao """ 2864adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao return loads(fp.read(), 2874adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao encoding=encoding, cls=cls, object_hook=object_hook, 2884adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao parse_float=parse_float, parse_int=parse_int, 2894adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, 2904adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao **kw) 2914adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2924adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2934adfde8bc82dd39f59e0445588c3e599ada477dJosh Gaodef loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, 2944adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao parse_int=None, parse_constant=None, object_pairs_hook=None, **kw): 2954adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON 2964adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao document) to a Python object. 2974adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 2984adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding 2994adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name 3004adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao must be specified. Encodings that are not ASCII based (such as UCS-2) 3014adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao are not allowed and should be decoded to ``unicode`` first. 3024adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 3034adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``object_hook`` is an optional function that will be called with the 3044adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao result of any object literal decode (a ``dict``). The return value of 3054adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``object_hook`` will be used instead of the ``dict``. This feature 3064adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao can be used to implement custom decoders (e.g. JSON-RPC class hinting). 3074adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 3084adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``object_pairs_hook`` is an optional function that will be called with the 3094adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao result of any object literal decoded with an ordered list of pairs. The 3104adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao return value of ``object_pairs_hook`` will be used instead of the ``dict``. 3114adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao This feature can be used to implement custom decoders that rely on the 3124adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao order that the key and value pairs are decoded (for example, 3134adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao collections.OrderedDict will remember the order of insertion). If 3144adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority. 3154adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 3164adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``parse_float``, if specified, will be called with the string 3174adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao of every JSON float to be decoded. By default this is equivalent to 3184adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao float(num_str). This can be used to use another datatype or parser 3194adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao for JSON floats (e.g. decimal.Decimal). 3204adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 3214adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``parse_int``, if specified, will be called with the string 3224adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao of every JSON int to be decoded. By default this is equivalent to 3234adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao int(num_str). This can be used to use another datatype or parser 3244adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao for JSON integers (e.g. float). 3254adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 3264adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao ``parse_constant``, if specified, will be called with one of the 3274adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao following strings: -Infinity, Infinity, NaN, null, true, false. 3284adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao This can be used to raise an exception if invalid JSON numbers 3294adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao are encountered. 3304adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 3314adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 3324adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao kwarg; otherwise ``JSONDecoder`` is used. 3334adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao 3344adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao """ 3354adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if (cls is None and encoding is None and object_hook is None and 3364adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao parse_int is None and parse_float is None and 3374adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao parse_constant is None and object_pairs_hook is None and not kw): 3384adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao return _default_decoder.decode(s) 3394adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if cls is None: 3404adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao cls = JSONDecoder 3414adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if object_hook is not None: 3424adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao kw['object_hook'] = object_hook 3434adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if object_pairs_hook is not None: 3444adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao kw['object_pairs_hook'] = object_pairs_hook 3454adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if parse_float is not None: 3464adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao kw['parse_float'] = parse_float 3474adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if parse_int is not None: 3484adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao kw['parse_int'] = parse_int 3494adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao if parse_constant is not None: 3504adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao kw['parse_constant'] = parse_constant 3514adfde8bc82dd39f59e0445588c3e599ada477dJosh Gao return cls(encoding=encoding, **kw).decode(s) 352