From cf3fb259329eedfa9d2c802b2ea5ced287c21e78 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Oct 2007 10:52:38 +0000 Subject: Add :term: for generators. --- Doc/howto/functional.rst | 4 ++-- Doc/library/codecs.rst | 8 ++++---- Doc/library/compiler.rst | 2 +- Doc/library/contextlib.rst | 6 +++--- Doc/library/csv.rst | 4 ++-- Doc/library/difflib.rst | 14 +++++++------- Doc/library/dis.rst | 2 +- Doc/library/exceptions.rst | 6 +++--- Doc/library/itertools.rst | 4 ++-- Doc/library/os.path.rst | 4 ++-- Doc/library/sqlite3.rst | 2 +- Doc/library/stdtypes.rst | 10 +++++----- Doc/library/tokenize.rst | 2 +- Doc/library/types.rst | 4 ++-- Doc/library/weakref.rst | 6 +++--- Doc/library/xmlrpclib.rst | 3 ++- Doc/tutorial/classes.rst | 12 ++++++------ 17 files changed, 47 insertions(+), 46 deletions(-) diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index 39a1e05..b0739c7 100644 --- 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 index 1bcd376..5bab2af 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -242,8 +242,8 @@ 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 @@ -251,8 +251,8 @@ utility functions: .. 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 index 6d42dc9..5f5ed44 100644 --- 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 index fffb99c..a4b271f 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -39,9 +39,9 @@ Functions provided: foo - 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 index 34867f7..153dc89 100644 --- 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 index 60367a4..4da3be9 100644 --- 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 index c31a779..85c3030 100644 --- 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 index 623d73b..1de0693 100644 --- 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 index 93e62f6..e150070 100644 --- 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 index 291d155..125044d 100644 --- 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 index bee32e6..35f3f38 100644 --- 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 index 44467af..a191ab4 100644 --- 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 index 61f2c4d..9a2a11a 100644 --- 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 index 06832d1..b5e3830 100644 --- 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 index c5857ba..695bf94 100644 --- 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 index 5f58d9e..b3efb5c 100644 --- 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 index f91c3f0..d5bde44 100644 --- 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): -- cgit v0.12