Debian Codegraph @

Doc/library/json.rst

raw
1 :mod:`!json` --- JSON encoder and decoder
2 =========================================
3
4 .. module:: json
5 :synopsis: Encode and decode the JSON format.
6
7 .. moduleauthor:: Bob Ippolito <[email protected]>
8 .. sectionauthor:: Bob Ippolito <[email protected]>
9
10 **Source code:** :source:`Lib/json/__init__.py`
11
12 --------------
13
14 `JSON (JavaScript Object Notation) <https://json.org>`_, specified by
15 :rfc:`7159` (which obsoletes :rfc:`4627`) and by
16 `ECMA-404 <https://ecma-international.org/publications-and-standards/standards/ecma-404/>`_,
17 is a lightweight data interchange format inspired by
18 `JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax
19 (although it is not a strict subset of JavaScript [#rfc-errata]_ ).
20
21 .. note::
22 The term "object" in the context of JSON processing in Python can be
23 ambiguous. All values in Python are objects. In JSON, an object refers to
24 any data wrapped in curly braces, similar to a Python dictionary.
25
26 .. warning::
27 Be cautious when parsing JSON data from untrusted sources. A malicious
28 JSON string may cause the decoder to consume considerable CPU and memory
29 resources. Limiting the size of data to be parsed is recommended.
30
31 This module exposes an API familiar to users of the standard library
32 :mod:`marshal` and :mod:`pickle` modules.
33
34 Encoding basic Python object hierarchies::
35
36 >>> import json
37 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
38 '["foo", {"bar": ["baz", null, 1.0, 2]}]'
39 >>> print(json.dumps("\"foo\bar"))
40 "\"foo\bar"
41 >>> print(json.dumps('\u1234'))
42 "\u1234"
43 >>> print(json.dumps('\\'))
44 "\\"
45 >>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
46 {"a": 0, "b": 0, "c": 0}
47 >>> from io import StringIO
48 >>> io = StringIO()
49 >>> json.dump(['streaming API'], io)
50 >>> io.getvalue()
51 '["streaming API"]'
52
53 Compact encoding::
54
55 >>> import json
56 >>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
57 '[1,2,3,{"4":5,"6":7}]'
58
59 Pretty printing::
60
61 >>> import json
62 >>> print(json.dumps({'6': 7, '4': 5}, sort_keys=True, indent=4))
63 {
64 "4": 5,
65 "6": 7
66 }
67
68 Customizing JSON object encoding::
69
70 >>> import json
71 >>> def custom_json(obj):
72 ... if isinstance(obj, complex):
73 ... return {'__complex__': True, 'real': obj.real, 'imag': obj.imag}
74 ... raise TypeError(f'Cannot serialize object of {type(obj)}')
75 ...
76 >>> json.dumps(1 + 2j, default=custom_json)
77 '{"__complex__": true, "real": 1.0, "imag": 2.0}'
78
79 Decoding JSON::
80
81 >>> import json
82 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
83 ['foo', {'bar': ['baz', None, 1.0, 2]}]
84 >>> json.loads('"\\"foo\\bar"')
85 '"foo\x08ar'
86 >>> from io import StringIO
87 >>> io = StringIO('["streaming API"]')
88 >>> json.load(io)
89 ['streaming API']
90
91 Customizing JSON object decoding::
92
93 >>> import json
94 >>> def as_complex(dct):
95 ... if '__complex__' in dct:
96 ... return complex(dct['real'], dct['imag'])
97 ... return dct
98 ...
99 >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
100 ... object_hook=as_complex)
101 (1+2j)
102 >>> import decimal
103 >>> json.loads('1.1', parse_float=decimal.Decimal)
104 Decimal('1.1')
105
106 Extending :class:`JSONEncoder`::
107
108 >>> import json
109 >>> class ComplexEncoder(json.JSONEncoder):
110 ... def default(self, obj):
111 ... if isinstance(obj, complex):
112 ... return [obj.real, obj.imag]
113 ... # Let the base class default method raise the TypeError
114 ... return super().default(obj)
115 ...
116 >>> json.dumps(2 + 1j, cls=ComplexEncoder)
117 '[2.0, 1.0]'
118 >>> ComplexEncoder().encode(2 + 1j)
119 '[2.0, 1.0]'
120 >>> list(ComplexEncoder().iterencode(2 + 1j))
121 ['[2.0', ', 1.0', ']']
122
123
124 Using :mod:`!json` from the shell to validate and pretty-print:
125
126 .. code-block:: shell-session
127
128 $ echo '{"json":"obj"}' | python -m json
129 {
130 "json": "obj"
131 }
132 $ echo '{1.2:3.4}' | python -m json
133 Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
134
135 See :ref:`json-commandline` for detailed documentation.
136
137 .. note::
138
139 JSON is a subset of `YAML <https://yaml.org/>`_ 1.2. The JSON produced by
140 this module's default settings (in particular, the default *separators*
141 value) is also a subset of YAML 1.0 and 1.1. This module can thus also be
142 used as a YAML serializer.
143
144 .. note::
145
146 This module's encoders and decoders preserve input and output order by
147 default. Order is only lost if the underlying containers are unordered.
148
149
150 Basic Usage
151 -----------
152
153 .. function:: dump(obj, fp, *, skipkeys=False, ensure_ascii=True, \
154 check_circular=True, allow_nan=True, cls=None, \
155 indent=None, separators=None, default=None, \
156 sort_keys=False, **kw)
157
158 Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
159 :term:`file-like object`) using this :ref:`Python-to-JSON conversion table
160 <py-to-json-table>`.
161
162 .. note::
163
164 Unlike :mod:`pickle` and :mod:`marshal`, JSON is not a framed protocol,
165 so trying to serialize multiple objects with repeated calls to
166 :func:`dump` using the same *fp* will result in an invalid JSON file.
167
168 :param object obj:
169 The Python object to be serialized.
170
171 :param fp:
172 The file-like object *obj* will be serialized to.
173 The :mod:`!json` module always produces :class:`str` objects,
174 not :class:`bytes` objects,
175 therefore ``fp.write()`` must support :class:`str` input.
176 :type fp: :term:`file-like object`
177
178 :param bool skipkeys:
179 If ``True``, keys that are not of a basic type
180 (:class:`str`, :class:`int`, :class:`float`, :class:`bool`, ``None``)
181 will be skipped instead of raising a :exc:`TypeError`.
182 Default ``False``.
183
184 :param bool ensure_ascii:
185 If ``True`` (the default), the output is guaranteed to
186 have all incoming non-ASCII and non-printable characters escaped.
187 If ``False``, all characters will be outputted as-is, except for
188 the characters that must be escaped: quotation mark, reverse solidus,
189 and the control characters U+0000 through U+001F.
190
191 :param bool check_circular:
192 If ``False``, the circular reference check for container types is skipped
193 and a circular reference will result in a :exc:`RecursionError` (or worse).
194 Default ``True``.
195
196 :param bool allow_nan:
197 If ``False``, serialization of out-of-range :class:`float` values
198 (``nan``, ``inf``, ``-inf``) will result in a :exc:`ValueError`,
199 in strict compliance with the JSON specification.
200 If ``True`` (the default), their JavaScript equivalents
201 (``NaN``, ``Infinity``, ``-Infinity``) are used.
202
203 :param cls:
204 If set, a custom JSON encoder with the
205 :meth:`~JSONEncoder.default` method overridden,
206 for serializing into custom datatypes.
207 If ``None`` (the default), :class:`!JSONEncoder` is used.
208 :type cls: a :class:`JSONEncoder` subclass
209
210 :param indent:
211 If a positive integer or string, JSON array elements and
212 object members will be pretty-printed with that indent level.
213 A positive integer indents that many spaces per level;
214 a string (such as ``"\t"``) is used to indent each level.
215 If zero, negative, or ``""`` (the empty string),
216 only newlines are inserted.
217 If ``None`` (the default), no newlines are inserted.
218 :type indent: int | str | None
219
220 :param separators:
221 A two-tuple: ``(item_separator, key_separator)``.
222 If ``None`` (the default), *separators* defaults to
223 ``(', ', ': ')`` if *indent* is ``None``,
224 and ``(',', ': ')`` otherwise.
225 For the most compact JSON,
226 specify ``(',', ':')`` to eliminate whitespace.
227 :type separators: tuple | None
228
229 :param default:
230 A function that is called for objects that can't otherwise be serialized.
231 It should return a JSON encodable version of the object
232 or raise a :exc:`TypeError`.
233 If ``None`` (the default), :exc:`!TypeError` is raised.
234 :type default: :term:`callable` | None
235
236 :param bool sort_keys:
237 If ``True``, dictionaries will be outputted sorted by key.
238 Default ``False``.
239
240 .. versionchanged:: 3.2
241 Allow strings for *indent* in addition to integers.
242
243 .. versionchanged:: 3.4
244 Use ``(',', ': ')`` as default if *indent* is not ``None``.
245
246 .. versionchanged:: 3.6
247 All optional parameters are now :ref:`keyword-only <keyword-only_parameter>`.
248
249
250 .. function:: dumps(obj, *, skipkeys=False, ensure_ascii=True, \
251 check_circular=True, allow_nan=True, cls=None, \
252 indent=None, separators=None, default=None, \
253 sort_keys=False, **kw)
254
255 Serialize *obj* to a JSON formatted :class:`str` using this :ref:`conversion
256 table <py-to-json-table>`. The arguments have the same meaning as in
257 :func:`dump`.
258
259 .. note::
260
261 Keys in key/value pairs of JSON are always of the type :class:`str`. When
262 a dictionary is converted into JSON, all the keys of the dictionary are
263 coerced to strings. As a result of this, if a dictionary is converted
264 into JSON and then back into a dictionary, the dictionary may not equal
265 the original one. That is, ``loads(dumps(x)) != x`` if x has non-string
266 keys.
267
268 .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \
269 parse_int=None, parse_constant=None, \
270 object_pairs_hook=None, **kw)
271
272 Deserialize *fp* to a Python object
273 using the :ref:`JSON-to-Python conversion table <json-to-py-table>`.
274
275 :param fp:
276 A ``.read()``-supporting :term:`text file` or :term:`binary file`
277 containing the JSON document to be deserialized.
278 :type fp: :term:`file-like object`
279
280 :param cls:
281 If set, a custom JSON decoder.
282 Additional keyword arguments to :func:`!load`
283 will be passed to the constructor of *cls*.
284 If ``None`` (the default), :class:`!JSONDecoder` is used.
285 :type cls: a :class:`JSONDecoder` subclass
286
287 :param object_hook:
288 If set, a function that is called with the result of
289 any JSON object literal decoded (a :class:`dict`).
290 The return value of this function will be used
291 instead of the :class:`dict`.
292 This feature can be used to implement custom decoders,
293 for example `JSON-RPC <https://www.jsonrpc.org>`_ class hinting.
294 Default ``None``.
295 :type object_hook: :term:`callable` | None
296
297 :param object_pairs_hook:
298 If set, a function that is called with the result of
299 any JSON object literal decoded with an ordered list of pairs.
300 The return value of this function will be used
301 instead of the :class:`dict`.
302 This feature can be used to implement custom decoders.
303 If *object_hook* is also set, *object_pairs_hook* takes priority.
304 Default ``None``.
305 :type object_pairs_hook: :term:`callable` | None
306
307 :param parse_float:
308 If set, a function that is called with
309 the string of every JSON float to be decoded.
310 If ``None`` (the default), it is equivalent to ``float(num_str)``.
311 This can be used to parse JSON floats into custom datatypes,
312 for example :class:`decimal.Decimal`.
313 :type parse_float: :term:`callable` | None
314
315 :param parse_int:
316 If set, a function that is called with
317 the string of every JSON int to be decoded.
318 If ``None`` (the default), it is equivalent to ``int(num_str)``.
319 This can be used to parse JSON integers into custom datatypes,
320 for example :class:`float`.
321 :type parse_int: :term:`callable` | None
322
323 :param parse_constant:
324 If set, a function that is called with one of the following strings:
325 ``'-Infinity'``, ``'Infinity'``, or ``'NaN'``.
326 This can be used to raise an exception
327 if invalid JSON numbers are encountered.
328 Default ``None``.
329 :type parse_constant: :term:`callable` | None
330
331 :raises JSONDecodeError:
332 When the data being deserialized is not a valid JSON document.
333
334 :raises UnicodeDecodeError:
335 When the data being deserialized does not contain
336 UTF-8, UTF-16 or UTF-32 encoded data.
337
338 .. versionchanged:: 3.1
339
340 * Added the optional *object_pairs_hook* parameter.
341 * *parse_constant* doesn't get called on 'null', 'true', 'false' anymore.
342
343 .. versionchanged:: 3.6
344
345 * All optional parameters are now :ref:`keyword-only <keyword-only_parameter>`.
346 * *fp* can now be a :term:`binary file`.
347 The input encoding should be UTF-8, UTF-16 or UTF-32.
348
349 .. versionchanged:: 3.11
350 The default *parse_int* of :func:`int` now limits the maximum length of
351 the integer string via the interpreter's :ref:`integer string
352 conversion length limitation <int_max_str_digits>` to help avoid denial
353 of service attacks.
354
355 .. function:: loads(s, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
356
357 Identical to :func:`load`, but instead of a file-like object,
358 deserialize *s* (a :class:`str`, :class:`bytes` or :class:`bytearray`
359 instance containing a JSON document) to a Python object using this
360 :ref:`conversion table <json-to-py-table>`.
361
362 .. versionchanged:: 3.6
363 *s* can now be of type :class:`bytes` or :class:`bytearray`. The
364 input encoding should be UTF-8, UTF-16 or UTF-32.
365
366 .. versionchanged:: 3.9
367 The keyword argument *encoding* has been removed.
368
369
370 Encoders and Decoders
371 ---------------------
372
373 .. class:: JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)
374
375 Simple JSON decoder.
376
377 Performs the following translations in decoding by default:
378
379 .. _json-to-py-table:
380
381 +---------------+-------------------+
382 | JSON | Python |
383 +===============+===================+
384 | object | dict |
385 +---------------+-------------------+
386 | array | list |
387 +---------------+-------------------+
388 | string | str |
389 +---------------+-------------------+
390 | number (int) | int |
391 +---------------+-------------------+
392 | number (real) | float |
393 +---------------+-------------------+
394 | true | True |
395 +---------------+-------------------+
396 | false | False |
397 +---------------+-------------------+
398 | null | None |
399 +---------------+-------------------+
400
401 It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
402 corresponding ``float`` values, which is outside the JSON spec.
403
404 *object_hook* is an optional function that will be called with the result of
405 every JSON object decoded and its return value will be used in place of the
406 given :class:`dict`. This can be used to provide custom deserializations
407 (e.g. to support `JSON-RPC <https://www.jsonrpc.org>`_ class hinting).
408
409 *object_pairs_hook* is an optional function that will be called with the
410 result of every JSON object decoded with an ordered list of pairs. The
411 return value of *object_pairs_hook* will be used instead of the
412 :class:`dict`. This feature can be used to implement custom decoders. If
413 *object_hook* is also defined, the *object_pairs_hook* takes priority.
414
415 .. versionchanged:: 3.1
416 Added support for *object_pairs_hook*.
417
418 *parse_float* is an optional function that will be called with the string of
419 every JSON float to be decoded. By default, this is equivalent to
420 ``float(num_str)``. This can be used to use another datatype or parser for
421 JSON floats (e.g. :class:`decimal.Decimal`).
422
423 *parse_int* is an optional function that will be called with the string of
424 every JSON int to be decoded. By default, this is equivalent to
425 ``int(num_str)``. This can be used to use another datatype or parser for
426 JSON integers (e.g. :class:`float`).
427
428 *parse_constant* is an optional function that will be called with one of the
429 following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This can be
430 used to raise an exception if invalid JSON numbers are encountered.
431
432 If *strict* is false (``True`` is the default), then control characters
433 will be allowed inside strings. Control characters in this context are
434 those with character codes in the 0--31 range, including ``'\t'`` (tab),
435 ``'\n'``, ``'\r'`` and ``'\0'``.
436
437 If the data being deserialized is not a valid JSON document, a
438 :exc:`JSONDecodeError` will be raised.
439
440 .. versionchanged:: 3.6
441 All parameters are now :ref:`keyword-only <keyword-only_parameter>`.
442
443 .. method:: decode(s)
444
445 Return the Python representation of *s* (a :class:`str` instance
446 containing a JSON document).
447
448 :exc:`JSONDecodeError` will be raised if the given JSON document is not
449 valid.
450
451 .. method:: raw_decode(s)
452
453 Decode a JSON document from *s* (a :class:`str` beginning with a
454 JSON document) and return a 2-tuple of the Python representation
455 and the index in *s* where the document ended.
456
457 This can be used to decode a JSON document from a string that may have
458 extraneous data at the end.
459
460
461 .. class:: JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)
462
463 Extensible JSON encoder for Python data structures.
464
465 Supports the following objects and types by default:
466
467 .. _py-to-json-table:
468
469 +----------------------------------------+---------------+
470 | Python | JSON |
471 +========================================+===============+
472 | dict | object |
473 +----------------------------------------+---------------+
474 | list, tuple | array |
475 +----------------------------------------+---------------+
476 | str | string |
477 +----------------------------------------+---------------+
478 | int, float, int- & float-derived Enums | number |
479 +----------------------------------------+---------------+
480 | True | true |
481 +----------------------------------------+---------------+
482 | False | false |
483 +----------------------------------------+---------------+
484 | None | null |
485 +----------------------------------------+---------------+
486
487 .. versionchanged:: 3.4
488 Added support for int- and float-derived Enum classes.
489
490 To extend this to recognize other objects, subclass and implement a
491 :meth:`~JSONEncoder.default` method with another method that returns a serializable object
492 for ``o`` if possible, otherwise it should call the superclass implementation
493 (to raise :exc:`TypeError`).
494
495 If *skipkeys* is false (the default), a :exc:`TypeError` will be raised when
496 trying to encode keys that are not :class:`str`, :class:`int`, :class:`float`,
497 :class:`bool` or ``None``. If *skipkeys* is true, such items are simply skipped.
498
499 If *ensure_ascii* is true (the default), the output is guaranteed to
500 have all incoming non-ASCII and non-printable characters escaped.
501 If *ensure_ascii* is false, all characters will be output as-is, except for
502 the characters that must be escaped: quotation mark, reverse solidus,
503 and the control characters U+0000 through U+001F.
504
505 If *check_circular* is true (the default), then lists, dicts, and custom
506 encoded objects will be checked for circular references during encoding to
507 prevent an infinite recursion (which would cause a :exc:`RecursionError`).
508 Otherwise, no such check takes place.
509
510 If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and
511 ``-Infinity`` will be encoded as such. This behavior is not JSON
512 specification compliant, but is consistent with most JavaScript based
513 encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
514 such floats.
515
516 If *sort_keys* is true (default: ``False``), then the output of dictionaries
517 will be sorted by key; this is useful for regression tests to ensure that
518 JSON serializations can be compared on a day-to-day basis.
519
520 If *indent* is a non-negative integer or string, then JSON array elements and
521 object members will be pretty-printed with that indent level. An indent level
522 of 0, negative, or ``""`` will only insert newlines. ``None`` (the default)
523 selects the most compact representation. Using a positive integer indent
524 indents that many spaces per level. If *indent* is a string (such as ``"\t"``),
525 that string is used to indent each level.
526
527 .. versionchanged:: 3.2
528 Allow strings for *indent* in addition to integers.
529
530 If specified, *separators* should be an ``(item_separator, key_separator)``
531 tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and
532 ``(',', ': ')`` otherwise. To get the most compact JSON representation,
533 you should specify ``(',', ':')`` to eliminate whitespace.
534
535 .. versionchanged:: 3.4
536 Use ``(',', ': ')`` as default if *indent* is not ``None``.
537
538 If specified, *default* should be a function that gets called for objects that
539 can't otherwise be serialized. It should return a JSON encodable version of
540 the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
541 is raised.
542
543 .. versionchanged:: 3.6
544 All parameters are now :ref:`keyword-only <keyword-only_parameter>`.
545
546
547 .. method:: default(o)
548
549 Implement this method in a subclass such that it returns a serializable
550 object for *o*, or calls the base implementation (to raise a
551 :exc:`TypeError`).
552
553 For example, to support arbitrary iterators, you could implement
554 :meth:`~JSONEncoder.default` like this::
555
556 def default(self, o):
557 try:
558 iterable = iter(o)
559 except TypeError:
560 pass
561 else:
562 return list(iterable)
563 # Let the base class default method raise the TypeError
564 return super().default(o)
565
566
567 .. method:: encode(o)
568
569 Return a JSON string representation of a Python data structure, *o*. For
570 example::
571
572 >>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
573 '{"foo": ["bar", "baz"]}'
574
575
576 .. method:: iterencode(o)
577
578 Encode the given object, *o*, and yield each string representation as
579 available. For example::
580
581 for chunk in json.JSONEncoder().iterencode(bigobject):
582 mysocket.write(chunk)
583
584
585 Exceptions
586 ----------
587
588 .. exception:: JSONDecodeError(msg, doc, pos)
589
590 Subclass of :exc:`ValueError` with the following additional attributes:
591
592 .. attribute:: msg
593
594 The unformatted error message.
595
596 .. attribute:: doc
597
598 The JSON document being parsed.
599
600 .. attribute:: pos
601
602 The start index of *doc* where parsing failed.
603
604 .. attribute:: lineno
605
606 The line corresponding to *pos*.
607
608 .. attribute:: colno
609
610 The column corresponding to *pos*.
611
612 .. versionadded:: 3.5
613
614
615 Standard Compliance and Interoperability
616 ----------------------------------------
617
618 The JSON format is specified by :rfc:`7159` and by
619 `ECMA-404 <https://ecma-international.org/publications-and-standards/standards/ecma-404/>`_.
620 This section details this module's level of compliance with the RFC.
621 For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and
622 parameters other than those explicitly mentioned, are not considered.
623
624 This module does not comply with the RFC in a strict fashion, implementing some
625 extensions that are valid JavaScript but not valid JSON. In particular:
626
627 - Infinite and NaN number values are accepted and output;
628 - Repeated names within an object are accepted, and only the value of the last
629 name-value pair is used.
630
631 Since the RFC permits RFC-compliant parsers to accept input texts that are not
632 RFC-compliant, this module's deserializer is technically RFC-compliant under
633 default settings.
634
635 Character Encodings
636 ^^^^^^^^^^^^^^^^^^^
637
638 The RFC requires that JSON be represented using either UTF-8, UTF-16, or
639 UTF-32, with UTF-8 being the recommended default for maximum interoperability.
640
641 As permitted, though not required, by the RFC, this module's serializer sets
642 *ensure_ascii=True* by default, thus escaping the output so that the resulting
643 strings only contain printable ASCII characters.
644
645 Other than the *ensure_ascii* parameter, this module is defined strictly in
646 terms of conversion between Python objects and
647 :class:`Unicode strings <str>`, and thus does not otherwise directly address
648 the issue of character encodings.
649
650 The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text,
651 and this module's serializer does not add a BOM to its output.
652 The RFC permits, but does not require, JSON deserializers to ignore an initial
653 BOM in their input. This module's deserializer raises a :exc:`ValueError`
654 when an initial BOM is present.
655
656 The RFC does not explicitly forbid JSON strings which contain byte sequences
657 that don't correspond to valid Unicode characters (e.g. unpaired UTF-16
658 surrogates), but it does note that they may cause interoperability problems.
659 By default, this module accepts and outputs (when present in the original
660 :class:`str`) code points for such sequences.
661
662
663 Infinite and NaN Number Values
664 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
665
666 The RFC does not permit the representation of infinite or NaN number values.
667 Despite that, by default, this module accepts and outputs ``Infinity``,
668 ``-Infinity``, and ``NaN`` as if they were valid JSON number literal values::
669
670 >>> # Neither of these calls raises an exception, but the results are not valid JSON
671 >>> json.dumps(float('-inf'))
672 '-Infinity'
673 >>> json.dumps(float('nan'))
674 'NaN'
675 >>> # Same when deserializing
676 >>> json.loads('-Infinity')
677 -inf
678 >>> json.loads('NaN')
679 nan
680
681 In the serializer, the *allow_nan* parameter can be used to alter this
682 behavior. In the deserializer, the *parse_constant* parameter can be used to
683 alter this behavior.
684
685
686 Repeated Names Within an Object
687 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
688
689 The RFC specifies that the names within a JSON object should be unique, but
690 does not mandate how repeated names in JSON objects should be handled. By
691 default, this module does not raise an exception; instead, it ignores all but
692 the last name-value pair for a given name::
693
694 >>> weird_json = '{"x": 1, "x": 2, "x": 3}'
695 >>> json.loads(weird_json)
696 {'x': 3}
697
698 The *object_pairs_hook* parameter can be used to alter this behavior.
699
700
701 Top-level Non-Object, Non-Array Values
702 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
703
704 The old version of JSON specified by the obsolete :rfc:`4627` required that
705 the top-level value of a JSON text must be either a JSON object or array
706 (Python :class:`dict` or :class:`list`), and could not be a JSON null,
707 boolean, number, or string value. :rfc:`7159` removed that restriction, and
708 this module does not and has never implemented that restriction in either its
709 serializer or its deserializer.
710
711 Regardless, for maximum interoperability, you may wish to voluntarily adhere
712 to the restriction yourself.
713
714
715 Implementation Limitations
716 ^^^^^^^^^^^^^^^^^^^^^^^^^^
717
718 Some JSON deserializer implementations may set limits on:
719
720 * the size of accepted JSON texts
721 * the maximum level of nesting of JSON objects and arrays
722 * the range and precision of JSON numbers
723 * the content and maximum length of JSON strings
724
725 This module does not impose any such limits beyond those of the relevant
726 Python datatypes themselves or the Python interpreter itself.
727
728 When serializing to JSON, beware any such limitations in applications that may
729 consume your JSON. In particular, it is common for JSON numbers to be
730 deserialized into IEEE 754 double precision numbers and thus subject to that
731 representation's range and precision limitations. This is especially relevant
732 when serializing Python :class:`int` values of extremely large magnitude, or
733 when serializing instances of "exotic" numerical types such as
734 :class:`decimal.Decimal`.
735
736
737 .. _json-commandline:
738 .. program:: json
739
740 Command-line interface
741 ----------------------
742
743 .. module:: json.tool
744 :synopsis: A command-line interface to validate and pretty-print JSON.
745
746 **Source code:** :source:`Lib/json/tool.py`
747
748 --------------
749
750 The :mod:`!json` module can be invoked as a script via ``python -m json``
751 to validate and pretty-print JSON objects. The :mod:`!json.tool` submodule
752 implements this interface.
753
754 If the optional ``infile`` and ``outfile`` arguments are not
755 specified, :data:`sys.stdin` and :data:`sys.stdout` will be used respectively:
756
757 .. code-block:: shell-session
758
759 $ echo '{"json": "obj"}' | python -m json
760 {
761 "json": "obj"
762 }
763 $ echo '{1.2:3.4}' | python -m json
764 Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
765
766 .. versionchanged:: 3.5
767 The output is now in the same order as the input. Use the
768 :option:`--sort-keys` option to sort the output of dictionaries
769 alphabetically by key.
770
771 .. versionchanged:: 3.14
772 The :mod:`!json` module may now be directly executed as
773 ``python -m json``. For backwards compatibility, invoking
774 the CLI as ``python -m json.tool`` remains supported.
775
776
777 Command-line options
778 ^^^^^^^^^^^^^^^^^^^^
779
780 .. option:: infile
781
782 The JSON file to be validated or pretty-printed:
783
784 .. code-block:: shell-session
785
786 $ python -m json mp_films.json
787 [
788 {
789 "title": "And Now for Something Completely Different",
790 "year": 1971
791 },
792 {
793 "title": "Monty Python and the Holy Grail",
794 "year": 1975
795 }
796 ]
797
798 If *infile* is not specified, read from :data:`sys.stdin`.
799
800 .. option:: outfile
801
802 Write the output of the *infile* to the given *outfile*. Otherwise, write it
803 to :data:`sys.stdout`.
804
805 .. option:: --sort-keys
806
807 Sort the output of dictionaries alphabetically by key.
808
809 .. versionadded:: 3.5
810
811 .. option:: --no-ensure-ascii
812
813 Disable escaping of non-ascii characters, see :func:`json.dumps` for more information.
814
815 .. versionadded:: 3.9
816
817 .. option:: --json-lines
818
819 Parse every input line as separate JSON object.
820
821 .. versionadded:: 3.8
822
823 .. option:: --indent, --tab, --no-indent, --compact
824
825 Mutually exclusive options for whitespace control.
826
827 .. versionadded:: 3.9
828
829 .. option:: -h, --help
830
831 Show the help message.
832
833
834 .. rubric:: Footnotes
835
836 .. [#rfc-errata] As noted in `the errata for RFC 7159
837 <https://www.rfc-editor.org/errata_search.php?rfc=7159>`_,
838 JSON permits literal U+2028 (LINE SEPARATOR) and
839 U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript
840 (as of ECMAScript Edition 5.1) does not.