diff options
| -rw-r--r-- | Doc/ACKS.txt | 1 | ||||
| -rw-r--r-- | Doc/Makefile | 4 | ||||
| -rw-r--r-- | Doc/README.txt | 3 | ||||
| -rw-r--r-- | Doc/glossary.rst | 94 | ||||
| -rw-r--r-- | Doc/library/atexit.rst | 2 | ||||
| -rw-r--r-- | Doc/library/bdb.rst | 2 | ||||
| -rw-r--r-- | Doc/library/codecs.rst | 6 | ||||
| -rw-r--r-- | Doc/library/codeop.rst | 4 | ||||
| -rw-r--r-- | Doc/library/contextlib.rst | 6 | ||||
| -rw-r--r-- | Doc/library/doctest.rst | 3 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 12 | ||||
| -rw-r--r-- | Doc/library/functools.rst | 6 | ||||
| -rw-r--r-- | Doc/library/inspect.rst | 2 | ||||
| -rw-r--r-- | Doc/library/operator.rst | 8 | ||||
| -rw-r--r-- | Doc/library/sets.rst | 6 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 4 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 18 | ||||
| -rw-r--r-- | Doc/library/timeit.rst | 11 | ||||
| -rw-r--r-- | Doc/library/weakref.rst | 32 | ||||
| -rw-r--r-- | Doc/reference/compound_stmts.rst | 2 | ||||
| -rw-r--r-- | Doc/tutorial/stdlib2.rst | 4 |
21 files changed, 166 insertions, 64 deletions
diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index c41007b..34c657b 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -185,6 +185,7 @@ docs@python.org), and we'll be glad to correct the problem. * Glyn Webster * Bob Weiner * Eddy Welbourne +* Jeff Wheeler * Mats Wichmann * Gerry Wiener * Timothy Wild diff --git a/Doc/Makefile b/Doc/Makefile index aa88c8c..8569ba0 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -57,6 +57,10 @@ htmlhelp: build @echo "Build finished; now you can run HTML Help Workshop with the" \ "build/htmlhelp/pydoc.hhp project file." +latex: BUILDER = latex +latex: build + @echo "Build finished; the LaTeX files are in build/latex." + clean: -rm -rf build/* -rm -rf tools/sphinx diff --git a/Doc/README.txt b/Doc/README.txt index 9959da2..6e135e9 100644 --- a/Doc/README.txt +++ b/Doc/README.txt @@ -48,6 +48,9 @@ Available make targets are: To create the CHM file, you need to run the Microsoft HTML Help Workshop over the generated project (.hhp) file. + * "latex", which builds LaTeX source files that can be run with "pdflatex" + to produce PDF documents. + A "make update" updates the Subversion checkouts in `tools/`. diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 03484de..52a8415 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -15,6 +15,17 @@ Glossary ``...`` The typical Python prompt of the interactive shell when entering code for an indented code block. + + argument + A value passed to a function or method, assigned to a name local to + the body. A function or method may have both positional arguments and + keyword arguments in its definition. Positional and keyword arguments + may be variable-length: ``*`` accepts or passes (if in the function + definition or call) several positional arguments in a list, while ``**`` + does the same for keyword arguments in a dictionary. + + Any expression may be used within the argument list, and the evaluated + value is passed to the local variable. BDFL Benevolent Dictator For Life, a.k.a. `Guido van Rossum @@ -57,6 +68,22 @@ Glossary advanced mathematical feature. If you're not aware of a need for them, it's almost certain you can safely ignore them. + decorator + A function returning another function, usually applied as a function + transformation using the ``@wrapper`` syntax. Common examples for + decorators are :func:`classmethod` and :func:`staticmethod`. + + The decorator syntax is merely syntactic sugar, the following two + function definitions are semantically equivalent:: + + def f(...): + ... + f = staticmethod(f) + + @staticmethod + def f(...): + ... + descriptor Any *new-style* object that defines the methods :meth:`__get__`, :meth:`__set__`, or :meth:`__delete__`. When a class attribute is a @@ -94,10 +121,24 @@ Glossary statements. The technique contrasts with the :term:`LBYL` style that is common in many other languages such as C. + expression + A piece of syntax which can be evaluated to some value. In other words, + an expression is an accumulation of expression elements like literals, names, + attribute access, operators or function calls that all return a value. + In contrast to other languages, not all language constructs are expressions, + but there are also :term:`statement`\s that cannot be used as expressions, + such as :keyword:`print` or :keyword:`if`. Assignments are also not + expressions. + extension module A module written in C, using Python's C API to interact with the core and with user code. - + + function + A series of statements which returns some value to a caller. It can also + be passed zero or more arguments which may be used in the execution of + the body. See also :term:`argument` and :term:`method`. + __future__ A pseudo module which programmers can use to enable new language features which are not compatible with the current interpreter. For example, the @@ -241,6 +282,17 @@ Glossary More information can be found in :ref:`typeiter`. + keyword argument + Arguments which are preceded with a ``variable_name=`` in the call. + The variable name designates the local name in the function to which the + value is assigned. ``**`` is used to accept or pass a dictionary of + keyword arguments. See :term:`argument`. + + lambda + An anonymous inline function consisting of a single :term:`expression` + which is evaluated when the function is called. The syntax to create + a lambda function is ``lambda [arguments]: expression`` + LBYL Look before you leap. This coding style explicitly tests for pre-conditions before making calls or lookups. This style contrasts with @@ -271,6 +323,12 @@ Glossary singletons, and many other tasks. More information can be found in :ref:`metaclasses`. + + method + A function that is defined inside a class body. If called as an attribute + of an instance of that class, the method will get the instance object as + its first :term:`argument` (which is usually called ``self``). + See :term:`function` and :term:`nested scope`. mutable Mutable objects can change their value but keep their :func:`id`. See @@ -305,10 +363,32 @@ Glossary More information can be found in :ref:`newstyle`. + positional argument + The arguments assigned to local names inside a function or method, + determined by the order in which they were given in the call. ``*`` is + used to either accept multiple positional arguments (when in the + definition), or pass several arguments as a list to a function. See + :term:`argument`. + Python 3000 Nickname for the next major Python version, 3.0 (coined long ago when the release of version 3 was something in the distant future.) + Pythonic + An idea or piece of code which closely follows the most common idioms of + the Python language, rather than implementing code using concepts common + in other languages. For example, a common idiom in Python is the :keyword:`for` + loop structure; other languages don't have this easy keyword, so people + use a numerical counter instead:: + + for i in range(len(food)): + print food[i] + + As opposed to the cleaner, Pythonic method:: + + for piece in food: + print piece + reference count The number of places where a certain object is referenced to. When the reference count drops to zero, an object is deallocated. While reference @@ -331,6 +411,18 @@ Glossary mapping rather than a sequence because the lookups use arbitrary :term:`immutable` keys rather than integers. + slice + A list containing a portion of an indexed list-like object. A slice is + created using the subscript notation, ``[]`` with colons between numbers + when several are given, such as in ``variable_name[1:3:5]``. The bracket + (subscript) notation uses :class:`slice` objects internally (or in older + versions, :meth:`__getslice__` and :meth:`__setslice__`). + + statement + A statement is part of a suite (a "block" of code). A statement is either + an :term:`expression` or a one of several constructs with a keyword, such + as :keyword:`if`, :keyword:`while` or :keyword:`print`. + type The type of a Python object determines what kind of object it is; every object has a type. An object's type is accessible as its diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst index 0c3cc3e..35bd3fe 100644 --- a/Doc/library/atexit.rst +++ b/Doc/library/atexit.rst @@ -96,7 +96,7 @@ passed along to the registered function when it is called:: # or: atexit.register(goodbye, adjective='nice', name='Donny') -Usage as a decorator:: +Usage as a :term:`decorator`:: import atexit diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst index c44f9e3..a8a61f1 100644 --- a/Doc/library/bdb.rst +++ b/Doc/library/bdb.rst @@ -290,7 +290,7 @@ structure representing a stack trace. The following two methods can be called by clients to use a debugger to debug a -statement, given as a string. +:term:`statement`, given as a string. .. method:: Bdb.run(cmd, [globals, [locals]]) diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index 5bab2af..c6dc0a3 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -1119,9 +1119,9 @@ the table. | | | | all conversions. Can be | | | | | used as the system | | | | | encoding if no automatic | -| | | | coercion between byte and | -| | | | Unicode strings is | -| | | | desired. | +| | | | :term:`coercion` between | +| | | | byte and Unicode strings | +| | | | is desired. | +--------------------+---------------------------+----------------+---------------------------+ | unicode_escape | | Unicode string | Produce a string that is | | | | | suitable as Unicode | diff --git a/Doc/library/codeop.rst b/Doc/library/codeop.rst index 419e873..35430b4 100644 --- a/Doc/library/codeop.rst +++ b/Doc/library/codeop.rst @@ -43,8 +43,8 @@ To do just the former: :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal. The *symbol* argument determines whether *source* is compiled as a statement - (``'single'``, the default) or as an expression (``'eval'``). Any other value - will cause :exc:`ValueError` to be raised. + (``'single'``, the default) or as an :term:`expression` (``'eval'``). Any + other value will cause :exc:`ValueError` to be raised. .. warning:: diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index a4b271f..11af432 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -17,9 +17,9 @@ Functions provided: .. function:: contextmanager(func) - This function is a decorator that can be used to define a factory function for - :keyword:`with` statement context managers, without needing to create a class or - separate :meth:`__enter__` and :meth:`__exit__` methods. + This function is a :term:`decorator` that can be used to define a factory + function for :keyword:`with` statement context managers, without needing to + create a class or separate :meth:`__enter__` and :meth:`__exit__` methods. A simple example (this is not recommended as a real way of generating HTML!):: diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 88ccb86..acc8d1b 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -1135,7 +1135,8 @@ capabilities, then you should use the advanced API. The advanced API revolves around two container classes, which are used to store the interactive examples extracted from doctest cases: -* :class:`Example`: A single python statement, paired with its expected output. +* :class:`Example`: A single python :term:`statement`, paired with its expected + output. * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted from a single docstring or text file. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 1261547..1e71198 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -161,8 +161,8 @@ available. They are listed here in alphabetical order. @classmethod def f(cls, arg1, arg2, ...): ... - The ``@classmethod`` form is a function decorator -- see the description of - function definitions in :ref:`function` for details. + The ``@classmethod`` form is a function :term:`decorator` -- see the description + of function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. If a class @@ -825,7 +825,7 @@ available. They are listed here in alphabetical order. If given, *doc* will be the docstring of the property attribute. Otherwise, the property will copy *fget*'s docstring (if it exists). This makes it possible to - create read-only properties easily using :func:`property` as a decorator:: + create read-only properties easily using :func:`property` as a :term:`decorator`:: class Parrot(object): def __init__(self): @@ -1015,7 +1015,7 @@ available. They are listed here in alphabetical order. .. index:: single: Numerical Python - Return a slice object representing the set of indices specified by + Return a :term:`slice` object representing the set of indices specified by ``range(start, stop, step)``. The *start* and *step* arguments default to ``None``. Slice objects have read-only data attributes :attr:`start`, :attr:`stop` and :attr:`step` which merely return the argument values (or their @@ -1063,8 +1063,8 @@ available. They are listed here in alphabetical order. @staticmethod def f(arg1, arg2, ...): ... - The ``@staticmethod`` form is a function decorator -- see the description of - function definitions in :ref:`function` for details. + The ``@staticmethod`` form is a function :term:`decorator` -- see the + description of function definitions in :ref:`function` for details. It can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index f2f17b8..0f94848 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -68,9 +68,9 @@ The :mod:`functools` module defines the following functions: *WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the instance dictionary). - The main intended use for this function is in decorator functions which wrap the - decorated function and return the wrapper. If the wrapper function is not - updated, the metadata of the returned function will reflect the wrapper + The main intended use for this function is in :term:`decorator` functions which + wrap the decorated function and return the wrapper. If the wrapper function is + not updated, the metadata of the returned function will reflect the wrapper definition rather than the original function definition, which is typically less than helpful. diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 2c8041d..fbc9d04 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -235,7 +235,7 @@ Note: .. function:: isfunction(object) - Return true if the object is a Python function or unnamed (lambda) function. + Return true if the object is a Python function or unnamed (:term:`lambda`) function. .. function:: istraceback(object) diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst index 499a822..ea4d328 100644 --- a/Doc/library/operator.rst +++ b/Doc/library/operator.rst @@ -280,10 +280,10 @@ Operations which work with sequences include: Many operations have an "in-place" version. The following functions provide a more primitive access to in-place operators than the usual syntax does; for -example, the statement ``x += y`` is equivalent to ``x = operator.iadd(x, y)``. -Another way to put it is to say that ``z = operator.iadd(x, y)`` is equivalent -to the compound statement ``z = x; z += y``. - +example, the :term:`statement` ``x += y`` is equivalent to +``x = operator.iadd(x, y)``. Another way to put it is to say that +``z = operator.iadd(x, y)`` is equivalent to the compound statement +``z = x; z += y``. .. function:: iadd(a, b) __iadd__(a, b) diff --git a/Doc/library/sets.rst b/Doc/library/sets.rst index f9f8b59..88e442a 100644 --- a/Doc/library/sets.rst +++ b/Doc/library/sets.rst @@ -228,9 +228,9 @@ Sets can only contain immutable elements. For convenience, mutable :class:`Set` objects are automatically copied to an :class:`ImmutableSet` before being added as a set element. -The mechanism is to always add a hashable element, or if it is not hashable, the -element is checked to see if it has an :meth:`__as_immutable__` method which -returns an immutable equivalent. +The mechanism is to always add a :term:`hashable` element, or if it is not +hashable, the element is checked to see if it has an :meth:`__as_immutable__` +method which returns an immutable equivalent. Since :class:`Set` objects have a :meth:`__as_immutable__` method returning an instance of :class:`ImmutableSet`, it is possible to construct sets of sets. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 7419944..6b77d5b 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2191,8 +2191,8 @@ 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 :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a -convenient way to implement these protocols. If a generator function is +Python's :term:`generator`\s and the ``contextlib.contextfactory`` :term:`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 :meth:`__exit__` methods, rather than the iterator produced by an undecorated diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 5669e35..f9c7f29 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -86,9 +86,9 @@ always available. If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves it in ``__builtin__._``. - ``sys.displayhook`` is called on the result of evaluating an expression entered - in an interactive Python session. The display of these values can be customized - by assigning another one-argument function to ``sys.displayhook``. + ``sys.displayhook`` is called on the result of evaluating an :term:`expression` + entered in an interactive Python session. The display of these values can be + customized by assigning another one-argument function to ``sys.displayhook``. .. function:: excepthook(type, value, traceback) @@ -617,12 +617,12 @@ always available. File objects corresponding to the interpreter's standard input, output and error streams. ``stdin`` is used for all interpreter input except for scripts but including calls to :func:`input` and :func:`raw_input`. ``stdout`` is used for - the output of :keyword:`print` and expression statements and for the prompts of - :func:`input` and :func:`raw_input`. The interpreter's own prompts and (almost - all of) its error messages go to ``stderr``. ``stdout`` and ``stderr`` needn't - be built-in file objects: any object is acceptable as long as it has a - :meth:`write` method that takes a string argument. (Changing these objects - doesn't affect the standard I/O streams of processes executed by + the output of :keyword:`print` and :term:`expression` statements and for the + prompts of :func:`input` and :func:`raw_input`. The interpreter's own prompts + and (almost all of) its error messages go to ``stderr``. ``stdout`` and + ``stderr`` needn't be built-in file objects: any object is acceptable as long + as it has a :meth:`write` method that takes a string argument. (Changing these + objects doesn't affect the standard I/O streams of processes executed by :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in the :mod:`os` module.) diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst index fe3c16c..c545b97 100644 --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -88,11 +88,12 @@ The module defines the following public class: .. note:: - By default, :meth:`timeit` temporarily turns off garbage collection during the - timing. The advantage of this approach is that it makes independent timings - more comparable. This disadvantage is that GC may be an important component of - the performance of the function being measured. If so, GC can be re-enabled as - the first statement in the *setup* string. For example:: + By default, :meth:`timeit` temporarily turns off :term:`garbage collection` + during the timing. The advantage of this approach is that it makes + independent timings more comparable. This disadvantage is that GC may be + an important component of the performance of the function being measured. + If so, GC can be re-enabled as the first statement in the *setup* string. + For example:: timeit.Timer('for i in xrange(10): oct(i)', 'gc.enable()').timeit() diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 225991a..7d9c588 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -22,22 +22,22 @@ In the following, the term :dfn:`referent` means the object which is referred to by a weak reference. A weak reference to an object is not enough to keep the object alive: when the -only remaining references to a referent are weak references, garbage collection -is free to destroy the referent and reuse its memory for something else. A -primary use for weak references is to implement caches or mappings holding large -objects, where it's desired that a large object not be kept alive solely because -it appears in a cache or mapping. For example, if you have a number of large -binary image objects, you may wish to associate a name with each. If you used a -Python dictionary to map names to images, or images to names, the image objects -would remain alive just because they appeared as values or keys in the -dictionaries. The :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` -classes supplied by the :mod:`weakref` module are an alternative, using weak -references to construct mappings that don't keep objects alive solely because -they appear in the mapping objects. If, for example, an image object is a value -in a :class:`WeakValueDictionary`, then when the last remaining references to -that image object are the weak references held by weak mappings, garbage -collection can reclaim the object, and its corresponding entries in weak -mappings are simply deleted. +only remaining references to a referent are weak references, +:term:`garbage collection` is free to destroy the referent and reuse its memory +for something else. A primary use for weak references is to implement caches or +mappings holding large objects, where it's desired that a large object not be +kept alive solely because it appears in a cache or mapping. For example, if you +have a number of large binary image objects, you may wish to associate a name +with each. If you used a Python dictionary to map names to images, or images to +names, the image objects would remain alive just because they appeared as values +or keys in the dictionaries. The :class:`WeakKeyDictionary` and +:class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are +an alternative, using weak references to construct mappings that don't keep +objects alive solely because they appear in the mapping objects. If, for +example, an image object is a value in a :class:`WeakValueDictionary`, then when +the last remaining references to that image object are the weak references held +by weak mappings, garbage collection can reclaim the object, and its +corresponding entries in weak mappings are simply deleted. :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references in their implementation, setting up callback functions on the weak references diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index cebdcf1..9c6135c 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -428,7 +428,7 @@ when the function is called. The function definition does not execute the function body; this gets executed only when the function is called. -A function definition may be wrapped by one or more decorator expressions. +A function definition may be wrapped by one or more :term:`decorator` expressions. Decorator expressions are evaluated when the function is defined, in the scope that contains the function definition. The result must be a callable, which is invoked with the function object as the only argument. The returned value is diff --git a/Doc/tutorial/stdlib2.rst b/Doc/tutorial/stdlib2.rst index 9de2bc0..14c60dd 100644 --- a/Doc/tutorial/stdlib2.rst +++ b/Doc/tutorial/stdlib2.rst @@ -239,8 +239,8 @@ Weak References =============== Python does automatic memory management (reference counting for most objects and -garbage collection to eliminate cycles). The memory is freed shortly after the -last reference to it has been eliminated. +:term:`garbage collection` to eliminate cycles). The memory is freed shortly +after the last reference to it has been eliminated. This approach works fine for most applications but occasionally there is a need to track objects only as long as they are being used by something else. |