diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 4000f8aa1d4c0c7..72d8f97b67e4d05 100644 --- a/Doc/c-api/typeobj.rst +++ b/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 diff --git a/Doc/glossary.rst b/Doc/glossary.rst index cd9d38b2fe4af29..005684fd943f4f1 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 + :py:func:`next`) raise :py:exc:`StopIteration` + (or :py: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 a61fdaee27f6b18..f2ff5edeb733d7f 100644 --- a/Doc/howto/functional.rst +++ b/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 ` 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 @@ -783,7 +784,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 @@ -878,7 +879,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 @@ -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. :: diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 599a898eb2cef83..40f780c7d049d4e 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -699,7 +699,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 af654f7f82323af..ced19268dea2364 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1427,7 +1427,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 013150535cb089c..67893e670fdba7c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -129,7 +129,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. @@ -1223,7 +1223,7 @@ are always available. They are listed here in alphabetical order. process_block(block) *stop_exception* is useful for callables - which report exhaustion by raising an exception + which report :term:`exhaustion ` by raising an exception instead of returning a special value. For example, draining a queue:: @@ -1315,7 +1315,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`. @@ -1397,7 +1397,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() @@ -2312,7 +2312,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:: @@ -2327,7 +2327,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 98ea09d8f72d8b6..4002fc697ceaa56 100644 --- a/Doc/library/http.client.rst +++ b/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>` diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index e1730608887b3dd..1bc3158973930dc 100644 --- a/Doc/library/itertools.rst +++ b/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() - `_ + input iterator after *takewhile* has been run to :term:`exhaustion `. + To work around this problem, consider using `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:: diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 6e0e67d2a613c85..9eba3bafae0cb6e 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -3002,7 +3002,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 b9e6f65cb917df0..0b33240a4504ff9 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -922,7 +922,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. @@ -1272,7 +1272,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]) @@ -2949,7 +2949,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 28850ba801138f0..c13860eb3e9319a 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 8bac8df4368c00a..c397ed4f218b6a3 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`::