This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Give __len__() advice for "don't know"
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Todd.Rovito, benjamin.peterson, docs@python, georg.brandl, pitrou, rhettinger, tim.peters
Priority: normal Keywords: easy, needs review, patch

Created on 2005-09-06 15:37 by tim.peters, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
DataModel__len__3point4.patch Todd.Rovito, 2012-10-20 04:58 review
DataModel__len__2point7.patch Todd.Rovito, 2012-10-20 04:59 review
Messages (13)
msg61205 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2005-09-06 15:37
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>
msg61206 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2005-09-07 05:24
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.
msg82294 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2009-02-17 02:13
I believe this bug is out of date with the advent of __length_hint__.
msg82296 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2009-02-17 02:30
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.
msg82359 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2009-02-17 19:27
If iterators don't want their boolean value to be messed up, couldn't
they simply use __bool__ for that?
msg82361 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2009-02-17 20:13
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.
msg82399 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2009-02-18 00:35
Where would you prefer adding this documentation?
msg173015 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-10-16 05:00
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.
msg173220 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-10-18 00:20
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.
msg173366 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-10-20 04:57
Changed the file name so it is clear that this patch goes with version 3.4.
msg173367 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-10-20 04:58
Used the right patch file name this time...
msg173368 - (view) Author: Todd Rovito (Todd.Rovito) * Date: 2012-10-20 04:59
This patch is for Python 2.7.
msg388694 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-03-14 23:02
Looking at the patch years later, I'm thinking that this isn't needed or helpful.  Not needed because users haven't reported any misunderstandings in the interim.  Not helpful because the text looks forbidding and impenetrable, too much for a simple method like __len__().

I recommend closing this as out-of-date.  As Benjamin noted, the advent of __length_hint__ has mostly made this issue go away.
History
Date User Action Args
2022-04-11 14:56:12adminsetgithub: 42346
2022-01-09 23:10:15iritkatrielsetstatus: open -> closed
resolution: out of date
stage: patch review -> resolved
2021-03-14 23:02:32rhettingersetmessages: + msg388694
2021-03-14 19:21:59iritkatrielsetkeywords: + easy
versions: + Python 3.8, Python 3.9, Python 3.10, - Python 2.7, Python 3.5, Python 3.6, Python 3.7
2017-03-07 19:08:44serhiy.storchakasetkeywords: + needs review
status: pending -> open
stage: patch review
versions: + Python 3.5, Python 3.6, Python 3.7, - Python 3.4
2016-04-23 20:00:25serhiy.storchakasetstatus: open -> pending
2012-10-20 04:59:18Todd.Rovitosetfiles: + DataModel__len__2point7.patch

messages: + msg173368
versions: + Python 2.7
2012-10-20 04:58:17Todd.Rovitosetfiles: + DataModel__len__3point4.patch

messages: + msg173367
2012-10-20 04:57:52Todd.Rovitosetfiles: - RightClickContextMenuUpdatedFor3point4.patch
2012-10-20 04:57:33Todd.Rovitosetfiles: + RightClickContextMenuUpdatedFor3point4.patch

messages: + msg173366
2012-10-20 04:56:37Todd.Rovitosetfiles: - DataModel__len__.patch
2012-10-18 00:20:58Todd.Rovitosetfiles: + DataModel__len__.patch

messages: + msg173220
2012-10-17 22:45:24Todd.Rovitosetfiles: - DataModel__len__.patch
2012-10-16 05:00:12Todd.Rovitosetfiles: + DataModel__len__.patch
versions: + Python 3.4
nosy: + Todd.Rovito

messages: + msg173015

keywords: + patch
2010-08-21 19:06:04BreamoreBoysetassignee: georg.brandl -> docs@python

nosy: + docs@python
2009-02-18 00:35:08georg.brandlsetmessages: + msg82399
2009-02-17 20:13:28benjamin.petersonsetmessages: + msg82361
2009-02-17 19:27:13pitrousetnosy: + pitrou
messages: + msg82359
2009-02-17 02:30:42rhettingersetstatus: closed -> open
assignee: georg.brandl
resolution: out of date -> (no value)
messages: + msg82296
nosy: + georg.brandl
2009-02-17 02:13:33benjamin.petersonsetstatus: open -> closed
nosy: + benjamin.peterson
resolution: out of date
messages: + msg82294
2005-09-06 15:37:50tim.peterscreate