homepage

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 #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.

Issue 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 issue28876.

New changeset 85157cd89a6edac347a5b6871fcf20c500c6fbbf by Serhiy Storchaka in branch 'master':
bpo-15718: Document the upper bound constrain on the __len__ return value. (#1256)
https://github.com/python/cpython/commit/85157cd89a6edac347a5b6871fcf20c500c6fbbf

New changeset f2ed2858eea7569c8915b3611ca5ec92ae10b17f by Serhiy Storchaka in branch '3.6':
[3.6] bpo-15718: Document the upper bound constrain on the __len__ return value. (GH-1256) (#1259)
https://github.com/python/cpython/commit/f2ed2858eea7569c8915b3611ca5ec92ae10b17f

New changeset c358536fd5e40e8f29ee4f086588a82fccb25a09 by Serhiy Storchaka in branch '3.5':
[3.5] bpo-15718: Document the upper bound constrain on the __len__ return value. (GH-1256) (#1260)
https://github.com/python/cpython/commit/c358536fd5e40e8f29ee4f086588a82fccb25a09

New changeset bfc7dff63b9b30371e3423a5c35ccda2f3b52218 by Serhiy Storchaka in branch '2.7':
[2.7] bpo-15718: Document the upper bound constrain on the __len__ return value. (GH-1256). (#1261)
https://github.com/python/cpython/commit/bfc7dff63b9b30371e3423a5c35ccda2f3b52218