Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/simplejson-3.18.4-py3.8-linux-x86_64.egg/simplejson/__init__.py: 31%
80 statements
« prev ^ index » next coverage.py v7.2.2, created at 2023-03-26 06:04 +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.18.4'
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(
153 skipkeys=False,
154 ensure_ascii=True,
155 check_circular=True,
156 allow_nan=True,
157 indent=None,
158 separators=None,
159 encoding='utf-8',
160 default=None,
161 use_decimal=True,
162 namedtuple_as_object=True,
163 tuple_as_array=True,
164 iterable_as_array=False,
165 bigint_as_string=False,
166 item_sort_key=None,
167 for_json=False,
168 ignore_nan=False,
169 int_as_string_bitcount=None,
170)
172def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
173 allow_nan=True, cls=None, indent=None, separators=None,
174 encoding='utf-8', default=None, use_decimal=True,
175 namedtuple_as_object=True, tuple_as_array=True,
176 bigint_as_string=False, sort_keys=False, item_sort_key=None,
177 for_json=False, ignore_nan=False, int_as_string_bitcount=None,
178 iterable_as_array=False, **kw):
179 """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
180 ``.write()``-supporting file-like object).
182 If *skipkeys* is true then ``dict`` keys that are not basic types
183 (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``)
184 will be skipped instead of raising a ``TypeError``.
186 If *ensure_ascii* is false (default: ``True``), then the output may
187 contain non-ASCII characters, so long as they do not need to be escaped
188 by JSON. When it is true, all non-ASCII characters are escaped.
190 If *allow_nan* is false, then it will be a ``ValueError`` to
191 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
192 in strict compliance of the original JSON specification, instead of using
193 the JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). See
194 *ignore_nan* for ECMA-262 compliant behavior.
196 If *indent* is a string, then JSON array elements and object members
197 will be pretty-printed with a newline followed by that string repeated
198 for each level of nesting. ``None`` (the default) selects the most compact
199 representation without any newlines.
201 If specified, *separators* should be an
202 ``(item_separator, key_separator)`` tuple. The default is ``(', ', ': ')``
203 if *indent* is ``None`` and ``(',', ': ')`` otherwise. To get the most
204 compact JSON representation, you should specify ``(',', ':')`` to eliminate
205 whitespace.
207 *encoding* is the character encoding for str instances, default is UTF-8.
209 *default(obj)* is a function that should return a serializable version
210 of obj or raise ``TypeError``. The default simply raises ``TypeError``.
212 If *use_decimal* is true (default: ``True``) then decimal.Decimal
213 will be natively serialized to JSON with full precision.
215 If *namedtuple_as_object* is true (default: ``True``),
216 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
217 as JSON objects.
219 If *tuple_as_array* is true (default: ``True``),
220 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
222 If *iterable_as_array* is true (default: ``False``),
223 any object not in the above table that implements ``__iter__()``
224 will be encoded as a JSON array.
226 If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher
227 or lower than -2**53 will be encoded as strings. This is to avoid the
228 rounding that happens in Javascript otherwise. Note that this is still a
229 lossy operation that will not round-trip correctly and should be used
230 sparingly.
232 If *int_as_string_bitcount* is a positive number (n), then int of size
233 greater than or equal to 2**n or lower than or equal to -2**n will be
234 encoded as strings.
236 If specified, *item_sort_key* is a callable used to sort the items in
237 each dictionary. This is useful if you want to sort items other than
238 in alphabetical order by key. This option takes precedence over
239 *sort_keys*.
241 If *sort_keys* is true (default: ``False``), the output of dictionaries
242 will be sorted by item.
244 If *for_json* is true (default: ``False``), objects with a ``for_json()``
245 method will use the return value of that method for encoding as JSON
246 instead of the object.
248 If *ignore_nan* is true (default: ``False``), then out of range
249 :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as
250 ``null`` in compliance with the ECMA-262 specification. If true, this will
251 override *allow_nan*.
253 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
254 ``.default()`` method to serialize additional types), specify it with
255 the ``cls`` kwarg. NOTE: You should use *default* or *for_json* instead
256 of subclassing whenever possible.
258 """
259 # cached encoder
260 if (not skipkeys and ensure_ascii and
261 check_circular and allow_nan and
262 cls is None and indent is None and separators is None and
263 encoding == 'utf-8' and default is None and use_decimal
264 and namedtuple_as_object and tuple_as_array and not iterable_as_array
265 and not bigint_as_string and not sort_keys
266 and not item_sort_key and not for_json
267 and not ignore_nan and int_as_string_bitcount is None
268 and not kw
269 ):
270 iterable = _default_encoder.iterencode(obj)
271 else:
272 if cls is None:
273 cls = JSONEncoder
274 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
275 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
276 separators=separators, encoding=encoding,
277 default=default, use_decimal=use_decimal,
278 namedtuple_as_object=namedtuple_as_object,
279 tuple_as_array=tuple_as_array,
280 iterable_as_array=iterable_as_array,
281 bigint_as_string=bigint_as_string,
282 sort_keys=sort_keys,
283 item_sort_key=item_sort_key,
284 for_json=for_json,
285 ignore_nan=ignore_nan,
286 int_as_string_bitcount=int_as_string_bitcount,
287 **kw).iterencode(obj)
288 # could accelerate with writelines in some versions of Python, at
289 # a debuggability cost
290 for chunk in iterable:
291 fp.write(chunk)
294def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
295 allow_nan=True, cls=None, indent=None, separators=None,
296 encoding='utf-8', default=None, use_decimal=True,
297 namedtuple_as_object=True, tuple_as_array=True,
298 bigint_as_string=False, sort_keys=False, item_sort_key=None,
299 for_json=False, ignore_nan=False, int_as_string_bitcount=None,
300 iterable_as_array=False, **kw):
301 """Serialize ``obj`` to a JSON formatted ``str``.
303 If ``skipkeys`` is true then ``dict`` keys that are not basic types
304 (``str``, ``int``, ``long``, ``float``, ``bool``, ``None``)
305 will be skipped instead of raising a ``TypeError``.
307 If *ensure_ascii* is false (default: ``True``), then the output may
308 contain non-ASCII characters, so long as they do not need to be escaped
309 by JSON. When it is true, all non-ASCII characters are escaped.
311 If ``check_circular`` is false, then the circular reference check
312 for container types will be skipped and a circular reference will
313 result in an ``OverflowError`` (or worse).
315 If ``allow_nan`` is false, then it will be a ``ValueError`` to
316 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
317 strict compliance of the JSON specification, instead of using the
318 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
320 If ``indent`` is a string, then JSON array elements and object members
321 will be pretty-printed with a newline followed by that string repeated
322 for each level of nesting. ``None`` (the default) selects the most compact
323 representation without any newlines. For backwards compatibility with
324 versions of simplejson earlier than 2.1.0, an integer is also accepted
325 and is converted to a string with that many spaces.
327 If specified, ``separators`` should be an
328 ``(item_separator, key_separator)`` tuple. The default is ``(', ', ': ')``
329 if *indent* is ``None`` and ``(',', ': ')`` otherwise. To get the most
330 compact JSON representation, you should specify ``(',', ':')`` to eliminate
331 whitespace.
333 ``encoding`` is the character encoding for bytes instances, default is
334 UTF-8.
336 ``default(obj)`` is a function that should return a serializable version
337 of obj or raise TypeError. The default simply raises TypeError.
339 If *use_decimal* is true (default: ``True``) then decimal.Decimal
340 will be natively serialized to JSON with full precision.
342 If *namedtuple_as_object* is true (default: ``True``),
343 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
344 as JSON objects.
346 If *tuple_as_array* is true (default: ``True``),
347 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
349 If *iterable_as_array* is true (default: ``False``),
350 any object not in the above table that implements ``__iter__()``
351 will be encoded as a JSON array.
353 If *bigint_as_string* is true (not the default), ints 2**53 and higher
354 or lower than -2**53 will be encoded as strings. This is to avoid the
355 rounding that happens in Javascript otherwise.
357 If *int_as_string_bitcount* is a positive number (n), then int of size
358 greater than or equal to 2**n or lower than or equal to -2**n will be
359 encoded as strings.
361 If specified, *item_sort_key* is a callable used to sort the items in
362 each dictionary. This is useful if you want to sort items other than
363 in alphabetical order by key. This option takes precedence over
364 *sort_keys*.
366 If *sort_keys* is true (default: ``False``), the output of dictionaries
367 will be sorted by item.
369 If *for_json* is true (default: ``False``), objects with a ``for_json()``
370 method will use the return value of that method for encoding as JSON
371 instead of the object.
373 If *ignore_nan* is true (default: ``False``), then out of range
374 :class:`float` values (``nan``, ``inf``, ``-inf``) will be serialized as
375 ``null`` in compliance with the ECMA-262 specification. If true, this will
376 override *allow_nan*.
378 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
379 ``.default()`` method to serialize additional types), specify it with
380 the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
381 whenever possible.
383 """
384 # cached encoder
385 if (not skipkeys and ensure_ascii and
386 check_circular and allow_nan and
387 cls is None and indent is None and separators is None and
388 encoding == 'utf-8' and default is None and use_decimal
389 and namedtuple_as_object and tuple_as_array and not iterable_as_array
390 and not bigint_as_string and not sort_keys
391 and not item_sort_key and not for_json
392 and not ignore_nan and int_as_string_bitcount is None
393 and not kw
394 ):
395 return _default_encoder.encode(obj)
396 if cls is None:
397 cls = JSONEncoder
398 return cls(
399 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
400 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
401 separators=separators, encoding=encoding, default=default,
402 use_decimal=use_decimal,
403 namedtuple_as_object=namedtuple_as_object,
404 tuple_as_array=tuple_as_array,
405 iterable_as_array=iterable_as_array,
406 bigint_as_string=bigint_as_string,
407 sort_keys=sort_keys,
408 item_sort_key=item_sort_key,
409 for_json=for_json,
410 ignore_nan=ignore_nan,
411 int_as_string_bitcount=int_as_string_bitcount,
412 **kw).encode(obj)
415_default_decoder = JSONDecoder(encoding=None, object_hook=None,
416 object_pairs_hook=None)
419def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
420 parse_int=None, parse_constant=None, object_pairs_hook=None,
421 use_decimal=False, namedtuple_as_object=True, tuple_as_array=True,
422 **kw):
423 """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
424 a JSON document as `str` or `bytes`) to a Python object.
426 *encoding* determines the encoding used to interpret any
427 `bytes` objects decoded by this instance (``'utf-8'`` by
428 default). It has no effect when decoding `str` objects.
430 *object_hook*, if specified, will be called with the result of every
431 JSON object decoded and its return value will be used in place of the
432 given :class:`dict`. This can be used to provide custom
433 deserializations (e.g. to support JSON-RPC class hinting).
435 *object_pairs_hook* is an optional function that will be called with
436 the result of any object literal decode with an ordered list of pairs.
437 The return value of *object_pairs_hook* will be used instead of the
438 :class:`dict`. This feature can be used to implement custom decoders
439 that rely on the order that the key and value pairs are decoded (for
440 example, :func:`collections.OrderedDict` will remember the order of
441 insertion). If *object_hook* is also defined, the *object_pairs_hook*
442 takes priority.
444 *parse_float*, if specified, will be called with the string of every
445 JSON float to be decoded. By default, this is equivalent to
446 ``float(num_str)``. This can be used to use another datatype or parser
447 for JSON floats (e.g. :class:`decimal.Decimal`).
449 *parse_int*, if specified, will be called with the string of every
450 JSON int to be decoded. By default, this is equivalent to
451 ``int(num_str)``. This can be used to use another datatype or parser
452 for JSON integers (e.g. :class:`float`).
454 *parse_constant*, if specified, will be called with one of the
455 following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This
456 can be used to raise an exception if invalid JSON numbers are
457 encountered.
459 If *use_decimal* is true (default: ``False``) then it implies
460 parse_float=decimal.Decimal for parity with ``dump``.
462 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
463 kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
464 of subclassing whenever possible.
466 """
467 return loads(fp.read(),
468 encoding=encoding, cls=cls, object_hook=object_hook,
469 parse_float=parse_float, parse_int=parse_int,
470 parse_constant=parse_constant, object_pairs_hook=object_pairs_hook,
471 use_decimal=use_decimal, **kw)
474def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
475 parse_int=None, parse_constant=None, object_pairs_hook=None,
476 use_decimal=False, **kw):
477 """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
478 document) to a Python object.
480 *encoding* determines the encoding used to interpret any
481 :class:`bytes` objects decoded by this instance (``'utf-8'`` by
482 default). It has no effect when decoding :class:`unicode` objects.
484 *object_hook*, if specified, will be called with the result of every
485 JSON object decoded and its return value will be used in place of the
486 given :class:`dict`. This can be used to provide custom
487 deserializations (e.g. to support JSON-RPC class hinting).
489 *object_pairs_hook* is an optional function that will be called with
490 the result of any object literal decode with an ordered list of pairs.
491 The return value of *object_pairs_hook* will be used instead of the
492 :class:`dict`. This feature can be used to implement custom decoders
493 that rely on the order that the key and value pairs are decoded (for
494 example, :func:`collections.OrderedDict` will remember the order of
495 insertion). If *object_hook* is also defined, the *object_pairs_hook*
496 takes priority.
498 *parse_float*, if specified, will be called with the string of every
499 JSON float to be decoded. By default, this is equivalent to
500 ``float(num_str)``. This can be used to use another datatype or parser
501 for JSON floats (e.g. :class:`decimal.Decimal`).
503 *parse_int*, if specified, will be called with the string of every
504 JSON int to be decoded. By default, this is equivalent to
505 ``int(num_str)``. This can be used to use another datatype or parser
506 for JSON integers (e.g. :class:`float`).
508 *parse_constant*, if specified, will be called with one of the
509 following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This
510 can be used to raise an exception if invalid JSON numbers are
511 encountered.
513 If *use_decimal* is true (default: ``False``) then it implies
514 parse_float=decimal.Decimal for parity with ``dump``.
516 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
517 kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
518 of subclassing whenever possible.
520 """
521 if (cls is None and encoding is None and object_hook is None and
522 parse_int is None and parse_float is None and
523 parse_constant is None and object_pairs_hook is None
524 and not use_decimal and not kw):
525 return _default_decoder.decode(s)
526 if cls is None:
527 cls = JSONDecoder
528 if object_hook is not None:
529 kw['object_hook'] = object_hook
530 if object_pairs_hook is not None:
531 kw['object_pairs_hook'] = object_pairs_hook
532 if parse_float is not None:
533 kw['parse_float'] = parse_float
534 if parse_int is not None:
535 kw['parse_int'] = parse_int
536 if parse_constant is not None:
537 kw['parse_constant'] = parse_constant
538 if use_decimal:
539 if parse_float is not None:
540 raise TypeError("use_decimal=True implies parse_float=Decimal")
541 kw['parse_float'] = Decimal
542 return cls(encoding=encoding, **kw).decode(s)
545def _toggle_speedups(enabled):
546 from . import decoder as dec
547 from . import encoder as enc
548 from . import scanner as scan
549 c_make_encoder = _import_c_make_encoder()
550 if enabled:
551 dec.scanstring = dec.c_scanstring or dec.py_scanstring
552 enc.c_make_encoder = c_make_encoder
553 enc.encode_basestring_ascii = (enc.c_encode_basestring_ascii or
554 enc.py_encode_basestring_ascii)
555 scan.make_scanner = scan.c_make_scanner or scan.py_make_scanner
556 else:
557 dec.scanstring = dec.py_scanstring
558 enc.c_make_encoder = None
559 enc.encode_basestring_ascii = enc.py_encode_basestring_ascii
560 scan.make_scanner = scan.py_make_scanner
561 dec.make_scanner = scan.make_scanner
562 global _default_decoder
563 _default_decoder = JSONDecoder(
564 encoding=None,
565 object_hook=None,
566 object_pairs_hook=None,
567 )
568 global _default_encoder
569 _default_encoder = JSONEncoder(
570 skipkeys=False,
571 ensure_ascii=True,
572 check_circular=True,
573 allow_nan=True,
574 indent=None,
575 separators=None,
576 encoding='utf-8',
577 default=None,
578 )
580def simple_first(kv):
581 """Helper function to pass to item_sort_key to sort simple
582 elements to the top, then container elements.
583 """
584 return (isinstance(kv[1], (list, dict, tuple)), kv[0])