iterator
An object representing a stream of data. Repeated calls to the iterator's
- :meth:`__next__` method (or passing it to the built-in function
+ :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
Equivalent to ``map(func, *iterables)`` except *func* is executed
asynchronously and several calls to *func* may be made concurrently. The
- returned iterator raises a :exc:`TimeoutError` if :meth:`__next__()` is
- called and the result isn't available after *timeout* seconds from the
- original call to :meth:`Executor.map`. *timeout* can be an int or a
- float. If *timeout* is not specified or ``None``, there is no limit to
- the wait time. If a call raises an exception, then that exception will
- be raised when its value is retrieved from the iterator.
+ returned iterator raises a :exc:`TimeoutError` if
+ :meth:`~iterator.__next__` is called and the result isn't available
+ after *timeout* seconds from the original call to :meth:`Executor.map`.
+ *timeout* can be an int or a float. If *timeout* is not specified or
+ ``None``, there is no limit to the wait time. If a call raises an
+ exception, then that exception will be raised when its value is
+ retrieved from the iterator.
.. method:: shutdown(wait=True)
different :class:`Executor` instances) given by *fs* that yields futures as
they complete (finished or were cancelled). Any futures that completed
before :func:`as_completed` is called will be yielded first. The returned
- iterator raises a :exc:`TimeoutError` if :meth:`__next__` is called and the
- result isn't available after *timeout* seconds from the original call to
- :func:`as_completed`. *timeout* can be an int or float. If *timeout* is not
- specified or ``None``, there is no limit to the wait time.
+ iterator raises a :exc:`TimeoutError` if :meth:`~iterator.__next__` is
+ called and the result isn't available after *timeout* seconds from the
+ original call to :func:`as_completed`. *timeout* can be an int or float.
+ If *timeout* is not specified or ``None``, there is no limit to the wait
+ time.
.. seealso::
.. opcode:: FOR_ITER (delta)
- ``TOS`` is an :term:`iterator`. Call its :meth:`__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 ``TOS`` is popped, and the byte code
- counter is incremented by *delta*.
+ ``TOS`` 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 ``TOS`` is popped, and the
+ byte code counter is incremented by *delta*.
.. opcode:: LOAD_GLOBAL (namei)
.. exception:: StopIteration
Raised by built-in function :func:`next` and an :term:`iterator`\'s
- :meth:`__next__` method to signal that there are no further values.
+ :meth:`~iterator.__next__` method to signal that there are no further values.
.. exception:: SyntaxError
.. function:: enumerate(iterable, start=0)
Return an enumerate object. *iterable* must be a sequence, an
- :term:`iterator`, or some other object which supports iteration. The
- :meth:`__next__` method of the iterator returned by :func:`enumerate` returns a
- tuple containing a count (from *start* which defaults to 0) and the
- values obtained from iterating over *iterable*.
+ :term:`iterator`, or some other object which supports iteration.
+ The :meth:`~iterator.__next__` method of the iterator returned by
+ :func:`enumerate` returns a tuple containing a count (from *start* which
+ defaults to 0) and the values obtained from iterating over *iterable*.
>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
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
- will call *object* with no arguments for each call to its :meth:`__next__`
- method; if the value returned is equal to *sentinel*, :exc:`StopIteration`
- will be raised, otherwise the value will be returned.
+ will call *object* with no arguments for each call to its
+ :meth:`~iterator.__next__` method; if the value returned is equal to
+ *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
+ be returned.
One useful application of the second form of :func:`iter` is to read lines of
a file until a certain line is reached. The following example reads a file
.. function:: next(iterator[, default])
- Retrieve the next item from the *iterator* by calling its :meth:`__next__`
- method. If *default* is given, it is returned if the iterator is exhausted,
- otherwise :exc:`StopIteration` is raised.
+ Retrieve the next item from the *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.
.. function:: object()
specific types are not important beyond their implementation of the iterator
protocol.
-Once an iterator's :meth:`__next__` method raises :exc:`StopIteration`, it must
-continue to do so on subsequent calls. Implementations that do not obey this
-property are deemed broken.
+Once an iterator's :meth:`~iterator.__next__` method raises
+:exc:`StopIteration`, it must continue to do so on subsequent calls.
+Implementations that do not obey this property are deemed broken.
.. _generator-types:
Python's :term:`generator`\s provide a convenient way to implement the iterator
protocol. If a container object's :meth:`__iter__` method is implemented as a
generator, it will automatically return an iterator object (technically, a
-generator object) supplying the :meth:`__iter__` and :meth:`__next__` methods.
+generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__`
+methods.
More information about generators can be found in :ref:`the documentation for
the yield expression <yieldexpr>`.
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:`__next__` method will
- cause the function to execute until it provides a value using the
- :keyword:`yield` statement. When the function executes a
+ 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.
brackets or curly braces.
Variables used in the generator expression are evaluated lazily when the
-:meth:`__next__` method is called for generator object (in the same fashion as
-normal generators). However, the leftmost :keyword:`for` clause is immediately
-evaluated, so that an error produced by it can be seen before any other possible
-error in the code that handles the generator expression. Subsequent
-:keyword:`for` clauses cannot be evaluated immediately since they may depend on
-the previous :keyword:`for` loop. For example: ``(x*y for x in range(10) for y
-in bar(x))``.
+:meth:`~generator.__next__` method is called for generator object (in the same
+fashion as normal generators). However, the leftmost :keyword:`for` clause is
+immediately evaluated, so that an error produced by it can be seen before any
+other possible error in the code that handles the generator expression.
+Subsequent :keyword:`for` clauses cannot be evaluated immediately since they
+may depend on the previous :keyword:`for` loop. For example: ``(x*y for x in
+range(10) for y in bar(x))``.
The parentheses can be omitted on calls with only one argument. See section
:ref:`calls` for the detail.
Starts the execution of a generator function or resumes it at the last
executed :keyword:`yield` expression. When a generator function is resumed
- with a :meth:`__next__` method, the current :keyword:`yield` expression
- always evaluates to :const:`None`. The execution then continues to the next
- :keyword:`yield` expression, where the generator is suspended again, and the
- value of the :token:`expression_list` is returned to :meth:`next`'s caller.
+ with a :meth:`~generator.__next__` method, the current :keyword:`yield`
+ expression always evaluates to :const:`None`. The execution then continues
+ to the next :keyword:`yield` expression, where the generator is suspended
+ again, and the value of the :token:`expression_list` is returned to
+ :meth:`next`'s caller.
If the generator exits without yielding another value, a :exc:`StopIteration`
exception is raised.
This style of access is clear, concise, and convenient. The use of iterators
pervades and unifies Python. Behind the scenes, the :keyword:`for` statement
calls :func:`iter` on the container object. The function returns an iterator
-object that defines the method :meth:`__next__` which accesses elements in the
-container one at a time. When there are no more elements, :meth:`__next__`
-raises a :exc:`StopIteration` exception which tells the :keyword:`for` loop to
-terminate. You can call the :meth:`__next__` method using the :func:`next`
-built-in function; this example shows how it all works::
+object that defines the method :meth:`~iterator.__next__` which accesses
+elements in the container one at a time. When there are no more elements,
+:meth:`__next__` raises a :exc:`StopIteration` exception which tells the
+:keyword:`for` loop to terminate. You can call the :meth:`__next__` method
+using the :func:`next` built-in function; this example shows how it all works::
>>> s = 'abc'
>>> it = iter(s)
Having seen the mechanics behind the iterator protocol, it is easy to add
iterator behavior to your classes. Define an :meth:`__iter__` method which
-returns an object with a :meth:`__next__` method. If the class defines
-:meth:`__next__`, then :meth:`__iter__` can just return ``self``::
+returns an object with a :meth:`~iterator.__next__` method. If the class
+defines :meth:`__next__`, then :meth:`__iter__` can just return ``self``::
class Reverse:
"""Iterator for looping over a sequence backwards."""
Anything that can be done with generators can also be done with class based
iterators as described in the previous section. What makes generators so
-compact is that the :meth:`__iter__` and :meth:`__next__` methods are created
-automatically.
+compact is that the :meth:`__iter__` and :meth:`~generator.__next__` methods
+are created automatically.
Another key feature is that the local variables and execution state are
automatically saved between calls. This made the function easier to write and
respectively).
* :pep:`3114`: the standard :meth:`next` method has been renamed to
- :meth:`__next__`.
+ :meth:`~iterator.__next__`.
* The :meth:`__oct__` and :meth:`__hex__` special methods are removed
-- :func:`oct` and :func:`hex` use :meth:`__index__` now to convert
To get the old behavior of :func:`input`, use ``eval(input())``.
* A new built-in function :func:`next` was added to call the
- :meth:`__next__` method on an object.
+ :meth:`~iterator.__next__` method on an object.
* The :func:`round` function rounding strategy and return type have
changed. Exact halfway cases are now rounded to the nearest even
projects / thirdparty / Python / cpython.git / commitdiff
