I've encountered that OverflowError which can happen in __len__ method is still undocumented, though one issue on this problem: http://bugs.python.org/issue12159 ended up with "need to be documented" comment.

Link to documentation: http://docs.python.org/reference/datamodel.html#object.\_\_len__

I think it must be clarified that __len__ return value is constrained to upper boundary (Py_ssize_t c type) when you plan to call it via len() built-in function.

In bpo-12159, Victor correctly labelled this an implementation (IE, CPython) detail (limitation). I don't believe any implementation has to limit the range of len(). So the question is whether we should add a CPython implementation limit note, including the possibility of OverflowError, and if so, to both len() and __len__() entries. I am not sure of the current doc policy.

The second sentence of the len entry is out of date. " The argument may be a sequence (string, tuple or list) or a mapping (dictionary)." Sets and any collections with a size (len method) can also be arguments. I am not sure how to revise that either.

The deficiency noticed by Terry has been at least partially corrected in the len() docs
https://docs.python.org/2/library/functions.html#len
Return the length (the number of items) of an object. The argument may be a sequence (such as a string, bytes, tuple, list, or range) or a collection (such as a dictionary, set, or frozen set).

It doesn't mention the fact that the collection has to implement __len__, but I suppose that might be obvious to experienced Python users (isn't obvious to a beginner like me, though). So perhaps this might be a welcome clarification.

The issue regarding OverflowError raised by Rostyslav still remains unresolved.

bpo-10289 proposes to link from len() to __len__() in the documentation. I think the limitation only needs to be documented for __len__(); there are other ways to invoke it as well.

Has or will builtin classes be modified to follow advice to include a separate __bool__? In 3.6.1,

>>> r = range(19**100)
>>> bool(r)
Traceback (most recent call last):
  File "<pyshell#1>", line 1, in <module>
    bool(r)
OverflowError: Python int too large to convert to C ssize_t

Yes, and the range object already is fixed by bpo-28876.

New changeset 85157cd by Serhiy Storchaka in branch 'master':
bpo-15718: Document the upper bound constrain on the __len__ return value. (bpo-1256)
85157cd

New changeset f2ed285 by Serhiy Storchaka in branch '3.6':
[3.6] bpo-15718: Document the upper bound constrain on the __len__ return value. (GH-1256) (bpo-1259)
f2ed285

New changeset c358536 by Serhiy Storchaka in branch '3.5':
[3.5] bpo-15718: Document the upper bound constrain on the __len__ return value. (GH-1256) (bpo-1260)
c358536

New changeset bfc7dff by Serhiy Storchaka in branch '2.7':
[2.7] bpo-15718: Document the upper bound constrain on the __len__ return value. (GH-1256). (bpo-1261)
bfc7dff