https://github.com/python/cpython/commit/04ed190e875b94195051f6cc4eb471d051f77cd7 commit: 04ed190e875b94195051f6cc4eb471d051f77cd7 branch: 3.14 author: Stan Ulbrych <[email protected]> committer: encukou <[email protected]> date: 2026-09-10T17:16:23+02:00 summary:
[3.14] gh-141984: Add "exhausted" to glossary, link existing mentions (GH-157225) (GH-157272) (cherry picked from commit 9bd670cba21aa3559c126bbe28a55d3fbea76841) Co-authored-by: Petr Viktorin <[email protected]> Co-authored-by: Blaise Pabon <[email protected]> files: M Doc/c-api/typeobj.rst M Doc/glossary.rst M Doc/howto/functional.rst M Doc/library/collections.rst M Doc/library/dis.rst M Doc/library/functions.rst M Doc/library/http.client.rst M Doc/library/itertools.rst M Doc/library/os.rst M Doc/library/unittest.mock.rst M Doc/reference/compound_stmts.rst M Doc/tutorial/controlflow.rst diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 4d69821ba9dfae3..b8e2f19b50efafb 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 cd9d38b2fe4af29..68bc0560911161f 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 b78be3bbfbfed97..4a16c3d4bba5bf1 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 <exhausted>` 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 <https://en.wikipedia.org/wiki/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, ...) <itertools.chain>` 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) <itertools.compress>` 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 db5c49c026c17ab..eaa69d1da8f2502 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 <https://en.wikipedia.org/wiki/Round-robin_scheduling>`_ 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 d6b728b0848dff2..137d516f22cfef8 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 16c420ddd1b5e6e..73dff173fb60c71 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 14c67a0600f7287..68fa4a77efb869d 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 8bfe5ac31e8990d..2c66a80cc6e4059 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() - <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.before_and_after>`_ + input iterator after *takewhile* has been run to :term:`exhaustion <exhausted>`. + To work around this problem, consider using `more-itertools before_and_after() + <https://more-itertools.readthedocs.io/en/stable/api.html#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 8e839ffd1f376cf..5844a3daec0315e 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 048dee3c84e2775..77860e866ac16cb 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 877a1b94e173b01..f9ed9b455e9baa4 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 bee6cc39fafcdb9..02637582a670446 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`:: _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
