PEP 3114: rename .next() to .__next__() and add next() builtin.
diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
index 124dd01..98d1094 100644
--- a/Doc/howto/functional.rst
+++ b/Doc/howto/functional.rst
@@ -199,11 +199,13 @@
An iterator is an object representing a stream of data; this object
returns the data one element at a time. A Python iterator must
-support a method called ``next()`` that takes no arguments and always
+support a method called ``__next__()`` that takes no arguments and always
returns the next element of the stream. If there are no more elements
-in the stream, ``next()`` must raise the ``StopIteration`` exception.
+in the stream, ``__next__()`` must raise the ``StopIteration`` exception.
Iterators don't have to be finite, though; it's perfectly reasonable
to write an iterator that produces an infinite stream of data.
+The built-in ``next()`` function is normally used to call the iterator's
+``__next__()`` method.
The built-in ``iter()`` function takes an arbitrary object and tries
to return an iterator that will return the object's contents or
@@ -218,13 +220,13 @@
>>> it = iter(L)
>>> print it
<iterator object at 0x8116870>
- >>> it.next()
+ >>> next(it)
1
- >>> it.next()
+ >>> next(it)
2
- >>> it.next()
+ >>> next(it)
3
- >>> it.next()
+ >>> next(it)
Traceback (most recent call last):
File "<stdin>", line 1, in ?
StopIteration
@@ -271,7 +273,7 @@
Note that you can only go forward in an iterator; there's no way to
get the previous element, reset the iterator, or make a copy of it.
Iterator objects can optionally provide these additional capabilities,
-but the iterator protocol only specifies the ``next()`` method.
+but the iterator protocol only specifies the ``__next__()`` method.
Functions may therefore consume all of the iterator's output, and if
you need to do something different with the same stream, you'll have
to create a new iterator.
@@ -485,7 +487,7 @@
statement. The big difference between ``yield`` and a
``return`` statement is that on reaching a ``yield`` the
generator's state of execution is suspended and local variables are
-preserved. On the next call to the generator's ``.next()`` method,
+preserved. On the next call ``next(generator)``,
the function will resume executing.
Here's a sample usage of the ``generate_ints()`` generator::
@@ -493,13 +495,13 @@
>>> gen = generate_ints(3)
>>> gen
<generator object at 0x8117f90>
- >>> gen.next()
+ >>> next(gen)
0
- >>> gen.next()
+ >>> next(gen)
1
- >>> gen.next()
+ >>> next(gen)
2
- >>> gen.next()
+ >>> next(gen)
Traceback (most recent call last):
File "stdin", line 1, in ?
File "stdin", line 2, in generate_ints
@@ -521,7 +523,7 @@
own class and storing all the local variables of the generator as
instance variables. For example, returning a list of integers could
be done by setting ``self.count`` to 0, and having the
-``next()`` method increment ``self.count`` and return it.
+``__next__()`` method increment ``self.count`` and return it.
However, for a moderately complicated generator, writing a
corresponding class can be much messier.
@@ -583,7 +585,7 @@
Values are sent into a generator by calling its
``send(value)`` method. This method resumes the
generator's code and the ``yield`` expression returns the specified
-value. If the regular ``next()`` method is called, the
+value. If the regular ``__next__()`` method is called, the
``yield`` returns ``None``.
Here's a simple counter that increments by 1 and allows changing the
@@ -604,18 +606,18 @@
And here's an example of changing the counter:
>>> it = counter(10)
- >>> print it.next()
+ >>> print next(it)
0
- >>> print it.next()
+ >>> print next(it)
1
>>> print it.send(8)
8
- >>> print it.next()
+ >>> print next(it)
9
- >>> print it.next()
+ >>> print next(it)
Traceback (most recent call last):
File ``t.py'', line 15, in ?
- print it.next()
+ print next(it)
StopIteration
Because ``yield`` will often be returning ``None``, you