diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/api/newtypes.tex | 2 | ||||
| -rw-r--r-- | Doc/howto/functional.rst | 40 | ||||
| -rw-r--r-- | Doc/lib/libcollections.tex | 6 | ||||
| -rw-r--r-- | Doc/lib/libcsv.tex | 8 | ||||
| -rw-r--r-- | Doc/lib/libdis.tex | 8 | ||||
| -rw-r--r-- | Doc/lib/libexcs.tex | 4 | ||||
| -rw-r--r-- | Doc/lib/libfuncs.tex | 22 | ||||
| -rw-r--r-- | Doc/lib/libitertools.tex | 25 | ||||
| -rw-r--r-- | Doc/lib/libstdtypes.tex | 29 | ||||
| -rw-r--r-- | Doc/lib/sqlite3/executemany_1.py | 2 | ||||
| -rw-r--r-- | Doc/ref/ref3.tex | 2 | ||||
| -rw-r--r-- | Doc/ref/ref5.tex | 2 | ||||
| -rw-r--r-- | Doc/ref/ref6.tex | 25 | ||||
| -rw-r--r-- | Doc/tut/glossary.tex | 6 | ||||
| -rw-r--r-- | Doc/tut/tut.tex | 27 |
15 files changed, 105 insertions, 103 deletions
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 @@ 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 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 @@ 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 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 @@ 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 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 @@ 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): 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 @@ 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} 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 @@ 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. 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 @@ 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 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 @@ 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): 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 @@ 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. 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 @@ class IterChars: 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 @@ 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 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 @@ 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 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 @@ 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 \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 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. 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 @@ 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 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 @@ 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 |