From 867a96e19d2d56a1a59072fc5f31d17ab9b8a276 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 22 Oct 2021 12:02:56 -0700 Subject: [PATCH 01/12] Update the glossary --- Doc/glossary.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 1f14946fa13427..44e1031a66649f 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -129,8 +129,9 @@ Glossary :meth:`__aiter__` method. Introduced by :pep:`492`. asynchronous iterator - An object that implements the :meth:`__aiter__` and :meth:`__anext__` - methods. ``__anext__`` must return an :term:`awaitable` object. + An object that implements the :meth:`__anext__` method (and + implementing :meth:`__aiter__` is strongly encouraged). + ``__anext__`` must return an :term:`awaitable` object. :keyword:`async for` resolves the awaitables returned by an asynchronous iterator's :meth:`__anext__` method until it raises a :exc:`StopAsyncIteration` exception. Introduced by :pep:`492`. @@ -647,10 +648,10 @@ Glossary are available a :exc:`StopIteration` exception is raised instead. At this point, the iterator object is exhausted and any further calls to its :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators - are required to have an :meth:`__iter__` method that returns the iterator - object itself so every iterator is also iterable and may be used in most - places where other iterables are accepted. One notable exception is code - which attempts multiple iteration passes. A container object (such as a + are strongly encouraged to have an :meth:`__iter__` method that returns + the iterator object itself so an iterator can be used in most places where + other iterables are accepted. One notable exception is code which + attempts multiple iteration passes. A container object (such as a :class:`list`) produces a fresh new iterator each time you pass it to the :func:`iter` function or use it in a :keyword:`for` loop. Attempting this with an iterator will just return the same exhausted iterator object used From ff971281461aa7f290545d75e2b521fc0ffacf65 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 22 Oct 2021 12:09:26 -0700 Subject: [PATCH 02/12] Add a news entry --- .../Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst diff --git a/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst b/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst new file mode 100644 index 00000000000000..b62b5638b2c5a2 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst @@ -0,0 +1,3 @@ +Update the documentation to correctly reflect that iterators only need to +define ``__next__`` and not ``__iter__``, ``__anext__`` and not +``__anext__`` for asynchronous iterators. From aaddd9f836668c7d53aba99b34a27d7d2bb6463c Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 22 Oct 2021 12:13:59 -0700 Subject: [PATCH 03/12] Update the built-in functions --- Doc/library/functions.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 09211681baf30f..c4d58cf63ffa10 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -66,9 +66,6 @@ are always available. They are listed here in alphabetical order. 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 @@ are always available. They are listed here in alphabetical order. 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 @@ are always available. They are listed here in alphabetical order. .. 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. From 2b11e3f8dbaaac67a75e835b3699eca0b744f828 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 22 Oct 2021 12:19:27 -0700 Subject: [PATCH 04/12] Add some glossary links to the data model --- Doc/reference/datamodel.rst | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index f1334f047d4b73..eb33bc38dd87dd 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -648,13 +648,13 @@ Callable types A function or method which uses the :keyword:`yield` statement (see section :ref:`yield`) is called a :dfn:`generator function`. Such a function, when - called, always returns an iterator object which can be used to execute the - body of the function: calling the iterator's :meth:`iterator.__next__` - method will cause the function to execute until it provides a value - using the :keyword:`!yield` statement. When the function executes a - :keyword:`return` statement or falls off the end, a :exc:`StopIteration` - exception is raised and the iterator will have reached the end of the set of - values to be returned. + called, always returns an :term:`iterator` object which can be used to + execute the body of the function: calling the iterator's + :meth:`iterator.__next__` method will cause the function to execute until + it provides a value using the :keyword:`!yield` statement. When the + function executes a :keyword:`return` statement or falls off the end, a + :exc:`StopIteration` exception is raised and the iterator will have + reached the end of the set of values to be returned. Coroutine functions .. index:: @@ -674,7 +674,7 @@ Callable types A function or method which is defined using :keyword:`async def` and which uses the :keyword:`yield` statement is called a :dfn:`asynchronous generator function`. Such a function, when called, - returns an asynchronous iterator object which can be used in an + returns an :term:`asynchronous iterator` object which can be used in an :keyword:`async for` statement to execute the body of the function. Calling the asynchronous iterator's :meth:`aiterator.__anext__` method @@ -2371,12 +2371,14 @@ through the object's keys; for sequences, it should iterate through the values. .. method:: object.__iter__(self) - This method is called when an iterator is required for a container. This method - should return a new iterator object that can iterate over all the objects in the - container. For mappings, it should iterate over the keys of the container. + This method is called when an :term:`iterator` is required for a container. + This method should return a new iterator object that can iterate over all the + objects in the container. For mappings, it should iterate over the keys of + the container. - Iterator objects also need to implement this method; they are required to return - themselves. For more information on iterator objects, see :ref:`typeiter`. + Iterator objects also need to implement this method; they are required to + return themselves. For more information on iterator objects, see + :ref:`typeiter`. .. method:: object.__reversed__(self) From 5224d4df536ee9f5283fb624d3ada747236280af Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 22 Oct 2021 12:25:23 -0700 Subject: [PATCH 05/12] Update stdtypes.rst --- Doc/library/stdtypes.rst | 34 +++++++++++++--------------------- 1 file changed, 13 insertions(+), 21 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index eea9ddcc140031..9396e9a6d52b9a 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -811,39 +811,31 @@ 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 -support: +support and be considered an :term:`iterable`: .. 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. - -The iterator objects themselves are required to support the following two -methods, which together form the :dfn:`iterator protocol`: - - -.. 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. + :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 the +method, which forms the :dfn:`iterator protocol` (although iterators are +strongly encouraged to also implement :meth:`__iter__` as well): .. 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 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. Python defines several iterator objects to support iteration over general and specific sequence types, dictionaries, and other more specialized forms. The From 7ee081aea1d9936372ee3c4f102adc78bae8219a Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 22 Oct 2021 12:38:00 -0700 Subject: [PATCH 06/12] Clarify collections.abc docs --- Doc/library/collections.abc.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index 132b0ce7192ac1..dcc7c430acb638 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -233,9 +233,9 @@ Collections Abstract Base Classes -- Detailed Descriptions .. class:: Iterator - ABC for classes that provide the :meth:`~iterator.__iter__` and - :meth:`~iterator.__next__` methods. See also the definition of - :term:`iterator`. + ABC for classes that provide the :meth:`~iterator.__next__` method. The ABC + also provides an implementation of :meth:`~iterator.__iter__` for + convenience.See also the definition of :term:`iterator`. .. class:: Reversible From ad880090590e680062669bb3b85e5a751e0be12f Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 22 Oct 2021 12:38:58 -0700 Subject: [PATCH 07/12] Add glossary links to the C API for iterators --- Doc/c-api/typeobj.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index d3d23e1cf2ee31..3837936079ec90 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1509,9 +1509,9 @@ and :c:type:`PyType_Type` effectively act as defaults.) .. c:member:: getiterfunc PyTypeObject.tp_iter - An optional pointer to a function that returns an iterator for the object. Its - presence normally signals that the instances of this type are iterable (although - sequences may be iterable without this function). + An optional pointer to a function that returns an :term:`iterator` for the + object. Its presence normally signals that the instances of this type are + :term:`iterable` (although sequences may be iterable without this function). This function has the same signature as :c:func:`PyObject_GetIter`:: @@ -1524,8 +1524,8 @@ and :c:type:`PyType_Type` effectively act as defaults.) .. c:member:: iternextfunc PyTypeObject.tp_iternext - An optional pointer to a function that returns the next item in an iterator. - The signature is:: + An optional pointer to a function that returns the next item in an + :term:`iterator`. The signature is:: PyObject *tp_iternext(PyObject *self); @@ -2417,8 +2417,8 @@ Async Object Structures PyObject *am_await(PyObject *self); - The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must - return ``1`` for it. + The returned object must be an :term:`iterator`, i.e. :c:func:`PyIter_Check` + must return ``1`` for it. This slot may be set to ``NULL`` if an object is not an :term:`awaitable`. From 7dccf4bec91fa8e48c396a3b7c71f03ce0c9b2fc Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 22 Oct 2021 14:32:25 -0700 Subject: [PATCH 08/12] Fix issues found via review --- Doc/library/collections.abc.rst | 2 +- .../next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index dcc7c430acb638..9941164cc1d90b 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -235,7 +235,7 @@ Collections Abstract Base Classes -- Detailed Descriptions ABC for classes that provide the :meth:`~iterator.__next__` method. The ABC also provides an implementation of :meth:`~iterator.__iter__` for - convenience.See also the definition of :term:`iterator`. + convenience. See also the definition of :term:`iterator`. .. class:: Reversible diff --git a/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst b/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst index b62b5638b2c5a2..2a4e27b272137b 100644 --- a/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst +++ b/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst @@ -1,3 +1,3 @@ Update the documentation to correctly reflect that iterators only need to define ``__next__`` and not ``__iter__``, ``__anext__`` and not -``__anext__`` for asynchronous iterators. +``__aiter__`` for asynchronous iterators. From 1dcceb9503ec3549da393cfb20b95d977590a2b7 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 26 Oct 2021 14:30:50 -0700 Subject: [PATCH 09/12] Clarify the docs for collections.abc.AsyncIterator --- Doc/library/collections.abc.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index 9941164cc1d90b..4a4009efd142c5 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -334,8 +334,9 @@ Collections Abstract Base Classes -- Detailed Descriptions .. class:: AsyncIterator - ABC for classes that provide ``__aiter__`` and ``__anext__`` - methods. See also the definition of :term:`asynchronous iterator`. + ABC for classes that provide the ``__anext__`` method. An implementation + of ``__aiter__`` is provided for convenience. See also the definition of + :term:`asynchronous iterator`. .. versionadded:: 3.5 From 15ac1e27611b1b4d487acc4d321844d488a1fdf0 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 1 Nov 2021 09:58:15 -0700 Subject: [PATCH 10/12] Remove a reference to `__iter__()` having to be defined on iterators from the language reference --- Doc/reference/datamodel.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index eb33bc38dd87dd..fca77904ed3c4b 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -2376,10 +2376,6 @@ through the object's keys; for sequences, it should iterate through the values. objects in the container. For mappings, it should iterate over the keys of the container. - Iterator objects also need to implement this method; they are required to - return themselves. For more information on iterator objects, see - :ref:`typeiter`. - .. method:: object.__reversed__(self) From 91d86cf6b279925927f57b2973e0f690d22e8eb7 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sat, 20 Nov 2021 00:02:41 +0000 Subject: [PATCH 11/12] Revert some changes --- Doc/glossary.rst | 22 +++++++++++----------- Doc/library/collections.abc.rst | 11 +++++------ 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 44e1031a66649f..ccbfc0e6c36c7d 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -129,9 +129,8 @@ Glossary :meth:`__aiter__` method. Introduced by :pep:`492`. asynchronous iterator - An object that implements the :meth:`__anext__` method (and - implementing :meth:`__aiter__` is strongly encouraged). - ``__anext__`` must return an :term:`awaitable` object. + An object that implements the :meth:`__aiter__` and :meth:`__anext__` + methods. ``__anext__`` must return an :term:`awaitable` object. :keyword:`async for` resolves the awaitables returned by an asynchronous iterator's :meth:`__anext__` method until it raises a :exc:`StopAsyncIteration` exception. Introduced by :pep:`492`. @@ -511,12 +510,13 @@ Glossary :func:`functools.singledispatch` decorator, and :pep:`443`. generic type - A :term:`type` that can be parameterized; typically a container like - :class:`list`. Used for :term:`type hints ` and + A :term:`type` that can be parameterized; typically a + :ref:`container class` such as :class:`list` or + :class:`dict`. Used for :term:`type hints ` and :term:`annotations `. - See :pep:`483` for more details, and :mod:`typing` or - :ref:`generic alias type ` for its uses. + For more details, see :ref:`generic alias types`, + :pep:`483`, :pep:`484`, :pep:`585`, and the :mod:`typing` module. GIL See :term:`global interpreter lock`. @@ -648,10 +648,10 @@ Glossary are available a :exc:`StopIteration` exception is raised instead. At this point, the iterator object is exhausted and any further calls to its :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators - are strongly encouraged to have an :meth:`__iter__` method that returns - the iterator object itself so an iterator can be used in most places where - other iterables are accepted. One notable exception is code which - attempts multiple iteration passes. A container object (such as a + are required to have an :meth:`__iter__` method that returns the iterator + object itself so every iterator is also iterable and may be used in most + places where other iterables are accepted. One notable exception is code + which attempts multiple iteration passes. A container object (such as a :class:`list`) produces a fresh new iterator each time you pass it to the :func:`iter` function or use it in a :keyword:`for` loop. Attempting this with an iterator will just return the same exhausted iterator object used diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst index 4a4009efd142c5..132b0ce7192ac1 100644 --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -233,9 +233,9 @@ Collections Abstract Base Classes -- Detailed Descriptions .. class:: Iterator - ABC for classes that provide the :meth:`~iterator.__next__` method. The ABC - also provides an implementation of :meth:`~iterator.__iter__` for - convenience. See also the definition of :term:`iterator`. + ABC for classes that provide the :meth:`~iterator.__iter__` and + :meth:`~iterator.__next__` methods. See also the definition of + :term:`iterator`. .. class:: Reversible @@ -334,9 +334,8 @@ Collections Abstract Base Classes -- Detailed Descriptions .. class:: AsyncIterator - ABC for classes that provide the ``__anext__`` method. An implementation - of ``__aiter__`` is provided for convenience. See also the definition of - :term:`asynchronous iterator`. + ABC for classes that provide ``__aiter__`` and ``__anext__`` + methods. See also the definition of :term:`asynchronous iterator`. .. versionadded:: 3.5 From e0286fe3a70b7abfc822d624703fa3dd2f28f70b Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sat, 20 Nov 2021 00:20:50 +0000 Subject: [PATCH 12/12] Clarify that CPython is inconsistent when it comes to requiring iterators to define `__iter__` --- Doc/c-api/iter.rst | 13 ++++----- Doc/glossary.rst | 5 ++++ Doc/library/stdtypes.rst | 27 ++++++++++++------- .../2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst | 5 ++-- 4 files changed, 32 insertions(+), 18 deletions(-) diff --git a/Doc/c-api/iter.rst b/Doc/c-api/iter.rst index f7106f4ef09906..3e388bb917a029 100644 --- a/Doc/c-api/iter.rst +++ b/Doc/c-api/iter.rst @@ -9,8 +9,8 @@ There are two functions specifically for working with iterators. .. c:function:: int PyIter_Check(PyObject *o) - Return non-zero if the object *o* supports the iterator protocol, and ``0`` - otherwise. This function always succeeds. + Return non-zero if the object *o* can be safely passed to + :c:func:`PyIter_Next`, and ``0`` otherwise. This function always succeeds. .. c:function:: int PyAIter_Check(PyObject *o) @@ -21,10 +21,11 @@ There are two functions specifically for working with iterators. .. c:function:: PyObject* PyIter_Next(PyObject *o) - Return the next value from the iteration *o*. The object must be an iterator - (it is up to the caller to check this). If there are no remaining values, - returns ``NULL`` with no exception set. If an error occurs while retrieving - the item, returns ``NULL`` and passes along the exception. + Return the next value from the iterator *o*. The object must be an iterator + according to :c:func:`PyIter_Check` (it is up to the caller to check this). + If there are no remaining values, returns ``NULL`` with no exception set. + If an error occurs while retrieving the item, returns ``NULL`` and passes + along the exception. To write a loop which iterates over an iterator, the C code should look something like this:: diff --git a/Doc/glossary.rst b/Doc/glossary.rst index ccbfc0e6c36c7d..e71f6c0406a23a 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -659,6 +659,11 @@ Glossary More information can be found in :ref:`typeiter`. + .. impl-detail:: + + CPython does not consistently apply the requirement that an iterator + define :meth:`__iter__`. + key function A key function or collation function is a callable that returns a value used for sorting or ordering. For example, :func:`locale.strxfrm` is diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 9396e9a6d52b9a..de77507458a0a0 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -810,8 +810,8 @@ using two distinct methods; these are used to allow user-defined classes to 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 -support and be considered an :term:`iterable`: +One method needs to be defined for container objects to provide :term:`iterable` +support: .. XXX duplicated in reference/datamodel! @@ -826,17 +826,26 @@ support and be considered an :term:`iterable`: :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 the -method, which forms the :dfn:`iterator protocol` (although iterators are -strongly encouraged to also implement :meth:`__iter__` as well): +The iterator objects themselves are required to support the following two +methods, which together form the :dfn:`iterator protocol`: -.. 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 +.. method:: iterator.__iter__() + + 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 :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 specific types are not important beyond their implementation of the iterator diff --git a/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst b/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst index 2a4e27b272137b..0c2bf18b20010a 100644 --- a/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst +++ b/Misc/NEWS.d/next/Documentation/2021-10-22-12-09-18.bpo-45250.Iit5-Y.rst @@ -1,3 +1,2 @@ -Update the documentation to correctly reflect that iterators only need to -define ``__next__`` and not ``__iter__``, ``__anext__`` and not -``__aiter__`` for asynchronous iterators. +Update the documentation to note that CPython does not consistently +require iterators to define ``__iter__``.