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

[brettcannon]

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]

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.

[srittau]

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]

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]

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

[quicknir]

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]

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]

Okay, fair enough.

[brettcannon]

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]

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