[Python-checkins] r58582 - in python/trunk/Doc: howto/functional.rst library/codecs.rst library/compiler.rst library/contextlib.rst library/csv.rst library/difflib.rst library/dis.rst library/exceptions.rst library/itertools.rst library/os.path.rst library/sqlite3.rst library/stdtypes.rst library/tokenize.rst library/types.rst library/weakref.rst library/xmlrpclib.rst tutorial/classes.rst

[georg.brandl]

Author: georg.brandl
Date: Sun Oct 21 12:52:38 2007
New Revision: 58582

Modified:
   python/trunk/Doc/howto/functional.rst
   python/trunk/Doc/library/codecs.rst
   python/trunk/Doc/library/compiler.rst
   python/trunk/Doc/library/contextlib.rst
   python/trunk/Doc/library/csv.rst
   python/trunk/Doc/library/difflib.rst
   python/trunk/Doc/library/dis.rst
   python/trunk/Doc/library/exceptions.rst
   python/trunk/Doc/library/itertools.rst
   python/trunk/Doc/library/os.path.rst
   python/trunk/Doc/library/sqlite3.rst
   python/trunk/Doc/library/stdtypes.rst
   python/trunk/Doc/library/tokenize.rst
   python/trunk/Doc/library/types.rst
   python/trunk/Doc/library/weakref.rst
   python/trunk/Doc/library/xmlrpclib.rst
   python/trunk/Doc/tutorial/classes.rst
Log:
Add :term: for generators.


Modified: python/trunk/Doc/howto/functional.rst
==============================================================================
--- python/trunk/Doc/howto/functional.rst	(original)
+++ python/trunk/Doc/howto/functional.rst	Sun Oct 21 12:52:38 2007
@@ -13,8 +13,8 @@
 In this document, we'll take a tour of Python's features suitable for
 implementing programs in a functional style.  After an introduction to the
 concepts of functional programming, we'll look at language features such as
-iterators and generators and relevant library modules such as :mod:`itertools`
-and :mod:`functools`.
+iterators and :term:`generator`\s and relevant library modules such as
+:mod:`itertools` and :mod:`functools`.
 
 
 Introduction

Modified: python/trunk/Doc/library/codecs.rst
==============================================================================
--- python/trunk/Doc/library/codecs.rst	(original)
+++ python/trunk/Doc/library/codecs.rst	Sun Oct 21 12:52:38 2007
@@ -242,8 +242,8 @@
 .. function:: iterencode(iterable, encoding[, errors])
 
    Uses an incremental encoder to iteratively encode the input provided by
-   *iterable*. This function is a generator. *errors* (as well as any other keyword
-   argument) is passed through to the incremental encoder.
+   *iterable*. This function is a :term:`generator`.  *errors* (as well as any
+   other keyword argument) is passed through to the incremental encoder.
 
    .. versionadded:: 2.5
 
@@ -251,8 +251,8 @@
 .. function:: iterdecode(iterable, encoding[, errors])
 
    Uses an incremental decoder to iteratively decode the input provided by
-   *iterable*. This function is a generator. *errors* (as well as any other keyword
-   argument) is passed through to the incremental decoder.
+   *iterable*. This function is a :term:`generator`.  *errors* (as well as any
+   other keyword argument) is passed through to the incremental decoder.
 
    .. versionadded:: 2.5
 

Modified: python/trunk/Doc/library/compiler.rst
==============================================================================
--- python/trunk/Doc/library/compiler.rst	(original)
+++ python/trunk/Doc/library/compiler.rst	Sun Oct 21 12:52:38 2007
@@ -640,5 +640,5 @@
 call the :meth:`emit` method to emit a new bytecode.  The basic code generator
 is specialized for modules, classes, and functions.  An assembler converts that
 emitted instructions to the low-level bytecode format.  It handles things like
-generator of constant lists of code objects and calculation of jump offsets.
+generation of constant lists of code objects and calculation of jump offsets.
 

Modified: python/trunk/Doc/library/contextlib.rst
==============================================================================
--- python/trunk/Doc/library/contextlib.rst	(original)
+++ python/trunk/Doc/library/contextlib.rst	Sun Oct 21 12:52:38 2007
@@ -39,9 +39,9 @@
       foo
       </h1>
 
-   The function being decorated must return a generator-iterator when called. This
-   iterator must yield exactly one value, which will be bound to the targets in the
-   :keyword:`with` statement's :keyword:`as` clause, if any.
+   The function being decorated must return a :term:`generator`-iterator when
+   called. This iterator must yield exactly one value, which will be bound to
+   the targets in the :keyword:`with` statement's :keyword:`as` clause, if any.
 
    At the point where the generator yields, the block nested in the :keyword:`with`
    statement is executed.  The generator is then resumed after the block is exited.

Modified: python/trunk/Doc/library/csv.rst
==============================================================================
--- python/trunk/Doc/library/csv.rst	(original)
+++ python/trunk/Doc/library/csv.rst	Sun Oct 21 12:52:38 2007
@@ -442,9 +442,9 @@
 write functions or classes that handle the encoding and decoding for you as long
 as you avoid encodings like UTF-16 that use NULs.  UTF-8 is recommended.
 
-:func:`unicode_csv_reader` below is a generator that wraps :class:`csv.reader`
+:func:`unicode_csv_reader` below is a :term:`generator` that wraps :class:`csv.reader`
 to handle Unicode CSV data (a list of Unicode strings).  :func:`utf_8_encoder`
-is a generator that encodes the Unicode strings as UTF-8, one string (or row) at
+is a :term:`generator` that encodes the Unicode strings as UTF-8, one string (or row) at
 a time.  The encoded strings are parsed by the CSV reader, and
 :func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode::
 

Modified: python/trunk/Doc/library/difflib.rst
==============================================================================
--- python/trunk/Doc/library/difflib.rst	(original)
+++ python/trunk/Doc/library/difflib.rst	Sun Oct 21 12:52:38 2007
@@ -126,8 +126,8 @@
 
 .. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
 
-   Compare *a* and *b* (lists of strings); return a delta (a generator generating
-   the delta lines) in context diff format.
+   Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
+   generating the delta lines) in context diff format.
 
    Context diffs are a compact way of showing just the lines that have changed plus
    a few lines of context.  The changes are shown in a before/after style.  The
@@ -181,8 +181,8 @@
 
 .. function:: ndiff(a, b[, linejunk][, charjunk])
 
-   Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style delta
-   (a generator generating the delta lines).
+   Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style
+   delta (a :term:`generator` generating the delta lines).
 
    Optional keyword parameters *linejunk* and *charjunk* are for filter functions
    (or ``None``):
@@ -242,8 +242,8 @@
 
 .. function:: unified_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
 
-   Compare *a* and *b* (lists of strings); return a delta (a generator generating
-   the delta lines) in unified diff format.
+   Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
+   generating the delta lines) in unified diff format.
 
    Unified diffs are a compact way of showing just the lines that have changed plus
    a few lines of context.  The changes are shown in a inline style (instead of
@@ -442,7 +442,7 @@
 
 .. method:: SequenceMatcher.get_grouped_opcodes([n])
 
-   Return a generator of groups with up to *n* lines of context.
+   Return a :term:`generator` of groups with up to *n* lines of context.
 
    Starting with the groups returned by :meth:`get_opcodes`, this method splits out
    smaller change clusters and eliminates intervening ranges which have no changes.

Modified: python/trunk/Doc/library/dis.rst
==============================================================================
--- python/trunk/Doc/library/dis.rst	(original)
+++ python/trunk/Doc/library/dis.rst	Sun Oct 21 12:52:38 2007
@@ -482,7 +482,7 @@
 
 .. opcode:: YIELD_VALUE ()
 
-   Pops ``TOS`` and yields it from a generator.
+   Pops ``TOS`` and yields it from a :term:`generator`.
 
 
 .. opcode:: IMPORT_STAR ()

Modified: python/trunk/Doc/library/exceptions.rst
==============================================================================
--- python/trunk/Doc/library/exceptions.rst	(original)
+++ python/trunk/Doc/library/exceptions.rst	Sun Oct 21 12:52:38 2007
@@ -152,9 +152,9 @@
 
 .. exception:: GeneratorExit
 
-   Raise when a generator's :meth:`close` method is called. It directly inherits
-   from :exc:`Exception` instead of :exc:`StandardError` since it is technically
-   not an error.
+   Raise when a :term:`generator`\'s :meth:`close` method is called.  It
+   directly inherits from :exc:`Exception` instead of :exc:`StandardError` since
+   it is technically not an error.
 
    .. versionadded:: 2.5
 

Modified: python/trunk/Doc/library/itertools.rst
==============================================================================
--- python/trunk/Doc/library/itertools.rst	(original)
+++ python/trunk/Doc/library/itertools.rst	Sun Oct 21 12:52:38 2007
@@ -460,8 +460,8 @@
 rather than bringing the whole iterable into memory all at once. Code volume is
 kept small by linking the tools together in a functional style which helps
 eliminate temporary variables.  High speed is retained by preferring
-"vectorized" building blocks over the use of for-loops and generators which
-incur interpreter overhead. ::
+"vectorized" building blocks over the use of for-loops and :term:`generator`\s
+which incur interpreter overhead. ::
 
    def take(n, seq):
        return list(islice(seq, n))

Modified: python/trunk/Doc/library/os.path.rst
==============================================================================
--- python/trunk/Doc/library/os.path.rst	(original)
+++ python/trunk/Doc/library/os.path.rst	Sun Oct 21 12:52:38 2007
@@ -303,8 +303,8 @@
 
    .. note::
 
-      The newer :func:`os.walk` generator supplies similar functionality and can be
-      easier to use.
+      The newer :func:`os.walk` :term:`generator` supplies similar functionality
+      and can be easier to use.
 
 
 .. data:: supports_unicode_filenames

Modified: python/trunk/Doc/library/sqlite3.rst
==============================================================================
--- python/trunk/Doc/library/sqlite3.rst	(original)
+++ python/trunk/Doc/library/sqlite3.rst	Sun Oct 21 12:52:38 2007
@@ -416,7 +416,7 @@
 
    .. literalinclude:: ../includes/sqlite3/executemany_1.py
 
-   Here's a shorter example using a generator:
+   Here's a shorter example using a :term:`generator`:
 
    .. literalinclude:: ../includes/sqlite3/executemany_2.py
 

Modified: python/trunk/Doc/library/stdtypes.rst
==============================================================================
--- python/trunk/Doc/library/stdtypes.rst	(original)
+++ python/trunk/Doc/library/stdtypes.rst	Sun Oct 21 12:52:38 2007
@@ -479,10 +479,10 @@
 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 :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.
+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.
 
 
 .. _typesseq:
@@ -2183,7 +2183,7 @@
 their implementation of the context management protocol. See the
 :mod:`contextlib` module for some examples.
 
-Python's generators and the ``contextlib.contextfactory`` decorator provide a
+Python's :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a
 convenient way to implement these protocols.  If a generator function is
 decorated with the ``contextlib.contextfactory`` decorator, it will return a
 context manager implementing the necessary :meth:`__enter__` and

Modified: python/trunk/Doc/library/tokenize.rst
==============================================================================
--- python/trunk/Doc/library/tokenize.rst	(original)
+++ python/trunk/Doc/library/tokenize.rst	Sun Oct 21 12:52:38 2007
@@ -13,7 +13,7 @@
 well, making it useful for implementing "pretty-printers," including colorizers
 for on-screen displays.
 
-The primary entry point is a generator:
+The primary entry point is a :term:`generator`:
 
 
 .. function:: generate_tokens(readline)

Modified: python/trunk/Doc/library/types.rst
==============================================================================
--- python/trunk/Doc/library/types.rst	(original)
+++ python/trunk/Doc/library/types.rst	Sun Oct 21 12:52:38 2007
@@ -128,8 +128,8 @@
 
 .. data:: GeneratorType
 
-   The type of generator-iterator objects, produced by calling a generator
-   function.
+   The type of :term:`generator`-iterator objects, produced by calling a
+   generator function.
 
    .. versionadded:: 2.2
 

Modified: python/trunk/Doc/library/weakref.rst
==============================================================================
--- python/trunk/Doc/library/weakref.rst	(original)
+++ python/trunk/Doc/library/weakref.rst	Sun Oct 21 12:52:38 2007
@@ -50,9 +50,9 @@
 
 Not all objects can be weakly referenced; those objects which can include class
 instances, functions written in Python (but not in C), methods (both bound and
-unbound), sets, frozensets, file objects, generators, type objects, DBcursor
-objects from the :mod:`bsddb` module, sockets, arrays, deques, and regular
-expression pattern objects.
+unbound), sets, frozensets, file objects, :term:`generator`\s, type objects,
+:class:`DBcursor` objects from the :mod:`bsddb` module, sockets, arrays, deques,
+and regular expression pattern objects.
 
 .. versionchanged:: 2.4
    Added support for files, sockets, arrays, and patterns.

Modified: python/trunk/Doc/library/xmlrpclib.rst
==============================================================================
--- python/trunk/Doc/library/xmlrpclib.rst	(original)
+++ python/trunk/Doc/library/xmlrpclib.rst	Sun Oct 21 12:52:38 2007
@@ -325,7 +325,8 @@
    return ``None``, and only store the call name and parameters in the
    :class:`MultiCall` object. Calling the object itself causes all stored calls to
    be transmitted as a single ``system.multicall`` request. The result of this call
-   is a generator; iterating over this generator yields the individual results.
+   is a :term:`generator`; iterating over this generator yields the individual
+   results.
 
 A usage example of this class is ::
 

Modified: python/trunk/Doc/tutorial/classes.rst
==============================================================================
--- python/trunk/Doc/tutorial/classes.rst	(original)
+++ python/trunk/Doc/tutorial/classes.rst	Sun Oct 21 12:52:38 2007
@@ -711,12 +711,12 @@
 Generators
 ==========
 
-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 :meth:`next` is called, 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::
+: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
+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::
 
    def reverse(data):
        for index in range(len(data)-1, -1, -1):