Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/simplejson/__init__.py: 30%
82 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-07 06:20 +0000
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, but maintains
8compatibility back to Python 2.5 and (currently) has significant performance
9advantages, even 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__ = '3.19.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
136def _import_OrderedDict():
137 import collections
138 try:
139 return collections.OrderedDict
140 except AttributeError:
141 from . import ordered_dict
142 return ordered_dict.OrderedDict
143OrderedDict = _import_OrderedDict()
145def _import_c_make_encoder():
146 try:
147 from ._speedups import make_encoder
148 return make_encoder
149 except ImportError:
150 return None
152_default_encoder = JSONEncoder()
154def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
155 allow_nan=False, cls=None, indent=None, separators=None,
156 encoding='utf-8', default=None, use_decimal=True,
157 namedtuple_as_object=True, tuple_as_array=True,
158 bigint_as_string=False, sort_keys=False, item_sort_key=None,
159 for_json=False, ignore_nan=False, int_as_string_bitcount=None,
160 iterable_as_array=False, **kw):
161 """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
162 ``.write()``-supporting file-like object).
164 If *skipkeys* is true then ``dict`` keys that are not basic types
165 (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``)
166 will be skipped instead of raising a ``TypeError``.
168 If *ensure_ascii* is false (default: ``True``), then the output may
169 contain non-ASCII characters, so long as they do not need to be escaped
170 by JSON. When it is true, all non-ASCII characters are escaped.
172 If *allow_nan* is true (default: ``False``), then out of range ``float``
173 values (``nan``, ``inf``, ``-inf``) will be serialized to
174 their JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``)
175 instead of raising a ValueError. See
176 *ignore_nan* for ECMA-262 compliant behavior.
178 If *indent* is a string, then JSON array elements and object members
179 will be pretty-printed with a newline followed by that string repeated
180 for each level of nesting. ``None`` (the default) selects the most compact
181 representation without any newlines.
183 If specified, *separators* should be an
184 ``(item_separator, key_separator)`` tuple. The default is ``(', ', ': ')``
185 if *indent* is ``None`` and ``(',', ': ')`` otherwise. To get the most
186 compact JSON representation, you should specify ``(',', ':')`` to eliminate
187 whitespace.
189 *encoding* is the character encoding for str instances, default is UTF-8.
191 *default(obj)* is a function that should return a serializable version
192 of obj or raise ``TypeError``. The default simply raises ``TypeError``.
194 If *use_decimal* is true (default: ``True``) then decimal.Decimal
195 will be natively serialized to JSON with full precision.
197 If *namedtuple_as_object* is true (default: ``True``),
198 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
199 as JSON objects.
201 If *tuple_as_array* is true (default: ``True``),
202 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
204 If *iterable_as_array* is true (default: ``False``),
205 any object not in the above table that implements ``__iter__()``
206 will be encoded as a JSON array.
208 If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher
209 or lower than -2**53 will be encoded as strings. This is to avoid the
210 rounding that happens in Javascript otherwise. Note that this is still a
211 lossy operation that will not round-trip correctly and should be used
212 sparingly.
214 If *int_as_string_bitcount* is a positive number (n), then int of size
215 greater than or equal to 2**n or lower than or equal to -2**n will be
216 encoded as strings.
218 If specified, *item_sort_key* is a callable used to sort the items in
219 each dictionary. This is useful if you want to sort items other than
220 in alphabetical order by key. This option takes precedence over
221 *sort_keys*.
223 If *sort_keys* is true (default: ``False``), the output of dictionaries
224 will be sorted by item.
226 If *for_json* is true (default: ``False``), objects with a ``for_json()``
227 method will use the return value of that method for encoding as JSON
228 instead of the object.
230 If *ignore_nan* is true (default: ``False``), then out of range
231 :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as
232 ``null`` in compliance with the ECMA-262 specification. If true, this will
233 override *allow_nan*.
235 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
236 ``.default()`` method to serialize additional types), specify it with
237 the ``cls`` kwarg. NOTE: You should use *default* or *for_json* instead
238 of subclassing whenever possible.
240 """
241 # cached encoder
242 if (not skipkeys and ensure_ascii and
243 check_circular and not allow_nan and
244 cls is None and indent is None and separators is None and
245 encoding == 'utf-8' and default is None and use_decimal
246 and namedtuple_as_object and tuple_as_array and not iterable_as_array
247 and not bigint_as_string and not sort_keys
248 and not item_sort_key and not for_json
249 and not ignore_nan and int_as_string_bitcount is None
250 and not kw
251 ):
252 iterable = _default_encoder.iterencode(obj)
253 else:
254 if cls is None:
255 cls = JSONEncoder
256 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
257 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
258 separators=separators, encoding=encoding,
259 default=default, use_decimal=use_decimal,
260 namedtuple_as_object=namedtuple_as_object,
261 tuple_as_array=tuple_as_array,
262 iterable_as_array=iterable_as_array,
263 bigint_as_string=bigint_as_string,
264 sort_keys=sort_keys,
265 item_sort_key=item_sort_key,
266 for_json=for_json,
267 ignore_nan=ignore_nan,
268 int_as_string_bitcount=int_as_string_bitcount,
269 **kw).iterencode(obj)
270 # could accelerate with writelines in some versions of Python, at
271 # a debuggability cost
272 for chunk in iterable:
273 fp.write(chunk)
276def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
277 allow_nan=False, cls=None, indent=None, separators=None,
278 encoding='utf-8', default=None, use_decimal=True,
279 namedtuple_as_object=True, tuple_as_array=True,
280 bigint_as_string=False, sort_keys=False, item_sort_key=None,
281 for_json=False, ignore_nan=False, int_as_string_bitcount=None,
282 iterable_as_array=False, **kw):
283 """Serialize ``obj`` to a JSON formatted ``str``.
285 If ``skipkeys`` is true then ``dict`` keys that are not basic types
286 (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``)
287 will be skipped instead of raising a ``TypeError``.
289 If *ensure_ascii* is false (default: ``True``), then the output may
290 contain non-ASCII characters, so long as they do not need to be escaped
291 by JSON. When it is true, all non-ASCII characters are escaped.
293 If ``check_circular`` is false, then the circular reference check
294 for container types will be skipped and a circular reference will
295 result in an ``OverflowError`` (or worse).
297 If *allow_nan* is true (default: ``False``), then out of range ``float``
298 values (``nan``, ``inf``, ``-inf``) will be serialized to
299 their JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``)
300 instead of raising a ValueError. See
301 *ignore_nan* for ECMA-262 compliant behavior.
303 If ``indent`` is a string, then JSON array elements and object members
304 will be pretty-printed with a newline followed by that string repeated
305 for each level of nesting. ``None`` (the default) selects the most compact
306 representation without any newlines. For backwards compatibility with
307 versions of simplejson earlier than 2.1.0, an integer is also accepted
308 and is converted to a string with that many spaces.
310 If specified, ``separators`` should be an
311 ``(item_separator, key_separator)`` tuple. The default is ``(', ', ': ')``
312 if *indent* is ``None`` and ``(',', ': ')`` otherwise. To get the most
313 compact JSON representation, you should specify ``(',', ':')`` to eliminate
314 whitespace.
316 ``encoding`` is the character encoding for bytes instances, default is
317 UTF-8.
319 ``default(obj)`` is a function that should return a serializable version
320 of obj or raise TypeError. The default simply raises TypeError.
322 If *use_decimal* is true (default: ``True``) then decimal.Decimal
323 will be natively serialized to JSON with full precision.
325 If *namedtuple_as_object* is true (default: ``True``),
326 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
327 as JSON objects.
329 If *tuple_as_array* is true (default: ``True``),
330 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
332 If *iterable_as_array* is true (default: ``False``),
333 any object not in the above table that implements ``__iter__()``
334 will be encoded as a JSON array.
336 If *bigint_as_string* is true (not the default), ints 2**53 and higher
337 or lower than -2**53 will be encoded as strings. This is to avoid the
338 rounding that happens in Javascript otherwise.
340 If *int_as_string_bitcount* is a positive number (n), then int of size
341 greater than or equal to 2**n or lower than or equal to -2**n will be
342 encoded as strings.
344 If specified, *item_sort_key* is a callable used to sort the items in
345 each dictionary. This is useful if you want to sort items other than
346 in alphabetical order by key. This option takes precedence over
347 *sort_keys*.
349 If *sort_keys* is true (default: ``False``), the output of dictionaries
350 will be sorted by item.
352 If *for_json* is true (default: ``False``), objects with a ``for_json()``
353 method will use the return value of that method for encoding as JSON
354 instead of the object.
356 If *ignore_nan* is true (default: ``False``), then out of range
357 :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as
358 ``null`` in compliance with the ECMA-262 specification. If true, this will
359 override *allow_nan*.
361 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
362 ``.default()`` method to serialize additional types), specify it with
363 the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
364 whenever possible.
366 """
367 # cached encoder
368 if (not skipkeys and ensure_ascii and
369 check_circular and not allow_nan and
370 cls is None and indent is None and separators is None and
371 encoding == 'utf-8' and default is None and use_decimal
372 and namedtuple_as_object and tuple_as_array and not iterable_as_array
373 and not bigint_as_string and not sort_keys
374 and not item_sort_key and not for_json
375 and not ignore_nan and int_as_string_bitcount is None
376 and not kw
377 ):
378 return _default_encoder.encode(obj)
379 if cls is None:
380 cls = JSONEncoder
381 return cls(
382 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
383 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
384 separators=separators, encoding=encoding, default=default,
385 use_decimal=use_decimal,
386 namedtuple_as_object=namedtuple_as_object,
387 tuple_as_array=tuple_as_array,
388 iterable_as_array=iterable_as_array,
389 bigint_as_string=bigint_as_string,
390 sort_keys=sort_keys,
391 item_sort_key=item_sort_key,
392 for_json=for_json,
393 ignore_nan=ignore_nan,
394 int_as_string_bitcount=int_as_string_bitcount,
395 **kw).encode(obj)
398_default_decoder = JSONDecoder()
401def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
402 parse_int=None, parse_constant=None, object_pairs_hook=None,
403 use_decimal=False, allow_nan=False, **kw):
404 """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
405 a JSON document as `str` or `bytes`) to a Python object.
407 *encoding* determines the encoding used to interpret any
408 `bytes` objects decoded by this instance (``'utf-8'`` by
409 default). It has no effect when decoding `str` objects.
411 *object_hook*, if specified, will be called with the result of every
412 JSON object decoded and its return value will be used in place of the
413 given :class:`dict`. This can be used to provide custom
414 deserializations (e.g. to support JSON-RPC class hinting).
416 *object_pairs_hook* is an optional function that will be called with
417 the result of any object literal decode with an ordered list of pairs.
418 The return value of *object_pairs_hook* will be used instead of the
419 :class:`dict`. This feature can be used to implement custom decoders
420 that rely on the order that the key and value pairs are decoded (for
421 example, :func:`collections.OrderedDict` will remember the order of
422 insertion). If *object_hook* is also defined, the *object_pairs_hook*
423 takes priority.
425 *parse_float*, if specified, will be called with the string of every
426 JSON float to be decoded. By default, this is equivalent to
427 ``float(num_str)``. This can be used to use another datatype or parser
428 for JSON floats (e.g. :class:`decimal.Decimal`).
430 *parse_int*, if specified, will be called with the string of every
431 JSON int to be decoded. By default, this is equivalent to
432 ``int(num_str)``. This can be used to use another datatype or parser
433 for JSON integers (e.g. :class:`float`).
435 *allow_nan*, if True (default false), will allow the parser to
436 accept the non-standard floats ``NaN``, ``Infinity``, and ``-Infinity``
437 and enable the use of the deprecated *parse_constant*.
439 If *use_decimal* is true (default: ``False``) then it implies
440 parse_float=decimal.Decimal for parity with ``dump``.
442 *parse_constant*, if specified, will be
443 called with one of the following strings: ``'-Infinity'``,
444 ``'Infinity'``, ``'NaN'``. It is not recommended to use this feature,
445 as it is rare to parse non-compliant JSON containing these values.
447 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
448 kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
449 of subclassing whenever possible.
451 """
452 return loads(fp.read(),
453 encoding=encoding, cls=cls, object_hook=object_hook,
454 parse_float=parse_float, parse_int=parse_int,
455 parse_constant=parse_constant, object_pairs_hook=object_pairs_hook,
456 use_decimal=use_decimal, allow_nan=allow_nan, **kw)
459def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
460 parse_int=None, parse_constant=None, object_pairs_hook=None,
461 use_decimal=False, allow_nan=False, **kw):
462 """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
463 document) to a Python object.
465 *encoding* determines the encoding used to interpret any
466 :class:`bytes` objects decoded by this instance (``'utf-8'`` by
467 default). It has no effect when decoding :class:`unicode` objects.
469 *object_hook*, if specified, will be called with the result of every
470 JSON object decoded and its return value will be used in place of the
471 given :class:`dict`. This can be used to provide custom
472 deserializations (e.g. to support JSON-RPC class hinting).
474 *object_pairs_hook* is an optional function that will be called with
475 the result of any object literal decode with an ordered list of pairs.
476 The return value of *object_pairs_hook* will be used instead of the
477 :class:`dict`. This feature can be used to implement custom decoders
478 that rely on the order that the key and value pairs are decoded (for
479 example, :func:`collections.OrderedDict` will remember the order of
480 insertion). If *object_hook* is also defined, the *object_pairs_hook*
481 takes priority.
483 *parse_float*, if specified, will be called with the string of every
484 JSON float to be decoded. By default, this is equivalent to
485 ``float(num_str)``. This can be used to use another datatype or parser
486 for JSON floats (e.g. :class:`decimal.Decimal`).
488 *parse_int*, if specified, will be called with the string of every
489 JSON int to be decoded. By default, this is equivalent to
490 ``int(num_str)``. This can be used to use another datatype or parser
491 for JSON integers (e.g. :class:`float`).
493 *allow_nan*, if True (default false), will allow the parser to
494 accept the non-standard floats ``NaN``, ``Infinity``, and ``-Infinity``
495 and enable the use of the deprecated *parse_constant*.
497 If *use_decimal* is true (default: ``False``) then it implies
498 parse_float=decimal.Decimal for parity with ``dump``.
500 *parse_constant*, if specified, will be
501 called with one of the following strings: ``'-Infinity'``,
502 ``'Infinity'``, ``'NaN'``. It is not recommended to use this feature,
503 as it is rare to parse non-compliant JSON containing these values.
505 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
506 kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
507 of subclassing whenever possible.
509 """
510 if (cls is None and encoding is None and object_hook is None and
511 parse_int is None and parse_float is None and
512 parse_constant is None and object_pairs_hook is None
513 and not use_decimal and not allow_nan and not kw):
514 return _default_decoder.decode(s)
515 if cls is None:
516 cls = JSONDecoder
517 if object_hook is not None:
518 kw['object_hook'] = object_hook
519 if object_pairs_hook is not None:
520 kw['object_pairs_hook'] = object_pairs_hook
521 if parse_float is not None:
522 kw['parse_float'] = parse_float
523 if parse_int is not None:
524 kw['parse_int'] = parse_int
525 if parse_constant is not None:
526 kw['parse_constant'] = parse_constant
527 if use_decimal:
528 if parse_float is not None:
529 raise TypeError("use_decimal=True implies parse_float=Decimal")
530 kw['parse_float'] = Decimal
531 if allow_nan:
532 kw['allow_nan'] = True
533 return cls(encoding=encoding, **kw).decode(s)
536def _toggle_speedups(enabled):
537 from . import decoder as dec
538 from . import encoder as enc
539 from . import scanner as scan
540 c_make_encoder = _import_c_make_encoder()
541 if enabled:
542 dec.scanstring = dec.c_scanstring or dec.py_scanstring
543 enc.c_make_encoder = c_make_encoder
544 enc.encode_basestring_ascii = (enc.c_encode_basestring_ascii or
545 enc.py_encode_basestring_ascii)
546 scan.make_scanner = scan.c_make_scanner or scan.py_make_scanner
547 else:
548 dec.scanstring = dec.py_scanstring
549 enc.c_make_encoder = None
550 enc.encode_basestring_ascii = enc.py_encode_basestring_ascii
551 scan.make_scanner = scan.py_make_scanner
552 dec.make_scanner = scan.make_scanner
553 global _default_decoder
554 _default_decoder = JSONDecoder()
555 global _default_encoder
556 _default_encoder = JSONEncoder()
558def simple_first(kv):
559 """Helper function to pass to item_sort_key to sort simple
560 elements to the top, then container elements.
561 """
562 return (isinstance(kv[1], (list, dict, tuple)), kv[0])