Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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.
5:mod:`simplejson` 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+, supporting
8Python 2.7 and Python 3.8+, and has significant performance advantages,
9even without using the optional C extension for speedups.
11Encoding basic Python object hierarchies::
13 >>> import simplejson as json
14 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
15 '["foo", {"bar": ["baz", null, 1.0, 2]}]'
16 >>> print(json.dumps("\"foo\bar"))
17 "\"foo\bar"
18 >>> print(json.dumps(u'\u1234'))
19 "\u1234"
20 >>> print(json.dumps('\\'))
21 "\\"
22 >>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
23 {"a": 0, "b": 0, "c": 0}
24 >>> from simplejson.compat import StringIO
25 >>> io = StringIO()
26 >>> json.dump(['streaming API'], io)
27 >>> io.getvalue()
28 '["streaming API"]'
30Compact encoding::
32 >>> import simplejson as json
33 >>> obj = [1,2,3,{'4': 5, '6': 7}]
34 >>> json.dumps(obj, separators=(',',':'), sort_keys=True)
35 '[1,2,3,{"4":5,"6":7}]'
37Pretty printing::
39 >>> import simplejson as json
40 >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=' '))
41 {
42 "4": 5,
43 "6": 7
44 }
46Decoding JSON::
48 >>> import simplejson as json
49 >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
50 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj
51 True
52 >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar'
53 True
54 >>> from simplejson.compat import StringIO
55 >>> io = StringIO('["streaming API"]')
56 >>> json.load(io)[0] == 'streaming API'
57 True
59Specializing JSON object decoding::
61 >>> import simplejson as json
62 >>> def as_complex(dct):
63 ... if '__complex__' in dct:
64 ... return complex(dct['real'], dct['imag'])
65 ... return dct
66 ...
67 >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
68 ... object_hook=as_complex)
69 (1+2j)
70 >>> from decimal import Decimal
71 >>> json.loads('1.1', parse_float=Decimal) == Decimal('1.1')
72 True
74Specializing JSON object encoding::
76 >>> import simplejson as json
77 >>> def encode_complex(obj):
78 ... if isinstance(obj, complex):
79 ... return [obj.real, obj.imag]
80 ... raise TypeError('Object of type %s is not JSON serializable' %
81 ... obj.__class__.__name__)
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]'
90Using simplejson.tool from the shell to validate and pretty-print::
92 $ echo '{"json":"obj"}' | python -m simplejson.tool
93 {
94 "json": "obj"
95 }
96 $ echo '{ 1.2:3.4}' | python -m simplejson.tool
97 Expecting property name: line 1 column 3 (char 2)
99Parsing multiple documents serialized as JSON lines (newline-delimited JSON)::
101 >>> import simplejson as json
102 >>> def loads_lines(docs):
103 ... for doc in docs.splitlines():
104 ... yield json.loads(doc)
105 ...
106 >>> sum(doc["count"] for doc in loads_lines('{"count":1}\n{"count":2}\n{"count":3}\n'))
107 6
109Serializing multiple objects to JSON lines (newline-delimited JSON)::
111 >>> import simplejson as json
112 >>> def dumps_lines(objs):
113 ... for obj in objs:
114 ... yield json.dumps(obj, separators=(',',':')) + '\n'
115 ...
116 >>> ''.join(dumps_lines([{'count': 1}, {'count': 2}, {'count': 3}]))
117 '{"count":1}\n{"count":2}\n{"count":3}\n'
119"""
120from __future__ import absolute_import
121__version__ = '4.1.1'
122__all__ = [
123 'dump', 'dumps', 'load', 'loads',
124 'JSONDecoder', 'JSONDecodeError', 'JSONEncoder',
125 'OrderedDict', 'simple_first', 'RawJSON'
126]
128__author__ = 'Bob Ippolito <bob@redivi.com>'
130from decimal import Decimal
132from .errors import JSONDecodeError
133from .raw_json import RawJSON
134from .decoder import JSONDecoder
135from .encoder import JSONEncoder, JSONEncoderForHTML
137def _import_OrderedDict():
138 import collections
139 try:
140 return collections.OrderedDict
141 except AttributeError:
142 from . import ordered_dict
143 return ordered_dict.OrderedDict
144OrderedDict = _import_OrderedDict()
146def _import_c_make_encoder():
147 try:
148 from ._speedups import make_encoder
149 return make_encoder
150 except ImportError:
151 return None
153_default_encoder = JSONEncoder()
155def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
156 allow_nan=False, cls=None, indent=None, separators=None,
157 encoding='utf-8', default=None, use_decimal=True,
158 namedtuple_as_object=True, tuple_as_array=True,
159 bigint_as_string=False, sort_keys=False, item_sort_key=None,
160 for_json=False, ignore_nan=False, int_as_string_bitcount=None,
161 iterable_as_array=False, **kw):
162 """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
163 ``.write()``-supporting file-like object).
165 If *skipkeys* is true then ``dict`` keys that are not basic types
166 (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``)
167 will be skipped instead of raising a ``TypeError``.
169 If *ensure_ascii* is false (default: ``True``), then the output may
170 contain non-ASCII characters, so long as they do not need to be escaped
171 by JSON. When it is true, all non-ASCII characters are escaped.
173 If *allow_nan* is true (default: ``False``), then out of range ``float``
174 values (``nan``, ``inf``, ``-inf``) will be serialized to
175 their JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``)
176 instead of raising a ValueError. See
177 *ignore_nan* for ECMA-262 compliant behavior.
179 If *indent* is a string, then JSON array elements and object members
180 will be pretty-printed with a newline followed by that string repeated
181 for each level of nesting. ``None`` (the default) selects the most compact
182 representation without any newlines.
184 If specified, *separators* should be an
185 ``(item_separator, key_separator)`` tuple. The default is ``(', ', ': ')``
186 if *indent* is ``None`` and ``(',', ': ')`` otherwise. To get the most
187 compact JSON representation, you should specify ``(',', ':')`` to eliminate
188 whitespace.
190 *encoding* is the character encoding for str instances, default is UTF-8.
192 *default(obj)* is a function that should return a serializable version
193 of obj or raise ``TypeError``. The default simply raises ``TypeError``.
195 If *use_decimal* is true (default: ``True``) then decimal.Decimal
196 will be natively serialized to JSON with full precision.
198 If *namedtuple_as_object* is true (default: ``True``),
199 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
200 as JSON objects.
202 If *tuple_as_array* is true (default: ``True``),
203 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
205 If *iterable_as_array* is true (default: ``False``),
206 any object not in the above table that implements ``__iter__()``
207 will be encoded as a JSON array.
209 If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher
210 or lower than -2**53 will be encoded as strings. This is to avoid the
211 rounding that happens in Javascript otherwise. Note that this is still a
212 lossy operation that will not round-trip correctly and should be used
213 sparingly.
215 If *int_as_string_bitcount* is a positive number (n), then int of size
216 greater than or equal to 2**n or lower than or equal to -2**n will be
217 encoded as strings.
219 If specified, *item_sort_key* is a callable used to sort the items in
220 each dictionary. This is useful if you want to sort items other than
221 in alphabetical order by key. This option takes precedence over
222 *sort_keys*.
224 If *sort_keys* is true (default: ``False``), the output of dictionaries
225 will be sorted by item.
227 If *for_json* is true (default: ``False``), objects with a ``for_json()``
228 method will use the return value of that method for encoding as JSON
229 instead of the object.
231 If *ignore_nan* is true (default: ``False``), then out of range
232 :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as
233 ``null`` in compliance with the ECMA-262 specification. If true, this will
234 override *allow_nan*.
236 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
237 ``.default()`` method to serialize additional types), specify it with
238 the ``cls`` kwarg. NOTE: You should use *default* or *for_json* instead
239 of subclassing whenever possible.
241 """
242 # cached encoder
243 if (not skipkeys and ensure_ascii and
244 check_circular and not allow_nan and
245 cls is None and indent is None and separators is None and
246 encoding == 'utf-8' and default is None and use_decimal
247 and namedtuple_as_object and tuple_as_array and not iterable_as_array
248 and not bigint_as_string and not sort_keys
249 and not item_sort_key and not for_json
250 and not ignore_nan and int_as_string_bitcount is None
251 and not kw
252 ):
253 iterable = _default_encoder.iterencode(obj)
254 else:
255 if cls is None:
256 cls = JSONEncoder
257 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
258 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
259 separators=separators, encoding=encoding,
260 default=default, use_decimal=use_decimal,
261 namedtuple_as_object=namedtuple_as_object,
262 tuple_as_array=tuple_as_array,
263 iterable_as_array=iterable_as_array,
264 bigint_as_string=bigint_as_string,
265 sort_keys=sort_keys,
266 item_sort_key=item_sort_key,
267 for_json=for_json,
268 ignore_nan=ignore_nan,
269 int_as_string_bitcount=int_as_string_bitcount,
270 **kw).iterencode(obj)
271 # could accelerate with writelines in some versions of Python, at
272 # a debuggability cost
273 for chunk in iterable:
274 fp.write(chunk)
277def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
278 allow_nan=False, cls=None, indent=None, separators=None,
279 encoding='utf-8', default=None, use_decimal=True,
280 namedtuple_as_object=True, tuple_as_array=True,
281 bigint_as_string=False, sort_keys=False, item_sort_key=None,
282 for_json=False, ignore_nan=False, int_as_string_bitcount=None,
283 iterable_as_array=False, **kw):
284 """Serialize ``obj`` to a JSON formatted ``str``.
286 If ``skipkeys`` is true then ``dict`` keys that are not basic types
287 (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``)
288 will be skipped instead of raising a ``TypeError``.
290 If *ensure_ascii* is false (default: ``True``), then the output may
291 contain non-ASCII characters, so long as they do not need to be escaped
292 by JSON. When it is true, all non-ASCII characters are escaped.
294 If ``check_circular`` is false, then the circular reference check
295 for container types will be skipped and a circular reference will
296 result in an ``OverflowError`` (or worse).
298 If *allow_nan* is true (default: ``False``), then out of range ``float``
299 values (``nan``, ``inf``, ``-inf``) will be serialized to
300 their JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``)
301 instead of raising a ValueError. See
302 *ignore_nan* for ECMA-262 compliant behavior.
304 If ``indent`` is a string, then JSON array elements and object members
305 will be pretty-printed with a newline followed by that string repeated
306 for each level of nesting. ``None`` (the default) selects the most compact
307 representation without any newlines. For backwards compatibility with
308 versions of simplejson earlier than 2.1.0, an integer is also accepted
309 and is converted to a string with that many spaces.
311 If specified, ``separators`` should be an
312 ``(item_separator, key_separator)`` tuple. The default is ``(', ', ': ')``
313 if *indent* is ``None`` and ``(',', ': ')`` otherwise. To get the most
314 compact JSON representation, you should specify ``(',', ':')`` to eliminate
315 whitespace.
317 ``encoding`` is the character encoding for bytes instances, default is
318 UTF-8.
320 ``default(obj)`` is a function that should return a serializable version
321 of obj or raise TypeError. The default simply raises TypeError.
323 If *use_decimal* is true (default: ``True``) then decimal.Decimal
324 will be natively serialized to JSON with full precision.
326 If *namedtuple_as_object* is true (default: ``True``),
327 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
328 as JSON objects.
330 If *tuple_as_array* is true (default: ``True``),
331 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
333 If *iterable_as_array* is true (default: ``False``),
334 any object not in the above table that implements ``__iter__()``
335 will be encoded as a JSON array.
337 If *bigint_as_string* is true (not the default), ints 2**53 and higher
338 or lower than -2**53 will be encoded as strings. This is to avoid the
339 rounding that happens in Javascript otherwise.
341 If *int_as_string_bitcount* is a positive number (n), then int of size
342 greater than or equal to 2**n or lower than or equal to -2**n will be
343 encoded as strings.
345 If specified, *item_sort_key* is a callable used to sort the items in
346 each dictionary. This is useful if you want to sort items other than
347 in alphabetical order by key. This option takes precedence over
348 *sort_keys*.
350 If *sort_keys* is true (default: ``False``), the output of dictionaries
351 will be sorted by item.
353 If *for_json* is true (default: ``False``), objects with a ``for_json()``
354 method will use the return value of that method for encoding as JSON
355 instead of the object.
357 If *ignore_nan* is true (default: ``False``), then out of range
358 :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as
359 ``null`` in compliance with the ECMA-262 specification. If true, this will
360 override *allow_nan*.
362 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
363 ``.default()`` method to serialize additional types), specify it with
364 the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
365 whenever possible.
367 """
368 # cached encoder
369 if (not skipkeys and ensure_ascii and
370 check_circular and not allow_nan and
371 cls is None and indent is None and separators is None and
372 encoding == 'utf-8' and default is None and use_decimal
373 and namedtuple_as_object and tuple_as_array and not iterable_as_array
374 and not bigint_as_string and not sort_keys
375 and not item_sort_key and not for_json
376 and not ignore_nan and int_as_string_bitcount is None
377 and not kw
378 ):
379 return _default_encoder.encode(obj)
380 if cls is None:
381 cls = JSONEncoder
382 return cls(
383 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
384 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
385 separators=separators, encoding=encoding, default=default,
386 use_decimal=use_decimal,
387 namedtuple_as_object=namedtuple_as_object,
388 tuple_as_array=tuple_as_array,
389 iterable_as_array=iterable_as_array,
390 bigint_as_string=bigint_as_string,
391 sort_keys=sort_keys,
392 item_sort_key=item_sort_key,
393 for_json=for_json,
394 ignore_nan=ignore_nan,
395 int_as_string_bitcount=int_as_string_bitcount,
396 **kw).encode(obj)
399_default_decoder = JSONDecoder()
402def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
403 parse_int=None, parse_constant=None, object_pairs_hook=None,
404 use_decimal=False, allow_nan=False, array_hook=None, **kw):
405 """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
406 a JSON document as `str` or `bytes`) to a Python object.
408 *encoding* determines the encoding used to interpret any
409 `bytes` objects decoded by this instance (``'utf-8'`` by
410 default). It has no effect when decoding `str` objects.
412 *object_hook*, if specified, will be called with the result of every
413 JSON object decoded and its return value will be used in place of the
414 given :class:`dict`. This can be used to provide custom
415 deserializations (e.g. to support JSON-RPC class hinting).
417 *object_pairs_hook* is an optional function that will be called with
418 the result of any object literal decode with an ordered list of pairs.
419 The return value of *object_pairs_hook* will be used instead of the
420 :class:`dict`. This feature can be used to implement custom decoders
421 that rely on the order that the key and value pairs are decoded (for
422 example, :func:`collections.OrderedDict` will remember the order of
423 insertion). If *object_hook* is also defined, the *object_pairs_hook*
424 takes priority.
426 *parse_float*, if specified, will be called with the string of every
427 JSON float to be decoded. By default, this is equivalent to
428 ``float(num_str)``. This can be used to use another datatype or parser
429 for JSON floats (e.g. :class:`decimal.Decimal`).
431 *parse_int*, if specified, will be called with the string of every
432 JSON int to be decoded. By default, this is equivalent to
433 ``int(num_str)``. This can be used to use another datatype or parser
434 for JSON integers (e.g. :class:`float`).
436 *allow_nan*, if True (default false), will allow the parser to
437 accept the non-standard floats ``NaN``, ``Infinity``, and ``-Infinity``
438 and enable the use of the deprecated *parse_constant*.
440 If *use_decimal* is true (default: ``False``) then it implies
441 parse_float=decimal.Decimal for parity with ``dump``.
443 *parse_constant*, if specified, will be
444 called with one of the following strings: ``'-Infinity'``,
445 ``'Infinity'``, ``'NaN'``. It is not recommended to use this feature,
446 as it is rare to parse non-compliant JSON containing these values.
448 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
449 kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
450 of subclassing whenever possible.
452 """
453 return loads(fp.read(),
454 encoding=encoding, cls=cls, object_hook=object_hook,
455 parse_float=parse_float, parse_int=parse_int,
456 parse_constant=parse_constant, object_pairs_hook=object_pairs_hook,
457 use_decimal=use_decimal, allow_nan=allow_nan,
458 array_hook=array_hook, **kw)
461def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
462 parse_int=None, parse_constant=None, object_pairs_hook=None,
463 use_decimal=False, allow_nan=False, array_hook=None, **kw):
464 """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
465 document) to a Python object.
467 *encoding* determines the encoding used to interpret any
468 :class:`bytes` objects decoded by this instance (``'utf-8'`` by
469 default). It has no effect when decoding :class:`unicode` objects.
471 *object_hook*, if specified, will be called with the result of every
472 JSON object decoded and its return value will be used in place of the
473 given :class:`dict`. This can be used to provide custom
474 deserializations (e.g. to support JSON-RPC class hinting).
476 *object_pairs_hook* is an optional function that will be called with
477 the result of any object literal decode with an ordered list of pairs.
478 The return value of *object_pairs_hook* will be used instead of the
479 :class:`dict`. This feature can be used to implement custom decoders
480 that rely on the order that the key and value pairs are decoded (for
481 example, :func:`collections.OrderedDict` will remember the order of
482 insertion). If *object_hook* is also defined, the *object_pairs_hook*
483 takes priority.
485 *parse_float*, if specified, will be called with the string of every
486 JSON float to be decoded. By default, this is equivalent to
487 ``float(num_str)``. This can be used to use another datatype or parser
488 for JSON floats (e.g. :class:`decimal.Decimal`).
490 *parse_int*, if specified, will be called with the string of every
491 JSON int to be decoded. By default, this is equivalent to
492 ``int(num_str)``. This can be used to use another datatype or parser
493 for JSON integers (e.g. :class:`float`).
495 *allow_nan*, if True (default false), will allow the parser to
496 accept the non-standard floats ``NaN``, ``Infinity``, and ``-Infinity``
497 and enable the use of the deprecated *parse_constant*.
499 If *use_decimal* is true (default: ``False``) then it implies
500 parse_float=decimal.Decimal for parity with ``dump``.
502 *parse_constant*, if specified, will be
503 called with one of the following strings: ``'-Infinity'``,
504 ``'Infinity'``, ``'NaN'``. It is not recommended to use this feature,
505 as it is rare to parse non-compliant JSON containing these values.
507 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
508 kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
509 of subclassing whenever possible.
511 """
512 if (cls is None and encoding is None and object_hook is None and
513 parse_int is None and parse_float is None and
514 parse_constant is None and object_pairs_hook is None
515 and array_hook is None
516 and not use_decimal and not allow_nan and not kw):
517 return _default_decoder.decode(s)
518 if cls is None:
519 cls = JSONDecoder
520 if object_hook is not None:
521 kw['object_hook'] = object_hook
522 if object_pairs_hook is not None:
523 kw['object_pairs_hook'] = object_pairs_hook
524 if array_hook is not None:
525 kw['array_hook'] = array_hook
526 if parse_float is not None:
527 kw['parse_float'] = parse_float
528 if parse_int is not None:
529 kw['parse_int'] = parse_int
530 if parse_constant is not None:
531 kw['parse_constant'] = parse_constant
532 if use_decimal:
533 if parse_float is not None:
534 raise TypeError("use_decimal=True implies parse_float=Decimal")
535 kw['parse_float'] = Decimal
536 if allow_nan:
537 kw['allow_nan'] = True
538 return cls(encoding=encoding, **kw).decode(s)
541def _toggle_speedups(enabled):
542 from . import decoder as dec
543 from . import encoder as enc
544 from . import scanner as scan
545 c_make_encoder = _import_c_make_encoder()
546 if enabled:
547 dec.scanstring = dec.c_scanstring or dec.py_scanstring
548 enc.c_make_encoder = c_make_encoder
549 enc.encode_basestring_ascii = (enc.c_encode_basestring_ascii or
550 enc.py_encode_basestring_ascii)
551 enc.encode_basestring = (enc.c_encode_basestring or
552 enc.py_encode_basestring)
553 scan.make_scanner = scan.c_make_scanner or scan.py_make_scanner
554 else:
555 dec.scanstring = dec.py_scanstring
556 enc.c_make_encoder = None
557 enc.encode_basestring_ascii = enc.py_encode_basestring_ascii
558 enc.encode_basestring = enc.py_encode_basestring
559 scan.make_scanner = scan.py_make_scanner
560 dec.make_scanner = scan.make_scanner
561 global _default_decoder
562 _default_decoder = JSONDecoder()
563 global _default_encoder
564 _default_encoder = JSONEncoder()
566def simple_first(kv):
567 """Helper function to pass to item_sort_key to sort simple
568 elements to the top, then container elements.
569 """
570 return (isinstance(kv[1], (list, dict, tuple)), kv[0])