| # Gaudi Framework, version v21r9 |

Home |  | Generated: 3 May 2010

# __init__.py

Go to the documentation of this file.

    00001 r"""JSON (JavaScript Object Notation) <http://json.org> is a subset of
    00002 JavaScript syntax (ECMA-262 3rd edition) used as a lightweight data
    00003 interchange format.
    00004
    00005 :mod:`simplejson` exposes an API familiar to users of the standard library
    00006 :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained
    00007 version of the :mod:`json` library contained in Python 2.6, but maintains
    00008 compatibility with Python 2.4 and Python 2.5 and (currently) has
    00009 significant performance advantages, even without using the optional C
    00010 extension for speedups.
    00011
    00012 Encoding basic Python object hierarchies::
    00013
    00014     >>> import simplejson as json
    00015     >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
    00016     '["foo", {"bar": ["baz", null, 1.0, 2]}]'
    00017     >>> print json.dumps("\"foo\bar")
    00018     "\"foo\bar"
    00019     >>> print json.dumps(u'\u1234')
    00020     "\u1234"
    00021     >>> print json.dumps('\\')
    00022     "\\"
    00023     >>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
    00024     {"a": 0, "b": 0, "c": 0}
    00025     >>> from StringIO import StringIO
    00026     >>> io = StringIO()
    00027     >>> json.dump(['streaming API'], io)
    00028     >>> io.getvalue()
    00029     '["streaming API"]'
    00030
    00031 Compact encoding::
    00032
    00033     >>> import simplejson as json
    00034     >>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
    00035     '[1,2,3,{"4":5,"6":7}]'
    00036
    00037 Pretty printing::
    00038
    00039     >>> import simplejson as json
    00040     >>> s = json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)
    00041     >>> print '\n'.join([l.rstrip() for l in  s.splitlines()])
    00042     {
    00043         "4": 5,
    00044         "6": 7
    00045     }
    00046
    00047 Decoding JSON::
    00048
    00049     >>> import simplejson as json
    00050     >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
    00051     >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj
    00052     True
    00053     >>> json.loads('"\\"foo\\bar"') == u'"foo\x08ar'
    00054     True
    00055     >>> from StringIO import StringIO
    00056     >>> io = StringIO('["streaming API"]')
    00057     >>> json.load(io)[0] == 'streaming API'
    00058     True
    00059
    00060 Specializing JSON object decoding::
    00061
    00062     >>> import simplejson as json
    00063     >>> def as_complex(dct):
    00064     ...     if '__complex__' in dct:
    00065     ...         return complex(dct['real'], dct['imag'])
    00066     ...     return dct
    00067     ...
    00068     >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
    00069     ...     object_hook=as_complex)
    00070     (1+2j)
    00071     >>> import decimal
    00072     >>> json.loads('1.1', parse_float=decimal.Decimal) == decimal.Decimal('1.1')
    00073     True
    00074
    00075 Specializing JSON object encoding::
    00076
    00077     >>> import simplejson as json
    00078     >>> def encode_complex(obj):
    00079     ...     if isinstance(obj, complex):
    00080     ...         return [obj.real, obj.imag]
    00081     ...     raise TypeError(repr(o) + " is not JSON serializable")
    00082     ...
    00083     >>> json.dumps(2 + 1j, default=encode_complex)
    00084     '[2.0, 1.0]'
    00085     >>> json.JSONEncoder(default=encode_complex).encode(2 + 1j)
    00086     '[2.0, 1.0]'
    00087     >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j))
    00088     '[2.0, 1.0]'
    00089
    00090
    00091 Using simplejson.tool from the shell to validate and pretty-print::
    00092
    00093     $ echo '{"json":"obj"}' | python -m simplejson.tool
    00094     {
    00095         "json": "obj"
    00096     }
    00097     $ echo '{ 1.2:3.4}' | python -m simplejson.tool
    00098     Expecting property name: line 1 column 2 (char 2)
    00099 """
    00100 __version__ = '2.0.9'
    00101 __all__ = [
    00102     'dump', 'dumps', 'load', 'loads',
    00103     'JSONDecoder', 'JSONEncoder',
    00104 ]
    00105
    00106 __author__ = 'Bob Ippolito <bob@redivi.com>'
    00107
    00108 from decoder import JSONDecoder
    00109 from encoder import JSONEncoder
    00110
    00111 _default_encoder = JSONEncoder(
    00112     skipkeys=False,
    00113     ensure_ascii=True,
    00114     check_circular=True,
    00115     allow_nan=True,
    00116     indent=None,
    00117     separators=None,
    00118     encoding='utf-8',
    00119     default=None,
    00120 )
    00121
    00122 def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
    00123         allow_nan=True, cls=None, indent=None, separators=None,
    00124         encoding='utf-8', default=None, **kw):
    00125     """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
    00126     ``.write()``-supporting file-like object).
    00127
    00128     If ``skipkeys`` is true then ``dict`` keys that are not basic types
    00129     (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
    00130     will be skipped instead of raising a ``TypeError``.
    00131
    00132     If ``ensure_ascii`` is false, then the some chunks written to ``fp``
    00133     may be ``unicode`` instances, subject to normal Python ``str`` to
    00134     ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
    00135     understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
    00136     to cause an error.
    00137
    00138     If ``check_circular`` is false, then the circular reference check
    00139     for container types will be skipped and a circular reference will
    00140     result in an ``OverflowError`` (or worse).
    00141
    00142     If ``allow_nan`` is false, then it will be a ``ValueError`` to
    00143     serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``)
    00144     in strict compliance of the JSON specification, instead of using the
    00145     JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
    00146
    00147     If ``indent`` is a non-negative integer, then JSON array elements and object
    00148     members will be pretty-printed with that indent level. An indent level
    00149     of 0 will only insert newlines. ``None`` is the most compact representation.
    00150
    00151     If ``separators`` is an ``(item_separator, dict_separator)`` tuple
    00152     then it will be used instead of the default ``(', ', ': ')`` separators.
    00153     ``(',', ':')`` is the most compact JSON representation.
    00154
    00155     ``encoding`` is the character encoding for str instances, default is UTF-8.
    00156
    00157     ``default(obj)`` is a function that should return a serializable version
    00158     of obj or raise TypeError. The default simply raises TypeError.
    00159
    00160     To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
    00161     ``.default()`` method to serialize additional types), specify it with
    00162     the ``cls`` kwarg.
    00163
    00164     """
    00165     # cached encoder
    00166     if (not skipkeys and ensure_ascii and
    00167         check_circular and allow_nan and
    00168         cls is None and indent is None and separators is None and
    00169         encoding == 'utf-8' and default is None and not kw):
    00170         iterable = _default_encoder.iterencode(obj)
    00171     else:
    00172         if cls is None:
    00173             cls = JSONEncoder
    00174         iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
    00175             check_circular=check_circular, allow_nan=allow_nan, indent=indent,
    00176             separators=separators, encoding=encoding,
    00177             default=default, **kw).iterencode(obj)
    00178     # could accelerate with writelines in some versions of Python, at
    00179     # a debuggability cost
    00180     for chunk in iterable:
    00181         fp.write(chunk)
    00182
    00183
    00184 def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
    00185         allow_nan=True, cls=None, indent=None, separators=None,
    00186         encoding='utf-8', default=None, **kw):
    00187     """Serialize ``obj`` to a JSON formatted ``str``.
    00188
    00189     If ``skipkeys`` is false then ``dict`` keys that are not basic types
    00190     (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
    00191     will be skipped instead of raising a ``TypeError``.
    00192
    00193     If ``ensure_ascii`` is false, then the return value will be a
    00194     ``unicode`` instance subject to normal Python ``str`` to ``unicode``
    00195     coercion rules instead of being escaped to an ASCII ``str``.
    00196
    00197     If ``check_circular`` is false, then the circular reference check
    00198     for container types will be skipped and a circular reference will
    00199     result in an ``OverflowError`` (or worse).
    00200
    00201     If ``allow_nan`` is false, then it will be a ``ValueError`` to
    00202     serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
    00203     strict compliance of the JSON specification, instead of using the
    00204     JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
    00205
    00206     If ``indent`` is a non-negative integer, then JSON array elements and
    00207     object members will be pretty-printed with that indent level. An indent
    00208     level of 0 will only insert newlines. ``None`` is the most compact
    00209     representation.
    00210
    00211     If ``separators`` is an ``(item_separator, dict_separator)`` tuple
    00212     then it will be used instead of the default ``(', ', ': ')`` separators.
    00213     ``(',', ':')`` is the most compact JSON representation.
    00214
    00215     ``encoding`` is the character encoding for str instances, default is UTF-8.
    00216
    00217     ``default(obj)`` is a function that should return a serializable version
    00218     of obj or raise TypeError. The default simply raises TypeError.
    00219
    00220     To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
    00221     ``.default()`` method to serialize additional types), specify it with
    00222     the ``cls`` kwarg.
    00223
    00224     """
    00225     # cached encoder
    00226     if (not skipkeys and ensure_ascii and
    00227         check_circular and allow_nan and
    00228         cls is None and indent is None and separators is None and
    00229         encoding == 'utf-8' and default is None and not kw):
    00230         return _default_encoder.encode(obj)
    00231     if cls is None:
    00232         cls = JSONEncoder
    00233     return cls(
    00234         skipkeys=skipkeys, ensure_ascii=ensure_ascii,
    00235         check_circular=check_circular, allow_nan=allow_nan, indent=indent,
    00236         separators=separators, encoding=encoding, default=default,
    00237         **kw).encode(obj)
    00238
    00239
    00240 _default_decoder = JSONDecoder(encoding=None, object_hook=None)
    00241
    00242
    00243 def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
    00244         parse_int=None, parse_constant=None, **kw):
    00245     """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
    00246     a JSON document) to a Python object.
    00247
    00248     If the contents of ``fp`` is encoded with an ASCII based encoding other
    00249     than utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must
    00250     be specified. Encodings that are not ASCII based (such as UCS-2) are
    00251     not allowed, and should be wrapped with
    00252     ``codecs.getreader(fp)(encoding)``, or simply decoded to a ``unicode``
    00253     object and passed to ``loads()``
    00254
    00255     ``object_hook`` is an optional function that will be called with the
    00256     result of any object literal decode (a ``dict``). The return value of
    00257     ``object_hook`` will be used instead of the ``dict``. This feature
    00258     can be used to implement custom decoders (e.g. JSON-RPC class hinting).
    00259
    00260     To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
    00261     kwarg.
    00262
    00263     """
    00264     return loads(fp.read(),
    00265         encoding=encoding, cls=cls, object_hook=object_hook,
    00266         parse_float=parse_float, parse_int=parse_int,
    00267         parse_constant=parse_constant, **kw)
    00268
    00269
    00270 def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
    00271         parse_int=None, parse_constant=None, **kw):
    00272     """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
    00273     document) to a Python object.
    00274
    00275     If ``s`` is a ``str`` instance and is encoded with an ASCII based encoding
    00276     other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name
    00277     must be specified. Encodings that are not ASCII based (such as UCS-2)
    00278     are not allowed and should be decoded to ``unicode`` first.
    00279
    00280     ``object_hook`` is an optional function that will be called with the
    00281     result of any object literal decode (a ``dict``). The return value of
    00282     ``object_hook`` will be used instead of the ``dict``. This feature
    00283     can be used to implement custom decoders (e.g. JSON-RPC class hinting).
    00284
    00285     ``parse_float``, if specified, will be called with the string
    00286     of every JSON float to be decoded. By default this is equivalent to
    00287     float(num_str). This can be used to use another datatype or parser
    00288     for JSON floats (e.g. decimal.Decimal).
    00289
    00290     ``parse_int``, if specified, will be called with the string
    00291     of every JSON int to be decoded. By default this is equivalent to
    00292     int(num_str). This can be used to use another datatype or parser
    00293     for JSON integers (e.g. float).
    00294
    00295     ``parse_constant``, if specified, will be called with one of the
    00296     following strings: -Infinity, Infinity, NaN, null, true, false.
    00297     This can be used to raise an exception if invalid JSON numbers
    00298     are encountered.
    00299
    00300     To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
    00301     kwarg.
    00302
    00303     """
    00304     if (cls is None and encoding is None and object_hook is None and
    00305             parse_int is None and parse_float is None and
    00306             parse_constant is None and not kw):
    00307         return _default_decoder.decode(s)
    00308     if cls is None:
    00309         cls = JSONDecoder
    00310     if object_hook is not None:
    00311         kw['object_hook'] = object_hook
    00312     if parse_float is not None:
    00313         kw['parse_float'] = parse_float
    00314     if parse_int is not None:
    00315         kw['parse_int'] = parse_int
    00316     if parse_constant is not None:
    00317         kw['parse_constant'] = parse_constant
    00318     return cls(encoding=encoding, **kw).decode(s)