From 6e6cb8e0e491477614bae33c29f6e00d0d48c20b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Tue, 16 Nov 2010 19:13:50 +0000 Subject: Provide links to Python source where the code is short, readable and informative adjunct to the docs. Forward-port of Raymond's r86225 and r86245 using the new source reST role added in #10334. --- Doc/library/ast.rst | 3 +++ Doc/library/atexit.rst | 5 +++++ Doc/library/bisect.rst | 5 +++++ Doc/library/calendar.rst | 4 ++++ Doc/library/cmd.rst | 3 +++ Doc/library/collections.rst | 8 ++++++++ Doc/library/contextlib.rst | 5 +++++ Doc/library/dis.rst | 4 ++++ Doc/library/filecmp.rst | 5 +++++ Doc/library/fileinput.rst | 5 +++++ Doc/library/fnmatch.rst | 4 ++++ Doc/library/functools.rst | 5 +++++ Doc/library/glob.rst | 3 +++ Doc/library/heapq.rst | 5 +++++ Doc/library/keyword.rst | 5 +++++ Doc/library/linecache.rst | 5 +++++ Doc/library/pprint.rst | 5 +++++ Doc/library/queue.rst | 5 +++++ Doc/library/quopri.rst | 4 ++++ Doc/library/random.rst | 5 +++++ Doc/library/sched.rst | 4 ++++ Doc/library/shelve.rst | 4 ++++ Doc/library/shutil.rst | 6 ++++++ Doc/library/string.rst | 5 +++++ Doc/library/textwrap.rst | 4 ++++ Doc/library/threading.rst | 5 +++++ Doc/library/tokenize.rst | 5 +++++ Doc/library/trace.rst | 4 ++++ Doc/library/uu.rst | 4 ++++ 29 files changed, 134 insertions(+) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 66b29e0..a9821e1 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -19,6 +19,9 @@ helper provided in this module. The result will be a tree of objects whose classes all inherit from :class:`ast.AST`. An abstract syntax tree can be compiled into a Python code object using the built-in :func:`compile` function. +.. seealso:: + + Latest version of the :source:`ast module Python source code ` Node classes ------------ diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst index 104c730..1ce45c4 100644 --- a/Doc/library/atexit.rst +++ b/Doc/library/atexit.rst @@ -11,6 +11,11 @@ The :mod:`atexit` module defines functions to register and unregister cleanup functions. Functions thus registered are automatically executed upon normal interpreter termination. +.. seealso:: + + Latest version of the :source:`atexit Python source code + ` + Note: the functions registered via this module are not called when the program is killed by a signal not handled by Python, when a Python fatal internal error is detected, or when :func:`os._exit` is called. diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index eb23159..ca853e0 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -14,6 +14,11 @@ approach. The module is called :mod:`bisect` because it uses a basic bisection algorithm to do its work. The source code may be most useful as a working example of the algorithm (the boundary conditions are already right!). +.. seealso:: + + Latest version of the :source:`bisect module Python source code + ` + The following functions are provided: diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst index c8dac49..4ebe616 100644 --- a/Doc/library/calendar.rst +++ b/Doc/library/calendar.rst @@ -21,6 +21,10 @@ in both directions. This matches the definition of the "proleptic Gregorian" calendar in Dershowitz and Reingold's book "Calendrical Calculations", where it's the base calendar for all computations. +.. seealso:: + + Latest version of the :source:`calendar module Python source code + ` .. class:: Calendar(firstweekday=0) diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst index d0332aa..53d62c5 100644 --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -11,6 +11,9 @@ command interpreters. These are often useful for test harnesses, administrative tools, and prototypes that will later be wrapped in a more sophisticated interface. +.. seealso:: + + Latest version of the :source:`cmd module Python source code ` .. class:: Cmd(completekey='tab', stdin=None, stdout=None) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 439e3bf..e34e394 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -31,6 +31,11 @@ In addition to the concrete container classes, the collections module provides ABCs (abstract base classes) that can be used to test whether a class provides a particular interface, for example, whether it is hashable or a mapping. +.. seealso:: + + Latest version of the :source:`collections module Python source code + ` + :class:`Counter` objects ------------------------ @@ -1059,6 +1064,9 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin: .. seealso:: + * Latest version of the :source:`Python source code for the collections + abstract base classes ` + * `OrderedSet recipe `_ for an example built on :class:`MutableSet`. diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 35eb882..5e1a11a 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -9,6 +9,11 @@ This module provides utilities for common tasks involving the :keyword:`with` statement. For more information see also :ref:`typecontextmanager` and :ref:`context-managers`. +.. seealso:: + + Latest version of the :source:`contextlib Python source code + ` + Functions provided: diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index b6f1d9f..cf880fc 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -10,6 +10,10 @@ disassembling it. The CPython bytecode which this module takes as an input is defined in the file :file:`Include/opcode.h` and used by the compiler and the interpreter. +.. seealso:: + + Latest version of the :source:`dis module Python source code ` + .. impl-detail:: Bytecode is an implementation detail of the CPython interpreter! No diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst index f57dcce..d6cdd29 100644 --- a/Doc/library/filecmp.rst +++ b/Doc/library/filecmp.rst @@ -10,6 +10,11 @@ The :mod:`filecmp` module defines functions to compare files and directories, with various optional time/correctness trade-offs. For comparing files, see also the :mod:`difflib` module. +.. seealso:: + + Latest version of the :source:`filecmp Python source code + ` + The :mod:`filecmp` module defines the following functions: diff --git a/Doc/library/fileinput.rst b/Doc/library/fileinput.rst index 7055f32..9174830 100644 --- a/Doc/library/fileinput.rst +++ b/Doc/library/fileinput.rst @@ -44,6 +44,11 @@ hook must be a function that takes two arguments, *filename* and *mode*, and returns an accordingly opened file-like object. Two useful hooks are already provided by this module. +.. seealso:: + + Latest version of the :source:`fileinput Python source code + ` + The following function is the primary interface of this module: diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst index 0352b52..8af6c0b 100644 --- a/Doc/library/fnmatch.rst +++ b/Doc/library/fnmatch.rst @@ -33,6 +33,10 @@ module. See module :mod:`glob` for pathname expansion (:mod:`glob` uses a period are not special for this module, and are matched by the ``*`` and ``?`` patterns. +.. seealso:: + + Latest version of the :source:`fnmatch Python source code + ` .. function:: fnmatch(filename, pattern) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 8e97c54..58c2429 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -13,6 +13,11 @@ The :mod:`functools` module is for higher-order functions: functions that act on or return other functions. In general, any callable object can be treated as a function for the purposes of this module. +.. seealso:: + + Latest version of the :source:`functools Python source code + ` + The :mod:`functools` module defines the following functions: .. function:: cmp_to_key(func) diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst index 3e0322d..0de763f 100644 --- a/Doc/library/glob.rst +++ b/Doc/library/glob.rst @@ -15,6 +15,9 @@ matched. This is done by using the :func:`os.listdir` and subshell. (For tilde and shell variable expansion, use :func:`os.path.expanduser` and :func:`os.path.expandvars`.) +.. seealso:: + + Latest version of the :source:`glob module Python source code ` .. function:: glob(pathname) diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index 78beee9..67bda56 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -11,6 +11,11 @@ This module provides an implementation of the heap queue algorithm, also known as the priority queue algorithm. +.. seealso:: + + Latest version of the :source:`heapq Python source code + ` + Heaps are arrays for which ``heap[k] <= heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k*, counting elements from zero. For the sake of comparison, non-existing elements are considered to be infinite. The diff --git a/Doc/library/keyword.rst b/Doc/library/keyword.rst index a4bfa50..4d8a1f1 100644 --- a/Doc/library/keyword.rst +++ b/Doc/library/keyword.rst @@ -19,3 +19,8 @@ This module allows a Python program to determine if a string is a keyword. keywords are defined to only be active when particular :mod:`__future__` statements are in effect, these will be included as well. + +.. seealso:: + + Latest version of the :source:`keyword module Python source code + ` diff --git a/Doc/library/linecache.rst b/Doc/library/linecache.rst index 688e297..d8a9ff3 100644 --- a/Doc/library/linecache.rst +++ b/Doc/library/linecache.rst @@ -11,6 +11,11 @@ attempting to optimize internally, using a cache, the common case where many lines are read from a single file. This is used by the :mod:`traceback` module to retrieve source lines for inclusion in the formatted traceback. +.. seealso:: + + Latest version of the :source:`linecache module Python source code + ` + The :mod:`linecache` module defines the following functions: diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 932be75..82648a1 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -21,6 +21,11 @@ width constraint. Dictionaries are sorted by key before the display is computed. +.. seealso:: + + Latest version of the :source:`pprint module Python source code + ` + The :mod:`pprint` module defines one class: .. First the implementation class: diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst index 0ee920b..424998e 100644 --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -19,6 +19,11 @@ the first retrieved (operating like a stack). With a priority queue, the entries are kept sorted (using the :mod:`heapq` module) and the lowest valued entry is retrieved first. +.. seealso:: + + Latest version of the :source:`queue module Python source code + ` + The :mod:`queue` module defines the following classes and exceptions: .. class:: Queue(maxsize=0) diff --git a/Doc/library/quopri.rst b/Doc/library/quopri.rst index d7c7204..4eded5b 100644 --- a/Doc/library/quopri.rst +++ b/Doc/library/quopri.rst @@ -17,6 +17,10 @@ few nonprintable characters; the base64 encoding scheme available via the :mod:`base64` module is more compact if there are many such characters, as when sending a graphics file. +.. seealso:: + + Latest version of the :source:`quopri module Python source code + ` .. function:: decode(input, output, header=False) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 55edcf8..7aa0894 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -8,6 +8,11 @@ This module implements pseudo-random number generators for various distributions. +.. seealso:: + + Latest version of the :source:`random module Python source code + ` + For integers, there is uniform selection from a range. For sequences, there is uniform selection of a random element, a function to generate a random permutation of a list in-place, and a function for random sampling without diff --git a/Doc/library/sched.rst b/Doc/library/sched.rst index 0290ec4..94f7991 100644 --- a/Doc/library/sched.rst +++ b/Doc/library/sched.rst @@ -10,6 +10,10 @@ The :mod:`sched` module defines a class which implements a general purpose event scheduler: +.. seealso:: + + Latest version of the :source:`sched module Python source code + ` .. class:: scheduler(timefunc, delayfunc) diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst index f5374c9..512788c 100644 --- a/Doc/library/shelve.rst +++ b/Doc/library/shelve.rst @@ -13,6 +13,10 @@ arbitrary Python objects --- anything that the :mod:`pickle` module can handle. This includes most class instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings. +.. seealso:: + + Latest version of the :source:`shelve module Python source code + ` .. function:: open(filename, flag='c', protocol=None, writeback=False) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index e9dfe65..0144876 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -15,6 +15,11 @@ collections of files. In particular, functions are provided which support file copying and removal. For operations on individual files, see also the :mod:`os` module. +.. seealso:: + + Latest version of the :source:`shutil module Python source code + ` + .. warning:: Even the higher-level file copying functions (:func:`copy`, :func:`copy2`) @@ -26,6 +31,7 @@ copying and removal. For operations on individual files, see also the not be correct. On Windows, file owners, ACLs and alternate data streams are not copied. + Directory and files operations ------------------------------ diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 69cc25b..b785fc2 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -15,6 +15,11 @@ section, and also the string-specific methods described in the :ref:`string-formatting` section. Also, see the :mod:`re` module for string functions based on regular expressions. +.. seealso:: + + Latest version of the :source:`string module Python source code + ` + String constants ---------------- diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst index f66416f..f881701 100644 --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -13,6 +13,10 @@ and a utility function :func:`dedent`. If you're just wrapping or filling one or two text strings, the convenience functions should be good enough; otherwise, you should use an instance of :class:`TextWrapper` for efficiency. +.. seealso:: + + Latest version of the :source:`textwrap module Python source code + ` .. function:: wrap(text, width=70, **kwargs) diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 702f4be..d3d7d9e 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -17,6 +17,11 @@ The :mod:`dummy_threading` module is provided for situations where methods and functions in this module in the Python 2.x series are still supported by this module. +.. seealso:: + + Latest version of the :source:`threading module Python source code + ` + This module defines the following functions and objects: diff --git a/Doc/library/tokenize.rst b/Doc/library/tokenize.rst index 6a96609..d7ae638 100644 --- a/Doc/library/tokenize.rst +++ b/Doc/library/tokenize.rst @@ -12,6 +12,11 @@ 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. +.. seealso:: + + Latest version of the :source:`tokenize module Python source code + ` + The primary entry point is a :term:`generator`: .. function:: tokenize(readline) diff --git a/Doc/library/trace.rst b/Doc/library/trace.rst index f90f44b..878fbed 100644 --- a/Doc/library/trace.rst +++ b/Doc/library/trace.rst @@ -10,6 +10,10 @@ annotated statement coverage listings, print caller/callee relationships and list functions executed during a program run. It can be used in another program or from the command line. +.. seealso:: + + Latest version of the :source:`trace module Python source code + ` .. _trace-cli: diff --git a/Doc/library/uu.rst b/Doc/library/uu.rst index 7813e44..53d269b 100644 --- a/Doc/library/uu.rst +++ b/Doc/library/uu.rst @@ -21,6 +21,10 @@ that, when required, the mode is ``'rb'`` or ``'wb'`` on Windows. This code was contributed by Lance Ellinghouse, and modified by Jack Jansen. +.. seealso:: + + Latest version of the :source:`uu module Python source code ` + The :mod:`uu` module defines the following functions: -- cgit v0.12