the C functions with \samp{AL} prefixed to their name.
Symbolic constants from the C header file \code{<audio.h>} are
-defined in the standard module \module{AL}\refstmodindex{AL}, see
-below.
+defined in the standard module
+\refmodule[al-constants]{AL}\refstmodindex{AL}, see below.
\strong{Warning:} the current version of the audio library may dump core
when bad argument values are passed rather than returning an error
This module defines symbolic constants needed to use the built-in
-module \module{al} (see above); they are equivalent to those defined
+module \refmodule{al} (see above); they are equivalent to those defined
in the C header file \code{<audio.h>} except that the name prefix
\samp{AL_} is omitted. Read the module source for a complete list of
the defined names. Suggested use:
\section{\module{audioop} ---
- Manipulate raw audio data.}
-\declaremodule{builtin}{audioop}
+ Manipulate raw audio data}
+\declaremodule{builtin}{audioop}
\modulesynopsis{Manipulate raw audio data.}
The \module{audioop} module contains some useful operations on sound
fragments. It operates on sound fragments consisting of signed
integer samples 8, 16 or 32 bits wide, stored in Python strings. This
-is the same format as used by the \module{al} and \module{sunaudiodev}
+is the same format as used by the \refmodule{al} and \refmodule{sunaudiodev}
modules. All scalar items are integers, unless specified otherwise.
% This para is mostly here to provide an excuse for the index entries...
\section{\module{binascii} ---
- Convert between binary and various ascii-encoded representations.}
-\declaremodule{builtin}{binascii}
+ Convert between binary \ASCII{}-encoded formats}
+\declaremodule{builtin}{binascii}
\modulesynopsis{Tools for converting between binary and various
-ascii-encoded binary representations.}
+ \ASCII{}-encoded binary representations.}
The \module{binascii} module contains a number of methods to convert
between binary and various \ASCII{}-encoded binary
-representations. Normally, you will not use these modules directly but
-use wrapper modules like \module{uu}\refstmodindex{uu} or
+representations. Normally, you will not use these functions directly
+but use wrapper modules like \refmodule{uu}\refstmodindex{uu} or
\module{hexbin}\refstmodindex{hexbin} instead, this module solely
exists because bit-manipuation of large amounts of data is slow in
Python.
\section{\module{copy_reg} ---
- Register \module{pickle} support functions.}
-\declaremodule[copyreg]{standard}{copy_reg}
+ Register \module{pickle} support functions}
+\declaremodule[copyreg]{standard}{copy_reg}
\modulesynopsis{Register \module{pickle} support functions.}
The \module{copy_reg} module provides support for the
-\module{pickle}\refstmodindex{pickle} and
-\module{cPickle}\refbimodindex{cPickle} modules. The
-\module{copy}\refstmodindex{copy} module is likely to use this in the
+\refmodule{pickle}\refstmodindex{pickle} and
+\refmodule{cPickle}\refbimodindex{cPickle} modules. The
+\refmodule{copy}\refstmodindex{copy} module is likely to use this in the
future as well. It provides configuration information about object
constructors which are not classes. Such constructors may be factory
functions or class instances.
\section{Built-in Exceptions}
-\declaremodule{standard}{exceptions}
+\declaremodule{standard}{exceptions}
\modulesynopsis{Standard exceptions classes.}
\begin{excdesc}{OSError}
%xref for os module
This class is derived from \exception{EnvironmentError} and is used
- primarily as the \module{os} module's \code{os.error} exception.
+ primarily as the \refmodule{os} module's \code{os.error} exception.
See \exception{EnvironmentError} above for a description of the
possible associated values.
\versionadded{1.5.2}
This module supports two interface definitions, each with mulitple
implementations. The \emph{formatter} interface is used by the
-\class{HTMLParser} class of the \module{htmllib} module, and the
+\class{HTMLParser} class of the \refmodule{htmllib} module, and the
\emph{writer} interface is required by the formatter interface.
\withsubitem{(class in htmllib)}{\ttindex{HTMLParser}}
\envvar{USER}, \envvar{LNAME} and \envvar{USERNAME}, in order, and
returns the value of the first one which is set to a non-empty
string. If none are set, the login name from the password database
- is returned on systems which support the \module{pwd} module,
+ is returned on systems which support the \refmodule{pwd} module,
otherwise, an exception is raised.
\end{funcdesc}
\section{\module{imageop} ---
- Manipulate raw image data.}
-\declaremodule{builtin}{imageop}
+ Manipulate raw image data}
+\declaremodule{builtin}{imageop}
\modulesynopsis{Manipulate raw image data.}
The \module{imageop} module contains some useful operations on images.
It operates on images consisting of 8 or 32 bit pixels stored in
Python strings. This is the same format as used by
-\function{gl.lrectwrite()} and the \module{imgfile} module.
+\function{gl.lrectwrite()} and the \refmodule{imgfile} module.
The module defines the following variables and functions:
\section{\module{marshal} ---
Alternate Python object serialization}
-\declaremodule{builtin}{marshal}
+\declaremodule{builtin}{marshal}
\modulesynopsis{Convert Python objects to streams of bytes and back
-(with different constraints).}
+ (with different constraints).}
This module contains functions that can read and write Python
This is not a general ``persistency'' module. For general persistency
and transfer of Python objects through RPC calls, see the modules
-\module{pickle} and \module{shelve}. The \module{marshal} module exists
+\refmodule{pickle} and \refmodule{shelve}. The \module{marshal} module exists
mainly to support reading and writing the ``pseudo-compiled'' code for
Python modules of \file{.pyc} files.
\refstmodindex{pickle}
one. The first element is an integer which identifies a production in
the grammar. These integers are given symbolic names in the C header
file \file{Include/graminit.h} and the Python module
-\module{symbol}. Each additional element of the sequence represents
+\refmodule{symbol}. Each additional element of the sequence represents
a component of the production as recognized in the input string: these
are always sequences which have the same form as the parent. An
important aspect of this structure which should be noted is that
identified. The example of the \keyword{if} keyword above is
representative. The various types of terminal symbols are defined in
the C header file \file{Include/token.h} and the Python module
-\module{token}.
+\refmodule{token}.
The AST objects are not required to support the functionality of this
module, but are provided for three purposes: to allow an application
\function{sequence2ast()} have no methods of their own.
Ordered and equality comparisons are supported between AST objects.
-Pickling of AST objects (using the \module{pickle} module) is also
+Pickling of AST objects (using the \refmodule{pickle} module) is also
supported.
\begin{datadesc}{ASTType}
types; they map directly to terminal and non-terminal symbols in the
grammar. Unfortunately, they are represented as integers in the
internal representation, and the Python structures generated do not
-change that. However, the \module{symbol} and \module{token} modules
+change that. However, the \refmodule{symbol} and \refmodule{token} modules
provide symbolic names for the node types and dictionaries which map
from the integers to the symbolic names for the node types.
\section{\module{pickle} ---
- Python object serialization.}
-\declaremodule{standard}{pickle}
+ Python object serialization}
+\declaremodule{standard}{pickle}
\modulesynopsis{Convert Python objects to streams of bytes and back.}
\index{persistency}
the same internal structure. The most obvious thing to do with these
byte streams is to write them onto a file, but it is also conceivable
to send them across a network or store them in a database. The module
-\module{shelve} provides a simple interface to pickle and unpickle
-objects on ``dbm''-style database files.
-\refstmodindex{shelve}
+\refmodule{shelve}\refstmodindex{shelve} provides a simple interface
+to pickle and unpickle objects on DBM-style database files.
+
\strong{Note:} The \module{pickle} module is rather slow. A
-reimplementation of the same algorithm in \C{}, which is up to 1000 times
-faster, is available as the \module{cPickle}\refbimodindex{cPickle}
+reimplementation of the same algorithm in C, which is up to 1000 times
+faster, is available as the \refmodule{cPickle}\refbimodindex{cPickle}
module. This has the same interface except that \code{Pickler} and
\code{Unpickler} are factory functions, not classes (so they cannot be
used as base classes for inheritance).
-Unlike the built-in module \module{marshal}, \module{pickle} handles
-the following correctly:
-\refbimodindex{marshal}
+Unlike the built-in module \refmodule{marshal}\refbimodindex{marshal},
+\module{pickle} handles the following correctly:
+
\begin{itemize}
The data format used by \module{pickle} is Python-specific. This has
the advantage that there are no restrictions imposed by external
-standards such as XDR%
-\index{XDR}
-\index{External Data Representation}
-(which can't represent pointer sharing); however
-it means that non-Python programs may not be able to reconstruct
-pickled Python objects.
+standards such as
+XDR\index{XDR}\index{External Data Representation} (which can't
+represent pointer sharing); however it means that non-Python programs
+may not be able to reconstruct pickled Python objects.
By default, the \module{pickle} data format uses a printable \ASCII{}
representation. This is slightly more voluminous than a binary
the default may change to binary.
The \module{pickle} module doesn't handle code objects, which the
-\module{marshal} module does. I suppose \module{pickle} could, and maybe
+\refmodule{marshal} module does. I suppose \module{pickle} could, and maybe
it should, but there's probably no great need for it right now (as
-long as \module{marshal} continues to be used for reading and writing
+long as \refmodule{marshal} continues to be used for reading and writing
code objects), and at least this avoids the possibility of smuggling
Trojan horses into a program.
\refbimodindex{marshal}
instance's dictionary. (If a class defines both \method{__getstate__()}
and \method{__setstate__()}, the state object needn't be a dictionary
--- these methods can do what they want.) This protocol is also used
-by the shallow and deep copying operations defined in the \module{copy}
-module.\refstmodindex{copy}
+by the shallow and deep copying operations defined in the
+\refmodule{copy}\refstmodindex{copy} module.
\ttindex{__getstate__()}
\ttindex{__setstate__()}
\ttindex{__dict__}
\begin{seealso}
-\seemodule[copyreg]{copy_reg}{pickle interface constructor
-registration}
+ \seemodule[copyreg]{copy_reg}{pickle interface constructor
+ registration}
-\seemodule{shelve}{indexed databases of objects; uses \module{pickle}}
+ \seemodule{shelve}{indexed databases of objects; uses \module{pickle}}
-\seemodule{copy}{shallow and deep object copying}
+ \seemodule{copy}{shallow and deep object copying}
-\seemodule{marshal}{high-performance serialization of built-in types}
+ \seemodule{marshal}{high-performance serialization of built-in types}
\end{seealso}
\section{\module{cPickle} ---
- Alternate implementation of \module{pickle}.}
-\declaremodule{builtin}{cPickle}
+ Alternate implementation of \module{pickle}}
+\declaremodule{builtin}{cPickle}
\modulesynopsis{Faster version of \module{pickle}, but not subclassable.}
+\moduleauthor{Jim Fulton}{jfulton@digicool.com}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
-% This section was written by Fred L. Drake, Jr. <fdrake@acm.org>
-
The \module{cPickle} module provides a similar interface and identical
-functionality as the \module{pickle} module, but can be up to 1000
-times faster since it is implemented in \C{}. The only other
+functionality as the \refmodule{pickle} module, but can be up to 1000
+times faster since it is implemented in C. The only other
important difference to note is that \function{Pickler()} and
\function{Unpickler()} are functions and not classes, and so cannot be
subclassed. This should not be an issue in most cases.
The format of the pickle data is identical to that produced using the
-\module{pickle} module, so it is possible to use \module{pickle} and
+\refmodule{pickle} module, so it is possible to use \refmodule{pickle} and
\module{cPickle} interchangably with existing pickles.
(Since the pickle data format is actually a tiny stack-oriented
0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
expression (to pattern match the standard name that is printed; as of
Python 1.5b1, this uses the Perl-style regular expression syntax
-defined by the \module{re} module). If several restrictions are
+defined by the \refmodule{re} module). If several restrictions are
provided, then they are applied sequentially. For example:
\begin{verbatim}
\declaremodule{standard}{quopri}
\modulesynopsis{Encode and decode files using the MIME
-quoted-printable encoding.}
+ quoted-printable encoding.}
This module performs quoted-printable transport encoding and decoding,
as defined in \rfc{1521}: ``MIME (Multipurpose Internet Mail Extensions)
Part One''. The quoted-printable encoding is designed for data where
there are relatively few nonprintable characters; the base64 encoding
-scheme available via the \module{base64} module is more compact if there
+scheme available via the \refmodule{base64} module is more compact if there
are many such characters, as when sending a graphics file.
\indexii{quoted-printable}{encoding}
\index{MIME!quoted-printable encoding}
\section{\module{regsub} ---
- Substitution and splitting operations that use regular expressions.}
-\declaremodule{standard}{regsub}
+ String operations using regular expressions}
-\modulesynopsis{Substitution and splitting operations that use regular expressions.}
+\declaremodule{standard}{regsub}
+\modulesynopsis{Substitution and splitting operations that use
+ regular expressions.}
This module defines a number of functions useful for working with
-regular expressions (see built-in module \code{regex}).
+regular expressions (see built-in module \refmodule{regex}).
Warning: these functions are not thread-safe.
\strong{Obsolescence note:}
This module is obsolete as of Python version 1.5; it is still being
maintained because much existing code still uses it. All new code in
-need of regular expressions should use the new \module{re} module, which
+need of regular expressions should use the new \refmodule{re} module, which
supports the more powerful and regular Perl-style regular expressions.
Existing code should be converted. The standard library module
-\module{reconvert} helps in converting \code{regex} style regular
-expressions to \module{re} style regular expressions. (For more
+\module{reconvert} helps in converting \refmodule{regex} style regular
+expressions to \refmodule{re} style regular expressions. (For more
conversion help, see Andrew Kuchling's\index{Kuchling, Andrew}
``regex-to-re HOWTO'' at
\url{http://www.python.org/doc/howto/regex-to-re/}.)
\section{\module{rexec} ---
- Basic restricted execution framework.}
-\declaremodule{standard}{rexec}
+ Restricted execution framework}
+\declaremodule{standard}{rexec}
\modulesynopsis{Basic restricted execution framework.}
\var{hooks} is an instance of the \class{RHooks} class or a subclass of it.
If it is omitted or \code{None}, the default \class{RHooks} class is
instantiated.
-Whenever the \module{RExec} module searches for a module (even a
+Whenever the \module{rexec} module searches for a module (even a
built-in one) or reads a module's code, it doesn't actually go out to
the file system itself. Rather, it calls methods of an \class{RHooks}
instance that was passed to or created by its constructor. (Actually,
\begin{memberdesc}{ok_posix_names}
% Should this be called ok_os_names?
-Contains the names of the functions in the \module{os} module which will be
+Contains the names of the functions in the \refmodule{os} module which will be
available to programs running in the restricted environment. The
value for \class{RExec} is \code{('error',} \code{'fstat',}
\code{'listdir',} \code{'lstat',} \code{'readlink',} \code{'stat',}
\end{memberdesc}
\begin{memberdesc}{ok_sys_names}
-Contains the names of the functions and variables in the \module{sys}
+Contains the names of the functions and variables in the \refmodule{sys}
module which will be available to programs running in the restricted
environment. The value for \class{RExec} is \code{('ps1',}
\code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}
\section{\module{rfc822} ---
- Parse RFC 822 mail headers.}
-\declaremodule{standard}{rfc822}
+ Parse RFC 822 mail headers}
+\declaremodule{standard}{rfc822}
\modulesynopsis{Parse \rfc{822} style mail headers.}
This module defines a class, \class{Message}, which represents a
\class{AddressList} for parsing RFC822 addresses.
Note that there's a separate module to read \UNIX{}, MH, and MMDF
-style mailbox files: \module{mailbox}\refstmodindex{mailbox}.
+style mailbox files: \refmodule{mailbox}\refstmodindex{mailbox}.
\begin{classdesc}{Message}{file\optional{, seekable}}
A \class{Message} instance is instantiated with an input object as
\section{\module{shelve} ---
Python object persistency}
-\declaremodule{standard}{shelve}
+\declaremodule{standard}{shelve}
\modulesynopsis{Python object persistency.}
\seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.}
\seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.}
\seemodule{pickle}{Object serialization used by \module{shelve}.}
- \seemodule{cPickle}{High-performance version of \module{pickle}.}
+ \seemodule{cPickle}{High-performance version of \refmodule{pickle}.}
\end{seealso}
under X11, Win32 for Windows and Windows NT, and a collection of
native toolkit interfaces for the Macintosh.
+
\section{\module{stdwin} ---
Platform-independent GUI System}
-\declaremodule{builtin}{stdwin}
-\modulesynopsis{Older GUI system for X11 and Macintosh}
+\declaremodule{builtin}{stdwin}
+\modulesynopsis{Older GUI system for X11 and Macintosh.}
This module defines several new object types and functions that
if it applies to no window in particular;
the third element is type-dependent.
Names for event types and command codes are defined in the standard
-module \module{stdwinevent}.
+module \refmodule{stdwinevents}.
\end{funcdesc}
\begin{funcdesc}{pollevent}{}
\begin{funcdesc}{getselection}{i}
Return X11 selection number \var{i.} Selections are not cut buffers.
-Selection numbers are defined in module \module{stdwinevents}.
+Selection numbers are defined in module \refmodule{stdwinevents}.
Selection \constant{WS_PRIMARY} is the \dfn{primary} selection (used
by \program{xterm}, for instance); selection \constant{WS_SECONDARY}
is the \dfn{secondary} selection; selection \constant{WS_CLIPBOARD} is
Pass an arrow event to the text-edit block.
The \var{code} must be one of \constant{WC_LEFT}, \constant{WC_RIGHT},
\constant{WC_UP} or \constant{WC_DOWN} (see module
-\module{stdwinevents}).
+\refmodule{stdwinevents}).
\end{methoddesc}
\begin{methoddesc}[text-edit]{draw}{rect}
main()
\end{verbatim}
+
\section{\module{stdwinevents} ---
Constants for use with \module{stdwin}}
-\declaremodule{standard}{stdwinevents}
+\declaremodule{standard}{stdwinevents}
\modulesynopsis{Constant definitions for use with \module{stdwin}}
>>>
\end{verbatim}
+
\section{\module{rect} ---
Functions for use with \module{stdwin}}
-\declaremodule{standard}{rect}
-\modulesynopsis{Geometry-related utility function for use with \module{stdwin}}
+\declaremodule{standard}{rect}
+\modulesynopsis{Geometry-related utility function for use with
+ \module{stdwin}.}
This module contains useful operations on rectangles.
-A rectangle is defined as in module \module{stdwin}:
+A rectangle is defined as in module \refmodule{stdwin}:
a pair of points, where a point is a pair of integers.
For example, the rectangle
is a rectangle whose left, top, right and bottom edges are 10, 20, 90
and 80, respectively. Note that the positive vertical axis points
-down (as in \module{stdwin}).
+down (as in \refmodule{stdwin}).
The module defines the following objects:
\section{\module{string} ---
- Common string operations.}
-\declaremodule{standard}{string}
+ Common string operations}
+\declaremodule{standard}{string}
\modulesynopsis{Common string operations.}
This module defines some constants useful for checking character
classes and some useful string functions. See the module
-\module{re}\refstmodindex{re} for string functions based on regular
+\refmodule{re}\refstmodindex{re} for string functions based on regular
expressions.
The constants defined in this module are are:
\section{\module{sys} ---
- System-specific parameters and functions.}
-\declaremodule{builtin}{sys}
+ System-specific parameters and functions}
+\declaremodule{builtin}{sys}
\modulesynopsis{Access system-specific parameters and functions.}
This module provides access to some variables used or maintained by the
a \method{write()} method that takes a string argument. (Changing these
objects doesn't affect the standard I/O streams of processes
executed by \function{os.popen()}, \function{os.system()} or the
- \function{exec*()} family of functions in the \module{os} module.)
+ \function{exec*()} family of functions in the \refmodule{os} module.)
\refstmodindex{os}
\end{datadesc}
This module constructs higher-level threading interfaces on top of the
-lower level \module{thread} module.
+lower level \refmodule{thread} module.
This module is safe for use with \samp{from threading import *}. It
defines the following functions and objects:
A primitive lock is a synchronization primitive that is not owned
by a particular thread when locked. In Python, it is currently
the lowest level synchronization primitive available, implemented
-directly by the \module{thread} extension module.
+directly by the \refmodule{thread} extension module.
A primitive lock is in one of two states, ``locked'' or ``unlocked''.
It is created in the unlocked state. It has two basic methods,
projects / python / commitdiff