update documentation per #102docs-102

1 files changed, 216 insertions, 39 deletions

diff --git a/index.rst b/index.rst
index ea1e35d..a959d0a 100644
--- a/index.rst
+++ b/index.rst
@@ -6,8 +6,10 @@
 .. moduleauthor:: Bob Ippolito <bob@redivi.com>
 .. sectionauthor:: Bob Ippolito <bob@redivi.com>
 
-JSON (JavaScript Object Notation) <http://json.org> is a subset of JavaScript
-syntax (ECMA-262 3rd edition) used as a lightweight data interchange format.
+`JSON (JavaScript Object Notation) <http://json.org>`_, specified by
+:rfc:`4627`, is a lightweight data interchange format based on a subset of
+`JavaScript <http://en.wikipedia.org/wiki/JavaScript>`_ syntax (`ECMA-262 3rd
+edition <http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf>`_).
 
 :mod:`simplejson` exposes an API familiar to users of the standard library
 :mod:`marshal` and :mod:`pickle` modules. It is the externally maintained
@@ -107,7 +109,7 @@ Specializing JSON object encoding::
     '[2.0, 1.0]'
 
 
-.. highlight:: none
+.. highlight:: bash
 
 Using :mod:`simplejson.tool` from the shell to validate and pretty-print::
 
@@ -122,23 +124,36 @@ Using :mod:`simplejson.tool` from the shell to validate and pretty-print::
 
 .. 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.
+   JSON is a subset of `YAML <http://yaml.org/>`_ 1.2. The JSON produced by
+   this module's default settings (in particular, the default *separators*
+   value) is also a subset of YAML 1.0 and 1.1. This module can thus also be
+   used as a YAML serializer.
 
 
 Basic Usage
 -----------
 
-.. function:: dump(obj, fp[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, sort_keys[, item_sort_key[, [for_json[, ignore_nan[, int_as_string_bitcount[, **kw]]]]]]]]]]]]]]]]]]])
+.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, \
+                   check_circular=True, allow_nan=True, cls=None, \
+                   indent=None, separators=None, encoding='utf-8', \
+                   default=None, use_decimal=True, \
+                   namedtuple_as_object=True, tuple_as_array=True, \
+                   bigint_as_string=False, sort_keys=False, \
+                   item_sort_key=None, for_json=None, ignore_nan=False, \
+                   int_as_string_bitcount=None, **kw)
 
    Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
-   file-like object).
+   file-like object) using this :ref:`conversion table <py-to-json-table>`.
 
    If *skipkeys* is true (default: ``False``), then dict keys that are not
    of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
    :class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
    :exc:`TypeError`.
 
+   The :mod:`simplejson` module will produce :class:`str` objects in Python 3,
+   not :class:`bytes` objects. Therefore, ``fp.write()`` must support
+   :class:`str` input.
+
    If *ensure_ascii* is false (default: ``True``), then some chunks written
    to *fp* may be :class:`unicode` instances, subject to normal Python
    :class:`str` to :class:`unicode` coercion rules.  Unless ``fp.write()``
@@ -179,7 +194,7 @@ Basic Usage
    ``'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`.
+   *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`.
 
    To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
    :meth:`default` method to serialize additional types), specify it with the
@@ -262,7 +277,7 @@ Basic Usage
    .. versionchanged:: 3.2.0
       *ignore_nan* is new in 3.2.0.
 
-   If *int_as_string_bitcount* is a positive number ``n`` (default: ``False``),
+   If *int_as_string_bitcount* is a positive number ``n`` (default: ``None``),
    :class:`int` ``2**n`` and higher or lower than ``-2**n`` will be encoded as strings. This is to
    avoid the rounding that happens in Javascript otherwise. Note that this
    option loses type information, so use with extreme caution.
@@ -278,22 +293,33 @@ Basic Usage
         container protocol to delimit them.
 
 
-.. function:: dumps(obj[, skipkeys[, ensure_ascii[, check_circular[, allow_nan[, cls[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, sort_keys[, item_sort_key[, for_json[, ignore_nan[, int_as_string_bitcount[, **kw]]]]]]]]]]]]]]]]]])
+.. function:: dumps(obj, skipkeys=False, ensure_ascii=True, \
+                    check_circular=True, allow_nan=True, cls=None, \
+                    indent=None, separators=None, encoding='utf-8', \
+                    default=None, use_decimal=True, \
+                    namedtuple_as_object=True, tuple_as_array=True, \
+                    bigint_as_string=False, sort_keys=False, \
+                    item_sort_key=None, for_json=None, ignore_nan=False, \
+                    int_as_string_bitcount=None, **kw)
 
    Serialize *obj* to a JSON formatted :class:`str`.
 
    If *ensure_ascii* is false, then the return value will be a
    :class:`unicode` instance.  The other arguments have the same meaning as in
    :func:`dump`. Note that the default *ensure_ascii* setting has much
-   better performance.
+   better performance in Python 2.
 
    The other options have the same meaning as in :func:`dump`.
 
 
-.. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, use_decimal[, **kw]]]]]]]]])
+.. function:: load(fp, encoding='utf-8', cls=None, object_hook=None, \
+                   parse_float=None, parse_int=None, \
+                   parse_constant=None, object_pairs_hook=None, \
+                   use_decimal=None, **kw)
 
    Deserialize *fp* (a ``.read()``-supporting file-like object containing a JSON
-   document) to a Python object. :exc:`JSONDecodeError` will be
+   document) to a Python object using this
+   :ref:`conversion table <json-to-py-table>`. :exc:`JSONDecodeError` will be
    raised if the given JSON document is not valid.
 
    If the contents of *fp* are encoded with an ASCII based encoding other than
@@ -311,7 +337,8 @@ Basic Usage
    *object_hook* is an optional function that will be called with the result of
    any object literal decode (a :class:`dict`).  The return value of
    *object_hook* will be used instead of the :class:`dict`.  This feature can be used
-   to implement custom decoders (e.g. JSON-RPC class hinting).
+   to implement custom decoders (e.g. `JSON-RPC <http://www.jsonrpc.org>`_
+   class hinting).
 
    *object_pairs_hook* is an optional function that will be called with the
    result of any object literal decode with an ordered list of pairs.  The
@@ -363,7 +390,10 @@ Basic Usage
         only one JSON document, it is recommended to use :func:`loads`.
 
 
-.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, use_decimal[, **kw]]]]]]]]])
+.. function:: loads(fp, encoding='utf-8', cls=None, object_hook=None, \
+                    parse_float=None, parse_int=None, \
+                    parse_constant=None, object_pairs_hook=None, \
+                    use_decimal=None, **kw)
 
    Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
    document) to a Python object. :exc:`JSONDecodeError` will be
@@ -385,31 +415,35 @@ Basic Usage
 Encoders and decoders
 ---------------------
 
-.. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, strict]]]]]]])
+.. class:: JSONDecoder(encoding='utf-8', object_hook=None, parse_float=None, \
+                       parse_int=None, parse_constant=None, \
+                       object_pairs_hook=None, strict=True)
 
    Simple JSON decoder.
 
    Performs the following translations in decoding by default:
 
-   +---------------+-------------------+
-   | JSON          | Python            |
-   +===============+===================+
-   | object        | dict              |
-   +---------------+-------------------+
-   | array         | list              |
-   +---------------+-------------------+
-   | string        | unicode           |
-   +---------------+-------------------+
-   | number (int)  | int, long         |
-   +---------------+-------------------+
-   | number (real) | float             |
-   +---------------+-------------------+
-   | true          | True              |
-   +---------------+-------------------+
-   | false         | False             |
-   +---------------+-------------------+
-   | null          | None              |
-   +---------------+-------------------+
+   .. _json-to-py-table:
+
+   +---------------+-----------+-----------+
+   | JSON          | Python 2  | Python 3  |
+   +===============+===========+===========+
+   | object        | dict      | dict      |
+   +---------------+-----------+-----------+
+   | array         | list      | list      |
+   +---------------+-----------+-----------+
+   | string        | unicode   | str       |
+   +---------------+-----------+-----------+
+   | number (int)  | int, long | int       |
+   +---------------+-----------+-----------+
+   | number (real) | float     | float     |
+   +---------------+-----------+-----------+
+   | true          | True      | True      |
+   +---------------+-----------+-----------+
+   | false         | False     | False     |
+   +---------------+-----------+-----------+
+   | null          | None      | None      |
+   +---------------+-----------+-----------+
 
    It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
    corresponding ``float`` values, which is outside the JSON spec.
@@ -484,12 +518,21 @@ Encoders and decoders
       :exc:`JSONDecodeError` will be raised if the given JSON
       document is not valid.
 
-.. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, item_sort_key[, for_json[, ignore_nan]]]]]]]]]]]]]]]])
+.. class:: JSONEncoder(skipkeys=False, ensure_ascii=True, \
+                       check_circular=True, allow_nan=True, sort_keys=False, \
+                       indent=None, separators=None, encoding='utf-8', \
+                       default=None, use_decimal=True, \
+                       namedtuple_as_object=True, tuple_as_array=True, \
+                       bigint_as_string=False, item_sort_key=None, \
+                       for_json=True, ignore_nan=False, \
+                       int_as_string_bitcount=None)
 
    Extensible JSON encoder for Python data structures.
 
    Supports the following objects and types by default:
 
+   .. _py-to-json-table:
+
    +-------------------+---------------+
    | Python            | JSON          |
    +===================+===============+
@@ -508,6 +551,9 @@ Encoders and decoders
    | None              | null          |
    +-------------------+---------------+
 
+   It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
+   corresponding ``float`` values, which is outside the JSON spec.
+
    .. versionchanged:: 2.2.0
       Changed *namedtuple* encoding from JSON array to object.
 
@@ -529,7 +575,7 @@ Encoders and decoders
    :class:`str` objects with all incoming unicode characters escaped.  If
    *ensure_ascii* is false, the output will be a unicode object.
 
-   If *check_circular* is false (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
    prevent an infinite recursion (which would cause an :exc:`OverflowError`).
    Otherwise, no such check takes place.
@@ -675,7 +721,16 @@ Encoders and decoders
       Note that :meth:`encode` has much better performance than
       :meth:`iterencode`.
 
-.. class:: JSONEncoderForHTML([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default[, use_decimal[, namedtuple_as_object[, tuple_as_array[, bigint_as_string[, item_sort_key[, for_json[, ignore_nan]]]]]]]]]]]]]]]])
+.. class:: JSONEncoderForHTML(skipkeys=False, ensure_ascii=True, \
+                              check_circular=True, allow_nan=True, \
+                              sort_keys=False, indent=None, separators=None, \
+                              encoding='utf-8', \
+                              default=None, use_decimal=True, \
+                              namedtuple_as_object=True, \
+                              tuple_as_array=True, \
+                              bigint_as_string=False, item_sort_key=None, \
+                              for_json=True, ignore_nan=False, \
+                              int_as_string_bitcount=None)
 
    Subclass of :class:`JSONEncoder` that escapes &, <, and > for embedding in HTML.
 
@@ -685,7 +740,7 @@ Encoders and decoders
 Exceptions
 ----------
 
-.. exception:: JSONDecodeError(msg, doc, pos[, end])
+.. exception:: JSONDecodeError(msg, doc, pos, end=None)
 
     Subclass of :exc:`ValueError` with the following additional attributes:
 
@@ -720,3 +775,125 @@ Exceptions
     .. attribute:: endcolno
 
         The column corresponding to end (may be ``None``)
+
+
+Standard Compliance
+-------------------
+
+The JSON format is specified by :rfc:`4627`.  This section details this
+module's level of compliance with the RFC.  For simplicity,
+:class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and parameters other
+than those explicitly mentioned, are not considered.
+
+This module does not comply with the RFC in a strict fashion, implementing some
+extensions that are valid JavaScript but not valid JSON.  In particular:
+
+- Top-level non-object, non-array values are accepted and output;
+- Infinite and NaN number values are accepted and output;
+- Repeated names within an object are accepted, and only the value of the last
+  name-value pair is used.
+
+Since the RFC permits RFC-compliant parsers to accept input texts that are not
+RFC-compliant, this module's deserializer is technically RFC-compliant under
+default settings.
+
+
+Character Encodings
+^^^^^^^^^^^^^^^^^^^
+
+The RFC recommends that JSON be represented using either UTF-8, UTF-16, or
+UTF-32, with UTF-8 being the default.
+
+As permitted, though not required, by the RFC, this module's serializer sets
+*ensure_ascii=True* by default, thus escaping the output so that the resulting
+strings only contain ASCII characters.
+
+Other than the *ensure_ascii* parameter, this module is defined strictly in
+terms of conversion between Python objects and
+:class:`Unicode strings <str>`, and thus does not otherwise address the issue
+of character encodings.
+
+
+Infinite and NaN Number Values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The RFC does not permit the representation of infinite or NaN number values.
+Despite that, by default, this module accepts and outputs ``Infinity``,
+``-Infinity``, and ``NaN`` as if they were valid JSON number literal values::
+
+   >>> # Neither of these calls raises an exception, but the results are not valid JSON
+   >>> json.dumps(float('-inf'))
+   '-Infinity'
+   >>> json.dumps(float('nan'))
+   'NaN'
+   >>> # Same when deserializing
+   >>> json.loads('-Infinity')
+   -inf
+   >>> json.loads('NaN')
+   nan
+
+In the serializer, the *allow_nan* parameter can be used to alter this
+behavior.  In the deserializer, the *parse_constant* parameter can be used to
+alter this behavior.
+
+
+Repeated Names Within an Object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The RFC specifies that the names within a JSON object should be unique, but
+does not specify how repeated names in JSON objects should be handled.  By
+default, this module does not raise an exception; instead, it ignores all but
+the last name-value pair for a given name::
+
+   >>> weird_json = '{"x": 1, "x": 2, "x": 3}'
+   >>> json.loads(weird_json) == {'x': 3}
+   True
+
+The *object_pairs_hook* parameter can be used to alter this behavior.
+
+.. highlight:: bash
+
+.. _json-commandline:
+
+Command Line Interface
+----------------------
+
+The :mod:`simplejson.tool` module provides a simple command line interface to
+validate and pretty-print JSON.
+
+If the optional :option:`infile` and :option:`outfile` arguments are not
+specified, :attr:`sys.stdin` and :attr:`sys.stdout` will be used respectively::
+
+    $ echo '{"json": "obj"}' | python -m simplejson.tool
+    {
+        "json": "obj"
+    }
+    $ echo '{1.2:3.4}' | python -m simplejson.tool
+    Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
+
+
+Command line options
+^^^^^^^^^^^^^^^^^^^^
+
+.. cmdoption:: infile
+
+   The JSON file to be validated or pretty-printed::
+
+      $ python -m simplejson.tool mp_films.json
+      [
+          {
+              "title": "And Now for Something Completely Different",
+              "year": 1971
+          },
+          {
+              "title": "Monty Python and the Holy Grail",
+              "year": 1975
+          }
+      ]
+
+   If *infile* is not specified, read from :attr:`sys.stdin`.
+
+.. cmdoption:: outfile
+
+   Write the output of the *infile* to the given *outfile*. Otherwise, write it
+   to :attr:`sys.stdout`.