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

Make sure documentation is accurate for what an (async) iterable and (async) iterator are #89413

Closed
brettcannon opened this issue Sep 20, 2021 · 9 comments
Assignees
Labels
docs Documentation in the Doc dir

Comments

@brettcannon
Copy link
Member

BPO 45250
Nosy @brettcannon, @srittau
PRs
  • bpo-45250: fix docs regarding __iter__ and iterators being inconsistently required by CPython #29170
  • [3.10] bpo-45250: fix docs regarding __iter__ and iterators being inconsistently required by CPython (GH-29170) #29650
  • 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 = 'https://github.com/brettcannon'
    closed_at = <Date 2021-11-22.23:09:30.138>
    created_at = <Date 2021-09-20.20:03:02.721>
    labels = ['docs']
    title = 'Make sure documentation is accurate for what an (async) iterable and (async) iterator are'
    updated_at = <Date 2021-11-22.23:09:30.137>
    user = 'https://github.com/brettcannon'

    bugs.python.org fields:

    activity = <Date 2021-11-22.23:09:30.137>
    actor = 'brett.cannon'
    assignee = 'brett.cannon'
    closed = True
    closed_date = <Date 2021-11-22.23:09:30.138>
    closer = 'brett.cannon'
    components = ['Documentation']
    creation = <Date 2021-09-20.20:03:02.721>
    creator = 'brett.cannon'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 45250
    keywords = ['patch']
    message_count = 9.0
    messages = ['402276', '402304', '404816', '404817', '405330', '405451', '405458', '406634', '406809']
    nosy_count = 3.0
    nosy_names = ['brett.cannon', 'srittau', 'quicknir']
    pr_nums = ['29170', '29650']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = None
    url = 'https://bugs.python.org/issue45250'
    versions = []

    @brettcannon
    Copy link
    Member Author

    There's some inaccuracies when it comes to iterable and iterators (async and not). See https://mail.python.org/archives/list/python-dev@python.org/thread/3W7TDX5KNVQVGT5CUHBK33M7VNTP25DZ/#3W7TDX5KNVQVGT5CUHBK33M7VNTP25DZ for background.

    Should probably check:

    1. The glossary.
    2. Language reference.
    3. Built-ins.

    This applies to iter()/iter/iterable, next()/next/iterator, and their async equivalents.

    @brettcannon brettcannon self-assigned this Sep 20, 2021
    @brettcannon brettcannon added the docs Documentation in the Doc dir label Sep 20, 2021
    @brettcannon brettcannon self-assigned this Sep 20, 2021
    @brettcannon brettcannon added the docs Documentation in the Doc dir label Sep 20, 2021
    @srittau
    Copy link
    Mannequin

    srittau mannequin commented Sep 21, 2021

    One thing I would strongly suggest for consistent terminology: Make "iterator" mean an object that has both "__next()" and "__iter()". This is consistent with how an iterator has been described in the glossary for a long time, but also consistent with (abc.collections|typing).Iterator.

    Either invent a different term for objects having "__next__()" (but not necessarily "__iter__()"), or use a description like "an iterator or any other object that has a __next__() method".

    @brettcannon
    Copy link
    Member Author

    One thing I would strongly suggest for consistent terminology: Make "iterator" mean an object that has both "__next()" and "__iter()".

    The point of this issue, though, is to not make that claim as it's inaccurate.

    @brettcannon
    Copy link
    Member Author

    I also need to leave a comment on python/typeshed#6030 if/when this is fixed.

    @quicknir
    Copy link
    Mannequin

    quicknir mannequin commented Oct 29, 2021

    Wouldn't a nicer resolution for this be to change iter (which effectively defines what is "iterable"), so that if iter does not find the __iter__ or sequence protocol, it then looks for the iterator protocol (__next__), and if it finds that, return the argument?

    In that way, all iterators would automatically get the sane implementation of __iter__ by default, and we could say that in the "runtime", all iterators are iterable, matching the types. And people wouldn't need to implement __iter__ any more on their iterators i.e. the recommendation could simply be dropped).

    @brettcannon
    Copy link
    Member Author

    Wouldn't a nicer resolution for this be to change iter

    Unfortunately that isn't backwards-compatible. Some people may explicitly want their iterators to not be iterables to guarantee that people who want an iterator get a fresh/new one instead of reusing a live iterator.

    @quicknir
    Copy link
    Mannequin

    quicknir mannequin commented Nov 1, 2021

    Okay, fair enough.

    @brettcannon
    Copy link
    Member Author

    New changeset be36e06 by Brett Cannon in branch 'main':
    bpo-45250: fix docs regarding __iter__ and iterators being inconsistently required by CPython (GH-29170)
    be36e06

    @brettcannon
    Copy link
    Member Author

    New changeset 99aad31 by Brett Cannon in branch '3.10':
    [3.10] bpo-45250: fix docs regarding __iter__ and iterators being inconsistently required by CPython (GH-29170) (GH-29650)
    99aad31

    @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
    docs Documentation in the Doc dir
    Projects
    None yet
    Development

    No branches or pull requests

    1 participant