homepage

The JSONEncoder documentation says we can implement our own encoder as:
 >>> class ComplexEncoder(json.JSONEncoder):
 ... def default(self, obj):
 ... if isinstance(obj, complex):
 ... return [obj.real, obj.imag]
 ... return json.JSONEncoder.default(self, obj)
Later on, we give the following example of how to implement the default method in a subclass of json.JSONEncoder:
 def default(self, o):
 try:
 iterable = iter(o)
 except TypeError:
 pass
 else:
 return list(iterable)
 return JSONEncoder.default(self, o)
These are both incorrect, as a quick reading of the source will reveal. JSONEncoder.default() throws for all input values. We should s/JSONEncoder.default/JSONEncoder.encode/ here, I think.

The implementation clearly says that default method should return a serializable object or calls the base implementation to raise TypeError. So I don't think any of the examples is a bug.

Ah, I see. The examples do what you think they should do, but not for the reason you think they should do it -- the JSON encoding logic calls the encoder's encode() method before calling its default() method.
I still think the examples could be improved, perhaps by adding a comment to the effect of 
 # Raises a TypeError.
before the call to JSONEncoder.default(). Explicit is better than implicit, after all. :)
Thanks for looking at this.

Ok, I will submit a patch.

Patch to update docstring and documentation with explicit saying that calling JSONEncoder.default raises a TypeError

The previous patch should be back committed to all 3.x and 2.7 branch.

New changeset 5d56e1214e95 by R David Murray in branch '3.2':
#16057: Clarify why the base method default is called in custom encoders.
http://hg.python.org/cpython/rev/5d56e1214e95
New changeset 5f76e7db97ac by R David Murray in branch '3.3':
Merge #16057: Clarify why the base method default is called in custom encoders.
http://hg.python.org/cpython/rev/5f76e7db97ac
New changeset 406c6fd7e753 by R David Murray in branch 'default':
Merge #16057: Clarify why the base method default is called in custom encoders.
http://hg.python.org/cpython/rev/406c6fd7e753
New changeset ef8ea052bcc4 by R David Murray in branch '2.7':
#16057: Clarify why the base method default is called in custom encoders.
http://hg.python.org/cpython/rev/ef8ea052bcc4 

Thanks Kushal.