1 :mod:`simplejson` --- JSON encoder and decoder
2 ==============================================
5 :synopsis: Encode and decode the JSON format.
6 .. moduleauthor:: Bob Ippolito <bob@redivi.com>
7 .. sectionauthor:: Bob Ippolito <bob@redivi.com>
9 JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript
10 syntax (ECMA-262 3rd edition) used as a lightweight data interchange format.
12 :mod:`simplejson` exposes an API familiar to users of the standard library
13 :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained
14 version of the :mod:`json` library contained in Python 2.6, but maintains
15 compatibility with Python 2.5 and (currently) has
16 significant performance advantages, even without using the optional C
17 extension for speedups.
19 Encoding basic Python object hierarchies::
21 >>> import simplejson as json
22 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
23 '["foo", {"bar": ["baz", null, 1.0, 2]}]'
24 >>> print json.dumps("\"foo\bar")
26 >>> print json.dumps(u'\u1234')
28 >>> print json.dumps('\\')
30 >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
31 {"a": 0, "b": 0, "c": 0}
32 >>> from StringIO import StringIO
34 >>> json.dump(['streaming API'], io)
40 >>> import simplejson as json
41 >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
42 '[1,2,3,{"4":5,"6":7}]'
46 >>> import simplejson as json
47 >>> s = json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4 * ' ')
48 >>> print '\n'.join([l.rstrip() for l in s.splitlines()])
56 >>> import simplejson as json
57 >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
58 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj
60 >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar'
62 >>> from StringIO import StringIO
63 >>> io = StringIO('["streaming API"]')
64 >>> json.load(io)[0] == 'streaming API'
67 Using Decimal instead of float::
69 >>> import simplejson as json
70 >>> from decimal import Decimal
71 >>> json.loads('1.1', use_decimal=True) == Decimal('1.1')
73 >>> json.dumps(Decimal('1.1'), use_decimal=True) == '1.1'
76 Specializing JSON object decoding::
78 >>> import simplejson as json
79 >>> def as_complex(dct):
80 ... if '__complex__' in dct:
81 ... return complex(dct['real'], dct['imag'])
84 >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
85 ... object_hook=as_complex)
88 >>> json.loads('1.1', parse_float=decimal.Decimal) == decimal.Decimal('1.1')
91 Specializing JSON object encoding::
93 >>> import simplejson as json
94 >>> def encode_complex(obj):
95 ... if isinstance(obj, complex):
96 ... return [obj.real, obj.imag]
97 ... raise TypeError(repr(o) + " is not JSON serializable")
99 >>> json.dumps(2 + 1j, default=encode_complex)
101 >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j)
103 >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j))
109 Using :mod:`simplejson.tool` from the shell to validate and pretty-print::
111 $ echo '{"json":"obj"}' | python -m simplejson.tool
115 $ echo '{ 1.2:3.4}' | python -m simplejson.tool
116 Expecting property name: line 1 column 2 (char 2)
118 .. highlight:: python
122 The JSON produced by this module's default settings is a subset of
123 YAML, so it may be used as a serializer for that as well.
129 .. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, **kw]]]]]]]]]]])
131 Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
134 If *skipkeys* is true (default: ``False``), then dict keys that are not
135 of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
136 :class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
139 If *ensure_ascii* is false (default: ``True``), then some chunks written
140 to *fp* may be :class:`unicode` instances, subject to normal Python
141 :class:`str` to :class:`unicode` coercion rules. Unless ``fp.write()``
142 explicitly understands :class:`unicode` (as in :func:`codecs.getwriter`) this
143 is likely to cause an error. It's best to leave the default settings, because
144 they are safe and it is highly optimized.
146 If *check_circular* is false (default: ``True``), then the circular
147 reference check for container types will be skipped and a circular reference
148 will result in an :exc:`OverflowError` (or worse).
150 If *allow_nan* is false (default: ``True``), then it will be a
151 :exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
152 ``inf``, ``-inf``) in strict compliance of the JSON specification.
153 If *allow_nan* is true, their JavaScript equivalents will be used
154 (``NaN``, ``Infinity``, ``-Infinity``).
156 If *indent* is a string, then JSON array elements and object members
157 will be pretty-printed with a newline followed by that string repeated
158 for each level of nesting. ``None`` (the default) selects the most compact
159 representation without any newlines. For backwards compatibility with
160 versions of simplejson earlier than 2.1.0, an integer is also accepted
161 and is converted to a string with that many spaces.
163 .. versionchanged:: 2.1.0
164 Changed *indent* from an integer number of spaces to a string.
166 If specified, *separators* should be an ``(item_separator, dict_separator)``
167 tuple. By default, ``(', ', ': ')`` are used. To get the most compact JSON
168 representation, you should specify ``(',', ':')`` to eliminate whitespace.
170 *encoding* is the character encoding for str instances, default is
173 *default(obj)* is a function that should return a serializable version of
174 *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`.
176 To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
177 :meth:`default` method to serialize additional types), specify it with the
180 If *use_decimal* is true (default: ``False``) then :class:`decimal.Decimal`
181 will be natively serialized to JSON with full precision.
183 .. versionchanged:: 2.1.0
184 *use_decimal* is new in 2.1.0.
188 JSON is not a framed protocol so unlike :mod:`pickle` or :mod:`marshal` it
189 does not make sense to serialize more than one JSON document without some
190 container protocol to delimit them.
193 .. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, **kw]]]]]]]]]]])
195 Serialize *obj* to a JSON formatted :class:`str`.
197 If *ensure_ascii* is false, then the return value will be a
198 :class:`unicode` instance. The other arguments have the same meaning as in
199 :func:`dump`. Note that the default *ensure_ascii* setting has much
203 .. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, use_decimal[, **kw]]]]]]]]])
205 Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
206 document) to a Python object.
208 If the contents of *fp* are encoded with an ASCII based encoding other than
209 UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be specified.
210 Encodings that are not ASCII based (such as UCS-2) are not allowed, and
211 should be wrapped with ``codecs.getreader(fp)(encoding)``, or simply decoded
212 to a :class:`unicode` object and passed to :func:`loads`. The default
213 setting of ``'utf-8'`` is fastest and should be using whenever possible.
215 If *fp.read()* returns :class:`str` then decoded JSON strings that contain
216 only ASCII characters may be parsed as :class:`str` for performance and
217 memory reasons. If your code expects only :class:`unicode` the appropriate
218 solution is to wrap fp with a reader as demonstrated above.
220 *object_hook* is an optional function that will be called with the result of
221 any object literal decode (a :class:`dict`). The return value of
222 *object_hook* will be used instead of the :class:`dict`. This feature can be used
223 to implement custom decoders (e.g. JSON-RPC class hinting).
225 *object_pairs_hook* is an optional function that will be called with the
226 result of any object literal decode with an ordered list of pairs. The
227 return value of *object_pairs_hook* will be used instead of the
228 :class:`dict`. This feature can be used to implement custom decoders that
229 rely on the order that the key and value pairs are decoded (for example,
230 :class:`collections.OrderedDict` will remember the order of insertion). If
231 *object_hook* is also defined, the *object_pairs_hook* takes priority.
233 .. versionchanged:: 2.1.0
234 Added support for *object_pairs_hook*.
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`).
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`).
246 *parse_constant*, if specified, will be called with one of the following
247 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This can be used to
248 raise an exception if invalid JSON numbers are encountered.
250 If *use_decimal* is true (default: ``False``) then *parse_float* is set to
251 :class:`decimal.Decimal`. This is a convenience for parity with the
252 :func:`dump` parameter.
254 .. versionchanged:: 2.1.0
255 *use_decimal* is new in 2.1.0.
257 To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
258 kwarg. Additional keyword arguments will be passed to the constructor of the
263 :func:`load` will read the rest of the file-like object as a string and
264 then call :func:`loads`. It does not stop at the end of the first valid
265 JSON document it finds and it will raise an error if there is anything
266 other than whitespace after the document. Except for files containing
267 only one JSON document, it is recommended to use :func:`loads`.
270 .. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, use_decimal[, **kw]]]]]]]]])
272 Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
273 document) to a Python object.
275 If *s* is a :class:`str` instance and is encoded with an ASCII based encoding
276 other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be
277 specified. Encodings that are not ASCII based (such as UCS-2) are not
278 allowed and should be decoded to :class:`unicode` first.
280 If *s* is a :class:`str` then decoded JSON strings that contain
281 only ASCII characters may be parsed as :class:`str` for performance and
282 memory reasons. If your code expects only :class:`unicode` the appropriate
283 solution is decode *s* to :class:`unicode` prior to calling loads.
285 The other arguments have the same meaning as in :func:`load`.
288 Encoders and decoders
289 ---------------------
291 .. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, strict]]]]]]])
295 Performs the following translations in decoding by default:
297 +---------------+-------------------+
299 +===============+===================+
301 +---------------+-------------------+
303 +---------------+-------------------+
305 +---------------+-------------------+
306 | number (int) | int, long |
307 +---------------+-------------------+
308 | number (real) | float |
309 +---------------+-------------------+
311 +---------------+-------------------+
313 +---------------+-------------------+
315 +---------------+-------------------+
317 It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
318 corresponding ``float`` values, which is outside the JSON spec.
320 *encoding* determines the encoding used to interpret any :class:`str` objects
321 decoded by this instance (``'utf-8'`` by default). It has no effect when decoding
322 :class:`unicode` objects.
324 Note that currently only encodings that are a superset of ASCII work, strings
325 of other encodings should be passed in as :class:`unicode`.
327 *object_hook* is an optional function that will be called with the result of
328 every JSON object decoded and its return value will be used in place of the
329 given :class:`dict`. This can be used to provide custom deserializations
330 (e.g. to support JSON-RPC class hinting).
332 *object_pairs_hook* is an optional function that will be called with the
333 result of any object literal decode with an ordered list of pairs. The
334 return value of *object_pairs_hook* will be used instead of the
335 :class:`dict`. This feature can be used to implement custom decoders that
336 rely on the order that the key and value pairs are decoded (for example,
337 :class:`collections.OrderedDict` will remember the order of insertion). If
338 *object_hook* is also defined, the *object_pairs_hook* takes priority.
340 .. versionchanged:: 2.1.0
341 Added support for *object_pairs_hook*.
343 *parse_float*, if specified, will be called with the string of every JSON
344 float to be decoded. By default, this is equivalent to ``float(num_str)``.
345 This can be used to use another datatype or parser for JSON floats
346 (e.g. :class:`decimal.Decimal`).
348 *parse_int*, if specified, will be called with the string of every JSON int
349 to be decoded. By default, this is equivalent to ``int(num_str)``. This can
350 be used to use another datatype or parser for JSON integers
351 (e.g. :class:`float`).
353 *parse_constant*, if specified, will be called with one of the following
354 strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This can be used to
355 raise an exception if invalid JSON numbers are encountered.
357 *strict* controls the parser's behavior when it encounters an invalid
358 control character in a string. The default setting of ``True`` means that
359 unescaped control characters are parse errors, if ``False`` then control
360 characters will be allowed in strings.
362 .. method:: decode(s)
364 Return the Python representation of *s* (a :class:`str` or
365 :class:`unicode` instance containing a JSON document)
367 If *s* is a :class:`str` then decoded JSON strings that contain
368 only ASCII characters may be parsed as :class:`str` for performance and
369 memory reasons. If your code expects only :class:`unicode` the
370 appropriate solution is decode *s* to :class:`unicode` prior to calling
373 .. method:: raw_decode(s)
375 Decode a JSON document from *s* (a :class:`str` or :class:`unicode`
376 beginning with a JSON document) and return a 2-tuple of the Python
377 representation and the index in *s* where the document ended.
379 This can be used to decode a JSON document from a string that may have
380 extraneous data at the end.
383 .. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]])
385 Extensible JSON encoder for Python data structures.
387 Supports the following objects and types by default:
389 +-------------------+---------------+
391 +===================+===============+
393 +-------------------+---------------+
394 | list, tuple | array |
395 +-------------------+---------------+
396 | str, unicode | string |
397 +-------------------+---------------+
398 | int, long, float | number |
399 +-------------------+---------------+
401 +-------------------+---------------+
403 +-------------------+---------------+
405 +-------------------+---------------+
407 To extend this to recognize other objects, subclass and implement a
408 :meth:`default` method with another method that returns a serializable object
409 for ``o`` if possible, otherwise it should call the superclass implementation
410 (to raise :exc:`TypeError`).
412 If *skipkeys* is false (the default), then it is a :exc:`TypeError` to
413 attempt encoding of keys that are not str, int, long, float or None. If
414 *skipkeys* is true, such items are simply skipped.
416 If *ensure_ascii* is true (the default), the output is guaranteed to be
417 :class:`str` objects with all incoming unicode characters escaped. If
418 *ensure_ascii* is false, the output will be a unicode object.
420 If *check_circular* is false (the default), then lists, dicts, and custom
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.
425 If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and
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
431 If *sort_keys* is true (not the default), then the output of dictionaries
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.
435 If *indent* is a string, then JSON array elements and object members
436 will be pretty-printed with a newline followed by that string repeated
437 for each level of nesting. ``None`` (the default) selects the most compact
438 representation without any newlines. For backwards compatibility with
439 versions of simplejson earlier than 2.1.0, an integer is also accepted
440 and is converted to a string with that many spaces.
442 .. versionchanged:: 2.1.0
443 Changed *indent* from an integer number of spaces to a string.
445 If specified, *separators* should be an ``(item_separator, key_separator)``
446 tuple. By default, ``(', ', ': ')`` are used. To get the most compact JSON
447 representation, you should specify ``(',', ':')`` to eliminate whitespace.
449 If specified, *default* should be a function that gets called for objects
450 that can't otherwise be serialized. It should return a JSON encodable
451 version of the object or raise a :exc:`TypeError`.
453 If *encoding* is not ``None``, then all input strings will be transformed
454 into unicode using that encoding prior to JSON-encoding. The default is
458 .. method:: default(o)
460 Implement this method in a subclass such that it returns a serializable
461 object for *o*, or calls the base implementation (to raise a
464 For example, to support arbitrary iterators, you could implement default
467 def default(self, o):
473 return list(iterable)
474 return JSONEncoder.default(self, o)
477 .. method:: encode(o)
479 Return a JSON string representation of a Python data structure, *o*. For
482 >>> import simplejson as json
483 >>> json.JSONEncoder().encode({"foo": ["bar", "baz"]})
484 '{"foo": ["bar", "baz"]}'
487 .. method:: iterencode(o)
489 Encode the given object, *o*, and yield each string representation as
490 available. For example::
492 for chunk in JSONEncoder().iterencode(bigobject):
493 mysocket.write(chunk)
495 Note that :meth:`encode` has much better performance than
498 .. class:: JSONEncoderForHTML([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]])
500 Subclass of :class:`JSONEncoder` that escapes &, <, and > for embedding in HTML.
502 .. versionchanged:: 2.1.0