# HG changeset patch
# User Bob Ippolito <bob@redivi.com>
# Date 1365189833 25200
# Fri Apr 05 12:23:53 2013 -0700
# Node ID 62865d5e55db0d59405db3c3297c6bc9a2dcdb13
# Parent d4c5fd9d915190302417a46b6f3380c3b5c3f4d3
v3.1.3 - docs update to discourage subclassing
diff --git a/CHANGES.txt b/CHANGES.txt
--- 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
--- a/README.rst
+++ b/README.rst
@@ -10,10 +10,14 @@
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
--- a/conf.py
+++ b/conf.py
@@ -44,7 +44,7 @@
# 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
--- a/index.rst
+++ b/index.rst
@@ -184,6 +184,11 @@
: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 @@
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 @@
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 @@
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
--- a/setup.py
+++ b/setup.py
@@ -8,7 +8,7 @@
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
--- 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.1.2'
+__version__ = '3.1.3'
__all__ = [
'dump', 'dumps', 'load', 'loads',
'JSONDecoder', 'JSONDecodeError', 'JSONEncoder',
@@ -179,10 +179,11 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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