index.rst 40 KB

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