external_libraries/simplejson-2.3.2/__init__.py

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