python模块：json

1 r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of
2 JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data
3 interchange 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
7 version of the externally maintained simplejson library.
8
9 Encoding 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
28 Compact 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
36 Pretty 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
45 Decoding 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
58 Specializing 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
73 Specializing 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(obj) + " 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
89 Using 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
106 from .decoder import JSONDecoder, JSONDecodeError
107 from .encoder import JSONEncoder
108 import 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
120 def 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
183 def 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
244 def 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
274 def 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
302 def 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)