[3.10] bpo-45250: fix docs regarding `__iter__` and iterators being inconsistently required by CPython (GH-29170) (GH-29650)
It is now considered a historical accident that e.g. `for` loops and the `iter()` built-in function do not require the iterators they work with to define `__iter__`, only `__next__`.
(cherry picked from commit be36e0634060c7d5dee8e8876fb888bbb53d992a)
Co-authored-by: Brett Cannon <brett@python.org>
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 47ebbd0..307d679 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -66,9 +66,6 @@
Return an :term:`asynchronous iterator` for an :term:`asynchronous iterable`.
Equivalent to calling ``x.__aiter__()``.
- ``aiter(x)`` itself has an ``__aiter__()`` method that returns ``x``,
- so ``aiter(aiter(x))`` is the same as ``aiter(x)``.
-
Note: Unlike :func:`iter`, :func:`aiter` has no 2-argument variant.
.. versionadded:: 3.10
@@ -929,8 +926,8 @@
Return an :term:`iterator` object. The first argument is interpreted very
differently depending on the presence of the second argument. Without a
second argument, *object* must be a collection object which supports the
- iteration protocol (the :meth:`__iter__` method), or it must support the
- sequence protocol (the :meth:`__getitem__` method with integer arguments
+ :term:`iterable` protocol (the :meth:`__iter__` method), or it must support
+ the sequence protocol (the :meth:`__getitem__` method with integer arguments
starting at ``0``). If it does not support either of those protocols,
:exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
then *object* must be a callable object. The iterator created in this case
@@ -1060,7 +1057,7 @@
.. function:: next(iterator[, default])
- Retrieve the next item from the *iterator* by calling its
+ Retrieve the next item from the :term:`iterator` by calling its
:meth:`~iterator.__next__` method. If *default* is given, it is returned
if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.