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

Author: birkenfeld

Doc/api/newtypes.tex

@@ -1071,7 +1071,7 @@ \section{Type Objects \label{type-structs}}
   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

Doc/howto/functional.rst

@@ -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,21 +487,21 @@ 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::
 
     >>> 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

Doc/lib/libcollections.tex

@@ -174,7 +174,7 @@ \subsubsection{Recipes \label{deque-recipes}}
     while pending:
         task = pending.popleft()
         try:
-            yield task.next()
+            yield next(task)
         except StopIteration:
             continue
         pending.append(task)
@@ -315,12 +315,12 @@ \subsubsection{\class{defaultdict} Examples \label{defaultdict-examples}}
 
 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

Doc/lib/libcsv.tex

@@ -487,8 +487,8 @@ \subsection{Examples\label{csv-examples}}
     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 @@ \subsection{Examples\label{csv-examples}}
         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):

Doc/lib/libdis.tex

@@ -529,10 +529,10 @@ \subsection{Python Byte Code Instructions}
 \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}

Doc/lib/libexcs.tex

@@ -265,8 +265,8 @@ \section{Built-in Exceptions}
 \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.

Doc/lib/libfuncs.tex

@@ -342,14 +342,12 @@ \section{Built-in Functions \label{built-in-funcs}}
 \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 @@ \section{Built-in Functions \label{built-in-funcs}}
   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 @@ \section{Built-in Functions \label{built-in-funcs}}
   \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

Doc/lib/libitertools.tex

@@ -164,16 +164,16 @@ \subsection{Itertool functions \label{itertools-functions}}
             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 @@ \subsection{Itertool functions \label{itertools-functions}}
      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 @@ \subsection{Itertool functions \label{itertools-functions}}
      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 @@ \subsection{Itertool functions \label{itertools-functions}}
      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 @@ \subsection{Itertool functions \label{itertools-functions}}
   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 @@ \subsection{Itertool functions \label{itertools-functions}}
      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 @@ \subsection{Itertool functions \label{itertools-functions}}
                      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 @@ \subsection{Recipes \label{itertools-recipes}}
 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):

Doc/lib/libstdtypes.tex

@@ -388,18 +388,17 @@ \section{Iterator Types \label{typeiter}}
 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 @@ \section{File Objects
   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.

Doc/lib/sqlite3/executemany_1.py

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