From 0d1b27135bc22bfdf95e9f3148feba809488e15f Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 10 Sep 2026 16:16:18 +0200 Subject: [PATCH] [3.14] gh-141984: Add "exhausted" to glossary, link existing mentions (GH-157225) (cherry picked from commit 9bd670cba21aa3559c126bbe28a55d3fbea76841) Co-authored-by: Petr Viktorin Co-authored-by: Blaise Pabon Co-authored-by: Stan Ulbrych --- Doc/c-api/typeobj.rst | 7 ++++--- Doc/glossary.rst | 10 +++++++++- Doc/howto/functional.rst | 13 +++++++------ Doc/library/collections.rst | 2 +- Doc/library/dis.rst | 2 +- Doc/library/functions.rst | 10 +++++----- Doc/library/http.client.rst | 2 +- Doc/library/itertools.rst | 18 +++++++++--------- Doc/library/os.rst | 2 +- Doc/library/unittest.mock.rst | 6 +++--- Doc/reference/compound_stmts.rst | 2 +- Doc/tutorial/controlflow.rst | 2 +- 12 files changed, 43 insertions(+), 33 deletions(-) diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 4d69821ba9dfae..b8e2f19b50efaf 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1928,9 +1928,10 @@ and :c:data:`PyType_Type` effectively act as defaults.) PyObject *tp_iternext(PyObject *self); - When the iterator is exhausted, it must return ``NULL``; a :exc:`StopIteration` - exception may or may not be set. When another error occurs, it must return - ``NULL`` too. Its presence signals that the instances of this type are + When the iterator is :term:`exhausted`, the ``tp_iternext`` function must + return ``NULL``; a :exc:`StopIteration` exception may or may not be set. + When another error occurs, it must return ``NULL`` too. + The presence of ``tp_iternext`` signals that the instances of this type are iterators. Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that diff --git a/Doc/glossary.rst b/Doc/glossary.rst index cd9d38b2fe4af2..68bc0560911161 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -505,6 +505,14 @@ Glossary of an object, such as the value of type aliases created with the :keyword:`type` statement. + exhausted + An :term:`iterator` that has produced all of its values is said to be + :dfn:`exhausted`. + Further attempts to get the next value (for example, calls to + :func:`next`) raise :exc:`StopIteration` + (or :exc:`StopAsyncIteration` in the case of an :term:`asynchronous + iterator`). + expression A piece of syntax which can be evaluated to some value. In other words, an expression is an accumulation of expression elements like literals, @@ -869,7 +877,7 @@ Glossary :meth:`~iterator.__next__` method (or passing it to the built-in function :func:`next`) return successive items in the stream. When no more data are available a :exc:`StopIteration` exception is raised instead. At this - point, the iterator object is exhausted and any further calls to its + point, the iterator object is :term:`exhausted` and any further calls to its :meth:`!__next__` method just raise :exc:`StopIteration` again. Iterators are required to have an :meth:`~iterator.__iter__` method that returns the iterator object itself so every iterator is also iterable and may be used in most diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index b78be3bbfbfed9..4a16c3d4bba5bf 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -723,9 +723,10 @@ returns them in a tuple:: zip(['a', 'b', 'c'], (1, 2, 3)) => ('a', 1), ('b', 2), ('c', 3) -It doesn't construct an in-memory list and exhaust all the input iterators -before returning; instead tuples are constructed and returned only if they're -requested. (The technical term for this behaviour is `lazy evaluation +It doesn't construct an in-memory list and :term:`exhaust ` all +the input iterators before returning; instead tuples are constructed and +returned only if they're requested. +(The technical term for this behaviour is `lazy evaluation `__.) This iterator is intended to be used with iterables that are all of the same @@ -786,7 +787,7 @@ element *n* times, or returns the element endlessly if *n* is not provided. :: :func:`itertools.chain(iterA, iterB, ...) ` takes an arbitrary number of iterables as input, and returns all the elements of the first iterator, then all the elements of the second, and so on, until all of the -iterables have been exhausted. :: +iterables have been :term:`exhausted`. :: itertools.chain(['a', 'b', 'c'], (1, 2, 3)) => a, b, c, 1, 2, 3 @@ -881,7 +882,7 @@ iterable's results. :: :func:`itertools.compress(data, selectors) ` takes two iterators and returns only those elements of *data* for which the corresponding -element of *selectors* is true, stopping whenever either one is exhausted:: +element of *selectors* is true, stopping whenever either one is :term:`exhausted`:: itertools.compress([1, 2, 3, 4, 5], [True, True, False, False, True]) => 1, 2, 5 @@ -1031,7 +1032,7 @@ that takes two elements and returns a single value. :func:`functools.reduce` takes the first two elements A and B returned by the iterator and calculates ``func(A, B)``. It then requests the third element, C, calculates ``func(func(A, B), C)``, combines this result with the fourth element returned, -and continues until the iterable is exhausted. If the iterable returns no +and continues until the iterable is :term:`exhausted`. If the iterable returns no values at all, a :exc:`TypeError` exception is raised. If the initial value is supplied, it's used as a starting point and ``func(initial_value, A)`` is the first calculation. :: diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index db5c49c026c17a..eaa69d1da8f250 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -686,7 +686,7 @@ added elements by appending to the right and popping to the left:: A `round-robin scheduler `_ can be implemented with input iterators stored in a :class:`deque`. Values are yielded from the active -iterator in position zero. If that iterator is exhausted, it can be removed +iterator in position zero. If that iterator is :term:`exhausted`, it can be removed with :meth:`~deque.popleft`; otherwise, it can be cycled back to the end with the :meth:`~deque.rotate` method:: diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index d6b728b0848dff..137d516f22cfef 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1424,7 +1424,7 @@ iterations of the loop. ``STACK[-1]`` is an :term:`iterator`. Call its :meth:`~iterator.__next__` method. If this yields a new value, push it on the stack (leaving the iterator below - it). If the iterator indicates it is exhausted then the byte code counter is + it). If the iterator indicates it is :term:`exhausted` then the byte code counter is incremented by *delta*. .. versionchanged:: 3.12 diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 16c420ddd1b5e6..73dff173fb60c7 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -87,7 +87,7 @@ are always available. They are listed here in alphabetical order. anext(async_iterator, default, /) When awaited, return the next item from the given :term:`asynchronous - iterator`, or *default* if given and the iterator is exhausted. + iterator`, or *default* if given and the iterator is :term:`exhausted`. This is the async variant of the :func:`next` builtin, and behaves similarly. @@ -1216,7 +1216,7 @@ are always available. They are listed here in alphabetical order. yielding the results. If additional *iterables* arguments are passed, *function* must take that many arguments and is applied to the items from all iterables in parallel. With multiple iterables, the iterator stops when the - shortest iterable is exhausted. If *strict* is ``True`` and one of the + shortest iterable is :term:`exhausted`. If *strict* is ``True`` and one of the iterables is exhausted before the others, a :exc:`ValueError` is raised. For cases where the function inputs are already arranged into argument tuples, see :func:`itertools.starmap`. @@ -1298,7 +1298,7 @@ are always available. They are listed here in alphabetical order. 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. + if the iterator is :term:`exhausted`, otherwise :exc:`StopIteration` is raised. .. class:: object() @@ -2174,7 +2174,7 @@ are always available. They are listed here in alphabetical order. the code that prepared these iterables. Python offers three different approaches to dealing with this issue: - * By default, :func:`zip` stops when the shortest iterable is exhausted. + * By default, :func:`zip` stops when the shortest iterable is :term:`exhausted`. It will ignore the remaining items in the longer iterables, cutting off the result to the length of the shortest iterable:: @@ -2189,7 +2189,7 @@ are always available. They are listed here in alphabetical order. [('a', 1), ('b', 2), ('c', 3)] Unlike the default behavior, it raises a :exc:`ValueError` if one iterable - is exhausted before the others: + is :term:`exhausted` before the others: >>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True): # doctest: +SKIP ... print(item) diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 14c67a0600f728..68fa4a77efb869 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -269,7 +269,7 @@ HTTPConnection Objects instance of :class:`io.TextIOBase`, the data returned by the ``read()`` method will be encoded as ISO-8859-1, otherwise the data returned by ``read()`` is sent as is. If *body* is an iterable, the elements of the - iterable are sent as is until the iterable is exhausted. + iterable are sent as is until the iterable is :term:`exhausted`. The *headers* argument should be a mapping of extra HTTP headers to send with the request. A :rfc:`Host header <2616#section-14.23>` diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 8bfe5ac31e8990..2c66a80cc6e405 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -161,7 +161,7 @@ loops that truncate the stream. Loops over the input iterable and accumulates data into tuples up to size *n*. The input is consumed lazily, just enough to fill a batch. The result is yielded as soon as the batch is full or when the input - iterable is exhausted: + iterable is :term:`exhausted`: .. doctest:: @@ -191,7 +191,7 @@ loops that truncate the stream. .. function:: chain(*iterables) Make an iterator that returns elements from the first iterable until - it is exhausted, then proceeds to the next iterable, until all of the + it is :term:`exhausted`, then proceeds to the next iterable, until all of the iterables are exhausted. This combines multiple data sources into a single iterator. Roughly equivalent to:: @@ -300,7 +300,7 @@ loops that truncate the stream. Make an iterator that returns elements from *data* where the corresponding element in *selectors* is true. Stops when either the - *data* or *selectors* iterables have been exhausted. Roughly + *data* or *selectors* iterables have been :term:`exhausted`. Roughly equivalent to:: def compress(data, selectors): @@ -336,7 +336,7 @@ loops that truncate the stream. .. function:: cycle(iterable) Make an iterator returning elements from the *iterable* and saving a - copy of each. When the iterable is exhausted, return elements from + copy of each. When the iterable is :term:`exhausted`, return elements from the saved copy. Repeats indefinitely. Roughly equivalent to:: def cycle(iterable): @@ -467,7 +467,7 @@ loops that truncate the stream. elements from the iterable are skipped until *start* is reached. If *stop* is ``None``, iteration continues until the input is - exhausted, if at all. Otherwise, it stops at the specified position. + :term:`exhausted`, if at all. Otherwise, it stops at the specified position. If *step* is ``None``, the step defaults to one. Elements are returned consecutively unless *step* is set higher than one which results in @@ -672,9 +672,9 @@ loops that truncate the stream. Note, the element that first fails the predicate condition is consumed from the input iterator and there is no way to access it. This could be an issue if an application wants to further consume the - input iterator after *takewhile* has been run to exhaustion. To work - around this problem, consider using `more-itertools before_and_after() - `_ + input iterator after *takewhile* has been run to :term:`exhaustion `. + To work around this problem, consider using `more-itertools before_and_after() + `__ instead. @@ -761,7 +761,7 @@ loops that truncate the stream. If the iterables are of uneven length, missing values are filled-in with *fillvalue*. If not specified, *fillvalue* defaults to ``None``. - Iteration continues until the longest iterable is exhausted. + Iteration continues until the longest iterable is :term:`exhausted`. Roughly equivalent to:: diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 8e839ffd1f376c..5844a3daec0315 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -2899,7 +2899,7 @@ features: Close the iterator and free acquired resources. - This is called automatically when the iterator is exhausted or garbage + This is called automatically when the iterator is :term:`exhausted` or garbage collected, or when an error happens during iterating. However it is advisable to call it explicitly or use the :keyword:`with` statement. diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index 048dee3c84e277..77860e866ac16c 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -919,7 +919,7 @@ object:: exception, - if ``side_effect`` is an iterable, the async function will return the next value of the iterable, however, if the sequence of result is - exhausted, ``StopAsyncIteration`` is raised immediately, + :term:`exhausted`, ``StopAsyncIteration`` is raised immediately, - if ``side_effect`` is not defined, the async function will return the value defined by ``return_value``, hence, by default, the async function returns a new :class:`AsyncMock` object. @@ -1269,7 +1269,7 @@ To remove a :attr:`~Mock.side_effect`, and return to the default behaviour, set 6 The :attr:`~Mock.side_effect` can also be any iterable object. Repeated calls to the mock -will return values from the iterable (until the iterable is exhausted and +will return values from the iterable (until the iterable is :term:`exhausted` and a :exc:`StopIteration` is raised): >>> m = MagicMock(side_effect=[1, 2, 3]) @@ -2946,7 +2946,7 @@ precedence remains the same: >>> order_mock.get_value() 'third' -If :attr:`~Mock.side_effect` is exhausted, the order of precedence will not +If :attr:`~Mock.side_effect` is :term:`exhausted`, the order of precedence will not cause a value to be obtained from the successors. Instead, ``StopIteration`` exception is raised. diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 877a1b94e173b0..f9ed9b455e9baa 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -162,7 +162,7 @@ once; it should yield an :term:`iterable` object. An :term:`iterator` is created for that iterable. The first item provided by the iterator is then assigned to the target list using the standard rules for assignments (see :ref:`assignment`), and the suite is executed. This repeats for each -item provided by the iterator. When the iterator is exhausted, +item provided by the iterator. When the iterator is :term:`exhausted`, the suite in the :keyword:`!else` clause, if present, is executed, and the loop terminates. diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index bee6cc39fafcdb..02637582a67044 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -147,7 +147,7 @@ the list, thus saving space. We say such an object is :term:`iterable`, that is, suitable as a target for functions and constructs that expect something from which they can -obtain successive items until the supply is exhausted. We have seen that +obtain successive items until the supply is :term:`exhausted`. We have seen that the :keyword:`for` statement is such a construct, while an example of a function that takes an iterable is :func:`sum`::