1r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of
2JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data
3interchange format.
4
5:mod:`json` exposes an API familiar to users of the standard library
6:mod:`marshal` and :mod:`pickle` modules.  It is derived from a
7version of the externally maintained simplejson library.
8
9Encoding basic Python object hierarchies::
10
11    >>> import json
12    >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
13    '["foo", {"bar": ["baz", null, 1.0, 2]}]'
14    >>> print(json.dumps("\"foo\bar"))
15    "\"foo\bar"
16    >>> print(json.dumps('\u1234'))
17    "\u1234"
18    >>> print(json.dumps('\\'))
19    "\\"
20    >>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
21    {"a": 0, "b": 0, "c": 0}
22    >>> from io import StringIO
23    >>> io = StringIO()
24    >>> json.dump(['streaming API'], io)
25    >>> io.getvalue()
26    '["streaming API"]'
27
28Compact encoding::
29
30    >>> import json
31    >>> from collections import OrderedDict
32    >>> mydict = OrderedDict([('4', 5), ('6', 7)])
33    >>> json.dumps([1,2,3,mydict], separators=(',', ':'))
34    '[1,2,3,{"4":5,"6":7}]'
35
36Pretty printing::
37
38    >>> import json
39    >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))
40    {
41        "4": 5,
42        "6": 7
43    }
44
45Decoding JSON::
46
47    >>> import json
48    >>> obj = ['foo', {'bar': ['baz', None, 1.0, 2]}]
49    >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj
50    True
51    >>> json.loads('"\\"foo\\bar"') == '"foo\x08ar'
52    True
53    >>> from io import StringIO
54    >>> io = StringIO('["streaming API"]')
55    >>> json.load(io)[0] == 'streaming API'
56    True
57
58Specializing JSON object decoding::
59
60    >>> import json
61    >>> def as_complex(dct):
62    ...     if '__complex__' in dct:
63    ...         return complex(dct['real'], dct['imag'])
64    ...     return dct
65    ...
66    >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
67    ...     object_hook=as_complex)
68    (1+2j)
69    >>> from decimal import Decimal
70    >>> json.loads('1.1', parse_float=Decimal) == Decimal('1.1')
71    True
72
73Specializing JSON object encoding::
74
75    >>> import json
76    >>> def encode_complex(obj):
77    ...     if isinstance(obj, complex):
78    ...         return [obj.real, obj.imag]
79    ...     raise TypeError(repr(o) + " is not JSON serializable")
80    ...
81    >>> json.dumps(2 + 1j, default=encode_complex)
82    '[2.0, 1.0]'
83    >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j)
84    '[2.0, 1.0]'
85    >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j))
86    '[2.0, 1.0]'
87
88
89Using json.tool from the shell to validate and pretty-print::
90
91    $ echo '{"json":"obj"}' | python -m json.tool
92    {
93        "json": "obj"
94    }
95    $ echo '{ 1.2:3.4}' | python -m json.tool
96    Expecting property name enclosed in double quotes: line 1 column 3 (char 2)
97"""
98__version__ = '2.0.9'
99__all__ = [
100    'dump', 'dumps', 'load', 'loads',
101    'JSONDecoder', 'JSONDecodeError', 'JSONEncoder',
102]
103
104__author__ = 'Bob Ippolito <bob@redivi.com>'
105
106from .decoder import JSONDecoder, JSONDecodeError
107from .encoder import JSONEncoder
108import codecs
109
110_default_encoder = JSONEncoder(
111    skipkeys=False,
112    ensure_ascii=True,
113    check_circular=True,
114    allow_nan=True,
115    indent=None,
116    separators=None,
117    default=None,
118)
119
120def dump(obj, fp, *, skipkeys=False, ensure_ascii=True, check_circular=True,
121        allow_nan=True, cls=None, indent=None, separators=None,
122        default=None, sort_keys=False, **kw):
123    """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
124    ``.write()``-supporting file-like object).
125
126    If ``skipkeys`` is true then ``dict`` keys that are not basic types
127    (``str``, ``int``, ``float``, ``bool``, ``None``) will be skipped
128    instead of raising a ``TypeError``.
129
130    If ``ensure_ascii`` is false, then the strings written to ``fp`` can
131    contain non-ASCII characters if they appear in strings contained in
132    ``obj``. Otherwise, all such characters are escaped in JSON strings.
133
134    If ``check_circular`` is false, then the circular reference check
135    for container types will be skipped and a circular reference will
136    result in an ``OverflowError`` (or worse).
137
138    If ``allow_nan`` is false, then it will be a ``ValueError`` to
139    serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
140    in strict compliance of the JSON specification, instead of using the
141    JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
142
143    If ``indent`` is a non-negative integer, then JSON array elements and
144    object members will be pretty-printed with that indent level. An indent
145    level of 0 will only insert newlines. ``None`` is the most compact
146    representation.
147
148    If specified, ``separators`` should be an ``(item_separator, key_separator)``
149    tuple.  The default is ``(', ', ': ')`` if *indent* is ``None`` and
150    ``(',', ': ')`` otherwise.  To get the most compact JSON representation,
151    you should specify ``(',', ':')`` to eliminate whitespace.
152
153    ``default(obj)`` is a function that should return a serializable version
154    of obj or raise TypeError. The default simply raises TypeError.
155
156    If *sort_keys* is true (default: ``False``), then the output of
157    dictionaries will be sorted by key.
158
159    To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
160    ``.default()`` method to serialize additional types), specify it with
161    the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
162
163    """
164    # cached encoder
165    if (not skipkeys and ensure_ascii and
166        check_circular and allow_nan and
167        cls is None and indent is None and separators is None and
168        default is None and not sort_keys and not kw):
169        iterable = _default_encoder.iterencode(obj)
170    else:
171        if cls is None:
172            cls = JSONEncoder
173        iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
174            check_circular=check_circular, allow_nan=allow_nan, indent=indent,
175            separators=separators,
176            default=default, sort_keys=sort_keys, **kw).iterencode(obj)
177    # could accelerate with writelines in some versions of Python, at
178    # a debuggability cost
179    for chunk in iterable:
180        fp.write(chunk)
181
182
183def dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True,
184        allow_nan=True, cls=None, indent=None, separators=None,
185        default=None, sort_keys=False, **kw):
186    """Serialize ``obj`` to a JSON formatted ``str``.
187
188    If ``skipkeys`` is true then ``dict`` keys that are not basic types
189    (``str``, ``int``, ``float``, ``bool``, ``None``) will be skipped
190    instead of raising a ``TypeError``.
191
192    If ``ensure_ascii`` is false, then the return value can contain non-ASCII
193    characters if they appear in strings contained in ``obj``. Otherwise, all
194    such characters are escaped in JSON strings.
195
196    If ``check_circular`` is false, then the circular reference check
197    for container types will be skipped and a circular reference will
198    result in an ``OverflowError`` (or worse).
199
200    If ``allow_nan`` is false, then it will be a ``ValueError`` to
201    serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
202    strict compliance of the JSON specification, instead of using the
203    JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
204
205    If ``indent`` is a non-negative integer, then JSON array elements and
206    object members will be pretty-printed with that indent level. An indent
207    level of 0 will only insert newlines. ``None`` is the most compact
208    representation.
209
210    If specified, ``separators`` should be an ``(item_separator, key_separator)``
211    tuple.  The default is ``(', ', ': ')`` if *indent* is ``None`` and
212    ``(',', ': ')`` otherwise.  To get the most compact JSON representation,
213    you should specify ``(',', ':')`` to eliminate whitespace.
214
215    ``default(obj)`` is a function that should return a serializable version
216    of obj or raise TypeError. The default simply raises TypeError.
217
218    If *sort_keys* is true (default: ``False``), then the output of
219    dictionaries will be sorted by key.
220
221    To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
222    ``.default()`` method to serialize additional types), specify it with
223    the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
224
225    """
226    # cached encoder
227    if (not skipkeys and ensure_ascii and
228        check_circular and allow_nan and
229        cls is None and indent is None and separators is None and
230        default is None and not sort_keys and not kw):
231        return _default_encoder.encode(obj)
232    if cls is None:
233        cls = JSONEncoder
234    return cls(
235        skipkeys=skipkeys, ensure_ascii=ensure_ascii,
236        check_circular=check_circular, allow_nan=allow_nan, indent=indent,
237        separators=separators, default=default, sort_keys=sort_keys,
238        **kw).encode(obj)
239
240
241_default_decoder = JSONDecoder(object_hook=None, object_pairs_hook=None)
242
243
244def detect_encoding(b):
245    bstartswith = b.startswith
246    if bstartswith((codecs.BOM_UTF32_BE, codecs.BOM_UTF32_LE)):
247        return 'utf-32'
248    if bstartswith((codecs.BOM_UTF16_BE, codecs.BOM_UTF16_LE)):
249        return 'utf-16'
250    if bstartswith(codecs.BOM_UTF8):
251        return 'utf-8-sig'
252
253    if len(b) >= 4:
254        if not b[0]:
255            # 00 00 -- -- - utf-32-be
256            # 00 XX -- -- - utf-16-be
257            return 'utf-16-be' if b[1] else 'utf-32-be'
258        if not b[1]:
259            # XX 00 00 00 - utf-32-le
260            # XX 00 00 XX - utf-16-le
261            # XX 00 XX -- - utf-16-le
262            return 'utf-16-le' if b[2] or b[3] else 'utf-32-le'
263    elif len(b) == 2:
264        if not b[0]:
265            # 00 XX - utf-16-be
266            return 'utf-16-be'
267        if not b[1]:
268            # XX 00 - utf-16-le
269            return 'utf-16-le'
270    # default
271    return 'utf-8'
272
273
274def load(fp, *, cls=None, object_hook=None, parse_float=None,
275        parse_int=None, parse_constant=None, object_pairs_hook=None, **kw):
276    """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
277    a JSON document) to a Python object.
278
279    ``object_hook`` is an optional function that will be called with the
280    result of any object literal decode (a ``dict``). The return value of
281    ``object_hook`` will be used instead of the ``dict``. This feature
282    can be used to implement custom decoders (e.g. JSON-RPC class hinting).
283
284    ``object_pairs_hook`` is an optional function that will be called with the
285    result of any object literal decoded with an ordered list of pairs.  The
286    return value of ``object_pairs_hook`` will be used instead of the ``dict``.
287    This feature can be used to implement custom decoders that rely on the
288    order that the key and value pairs are decoded (for example,
289    collections.OrderedDict will remember the order of insertion). If
290    ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority.
291
292    To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
293    kwarg; otherwise ``JSONDecoder`` is used.
294
295    """
296    return loads(fp.read(),
297        cls=cls, object_hook=object_hook,
298        parse_float=parse_float, parse_int=parse_int,
299        parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, **kw)
300
301
302def loads(s, *, encoding=None, cls=None, object_hook=None, parse_float=None,
303        parse_int=None, parse_constant=None, object_pairs_hook=None, **kw):
304    """Deserialize ``s`` (a ``str``, ``bytes`` or ``bytearray`` instance
305    containing a JSON document) to a Python object.
306
307    ``object_hook`` is an optional function that will be called with the
308    result of any object literal decode (a ``dict``). The return value of
309    ``object_hook`` will be used instead of the ``dict``. This feature
310    can be used to implement custom decoders (e.g. JSON-RPC class hinting).
311
312    ``object_pairs_hook`` is an optional function that will be called with the
313    result of any object literal decoded with an ordered list of pairs.  The
314    return value of ``object_pairs_hook`` will be used instead of the ``dict``.
315    This feature can be used to implement custom decoders that rely on the
316    order that the key and value pairs are decoded (for example,
317    collections.OrderedDict will remember the order of insertion). If
318    ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority.
319
320    ``parse_float``, if specified, will be called with the string
321    of every JSON float to be decoded. By default this is equivalent to
322    float(num_str). This can be used to use another datatype or parser
323    for JSON floats (e.g. decimal.Decimal).
324
325    ``parse_int``, if specified, will be called with the string
326    of every JSON int to be decoded. By default this is equivalent to
327    int(num_str). This can be used to use another datatype or parser
328    for JSON integers (e.g. float).
329
330    ``parse_constant``, if specified, will be called with one of the
331    following strings: -Infinity, Infinity, NaN.
332    This can be used to raise an exception if invalid JSON numbers
333    are encountered.
334
335    To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
336    kwarg; otherwise ``JSONDecoder`` is used.
337
338    The ``encoding`` argument is ignored and deprecated.
339
340    """
341    if isinstance(s, str):
342        if s.startswith('\ufeff'):
343            raise JSONDecodeError("Unexpected UTF-8 BOM (decode using utf-8-sig)",
344                                  s, 0)
345    else:
346        if not isinstance(s, (bytes, bytearray)):
347            raise TypeError('the JSON object must be str, bytes or bytearray, '
348                            'not {!r}'.format(s.__class__.__name__))
349        s = s.decode(detect_encoding(s), 'surrogatepass')
350
351    if (cls is None and object_hook is None and
352            parse_int is None and parse_float is None and
353            parse_constant is None and object_pairs_hook is None and not kw):
354        return _default_decoder.decode(s)
355    if cls is None:
356        cls = JSONDecoder
357    if object_hook is not None:
358        kw['object_hook'] = object_hook
359    if object_pairs_hook is not None:
360        kw['object_pairs_hook'] = object_pairs_hook
361    if parse_float is not None:
362        kw['parse_float'] = parse_float
363    if parse_int is not None:
364        kw['parse_int'] = parse_int
365    if parse_constant is not None:
366        kw['parse_constant'] = parse_constant
367    return cls(**kw).decode(s)
368