1 r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of
2 JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data
3 interchange format.
4
5 :mod:`simplejson` exposes an API familiar to users of the standard library
6 :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained
7 version of the :mod:`json` library contained in Python 2.6, but maintains
8 compatibility with Python 2.4 and Python 2.5 and (currently) has
9 significant performance advantages, even without using the optional C
10 extension for speedups.
11
12 Encoding basic Python object hierarchies::
13
14 >>> import simplejson as json
15 >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
16 '["foo", {"bar": ["baz", null, 1.0, 2]}]'
17 >>> print json.dumps("\"foo\bar")
18 "\"foo\bar"
19 >>> print json.dumps(u'\u1234')
20 "\u1234"
21 >>> print json.dumps('\\')
22 "\\"
23 >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
24 {"a": 0, "b": 0, "c": 0}
25 >>> from StringIO import StringIO
26 >>> io = StringIO()
27 >>> json.dump(['streaming API'], io)
28 >>> io.getvalue()
29 '["streaming API"]'
30
31 Compact encoding::
32
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
37 Pretty printing::
38
39 >>> import simplejson as json
40 >>> s = json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=' ')
41 >>> print '\n'.join([l.rstrip() for l in s.splitlines()])
42 {
43 "4": 5,
44 "6": 7
45 }
46
47 Decoding JSON::
48
49 >>> import simplejson as json
50 >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
51 >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj
52 True
53 >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar'
54 True
55 >>> from StringIO import StringIO
56 >>> io = StringIO('["streaming API"]')
57 >>> json.load(io)[0] == 'streaming API'
58 True
59
60 Specializing JSON object decoding::
61
62 >>> import simplejson as json
63 >>> def as_complex(dct):
64 ... if '__complex__' in dct:
65 ... return complex(dct['real'], dct['imag'])
66 ... return dct
67 ...
68 >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
69 ... object_hook=as_complex)
70 (1+2j)
71 >>> from decimal import Decimal
72 >>> json.loads('1.1', parse_float=Decimal) == Decimal('1.1')
73 True
74
75 Specializing JSON object encoding::
76
77 >>> import simplejson as json
78 >>> def encode_complex(obj):
79 ... if isinstance(obj, complex):
80 ... return [obj.real, obj.imag]
81 ... raise TypeError(repr(o) + " is not JSON serializable")
82 ...
83 >>> json.dumps(2 + 1j, default=encode_complex)
84 '[2.0, 1.0]'
85 >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j)
86 '[2.0, 1.0]'
87 >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j))
88 '[2.0, 1.0]'
89
90
91 Using simplejson.tool from the shell to validate and pretty-print::
92
93 $ echo '{"json":"obj"}' | python -m simplejson.tool
94 {
95 "json": "obj"
96 }
97 $ echo '{ 1.2:3.4}' | python -m simplejson.tool
98 Expecting property name: line 1 column 2 (char 2)
99 """
100 __version__ = '2.6.0'
101 __all__ = [
102 'dump', 'dumps', 'load', 'loads',
103 'JSONDecoder', 'JSONDecodeError', 'JSONEncoder',
104 'OrderedDict', 'simple_first',
105 ]
106
107 __author__ = 'Bob Ippolito <bob@redivi.com>'
108
109 from decimal import Decimal
110
111 from decoder import JSONDecoder, JSONDecodeError
112 from encoder import JSONEncoder
114 import collections
115 try:
116 return collections.OrderedDict
117 except AttributeError:
118 import ordered_dict
119 return ordered_dict.OrderedDict
120 OrderedDict = _import_OrderedDict()
121
123 try:
124 from simplejson._speedups import make_encoder
125 return make_encoder
126 except ImportError:
127 return None
128
129 _default_encoder = JSONEncoder(
130 skipkeys=False,
131 ensure_ascii=True,
132 check_circular=True,
133 allow_nan=True,
134 indent=None,
135 separators=None,
136 encoding='utf-8',
137 default=None,
138 use_decimal=True,
139 namedtuple_as_object=True,
140 tuple_as_array=True,
141 bigint_as_string=False,
142 item_sort_key=None,
143 )
144
145 -def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
146 allow_nan=True, cls=None, indent=None, separators=None,
147 encoding='utf-8', default=None, use_decimal=True,
148 namedtuple_as_object=True, tuple_as_array=True,
149 bigint_as_string=False, sort_keys=False, item_sort_key=None,
150 **kw):
151 """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
152 ``.write()``-supporting file-like object).
153
154 If ``skipkeys`` is true then ``dict`` keys that are not basic types
155 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
156 will be skipped instead of raising a ``TypeError``.
157
158 If ``ensure_ascii`` is false, then the some chunks written to ``fp``
159 may be ``unicode`` instances, subject to normal Python ``str`` to
160 ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
161 understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
162 to cause an error.
163
164 If ``check_circular`` is false, then the circular reference check
165 for container types will be skipped and a circular reference will
166 result in an ``OverflowError`` (or worse).
167
168 If ``allow_nan`` is false, then it will be a ``ValueError`` to
169 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
170 in strict compliance of the JSON specification, instead of using the
171 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
172
173 If *indent* is a string, then JSON array elements and object members
174 will be pretty-printed with a newline followed by that string repeated
175 for each level of nesting. ``None`` (the default) selects the most compact
176 representation without any newlines. For backwards compatibility with
177 versions of simplejson earlier than 2.1.0, an integer is also accepted
178 and is converted to a string with that many spaces.
179
180 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
181 then it will be used instead of the default ``(', ', ': ')`` separators.
182 ``(',', ':')`` is the most compact JSON representation.
183
184 ``encoding`` is the character encoding for str instances, default is UTF-8.
185
186 ``default(obj)`` is a function that should return a serializable version
187 of obj or raise TypeError. The default simply raises TypeError.
188
189 If *use_decimal* is true (default: ``True``) then decimal.Decimal
190 will be natively serialized to JSON with full precision.
191
192 If *namedtuple_as_object* is true (default: ``True``),
193 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
194 as JSON objects.
195
196 If *tuple_as_array* is true (default: ``True``),
197 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
198
199 If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher
200 or lower than -2**53 will be encoded as strings. This is to avoid the
201 rounding that happens in Javascript otherwise. Note that this is still a
202 lossy operation that will not round-trip correctly and should be used
203 sparingly.
204
205 If specified, *item_sort_key* is a callable used to sort the items in
206 each dictionary. This is useful if you want to sort items other than
207 in alphabetical order by key. This option takes precedence over
208 *sort_keys*.
209
210 If *sort_keys* is true (default: ``False``), the output of dictionaries
211 will be sorted by item.
212
213 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
214 ``.default()`` method to serialize additional types), specify it with
215 the ``cls`` kwarg.
216
217 """
218
219 if (not skipkeys and ensure_ascii and
220 check_circular and allow_nan and
221 cls is None and indent is None and separators is None and
222 encoding == 'utf-8' and default is None and use_decimal
223 and namedtuple_as_object and tuple_as_array
224 and not bigint_as_string and not item_sort_key and not kw):
225 iterable = _default_encoder.iterencode(obj)
226 else:
227 if cls is None:
228 cls = JSONEncoder
229 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
230 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
231 separators=separators, encoding=encoding,
232 default=default, use_decimal=use_decimal,
233 namedtuple_as_object=namedtuple_as_object,
234 tuple_as_array=tuple_as_array,
235 bigint_as_string=bigint_as_string,
236 sort_keys=sort_keys,
237 item_sort_key=item_sort_key,
238 **kw).iterencode(obj)
239
240
241 for chunk in iterable:
242 fp.write(chunk)
243
244
245 -def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
246 allow_nan=True, cls=None, indent=None, separators=None,
247 encoding='utf-8', default=None, use_decimal=True,
248 namedtuple_as_object=True, tuple_as_array=True,
249 bigint_as_string=False, sort_keys=False, item_sort_key=None,
250 **kw):
251 """Serialize ``obj`` to a JSON formatted ``str``.
252
253 If ``skipkeys`` is false then ``dict`` keys that are not basic types
254 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
255 will be skipped instead of raising a ``TypeError``.
256
257 If ``ensure_ascii`` is false, then the return value will be a
258 ``unicode`` instance subject to normal Python ``str`` to ``unicode``
259 coercion rules instead of being escaped to an ASCII ``str``.
260
261 If ``check_circular`` is false, then the circular reference check
262 for container types will be skipped and a circular reference will
263 result in an ``OverflowError`` (or worse).
264
265 If ``allow_nan`` is false, then it will be a ``ValueError`` to
266 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
267 strict compliance of the JSON specification, instead of using the
268 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
269
270 If ``indent`` is a string, then JSON array elements and object members
271 will be pretty-printed with a newline followed by that string repeated
272 for each level of nesting. ``None`` (the default) selects the most compact
273 representation without any newlines. For backwards compatibility with
274 versions of simplejson earlier than 2.1.0, an integer is also accepted
275 and is converted to a string with that many spaces.
276
277 If ``separators`` is an ``(item_separator, dict_separator)`` tuple
278 then it will be used instead of the default ``(', ', ': ')`` separators.
279 ``(',', ':')`` is the most compact JSON representation.
280
281 ``encoding`` is the character encoding for str instances, default is UTF-8.
282
283 ``default(obj)`` is a function that should return a serializable version
284 of obj or raise TypeError. The default simply raises TypeError.
285
286 If *use_decimal* is true (default: ``True``) then decimal.Decimal
287 will be natively serialized to JSON with full precision.
288
289 If *namedtuple_as_object* is true (default: ``True``),
290 :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
291 as JSON objects.
292
293 If *tuple_as_array* is true (default: ``True``),
294 :class:`tuple` (and subclasses) will be encoded as JSON arrays.
295
296 If *bigint_as_string* is true (not the default), ints 2**53 and higher
297 or lower than -2**53 will be encoded as strings. This is to avoid the
298 rounding that happens in Javascript otherwise.
299
300 If specified, *item_sort_key* is a callable used to sort the items in
301 each dictionary. This is useful if you want to sort items other than
302 in alphabetical order by key. This option takes precendence over
303 *sort_keys*.
304
305 If *sort_keys* is true (default: ``False``), the output of dictionaries
306 will be sorted by item.
307
308 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
309 ``.default()`` method to serialize additional types), specify it with
310 the ``cls`` kwarg.
311
312 """
313
314 if (not skipkeys and ensure_ascii and
315 check_circular and allow_nan and
316 cls is None and indent is None and separators is None and
317 encoding == 'utf-8' and default is None and use_decimal
318 and namedtuple_as_object and tuple_as_array
319 and not bigint_as_string and not sort_keys
320 and not item_sort_key and not kw):
321 return _default_encoder.encode(obj)
322 if cls is None:
323 cls = JSONEncoder
324 return cls(
325 skipkeys=skipkeys, ensure_ascii=ensure_ascii,
326 check_circular=check_circular, allow_nan=allow_nan, indent=indent,
327 separators=separators, encoding=encoding, default=default,
328 use_decimal=use_decimal,
329 namedtuple_as_object=namedtuple_as_object,
330 tuple_as_array=tuple_as_array,
331 bigint_as_string=bigint_as_string,
332 sort_keys=sort_keys,
333 item_sort_key=item_sort_key,
334 **kw).encode(obj)
335
336
337 _default_decoder = JSONDecoder(encoding=None, object_hook=None,
338 object_pairs_hook=None)
339
340
341 -def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
342 parse_int=None, parse_constant=None, object_pairs_hook=None,
343 use_decimal=False, namedtuple_as_object=True, tuple_as_array=True,
344 **kw):
345 """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
346 a JSON document) to a Python object.
347
348 *encoding* determines the encoding used to interpret any
349 :class:`str` objects decoded by this instance (``'utf-8'`` by
350 default). It has no effect when decoding :class:`unicode` objects.
351
352 Note that currently only encodings that are a superset of ASCII work,
353 strings of other encodings should be passed in as :class:`unicode`.
354
355 *object_hook*, if specified, will be called with the result of every
356 JSON object decoded and its return value will be used in place of the
357 given :class:`dict`. This can be used to provide custom
358 deserializations (e.g. to support JSON-RPC class hinting).
359
360 *object_pairs_hook* is an optional function that will be called with
361 the result of any object literal decode with an ordered list of pairs.
362 The return value of *object_pairs_hook* will be used instead of the
363 :class:`dict`. This feature can be used to implement custom decoders
364 that rely on the order that the key and value pairs are decoded (for
365 example, :func:`collections.OrderedDict` will remember the order of
366 insertion). If *object_hook* is also defined, the *object_pairs_hook*
367 takes priority.
368
369 *parse_float*, if specified, will be called with the string of every
370 JSON float to be decoded. By default, this is equivalent to
371 ``float(num_str)``. This can be used to use another datatype or parser
372 for JSON floats (e.g. :class:`decimal.Decimal`).
373
374 *parse_int*, if specified, will be called with the string of every
375 JSON int to be decoded. By default, this is equivalent to
376 ``int(num_str)``. This can be used to use another datatype or parser
377 for JSON integers (e.g. :class:`float`).
378
379 *parse_constant*, if specified, will be called with one of the
380 following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This
381 can be used to raise an exception if invalid JSON numbers are
382 encountered.
383
384 If *use_decimal* is true (default: ``False``) then it implies
385 parse_float=decimal.Decimal for parity with ``dump``.
386
387 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
388 kwarg.
389
390 """
391 return loads(fp.read(),
392 encoding=encoding, cls=cls, object_hook=object_hook,
393 parse_float=parse_float, parse_int=parse_int,
394 parse_constant=parse_constant, object_pairs_hook=object_pairs_hook,
395 use_decimal=use_decimal, **kw)
396
397
398 -def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
399 parse_int=None, parse_constant=None, object_pairs_hook=None,
400 use_decimal=False, **kw):
401 """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
402 document) to a Python object.
403
404 *encoding* determines the encoding used to interpret any
405 :class:`str` objects decoded by this instance (``'utf-8'`` by
406 default). It has no effect when decoding :class:`unicode` objects.
407
408 Note that currently only encodings that are a superset of ASCII work,
409 strings of other encodings should be passed in as :class:`unicode`.
410
411 *object_hook*, if specified, will be called with the result of every
412 JSON object decoded and its return value will be used in place of the
413 given :class:`dict`. This can be used to provide custom
414 deserializations (e.g. to support JSON-RPC class hinting).
415
416 *object_pairs_hook* is an optional function that will be called with
417 the result of any object literal decode with an ordered list of pairs.
418 The return value of *object_pairs_hook* will be used instead of the
419 :class:`dict`. This feature can be used to implement custom decoders
420 that rely on the order that the key and value pairs are decoded (for
421 example, :func:`collections.OrderedDict` will remember the order of
422 insertion). If *object_hook* is also defined, the *object_pairs_hook*
423 takes priority.
424
425 *parse_float*, if specified, will be called with the string of every
426 JSON float to be decoded. By default, this is equivalent to
427 ``float(num_str)``. This can be used to use another datatype or parser
428 for JSON floats (e.g. :class:`decimal.Decimal`).
429
430 *parse_int*, if specified, will be called with the string of every
431 JSON int to be decoded. By default, this is equivalent to
432 ``int(num_str)``. This can be used to use another datatype or parser
433 for JSON integers (e.g. :class:`float`).
434
435 *parse_constant*, if specified, will be called with one of the
436 following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This
437 can be used to raise an exception if invalid JSON numbers are
438 encountered.
439
440 If *use_decimal* is true (default: ``False``) then it implies
441 parse_float=decimal.Decimal for parity with ``dump``.
442
443 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
444 kwarg.
445
446 """
447 if (cls is None and encoding is None and object_hook is None and
448 parse_int is None and parse_float is None and
449 parse_constant is None and object_pairs_hook is None
450 and not use_decimal and not kw):
451 return _default_decoder.decode(s)
452 if cls is None:
453 cls = JSONDecoder
454 if object_hook is not None:
455 kw['object_hook'] = object_hook
456 if object_pairs_hook is not None:
457 kw['object_pairs_hook'] = object_pairs_hook
458 if parse_float is not None:
459 kw['parse_float'] = parse_float
460 if parse_int is not None:
461 kw['parse_int'] = parse_int
462 if parse_constant is not None:
463 kw['parse_constant'] = parse_constant
464 if use_decimal:
465 if parse_float is not None:
466 raise TypeError("use_decimal=True implies parse_float=Decimal")
467 kw['parse_float'] = Decimal
468 return cls(encoding=encoding, **kw).decode(s)
469
470
472 import simplejson.decoder as dec
473 import simplejson.encoder as enc
474 import simplejson.scanner as scan
475 c_make_encoder = _import_c_make_encoder()
476 if enabled:
477 dec.scanstring = dec.c_scanstring or dec.py_scanstring
478 enc.c_make_encoder = c_make_encoder
479 enc.encode_basestring_ascii = (enc.c_encode_basestring_ascii or
480 enc.py_encode_basestring_ascii)
481 scan.make_scanner = scan.c_make_scanner or scan.py_make_scanner
482 else:
483 dec.scanstring = dec.py_scanstring
484 enc.c_make_encoder = None
485 enc.encode_basestring_ascii = enc.py_encode_basestring_ascii
486 scan.make_scanner = scan.py_make_scanner
487 dec.make_scanner = scan.make_scanner
488 global _default_decoder
489 _default_decoder = JSONDecoder(
490 encoding=None,
491 object_hook=None,
492 object_pairs_hook=None,
493 )
494 global _default_encoder
495 _default_encoder = JSONEncoder(
496 skipkeys=False,
497 ensure_ascii=True,
498 check_circular=True,
499 allow_nan=True,
500 indent=None,
501 separators=None,
502 encoding='utf-8',
503 default=None,
504 )
505
507 """Helper function to pass to item_sort_key to sort simple
508 elements to the top, then container elements.
509 """
510 return (isinstance(kv[1], (list, dict, tuple)), kv[0])
511