New submission from Terry J. Reedy <tjre...@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/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.)
----------
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 <rep...@bugs.python.org>
<https://bugs.python.org/issue34118>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
