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