v3.1.3 - docs update to discourage subclassing

6 files changed, 57 insertions, 19 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 5d00207..d1db012 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,3 +1,9 @@
+Version 3.1.3 released XXXX-XX-XX
+
+* Updated documentation to discourage subclassing whenever possible.
+   default, object_hook, and object_pairs_hook provide almost all of
+   the functionality of subclassing.
+
 Version 3.1.2 released 2013-03-20
 
 * Updated documentation to reflect separators behavior when indent is
diff --git a/README.rst b/README.rst
index 5fdaf21..f2547ac 100644
--- a/README.rst
+++ b/README.rst
@@ -10,10 +10,14 @@ simplejson is the externally maintained development version of the
 json library included with Python 2.6 and Python 3.0, but maintains
 backwards compatibility with Python 2.5.
 
-The encoder may be subclassed to provide serialization in any kind of
+The encoder can be specialized to provide serialization in any kind of
 situation, without any special support by the objects to be serialized
-(somewhat like pickle).
+(somewhat like pickle). This is best done with the ``default`` kwarg
+to dumps.
 
 The decoder can handle incoming JSON strings of any specified encoding
-(UTF-8 by default).
+(UTF-8 by default). It can also be specialized to post-process JSON
+objects with the ``object_hook`` or ``object_pairs_hook`` kwargs. This
+is particularly useful for implementing protocols such as JSON-RPC
+that have a richer type system than JSON itself.
 
diff --git a/conf.py b/conf.py
index b8e92b2..9815ee7 100644
--- a/conf.py
+++ b/conf.py
@@ -44,7 +44,7 @@ copyright = '2013, Bob Ippolito'
 # The short X.Y version.
 version = '3.1'
 # The full version, including alpha/beta/rc tags.
-release = '3.1.2'
+release = '3.1.3'
 
 # 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 f682fd6..4dd8a58 100644
--- a/index.rst
+++ b/index.rst
@@ -184,6 +184,11 @@ Basic Usage
    :meth:`default` method to serialize additional types), specify it with the
    *cls* kwarg.
 
+   .. note::
+
+        Subclassing is not recommended. Use the *default* kwarg
+        instead. This is faster and more portable.
+
    If *use_decimal* is true (default: ``True``) then :class:`decimal.Decimal`
    will be natively serialized to JSON with full precision.
 
@@ -314,7 +319,12 @@ Basic Usage
 
    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.
+   class. You probably shouldn't do this.
+
+    .. note::
+
+        Subclassing is not recommended. You should use *object_hook* or
+        *object_pairs_hook*. This is faster and more portable than subclassing.
 
     .. note::
 
@@ -478,6 +488,11 @@ Encoders and decoders
    for ``o`` if possible, otherwise it should call the superclass implementation
    (to raise :exc:`TypeError`).
 
+    .. note::
+
+        Subclassing is not recommended. You should use the *default*
+        kwarg. This is faster and more portable than subclassing.
+
    If *skipkeys* is false (the default), then it is a :exc:`TypeError` to
    attempt encoding of keys that are not str, int, long, float or None.  If
    *skipkeys* is true, such items are simply skipped.
@@ -591,6 +606,13 @@ Encoders and decoders
                 return list(iterable)
             return JSONEncoder.default(self, o)
 
+    .. note::
+
+        Subclassing is not recommended. You should implement this
+        as a function and pass it to the *default* kwarg of :func:`dumps`.
+        This is faster and more portable than subclassing. The
+        semantics are the same, but without the self argument or the
+        call to the super implementation.
 
    .. method:: encode(o)
 
diff --git a/setup.py b/setup.py
index d0909ea..d85eec9 100644
--- a/setup.py
+++ b/setup.py
@@ -8,7 +8,7 @@ from distutils.errors import CCompilerError, DistutilsExecError, \
     DistutilsPlatformError
 
 IS_PYPY = hasattr(sys, 'pypy_translation_info')
-VERSION = '3.1.2'
+VERSION = '3.1.3'
 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 d3435f2..39f9fbf 100644
--- a/simplejson/__init__.py
+++ b/simplejson/__init__.py
@@ -98,7 +98,7 @@ Using simplejson.tool from the shell to validate and pretty-print::
     Expecting property name: line 1 column 3 (char 2)
 """
 from __future__ import absolute_import
-__version__ = '3.1.2'
+__version__ = '3.1.3'
 __all__ = [
     'dump', 'dumps', 'load', 'loads',
     'JSONDecoder', 'JSONDecodeError', 'JSONEncoder',
@@ -179,10 +179,11 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
     versions of simplejson earlier than 2.1.0, an integer is also accepted
     and is converted to a string with that many spaces.
 
-    If specified, ``separators`` should be an ``(item_separator, key_separator)``
-    tuple.  The default is ``(', ', ': ')`` if *indent* is ``None`` and
-    ``(',', ': ')`` otherwise.  To get the most compact JSON representation,
-    you should specify ``(',', ':')`` to eliminate whitespace.
+    If specified, ``separators`` should be an
+    ``(item_separator, key_separator)`` tuple.  The default is ``(', ', ': ')``
+    if *indent* is ``None`` and ``(',', ': ')`` otherwise.  To get the most
+    compact JSON representation, you should specify ``(',', ':')`` to eliminate
+    whitespace.
 
     ``encoding`` is the character encoding for str instances, default is UTF-8.
 
@@ -215,7 +216,8 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
 
     To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
     ``.default()`` method to serialize additional types), specify it with
-    the ``cls`` kwarg.
+    the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
+    whenever possible.
 
     """
     # cached encoder
@@ -277,10 +279,11 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
     versions of simplejson earlier than 2.1.0, an integer is also accepted
     and is converted to a string with that many spaces.
 
-    If specified, ``separators`` should be an ``(item_separator, key_separator)``
-    tuple.  The default is ``(', ', ': ')`` if *indent* is ``None`` and
-    ``(',', ': ')`` otherwise.  To get the most compact JSON representation,
-    you should specify ``(',', ':')`` to eliminate whitespace.
+    If specified, ``separators`` should be an
+    ``(item_separator, key_separator)`` tuple.  The default is ``(', ', ': ')``
+    if *indent* is ``None`` and ``(',', ': ')`` otherwise.  To get the most
+    compact JSON representation, you should specify ``(',', ':')`` to eliminate
+    whitespace.
 
     ``encoding`` is the character encoding for str instances, default is UTF-8.
 
@@ -311,7 +314,8 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
 
     To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
     ``.default()`` method to serialize additional types), specify it with
-    the ``cls`` kwarg.
+    the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
+    whenever possible.
 
     """
     # cached encoder
@@ -389,7 +393,8 @@ def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
     parse_float=decimal.Decimal for parity with ``dump``.
 
     To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
-    kwarg.
+    kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
+    of subclassing whenever possible.
 
     """
     return loads(fp.read(),
@@ -445,7 +450,8 @@ def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
     parse_float=decimal.Decimal for parity with ``dump``.
 
     To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
-    kwarg.
+    kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
+    of subclassing whenever possible.
 
     """
     if (cls is None and encoding is None and object_hook is None and