A class may wish to define __len__() despite that it 
doesn't know how many objects iterating an instance 
may produce.  The docs should give advice for this 
case.  They should also explicitly point out that the 
result of __len__() is generally taken to be a _hint_ 
(functions like map(), tuple(), etc., may preallocate 
space based on __len__()'s result, but adjust to the 
actual number of objects produced).

Tail end of a related thread:

<http://mail.zope.org/pipermail/zope3-dev/2005-
September/015599.html>

Logged In: YES 
user_id=80475

FWIW, I had explored this topic at some length with Guido's
input and arrived at somewhat similar guidance. At any given
time, a dynamic object with a __len__() method should report
accurately or not at all (raising a TypeError).  Accurate
means that at that moment, len(d) == len(list(d)).  
Subsequent mutations may affect the length and the __len__()
method is expected to adjust accordingly.  For more notes on
the subject, see the module docstring for
Lib/test/test_iterlen.py

In the face of dynamic inputs, consumer functions like map()
must regard the reported lengths as estimates. However, that
should not lower the standards for objects reporting their
length.  That number should continue to have some meaning
such as the point-in-time invariant described above.

I believe this bug is out of date with the advent of __length_hint__.

It should still be documented that __len__ can be used for this purpose.

The __length_hint__ attribute is mainly for iterators because they are
not allowed to have a __len__ as that would affect their boolean value.

If iterators don't want their boolean value to be messed up, couldn't
they simply use __bool__ for that?

On Tue, Feb 17, 2009 at 1:27 PM, Antoine Pitrou <report@bugs.python.org> wrote:
>
> Antoine Pitrou <pitrou@free.fr> added the comment:
>
> If iterators don't want their boolean value to be messed up, couldn't
> they simply use __bool__ for that?

Since there is no base iterator class, that would complicate the API
and lead to subtle bugs. Personally, I don't think any iterators
should supported len() at all.

Where would you prefer adding this documentation?

For Python 3.4 attached is a patch as suggested by Raymond Hettinger.  My suggestion is to put the patch in Doc/reference/datamodel.rst because if a user searches google.com for __len__ this is the first link in the list.  I think this extra information is a valuable addition to the documentation.

New patch with a better reference to the source for the test case.  This was suggested by PythonMentors list.  I think the patch improves the documentation.  This works on Python 3.4.

Changed the file name so it is clear that this patch goes with version 3.4.

Used the right patch file name this time...

This patch is for Python 2.7.