github.com/slspeek/camlistore_namedsearch@v0.0.0-20140519202248-ed6f70f7721a/lib/python/simplejson/__init__.py (about) 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.1.1' 101 __all__ = [ 102 'dump', 'dumps', 'load', 'loads', 103 'JSONDecoder', 'JSONDecodeError', 'JSONEncoder', 104 'OrderedDict', 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 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=False, 139 ) 140 141 def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, 142 allow_nan=True, cls=None, indent=None, separators=None, 143 encoding='utf-8', default=None, use_decimal=False, **kw): 144 """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a 145 ``.write()``-supporting file-like object). 146 147 If ``skipkeys`` is true then ``dict`` keys that are not basic types 148 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) 149 will be skipped instead of raising a ``TypeError``. 150 151 If ``ensure_ascii`` is false, then the some chunks written to ``fp`` 152 may be ``unicode`` instances, subject to normal Python ``str`` to 153 ``unicode`` coercion rules. Unless ``fp.write()`` explicitly 154 understands ``unicode`` (as in ``codecs.getwriter()``) this is likely 155 to cause an error. 156 157 If ``check_circular`` is false, then the circular reference check 158 for container types will be skipped and a circular reference will 159 result in an ``OverflowError`` (or worse). 160 161 If ``allow_nan`` is false, then it will be a ``ValueError`` to 162 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) 163 in strict compliance of the JSON specification, instead of using the 164 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 165 166 If *indent* is a string, then JSON array elements and object members 167 will be pretty-printed with a newline followed by that string repeated 168 for each level of nesting. ``None`` (the default) selects the most compact 169 representation without any newlines. For backwards compatibility with 170 versions of simplejson earlier than 2.1.0, an integer is also accepted 171 and is converted to a string with that many spaces. 172 173 If ``separators`` is an ``(item_separator, dict_separator)`` tuple 174 then it will be used instead of the default ``(', ', ': ')`` separators. 175 ``(',', ':')`` is the most compact JSON representation. 176 177 ``encoding`` is the character encoding for str instances, default is UTF-8. 178 179 ``default(obj)`` is a function that should return a serializable version 180 of obj or raise TypeError. The default simply raises TypeError. 181 182 If *use_decimal* is true (default: ``False``) then decimal.Decimal 183 will be natively serialized to JSON with full precision. 184 185 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 186 ``.default()`` method to serialize additional types), specify it with 187 the ``cls`` kwarg. 188 189 """ 190 # cached encoder 191 if (not skipkeys and ensure_ascii and 192 check_circular and allow_nan and 193 cls is None and indent is None and separators is None and 194 encoding == 'utf-8' and default is None and not kw): 195 iterable = _default_encoder.iterencode(obj) 196 else: 197 if cls is None: 198 cls = JSONEncoder 199 iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii, 200 check_circular=check_circular, allow_nan=allow_nan, indent=indent, 201 separators=separators, encoding=encoding, 202 default=default, use_decimal=use_decimal, **kw).iterencode(obj) 203 # could accelerate with writelines in some versions of Python, at 204 # a debuggability cost 205 for chunk in iterable: 206 fp.write(chunk) 207 208 209 def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, 210 allow_nan=True, cls=None, indent=None, separators=None, 211 encoding='utf-8', default=None, use_decimal=False, **kw): 212 """Serialize ``obj`` to a JSON formatted ``str``. 213 214 If ``skipkeys`` is false then ``dict`` keys that are not basic types 215 (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``) 216 will be skipped instead of raising a ``TypeError``. 217 218 If ``ensure_ascii`` is false, then the return value will be a 219 ``unicode`` instance subject to normal Python ``str`` to ``unicode`` 220 coercion rules instead of being escaped to an ASCII ``str``. 221 222 If ``check_circular`` is false, then the circular reference check 223 for container types will be skipped and a circular reference will 224 result in an ``OverflowError`` (or worse). 225 226 If ``allow_nan`` is false, then it will be a ``ValueError`` to 227 serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in 228 strict compliance of the JSON specification, instead of using the 229 JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``). 230 231 If ``indent`` is a string, then JSON array elements and object members 232 will be pretty-printed with a newline followed by that string repeated 233 for each level of nesting. ``None`` (the default) selects the most compact 234 representation without any newlines. For backwards compatibility with 235 versions of simplejson earlier than 2.1.0, an integer is also accepted 236 and is converted to a string with that many spaces. 237 238 If ``separators`` is an ``(item_separator, dict_separator)`` tuple 239 then it will be used instead of the default ``(', ', ': ')`` separators. 240 ``(',', ':')`` is the most compact JSON representation. 241 242 ``encoding`` is the character encoding for str instances, default is UTF-8. 243 244 ``default(obj)`` is a function that should return a serializable version 245 of obj or raise TypeError. The default simply raises TypeError. 246 247 If *use_decimal* is true (default: ``False``) then decimal.Decimal 248 will be natively serialized to JSON with full precision. 249 250 To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the 251 ``.default()`` method to serialize additional types), specify it with 252 the ``cls`` kwarg. 253 254 """ 255 # cached encoder 256 if (not skipkeys and ensure_ascii and 257 check_circular and allow_nan and 258 cls is None and indent is None and separators is None and 259 encoding == 'utf-8' and default is None and not use_decimal 260 and not kw): 261 return _default_encoder.encode(obj) 262 if cls is None: 263 cls = JSONEncoder 264 return cls( 265 skipkeys=skipkeys, ensure_ascii=ensure_ascii, 266 check_circular=check_circular, allow_nan=allow_nan, indent=indent, 267 separators=separators, encoding=encoding, default=default, 268 use_decimal=use_decimal, **kw).encode(obj) 269 270 271 _default_decoder = JSONDecoder(encoding=None, object_hook=None, 272 object_pairs_hook=None) 273 274 275 def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None, 276 parse_int=None, parse_constant=None, object_pairs_hook=None, 277 use_decimal=False, **kw): 278 """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing 279 a JSON document) to a Python object. 280 281 *encoding* determines the encoding used to interpret any 282 :class:`str` objects decoded by this instance (``'utf-8'`` by 283 default). It has no effect when decoding :class:`unicode` objects. 284 285 Note that currently only encodings that are a superset of ASCII work, 286 strings of other encodings should be passed in as :class:`unicode`. 287 288 *object_hook*, if specified, will be called with the result of every 289 JSON object decoded and its return value will be used in place of the 290 given :class:`dict`. This can be used to provide custom 291 deserializations (e.g. to support JSON-RPC class hinting). 292 293 *object_pairs_hook* is an optional function that will be called with 294 the result of any object literal decode with an ordered list of pairs. 295 The return value of *object_pairs_hook* will be used instead of the 296 :class:`dict`. This feature can be used to implement custom decoders 297 that rely on the order that the key and value pairs are decoded (for 298 example, :func:`collections.OrderedDict` will remember the order of 299 insertion). If *object_hook* is also defined, the *object_pairs_hook* 300 takes priority. 301 302 *parse_float*, if specified, will be called with the string of every 303 JSON float to be decoded. By default, this is equivalent to 304 ``float(num_str)``. This can be used to use another datatype or parser 305 for JSON floats (e.g. :class:`decimal.Decimal`). 306 307 *parse_int*, if specified, will be called with the string of every 308 JSON int to be decoded. By default, this is equivalent to 309 ``int(num_str)``. This can be used to use another datatype or parser 310 for JSON integers (e.g. :class:`float`). 311 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 317 If *use_decimal* is true (default: ``False``) then it implies 318 parse_float=decimal.Decimal for parity with ``dump``. 319 320 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 321 kwarg. 322 323 """ 324 return loads(fp.read(), 325 encoding=encoding, cls=cls, object_hook=object_hook, 326 parse_float=parse_float, parse_int=parse_int, 327 parse_constant=parse_constant, object_pairs_hook=object_pairs_hook, 328 use_decimal=use_decimal, **kw) 329 330 331 def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, 332 parse_int=None, parse_constant=None, object_pairs_hook=None, 333 use_decimal=False, **kw): 334 """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON 335 document) to a Python object. 336 337 *encoding* determines the encoding used to interpret any 338 :class:`str` objects decoded by this instance (``'utf-8'`` by 339 default). It has no effect when decoding :class:`unicode` objects. 340 341 Note that currently only encodings that are a superset of ASCII work, 342 strings of other encodings should be passed in as :class:`unicode`. 343 344 *object_hook*, if specified, will be called with the result of every 345 JSON object decoded and its return value will be used in place of the 346 given :class:`dict`. This can be used to provide custom 347 deserializations (e.g. to support JSON-RPC class hinting). 348 349 *object_pairs_hook* is an optional function that will be called with 350 the result of any object literal decode with an ordered list of pairs. 351 The return value of *object_pairs_hook* will be used instead of the 352 :class:`dict`. This feature can be used to implement custom decoders 353 that rely on the order that the key and value pairs are decoded (for 354 example, :func:`collections.OrderedDict` will remember the order of 355 insertion). If *object_hook* is also defined, the *object_pairs_hook* 356 takes priority. 357 358 *parse_float*, if specified, will be called with the string of every 359 JSON float to be decoded. By default, this is equivalent to 360 ``float(num_str)``. This can be used to use another datatype or parser 361 for JSON floats (e.g. :class:`decimal.Decimal`). 362 363 *parse_int*, if specified, will be called with the string of every 364 JSON int to be decoded. By default, this is equivalent to 365 ``int(num_str)``. This can be used to use another datatype or parser 366 for JSON integers (e.g. :class:`float`). 367 368 *parse_constant*, if specified, will be called with one of the 369 following strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``. This 370 can be used to raise an exception if invalid JSON numbers are 371 encountered. 372 373 If *use_decimal* is true (default: ``False``) then it implies 374 parse_float=decimal.Decimal for parity with ``dump``. 375 376 To use a custom ``JSONDecoder`` subclass, specify it with the ``cls`` 377 kwarg. 378 379 """ 380 if (cls is None and encoding is None and object_hook is None and 381 parse_int is None and parse_float is None and 382 parse_constant is None and object_pairs_hook is None 383 and not use_decimal and not kw): 384 return _default_decoder.decode(s) 385 if cls is None: 386 cls = JSONDecoder 387 if object_hook is not None: 388 kw['object_hook'] = object_hook 389 if object_pairs_hook is not None: 390 kw['object_pairs_hook'] = object_pairs_hook 391 if parse_float is not None: 392 kw['parse_float'] = parse_float 393 if parse_int is not None: 394 kw['parse_int'] = parse_int 395 if parse_constant is not None: 396 kw['parse_constant'] = parse_constant 397 if use_decimal: 398 if parse_float is not None: 399 raise TypeError("use_decimal=True implies parse_float=Decimal") 400 kw['parse_float'] = Decimal 401 return cls(encoding=encoding, **kw).decode(s) 402 403 404 def _toggle_speedups(enabled): 405 import simplejson.decoder as dec 406 import simplejson.encoder as enc 407 import simplejson.scanner as scan 408 c_make_encoder = _import_c_make_encoder() 409 if enabled: 410 dec.scanstring = dec.c_scanstring or dec.py_scanstring 411 enc.c_make_encoder = c_make_encoder 412 enc.encode_basestring_ascii = (enc.c_encode_basestring_ascii or 413 enc.py_encode_basestring_ascii) 414 scan.make_scanner = scan.c_make_scanner or scan.py_make_scanner 415 else: 416 dec.scanstring = dec.py_scanstring 417 enc.c_make_encoder = None 418 enc.encode_basestring_ascii = enc.py_encode_basestring_ascii 419 scan.make_scanner = scan.py_make_scanner 420 dec.make_scanner = scan.make_scanner 421 global _default_decoder 422 _default_decoder = JSONDecoder( 423 encoding=None, 424 object_hook=None, 425 object_pairs_hook=None, 426 ) 427 global _default_encoder 428 _default_encoder = JSONEncoder( 429 skipkeys=False, 430 ensure_ascii=True, 431 check_circular=True, 432 allow_nan=True, 433 indent=None, 434 separators=None, 435 encoding='utf-8', 436 default=None, 437 )