Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Fix JSON module docs.

This commit is contained in:
Georg Brandl 2008-05-05 20:53:39 +00:00
parent 4b964f9c90
commit 3961f1872c
1 changed files with 118 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

270
Doc/library/json.rst
View File

@ -1,8 +1,8 @@
:mod:`json` JSON encoder and decoder :mod:`json` --- JSON encoder and decoder
==================================== ========================================
.. module:: json .. module:: json
:synopsis: encode and decode the JSON format :synopsis: Encode and decode the JSON format.
.. moduleauthor:: Bob Ippolito <bob@redivi.com> .. moduleauthor:: Bob Ippolito <bob@redivi.com>
.. sectionauthor:: Bob Ippolito <bob@redivi.com> .. sectionauthor:: Bob Ippolito <bob@redivi.com>
.. versionadded:: 2.6 .. versionadded:: 2.6
@ -10,8 +10,8 @@
JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript
syntax (ECMA-262 3rd edition) used as a lightweight data interchange format. syntax (ECMA-262 3rd edition) used as a lightweight data interchange format.
:mod:`json` exposes an API familiar to uses of the standard library marshal and :mod:`json` exposes an API familiar to users of the standard library
pickle modules. :mod:`marshal` and :mod:`pickle` modules.
Encoding basic Python object hierarchies:: Encoding basic Python object hierarchies::
@ -74,7 +74,7 @@ Specializing JSON object decoding::
>>> json.loads('1.1', parse_float=decimal.Decimal) >>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1') Decimal('1.1')
Extending JSONEncoder:: Extending :class:`JSONEncoder`::
>>> import json >>> import json
>>> class ComplexEncoder(json.JSONEncoder): >>> class ComplexEncoder(json.JSONEncoder):
@ -106,7 +106,7 @@ Using json.tool from the shell to validate and pretty-print::
.. note:: .. note::
Note that the JSON produced by this module's default settings is a subset of 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. YAML, so it may be used as a serializer for that as well.
@ -115,118 +115,55 @@ Basic Usage
.. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]]) .. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])
Serialize *obj* as a JSON formatted stream to *fp* (a Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
``.write()``-supporting file-like object). file-like object).
If *skipkeys* is ``True`` (It is ``False`` by default.), then ``dict`` keys If *skipkeys* is ``True`` (default: ``False``), then dict keys that are not
that are not basic types (``str``, ``unicode``, ``int``, ``long``, of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
``float``, ``bool``, ``None``) will be skipped instead of raising a :class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
:exc:`TypeError`. :exc:`TypeError`.
If *ensure_ascii* is ``False`` (It is ``True`` by default.), then the some If *ensure_ascii* is ``False`` (default: ``True``), then some chunks written
chunks written to *fp* may be ``unicode`` instances, subject to normal to *fp* may be :class:`unicode` instances, subject to normal Python
Python ``str`` to ``unicode`` coercion rules. Unless ``fp.write()`` :class:`str` to :class:`unicode` coercion rules. Unless ``fp.write()``
explicitly understands ``unicode`` (as in ``codecs.getwriter()``) this is explicitly understands :class:`unicode` (as in :func:`codecs.getwriter`) this
likely to cause an error. is likely to cause an error.
If *check_circular* is ``False``, then the circular reference check for If *check_circular* is ``False`` (default: ``True``), then the circular
container types will be skipped and a circular reference will result in an reference check for container types will be skipped and a circular reference
:exc:`OverflowError` (or worse). will result in an :exc:`OverflowError` (or worse).
If *allow_nan* is ``False``, then it will be a :exc:`ValueError` to If *allow_nan* is ``False`` (default: ``True``), then it will be a
serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in :exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
strict compliance of the JSON specification, instead of using the JavaScript ``inf``, ``-inf``) in strict compliance of the JSON specification, instead of
equivalents (``NaN``, ``Infinity``, ``-Infinity``). using the JavaScript equivalents (``NaN``, ``Infinity``, ``-Infinity``).
If *indent* is a non-negative integer, then JSON array elements and object If *indent* is a non-negative integer, then JSON array elements and object
members will be pretty-printed with that indent level. An indent level of 0 members will be pretty-printed with that indent level. An indent level of 0
will only insert newlines. ``None`` is the most compact representation. will only insert newlines. ``None`` (the default) selects the most compact
representation.
If *separators* is an ``(item_separator, dict_separator)`` tuple then it If *separators* is an ``(item_separator, dict_separator)`` tuple, then it
will be used instead of the default ``(', ', ': ')`` separators. ``(',', will be used instead of the default ``(', ', ': ')`` separators. ``(',',
':')`` is the most compact JSON representation. ':')`` is the most compact JSON representation.
*encoding* is the character encoding for str instances, default is UTF-8. *encoding* is the character encoding for str instances, default is UTF-8.
*default(obj)* is a function that should return a serializable version of *default(obj)* is a function that should return a serializable version of
obj or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. *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
``.default()`` method to serialize additional types), specify it with the :meth:`default` method to serialize additional types), specify it with the
*cls* kwarg. *cls* kwarg.
.. function:: dump(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]]) .. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, **kw]]]]]]]]]])
Serialize *obj* to a JSON formatted ``str``. Serialize *obj* to a JSON formatted :class:`str`.
If *skipkeys* is ``True`` (It is ``False`` by default.), then ``dict`` keys If *ensure_ascii* is ``False``, then the return value will be a
that are not basic types (``str``, ``unicode``, ``int``, ``long``, :class:`unicode` instance. The other arguments have the same meaning as in
``float``, ``bool``, ``None``) will be skipped instead of raising a :func:`dump`.
:exc:`TypeError`.
If *ensure_ascii* is ``False``, then the return value will be a ``unicode``
instance subject to normal Python ``str`` to ``unicode`` coercion rules
instead of being escaped to an ASCII ``str``.
If *check_circular* is ``False``, then the circular reference check for
container types will be skipped and a circular reference will result in an
:exc:`OverflowError` (or worse).
If *allow_nan* is ``False``, then it will be a :exc:`ValueError` to
serialize out of range ``float`` values (``nan``, ``inf``, ``-inf``) in
strict compliance of the JSON specification, instead of using the JavaScript
equivalents (``NaN``, ``Infinity``, ``-Infinity``).
If *indent* is a non-negative integer, then JSON array elements and object
members will be pretty-printed with that indent level. An indent level of 0
will only insert newlines. ``None`` is the most compact representation.
If *separators* is an ``(item_separator, dict_separator)`` tuple then it
will be used instead of the default ``(', ', ': ')`` separators. ``(',',
':')`` is the most compact JSON representation.
*encoding* is the character encoding for str instances, default is UTF-8.
*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
``.default()`` method to serialize additional types), specify it with the
*cls* kwarg.
.. function loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, **kw]]]]]]])
Deserialize *s* (a ``str`` or ``unicode`` instance containing a JSON
document) to a Python object.
If *s* is a ``str`` instance and is encoded with an ASCII based encoding
other than utf-8 (e.g. latin-1) then an appropriate ``encoding`` name must be
specified. Encodings that are not ASCII based (such as UCS-2) are not allowed
and should be decoded to ``unicode`` first.
*object_hook* is an optional function that will be called with the result of
any object literal decode (a ``dict``). The return value of ``object_hook``
will be used instead of the ``dict``. This feature can be used to implement
custom decoders (e.g. JSON-RPC class hinting).
*parse_float*, if specified, will be called with the string of every JSON
float to be decoded. By default, this is equivalent to
``float(num_str)``. This can be used to use another datatype or parser for
JSON floats (e.g. decimal.Decimal).
*parse_int*, if specified, will be called with the string of every JSON int
to be decoded. By default this is equivalent to int(num_str). This can be
used to use another datatype or parser for JSON integers (e.g. float).
*parse_constant*, if specified, will be called with one of the following
strings: -Infinity, Infinity, NaN, null, true, false. This can be used to
raise an exception if invalid JSON numbers are encountered.
To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
kwarg. Additional keyword arguments will be passed to the constructor of the
class.
.. 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]]]]]]])
@ -234,28 +171,56 @@ Basic Usage
Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
document) to a Python object. document) to a Python object.
If the contents of *fp* is encoded with an ASCII based encoding other than If the contents of *fp* are encoded with an ASCII based encoding other than
utf-8 (e.g. latin-1), then an appropriate ``encoding`` name must be UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be specified.
specified. Encodings that are not ASCII based (such as UCS-2) are not Encodings that are not ASCII based (such as UCS-2) are not allowed, and
allowed, and should be wrapped with :func:`codecs.getreader(fp)(encoding)`, should be wrapped with ``codecs.getreader(fp)(encoding)``, or simply decoded
or simply decoded to a ``unicode`` object and passed to ``loads()`` to a :class:`unicode` object and passed to :func:`loads`.
*object_hook* is an optional function that will be called with the result of *object_hook* is an optional function that will be called with the result of
any object literal decode (a ``dict``). The return value of *object_hook* any object literal decode (a :class:`dict`). The return value of
will be used instead of the ``dict``. This feature can be used to implement *object_hook* will be used instead of the :class:`dict`. This feature can be used
custom decoders (e.g. JSON-RPC class hinting). to implement custom decoders (e.g. JSON-RPC class hinting).
*parse_float*, if specified, will be called with the string of every JSON
float to be decoded. By default, this is equivalent to ``float(num_str)``.
This can be used to use another datatype or parser for JSON floats
(e.g. :class:`decimal.Decimal`).
*parse_int*, if specified, will be called with the string of every JSON int
to be decoded. By default, this is equivalent to ``int(num_str)``. This can
be used to use another datatype or parser for JSON integers
(e.g. :class:`float`).
*parse_constant*, if specified, will be called with one of the following
strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``, ``'null'``, ``'true'``,
``'false'``. This can be used to raise an exception if invalid JSON numbers
are encountered.
To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls`` To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
kwarg. Additional keyword arguments will be passed to the constructor of the kwarg. Additional keyword arguments will be passed to the constructor of the
class. class.
.. 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.
If *s* is a :class:`str` instance and is encoded with an ASCII based encoding
other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be
specified. Encodings that are not ASCII based (such as UCS-2) are not
allowed and should be decoded to :class:`unicode` first.
The other arguments have the same meaning as in :func:`dump`.
Encoders and decoders Encoders and decoders
--------------------- ---------------------
.. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict]]]]]]) .. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict]]]]]])
Simple JSON decoder Simple JSON decoder.
Performs the following translations in decoding by default: Performs the following translations in decoding by default:
@ -282,50 +247,52 @@ Encoders and decoders
It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
corresponding ``float`` values, which is outside the JSON spec. corresponding ``float`` values, which is outside the JSON spec.
*encoding* determines the encoding used to interpret any ``str`` objects *encoding* determines the encoding used to interpret any :class:`str` objects
decoded by this instance (utf-8 by default). It has no effect when decoding decoded by this instance (UTF-8 by default). It has no effect when decoding
``unicode`` objects. :class:`unicode` objects.
Note that currently only encodings that are a superset of ASCII work, Note that currently only encodings that are a superset of ASCII work, strings
strings of other encodings should be passed in as ``unicode``. of other encodings should be passed in as :class:`unicode`.
*object_hook*, if specified, will be called with the result of every JSON *object_hook*, if specified, will be called with the result of every JSON
object decoded and its return value will be used in place of the given object decoded and its return value will be used in place of the given
``dict``. This can be used to provide custom deserializations (e.g. to :class:`dict`. This can be used to provide custom deserializations (e.g. to
support JSON-RPC class hinting). support JSON-RPC class hinting).
*parse_float*, if specified, will be called with the string of every JSON *parse_float*, if specified, will be called with the string of every JSON
float to be decoded. By default this is equivalent to float(num_str). This float to be decoded. By default, this is equivalent to ``float(num_str)``.
can be used to use another datatype or parser for JSON floats This can be used to use another datatype or parser for JSON floats
(e.g. decimal.Decimal). (e.g. :class:`decimal.Decimal`).
*parse_int*, if specified, will be called with the string of every JSON int *parse_int*, if specified, will be called with the string of every JSON int
to be decoded. By default this is equivalent to int(num_str). This can be to be decoded. By default, this is equivalent to ``int(num_str)``. This can
used to use another datatype or parser for JSON integers (e.g. float). be used to use another datatype or parser for JSON integers
(e.g. :class:`float`).
*parse_constant*, if specified, will be called with one of the following *parse_constant*, if specified, will be called with one of the following
strings: -Infinity, Infinity, NaN, null, true, false. This can be used to strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``, ``'null'``, ``'true'``,
raise an exception if invalid JSON numbers are encountered. ``'false'``. This can be used to raise an exception if invalid JSON numbers
are encountered.
.. method:: decode(s) .. method:: decode(s)
Return the Python representation of *s* (a ``str`` or ``unicode`` instance Return the Python representation of *s* (a :class:`str` or
containing a JSON document) :class:`unicode` instance containing a JSON document)
.. method:: raw_decode(s) .. method:: raw_decode(s)
Decode a JSON document from *s* (a ``str`` or ``unicode`` beginning with a Decode a JSON document from *s* (a :class:`str` or :class:`unicode`
JSON document) and return a 2-tuple of the Python representation and the beginning with a JSON document) and return a 2-tuple of the Python
index in *s* where the document ended. representation and the index in *s* where the document ended.
This can be used to decode a JSON document from a string that may have This can be used to decode a JSON document from a string that may have
extraneous data at the end. extraneous data at the end.
.. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]]) .. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]])
Extensible JSON <http://json.org> encoder for Python data structures. Extensible JSON encoder for Python data structures.
Supports the following objects and types by default: Supports the following objects and types by default:
@ -348,7 +315,7 @@ Encoders and decoders
+-------------------+---------------+ +-------------------+---------------+
To extend this to recognize other objects, subclass and implement a To extend this to recognize other objects, subclass and implement a
``.default()`` method with another method that returns a serializable object :meth:`default` method with another method that returns a serializable object
for ``o`` if possible, otherwise it should call the superclass implementation for ``o`` if possible, otherwise it should call the superclass implementation
(to raise :exc:`TypeError`). (to raise :exc:`TypeError`).
@ -356,31 +323,32 @@ Encoders and decoders
attempt encoding of keys that are not str, int, long, float or None. If attempt encoding of keys that are not str, int, long, float or None. If
*skipkeys* is ``True``, such items are simply skipped. *skipkeys* is ``True``, such items are simply skipped.
If *ensure_ascii* is ``True``, the output is guaranteed to be ``str`` objects If *ensure_ascii* is ``True`` (the default), the output is guaranteed to be
with all incoming unicode characters escaped. If *ensure_ascii* is :class:`str` objects with all incoming unicode characters escaped. If
``False``, the output will be unicode object. *ensure_ascii* is ``False``, the output will be a unicode object.
If *check_circular* is ``True`` (the default), then lists, dicts, and custom If *check_circular* is ``True`` (the default), then lists, dicts, and custom
encoded objects will be checked for circular references during encoding to encoded objects will be checked for circular references during encoding to
prevent an infinite recursion (which would cause an :exc:`OverflowError`). prevent an infinite recursion (which would cause an :exc:`OverflowError`).
Otherwise, no such check takes place. Otherwise, no such check takes place.
If *allow_nan* is ``True`` (the default), then ``NaN``, ``Infinity``, and ``-Infinity`` If *allow_nan* is ``True`` (the default), then ``NaN``, ``Infinity``, and
will be encoded as such. This behavior is not JSON specification compliant, ``-Infinity`` will be encoded as such. This behavior is not JSON
but is consistent with most JavaScript based encoders and decoders. specification compliant, but is consistent with most JavaScript based
Otherwise, it will be a :exc:`ValueError` to encode such floats. encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
such floats.
If *sort_keys* is ``True`` (the default), then the output of dictionaries If *sort_keys* is ``True`` (the default), then the output of dictionaries
will be sorted by key; this is useful for regression tests to ensure that will be sorted by key; this is useful for regression tests to ensure that
JSON serializations can be compared on a day-to-day basis. JSON serializations can be compared on a day-to-day basis.
If *indent* is a non-negative integer (It is ``None`` by default.), then JSON If *indent* is a non-negative integer (it is ``None`` by default), then JSON
array elements and object members will be pretty-printed with that indent array elements and object members will be pretty-printed with that indent
level. An indent level of 0 will only insert newlines. ``None`` is the most level. An indent level of 0 will only insert newlines. ``None`` is the most
compact representation. compact representation.
If specified, *separators* should be a (item_separator, key_separator) tuple. If specified, *separators* should be an ``(item_separator, key_separator)``
The default is ``(', ', ': ')``. To get the most compact JSON tuple. The default is ``(', ', ': ')``. To get the most compact JSON
representation, you should specify ``(',', ':')`` to eliminate whitespace. representation, you should specify ``(',', ':')`` to eliminate whitespace.
If specified, *default* is a function that gets called for objects that can't If specified, *default* is a function that gets called for objects that can't
@ -413,7 +381,7 @@ Encoders and decoders
.. method:: encode(o) .. method:: encode(o)
Return a JSON string representation of a Python data structure, *o*. For Return a JSON string representation of a Python data structure, *o*. For
example:: example::
>>> JSONEncoder().encode({"foo": ["bar", "baz"]}) >>> JSONEncoder().encode({"foo": ["bar", "baz"]})
@ -423,9 +391,7 @@ Encoders and decoders
.. method:: iterencode(o) .. method:: iterencode(o)
Encode the given object, *o*, and yield each string representation as Encode the given object, *o*, and yield each string representation as
available. available. For example::
For example::
for chunk in JSONEncoder().iterencode(bigobject): for chunk in JSONEncoder().iterencode(bigobject):
mysocket.write(chunk) mysocket.write(chunk)