diff --git a/CHANGES.txt b/CHANGES.txt
index efd37532e4e9cade26bd7bca33ecfa2c5a570d83_Q0hBTkdFUy50eHQ=..e22a95b5284eaf4197b33f4394c7a44ca0abe160_Q0hBTkdFUy50eHQ= 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,3 +1,8 @@
+Version 3.6.1 released 2014-08-09
+
+* Documentation updates
+ https://github.com/simplejson/simplejson/issues/102
+
Version 3.6.0 released 2014-07-21
* Automatically strip any UTF-8 BOM from input to more closely
diff --git a/conf.py b/conf.py
index efd37532e4e9cade26bd7bca33ecfa2c5a570d83_Y29uZi5weQ==..e22a95b5284eaf4197b33f4394c7a44ca0abe160_Y29uZi5weQ== 100644
--- a/conf.py
+++ b/conf.py
@@ -44,7 +44,7 @@
# The short X.Y version.
version = '3.6'
# The full version, including alpha/beta/rc tags.
-release = '3.6.0'
+release = '3.6.1'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
diff --git a/index.rst b/index.rst
index efd37532e4e9cade26bd7bca33ecfa2c5a570d83_aW5kZXgucnN0..e22a95b5284eaf4197b33f4394c7a44ca0abe160_aW5kZXgucnN0 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 @@
'[2.0, 1.0]'
-.. highlight:: none
+.. highlight:: bash
Using :mod:`simplejson.tool` from the shell to validate and pretty-print::
@@ -122,10 +124,12 @@
.. 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
-----------
@@ -127,8 +131,15 @@
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
@@ -133,9 +144,9 @@
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`.
@@ -136,9 +147,13 @@
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 @@
``'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 @@
.. 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,10 +293,17 @@
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
@@ -282,11 +304,11 @@
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`.
@@ -289,7 +311,10 @@
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
@@ -294,6 +319,7 @@
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 @@
*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 @@
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,9 +415,11 @@
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:
@@ -389,27 +421,29 @@
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,9 +518,16 @@
: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:
@@ -488,8 +529,10 @@
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 @@
| 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 @@
: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 @@
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 @@
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 @@
.. 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`.
diff --git a/setup.py b/setup.py
index efd37532e4e9cade26bd7bca33ecfa2c5a570d83_c2V0dXAucHk=..e22a95b5284eaf4197b33f4394c7a44ca0abe160_c2V0dXAucHk= 100644
--- a/setup.py
+++ b/setup.py
@@ -11,7 +11,7 @@
DistutilsPlatformError
IS_PYPY = hasattr(sys, 'pypy_translation_info')
-VERSION = '3.6.0'
+VERSION = '3.6.1'
DESCRIPTION = "Simple, fast, extensible JSON encoder/decoder for Python"
with open('README.rst', 'r') as f:
diff --git a/simplejson/__init__.py b/simplejson/__init__.py
index efd37532e4e9cade26bd7bca33ecfa2c5a570d83_c2ltcGxlanNvbi9fX2luaXRfXy5weQ==..e22a95b5284eaf4197b33f4394c7a44ca0abe160_c2ltcGxlanNvbi9fX2luaXRfXy5weQ== 100644
--- a/simplejson/__init__.py
+++ b/simplejson/__init__.py
@@ -98,7 +98,7 @@
Expecting property name: line 1 column 3 (char 2)
"""
from __future__ import absolute_import
-__version__ = '3.6.0'
+__version__ = '3.6.1'
__all__ = [
'dump', 'dumps', 'load', 'loads',
'JSONDecoder', 'JSONDecodeError', 'JSONEncoder',