From e7a0990113873e5f0cc5cac203f47a8dcbda9848 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Oct 2007 12:10:28 +0000 Subject: Add :term:s for iterator. --- Doc/glossary.rst | 2 ++ Doc/howto/functional.rst | 2 +- Doc/howto/regex.rst | 4 ++-- Doc/library/autogil.rst | 4 ++-- Doc/library/cookielib.rst | 2 +- Doc/library/csv.rst | 2 +- Doc/library/ctypes.rst | 4 ++-- Doc/library/dis.rst | 8 ++++---- Doc/library/exceptions.rst | 7 ++++--- Doc/library/functions.rst | 12 ++++++------ Doc/library/glob.rst | 4 ++-- Doc/library/heapq.rst | 4 ++-- Doc/library/itertools.rst | 2 +- Doc/library/pickletools.rst | 8 ++++---- Doc/library/re.rst | 2 +- Doc/library/sqlite3.rst | 14 +++++++------- Doc/library/urllib.rst | 2 +- Doc/library/weakref.rst | 4 ++-- Doc/library/wsgiref.rst | 2 +- Doc/library/xml.etree.elementtree.rst | 4 ++-- 20 files changed, 48 insertions(+), 45 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 88b1ccb..a81d2c9 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -225,6 +225,8 @@ Glossary with an iterator will just return the same exhausted iterator object used in the previous iteration pass, making it appear like an empty container. + More information can be found in :ref:`typeiter`. + LBYL Look before you leap. This coding style explicitly tests for pre-conditions before making calls or lookups. This style contrasts with diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index b0739c7..a7b53db 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -13,7 +13,7 @@ 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 :term:`generator`\s and relevant library modules such as +:term:`iterator`\s and :term:`generator`\s and relevant library modules such as :mod:`itertools` and :mod:`functools`. diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst index b200764..131bb51 100644 --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -354,7 +354,7 @@ listing. | | returns them as a list. | +------------------+-----------------------------------------------+ | ``finditer()`` | Find all substrings where the RE matches, and | -| | returns them as an iterator. | +| | returns them as an :term:`iterator`. | +------------------+-----------------------------------------------+ :meth:`match` and :meth:`search` return ``None`` if no match can be found. If @@ -460,7 +460,7 @@ Two :class:`RegexObject` methods return all of the matches for a pattern. :meth:`findall` has to create the entire list before it can be returned as the result. The :meth:`finditer` method returns a sequence of :class:`MatchObject` -instances as an iterator. [#]_ :: +instances as an :term:`iterator`. [#]_ :: >>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...') >>> iterator diff --git a/Doc/library/autogil.rst b/Doc/library/autogil.rst index 93f0d04..7625be6 100644 --- a/Doc/library/autogil.rst +++ b/Doc/library/autogil.rst @@ -9,8 +9,8 @@ The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that -automatically locks and unlocks Python's Global Interpreter Lock when running an -event loop. +automatically locks and unlocks Python's :term:`Global Interpreter Lock` when +running an event loop. .. exception:: AutoGILError diff --git a/Doc/library/cookielib.rst b/Doc/library/cookielib.rst index 44045d3..a84649c 100644 --- a/Doc/library/cookielib.rst +++ b/Doc/library/cookielib.rst @@ -144,7 +144,7 @@ The following classes are provided: CookieJar and FileCookieJar Objects ----------------------------------- -:class:`CookieJar` objects support the iterator protocol for iterating over +:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over contained :class:`Cookie` objects. :class:`CookieJar` has the following methods: diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 153dc89..98fc6c9 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -62,7 +62,7 @@ The :mod:`csv` module defines the following functions: .. function:: reader(csvfile[, dialect='excel'][, fmtparam]) Return a reader object which will iterate over lines in the given *csvfile*. - *csvfile* can be any object which supports the iterator protocol and returns a + *csvfile* can be any object which supports the :term:`iterator` protocol and returns a string each time its :meth:`next` method is called --- file objects and list objects are both suitable. If *csvfile* is a file object, it must be opened with the 'b' flag on platforms where that makes a difference. An optional diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index c28fcd3..4b749d1 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1368,8 +1368,8 @@ way is to instantiate one of the following classes: :class:`WinDLL` and :class:`OleDLL` use the standard calling convention on this platform. -The Python GIL is released before calling any function exported by these -libraries, and reacquired afterwards. +The Python :term:`global interpreter lock` is released before calling any +function exported by these libraries, and reacquired afterwards. .. class:: PyDLL(name, mode=DEFAULT_MODE, handle=None) diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 85c3030..58276da 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -674,10 +674,10 @@ the more significant byte last. .. opcode:: FOR_ITER (delta) - ``TOS`` is an iterator. Call its :meth:`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 bytecode counter is - incremented by *delta*. + ``TOS`` is an :term:`iterator`. Call its :meth:`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 bytecode + counter is incremented by *delta*. .. % \begin{opcodedesc}{FOR_LOOP}{delta} .. % This opcode is obsolete. diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 1de0693..9fa5022 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -285,9 +285,10 @@ The following exceptions are the exceptions that are actually raised. .. exception:: StopIteration - Raised by an iterator's :meth:`next` method to signal that there are no further - values. This is derived from :exc:`Exception` rather than :exc:`StandardError`, - since this is not considered an error in its normal application. + Raised by an :term:`iterator`\'s :meth:`next` method to signal that there are + no further values. This is derived from :exc:`Exception` rather than + :exc:`StandardError`, since this is not considered an error in its normal + application. .. versionadded:: 2.2 diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 0d380ea..f98adce 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -322,7 +322,7 @@ available. They are listed here in alphabetical order. .. function:: enumerate(iterable) - Return an enumerate object. *iterable* must be a sequence, an iterator, or some + Return an enumerate object. *iterable* must be a sequence, an :term:`iterator`, or some other object which supports iteration. The :meth:`next` method of the iterator returned by :func:`enumerate` returns a tuple containing a count (from zero) and the corresponding value obtained from iterating over *iterable*. @@ -420,7 +420,7 @@ available. They are listed here in alphabetical order. Construct a list from those elements of *iterable* for which *function* returns true. *iterable* may be either a sequence, a container which supports - iteration, or an iterator, If *iterable* is a string or a tuple, the result + iteration, or an iterator. If *iterable* is a string or a tuple, the result also has that type; otherwise it is always a list. If *function* is ``None``, the identity function is assumed, that is, all elements of *iterable* that are false are removed. @@ -590,7 +590,7 @@ available. They are listed here in alphabetical order. .. function:: iter(o[, sentinel]) - Return an iterator object. The first argument is interpreted very differently + Return an :term:`iterator` object. The first argument is interpreted very differently depending on the presence of the second argument. Without a second argument, *o* must be a collection object which supports the iteration protocol (the :meth:`__iter__` method), or it must support the sequence protocol (the @@ -973,9 +973,9 @@ available. They are listed here in alphabetical order. .. function:: reversed(seq) - Return a reverse iterator. *seq* must be an object which supports the sequence - protocol (the :meth:`__len__` method and the :meth:`__getitem__` method with - integer arguments starting at ``0``). + Return a reverse :term:`iterator`. *seq* must be an object which supports + the sequence protocol (the :meth:`__len__` method and the :meth:`__getitem__` + method with integer arguments starting at ``0``). .. versionadded:: 2.4 diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 80bdac2..5f28480 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -28,8 +28,8 @@ subshell. (For tilde and shell variable expansion, use .. function:: iglob(pathname) - Return an iterator which yields the same values as :func:`glob` without actually - storing them all simultaneously. + Return an :term:`iterator` which yields the same values as :func:`glob` + without actually storing them all simultaneously. .. versionadded:: 2.5 diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index 2d38c26..bd4c79f 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -92,8 +92,8 @@ The module also offers three general purpose functions based on heaps. .. function:: merge(*iterables) Merge multiple sorted inputs into a single sorted output (for example, merge - timestamped entries from multiple log files). Returns an iterator over over the - sorted values. + timestamped entries from multiple log files). Returns an :term:`iterator` + over over the sorted values. Similar to ``sorted(itertools.chain(*iterables))`` but returns an iterable, does not pull the data into memory all at once, and assumes that each of the input diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index e150070..c1bffa4 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -10,7 +10,7 @@ .. versionadded:: 2.3 -This module implements a number of iterator building blocks inspired by +This module implements a number of :term:`iterator` building blocks inspired by constructs from the Haskell and SML programming languages. Each has been recast in a form suitable for Python. diff --git a/Doc/library/pickletools.rst b/Doc/library/pickletools.rst index ec220d9..a19b978 100644 --- a/Doc/library/pickletools.rst +++ b/Doc/library/pickletools.rst @@ -29,9 +29,9 @@ probably won't find the :mod:`pickletools` module relevant. .. function:: genops(pickle) - Provides an iterator over all of the opcodes in a pickle, returning a sequence - of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an - :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of - the opcode's argument; *pos* is the position at which this opcode is located. + Provides an :term:`iterator` over all of the opcodes in a pickle, returning a + sequence of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an + :class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of + the opcode's argument; *pos* is the position at which this opcode is located. *pickle* can be a string or a file-like object. diff --git a/Doc/library/re.rst b/Doc/library/re.rst index eec6a9e..1caaaf2 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -568,7 +568,7 @@ form. .. function:: finditer(pattern, string[, flags]) - Return an iterator yielding :class:`MatchObject` instances over all + Return an :term:`iterator` yielding :class:`MatchObject` instances over all non-overlapping matches for the RE *pattern* in *string*. Empty matches are included in the result unless they touch the beginning of another match. diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 35f3f38..029b8ba 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -71,10 +71,10 @@ may use a different placeholder, such as ``%s`` or ``:1``.) For example:: ): c.execute('insert into stocks values (?,?,?,?,?)', t) -To retrieve data after executing a SELECT statement, you can either treat the -cursor as an iterator, call the cursor's :meth:`fetchone` method to retrieve a -single matching row, or call :meth:`fetchall` to get a list of the matching -rows. +To retrieve data after executing a SELECT statement, you can either treat the +cursor as an :term:`iterator`, call the cursor's :meth:`fetchone` method to +retrieve a single matching row, or call :meth:`fetchall` to get a list of the +matching rows. This example uses the iterator form:: @@ -410,9 +410,9 @@ A :class:`Cursor` instance has the following attributes and methods: .. method:: Cursor.executemany(sql, seq_of_parameters) - Executes a SQL command against all parameter sequences or mappings found in the - sequence *sql*. The :mod:`sqlite3` module also allows using an iterator yielding - parameters instead of a sequence. + Executes a SQL command against all parameter sequences or mappings found in + the sequence *sql*. The :mod:`sqlite3` module also allows using an + :term:`iterator` yielding parameters instead of a sequence. .. literalinclude:: ../includes/sqlite3/executemany_1.py diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst index ef8264f..81dd36f 100644 --- a/Doc/library/urllib.rst +++ b/Doc/library/urllib.rst @@ -29,7 +29,7 @@ It defines the following public functions: :exc:`IOError` exception is raised. If all went well, a file-like object is returned. This supports the following methods: :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`fileno`, :meth:`close`, :meth:`info` and - :meth:`geturl`. It also has proper support for the iterator protocol. One + :meth:`geturl`. It also has proper support for the :term:`iterator` protocol. One caveat: the :meth:`read` method, if the size argument is omitted or negative, may not read until the end of the data stream; there is no good way to determine that the entire stream from a socket has been read in the general case. diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 695bf94..21007d9 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -150,7 +150,7 @@ than needed. .. method:: WeakKeyDictionary.iterkeyrefs() - Return an iterator that yields the weak references to the keys. + Return an :term:`iterator` that yields the weak references to the keys. .. versionadded:: 2.5 @@ -182,7 +182,7 @@ methods of :class:`WeakKeyDictionary` objects. .. method:: WeakValueDictionary.itervaluerefs() - Return an iterator that yields the weak references to the values. + Return an :term:`iterator` that yields the weak references to the values. .. versionadded:: 2.5 diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst index ff68684..8df10bf 100644 --- a/Doc/library/wsgiref.rst +++ b/Doc/library/wsgiref.rst @@ -126,7 +126,7 @@ also provides these miscellaneous utilities: .. class:: FileWrapper(filelike [, blksize=8192]) - A wrapper to convert a file-like object to an iterator. The resulting objects + A wrapper to convert a file-like object to an :term:`iterator`. The resulting objects support both :meth:`__getitem__` and :meth:`__iter__` iteration styles, for compatibility with Python 2.1 and Jython. As the object is iterated over, the optional *blksize* parameter will be repeatedly passed to the *filelike* diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index ead8d29..f55eee0 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -89,7 +89,7 @@ Functions Parses an XML section into an element tree incrementally, and reports what's going on to the user. *source* is a filename or file object containing XML data. *events* is a list of events to report back. If omitted, only "end" events are - reported. Returns an iterator providing ``(event, elem)`` pairs. + reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs. .. function:: parse(source[, parser]) @@ -318,7 +318,7 @@ ElementTree Objects .. method:: ElementTree.findall(path) Finds all toplevel elements with the given tag. Same as getroot().findall(path). - *path* is the element to look for. Returns a list or iterator containing all + *path* is the element to look for. Returns a list or :term:`iterator` containing all matching elements, in document order. -- cgit v0.12