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