classification
Title: Fix some class entries in 'Built-in Functions'
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, miss-islington, ncoghlan, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2018-07-15 03:04 by terry.reedy, last changed 2019-12-30 22:24 by miss-islington.

Pull Requests
URL Status Linked Edit
PR 17761 merged terry.reedy, 2019-12-30 21:45
PR 17762 merged miss-islington, 2019-12-30 22:16
PR 17763 merged miss-islington, 2019-12-30 22:18
Messages (13)
msg321674 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-07-15 03:04
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/83c0ae5de642145ec225d29e7b239aa410229539.)  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.)
msg321732 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-07-16 10:41
> 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.
msg321771 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-07-16 21:31
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.
msg321786 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-07-17 01:54
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.
msg321799 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-07-17 07:16
> 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.
msg321997 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-07-20 10:49
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.
msg321998 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-07-20 10:53
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-hierarchy 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.
msg322030 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-07-20 17:06
I will write a PR only touching the collection class entries.
msg358969 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-12-28 22:10
I closed #39112, about tuple only, as a duplicate of this.
msg359062 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-12-30 22:16
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/ee9ff05ec22ecd47dbffdd361967ccd55963dad2
msg359063 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-12-30 22:17
I started with the agreed-on 'function' => 'class' changes and intend to follow with a PR for text changes.
msg359064 - (view) Author: miss-islington (miss-islington) Date: 2019-12-30 22:22
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/c9c17cc933dcffb9ed7f03e3f791d8cfd7acc54a
msg359065 - (view) Author: miss-islington (miss-islington) Date: 2019-12-30 22:24
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/ec941568bdb25e164a87a23cf1b8870ac047b4e3
History
Date User Action Args
2019-12-30 22:24:30miss-islingtonsetmessages: + msg359065
2019-12-30 22:22:27miss-islingtonsetnosy: + miss-islington
messages: + msg359064
2019-12-30 22:18:24miss-islingtonsetstage: needs patch -> patch review
pull_requests: + pull_request17199
2019-12-30 22:17:43terry.reedysetmessages: + msg359063
stage: patch review -> needs patch
2019-12-30 22:16:58miss-islingtonsetpull_requests: + pull_request17198
2019-12-30 22:16:51terry.reedysetmessages: + msg359062
2019-12-30 21:45:40terry.reedysetstage: needs patch -> patch review
pull_requests: + pull_request17197
2019-12-28 22:10:24terry.reedysetkeywords: + patch

messages: + msg358969
versions: + Python 3.9, - Python 3.6
2019-12-28 22:05:03terry.reedylinkissue39112 superseder
2018-07-20 17:06:14terry.reedysetmessages: + msg322030
2018-07-20 10:53:24ncoghlansetmessages: + msg321998
2018-07-20 10:49:36ncoghlansetmessages: + msg321997
2018-07-17 07:16:14rhettingersetmessages: + msg321799
2018-07-17 01:54:47terry.reedysetmessages: + msg321786
2018-07-16 21:31:25terry.reedysetmessages: + msg321771
2018-07-16 10:41:34rhettingersetmessages: + msg321732
2018-07-15 05:43:22serhiy.storchakasettitle: Fix some class entries entries in 'Built-in Functions' -> Fix some class entries in 'Built-in Functions'
2018-07-15 03:04:38terry.reedycreate