next() function).
exception may or may not be set. When another error occurs, it must return
*NULL* too. Its presence normally signals that the instances of this type
are iterators (although classic instances always have this function, even if
- they don't define a :meth:`next` method).
+ they don't define a :meth:`~iterator.next` method).
Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that
function should return the iterator instance itself (not a new iterator
iterator
An object representing a stream of data. Repeated calls to the iterator's
- :meth:`next` method return successive items in the stream. When no more
+ :meth:`~generator.next` method 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
- :meth:`next` method just raise :exc:`StopIteration` again. Iterators are
+ :meth:`~generator.next` method just raise :exc:`StopIteration` again. Iterators are
required to have an :meth:`__iter__` method that returns the iterator
object itself so every iterator is also iterable and may be used in most
places where other iterables are accepted. One notable exception is code
.. 2to3fixer:: next
Converts the use of iterator's :meth:`~iterator.next` methods to the
- :func:`next` function. It also renames :meth:`next` methods to
+ :func:`next` function. It also renames :meth:`~iterator.next` methods to
:meth:`~iterator.__next__`.
.. 2to3fixer:: nonzero
.. class:: Iterator
- ABC for classes that provide the :meth:`__iter__` and :meth:`next` methods.
- See also the definition of :term:`iterator`.
+ ABC for classes that provide the :meth:`~iterator.__iter__` and
+ :meth:`~iterator.next` methods. See also the definition of :term:`iterator`.
.. class:: Sequence
MutableSequence
specific types are not important beyond their implementation of the iterator
protocol.
-The intention of the protocol is that once an iterator's :meth:`next` method
+The intention of the protocol is that once an iterator's :meth:`~iterator.next` method
raises :exc:`StopIteration`, it will continue to do so on subsequent calls.
Implementations that do not obey this property are deemed broken. (This
constraint was added in Python 2.3; in Python 2.2, various iterators are broken
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. More
-information about generators can be found in :ref:`the documentation for the
-yield expression <yieldexpr>`.
+generator object) supplying the :meth:`~iterator.__iter__` and
+:meth:`~iterator.next` methods. More information about generators can be found
+in :ref:`the documentation for the yield expression <yieldexpr>`.
.. _typesseq:
is already executing raises a :exc:`ValueError` exception.
.. index:: exception: StopIteration
-.. class:: generator
.. method:: generator.next()
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
+ :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
+ :token:`expression_list` is returned to :meth:`~generator.next`'s caller.
+ If the generator
exits without yielding another value, a :exc:`StopIteration` exception is
raised.
-.. class:: .
-
.. method:: generator.send(value)
Resumes the execution and "sends" a value into the generator function. The
When a generator function is called, it returns an iterator known as a generator
iterator, or more commonly, a generator. The body of the generator function is
-executed by calling the generator's :meth:`next` method repeatedly until it
-raises an exception.
+executed by calling the generator's :meth:`~generator.next` method repeatedly
+until it raises an exception.
When a :keyword:`yield` statement is executed, the state of the generator is
-frozen and the value of :token:`expression_list` is returned to :meth:`next`'s
-caller. By "frozen" we mean that all local state is retained, including the
-current bindings of local variables, the instruction pointer, and the internal
-evaluation stack: enough information is saved so that the next time :meth:`next`
-is invoked, the function can proceed exactly as if the :keyword:`yield`
-statement were just another external call.
+frozen and the value of :token:`expression_list` is returned to
+:meth:`~generator.next`'s caller. By "frozen" we mean that all local state is
+retained, including the current bindings of local variables, the instruction
+pointer, and the internal evaluation stack: enough information is saved so that
+the next time :meth:`~generator.next` is invoked, the function can proceed
+exactly as if the :keyword:`yield` statement were just another external call.
As of Python version 2.5, the :keyword:`yield` statement is now allowed in the
:keyword:`try` clause of a :keyword:`try` ... :keyword:`finally` construct. If
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:`~iterator.next`, then :meth:`__iter__` can just return ``self``::
class Reverse:
"""Iterator for looping over a sequence backwards."""
:term:`Generator`\s are a simple and powerful tool for creating iterators. They
are written like regular functions but use the :keyword:`yield` statement
-whenever they want to return data. Each time :meth:`next` is called, the
+whenever they want to return data. Each time :func:`next` is called on it, the
generator resumes where it left-off (it remembers all the data values and which
statement was last executed). An example shows that generators can be trivially
easy to create::
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
projects / python / commitdiff