This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author terry.reedy
Recipients docs@python, ncoghlan, rhettinger, terry.reedy
Date 2018-07-15.03:04:36
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1531623878.78.0.56676864532.issue34118@psf.upfronthosting.co.za>
In-reply-to
Content
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.)
History
Date User Action Args
2018-07-15 03:04:38terry.reedysetrecipients: + terry.reedy, rhettinger, ncoghlan, docs@python
2018-07-15 03:04:38terry.reedysetmessageid: <1531623878.78.0.56676864532.issue34118@psf.upfronthosting.co.za>
2018-07-15 03:04:38terry.reedylinkissue34118 messages
2018-07-15 03:04:36terry.reedycreate