PEP 3114: rename .next() to .__next__() and add next() builtin.

This commit is contained in:
Georg Brandl
2007-04-21 15:47:16 +00:00
parent 4d2adcca52
commit a18af4e7a2
83 changed files with 495 additions and 425 deletions

View File

@@ -1071,7 +1071,7 @@ The next two fields only exist if the
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

View File

@@ -199,11 +199,13 @@ foundation for writing functional-style programs: iterators.
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 @@ You can experiment with the iteration interface manually::
>>> 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 @@ won't return either.
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 @@ outputs the value of ``i``, similar to a ``return``
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 @@ Here's a sample usage of the ``generate_ints()`` generator::
>>> 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 @@ You could achieve the effect of generators manually by writing your
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 @@ use parentheses when there's an operation, as in ``val = (yield i)
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 @@ value of the internal counter.
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

View File

@@ -174,7 +174,7 @@ def roundrobin(*iterables):
while pending:
task = pending.popleft()
try:
yield task.next()
yield next(task)
except StopIteration:
continue
pending.append(task)
@@ -315,12 +315,12 @@ letter.
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

View File

@@ -487,8 +487,8 @@ class UTF8Recoder:
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 @@ class UnicodeReader:
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):

View File

@@ -529,10 +529,10 @@ Set byte code counter to \var{target}.
\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}

View File

@@ -265,8 +265,8 @@ Raised when an \keyword{assert} statement fails.
\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.

View File

@@ -342,14 +342,12 @@ class C:
\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 @@ class C:
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 @@ class C:
\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

View File

@@ -164,16 +164,16 @@ by functions or loops that truncate the stream.
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 @@ by functions or loops that truncate the stream.
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 @@ by functions or loops that truncate the stream.
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 @@ by functions or loops that truncate the stream.
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 @@ by functions or loops that truncate the stream.
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 @@ by functions or loops that truncate the stream.
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 @@ by functions or loops that truncate the stream.
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 repeatfunc(func, times=None, *args):
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):

View File

@@ -388,18 +388,17 @@ general and specific sequence types, dictionaries, and other more
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 @@ finally:
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.

View File

@@ -7,7 +7,7 @@ class IterChars:
def __iter__(self):
return self
def next(self):
def __next__(self):
if self.count > ord('z'):
raise StopIteration
self.count += 1

View File

@@ -633,7 +633,7 @@ A function or method which uses the \keyword{yield} statement (see
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

View File

@@ -222,7 +222,7 @@ evaluating the expression to yield a value that is reached the
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

View File

@@ -418,19 +418,18 @@ Using a \keyword{yield} statement in a function definition is
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} ...\

View File

@@ -117,7 +117,7 @@ contain one or more {}\keyword{for} or \keyword{while} loops that
\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 @@ hold the iterator for the duration of the loop. See also
\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

View File

@@ -4488,34 +4488,35 @@ 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 \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 @@ class Reverse:
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 @@ s
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 @@ g
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

View File

@@ -64,10 +64,10 @@ class StringIO:
def __iter__(self):
return self
def next(self):
def __next__(self):
"""A file object is its own iterator, for example iter(f) returns f
(unless f is closed). When a file is used as an iterator, typically
in a for loop (for example, for line in f: print line), the next()
in a for loop (for example, for line in f: print line), the __next__()
method is called repeatedly. This method returns the next input line,
or raises StopIteration when EOF is hit.
"""

View File

@@ -139,7 +139,7 @@ class DictMixin:
return value
def popitem(self):
try:
k, v = self.iteritems().next()
k, v = next(self.iteritems())
except StopIteration:
raise KeyError, 'container is empty'
del self[k]

View File

@@ -600,7 +600,7 @@ class StreamReader(Codec):
self.reset()
self.stream.seek(offset, whence)
def next(self):
def __next__(self):
""" Return the next decoded line from the input stream."""
line = self.readline()
@@ -669,10 +669,10 @@ class StreamReaderWriter:
return self.reader.readlines(sizehint)
def next(self):
def __next__(self):
""" Return the next decoded line from the input stream."""
return self.reader.next()
return next(self.reader)
def __iter__(self):
return self
@@ -782,10 +782,10 @@ class StreamRecoder:
data, bytesencoded = self.encode(data, self.errors)
return data.splitlines(1)
def next(self):
def __next__(self):
""" Return the next decoded line from the input stream."""
data = self.reader.next()
data = next(self.reader)
data, bytesencoded = self.encode(data, self.errors)
return data

View File

@@ -12,14 +12,14 @@ class GeneratorContextManager(object):
def __enter__(self):
try:
return self.gen.next()
return next(self.gen)
except StopIteration:
raise RuntimeError("generator didn't yield")
def __exit__(self, type, value, traceback):
if type is None:
try:
self.gen.next()
next(self.gen)
except StopIteration:
return
else:

View File

@@ -79,17 +79,17 @@ class DictReader:
def __iter__(self):
return self
def next(self):
row = self.reader.next()
def __next__(self):
row = next(self.reader)
if self.fieldnames is None:
self.fieldnames = row
row = self.reader.next()
row = next(self.reader)
# unlike the basic reader, we prefer not to return blanks,
# because we will typically wind up with a dict full of None
# values
while row == []:
row = self.reader.next()
row = next(self.reader)
d = dict(zip(self.fieldnames, row))
lf = len(self.fieldnames)
lr = len(row)
@@ -351,7 +351,7 @@ class Sniffer:
rdr = reader(StringIO(sample), self.sniff(sample))
header = rdr.next() # assume first row is header
header = next(rdr) # assume first row is header
columns = len(header)
columnTypes = {}

Some files were not shown because too many files have changed in this diff Show More