diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/glossary.rst | 2 | ||||
| -rw-r--r-- | Doc/library/concurrent.futures.rst | 22 | ||||
| -rw-r--r-- | Doc/library/dis.rst | 8 | ||||
| -rw-r--r-- | Doc/library/exceptions.rst | 2 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 21 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 9 | ||||
| -rw-r--r-- | Doc/reference/datamodel.rst | 6 | ||||
| -rw-r--r-- | Doc/reference/expressions.rst | 23 | ||||
| -rw-r--r-- | Doc/tutorial/classes.rst | 18 | ||||
| -rw-r--r-- | Doc/whatsnew/3.0.rst | 4 |
10 files changed, 60 insertions, 55 deletions
diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 2151350..3c11de7 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -354,7 +354,7 @@ Glossary iterator An object representing a stream of data. Repeated calls to the iterator's - :meth:`__next__` method (or passing it to the built-in function + :meth:`~iterator.__next__` method (or passing it to the built-in function :func:`next`) return successive items in the stream. When no more data are available a :exc:`StopIteration` exception is raised instead. At this point, the iterator object is exhausted and any further calls to its diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index 29ffc0d..eee2285 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -42,12 +42,13 @@ Executor Objects Equivalent to ``map(func, *iterables)`` except *func* is executed asynchronously and several calls to *func* may be made concurrently. The - returned iterator raises a :exc:`TimeoutError` if :meth:`__next__()` is - called and the result isn't available after *timeout* seconds from the - original call to :meth:`Executor.map`. *timeout* can be an int or a - float. If *timeout* is not specified or ``None``, there is no limit to - the wait time. If a call raises an exception, then that exception will - be raised when its value is retrieved from the iterator. + returned iterator raises a :exc:`TimeoutError` if + :meth:`~iterator.__next__` is called and the result isn't available + after *timeout* seconds from the original call to :meth:`Executor.map`. + *timeout* can be an int or a float. If *timeout* is not specified or + ``None``, there is no limit to the wait time. If a call raises an + exception, then that exception will be raised when its value is + retrieved from the iterator. .. method:: shutdown(wait=True) @@ -358,10 +359,11 @@ Module Functions different :class:`Executor` instances) given by *fs* that yields futures as they complete (finished or were cancelled). Any futures that completed before :func:`as_completed` is called will be yielded first. The returned - iterator raises a :exc:`TimeoutError` if :meth:`__next__` is called and the - result isn't available after *timeout* seconds from the original call to - :func:`as_completed`. *timeout* can be an int or float. If *timeout* is not - specified or ``None``, there is no limit to the wait time. + iterator raises a :exc:`TimeoutError` if :meth:`~iterator.__next__` is + called and the result isn't available after *timeout* seconds from the + original call to :func:`as_completed`. *timeout* can be an int or float. + If *timeout* is not specified or ``None``, there is no limit to the wait + time. .. seealso:: diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 79cc583..108cda7 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -658,10 +658,10 @@ the more significant byte last. .. opcode:: FOR_ITER (delta) - ``TOS`` is an :term:`iterator`. Call its :meth:`__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 ``TOS`` is popped, and the byte code - counter is incremented by *delta*. + ``TOS`` is an :term:`iterator`. Call its :meth:`~iterator.__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 ``TOS`` is popped, and the + byte code counter is incremented by *delta*. .. opcode:: LOAD_GLOBAL (namei) diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index ca3ad3e..7d622c2 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -262,7 +262,7 @@ The following exceptions are the exceptions that are usually raised. .. exception:: StopIteration Raised by built-in function :func:`next` and an :term:`iterator`\'s - :meth:`__next__` method to signal that there are no further values. + :meth:`~iterator.__next__` method to signal that there are no further values. .. exception:: SyntaxError diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 2575d7f..572706a 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -346,10 +346,10 @@ are always available. They are listed here in alphabetical order. .. function:: enumerate(iterable, start=0) Return an enumerate object. *iterable* must be a sequence, an - :term:`iterator`, or some other object which supports iteration. The - :meth:`__next__` method of the iterator returned by :func:`enumerate` returns a - tuple containing a count (from *start* which defaults to 0) and the - values obtained from iterating over *iterable*. + :term:`iterator`, or some other object which supports iteration. + The :meth:`~iterator.__next__` method of the iterator returned by + :func:`enumerate` returns a tuple containing a count (from *start* which + defaults to 0) and the values obtained from iterating over *iterable*. >>> seasons = ['Spring', 'Summer', 'Fall', 'Winter'] >>> list(enumerate(seasons)) @@ -681,9 +681,10 @@ are always available. They are listed here in alphabetical order. starting at ``0``). If it does not support either of those protocols, :exc:`TypeError` is raised. If the second argument, *sentinel*, is given, then *object* must be a callable object. The iterator created in this case - will call *object* with no arguments for each call to its :meth:`__next__` - method; if the value returned is equal to *sentinel*, :exc:`StopIteration` - will be raised, otherwise the value will be returned. + will call *object* with no arguments for each call to its + :meth:`~iterator.__next__` method; if the value returned is equal to + *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will + be returned. One useful application of the second form of :func:`iter` is to read lines of a file until a certain line is reached. The following example reads a file @@ -781,9 +782,9 @@ are always available. They are listed here in alphabetical order. .. function:: next(iterator[, default]) - Retrieve the next item from the *iterator* by calling its :meth:`__next__` - method. If *default* is given, it is returned if the iterator is exhausted, - otherwise :exc:`StopIteration` is raised. + Retrieve the next item from the *iterator* by calling its + :meth:`~iterator.__next__` method. If *default* is given, it is returned + if the iterator is exhausted, otherwise :exc:`StopIteration` is raised. .. function:: object() diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 9688393..7d47ec7 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -775,9 +775,9 @@ specific sequence types, dictionaries, and other more specialized forms. The specific types are not important beyond their implementation of the iterator protocol. -Once an iterator's :meth:`__next__` method raises :exc:`StopIteration`, it must -continue to do so on subsequent calls. Implementations that do not obey this -property are deemed broken. +Once an iterator's :meth:`~iterator.__next__` method raises +:exc:`StopIteration`, it must continue to do so on subsequent calls. +Implementations that do not obey this property are deemed broken. .. _generator-types: @@ -788,7 +788,8 @@ Generator Types Python's :term:`generator`\s provide a convenient way to implement the iterator protocol. If a container object's :meth:`__iter__` method is implemented as a generator, it will automatically return an iterator object (technically, a -generator object) supplying the :meth:`__iter__` and :meth:`__next__` methods. +generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__` +methods. More information about generators can be found in :ref:`the documentation for the yield expression <yieldexpr>`. diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index ea2e078..322e8c8 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -588,9 +588,9 @@ Callable types A function or method which uses the :keyword:`yield` statement (see section :ref:`yield`) 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 :meth:`__next__` method will - cause the function to execute until it provides a value using the - :keyword:`yield` statement. When the function executes a + body of the function: calling the iterator's :meth:`iterator__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 :exc:`StopIteration` exception is raised and the iterator will have reached the end of the set of values to be returned. diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index e359237..2c6acb6 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -294,13 +294,13 @@ for comprehensions, except that it is enclosed in parentheses instead of brackets or curly braces. Variables used in the generator expression are evaluated lazily when the -:meth:`__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 an error produced by it can be seen before any other possible -error in the code that handles the generator expression. Subsequent -:keyword:`for` clauses cannot be evaluated immediately since they may depend on -the previous :keyword:`for` loop. For example: ``(x*y for x in range(10) for y -in bar(x))``. +:meth:`~generator.__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 an error produced by it can be seen before any +other possible error in the code that handles the generator expression. +Subsequent :keyword:`for` clauses cannot be evaluated immediately since they +may depend on the previous :keyword:`for` loop. For example: ``(x*y for x in +range(10) for y in bar(x))``. The parentheses can be omitted on calls with only one argument. See section :ref:`calls` for the detail. @@ -371,10 +371,11 @@ is already executing raises a :exc:`ValueError` exception. Starts the execution of a generator function or resumes it at the last executed :keyword:`yield` expression. When a generator function is resumed - with a :meth:`__next__` method, the current :keyword:`yield` expression - always evaluates to :const:`None`. The execution then continues to the next - :keyword:`yield` expression, where the generator is suspended again, and the - value of the :token:`expression_list` is returned to :meth:`next`'s caller. + with a :meth:`~generator.__next__` method, the current :keyword:`yield` + expression always evaluates to :const:`None`. The execution then continues + to the next :keyword:`yield` expression, where the generator is suspended + again, and the value of the :token:`expression_list` is returned to + :meth:`next`'s caller. If the generator exits without yielding another value, a :exc:`StopIteration` exception is raised. diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst index 5ce3669..cff2710 100644 --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -738,11 +738,11 @@ using a :keyword:`for` statement:: 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 :func:`iter` on the container object. The function returns an iterator -object that defines the method :meth:`__next__` which accesses elements in the -container one at a time. When there are no more elements, :meth:`__next__` -raises a :exc:`StopIteration` exception which tells the :keyword:`for` loop to -terminate. You can call the :meth:`__next__` method using the :func:`next` -built-in function; this example shows how it all works:: +object that defines the method :meth:`~iterator.__next__` which accesses +elements in the container one at a time. When there are no more elements, +:meth:`__next__` raises a :exc:`StopIteration` exception which tells the +:keyword:`for` loop to terminate. You can call the :meth:`__next__` method +using the :func:`next` built-in function; this example shows how it all works:: >>> s = 'abc' >>> it = iter(s) @@ -762,8 +762,8 @@ built-in function; this example shows how it all works:: Having seen the mechanics behind the iterator protocol, it is easy to add iterator behavior to your classes. Define an :meth:`__iter__` method which -returns an object with a :meth:`__next__` method. If the class defines -:meth:`__next__`, then :meth:`__iter__` can just return ``self``:: +returns an object with a :meth:`~iterator.__next__` method. If the class +defines :meth:`__next__`, then :meth:`__iter__` can just return ``self``:: class Reverse: """Iterator for looping over a sequence backwards.""" @@ -820,8 +820,8 @@ easy to create:: 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 :meth:`__iter__` and :meth:`__next__` methods are created -automatically. +compact is that the :meth:`__iter__` and :meth:`~generator.__next__` methods +are created automatically. Another key feature is that the local variables and execution state are automatically saved between calls. This made the function easier to write and diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst index 55b65ba..9f1ec97 100644 --- a/Doc/whatsnew/3.0.rst +++ b/Doc/whatsnew/3.0.rst @@ -771,7 +771,7 @@ Operators And Special Methods respectively). * :pep:`3114`: the standard :meth:`next` method has been renamed to - :meth:`__next__`. + :meth:`~iterator.__next__`. * The :meth:`__oct__` and :meth:`__hex__` special methods are removed -- :func:`oct` and :func:`hex` use :meth:`__index__` now to convert @@ -807,7 +807,7 @@ Builtins To get the old behavior of :func:`input`, use ``eval(input())``. * A new built-in function :func:`next` was added to call the - :meth:`__next__` method on an object. + :meth:`~iterator.__next__` method on an object. * The :func:`round` function rounding strategy and return type have changed. Exact halfway cases are now rounded to the nearest even |