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.2' 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, JSONEncoderForHTML 113 def _import_OrderedDict(): 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 122 def _import_c_make_encoder(): 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 # cached encoder 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 # could accelerate with writelines in some versions of Python, at 240 # a debuggability cost 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 # cached encoder 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 471 def _toggle_speedups(enabled): 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 506 def simple_first(kv): 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
