__init__.py revision 2a99a7e74a7f215066514fe81d2bfa6639d9eddd
12a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)interchange format. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 52a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles):mod:`simplejson` exposes an API familiar to users of the standard library 62a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles):mod:`marshal` and :mod:`pickle` modules. It is the externally maintained 72a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)version of the :mod:`json` library contained in Python 2.6, but maintains 82a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)compatibility with Python 2.4 and Python 2.5 and (currently) has 92a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)significant performance advantages, even without using the optional C 102a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)extension for speedups. 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Encoding basic Python object hierarchies:: 132a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 142a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> import simplejson as json 152a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) '["foo", {"bar": ["baz", null, 1.0, 2]}]' 172a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> print json.dumps("\"foo\bar") 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) "\"foo\bar" 192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> print json.dumps(u'\u1234') 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) "\u1234" 212a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> print json.dumps('\\') 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) "\\" 232a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True) 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) {"a": 0, "b": 0, "c": 0} 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) >>> from StringIO import StringIO 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) >>> io = StringIO() 272a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.dump(['streaming API'], io) 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) >>> io.getvalue() 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) '["streaming API"]' 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Compact encoding:: 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 332a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> import simplejson as json 342a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':')) 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) '[1,2,3,{"4":5,"6":7}]' 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Pretty printing:: 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 392a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> import simplejson as json 402a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> s = json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=' ') 412a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> print '\n'.join([l.rstrip() for l in s.splitlines()]) 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) { 432a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) "4": 5, 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) "6": 7 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) } 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Decoding JSON:: 482a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 492a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> import simplejson as json 502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] 512a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj 522a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) True 532a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar' 542a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) True 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) >>> from StringIO import StringIO 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) >>> io = StringIO('["streaming API"]') 572a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.load(io)[0] == 'streaming API' 582a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) True 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Specializing JSON object decoding:: 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 622a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> import simplejson as json 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) >>> def as_complex(dct): 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ... if '__complex__' in dct: 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ... return complex(dct['real'], dct['imag']) 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ... return dct 672a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ... 682a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ... object_hook=as_complex) 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (1+2j) 712a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> from decimal import Decimal 722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.loads('1.1', parse_float=Decimal) == Decimal('1.1') 732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) True 742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)Specializing JSON object encoding:: 762a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 772a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> import simplejson as json 782a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> def encode_complex(obj): 792a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ... if isinstance(obj, complex): 802a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ... return [obj.real, obj.imag] 812a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ... raise TypeError(repr(o) + " is not JSON serializable") 822a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ... 832a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.dumps(2 + 1j, default=encode_complex) 842a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) '[2.0, 1.0]' 852a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j) 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) '[2.0, 1.0]' 872a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) '[2.0, 1.0]' 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 902a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 912a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)Using simplejson.tool from the shell to validate and pretty-print:: 922a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 932a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) $ echo '{"json":"obj"}' | python -m simplejson.tool 942a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) { 952a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) "json": "obj" 962a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) } 972a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) $ echo '{ 1.2:3.4}' | python -m simplejson.tool 982a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) Expecting property name: line 1 column 2 (char 2) 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)""" 1002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)__version__ = '2.6.2' 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)__all__ = [ 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 'dump', 'dumps', 'load', 'loads', 1032a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 'JSONDecoder', 'JSONDecodeError', 'JSONEncoder', 1042a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 'OrderedDict', 'simple_first', 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)] 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1072a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)__author__ = 'Bob Ippolito <bob@redivi.com>' 1082a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1092a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)from decimal import Decimal 1102a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1112a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)from decoder import JSONDecoder, JSONDecodeError 1122a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)from encoder import JSONEncoder, JSONEncoderForHTML 1132a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)def _import_OrderedDict(): 1142a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) import collections 1152a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) try: 1162a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) return collections.OrderedDict 1172a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) except AttributeError: 1182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) import ordered_dict 1192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) return ordered_dict.OrderedDict 1202a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)OrderedDict = _import_OrderedDict() 1212a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1222a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)def _import_c_make_encoder(): 1232a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) try: 1242a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) from simplejson._speedups import make_encoder 1252a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) return make_encoder 1262a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) except ImportError: 1272a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) return None 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)_default_encoder = JSONEncoder( 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) skipkeys=False, 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ensure_ascii=True, 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) check_circular=True, 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) allow_nan=True, 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) indent=None, 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) separators=None, 1362a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encoding='utf-8', 1372a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) default=None, 1382a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) use_decimal=True, 1392a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) namedtuple_as_object=True, 1402a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) tuple_as_array=True, 1412a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) bigint_as_string=False, 1422a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) item_sort_key=None, 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)) 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) allow_nan=True, cls=None, indent=None, separators=None, 1472a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encoding='utf-8', default=None, use_decimal=True, 1482a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) namedtuple_as_object=True, tuple_as_array=True, 1492a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) bigint_as_string=False, sort_keys=False, item_sort_key=None, 1502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) **kw): 1512a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``.write()``-supporting file-like object). 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1542a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``skipkeys`` is true then ``dict`` keys that are not basic types 1552a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) will be skipped instead of raising a ``TypeError``. 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1582a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``ensure_ascii`` is false, then the some chunks written to ``fp`` 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) may be ``unicode`` instances, subject to normal Python ``str`` to 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``unicode`` coercion rules. Unless ``fp.write()`` explicitly 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) understands ``unicode`` (as in ``codecs.getwriter()``) this is likely 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) to cause an error. 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1642a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``check_circular`` is false, then the circular reference check 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) for container types will be skipped and a circular reference will 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) result in an ``OverflowError`` (or worse). 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1682a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``allow_nan`` is false, then it will be a ``ValueError`` to 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) in strict compliance of the JSON specification, instead of using the 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *indent* is a string, then JSON array elements and object members 1742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) will be pretty-printed with a newline followed by that string repeated 1752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) for each level of nesting. ``None`` (the default) selects the most compact 1762a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) representation without any newlines. For backwards compatibility with 1772a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) versions of simplejson earlier than 2.1.0, an integer is also accepted 1782a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) and is converted to a string with that many spaces. 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If ``separators`` is an ``(item_separator, dict_separator)`` tuple 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) then it will be used instead of the default ``(', ', ': ')`` separators. 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``(',', ':')`` is the most compact JSON representation. 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``encoding`` is the character encoding for str instances, default is UTF-8. 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1862a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ``default(obj)`` is a function that should return a serializable version 1872a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) of obj or raise TypeError. The default simply raises TypeError. 1882a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1892a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *use_decimal* is true (default: ``True``) then decimal.Decimal 1902a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) will be natively serialized to JSON with full precision. 1912a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1922a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *namedtuple_as_object* is true (default: ``True``), 1932a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) :class:`tuple` subclasses with ``_asdict()`` methods will be encoded 1942a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) as JSON objects. 1952a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1962a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *tuple_as_array* is true (default: ``True``), 1972a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) :class:`tuple` (and subclasses) will be encoded as JSON arrays. 1982a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 1992a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher 2002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) or lower than -2**53 will be encoded as strings. This is to avoid the 2012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) rounding that happens in Javascript otherwise. Note that this is still a 2022a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) lossy operation that will not round-trip correctly and should be used 2032a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) sparingly. 2042a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2052a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If specified, *item_sort_key* is a callable used to sort the items in 2062a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) each dictionary. This is useful if you want to sort items other than 2072a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) in alphabetical order by key. This option takes precedence over 2082a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *sort_keys*. 2092a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2102a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *sort_keys* is true (default: ``False``), the output of dictionaries 2112a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) will be sorted by item. 2122a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 2145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``.default()`` method to serialize additional types), specify it with 2155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) the ``cls`` kwarg. 2162a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """ 2185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) # cached encoder 2192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if (not skipkeys and ensure_ascii and 2202a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) check_circular and allow_nan and 2215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) cls is None and indent is None and separators is None and 2222a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encoding == 'utf-8' and default is None and use_decimal 2232a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) and namedtuple_as_object and tuple_as_array 2242a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) and not bigint_as_string and not item_sort_key and not kw): 2255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) iterable = _default_encoder.iterencode(obj) 2265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) else: 2275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) if cls is None: 2285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) cls = JSONEncoder 2295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii, 2305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) check_circular=check_circular, allow_nan=allow_nan, indent=indent, 2312a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) separators=separators, encoding=encoding, 2322a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) default=default, use_decimal=use_decimal, 2332a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) namedtuple_as_object=namedtuple_as_object, 2342a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) tuple_as_array=tuple_as_array, 2352a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) bigint_as_string=bigint_as_string, 2362a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) sort_keys=sort_keys, 2372a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) item_sort_key=item_sort_key, 2382a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) **kw).iterencode(obj) 2395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) # could accelerate with writelines in some versions of Python, at 2405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) # a debuggability cost 2415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) for chunk in iterable: 2425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) fp.write(chunk) 2435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, 2465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) allow_nan=True, cls=None, indent=None, separators=None, 2472a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encoding='utf-8', default=None, use_decimal=True, 2482a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) namedtuple_as_object=True, tuple_as_array=True, 2492a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) bigint_as_string=False, sort_keys=False, item_sort_key=None, 2502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) **kw): 2512a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) """Serialize ``obj`` to a JSON formatted ``str``. 2522a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2532a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``skipkeys`` is false then ``dict`` keys that are not basic types 2542a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) 2555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) will be skipped instead of raising a ``TypeError``. 2565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2572a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``ensure_ascii`` is false, then the return value will be a 2585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``unicode`` instance subject to normal Python ``str`` to ``unicode`` 2595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) coercion rules instead of being escaped to an ASCII ``str``. 2605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2612a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``check_circular`` is false, then the circular reference check 2625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) for container types will be skipped and a circular reference will 2635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) result in an ``OverflowError`` (or worse). 2645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2652a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``allow_nan`` is false, then it will be a ``ValueError`` to 2665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in 2675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) strict compliance of the JSON specification, instead of using the 2685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 2695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2702a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If ``indent`` is a string, then JSON array elements and object members 2712a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) will be pretty-printed with a newline followed by that string repeated 2722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) for each level of nesting. ``None`` (the default) selects the most compact 2732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) representation without any newlines. For backwards compatibility with 2742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) versions of simplejson earlier than 2.1.0, an integer is also accepted 2752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) and is converted to a string with that many spaces. 2765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) If ``separators`` is an ``(item_separator, dict_separator)`` tuple 2785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) then it will be used instead of the default ``(', ', ': ')`` separators. 2795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``(',', ':')`` is the most compact JSON representation. 2805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``encoding`` is the character encoding for str instances, default is UTF-8. 2825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 2832a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ``default(obj)`` is a function that should return a serializable version 2842a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) of obj or raise TypeError. The default simply raises TypeError. 2852a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2862a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *use_decimal* is true (default: ``True``) then decimal.Decimal 2872a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) will be natively serialized to JSON with full precision. 2882a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2892a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *namedtuple_as_object* is true (default: ``True``), 2902a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) :class:`tuple` subclasses with ``_asdict()`` methods will be encoded 2912a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) as JSON objects. 2922a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2932a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *tuple_as_array* is true (default: ``True``), 2942a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) :class:`tuple` (and subclasses) will be encoded as JSON arrays. 2952a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 2962a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *bigint_as_string* is true (not the default), ints 2**53 and higher 2972a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) or lower than -2**53 will be encoded as strings. This is to avoid the 2982a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) rounding that happens in Javascript otherwise. 2992a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If specified, *item_sort_key* is a callable used to sort the items in 3012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) each dictionary. This is useful if you want to sort items other than 3022a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) in alphabetical order by key. This option takes precendence over 3032a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *sort_keys*. 3042a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3052a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *sort_keys* is true (default: ``False``), the output of dictionaries 3062a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) will be sorted by item. 3072a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 3095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ``.default()`` method to serialize additional types), specify it with 3105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) the ``cls`` kwarg. 3112a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """ 3135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) # cached encoder 3142a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if (not skipkeys and ensure_ascii and 3152a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) check_circular and allow_nan and 3165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) cls is None and indent is None and separators is None and 3172a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encoding == 'utf-8' and default is None and use_decimal 3182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) and namedtuple_as_object and tuple_as_array 3192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) and not bigint_as_string and not sort_keys 3202a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) and not item_sort_key and not kw): 3215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return _default_encoder.encode(obj) 3225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) if cls is None: 3235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) cls = JSONEncoder 3245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return cls( 3255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) skipkeys=skipkeys, ensure_ascii=ensure_ascii, 3265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) check_circular=check_circular, allow_nan=allow_nan, indent=indent, 3272a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) separators=separators, encoding=encoding, default=default, 3282a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) use_decimal=use_decimal, 3292a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) namedtuple_as_object=namedtuple_as_object, 3302a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) tuple_as_array=tuple_as_array, 3312a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) bigint_as_string=bigint_as_string, 3322a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) sort_keys=sort_keys, 3332a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) item_sort_key=item_sort_key, 3345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) **kw).encode(obj) 3355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3372a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)_default_decoder = JSONDecoder(encoding=None, object_hook=None, 3382a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) object_pairs_hook=None) 3392a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3402a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3412a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None, 3422a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) parse_int=None, parse_constant=None, object_pairs_hook=None, 3432a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) use_decimal=False, namedtuple_as_object=True, tuple_as_array=True, 3442a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) **kw): 3452a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing 3465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) a JSON document) to a Python object. 3475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3482a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *encoding* determines the encoding used to interpret any 3492a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) :class:`str` objects decoded by this instance (``'utf-8'`` by 3502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) default). It has no effect when decoding :class:`unicode` objects. 3512a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3522a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) Note that currently only encodings that are a superset of ASCII work, 3532a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) strings of other encodings should be passed in as :class:`unicode`. 3542a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3552a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *object_hook*, if specified, will be called with the result of every 3562a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) JSON object decoded and its return value will be used in place of the 3572a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) given :class:`dict`. This can be used to provide custom 3582a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) deserializations (e.g. to support JSON-RPC class hinting). 3592a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3602a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *object_pairs_hook* is an optional function that will be called with 3612a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) the result of any object literal decode with an ordered list of pairs. 3622a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) The return value of *object_pairs_hook* will be used instead of the 3632a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) :class:`dict`. This feature can be used to implement custom decoders 3642a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) that rely on the order that the key and value pairs are decoded (for 3652a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) example, :func:`collections.OrderedDict` will remember the order of 3662a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) insertion). If *object_hook* is also defined, the *object_pairs_hook* 3672a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) takes priority. 3682a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3692a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *parse_float*, if specified, will be called with the string of every 3702a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) JSON float to be decoded. By default, this is equivalent to 3712a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ``float(num_str)``. This can be used to use another datatype or parser 3722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) for JSON floats (e.g. :class:`decimal.Decimal`). 3732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *parse_int*, if specified, will be called with the string of every 3752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) JSON int to be decoded. By default, this is equivalent to 3762a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ``int(num_str)``. This can be used to use another datatype or parser 3772a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) for JSON integers (e.g. :class:`float`). 3782a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3792a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *parse_constant*, if specified, will be called with one of the 3802a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This 3812a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) can be used to raise an exception if invalid JSON numbers are 3822a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encountered. 3832a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3842a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *use_decimal* is true (default: ``False``) then it implies 3852a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) parse_float=decimal.Decimal for parity with ``dump``. 3862a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 3885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kwarg. 3892a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 3905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """ 3915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return loads(fp.read(), 3922a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encoding=encoding, cls=cls, object_hook=object_hook, 3932a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) parse_float=parse_float, parse_int=parse_int, 3942a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, 3952a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) use_decimal=use_decimal, **kw) 3965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 3982a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, 3992a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) parse_int=None, parse_constant=None, object_pairs_hook=None, 4002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) use_decimal=False, **kw): 4012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON 4022a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) document) to a Python object. 4035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4042a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *encoding* determines the encoding used to interpret any 4052a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) :class:`str` objects decoded by this instance (``'utf-8'`` by 4062a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) default). It has no effect when decoding :class:`unicode` objects. 4072a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 4082a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) Note that currently only encodings that are a superset of ASCII work, 4092a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) strings of other encodings should be passed in as :class:`unicode`. 4102a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 4112a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *object_hook*, if specified, will be called with the result of every 4122a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) JSON object decoded and its return value will be used in place of the 4132a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) given :class:`dict`. This can be used to provide custom 4142a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) deserializations (e.g. to support JSON-RPC class hinting). 4152a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 4162a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *object_pairs_hook* is an optional function that will be called with 4172a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) the result of any object literal decode with an ordered list of pairs. 4182a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) The return value of *object_pairs_hook* will be used instead of the 4192a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) :class:`dict`. This feature can be used to implement custom decoders 4202a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) that rely on the order that the key and value pairs are decoded (for 4212a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) example, :func:`collections.OrderedDict` will remember the order of 4222a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) insertion). If *object_hook* is also defined, the *object_pairs_hook* 4232a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) takes priority. 4242a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 4252a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *parse_float*, if specified, will be called with the string of every 4262a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) JSON float to be decoded. By default, this is equivalent to 4272a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ``float(num_str)``. This can be used to use another datatype or parser 4282a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) for JSON floats (e.g. :class:`decimal.Decimal`). 4292a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 4302a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *parse_int*, if specified, will be called with the string of every 4312a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) JSON int to be decoded. By default, this is equivalent to 4322a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ``int(num_str)``. This can be used to use another datatype or parser 4332a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) for JSON integers (e.g. :class:`float`). 4342a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 4352a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) *parse_constant*, if specified, will be called with one of the 4362a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This 4372a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) can be used to raise an exception if invalid JSON numbers are 4382a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encountered. 4392a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 4402a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) If *use_decimal* is true (default: ``False``) then it implies 4412a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) parse_float=decimal.Decimal for parity with ``dump``. 4425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 4445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kwarg. 4452a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 4465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """ 4472a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if (cls is None and encoding is None and object_hook is None and 4482a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) parse_int is None and parse_float is None and 4492a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) parse_constant is None and object_pairs_hook is None 4502a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) and not use_decimal and not kw): 4515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return _default_decoder.decode(s) 4525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) if cls is None: 4535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) cls = JSONDecoder 4545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) if object_hook is not None: 4555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kw['object_hook'] = object_hook 4562a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if object_pairs_hook is not None: 4572a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) kw['object_pairs_hook'] = object_pairs_hook 4582a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if parse_float is not None: 4592a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) kw['parse_float'] = parse_float 4602a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if parse_int is not None: 4612a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) kw['parse_int'] = parse_int 4622a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if parse_constant is not None: 4632a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) kw['parse_constant'] = parse_constant 4642a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if use_decimal: 4652a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if parse_float is not None: 4662a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) raise TypeError("use_decimal=True implies parse_float=Decimal") 4672a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) kw['parse_float'] = Decimal 4685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return cls(encoding=encoding, **kw).decode(s) 4695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 4712a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)def _toggle_speedups(enabled): 4722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) import simplejson.decoder as dec 4732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) import simplejson.encoder as enc 4742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) import simplejson.scanner as scan 4752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) c_make_encoder = _import_c_make_encoder() 4762a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) if enabled: 4772a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) dec.scanstring = dec.c_scanstring or dec.py_scanstring 4782a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) enc.c_make_encoder = c_make_encoder 4792a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) enc.encode_basestring_ascii = (enc.c_encode_basestring_ascii or 4802a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) enc.py_encode_basestring_ascii) 4812a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) scan.make_scanner = scan.c_make_scanner or scan.py_make_scanner 4822a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) else: 4832a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) dec.scanstring = dec.py_scanstring 4842a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) enc.c_make_encoder = None 4852a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) enc.encode_basestring_ascii = enc.py_encode_basestring_ascii 4862a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) scan.make_scanner = scan.py_make_scanner 4872a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) dec.make_scanner = scan.make_scanner 4882a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) global _default_decoder 4892a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) _default_decoder = JSONDecoder( 4902a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encoding=None, 4912a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) object_hook=None, 4922a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) object_pairs_hook=None, 4932a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ) 4942a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) global _default_encoder 4952a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) _default_encoder = JSONEncoder( 4962a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) skipkeys=False, 4972a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ensure_ascii=True, 4982a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) check_circular=True, 4992a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) allow_nan=True, 5002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) indent=None, 5012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) separators=None, 5022a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) encoding='utf-8', 5032a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) default=None, 5042a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) ) 5052a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) 5062a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)def simple_first(kv): 5072a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) """Helper function to pass to item_sort_key to sort simple 5082a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) elements to the top, then container elements. 5095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """ 5102a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) return (isinstance(kv[1], (list, dict, tuple)), kv[0]) 511