# HG changeset patch # User Zbigniew Jędrzejewski-Szmek # Date 1316548109 -7200 # Branch pep380 # Node ID a98ba324e042bf185103a220617b214cb2bce9c1 # Parent 4f685c6944b131c24e955b14914d8acba5fbd60c Fix references to __next__, __iter__, and nearby references In conversion from python 2 documentation, references to the next() method where automatically converted to references to __next__(), which are broken, because there's no top-level __next__. Previously they worked, sort-of, by accident: sphinx doesn't distinguish between methods and functions, so :meth:`next` would refer to the built-in next function. Likewise, attempted references to iterator.__iter__() worked, sort-of, because :meth:`__iter__` would link to object.__iter__. In reality those two methods are completely different: one returns a new iterator, the other one has to return self. Their _meaning_ is different, so it is important to link to the right one based upon context. In some situations, __next__ and __iter__ should link to generator not iterator methods. I've also attempted to improve some nearby links, especially when I would reflow the paragraph anyway after changing links to the iterator methods which often increased the line length far past the 80 column limit. [Text is not reflowed in this patch version.] --- diff --git a/Doc/glossary.rst b/Doc/glossary.rst --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -340,26 +340,27 @@ An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as :class:`list`, :class:`str`, and :class:`tuple`) and some non-sequence - types like :class:`dict` and :class:`file` and objects of any classes you - define with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables + types like :class:`dict` and :term:`file ` and objects of any classes you + define with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables can be used in a :keyword:`for` loop and in many other places where a sequence is needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed as an argument to the built-in function :func:`iter`, it returns an iterator for the object. This iterator is good for one pass over the set of values. When using iterables, it is usually not necessary - to call :func:`iter` or deal with iterator objects yourself. The ``for`` + to call :func:`iter` or deal with iterator objects yourself. The :keyword:`for` statement does that automatically for you, creating a temporary unnamed - variable to hold the iterator for the duration of the loop. See also - :term:`iterator`, :term:`sequence`, and :term:`generator`. + variable to hold the iterator for the duration of the loop. + + See also :term:`iterator`, :term:`sequence`, and :term:`generator`. 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 - :meth:`__next__` method just raise :exc:`StopIteration` again. Iterators - are required to have an :meth:`__iter__` method that returns the iterator + :meth:`~iterator.__next__` method just raise :exc:`StopIteration` again. Iterators + are required to have an :meth:`~iterator.__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 which attempts multiple iteration passes. A container object (such as a diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -67,7 +67,7 @@ statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all side effects. Printing to the screen or writing to a disk file are side effects, for example. For example, in Python a call to the :func:`print` or -:func:`time.sleep` function both return no useful value; they're only called for +:func:`time.sleep` functions both return no useful value; they're only called for their side effects of sending some text to the screen or pausing execution for a second. @@ -181,9 +181,9 @@ 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 returns the next element of -the stream. If there are no more elements in the stream, ``__next__()`` must -raise the ``StopIteration`` exception. Iterators don't have to be finite, +:obj:`~iterator.__next__` that takes no arguments and always returns the next element of +the stream. If there are no more elements in the stream, :obj:`~iterator.__next__` must +raise the :exc:`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. @@ -243,17 +243,17 @@ (1, 2, 3) Built-in functions such as :func:`max` and :func:`min` can take a single -iterator argument and will return the largest or smallest element. The ``"in"`` -and ``"not in"`` operators also support iterators: ``X in iterator`` is true if -X is found in the stream returned by the iterator. You'll run into obvious -problems if the iterator is infinite; ``max()``, ``min()``, and ``"not in"`` -will never return, and if the element X never appears in the stream, the -``"in"`` operator won't return either. +iterator argument and will return the largest or smallest element. The :keyword:`in` +and :keyword:`not in` operators also support iterators: ``X in iterator`` is true if +``X`` is found in the stream returned by the iterator. You'll run into obvious +problems if the iterator is infinite; :func:`max`, :func:`min`, and :keyword:`not in` +will never return, and if the element ``X`` never appears in the stream, the +:keyword:`in` operator 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. Functions may therefore consume all of +only specifies the :obj:`~iterator.__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. @@ -454,17 +454,17 @@ for i in range(N): yield i -Any function containing a ``yield`` keyword is a generator function; this is +Any function containing a :keyword:`yield` keyword is a generator function; this is detected by Python's :term:`bytecode` compiler which compiles the function specially as a result. When you call a generator function, it doesn't return a single value; instead it returns a generator object that supports the iterator protocol. On executing -the ``yield`` expression, the generator 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 +the :keyword:`yield` expression, the generator outputs the value of ``i``, similar to a +:keyword:`return` statement. The big difference between :keyword:`yield` and a :keyword:`return` +statement is that on reaching a :keyword:`yield` the generator's state of execution is suspended and local variables are preserved. On the next call to the -generator's ``.__next__()`` method, the function will resume executing. +generator's `~generator.__next__` method, the function will resume executing. Here's a sample usage of the ``generate_ints()`` generator: @@ -486,9 +486,9 @@ You could equally write ``for i in generate_ints(5)``, or ``a,b,c = generate_ints(3)``. -Inside a generator function, the ``return`` statement can only be used without a +Inside a generator function, the :keyword:`return` statement can only be used without a value, and signals the end of the procession of values; after executing a -``return`` the generator cannot return any further values. ``return`` with a +:keyword:`return` the generator cannot return any further values. :keyword:`return` with a value, such as ``return 5``, is a syntax error inside a generator function. The end of the generator's results can also be indicated by raising ``StopIteration`` manually, or by just letting the flow of execution fall off @@ -539,21 +539,21 @@ val = (yield i) -I recommend that you **always** put parentheses around a ``yield`` expression +I recommend that you **always** put parentheses around a :keyword:`yield` expression when you're doing something with the returned value, as in the above example. The parentheses aren't always necessary, but it's easier to always add them instead of having to remember when they're needed. -(PEP 342 explains the exact rules, which are that a ``yield``-expression must +(:PEP:`342` explains the exact rules, which are that a :keyword:`yield`-expression must always be parenthesized except when it occurs at the top-level expression on the right-hand side of an assignment. This means you can write ``val = yield i`` but have to use parentheses when there's an operation, as in ``val = (yield i) + 12``.) -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 ``yield`` -returns ``None``. +Values are sent into a generator by calling its :obj:`send(value) ` method. This +method resumes the generator's code and the :keyword:`yield` expression returns +the specified value. If the regular :meth:`~generator.__next__` method is called, the :keyword:`yield` +returns :obj:`None`. Here's a simple counter that increments by 1 and allows changing the value of the internal counter. @@ -587,21 +587,21 @@ it.next() StopIteration -Because ``yield`` will often be returning ``None``, you should always check for +Because :keyword:`yield` will often be returning ``None``, you should always check for this case. Don't just use its value in expressions unless you're sure that the ``send()`` method will be the only method used resume your generator function. In addition to ``send()``, there are two other new methods on generators: -* ``throw(type, value=None, traceback=None)`` is used to raise an exception - inside the generator; the exception is raised by the ``yield`` expression +* :obj:`throw(type, value=None, traceback=None) ` is used to raise an exception + inside the generator; the exception is raised by the :keyword:`yield` expression where the generator's execution is paused. -* ``close()`` raises a :exc:`GeneratorExit` exception inside the generator to - terminate the iteration. On receiving this exception, the generator's code +* :meth:`~generator.close` raises a :exc:`GeneratorExit` exception inside the generator to + terminate the iteration. On receiving this exception, the generator's code must either raise :exc:`GeneratorExit` or :exc:`StopIteration`; catching the exception and doing anything else is illegal and will trigger a - :exc:`RuntimeError`. ``close()`` will also be called by Python's garbage + :exc:`RuntimeError`. :meth:`~generator.close` will also be called by Python's garbage collector when the generator is garbage-collected. If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I suggest @@ -612,8 +612,8 @@ Generators also become **coroutines**, a more generalized form of subroutines. Subroutines are entered at one point and exited at another point (the top of the -function, and a ``return`` statement), but coroutines can be entered, exited, -and resumed at many different points (the ``yield`` statements). +function, and a :keyword:`return` statement), but coroutines can be entered, exited, +and resumed at many different points (the :keyword:`yield` statements). Built-in functions diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -255,9 +255,9 @@ .. 2to3fixer:: next - Converts the use of iterator's :meth:`~iterator.next` methods to the - :func:`next` function. It also renames :meth:`next` methods to - :meth:`~object.__next__`. + Converts the use of iterator's :meth:`next ` methods to the + :func:`next` function. It also renames :meth:`!next` methods to + :meth:`~iterator.__next__`. .. 2to3fixer:: nonzero diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -90,7 +90,8 @@ .. class:: Iterator - ABC for classes that provide the :meth:`__iter__` and :meth:`next` methods. + ABC for classes that provide the :meth:`~iterator.__iter__` and :meth:`~iterator.__next__` methods. + See also the definition of :term:`iterator`. .. class:: Sequence @@ -101,7 +102,7 @@ .. class:: Set MutableSet - ABCs for read-only and mutable sets. + ABCs for :class:`read-only ` and :class:`mutable sets `. .. class:: Mapping MutableMapping diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -42,7 +42,7 @@ 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 + 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 @@ -364,7 +364,7 @@ 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 + 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. diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -50,7 +50,7 @@ Return a reader object which will iterate over lines in the given *csvfile*. *csvfile* can be any object which supports the :term:`iterator` protocol and returns a - string each time its :meth:`!__next__` method is called --- :term:`file objects + string each time its :meth:`~iterator.__next__` method is called --- :term:`file objects ` and list objects are both suitable. If *csvfile* is a file object, it should be opened with ``newline=''``. [1]_ An optional *dialect* parameter can be given which is used to define a set of parameters diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -714,7 +714,7 @@ .. opcode:: FOR_ITER (delta) - ``TOS`` is an :term:`iterator`. Call its :meth:`__next__` method. If this + ``TOS`` is an :term:`iterator`. Call its :obj:`~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*. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -40,11 +40,11 @@ .. index:: single: None (Built-in object) -* ``None`` +* :const:`None` .. index:: single: False (Built-in object) -* ``False`` +* :const:`False` * zero of any numeric type, for example, ``0``, ``0.0``, ``0j``. @@ -67,9 +67,9 @@ single: False single: True -Operations and built-in functions that have a Boolean result always return ``0`` -or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated. -(Important exception: the Boolean operations ``or`` and ``and`` always return +Operations and built-in functions that have a Boolean result always return :obj:`0 ` +or :const:`False` for false and :obj:`1 ` or :const:`True` for true, unless otherwise stated. +(Important exception: the Boolean operations :keyword:`or` and :keyword:`and` always return one of their operands.) @@ -111,7 +111,7 @@ argument if the first one is :const:`True`. (3) - ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is + :keyword:`not` has a lower priority than non-Boolean operators, so ``not a == b`` is interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. @@ -775,7 +775,7 @@ specific types are not important beyond their implementation of the iterator protocol. -Once an iterator's :meth:`__next__` method raises :exc:`StopIteration`, it must +Once an iterator's :obj:`~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. @@ -786,9 +786,9 @@ --------------- 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 +protocol. If a container object's :obj:`~object.__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 :obj:`~iterator.__iter__` and :obj:`~iterator.__next__` methods. More information about generators can be found in :ref:`the documentation for the yield expression `. diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -588,7 +588,7 @@ 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 + body of the function: calling the iterator's :obj:`~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` diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -294,12 +294,12 @@ 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 +:meth:`~iterator.__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 +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 diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -414,10 +414,10 @@ :keyword:`return` may only occur syntactically nested in a function definition, not within a nested class definition. -If an expression list is present, it is evaluated, else ``None`` is substituted. +If an expression list is present, it is evaluated, else :const:`None` is substituted. :keyword:`return` leaves the current function call with the expression list (or -``None``) as return value. +:const:`None`) as return value. .. index:: keyword: finally diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -735,10 +735,10 @@ 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__` +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:`~iterator.__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` +terminate. You can call the :meth:`~iterator.__next__` method using the :func:`next` built-in function; this example shows how it all works:: >>> s = 'abc' @@ -759,8 +759,8 @@ 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.""" @@ -817,7 +817,7 @@ 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 +compact is that the :meth:`~iterator.__iter__` and :meth:`~iterator.__next__` methods are created automatically. Another key feature is that the local variables and execution state are diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst --- a/Doc/whatsnew/3.0.rst +++ b/Doc/whatsnew/3.0.rst @@ -758,8 +758,8 @@ :meth:`__delitem__`, when used as an assignment or deletion target, respectively). -* :pep:`3114`: the standard :meth:`next` method has been renamed to - :meth:`__next__`. +* :pep:`3114`: the standard :meth:`!next` method has been renamed to + :meth:`~iterator.__next__`. * The :meth:`__oct__` and :meth:`__hex__` special methods are removed -- :func:`oct` and :func:`hex` use :meth:`__index__` now to convert