[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.
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index d6eff14..1b18abc 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -772,21 +772,21 @@
support iteration. Sequences, described below in more detail, always support
the iteration methods.
-One method needs to be defined for container objects to provide iteration
+One method needs to be defined for container objects to provide :term:`iterable`
support:
.. XXX duplicated in reference/datamodel!
.. method:: container.__iter__()
- Return an iterator object. The object is required to support the iterator
- protocol described below. If a container supports different types of
- iteration, additional methods can be provided to specifically request
+ Return an :term:`iterator` object. The object is required to support the
+ iterator protocol described below. If a container supports different types
+ of iteration, additional methods can be provided to specifically request
iterators for those iteration types. (An example of an object supporting
multiple forms of iteration would be a tree structure which supports both
breadth-first and depth-first traversal.) This method corresponds to the
- :c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python objects in the Python/C
- API.
+ :c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python
+ objects in the Python/C API.
The iterator objects themselves are required to support the following two
methods, which together form the :dfn:`iterator protocol`:
@@ -794,18 +794,19 @@
.. method:: iterator.__iter__()
- Return the iterator object itself. This is required to allow both containers
- and iterators to be used with the :keyword:`for` and :keyword:`in` statements.
- This method corresponds to the :c:member:`~PyTypeObject.tp_iter` slot of the type structure for
- Python objects in the Python/C API.
+ Return the :term:`iterator` object itself. This is required to allow both
+ containers and iterators to be used with the :keyword:`for` and
+ :keyword:`in` statements. This method corresponds to the
+ :c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python
+ objects in the Python/C API.
.. method:: iterator.__next__()
- Return the next item from the container. If there are no further items, raise
- the :exc:`StopIteration` exception. This method corresponds to the
- :c:member:`~PyTypeObject.tp_iternext` slot of the type structure for Python objects in the
- Python/C API.
+ Return the next item from the :term:`iterator`. If there are no further
+ items, raise the :exc:`StopIteration` exception. This method corresponds to
+ the :c:member:`~PyTypeObject.tp_iternext` slot of the type structure for
+ Python objects in the Python/C API.
Python defines several iterator objects to support iteration over general and
specific sequence types, dictionaries, and other more specialized forms. The