Add :term: for generators.

birkenfeld · birkenfeld · commit cf3fb259329e · 2007-10-21T10:52:38.000Z
diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
@@ -13,8 +13,8 @@ disclaimer.)
 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
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
@@ -242,17 +242,17 @@ utility functions:
 .. 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
 
 
 .. 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
 
diff --git a/Doc/library/compiler.rst b/Doc/library/compiler.rst
@@ -640,5 +640,5 @@ The code generator is a visitor that emits bytecodes.  Each visit method can
 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.
 
diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
@@ -39,9 +39,9 @@ Functions provided:
       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.
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
@@ -442,9 +442,9 @@ it is 8-bit-clean save for some problems with ASCII NUL characters.  So you can
 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::
 
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
@@ -126,8 +126,8 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
 
 .. 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 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
 
 .. 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 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
 
 .. 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 @@ use :meth:`set_seq2` to set the commonly used sequence once and call
 
 .. 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.
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
@@ -482,7 +482,7 @@ Miscellaneous opcodes.
 
 .. opcode:: YIELD_VALUE ()
 
-   Pops ``TOS`` and yields it from a generator.
+   Pops ``TOS`` and yields it from a :term:`generator`.
 
 
 .. opcode:: IMPORT_STAR ()
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
@@ -152,9 +152,9 @@ The following exceptions are the exceptions that are actually raised.
 
 .. 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
 
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
@@ -460,8 +460,8 @@ The superior memory performance is kept by processing elements one at a time
 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))
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
@@ -303,8 +303,8 @@ write files see :func:`open`, and for accessing the filesystem see the
 
    .. 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
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
@@ -416,7 +416,7 @@ A :class:`Cursor` instance has the following attributes and methods:
 
    .. 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
 
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -479,10 +479,10 @@ 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 :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 @@ decimal arithmetic context. The specific types are not treated specially beyond
 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
diff --git a/Doc/library/tokenize.rst b/Doc/library/tokenize.rst
@@ -13,7 +13,7 @@ implemented in Python.  The scanner in this module returns comments as tokens as
 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)
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
@@ -128,8 +128,8 @@ The module defines the following names:
 
 .. 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
 
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
@@ -50,9 +50,9 @@ benefit of advanced uses.
 
 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.
diff --git a/Doc/library/xmlrpclib.rst b/Doc/library/xmlrpclib.rst
@@ -325,7 +325,8 @@ encapsulate multiple calls to a remote server into a single request.
    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 ::
 
diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst
@@ -711,12 +711,12 @@ returns an object with a :meth:`next` method.  If the class defines
 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):
