diff options
author | Bob Ippolito <bob@redivi.com> | 2008-12-30 19:00:33 +0000 |
---|---|---|
committer | Bob Ippolito <bob@redivi.com> | 2008-12-30 19:00:33 +0000 |
commit | aa95b2226ed8566a643378f0995ee626b8200368 (patch) | |
tree | 7400c0070e2746a6c80d7b7ab1716444bfd92656 /index.rst | |
parent | ab589fa80b65895376cfb942ef786eb6b036f14a (diff) | |
download | simplejson-aa95b2226ed8566a643378f0995ee626b8200368.tar.gz |
version bump, fixes to docs re http://bugs.python.org/issue4783
git-svn-id: http://simplejson.googlecode.com/svn/trunk@157 a4795897-2c25-0410-b006-0d3caba88fa1
Diffstat (limited to 'index.rst')
-rw-r--r-- | index.rst | 44 |
1 files changed, 29 insertions, 15 deletions
@@ -13,11 +13,11 @@ syntax (ECMA-262 3rd edition) used as a lightweight data interchange format. :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained version of the :mod:`json` library contained in Python 2.6, but maintains compatibility with Python 2.4 and Python 2.5 and (currently) has -significant performance advantages, even without using the optional C +significant performance advantages, even without using the optional C extension for speedups. Encoding basic Python object hierarchies:: - + >>> import simplejson as json >>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}]) '["foo", {"bar": ["baz", null, 1.0, 2]}]' @@ -46,12 +46,12 @@ Pretty printing:: >>> import simplejson as json >>> print json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4) { - "4": 5, + "4": 5, "6": 7 } Decoding JSON:: - + >>> import simplejson as json >>> obj = [u'foo', {u'bar': [u'baz', None, 1.0, 2]}] >>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]') == obj @@ -70,7 +70,7 @@ Specializing JSON object decoding:: ... if '__complex__' in dct: ... return complex(dct['real'], dct['imag']) ... return dct - ... + ... >>> json.loads('{"__complex__": true, "real": 1, "imag": 2}', ... object_hook=as_complex) (1+2j) @@ -79,7 +79,7 @@ Specializing JSON object decoding:: True Specializing JSON object encoding:: - + >>> import simplejson as json >>> def encode_complex(obj): ... if isinstance(obj, complex): @@ -92,12 +92,12 @@ Specializing JSON object encoding:: '[2.0, 1.0]' >>> ''.join(json.JSONEncoder(default=encode_complex).iterencode(2 + 1j)) '[2.0, 1.0]' - + .. highlight:: none Using simplejson.tool from the shell to validate and pretty-print:: - + $ echo '{"json":"obj"}' | python -msimplejson.tool { "json": "obj" @@ -107,7 +107,7 @@ Using simplejson.tool from the shell to validate and pretty-print:: .. highlight:: python -.. note:: +.. note:: The JSON produced by this module's default settings is a subset of YAML, so it may be used as a serializer for that as well. @@ -156,10 +156,16 @@ Basic Usage *default(obj)* is a function that should return a serializable version of *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. - To use a custom :class:`JSONEncoder`` subclass (e.g. one that overrides the + To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the :meth:`default` method to serialize additional types), specify it with the *cls* kwarg. + .. note:: + + JSON is not a framed protocol so unlike :mod:`pickle` or :mod:`marshal` it + does not make sense to serialize more than one JSON document without some + container protocol to delimit them. + .. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]]) @@ -171,7 +177,7 @@ Basic Usage better performance. -.. function load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) +.. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON document) to a Python object. @@ -206,8 +212,16 @@ Basic Usage kwarg. Additional keyword arguments will be passed to the constructor of the class. + .. note:: + + :func:`load` will read the rest of the file-like object as a string and + then call :func:`loads`. It does not stop at the end of the first valid + JSON document it finds and it will raise an error if there is anything + other than whitespace after the document. Except for files containing + only one JSON document, it is recommended to use :func:`loads`. + -.. function loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) +.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]]) Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON document) to a Python object. @@ -372,7 +386,7 @@ Encoders and decoders For example, to support arbitrary iterators, you could implement default like this:: - + def default(self, o): try: iterable = iter(o) @@ -397,9 +411,9 @@ Encoders and decoders Encode the given object, *o*, and yield each string representation as available. For example:: - + for chunk in JSONEncoder().iterencode(bigobject): mysocket.write(chunk) - + Note that :meth:`encode` has much better performance than :meth:`iterencode`. |