Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 1 | :mod:`json` --- JSON encoder and decoder |
| 2 | ======================================== |
| 3 | |
| 4 | .. module:: json |
| 5 | :synopsis: Encode and decode the JSON format. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Bob Ippolito <bob@redivi.com> |
| 8 | .. sectionauthor:: Bob Ippolito <bob@redivi.com> |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 9 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 10 | **Source code:** :source:`Lib/json/__init__.py` |
| 11 | |
| 12 | -------------- |
| 13 | |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 14 | `JSON (JavaScript Object Notation) <http://json.org>`_, specified by |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 15 | :rfc:`7159` (which obsoletes :rfc:`4627`) and by |
| 16 | `ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`_, |
| 17 | is a lightweight data interchange format inspired by |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 18 | `JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 19 | (although it is not a strict subset of JavaScript [#rfc-errata]_ ). |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 20 | |
| 21 | :mod:`json` exposes an API familiar to users of the standard library |
| 22 | :mod:`marshal` and :mod:`pickle` modules. |
| 23 | |
| 24 | Encoding basic Python object hierarchies:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 25 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 26 | >>> import json |
| 27 | >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) |
| 28 | '["foo", {"bar": ["baz", null, 1.0, 2]}]' |
Neal Norwitz | 752abd0 | 2008-05-13 04:55:24 +0000 | [diff] [blame] | 29 | >>> print(json.dumps("\"foo\bar")) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 30 | "\"foo\bar" |
Benjamin Peterson | 2505bc6 | 2008-05-15 02:17:58 +0000 | [diff] [blame] | 31 | >>> print(json.dumps('\u1234')) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 32 | "\u1234" |
Neal Norwitz | 752abd0 | 2008-05-13 04:55:24 +0000 | [diff] [blame] | 33 | >>> print(json.dumps('\\')) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 34 | "\\" |
Neal Norwitz | 752abd0 | 2008-05-13 04:55:24 +0000 | [diff] [blame] | 35 | >>> print(json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 36 | {"a": 0, "b": 0, "c": 0} |
Benjamin Peterson | 2505bc6 | 2008-05-15 02:17:58 +0000 | [diff] [blame] | 37 | >>> from io import StringIO |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 38 | >>> io = StringIO() |
| 39 | >>> json.dump(['streaming API'], io) |
| 40 | >>> io.getvalue() |
| 41 | '["streaming API"]' |
| 42 | |
| 43 | Compact encoding:: |
| 44 | |
| 45 | >>> import json |
Sergey Fedoseev | a7fbad9 | 2017-09-09 21:39:36 +0500 | [diff] [blame] | 46 | >>> json.dumps([1, 2, 3, {'4': 5, '6': 7}], separators=(',', ':')) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 47 | '[1,2,3,{"4":5,"6":7}]' |
| 48 | |
| 49 | Pretty printing:: |
| 50 | |
| 51 | >>> import json |
Neal Norwitz | 752abd0 | 2008-05-13 04:55:24 +0000 | [diff] [blame] | 52 | >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 53 | { |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 54 | "4": 5, |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 55 | "6": 7 |
| 56 | } |
| 57 | |
| 58 | Decoding JSON:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 59 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 60 | >>> import json |
| 61 | >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') |
Benjamin Peterson | 2505bc6 | 2008-05-15 02:17:58 +0000 | [diff] [blame] | 62 | ['foo', {'bar': ['baz', None, 1.0, 2]}] |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 63 | >>> json.loads('"\\"foo\\bar"') |
Benjamin Peterson | 2505bc6 | 2008-05-15 02:17:58 +0000 | [diff] [blame] | 64 | '"foo\x08ar' |
| 65 | >>> from io import StringIO |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 66 | >>> io = StringIO('["streaming API"]') |
| 67 | >>> json.load(io) |
Benjamin Peterson | 2505bc6 | 2008-05-15 02:17:58 +0000 | [diff] [blame] | 68 | ['streaming API'] |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 69 | |
| 70 | Specializing 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 Peterson | 2505bc6 | 2008-05-15 02:17:58 +0000 | [diff] [blame] | 77 | ... |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 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 | |
| 85 | Extending :class:`JSONEncoder`:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 86 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 87 | >>> 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 Murray | dd24617 | 2013-03-17 21:52:35 -0400 | [diff] [blame] | 92 | ... # Let the base class default method raise the TypeError |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 93 | ... return json.JSONEncoder.default(self, obj) |
Benjamin Peterson | 2505bc6 | 2008-05-15 02:17:58 +0000 | [diff] [blame] | 94 | ... |
Georg Brandl | 0bb73b8 | 2010-09-03 22:36:22 +0000 | [diff] [blame] | 95 | >>> json.dumps(2 + 1j, cls=ComplexEncoder) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 96 | '[2.0, 1.0]' |
| 97 | >>> ComplexEncoder().encode(2 + 1j) |
| 98 | '[2.0, 1.0]' |
| 99 | >>> list(ComplexEncoder().iterencode(2 + 1j)) |
Georg Brandl | 0bb73b8 | 2010-09-03 22:36:22 +0000 | [diff] [blame] | 100 | ['[2.0', ', 1.0', ']'] |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 101 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 102 | |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 103 | Using :mod:`json.tool` from the shell to validate and pretty-print: |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 104 | |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 105 | .. code-block:: shell-session |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 106 | |
Georg Brandl | 946faa3 | 2014-10-28 22:54:24 +0100 | [diff] [blame] | 107 | $ echo '{"json":"obj"}' | python -m json.tool |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 108 | { |
| 109 | "json": "obj" |
| 110 | } |
Georg Brandl | 946faa3 | 2014-10-28 22:54:24 +0100 | [diff] [blame] | 111 | $ echo '{1.2:3.4}' | python -m json.tool |
Serhiy Storchaka | c510a04 | 2013-02-21 20:19:16 +0200 | [diff] [blame] | 112 | Expecting property name enclosed in double quotes: line 1 column 2 (char 1) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 113 | |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 114 | See :ref:`json-commandline` for detailed documentation. |
| 115 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 116 | .. note:: |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 117 | |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 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. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 122 | |
| 123 | |
| 124 | Basic Usage |
| 125 | ----------- |
| 126 | |
Serhiy Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 127 | .. function:: dump(obj, fp, *, skipkeys=False, ensure_ascii=True, \ |
Andrew Svetlov | 2ec53be | 2012-10-28 14:10:30 +0200 | [diff] [blame] | 128 | check_circular=True, allow_nan=True, cls=None, \ |
| 129 | indent=None, separators=None, default=None, \ |
| 130 | sort_keys=False, **kw) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 131 | |
| 132 | Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting |
Ezio Melotti | 6d2bc6e | 2013-03-29 03:59:29 +0200 | [diff] [blame] | 133 | :term:`file-like object`) using this :ref:`conversion table |
| 134 | <py-to-json-table>`. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 135 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 136 | If *skipkeys* is true (default: ``False``), then dict keys that are not |
Antoine Pitrou | 00d650b | 2011-01-21 21:37:32 +0000 | [diff] [blame] | 137 | of a basic type (:class:`str`, :class:`int`, :class:`float`, :class:`bool`, |
| 138 | ``None``) will be skipped instead of raising a :exc:`TypeError`. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 139 | |
Benjamin Peterson | c6b607d | 2009-05-02 12:36:44 +0000 | [diff] [blame] | 140 | 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 Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 144 | If *ensure_ascii* is true (the default), the output is guaranteed to |
Éric Araujo | 6f7aa00 | 2012-01-16 10:09:20 +0100 | [diff] [blame] | 145 | have all incoming non-ASCII characters escaped. If *ensure_ascii* is |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 146 | false, these characters will be output as-is. |
Éric Araujo | 6f7aa00 | 2012-01-16 10:09:20 +0100 | [diff] [blame] | 147 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 148 | If *check_circular* is false (default: ``True``), then the circular |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 149 | reference check for container types will be skipped and a circular reference |
| 150 | will result in an :exc:`OverflowError` (or worse). |
| 151 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 152 | If *allow_nan* is false (default: ``True``), then it will be a |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 153 | :exc:`ValueError` to serialize out of range :class:`float` values (``nan``, |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 154 | ``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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 157 | |
Raymond Hettinger | b643ef8 | 2010-10-31 08:00:16 +0000 | [diff] [blame] | 158 | 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 Murray | d531548 | 2011-04-12 21:09:18 -0400 | [diff] [blame] | 160 | of 0, negative, or ``""`` will only insert newlines. ``None`` (the default) |
| 161 | selects the most compact representation. Using a positive integer indent |
Petri Lehtinen | 72c6eef | 2012-08-27 20:27:30 +0300 | [diff] [blame] | 162 | indents that many spaces per level. If *indent* is a string (such as ``"\t"``), |
R David Murray | d531548 | 2011-04-12 21:09:18 -0400 | [diff] [blame] | 163 | that string is used to indent each level. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 164 | |
Petri Lehtinen | 72b1426 | 2012-08-28 07:08:44 +0300 | [diff] [blame] | 165 | .. versionchanged:: 3.2 |
| 166 | Allow strings for *indent* in addition to integers. |
| 167 | |
Ezio Melotti | 1003144 | 2012-11-29 00:42:56 +0200 | [diff] [blame] | 168 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 175 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 176 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 180 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 181 | If *sort_keys* is true (default: ``False``), then the output of |
Andrew Svetlov | 2ec53be | 2012-10-28 14:10:30 +0200 | [diff] [blame] | 182 | dictionaries will be sorted by key. |
| 183 | |
Georg Brandl | 1f01deb | 2009-01-03 22:47:39 +0000 | [diff] [blame] | 184 | To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 185 | :meth:`default` method to serialize additional types), specify it with the |
Georg Brandl | d4460aa | 2010-10-15 17:03:02 +0000 | [diff] [blame] | 186 | *cls* kwarg; otherwise :class:`JSONEncoder` is used. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 187 | |
Serhiy Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 188 | .. versionchanged:: 3.6 |
| 189 | All optional parameters are now :ref:`keyword-only <keyword-only_parameter>`. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 190 | |
Evan Allrich | 9e84084 | 2018-08-11 02:34:02 -0500 | [diff] [blame] | 191 | .. 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 Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 196 | |
| 197 | .. function:: dumps(obj, *, skipkeys=False, ensure_ascii=True, \ |
Andrew Svetlov | 2ec53be | 2012-10-28 14:10:30 +0200 | [diff] [blame] | 198 | check_circular=True, allow_nan=True, cls=None, \ |
| 199 | indent=None, separators=None, default=None, \ |
| 200 | sort_keys=False, **kw) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 201 | |
Ezio Melotti | 6d2bc6e | 2013-03-29 03:59:29 +0200 | [diff] [blame] | 202 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 205 | |
Ezio Melotti | 60adf95 | 2011-04-15 07:37:00 +0300 | [diff] [blame] | 206 | .. note:: |
| 207 | |
Senthil Kumaran | f2123d2 | 2012-03-17 00:40:34 -0700 | [diff] [blame] | 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 Reedy | 9cbcc2f | 2013-03-08 19:35:15 -0500 | [diff] [blame] | 210 | coerced to strings. As a result of this, if a dictionary is converted |
Senthil Kumaran | f2123d2 | 2012-03-17 00:40:34 -0700 | [diff] [blame] | 211 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 214 | |
Serhiy Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 215 | .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 216 | |
Anthony Sottile | bb6366b | 2018-06-07 02:58:12 -0700 | [diff] [blame] | 217 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 220 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 221 | *object_hook* is an optional function that will be called with the result of |
Benjamin Peterson | 25c95f1 | 2009-05-08 20:42:26 +0000 | [diff] [blame] | 222 | any object literal decoded (a :class:`dict`). The return value of |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 223 | *object_hook* will be used instead of the :class:`dict`. This feature can be used |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 224 | to implement custom decoders (e.g. `JSON-RPC <http://www.jsonrpc.org>`_ |
| 225 | class hinting). |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 226 | |
Raymond Hettinger | 9b8d069 | 2009-04-21 03:27:12 +0000 | [diff] [blame] | 227 | *object_pairs_hook* is an optional function that will be called with the |
Benjamin Peterson | 25c95f1 | 2009-05-08 20:42:26 +0000 | [diff] [blame] | 228 | result of any object literal decoded with an ordered list of pairs. The |
Raymond Hettinger | 9b8d069 | 2009-04-21 03:27:12 +0000 | [diff] [blame] | 229 | return value of *object_pairs_hook* will be used instead of the |
INADA Naoki | 629338f | 2018-04-03 12:39:47 +0900 | [diff] [blame] | 230 | :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 Hettinger | 9b8d069 | 2009-04-21 03:27:12 +0000 | [diff] [blame] | 232 | |
| 233 | .. versionchanged:: 3.1 |
Hirokazu Yamamoto | ae9eb5c | 2009-04-26 03:34:06 +0000 | [diff] [blame] | 234 | Added support for *object_pairs_hook*. |
Raymond Hettinger | 9b8d069 | 2009-04-21 03:27:12 +0000 | [diff] [blame] | 235 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 236 | *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 Schlawack | 9729fd4 | 2012-05-16 19:01:04 +0200 | [diff] [blame] | 247 | strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. |
| 248 | This can be used to raise an exception if invalid JSON numbers |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 249 | are encountered. |
| 250 | |
Hynek Schlawack | f54c060 | 2012-05-20 18:32:53 +0200 | [diff] [blame] | 251 | .. versionchanged:: 3.1 |
Hynek Schlawack | 1203e83 | 2012-05-20 12:03:17 +0200 | [diff] [blame] | 252 | *parse_constant* doesn't get called on 'null', 'true', 'false' anymore. |
| 253 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 254 | To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls`` |
Georg Brandl | d4460aa | 2010-10-15 17:03:02 +0000 | [diff] [blame] | 255 | kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments |
| 256 | will be passed to the constructor of the class. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 257 | |
Felix Crux | 60fb971 | 2013-08-12 17:39:51 -0400 | [diff] [blame] | 258 | If the data being deserialized is not a valid JSON document, a |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 259 | :exc:`JSONDecodeError` will be raised. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 260 | |
Serhiy Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 261 | .. versionchanged:: 3.6 |
| 262 | All optional parameters are now :ref:`keyword-only <keyword-only_parameter>`. |
| 263 | |
Anthony Sottile | bb6366b | 2018-06-07 02:58:12 -0700 | [diff] [blame] | 264 | .. 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 Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 268 | .. 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 269 | |
Nick Coghlan | b161562 | 2016-09-10 20:16:18 +1000 | [diff] [blame] | 270 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 273 | |
Antoine Pitrou | 00d650b | 2011-01-21 21:37:32 +0000 | [diff] [blame] | 274 | The other arguments have the same meaning as in :func:`load`, except |
| 275 | *encoding* which is ignored and deprecated. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 276 | |
Felix Crux | b435799 | 2013-08-12 17:39:51 -0400 | [diff] [blame] | 277 | If the data being deserialized is not a valid JSON document, a |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 278 | :exc:`JSONDecodeError` will be raised. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 279 | |
Raymond Hettinger | a57a8a3 | 2017-01-19 21:39:37 -0800 | [diff] [blame] | 280 | .. 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 Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 285 | Encoders and Decoders |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 286 | --------------------- |
| 287 | |
Serhiy Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 288 | .. class:: JSONDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 289 | |
| 290 | Simple JSON decoder. |
| 291 | |
| 292 | Performs the following translations in decoding by default: |
| 293 | |
Ezio Melotti | 6d2bc6e | 2013-03-29 03:59:29 +0200 | [diff] [blame] | 294 | .. _json-to-py-table: |
| 295 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 296 | +---------------+-------------------+ |
| 297 | | JSON | Python | |
| 298 | +===============+===================+ |
| 299 | | object | dict | |
| 300 | +---------------+-------------------+ |
| 301 | | array | list | |
| 302 | +---------------+-------------------+ |
Benjamin Peterson | c6b607d | 2009-05-02 12:36:44 +0000 | [diff] [blame] | 303 | | string | str | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 304 | +---------------+-------------------+ |
Georg Brandl | 639ce96 | 2009-04-11 18:18:16 +0000 | [diff] [blame] | 305 | | number (int) | int | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 306 | +---------------+-------------------+ |
| 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 319 | *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 Hettinger | 9b8d069 | 2009-04-21 03:27:12 +0000 | [diff] [blame] | 324 | *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 Naoki | 629338f | 2018-04-03 12:39:47 +0900 | [diff] [blame] | 327 | feature can be used to implement custom decoders. If *object_hook* is also |
| 328 | defined, the *object_pairs_hook* takes priority. |
Raymond Hettinger | 9b8d069 | 2009-04-21 03:27:12 +0000 | [diff] [blame] | 329 | |
| 330 | .. versionchanged:: 3.1 |
Hirokazu Yamamoto | ae9eb5c | 2009-04-26 03:34:06 +0000 | [diff] [blame] | 331 | Added support for *object_pairs_hook*. |
Raymond Hettinger | 9b8d069 | 2009-04-21 03:27:12 +0000 | [diff] [blame] | 332 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 333 | *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 Storchaka | 022371f | 2016-11-12 22:47:16 +0200 | [diff] [blame] | 344 | strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. |
| 345 | This can be used to raise an exception if invalid JSON numbers |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 346 | are encountered. |
| 347 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 348 | If *strict* is false (``True`` is the default), then control characters |
Georg Brandl | d4460aa | 2010-10-15 17:03:02 +0000 | [diff] [blame] | 349 | will be allowed inside strings. Control characters in this context are |
Serhiy Storchaka | c7b1a0b | 2016-11-26 13:43:28 +0200 | [diff] [blame] | 350 | those with character codes in the 0--31 range, including ``'\t'`` (tab), |
Georg Brandl | d4460aa | 2010-10-15 17:03:02 +0000 | [diff] [blame] | 351 | ``'\n'``, ``'\r'`` and ``'\0'``. |
| 352 | |
Felix Crux | 654f003 | 2013-08-12 17:39:51 -0400 | [diff] [blame] | 353 | If the data being deserialized is not a valid JSON document, a |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 354 | :exc:`JSONDecodeError` will be raised. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 355 | |
Serhiy Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 356 | .. versionchanged:: 3.6 |
| 357 | All parameters are now :ref:`keyword-only <keyword-only_parameter>`. |
| 358 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 359 | .. method:: decode(s) |
| 360 | |
Benjamin Peterson | c6b607d | 2009-05-02 12:36:44 +0000 | [diff] [blame] | 361 | Return the Python representation of *s* (a :class:`str` instance |
Martin Panter | d21e0b5 | 2015-10-10 10:36:22 +0000 | [diff] [blame] | 362 | containing a JSON document). |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 363 | |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 364 | :exc:`JSONDecodeError` will be raised if the given JSON document is not |
| 365 | valid. |
| 366 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 367 | .. method:: raw_decode(s) |
| 368 | |
Benjamin Peterson | c6b607d | 2009-05-02 12:36:44 +0000 | [diff] [blame] | 369 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 372 | |
| 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 Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 377 | .. class:: JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 378 | |
| 379 | Extensible JSON encoder for Python data structures. |
| 380 | |
| 381 | Supports the following objects and types by default: |
| 382 | |
Ezio Melotti | 6d2bc6e | 2013-03-29 03:59:29 +0200 | [diff] [blame] | 383 | .. _py-to-json-table: |
| 384 | |
Ethan Furman | a4998a7 | 2013-08-10 13:01:45 -0700 | [diff] [blame] | 385 | +----------------------------------------+---------------+ |
| 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 405 | |
| 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 Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 411 | If *skipkeys* is false (the default), then it is a :exc:`TypeError` to |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 412 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 415 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 416 | If *ensure_ascii* is true (the default), the output is guaranteed to |
Benjamin Peterson | c6b607d | 2009-05-02 12:36:44 +0000 | [diff] [blame] | 417 | have all incoming non-ASCII characters escaped. If *ensure_ascii* is |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 418 | false, these characters will be output as-is. |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 419 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 420 | If *check_circular* is true (the default), then lists, dicts, and custom |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 421 | 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 Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 425 | If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 426 | ``-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 Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 431 | If *sort_keys* is true (default: ``False``), then the output of dictionaries |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 432 | 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 Lehtinen | 72b1426 | 2012-08-28 07:08:44 +0300 | [diff] [blame] | 435 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 444 | |
| 445 | If specified, *separators* should be an ``(item_separator, key_separator)`` |
Ezio Melotti | 1003144 | 2012-11-29 00:42:56 +0200 | [diff] [blame] | 446 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 452 | |
Serhiy Storchaka | 15287f8 | 2016-06-30 13:59:12 +0300 | [diff] [blame] | 453 | 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 Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 457 | |
Serhiy Storchaka | aacd53f | 2016-06-22 00:03:20 +0300 | [diff] [blame] | 458 | .. versionchanged:: 3.6 |
| 459 | All parameters are now :ref:`keyword-only <keyword-only_parameter>`. |
| 460 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 461 | |
| 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 Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 470 | |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 471 | def default(self, o): |
| 472 | try: |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 473 | iterable = iter(o) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 474 | except TypeError: |
Benjamin Peterson | e9bbc8b | 2008-09-28 02:06:32 +0000 | [diff] [blame] | 475 | pass |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 476 | else: |
| 477 | return list(iterable) |
R David Murray | dd24617 | 2013-03-17 21:52:35 -0400 | [diff] [blame] | 478 | # Let the base class default method raise the TypeError |
Georg Brandl | 0bb73b8 | 2010-09-03 22:36:22 +0000 | [diff] [blame] | 479 | return json.JSONEncoder.default(self, o) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 480 | |
| 481 | |
| 482 | .. method:: encode(o) |
| 483 | |
| 484 | Return a JSON string representation of a Python data structure, *o*. For |
| 485 | example:: |
| 486 | |
Georg Brandl | 0bb73b8 | 2010-09-03 22:36:22 +0000 | [diff] [blame] | 487 | >>> json.JSONEncoder().encode({"foo": ["bar", "baz"]}) |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 488 | '{"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 Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 495 | |
Georg Brandl | 0bb73b8 | 2010-09-03 22:36:22 +0000 | [diff] [blame] | 496 | for chunk in json.JSONEncoder().iterencode(bigobject): |
Christian Heimes | 9054000 | 2008-05-08 14:29:10 +0000 | [diff] [blame] | 497 | mysocket.write(chunk) |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 498 | |
| 499 | |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 500 | Exceptions |
| 501 | ---------- |
| 502 | |
Serhiy Storchaka | 5becf38 | 2017-05-27 16:11:18 +0300 | [diff] [blame] | 503 | .. exception:: JSONDecodeError(msg, doc, pos) |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 504 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 505 | Subclass of :exc:`ValueError` with the following additional attributes: |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 506 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 507 | .. attribute:: msg |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 508 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 509 | The unformatted error message. |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 510 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 511 | .. attribute:: doc |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 512 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 513 | The JSON document being parsed. |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 514 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 515 | .. attribute:: pos |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 516 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 517 | The start index of *doc* where parsing failed. |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 518 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 519 | .. attribute:: lineno |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 520 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 521 | The line corresponding to *pos*. |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 522 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 523 | .. attribute:: colno |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 524 | |
Martin Panter | ef107ee | 2017-01-24 00:26:56 +0000 | [diff] [blame] | 525 | The column corresponding to *pos*. |
Serhiy Storchaka | 47efb4a | 2015-01-26 13:16:30 +0200 | [diff] [blame] | 526 | |
| 527 | .. versionadded:: 3.5 |
| 528 | |
| 529 | |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 530 | Standard Compliance and Interoperability |
| 531 | ---------------------------------------- |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 532 | |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 533 | The JSON format is specified by :rfc:`7159` and by |
| 534 | `ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`_. |
| 535 | This section details this module's level of compliance with the RFC. |
| 536 | For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and |
| 537 | parameters other than those explicitly mentioned, are not considered. |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 538 | |
| 539 | This module does not comply with the RFC in a strict fashion, implementing some |
| 540 | extensions that are valid JavaScript but not valid JSON. In particular: |
| 541 | |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 542 | - 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 | |
| 546 | Since the RFC permits RFC-compliant parsers to accept input texts that are not |
| 547 | RFC-compliant, this module's deserializer is technically RFC-compliant under |
| 548 | default settings. |
| 549 | |
| 550 | Character Encodings |
| 551 | ^^^^^^^^^^^^^^^^^^^ |
| 552 | |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 553 | The RFC requires that JSON be represented using either UTF-8, UTF-16, or |
| 554 | UTF-32, with UTF-8 being the recommended default for maximum interoperability. |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 555 | |
| 556 | As 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 |
| 558 | strings only contain ASCII characters. |
| 559 | |
| 560 | Other than the *ensure_ascii* parameter, this module is defined strictly in |
| 561 | terms of conversion between Python objects and |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 562 | :class:`Unicode strings <str>`, and thus does not otherwise directly address |
| 563 | the issue of character encodings. |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 564 | |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 565 | The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text, |
| 566 | and this module's serializer does not add a BOM to its output. |
| 567 | The RFC permits, but does not require, JSON deserializers to ignore an initial |
| 568 | BOM in their input. This module's deserializer raises a :exc:`ValueError` |
| 569 | when an initial BOM is present. |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 570 | |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 571 | The RFC does not explicitly forbid JSON strings which contain byte sequences |
| 572 | that don't correspond to valid Unicode characters (e.g. unpaired UTF-16 |
| 573 | surrogates), but it does note that they may cause interoperability problems. |
| 574 | By default, this module accepts and outputs (when present in the original |
Serhiy Storchaka | d3faf43 | 2015-01-18 11:28:37 +0200 | [diff] [blame] | 575 | :class:`str`) code points for such sequences. |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 576 | |
| 577 | |
| 578 | Infinite and NaN Number Values |
| 579 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 580 | |
| 581 | The RFC does not permit the representation of infinite or NaN number values. |
| 582 | Despite 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 | |
| 596 | In the serializer, the *allow_nan* parameter can be used to alter this |
| 597 | behavior. In the deserializer, the *parse_constant* parameter can be used to |
| 598 | alter this behavior. |
| 599 | |
| 600 | |
| 601 | Repeated Names Within an Object |
| 602 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 603 | |
| 604 | The RFC specifies that the names within a JSON object should be unique, but |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 605 | does not mandate how repeated names in JSON objects should be handled. By |
Antoine Pitrou | 331624b | 2012-08-24 19:37:23 +0200 | [diff] [blame] | 606 | default, this module does not raise an exception; instead, it ignores all but |
| 607 | the 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 | |
| 613 | The *object_pairs_hook* parameter can be used to alter this behavior. |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 614 | |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 615 | |
| 616 | Top-level Non-Object, Non-Array Values |
| 617 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 618 | |
| 619 | The old version of JSON specified by the obsolete :rfc:`4627` required that |
| 620 | the 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, |
| 622 | boolean, number, or string value. :rfc:`7159` removed that restriction, and |
| 623 | this module does not and has never implemented that restriction in either its |
| 624 | serializer or its deserializer. |
| 625 | |
| 626 | Regardless, for maximum interoperability, you may wish to voluntarily adhere |
| 627 | to the restriction yourself. |
| 628 | |
| 629 | |
| 630 | Implementation Limitations |
| 631 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 632 | |
| 633 | Some 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 | |
| 640 | This module does not impose any such limits beyond those of the relevant |
| 641 | Python datatypes themselves or the Python interpreter itself. |
| 642 | |
| 643 | When serializing to JSON, beware any such limitations in applications that may |
| 644 | consume your JSON. In particular, it is common for JSON numbers to be |
| 645 | deserialized into IEEE 754 double precision numbers and thus subject to that |
| 646 | representation's range and precision limitations. This is especially relevant |
| 647 | when serializing Python :class:`int` values of extremely large magnitude, or |
| 648 | when serializing instances of "exotic" numerical types such as |
| 649 | :class:`decimal.Decimal`. |
| 650 | |
Serhiy Storchaka | 083a7a1 | 2018-11-05 17:47:27 +0200 | [diff] [blame] | 651 | |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 652 | .. _json-commandline: |
Serhiy Storchaka | 083a7a1 | 2018-11-05 17:47:27 +0200 | [diff] [blame] | 653 | .. program:: json.tool |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 654 | |
| 655 | Command Line Interface |
| 656 | ---------------------- |
| 657 | |
Terry Jan Reedy | dcb6c88 | 2016-06-22 22:46:34 -0400 | [diff] [blame] | 658 | .. 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 Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 665 | The :mod:`json.tool` module provides a simple command line interface to validate |
| 666 | and pretty-print JSON objects. |
| 667 | |
Georg Brandl | 9e7fbde | 2014-09-21 00:38:13 +0200 | [diff] [blame] | 668 | If the optional ``infile`` and ``outfile`` arguments are not |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 669 | specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively: |
| 670 | |
| 671 | .. code-block:: shell-session |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 672 | |
| 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 Peksag | 39e4c4d | 2014-11-10 09:56:54 +0200 | [diff] [blame] | 680 | .. 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 Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 684 | |
Serhiy Storchaka | 083a7a1 | 2018-11-05 17:47:27 +0200 | [diff] [blame] | 685 | |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 686 | Command line options |
| 687 | ^^^^^^^^^^^^^^^^^^^^ |
| 688 | |
Benjamin Peterson | fc8e988 | 2014-04-13 19:52:14 -0400 | [diff] [blame] | 689 | .. cmdoption:: infile |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 690 | |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 691 | The JSON file to be validated or pretty-printed: |
| 692 | |
| 693 | .. code-block:: shell-session |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 694 | |
| 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 Peterson | fc8e988 | 2014-04-13 19:52:14 -0400 | [diff] [blame] | 707 | If *infile* is not specified, read from :attr:`sys.stdin`. |
| 708 | |
| 709 | .. cmdoption:: outfile |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 710 | |
| 711 | Write the output of the *infile* to the given *outfile*. Otherwise, write it |
| 712 | to :attr:`sys.stdout`. |
| 713 | |
Berker Peksag | 39e4c4d | 2014-11-10 09:56:54 +0200 | [diff] [blame] | 714 | .. cmdoption:: --sort-keys |
| 715 | |
| 716 | Sort the output of dictionaries alphabetically by key. |
| 717 | |
| 718 | .. versionadded:: 3.5 |
| 719 | |
HongWeipeng | f194479 | 2018-11-07 18:09:32 +0800 | [diff] [blame] | 720 | .. cmdoption:: --json-lines |
| 721 | |
| 722 | Parse every input line as separate JSON object. |
| 723 | |
| 724 | .. versionadded:: 3.8 |
| 725 | |
Benjamin Peterson | 940e207 | 2014-03-21 23:17:29 -0500 | [diff] [blame] | 726 | .. cmdoption:: -h, --help |
| 727 | |
| 728 | Show the help message. |
Serhiy Storchaka | 715f01b | 2014-11-27 19:45:31 +0200 | [diff] [blame] | 729 | |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 730 | |
| 731 | .. rubric:: Footnotes |
| 732 | |
| 733 | .. [#rfc-errata] As noted in `the errata for RFC 7159 |
Serhiy Storchaka | 6dff020 | 2016-05-07 10:49:07 +0300 | [diff] [blame] | 734 | <https://www.rfc-editor.org/errata_search.php?rfc=7159>`_, |
Serhiy Storchaka | 7a6915e | 2014-11-27 19:41:47 +0200 | [diff] [blame] | 735 | 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. |