[issue25866] Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence".
New submission from Andrew Barnert: 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." --- 3.3.2.3. __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 3.3.2.3.1 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 `collections.abc`.
... 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. ---------- assignee: docs@python components: Documentation messages: 256445 nosy: abarnert, docs@python priority: normal severity: normal status: open title: Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence". type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25866> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- keywords: +easy nosy: +ezio.melotti stage: -> needs patch versions: +Python 2.7, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25866> _______________________________________
Alex <alexpclarkson@gmail.com> added the comment: 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 https://github.com/python/cpython/commit/3bbb72265411585e64a5d2ccb5ba51763f2... 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 `collections.abc`. 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? ---------- keywords: +patch nosy: +alclarks Added file: https://bugs.python.org/file48713/issue25866.v1.patch _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Change by Brandt Bucher <brandtbucher@gmail.com>: ---------- nosy: +brandtbucher _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Can you please turn this into a regular PR? ---------- assignee: docs@python -> rhettinger nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Change by Andrei Daraschenka <dorosch.github.io@yandex.ru>: ---------- pull_requests: +16683 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/17175 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Alex <alexpclarkson@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Change by Alex <alexpclarkson@gmail.com>: ---------- pull_requests: +16685 pull_request: https://github.com/python/cpython/pull/17177 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Alex <alexpclarkson@gmail.com> added the comment: I've decided to raise a pull request for the patch, considering it's only been a few hours. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: New changeset 4544e78ec4558b75bf95e5b7dfc1b5bbb07ae5f0 by Raymond Hettinger (alclarks) in branch 'master': bpo-25866: Minor cleanups to "sequence" in docs (GH-17177) https://github.com/python/cpython/commit/4544e78ec4558b75bf95e5b7dfc1b5bbb07... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +16713 pull_request: https://github.com/python/cpython/pull/17208 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +16714 pull_request: https://github.com/python/cpython/pull/17209 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: 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) https://github.com/python/cpython/commit/72321c7be096434e3343bd5b37a4436aa9e... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: 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) https://github.com/python/cpython/commit/20a4f6cde65549fd0252eb8c879963e0e8b... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25866> _______________________________________
participants (7)
-
Alex -
Andrei Daraschenka
-
Andrew Barnert
-
Brandt Bucher
-
Ezio Melotti
-
miss-islington
-
Raymond Hettinger