blob: 589e86ca81071bd2bbd51f998cb62e84aba33b56 [file] [log] [blame]
Christian Heimes90540002008-05-08 14:29:10 +00001:mod:`json` --- JSON encoder and decoder
2========================================
3
4.. module:: json
5 :synopsis: Encode and decode the JSON format.
Terry Jan Reedyfa089b92016-06-11 15:02:54 -04006
Christian Heimes90540002008-05-08 14:29:10 +00007.. moduleauthor:: Bob Ippolito <bob@redivi.com>
8.. sectionauthor:: Bob Ippolito <bob@redivi.com>
Christian Heimes90540002008-05-08 14:29:10 +00009
Terry Jan Reedyfa089b92016-06-11 15:02:54 -040010**Source code:** :source:`Lib/json/__init__.py`
11
12--------------
13
Antoine Pitrou331624b2012-08-24 19:37:23 +020014`JSON (JavaScript Object Notation) <http://json.org>`_, specified by
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +020015: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
Georg Brandl5d941342016-02-26 19:37:12 +010018`JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +020019(although it is not a strict subset of JavaScript [#rfc-errata]_ ).
Christian Heimes90540002008-05-08 14:29:10 +000020
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::
Georg Brandl48310cd2009-01-03 21:18:54 +000025
Christian Heimes90540002008-05-08 14:29:10 +000026 >>> import json
27 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
28 '["foo", {"bar": ["baz", null, 1.0, 2]}]'
Neal Norwitz752abd02008-05-13 04:55:24 +000029 >>> print(json.dumps("\"foo\bar"))
Christian Heimes90540002008-05-08 14:29:10 +000030 "\"foo\bar"
Benjamin Peterson2505bc62008-05-15 02:17:58 +000031 >>> print(json.dumps('\u1234'))
Christian Heimes90540002008-05-08 14:29:10 +000032 "\u1234"
Neal Norwitz752abd02008-05-13 04:55:24 +000033 >>> print(json.dumps('\\'))
Christian Heimes90540002008-05-08 14:29:10 +000034 "\\"
Neal Norwitz752abd02008-05-13 04:55:24 +000035 >>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True))
Christian Heimes90540002008-05-08 14:29:10 +000036 {"a": 0, "b": 0, "c": 0}
Benjamin Peterson2505bc62008-05-15 02:17:58 +000037 >>> from io import StringIO
Christian Heimes90540002008-05-08 14:29:10 +000038 >>> io = StringIO()
39 >>> json.dump(['streaming API'], io)
40 >>> io.getvalue()
41 '["streaming API"]'
42
43Compact encoding::
44
45 >>> import json
Sergey Fedoseeva7fbad92017-09-09 21:39:36 +050046 >>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':'))
Christian Heimes90540002008-05-08 14:29:10 +000047 '[1,2,3,{"4":5,"6":7}]'
48
49Pretty printing::
50
51 >>> import json
Neal Norwitz752abd02008-05-13 04:55:24 +000052 >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4))
Christian Heimes90540002008-05-08 14:29:10 +000053 {
Georg Brandl48310cd2009-01-03 21:18:54 +000054 "4": 5,
Christian Heimes90540002008-05-08 14:29:10 +000055 "6": 7
56 }
57
58Decoding JSON::
Georg Brandl48310cd2009-01-03 21:18:54 +000059
Christian Heimes90540002008-05-08 14:29:10 +000060 >>> import json
61 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
Benjamin Peterson2505bc62008-05-15 02:17:58 +000062 ['foo', {'bar': ['baz', None, 1.0, 2]}]
Christian Heimes90540002008-05-08 14:29:10 +000063 >>> json.loads('"\\"foo\\bar"')
Benjamin Peterson2505bc62008-05-15 02:17:58 +000064 '"foo\x08ar'
65 >>> from io import StringIO
Christian Heimes90540002008-05-08 14:29:10 +000066 >>> io = StringIO('["streaming API"]')
67 >>> json.load(io)
Benjamin Peterson2505bc62008-05-15 02:17:58 +000068 ['streaming API']
Christian Heimes90540002008-05-08 14:29:10 +000069
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
Benjamin Peterson2505bc62008-05-15 02:17:58 +000077 ...
Christian Heimes90540002008-05-08 14:29:10 +000078 >>> 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`::
Georg Brandl48310cd2009-01-03 21:18:54 +000086
Christian Heimes90540002008-05-08 14:29:10 +000087 >>> import json
88 >>> class ComplexEncoder(json.JSONEncoder):
89 ... def default(self, obj):
90 ... if isinstance(obj, complex):
91 ... return [obj.real, obj.imag]
R David Murraydd246172013-03-17 21:52:35 -040092 ... # Let the base class default method raise the TypeError
Christian Heimes90540002008-05-08 14:29:10 +000093 ... return json.JSONEncoder.default(self, obj)
Benjamin Peterson2505bc62008-05-15 02:17:58 +000094 ...
Georg Brandl0bb73b82010-09-03 22:36:22 +000095 >>> json.dumps(2 + 1j, cls=ComplexEncoder)
Christian Heimes90540002008-05-08 14:29:10 +000096 '[2.0, 1.0]'
97 >>> ComplexEncoder().encode(2 + 1j)
98 '[2.0, 1.0]'
99 >>> list(ComplexEncoder().iterencode(2 + 1j))
Georg Brandl0bb73b82010-09-03 22:36:22 +0000100 ['[2.0', ', 1.0', ']']
Georg Brandl48310cd2009-01-03 21:18:54 +0000101
Christian Heimes90540002008-05-08 14:29:10 +0000102
Serhiy Storchaka46936d52018-04-08 19:18:04 +0300103Using :mod:`json.tool` from the shell to validate and pretty-print:
Christian Heimes90540002008-05-08 14:29:10 +0000104
Serhiy Storchaka46936d52018-04-08 19:18:04 +0300105.. code-block:: shell-session
Georg Brandl48310cd2009-01-03 21:18:54 +0000106
Georg Brandl946faa32014-10-28 22:54:24 +0100107 $ echo '{"json":"obj"}' | python -m json.tool
Christian Heimes90540002008-05-08 14:29:10 +0000108 {
109 "json": "obj"
110 }
Georg Brandl946faa32014-10-28 22:54:24 +0100111 $ echo '{1.2:3.4}' | python -m json.tool
Serhiy Storchakac510a042013-02-21 20:19:16 +0200112 Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
Christian Heimes90540002008-05-08 14:29:10 +0000113
Benjamin Peterson940e2072014-03-21 23:17:29 -0500114See :ref:`json-commandline` for detailed documentation.
115
Georg Brandl48310cd2009-01-03 21:18:54 +0000116.. note::
Christian Heimes90540002008-05-08 14:29:10 +0000117
Antoine Pitrou331624b2012-08-24 19:37:23 +0200118 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.
Christian Heimes90540002008-05-08 14:29:10 +0000122
123
124Basic Usage
125-----------
126
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300127.. function:: dump(obj, fp, *, skipkeys=False, ensure_ascii=True, \
Andrew Svetlov2ec53be2012-10-28 14:10:30 +0200128 check_circular=True, allow_nan=True, cls=None, \
129 indent=None, separators=None, default=None, \
130 sort_keys=False, **kw)
Christian Heimes90540002008-05-08 14:29:10 +0000131
132 Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200133 :term:`file-like object`) using this :ref:`conversion table
134 <py-to-json-table>`.
Christian Heimes90540002008-05-08 14:29:10 +0000135
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300136 If *skipkeys* is true (default: ``False``), then dict keys that are not
Antoine Pitrou00d650b2011-01-21 21:37:32 +0000137 of a basic type (:class:`str`, :class:`int`, :class:`float`, :class:`bool`,
138 ``None``) will be skipped instead of raising a :exc:`TypeError`.
Christian Heimes90540002008-05-08 14:29:10 +0000139
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000140 The :mod:`json` module always produces :class:`str` objects, not
141 :class:`bytes` objects. Therefore, ``fp.write()`` must support :class:`str`
142 input.
143
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300144 If *ensure_ascii* is true (the default), the output is guaranteed to
Éric Araujo6f7aa002012-01-16 10:09:20 +0100145 have all incoming non-ASCII characters escaped. If *ensure_ascii* is
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300146 false, these characters will be output as-is.
Éric Araujo6f7aa002012-01-16 10:09:20 +0100147
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300148 If *check_circular* is false (default: ``True``), then the circular
Christian Heimes90540002008-05-08 14:29:10 +0000149 reference check for container types will be skipped and a circular reference
150 will result in an :exc:`OverflowError` (or worse).
151
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300152 If *allow_nan* is false (default: ``True``), then it will be a
Christian Heimes90540002008-05-08 14:29:10 +0000153 :exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300154 ``inf``, ``-inf``) in strict compliance of the JSON specification.
155 If *allow_nan* is true, their JavaScript equivalents (``NaN``,
156 ``Infinity``, ``-Infinity``) will be used.
Christian Heimes90540002008-05-08 14:29:10 +0000157
Raymond Hettingerb643ef82010-10-31 08:00:16 +0000158 If *indent* is a non-negative integer or string, then JSON array elements and
159 object members will be pretty-printed with that indent level. An indent level
R David Murrayd5315482011-04-12 21:09:18 -0400160 of 0, negative, or ``""`` will only insert newlines. ``None`` (the default)
161 selects the most compact representation. Using a positive integer indent
Petri Lehtinen72c6eef2012-08-27 20:27:30 +0300162 indents that many spaces per level. If *indent* is a string (such as ``"\t"``),
R David Murrayd5315482011-04-12 21:09:18 -0400163 that string is used to indent each level.
Christian Heimes90540002008-05-08 14:29:10 +0000164
Petri Lehtinen72b14262012-08-28 07:08:44 +0300165 .. versionchanged:: 3.2
166 Allow strings for *indent* in addition to integers.
167
Ezio Melotti10031442012-11-29 00:42:56 +0200168 If specified, *separators* should be an ``(item_separator, key_separator)``
169 tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and
170 ``(',', ': ')`` otherwise. To get the most compact JSON representation,
171 you should specify ``(',', ':')`` to eliminate whitespace.
172
173 .. versionchanged:: 3.4
174 Use ``(',', ': ')`` as default if *indent* is not ``None``.
Christian Heimes90540002008-05-08 14:29:10 +0000175
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300176 If specified, *default* should be a function that gets called for objects that
177 can't otherwise be serialized. It should return a JSON encodable version of
178 the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
179 is raised.
Christian Heimes90540002008-05-08 14:29:10 +0000180
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300181 If *sort_keys* is true (default: ``False``), then the output of
Andrew Svetlov2ec53be2012-10-28 14:10:30 +0200182 dictionaries will be sorted by key.
183
Georg Brandl1f01deb2009-01-03 22:47:39 +0000184 To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
Christian Heimes90540002008-05-08 14:29:10 +0000185 :meth:`default` method to serialize additional types), specify it with the
Georg Brandld4460aa2010-10-15 17:03:02 +0000186 *cls* kwarg; otherwise :class:`JSONEncoder` is used.
Christian Heimes90540002008-05-08 14:29:10 +0000187
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300188 .. versionchanged:: 3.6
189 All optional parameters are now :ref:`keyword-only <keyword-only_parameter>`.
Christian Heimes90540002008-05-08 14:29:10 +0000190
Evan Allrich9e840842018-08-11 02:34:02 -0500191 .. note::
192
193 Unlike :mod:`pickle` and :mod:`marshal`, JSON is not a framed protocol,
194 so trying to serialize multiple objects with repeated calls to
195 :func:`dump` using the same *fp* will result in an invalid JSON file.
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300196
197.. function:: dumps(obj, *, skipkeys=False, ensure_ascii=True, \
Andrew Svetlov2ec53be2012-10-28 14:10:30 +0200198 check_circular=True, allow_nan=True, cls=None, \
199 indent=None, separators=None, default=None, \
200 sort_keys=False, **kw)
Christian Heimes90540002008-05-08 14:29:10 +0000201
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200202 Serialize *obj* to a JSON formatted :class:`str` using this :ref:`conversion
203 table <py-to-json-table>`. The arguments have the same meaning as in
204 :func:`dump`.
Christian Heimes90540002008-05-08 14:29:10 +0000205
Ezio Melotti60adf952011-04-15 07:37:00 +0300206 .. note::
207
Senthil Kumaranf2123d22012-03-17 00:40:34 -0700208 Keys in key/value pairs of JSON are always of the type :class:`str`. When
209 a dictionary is converted into JSON, all the keys of the dictionary are
Terry Jan Reedy9cbcc2f2013-03-08 19:35:15 -0500210 coerced to strings. As a result of this, if a dictionary is converted
Senthil Kumaranf2123d22012-03-17 00:40:34 -0700211 into JSON and then back into a dictionary, the dictionary may not equal
212 the original one. That is, ``loads(dumps(x)) != x`` if x has non-string
213 keys.
Christian Heimes90540002008-05-08 14:29:10 +0000214
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300215.. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
Christian Heimes90540002008-05-08 14:29:10 +0000216
Anthony Sottilebb6366b2018-06-07 02:58:12 -0700217 Deserialize *fp* (a ``.read()``-supporting :term:`text file` or
218 :term:`binary file` containing a JSON document) to a Python object using
219 this :ref:`conversion table <json-to-py-table>`.
Christian Heimes90540002008-05-08 14:29:10 +0000220
Christian Heimes90540002008-05-08 14:29:10 +0000221 *object_hook* is an optional function that will be called with the result of
Benjamin Peterson25c95f12009-05-08 20:42:26 +0000222 any object literal decoded (a :class:`dict`). The return value of
Christian Heimes90540002008-05-08 14:29:10 +0000223 *object_hook* will be used instead of the :class:`dict`. This feature can be used
Antoine Pitrou331624b2012-08-24 19:37:23 +0200224 to implement custom decoders (e.g. `JSON-RPC <http://www.jsonrpc.org>`_
225 class hinting).
Christian Heimes90540002008-05-08 14:29:10 +0000226
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000227 *object_pairs_hook* is an optional function that will be called with the
Benjamin Peterson25c95f12009-05-08 20:42:26 +0000228 result of any object literal decoded with an ordered list of pairs. The
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000229 return value of *object_pairs_hook* will be used instead of the
INADA Naoki629338f2018-04-03 12:39:47 +0900230 :class:`dict`. This feature can be used to implement custom decoders.
231 If *object_hook* is also defined, the *object_pairs_hook* takes priority.
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000232
233 .. versionchanged:: 3.1
Hirokazu Yamamotoae9eb5c2009-04-26 03:34:06 +0000234 Added support for *object_pairs_hook*.
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000235
Christian Heimes90540002008-05-08 14:29:10 +0000236 *parse_float*, if specified, will be called with the string of every JSON
237 float to be decoded. By default, this is equivalent to ``float(num_str)``.
238 This can be used to use another datatype or parser for JSON floats
239 (e.g. :class:`decimal.Decimal`).
240
241 *parse_int*, if specified, will be called with the string of every JSON int
242 to be decoded. By default, this is equivalent to ``int(num_str)``. This can
243 be used to use another datatype or parser for JSON integers
244 (e.g. :class:`float`).
245
246 *parse_constant*, if specified, will be called with one of the following
Hynek Schlawack9729fd42012-05-16 19:01:04 +0200247 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``.
248 This can be used to raise an exception if invalid JSON numbers
Christian Heimes90540002008-05-08 14:29:10 +0000249 are encountered.
250
Hynek Schlawackf54c0602012-05-20 18:32:53 +0200251 .. versionchanged:: 3.1
Hynek Schlawack1203e832012-05-20 12:03:17 +0200252 *parse_constant* doesn't get called on 'null', 'true', 'false' anymore.
253
Christian Heimes90540002008-05-08 14:29:10 +0000254 To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
Georg Brandld4460aa2010-10-15 17:03:02 +0000255 kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments
256 will be passed to the constructor of the class.
Christian Heimes90540002008-05-08 14:29:10 +0000257
Felix Crux60fb9712013-08-12 17:39:51 -0400258 If the data being deserialized is not a valid JSON document, a
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200259 :exc:`JSONDecodeError` will be raised.
Christian Heimes90540002008-05-08 14:29:10 +0000260
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300261 .. versionchanged:: 3.6
262 All optional parameters are now :ref:`keyword-only <keyword-only_parameter>`.
263
Anthony Sottilebb6366b2018-06-07 02:58:12 -0700264 .. versionchanged:: 3.6
265 *fp* can now be a :term:`binary file`. The input encoding should be
266 UTF-8, UTF-16 or UTF-32.
267
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300268.. function:: loads(s, *, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
Christian Heimes90540002008-05-08 14:29:10 +0000269
Nick Coghlanb1615622016-09-10 20:16:18 +1000270 Deserialize *s* (a :class:`str`, :class:`bytes` or :class:`bytearray`
271 instance containing a JSON document) to a Python object using this
272 :ref:`conversion table <json-to-py-table>`.
Christian Heimes90540002008-05-08 14:29:10 +0000273
Antoine Pitrou00d650b2011-01-21 21:37:32 +0000274 The other arguments have the same meaning as in :func:`load`, except
275 *encoding* which is ignored and deprecated.
Christian Heimes90540002008-05-08 14:29:10 +0000276
Felix Cruxb4357992013-08-12 17:39:51 -0400277 If the data being deserialized is not a valid JSON document, a
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200278 :exc:`JSONDecodeError` will be raised.
Christian Heimes90540002008-05-08 14:29:10 +0000279
Raymond Hettingera57a8a32017-01-19 21:39:37 -0800280 .. versionchanged:: 3.6
281 *s* can now be of type :class:`bytes` or :class:`bytearray`. The
282 input encoding should be UTF-8, UTF-16 or UTF-32.
283
284
Antoine Pitrou331624b2012-08-24 19:37:23 +0200285Encoders and Decoders
Christian Heimes90540002008-05-08 14:29:10 +0000286---------------------
287
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300288.. class:: JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)
Christian Heimes90540002008-05-08 14:29:10 +0000289
290 Simple JSON decoder.
291
292 Performs the following translations in decoding by default:
293
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200294 .. _json-to-py-table:
295
Christian Heimes90540002008-05-08 14:29:10 +0000296 +---------------+-------------------+
297 | JSON | Python |
298 +===============+===================+
299 | object | dict |
300 +---------------+-------------------+
301 | array | list |
302 +---------------+-------------------+
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000303 | string | str |
Christian Heimes90540002008-05-08 14:29:10 +0000304 +---------------+-------------------+
Georg Brandl639ce962009-04-11 18:18:16 +0000305 | number (int) | int |
Christian Heimes90540002008-05-08 14:29:10 +0000306 +---------------+-------------------+
307 | number (real) | float |
308 +---------------+-------------------+
309 | true | True |
310 +---------------+-------------------+
311 | false | False |
312 +---------------+-------------------+
313 | null | None |
314 +---------------+-------------------+
315
316 It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
317 corresponding ``float`` values, which is outside the JSON spec.
318
Christian Heimes90540002008-05-08 14:29:10 +0000319 *object_hook*, if specified, will be called with the result of every JSON
320 object decoded and its return value will be used in place of the given
321 :class:`dict`. This can be used to provide custom deserializations (e.g. to
322 support JSON-RPC class hinting).
323
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000324 *object_pairs_hook*, if specified will be called with the result of every
325 JSON object decoded with an ordered list of pairs. The return value of
326 *object_pairs_hook* will be used instead of the :class:`dict`. This
INADA Naoki629338f2018-04-03 12:39:47 +0900327 feature can be used to implement custom decoders. If *object_hook* is also
328 defined, the *object_pairs_hook* takes priority.
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000329
330 .. versionchanged:: 3.1
Hirokazu Yamamotoae9eb5c2009-04-26 03:34:06 +0000331 Added support for *object_pairs_hook*.
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000332
Christian Heimes90540002008-05-08 14:29:10 +0000333 *parse_float*, if specified, will be called with the string of every JSON
334 float to be decoded. By default, this is equivalent to ``float(num_str)``.
335 This can be used to use another datatype or parser for JSON floats
336 (e.g. :class:`decimal.Decimal`).
337
338 *parse_int*, if specified, will be called with the string of every JSON int
339 to be decoded. By default, this is equivalent to ``int(num_str)``. This can
340 be used to use another datatype or parser for JSON integers
341 (e.g. :class:`float`).
342
343 *parse_constant*, if specified, will be called with one of the following
Serhiy Storchaka022371f2016-11-12 22:47:16 +0200344 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``.
345 This can be used to raise an exception if invalid JSON numbers
Christian Heimes90540002008-05-08 14:29:10 +0000346 are encountered.
347
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300348 If *strict* is false (``True`` is the default), then control characters
Georg Brandld4460aa2010-10-15 17:03:02 +0000349 will be allowed inside strings. Control characters in this context are
Serhiy Storchakac7b1a0b2016-11-26 13:43:28 +0200350 those with character codes in the 0--31 range, including ``'\t'`` (tab),
Georg Brandld4460aa2010-10-15 17:03:02 +0000351 ``'\n'``, ``'\r'`` and ``'\0'``.
352
Felix Crux654f0032013-08-12 17:39:51 -0400353 If the data being deserialized is not a valid JSON document, a
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200354 :exc:`JSONDecodeError` will be raised.
Christian Heimes90540002008-05-08 14:29:10 +0000355
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300356 .. versionchanged:: 3.6
357 All parameters are now :ref:`keyword-only <keyword-only_parameter>`.
358
Christian Heimes90540002008-05-08 14:29:10 +0000359 .. method:: decode(s)
360
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000361 Return the Python representation of *s* (a :class:`str` instance
Martin Panterd21e0b52015-10-10 10:36:22 +0000362 containing a JSON document).
Christian Heimes90540002008-05-08 14:29:10 +0000363
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200364 :exc:`JSONDecodeError` will be raised if the given JSON document is not
365 valid.
366
Christian Heimes90540002008-05-08 14:29:10 +0000367 .. method:: raw_decode(s)
368
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000369 Decode a JSON document from *s* (a :class:`str` beginning with a
370 JSON document) and return a 2-tuple of the Python representation
371 and the index in *s* where the document ended.
Christian Heimes90540002008-05-08 14:29:10 +0000372
373 This can be used to decode a JSON document from a string that may have
374 extraneous data at the end.
375
376
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300377.. class:: JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)
Christian Heimes90540002008-05-08 14:29:10 +0000378
379 Extensible JSON encoder for Python data structures.
380
381 Supports the following objects and types by default:
382
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200383 .. _py-to-json-table:
384
Ethan Furmana4998a72013-08-10 13:01:45 -0700385 +----------------------------------------+---------------+
386 | Python | JSON |
387 +========================================+===============+
388 | dict | object |
389 +----------------------------------------+---------------+
390 | list, tuple | array |
391 +----------------------------------------+---------------+
392 | str | string |
393 +----------------------------------------+---------------+
394 | int, float, int- & float-derived Enums | number |
395 +----------------------------------------+---------------+
396 | True | true |
397 +----------------------------------------+---------------+
398 | False | false |
399 +----------------------------------------+---------------+
400 | None | null |
401 +----------------------------------------+---------------+
402
403 .. versionchanged:: 3.4
404 Added support for int- and float-derived Enum classes.
Christian Heimes90540002008-05-08 14:29:10 +0000405
406 To extend this to recognize other objects, subclass and implement a
407 :meth:`default` method with another method that returns a serializable object
408 for ``o`` if possible, otherwise it should call the superclass implementation
409 (to raise :exc:`TypeError`).
410
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300411 If *skipkeys* is false (the default), then it is a :exc:`TypeError` to
Serhiy Storchakaecf41da2016-10-19 16:29:26 +0300412 attempt encoding of keys that are not :class:`str`, :class:`int`,
413 :class:`float` or ``None``. If *skipkeys* is true, such items are simply
414 skipped.
Christian Heimes90540002008-05-08 14:29:10 +0000415
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300416 If *ensure_ascii* is true (the default), the output is guaranteed to
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000417 have all incoming non-ASCII characters escaped. If *ensure_ascii* is
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300418 false, these characters will be output as-is.
Christian Heimes90540002008-05-08 14:29:10 +0000419
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300420 If *check_circular* is true (the default), then lists, dicts, and custom
Christian Heimes90540002008-05-08 14:29:10 +0000421 encoded objects will be checked for circular references during encoding to
422 prevent an infinite recursion (which would cause an :exc:`OverflowError`).
423 Otherwise, no such check takes place.
424
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300425 If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and
Christian Heimes90540002008-05-08 14:29:10 +0000426 ``-Infinity`` will be encoded as such. This behavior is not JSON
427 specification compliant, but is consistent with most JavaScript based
428 encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
429 such floats.
430
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300431 If *sort_keys* is true (default: ``False``), then the output of dictionaries
Christian Heimes90540002008-05-08 14:29:10 +0000432 will be sorted by key; this is useful for regression tests to ensure that
433 JSON serializations can be compared on a day-to-day basis.
434
Petri Lehtinen72b14262012-08-28 07:08:44 +0300435 If *indent* is a non-negative integer or string, then JSON array elements and
436 object members will be pretty-printed with that indent level. An indent level
437 of 0, negative, or ``""`` will only insert newlines. ``None`` (the default)
438 selects the most compact representation. Using a positive integer indent
439 indents that many spaces per level. If *indent* is a string (such as ``"\t"``),
440 that string is used to indent each level.
441
442 .. versionchanged:: 3.2
443 Allow strings for *indent* in addition to integers.
Christian Heimes90540002008-05-08 14:29:10 +0000444
445 If specified, *separators* should be an ``(item_separator, key_separator)``
Ezio Melotti10031442012-11-29 00:42:56 +0200446 tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and
447 ``(',', ': ')`` otherwise. To get the most compact JSON representation,
448 you should specify ``(',', ':')`` to eliminate whitespace.
449
450 .. versionchanged:: 3.4
451 Use ``(',', ': ')`` as default if *indent* is not ``None``.
Christian Heimes90540002008-05-08 14:29:10 +0000452
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300453 If specified, *default* should be a function that gets called for objects that
454 can't otherwise be serialized. It should return a JSON encodable version of
455 the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
456 is raised.
Christian Heimes90540002008-05-08 14:29:10 +0000457
Serhiy Storchakaaacd53f2016-06-22 00:03:20 +0300458 .. versionchanged:: 3.6
459 All parameters are now :ref:`keyword-only <keyword-only_parameter>`.
460
Christian Heimes90540002008-05-08 14:29:10 +0000461
462 .. method:: default(o)
463
464 Implement this method in a subclass such that it returns a serializable
465 object for *o*, or calls the base implementation (to raise a
466 :exc:`TypeError`).
467
468 For example, to support arbitrary iterators, you could implement default
469 like this::
Georg Brandl48310cd2009-01-03 21:18:54 +0000470
Christian Heimes90540002008-05-08 14:29:10 +0000471 def default(self, o):
472 try:
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +0000473 iterable = iter(o)
Christian Heimes90540002008-05-08 14:29:10 +0000474 except TypeError:
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +0000475 pass
Christian Heimes90540002008-05-08 14:29:10 +0000476 else:
477 return list(iterable)
R David Murraydd246172013-03-17 21:52:35 -0400478 # Let the base class default method raise the TypeError
Georg Brandl0bb73b82010-09-03 22:36:22 +0000479 return json.JSONEncoder.default(self, o)
Christian Heimes90540002008-05-08 14:29:10 +0000480
481
482 .. method:: encode(o)
483
484 Return a JSON string representation of a Python data structure, *o*. For
485 example::
486
Georg Brandl0bb73b82010-09-03 22:36:22 +0000487 >>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
Christian Heimes90540002008-05-08 14:29:10 +0000488 '{"foo": ["bar", "baz"]}'
489
490
491 .. method:: iterencode(o)
492
493 Encode the given object, *o*, and yield each string representation as
494 available. For example::
Georg Brandl48310cd2009-01-03 21:18:54 +0000495
Georg Brandl0bb73b82010-09-03 22:36:22 +0000496 for chunk in json.JSONEncoder().iterencode(bigobject):
Christian Heimes90540002008-05-08 14:29:10 +0000497 mysocket.write(chunk)
Antoine Pitrou331624b2012-08-24 19:37:23 +0200498
499
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200500Exceptions
501----------
502
Serhiy Storchaka5becf382017-05-27 16:11:18 +0300503.. exception:: JSONDecodeError(msg, doc, pos)
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200504
Martin Panteref107ee2017-01-24 00:26:56 +0000505 Subclass of :exc:`ValueError` with the following additional attributes:
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200506
Martin Panteref107ee2017-01-24 00:26:56 +0000507 .. attribute:: msg
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200508
Martin Panteref107ee2017-01-24 00:26:56 +0000509 The unformatted error message.
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200510
Martin Panteref107ee2017-01-24 00:26:56 +0000511 .. attribute:: doc
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200512
Martin Panteref107ee2017-01-24 00:26:56 +0000513 The JSON document being parsed.
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200514
Martin Panteref107ee2017-01-24 00:26:56 +0000515 .. attribute:: pos
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200516
Martin Panteref107ee2017-01-24 00:26:56 +0000517 The start index of *doc* where parsing failed.
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200518
Martin Panteref107ee2017-01-24 00:26:56 +0000519 .. attribute:: lineno
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200520
Martin Panteref107ee2017-01-24 00:26:56 +0000521 The line corresponding to *pos*.
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200522
Martin Panteref107ee2017-01-24 00:26:56 +0000523 .. attribute:: colno
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200524
Martin Panteref107ee2017-01-24 00:26:56 +0000525 The column corresponding to *pos*.
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200526
527 .. versionadded:: 3.5
528
529
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200530Standard Compliance and Interoperability
531----------------------------------------
Antoine Pitrou331624b2012-08-24 19:37:23 +0200532
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200533The JSON format is specified by :rfc:`7159` and by
534`ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`_.
535This section details this module's level of compliance with the RFC.
536For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and
537parameters other than those explicitly mentioned, are not considered.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200538
539This module does not comply with the RFC in a strict fashion, implementing some
540extensions that are valid JavaScript but not valid JSON. In particular:
541
Antoine Pitrou331624b2012-08-24 19:37:23 +0200542- Infinite and NaN number values are accepted and output;
543- Repeated names within an object are accepted, and only the value of the last
544 name-value pair is used.
545
546Since the RFC permits RFC-compliant parsers to accept input texts that are not
547RFC-compliant, this module's deserializer is technically RFC-compliant under
548default settings.
549
550Character Encodings
551^^^^^^^^^^^^^^^^^^^
552
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200553The RFC requires that JSON be represented using either UTF-8, UTF-16, or
554UTF-32, with UTF-8 being the recommended default for maximum interoperability.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200555
556As permitted, though not required, by the RFC, this module's serializer sets
557*ensure_ascii=True* by default, thus escaping the output so that the resulting
558strings only contain ASCII characters.
559
560Other than the *ensure_ascii* parameter, this module is defined strictly in
561terms of conversion between Python objects and
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200562:class:`Unicode strings <str>`, and thus does not otherwise directly address
563the issue of character encodings.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200564
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200565The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text,
566and this module's serializer does not add a BOM to its output.
567The RFC permits, but does not require, JSON deserializers to ignore an initial
568BOM in their input. This module's deserializer raises a :exc:`ValueError`
569when an initial BOM is present.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200570
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200571The RFC does not explicitly forbid JSON strings which contain byte sequences
572that don't correspond to valid Unicode characters (e.g. unpaired UTF-16
573surrogates), but it does note that they may cause interoperability problems.
574By default, this module accepts and outputs (when present in the original
Serhiy Storchakad3faf432015-01-18 11:28:37 +0200575:class:`str`) code points for such sequences.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200576
577
578Infinite and NaN Number Values
579^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
580
581The RFC does not permit the representation of infinite or NaN number values.
582Despite that, by default, this module accepts and outputs ``Infinity``,
583``-Infinity``, and ``NaN`` as if they were valid JSON number literal values::
584
585 >>> # Neither of these calls raises an exception, but the results are not valid JSON
586 >>> json.dumps(float('-inf'))
587 '-Infinity'
588 >>> json.dumps(float('nan'))
589 'NaN'
590 >>> # Same when deserializing
591 >>> json.loads('-Infinity')
592 -inf
593 >>> json.loads('NaN')
594 nan
595
596In the serializer, the *allow_nan* parameter can be used to alter this
597behavior. In the deserializer, the *parse_constant* parameter can be used to
598alter this behavior.
599
600
601Repeated Names Within an Object
602^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
603
604The RFC specifies that the names within a JSON object should be unique, but
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200605does not mandate how repeated names in JSON objects should be handled. By
Antoine Pitrou331624b2012-08-24 19:37:23 +0200606default, this module does not raise an exception; instead, it ignores all but
607the last name-value pair for a given name::
608
609 >>> weird_json = '{"x": 1, "x": 2, "x": 3}'
610 >>> json.loads(weird_json)
611 {'x': 3}
612
613The *object_pairs_hook* parameter can be used to alter this behavior.
Benjamin Peterson940e2072014-03-21 23:17:29 -0500614
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200615
616Top-level Non-Object, Non-Array Values
617^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
618
619The old version of JSON specified by the obsolete :rfc:`4627` required that
620the top-level value of a JSON text must be either a JSON object or array
621(Python :class:`dict` or :class:`list`), and could not be a JSON null,
622boolean, number, or string value. :rfc:`7159` removed that restriction, and
623this module does not and has never implemented that restriction in either its
624serializer or its deserializer.
625
626Regardless, for maximum interoperability, you may wish to voluntarily adhere
627to the restriction yourself.
628
629
630Implementation Limitations
631^^^^^^^^^^^^^^^^^^^^^^^^^^
632
633Some JSON deserializer implementations may set limits on:
634
635* the size of accepted JSON texts
636* the maximum level of nesting of JSON objects and arrays
637* the range and precision of JSON numbers
638* the content and maximum length of JSON strings
639
640This module does not impose any such limits beyond those of the relevant
641Python datatypes themselves or the Python interpreter itself.
642
643When serializing to JSON, beware any such limitations in applications that may
644consume your JSON. In particular, it is common for JSON numbers to be
645deserialized into IEEE 754 double precision numbers and thus subject to that
646representation's range and precision limitations. This is especially relevant
647when serializing Python :class:`int` values of extremely large magnitude, or
648when serializing instances of "exotic" numerical types such as
649:class:`decimal.Decimal`.
650
Serhiy Storchaka083a7a12018-11-05 17:47:27 +0200651
Benjamin Peterson940e2072014-03-21 23:17:29 -0500652.. _json-commandline:
Serhiy Storchaka083a7a12018-11-05 17:47:27 +0200653.. program:: json.tool
Benjamin Peterson940e2072014-03-21 23:17:29 -0500654
655Command Line Interface
656----------------------
657
Terry Jan Reedydcb6c882016-06-22 22:46:34 -0400658.. module:: json.tool
659 :synopsis: A command line to validate and pretty-print JSON.
660
661**Source code:** :source:`Lib/json/tool.py`
662
663--------------
664
Benjamin Peterson940e2072014-03-21 23:17:29 -0500665The :mod:`json.tool` module provides a simple command line interface to validate
666and pretty-print JSON objects.
667
Georg Brandl9e7fbde2014-09-21 00:38:13 +0200668If the optional ``infile`` and ``outfile`` arguments are not
Serhiy Storchaka46936d52018-04-08 19:18:04 +0300669specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively:
670
671.. code-block:: shell-session
Benjamin Peterson940e2072014-03-21 23:17:29 -0500672
673 $ echo '{"json": "obj"}' | python -m json.tool
674 {
675 "json": "obj"
676 }
677 $ echo '{1.2:3.4}' | python -m json.tool
678 Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
679
Berker Peksag39e4c4d2014-11-10 09:56:54 +0200680.. versionchanged:: 3.5
681 The output is now in the same order as the input. Use the
682 :option:`--sort-keys` option to sort the output of dictionaries
683 alphabetically by key.
Benjamin Peterson940e2072014-03-21 23:17:29 -0500684
Serhiy Storchaka083a7a12018-11-05 17:47:27 +0200685
Benjamin Peterson940e2072014-03-21 23:17:29 -0500686Command line options
687^^^^^^^^^^^^^^^^^^^^
688
Benjamin Petersonfc8e9882014-04-13 19:52:14 -0400689.. cmdoption:: infile
Benjamin Peterson940e2072014-03-21 23:17:29 -0500690
Serhiy Storchaka46936d52018-04-08 19:18:04 +0300691 The JSON file to be validated or pretty-printed:
692
693 .. code-block:: shell-session
Benjamin Peterson940e2072014-03-21 23:17:29 -0500694
695 $ python -m json.tool mp_films.json
696 [
697 {
698 "title": "And Now for Something Completely Different",
699 "year": 1971
700 },
701 {
702 "title": "Monty Python and the Holy Grail",
703 "year": 1975
704 }
705 ]
706
Benjamin Petersonfc8e9882014-04-13 19:52:14 -0400707 If *infile* is not specified, read from :attr:`sys.stdin`.
708
709.. cmdoption:: outfile
Benjamin Peterson940e2072014-03-21 23:17:29 -0500710
711 Write the output of the *infile* to the given *outfile*. Otherwise, write it
712 to :attr:`sys.stdout`.
713
Berker Peksag39e4c4d2014-11-10 09:56:54 +0200714.. cmdoption:: --sort-keys
715
716 Sort the output of dictionaries alphabetically by key.
717
718 .. versionadded:: 3.5
719
HongWeipengf1944792018-11-07 18:09:32 +0800720.. cmdoption:: --json-lines
721
722 Parse every input line as separate JSON object.
723
724 .. versionadded:: 3.8
725
Benjamin Peterson940e2072014-03-21 23:17:29 -0500726.. cmdoption:: -h, --help
727
728 Show the help message.
Serhiy Storchaka715f01b2014-11-27 19:45:31 +0200729
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200730
731.. rubric:: Footnotes
732
733.. [#rfc-errata] As noted in `the errata for RFC 7159
Serhiy Storchaka6dff0202016-05-07 10:49:07 +0300734 <https://www.rfc-editor.org/errata_search.php?rfc=7159>`_,
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200735 JSON permits literal U+2028 (LINE SEPARATOR) and
736 U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript
737 (as of ECMAScript Edition 5.1) does not.