From: Serhiy Storchaka Date: Fri, 5 Sep 2014 20:34:12 +0000 (+0300) Subject: Issue #20643: Fixed references to the next() method (distinguish from the X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ea217728c3b00ddc4ceedd4a4c5c37a496a16b45;p=python Issue #20643: Fixed references to the next() method (distinguish from the next() function). --- diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index b545b061b2..fdd679f7c9 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -770,7 +770,7 @@ set. exception may or may not be set. When another error occurs, it must return *NULL* too. 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 :meth:`next` method). + they don't define a :meth:`~iterator.next` method). Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that function should return the iterator instance itself (not a new iterator diff --git a/Doc/glossary.rst b/Doc/glossary.rst index b5e8171783..ff8ebdeb8b 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -408,10 +408,10 @@ Glossary iterator An object representing a stream of data. Repeated calls to the iterator's - :meth:`next` method return successive items in the stream. When no more + :meth:`~generator.next` method 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 - :meth:`next` method just raise :exc:`StopIteration` again. Iterators are + :meth:`~generator.next` method just raise :exc:`StopIteration` again. Iterators are required to have an :meth:`__iter__` method that returns the iterator object itself so every iterator is also iterable and may be used in most places where other iterables are accepted. One notable exception is code diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index a927510ebd..73554264f1 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -289,7 +289,7 @@ and off individually. They are described here in more detail. .. 2to3fixer:: next Converts the use of iterator's :meth:`~iterator.next` methods to the - :func:`next` function. It also renames :meth:`next` methods to + :func:`next` function. It also renames :meth:`~iterator.next` methods to :meth:`~iterator.__next__`. .. 2to3fixer:: nonzero diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index f00b870c91..b947e272da 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -954,8 +954,8 @@ ABC Inherits from Abstract Methods Mixin .. class:: Iterator - ABC for classes that provide the :meth:`__iter__` and :meth:`next` methods. - See also the definition of :term:`iterator`. + ABC for classes that provide the :meth:`~iterator.__iter__` and + :meth:`~iterator.next` methods. See also the definition of :term:`iterator`. .. class:: Sequence MutableSequence diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index f229967068..56f0957be7 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -652,7 +652,7 @@ 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 :meth:`next` method +The intention of the protocol is that once an iterator's :meth:`~iterator.next` method raises :exc:`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 @@ -667,9 +667,9 @@ 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. More -information about generators can be found in :ref:`the documentation for the -yield expression `. +generator object) supplying the :meth:`~iterator.__iter__` and +:meth:`~iterator.next` methods. More information about generators can be found +in :ref:`the documentation for the yield expression `. .. _typesseq: diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index b4dacf8810..427a63ac2c 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -431,22 +431,21 @@ Note that calling any of the generator methods below when the generator is already executing raises a :exc:`ValueError` exception. .. index:: exception: StopIteration -.. class:: generator .. method:: generator.next() 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 + :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 + :token:`expression_list` is returned to :meth:`~generator.next`'s caller. + If the generator exits without yielding another value, a :exc:`StopIteration` exception is raised. -.. class:: . - .. method:: generator.send(value) Resumes the execution and "sends" a value into the generator function. The diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index d8e539d53c..0158e87100 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -506,16 +506,16 @@ 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 :meth:`next` method repeatedly until it -raises an exception. +executed by calling the generator's :meth:`~generator.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 :token:`expression_list` is returned to :meth:`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 :meth:`next` -is invoked, the function can proceed exactly as if the :keyword:`yield` -statement were just another external call. +frozen and the value of :token:`expression_list` is returned to +:meth:`~generator.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 :meth:`~generator.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` ... :keyword:`finally` construct. If diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst index 60d382c5b8..77c050b4cc 100644 --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -788,8 +788,8 @@ 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:`~iterator.next`, then :meth:`__iter__` can just return ``self``:: class Reverse: """Iterator for looping over a sequence backwards.""" @@ -825,7 +825,7 @@ Generators :term:`Generator`\s 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 :meth:`next` is called, the +whenever they want to return data. Each time :func:`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:: @@ -846,8 +846,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