| msg201019 - (view) |
Author: Gareth Rees (gdr@garethrees.org) *  |
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) *  |
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) * |
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) * |
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) * |
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) * |
Date: 2013-10-23 14:37 |
| I thought we were talking about the reference guide, not the tutorial? |
|
|
| msg201034 - (view) |
Author: Antoine Pitrou (pitrou) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
Date: 2014-06-14 02:19 |
| Thanks Terry. |
|
|
| msg220701 - (view) |
Author: Roundup Robot (python-dev) |
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 |
|
|