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.