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

Created on 2015-12-15 08:12 by abarnert, last changed 2019-11-17 22:13 by rhettinger. This issue is now closed.

File name Uploaded Description Edit
issue25866.v1.patch alclarks, 2019-11-13 16:42 issue 25866 patch v1
Pull Requests
URL Status Linked Edit
PR 17175 closed dorosch, 2019-11-15 18:27
PR 17177 merged alclarks, 2019-11-15 20:02
PR 17208 merged miss-islington, 2019-11-17 22:00
PR 17209 merged miss-islington, 2019-11-17 22:01
Messages (8)
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.
msg356542 - (view) Author: Alex (alclarks) * Date: 2019-11-13 16:42
Hi, I've taken a look at these suggestions and the documentation and I've posted a patch to get things moving :)

A couple of points about the suggested changes that I haven't included in the patch:

1) I think changing the documentation for __dir__() to say it can return an iterable needs some discussion.

The documentation also says:
"The ``__dir__`` function should accept no arguments, and return a list of strings that represents the names accessible on module. If present, this function overrides the standard :func:`dir` search on a module."
And this should definitely be updated from "list of strings" to either "sequence of strings" or "iterable of strings".

However, I'm not sure about updating docs to include "accidental" functionality - looking at the testing, news, and documentation from commit the intention was to allow __dir__ to return a sequence.

I think updating the docs to say __dir__ should return an iterator would be a separate issue which would also include test enchancements, so I've left that change out of my patch and I've just corrected the line I've quoted above.

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

I couldn't find an instance of this, it's probably been corrected at some point.

Any thoughts on the above, the other suggestions, or the patch?
msg356688 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-11-15 16:36
Can you please turn this into a regular PR?
msg356708 - (view) Author: Alex (alclarks) * Date: 2019-11-15 19:34
dorosch, please note section 3.9 from the developers guide:

"When a patch exists in the issue tracker that should be converted into a GitHub pull request, please first ask the original patch author to prepare their own pull request. If the author does not respond after a week, it is acceptable for another contributor to prepare the pull request based on the existing patch."

It's been two hours, not a week, and I would've liked to raise a pull request for this change.
msg356712 - (view) Author: Alex (alclarks) * Date: 2019-11-15 20:04
I've decided to raise a pull request for the patch, considering it's only been a few hours.
msg356830 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-11-17 22:00
New changeset 4544e78ec4558b75bf95e5b7dfc1b5bbb07ae5f0 by Raymond Hettinger (alclarks) in branch 'master':
bpo-25866: Minor cleanups to "sequence" in docs (GH-17177)
msg356831 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-11-17 22:07
New changeset 72321c7be096434e3343bd5b37a4436aa9eea098 by Raymond Hettinger (Miss Islington (bot)) in branch '3.7':
bpo-25866: Minor cleanups to "sequence" in docs (GH-17177) (GH-17209)
msg356832 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-11-17 22:13
New changeset 20a4f6cde65549fd0252eb8c879963e0e8b40390 by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-25866: Minor cleanups to "sequence" in docs (GH-17177) (GH-17208)
Date User Action Args
2019-11-17 22:13:36rhettingersetmessages: + msg356832
2019-11-17 22:07:51rhettingersetmessages: + msg356831
2019-11-17 22:02:14rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-11-17 22:01:19miss-islingtonsetpull_requests: + pull_request16714
2019-11-17 22:00:55miss-islingtonsetpull_requests: + pull_request16713
2019-11-17 22:00:50rhettingersetmessages: + msg356830
2019-11-15 20:04:17alclarkssetmessages: + msg356712
2019-11-15 20:02:44alclarkssetpull_requests: + pull_request16685
2019-11-15 19:34:10alclarkssetmessages: + msg356708
2019-11-15 18:27:38doroschsetstage: needs patch -> patch review
pull_requests: + pull_request16683
2019-11-15 16:36:10rhettingersetassignee: docs@python -> rhettinger

messages: + msg356688
nosy: + rhettinger
2019-11-13 20:48:49brandtbuchersetnosy: + brandtbucher
2019-11-13 16:42:36alclarkssetfiles: + issue25866.v1.patch

nosy: + alclarks
messages: + msg356542

keywords: + patch
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