blob: f4875356092ef51c3a5aeb06c7cf30920f0e6b27 [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
Éric Araujode579d42011-04-21 02:37:41 +020046 >>> 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
Ezio Melotti84e59aa2012-04-13 21:02:18 -0600103.. highlight:: bash
Christian Heimes90540002008-05-08 14:29:10 +0000104
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300105Using :mod:`json.tool` from the shell to validate and pretty-print::
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
Ezio Melotti84e59aa2012-04-13 21:02:18 -0600116.. highlight:: python3
Christian Heimes90540002008-05-08 14:29:10 +0000117
Georg Brandl48310cd2009-01-03 21:18:54 +0000118.. note::
Christian Heimes90540002008-05-08 14:29:10 +0000119
Antoine Pitrou331624b2012-08-24 19:37:23 +0200120 JSON is a subset of `YAML <http://yaml.org/>`_ 1.2. The JSON produced by
121 this module's default settings (in particular, the default *separators*
122 value) is also a subset of YAML 1.0 and 1.1. This module can thus also be
123 used as a YAML serializer.
Christian Heimes90540002008-05-08 14:29:10 +0000124
125
126Basic Usage
127-----------
128
Andrew Svetlov2ec53be2012-10-28 14:10:30 +0200129.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, \
130 check_circular=True, allow_nan=True, cls=None, \
131 indent=None, separators=None, default=None, \
132 sort_keys=False, **kw)
Christian Heimes90540002008-05-08 14:29:10 +0000133
134 Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200135 :term:`file-like object`) using this :ref:`conversion table
136 <py-to-json-table>`.
Christian Heimes90540002008-05-08 14:29:10 +0000137
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300138 If *skipkeys* is true (default: ``False``), then dict keys that are not
Antoine Pitrou00d650b2011-01-21 21:37:32 +0000139 of a basic type (:class:`str`, :class:`int`, :class:`float`, :class:`bool`,
140 ``None``) will be skipped instead of raising a :exc:`TypeError`.
Christian Heimes90540002008-05-08 14:29:10 +0000141
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000142 The :mod:`json` module always produces :class:`str` objects, not
143 :class:`bytes` objects. Therefore, ``fp.write()`` must support :class:`str`
144 input.
145
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300146 If *ensure_ascii* is true (the default), the output is guaranteed to
Éric Araujo6f7aa002012-01-16 10:09:20 +0100147 have all incoming non-ASCII characters escaped. If *ensure_ascii* is
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300148 false, these characters will be output as-is.
Éric Araujo6f7aa002012-01-16 10:09:20 +0100149
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300150 If *check_circular* is false (default: ``True``), then the circular
Christian Heimes90540002008-05-08 14:29:10 +0000151 reference check for container types will be skipped and a circular reference
152 will result in an :exc:`OverflowError` (or worse).
153
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300154 If *allow_nan* is false (default: ``True``), then it will be a
Christian Heimes90540002008-05-08 14:29:10 +0000155 :exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300156 ``inf``, ``-inf``) in strict compliance of the JSON specification.
157 If *allow_nan* is true, their JavaScript equivalents (``NaN``,
158 ``Infinity``, ``-Infinity``) will be used.
Christian Heimes90540002008-05-08 14:29:10 +0000159
Raymond Hettingerb643ef82010-10-31 08:00:16 +0000160 If *indent* is a non-negative integer or string, then JSON array elements and
161 object members will be pretty-printed with that indent level. An indent level
R David Murrayd5315482011-04-12 21:09:18 -0400162 of 0, negative, or ``""`` will only insert newlines. ``None`` (the default)
163 selects the most compact representation. Using a positive integer indent
Petri Lehtinen72c6eef2012-08-27 20:27:30 +0300164 indents that many spaces per level. If *indent* is a string (such as ``"\t"``),
R David Murrayd5315482011-04-12 21:09:18 -0400165 that string is used to indent each level.
Christian Heimes90540002008-05-08 14:29:10 +0000166
Petri Lehtinen72b14262012-08-28 07:08:44 +0300167 .. versionchanged:: 3.2
168 Allow strings for *indent* in addition to integers.
169
Ezio Melotti10031442012-11-29 00:42:56 +0200170 If specified, *separators* should be an ``(item_separator, key_separator)``
171 tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and
172 ``(',', ': ')`` otherwise. To get the most compact JSON representation,
173 you should specify ``(',', ':')`` to eliminate whitespace.
174
175 .. versionchanged:: 3.4
176 Use ``(',', ': ')`` as default if *indent* is not ``None``.
Christian Heimes90540002008-05-08 14:29:10 +0000177
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300178 If specified, *default* should be a function that gets called for objects that
179 can't otherwise be serialized. It should return a JSON encodable version of
180 the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
181 is raised.
Christian Heimes90540002008-05-08 14:29:10 +0000182
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300183 If *sort_keys* is true (default: ``False``), then the output of
Andrew Svetlov2ec53be2012-10-28 14:10:30 +0200184 dictionaries will be sorted by key.
185
Georg Brandl1f01deb2009-01-03 22:47:39 +0000186 To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
Christian Heimes90540002008-05-08 14:29:10 +0000187 :meth:`default` method to serialize additional types), specify it with the
Georg Brandld4460aa2010-10-15 17:03:02 +0000188 *cls* kwarg; otherwise :class:`JSONEncoder` is used.
Christian Heimes90540002008-05-08 14:29:10 +0000189
190
Andrew Svetlov2ec53be2012-10-28 14:10:30 +0200191.. function:: dumps(obj, skipkeys=False, ensure_ascii=True, \
192 check_circular=True, allow_nan=True, cls=None, \
193 indent=None, separators=None, default=None, \
194 sort_keys=False, **kw)
Christian Heimes90540002008-05-08 14:29:10 +0000195
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200196 Serialize *obj* to a JSON formatted :class:`str` using this :ref:`conversion
197 table <py-to-json-table>`. The arguments have the same meaning as in
198 :func:`dump`.
Christian Heimes90540002008-05-08 14:29:10 +0000199
Ezio Melotti60adf952011-04-15 07:37:00 +0300200 .. note::
201
Georg Brandl340d2692011-04-16 16:54:15 +0200202 Unlike :mod:`pickle` and :mod:`marshal`, JSON is not a framed protocol,
203 so trying to serialize multiple objects with repeated calls to
204 :func:`dump` using the same *fp* will result in an invalid JSON file.
205
Senthil Kumaranf2123d22012-03-17 00:40:34 -0700206 .. note::
207
208 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
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000215.. 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
Antoine Pitrou15251a92012-08-24 19:49:08 +0200217 Deserialize *fp* (a ``.read()``-supporting :term:`file-like object`
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200218 containing a JSON document) to a Python object using this :ref:`conversion
219 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
230 :class:`dict`. This feature can be used to implement custom decoders that
231 rely on the order that the key and value pairs are decoded (for example,
232 :func:`collections.OrderedDict` will remember the order of insertion). If
233 *object_hook* is also defined, the *object_pairs_hook* takes priority.
234
235 .. versionchanged:: 3.1
Hirokazu Yamamotoae9eb5c2009-04-26 03:34:06 +0000236 Added support for *object_pairs_hook*.
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000237
Christian Heimes90540002008-05-08 14:29:10 +0000238 *parse_float*, if specified, will be called with the string of every JSON
239 float to be decoded. By default, this is equivalent to ``float(num_str)``.
240 This can be used to use another datatype or parser for JSON floats
241 (e.g. :class:`decimal.Decimal`).
242
243 *parse_int*, if specified, will be called with the string of every JSON int
244 to be decoded. By default, this is equivalent to ``int(num_str)``. This can
245 be used to use another datatype or parser for JSON integers
246 (e.g. :class:`float`).
247
248 *parse_constant*, if specified, will be called with one of the following
Hynek Schlawack9729fd42012-05-16 19:01:04 +0200249 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``.
250 This can be used to raise an exception if invalid JSON numbers
Christian Heimes90540002008-05-08 14:29:10 +0000251 are encountered.
252
Hynek Schlawackf54c0602012-05-20 18:32:53 +0200253 .. versionchanged:: 3.1
Hynek Schlawack1203e832012-05-20 12:03:17 +0200254 *parse_constant* doesn't get called on 'null', 'true', 'false' anymore.
255
Christian Heimes90540002008-05-08 14:29:10 +0000256 To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
Georg Brandld4460aa2010-10-15 17:03:02 +0000257 kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments
258 will be passed to the constructor of the class.
Christian Heimes90540002008-05-08 14:29:10 +0000259
Felix Crux60fb9712013-08-12 17:39:51 -0400260 If the data being deserialized is not a valid JSON document, a
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200261 :exc:`JSONDecodeError` will be raised.
Christian Heimes90540002008-05-08 14:29:10 +0000262
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000263.. 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 +0000264
Antoine Pitrou00d650b2011-01-21 21:37:32 +0000265 Deserialize *s* (a :class:`str` instance containing a JSON document) to a
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200266 Python object using this :ref:`conversion table <json-to-py-table>`.
Christian Heimes90540002008-05-08 14:29:10 +0000267
Antoine Pitrou00d650b2011-01-21 21:37:32 +0000268 The other arguments have the same meaning as in :func:`load`, except
269 *encoding* which is ignored and deprecated.
Christian Heimes90540002008-05-08 14:29:10 +0000270
Felix Cruxb4357992013-08-12 17:39:51 -0400271 If the data being deserialized is not a valid JSON document, a
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200272 :exc:`JSONDecodeError` will be raised.
Christian Heimes90540002008-05-08 14:29:10 +0000273
Antoine Pitrou331624b2012-08-24 19:37:23 +0200274Encoders and Decoders
Christian Heimes90540002008-05-08 14:29:10 +0000275---------------------
276
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000277.. 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 +0000278
279 Simple JSON decoder.
280
281 Performs the following translations in decoding by default:
282
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200283 .. _json-to-py-table:
284
Christian Heimes90540002008-05-08 14:29:10 +0000285 +---------------+-------------------+
286 | JSON | Python |
287 +===============+===================+
288 | object | dict |
289 +---------------+-------------------+
290 | array | list |
291 +---------------+-------------------+
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000292 | string | str |
Christian Heimes90540002008-05-08 14:29:10 +0000293 +---------------+-------------------+
Georg Brandl639ce962009-04-11 18:18:16 +0000294 | number (int) | int |
Christian Heimes90540002008-05-08 14:29:10 +0000295 +---------------+-------------------+
296 | number (real) | float |
297 +---------------+-------------------+
298 | true | True |
299 +---------------+-------------------+
300 | false | False |
301 +---------------+-------------------+
302 | null | None |
303 +---------------+-------------------+
304
305 It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
306 corresponding ``float`` values, which is outside the JSON spec.
307
Christian Heimes90540002008-05-08 14:29:10 +0000308 *object_hook*, if specified, will be called with the result of every JSON
309 object decoded and its return value will be used in place of the given
310 :class:`dict`. This can be used to provide custom deserializations (e.g. to
311 support JSON-RPC class hinting).
312
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000313 *object_pairs_hook*, if specified will be called with the result of every
314 JSON object decoded with an ordered list of pairs. The return value of
315 *object_pairs_hook* will be used instead of the :class:`dict`. This
316 feature can be used to implement custom decoders that rely on the order
317 that the key and value pairs are decoded (for example,
318 :func:`collections.OrderedDict` will remember the order of insertion). If
319 *object_hook* is also defined, the *object_pairs_hook* takes priority.
320
321 .. versionchanged:: 3.1
Hirokazu Yamamotoae9eb5c2009-04-26 03:34:06 +0000322 Added support for *object_pairs_hook*.
Raymond Hettinger9b8d0692009-04-21 03:27:12 +0000323
Christian Heimes90540002008-05-08 14:29:10 +0000324 *parse_float*, if specified, will be called with the string of every JSON
325 float to be decoded. By default, this is equivalent to ``float(num_str)``.
326 This can be used to use another datatype or parser for JSON floats
327 (e.g. :class:`decimal.Decimal`).
328
329 *parse_int*, if specified, will be called with the string of every JSON int
330 to be decoded. By default, this is equivalent to ``int(num_str)``. This can
331 be used to use another datatype or parser for JSON integers
332 (e.g. :class:`float`).
333
334 *parse_constant*, if specified, will be called with one of the following
Serhiy Storchaka022371f2016-11-12 22:47:16 +0200335 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``.
336 This can be used to raise an exception if invalid JSON numbers
Christian Heimes90540002008-05-08 14:29:10 +0000337 are encountered.
338
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300339 If *strict* is false (``True`` is the default), then control characters
Georg Brandld4460aa2010-10-15 17:03:02 +0000340 will be allowed inside strings. Control characters in this context are
Serhiy Storchakac7b1a0b2016-11-26 13:43:28 +0200341 those with character codes in the 0--31 range, including ``'\t'`` (tab),
Georg Brandld4460aa2010-10-15 17:03:02 +0000342 ``'\n'``, ``'\r'`` and ``'\0'``.
343
Felix Crux654f0032013-08-12 17:39:51 -0400344 If the data being deserialized is not a valid JSON document, a
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200345 :exc:`JSONDecodeError` will be raised.
Christian Heimes90540002008-05-08 14:29:10 +0000346
347 .. method:: decode(s)
348
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000349 Return the Python representation of *s* (a :class:`str` instance
Martin Panterd21e0b52015-10-10 10:36:22 +0000350 containing a JSON document).
Christian Heimes90540002008-05-08 14:29:10 +0000351
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200352 :exc:`JSONDecodeError` will be raised if the given JSON document is not
353 valid.
354
Christian Heimes90540002008-05-08 14:29:10 +0000355 .. method:: raw_decode(s)
356
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000357 Decode a JSON document from *s* (a :class:`str` beginning with a
358 JSON document) and return a 2-tuple of the Python representation
359 and the index in *s* where the document ended.
Christian Heimes90540002008-05-08 14:29:10 +0000360
361 This can be used to decode a JSON document from a string that may have
362 extraneous data at the end.
363
364
Georg Brandlcd7f32b2009-06-08 09:13:45 +0000365.. 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 +0000366
367 Extensible JSON encoder for Python data structures.
368
369 Supports the following objects and types by default:
370
Ezio Melotti6d2bc6e2013-03-29 03:59:29 +0200371 .. _py-to-json-table:
372
Ethan Furmana4998a72013-08-10 13:01:45 -0700373 +----------------------------------------+---------------+
374 | Python | JSON |
375 +========================================+===============+
376 | dict | object |
377 +----------------------------------------+---------------+
378 | list, tuple | array |
379 +----------------------------------------+---------------+
380 | str | string |
381 +----------------------------------------+---------------+
382 | int, float, int- & float-derived Enums | number |
383 +----------------------------------------+---------------+
384 | True | true |
385 +----------------------------------------+---------------+
386 | False | false |
387 +----------------------------------------+---------------+
388 | None | null |
389 +----------------------------------------+---------------+
390
391 .. versionchanged:: 3.4
392 Added support for int- and float-derived Enum classes.
Christian Heimes90540002008-05-08 14:29:10 +0000393
394 To extend this to recognize other objects, subclass and implement a
395 :meth:`default` method with another method that returns a serializable object
396 for ``o`` if possible, otherwise it should call the superclass implementation
397 (to raise :exc:`TypeError`).
398
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300399 If *skipkeys* is false (the default), then it is a :exc:`TypeError` to
Serhiy Storchakaecf41da2016-10-19 16:29:26 +0300400 attempt encoding of keys that are not :class:`str`, :class:`int`,
401 :class:`float` or ``None``. If *skipkeys* is true, such items are simply
402 skipped.
Christian Heimes90540002008-05-08 14:29:10 +0000403
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300404 If *ensure_ascii* is true (the default), the output is guaranteed to
Benjamin Petersonc6b607d2009-05-02 12:36:44 +0000405 have all incoming non-ASCII characters escaped. If *ensure_ascii* is
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300406 false, these characters will be output as-is.
Christian Heimes90540002008-05-08 14:29:10 +0000407
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300408 If *check_circular* is true (the default), then lists, dicts, and custom
Christian Heimes90540002008-05-08 14:29:10 +0000409 encoded objects will be checked for circular references during encoding to
410 prevent an infinite recursion (which would cause an :exc:`OverflowError`).
411 Otherwise, no such check takes place.
412
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300413 If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and
Christian Heimes90540002008-05-08 14:29:10 +0000414 ``-Infinity`` will be encoded as such. This behavior is not JSON
415 specification compliant, but is consistent with most JavaScript based
416 encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
417 such floats.
418
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300419 If *sort_keys* is true (default: ``False``), then the output of dictionaries
Christian Heimes90540002008-05-08 14:29:10 +0000420 will be sorted by key; this is useful for regression tests to ensure that
421 JSON serializations can be compared on a day-to-day basis.
422
Petri Lehtinen72b14262012-08-28 07:08:44 +0300423 If *indent* is a non-negative integer or string, then JSON array elements and
424 object members will be pretty-printed with that indent level. An indent level
425 of 0, negative, or ``""`` will only insert newlines. ``None`` (the default)
426 selects the most compact representation. Using a positive integer indent
427 indents that many spaces per level. If *indent* is a string (such as ``"\t"``),
428 that string is used to indent each level.
429
430 .. versionchanged:: 3.2
431 Allow strings for *indent* in addition to integers.
Christian Heimes90540002008-05-08 14:29:10 +0000432
433 If specified, *separators* should be an ``(item_separator, key_separator)``
Ezio Melotti10031442012-11-29 00:42:56 +0200434 tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and
435 ``(',', ': ')`` otherwise. To get the most compact JSON representation,
436 you should specify ``(',', ':')`` to eliminate whitespace.
437
438 .. versionchanged:: 3.4
439 Use ``(',', ': ')`` as default if *indent* is not ``None``.
Christian Heimes90540002008-05-08 14:29:10 +0000440
Serhiy Storchaka15287f82016-06-30 13:59:12 +0300441 If specified, *default* should be a function that gets called for objects that
442 can't otherwise be serialized. It should return a JSON encodable version of
443 the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
444 is raised.
Christian Heimes90540002008-05-08 14:29:10 +0000445
Christian Heimes90540002008-05-08 14:29:10 +0000446
447 .. method:: default(o)
448
449 Implement this method in a subclass such that it returns a serializable
450 object for *o*, or calls the base implementation (to raise a
451 :exc:`TypeError`).
452
453 For example, to support arbitrary iterators, you could implement default
454 like this::
Georg Brandl48310cd2009-01-03 21:18:54 +0000455
Christian Heimes90540002008-05-08 14:29:10 +0000456 def default(self, o):
457 try:
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +0000458 iterable = iter(o)
Christian Heimes90540002008-05-08 14:29:10 +0000459 except TypeError:
Benjamin Petersone9bbc8b2008-09-28 02:06:32 +0000460 pass
Christian Heimes90540002008-05-08 14:29:10 +0000461 else:
462 return list(iterable)
R David Murraydd246172013-03-17 21:52:35 -0400463 # Let the base class default method raise the TypeError
Georg Brandl0bb73b82010-09-03 22:36:22 +0000464 return json.JSONEncoder.default(self, o)
Christian Heimes90540002008-05-08 14:29:10 +0000465
466
467 .. method:: encode(o)
468
469 Return a JSON string representation of a Python data structure, *o*. For
470 example::
471
Georg Brandl0bb73b82010-09-03 22:36:22 +0000472 >>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
Christian Heimes90540002008-05-08 14:29:10 +0000473 '{"foo": ["bar", "baz"]}'
474
475
476 .. method:: iterencode(o)
477
478 Encode the given object, *o*, and yield each string representation as
479 available. For example::
Georg Brandl48310cd2009-01-03 21:18:54 +0000480
Georg Brandl0bb73b82010-09-03 22:36:22 +0000481 for chunk in json.JSONEncoder().iterencode(bigobject):
Christian Heimes90540002008-05-08 14:29:10 +0000482 mysocket.write(chunk)
Antoine Pitrou331624b2012-08-24 19:37:23 +0200483
484
Serhiy Storchaka47efb4a2015-01-26 13:16:30 +0200485Exceptions
486----------
487
488.. exception:: JSONDecodeError(msg, doc, pos, end=None)
489
490 Subclass of :exc:`ValueError` with the following additional attributes:
491
492 .. attribute:: msg
493
494 The unformatted error message.
495
496 .. attribute:: doc
497
498 The JSON document being parsed.
499
500 .. attribute:: pos
501
502 The start index of *doc* where parsing failed.
503
504 .. attribute:: lineno
505
506 The line corresponding to *pos*.
507
508 .. attribute:: colno
509
510 The column corresponding to *pos*.
511
512 .. versionadded:: 3.5
513
514
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200515Standard Compliance and Interoperability
516----------------------------------------
Antoine Pitrou331624b2012-08-24 19:37:23 +0200517
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200518The JSON format is specified by :rfc:`7159` and by
519`ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`_.
520This section details this module's level of compliance with the RFC.
521For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and
522parameters other than those explicitly mentioned, are not considered.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200523
524This module does not comply with the RFC in a strict fashion, implementing some
525extensions that are valid JavaScript but not valid JSON. In particular:
526
Antoine Pitrou331624b2012-08-24 19:37:23 +0200527- Infinite and NaN number values are accepted and output;
528- Repeated names within an object are accepted, and only the value of the last
529 name-value pair is used.
530
531Since the RFC permits RFC-compliant parsers to accept input texts that are not
532RFC-compliant, this module's deserializer is technically RFC-compliant under
533default settings.
534
535Character Encodings
536^^^^^^^^^^^^^^^^^^^
537
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200538The RFC requires that JSON be represented using either UTF-8, UTF-16, or
539UTF-32, with UTF-8 being the recommended default for maximum interoperability.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200540
541As permitted, though not required, by the RFC, this module's serializer sets
542*ensure_ascii=True* by default, thus escaping the output so that the resulting
543strings only contain ASCII characters.
544
545Other than the *ensure_ascii* parameter, this module is defined strictly in
546terms of conversion between Python objects and
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200547:class:`Unicode strings <str>`, and thus does not otherwise directly address
548the issue of character encodings.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200549
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200550The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text,
551and this module's serializer does not add a BOM to its output.
552The RFC permits, but does not require, JSON deserializers to ignore an initial
553BOM in their input. This module's deserializer raises a :exc:`ValueError`
554when an initial BOM is present.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200555
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200556The RFC does not explicitly forbid JSON strings which contain byte sequences
557that don't correspond to valid Unicode characters (e.g. unpaired UTF-16
558surrogates), but it does note that they may cause interoperability problems.
559By default, this module accepts and outputs (when present in the original
Serhiy Storchakad3faf432015-01-18 11:28:37 +0200560:class:`str`) code points for such sequences.
Antoine Pitrou331624b2012-08-24 19:37:23 +0200561
562
563Infinite and NaN Number Values
564^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
565
566The RFC does not permit the representation of infinite or NaN number values.
567Despite that, by default, this module accepts and outputs ``Infinity``,
568``-Infinity``, and ``NaN`` as if they were valid JSON number literal values::
569
570 >>> # Neither of these calls raises an exception, but the results are not valid JSON
571 >>> json.dumps(float('-inf'))
572 '-Infinity'
573 >>> json.dumps(float('nan'))
574 'NaN'
575 >>> # Same when deserializing
576 >>> json.loads('-Infinity')
577 -inf
578 >>> json.loads('NaN')
579 nan
580
581In the serializer, the *allow_nan* parameter can be used to alter this
582behavior. In the deserializer, the *parse_constant* parameter can be used to
583alter this behavior.
584
585
586Repeated Names Within an Object
587^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
588
589The RFC specifies that the names within a JSON object should be unique, but
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200590does not mandate how repeated names in JSON objects should be handled. By
Antoine Pitrou331624b2012-08-24 19:37:23 +0200591default, this module does not raise an exception; instead, it ignores all but
592the last name-value pair for a given name::
593
594 >>> weird_json = '{"x": 1, "x": 2, "x": 3}'
595 >>> json.loads(weird_json)
596 {'x': 3}
597
598The *object_pairs_hook* parameter can be used to alter this behavior.
Benjamin Peterson940e2072014-03-21 23:17:29 -0500599
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200600
601Top-level Non-Object, Non-Array Values
602^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
603
604The old version of JSON specified by the obsolete :rfc:`4627` required that
605the top-level value of a JSON text must be either a JSON object or array
606(Python :class:`dict` or :class:`list`), and could not be a JSON null,
607boolean, number, or string value. :rfc:`7159` removed that restriction, and
608this module does not and has never implemented that restriction in either its
609serializer or its deserializer.
610
611Regardless, for maximum interoperability, you may wish to voluntarily adhere
612to the restriction yourself.
613
614
615Implementation Limitations
616^^^^^^^^^^^^^^^^^^^^^^^^^^
617
618Some JSON deserializer implementations may set limits on:
619
620* the size of accepted JSON texts
621* the maximum level of nesting of JSON objects and arrays
622* the range and precision of JSON numbers
623* the content and maximum length of JSON strings
624
625This module does not impose any such limits beyond those of the relevant
626Python datatypes themselves or the Python interpreter itself.
627
628When serializing to JSON, beware any such limitations in applications that may
629consume your JSON. In particular, it is common for JSON numbers to be
630deserialized into IEEE 754 double precision numbers and thus subject to that
631representation's range and precision limitations. This is especially relevant
632when serializing Python :class:`int` values of extremely large magnitude, or
633when serializing instances of "exotic" numerical types such as
634:class:`decimal.Decimal`.
635
Benjamin Peterson940e2072014-03-21 23:17:29 -0500636.. highlight:: bash
637
638.. _json-commandline:
639
640Command Line Interface
641----------------------
642
Terry Jan Reedydcb6c882016-06-22 22:46:34 -0400643.. module:: json.tool
644 :synopsis: A command line to validate and pretty-print JSON.
645
646**Source code:** :source:`Lib/json/tool.py`
647
648--------------
649
Benjamin Peterson940e2072014-03-21 23:17:29 -0500650The :mod:`json.tool` module provides a simple command line interface to validate
651and pretty-print JSON objects.
652
Georg Brandl9e7fbde2014-09-21 00:38:13 +0200653If the optional ``infile`` and ``outfile`` arguments are not
Benjamin Peterson940e2072014-03-21 23:17:29 -0500654specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively::
655
656 $ echo '{"json": "obj"}' | python -m json.tool
657 {
658 "json": "obj"
659 }
660 $ echo '{1.2:3.4}' | python -m json.tool
661 Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
662
Berker Peksag39e4c4d2014-11-10 09:56:54 +0200663.. versionchanged:: 3.5
664 The output is now in the same order as the input. Use the
665 :option:`--sort-keys` option to sort the output of dictionaries
666 alphabetically by key.
Benjamin Peterson940e2072014-03-21 23:17:29 -0500667
668Command line options
669^^^^^^^^^^^^^^^^^^^^
670
Benjamin Petersonfc8e9882014-04-13 19:52:14 -0400671.. cmdoption:: infile
Benjamin Peterson940e2072014-03-21 23:17:29 -0500672
673 The JSON file to be validated or pretty-printed::
674
675 $ python -m json.tool mp_films.json
676 [
677 {
678 "title": "And Now for Something Completely Different",
679 "year": 1971
680 },
681 {
682 "title": "Monty Python and the Holy Grail",
683 "year": 1975
684 }
685 ]
686
Benjamin Petersonfc8e9882014-04-13 19:52:14 -0400687 If *infile* is not specified, read from :attr:`sys.stdin`.
688
689.. cmdoption:: outfile
Benjamin Peterson940e2072014-03-21 23:17:29 -0500690
691 Write the output of the *infile* to the given *outfile*. Otherwise, write it
692 to :attr:`sys.stdout`.
693
Berker Peksag39e4c4d2014-11-10 09:56:54 +0200694.. cmdoption:: --sort-keys
695
696 Sort the output of dictionaries alphabetically by key.
697
698 .. versionadded:: 3.5
699
Benjamin Peterson940e2072014-03-21 23:17:29 -0500700.. cmdoption:: -h, --help
701
702 Show the help message.
Serhiy Storchaka715f01b2014-11-27 19:45:31 +0200703
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200704
705.. rubric:: Footnotes
706
707.. [#rfc-errata] As noted in `the errata for RFC 7159
Serhiy Storchaka6dff0202016-05-07 10:49:07 +0300708 <https://www.rfc-editor.org/errata_search.php?rfc=7159>`_,
Serhiy Storchaka7a6915e2014-11-27 19:41:47 +0200709 JSON permits literal U+2028 (LINE SEPARATOR) and
710 U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript
711 (as of ECMAScript Edition 5.1) does not.