[issue34118] Fix some class entries entries in 'Built-in Functions'
New submission from Terry J. Reedy <tjreedy@udel.edu>: The Library Reference 'Built-in Functions' chapter includes build-in classes because classes are functions in the sense of being callable with arguments and returning objects. A proposal to change the name to Built-in Functions and Classes was rejected (by Raymond, as I remember). I suspect that 'Built-in Callables' has also been proposed. Some of the current entries need one or both of two fixes. 1. Most, but not all, of the classes are tagged with '*class*' before the class name. Classes classmethod and staticmethed are instead tagged with '@' since they are mostly used as decorators, although property is tagged *class*. Classes enumerate, filter, map, memoryview, range, reversed, tuple, and zip are untagged. I think, to be consistent, that they should all get the *class* tag. 2. Nearly all entries fully describe the arguments and return values. The exceptions are those for 6 collection classes. The first 3 have an abbreviated description of the result and a reference for further details on the relationship of input to result. class dict(iterable, **kwarg) Create a new dictionary. The dict object is the dictionary class. See dict and Mapping Types — dict for documentation about this class. For other containers see the built-in list, set, and tuple classes, as well as the collections module. class frozenset([iterable]) Return a new frozenset object, optionally with elements taken from iterable. frozenset is a built-in class. See frozenset and Set Types — set, frozenset for documentation about this class. For other containers see the built-in set, list, tuple, and dict classes, as well as the collections module. class set([iterable]) Return a new set object, optionally with elements taken from iterable. set is a built-in class. See set and Set Types — set, frozenset for documentation about this class. For other containers see the built-in frozenset, list, tuple, and dict classes, as well as the collections module. The next 3 replace 'Return a ___' with 'Rather than being a function'. (This is from Nick's patch 6 years ago. https://github.com/python/cpython/commit/83c0ae5de642145ec225d29e7b239aa4102....) I object to this because it is wrong if one uses the broad definition of function used in the chapter title. It is also wrong in the implication there is anything special about these classes in regard to being functions verses classess. class list([iterable]) Rather than being a function, list is actually a mutable sequence type, as documented in Lists and Sequence Types — list, tuple, range. range(start, stop[, step]) Rather than being a function, range is actually an immutable sequence type, as documented in Ranges and Sequence Types — list, tuple, range. tuple([iterable]) Rather than being a function, tuple is actually an immutable sequence type, as documented in Tuples and Sequence Types — list, tuple, range. I propose that the 2nd 3 follow the model of the 1st 3, except that the final line should be: "For other collections see the built-in range, tuple, list, frozenset, set, and dict classes, as well as the collections module." (with 1 of the 6 omitted as appropriate). (Range represents a collection, but is not a container in the sense that the others are.) ---------- assignee: docs@python components: Documentation messages: 321674 nosy: docs@python, ncoghlan, rhettinger, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Fix some class entries entries in 'Built-in Functions' type: behavior versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- title: Fix some class entries entries in 'Built-in Functions' -> Fix some class entries in 'Built-in Functions' _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment:
I propose that the 2nd 3 follow the model of the 1st 3,
This makes sense and would read a little better.
Classes enumerate, filter, map, memoryview, range, reversed, tuple, and zip are untagged. I think, to be consistent, that they should all get the *class* tag.
To me, that makes the most sense for: memoryview, range and tuple. The rest are used like functions. Even though they are technically classes, it is confusing to think of them as such (we don't call map() to get an instance of a mapobject and do a dir() to what interesting methods it may have). Tools like map() and filter() actually were functions at one time. The substantive change was that they were made to be lazy. The implementation detail was that they were implemented as classes -- they could have been generators instead. Accordingly, I think tagging these as classes is pedantically correct but actually makes the docs a little less usable. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: I was forgetting that this is a Python, not CPython doc. So I agree to not tag the iterator classes as such. For all I know, PyPy might use (compiled?) generator functions. And if we were to allow use of Cython, say, for CPython, we might try that. How about a note under the index table: Functions that must be classes are tagged *class*. The iterator functions enumerate, filter, map, reversed, and zip are classes in CPython, but they are not tagged because they could be implemented as generator functions. Or we could add an *iterator* tag. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: SO user abarnert, who I presume is bpo abarnert (Andrew Barnert) claims that "Create a new dictionary. The dict object is the dictionary class." sounds a bit like dict returns the dictionary class. It is different from "Return a new set object, ... . set is a built-in class." I like the latter better and will use it as the pattern. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment:
How about a note under the index table:
Functions that must be classes are tagged *class*. < The iterator functions enumerate, filter, map, reversed, and zip are classes in CPython, but they are not tagged because they could be implemented as generator functions.
This doesn't seem like it adds any value at all and I don't see what problem is being solved. Adding a cryptic note at the top doesn't make the docs any more readable. I recommend leaving the iterator factories as-is. AFAICT, the current docs are not a source of confusion and the text descriptions suffice to explain what is being done. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Marking memoryview, range, and tuple explicitly as classes, and making the initial phrasing in the docs consistent across all the builtin collection/container types sounds like a good improvement to me. I agree with Raymond that we should leave whether or not enumerate, filter, map, reversed, and zip support inheritance, isinstance() and issubclass() ambiguous for now (at least within the scope of this issue). That's the main observable difference between implementations that expose a class definition directly, and those that wrap them in a factory function. While technically that ambiguity is a portability problem across implementations, in practice folks that want to emulate one of these behaviours are far more likely to write their own generator function or iterator class from scratch than they are to try to inherit from one of these. If we were going to note anything at all for these, it would be to put a "CPython implementation detail" note in each one about the fact that you can subclass them being a CPython implementation detail, but I'd only suggest adding that if we ever get complaints about this hindering portability in practice, rather than our pointing it ourselves as a potential point of inconsistency. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Note that an alternative option for clarifying the status of the "Are they types or factory functions?" builtins would be for someone to review https://docs.python.org/3/reference/datamodel.html#the-standard-type-hierarc... and compare it to the builtins documentation in the library reference. The language reference is often a better home for clarifying the Python vs CPython behavioural oundary, since it avoids cluttering up the main docs with info that's going to be irrelevant to the vast majority of users. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: I will write a PR only touching the collection class entries. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: I closed #39112, about tuple only, as a duplicate of this. ---------- keywords: +patch versions: +Python 3.9 -Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Change by Terry J. Reedy <tjreedy@udel.edu>: ---------- pull_requests: +17197 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/17761 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: New changeset ee9ff05ec22ecd47dbffdd361967ccd55963dad2 by Terry Jan Reedy in branch 'master': bpo-34118: memoryview, range, and tuple are classes (GH-17761) https://github.com/python/cpython/commit/ee9ff05ec22ecd47dbffdd361967ccd5596... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +17198 pull_request: https://github.com/python/cpython/pull/17762 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: I started with the agreed-on 'function' => 'class' changes and intend to follow with a PR for text changes. ---------- stage: patch review -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +17199 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/17763 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset c9c17cc933dcffb9ed7f03e3f791d8cfd7acc54a by Miss Islington (bot) in branch '3.7': bpo-34118: memoryview, range, and tuple are classes (GH-17761) https://github.com/python/cpython/commit/c9c17cc933dcffb9ed7f03e3f791d8cfd7a... ---------- nosy: +miss-islington _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset ec941568bdb25e164a87a23cf1b8870ac047b4e3 by Miss Islington (bot) in branch '3.8': bpo-34118: memoryview, range, and tuple are classes (GH-17761) https://github.com/python/cpython/commit/ec941568bdb25e164a87a23cf1b8870ac04... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________
participants (5)
-
miss-islington -
Nick Coghlan
-
Raymond Hettinger
-
Serhiy Storchaka
-
Terry J. Reedy