[3.15] gh-141984: Add "exhausted" to glossary, link existing mentions (GH-157225) (#157271)

Co-authored-by: Blaise Pabon <blaise@gmail.com>
Co-authored-by: Stan Ulbrych <stan@python.org>

Author: 3 people

Doc/c-api/typeobj.rst

@@ -1869,9 +1869,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

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

Doc/howto/functional.rst

@@ -720,9 +720,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
@@ -783,7 +784,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
@@ -878,7 +879,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
@@ -1028,7 +1029,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. ::

Doc/library/collections.rst

@@ -690,7 +690,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::
 

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

Doc/library/functions.rst

@@ -89,7 +89,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.
@@ -1250,7 +1250,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`.
@@ -1332,7 +1332,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()
@@ -2247,7 +2247,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::
 
@@ -2262,7 +2262,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)

Doc/library/http.client.rst

@@ -277,7 +277,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>`

Doc/library/itertools.rst

@@ -158,7 +158,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::
 
@@ -188,7 +188,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::
 
@@ -305,7 +305,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):
@@ -341,7 +341,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):
@@ -472,7 +472,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
@@ -677,9 +677,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.
 
 
@@ -766,7 +766,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::
 

Doc/library/os.rst

@@ -2952,7 +2952,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.

Doc/library/unittest.mock.rst

@@ -918,7 +918,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.
@@ -1268,7 +1268,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])
@@ -2945,7 +2945,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.