Documentation for len() fails to mention that it works on sets

[gareth-rees]

BPO	19362
Nosy	@rhettinger, @terryjreedy, @pitrou, @ezio-melotti, @bitdancer, @gareth-rees
Files	len-set.patch len-set.patch len-set.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/terryjreedy'
closed_at = <Date 2014-06-16.07:08:34.439>
created_at = <Date 2013-10-23.12:22:08.684>
labels = ['type-feature', 'docs']
title = 'Documentation for len() fails to mention that it works on sets'
updated_at = <Date 2014-06-16.07:08:34.424>
user = 'https://github.com/gareth-rees'

bugs.python.org fields:

activity = <Date 2014-06-16.07:08:34.424>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2014-06-16.07:08:34.439>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2013-10-23.12:22:08.684>
creator = 'gdr@garethrees.org'
dependencies = []
files = ['32313', '33904', '33916']
hgrepos = []
issue_num = 19362
keywords = ['patch']
message_count = 19.0
messages = ['201019', '201022', '201026', '201027', '201029', '201033', '201034', '201153', '201304', '201461', '203109', '210227', '210267', '210268', '220454', '220486', '220493', '220525', '220701']
nosy_count = 10.0
nosy_names = ['rhettinger', 'terry.reedy', 'pitrou', 'ezio.melotti', 'r.david.murray', 'docs@python', 'BreamoreBoy', 'python-dev', 'gdr@garethrees.org', 'Ramchandra Apte']
pr_nums = []
priority = 'low'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19362'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[gareth-rees]

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

[pitrou]

"Return the number of items of a container" sounds simple and accurate to me.

[gareth-rees]

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.

[bitdancer]

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__).

[pitrou]

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 ;-)

[bitdancer]

I thought we were talking about the reference guide, not the tutorial?

[pitrou]

Well, the patch is for the builtins documentation as well as len.__doc__.

[rhettinger]

"Return the number of items of a container" sounds
simple and accurate to me.

I agree this would be best.

[terryjreedy]

I would prefer 'collections with a known size' but 'collections' should be good enough for the doc string. The manual can follow with examples.

[RamchandraApte]

I also prefer collection.

[ezio-melotti]

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.

[gareth-rees]

Here's a revised patch using Ezio's suggestion ("Return the number of items of a sequence or container").

[terryjreedy]

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.

[gareth-rees]

Here's a revised patch for Terry ("Return the number of items of a sequence or collection.")

[BreamoreBoy]

This is a very simple docs patch so could we have it committed please?

[rhettinger]

I'll apply this (if only to bring this vacuous discussion to a close).

[terryjreedy]

Raymond, I was planning to do this today along with other small patches (already done). Just say so and I will take it.

[rhettinger]

Thanks Terry.

[python-dev]

New changeset 95d487abbfd8 by Terry Jan Reedy in branch '2.7':
Issue bpo-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 bpo-19362: Tweek len() doc and docstring to expand the indicated range of
http://hg.python.org/cpython/rev/8fcbe41e1242