__init__.py 20 KB

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