Fix some class entries in 'Built-in Functions'

[terryjreedy]

BPO	34118
Nosy	@rhettinger, @terryjreedy, @ncoghlan, @miss-islington
PRs	bpo-34118: memoryview, range, and tuple are classes  #17761 [3.7] bpo-34118: memoryview, range, and tuple are classes (GH-17761) #17762 [3.8] bpo-34118: memoryview, range, and tuple are classes (GH-17761) #17763

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2018-07-15.03:04:38.552>
labels = ['3.8', 'type-bug', '3.7', '3.9', 'docs']
title = "Fix some class entries in 'Built-in Functions'"
updated_at = <Date 2019-12-30.22:24:30.623>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2019-12-30.22:24:30.623>
actor = 'miss-islington'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-07-15.03:04:38.552>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 34118
keywords = ['patch']
message_count = 13.0
messages = ['321674', '321732', '321771', '321786', '321799', '321997', '321998', '322030', '358969', '359062', '359063', '359064', '359065']
nosy_count = 5.0
nosy_names = ['rhettinger', 'terry.reedy', 'ncoghlan', 'docs@python', 'miss-islington']
pr_nums = ['17761', '17762', '17763']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue34118'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[terryjreedy]

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. 83c0ae5.) 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.)

[rhettinger]

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.

[terryjreedy]

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.

[terryjreedy]

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.

[rhettinger]

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.

[ncoghlan]

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.

[ncoghlan]

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.

[terryjreedy]

I will write a PR only touching the collection class entries.

[terryjreedy]

I closed bpo-39112, about tuple only, as a duplicate of this.