Add more entries to the glossary.
Written by Jeff Wheeler for GHOP.
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 @@
* 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 @@
@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 @@
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 @@
``...``
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
# 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 @@
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 @@
| | | | 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 @@
: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 @@
.. 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 @@
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 @@
@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 @@
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 @@
.. 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 @@
@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 @@
*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 @@
.. 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
.. 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 @@
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 @@
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 @@
===============
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.