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

[Brett Cannon]

Change by Brett Cannon :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brett Cannon]

Brett Cannon  added the comment:


New changeset 99aad31b7ad493d4feea04064bcd6b04061477f9 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)
https://github.com/python/cpython/commit/99aad31b7ad493d4feea04064bcd6b04061477f9


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brett Cannon]

Change by Brett Cannon :


--
pull_requests: +27888
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/29650

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brett Cannon]

Brett Cannon  added the comment:


New changeset be36e0634060c7d5dee8e8876fb888bbb53d992a by Brett Cannon in 
branch 'main':
bpo-45250: fix docs regarding `__iter__` and iterators being inconsistently 
required by CPython (GH-29170)
https://github.com/python/cpython/commit/be36e0634060c7d5dee8e8876fb888bbb53d992a


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Nir Friedman]

Nir Friedman  added the comment:

Okay, fair enough.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brett Cannon]

Brett Cannon  added the comment:

> 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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Nir Friedman]

Nir Friedman  added the comment:

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).

--
nosy: +quicknir

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brett Cannon]

Brett Cannon  added the comment:

I also need to leave a comment on 
https://github.com/python/typeshed/issues/6030 if/when this is fixed.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brett Cannon]

Brett Cannon  added the comment:

> 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.

--
stage: patch review -> 

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brett Cannon]

Change by Brett Cannon :


--
keywords: +patch
pull_requests: +27443
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/29170

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Sebastian Rittau]

Sebastian Rittau  added the comment:

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".

--
nosy: +srittau

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Brett Cannon]

New submission from Brett Cannon :

There's some inaccuracies when it comes to iterable and iterators (async and 
not). See 
https://mail.python.org/archives/list/python-...@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.

--
assignee: brett.cannon
components: Documentation
messages: 402276
nosy: brett.cannon
priority: normal
severity: normal
status: open
title: Make sure documentation is accurate for what an (async) iterable and 
(async) iterator are

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com