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