index.rst 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428
  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> is a subset of JavaScript
  8. syntax (ECMA-262 3rd edition) used as a lightweight data interchange format.
  9. :mod:`simplejson` exposes an API familiar to users of the standard library
  10. :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained
  11. version of the :mod:`json` library contained in Python 2.6, but maintains
  12. compatibility with Python 2.4 and Python 2.5 and (currently) has
  13. significant performance advantages, even without using the optional C
  14. extension for speedups.
  15. Encoding basic Python object hierarchies::
  16. >>> import simplejson as json
  17. >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
  18. '["foo", {"bar": ["baz", null, 1.0, 2]}]'
  19. >>> print json.dumps("\"foo\bar")
  20. "\"foo\bar"
  21. >>> print json.dumps(u'\u1234')
  22. "\u1234"
  23. >>> print json.dumps('\\')
  24. "\\"
  25. >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
  26. {"a": 0, "b": 0, "c": 0}
  27. >>> from StringIO import StringIO
  28. >>> io = StringIO()
  29. >>> json.dump(['streaming API'], io)
  30. >>> io.getvalue()
  31. '["streaming API"]'
  32. Compact encoding::
  33. >>> import simplejson as json
  34. >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
  35. '[1,2,3,{"4":5,"6":7}]'
  36. Pretty printing::
  37. >>> import simplejson as json
  38. >>> s = json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)
  39. >>> print '\n'.join([l.rstrip() for l in s.splitlines()])
  40. {
  41. "4": 5,
  42. "6": 7
  43. }
  44. Decoding JSON::
  45. >>> import simplejson as json
  46. >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
  47. >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj
  48. True
  49. >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar'
  50. True
  51. >>> from StringIO import StringIO
  52. >>> io = StringIO('["streaming API"]')
  53. >>> json.load(io)[0] == 'streaming API'
  54. True
  55. Specializing JSON object decoding::
  56. >>> import simplejson as json
  57. >>> def as_complex(dct):
  58. ... if '__complex__' in dct:
  59. ... return complex(dct['real'], dct['imag'])
  60. ... return dct
  61. ...
  62. >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
  63. ... object_hook=as_complex)
  64. (1+2j)
  65. >>> import decimal
  66. >>> json.loads('1.1', parse_float=decimal.Decimal) == decimal.Decimal('1.1')
  67. True
  68. Specializing JSON object encoding::
  69. >>> import simplejson as json
  70. >>> def encode_complex(obj):
  71. ... if isinstance(obj, complex):
  72. ... return [obj.real, obj.imag]
  73. ... raise TypeError(repr(o) + " is not JSON serializable")
  74. ...
  75. >>> json.dumps(2 + 1j, default=encode_complex)
  76. '[2.0, 1.0]'
  77. >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j)
  78. '[2.0, 1.0]'
  79. >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j))
  80. '[2.0, 1.0]'
  81. .. highlight:: none
  82. Using :mod:`simplejson.tool` from the shell to validate and pretty-print::
  83. $ echo '{"json":"obj"}' | python -m simplejson.tool
  84. {
  85. "json": "obj"
  86. }
  87. $ echo '{ 1.2:3.4}' | python -m simplejson.tool
  88. Expecting property name: line 1 column 2 (char 2)
  89. .. highlight:: python
  90. .. note::
  91. The JSON produced by this module's default settings is a subset of
  92. YAML, so it may be used as a serializer for that as well.
  93. Basic Usage
  94. -----------
  95. .. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])
  96. Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
  97. file-like object).
  98. If *skipkeys* is true (default: ``False``), then dict keys that are not
  99. of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
  100. :class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
  101. :exc:`TypeError`.
  102. If *ensure_ascii* is false (default: ``True``), then some chunks written
  103. to *fp* may be :class:`unicode` instances, subject to normal Python
  104. :class:`str` to :class:`unicode` coercion rules. Unless ``fp.write()``
  105. explicitly understands :class:`unicode` (as in :func:`codecs.getwriter`) this
  106. is likely to cause an error. It's best to leave the default settings, because
  107. they are safe and it is highly optimized.
  108. If *check_circular* is false (default: ``True``), then the circular
  109. reference check for container types will be skipped and a circular reference
  110. will result in an :exc:`OverflowError` (or worse).
  111. If *allow_nan* is false (default: ``True``), then it will be a
  112. :exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
  113. ``inf``, ``-inf``) in strict compliance of the JSON specification.
  114. If *allow_nan* is true, their JavaScript equivalents will be used
  115. (``NaN``, ``Infinity``, ``-Infinity``).
  116. If *indent* is a non-negative integer, then JSON array elements and object
  117. members will be pretty-printed with that indent level. An indent level of 0
  118. will only insert newlines. ``None`` (the default) selects the most compact
  119. representation.
  120. If specified, *separators* should be an ``(item_separator, dict_separator)``
  121. tuple. By default, ``(', ', ': ')`` are used. To get the most compact JSON
  122. representation, you should specify ``(',', ':')`` to eliminate whitespace.
  123. *encoding* is the character encoding for str instances, default is
  124. ``'utf-8'``.
  125. If specified, *default* should be a function that gets called for objects
  126. that can't otherwise be serialized. It should return a JSON encodable
  127. version of the object or raise a :exc:`TypeError`. If not specified,
  128. :exc:`TypeError` is always raised in those cases.
  129. To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
  130. :meth:`default` method to serialize additional types), specify it with the
  131. *cls* kwarg.
  132. .. note::
  133. JSON is not a framed protocol so unlike :mod:`pickle` or :mod:`marshal` it
  134. does not make sense to serialize more than one JSON document without some
  135. container protocol to delimit them.
  136. .. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])
  137. Serialize *obj* to a JSON formatted :class:`str`.
  138. If *ensure_ascii* is false, then the return value will be a
  139. :class:`unicode` instance. The other arguments have the same meaning as in
  140. :func:`dump`. Note that the default *ensure_ascii* setting has much
  141. better performance.
  142. .. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])
  143. Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
  144. document) to a Python object.
  145. If the contents of *fp* are encoded with an ASCII based encoding other than
  146. UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be specified.
  147. Encodings that are not ASCII based (such as UCS-2) are not allowed, and
  148. should be wrapped with ``codecs.getreader(fp)(encoding)``, or simply decoded
  149. to a :class:`unicode` object and passed to :func:`loads`. The default
  150. setting of ``'utf-8'`` is fastest and should be using whenever possible.
  151. *object_hook* is an optional function that will be called with the result of
  152. any object literal decode (a :class:`dict`). The return value of
  153. *object_hook* will be used instead of the :class:`dict`. This feature can be used
  154. to implement custom decoders (e.g. JSON-RPC class hinting).
  155. *parse_float*, if specified, will be called with the string of every JSON
  156. float to be decoded. By default, this is equivalent to ``float(num_str)``.
  157. This can be used to use another datatype or parser for JSON floats
  158. (e.g. :class:`decimal.Decimal`).
  159. *parse_int*, if specified, will be called with the string of every JSON int
  160. to be decoded. By default, this is equivalent to ``int(num_str)``. This can
  161. be used to use another datatype or parser for JSON integers
  162. (e.g. :class:`float`).
  163. *parse_constant*, if specified, will be called with one of the following
  164. strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This can be used to
  165. raise an exception if invalid JSON numbers are encountered.
  166. To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
  167. kwarg. Additional keyword arguments will be passed to the constructor of the
  168. class.
  169. .. note::
  170. :func:`load` will read the rest of the file-like object as a string and
  171. then call :func:`loads`. It does not stop at the end of the first valid
  172. JSON document it finds and it will raise an error if there is anything
  173. other than whitespace after the document. Except for files containing
  174. only one JSON document, it is recommended to use :func:`loads`.
  175. .. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])
  176. Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
  177. document) to a Python object.
  178. If *s* is a :class:`str` instance and is encoded with an ASCII based encoding
  179. other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be
  180. specified. Encodings that are not ASCII based (such as UCS-2) are not
  181. allowed and should be decoded to :class:`unicode` first.
  182. The other arguments have the same meaning as in :func:`load`.
  183. Encoders and decoders
  184. ---------------------
  185. .. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict]]]]]])
  186. Simple JSON decoder.
  187. Performs the following translations in decoding by default:
  188. +---------------+-------------------+
  189. | JSON | Python |
  190. +===============+===================+
  191. | object | dict |
  192. +---------------+-------------------+
  193. | array | list |
  194. +---------------+-------------------+
  195. | string | unicode |
  196. +---------------+-------------------+
  197. | number (int) | int, long |
  198. +---------------+-------------------+
  199. | number (real) | float |
  200. +---------------+-------------------+
  201. | true | True |
  202. +---------------+-------------------+
  203. | false | False |
  204. +---------------+-------------------+
  205. | null | None |
  206. +---------------+-------------------+
  207. It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
  208. corresponding ``float`` values, which is outside the JSON spec.
  209. *encoding* determines the encoding used to interpret any :class:`str` objects
  210. decoded by this instance (``'utf-8'`` by default). It has no effect when decoding
  211. :class:`unicode` objects.
  212. Note that currently only encodings that are a superset of ASCII work, strings
  213. of other encodings should be passed in as :class:`unicode`.
  214. *object_hook*, if specified, will be called with the result of every JSON
  215. object decoded and its return value will be used in place of the given
  216. :class:`dict`. This can be used to provide custom deserializations (e.g. to
  217. support JSON-RPC class hinting).
  218. *parse_float*, if specified, will be called with the string of every JSON
  219. float to be decoded. By default, this is equivalent to ``float(num_str)``.
  220. This can be used to use another datatype or parser for JSON floats
  221. (e.g. :class:`decimal.Decimal`).
  222. *parse_int*, if specified, will be called with the string of every JSON int
  223. to be decoded. By default, this is equivalent to ``int(num_str)``. This can
  224. be used to use another datatype or parser for JSON integers
  225. (e.g. :class:`float`).
  226. *parse_constant*, if specified, will be called with one of the following
  227. strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This can be used to
  228. raise an exception if invalid JSON numbers are encountered.
  229. *strict* controls the parser's behavior when it encounters an invalid
  230. control character in a string. The default setting of ``True`` means that
  231. unescaped control characters are parse errors, if ``False`` then control
  232. characters will be allowed in strings.
  233. .. method:: decode(s)
  234. Return the Python representation of *s* (a :class:`str` or
  235. :class:`unicode` instance containing a JSON document)
  236. .. method:: raw_decode(s)
  237. Decode a JSON document from *s* (a :class:`str` or :class:`unicode`
  238. beginning with a JSON document) and return a 2-tuple of the Python
  239. representation and the index in *s* where the document ended.
  240. This can be used to decode a JSON document from a string that may have
  241. extraneous data at the end.
  242. .. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]])
  243. Extensible JSON encoder for Python data structures.
  244. Supports the following objects and types by default:
  245. +-------------------+---------------+
  246. | Python | JSON |
  247. +===================+===============+
  248. | dict | object |
  249. +-------------------+---------------+
  250. | list, tuple | array |
  251. +-------------------+---------------+
  252. | str, unicode | string |
  253. +-------------------+---------------+
  254. | int, long, float | number |
  255. +-------------------+---------------+
  256. | True | true |
  257. +-------------------+---------------+
  258. | False | false |
  259. +-------------------+---------------+
  260. | None | null |
  261. +-------------------+---------------+
  262. To extend this to recognize other objects, subclass and implement a
  263. :meth:`default` method with another method that returns a serializable object
  264. for ``o`` if possible, otherwise it should call the superclass implementation
  265. (to raise :exc:`TypeError`).
  266. If *skipkeys* is false (the default), then it is a :exc:`TypeError` to
  267. attempt encoding of keys that are not str, int, long, float or None. If
  268. *skipkeys* is true, such items are simply skipped.
  269. If *ensure_ascii* is true (the default), the output is guaranteed to be
  270. :class:`str` objects with all incoming unicode characters escaped. If
  271. *ensure_ascii* is false, the output will be a unicode object.
  272. If *check_circular* is false (the default), then lists, dicts, and custom
  273. encoded objects will be checked for circular references during encoding to
  274. prevent an infinite recursion (which would cause an :exc:`OverflowError`).
  275. Otherwise, no such check takes place.
  276. If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and
  277. ``-Infinity`` will be encoded as such. This behavior is not JSON
  278. specification compliant, but is consistent with most JavaScript based
  279. encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
  280. such floats.
  281. If *sort_keys* is true (the default), then the output of dictionaries
  282. will be sorted by key; this is useful for regression tests to ensure that
  283. JSON serializations can be compared on a day-to-day basis.
  284. If *indent* is a non-negative integer (it is ``None`` by default), then JSON
  285. array elements and object members will be pretty-printed with that indent
  286. level. An indent level of 0 will only insert newlines. ``None`` is the most
  287. compact representation.
  288. If specified, *separators* should be an ``(item_separator, key_separator)``
  289. tuple. By default, ``(', ', ': ')`` are used. To get the most compact JSON
  290. representation, you should specify ``(',', ':')`` to eliminate whitespace.
  291. If specified, *default* should be a function that gets called for objects
  292. that can't otherwise be serialized. It should return a JSON encodable
  293. version of the object or raise a :exc:`TypeError`.
  294. If *encoding* is not ``None``, then all input strings will be transformed
  295. into unicode using that encoding prior to JSON-encoding. The default is
  296. ``'utf-8'``.
  297. .. method:: default(o)
  298. Implement this method in a subclass such that it returns a serializable
  299. object for *o*, or calls the base implementation (to raise a
  300. :exc:`TypeError`).
  301. For example, to support arbitrary iterators, you could implement default
  302. like this::
  303. def default(self, o):
  304. try:
  305. iterable = iter(o)
  306. except TypeError:
  307. pass
  308. else:
  309. return list(iterable)
  310. return JSONEncoder.default(self, o)
  311. .. method:: encode(o)
  312. Return a JSON string representation of a Python data structure, *o*. For
  313. example::
  314. >>> import simplejson as json
  315. >>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
  316. '{"foo": ["bar", "baz"]}'
  317. .. method:: iterencode(o)
  318. Encode the given object, *o*, and yield each string representation as
  319. available. For example::
  320. for chunk in JSONEncoder().iterencode(bigobject):
  321. mysocket.write(chunk)
  322. Note that :meth:`encode` has much better performance than
  323. :meth:`iterencode`.