classification
Title: Documentation for len() fails to mention that it works on sets
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: BreamoreBoy, Ramchandra Apte, docs@python, ezio.melotti, gdr@garethrees.org, pitrou, python-dev, r.david.murray, rhettinger, terry.reedy
Priority: low Keywords: patch

Created on 2013-10-23 12:22 by gdr@garethrees.org, last changed 2014-06-16 07:08 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
len-set.patch gdr@garethrees.org, 2013-10-23 12:22 review
len-set.patch gdr@garethrees.org, 2014-02-04 13:25 review
len-set.patch gdr@garethrees.org, 2014-02-04 21:39 review
Messages (19)
msg201019 - (view) Author: Gareth Rees (gdr@garethrees.org) * (Python triager) Date: 2013-10-23 12:22
The help text for the len() built-in function says:

    Return the number of items of a sequence or mapping.

This omits to mention that len() works on sets too. I suggest this be changed to:

    Return the number of items of a sequence, mapping, or set.

Similarly, the documentation for len() says:

    The argument may be a sequence (string, tuple or list) or a mapping (dictionary).

I suggest this be changed to

    The argument may be a sequence (string, tuple or list), a mapping (dictionary), or a set.

(Of course, strictly speaking, len() accepts any object with a __len__ method, but sequences, mappings and sets are the ones that are built-in to the Python core, and so these are the ones it is important to mention in the help and the documentation.)
msg201022 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-10-23 13:38
"Return the number of items of a container" sounds simple and accurate to me.
msg201026 - (view) Author: Gareth Rees (gdr@garethrees.org) * (Python triager) Date: 2013-10-23 13:59
I considered suggesting "container", but the problem is that "container" is used elsewhere to mean "object supporting the 'in' operator" (in particular, collections.abc.Container has a __contains__ method but no __len__ method).

The abstract base class for "object with a length" is collections.abc.Sized, but I don't think using the term "sized" would be clear to users.
msg201027 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-10-23 14:05
Perhaps it would be better to say that "the argument may be any object with a __len__, such as the commonly used Python sequence and container types str, bytes, tuple, list, dict, and set".  After all, there are other built in types it works on as well: bytearray, frozenset, memoryview.

For the other, "the number of items in a sequence or container type" would mostly cover it, but at the cost of being a bit obscure.  Perhaps that's OK for the help text, though, since it is supposed to be a reminder, not the full documentation.  Another even more obscure alternative would be "the number of items in a Sized object", which would also be more accurate (since an object with a __len__ doesn't *have* to conform fully to the sequence or container ABCs...nor does a container *have* to implement __len__).
msg201029 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-10-23 14:09
> Perhaps it would be better to say that "the argument may be any
> object with a __len__, such as the commonly used Python sequence and
> container types str, bytes, tuple, list, dict, and set".  After all,
> there are other built in types it works on as well: bytearray,
> frozenset, memoryview.

__len__ is an implementation detail for experts. Beginners don't need
to know about __len__ in order to understand querying the length of
a container. Similarly, they don't need to know about ABCs to understand,
intuitively, what a container is ;-)
msg201033 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2013-10-23 14:37
I thought we were talking about the reference guide, not the tutorial?
msg201034 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-10-23 14:40
Well, the patch is for the builtins documentation as well as len.__doc__.
msg201153 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-10-24 16:29
> "Return the number of items of a container" sounds 
> simple and accurate to me.

I agree this would be best.
msg201304 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-10-26 00:14
I would prefer 'collections with a known size' but 'collections' should be good enough for the doc string. The manual can follow with examples.
msg201461 - (view) Author: Ramchandra Apte (Ramchandra Apte) * Date: 2013-10-27 14:28
I also prefer collection.
msg203109 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-11-17 00:07
I think it's better to do:
-Return the number of items of a sequence or mapping.
+Return the number of items of a sequence or container.

While it's true that most sequences are clearly containers (e.g. lists), the same is not so evident for other types like bytes or strings.
I'm also starting from the assumption that people reading the docstring of len just started with Python or programming in general, so it's more important to keep it simple and understandable rather than being 100% accurate.
msg210227 - (view) Author: Gareth Rees (gdr@garethrees.org) * (Python triager) Date: 2014-02-04 13:25
Here's a revised patch using Ezio's suggestion ("Return the number of items of a sequence or container").
msg210267 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-02-04 21:26
My objection to 'container' is that it is inaccurate and leads to inaccurate mental models. A set is like a non-exclusive club or association, defined either by rule or roster, not like a box or room, which contain exclusively. I am 'in' the set Python Developers, but am not contained by it.

Some decades ago I was hindered by the notion that a set is like a box (container). A web search indicates that the top hits all have variations on 'well-defined, unordered *collection* of objects, considered as an object in itself' -- wikipedia, mathisfun, wikia, brittanica, math.ku.edu.  We do a disservice to call a set a container.

It is true that many Python collections are implemented by containing references to objects (a roster) but ranges are not (a parameterized rule). The *collections* module is properly named.
msg210268 - (view) Author: Gareth Rees (gdr@garethrees.org) * (Python triager) Date: 2014-02-04 21:39
Here's a revised patch for Terry ("Return the number of items of a sequence or collection.")
msg220454 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-06-13 15:30
This is a very simple docs patch so could we have it committed please?
msg220486 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-06-13 19:32
I'll apply this (if only to bring this vacuous discussion to a close).
msg220493 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-06-13 20:17
Raymond, I was planning to do this today along with other small patches (already done). Just say so and I will take it.
msg220525 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-06-14 02:19
Thanks Terry.
msg220701 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-06-16 07:06
New changeset 95d487abbfd8 by Terry Jan Reedy in branch '2.7':
Issue #19362: Tweek len() doc and docstring to expand the indicated range of
http://hg.python.org/cpython/rev/95d487abbfd8

New changeset 8fcbe41e1242 by Terry Jan Reedy in branch '3.4':
Issue #19362: Tweek len() doc and docstring to expand the indicated range of
http://hg.python.org/cpython/rev/8fcbe41e1242
History
Date User Action Args
2014-06-16 07:08:34terry.reedysetstatus: open -> closed
stage: resolved
resolution: fixed
versions: + Python 2.7, Python 3.5
2014-06-16 07:06:28python-devsetnosy: + python-dev
messages: + msg220701
2014-06-14 02:19:50rhettingersetassignee: rhettinger -> terry.reedy
messages: + msg220525
2014-06-13 20:17:38terry.reedysetmessages: + msg220493
2014-06-13 19:32:37rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger
messages: + msg220486
2014-06-13 15:30:19BreamoreBoysetnosy: + BreamoreBoy
messages: + msg220454
2014-02-04 21:39:38gdr@garethrees.orgsetfiles: + len-set.patch

messages: + msg210268
2014-02-04 21:26:05terry.reedysetmessages: + msg210267
2014-02-04 13:31:46gdr@garethrees.orgsetversions: + Python 3.4
title: Documentation for len() fails to mention that it works on sets -> Documentation for len() fails to mention that it works on sets
2014-02-04 13:25:47gdr@garethrees.orgsetfiles: + len-set.patch

messages: + msg210227
2013-11-17 00:07:34ezio.melottisetmessages: + msg203109
2013-10-27 14:28:10Ramchandra Aptesetnosy: + Ramchandra Apte
messages: + msg201461
2013-10-26 00:14:45terry.reedysetnosy: + terry.reedy
messages: + msg201304
2013-10-24 16:29:45rhettingersetmessages: + msg201153
2013-10-23 14:40:46pitrousetmessages: + msg201034
2013-10-23 14:37:15r.david.murraysetmessages: + msg201033
2013-10-23 14:09:37pitrousetmessages: + msg201029
title: Documentation for len() fails to mention that it works on sets -> Documentation for len() fails to mention that it works on sets
2013-10-23 14:05:54r.david.murraysetnosy: + r.david.murray
messages: + msg201027
2013-10-23 13:59:50gdr@garethrees.orgsetmessages: + msg201026
2013-10-23 13:38:02pitrousetnosy: + rhettinger, pitrou
messages: + msg201022
2013-10-23 12:31:37ezio.melottisetnosy: + ezio.melotti
2013-10-23 12:22:08gdr@garethrees.orgcreate