Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix some class entries in 'Built-in Functions' #78299

Open
terryjreedy opened this issue Jul 15, 2018 · 13 comments
Open

Fix some class entries in 'Built-in Functions' #78299

terryjreedy opened this issue Jul 15, 2018 · 13 comments
Labels
3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@terryjreedy
Copy link
Member

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
    Copy link
    Member Author

    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.

    1. 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 Typesdict 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 Typesset, 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 Typesset, 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 Typeslist, tuple, range.
    
    range(start, stop[, step])
        Rather than being a function, range is actually an immutable sequence type, as documented in Ranges and Sequence Typeslist, tuple, range.
    
    tuple([iterable])
        Rather than being a function, tuple is actually an immutable sequence type, as documented in Tuples and Sequence Typeslist, 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.)

    @terryjreedy terryjreedy added 3.7 (EOL) end of life 3.8 only security fixes labels Jul 15, 2018
    @terryjreedy terryjreedy added docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error labels Jul 15, 2018
    @serhiy-storchaka serhiy-storchaka changed the title Fix some class entries entries in 'Built-in Functions' Fix some class entries in 'Built-in Functions' Jul 15, 2018
    @rhettinger
    Copy link
    Contributor

    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
    Copy link
    Member Author

    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
    Copy link
    Member Author

    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
    Copy link
    Contributor

    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
    Copy link
    Contributor

    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
    Copy link
    Contributor

    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
    Copy link
    Member Author

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

    @terryjreedy
    Copy link
    Member Author

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

    @terryjreedy terryjreedy added the 3.9 only security fixes label Dec 28, 2019
    @terryjreedy
    Copy link
    Member Author

    New changeset ee9ff05 by Terry Jan Reedy in branch 'master':
    bpo-34118: memoryview, range, and tuple are classes (GH-17761)
    ee9ff05

    @terryjreedy
    Copy link
    Member Author

    I started with the agreed-on 'function' => 'class' changes and intend to follow with a PR for text changes.

    @miss-islington
    Copy link
    Contributor

    New changeset c9c17cc by Miss Islington (bot) in branch '3.7':
    bpo-34118: memoryview, range, and tuple are classes (GH-17761)
    c9c17cc

    @miss-islington
    Copy link
    Contributor

    New changeset ec94156 by Miss Islington (bot) in branch '3.8':
    bpo-34118: memoryview, range, and tuple are classes (GH-17761)
    ec94156

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Development

    No branches or pull requests

    4 participants