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.9+, 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.2.0'
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 item_sort_key is None 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 (including iterables encoded with
296 ``iterable_as_array``) will be skipped and a circular reference will
297 result in a ``RecursionError`` (``RuntimeError`` on Python 2) or worse.
299 If *allow_nan* is true (default: ``False``), then out of range ``float``
300 values (``nan``, ``inf``, ``-inf``) will be serialized to
301 their JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``)
302 instead of raising a ValueError. See
303 *ignore_nan* for ECMA-262 compliant behavior.
305 If ``indent`` is a string, then JSON array elements and object members
306 will be pretty-printed with a newline followed by that string repeated
307 for each level of nesting. ``None`` (the default) selects the most compact
308 representation without any newlines. For backwards compatibility with
309 versions of simplejson earlier than 2.1.0, an integer is also accepted
310 and is converted to a string with that many spaces.
312 If specified, ``separators`` should be an
313 ``(item_separator, key_separator)`` tuple. The default is ``(', ', ': ')``
314 if *indent* is ``None`` and ``(',', ': ')`` otherwise. To get the most
315 compact JSON representation, you should specify ``(',', ':')`` to eliminate
316 whitespace.
318 ``encoding`` is the character encoding for bytes instances, default is
319 UTF-8.
321 ``default(obj)`` is a function that should return a serializable version
322 of obj or raise TypeError. The default simply raises TypeError.
324 If *use_decimal* is true (default: ``True``) then decimal.Decimal
325 will be natively serialized to JSON with full precision.
327 If *namedtuple_as_object* is true (default: ``True``),
328 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
329 as JSON objects.
331 If *tuple_as_array* is true (default: ``True``),
332 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
334 If *iterable_as_array* is true (default: ``False``),
335 any object not in the above table that implements ``__iter__()``
336 will be encoded as a JSON array.
338 If *bigint_as_string* is true (not the default), ints 2**53 and higher
339 or lower than -2**53 will be encoded as strings. This is to avoid the
340 rounding that happens in Javascript otherwise.
342 If *int_as_string_bitcount* is a positive number (n), then int of size
343 greater than or equal to 2**n or lower than or equal to -2**n will be
344 encoded as strings.
346 If specified, *item_sort_key* is a callable used to sort the items in
347 each dictionary. This is useful if you want to sort items other than
348 in alphabetical order by key. This option takes precedence over
349 *sort_keys*.
351 If *sort_keys* is true (default: ``False``), the output of dictionaries
352 will be sorted by item.
354 If *for_json* is true (default: ``False``), objects with a ``for_json()``
355 method will use the return value of that method for encoding as JSON
356 instead of the object.
358 If *ignore_nan* is true (default: ``False``), then out of range
359 :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as
360 ``null`` in compliance with the ECMA-262 specification. If true, this will
361 override *allow_nan*.
363 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
364 ``.default()`` method to serialize additional types), specify it with
365 the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
366 whenever possible.
368 """
369 # cached encoder
370 if (not skipkeys and ensure_ascii and
371 check_circular and not allow_nan and
372 cls is None and indent is None and separators is None and
373 encoding == 'utf-8' and default is None and use_decimal
374 and namedtuple_as_object and tuple_as_array and not iterable_as_array
375 and not bigint_as_string and not sort_keys
376 and item_sort_key is None and not for_json
377 and not ignore_nan and int_as_string_bitcount is None
378 and not kw
379 ):
380 return _default_encoder.encode(obj)
381 if cls is None:
382 cls = JSONEncoder
383 return cls(
384 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
385 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
386 separators=separators, encoding=encoding, default=default,
387 use_decimal=use_decimal,
388 namedtuple_as_object=namedtuple_as_object,
389 tuple_as_array=tuple_as_array,
390 iterable_as_array=iterable_as_array,
391 bigint_as_string=bigint_as_string,
392 sort_keys=sort_keys,
393 item_sort_key=item_sort_key,
394 for_json=for_json,
395 ignore_nan=ignore_nan,
396 int_as_string_bitcount=int_as_string_bitcount,
397 **kw).encode(obj)
400_default_decoder = JSONDecoder()
403def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
404 parse_int=None, parse_constant=None, object_pairs_hook=None,
405 use_decimal=False, allow_nan=False, array_hook=None, **kw):
406 """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
407 a JSON document as `str` or `bytes`) to a Python object.
409 *encoding* determines the encoding used to interpret any
410 `bytes` objects decoded by this instance (``'utf-8'`` by
411 default). It has no effect when decoding `str` objects.
413 *object_hook*, if specified, will be called with the result of every
414 JSON object decoded and its return value will be used in place of the
415 given :class:`dict`. This can be used to provide custom
416 deserializations (e.g. to support JSON-RPC class hinting).
418 *object_pairs_hook* is an optional function that will be called with
419 the result of any object literal decode with an ordered list of pairs.
420 The return value of *object_pairs_hook* will be used instead of the
421 :class:`dict`. This feature can be used to implement custom decoders
422 that rely on the order that the key and value pairs are decoded (for
423 example, :func:`collections.OrderedDict` will remember the order of
424 insertion). If *object_hook* is also defined, the *object_pairs_hook*
425 takes priority.
427 *parse_float*, if specified, will be called with the string of every
428 JSON float to be decoded. By default, this is equivalent to
429 ``float(num_str)``. This can be used to use another datatype or parser
430 for JSON floats (e.g. :class:`decimal.Decimal`).
432 *parse_int*, if specified, will be called with the string of every
433 JSON int to be decoded. By default, this is equivalent to
434 ``int(num_str)``. This can be used to use another datatype or parser
435 for JSON integers (e.g. :class:`float`).
437 *allow_nan*, if True (default false), will allow the parser to
438 accept the non-standard floats ``NaN``, ``Infinity``, and ``-Infinity``
439 and enable the use of the deprecated *parse_constant*.
441 If *use_decimal* is true (default: ``False``) then it implies
442 parse_float=decimal.Decimal for parity with ``dump``.
444 *parse_constant*, if specified, will be
445 called with one of the following strings: ``'-Infinity'``,
446 ``'Infinity'``, ``'NaN'``. It is not recommended to use this feature,
447 as it is rare to parse non-compliant JSON containing these values.
449 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
450 kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
451 of subclassing whenever possible.
453 """
454 return loads(fp.read(),
455 encoding=encoding, cls=cls, object_hook=object_hook,
456 parse_float=parse_float, parse_int=parse_int,
457 parse_constant=parse_constant, object_pairs_hook=object_pairs_hook,
458 use_decimal=use_decimal, allow_nan=allow_nan,
459 array_hook=array_hook, **kw)
462def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
463 parse_int=None, parse_constant=None, object_pairs_hook=None,
464 use_decimal=False, allow_nan=False, array_hook=None, **kw):
465 """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
466 document) to a Python object.
468 *encoding* determines the encoding used to interpret any
469 :class:`bytes` objects decoded by this instance (``'utf-8'`` by
470 default). It has no effect when decoding :class:`unicode` objects.
472 *object_hook*, if specified, will be called with the result of every
473 JSON object decoded and its return value will be used in place of the
474 given :class:`dict`. This can be used to provide custom
475 deserializations (e.g. to support JSON-RPC class hinting).
477 *object_pairs_hook* is an optional function that will be called with
478 the result of any object literal decode with an ordered list of pairs.
479 The return value of *object_pairs_hook* will be used instead of the
480 :class:`dict`. This feature can be used to implement custom decoders
481 that rely on the order that the key and value pairs are decoded (for
482 example, :func:`collections.OrderedDict` will remember the order of
483 insertion). If *object_hook* is also defined, the *object_pairs_hook*
484 takes priority.
486 *parse_float*, if specified, will be called with the string of every
487 JSON float to be decoded. By default, this is equivalent to
488 ``float(num_str)``. This can be used to use another datatype or parser
489 for JSON floats (e.g. :class:`decimal.Decimal`).
491 *parse_int*, if specified, will be called with the string of every
492 JSON int to be decoded. By default, this is equivalent to
493 ``int(num_str)``. This can be used to use another datatype or parser
494 for JSON integers (e.g. :class:`float`).
496 *allow_nan*, if True (default false), will allow the parser to
497 accept the non-standard floats ``NaN``, ``Infinity``, and ``-Infinity``
498 and enable the use of the deprecated *parse_constant*.
500 If *use_decimal* is true (default: ``False``) then it implies
501 parse_float=decimal.Decimal for parity with ``dump``.
503 *parse_constant*, if specified, will be
504 called with one of the following strings: ``'-Infinity'``,
505 ``'Infinity'``, ``'NaN'``. It is not recommended to use this feature,
506 as it is rare to parse non-compliant JSON containing these values.
508 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
509 kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
510 of subclassing whenever possible.
512 """
513 if (cls is None and encoding is None and object_hook is None and
514 parse_int is None and parse_float is None and
515 parse_constant is None and object_pairs_hook is None
516 and array_hook is None
517 and not use_decimal and not allow_nan and not kw):
518 return _default_decoder.decode(s)
519 if cls is None:
520 cls = JSONDecoder
521 if object_hook is not None:
522 kw['object_hook'] = object_hook
523 if object_pairs_hook is not None:
524 kw['object_pairs_hook'] = object_pairs_hook
525 if array_hook is not None:
526 kw['array_hook'] = array_hook
527 if parse_float is not None:
528 kw['parse_float'] = parse_float
529 if parse_int is not None:
530 kw['parse_int'] = parse_int
531 if parse_constant is not None:
532 kw['parse_constant'] = parse_constant
533 if use_decimal:
534 if parse_float is not None:
535 raise TypeError("use_decimal=True implies parse_float=Decimal")
536 kw['parse_float'] = Decimal
537 if allow_nan:
538 kw['allow_nan'] = True
539 return cls(encoding=encoding, **kw).decode(s)
542def _toggle_speedups(enabled):
543 from . import decoder as dec
544 from . import encoder as enc
545 from . import scanner as scan
546 c_make_encoder = _import_c_make_encoder()
547 if enabled:
548 dec.scanstring = dec.c_scanstring or dec.py_scanstring
549 enc.c_make_encoder = c_make_encoder
550 enc.encode_basestring_ascii = (enc.c_encode_basestring_ascii or
551 enc.py_encode_basestring_ascii)
552 enc.encode_basestring = (enc.c_encode_basestring or
553 enc.py_encode_basestring)
554 scan.make_scanner = scan.c_make_scanner or scan.py_make_scanner
555 else:
556 dec.scanstring = dec.py_scanstring
557 enc.c_make_encoder = None
558 enc.encode_basestring_ascii = enc.py_encode_basestring_ascii
559 enc.encode_basestring = enc.py_encode_basestring
560 scan.make_scanner = scan.py_make_scanner
561 dec.make_scanner = scan.make_scanner
562 global _default_decoder
563 _default_decoder = JSONDecoder()
564 global _default_encoder
565 _default_encoder = JSONEncoder()
567def simple_first(kv):
568 """Helper function to pass to item_sort_key to sort simple
569 elements to the top, then container elements.
570 """
571 return (isinstance(kv[1], (list, dict, tuple)), kv[0])