PEP 3114: rename .next() to .__next__() and add next() builtin.
diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex
index e5c5aac..af1aed3 100644
--- a/Doc/api/newtypes.tex
+++ b/Doc/api/newtypes.tex
@@ -1071,7 +1071,7 @@
iterator, or raises \exception{StopIteration} when the iterator is
exhausted. 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 \method{next()} method).
+ function, even if they don't define a \method{__next__()} method).
Iterator types should also define the \member{tp_iter} function, and
that function should return the iterator instance itself (not a new
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
diff --git a/Doc/lib/libcollections.tex b/Doc/lib/libcollections.tex
index a763e31..5a07a2d 100644
--- a/Doc/lib/libcollections.tex
+++ b/Doc/lib/libcollections.tex
@@ -174,7 +174,7 @@
while pending:
task = pending.popleft()
try:
- yield task.next()
+ yield next(task)
except StopIteration:
continue
pending.append(task)
@@ -315,12 +315,12 @@
The function \function{int()} which always returns zero is just a special
case of constant functions. A faster and more flexible way to create
-constant functions is to use \function{itertools.repeat()} which can supply
+constant functions is to use a lambda function which can supply
any constant value (not just zero):
\begin{verbatim}
>>> def constant_factory(value):
-... return itertools.repeat(value).next
+... return lambda: value
>>> d = defaultdict(constant_factory('<missing>'))
>>> d.update(name='John', action='ran')
>>> '%(name)s %(action)s to %(object)s' % d
diff --git a/Doc/lib/libcsv.tex b/Doc/lib/libcsv.tex
index b87bc9d..54fc8db 100644
--- a/Doc/lib/libcsv.tex
+++ b/Doc/lib/libcsv.tex
@@ -487,8 +487,8 @@
def __iter__(self):
return self
- def next(self):
- return self.reader.next().encode("utf-8")
+ def __next__(self):
+ return next(self.reader).encode("utf-8")
class UnicodeReader:
"""
@@ -500,8 +500,8 @@
f = UTF8Recoder(f, encoding)
self.reader = csv.reader(f, dialect=dialect, **kwds)
- def next(self):
- row = self.reader.next()
+ def __next__(self):
+ row = next(self.reader)
return [unicode(s, "utf-8") for s in row]
def __iter__(self):
diff --git a/Doc/lib/libdis.tex b/Doc/lib/libdis.tex
index 4b0d63b..2d78d9a 100644
--- a/Doc/lib/libdis.tex
+++ b/Doc/lib/libdis.tex
@@ -529,10 +529,10 @@
\end{opcodedesc}
\begin{opcodedesc}{FOR_ITER}{delta}
-\code{TOS} is an iterator. Call its \method{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 \code{TOS} is
-popped, and the byte code counter is incremented by \var{delta}.
+ \code{TOS} is an iterator. Call its \method{__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 \code{TOS} is popped, and the byte code
+ counter is incremented by \var{delta}.
\end{opcodedesc}
%\begin{opcodedesc}{FOR_LOOP}{delta}
diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex
index 02e99a7..d119ed9 100644
--- a/Doc/lib/libexcs.tex
+++ b/Doc/lib/libexcs.tex
@@ -265,8 +265,8 @@
\end{excdesc}
\begin{excdesc}{StopIteration}
- Raised by an iterator's \method{next()} method to signal that there
- are no further values.
+ Raised by builtin \function{next()} and an iterator's \method{__next__()}
+ method to signal that there are no further values.
This is derived from \exception{Exception} rather than
\exception{StandardError}, since this is not considered an error in
its normal application.
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index b1d2983..b488ce4 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -342,14 +342,12 @@
\end{funcdesc}
\begin{funcdesc}{enumerate}{iterable}
- Return an enumerate object. \var{iterable} must be a sequence, an
- iterator, or some other object which supports iteration. The
- \method{next()} method of the iterator returned by
- \function{enumerate()} returns a tuple containing a count (from
- zero) and the corresponding value obtained from iterating over
- \var{iterable}. \function{enumerate()} is useful for obtaining an
- indexed series: \code{(0, seq[0])}, \code{(1, seq[1])}, \code{(2,
- seq[2])}, \ldots.
+ Return an enumerate object. \var{iterable} must be a sequence, an iterator, or
+ some other object which supports iteration. The \method{__next__()} method of
+ the iterator returned by \function{enumerate()} returns a tuple containing a
+ count (from zero) and the corresponding value obtained from iterating over
+ \var{iterable}. \function{enumerate()} is useful for obtaining an indexed
+ series: \code{(0, seq[0])}, \code{(1, seq[1])}, \code{(2, seq[2])}, \ldots.
\versionadded{2.3}
\end{funcdesc}
@@ -615,7 +613,7 @@
support either of those protocols, \exception{TypeError} is raised.
If the second argument, \var{sentinel}, is given, then \var{o} must
be a callable object. The iterator created in this case will call
- \var{o} with no arguments for each call to its \method{next()}
+ \var{o} with no arguments for each call to its \method{__next__()}
method; if the value returned is equal to \var{sentinel},
\exception{StopIteration} will be raised, otherwise the value will
be returned.
@@ -695,6 +693,12 @@
\versionchanged[Added support for the optional \var{key} argument]{2.5}
\end{funcdesc}
+\begin{funcdesc}{next}{iterator\optional{, default}}
+ Retrieve the next item from the \var{iterable} by calling its
+ \method{__next__()} method. If \var{default} is given, it is returned if the
+ iterator is exhausted, otherwise \exception{StopIteration} is raised.
+\end{funcdesc}
+
\begin{funcdesc}{object}{}
Return a new featureless object. \class{object} is a base
for all new style classes. It has the methods that are common
diff --git a/Doc/lib/libitertools.tex b/Doc/lib/libitertools.tex
index ac6028b..a2f37d7 100644
--- a/Doc/lib/libitertools.tex
+++ b/Doc/lib/libitertools.tex
@@ -164,16 +164,16 @@
self.tgtkey = self.currkey = self.currvalue = xrange(0)
def __iter__(self):
return self
- def next(self):
+ def __next__(self):
while self.currkey == self.tgtkey:
- self.currvalue = self.it.next() # Exit on StopIteration
+ self.currvalue = next(self.it) # Exit on StopIteration
self.currkey = self.keyfunc(self.currvalue)
self.tgtkey = self.currkey
return (self.currkey, self._grouper(self.tgtkey))
def _grouper(self, tgtkey):
while self.currkey == tgtkey:
yield self.currvalue
- self.currvalue = self.it.next() # Exit on StopIteration
+ self.currvalue = next(self.it) # Exit on StopIteration
self.currkey = self.keyfunc(self.currvalue)
\end{verbatim}
\versionadded{2.4}
@@ -227,7 +227,7 @@
def imap(function, *iterables):
iterables = map(iter, iterables)
while True:
- args = [i.next() for i in iterables]
+ args = [next(i) for i in iterables]
if function is None:
yield tuple(args)
else:
@@ -253,11 +253,11 @@
def islice(iterable, *args):
s = slice(*args)
it = iter(xrange(s.start or 0, s.stop or sys.maxint, s.step or 1))
- nexti = it.next()
+ nexti = next(it)
for i, element in enumerate(iterable):
if i == nexti:
yield element
- nexti = it.next()
+ nexti = next(it)
\end{verbatim}
If \var{start} is \code{None}, then iteration starts at zero.
@@ -276,7 +276,7 @@
def izip(*iterables):
iterables = map(iter, iterables)
while iterables:
- result = [it.next() for it in iterables]
+ result = [next(it) for it in iterables]
yield tuple(result)
\end{verbatim}
@@ -297,7 +297,7 @@
from each iterator in-turn, but the process ends when one of the iterators
terminates. This leaves the last fetched values in limbo (they cannot be
returned in a final, incomplete tuple and they are cannot be pushed back
- into the iterator for retrieval with \code{it.next()}). In general,
+ into the iterator for retrieval with \code{next(it)}). In general,
\function{izip()} should only be used with unequal length inputs when you
don't care about trailing, unmatched values from the longer iterables.
\end{funcdesc}
@@ -360,7 +360,7 @@
def starmap(function, iterable):
iterable = iter(iterable)
while True:
- yield function(*iterable.next())
+ yield function(*next(iterable))
\end{verbatim}
\end{funcdesc}
@@ -393,7 +393,7 @@
item = data.pop(i)
yield item
it = iter(iterable)
- return (gen(it.next), gen(it.next))
+ return (gen(it.__next__), gen(it.__next__))
\end{verbatim}
Note, once \function{tee()} has made a split, the original \var{iterable}
@@ -556,10 +556,7 @@
def pairwise(iterable):
"s -> (s0,s1), (s1,s2), (s2, s3), ..."
a, b = tee(iterable)
- try:
- b.next()
- except StopIteration:
- pass
+ next(b, None)
return izip(a, b)
def grouper(n, iterable, padvalue=None):
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index f3ce92a..d7b8858 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -388,18 +388,17 @@
specialized forms. The specific types are not important beyond their
implementation of the iterator protocol.
-The intention of the protocol is that once an iterator's
-\method{next()} method raises \exception{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 according to this rule.)
+The intention of the protocol is that once an iterator's \method{__next__()}
+method raises \exception{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
+according to this rule.)
-Python's generators provide a convenient way to implement the
-iterator protocol. If a container object's \method{__iter__()}
-method is implemented as a generator, it will automatically
-return an iterator object (technically, a generator object)
-supplying the \method{__iter__()} and \method{next()} methods.
+Python's generators provide a convenient way to implement the iterator protocol.
+If a container object's \method{__iter__()} method is implemented as a
+generator, it will automatically return an iterator object (technically, a
+generator object) supplying the \method{__iter__()} and \method{__next__()}
+methods.
\section{Sequence Types ---
@@ -1587,17 +1586,17 @@
with a real file, this method should \emph{not} be implemented.}
\end{methoddesc}
-\begin{methoddesc}[file]{next}{}
+\begin{methoddesc}[file]{__next__}{}
A file object is its own iterator, for example \code{iter(\var{f})} returns
\var{f} (unless \var{f} is closed). When a file is used as an
iterator, typically in a \keyword{for} loop (for example,
-\code{for line in f: print line}), the \method{next()} method is
+\code{for line in f: print line}), the \method{__next__()} method is
called repeatedly. This method returns the next input line, or raises
\exception{StopIteration} when \EOF{} is hit. In order to make a
\keyword{for} loop the most efficient way of looping over the lines of
-a file (a very common operation), the \method{next()} method uses a
+a file (a very common operation), the \method{__next__()} method uses a
hidden read-ahead buffer. As a consequence of using a read-ahead
-buffer, combining \method{next()} with other file methods (like
+buffer, combining \method{__next__()} with other file methods (like
\method{readline()}) does not work right. However, using
\method{seek()} to reposition the file to an absolute position will
flush the read-ahead buffer.
diff --git a/Doc/lib/sqlite3/executemany_1.py b/Doc/lib/sqlite3/executemany_1.py
index 24357c5..2dc72cd 100644
--- a/Doc/lib/sqlite3/executemany_1.py
+++ b/Doc/lib/sqlite3/executemany_1.py
@@ -7,7 +7,7 @@
def __iter__(self):
return self
- def next(self):
+ def __next__(self):
if self.count > ord('z'):
raise StopIteration
self.count += 1
diff --git a/Doc/ref/ref3.tex b/Doc/ref/ref3.tex
index a63ae3a..40b2ebd 100644
--- a/Doc/ref/ref3.tex
+++ b/Doc/ref/ref3.tex
@@ -633,7 +633,7 @@
section~\ref{yield}, ``The \keyword{yield} statement'') 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 \method{next()} method will
+the function: calling the iterator's \method{__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
diff --git a/Doc/ref/ref5.tex b/Doc/ref/ref5.tex
index 6aa6de1..0b4e978 100644
--- a/Doc/ref/ref5.tex
+++ b/Doc/ref/ref5.tex
@@ -222,7 +222,7 @@
innermost block for each iteration.
Variables used in the generator expression are evaluated lazily
-when the \method{next()} method is called for generator object
+when the \method{__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 error produced
by it can be seen before any other possible error in the code that
diff --git a/Doc/ref/ref6.tex b/Doc/ref/ref6.tex
index 4c7487b..e92a63d 100644
--- a/Doc/ref/ref6.tex
+++ b/Doc/ref/ref6.tex
@@ -418,19 +418,18 @@
sufficient to cause that definition to create a generator function
instead of a normal function.
-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
-\method{next()} method repeatedly until it raises an exception.
+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 \method{__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 \grammartoken{expression_list} is
-returned to \method{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 \method{next()} is
-invoked, the function can proceed exactly as if the \keyword{yield}
-statement were just another external call.
+When a \keyword{yield} statement is executed, the state of the generator is
+frozen and the value of \grammartoken{expression_list} is returned to
+\method{__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 \method{__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} ...\
diff --git a/Doc/tut/glossary.tex b/Doc/tut/glossary.tex
index 738e12d..a19416b 100644
--- a/Doc/tut/glossary.tex
+++ b/Doc/tut/glossary.tex
@@ -117,7 +117,7 @@
\keyword{yield} elements back to the caller. The function execution is
stopped at the {}\keyword{yield} keyword (returning the result) and is
resumed there when the next element is requested by calling the
-\method{next()} method of the returned iterator.
+\method{__next__()} method of the returned iterator.
\index{generator expression}
\item[generator expression]
@@ -207,10 +207,10 @@
\index{iterator}
\item[iterator]
An object representing a stream of data. Repeated calls to the
-iterator's \method{next()} method return successive items in the
+iterator's \method{__next__()} method return successive items in the
stream. When no more data is available a \exception{StopIteration}
exception is raised instead. At this point, the iterator object is
-exhausted and any further calls to its \method{next()} method just
+exhausted and any further calls to its \method{__next__()} method just
raise \exception{StopIteration} again. Iterators are required to have
an \method{__iter__()} method that returns the iterator object
itself so every iterator is also iterable and may be used in most
diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index a0b75c6..4abd0bd 100644
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -4488,34 +4488,35 @@
pervades and unifies Python. Behind the scenes, the \keyword{for}
statement calls \function{iter()} on the container object. The
function returns an iterator object that defines the method
-\method{next()} which accesses elements in the container one at a
-time. When there are no more elements, \method{next()} raises a
+\method{__next__()} which accesses elements in the container one at a
+time. When there are no more elements, \method{__next__()} raises a
\exception{StopIteration} exception which tells the \keyword{for} loop
-to terminate. This example shows how it all works:
+to terminate. You can call the \method{__next__()} method using the
+\function{next()} builtin; this example shows how it all works:
\begin{verbatim}
>>> s = 'abc'
>>> it = iter(s)
>>> it
<iterator object at 0x00A1DB50>
->>> it.next()
+>>> next(it)
'a'
->>> it.next()
+>>> next(it)
'b'
->>> it.next()
+>>> next(it)
'c'
->>> it.next()
+>>> next(it)
Traceback (most recent call last):
File "<stdin>", line 1, in ?
- it.next()
+ next(it)
StopIteration
\end{verbatim}
Having seen the mechanics behind the iterator protocol, it is easy to add
iterator behavior to your classes. Define a \method{__iter__()} method
-which returns an object with a \method{next()} method. If the class defines
-\method{next()}, then \method{__iter__()} can just return \code{self}:
+which returns an object with a \method{__next__()} method. If the class defines
+\method{__next__()}, then \method{__iter__()} can just return \code{self}:
\begin{verbatim}
class Reverse:
@@ -4525,7 +4526,7 @@
self.index = len(data)
def __iter__(self):
return self
- def next(self):
+ def __next__(self):
if self.index == 0:
raise StopIteration
self.index = self.index - 1
@@ -4545,7 +4546,7 @@
Generators 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 \method{next()} is called, the
+they want to return data. Each time \function{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:
@@ -4566,7 +4567,7 @@
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 \method{__iter__()} and \method{next()} methods are
+compact is that the \method{__iter__()} and \method{__next__()} methods are
created automatically.
Another key feature is that the local variables and execution state