Title: Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence".
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: abarnert, docs@python, ezio.melotti
Priority: normal Keywords: easy

Created on 2015-12-15 08:12 by abarnert, last changed 2016-01-04 03:56 by ezio.melotti.

Messages (1)
msg256445 - (view) Author: Andrew Barnert (abarnert) * Date: 2015-12-15 08:12
None of the below are very serious or likely to mislead anyone using or implementing Python, but...


3.3.2. Customizing attribute access

The docs for `__dir__` say:

> A sequence must be returned. dir() converts the returned sequence to a list and sorts it.

At least in CPython and PyPy, this isn't enforced; any iterable can be returned (and it's then converted to a list and sorted). You can even make `__dir__` a generator function. (I've never seen that in the wild--but I have seen code that returns a `map` iterator.)

I think it would be better to say "An iterable must be returned. dir() converts the returned iterable to a list and sorts it."

--- __slots__

> This class variable can be assigned a string, iterable, or sequence of strings...

While it's true that you can assign any iterable, it's at best misleading to assign an iterator. For example, if you use `__slots__ = iter('abc')`, you will get a class with descriptors named `a`, `b`, and `c`, but with an empty iterator in `__slots__`. There's probably no reason to actually outlaw that, but it might be worth noting in along with the other weird possibilities like assigning a mapping.


3.3.6. Emulating container types

The docs still say that the ABCs are in `collections` rather than ``.

> ... for mappings, __iter__() should be the same as keys()

No; `__iter__()` should be an iterator over the keys; `keys()` _can_ be an iterator, but generally should be a view instead.

> The membership test operators (in and not in) are normally implemented as an iteration through a sequence. However, container objects can supply the following special method with a more efficient implementation, which also does not require the object be a sequence.

I don't think this should say "through a sequence". They're implemented as iteration through whatever the container is, whether it's a sequence, a set, a linked list, or anything else. The documentation on `__contains__` immediately below clarifies this, but it's probably better to be clear from the start.
Date User Action Args
2016-01-04 03:56:32ezio.melottisetkeywords: + easy
nosy: + ezio.melotti
stage: needs patch

versions: + Python 2.7, Python 3.5, Python 3.6
2015-12-15 08:12:47abarnertcreate