traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Relocating file to Doc/lib/

This commit is contained in:
Fred Drake 1998-05-07 01:49:07 +00:00
parent bbe33c5594
commit cda63cc875
142 changed files with 0 additions and 21211 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
Doc/lib.tex
View File

@ -1,234 +0,0 @@
\documentclass{manual}
% NOTE: this file controls which chapters/sections of the library
% manual are actually printed. It is easy to customize your manual
% by commenting out sections that you're not interested in.
\title{Python Library Reference}
\input{boilerplate}
\makeindex % tell \index to actually write the
% .idx file
\makemodindex % ... and the module index as well.
\begin{document}
\maketitle
\input{copyright}
\begin{abstract}
\noindent
Python is an extensible, interpreted, object-oriented programming
language. It supports a wide range of applications, from simple text
processing scripts to interactive WWW browsers.
While the \emph{Python Reference Manual} describes the exact syntax and
semantics of the language, it does not describe the standard library
that is distributed with the language, and which greatly enhances its
immediate usability. This library contains built-in modules (written
in C) that provide access to system functionality such as file I/O
that would otherwise be inaccessible to Python programmers, as well as
modules written in Python that provide standardized solutions for many
problems that occur in everyday programming. Some of these modules
are explicitly designed to encourage and enhance the portability of
Python programs.
This library reference manual documents Python's standard library, as
well as many optional library modules (which may or may not be
available, depending on whether the underlying platform supports them
and on the configuration choices made at compile time). It also
documents the standard types of the language and its built-in
functions and exceptions, many of which are not or incompletely
documented in the Reference Manual.
This manual assumes basic knowledge about the Python language. For an
informal introduction to Python, see the \emph{Python Tutorial}; the
\emph{Python Reference Manual} remains the highest authority on
syntactic and semantic questions. Finally, the manual entitled
\emph{Extending and Embedding the Python Interpreter} describes how to
add new extensions to Python and how to embed it in other applications.
\end{abstract}
\tableofcontents
% Chapter title:
\input{libintro} % Introduction
\input{libobjs} % Built-in Types, Exceptions and Functions
\input{libtypes}
\input{libexcs}
\input{libfuncs}
\input{libpython} % Python Services
\input{libsys}
\input{libtypes2} % types is already taken :-(
\input{libuserdict}
\input{liboperator}
\input{libtraceback}
\input{libpickle}
\input{libcopyreg}
\input{libshelve}
\input{libcopy}
\input{libmarshal}
\input{libimp}
%\input{libni}
\input{libparser}
\input{libsymbol}
\input{libtoken}
\input{libkeyword}
\input{libcode}
\input{libpprint}
\input{libdis}
\input{libsite}
\input{libuser}
\input{libbltin} % really __builtin__
\input{libmain} % really __main__
\input{libstrings} % String Services
\input{libstring}
\input{libre}
\input{libregex}
\input{libregsub}
\input{libstruct}
\input{libstrio}
%\input{libsoundex}
\input{libmisc} % Miscellaneous Services
\input{libmath}
\input{libcmath}
\input{libwhrandom}
\input{librandom}
%\input{librand}
\input{libbisect}
\input{libarray}
\input{libfileinput}
\input{libcalendar}
\input{liballos} % Generic Operating System Services
\input{libos}
\input{libtime}
\input{libgetopt}
\input{libtempfile}
\input{liberrno}
\input{libglob}
\input{libfnmatch}
\input{liblocale}
\input{libsomeos} % Optional Operating System Services
\input{libsignal}
\input{libsocket}
\input{libselect}
\input{libthread}
\input{libqueue}
\input{libanydbm}
\input{libwhichdb}
\input{libzlib}
\input{libgzip}
\input{libunix} % UNIX Specific Services
\input{libposix}
\input{libppath} % == posixpath
\input{libpwd}
\input{libgrp}
\input{libcrypt}
\input{libdbm}
\input{libgdbm}
\input{libtermios}
\input{libfcntl}
\input{libposixfile}
\input{libresource}
\input{libsyslog}
\input{libstat}
\input{libpopen2}
\input{libcommands}
\input{libpdb} % The Python Debugger
\input{libprofile} % The Python Profiler
\input{libwww} % Internet and WWW Services
\input{libcgi}
\input{liburllib}
\input{libhttplib}
\input{libftplib}
\input{libgopherlib}
\input{libpoplib}
\input{libimaplib}
\input{libnntplib}
\input{liburlparse}
\input{libsgmllib}
\input{libhtmllib}
\input{libxmllib}
\input{libformatter}
\input{librfc822}
\input{libmimetools}
\input{libbinhex}
\input{libuu}
\input{libbinascii}
\input{libxdrlib}
\input{libmailcap}
\input{libbase64}
\input{libquopri}
\input{libsocksvr}
\input{libmailbox}
\input{libmimify}
\input{libbasehttp}
\input{librestricted}
\input{librexec}
\input{libbastion}
\input{libmm} % Multimedia Services
\input{libaudioop}
\input{libimageop}
\input{libaifc}
\input{libjpeg}
\input{librgbimg}
\input{libimghdr}
\input{libcrypto} % Cryptographic Services
\input{libmd5}
\input{libmpz}
\input{librotor}
%\input{libamoeba} % AMOEBA ONLY
%\input{libstdwin} % STDWIN ONLY
\input{libsgi} % SGI IRIX ONLY
\input{libal}
\input{libcd}
\input{libfl}
\input{libfm}
\input{libgl}
\input{libimgfile}
%\input{libpanel}
\input{libsun} % SUNOS ONLY
\input{libsunaudio}
\input{libundoc}
%
% The ugly "%begin{latexonly}" pseudo-environments are really just to
% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
% not really valuable.
%
%begin{latexonly}
\renewcommand{\indexname}{Module Index}
%end{latexonly}
\input{modlib.ind} % Module Index
%begin{latexonly}
\renewcommand{\indexname}{Index}
%end{latexonly}
\input{lib.ind} % Index
\end{document}

194
Doc/libaifc.tex
View File

@ -1,194 +0,0 @@
\section{Standard Module \module{aifc}}
\label{module-aifc}
\stmodindex{aifc}
This module provides support for reading and writing AIFF and AIFF-C
files. AIFF is Audio Interchange File Format, a format for storing
digital audio samples in a file. AIFF-C is a newer version of the
format that includes the ability to compress the audio data.
\index{Audio Interchange File Format}
\index{AIFF}
\index{AIFF-C}
Audio files have a number of parameters that describe the audio data.
The sampling rate or frame rate is the number of times per second the
sound is sampled. The number of channels indicate if the audio is
mono, stereo, or quadro. Each frame consists of one sample per
channel. The sample size is the size in bytes of each sample. Thus a
frame consists of \var{nchannels}*\var{samplesize} bytes, and a
second's worth of audio consists of
\var{nchannels}*\var{samplesize}*\var{framerate} bytes.
For example, CD quality audio has a sample size of two bytes (16
bits), uses two channels (stereo) and has a frame rate of 44,100
frames/second. This gives a frame size of 4 bytes (2*2), and a
second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes.
Module \module{aifc} defines the following function:
\begin{funcdesc}{open}{file, mode}
Open an AIFF or AIFF-C file and return an object instance with
methods that are described below. The argument file is either a
string naming a file or a file object. The mode is either the string
\code{'r'} when the file must be opened for reading, or \code{'w'}
when the file must be opened for writing. When used for writing, the
file object should be seekable, unless you know ahead of time how many
samples you are going to write in total and use
\method{writeframesraw()} and \method{setnframes()}.
\end{funcdesc}
Objects returned by \function{open()} when a file is opened for
reading have the following methods:
\begin{methoddesc}[aifc]{getnchannels}{}
Return the number of audio channels (1 for mono, 2 for stereo).
\end{methoddesc}
\begin{methoddesc}[aifc]{getsampwidth}{}
Return the size in bytes of individual samples.
\end{methoddesc}
\begin{methoddesc}[aifc]{getframerate}{}
Return the sampling rate (number of audio frames per second).
\end{methoddesc}
\begin{methoddesc}[aifc]{getnframes}{}
Return the number of audio frames in the file.
\end{methoddesc}
\begin{methoddesc}[aifc]{getcomptype}{}
Return a four-character string describing the type of compression used
in the audio file. For AIFF files, the returned value is
\code{'NONE'}.
\end{methoddesc}
\begin{methoddesc}[aifc]{getcompname}{}
Return a human-readable description of the type of compression used in
the audio file. For AIFF files, the returned value is \code{'not
compressed'}.
\end{methoddesc}
\begin{methoddesc}[aifc]{getparams}{}
Return a tuple consisting of all of the above values in the above
order.
\end{methoddesc}
\begin{methoddesc}[aifc]{getmarkers}{}
Return a list of markers in the audio file. A marker consists of a
tuple of three elements. The first is the mark ID (an integer), the
second is the mark position in frames from the beginning of the data
(an integer), the third is the name of the mark (a string).
\end{methoddesc}
\begin{methoddesc}[aifc]{getmark}{id}
Return the tuple as described in \method{getmarkers()} for the mark
with the given \var{id}.
\end{methoddesc}
\begin{methoddesc}[aifc]{readframes}{nframes}
Read and return the next \var{nframes} frames from the audio file. The
returned data is a string containing for each frame the uncompressed
samples of all channels.
\end{methoddesc}
\begin{methoddesc}[aifc]{rewind}{}
Rewind the read pointer. The next \method{readframes()} will start from
the beginning.
\end{methoddesc}
\begin{methoddesc}[aifc]{setpos}{pos}
Seek to the specified frame number.
\end{methoddesc}
\begin{methoddesc}[aifc]{tell}{}
Return the current frame number.
\end{methoddesc}
\begin{methoddesc}[aifc]{close}{}
Close the AIFF file. After calling this method, the object can no
longer be used.
\end{methoddesc}
Objects returned by \function{open()} when a file is opened for
writing have all the above methods, except for \method{readframes()} and
\method{setpos()}. In addition the following methods exist. The
\method{get*()} methods can only be called after the corresponding
\method{set*()} methods have been called. Before the first
\method{writeframes()} or \method{writeframesraw()}, all parameters
except for the number of frames must be filled in.
\begin{methoddesc}[aifc]{aiff}{}
Create an AIFF file. The default is that an AIFF-C file is created,
unless the name of the file ends in \code{'.aiff'} in which case the
default is an AIFF file.
\end{methoddesc}
\begin{methoddesc}[aifc]{aifc}{}
Create an AIFF-C file. The default is that an AIFF-C file is created,
unless the name of the file ends in \code{'.aiff'} in which case the
default is an AIFF file.
\end{methoddesc}
\begin{methoddesc}[aifc]{setnchannels}{nchannels}
Specify the number of channels in the audio file.
\end{methoddesc}
\begin{methoddesc}[aifc]{setsampwidth}{width}
Specify the size in bytes of audio samples.
\end{methoddesc}
\begin{methoddesc}[aifc]{setframerate}{rate}
Specify the sampling frequency in frames per second.
\end{methoddesc}
\begin{methoddesc}[aifc]{setnframes}{nframes}
Specify the number of frames that are to be written to the audio file.
If this parameter is not set, or not set correctly, the file needs to
support seeking.
\end{methoddesc}
\begin{methoddesc}[aifc]{setcomptype}{type, name}
Specify the compression type. If not specified, the audio data will
not be compressed. In AIFF files, compression is not possible. The
name parameter should be a human-readable description of the
compression type, the type parameter should be a four-character
string. Currently the following compression types are supported:
NONE, ULAW, ALAW, G722.
\index{u-LAW}
\index{A-LAW}
\index{G.722}
\end{methoddesc}
\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname}
Set all the above parameters at once. The argument is a tuple
consisting of the various parameters. This means that it is possible
to use the result of a \method{getparams()} call as argument to
\method{setparams()}.
\end{methoddesc}
\begin{methoddesc}[aifc]{setmark}{id, pos, name}
Add a mark with the given id (larger than 0), and the given name at
the given position. This method can be called at any time before
\method{close()}.
\end{methoddesc}
\begin{methoddesc}[aifc]{tell}{}
Return the current write position in the output file. Useful in
combination with \method{setmark()}.
\end{methoddesc}
\begin{methoddesc}[aifc]{writeframes}{data}
Write data to the output file. This method can only be called after
the audio file parameters have been set.
\end{methoddesc}
\begin{methoddesc}[aifc]{writeframesraw}{data}
Like \method{writeframes()}, except that the header of the audio file
is not updated.
\end{methoddesc}
\begin{methoddesc}[aifc]{close}{}
Close the AIFF file. The header of the file is updated to reflect the
actual size of the audio data. After calling this method, the object
can no longer be used.
\end{methoddesc}

175
Doc/libal.tex
View File

@ -1,175 +0,0 @@
\section{Built-in Module \module{al}}
\label{module-al}
\bimodindex{al}
This module provides access to the audio facilities of the SGI Indy
and Indigo workstations. See section 3A of the IRIX man pages for
details. You'll need to read those man pages to understand what these
functions do! Some of the functions are not available in IRIX
releases before 4.0.5. Again, see the manual to check whether a
specific function is available on your platform.
All functions and methods defined in this module are equivalent to
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.
\strong{Warning:} the current version of the audio library may dump core
when bad argument values are passed rather than returning an error
status. Unfortunately, since the precise circumstances under which
this may happen are undocumented and hard to check, the Python
interface can provide no protection against this kind of problems.
(One example is specifying an excessive queue size --- there is no
documented upper limit.)
The module defines the following functions:
\begin{funcdesc}{openport}{name, direction\optional{, config}}
The name and direction arguments are strings. The optional
\var{config} argument is a configuration object as returned by
\function{newconfig()}. The return value is an \dfn{audio port
object}; methods of audio port objects are described below.
\end{funcdesc}
\begin{funcdesc}{newconfig}{}
The return value is a new \dfn{audio configuration object}; methods of
audio configuration objects are described below.
\end{funcdesc}
\begin{funcdesc}{queryparams}{device}
The device argument is an integer. The return value is a list of
integers containing the data returned by \cfunction{ALqueryparams()}.
\end{funcdesc}
\begin{funcdesc}{getparams}{device, list}
The \var{device} argument is an integer. The list argument is a list
such as returned by \function{queryparams()}; it is modified in place
(!).
\end{funcdesc}
\begin{funcdesc}{setparams}{device, list}
The \var{device} argument is an integer. The \var{list} argument is a
list such as returned by \function{queryparams()}.
\end{funcdesc}
\subsection{Configuration Objects}
\label{al-config-objects}
Configuration objects (returned by \function{newconfig()} have the
following methods:
\begin{methoddesc}[audio configuration]{getqueuesize}{}
Return the queue size.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{setqueuesize}{size}
Set the queue size.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{getwidth}{}
Get the sample width.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{setwidth}{width}
Set the sample width.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{getchannels}{}
Get the channel count.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{setchannels}{nchannels}
Set the channel count.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{getsampfmt}{}
Get the sample format.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{setsampfmt}{sampfmt}
Set the sample format.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{getfloatmax}{}
Get the maximum value for floating sample formats.
\end{methoddesc}
\begin{methoddesc}[audio configuration]{setfloatmax}{floatmax}
Set the maximum value for floating sample formats.
\end{methoddesc}
\subsection{Port Objects}
\label{al-port-objects}
Port objects, as returned by \function{openport()}, have the following
methods:
\begin{methoddesc}[audio port]{closeport}{}
Close the port.
\end{methoddesc}
\begin{methoddesc}[audio port]{getfd}{}
Return the file descriptor as an int.
\end{methoddesc}
\begin{methoddesc}[audio port]{getfilled}{}
Return the number of filled samples.
\end{methoddesc}
\begin{methoddesc}[audio port]{getfillable}{}
Return the number of fillable samples.
\end{methoddesc}
\begin{methoddesc}[audio port]{readsamps}{nsamples}
Read a number of samples from the queue, blocking if necessary.
Return the data as a string containing the raw data, (e.g., 2 bytes per
sample in big-endian byte order (high byte, low byte) if you have set
the sample width to 2 bytes).
\end{methoddesc}
\begin{methoddesc}[audio port]{writesamps}{samples}
Write samples into the queue, blocking if necessary. The samples are
encoded as described for the \method{readsamps()} return value.
\end{methoddesc}
\begin{methoddesc}[audio port]{getfillpoint}{}
Return the `fill point'.
\end{methoddesc}
\begin{methoddesc}[audio port]{setfillpoint}{fillpoint}
Set the `fill point'.
\end{methoddesc}
\begin{methoddesc}[audio port]{getconfig}{}
Return a configuration object containing the current configuration of
the port.
\end{methoddesc}
\begin{methoddesc}[audio port]{setconfig}{config}
Set the configuration from the argument, a configuration object.
\end{methoddesc}
\begin{methoddesc}[audio port]{getstatus}{list}
Get status information on last error.
\end{methoddesc}
\section{Standard Module \module{AL}}
\nodename{AL (uppercase)}
\stmodindex{AL}
This module defines symbolic constants needed to use the built-in
module \module{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:
\begin{verbatim}
import al
from AL import *
\end{verbatim}

36
Doc/liballos.tex
View File

@ -1,36 +0,0 @@
\chapter{Generic Operating System Services}
\label{allos}
The modules described in this chapter provide interfaces to operating
system features that are available on (almost) all operating systems,
such as files and a clock. The interfaces are generally modelled
after the \UNIX{} or \C{} interfaces but they are available on most
other systems as well. Here's an overview:
\begin{description}
\item[os]
--- Miscellaneous OS interfaces.
\item[time]
--- Time access and conversions.
\item[getopt]
--- Parser for command line options.
\item[tempfile]
--- Generate temporary file names.
\item[errno]
--- Standard errno system symbols.
\item[glob]
--- \UNIX{} shell style pathname pattern expansion.
\item[fnmatch]
--- \UNIX{} shell style pathname pattern matching.
\item[locale]
--- Internationalization services.
\end{description}

128
Doc/libamoeba.tex
View File

@ -1,128 +0,0 @@
\chapter{Amoeba Specific Services}
\section{Built-in Module \module{amoeba}}
\label{module-amoeba}
\bimodindex{amoeba}
This module provides some object types and operations useful for
Amoeba applications. It is only available on systems that support
Amoeba operations. RPC errors and other Amoeba errors are reported as
the exception \code{amoeba.error = 'amoeba.error'}.
The module \code{amoeba} defines the following items:
\begin{funcdesc}{name_append}{path, cap}
Stores a capability in the Amoeba directory tree.
Arguments are the pathname (a string) and the capability (a capability
object as returned by
\code{name_lookup()}).
\end{funcdesc}
\begin{funcdesc}{name_delete}{path}
Deletes a capability from the Amoeba directory tree.
Argument is the pathname.
\end{funcdesc}
\begin{funcdesc}{name_lookup}{path}
Looks up a capability.
Argument is the pathname.
Returns a
\dfn{capability}
object, to which various interesting operations apply, described below.
\end{funcdesc}
\begin{funcdesc}{name_replace}{path, cap}
Replaces a capability in the Amoeba directory tree.
Arguments are the pathname and the new capability.
(This differs from
\code{name_append()}
in the behavior when the pathname already exists:
\code{name_append()}
finds this an error while
\code{name_replace()}
allows it, as its name suggests.)
\end{funcdesc}
\begin{datadesc}{capv}
A table representing the capability environment at the time the
interpreter was started.
(Alas, modifying this table does not affect the capability environment
of the interpreter.)
For example,
\code{amoeba.capv['ROOT']}
is the capability of your root directory, similar to
\code{getcap("ROOT")}
in C.
\end{datadesc}
\begin{excdesc}{error}
The exception raised when an Amoeba function returns an error.
The value accompanying this exception is a pair containing the numeric
error code and the corresponding string, as returned by the C function
\code{err_why()}.
\end{excdesc}
\begin{funcdesc}{timeout}{msecs}
Sets the transaction timeout, in milliseconds.
Returns the previous timeout.
Initially, the timeout is set to 2 seconds by the Python interpreter.
\end{funcdesc}
\subsection{Capability Operations}
Capabilities are written in a convenient \ASCII{} format, also used by the
Amoeba utilities
\emph{c2a}(U)
and
\emph{a2c}(U).
For example:
\begin{verbatim}
>>> amoeba.name_lookup('/profile/cap')
aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
>>>
\end{verbatim}
%
The following methods are defined for capability objects.
\setindexsubitem{(capability method)}
\begin{funcdesc}{dir_list}{}
Returns a list of the names of the entries in an Amoeba directory.
\end{funcdesc}
\begin{funcdesc}{b_read}{offset, maxsize}
Reads (at most)
\var{maxsize}
bytes from a bullet file at offset
\var{offset.}
The data is returned as a string.
EOF is reported as an empty string.
\end{funcdesc}
\begin{funcdesc}{b_size}{}
Returns the size of a bullet file.
\end{funcdesc}
\begin{funcdesc}{dir_append}{}
\funcline{dir_delete}{}\
\funcline{dir_lookup}{}\
\funcline{dir_replace}{}
Like the corresponding
\samp{name_}*
functions, but with a path relative to the capability.
(For paths beginning with a slash the capability is ignored, since this
is the defined semantics for Amoeba.)
\end{funcdesc}
\begin{funcdesc}{std_info}{}
Returns the standard info string of the object.
\end{funcdesc}
\begin{funcdesc}{tod_gettime}{}
Returns the time (in seconds since the Epoch, in UCT, as for \POSIX{}) from
a time server.
\end{funcdesc}
\begin{funcdesc}{tod_settime}{t}
Sets the time kept by a time server.
\end{funcdesc}

71
Doc/libanydbm.tex
View File

@ -1,71 +0,0 @@
\section{Standard Module \module{anydbm}}
\label{module-anydbm}
\stmodindex{anydbm}
\module{anydbm} is a generic interface to variants of the DBM
database --- \module{dbhash}\refbimodindex{dbhash},
\module{gdbm}\refbimodindex{gdbm}, or \module{dbm}\refbimodindex{dbm}.
If none of these modules is installed, the slow-but-simple
implementation in module \module{dumbdbm}\refstmodindex{dumbdbm} will
be used.
\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
Open the database file \var{filename} and return a corresponding object.
If the database file already exists, the \module{whichdb} module is
used to determine its type and the appropriate module is used; if it
doesn't exist, the first module listed above that can be imported is
used.
The optional \var{flag} argument can be
\code{'r'} to open an existing database for reading only,
\code{'w'} to open an existing database for reading and writing,
\code{'c'} to create the database if it doesn't exist, or
\code{'n'}, which will always create a new empty database. If not
specified, the default value is \code{'r'}.
The optional \var{mode} argument is the \UNIX{} mode of the file, used
only when the database has to be created. It defaults to octal
\code{0666} (and will be modified by the prevailing umask).
\end{funcdesc}
\begin{excdesc}{error}
A tuple containing the exceptions that can be raised by each of the
supported modules, with a unique exception \exception{anydbm.error} as
the first item --- the latter is used when \exception{anydbm.error} is
raised.
\end{excdesc}
The object returned by \function{open()} supports most of the same
functionality as dictionaries; keys and their corresponding values can
be stored, retrieved, and deleted, and the \method{has_key()} and
\method{keys()} methods are available. Keys and values must always be
strings.
\section{Standard Module \module{dumbdbm}}
\label{module-dumbdbm}
\stmodindex{dumbdbm}
A simple and slow database implemented entirely in Python. This
should only be used when no other DBM-style database is available.
\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
Open the database file \var{filename} and return a corresponding object.
The optional \var{flag} argument can be
\code{'r'} to open an existing database for reading only,
\code{'w'} to open an existing database for reading and writing,
\code{'c'} to create the database if it doesn't exist, or
\code{'n'}, which will always create a new empty database. If not
specified, the default value is \code{'r'}.
The optional \var{mode} argument is the \UNIX{} mode of the file, used
only when the database has to be created. It defaults to octal
\code{0666} (and will be modified by the prevailing umask).
\end{funcdesc}
\begin{excdesc}{error}
Raised for errors not reported as \exception{KeyError} errors.
\end{excdesc}

161
Doc/libarray.tex
View File

@ -1,161 +0,0 @@
\section{Built-in Module \module{array}}
\label{module-array}
\bimodindex{array}
\index{arrays}
This module defines a new object type which can efficiently represent
an array of basic values: characters, integers, floating point
numbers. Arrays are sequence types and behave very much like lists,
except that the type of objects stored in them is constrained. The
type is specified at object creation time by using a \dfn{type code},
which is a single character. The following type codes are defined:
\begin{tableiii}{c|l|c}{code}{Type code}{C Type}{Minimum size in bytes}
\lineiii{'c'}{character}{1}
\lineiii{'b'}{signed integer}{1}
\lineiii{'B'}{unsigned integer}{1}
\lineiii{'h'}{signed integer}{2}
\lineiii{'H'}{unsigned integer}{2}
\lineiii{'i'}{signed integer}{2}
\lineiii{'I'}{unsigned integer}{2}
\lineiii{'l'}{signed integer}{4}
\lineiii{'L'}{unsigned integer}{4}
\lineiii{'f'}{floating point}{4}
\lineiii{'d'}{floating point}{8}
\end{tableiii}
The actual representation of values is determined by the machine
architecture (strictly speaking, by the \C{} implementation). The actual
size can be accessed through the \var{itemsize} attribute. The values
stored for \code{'L'} and \code{'I'} items will be represented as
Python long integers when retrieved, because Python's plain integer
type cannot represent the full range of \C{}'s unsigned (long) integers.
The module defines the following function and type object:
\begin{funcdesc}{array}{typecode\optional{, initializer}}
Return a new array whose items are restricted by \var{typecode}, and
initialized from the optional \var{initializer} value, which must be a
list or a string. The list or string is passed to the new array's
\method{fromlist()} or \method{fromstring()} method (see below) to add
initial items to the array.
\end{funcdesc}
\begin{datadesc}{ArrayType}
Type object corresponding to the objects returned by
\function{array()}.
\end{datadesc}
Array objects support the following data items and methods:
\begin{memberdesc}[array]{typecode}
The typecode character used to create the array.
\end{memberdesc}
\begin{memberdesc}[array]{itemsize}
The length in bytes of one array item in the internal representation.
\end{memberdesc}
\begin{methoddesc}[array]{append}{x}
Append a new item with value \var{x} to the end of the array.
\end{methoddesc}
\begin{methoddesc}[array]{buffer_info}{}
Return a tuple \code{(\var{address}, \var{length})} giving the current
memory address and the length in bytes of the buffer used to hold
array's contents. This is occasionally useful when working with
low-level (and inherently unsafe) I/O interfaces that require memory
addresses, such as certain \cfunction{ioctl()} operations. The returned
numbers are valid as long as the array exists and no length-changing
operations are applied to it.
\end{methoddesc}
\begin{methoddesc}[array]{byteswap}{x}
``Byteswap'' all items of the array. This is only supported for
integer values. It is useful when reading data from a file written
on a machine with a different byte order.
\end{methoddesc}
\begin{methoddesc}[array]{fromfile}{f, n}
Read \var{n} items (as machine values) from the file object \var{f}
and append them to the end of the array. If less than \var{n} items
are available, \exception{EOFError} is raised, but the items that were
available are still inserted into the array. \var{f} must be a real
built-in file object; something else with a \method{read()} method won't
do.
\end{methoddesc}
\begin{methoddesc}[array]{fromlist}{list}
Append items from the list. This is equivalent to
\samp{for x in \var{list}:\ a.append(x)}
except that if there is a type error, the array is unchanged.
\end{methoddesc}
\begin{methoddesc}[array]{fromstring}{s}
Appends items from the string, interpreting the string as an
array of machine values (i.e. as if it had been read from a
file using the \method{fromfile()} method).
\end{methoddesc}
\begin{methoddesc}[array]{insert}{i, x}
Insert a new item with value \var{x} in the array before position
\var{i}.
\end{methoddesc}
\begin{methoddesc}[array]{read}{f, n}
\deprecated {1.5.1}
{Use the \method{fromfile()} method.}
Read \var{n} items (as machine values) from the file object \var{f}
and append them to the end of the array. If less than \var{n} items
are available, \exception{EOFError} is raised, but the items that were
available are still inserted into the array. \var{f} must be a real
built-in file object; something else with a \method{read()} method won't
do.
\end{methoddesc}
\begin{methoddesc}[array]{reverse}{}
Reverse the order of the items in the array.
\end{methoddesc}
\begin{methoddesc}[array]{tofile}{f}
Write all items (as machine values) to the file object \var{f}.
\end{methoddesc}
\begin{methoddesc}[array]{tolist}{}
Convert the array to an ordinary list with the same items.
\end{methoddesc}
\begin{methoddesc}[array]{tostring}{}
Convert the array to an array of machine values and return the
string representation (the same sequence of bytes that would
be written to a file by the \method{tofile()} method.)
\end{methoddesc}
\begin{methoddesc}[array]{write}{f}
\deprecated {1.5.1}
{Use the \method{tofile()} method.}
Write all items (as machine values) to the file object \var{f}.
\end{methoddesc}
When an array object is printed or converted to a string, it is
represented as \code{array(\var{typecode}, \var{initializer})}. The
\var{initializer} is omitted if the array is empty, otherwise it is a
string if the \var{typecode} is \code{'c'}, otherwise it is a list of
numbers. The string is guaranteed to be able to be converted back to
an array with the same type and value using reverse quotes
(\code{``}). Examples:
\begin{verbatim}
array('l')
array('c', 'hello world')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])
\end{verbatim}
\begin{seealso}
\seemodule{struct}{Packing and unpacking of heterogeneous binary data.}
\end{seealso}

257
Doc/libaudioop.tex
View File

@ -1,257 +0,0 @@
\section{Built-in Module \module{audioop}}
\label{module-audioop}
\bimodindex{audioop}
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}
modules. All scalar items are integers, unless specified otherwise.
% This para is mostly here to provide an excuse for the index entries...
This module provides support for u-LAW and Intel/DVI ADPCM encodings.
\index{Intel/DVI ADPCM}
\index{ADPCM, Intel/DVI}
\index{u-LAW}
A few of the more complicated operations only take 16-bit samples,
otherwise the sample size (in bytes) is always a parameter of the
operation.
The module defines the following variables and functions:
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bytes
per sample, etc.
\end{excdesc}
\begin{funcdesc}{add}{fragment1, fragment2, width}
Return a fragment which is the addition of the two samples passed as
parameters. \var{width} is the sample width in bytes, either
\code{1}, \code{2} or \code{4}. Both fragments should have the same
length.
\end{funcdesc}
\begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state}
Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
the description of \function{lin2adpcm()} for details on ADPCM coding.
Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
has the width specified in \var{width}.
\end{funcdesc}
\begin{funcdesc}{adpcm32lin}{adpcmfragment, width, state}
Decode an alternative 3-bit ADPCM code. See \function{lin2adpcm3()}
for details.
\end{funcdesc}
\begin{funcdesc}{avg}{fragment, width}
Return the average over all samples in the fragment.
\end{funcdesc}
\begin{funcdesc}{avgpp}{fragment, width}
Return the average peak-peak value over all samples in the fragment.
No filtering is done, so the usefulness of this routine is
questionable.
\end{funcdesc}
\begin{funcdesc}{bias}{fragment, width, bias}
Return a fragment that is the original fragment with a bias added to
each sample.
\end{funcdesc}
\begin{funcdesc}{cross}{fragment, width}
Return the number of zero crossings in the fragment passed as an
argument.
\end{funcdesc}
\begin{funcdesc}{findfactor}{fragment, reference}
Return a factor \var{F} such that
\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is
minimal, i.e., return the factor with which you should multiply
\var{reference} to make it match as well as possible to
\var{fragment}. The fragments should both contain 2-byte samples.
The time taken by this routine is proportional to
\code{len(\var{fragment})}.
\end{funcdesc}
\begin{funcdesc}{findfit}{fragment, reference}
Try to match \var{reference} as well as possible to a portion of
\var{fragment} (which should be the longer fragment). This is
(conceptually) done by taking slices out of \var{fragment}, using
\function{findfactor()} to compute the best match, and minimizing the
result. The fragments should both contain 2-byte samples. Return a
tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
(integer) offset into \var{fragment} where the optimal match started
and \var{factor} is the (floating-point) factor as per
\function{findfactor()}.
\end{funcdesc}
\begin{funcdesc}{findmax}{fragment, length}
Search \var{fragment} for a slice of length \var{length} samples (not
bytes!)\ with maximum energy, i.e., return \var{i} for which
\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
should both contain 2-byte samples.
The routine takes time proportional to \code{len(\var{fragment})}.
\end{funcdesc}
\begin{funcdesc}{getsample}{fragment, width, index}
Return the value of sample \var{index} from the fragment.
\end{funcdesc}
\begin{funcdesc}{lin2lin}{fragment, width, newwidth}
Convert samples between 1-, 2- and 4-byte formats.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm}{fragment, width, state}
Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an
adaptive coding scheme, whereby each 4 bit number is the difference
between one sample and the next, divided by a (varying) step. The
Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
may well become a standard.
\var{state} is a tuple containing the state of the coder. The coder
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
\var{newstate} should be passed to the next call of
\function{lin2adpcm()}. In the initial call, \code{None} can be
passed as the state. \var{adpcmfrag} is the ADPCM coded fragment
packed 2 4-bit values per byte.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm3}{fragment, width, state}
This is an alternative ADPCM coder that uses only 3 bits per sample.
It is not compatible with the Intel/DVI ADPCM coder and its output is
not packed (due to laziness on the side of the author). Its use is
discouraged.
\end{funcdesc}
\begin{funcdesc}{lin2ulaw}{fragment, width}
Convert samples in the audio fragment to u-LAW encoding and return
this as a Python string. u-LAW is an audio encoding format whereby
you get a dynamic range of about 14 bits using only 8 bit samples. It
is used by the Sun audio hardware, among others.
\end{funcdesc}
\begin{funcdesc}{minmax}{fragment, width}
Return a tuple consisting of the minimum and maximum values of all
samples in the sound fragment.
\end{funcdesc}
\begin{funcdesc}{max}{fragment, width}
Return the maximum of the \emph{absolute value} of all samples in a
fragment.
\end{funcdesc}
\begin{funcdesc}{maxpp}{fragment, width}
Return the maximum peak-peak value in the sound fragment.
\end{funcdesc}
\begin{funcdesc}{mul}{fragment, width, factor}
Return a fragment that has all samples in the original framgent
multiplied by the floating-point value \var{factor}. Overflow is
silently ignored.
\end{funcdesc}
\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate,
state\optional{, weightA\optional{, weightB}}}
Convert the frame rate of the input fragment.
\var{state} is a tuple containing the state of the converter. The
converter returns a tupl \code{(\var{newfragment}, \var{newstate})},
and \var{newstate} should be passed to the next call of
\function{ratecv()}.
The \var{weightA} and \var{weightB} arguments are parameters for a
simple digital filter and default to \code{1} and \code{0}
respectively.
\end{funcdesc}
\begin{funcdesc}{reverse}{fragment, width}
Reverse the samples in a fragment and returns the modified fragment.
\end{funcdesc}
\begin{funcdesc}{rms}{fragment, width}
Return the root-mean-square of the fragment, i.e.
the square root of the quotient of the sum of all squared sample value,
divided by the sumber of samples.
%begin{latexonly}
% in eqn: sqrt { sum S sub i sup 2 over n }
\begin{displaymath}
\catcode`_=8
\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
\end{displaymath}
%end{latexonly}
This is a measure of the power in an audio signal.
\end{funcdesc}
\begin{funcdesc}{tomono}{fragment, width, lfactor, rfactor}
Convert a stereo fragment to a mono fragment. The left channel is
multiplied by \var{lfactor} and the right channel by \var{rfactor}
before adding the two channels to give a mono signal.
\end{funcdesc}
\begin{funcdesc}{tostereo}{fragment, width, lfactor, rfactor}
Generate a stereo fragment from a mono fragment. Each pair of samples
in the stereo fragment are computed from the mono sample, whereby left
channel samples are multiplied by \var{lfactor} and right channel
samples by \var{rfactor}.
\end{funcdesc}
\begin{funcdesc}{ulaw2lin}{fragment, width}
Convert sound fragments in u-LAW encoding to linearly encoded sound
fragments. u-LAW encoding always uses 8 bits samples, so \var{width}
refers only to the sample width of the output fragment here.
\end{funcdesc}
Note that operations such as \function{mul()} or \function{max()} make
no distinction between mono and stereo fragments, i.e.\ all samples
are treated equal. If this is a problem the stereo fragment should be
split into two mono fragments first and recombined later. Here is an
example of how to do that:
\begin{verbatim}
def mul_stereo(sample, width, lfactor, rfactor):
lsample = audioop.tomono(sample, width, 1, 0)
rsample = audioop.tomono(sample, width, 0, 1)
lsample = audioop.mul(sample, width, lfactor)
rsample = audioop.mul(sample, width, rfactor)
lsample = audioop.tostereo(lsample, width, 1, 0)
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
\end{verbatim}
If you use the ADPCM coder to build network packets and you want your
protocol to be stateless (i.e.\ to be able to tolerate packet loss)
you should not only transmit the data but also the state. Note that
you should send the \var{initial} state (the one you passed to
\function{lin2adpcm()}) along to the decoder, not the final state (as
returned by the coder). If you want to use \function{struct.struct()}
to store the state in binary you can code the first element (the
predicted value) in 16 bits and the second (the delta index) in 8.
The ADPCM coders have never been tried against other ADPCM coders,
only against themselves. It could well be that I misinterpreted the
standards in which case they will not be interoperable with the
respective standards.
The \function{find*()} routines might look a bit funny at first sight.
They are primarily meant to do echo cancellation. A reasonably
fast way to do this is to pick the most energetic piece of the output
sample, locate that in the input sample and subtract the whole output
sample from the input sample:
\begin{verbatim}
def echocancel(outputdata, inputdata):
pos = audioop.findmax(outputdata, 800) # one tenth second
out_test = outputdata[pos*2:]
in_test = inputdata[pos*2:]
ipos, factor = audioop.findfit(in_test, out_test)
# Optional (for better cancellation):
# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
# out_test)
prefill = '\0'*(pos+ipos)*2
postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
return audioop.add(inputdata, outputdata, 2)
\end{verbatim}

45
Doc/libbase64.tex
View File

@ -1,45 +0,0 @@
\section{Standard Module \module{base64}}
\label{module-base64}
\stmodindex{base64}
\indexii{base64}{encoding}
\index{MIME!base64 encoding}
This module perform base64 encoding and decoding of arbitrary binary
strings into text strings that can be safely emailed or posted. The
encoding scheme is defined in \rfc{1421} (``Privacy Enhancement for
Internet Electronic Mail: Part I: Message Encryption and
Authentication Procedures'', section 4.3.2.4, ``Step 4: Printable
Encoding'') and is used for MIME email and
various other Internet-related applications; it is not the same as the
output produced by the \program{uuencode} program. For example, the
string \code{'www.python.org'} is encoded as the string
\code{'d3d3LnB5dGhvbi5vcmc=\e n'}.
\begin{funcdesc}{decode}{input, output}
Decode the contents of the \var{input} file and write the resulting
binary data to the \var{output} file.
\var{input} and \var{output} must either be file objects or objects that
mimic the file object interface. \var{input} will be read until
\code{\var{input}.read()} returns an empty string.
\end{funcdesc}
\begin{funcdesc}{decodestring}{s}
Decode the string \var{s}, which must contain one or more lines of
base64 encoded data, and return a string containing the resulting
binary data.
\end{funcdesc}
\begin{funcdesc}{encode}{input, output}
Encode the contents of the \var{input} file and write the resulting
base64 encoded data to the \var{output} file.
\var{input} and \var{output} must either be file objects or objects that
mimic the file object interface. \var{input} will be read until
\code{\var{input}.read()} returns an empty string.
\end{funcdesc}
\begin{funcdesc}{encodestring}{s}
Encode the string \var{s}, which can contain arbitrary binary data,
and return a string containing one or more lines of
base64 encoded data.
\end{funcdesc}

219
Doc/libbasehttp.tex
View File

@ -1,219 +0,0 @@
\section{Standard Module \module{BaseHTTPServer}}
\label{module-BaseHTTPServer}
\stmodindex{BaseHTTPServer}
\indexii{WWW}{server}
\indexii{HTTP}{protocol}
\index{URL}
\index{httpd}
This module defines two classes for implementing HTTP servers
(web servers). Usually, this module isn't used directly, but is used
as a basis for building functioning web servers. See the
\module{SimpleHTTPServer} and \module{CGIHTTPServer} modules.
\refstmodindex{SimpleHTTPServer}
\refstmodindex{CGIHTTPServer}
The first class, \class{HTTPServer}, is a
\class{SocketServer.TCPServer} subclass. It creates and listens at the
web socket, dispatching the requests to a handler. Code to create and
run the server looks like this:
\begin{verbatim}
def run(server_class=BaseHTTPServer.HTTPServer,
handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
httpd.serve_forever()
\end{verbatim}
\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass}
This class builds on the \class{TCPServer} class by
storing the server address as instance
variables named \member{server_name} and \member{server_port}. The
server is accessible by the handler, typically through the handler's
\member{server} instance variable.
\end{classdesc}
\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server}
This class is used
to handle the HTTP requests that arrive at the server. By itself,
it cannot respond to any actual HTTP requests; it must be subclassed
to handle each request method (e.g. GET or POST).
\class{BaseHTTPRequestHandler} provides a number of class and instance
variables, and methods for use by subclasses.
The handler will parse the request and the headers, then call a
method specific to the request type. The method name is constructed
from the request. For example, for the request method \samp{SPAM}, the
\method{do_SPAM()} method will be called with no arguments. All of
the relevant information is stored in instance variables of the
handler. Subclasses should not need to override or extend the
\method{__init__()} method.
\end{classdesc}
\class{BaseHTTPRequestHandler} has the following instance variables:
\begin{memberdesc}{client_address}
Contains a tuple of the form \code{(\var{host}, \var{port})} referring
to the client's address.
\end{memberdesc}
\begin{memberdesc}{command}
Contains the command (request type). For example, \code{'GET'}.
\end{memberdesc}
\begin{memberdesc}{path}
Contains the request path.
\end{memberdesc}
\begin{memberdesc}{request_version}
Contains the version string from the request. For example,
\code{'HTTP/1.0'}.
\end{memberdesc}
\begin{memberdesc}{headers}
Holds an instance of the class specified by the \member{MessageClass}
class variable. This instance parses and manages the headers in
the HTTP request.
\end{memberdesc}
\begin{memberdesc}{rfile}
Contains an input stream, positioned at the start of the optional
input data.
\end{memberdesc}
\begin{memberdesc}{wfile}
Contains the output stream for writing a response back to the client.
Proper adherance to the HTTP protocol must be used when writing
to this stream.
\end{memberdesc}
\class{BaseHTTPRequestHandler} has the following class variables:
\begin{memberdesc}{server_version}
Specifies the server software version. You may want to override
this.
The format is multiple whitespace-separated strings,
where each string is of the form name[/version].
For example, \code{'BaseHTTP/0.2'}.
\end{memberdesc}
\begin{memberdesc}{sys_version}
Contains the Python system version, in a form usable by the
\member{version_string} method and the \member{server_version} class
variable. For example, \code{'Python/1.4'}.
\end{memberdesc}
\begin{memberdesc}{error_message_format}
Specifies a format string for building an error response to the
client. It uses parenthesized, keyed format specifiers, so the
format operand must be a dictionary. The \var{code} key should
be an integer, specifing the numeric HTTP error code value.
\var{message} should be a string containing a (detailed) error
message of what occurred, and \var{explain} should be an
explanation of the error code number. Default \var{message}
and \var{explain} values can found in the \var{responses}
class variable.
\end{memberdesc}
\begin{memberdesc}{protocol_version}
This specifies the HTTP protocol version used in responses.
Typically, this should not be overridden. Defaults to
\code{'HTTP/1.0'}.
\end{memberdesc}
\begin{memberdesc}{MessageClass}
Specifies a \class{rfc822.Message}-like class to parse HTTP
headers. Typically, this is not overridden, and it defaults to
\class{mimetools.Message}.
\withsubitem{(in module mimetools)}{\ttindex{Message}}
\end{memberdesc}
\begin{memberdesc}{responses}
This variable contains a mapping of error code integers to two-element
tuples containing a short and long message. For example,
\code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The
\var{shortmessage} is usually used as the \var{message} key in an
error response, and \var{longmessage} as the \var{explain} key
(see the \member{error_message_format} class variable).
\end{memberdesc}
A \class{BaseHTTPRequestHandler} instance has the following methods:
\begin{methoddesc}{handle}{}
Overrides the superclass' \method{handle()} method to provide the
specific handler behavior. This method will parse and dispatch
the request to the appropriate \method{do_*()} method.
\end{methoddesc}
\begin{methoddesc}{send_error}{code\optional{, message}}
Sends and logs a complete error reply to the client. The numeric
\var{code} specifies the HTTP error code, with \var{message} as
optional, more specific text. A complete set of headers is sent,
followed by text composed using the \member{error_message_format}
class variable.
\end{methoddesc}
\begin{methoddesc}{send_response}{code\optional{, message}}
Sends a response header and logs the accepted request. The HTTP
response line is sent, followed by \emph{Server} and \emph{Date}
headers. The values for these two headers are picked up from the
\method{version_string()} and \method{date_time_string()} methods,
respectively.
\end{methoddesc}
\begin{methoddesc}{send_header}{keyword, value}
Writes a specific MIME header to the output stream. \var{keyword}
should specify the header keyword, with \var{value} specifying
its value.
\end{methoddesc}
\begin{methoddesc}{end_headers}{}
Sends a blank line, indicating the end of the MIME headers in
the response.
\end{methoddesc}
\begin{methoddesc}{log_request}{\optional{code\optional{, size}}}
Logs an accepted (successful) request. \var{code} should specify
the numeric HTTP code associated with the response. If a size of
the response is available, then it should be passed as the
\var{size} parameter.
\end{methoddesc}
\begin{methoddesc}{log_error}{...}
Logs an error when a request cannot be fulfilled. By default,
it passes the message to \method{log_message()}, so it takes the
same arguments (\var{format} and additional values).
\end{methoddesc}
\begin{methoddesc}{log_message}{format, ...}
Logs an arbitrary message to \code{sys.stderr}. This is typically
overridden to create custom error logging mechanisms. The
\var{format} argument is a standard printf-style format string,
where the additional arguments to \method{log_message()} are applied
as inputs to the formatting. The client address and current date
and time are prefixed to every message logged.
\end{methoddesc}
\begin{methoddesc}{version_string}{}
Returns the server software's version string. This is a combination
of the \member{server_version} and \member{sys_version} class variables.
\end{methoddesc}
\begin{methoddesc}{date_time_string}{}
Returns the current date and time, formatted for a message header.
\end{methoddesc}
\begin{methoddesc}{log_data_time_string}{}
Returns the current date and time, formatted for logging.
\end{methoddesc}
\begin{methoddesc}{address_string}{}
Returns the client address, formatted for logging. A name lookup
is performed on the client's IP address.
\end{methoddesc}

48
Doc/libbastion.tex
View File

@ -1,48 +0,0 @@
\section{Standard Module \module{Bastion}}
\label{module-Bastion}
\stmodindex{Bastion}
% I'm concerned that the word 'bastion' won't be understood by people
% for whom English is a second language, making the module name
% somewhat mysterious. Thus, the brief definition... --amk
According to the dictionary, a bastion is ``a fortified area or
position'', or ``something that is considered a stronghold.'' It's a
suitable name for this module, which provides a way to forbid access
to certain attributes of an object. It must always be used with the
\module{rexec} module, in order to allow restricted-mode programs access
to certain safe attributes of an object, while denying access to
other, unsafe attributes.
% I've punted on the issue of documenting keyword arguments for now.
\begin{funcdesc}{Bastion}{object\optional{, filter\optional{,
name\optional{, class}}}}
Protect the object \var{object}, returning a bastion for the
object. Any attempt to access one of the object's attributes will
have to be approved by the \var{filter} function; if the access is
denied an \exception{AttributeError} exception will be raised.
If present, \var{filter} must be a function that accepts a string
containing an attribute name, and returns true if access to that
attribute will be permitted; if \var{filter} returns false, the access
is denied. The default filter denies access to any function beginning
with an underscore (\samp{_}). The bastion's string representation
will be \samp{<Bastion for \var{name}>} if a value for
\var{name} is provided; otherwise, \samp{repr(\var{object})} will be
used.
\var{class}, if present, should be a subclass of \class{BastionClass};
see the code in \file{bastion.py} for the details. Overriding the
default \class{BastionClass} will rarely be required.
\end{funcdesc}
\begin{classdesc}{BastionClass}{getfunc, name}
Class which actually implements bastion objects. This is the default
class used by \function{Bastion()}. The \var{getfunc} parameter is a
function which returns the value of an attribute which should be
exposed to the restricted execution environment when called with the
name of the attribute as the only parameter. \var{name} is used to
construct the \function{repr()} of the \class{BastionClass} instance.
\end{classdesc}

79
Doc/libbinascii.tex
View File

@ -1,79 +0,0 @@
\section{Built-in Module \module{binascii}}
\label{module-binascii}
\bimodindex{binascii}
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
\module{hexbin}\refstmodindex{hexbin} instead, this module solely
exists because bit-manipuation of large amounts of data is slow in
Python.
The \module{binascii} module defines the following functions:
\begin{funcdesc}{a2b_uu}{string}
Convert a single line of uuencoded data back to binary and return the
binary data. Lines normally contain 45 (binary) bytes, except for the
last line. Line data may be followed by whitespace.
\end{funcdesc}
\begin{funcdesc}{b2a_uu}{data}
Convert binary data to a line of \ASCII{} characters, the return value
is the converted line, including a newline char. The length of
\var{data} should be at most 45.
\end{funcdesc}
\begin{funcdesc}{a2b_base64}{string}
Convert a block of base64 data back to binary and return the
binary data. More than one line may be passed at a time.
\end{funcdesc}
\begin{funcdesc}{b2a_base64}{data}
Convert binary data to a line of \ASCII{} characters in base64 coding.
The return value is the converted line, including a newline char.
The length of \var{data} should be at most 57 to adhere to the base64
standard.
\end{funcdesc}
\begin{funcdesc}{a2b_hqx}{string}
Convert binhex4 formatted \ASCII{} data to binary, without doing
RLE-decompression. The string should contain a complete number of
binary bytes, or (in case of the last portion of the binhex4 data)
have the remaining bits zero.
\end{funcdesc}
\begin{funcdesc}{rledecode_hqx}{data}
Perform RLE-decompression on the data, as per the binhex4
standard. The algorithm uses \code{0x90} after a byte as a repeat
indicator, followed by a count. A count of \code{0} specifies a byte
value of \code{0x90}. The routine returns the decompressed data,
unless data input data ends in an orphaned repeat indicator, in which
case the \exception{Incomplete} exception is raised.
\end{funcdesc}
\begin{funcdesc}{rlecode_hqx}{data}
Perform binhex4 style RLE-compression on \var{data} and return the
result.
\end{funcdesc}
\begin{funcdesc}{b2a_hqx}{data}
Perform hexbin4 binary-to-\ASCII{} translation and return the
resulting string. The argument should already be RLE-coded, and have a
length divisible by 3 (except possibly the last fragment).
\end{funcdesc}
\begin{funcdesc}{crc_hqx}{data, crc}
Compute the binhex4 crc value of \var{data}, starting with an initial
\var{crc} and returning the result.
\end{funcdesc}
\begin{excdesc}{Error}
Exception raised on errors. These are usually programming errors.
\end{excdesc}
\begin{excdesc}{Incomplete}
Exception raised on incomplete data. These are usually not programming
errors, but may be handled by reading a little more data and trying
again.
\end{excdesc}

36
Doc/libbinhex.tex
View File

@ -1,36 +0,0 @@
\section{Standard Module \module{binhex}}
\label{module-binhex}
\stmodindex{binhex}
This module encodes and decodes files in binhex4 format, a format
allowing representation of Macintosh files in \ASCII{}. On the Macintosh,
both forks of a file and the finder information are encoded (or
decoded), on other platforms only the data fork is handled.
The \module{binhex} module defines the following functions:
\begin{funcdesc}{binhex}{input, output}
Convert a binary file with filename \var{input} to binhex file
\var{output}. The \var{output} parameter can either be a filename or a
file-like object (any object supporting a \var{write} and \var{close}
method).
\end{funcdesc}
\begin{funcdesc}{hexbin}{input\optional{, output}}
Decode a binhex file \var{input}. \var{input} may be a filename or a
file-like object supporting \var{read} and \var{close} methods.
The resulting file is written to a file named \var{output}, unless the
argument is empty in which case the output filename is read from the
binhex file.
\end{funcdesc}
\subsection{Notes}
There is an alternative, more powerful interface to the coder and
decoder, see the source for details.
If you code or decode textfiles on non-Macintosh platforms they will
still use the Macintosh newline convention (carriage-return as end of
line).
As of this writing, \function{hexbin()} appears to not work in all
cases.

55
Doc/libbisect.tex
View File

@ -1,55 +0,0 @@
% LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an
% example based on the PyModules FAQ entry by Aaron Watters
% <arw@pythonpros.com>.
\section{Standard Module \module{bisect}}
\stmodindex{bisect}
\label{module-bisect}
This module provides support for maintaining a list in sorted order
without having to sort the list after each insertion. For long lists
of items with expensive comparison operations, this can be an
improvement over the more common approach. The module is called
\module{bisect} because it uses a basic bisection algorithm to do its
work. The source code may be used a useful reference for a working
example of the algorithm (i.e., the boundary conditions are already
right!).
The following functions are provided:
\begin{funcdesc}{bisect}{list, item\optional{, lo\optional{, hi}}}
Locate the proper insertion point for \var{item} in \var{list} to
maintain sorted order. The parameters \var{lo} and \var{hi} may be
used to specify a subset of the list which should be considered. The
return value is suitable for use as the first parameter to
\code{\var{list}.insert()}.
\end{funcdesc}
\begin{funcdesc}{insort}{list, item\optional{, lo\optional{, hi}}}
Insert \var{item} in \var{list} in sorted order. This is equivalent
to \code{\var{list}.insert(bisect.bisect(\var{list}, \var{item},
\var{lo}, \var{hi}), \var{item})}.
\end{funcdesc}
\subsection{Example}
\nodename{bisect-example}
The \function{bisect()} function is generally useful for categorizing
numeric data. This example uses \function{bisect()} to look up a
letter grade for an exam total (say) based on a set of ordered numeric
breakpoints: 85 and up is an `A', 75..84 is a `B', etc.
\begin{verbatim}
>>> grades = "FEDCBA"
>>> breakpoints = [30, 44, 66, 75, 85]
>>> from bisect import bisect
>>> def grade(total):
... return grades[bisect(breakpoints, total)]
...
>>> grade(66)
'C'
>>> map(grade, [33, 99, 77, 44, 12, 88])
['E', 'A', 'B', 'D', 'F', 'A']
\end{verbatim}

8
Doc/libbltin.tex
View File

@ -1,8 +0,0 @@
\section{Built-in Module \module{__builtin__}}
\label{module-builtin}
\bimodindex{__builtin__}
This module provides direct access to all `built-in' identifiers of
Python; e.g. \code{__builtin__.open} is the full name for the built-in
function \code{open()}. See section \ref{built-in-funcs}, ``Built-in
Functions.''

45
Doc/libcalendar.tex
View File

@ -1,45 +0,0 @@
% This section was contributed by Drew Csillag <drew_csillag@geocities.com>.
\section{Standard Module \module{calendar}}
\label{module-calendar}
\stmodindex{calendar}
This module allows you to output calendars like the \UNIX{}
\manpage{cal}{1} program.
\begin{funcdesc}{isleap}{year}
Returns \code{1} if \var{year} is a leap year.
\end{funcdesc}
\begin{funcdesc}{leapdays}{year1, year2}
Return the number of leap years in the range
[\var{year1}\ldots\var{year2}].
\end{funcdesc}
\begin{funcdesc}{weekday}{year, month, day}
Returns the day of the week (\code{0} is Monday) for \var{year}
(\code{1970}--\dots), \var{month} (\code{1}--\code{12}), \var{day}
(\code{1}--\code{31}).
\end{funcdesc}
\begin{funcdesc}{monthrange}{year, month}
Returns weekday of first day of the month and number of days in month,
for the specified \var{year} and \var{month}.
\end{funcdesc}
\begin{funcdesc}{monthcalendar}{year, month}
Returns a matrix representing a month's calendar. Each row represents
a week; days outside of the month a represented by zeros.
\end{funcdesc}
\begin{funcdesc}{prmonth}{year, month\optional{, width\optional{, length}}}
Prints a month's calendar. If \var{width} is provided, it specifies
the width of the columns that the numbers are centered in. If
\var{length} is given, it specifies the number of lines that each
week will use.
\end{funcdesc}
\begin{funcdesc}{prcal}{year}
Prints the calendar for the year \var{year}.
\end{funcdesc}

300
Doc/libcd.tex
View File

@ -1,300 +0,0 @@
\section{Built-in Module \module{cd}}
\label{module-cd}
\bimodindex{cd}
This module provides an interface to the Silicon Graphics CD library.
It is available only on Silicon Graphics systems.
The way the library works is as follows. A program opens the CD-ROM
device with \function{open()} and creates a parser to parse the data
from the CD with \function{createparser()}. The object returned by
\function{open()} can be used to read data from the CD, but also to get
status information for the CD-ROM device, and to get information about
the CD, such as the table of contents. Data from the CD is passed to
the parser, which parses the frames, and calls any callback
functions that have previously been added.
An audio CD is divided into \dfn{tracks} or \dfn{programs} (the terms
are used interchangeably). Tracks can be subdivided into
\dfn{indices}. An audio CD contains a \dfn{table of contents} which
gives the starts of the tracks on the CD. Index 0 is usually the
pause before the start of a track. The start of the track as given by
the table of contents is normally the start of index 1.
Positions on a CD can be represented in two ways. Either a frame
number or a tuple of three values, minutes, seconds and frames. Most
functions use the latter representation. Positions can be both
relative to the beginning of the CD, and to the beginning of the
track.
Module \module{cd} defines the following functions and constants:
\begin{funcdesc}{createparser}{}
Create and return an opaque parser object. The methods of the parser
object are described below.
\end{funcdesc}
\begin{funcdesc}{msftoframe}{minutes, seconds, frames}
Converts a \code{(\var{minutes}, \var{seconds}, \var{frames})} triple
representing time in absolute time code into the corresponding CD
frame number.
\end{funcdesc}
\begin{funcdesc}{open}{\optional{device\optional{, mode}}}
Open the CD-ROM device. The return value is an opaque player object;
methods of the player object are described below. The device is the
name of the SCSI device file, e.g. \code{'/dev/scsi/sc0d4l0'}, or
\code{None}. If omitted or \code{None}, the hardware inventory is
consulted to locate a CD-ROM drive. The \var{mode}, if not omited,
should be the string \code{'r'}.
\end{funcdesc}
The module defines the following variables:
\begin{excdesc}{error}
Exception raised on various errors.
\end{excdesc}
\begin{datadesc}{DATASIZE}
The size of one frame's worth of audio data. This is the size of the
audio data as passed to the callback of type \code{audio}.
\end{datadesc}
\begin{datadesc}{BLOCKSIZE}
The size of one uninterpreted frame of audio data.
\end{datadesc}
The following variables are states as returned by
\function{getstatus()}:
\begin{datadesc}{READY}
The drive is ready for operation loaded with an audio CD.
\end{datadesc}
\begin{datadesc}{NODISC}
The drive does not have a CD loaded.
\end{datadesc}
\begin{datadesc}{CDROM}
The drive is loaded with a CD-ROM. Subsequent play or read operations
will return I/O errors.
\end{datadesc}
\begin{datadesc}{ERROR}
An error aoocurred while trying to read the disc or its table of
contents.
\end{datadesc}
\begin{datadesc}{PLAYING}
The drive is in CD player mode playing an audio CD through its audio
jacks.
\end{datadesc}
\begin{datadesc}{PAUSED}
The drive is in CD layer mode with play paused.
\end{datadesc}
\begin{datadesc}{STILL}
The equivalent of \constant{PAUSED} on older (non 3301) model Toshiba
CD-ROM drives. Such drives have never been shipped by SGI.
\end{datadesc}
\begin{datadesc}{audio}
\dataline{pnum}
\dataline{index}
\dataline{ptime}
\dataline{atime}
\dataline{catalog}
\dataline{ident}
\dataline{control}
Integer constants describing the various types of parser callbacks
that can be set by the \method{addcallback()} method of CD parser
objects (see below).
\end{datadesc}
\subsection{Player Objects}
\label{player-objects}
Player objects (returned by \function{open()}) have the following
methods:
\begin{methoddesc}[CD player]{allowremoval}{}
Unlocks the eject button on the CD-ROM drive permitting the user to
eject the caddy if desired.
\end{methoddesc}
\begin{methoddesc}[CD player]{bestreadsize}{}
Returns the best value to use for the \var{num_frames} parameter of
the \method{readda()} method. Best is defined as the value that
permits a continuous flow of data from the CD-ROM drive.
\end{methoddesc}
\begin{methoddesc}[CD player]{close}{}
Frees the resources associated with the player object. After calling
\method{close()}, the methods of the object should no longer be used.
\end{methoddesc}
\begin{methoddesc}[CD player]{eject}{}
Ejects the caddy from the CD-ROM drive.
\end{methoddesc}
\begin{methoddesc}[CD player]{getstatus}{}
Returns information pertaining to the current state of the CD-ROM
drive. The returned information is a tuple with the following values:
\var{state}, \var{track}, \var{rtime}, \var{atime}, \var{ttime},
\var{first}, \var{last}, \var{scsi_audio}, \var{cur_block}.
\var{rtime} is the time relative to the start of the current track;
\var{atime} is the time relative to the beginning of the disc;
\var{ttime} is the total time on the disc. For more information on
the meaning of the values, see the man page \manpage{CDgetstatus}{3dm}.
The value of \var{state} is one of the following: \constant{ERROR},
\constant{NODISC}, \constant{READY}, \constant{PLAYING},
\constant{PAUSED}, \constant{STILL}, or \constant{CDROM}.
\end{methoddesc}
\begin{methoddesc}[CD player]{gettrackinfo}{track}
Returns information about the specified track. The returned
information is a tuple consisting of two elements, the start time of
the track and the duration of the track.
\end{methoddesc}
\begin{methoddesc}[CD player]{msftoblock}{min, sec, frame}
Converts a minutes, seconds, frames triple representing a time in
absolute time code into the corresponding logical block number for the
given CD-ROM drive. You should use \function{msftoframe()} rather than
\method{msftoblock()} for comparing times. The logical block number
differs from the frame number by an offset required by certain CD-ROM
drives.
\end{methoddesc}
\begin{methoddesc}[CD player]{play}{start, play}
Starts playback of an audio CD in the CD-ROM drive at the specified
track. The audio output appears on the CD-ROM drive's headphone and
audio jacks (if fitted). Play stops at the end of the disc.
\var{start} is the number of the track at which to start playing the
CD; if \var{play} is 0, the CD will be set to an initial paused
state. The method \method{togglepause()} can then be used to commence
play.
\end{methoddesc}
\begin{methoddesc}[CD player]{playabs}{minutes, seconds, frames, play}
Like \method{play()}, except that the start is given in minutes,
seconds, and frames instead of a track number.
\end{methoddesc}
\begin{methoddesc}[CD player]{playtrack}{start, play}
Like \method{play()}, except that playing stops at the end of the
track.
\end{methoddesc}
\begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play}
Like \method{play()}, except that playing begins at the spcified
absolute time and ends at the end of the specified track.
\end{methoddesc}
\begin{methoddesc}[CD player]{preventremoval}{}
Locks the eject button on the CD-ROM drive thus preventing the user
from arbitrarily ejecting the caddy.
\end{methoddesc}
\begin{methoddesc}[CD player]{readda}{num_frames}
Reads the specified number of frames from an audio CD mounted in the
CD-ROM drive. The return value is a string representing the audio
frames. This string can be passed unaltered to the
\method{parseframe()} method of the parser object.
\end{methoddesc}
\begin{methoddesc}[CD player]{seek}{minutes, seconds, frames}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to an absolute
time code location specified in \var{minutes}, \var{seconds}, and
\var{frames}. The return value is the logical block number to which
the pointer has been set.
\end{methoddesc}
\begin{methoddesc}[CD player]{seekblock}{block}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to the specified
logical block number. The return value is the logical block number to
which the pointer has been set.
\end{methoddesc}
\begin{methoddesc}[CD player]{seektrack}{track}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to the specified
track. The return value is the logical block number to which the
pointer has been set.
\end{methoddesc}
\begin{methoddesc}[CD player]{stop}{}
Stops the current playing operation.
\end{methoddesc}
\begin{methoddesc}[CD player]{togglepause}{}
Pauses the CD if it is playing, and makes it play if it is paused.
\end{methoddesc}
\subsection{Parser Objects}
\label{cd-parser-objects}
Parser objects (returned by \function{createparser()}) have the
following methods:
\begin{methoddesc}[CD parser]{addcallback}{type, func, arg}
Adds a callback for the parser. The parser has callbacks for eight
different types of data in the digital audio data stream. Constants
for these types are defined at the \module{cd} module level (see above).
The callback is called as follows: \code{\var{func}(\var{arg}, type,
data)}, where \var{arg} is the user supplied argument, \var{type} is
the particular type of callback, and \var{data} is the data returned
for this \var{type} of callback. The type of the data depends on the
\var{type} of callback as follows:
\begin{tableii}{l|p{4in}}{code}{Type}{Value}
\lineii{audio}{String which can be passed unmodified to
\function{al.writesamps()}.}
\lineii{pnum}{Integer giving the program (track) number.}
\lineii{index}{Integer giving the index number.}
\lineii{ptime}{Tuple consisting of the program time in minutes,
seconds, and frames.}
\lineii{atime}{Tuple consisting of the absolute time in minutes,
seconds, and frames.}
\lineii{catalog}{String of 13 characters, giving the catalog number
of the CD.}
\lineii{ident}{String of 12 characters, giving the ISRC
identification number of the recording. The string consists of two
characters country code, three characters owner code, two characters
giving the year, and five characters giving a serial number.}
\lineii{control}{Integer giving the control bits from the CD
subcode data}
\end{tableii}
\end{methoddesc}
\begin{methoddesc}[CD parser]{deleteparser}{}
Deletes the parser and frees the memory it was using. The object
should not be used after this call. This call is done automatically
when the last reference to the object is removed.
\end{methoddesc}
\begin{methoddesc}[CD parser]{parseframe}{frame}
Parses one or more frames of digital audio data from a CD such as
returned by \method{readda()}. It determines which subcodes are
present in the data. If these subcodes have changed since the last
frame, then \method{parseframe()} executes a callback of the
appropriate type passing to it the subcode data found in the frame.
Unlike the \C{} function, more than one frame of digital audio data
can be passed to this method.
\end{methoddesc}
\begin{methoddesc}[CD parser]{removecallback}{type}
Removes the callback for the given \var{type}.
\end{methoddesc}
\begin{methoddesc}[CD parser]{resetparser}{}
Resets the fields of the parser used for tracking subcodes to an
initial state. \method{resetparser()} should be called after the disc
has been changed.
\end{methoddesc}

461
Doc/libcgi.tex
View File

@ -1,461 +0,0 @@
\section{Standard Module \module{cgi}}
\label{module-cgi}
\stmodindex{cgi}
\indexii{WWW}{server}
\indexii{CGI}{protocol}
\indexii{HTTP}{protocol}
\indexii{MIME}{headers}
\index{URL}
Support module for CGI (Common Gateway Interface) scripts.%
\index{Common Gateway Interface}
This module defines a number of utilities for use by CGI scripts
written in Python.
\subsection{Introduction}
\nodename{cgi-intro}
A CGI script is invoked by an HTTP server, usually to process user
input submitted through an HTML \code{<FORM>} or \code{<ISINPUT>} element.
Most often, CGI scripts live in the server's special \file{cgi-bin}
directory. The HTTP server places all sorts of information about the
request (such as the client's hostname, the requested URL, the query
string, and lots of other goodies) in the script's shell environment,
executes the script, and sends the script's output back to the client.
The script's input is connected to the client too, and sometimes the
form data is read this way; at other times the form data is passed via
the ``query string'' part of the URL. This module is intended
to take care of the different cases and provide a simpler interface to
the Python script. It also provides a number of utilities that help
in debugging scripts, and the latest addition is support for file
uploads from a form (if your browser supports it --- Grail 0.3 and
Netscape 2.0 do).
The output of a CGI script should consist of two sections, separated
by a blank line. The first section contains a number of headers,
telling the client what kind of data is following. Python code to
generate a minimal header section looks like this:
\begin{verbatim}
print "Content-type: text/html" # HTML is following
print # blank line, end of headers
\end{verbatim}
The second section is usually HTML, which allows the client software
to display nicely formatted text with header, in-line images, etc.
Here's Python code that prints a simple piece of HTML:
\begin{verbatim}
print "<TITLE>CGI script output</TITLE>"
print "<H1>This is my first CGI script</H1>"
print "Hello, world!"
\end{verbatim}
(It may not be fully legal HTML according to the letter of the
standard, but any browser will understand it.)
\subsection{Using the cgi module}
\nodename{Using the cgi module}
Begin by writing \samp{import cgi}. Do not use \samp{from cgi import
*} --- the module defines all sorts of names for its own use or for
backward compatibility that you don't want in your namespace.
It's best to use the \class{FieldStorage} class. The other classes
defined in this module are provided mostly for backward compatibility.
Instantiate it exactly once, without arguments. This reads the form
contents from standard input or the environment (depending on the
value of various environment variables set according to the CGI
standard). Since it may consume standard input, it should be
instantiated only once.
The \class{FieldStorage} instance can be accessed as if it were a Python
dictionary. For instance, the following code (which assumes that the
\code{content-type} header and blank line have already been printed)
checks that the fields \code{name} and \code{addr} are both set to a
non-empty string:
\begin{verbatim}
form = cgi.FieldStorage()
form_ok = 0
if form.has_key("name") and form.has_key("addr"):
if form["name"].value != "" and form["addr"].value != "":
form_ok = 1
if not form_ok:
print "<H1>Error</H1>"
print "Please fill in the name and addr fields."
return
...further form processing here...
\end{verbatim}
Here the fields, accessed through \samp{form[\var{key}]}, are
themselves instances of \class{FieldStorage} (or
\class{MiniFieldStorage}, depending on the form encoding).
If the submitted form data contains more than one field with the same
name, the object retrieved by \samp{form[\var{key}]} is not a
\class{FieldStorage} or \class{MiniFieldStorage}
instance but a list of such instances. If you expect this possibility
(i.e., when your HTML form comtains multiple fields with the same
name), use the \function{type()} function to determine whether you
have a single instance or a list of instances. For example, here's
code that concatenates any number of username fields, separated by
commas:
\begin{verbatim}
username = form["username"]
if type(username) is type([]):
# Multiple username fields specified
usernames = ""
for item in username:
if usernames:
# Next item -- insert comma
usernames = usernames + "," + item.value
else:
# First item -- don't insert comma
usernames = item.value
else:
# Single username field specified
usernames = username.value
\end{verbatim}
If a field represents an uploaded file, the value attribute reads the
entire file in memory as a string. This may not be what you want.
You can test for an uploaded file by testing either the filename
attribute or the file attribute. You can then read the data at
leasure from the file attribute:
\begin{verbatim}
fileitem = form["userfile"]
if fileitem.file:
# It's an uploaded file; count lines
linecount = 0
while 1:
line = fileitem.file.readline()
if not line: break
linecount = linecount + 1
\end{verbatim}
The file upload draft standard entertains the possibility of uploading
multiple files from one field (using a recursive
\mimetype{multipart/*} encoding). When this occurs, the item will be
a dictionary-like \class{FieldStorage} item. This can be determined
by testing its \member{type} attribute, which should be
\mimetype{multipart/form-data} (or perhaps another MIME type matching
\mimetype{multipart/*}). It this case, it can be iterated over
recursively just like the top-level form object.
When a form is submitted in the ``old'' format (as the query string or
as a single data part of type
\mimetype{application/x-www-form-urlencoded}), the items will actually
be instances of the class \class{MiniFieldStorage}. In this case, the
list, file and filename attributes are always \code{None}.
\subsection{Old classes}
These classes, present in earlier versions of the \module{cgi} module,
are still supported for backward compatibility. New applications
should use the \class{FieldStorage} class.
\class{SvFormContentDict} stores single value form content as
dictionary; it assumes each field name occurs in the form only once.
\class{FormContentDict} stores multiple value form content as a
dictionary (the form items are lists of values). Useful if your form
contains multiple fields with the same name.
Other classes (\class{FormContent}, \class{InterpFormContentDict}) are
present for backwards compatibility with really old applications only.
If you still use these and would be inconvenienced when they
disappeared from a next version of this module, drop me a note.
\subsection{Functions}
\nodename{Functions in cgi module}
These are useful if you want more control, or if you want to employ
some of the algorithms implemented in this module in other
circumstances.
\begin{funcdesc}{parse}{fp}
Parse a query in the environment or from a file (default
\code{sys.stdin}).
\end{funcdesc}
\begin{funcdesc}{parse_qs}{qs}
Parse a query string given as a string argument (data of type
\mimetype{application/x-www-form-urlencoded}).
\end{funcdesc}
\begin{funcdesc}{parse_multipart}{fp, pdict}
Parse input of type \mimetype{multipart/form-data} (for
file uploads). Arguments are \var{fp} for the input file and
\var{pdict} for the dictionary containing other parameters of
\code{content-type} header
Returns a dictionary just like \function{parse_qs()} keys are the
field names, each value is a list of values for that field. This is
easy to use but not much good if you are expecting megabytes to be
uploaded --- in that case, use the \class{FieldStorage} class instead
which is much more flexible. Note that \code{content-type} is the
raw, unparsed contents of the \code{content-type} header.
Note that this does not parse nested multipart parts --- use
\class{FieldStorage} for that.
\end{funcdesc}
\begin{funcdesc}{parse_header}{string}
Parse a header like \code{content-type} into a main
content-type and a dictionary of parameters.
\end{funcdesc}
\begin{funcdesc}{test}{}
Robust test CGI script, usable as main program.
Writes minimal HTTP headers and formats all information provided to
the script in HTML form.
\end{funcdesc}
\begin{funcdesc}{print_environ}{}
Format the shell environment in HTML.
\end{funcdesc}
\begin{funcdesc}{print_form}{form}
Format a form in HTML.
\end{funcdesc}
\begin{funcdesc}{print_directory}{}
Format the current directory in HTML.
\end{funcdesc}
\begin{funcdesc}{print_environ_usage}{}
Print a list of useful (used by CGI) environment variables in
HTML.
\end{funcdesc}
\begin{funcdesc}{escape}{s\optional{, quote}}
Convert the characters
\character{\&}, \character{<} and \character{>} in string \var{s} to
HTML-safe sequences. Use this if you need to display text that might
contain such characters in HTML. If the optional flag \var{quote} is
true, the double quote character (\character{"}) is also translated;
this helps for inclusion in an HTML attribute value, e.g. in \code{<A
HREF="...">}.
\end{funcdesc}
\subsection{Caring about security}
There's one important rule: if you invoke an external program (e.g.
via the \function{os.system()} or \function{os.popen()} functions),
make very sure you don't pass arbitrary strings received from the
client to the shell. This is a well-known security hole whereby
clever hackers anywhere on the web can exploit a gullible CGI script
to invoke arbitrary shell commands. Even parts of the URL or field
names cannot be trusted, since the request doesn't have to come from
your form!
To be on the safe side, if you must pass a string gotten from a form
to a shell command, you should make sure the string contains only
alphanumeric characters, dashes, underscores, and periods.
\subsection{Installing your CGI script on a Unix system}
Read the documentation for your HTTP server and check with your local
system administrator to find the directory where CGI scripts should be
installed; usually this is in a directory \file{cgi-bin} in the server tree.
Make sure that your script is readable and executable by ``others''; the
\UNIX{} file mode should be \code{0755} octal (use \samp{chmod 0755
filename}). Make sure that the first line of the script contains
\code{\#!} starting in column 1 followed by the pathname of the Python
interpreter, for instance:
\begin{verbatim}
#!/usr/local/bin/python
\end{verbatim}
Make sure the Python interpreter exists and is executable by ``others''.
Make sure that any files your script needs to read or write are
readable or writable, respectively, by ``others'' --- their mode
should be \code{0644} for readable and \code{0666} for writable. This
is because, for security reasons, the HTTP server executes your script
as user ``nobody'', without any special privileges. It can only read
(write, execute) files that everybody can read (write, execute). The
current directory at execution time is also different (it is usually
the server's cgi-bin directory) and the set of environment variables
is also different from what you get at login. In particular, don't
count on the shell's search path for executables (\envvar{PATH}) or
the Python module search path (\envvar{PYTHONPATH}) to be set to
anything interesting.
If you need to load modules from a directory which is not on Python's
default module search path, you can change the path in your script,
before importing other modules, e.g.:
\begin{verbatim}
import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")
\end{verbatim}
(This way, the directory inserted last will be searched first!)
Instructions for non-\UNIX{} systems will vary; check your HTTP server's
documentation (it will usually have a section on CGI scripts).
\subsection{Testing your CGI script}
Unfortunately, a CGI script will generally not run when you try it
from the command line, and a script that works perfectly from the
command line may fail mysteriously when run from the server. There's
one reason why you should still test your script from the command
line: if it contains a syntax error, the Python interpreter won't
execute it at all, and the HTTP server will most likely send a cryptic
error to the client.
Assuming your script has no syntax errors, yet it does not work, you
have no choice but to read the next section.
\subsection{Debugging CGI scripts}
First of all, check for trivial installation errors --- reading the
section above on installing your CGI script carefully can save you a
lot of time. If you wonder whether you have understood the
installation procedure correctly, try installing a copy of this module
file (\file{cgi.py}) as a CGI script. When invoked as a script, the file
will dump its environment and the contents of the form in HTML form.
Give it the right mode etc, and send it a request. If it's installed
in the standard \file{cgi-bin} directory, it should be possible to send it a
request by entering a URL into your browser of the form:
\begin{verbatim}
http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
\end{verbatim}
If this gives an error of type 404, the server cannot find the script
-- perhaps you need to install it in a different directory. If it
gives another error (e.g. 500), there's an installation problem that
you should fix before trying to go any further. If you get a nicely
formatted listing of the environment and form content (in this
example, the fields should be listed as ``addr'' with value ``At Home''
and ``name'' with value ``Joe Blow''), the \file{cgi.py} script has been
installed correctly. If you follow the same procedure for your own
script, you should now be able to debug it.
The next step could be to call the \module{cgi} module's
\function{test()} function from your script: replace its main code
with the single statement
\begin{verbatim}
cgi.test()
\end{verbatim}
This should produce the same results as those gotten from installing
the \file{cgi.py} file itself.
When an ordinary Python script raises an unhandled exception
(e.g. because of a typo in a module name, a file that can't be opened,
etc.), the Python interpreter prints a nice traceback and exits.
While the Python interpreter will still do this when your CGI script
raises an exception, most likely the traceback will end up in one of
the HTTP server's log file, or be discarded altogether.
Fortunately, once you have managed to get your script to execute
\emph{some} code, it is easy to catch exceptions and cause a traceback
to be printed. The \function{test()} function below in this module is
an example. Here are the rules:
\begin{enumerate}
\item Import the traceback module before entering the \keyword{try}
... \keyword{except} statement
\item Assign \code{sys.stderr} to be \code{sys.stdout}
\item Make sure you finish printing the headers and the blank line
early
\item Wrap all remaining code in a \keyword{try} ... \keyword{except}
statement
\item In the except clause, call \function{traceback.print_exc()}
\end{enumerate}
For example:
\begin{verbatim}
import sys
import traceback
print "Content-type: text/html"
print
sys.stderr = sys.stdout
try:
...your code here...
except:
print "\n\n<PRE>"
traceback.print_exc()
\end{verbatim}
Notes: The assignment to \code{sys.stderr} is needed because the
traceback prints to \code{sys.stderr}.
The \code{print "{\e}n{\e}n<PRE>"} statement is necessary to
disable the word wrapping in HTML.
If you suspect that there may be a problem in importing the traceback
module, you can use an even more robust approach (which only uses
built-in modules):
\begin{verbatim}
import sys
sys.stderr = sys.stdout
print "Content-type: text/plain"
print
...your code here...
\end{verbatim}
This relies on the Python interpreter to print the traceback. The
content type of the output is set to plain text, which disables all
HTML processing. If your script works, the raw HTML will be displayed
by your client. If it raises an exception, most likely after the
first two lines have been printed, a traceback will be displayed.
Because no HTML interpretation is going on, the traceback will
readable.
\subsection{Common problems and solutions}
\begin{itemize}
\item Most HTTP servers buffer the output from CGI scripts until the
script is completed. This means that it is not possible to display a
progress report on the client's display while the script is running.
\item Check the installation instructions above.
\item Check the HTTP server's log files. (\samp{tail -f logfile} in a
separate window may be useful!)
\item Always check a script for syntax errors first, by doing something
like \samp{python script.py}.
\item When using any of the debugging techniques, don't forget to add
\samp{import sys} to the top of the script.
\item When invoking external programs, make sure they can be found.
Usually, this means using absolute path names --- \envvar{PATH} is
usually not set to a very useful value in a CGI script.
\item When reading or writing external files, make sure they can be read
or written by every user on the system.
\item Don't try to give a CGI script a set-uid mode. This doesn't work on
most systems, and is a security liability as well.
\end{itemize}

90
Doc/libcmath.tex
View File

@ -1,90 +0,0 @@
\section{Built-in Module \module{cmath}}
\label{module-cmath}
\bimodindex{cmath}
This module is always available.
It provides access to mathematical functions for complex numbers.
The functions are:
\begin{funcdesc}{acos}{x}
Return the arc cosine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{acosh}{x}
Return the hyperbolic arc cosine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{asin}{x}
Return the arc sine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{asinh}{x}
Return the hyperbolic arc sine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{atan}{x}
Return the arc tangent of \var{x}.
\end{funcdesc}
\begin{funcdesc}{atanh}{x}
Return the hyperbolic arc tangent of \var{x}.
\end{funcdesc}
\begin{funcdesc}{cos}{x}
Return the cosine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{cosh}{x}
Return the hyperbolic cosine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{exp}{x}
Return the exponential value \code{e**\var{x}}.
\end{funcdesc}
\begin{funcdesc}{log}{x}
Return the natural logarithm of \var{x}.
\end{funcdesc}
\begin{funcdesc}{log10}{x}
Return the base-10 logarithm of \var{x}.
\end{funcdesc}
\begin{funcdesc}{sin}{x}
Return the sine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{sinh}{x}
Return the hyperbolic sine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{sqrt}{x}
Return the square root of \var{x}.
\end{funcdesc}
\begin{funcdesc}{tan}{x}
Return the tangent of \var{x}.
\end{funcdesc}
\begin{funcdesc}{tanh}{x}
Return the hyperbolic tangent of \var{x}.
\end{funcdesc}
The module also defines two mathematical constants:
\begin{datadesc}{pi}
The mathematical constant \emph{pi}, as a real.
\end{datadesc}
\begin{datadesc}{e}
The mathematical constant \emph{e}, as a real.
\end{datadesc}
Note that the selection of functions is similar, but not identical, to
that in module \code{math}\refbimodindex{math}. The reason for having
two modules is, that some users aren't interested in complex numbers,
and perhaps don't even know what they are. They would rather have
\code{math.sqrt(-1)} raise an exception than return a complex number.
Also note that the functions defined in \code{cmath} always return a
complex number, even if the answer can be expressed as a real number
(in which case the complex number has an imaginary part of zero).

31
Doc/libcode.tex
View File

@ -1,31 +0,0 @@
\section{Standard Module \module{code}}
\label{module-code}
\stmodindex{code}
The \code{code} module defines operations pertaining to Python code
objects.
The \code{code} module defines the following functions:
\begin{funcdesc}{compile_command}{source, \optional{filename\optional{, symbol}}}
This function is useful for programs that want to emulate Python's
interpreter main loop (a.k.a. the read-eval-print loop). The tricky
part is to determine when the user has entered an incomplete command
that can be completed by entering more text (as opposed to a complete
command or a syntax error). This function \emph{almost} always makes
the same decision as the real interpreter main loop.
Arguments: \var{source} is the source string; \var{filename} is the
optional filename from which source was read, defaulting to
\code{"<input>"}; and \var{symbol} is the optional grammar start
symbol, which should be either \code{"single"} (the default) or
\code{"eval"}.
Return a code object (the same as \code{compile(\var{source},
\var{filename}, \var{symbol})}) if the command is complete and valid;
return \code{None} if the command is incomplete; raise
\code{SyntaxError} if the command is a syntax error.
\end{funcdesc}

52
Doc/libcommands.tex
View File

@ -1,52 +0,0 @@
% Documentation written by Sue Williams.
\section{Standard Module \module{commands}}
\stmodindex{commands}
\label{module-commands}
The \module{commands} module contains wrapper functions for
\function{os.popen()} which take a system command as a string and
return any output generated by the command and, optionally, the exit
status.
The \module{commands} module is only usable on systems which support
\function{os.popen()} (currently \UNIX{}). It defines the following
functions:
\begin{funcdesc}{getstatusoutput}{cmd}
Execute the string \var{cmd} in a shell with \function{os.popen()} and
return a 2-tuple \code{(\var{status}, \var{output})}. \var{cmd} is
actually run as \code{\{ \var{cmd} ; \} 2>\&1}, so that the returned
output will contain output or error messages. A trailing newline is
stripped from the output. The exit status for the command can be
interpreted according to the rules for the \C{} function
\cfunction{wait()}.
\end{funcdesc}
\begin{funcdesc}{getoutput}{cmd}
Like \function{getstatusoutput()}, except the exit status is ignored
and the return value is a string containing the command's output.
\end{funcdesc}
\begin{funcdesc}{getstatus}{file}
Return the output of \samp{ls -ld \var{file}} as a string. This
function uses the \function{getoutput()} function, and properly
escapes backslashes and dollar signs in the argument.
\end{funcdesc}
Example:
\begin{verbatim}
>>> import commands
>>> commands.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> commands.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> commands.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')
>>> commands.getoutput('ls /bin/ls')
'/bin/ls'
>>> commands.getstatus('/bin/ls')
'-rwxr-xr-x 1 root 13352 Oct 14 1994 /bin/ls'
\end{verbatim}

82
Doc/libcopy.tex
View File

@ -1,82 +0,0 @@
\section{Standard Module \module{copy}}
\label{module-copy}
\stmodindex{copy}
\setindexsubitem{(copy function)}
\ttindex{copy}
\ttindex{deepcopy}
This module provides generic (shallow and deep) copying operations.
Interface summary:
\begin{verbatim}
import copy
x = copy.copy(y) # make a shallow copy of y
x = copy.deepcopy(y) # make a deep copy of y
\end{verbatim}
%
For module specific errors, \code{copy.error} is raised.
The difference between shallow and deep copying is only relevant for
compound objects (objects that contain other objects, like lists or
class instances):
\begin{itemize}
\item
A \emph{shallow copy} constructs a new compound object and then (to the
extent possible) inserts \emph{references} into it to the objects found
in the original.
\item
A \emph{deep copy} constructs a new compound object and then,
recursively, inserts \emph{copies} into it of the objects found in the
original.
\end{itemize}
Two problems often exist with deep copy operations that don't exist
with shallow copy operations:
\begin{itemize}
\item
Recursive objects (compound objects that, directly or indirectly,
contain a reference to themselves) may cause a recursive loop.
\item
Because deep copy copies \emph{everything} it may copy too much, e.g.\
administrative data structures that should be shared even between
copies.
\end{itemize}
Python's \code{deepcopy()} operation avoids these problems by:
\begin{itemize}
\item
keeping a table of objects already copied during the current
copying pass; and
\item
letting user-defined classes override the copying operation or the
set of components copied.
\end{itemize}
This version does not copy types like module, class, function, method,
nor stack trace, stack frame, nor file, socket, window, nor array, nor
any similar types.
Classes can use the same interfaces to control copying that they use
to control pickling: they can define methods called
\code{__getinitargs__()}, \code{__getstate__()} and
\code{__setstate__()}. See the description of module \code{pickle}
for information on these methods.
\refstmodindex{pickle}
\setindexsubitem{(copy protocol)}
\ttindex{__getinitargs__}
\ttindex{__getstate__}
\ttindex{__setstate__}

27
Doc/libcopyreg.tex
View File

@ -1,27 +0,0 @@
\section{Standard Module \module{copy_reg}}
% Note that the label is a little off; the underscore causes LaTeX to
% yell & scream.
\label{module-copyreg}
\stmodindex{copy_reg}
The \code{copy_reg} module provides support for the
\code{pickle}\refstmodindex{pickle} and
\code{cPickle}\refbimodindex{cPickle} modules. The
\code{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.
\begin{funcdesc}{constructor}{object}
Declares \var{object} to be a valid constructor.
\end{funcdesc}
\begin{funcdesc}{pickle}{type, function\optional{, constructor}}
Declares that \var{function} should be used as a ``reduction''
function for objects of type or class \var{type}. \var{function}
should return either a string or a tuple. The optional
\var{constructor} parameter, if provided, is a callable object which
can be used to reconstruct the object when called with the tuple of
arguments returned by \var{function} at pickling time.
\end{funcdesc}

22
Doc/libcrypt.tex
View File

@ -1,22 +0,0 @@
\section{Built-in Module \module{crypt}}
\label{module-crypt}
\bimodindex{crypt}
This module implements an interface to the \manpage{crypt}{3} routine,
which is a one-way hash function based upon a modified DES algorithm;
see the \UNIX{} man page for further details. Possible uses include
allowing Python scripts to accept typed passwords from the user, or
attempting to crack \UNIX{} passwords with a dictionary.
\index{crypt(3)}
\begin{funcdesc}{crypt}{word, salt}
\var{word} will usually be a user's password. \var{salt} is a
2-character string which will be used to select one of 4096 variations
of DES\indexii{cipher}{DES}. The characters in \var{salt} must be
either \code{.}, \code{/}, or an alphanumeric character. Returns the
hashed password as a string, which will be composed of characters from
the same alphabet as the salt.
\end{funcdesc}
The module and documentation were written by Steve Majewski.
\index{Majewski, Steve}

34
Doc/libcrypto.tex
View File

@ -1,34 +0,0 @@
\chapter{Cryptographic Services}
\label{crypto}
\index{cryptography}
The modules described in this chapter implement various algorithms of
a cryptographic nature. They are available at the discretion of the
installation. Here's an overview:
\begin{description}
\item[md5]
--- RSA's MD5 message digest algorithm.
\item[mpz]
--- Interface to the GNU MP library for arbitrary precision arithmetic.
\item[rotor]
--- Enigma-like encryption and decryption.
\end{description}
Hardcore cypherpunks will probably find the cryptographic modules
written by Andrew Kuchling of further interest; the package adds
built-in modules for DES and IDEA encryption, provides a Python module
for reading and decrypting PGP files, and then some. These modules
are not distributed with Python but available separately. See the URL
\url{http://starship.skyport.net/crew/amk/maintained/crypto.html} or
send email to \email{akuchlin@acm.org} for more information.
\index{PGP}
\index{Pretty Good Privacy}
\indexii{DES}{cipher}
\indexii{IDEA}{cipher}
\index{cryptography}
\index{Kuchling, Andrew}

36
Doc/libdbm.tex
View File

@ -1,36 +0,0 @@
\section{Built-in Module \module{dbm}}
\label{module-dbm}
\bimodindex{dbm}
The \code{dbm} module provides an interface to the \UNIX{}
\code{(n)dbm} library. Dbm objects behave like mappings
(dictionaries), except that keys and values are always strings.
Printing a dbm object doesn't print the keys and values, and the
\code{items()} and \code{values()} methods are not supported.
See also the \code{gdbm} module, which provides a similar interface
using the GNU GDBM library.
\refbimodindex{gdbm}
The module defines the following constant and functions:
\begin{excdesc}{error}
Raised on dbm-specific errors, such as I/O errors. \code{KeyError} is
raised for general mapping errors like specifying an incorrect key.
\end{excdesc}
\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
Open a dbm database and return a dbm object. The \var{filename}
argument is the name of the database file (without the \file{.dir} or
\file{.pag} extensions).
The optional \var{flag} argument can be
\code{'r'} (to open an existing database for reading only --- default),
\code{'w'} (to open an existing database for reading and writing),
\code{'c'} (which creates the database if it doesn't exist), or
\code{'n'} (which always creates a new empty database).
The optional \var{mode} argument is the \UNIX{} mode of the file, used
only when the database has to be created. It defaults to octal
\code{0666}.
\end{funcdesc}

512
Doc/libdis.tex
View File

@ -1,512 +0,0 @@
\section{Standard Module \module{dis}}
\stmodindex{dis}
\label{module-dis}
The \module{dis} module supports the analysis of Python byte code by
disassembling it. Since there is no Python assembler, this module
defines the Python assembly language. The Python byte code which
this module takes as an input is defined in the file
\file{Include/opcode.h} and used by the compiler and the interpreter.
Example: Given the function \function{myfunc}:
\begin{verbatim}
def myfunc(alist):
return len(alist)
\end{verbatim}
the following command can be used to get the disassembly of
\function{myfunc()}:
\begin{verbatim}
>>> dis.dis(myfunc)
0 SET_LINENO 1
3 SET_LINENO 2
6 LOAD_GLOBAL 0 (len)
9 LOAD_FAST 0 (alist)
12 CALL_FUNCTION 1
15 RETURN_VALUE
16 LOAD_CONST 0 (None)
19 RETURN_VALUE
\end{verbatim}
The \module{dis} module defines the following functions:
\begin{funcdesc}{dis}{\optional{bytesource}}
Disassemble the \var{bytesource} object. \var{bytesource} can denote
either a class, a method, a function, or a code object. For a class,
it disassembles all methods. For a single code sequence, it prints
one line per byte code instruction. If no object is provided, it
disassembles the last traceback.
\end{funcdesc}
\begin{funcdesc}{distb}{\optional{tb}}
Disassembles the top-of-stack function of a traceback, using the last
traceback if none was passed. The instruction causing the exception
is indicated.
\end{funcdesc}
\begin{funcdesc}{disassemble}{code\optional{, lasti}}
Disassembles a code object, indicating the last instruction if \var{lasti}
was provided. The output is divided in the following columns:
\begin{enumerate}
\item the current instruction, indicated as \samp{-->},
\item a labelled instruction, indicated with \samp{>>},
\item the address of the instruction,
\item the operation code name,
\item operation parameters, and
\item interpretation of the parameters in parentheses.
\end{enumerate}
The parameter interpretation recognizes local and global
variable names, constant values, branch targets, and compare
operators.
\end{funcdesc}
\begin{funcdesc}{disco}{code\optional{, lasti}}
A synonym for disassemble. It is more convenient to type, and kept
for compatibility with earlier Python releases.
\end{funcdesc}
\begin{datadesc}{opname}
Sequence of a operation names, indexable using the byte code.
\end{datadesc}
\begin{datadesc}{cmp_op}
Sequence of all compare operation names.
\end{datadesc}
\begin{datadesc}{hasconst}
Sequence of byte codes that have a constant parameter.
\end{datadesc}
\begin{datadesc}{hasname}
Sequence of byte codes that access a attribute by name.
\end{datadesc}
\begin{datadesc}{hasjrel}
Sequence of byte codes that have a relative jump target.
\end{datadesc}
\begin{datadesc}{hasjabs}
Sequence of byte codes that have an absolute jump target.
\end{datadesc}
\begin{datadesc}{haslocal}
Sequence of byte codes that access a a local variable.
\end{datadesc}
\begin{datadesc}{hascompare}
Sequence of byte codes of boolean operations.
\end{datadesc}
\subsection{Python Byte Code Instructions}
\label{bytecodes}
The Python compiler currently generates the following byte code
instructions.
\setindexsubitem{(byte code insns)}
\begin{opcodedesc}{STOP_CODE}{}
Indicates end-of-code to the compiler, not used by the interpreter.
\end{opcodedesc}
\begin{opcodedesc}{POP_TOP}{}
Removes the top-of-stack (TOS) item.
\end{opcodedesc}
\begin{opcodedesc}{ROT_TWO}{}
Swaps the two top-most stack items.
\end{opcodedesc}
\begin{opcodedesc}{ROT_THREE}{}
Lifts second and third stack item one position up, moves top down
to position three.
\end{opcodedesc}
\begin{opcodedesc}{DUP_TOP}{}
Duplicates the reference on top of the stack.
\end{opcodedesc}
Unary Operations take the top of the stack, apply the operation, and
push the result back on the stack.
\begin{opcodedesc}{UNARY_POSITIVE}{}
Implements \code{TOS = +TOS}.
\end{opcodedesc}
\begin{opcodedesc}{UNARY_NEG}{}
Implements \code{TOS = -TOS}.
\end{opcodedesc}
\begin{opcodedesc}{UNARY_NOT}{}
Implements \code{TOS = not TOS}.
\end{opcodedesc}
\begin{opcodedesc}{UNARY_CONVERT}{}
Implements \code{TOS = `TOS`}.
\end{opcodedesc}
\begin{opcodedesc}{UNARY_INVERT}{}
Implements \code{TOS = \~TOS}.
\end{opcodedesc}
Binary operations remove the top of the stack (TOS) and the second top-most
stack item (TOS1) from the stack. They perform the operation, and put the
result back on the stack.
\begin{opcodedesc}{BINARY_POWER}{}
Implements \code{TOS = TOS1 ** TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_MULTIPLY}{}
Implements \code{TOS = TOS1 * TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_DIVIDE}{}
Implements \code{TOS = TOS1 / TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_MODULO}{}
Implements \code{TOS = TOS1 \% TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_ADD}{}
Implements \code{TOS = TOS1 + TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_SUBTRACT}{}
Implements \code{TOS = TOS1 - TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_SUBSCR}{}
Implements \code{TOS = TOS1[TOS]}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_LSHIFT}{}
Implements \code{TOS = TOS1 << TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_RSHIFT}{}
Implements \code{TOS = TOS1 >> TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_AND}{}
Implements \code{TOS = TOS1 and TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_XOR}{}
Implements \code{TOS = TOS1 \^\ TOS}.
\end{opcodedesc}
\begin{opcodedesc}{BINARY_OR}{}
Implements \code{TOS = TOS1 or TOS}.
\end{opcodedesc}
The slice opcodes take up to three parameters.
\begin{opcodedesc}{SLICE+0}{}
Implements \code{TOS = TOS[:]}.
\end{opcodedesc}
\begin{opcodedesc}{SLICE+1}{}
Implements \code{TOS = TOS1[TOS:]}.
\end{opcodedesc}
\begin{opcodedesc}{SLICE+2}{}
Implements \code{TOS = TOS1[:TOS1]}.
\end{opcodedesc}
\begin{opcodedesc}{SLICE+3}{}
Implements \code{TOS = TOS2[TOS1:TOS]}.
\end{opcodedesc}
Slice assignment needs even an additional parameter. As any statement,
they put nothing on the stack.
\begin{opcodedesc}{STORE_SLICE+0}{}
Implements \code{TOS[:] = TOS1}.
\end{opcodedesc}
\begin{opcodedesc}{STORE_SLICE+1}{}
Implements \code{TOS1[TOS:] = TOS2}.
\end{opcodedesc}
\begin{opcodedesc}{STORE_SLICE+2}{}
Implements \code{TOS1[:TOS] = TOS2}.
\end{opcodedesc}
\begin{opcodedesc}{STORE_SLICE+3}{}
Implements \code{TOS2[TOS1:TOS] = TOS3}.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_SLICE+0}{}
Implements \code{del TOS[:]}.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_SLICE+1}{}
Implements \code{del TOS1[TOS:]}.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_SLICE+2}{}
Implements \code{del TOS1[:TOS]}.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_SLICE+3}{}
Implements \code{del TOS2[TOS1:TOS]}.
\end{opcodedesc}
\begin{opcodedesc}{STORE_SUBSCR}{}
Implements \code{TOS1[TOS] = TOS2}.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_SUBSCR}{}
Implements \code{del TOS1[TOS]}.
\end{opcodedesc}
\begin{opcodedesc}{PRINT_EXPR}{}
Implements the expression statement for the interactive mode. TOS is
removed from the stack and printed. In non-interactive mode, an
expression statement is terminated with \code{POP_STACK}.
\end{opcodedesc}
\begin{opcodedesc}{PRINT_ITEM}{}
Prints TOS. There is one such instruction for
each item in the print statement.
\end{opcodedesc}
\begin{opcodedesc}{PRINT_NEWLINE}{}
Prints a new line on \code{sys.stdout}. This is generated as the
last operation of a print statement, unless the statement ends
with a comma.
\end{opcodedesc}
\begin{opcodedesc}{BREAK_LOOP}{}
Terminates a loop due to a break statement.
\end{opcodedesc}
\begin{opcodedesc}{LOAD_LOCALS}{}
Pushes a reference to the locals of the current scope on the stack.
This is used in the code for a class definition: After the class body
is evaluated, the locals are passed to the class definition.
\end{opcodedesc}
\begin{opcodedesc}{RETURN_VALUE}{}
Returns with TOS to the caller of the function.
\end{opcodedesc}
\begin{opcodedesc}{EXEC_STMT}{}
Implements \code{exec TOS2,TOS1,TOS}. The compiler fills
missing optional parameters with None.
\end{opcodedesc}
\begin{opcodedesc}{POP_BLOCK}{}
Removes one block from the block stack. Per frame, there is a
stack of blocks, denoting nested loops, try statements, and such.
\end{opcodedesc}
\begin{opcodedesc}{END_FINALLY}{}
Terminates a finally-block. The interpreter recalls whether the
exception has to be re-raised, or whether the function returns,
and continues with the outer-next block.
\end{opcodedesc}
\begin{opcodedesc}{BUILD_CLASS}{}
Creates a new class object. TOS is the methods dictionary, TOS1
the tuple of the names of the base classes, and TOS2 the class name.
\end{opcodedesc}
All of the following opcodes expect arguments. An argument is two
bytes, with the more significant byte last.
\begin{opcodedesc}{STORE_NAME}{namei}
Implements \code{name = TOS}. \var{namei} is the index of \var{name}
in the attribute \member{co_names} of the code object.
The compiler tries to use \code{STORE_LOCAL} or \code{STORE_GLOBAL}
if possible.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_NAME}{namei}
Implements \code{del name}, where \var{namei} is the index into
\member{co_names} attribute of the code object.
\end{opcodedesc}
\begin{opcodedesc}{UNPACK_TUPLE}{count}
Unpacks TOS into \var{count} individual values, which are put onto
the stack right-to-left.
\end{opcodedesc}
\begin{opcodedesc}{UNPACK_LIST}{count}
Unpacks TOS into \var{count} individual values.
\end{opcodedesc}
%\begin{opcodedesc}{UNPACK_ARG}{count}
%This opcode is obsolete.
%\end{opcodedesc}
\begin{opcodedesc}{STORE_ATTR}{namei}
Implements \code{TOS.name = TOS1}, where \var{namei} is the index
of name in \member{co_names}.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_ATTR}{namei}
Implements \code{del TOS.name}, using \var{namei} as index into
\member{co_names}.
\end{opcodedesc}
\begin{opcodedesc}{STORE_GLOBAL}{namei}
Works as \code{STORE_NAME}, but stores the name as a global.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_GLOBAL}{namei}
Works as \code{DELETE_NAME}, but deletes a global name.
\end{opcodedesc}
%\begin{opcodedesc}{UNPACK_VARARG}{argc}
%This opcode is obsolete.
%\end{opcodedesc}
\begin{opcodedesc}{LOAD_CONST}{consti}
Pushes \samp{co_consts[\var{consti}]} onto the stack.
\end{opcodedesc}
\begin{opcodedesc}{LOAD_NAME}{namei}
Pushes the value associated with \samp{co_names[\var{namei}]} onto the stack.
\end{opcodedesc}
\begin{opcodedesc}{BUILD_TUPLE}{count}
Creates a tuple consuming \var{count} items from the stack, and pushes
the resulting tuple onto the stack.
\end{opcodedesc}
\begin{opcodedesc}{BUILD_LIST}{count}
Works as \code{BUILD_TUPLE}, but creates a list.
\end{opcodedesc}
\begin{opcodedesc}{BUILD_MAP}{zero}
Pushes an empty dictionary object onto the stack. The argument is ignored
and set to zero by the compiler.
\end{opcodedesc}
\begin{opcodedesc}{LOAD_ATTR}{namei}
Replaces TOS with \code{getattr(TOS,co_names[\var{namei}]}.
\end{opcodedesc}
\begin{opcodedesc}{COMPARE_OP}{opname}
Performs a boolean operation. The operation name can be found
in \code{cmp_op[\var{opname}]}.
\end{opcodedesc}
\begin{opcodedesc}{IMPORT_NAME}{namei}
Imports the module \code{co_names[\var{namei}]}. The module object is
pushed onto the stack. The current name space is not affected: for a
proper import statement, a subsequent \code{STORE_FAST} instruction
modifies the name space.
\end{opcodedesc}
\begin{opcodedesc}{IMPORT_FROM}{namei}
Imports the attribute \code{co_names[\var{namei}]}. The module to import
from is found in TOS and left there.
\end{opcodedesc}
\begin{opcodedesc}{JUMP_FORWARD}{delta}
Increments byte code counter by \var{delta}.
\end{opcodedesc}
\begin{opcodedesc}{JUMP_IF_TRUE}{delta}
If TOS is true, increment the byte code counter by \var{delta}. TOS is
left on the stack.
\end{opcodedesc}
\begin{opcodedesc}{JUMP_IF_FALSE}{delta}
If TOS is false, increment the byte code counter by \var{delta}. TOS
is not changed.
\end{opcodedesc}
\begin{opcodedesc}{JUMP_ABSOLUTE}{target}
Set byte code counter to \var{target}.
\end{opcodedesc}
\begin{opcodedesc}{FOR_LOOP}{delta}
Iterate over a sequence. TOS is the current index, TOS1 the sequence.
First, the next element is computed. If the sequence is exhausted,
increment byte code counter by \var{delta}. Otherwise, push the
sequence, the incremented counter, and the current item onto the stack.
\end{opcodedesc}
%\begin{opcodedesc}{LOAD_LOCAL}{namei}
%This opcode is obsolete.
%\end{opcodedesc}
\begin{opcodedesc}{LOAD_GLOBAL}{namei}
Loads the global named \code{co_names[\var{namei}]} onto the stack.
\end{opcodedesc}
%\begin{opcodedesc}{SET_FUNC_ARGS}{argc}
%This opcode is obsolete.
%\end{opcodedesc}
\begin{opcodedesc}{SETUP_LOOP}{delta}
Pushes a block for a loop onto the block stack. The block spans
from the current instruction with a size of \var{delta} bytes.
\end{opcodedesc}
\begin{opcodedesc}{SETUP_EXCEPT}{delta}
Pushes a try block from a try-except clause onto the block stack.
\var{delta} points to the first except block.
\end{opcodedesc}
\begin{opcodedesc}{SETUP_FINALLY}{delta}
Pushes a try block from a try-except clause onto the block stack.
\var{delta} points to the finally block.
\end{opcodedesc}
\begin{opcodedesc}{LOAD_FAST}{var_num}
Pushes a reference to the local \code{co_varnames[\var{var_num}]} onto
the stack.
\end{opcodedesc}
\begin{opcodedesc}{STORE_FAST}{var_num}
Stores TOS into the local \code{co_varnames[\var{var_num}]}.
\end{opcodedesc}
\begin{opcodedesc}{DELETE_FAST}{var_num}
Deletes local \code{co_varnames[\var{var_num}]}.
\end{opcodedesc}
\begin{opcodedesc}{SET_LINE_NO}{lineno}
Sets the current line number to \var{lineno}.
\end{opcodedesc}
\begin{opcodedesc}{RAISE_VARARGS}{argc}
Raises an exception. \var{argc} indicates the number of parameters
to the raise statement, ranging from 1 to 3. The handler will find
the traceback as TOS2, the parameter as TOS1, and the exception
as TOS.
\end{opcodedesc}
\begin{opcodedesc}{CALL_FUNCTION}{argc}
Calls a function. The low byte of \var{argc} indicates the number of
positional parameters, the high byte the number of keyword parameters.
On the stack, the opcode finds the keyword parameters first. For each
keyword argument, the value is on top of the key. Below the keyword
parameters, the positional parameters are on the stack, with the
right-most parameter on top. Below the parameters, the function object
to call is on the stack.
\end{opcodedesc}
\begin{opcodedesc}{MAKE_FUNCTION}{argc}
Pushes a new function object on the stack. TOS is the code associated
with the function. The function object is defined to have \var{argc}
default parameters, which are found below TOS.
\end{opcodedesc}
\begin{opcodedesc}{BUILD_SLICE}{argc}
Pushes a slice object on the stack. \var{argc} must be 2 or 3. If it
is 2, \code{slice(TOS1, TOS)} is pushed; if it is 3,
\code{slice(TOS2, TOS1, TOS)} is pushed.
See the \code{slice()}\bifuncindex{slice} built-in function.
\end{opcodedesc}

146
Doc/liberrno.tex
View File

@ -1,146 +0,0 @@
\section{Standard Module \module{errno}}
\label{module-errno}
\stmodindex{errno}
This module makes available standard errno system symbols.
The value of each symbol is the corresponding integer value.
The names and descriptions are borrowed from \file{linux/include/errno.h},
which should be pretty all-inclusive.
\begin{datadesc}{errorcode}
Dictionary providing a mapping from the errno value to the string
name in the underlying system. For instance,
\code{errno.errorcode[errno.EPERM]} maps to \code{'EPERM'}.
\end{datadesc}
To translate a numeric error code to an error message, use
\function{os.strerror()}.
Of the following list, symbols that are not used on the current
platform are not defined by the module. Symbols available can
include:
\begin{datadesc}{EPERM} Operation not permitted \end{datadesc}
\begin{datadesc}{ENOENT} No such file or directory \end{datadesc}
\begin{datadesc}{ESRCH} No such process \end{datadesc}
\begin{datadesc}{EINTR} Interrupted system call \end{datadesc}
\begin{datadesc}{EIO} I/O error \end{datadesc}
\begin{datadesc}{ENXIO} No such device or address \end{datadesc}
\begin{datadesc}{E2BIG} Arg list too long \end{datadesc}
\begin{datadesc}{ENOEXEC} Exec format error \end{datadesc}
\begin{datadesc}{EBADF} Bad file number \end{datadesc}
\begin{datadesc}{ECHILD} No child processes \end{datadesc}
\begin{datadesc}{EAGAIN} Try again \end{datadesc}
\begin{datadesc}{ENOMEM} Out of memory \end{datadesc}
\begin{datadesc}{EACCES} Permission denied \end{datadesc}
\begin{datadesc}{EFAULT} Bad address \end{datadesc}
\begin{datadesc}{ENOTBLK} Block device required \end{datadesc}
\begin{datadesc}{EBUSY} Device or resource busy \end{datadesc}
\begin{datadesc}{EEXIST} File exists \end{datadesc}
\begin{datadesc}{EXDEV} Cross-device link \end{datadesc}
\begin{datadesc}{ENODEV} No such device \end{datadesc}
\begin{datadesc}{ENOTDIR} Not a directory \end{datadesc}
\begin{datadesc}{EISDIR} Is a directory \end{datadesc}
\begin{datadesc}{EINVAL} Invalid argument \end{datadesc}
\begin{datadesc}{ENFILE} File table overflow \end{datadesc}
\begin{datadesc}{EMFILE} Too many open files \end{datadesc}
\begin{datadesc}{ENOTTY} Not a typewriter \end{datadesc}
\begin{datadesc}{ETXTBSY} Text file busy \end{datadesc}
\begin{datadesc}{EFBIG} File too large \end{datadesc}
\begin{datadesc}{ENOSPC} No space left on device \end{datadesc}
\begin{datadesc}{ESPIPE} Illegal seek \end{datadesc}
\begin{datadesc}{EROFS} Read-only file system \end{datadesc}
\begin{datadesc}{EMLINK} Too many links \end{datadesc}
\begin{datadesc}{EPIPE} Broken pipe \end{datadesc}
\begin{datadesc}{EDOM} Math argument out of domain of func \end{datadesc}
\begin{datadesc}{ERANGE} Math result not representable \end{datadesc}
\begin{datadesc}{EDEADLK} Resource deadlock would occur \end{datadesc}
\begin{datadesc}{ENAMETOOLONG} File name too long \end{datadesc}
\begin{datadesc}{ENOLCK} No record locks available \end{datadesc}
\begin{datadesc}{ENOSYS} Function not implemented \end{datadesc}
\begin{datadesc}{ENOTEMPTY} Directory not empty \end{datadesc}
\begin{datadesc}{ELOOP} Too many symbolic links encountered \end{datadesc}
\begin{datadesc}{EWOULDBLOCK} Operation would block \end{datadesc}
\begin{datadesc}{ENOMSG} No message of desired type \end{datadesc}
\begin{datadesc}{EIDRM} Identifier removed \end{datadesc}
\begin{datadesc}{ECHRNG} Channel number out of range \end{datadesc}
\begin{datadesc}{EL2NSYNC} Level 2 not synchronized \end{datadesc}
\begin{datadesc}{EL3HLT} Level 3 halted \end{datadesc}
\begin{datadesc}{EL3RST} Level 3 reset \end{datadesc}
\begin{datadesc}{ELNRNG} Link number out of range \end{datadesc}
\begin{datadesc}{EUNATCH} Protocol driver not attached \end{datadesc}
\begin{datadesc}{ENOCSI} No CSI structure available \end{datadesc}
\begin{datadesc}{EL2HLT} Level 2 halted \end{datadesc}
\begin{datadesc}{EBADE} Invalid exchange \end{datadesc}
\begin{datadesc}{EBADR} Invalid request descriptor \end{datadesc}
\begin{datadesc}{EXFULL} Exchange full \end{datadesc}
\begin{datadesc}{ENOANO} No anode \end{datadesc}
\begin{datadesc}{EBADRQC} Invalid request code \end{datadesc}
\begin{datadesc}{EBADSLT} Invalid slot \end{datadesc}
\begin{datadesc}{EDEADLOCK} File locking deadlock error \end{datadesc}
\begin{datadesc}{EBFONT} Bad font file format \end{datadesc}
\begin{datadesc}{ENOSTR} Device not a stream \end{datadesc}
\begin{datadesc}{ENODATA} No data available \end{datadesc}
\begin{datadesc}{ETIME} Timer expired \end{datadesc}
\begin{datadesc}{ENOSR} Out of streams resources \end{datadesc}
\begin{datadesc}{ENONET} Machine is not on the network \end{datadesc}
\begin{datadesc}{ENOPKG} Package not installed \end{datadesc}
\begin{datadesc}{EREMOTE} Object is remote \end{datadesc}
\begin{datadesc}{ENOLINK} Link has been severed \end{datadesc}
\begin{datadesc}{EADV} Advertise error \end{datadesc}
\begin{datadesc}{ESRMNT} Srmount error \end{datadesc}
\begin{datadesc}{ECOMM} Communication error on send \end{datadesc}
\begin{datadesc}{EPROTO} Protocol error \end{datadesc}
\begin{datadesc}{EMULTIHOP} Multihop attempted \end{datadesc}
\begin{datadesc}{EDOTDOT} RFS specific error \end{datadesc}
\begin{datadesc}{EBADMSG} Not a data message \end{datadesc}
\begin{datadesc}{EOVERFLOW} Value too large for defined data type \end{datadesc}
\begin{datadesc}{ENOTUNIQ} Name not unique on network \end{datadesc}
\begin{datadesc}{EBADFD} File descriptor in bad state \end{datadesc}
\begin{datadesc}{EREMCHG} Remote address changed \end{datadesc}
\begin{datadesc}{ELIBACC} Can not access a needed shared library \end{datadesc}
\begin{datadesc}{ELIBBAD} Accessing a corrupted shared library \end{datadesc}
\begin{datadesc}{ELIBSCN} .lib section in a.out corrupted \end{datadesc}
\begin{datadesc}{ELIBMAX} Attempting to link in too many shared libraries \end{datadesc}
\begin{datadesc}{ELIBEXEC} Cannot exec a shared library directly \end{datadesc}
\begin{datadesc}{EILSEQ} Illegal byte sequence \end{datadesc}
\begin{datadesc}{ERESTART} Interrupted system call should be restarted \end{datadesc}
\begin{datadesc}{ESTRPIPE} Streams pipe error \end{datadesc}
\begin{datadesc}{EUSERS} Too many users \end{datadesc}
\begin{datadesc}{ENOTSOCK} Socket operation on non-socket \end{datadesc}
\begin{datadesc}{EDESTADDRREQ} Destination address required \end{datadesc}
\begin{datadesc}{EMSGSIZE} Message too long \end{datadesc}
\begin{datadesc}{EPROTOTYPE} Protocol wrong type for socket \end{datadesc}
\begin{datadesc}{ENOPROTOOPT} Protocol not available \end{datadesc}
\begin{datadesc}{EPROTONOSUPPORT} Protocol not supported \end{datadesc}
\begin{datadesc}{ESOCKTNOSUPPORT} Socket type not supported \end{datadesc}
\begin{datadesc}{EOPNOTSUPP} Operation not supported on transport endpoint \end{datadesc}
\begin{datadesc}{EPFNOSUPPORT} Protocol family not supported \end{datadesc}
\begin{datadesc}{EAFNOSUPPORT} Address family not supported by protocol \end{datadesc}
\begin{datadesc}{EADDRINUSE} Address already in use \end{datadesc}
\begin{datadesc}{EADDRNOTAVAIL} Cannot assign requested address \end{datadesc}
\begin{datadesc}{ENETDOWN} Network is down \end{datadesc}
\begin{datadesc}{ENETUNREACH} Network is unreachable \end{datadesc}
\begin{datadesc}{ENETRESET} Network dropped connection because of reset \end{datadesc}
\begin{datadesc}{ECONNABORTED} Software caused connection abort \end{datadesc}
\begin{datadesc}{ECONNRESET} Connection reset by peer \end{datadesc}
\begin{datadesc}{ENOBUFS} No buffer space available \end{datadesc}
\begin{datadesc}{EISCONN} Transport endpoint is already connected \end{datadesc}
\begin{datadesc}{ENOTCONN} Transport endpoint is not connected \end{datadesc}
\begin{datadesc}{ESHUTDOWN} Cannot send after transport endpoint shutdown \end{datadesc}
\begin{datadesc}{ETOOMANYREFS} Too many references: cannot splice \end{datadesc}
\begin{datadesc}{ETIMEDOUT} Connection timed out \end{datadesc}
\begin{datadesc}{ECONNREFUSED} Connection refused \end{datadesc}
\begin{datadesc}{EHOSTDOWN} Host is down \end{datadesc}
\begin{datadesc}{EHOSTUNREACH} No route to host \end{datadesc}
\begin{datadesc}{EALREADY} Operation already in progress \end{datadesc}
\begin{datadesc}{EINPROGRESS} Operation now in progress \end{datadesc}
\begin{datadesc}{ESTALE} Stale NFS file handle \end{datadesc}
\begin{datadesc}{EUCLEAN} Structure needs cleaning \end{datadesc}
\begin{datadesc}{ENOTNAM} Not a XENIX named type file \end{datadesc}
\begin{datadesc}{ENAVAIL} No XENIX semaphores available \end{datadesc}
\begin{datadesc}{EISNAM} Is a named type file \end{datadesc}
\begin{datadesc}{EREMOTEIO} Remote I/O error \end{datadesc}
\begin{datadesc}{EDQUOT} Quota exceeded \end{datadesc}

272
Doc/libexcs.tex
View File

@ -1,272 +0,0 @@
\section{Built-in Exceptions}
\label{module-exceptions}
\stmodindex{exceptions}
Exceptions can be class objects or string objects. While
traditionally, most exceptions have been string objects, in Python
1.5, all standard exceptions have been converted to class objects,
and users are encouraged to the the same. The source code for those
exceptions is present in the standard library module
\code{exceptions}; this module never needs to be imported explicitly.
For backward compatibility, when Python is invoked with the \code{-X}
option, the standard exceptions are strings. This may be needed to
run some code that breaks because of the different semantics of class
based exceptions. The \code{-X} option will become obsolete in future
Python versions, so the recommended solution is to fix the code.
Two distinct string objects with the same value are considered different
exceptions. This is done to force programmers to use exception names
rather than their string value when specifying exception handlers.
The string value of all built-in exceptions is their name, but this is
not a requirement for user-defined exceptions or exceptions defined by
library modules.
For class exceptions, in a \code{try} statement with an \code{except}
clause that mentions a particular class, that clause also handles
any exception classes derived from that class (but not exception
classes from which \emph{it} is derived). Two exception classes
that are not related via subclassing are never equivalent, even if
they have the same name.
\stindex{try}
\stindex{except}
The built-in exceptions listed below can be generated by the
interpreter or built-in functions. Except where mentioned, they have
an ``associated value'' indicating the detailed cause of the error.
This may be a string or a tuple containing several items of
information (e.g., an error code and a string explaining the code).
The associated value is the second argument to the \code{raise}
statement. For string exceptions, the associated value itself will be
stored in the variable named as the second argument of the
\code{except} clause (if any). For class exceptions derived from
the root class \code{Exception}, that variable receives the exception
instance, and the associated value is present as the exception
instance's \code{args} attribute; this is a tuple even if the second
argument to \code{raise} was not (then it is a singleton tuple).
\stindex{raise}
User code can raise built-in exceptions. This can be used to test an
exception handler or to report an error condition ``just like'' the
situation in which the interpreter raises the same exception; but
beware that there is nothing to prevent user code from raising an
inappropriate error.
\setindexsubitem{(built-in exception base class)}
The following exceptions are only used as base classes for other
exceptions. When string-based standard exceptions are used, they
are tuples containing the directly derived classes.
\begin{excdesc}{Exception}
The root class for exceptions. All built-in exceptions are derived
from this class. All user-defined exceptions should also be derived
from this class, but this is not (yet) enforced. The \code{str()}
function, when applied to an instance of this class (or most derived
classes) returns the string value of the argument or arguments, or an
empty string if no arguments were given to the constructor. When used
as a sequence, this accesses the arguments given to the constructor
(handy for backward compatibility with old code).
\end{excdesc}
\begin{excdesc}{StandardError}
The base class for built-in exceptions. All built-in exceptions are
derived from this class, which is itself derived from the root class
\code{Exception}.
\end{excdesc}
\begin{excdesc}{ArithmeticError}
The base class for those built-in exceptions that are raised for
various arithmetic errors: \code{OverflowError},
\code{ZeroDivisionError}, \code{FloatingPointError}.
\end{excdesc}
\begin{excdesc}{LookupError}
The base class for thise exceptions that are raised when a key or
index used on a mapping or sequence is invalid: \code{IndexError},
\code{KeyError}.
\end{excdesc}
\setindexsubitem{(built-in exception)}
The following exceptions are the exceptions that are actually raised.
They are class objects, except when the \code{-X} option is used to
revert back to string-based standard exceptions.
\begin{excdesc}{AssertionError}
Raised when an \code{assert} statement fails.
\stindex{assert}
\end{excdesc}
\begin{excdesc}{AttributeError}
% xref to attribute reference?
Raised when an attribute reference or assignment fails. (When an
object does not support attribute references or attribute assignments
at all, \code{TypeError} is raised.)
\end{excdesc}
\begin{excdesc}{EOFError}
% XXXJH xrefs here
Raised when one of the built-in functions (\code{input()} or
\code{raw_input()}) hits an end-of-file condition (\EOF{}) without
reading any data.
% XXXJH xrefs here
(N.B.: the \code{read()} and \code{readline()} methods of file
objects return an empty string when they hit \EOF{}.) No associated value.
\end{excdesc}
\begin{excdesc}{FloatingPointError}
Raised when a floating point operation fails. This exception is
always defined, but can only be raised when Python is configured with
the \code{--with-fpectl} option, or the \code{WANT_SIGFPE_HANDLER}
symbol is defined in the \file{config.h} file.
\end{excdesc}
\begin{excdesc}{IOError}
% XXXJH xrefs here
Raised when an I/O operation (such as a \code{print} statement, the
built-in \code{open()} function or a method of a file object) fails
for an I/O-related reason, e.g., ``file not found'' or ``disk full''.
When class exceptions are used, and this exception is instantiated as
\code{IOError(errno, strerror)}, the instance has two additional
attributes \code{errno} and \code{strerror} set to the error code and
the error message, respectively. These attributes default to
\code{None}.
\end{excdesc}
\begin{excdesc}{ImportError}
% XXXJH xref to import statement?
Raised when an \code{import} statement fails to find the module
definition or when a \code{from {\rm \ldots} import} fails to find a
name that is to be imported.
\end{excdesc}
\begin{excdesc}{IndexError}
% XXXJH xref to sequences
Raised when a sequence subscript is out of range. (Slice indices are
silently truncated to fall in the allowed range; if an index is not a
plain integer, \code{TypeError} is raised.)
\end{excdesc}
\begin{excdesc}{KeyError}
% XXXJH xref to mapping objects?
Raised when a mapping (dictionary) key is not found in the set of
existing keys.
\end{excdesc}
\begin{excdesc}{KeyboardInterrupt}
Raised when the user hits the interrupt key (normally
\kbd{Control-C} or \kbd{DEL}). During execution, a check for
interrupts is made regularly.
% XXXJH xrefs here
Interrupts typed when a built-in function \function{input()} or
\function{raw_input()}) is waiting for input also raise this
exception. This exception has no associated value.
\end{excdesc}
\begin{excdesc}{MemoryError}
Raised when an operation runs out of memory but the situation may
still be rescued (by deleting some objects). The associated value is
a string indicating what kind of (internal) operation ran out of memory.
Note that because of the underlying memory management architecture
(\C{}'s \code{malloc()} function), the interpreter may not always be able
to completely recover from this situation; it nevertheless raises an
exception so that a stack traceback can be printed, in case a run-away
program was the cause.
\end{excdesc}
\begin{excdesc}{NameError}
Raised when a local or global name is not found. This applies only
to unqualified names. The associated value is the name that could
not be found.
\end{excdesc}
\begin{excdesc}{OverflowError}
% XXXJH reference to long's and/or int's?
Raised when the result of an arithmetic operation is too large to be
represented. This cannot occur for long integers (which would rather
raise \code{MemoryError} than give up). Because of the lack of
standardization of floating point exception handling in \C{}, most
floating point operations also aren't checked. For plain integers,
all operations that can overflow are checked except left shift, where
typical applications prefer to drop bits than raise an exception.
\end{excdesc}
\begin{excdesc}{RuntimeError}
Raised when an error is detected that doesn't fall in any of the
other categories. The associated value is a string indicating what
precisely went wrong. (This exception is mostly a relic from a
previous version of the interpreter; it is not used very much any
more.)
\end{excdesc}
\begin{excdesc}{SyntaxError}
% XXXJH xref to these functions?
Raised when the parser encounters a syntax error. This may occur in
an \code{import} statement, in an \code{exec} statement, in a call
to the built-in function \code{eval()} or \code{input()}, or
when reading the initial script or standard input (also
interactively).
When class exceptions are used, instances of this class have
atttributes \code{filename}, \code{lineno}, \code{offset} and
\code{text} for easier access to the details; for string exceptions,
the associated value is usually a tuple of the form
\code{(message, (filename, lineno, offset, text))}.
For class exceptions, \code{str()} returns only the message.
\end{excdesc}
\begin{excdesc}{SystemError}
Raised when the interpreter finds an internal error, but the
situation does not look so serious to cause it to abandon all hope.
The associated value is a string indicating what went wrong (in
low-level terms).
You should report this to the author or maintainer of your Python
interpreter. Be sure to report the version string of the Python
interpreter (\code{sys.version}; it is also printed at the start of an
interactive Python session), the exact error message (the exception's
associated value) and if possible the source of the program that
triggered the error.
\end{excdesc}
\begin{excdesc}{SystemExit}
% XXXJH xref to module sys?
This exception is raised by the \code{sys.exit()} function. When it
is not handled, the Python interpreter exits; no stack traceback is
printed. If the associated value is a plain integer, it specifies the
system exit status (passed to \C{}'s \code{exit()} function); if it is
\code{None}, the exit status is zero; if it has another type (such as
a string), the object's value is printed and the exit status is one.
When class exceptions are used, the instance has an attribute
\code{code} which is set to the proposed exit status or error message
(defaulting to \code{None}).
A call to \code{sys.exit()} is translated into an exception so that
clean-up handlers (\code{finally} clauses of \code{try} statements)
can be executed, and so that a debugger can execute a script without
running the risk of losing control. The \code{os._exit()} function
can be used if it is absolutely positively necessary to exit
immediately (e.g., after a \code{fork()} in the child process).
\end{excdesc}
\begin{excdesc}{TypeError}
Raised when a built-in operation or function is applied to an object
of inappropriate type. The associated value is a string giving
details about the type mismatch.
\end{excdesc}
\begin{excdesc}{ValueError}
Raised when a built-in operation or function receives an argument
that has the right type but an inappropriate value, and the
situation is not described by a more precise exception such as
\code{IndexError}.
\end{excdesc}
\begin{excdesc}{ZeroDivisionError}
Raised when the second argument of a division or modulo operation is
zero. The associated value is a string indicating the type of the
operands and the operation.
\end{excdesc}

75
Doc/libfcntl.tex
View File

@ -1,75 +0,0 @@
% Manual text by Jaap Vermeulen
\section{Built-in Module \module{fcntl}}
\label{module-fcntl}
\bimodindex{fcntl}
\indexii{UNIX@\UNIX{}}{file control}
\indexii{UNIX@\UNIX{}}{I/O control}
This module performs file control and I/O control on file descriptors.
It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()}
\UNIX{} routines. File descriptors can be obtained with the
\method{fileno()} method of a file or socket object.
The module defines the following functions:
\begin{funcdesc}{fcntl}{fd, op\optional{, arg}}
Perform the requested operation on file descriptor \var{fd}.
The operation is defined by \var{op} and is operating system
dependent. Typically these codes can be retrieved from the library
module \module{FCNTL}\refstmodindex{FCNTL}. The argument \var{arg}
is optional, and defaults to the integer value \code{0}. When
present, it can either be an integer value, or a string. With
the argument missing or an integer value, the return value of this
function is the integer return value of the \C{} \cfunction{fcntl()}
call. When the argument is a string it represents a binary
structure, e.g.\ created by \function{struct.pack()}. The binary
data is copied to a buffer whose address is passed to the \C{}
\cfunction{fcntl()} call. The return value after a successful call
is the contents of the buffer, converted to a string object. In
case the \cfunction{fcntl()} fails, an \exception{IOError} is
raised.
\end{funcdesc}
\begin{funcdesc}{ioctl}{fd, op, arg}
This function is identical to the \function{fcntl()} function, except
that the operations are typically defined in the library module
\module{IOCTL}.
\end{funcdesc}
\begin{funcdesc}{flock}{fd, op}
Perform the lock operation \var{op} on file descriptor \var{fd}.
See the \UNIX{} manual \manpage{flock}{3} for details. (On some
systems, this function is emulated using \cfunction{fcntl()}.)
\end{funcdesc}
\begin{funcdesc}{lockf}{fd, code, \optional{len, \optional{start, \optional{whence}}}}
This is a wrapper around the \constant{FCNTL.F_SETLK} and
\constant{FCNTL.F_SETLKW} \function{fcntl()} calls. See the \UNIX{}
manual for details.
\end{funcdesc}
If the library modules \module{FCNTL}\refstmodindex{FCNTL} or
\module{IOCTL}\refstmodindex{IOCTL} are missing, you can find the
opcodes in the \C{} include files \code{<sys/fcntl.h>} and
\code{<sys/ioctl.h>}. You can create the modules yourself with the
\program{h2py} script, found in the \file{Tools/scripts/} directory.
Examples (all on a SVR4 compliant system):
\begin{verbatim}
import struct, FCNTL
file = open(...)
rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1)
lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
\end{verbatim}
Note that in the first example the return value variable \code{rv} will
hold an integer value; in the second example it will hold a string
value. The structure lay-out for the \var{lockdata} variable is
system dependent --- therefore using the \function{flock()} call may be
better.

124
Doc/libfileinput.tex
View File

@ -1,124 +0,0 @@
% Documentation heavily adapted from module docstring.
\section{Standard Module \module{fileinput}}
\stmodindex{fileinput}
\label{module-fileinput}
This module implements a helper class and functions to quickly write a
loop over standard input or a list of files.
The typical use is:
\begin{verbatim}
import fileinput
for line in fileinput.input():
process(line)
\end{verbatim}
This iterates over the lines of all files listed in
\code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is
empty. If a filename is \code{'-'}, it is also replaced by
\code{sys.stdin}. To specify an alternative list of filenames, pass
it as the first argument to \function{input()}. A single file name is
also allowed.
All files are opened in text mode. If an I/O error occurs during
opening or reading a file, \exception{IOError} is raised.
If \code{sys.stdin} is used more than once, the second and further use
will return no lines, except perhaps for interactive use, or if it has
been explicitly reset (e.g. using \code{sys.stdin.seek(0)}).
Empty files are opened and immediately closed; the only time their
presence in the list of filenames is noticeable at all is when the
last file opened is empty.
It is possible that the last line of a file does not end in a newline
character; lines are returned including the trailing newline when it
is present.
The following function is the primary interface of this module:
\begin{funcdesc}{input}{\optional{files\optional{,
inplace\optional{, backup}}}}
Create an instance of the \class{FileInput} class. The instance
will be used as global state for the functions of this module, and
is also returned to use during iteration.
\end{funcdesc}
The following functions use the global state created by
\function{input()}; if there is no active state,
\exception{RuntimeError} is raised.
\begin{funcdesc}{filename}{}
Return the name of the file currently being read. Before the first
line has been read, returns \code{None}.
\end{funcdesc}
\begin{funcdesc}{lineno}{}
Return the cumulative line number of the line that has just been
read. Before the first line has been read, returns \code{0}. After
the last line of the last file has been read, returns the line
number of that line.
\end{funcdesc}
\begin{funcdesc}{filelineno}{}
Return the line number in the current file. Before the first line
has been read, returns \code{0}. After the last line of the last
file has been read, returns the line number of that line within the
file.
\end{funcdesc}
\begin{funcdesc}{isfirstline}{}
Return true iff the line just read is the first line of its file.
\end{funcdesc}
\begin{funcdesc}{isstdin}{}
Returns true iff the last line was read from \code{sys.stdin}.
\end{funcdesc}
\begin{funcdesc}{nextfile}{}
Close the current file so that the next iteration will read the
first line from the next file (if any); lines not read from the file
will not count towards the cumulative line count. The filename is
not changed until after the first line of the next file has been
read. Before the first line has been read, this function has no
effect; it cannot be used to skip the first file. After the last
line of the last file has been read, this function has no effect.
\end{funcdesc}
\begin{funcdesc}{close}{}
Close the sequence.
\end{funcdesc}
The class which implements the sequence behavior provided by the
module is available for subclassing as well:
\begin{classdesc}{FileInput}{\optional{files\optional{,
inplace\optional{, backup}}}}
Class \class{FileInput} is the implementation; its methods
\method{filename()}, \method{lineno()}, \method{fileline()},
\method{isfirstline()}, \method{isstdin()}, \method{nextfile()} and
\method{close()} correspond to the functions of the same name in the
module. In addition it has a \method{readline()} method which
returns the next input line, and a \method{__getitem__()} method
which implements the sequence behavior. The sequence must be
accessed in strictly sequential order; random access and
\method{readline()} cannot be mixed.
\end{classdesc}
\strong{Optional in-place filtering:} if the keyword argument
\code{\var{inplace}=1} is passed to \function{input()} or to the
\class{FileInput} constructor, the file is moved to a backup file and
standard output is directed to the input file.
This makes it possible to write a filter that rewrites its input file
in place. If the keyword argument \code{\var{backup}='.<some
extension>'} is also given, it specifies the extension for the backup
file, and the backup file remains around; by default, the extension is
\code{'.bak'} and it is deleted when the output file is closed. In-place
filtering is disabled when standard input is read.
\strong{Caveat:} The current implementation does not work for MS-DOS
8+3 filesystems.

491
Doc/libfl.tex
View File

@ -1,491 +0,0 @@
\section{Built-in Module \module{fl}}
\label{module-fl}
\bimodindex{fl}
This module provides an interface to the FORMS Library\index{FORMS
Library} by Mark Overmars\index{Overmars, Mark}. The source for the
library can be retrieved by anonymous ftp from host
\samp{ftp.cs.ruu.nl}, directory \file{SGI/FORMS}. It was last tested
with version 2.0b.
Most functions are literal translations of their \C{} equivalents,
dropping the initial \samp{fl_} from their name. Constants used by
the library are defined in module \module{FL} described below.
The creation of objects is a little different in Python than in C:
instead of the `current form' maintained by the library to which new
FORMS objects are added, all functions that add a FORMS object to a
form are methods of the Python object representing the form.
Consequently, there are no Python equivalents for the C functions
\cfunction{fl_addto_form()} and \cfunction{fl_end_form()}, and the
equivalent of \cfunction{fl_bgn_form()} is called
\function{fl.make_form()}.
Watch out for the somewhat confusing terminology: FORMS uses the word
\dfn{object} for the buttons, sliders etc. that you can place in a form.
In Python, `object' means any value. The Python interface to FORMS
introduces two new Python object types: form objects (representing an
entire form) and FORMS objects (representing one button, slider etc.).
Hopefully this isn't too confusing.
There are no `free objects' in the Python interface to FORMS, nor is
there an easy way to add object classes written in Python. The FORMS
interface to GL event handling is available, though, so you can mix
FORMS with pure GL windows.
\strong{Please note:} importing \module{fl} implies a call to the GL
function \cfunction{foreground()} and to the FORMS routine
\cfunction{fl_init()}.
\subsection{Functions Defined in Module \module{fl}}
\nodename{FL Functions}
Module \module{fl} defines the following functions. For more
information about what they do, see the description of the equivalent
\C{} function in the FORMS documentation:
\begin{funcdesc}{make_form}{type, width, height}
Create a form with given type, width and height. This returns a
\dfn{form} object, whose methods are described below.
\end{funcdesc}
\begin{funcdesc}{do_forms}{}
The standard FORMS main loop. Returns a Python object representing
the FORMS object needing interaction, or the special value
\constant{FL.EVENT}.
\end{funcdesc}
\begin{funcdesc}{check_forms}{}
Check for FORMS events. Returns what \function{do_forms()} above
returns, or \code{None} if there is no event that immediately needs
interaction.
\end{funcdesc}
\begin{funcdesc}{set_event_call_back}{function}
Set the event callback function.
\end{funcdesc}
\begin{funcdesc}{set_graphics_mode}{rgbmode, doublebuffering}
Set the graphics modes.
\end{funcdesc}
\begin{funcdesc}{get_rgbmode}{}
Return the current rgb mode. This is the value of the \C{} global
variable \cdata{fl_rgbmode}.
\end{funcdesc}
\begin{funcdesc}{show_message}{str1, str2, str3}
Show a dialog box with a three-line message and an OK button.
\end{funcdesc}
\begin{funcdesc}{show_question}{str1, str2, str3}
Show a dialog box with a three-line message and YES and NO buttons.
It returns \code{1} if the user pressed YES, \code{0} if NO.
\end{funcdesc}
\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{,
but2\optional{, but3}}}
Show a dialog box with a three-line message and up to three buttons.
It returns the number of the button clicked by the user
(\code{1}, \code{2} or \code{3}).
\end{funcdesc}
\begin{funcdesc}{show_input}{prompt, default}
Show a dialog box with a one-line prompt message and text field in
which the user can enter a string. The second argument is the default
input string. It returns the string value as edited by the user.
\end{funcdesc}
\begin{funcdesc}{show_file_selector}{message, directory, pattern, default}
Show a dialog box in which the user can select a file. It returns
the absolute filename selected by the user, or \code{None} if the user
presses Cancel.
\end{funcdesc}
\begin{funcdesc}{get_directory}{}
\funcline{get_pattern}{}
\funcline{get_filename}{}
These functions return the directory, pattern and filename (the tail
part only) selected by the user in the last
\function{show_file_selector()} call.
\end{funcdesc}
\begin{funcdesc}{qdevice}{dev}
\funcline{unqdevice}{dev}
\funcline{isqueued}{dev}
\funcline{qtest}{}
\funcline{qread}{}
%\funcline{blkqread}{?}
\funcline{qreset}{}
\funcline{qenter}{dev, val}
\funcline{get_mouse}{}
\funcline{tie}{button, valuator1, valuator2}
These functions are the FORMS interfaces to the corresponding GL
functions. Use these if you want to handle some GL events yourself
when using \function{fl.do_events()}. When a GL event is detected that
FORMS cannot handle, \function{fl.do_forms()} returns the special value
\constant{FL.EVENT} and you should call \function{fl.qread()} to read
the event from the queue. Don't use the equivalent GL functions!
\end{funcdesc}
\begin{funcdesc}{color}{}
\funcline{mapcolor}{}
\funcline{getmcolor}{}
See the description in the FORMS documentation of
\cfunction{fl_color()}, \cfunction{fl_mapcolor()} and
\cfunction{fl_getmcolor()}.
\end{funcdesc}
\subsection{Form Objects}
\label{form-objects}
Form objects (returned by \function{make_form()} above) have the
following methods. Each method corresponds to a \C{} function whose
name is prefixed with \samp{fl_}; and whose first argument is a form
pointer; please refer to the official FORMS documentation for
descriptions.
All the \method{add_*()} methods return a Python object representing
the FORMS object. Methods of FORMS objects are described below. Most
kinds of FORMS object also have some methods specific to that kind;
these methods are listed here.
\begin{flushleft}
\begin{methoddesc}[form]{show_form}{placement, bordertype, name}
Show the form.
\end{methoddesc}
\begin{methoddesc}[form]{hide_form}{}
Hide the form.
\end{methoddesc}
\begin{methoddesc}[form]{redraw_form}{}
Redraw the form.
\end{methoddesc}
\begin{methoddesc}[form]{set_form_position}{x, y}
Set the form's position.
\end{methoddesc}
\begin{methoddesc}[form]{freeze_form}{}
Freeze the form.
\end{methoddesc}
\begin{methoddesc}[form]{unfreeze_form}{}
Unfreeze the form.
\end{methoddesc}
\begin{methoddesc}[form]{activate_form}{}
Activate the form.
\end{methoddesc}
\begin{methoddesc}[form]{deactivate_form}{}
Deactivate the form.
\end{methoddesc}
\begin{methoddesc}[form]{bgn_group}{}
Begin a new group of objects; return a group object.
\end{methoddesc}
\begin{methoddesc}[form]{end_group}{}
End the current group of objects.
\end{methoddesc}
\begin{methoddesc}[form]{find_first}{}
Find the first object in the form.
\end{methoddesc}
\begin{methoddesc}[form]{find_last}{}
Find the last object in the form.
\end{methoddesc}
%---
\begin{methoddesc}[form]{add_box}{type, x, y, w, h, name}
Add a box object to the form.
No extra methods.
\end{methoddesc}
\begin{methoddesc}[form]{add_text}{type, x, y, w, h, name}
Add a text object to the form.
No extra methods.
\end{methoddesc}
%\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
%Add a bitmap object to the form.
%\end{methoddesc}
\begin{methoddesc}[form]{add_clock}{type, x, y, w, h, name}
Add a clock object to the form. \\
Method:
\method{get_clock()}.
\end{methoddesc}
%---
\begin{methoddesc}[form]{add_button}{type, x, y, w, h, name}
Add a button object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{methoddesc}
\begin{methoddesc}[form]{add_lightbutton}{type, x, y, w, h, name}
Add a lightbutton object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{methoddesc}
\begin{methoddesc}[form]{add_roundbutton}{type, x, y, w, h, name}
Add a roundbutton object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{methoddesc}
%---
\begin{methoddesc}[form]{add_slider}{type, x, y, w, h, name}
Add a slider object to the form. \\
Methods:
\method{set_slider_value()},
\method{get_slider_value()},
\method{set_slider_bounds()},
\method{get_slider_bounds()},
\method{set_slider_return()},
\method{set_slider_size()},
\method{set_slider_precision()},
\method{set_slider_step()}.
\end{methoddesc}
\begin{methoddesc}[form]{add_valslider}{type, x, y, w, h, name}
Add a valslider object to the form. \\
Methods:
\method{set_slider_value()},
\method{get_slider_value()},
\method{set_slider_bounds()},
\method{get_slider_bounds()},
\method{set_slider_return()},
\method{set_slider_size()},
\method{set_slider_precision()},
\method{set_slider_step()}.
\end{methoddesc}
\begin{methoddesc}[form]{add_dial}{type, x, y, w, h, name}
Add a dial object to the form. \\
Methods:
\method{set_dial_value()},
\method{get_dial_value()},
\method{set_dial_bounds()},
\method{get_dial_bounds()}.
\end{methoddesc}
\begin{methoddesc}[form]{add_positioner}{type, x, y, w, h, name}
Add a positioner object to the form. \\
Methods:
\method{set_positioner_xvalue()},
\method{set_positioner_yvalue()},
\method{set_positioner_xbounds()},
\method{set_positioner_ybounds()},
\method{get_positioner_xvalue()},
\method{get_positioner_yvalue()},
\method{get_positioner_xbounds()},
\method{get_positioner_ybounds()}.
\end{methoddesc}
\begin{methoddesc}[form]{add_counter}{type, x, y, w, h, name}
Add a counter object to the form. \\
Methods:
\method{set_counter_value()},
\method{get_counter_value()},
\method{set_counter_bounds()},
\method{set_counter_step()},
\method{set_counter_precision()},
\method{set_counter_return()}.
\end{methoddesc}
%---
\begin{methoddesc}[form]{add_input}{type, x, y, w, h, name}
Add a input object to the form. \\
Methods:
\method{set_input()},
\method{get_input()},
\method{set_input_color()},
\method{set_input_return()}.
\end{methoddesc}
%---
\begin{methoddesc}[form]{add_menu}{type, x, y, w, h, name}
Add a menu object to the form. \\
Methods:
\method{set_menu()},
\method{get_menu()},
\method{addto_menu()}.
\end{methoddesc}
\begin{methoddesc}[form]{add_choice}{type, x, y, w, h, name}
Add a choice object to the form. \\
Methods:
\method{set_choice()},
\method{get_choice()},
\method{clear_choice()},
\method{addto_choice()},
\method{replace_choice()},
\method{delete_choice()},
\method{get_choice_text()},
\method{set_choice_fontsize()},
\method{set_choice_fontstyle()}.
\end{methoddesc}
\begin{methoddesc}[form]{add_browser}{type, x, y, w, h, name}
Add a browser object to the form. \\
Methods:
\method{set_browser_topline()},
\method{clear_browser()},
\method{add_browser_line()},
\method{addto_browser()},
\method{insert_browser_line()},
\method{delete_browser_line()},
\method{replace_browser_line()},
\method{get_browser_line()},
\method{load_browser()},
\method{get_browser_maxline()},
\method{select_browser_line()},
\method{deselect_browser_line()},
\method{deselect_browser()},
\method{isselected_browser_line()},
\method{get_browser()},
\method{set_browser_fontsize()},
\method{set_browser_fontstyle()},
\method{set_browser_specialkey()}.
\end{methoddesc}
%---
\begin{methoddesc}[form]{add_timer}{type, x, y, w, h, name}
Add a timer object to the form. \\
Methods:
\method{set_timer()},
\method{get_timer()}.
\end{methoddesc}
\end{flushleft}
Form objects have the following data attributes; see the FORMS
documentation:
\begin{tableiii}{l|l|l}{member}{Name}{C Type}{Meaning}
\lineiii{window}{int (read-only)}{GL window id}
\lineiii{w}{float}{form width}
\lineiii{h}{float}{form height}
\lineiii{x}{float}{form x origin}
\lineiii{y}{float}{form y origin}
\lineiii{deactivated}{int}{nonzero if form is deactivated}
\lineiii{visible}{int}{nonzero if form is visible}
\lineiii{frozen}{int}{nonzero if form is frozen}
\lineiii{doublebuf}{int}{nonzero if double buffering on}
\end{tableiii}
\subsection{FORMS Objects}
\label{forms-objects}
Besides methods specific to particular kinds of FORMS objects, all
FORMS objects also have the following methods:
\begin{methoddesc}[FORMS object]{set_call_back}{function, argument}
Set the object's callback function and argument. When the object
needs interaction, the callback function will be called with two
arguments: the object, and the callback argument. (FORMS objects
without a callback function are returned by \function{fl.do_forms()}
or \function{fl.check_forms()} when they need interaction.) Call this
method without arguments to remove the callback function.
\end{methoddesc}
\begin{methoddesc}[FORMS object]{delete_object}{}
Delete the object.
\end{methoddesc}
\begin{methoddesc}[FORMS object]{show_object}{}
Show the object.
\end{methoddesc}
\begin{methoddesc}[FORMS object]{hide_object}{}
Hide the object.
\end{methoddesc}
\begin{methoddesc}[FORMS object]{redraw_object}{}
Redraw the object.
\end{methoddesc}
\begin{methoddesc}[FORMS object]{freeze_object}{}
Freeze the object.
\end{methoddesc}
\begin{methoddesc}[FORMS object]{unfreeze_object}{}
Unfreeze the object.
\end{methoddesc}
%\begin{methoddesc}[FORMS object]{handle_object}{} XXX
%\end{methoddesc}
%\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
%\end{methoddesc}
FORMS objects have these data attributes; see the FORMS documentation:
\begin{tableiii}{l|l|l}{member}{Name}{C Type}{Meaning}
\lineiii{objclass}{int (read-only)}{object class}
\lineiii{type}{int (read-only)}{object type}
\lineiii{boxtype}{int}{box type}
\lineiii{x}{float}{x origin}
\lineiii{y}{float}{y origin}
\lineiii{w}{float}{width}
\lineiii{h}{float}{height}
\lineiii{col1}{int}{primary color}
\lineiii{col2}{int}{secondary color}
\lineiii{align}{int}{alignment}
\lineiii{lcol}{int}{label color}
\lineiii{lsize}{float}{label font size}
\lineiii{label}{string}{label string}
\lineiii{lstyle}{int}{label style}
\lineiii{pushed}{int (read-only)}{(see FORMS docs)}
\lineiii{focus}{int (read-only)}{(see FORMS docs)}
\lineiii{belowmouse}{int (read-only)}{(see FORMS docs)}
\lineiii{frozen}{int (read-only)}{(see FORMS docs)}
\lineiii{active}{int (read-only)}{(see FORMS docs)}
\lineiii{input}{int (read-only)}{(see FORMS docs)}
\lineiii{visible}{int (read-only)}{(see FORMS docs)}
\lineiii{radio}{int (read-only)}{(see FORMS docs)}
\lineiii{automatic}{int (read-only)}{(see FORMS docs)}
\end{tableiii}
\section{Standard Module \module{FL}}
\label{module-FLuppercase}
\stmodindex{FL}
This module defines symbolic constants needed to use the built-in
module \module{fl} (see above); they are equivalent to those defined in
the \C{} header file \code{<forms.h>} except that the name prefix
\samp{FL_} is omitted. Read the module source for a complete list of
the defined names. Suggested use:
\begin{verbatim}
import fl
from FL import *
\end{verbatim}
\section{Standard Module \module{flp}}
\label{module-flp}
\stmodindex{flp}
This module defines functions that can read form definitions created
by the `form designer' (\program{fdesign}) program that comes with the
FORMS library (see module \module{fl} above).
For now, see the file \file{flp.doc} in the Python library source
directory for a description.
XXX A complete description should be inserted here!

90
Doc/libfm.tex
View File

@ -1,90 +0,0 @@
\section{Built-in Module \module{fm}}
\label{module-fm}
\bimodindex{fm}
This module provides access to the IRIS \emph{Font Manager} library.
\index{Font Manager, IRIS}
\index{IRIS Font Manager}
It is available only on Silicon Graphics machines.
See also: \emph{4Sight User's Guide}, Section 1, Chapter 5: ``Using
the IRIS Font Manager.''
This is not yet a full interface to the IRIS Font Manager.
Among the unsupported features are: matrix operations; cache
operations; character operations (use string operations instead); some
details of font info; individual glyph metrics; and printer matching.
It supports the following operations:
\begin{funcdesc}{init}{}
Initialization function.
Calls \cfunction{fminit()}.
It is normally not necessary to call this function, since it is called
automatically the first time the \module{fm} module is imported.
\end{funcdesc}
\begin{funcdesc}{findfont}{fontname}
Return a font handle object.
Calls \code{fmfindfont(\var{fontname})}.
\end{funcdesc}
\begin{funcdesc}{enumerate}{}
Returns a list of available font names.
This is an interface to \cfunction{fmenumerate()}.
\end{funcdesc}
\begin{funcdesc}{prstr}{string}
Render a string using the current font (see the \function{setfont()} font
handle method below).
Calls \code{fmprstr(\var{string})}.
\end{funcdesc}
\begin{funcdesc}{setpath}{string}
Sets the font search path.
Calls \code{fmsetpath(\var{string})}.
(XXX Does not work!?!)
\end{funcdesc}
\begin{funcdesc}{fontpath}{}
Returns the current font search path.
\end{funcdesc}
Font handle objects support the following operations:
\setindexsubitem{(font handle method)}
\begin{funcdesc}{scalefont}{factor}
Returns a handle for a scaled version of this font.
Calls \code{fmscalefont(\var{fh}, \var{factor})}.
\end{funcdesc}
\begin{funcdesc}{setfont}{}
Makes this font the current font.
Note: the effect is undone silently when the font handle object is
deleted.
Calls \code{fmsetfont(\var{fh})}.
\end{funcdesc}
\begin{funcdesc}{getfontname}{}
Returns this font's name.
Calls \code{fmgetfontname(\var{fh})}.
\end{funcdesc}
\begin{funcdesc}{getcomment}{}
Returns the comment string associated with this font.
Raises an exception if there is none.
Calls \code{fmgetcomment(\var{fh})}.
\end{funcdesc}
\begin{funcdesc}{getfontinfo}{}
Returns a tuple giving some pertinent data about this font.
This is an interface to \code{fmgetfontinfo()}.
The returned tuple contains the following numbers:
\code{(}\var{printermatched}, \var{fixed_width}, \var{xorig},
\var{yorig}, \var{xsize}, \var{ysize}, \var{height},
\var{nglyphs}\code{)}.
\end{funcdesc}
\begin{funcdesc}{getstrwidth}{string}
Returns the width, in pixels, of \var{string} when drawn in this font.
Calls \code{fmgetstrwidth(\var{fh}, \var{string})}.
\end{funcdesc}

40
Doc/libfnmatch.tex
View File

@ -1,40 +0,0 @@
\section{Standard Module \module{fnmatch}}
\label{module-fnmatch}
\stmodindex{fnmatch}
This module provides support for \UNIX{} shell-style wildcards, which
are \emph{not} the same as regular expressions (which are documented
in the \module{re}\refstmodindex{re} module). The special characters
used in shell-style wildcards are:
\begin{list}{}{\leftmargin 0.5in \labelwidth 0.45in}
\item[\code{*}] matches everything
\item[\code{?}] matches any single character
\item[\code{[}\var{seq}\code{]}] matches any character in \var{seq}
\item[\code{[!}\var{seq}\code{]}] matches any character not in \var{seq}
\end{list}
Note that the filename separator (\code{'/'} on \UNIX{}) is \emph{not}
special to this module. See module \code{glob}\refstmodindex{glob}
for pathname expansion (\module{glob} uses \function{fnmatch()} to
match filename segments).
\begin{funcdesc}{fnmatch}{filename, pattern}
Test whether the \var{filename} string matches the \var{pattern}
string, returning true or false. If the operating system is
case-insensitive, then both parameters will be normalized to all
lower- or upper-case before the comparision is performed. If you
require a case-sensitive comparision regardless of whether that's
standard for your operating system, use \function{fnmatchcase()}
instead.
\end{funcdesc}
\begin{funcdesc}{fnmatchcase}{filename, pattern}
Test whether \var{filename} matches \var{pattern}, returning true or
false; the comparision is case-sensitive.
\end{funcdesc}
\begin{seealso}
\seemodule{glob}{Shell-style path expansion}
\end{seealso}

323
Doc/libformatter.tex
View File

@ -1,323 +0,0 @@
\section{Standard Module \module{formatter}}
\label{module-formatter}
\stmodindex{formatter}
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
\emph{writer} interface is required by the formatter interface.
\withsubitem{(class in htmllib)}{\ttindex{HTMLParser}}
Formatter objects transform an abstract flow of formatting events into
specific output events on writer objects. Formatters manage several
stack structures to allow various properties of a writer object to be
changed and restored; writers need not be able to handle relative
changes nor any sort of ``change back'' operation. Specific writer
properties which may be controlled via formatter objects are
horizontal alignment, font, and left margin indentations. A mechanism
is provided which supports providing arbitrary, non-exclusive style
settings to a writer as well. Additional interfaces facilitate
formatting events which are not reversible, such as paragraph
separation.
Writer objects encapsulate device interfaces. Abstract devices, such
as file formats, are supported as well as physical devices. The
provided implementations all work with abstract devices. The
interface makes available mechanisms for setting the properties which
formatter objects manage and inserting data into the output.
\subsection{The Formatter Interface}
Interfaces to create formatters are dependent on the specific
formatter class being instantiated. The interfaces described below
are the required interfaces which all formatters must support once
initialized.
One data element is defined at the module level:
\begin{datadesc}{AS_IS}
Value which can be used in the font specification passed to the
\code{push_font()} method described below, or as the new value to any
other \code{push_\var{property}()} method. Pushing the \code{AS_IS}
value allows the corresponding \code{pop_\var{property}()} method to
be called without having to track whether the property was changed.
\end{datadesc}
The following attributes are defined for formatter instance objects:
\begin{memberdesc}[formatter]{writer}
The writer instance with which the formatter interacts.
\end{memberdesc}
\begin{methoddesc}[formatter]{end_paragraph}{blanklines}
Close any open paragraphs and insert at least \var{blanklines}
before the next paragraph.
\end{methoddesc}
\begin{methoddesc}[formatter]{add_line_break}{}
Add a hard line break if one does not already exist. This does not
break the logical paragraph.
\end{methoddesc}
\begin{methoddesc}[formatter]{add_hor_rule}{*args, **kw}
Insert a horizontal rule in the output. A hard break is inserted if
there is data in the current paragraph, but the logical paragraph is
not broken. The arguments and keywords are passed on to the writer's
\method{send_line_break()} method.
\end{methoddesc}
\begin{methoddesc}[formatter]{add_flowing_data}{data}
Provide data which should be formatted with collapsed whitespaces.
Whitespace from preceeding and successive calls to
\method{add_flowing_data()} is considered as well when the whitespace
collapse is performed. The data which is passed to this method is
expected to be word-wrapped by the output device. Note that any
word-wrapping still must be performed by the writer object due to the
need to rely on device and font information.
\end{methoddesc}
\begin{methoddesc}[formatter]{add_literal_data}{data}
Provide data which should be passed to the writer unchanged.
Whitespace, including newline and tab characters, are considered legal
in the value of \var{data}.
\end{methoddesc}
\begin{methoddesc}[formatter]{add_label_data}{format, counter}
Insert a label which should be placed to the left of the current left
margin. This should be used for constructing bulleted or numbered
lists. If the \var{format} value is a string, it is interpreted as a
format specification for \var{counter}, which should be an integer.
The result of this formatting becomes the value of the label; if
\var{format} is not a string it is used as the label value directly.
The label value is passed as the only argument to the writer's
\method{send_label_data()} method. Interpretation of non-string label
values is dependent on the associated writer.
Format specifications are strings which, in combination with a counter
value, are used to compute label values. Each character in the format
string is copied to the label value, with some characters recognized
to indicate a transform on the counter value. Specifically, the
character \character{1} represents the counter value formatter as an
arabic number, the characters \character{A} and \character{a}
represent alphabetic representations of the counter value in upper and
lower case, respectively, and \character{I} and \character{i}
represent the counter value in Roman numerals, in upper and lower
case. Note that the alphabetic and roman transforms require that the
counter value be greater than zero.
\end{methoddesc}
\begin{methoddesc}[formatter]{flush_softspace}{}
Send any pending whitespace buffered from a previous call to
\method{add_flowing_data()} to the associated writer object. This
should be called before any direct manipulation of the writer object.
\end{methoddesc}
\begin{methoddesc}[formatter]{push_alignment}{align}
Push a new alignment setting onto the alignment stack. This may be
\constant{AS_IS} if no change is desired. If the alignment value is
changed from the previous setting, the writer's \method{new_alignment()}
method is called with the \var{align} value.
\end{methoddesc}
\begin{methoddesc}[formatter]{pop_alignment}{}
Restore the previous alignment.
\end{methoddesc}
\begin{methoddesc}[formatter]{push_font}{\code{(}size, italic, bold, teletype\code{)}}
Change some or all font properties of the writer object. Properties
which are not set to \constant{AS_IS} are set to the values passed in
while others are maintained at their current settings. The writer's
\method{new_font()} method is called with the fully resolved font
specification.
\end{methoddesc}
\begin{methoddesc}[formatter]{pop_font}{}
Restore the previous font.
\end{methoddesc}
\begin{methoddesc}[formatter]{push_margin}{margin}
Increase the number of left margin indentations by one, associating
the logical tag \var{margin} with the new indentation. The initial
margin level is \code{0}. Changed values of the logical tag must be
true values; false values other than \constant{AS_IS} are not
sufficient to change the margin.
\end{methoddesc}
\begin{methoddesc}[formatter]{pop_margin}{}
Restore the previous margin.
\end{methoddesc}
\begin{methoddesc}[formatter]{push_style}{*styles}
Push any number of arbitrary style specifications. All styles are
pushed onto the styles stack in order. A tuple representing the
entire stack, including \constant{AS_IS} values, is passed to the
writer's \method{new_styles()} method.
\end{methoddesc}
\begin{methoddesc}[formatter]{pop_style}{\optional{n\code{ = 1}}}
Pop the last \var{n} style specifications passed to
\method{push_style()}. A tuple representing the revised stack,
including \constant{AS_IS} values, is passed to the writer's
\method{new_styles()} method.
\end{methoddesc}
\begin{methoddesc}[formatter]{set_spacing}{spacing}
Set the spacing style for the writer.
\end{methoddesc}
\begin{methoddesc}[formatter]{assert_line_data}{\optional{flag\code{ = 1}}}
Inform the formatter that data has been added to the current paragraph
out-of-band. This should be used when the writer has been manipulated
directly. The optional \var{flag} argument can be set to false if
the writer manipulations produced a hard line break at the end of the
output.
\end{methoddesc}
\subsection{Formatter Implementations}
Two implementations of formatter objects are provided by this module.
Most applications may use one of these classes without modification or
subclassing.
\begin{classdesc}{NullFormatter}{\optional{writer}}
A formatter which does nothing. If \var{writer} is omitted, a
\class{NullWriter} instance is created. No methods of the writer are
called by \class{NullFormatter} instances. Implementations should
inherit from this class if implementing a writer interface but don't
need to inherit any implementation.
\end{classdesc}
\begin{classdesc}{AbstractFormatter}{writer}
The standard formatter. This implementation has demonstrated wide
applicability to many writers, and may be used directly in most
circumstances. It has been used to implement a full-featured
world-wide web browser.
\end{classdesc}
\subsection{The Writer Interface}
Interfaces to create writers are dependent on the specific writer
class being instantiated. The interfaces described below are the
required interfaces which all writers must support once initialized.
Note that while most applications can use the
\class{AbstractFormatter} class as a formatter, the writer must
typically be provided by the application.
\begin{methoddesc}[writer]{flush}{}
Flush any buffered output or device control events.
\end{methoddesc}
\begin{methoddesc}[writer]{new_alignment}{align}
Set the alignment style. The \var{align} value can be any object,
but by convention is a string or \code{None}, where \code{None}
indicates that the writer's ``preferred'' alignment should be used.
Conventional \var{align} values are \code{'left'}, \code{'center'},
\code{'right'}, and \code{'justify'}.
\end{methoddesc}
\begin{methoddesc}[writer]{new_font}{font}
Set the font style. The value of \var{font} will be \code{None},
indicating that the device's default font should be used, or a tuple
of the form \code{(}\var{size}, \var{italic}, \var{bold},
\var{teletype}\code{)}. Size will be a string indicating the size of
font that should be used; specific strings and their interpretation
must be defined by the application. The \var{italic}, \var{bold}, and
\var{teletype} values are boolean indicators specifying which of those
font attributes should be used.
\end{methoddesc}
\begin{methoddesc}[writer]{new_margin}{margin, level}
Set the margin level to the integer \var{level} and the logical tag
to \var{margin}. Interpretation of the logical tag is at the
writer's discretion; the only restriction on the value of the logical
tag is that it not be a false value for non-zero values of
\var{level}.
\end{methoddesc}
\begin{methoddesc}[writer]{new_spacing}{spacing}
Set the spacing style to \var{spacing}.
\end{methoddesc}
\begin{methoddesc}[writer]{new_styles}{styles}
Set additional styles. The \var{styles} value is a tuple of
arbitrary values; the value \constant{AS_IS} should be ignored. The
\var{styles} tuple may be interpreted either as a set or as a stack
depending on the requirements of the application and writer
implementation.
\end{methoddesc}
\begin{methoddesc}[writer]{send_line_break}{}
Break the current line.
\end{methoddesc}
\begin{methoddesc}[writer]{send_paragraph}{blankline}
Produce a paragraph separation of at least \var{blankline} blank
lines, or the equivelent. The \var{blankline} value will be an
integer.
\end{methoddesc}
\begin{methoddesc}[writer]{send_hor_rule}{*args, **kw}
Display a horizontal rule on the output device. The arguments to this
method are entirely application- and writer-specific, and should be
interpreted with care. The method implementation may assume that a
line break has already been issued via \method{send_line_break()}.
\end{methoddesc}
\begin{methoddesc}[writer]{send_flowing_data}{data}
Output character data which may be word-wrapped and re-flowed as
needed. Within any sequence of calls to this method, the writer may
assume that spans of multiple whitespace characters have been
collapsed to single space characters.
\end{methoddesc}
\begin{methoddesc}[writer]{send_literal_data}{data}
Output character data which has already been formatted
for display. Generally, this should be interpreted to mean that line
breaks indicated by newline characters should be preserved and no new
line breaks should be introduced. The data may contain embedded
newline and tab characters, unlike data provided to the
\method{send_formatted_data()} interface.
\end{methoddesc}
\begin{methoddesc}[writer]{send_label_data}{data}
Set \var{data} to the left of the current left margin, if possible.
The value of \var{data} is not restricted; treatment of non-string
values is entirely application- and writer-dependent. This method
will only be called at the beginning of a line.
\end{methoddesc}
\subsection{Writer Implementations}
Three implementations of the writer object interface are provided as
examples by this module. Most applications will need to derive new
writer classes from the \class{NullWriter} class.
\begin{classdesc}{NullWriter}{}
A writer which only provides the interface definition; no actions are
taken on any methods. This should be the base class for all writers
which do not need to inherit any implementation methods.
\end{classdesc}
\begin{classdesc}{AbstractWriter}{}
A writer which can be used in debugging formatters, but not much
else. Each method simply announces itself by printing its name and
arguments on standard output.
\end{classdesc}
\begin{classdesc}{DumbWriter}{\optional{file\optional{, maxcol\code{ = 72}}}}
Simple writer class which writes output on the file object passed in
as \var{file} or, if \var{file} is omitted, on standard output. The
output is simply word-wrapped to the number of columns specified by
\var{maxcol}. This class is suitable for reflowing a sequence of
paragraphs.
\end{classdesc}

294
Doc/libframework.tex
View File

@ -1,294 +0,0 @@
\section{Standard Module \module{FrameWork}}
\stmodindex{FrameWork}
\label{module-FrameWork}
The \module{FrameWork} module contains classes that together provide a
framework for an interactive Macintosh application. The programmer
builds an application by creating subclasses that override various
methods of the bases classes, thereby implementing the functionality
wanted. Overriding functionality can often be done on various
different levels, i.e. to handle clicks in a single dialog window in a
non-standard way it is not necessary to override the complete event
handling.
The \module{FrameWork} is still very much work-in-progress, and the
documentation describes only the most important functionality, and not
in the most logical manner at that. Examine the source or the examples
for more details.
The \module{FrameWork} module defines the following functions:
\begin{funcdesc}{Application}{}
An object representing the complete application. See below for a
description of the methods. The default \method{__init__()} routine
creates an empty window dictionary and a menu bar with an apple menu.
\end{funcdesc}
\begin{funcdesc}{MenuBar}{}
An object representing the menubar. This object is usually not created
by the user.
\end{funcdesc}
\begin{funcdesc}{Menu}{bar, title\optional{, after}}
An object representing a menu. Upon creation you pass the
\code{MenuBar} the menu appears in, the \var{title} string and a
position (1-based) \var{after} where the menu should appear (default:
at the end).
\end{funcdesc}
\begin{funcdesc}{MenuItem}{menu, title\optional{, shortcut, callback}}
Create a menu item object. The arguments are the menu to crate the
item it, the item title string and optionally the keyboard shortcut
and a callback routine. The callback is called with the arguments
menu-id, item number within menu (1-based), current front window and
the event record.
In stead of a callable object the callback can also be a string. In
this case menu selection causes the lookup of a method in the topmost
window and the application. The method name is the callback string
with \code{'domenu_'} prepended.
Calling the \code{MenuBar} \code{fixmenudimstate} method sets the
correct dimming for all menu items based on the current front window.
\end{funcdesc}
\begin{funcdesc}{Separator}{menu}
Add a separator to the end of a menu.
\end{funcdesc}
\begin{funcdesc}{SubMenu}{menu, label}
Create a submenu named \var{label} under menu \var{menu}. The menu
object is returned.
\end{funcdesc}
\begin{funcdesc}{Window}{parent}
Creates a (modeless) window. \var{Parent} is the application object to
which the window belongs. The window is not displayed until later.
\end{funcdesc}
\begin{funcdesc}{DialogWindow}{parent}
Creates a modeless dialog window.
\end{funcdesc}
\begin{funcdesc}{windowbounds}{width, height}
Return a \code{(left, top, right, bottom)} tuple suitable for creation
of a window of given width and height. The window will be staggered
with respect to previous windows, and an attempt is made to keep the
whole window on-screen. The window will however always be exact the
size given, so parts may be offscreen.
\end{funcdesc}
\begin{funcdesc}{setwatchcursor}{}
Set the mouse cursor to a watch.
\end{funcdesc}
\begin{funcdesc}{setarrowcursor}{}
Set the mouse cursor to an arrow.
\end{funcdesc}
\subsection{Application Objects}
\label{application-objects}
Application objects have the following methods, among others:
\setindexsubitem{(Application method)}
\begin{funcdesc}{makeusermenus}{}
Override this method if you need menus in your application. Append the
menus to the attribute \member{menubar}.
\end{funcdesc}
\begin{funcdesc}{getabouttext}{}
Override this method to return a text string describing your
application. Alternatively, override the \method{do_about()} method
for more elaborate ``about'' messages.
\end{funcdesc}
\begin{funcdesc}{mainloop}{\optional{mask\optional{, wait}}}
This routine is the main event loop, call it to set your application
rolling. \var{Mask} is the mask of events you want to handle,
\var{wait} is the number of ticks you want to leave to other
concurrent application (default 0, which is probably not a good
idea). While raising \code{self} to exit the mainloop is still
supported it is not recommended, call \code{self._quit} instead.
The event loop is split into many small parts, each of which can be
overridden. The default methods take care of dispatching events to
windows and dialogs, handling drags and resizes, Apple Events, events
for non-FrameWork windows, etc.
In general, all event handlers should return \code{1} if the event is fully
handled and \code{0} otherwise (because the front window was not a FrameWork
window, for instance). This is needed so that update events and such
can be passed on to other windows like the Sioux console window.
Calling \function{MacOS.HandleEvent()} is not allowed within
\var{our_dispatch} or its callees, since this may result in an
infinite loop if the code is called through the Python inner-loop
event handler.
\end{funcdesc}
\begin{funcdesc}{asyncevents}{onoff}
Call this method with a nonzero parameter to enable
asynchronous event handling. This will tell the inner interpreter loop
to call the application event handler \var{async_dispatch} whenever events
are available. This will cause FrameWork window updates and the user
interface to remain working during long computations, but will slow the
interpreter down and may cause surprising results in non-reentrant code
(such as FrameWork itself). By default \var{async_dispatch} will immedeately
call \var{our_dispatch} but you may override this to handle only certain
events asynchronously. Events you do not handle will be passed to Sioux
and such.
The old on/off value is returned.
\end{funcdesc}
\begin{funcdesc}{_quit}{}
Terminate the running \method{mainloop()} call at the next convenient
moment.
\end{funcdesc}
\begin{funcdesc}{do_char}{c, event}
The user typed character \var{c}. The complete details of the event
can be found in the \var{event} structure. This method can also be
provided in a \code{Window} object, which overrides the
application-wide handler if the window is frontmost.
\end{funcdesc}
\begin{funcdesc}{do_dialogevent}{event}
Called early in the event loop to handle modeless dialog events. The
default method simply dispatches the event to the relevant dialog (not
through the the \code{DialogWindow} object involved). Override if you
need special handling of dialog events (keyboard shortcuts, etc).
\end{funcdesc}
\begin{funcdesc}{idle}{event}
Called by the main event loop when no events are available. The
null-event is passed (so you can look at mouse position, etc).
\end{funcdesc}
\subsection{Window Objects}
\label{window-objects}
Window objects have the following methods, among others:
\setindexsubitem{(Window method)}
\begin{funcdesc}{open}{}
Override this method to open a window. Store the MacOS window-id in
\code{self.wid} and call \code{self.do_postopen} to register the
window with the parent application.
\end{funcdesc}
\begin{funcdesc}{close}{}
Override this method to do any special processing on window
close. Call \code{self.do_postclose} to cleanup the parent state.
\end{funcdesc}
\begin{funcdesc}{do_postresize}{width, height, macoswindowid}
Called after the window is resized. Override if more needs to be done
than calling \code{InvalRect}.
\end{funcdesc}
\begin{funcdesc}{do_contentclick}{local, modifiers, event}
The user clicked in the content part of a window. The arguments are
the coordinates (window-relative), the key modifiers and the raw
event.
\end{funcdesc}
\begin{funcdesc}{do_update}{macoswindowid, event}
An update event for the window was received. Redraw the window.
\end{funcdesc}
\begin{funcdesc}{do_activate}{activate, event}
The window was activated (\code{activate==1}) or deactivated
(\code{activate==0}). Handle things like focus highlighting, etc.
\end{funcdesc}
\subsection{ControlsWindow Object}
\label{controlswindow-object}
ControlsWindow objects have the following methods besides those of
\code{Window} objects:
\setindexsubitem{(ControlsWindow method)}
\begin{funcdesc}{do_controlhit}{window, control, pcode, event}
Part \code{pcode} of control \code{control} was hit by the
user. Tracking and such has already been taken care of.
\end{funcdesc}
\subsection{ScrolledWindow Object}
\label{scrolledwindow-object}
ScrolledWindow objects are ControlsWindow objects with the following
extra methods:
\setindexsubitem{(ScrolledWindow method)}
\begin{funcdesc}{scrollbars}{\optional{wantx\optional{, wanty}}}
Create (or destroy) horizontal and vertical scrollbars. The arguments
specify which you want (default: both). The scrollbars always have
minimum \code{0} and maximum \code{32767}.
\end{funcdesc}
\begin{funcdesc}{getscrollbarvalues}{}
You must supply this method. It should return a tuple \code{(\var{x},
\var{y})} giving the current position of the scrollbars (between
\code{0} and \code{32767}). You can return \code{None} for either to
indicate the whole document is visible in that direction.
\end{funcdesc}
\begin{funcdesc}{updatescrollbars}{}
Call this method when the document has changed. It will call
\method{getscrollbarvalues()} and update the scrollbars.
\end{funcdesc}
\begin{funcdesc}{scrollbar_callback}{which, what, value}
Supplied by you and called after user interaction. \var{which} will
be \code{'x'} or \code{'y'}, \var{what} will be \code{'-'},
\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For
\code{'set'}, \var{value} will contain the new scrollbar position.
\end{funcdesc}
\begin{funcdesc}{scalebarvalues}{absmin, absmax, curmin, curmax}
Auxiliary method to help you calculate values to return from
\method{getscrollbarvalues()}. You pass document minimum and maximum value
and topmost (leftmost) and bottommost (rightmost) visible values and
it returns the correct number or \code{None}.
\end{funcdesc}
\begin{funcdesc}{do_activate}{onoff, event}
Takes care of dimming/highlighting scrollbars when a window becomes
frontmost vv. If you override this method call this one at the end of
your method.
\end{funcdesc}
\begin{funcdesc}{do_postresize}{width, height, window}
Moves scrollbars to the correct position. Call this method initially
if you override it.
\end{funcdesc}
\begin{funcdesc}{do_controlhit}{window, control, pcode, event}
Handles scrollbar interaction. If you override it call this method
first, a nonzero return value indicates the hit was in the scrollbars
and has been handled.
\end{funcdesc}
\subsection{DialogWindow Objects}
\label{dialogwindow-objects}
DialogWindow objects have the following methods besides those of
\code{Window} objects:
\setindexsubitem{(DialogWindow method)}
\begin{funcdesc}{open}{resid}
Create the dialog window, from the DLOG resource with id
\var{resid}. The dialog object is stored in \code{self.wid}.
\end{funcdesc}
\begin{funcdesc}{do_itemhit}{item, event}
Item number \var{item} was hit. You are responsible for redrawing
toggle buttons, etc.
\end{funcdesc}

240
Doc/libftplib.tex
View File

@ -1,240 +0,0 @@
\section{Standard Module \module{ftplib}}
\label{module-ftplib}
\stmodindex{ftplib}
\indexii{FTP}{protocol}
This module defines the class \class{FTP} and a few related items.
The \class{FTP} class implements the client side of the FTP protocol.
You can use this to write Python programs that perform a variety of
automated FTP jobs, such as mirroring other ftp servers. It is also
used by the module \module{urllib} to handle URLs that use FTP. For
more information on FTP (File Transfer Protocol), see Internet
\rfc{959}.
Here's a sample session using the \module{ftplib} module:
\begin{verbatim}
>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
>>> ftp.login() # user anonymous, passwd user@hostname
>>> ftp.retrlines('LIST') # list directory contents
total 24418
drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 .
dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
-rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX
.
.
.
>>> ftp.quit()
\end{verbatim}
The module defines the following items:
\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{,
passwd\optional{, acct}}}}}
Return a new instance of the \class{FTP} class. When
\var{host} is given, the method call \code{connect(\var{host})} is
made. When \var{user} is given, additionally the method call
\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where
\var{passwd} and \var{acct} default to the empty string when not given).
\end{classdesc}
\begin{datadesc}{all_errors}
The set of all exceptions (as a tuple) that methods of \class{FTP}
instances may raise as a result of problems with the FTP connection
(as opposed to programming errors made by the caller). This set
includes the four exceptions listed below as well as
\exception{socket.error} and \exception{IOError}.
\end{datadesc}
\begin{excdesc}{error_reply}
Exception raised when an unexpected reply is received from the server.
\end{excdesc}
\begin{excdesc}{error_temp}
Exception raised when an error code in the range 400--499 is received.
\end{excdesc}
\begin{excdesc}{error_perm}
Exception raised when an error code in the range 500--599 is received.
\end{excdesc}
\begin{excdesc}{error_proto}
Exception raised when a reply is received from the server that does
not begin with a digit in the range 1--5.
\end{excdesc}
\subsection{FTP Objects}
\label{ftp-objects}
\class{FTP} instances have the following methods:
\begin{methoddesc}{set_debuglevel}{level}
Set the instance's debugging level. This controls the amount of
debugging output printed. The default, \code{0}, produces no
debugging output. A value of \code{1} produces a moderate amount of
debugging output, generally a single line per request. A value of
\code{2} or higher produces the maximum amount of debugging output,
logging each line sent and received on the control connection.
\end{methoddesc}
\begin{methoddesc}{connect}{host\optional{, port}}
Connect to the given host and port. The default port number is \code{21}, as
specified by the FTP protocol specification. It is rarely needed to
specify a different port number. This function should be called only
once for each instance; it should not be called at all if a host was
given when the instance was created. All other methods can only be
used after a connection has been made.
\end{methoddesc}
\begin{methoddesc}{getwelcome}{}
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.)
\end{methoddesc}
\begin{methoddesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
Log in as the given \var{user}. The \var{passwd} and \var{acct}
parameters are optional and default to the empty string. If no
\var{user} is specified, it defaults to \code{'anonymous'}. If
\var{user} is \code{anonymous}, the default \var{passwd} is
\samp{\var{realuser}@\var{host}} where \var{realuser} is the real user
name (glanced from the \envvar{LOGNAME} or \envvar{USER} environment
variable) and \var{host} is the hostname as returned by
\function{socket.gethostname()}. This function should be called only
once for each instance, after a connection has been established; it
should not be called at all if a host and user were given when the
instance was created. Most FTP commands are only allowed after the
client has logged in.
\end{methoddesc}
\begin{methoddesc}{abort}{}
Abort a file transfer that is in progress. Using this does not always
work, but it's worth a try.
\end{methoddesc}
\begin{methoddesc}{sendcmd}{command}
Send a simple command string to the server and return the response
string.
\end{methoddesc}
\begin{methoddesc}{voidcmd}{command}
Send a simple command string to the server and handle the response.
Return nothing if a response code in the range 200--299 is received.
Raise an exception otherwise.
\end{methoddesc}
\begin{methoddesc}{retrbinary}{command, callback\optional{, maxblocksize}}
Retrieve a file in binary transfer mode. \var{command} should be an
appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}.
The \var{callback} function is called for each block of data received,
with a single string argument giving the data block.
The optional \var{maxblocksize} argument specifies the maximum chunk size to
read on the low-level socket object created to do the actual transfer
(which will also be the largest size of the data blocks passed to
\var{callback}). A reasonable default is chosen.
\end{methoddesc}
\begin{methoddesc}{retrlines}{command\optional{, callback}}
Retrieve a file or directory listing in \ASCII{} transfer mode.
\var{command} should be an appropriate \samp{RETR} command (see
\method{retrbinary()} or a \samp{LIST} command (usually just the string
\code{'LIST'}). The \var{callback} function is called for each line,
with the trailing CRLF stripped. The default \var{callback} prints
the line to \code{sys.stdout}.
\end{methoddesc}
\begin{methoddesc}{storbinary}{command, file, blocksize}
Store a file in binary transfer mode. \var{command} should be an
appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}.
\var{file} is an open file object which is read until \EOF{} using its
\method{read()} method in blocks of size \var{blocksize} to provide the
data to be stored.
\end{methoddesc}
\begin{methoddesc}{storlines}{command, file}
Store a file in \ASCII{} transfer mode. \var{command} should be an
appropriate \samp{STOR} command (see \method{storbinary()}). Lines are
read until \EOF{} from the open file object \var{file} using its
\method{readline()} method to privide the data to be stored.
\end{methoddesc}
\begin{methoddesc}{transfercmd}{cmd}
Initiate a transfer over the data connection. If the transfer is
active, send a \samp{PORT} command and the transfer command specified
by \var{cmd}, and accept the connection. If the server is passive,
send a \samp{PASV} command, connect to it, and start the transfer
command. Either way, return the socket for the connection.
\end{methoddesc}
\begin{methoddesc}{ntransfercmd}{cmd}
Like \method{transfercmd()}, but returns a tuple of the data
connection and the expected size of the data. If the expected size
could not be computed, \code{None} will be returned as the expected
size.
\end{methoddesc}
\begin{methoddesc}{nlst}{argument\optional{, \ldots}}
Return a list of files as returned by the \samp{NLST} command. The
optional \var{argument} is a directory to list (default is the current
server directory). Multiple arguments can be used to pass
non-standard options to the \samp{NLST} command.
\end{methoddesc}
\begin{methoddesc}{dir}{argument\optional{, \ldots}}
Return a directory listing as returned by the \samp{LIST} command, as
a list of lines. The optional \var{argument} is a directory to list
(default is the current server directory). Multiple arguments can be
used to pass non-standard options to the \samp{LIST} command. If the
last argument is a function, it is used as a \var{callback} function
as for \method{retrlines()}.
\end{methoddesc}
\begin{methoddesc}{rename}{fromname, toname}
Rename file \var{fromname} on the server to \var{toname}.
\end{methoddesc}
\begin{methoddesc}{delete}{filename}
Remove the file named \var{filename} from the server. If successful,
returns the text of the response, otherwise raises
\exception{error_perm} on permission errors or \exception{error_reply}
on other errors.
\end{methoddesc}
\begin{methoddesc}{cwd}{pathname}
Set the current directory on the server.
\end{methoddesc}
\begin{methoddesc}{mkd}{pathname}
Create a new directory on the server.
\end{methoddesc}
\begin{methoddesc}{pwd}{}
Return the pathname of the current directory on the server.
\end{methoddesc}
\begin{methoddesc}{rmd}{dirname}
Remove the directory named \var{dirname} on the server.
\end{methoddesc}
\begin{methoddesc}{size}{filename}
Request the size of the file named \var{filename} on the server. On
success, the size of the file is returned as an integer, otherwise
\code{None} is returned. Note that the \samp{SIZE} command is not
standardized, but is supported by many common server implementations.
\end{methoddesc}
\begin{methoddesc}{quit}{}
Send a \samp{QUIT} command to the server and close the connection.
This is the ``polite'' way to close a connection, but it may raise an
exception of the server reponds with an error to the \samp{QUIT}
command.
\end{methoddesc}
\begin{methoddesc}{close}{}
Close the connection unilaterally. This should not be applied to an
already closed connection (e.g.\ after a successful call to
\method{quit()}.
\end{methoddesc}

635
Doc/libfuncs.tex
View File

@ -1,635 +0,0 @@
\section{Built-in Functions}
\label{built-in-funcs}
The Python interpreter has a number of functions built into it that
are always available. They are listed here in alphabetical order.
\setindexsubitem{(built-in function)}
\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist}}}}
This function is invoked by the \keyword{import} statement. It
mainly exists so that you can replace it with another
function that has a compatible interface, in order to change the
semantics of the \keyword{import} statement. For examples of why and
how you would do this, see the standard library modules
\module{ihooks} and \module{rexec}. See also the built-in module
\module{imp}, which defines some useful operations out of which you can
build your own \function{__import__()} function.
\stindex{import}
\refstmodindex{ihooks}
\refstmodindex{rexec}
\refbimodindex{imp}
For example, the statement `\code{import} \code{spam}' results in the
following call:
\code{__import__('spam',} \code{globals(),} \code{locals(), [])};
the statement \code{from} \code{spam.ham import} \code{eggs} results
in \code{__import__('spam.ham',} \code{globals(),} \code{locals(),}
\code{['eggs'])}.
Note that even though \code{locals()} and \code{['eggs']} are passed
in as arguments, the \function{__import__()} function does not set the
local variable named \code{eggs}; this is done by subsequent code that
is generated for the import statement. (In fact, the standard
implementation does not use its \var{locals} argument at all, and uses
its \var{globals} only to determine the package context of the
\keyword{import} statement.)
When the \var{name} variable is of the form \code{package.module},
normally, the top-level package (the name up till the first dot) is
returned, \emph{not} the module named by \var{name}. However, when a
non-empty \var{fromlist} argument is given, the module named by
\var{name} is returned. This is done for compatibility with the
bytecode generated for the different kinds of import statement; when
using \samp{import spam.ham.eggs}, the top-level package \code{spam}
must be placed in the importing namespace, but when using \samp{from
spam.ham import eggs}, the \code{spam.ham} subpackage must be used to
find the \code{eggs} variable.
\end{funcdesc}
\begin{funcdesc}{abs}{x}
Return the absolute value of a number. The argument may be a plain
or long integer or a floating point number. If the argument is a
complex number, its magnitude is returned.
\end{funcdesc}
\begin{funcdesc}{apply}{function, args\optional{, keywords}}
The \var{function} argument must be a callable object (a user-defined or
built-in function or method, or a class object) and the \var{args}
argument must be a tuple. The \var{function} is called with
\var{args} as argument list; the number of arguments is the the length
of the tuple. (This is different from just calling
\code{\var{func}(\var{args})}, since in that case there is always
exactly one argument.)
If the optional \var{keywords} argument is present, it must be a
dictionary whose keys are strings. It specifies keyword arguments to
be added to the end of the the argument list.
\end{funcdesc}
\begin{funcdesc}{callable}{object}
Return true if the \var{object} argument appears callable, false if
not. If this returns true, it is still possible that a call fails,
but if it is false, calling \var{object} will never succeed. Note
that classes are callable (calling a class returns a new instance);
class instances are callable if they have a \method{__call__()} method.
\end{funcdesc}
\begin{funcdesc}{chr}{i}
Return a string of one character whose \ASCII{} code is the integer
\var{i}, e.g., \code{chr(97)} returns the string \code{'a'}. This is the
inverse of \function{ord()}. The argument must be in the range [0..255],
inclusive.
\end{funcdesc}
\begin{funcdesc}{cmp}{x, y}
Compare the two objects \var{x} and \var{y} and return an integer
according to the outcome. The return value is negative if \code{\var{x}
< \var{y}}, zero if \code{\var{x} == \var{y}} and strictly positive if
\code{\var{x} > \var{y}}.
\end{funcdesc}
\begin{funcdesc}{coerce}{x, y}
Return a tuple consisting of the two numeric arguments converted to
a common type, using the same rules as used by arithmetic
operations.
\end{funcdesc}
\begin{funcdesc}{compile}{string, filename, kind}
Compile the \var{string} into a code object. Code objects can be
executed by an \keyword{exec} statement or evaluated by a call to
\function{eval()}. The \var{filename} argument should
give the file from which the code was read; pass e.g. \code{'<string>'}
if it wasn't read from a file. The \var{kind} argument specifies
what kind of code must be compiled; it can be \code{'exec'} if
\var{string} consists of a sequence of statements, \code{'eval'}
if it consists of a single expression, or \code{'single'} if
it consists of a single interactive statement (in the latter case,
expression statements that evaluate to something else than
\code{None} will printed).
\end{funcdesc}
\begin{funcdesc}{complex}{real\optional{, imag}}
Create a complex number with the value \var{real} + \var{imag}*j.
Each argument may be any numeric type (including complex).
If \var{imag} is omitted, it defaults to zero and the function
serves as a numeric conversion function like \function{int()},
\function{long()} and \function{float()}.
\end{funcdesc}
\begin{funcdesc}{delattr}{object, name}
This is a relative of \function{setattr()}. The arguments are an
object and a string. The string must be the name
of one of the object's attributes. The function deletes
the named attribute, provided the object allows it. For example,
\code{delattr(\var{x}, '\var{foobar}')} is equivalent to
\code{del \var{x}.\var{foobar}}.
\end{funcdesc}
\begin{funcdesc}{dir}{\optional{object}}
Without arguments, return the list of names in the current local
symbol table. With an argument, attempts to return a list of valid
attribute for that object. This information is gleaned from the
object's \member{__dict__}, \member{__methods__} and \member{__members__}
attributes, if defined. The list is not necessarily complete; e.g.,
for classes, attributes defined in base classes are not included,
and for class instances, methods are not included.
The resulting list is sorted alphabetically. For example:
\begin{verbatim}
>>> import sys
>>> dir()
['sys']
>>> dir(sys)
['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
>>>
\end{verbatim}
\end{funcdesc}
\begin{funcdesc}{divmod}{a, b}
Take two numbers as arguments and return a pair of numbers consisting
of their quotient and remainder when using long division. With mixed
operand types, the rules for binary arithmetic operators apply. For
plain and long integers, the result is the same as
\code{(\var{a} / \var{b}, \var{a} \%{} \var{b})}.
For floating point numbers the result is the same as
\code{(math.floor(\var{a} / \var{b}), \var{a} \%{} \var{b})}.
\end{funcdesc}
\begin{funcdesc}{eval}{expression\optional{, globals\optional{, locals}}}
The arguments are a string and two optional dictionaries. The
\var{expression} argument is parsed and evaluated as a Python
expression (technically speaking, a condition list) using the
\var{globals} and \var{locals} dictionaries as global and local name
space. If the \var{locals} dictionary is omitted it defaults to
the \var{globals} dictionary. If both dictionaries are omitted, the
expression is executed in the environment where \keyword{eval} is
called. The return value is the result of the evaluated expression.
Syntax errors are reported as exceptions. Example:
\begin{verbatim}
>>> x = 1
>>> print eval('x+1')
2
>>>
\end{verbatim}
This function can also be used to execute arbitrary code objects
(e.g.\ created by \function{compile()}). In this case pass a code
object instead of a string. The code object must have been compiled
passing \code{'eval'} to the \var{kind} argument.
Hints: dynamic execution of statements is supported by the
\keyword{exec} statement. Execution of statements from a file is
supported by the \function{execfile()} function. The
\function{globals()} and \function{locals()} functions returns the
current global and local dictionary, respectively, which may be
useful to pass around for use by \function{eval()} or
\function{execfile()}.
\end{funcdesc}
\begin{funcdesc}{execfile}{file\optional{, globals\optional{, locals}}}
This function is similar to the
\keyword{exec} statement, but parses a file instead of a string. It
is different from the \keyword{import} statement in that it does not
use the module administration --- it reads the file unconditionally
and does not create a new module.\footnote{It is used relatively
rarely so does not warrant being made into a statement.}
The arguments are a file name and two optional dictionaries. The
file is parsed and evaluated as a sequence of Python statements
(similarly to a module) using the \var{globals} and \var{locals}
dictionaries as global and local name space. If the \var{locals}
dictionary is omitted it defaults to the \var{globals} dictionary.
If both dictionaries are omitted, the expression is executed in the
environment where \function{execfile()} is called. The return value is
\code{None}.
\end{funcdesc}
\begin{funcdesc}{filter}{function, list}
Construct a list from those elements of \var{list} for which
\var{function} returns true. If \var{list} is a string or a tuple,
the result also has that type; otherwise it is always a list. If
\var{function} is \code{None}, the identity function is assumed,
i.e.\ all elements of \var{list} that are false (zero or empty) are
removed.
\end{funcdesc}
\begin{funcdesc}{float}{x}
Convert a string or a number to floating point. If the argument is a
string, it must contain a possibly singed decimal or floating point
number, possibly embedded in whitespace;
this behaves identical to \code{string.atof(\var{x})}.
Otherwise, the argument may be a plain or
long integer or a floating point number, and a floating point number
with the same value (within Python's floating point precision) is
returned.
\end{funcdesc}
\begin{funcdesc}{getattr}{object, name}
The arguments are an object and a string. The string must be the
name of one of the object's attributes. The result is the value of
that attribute. For example, \code{getattr(\var{x},
'\var{foobar}')} is equivalent to \code{\var{x}.\var{foobar}}.
\end{funcdesc}
\begin{funcdesc}{globals}{}
Return a dictionary representing the current global symbol table.
This is always the dictionary of the current module (inside a
function or method, this is the module where it is defined, not the
module from which it is called).
\end{funcdesc}
\begin{funcdesc}{hasattr}{object, name}
The arguments are an object and a string. The result is 1 if the
string is the name of one of the object's attributes, 0 if not.
(This is implemented by calling \code{getattr(\var{object},
\var{name})} and seeing whether it raises an exception or not.)
\end{funcdesc}
\begin{funcdesc}{hash}{object}
Return the hash value of the object (if it has one). Hash values
are integers. They are used to quickly compare dictionary
keys during a dictionary lookup. Numeric values that compare equal
have the same hash value (even if they are of different types, e.g.
1 and 1.0).
\end{funcdesc}
\begin{funcdesc}{hex}{x}
Convert an integer number (of any size) to a hexadecimal string.
The result is a valid Python expression. Note: this always yields
an unsigned literal, e.g. on a 32-bit machine, \code{hex(-1)} yields
\code{'0xffffffff'}. When evaluated on a machine with the same
word size, this literal is evaluated as -1; at a different word
size, it may turn up as a large positive number or raise an
\exception{OverflowError} exception.
\end{funcdesc}
\begin{funcdesc}{id}{object}
Return the `identity' of an object. This is an integer which is
guaranteed to be unique and constant for this object during its
lifetime. (Two objects whose lifetimes are disjunct may have the
same \function{id()} value.) (Implementation note: this is the
address of the object.)
\end{funcdesc}
\begin{funcdesc}{input}{\optional{prompt}}
Almost equivalent to \code{eval(raw_input(\var{prompt}))}. Like
\function{raw_input()}, the \var{prompt} argument is optional, and the
\module{readline} module is used when loaded. The difference
is that a long input expression may be broken over multiple lines using
the backslash convention.
\end{funcdesc}
\begin{funcdesc}{intern}{string}
Enter \var{string} in the table of ``interned'' strings and return
the interned string -- which is \var{string} itself or a copy.
Interning strings is useful to gain a little performance on
dictionary lookup -- if the keys in a dictionary are interned, and
the lookup key is interned, the key comparisons (after hashing) can
be done by a pointer compare instead of a string compare. Normally,
the names used in Python programs are automatically interned, and
the dictionaries used to hold module, class or instance attributes
have interned keys. Interned strings are immortal (i.e. never get
garbage collected).
\end{funcdesc}
\begin{funcdesc}{int}{x}
Convert a string or number to a plain integer. If the argument is a
string, it must contain a possibly singed decimal number
representable as a Python integer, possibly embedded in whitespace;
this behaves identical to \code{string.atoi(\var{x})}.
Otherwise, the argument may be a plain or
long integer or a floating point number. Conversion of floating
point numbers to integers is defined by the C semantics; normally
the conversion truncates towards zero.\footnote{This is ugly --- the
language definition should require truncation towards zero.}
\end{funcdesc}
\begin{funcdesc}{isinstance}{object, class}
Return true if the \var{object} argument is an instance of the
\var{class} argument, or of a (direct or indirect) subclass thereof.
Also return true if \var{class} is a type object and \var{object} is
an object of that type. If \var{object} is not a class instance or a
object of the given type, the function always returns false. If
\var{class} is neither a class object nor a type object, a
\exception{TypeError} exception is raised.
\end{funcdesc}
\begin{funcdesc}{issubclass}{class1, class2}
Return true if \var{class1} is a subclass (direct or indirect) of
\var{class2}. A class is considered a subclass of itself. If either
argument is not a class object, a \exception{TypeError} exception is
raised.
\end{funcdesc}
\begin{funcdesc}{len}{s}
Return the length (the number of items) of an object. The argument
may be a sequence (string, tuple or list) or a mapping (dictionary).
\end{funcdesc}
\begin{funcdesc}{list}{sequence}
Return a list whose items are the same and in the same order as
\var{sequence}'s items. If \var{sequence} is already a list,
a copy is made and returned, similar to \code{\var{sequence}[:]}.
For instance, \code{list('abc')} returns
returns \code{['a', 'b', 'c']} and \code{list( (1, 2, 3) )} returns
\code{[1, 2, 3]}.
\end{funcdesc}
\begin{funcdesc}{locals}{}
Return a dictionary representing the current local symbol table.
Inside a function, modifying this dictionary does not always have the
desired effect.
\end{funcdesc}
\begin{funcdesc}{long}{x}
Convert a string or number to a long integer. If the argument is a
string, it must contain a possibly singed decimal number of
arbitrary size, possibly embedded in whitespace;
this behaves identical to \code{string.atol(\var{x})}.
Otherwise, the argument may be a plain or
long integer or a floating point number, and a long integer with
the same value is returned. Conversion of floating
point numbers to integers is defined by the C semantics;
see the description of \function{int()}.
\end{funcdesc}
\begin{funcdesc}{map}{function, list, ...}
Apply \var{function} to every item of \var{list} and return a list
of the results. If additional \var{list} arguments are passed,
\var{function} must take that many arguments and is applied to
the items of all lists in parallel; if a list is shorter than another
it is assumed to be extended with \code{None} items. If
\var{function} is \code{None}, the identity function is assumed; if
there are multiple list arguments, \function{map()} returns a list
consisting of tuples containing the corresponding items from all lists
(i.e. a kind of transpose operation). The \var{list} arguments may be
any kind of sequence; the result is always a list.
\end{funcdesc}
\begin{funcdesc}{max}{s}
Return the largest item of a non-empty sequence (string, tuple or
list).
\end{funcdesc}
\begin{funcdesc}{min}{s}
Return the smallest item of a non-empty sequence (string, tuple or
list).
\end{funcdesc}
\begin{funcdesc}{oct}{x}
Convert an integer number (of any size) to an octal string. The
result is a valid Python expression. Note: this always yields
an unsigned literal, e.g. on a 32-bit machine, \code{oct(-1)} yields
\code{'037777777777'}. When evaluated on a machine with the same
word size, this literal is evaluated as -1; at a different word
size, it may turn up as a large positive number or raise an
\exception{OverflowError} exception.
\end{funcdesc}
\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
Return a new file object (described earlier under Built-in Types).
The first two arguments are the same as for \code{stdio}'s
\cfunction{fopen()}: \var{filename} is the file name to be opened,
\var{mode} indicates how the file is to be opened: \code{'r'} for
reading, \code{'w'} for writing (truncating an existing file), and
\code{'a'} opens it for appending (which on \emph{some} \UNIX{}
systems means that \emph{all} writes append to the end of the file,
regardless of the current seek position).
Modes \code{'r+'}, \code{'w+'} and
\code{'a+'} open the file for updating, provided the underlying
\code{stdio} library understands this. On systems that differentiate
between binary and text files, \code{'b'} appended to the mode opens
the file in binary mode. If the file cannot be opened,
\exception{IOError} is raised.
If \var{mode} is omitted, it defaults to \code{'r'}.
The optional \var{bufsize} argument specifies the file's desired
buffer size: 0 means unbuffered, 1 means line buffered, any other
positive value means use a buffer of (approximately) that size. A
negative \var{bufsize} means to use the system default, which is
usually line buffered for for tty devices and fully buffered for other
files.%
\footnote{Specifying a buffer size currently has no effect on systems
that don't have \cfunction{setvbuf()}. The interface to specify the buffer
size is not done using a method that calls \cfunction{setvbuf()}, because
that may dump core when called after any I/O has been performed, and
there's no reliable way to determine whether this is the case.}
\end{funcdesc}
\begin{funcdesc}{ord}{c}
Return the \ASCII{} value of a string of one character. E.g.,
\code{ord('a')} returns the integer \code{97}. This is the inverse of
\function{chr()}.
\end{funcdesc}
\begin{funcdesc}{pow}{x, y\optional{, z}}
Return \var{x} to the power \var{y}; if \var{z} is present, return
\var{x} to the power \var{y}, modulo \var{z} (computed more
efficiently than \code{pow(\var{x}, \var{y}) \%\ \var{z}}).
The arguments must have
numeric types. With mixed operand types, the rules for binary
arithmetic operators apply. The effective operand type is also the
type of the result; if the result is not expressible in this type, the
function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2,
35000)} is not allowed.
\end{funcdesc}
\begin{funcdesc}{range}{\optional{start,} stop\optional{, step}}
This is a versatile function to create lists containing arithmetic
progressions. It is most often used in \keyword{for} loops. The
arguments must be plain integers. If the \var{step} argument is
omitted, it defaults to \code{1}. If the \var{start} argument is
omitted, it defaults to \code{0}. The full form returns a list of
plain integers \code{[\var{start}, \var{start} + \var{step},
\var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
the last element is the largest \code{\var{start} + \var{i} *
\var{step}} less than \var{stop}; if \var{step} is negative, the last
element is the largest \code{\var{start} + \var{i} * \var{step}}
greater than \var{stop}. \var{step} must not be zero (or else
\exception{ValueError} is raised). Example:
\begin{verbatim}
>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> range(1, 11)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> range(0, 30, 5)
[0, 5, 10, 15, 20, 25]
>>> range(0, 10, 3)
[0, 3, 6, 9]
>>> range(0, -10, -1)
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> range(0)
[]
>>> range(1, 0)
[]
>>>
\end{verbatim}
\end{funcdesc}
\begin{funcdesc}{raw_input}{\optional{prompt}}
If the \var{prompt} argument is present, it is written to standard output
without a trailing newline. The function then reads a line from input,
converts it to a string (stripping a trailing newline), and returns that.
When \EOF{} is read, \exception{EOFError} is raised. Example:
\begin{verbatim}
>>> s = raw_input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"
>>>
\end{verbatim}
If the \module{readline} module was loaded, then
\function{raw_input()} will use it to provide elaborate
line editing and history features.
\end{funcdesc}
\begin{funcdesc}{reduce}{function, list\optional{, initializer}}
Apply the binary \var{function} to the items of \var{list} so as to
reduce the list to a single value. E.g.,
\code{reduce(lambda x, y: x*y, \var{list}, 1)} returns the product of
the elements of \var{list}. The optional \var{initializer} can be
thought of as being prepended to \var{list} so as to allow reduction
of an empty \var{list}. The \var{list} arguments may be any kind of
sequence.
\end{funcdesc}
\begin{funcdesc}{reload}{module}
Re-parse and re-initialize an already imported \var{module}. The
argument must be a module object, so it must have been successfully
imported before. This is useful if you have edited the module source
file using an external editor and want to try out the new version
without leaving the Python interpreter. The return value is the
module object (i.e.\ the same as the \var{module} argument).
There are a number of caveats:
If a module is syntactically correct but its initialization fails, the
first \keyword{import} statement for it does not bind its name locally,
but does store a (partially initialized) module object in
\code{sys.modules}. To reload the module you must first
\keyword{import} it again (this will bind the name to the partially
initialized module object) before you can \function{reload()} it.
When a module is reloaded, its dictionary (containing the module's
global variables) is retained. Redefinitions of names will override
the old definitions, so this is generally not a problem. If the new
version of a module does not define a name that was defined by the old
version, the old definition remains. This feature can be used to the
module's advantage if it maintains a global table or cache of objects
--- with a \keyword{try} statement it can test for the table's presence
and skip its initialization if desired.
It is legal though generally not very useful to reload built-in or
dynamically loaded modules, except for \module{sys}, \module{__main__}
and \module{__builtin__}. In certain cases, however, extension
modules are not designed to be initialized more than once, and may
fail in arbitrary ways when reloaded.
If a module imports objects from another module using \keyword{from}
\ldots{} \keyword{import} \ldots{}, calling \function{reload()} for
the other module does not redefine the objects imported from it ---
one way around this is to re-execute the \keyword{from} statement,
another is to use \keyword{import} and qualified names
(\var{module}.\var{name}) instead.
If a module instantiates instances of a class, reloading the module
that defines the class does not affect the method definitions of the
instances --- they continue to use the old class definition. The same
is true for derived classes.
\end{funcdesc}
\begin{funcdesc}{repr}{object}
Return a string containing a printable representation of an object.
This is the same value yielded by conversions (reverse quotes).
It is sometimes useful to be able to access this operation as an
ordinary function. For many types, this function makes an attempt
to return a string that would yield an object with the same value
when passed to \function{eval()}.
\end{funcdesc}
\begin{funcdesc}{round}{x, n}
Return the floating point value \var{x} rounded to \var{n} digits
after the decimal point. If \var{n} is omitted, it defaults to zero.
The result is a floating point number. Values are rounded to the
closest multiple of 10 to the power minus \var{n}; if two multiples
are equally close, rounding is done away from 0 (so e.g.
\code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}).
\end{funcdesc}
\begin{funcdesc}{setattr}{object, name, value}
This is the counterpart of \function{getattr()}. The arguments are an
object, a string and an arbitrary value. The string must be the name
of one of the object's attributes. The function assigns the value to
the attribute, provided the object allows it. For example,
\code{setattr(\var{x}, '\var{foobar}', 123)} is equivalent to
\code{\var{x}.\var{foobar} = 123}.
\end{funcdesc}
\begin{funcdesc}{slice}{\optional{start,} stop\optional{, step}}
Return a slice object representing the set of indices specified by
\code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
and \var{step} arguments default to None. Slice objects have
read-only data attributes \member{start}, \member{stop} and \member{step}
which merely return the argument values (or their default). They have
no other explicit functionality; however they are used by Numerical
Python\index{Numerical Python} and other third party extensions.
Slice objects are also generated when extended indexing syntax is
used, e.g. for \samp{a[start:stop:step]} or \samp{a[start:stop, i]}.
\end{funcdesc}
\begin{funcdesc}{str}{object}
Return a string containing a nicely printable representation of an
object. For strings, this returns the string itself. The difference
with \code{repr(\var{object})} is that \code{str(\var{object})} does not
always attempt to return a string that is acceptable to \function{eval()};
its goal is to return a printable string.
\end{funcdesc}
\begin{funcdesc}{tuple}{sequence}
Return a tuple whose items are the same and in the same order as
\var{sequence}'s items. If \var{sequence} is already a tuple, it
is returned unchanged. For instance, \code{tuple('abc')} returns
returns \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns
\code{(1, 2, 3)}.
\end{funcdesc}
\begin{funcdesc}{type}{object}
Return the type of an \var{object}. The return value is a type
object. The standard module \module{types} defines names for all
built-in types.
\refstmodindex{types}
\obindex{type}
For instance:
\begin{verbatim}
>>> import types
>>> if isinstance(x, types.StringType): print "It's a string"
\end{verbatim}
\end{funcdesc}
\begin{funcdesc}{vars}{\optional{object}}
Without arguments, return a dictionary corresponding to the current
local symbol table. With a module, class or class instance object as
argument (or anything else that has a \member{__dict__} attribute),
returns a dictionary corresponding to the object's symbol table.
The returned dictionary should not be modified: the effects on the
corresponding symbol table are undefined.%
\footnote{In the current implementation, local variable bindings
cannot normally be affected this way, but variables retrieved from
other scopes (e.g. modules) can be. This may change.}
\end{funcdesc}
\begin{funcdesc}{xrange}{\optional{start,} stop\optional{, step}}
This function is very similar to \function{range()}, but returns an
``xrange object'' instead of a list. This is an opaque sequence type
which yields the same values as the corresponding list, without
actually storing them all simultaneously. The advantage of
\function{xrange()} over \function{range()} is minimal (since
\function{xrange()} still has to create the values when asked for
them) except when a very large range is used on a memory-starved
machine (e.g. MS-DOS) or when all of the range's elements are never
used (e.g. when the loop is usually terminated with \keyword{break}).
\end{funcdesc}

93
Doc/libgdbm.tex
View File

@ -1,93 +0,0 @@
\section{Built-in Module \module{gdbm}}
\label{module-gdbm}
\bimodindex{gdbm}
% Note that if this section appears on the same page as the first
% paragraph of the dbm module section, makeindex will produce the
% warning:
%
% ## Warning (input = lib.idx, line = 1184; output = lib.ind, line = 852):
% -- Conflicting entries: multiple encaps for the same page under same key.
%
% This is because the \bimodindex{gdbm} and \refbimodindex{gdbm}
% entries in the .idx file are slightly different (the \bimodindex{}
% version includes "|textbf" at the end to make the defining occurance
% bold). There doesn't appear to be anything that can be done about
% this; it's just a little annoying. The warning can be ignored, but
% the index produced uses the non-bold version.
This module is quite similar to the \code{dbm} module, but uses \code{gdbm}
instead to provide some additional functionality. Please note that
the file formats created by \code{gdbm} and \code{dbm} are incompatible.
\refbimodindex{dbm}
The \code{gdbm} module provides an interface to the GNU DBM
library. \code{gdbm} objects behave like mappings
(dictionaries), except that keys and values are always strings.
Printing a \code{gdbm} object doesn't print the keys and values, and the
\code{items()} and \code{values()} methods are not supported.
The module defines the following constant and functions:
\begin{excdesc}{error}
Raised on \code{gdbm}-specific errors, such as I/O errors. \code{KeyError} is
raised for general mapping errors like specifying an incorrect key.
\end{excdesc}
\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
Open a \code{gdbm} database and return a \code{gdbm} object. The
\var{filename} argument is the name of the database file.
The optional \var{flag} argument can be
\code{'r'} (to open an existing database for reading only --- default),
\code{'w'} (to open an existing database for reading and writing),
\code{'c'} (which creates the database if it doesn't exist), or
\code{'n'} (which always creates a new empty database).
Appending \code{f} to the flag opens the database in fast mode;
altered data will not automatically be written to the disk after every
change. This results in faster writes to the database, but may result
in an inconsistent database if the program crashes while the database
is still open. Use the \code{sync()} method to force any unwritten
data to be written to the disk.
The optional \var{mode} argument is the \UNIX{} mode of the file, used
only when the database has to be created. It defaults to octal
\code{0666}.
\end{funcdesc}
In addition to the dictionary-like methods, \code{gdbm} objects have the
following methods:
\begin{funcdesc}{firstkey}{}
It's possible to loop over every key in the database using this method
and the \code{nextkey()} method. The traversal is ordered by \code{gdbm}'s
internal hash values, and won't be sorted by the key values. This
method returns the starting key.
\end{funcdesc}
\begin{funcdesc}{nextkey}{key}
Returns the key that follows \var{key} in the traversal. The
following code prints every key in the database \code{db}, without having to
create a list in memory that contains them all:
\begin{verbatim}
k=db.firstkey()
while k!=None:
print k
k=db.nextkey(k)
\end{verbatim}
\end{funcdesc}
\begin{funcdesc}{reorganize}{}
If you have carried out a lot of deletions and would like to shrink
the space used by the \code{gdbm} file, this routine will reorganize the
database. \code{gdbm} will not shorten the length of a database file except
by using this reorganization; otherwise, deleted file space will be
kept and reused as new (key,value) pairs are added.
\end{funcdesc}
\begin{funcdesc}{sync}{}
When the database has been opened in fast mode, this method forces any
unwritten data to be written to the disk.
\end{funcdesc}

80
Doc/libgetopt.tex
View File

@ -1,80 +0,0 @@
\section{Standard Module \module{getopt}}
\label{module-getopt}
\stmodindex{getopt}
This module helps scripts to parse the command line arguments in
\code{sys.argv}.
It supports the same conventions as the \UNIX{} \cfunction{getopt()}
function (including the special meanings of arguments of the form
`\code{-}' and `\code{-}\code{-}').
% That's to fool latex2html into leaving the two hyphens alone!
Long options similar to those supported by
GNU software may be used as well via an optional third argument.
This module provides a single function and an exception:
\begin{funcdesc}{getopt}{args, options\optional{, long_options}}
Parses command line options and parameter list. \var{args} is the
argument list to be parsed, without the leading reference to the
running program. Typically, this means \samp{sys.argv[1:]}.
\var{options} is the string of option letters that the script wants to
recognize, with options that require an argument followed by a colon
(i.e., the same format that \UNIX{} \cfunction{getopt()} uses). If
specified, \var{long_options} is a list of strings with the names of
the long options which should be supported. The leading
\code{'-}\code{-'} characters should not be included in the option
name. Options which require an argument should be followed by an
equal sign (\code{'='}).
The return value consists of two elements: the first is a list of
\code{(\var{option}, \var{value})} pairs; the second is the list of
program arguments left after the option list was stripped (this is a
trailing slice of the first argument).
Each option-and-value pair returned has the option as its first
element, prefixed with a hyphen (e.g., \code{'-x'}), and the option
argument as its second element, or an empty string if the option has
no argument.
The options occur in the list in the same order in which they were
found, thus allowing multiple occurrences. Long and short options may
be mixed.
\end{funcdesc}
\begin{excdesc}{error}
This is raised when an unrecognized option is found in the argument
list or when an option requiring an argument is given none.
The argument to the exception is a string indicating the cause of the
error. For long options, an argument given to an option which does
not require one will also cause this exception to be raised.
\end{excdesc}
An example using only \UNIX{} style options:
\begin{verbatim}
>>> import getopt, string
>>> args = string.split('-a -b -cfoo -d bar a1 a2')
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
>>>
\end{verbatim}
Using long option names is equally easy:
\begin{verbatim}
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = string.split(s)
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
... 'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
'')]
>>> args
['a1', 'a2']
>>>
\end{verbatim}

197
Doc/libgl.tex
View File

@ -1,197 +0,0 @@
\section{Built-in Module \module{gl}}
\label{module-gl}
\bimodindex{gl}
This module provides access to the Silicon Graphics
\emph{Graphics Library}.
It is available only on Silicon Graphics machines.
\strong{Warning:}
Some illegal calls to the GL library cause the Python interpreter to dump
core.
In particular, the use of most GL calls is unsafe before the first
window is opened.
The module is too large to document here in its entirety, but the
following should help you to get started.
The parameter conventions for the C functions are translated to Python as
follows:
\begin{itemize}
\item
All (short, long, unsigned) int values are represented by Python
integers.
\item
All float and double values are represented by Python floating point
numbers.
In most cases, Python integers are also allowed.
\item
All arrays are represented by one-dimensional Python lists.
In most cases, tuples are also allowed.
\item
\begin{sloppypar}
All string and character arguments are represented by Python strings,
for instance,
\code{winopen('Hi There!')}
and
\code{rotate(900, 'z')}.
\end{sloppypar}
\item
All (short, long, unsigned) integer arguments or return values that are
only used to specify the length of an array argument are omitted.
For example, the C call
\begin{verbatim}
lmdef(deftype, index, np, props)
\end{verbatim}
%
is translated to Python as
\begin{verbatim}
lmdef(deftype, index, props)
\end{verbatim}
%
\item
Output arguments are omitted from the argument list; they are
transmitted as function return values instead.
If more than one value must be returned, the return value is a tuple.
If the C function has both a regular return value (that is not omitted
because of the previous rule) and an output argument, the return value
comes first in the tuple.
Examples: the C call
\begin{verbatim}
getmcolor(i, &red, &green, &blue)
\end{verbatim}
%
is translated to Python as
\begin{verbatim}
red, green, blue = getmcolor(i)
\end{verbatim}
%
\end{itemize}
The following functions are non-standard or have special argument
conventions:
\begin{funcdesc}{varray}{argument}
%JHXXX the argument-argument added
Equivalent to but faster than a number of
\code{v3d()}
calls.
The \var{argument} is a list (or tuple) of points.
Each point must be a tuple of coordinates
\code{(\var{x}, \var{y}, \var{z})} or \code{(\var{x}, \var{y})}.
The points may be 2- or 3-dimensional but must all have the
same dimension.
Float and int values may be mixed however.
The points are always converted to 3D double precision points
by assuming \code{\var{z} = 0.0} if necessary (as indicated in the man page),
and for each point
\code{v3d()}
is called.
\end{funcdesc}
\begin{funcdesc}{nvarray}{}
Equivalent to but faster than a number of
\code{n3f}
and
\code{v3f}
calls.
The argument is an array (list or tuple) of pairs of normals and points.
Each pair is a tuple of a point and a normal for that point.
Each point or normal must be a tuple of coordinates
\code{(\var{x}, \var{y}, \var{z})}.
Three coordinates must be given.
Float and int values may be mixed.
For each pair,
\code{n3f()}
is called for the normal, and then
\code{v3f()}
is called for the point.
\end{funcdesc}
\begin{funcdesc}{vnarray}{}
Similar to
\code{nvarray()}
but the pairs have the point first and the normal second.
\end{funcdesc}
\begin{funcdesc}{nurbssurface}{s_k, t_k, ctl, s_ord, t_ord, type}
% XXX s_k[], t_k[], ctl[][]
Defines a nurbs surface.
The dimensions of
\code{\var{ctl}[][]}
are computed as follows:
\code{[len(\var{s_k}) - \var{s_ord}]},
\code{[len(\var{t_k}) - \var{t_ord}]}.
\end{funcdesc}
\begin{funcdesc}{nurbscurve}{knots, ctlpoints, order, type}
Defines a nurbs curve.
The length of ctlpoints is
\code{len(\var{knots}) - \var{order}}.
\end{funcdesc}
\begin{funcdesc}{pwlcurve}{points, type}
Defines a piecewise-linear curve.
\var{points}
is a list of points.
\var{type}
must be
\code{N_ST}.
\end{funcdesc}
\begin{funcdesc}{pick}{n}
\funcline{select}{n}
The only argument to these functions specifies the desired size of the
pick or select buffer.
\end{funcdesc}
\begin{funcdesc}{endpick}{}
\funcline{endselect}{}
These functions have no arguments.
They return a list of integers representing the used part of the
pick/select buffer.
No method is provided to detect buffer overrun.
\end{funcdesc}
Here is a tiny but complete example GL program in Python:
\begin{verbatim}
import gl, GL, time
def main():
gl.foreground()
gl.prefposition(500, 900, 500, 900)
w = gl.winopen('CrissCross')
gl.ortho2(0.0, 400.0, 0.0, 400.0)
gl.color(GL.WHITE)
gl.clear()
gl.color(GL.RED)
gl.bgnline()
gl.v2f(0.0, 0.0)
gl.v2f(400.0, 400.0)
gl.endline()
gl.bgnline()
gl.v2f(400.0, 0.0)
gl.v2f(0.0, 400.0)
gl.endline()
time.sleep(5)
main()
\end{verbatim}
%
\section{Standard Modules \module{GL} and \module{DEVICE}}
\nodename{GL and DEVICE}
\stmodindex{GL}
\stmodindex{DEVICE}
These modules define the constants used by the Silicon Graphics
\emph{Graphics Library}
that C programmers find in the header files
\file{<gl/gl.h>}
and
\file{<gl/device.h>}.
Read the module source files for details.

35
Doc/libglob.tex
View File

@ -1,35 +0,0 @@
\section{Standard Module \module{glob}}
\label{module-glob}
\stmodindex{glob}
The \module{glob} module finds all the pathnames matching a specified
pattern according to the rules used by the \UNIX{} shell. No tilde
expansion is done, but \code{*}, \code{?}, and character ranges
expressed with \code{[]} will be correctly matched. This is done by
using the \function{os.listdir()} and \function{fnmatch.fnmatch()}
functions in concert, and not by actually invoking a subshell. (For
tilde and shell variable expansion, use \function{os.path.expanduser()}
and \function{os.path.expandvars()}.)
\begin{funcdesc}{glob}{pathname}
Returns a possibly-empty list of path names that match \var{pathname},
which must be a string containing a path specification.
\var{pathname} can be either absolute (like
\file{/usr/src/Python-1.5/Makefile}) or relative (like
\file{../../Tools/*.gif}), and can contain shell-style wildcards.
\end{funcdesc}
For example, consider a directory containing only the following files:
\file{1.gif}, \file{2.txt}, and \file{card.gif}. \function{glob()}
will produce the following results. Notice how any leading components
of the path are preserved.
\begin{verbatim}
>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
>>> glob.glob('*.gif')
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']
\end{verbatim}

31
Doc/libgopherlib.tex
View File

@ -1,31 +0,0 @@
\section{Standard Module \module{gopherlib}}
\label{module-gopherlib}
\stmodindex{gopherlib}
\indexii{Gopher}{protocol}
This module provides a minimal implementation of client side of the
the Gopher protocol. It is used by the module \code{urllib} to handle
URLs that use the Gopher protocol.
The module defines the following functions:
\begin{funcdesc}{send_selector}{selector, host\optional{, port}}
Send a \var{selector} string to the gopher server at \var{host} and
\var{port} (default \code{70}). Returns an open file object from
which the returned document can be read.
\end{funcdesc}
\begin{funcdesc}{send_query}{selector, query, host\optional{, port}}
Send a \var{selector} string and a \var{query} string to a gopher
server at \var{host} and \var{port} (default \code{70}). Returns an
open file object from which the returned document can be read.
\end{funcdesc}
Note that the data returned by the Gopher server can be of any type,
depending on the first character of the selector string. If the data
is text (first character of the selector is \samp{0}), lines are
terminated by CRLF, and the data is terminated by a line consisting of
a single \samp{.}, and a leading \samp{.} should be stripped from
lines that begin with \samp{..}. Directory listings (first character
of the selector is \samp{1}) are transferred using the same protocol.

32
Doc/libgrp.tex
View File

@ -1,32 +0,0 @@
\section{Built-in Module \module{grp}}
\label{module-grp}
\bimodindex{grp}
This module provides access to the \UNIX{} group database.
It is available on all \UNIX{} versions.
Group database entries are reported as 4-tuples containing the
following items from the group database (see \file{<grp.h>}), in order:
\code{gr_name},
\code{gr_passwd},
\code{gr_gid},
\code{gr_mem}.
The gid is an integer, name and password are strings, and the member
list is a list of strings.
(Note that most users are not explicitly listed as members of the
group they are in according to the password database.)
A \code{KeyError} exception is raised if the entry asked for cannot be found.
It defines the following items:
\begin{funcdesc}{getgrgid}{gid}
Return the group database entry for the given numeric group ID.
\end{funcdesc}
\begin{funcdesc}{getgrnam}{name}
Return the group database entry for the given group name.
\end{funcdesc}
\begin{funcdesc}{getgrall}{}
Return a list of all available group entries, in arbitrary order.
\end{funcdesc}

47
Doc/libgzip.tex
View File

@ -1,47 +0,0 @@
\section{Standard Module \module{gzip}}
\label{module-gzip}
\stmodindex{gzip}
The data compression provided by the \code{zlib} module is compatible
with that used by the GNU compression program \program{gzip}.
Accordingly, the \module{gzip} module provides the \class{GzipFile}
class to read and write \program{gzip}-format files, automatically
compressing or decompressing the data so it looks like an ordinary
file object.
\class{GzipFile} objects simulate most of the methods of a file
object, though it's not possible to use the \method{seek()} and
\method{tell()} methods to access the file randomly.
\withsubitem{(class in gzip)}{\ttindex{GzipFile}}
\begin{funcdesc}{open}{fileobj\optional{, filename\optional{,
mode\optional{, compresslevel}}}}
Returns a new \class{GzipFile} object on top of \var{fileobj}, which
can be a regular file, a \class{StringIO} object, or any object which
simulates a file.
The \program{gzip} file format includes the original filename of the
uncompressed file; when opening a \class{GzipFile} object for
writing, it can be set by the \var{filename} argument. The default
value is an empty string.
\var{mode} can be either \code{'r'} or \code{'w'} depending on
whether the file will be read or written. \var{compresslevel} is an
integer from \code{1} to \code{9} controlling the level of
compression; \code{1} is fastest and produces the least compression,
and \code{9} is slowest and produces the most compression. The
default value of \var{compresslevel} is \code{9}.
Calling a \class{GzipFile} object's \method{close()} method does not
close \var{fileobj}, since you might wish to append more material
after the compressed data. This also allows you to pass a
\class{StringIO} object opened for writing as \var{fileobj}, and
retrieve the resulting memory buffer using the \class{StringIO}
object's \method{getvalue()} method.
\end{funcdesc}
\begin{seealso}
\seemodule{zlib}{the basic data compression module}
\end{seealso}

119
Doc/libhtmllib.tex
View File

@ -1,119 +0,0 @@
\section{Standard Module \module{htmllib}}
\label{module-htmllib}
\stmodindex{htmllib}
\index{HTML}
\index{hypertext}
This module defines a class which can serve as a base for parsing text
files formatted in the HyperText Mark-up Language (HTML). The class
is not directly concerned with I/O --- it must be provided with input
in string form via a method, and makes calls to methods of a
``formatter'' object in order to produce output. The
\class{HTMLParser} class is designed to be used as a base class for
other classes in order to add functionality, and allows most of its
methods to be extended or overridden. In turn, this class is derived
from and extends the \class{SGMLParser} class defined in module
\module{sgmllib}\refstmodindex{sgmllib}. The \class{HTMLParser}
implementation supports the HTML 2.0 language as described in
\rfc{1866}. Two implementations of formatter objects are provided in
the \module{formatter}\refstmodindex{formatter} module; refer to the
documentation for that module for information on the formatter
interface.
\index{SGML}
\withsubitem{(in module sgmllib)}{\ttindex{SGMLParser}}
\index{formatter}
The following is a summary of the interface defined by
\class{sgmllib.SGMLParser}:
\begin{itemize}
\item
The interface to feed data to an instance is through the \method{feed()}
method, which takes a string argument. This can be called with as
little or as much text at a time as desired; \samp{p.feed(a);
p.feed(b)} has the same effect as \samp{p.feed(a+b)}. When the data
contains complete HTML tags, these are processed immediately;
incomplete elements are saved in a buffer. To force processing of all
unprocessed data, call the \method{close()} method.
For example, to parse the entire contents of a file, use:
\begin{verbatim}
parser.feed(open('myfile.html').read())
parser.close()
\end{verbatim}
\item
The interface to define semantics for HTML tags is very simple: derive
a class and define methods called \code{start_\var{tag}()},
\code{end_\var{tag}()}, or \code{do_\var{tag}()}. The parser will
call these at appropriate moments: \code{start_\var{tag}} or
\code{do_\var{tag}()} is called when an opening tag of the form
\code{<\var{tag} ...>} is encountered; \code{end_\var{tag}()} is called
when a closing tag of the form \code{<\var{tag}>} is encountered. If
an opening tag requires a corresponding closing tag, like \code{<H1>}
... \code{</H1>}, the class should define the \code{start_\var{tag}()}
method; if a tag requires no closing tag, like \code{<P>}, the class
should define the \code{do_\var{tag}()} method.
\end{itemize}
The module defines a single class:
\begin{classdesc}{HTMLParser}{formatter}
This is the basic HTML parser class. It supports all entity names
required by the HTML 2.0 specification (\rfc{1866}). It also defines
handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
\end{classdesc}
In addition to tag methods, the \class{HTMLParser} class provides some
additional methods and instance variables for use within tag methods.
\begin{memberdesc}{formatter}
This is the formatter instance associated with the parser.
\end{memberdesc}
\begin{memberdesc}{nofill}
Boolean flag which should be true when whitespace should not be
collapsed, or false when it should be. In general, this should only
be true when character data is to be treated as ``preformatted'' text,
as within a \code{<PRE>} element. The default value is false. This
affects the operation of \method{handle_data()} and \method{save_end()}.
\end{memberdesc}
\begin{methoddesc}{anchor_bgn}{href, name, type}
This method is called at the start of an anchor region. The arguments
correspond to the attributes of the \code{<A>} tag with the same
names. The default implementation maintains a list of hyperlinks
(defined by the \code{href} attribute) within the document. The list
of hyperlinks is available as the data attribute \code{anchorlist}.
\end{methoddesc}
\begin{methoddesc}{anchor_end}{}
This method is called at the end of an anchor region. The default
implementation adds a textual footnote marker using an index into the
list of hyperlinks created by \method{anchor_bgn()}.
\end{methoddesc}
\begin{methoddesc}{handle_image}{source, alt\optional{, ismap\optional{, align\optional{, width\optional{, height}}}}}
This method is called to handle images. The default implementation
simply passes the \var{alt} value to the \method{handle_data()}
method.
\end{methoddesc}
\begin{methoddesc}{save_bgn}{}
Begins saving character data in a buffer instead of sending it to the
formatter object. Retrieve the stored data via \method{save_end()}.
Use of the \method{save_bgn()} / \method{save_end()} pair may not be
nested.
\end{methoddesc}
\begin{methoddesc}{save_end}{}
Ends buffering character data and returns all data saved since the
preceeding call to \method{save_bgn()}. If the \code{nofill} flag is
false, whitespace is collapsed to single spaces. A call to this
method without a preceeding call to \method{save_bgn()} will raise a
\exception{TypeError} exception.
\end{methoddesc}

129
Doc/libhttplib.tex
View File

@ -1,129 +0,0 @@
\section{Standard Module \module{httplib}}
\label{module-httplib}
\stmodindex{httplib}
\indexii{HTTP}{protocol}
This module defines a class which implements the client side of the
HTTP protocol. It is normally not used directly --- the module
\module{urllib}\refstmodindex{urllib} uses it to handle URLs that use
HTTP.
The module defines one class, \class{HTTP}:
\begin{classdesc}{HTTP}{\optional{host\optional{, port}}}
An \class{HTTP} instance
represents one transaction with an HTTP server. It should be
instantiated passing it a host and optional port number. If no port
number is passed, the port is extracted from the host string if it has
the form \code{\var{host}:\var{port}}, else the default HTTP port (80)
is used. If no host is passed, no connection is made, and the
\method{connect()} method should be used to connect to a server. For
example, the following calls all create instances that connect to the
server at the same host and port:
\begin{verbatim}
>>> h1 = httplib.HTTP('www.cwi.nl')
>>> h2 = httplib.HTTP('www.cwi.nl:80')
>>> h3 = httplib.HTTP('www.cwi.nl', 80)
\end{verbatim}
Once an \class{HTTP} instance has been connected to an HTTP server, it
should be used as follows:
\begin{enumerate}
\item[1.] Make exactly one call to the \method{putrequest()} method.
\item[2.] Make zero or more calls to the \method{putheader()} method.
\item[3.] Call the \method{endheaders()} method (this can be omitted if
step 4 makes no calls).
\item[4.] Optional calls to the \method{send()} method.
\item[5.] Call the \method{getreply()} method.
\item[6.] Call the \method{getfile()} method and read the data off the
file object that it returns.
\end{enumerate}
\end{classdesc}
\subsection{HTTP Objects}
\class{HTTP} instances have the following methods:
\begin{methoddesc}{set_debuglevel}{level}
Set the debugging level (the amount of debugging output printed).
The default debug level is \code{0}, meaning no debugging output is
printed.
\end{methoddesc}
\begin{methoddesc}{connect}{host\optional{, port}}
Connect to the server given by \var{host} and \var{port}. See the
intro for the default port. This should be called directly only if
the instance was instantiated without passing a host.
\end{methoddesc}
\begin{methoddesc}{send}{data}
Send data to the server. This should be used directly only after the
\method{endheaders()} method has been called and before
\method{getreply()} has been called.
\end{methoddesc}
\begin{methoddesc}{putrequest}{request, selector}
This should be the first call after the connection to the server has
been made. It sends a line to the server consisting of the
\var{request} string, the \var{selector} string, and the HTTP version
(\code{HTTP/1.0}).
\end{methoddesc}
\begin{methoddesc}{putheader}{header, argument\optional{, ...}}
Send an \rfc{822} style header to the server. It sends a line to the
server consisting of the header, a colon and a space, and the first
argument. If more arguments are given, continuation lines are sent,
each consisting of a tab and an argument.
\end{methoddesc}
\begin{methoddesc}{endheaders}{}
Send a blank line to the server, signalling the end of the headers.
\end{methoddesc}
\begin{methoddesc}{getreply}{}
Complete the request by shutting down the sending end of the socket,
read the reply from the server, and return a triple
\code{(\var{replycode}, \var{message}, \var{headers})}. Here,
\var{replycode} is the integer reply code from the request (e.g.\
\code{200} if the request was handled properly); \var{message} is the
message string corresponding to the reply code; and \var{headers} is
an instance of the class \class{mimetools.Message} containing the
headers received from the server. See the description of the
\module{mimetools}\refstmodindex{mimetools} module.
\end{methoddesc}
\begin{methoddesc}{getfile}{}
Return a file object from which the data returned by the server can be
read, using the \method{read()}, \method{readline()} or
\method{readlines()} methods.
\end{methoddesc}
\subsection{Example}
\nodename{HTTP Example}
Here is an example session:
\begin{verbatim}
>>> import httplib
>>> h = httplib.HTTP('www.cwi.nl')
>>> h.putrequest('GET', '/index.html')
>>> h.putheader('Accept', 'text/html')
>>> h.putheader('Accept', 'text/plain')
>>> h.endheaders()
>>> errcode, errmsg, headers = h.getreply()
>>> print errcode # Should be 200
>>> f = h.getfile()
>>> data = f.read() # Get the raw HTML
>>> f.close()
\end{verbatim}

85
Doc/libimageop.tex
View File

@ -1,85 +0,0 @@
\section{Built-in Module \module{imageop}}
\label{module-imageop}
\bimodindex{imageop}
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.
The module defines the following variables and functions:
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bits
per pixel, etc.
\end{excdesc}
\begin{funcdesc}{crop}{image, psize, width, height, x0, y0, x1, y1}
Return the selected part of \var{image}, which should by
\var{width} by \var{height} in size and consist of pixels of
\var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like
the \function{gl.lrectread()} parameters, i.e.\ the boundary is
included in the new image. The new boundaries need not be inside the
picture. Pixels that fall outside the old image will have their value
set to zero. If \var{x0} is bigger than \var{x1} the new image is
mirrored. The same holds for the y coordinates.
\end{funcdesc}
\begin{funcdesc}{scale}{image, psize, width, height, newwidth, newheight}
Return \var{image} scaled to size \var{newwidth} by \var{newheight}.
No interpolation is done, scaling is done by simple-minded pixel
duplication or removal. Therefore, computer-generated images or
dithered images will not look nice after scaling.
\end{funcdesc}
\begin{funcdesc}{tovideo}{image, psize, width, height}
Run a vertical low-pass filter over an image. It does so by computing
each destination pixel as the average of two vertically-aligned source
pixels. The main use of this routine is to forestall excessive
flicker if the image is displayed on a video device that uses
interlacing, hence the name.
\end{funcdesc}
\begin{funcdesc}{grey2mono}{image, width, height, threshold}
Convert a 8-bit deep greyscale image to a 1-bit deep image by
tresholding all the pixels. The resulting image is tightly packed and
is probably only useful as an argument to \function{mono2grey()}.
\end{funcdesc}
\begin{funcdesc}{dither2mono}{image, width, height}
Convert an 8-bit greyscale image to a 1-bit monochrome image using a
(simple-minded) dithering algorithm.
\end{funcdesc}
\begin{funcdesc}{mono2grey}{image, width, height, p0, p1}
Convert a 1-bit monochrome image to an 8 bit greyscale or color image.
All pixels that are zero-valued on input get value \var{p0} on output
and all one-value input pixels get value \var{p1} on output. To
convert a monochrome black-and-white image to greyscale pass the
values \code{0} and \code{255} respectively.
\end{funcdesc}
\begin{funcdesc}{grey2grey4}{image, width, height}
Convert an 8-bit greyscale image to a 4-bit greyscale image without
dithering.
\end{funcdesc}
\begin{funcdesc}{grey2grey2}{image, width, height}
Convert an 8-bit greyscale image to a 2-bit greyscale image without
dithering.
\end{funcdesc}
\begin{funcdesc}{dither2grey2}{image, width, height}
Convert an 8-bit greyscale image to a 2-bit greyscale image with
dithering. As for \function{dither2mono()}, the dithering algorithm
is currently very simple.
\end{funcdesc}
\begin{funcdesc}{grey42grey}{image, width, height}
Convert a 4-bit greyscale image to an 8-bit greyscale image.
\end{funcdesc}
\begin{funcdesc}{grey22grey}{image, width, height}
Convert a 2-bit greyscale image to an 8-bit greyscale image.
\end{funcdesc}

241
Doc/libimaplib.tex
View File

@ -1,241 +0,0 @@
% Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
%
% The imaplib module was written by Piers Lauder.
\section{Standard Module \module{imaplib}}
\stmodindex{imaplib}
\label{module-imaplib}
\indexii{IMAP4}{protocol}
This module defines a class, \class{IMAP4}, which encapsulates a
connection to an IMAP4 server and implements the IMAP4rev1 client
protocol as defined in \rfc{2060}. It is backward compatible with
IMAP4 (\rfc{1730}) servers, but note that the \samp{STATUS} command is
not supported in IMAP4.
A single class is provided by the \code{imaplib} module:
\begin{classdesc}{IMAP4}{\optional{host\optional{, port}}}
This class implements the actual IMAP4 protocol. The connection is
created and protocol version (IMAP4 or IMAP4rev1) is determined when
the instance is initialized.
If \var{host} is not specified, \code{''} (the local host) is used.
If \var{port} is omitted, the standard IMAP4 port (143) is used.
\end{classdesc}
Two exceptions are defined as attributes of the \class{IMAP4} class:
\begin{excdesc}{IMAP4.error}
Exception raised on any errors. The reason for the exception is
passed to the constructor as a string.
\end{excdesc}
\begin{excdesc}{IMAP4.abort}
IMAP4 server errors cause this exception to be raised. This is a
sub-class of \exception{IMAP4.error}. Note that closing the instance
and instantiating a new one will usually allow recovery from this
exception.
\end{excdesc}
The following utility functions are defined:
\begin{funcdesc}{Internaldate2tuple}{datestr}
Converts an IMAP4 INTERNALDATE string to Coordinated Universal
Time. Returns a \module{time} module tuple.
\end{funcdesc}
\begin{funcdesc}{Int2AP}{num}
Converts an integer into a string representation using characters
from the set [\code{A} .. \code{P}].
\end{funcdesc}
\begin{funcdesc}{ParseFlags}{flagstr}
Converts an IMAP4 \samp{FLAGS} response to a tuple of individual
flags.
\end{funcdesc}
\begin{funcdesc}{Time2Internaldate}{date_time}
Converts a \module{time} module tuple to an IMAP4
\samp{INTERNALDATE} representation. Returns a string in the form:
\code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes).
\end{funcdesc}
\subsection{IMAP4 Objects}
\label{imap4-objects}
All IMAP4rev1 commands are represented by methods of the same name,
either upper-case or lower-case.
Each command returns a tuple: \code{(}\var{type}, \code{[}\var{data},
...\code{])} where \var{type} is usually \code{'OK'} or \code{'NO'},
and \var{data} is either the text from the command response, or
mandated results from the command.
An \class{IMAP4} instance has the following methods:
\begin{methoddesc}{append}{mailbox, flags, date_time, message}
Append message to named mailbox.
\end{methoddesc}
\begin{methoddesc}{authenticate}{func}
Authenticate command --- requires response processing. This is
currently unimplemented, and raises an exception.
\end{methoddesc}
\begin{methoddesc}{check}{}
Checkpoint mailbox on server.
\end{methoddesc}
\begin{methoddesc}{close}{}
Close currently selected mailbox. Deleted messages are removed from
writable mailbox. This is the recommended command before
\samp{LOGOUT}.
\end{methoddesc}
\begin{methoddesc}{copy}{message_set, new_mailbox}
Copy \var{message_set} messages onto end of \var{new_mailbox}.
\end{methoddesc}
\begin{methoddesc}{create}{mailbox}
Create new mailbox named \var{mailbox}.
\end{methoddesc}
\begin{methoddesc}{delete}{mailbox}
Delete old mailbox named \var{mailbox}.
\end{methoddesc}
\begin{methoddesc}{expunge}{}
Permanently remove deleted items from selected mailbox. Generates an
\samp{EXPUNGE} response for each deleted message. Returned data
contains a list of \samp{EXPUNGE} message numbers in order
received.
\end{methoddesc}
\begin{methoddesc}{fetch}{message_set, message_parts}
Fetch (parts of) messages. Returned data are tuples of message part
envelope and data.
\end{methoddesc}
\begin{methoddesc}{list}{\optional{directory\optional{, pattern}}}
List mailbox names in \var{directory} matching
\var{pattern}. \var{directory} defaults to the top-level mail
folder, and \var{pattern} defaults to match anything. Returned data
contains a list of \samp{LIST} responses.
\end{methoddesc}
\begin{methoddesc}{login}{user, password}
Identify the client using a plaintext password.
\end{methoddesc}
\begin{methoddesc}{logout}{}
Shutdown connection to server. Returns server \samp{BYE} response.
\end{methoddesc}
\begin{methoddesc}{lsub}{\optional{directory\optional{, pattern}}}
List subscribed mailbox names in directory matching pattern.
\var{directory} defaults to the top level directory and
\var{pattern} defaults to match any mailbox.
Returned data are tuples of message part envelope and data.
\end{methoddesc}
\begin{methoddesc}{recent}{}
Prompt server for an update. Returned data is \code{None} if no new
messages, else value of \samp{RECENT} response.
\end{methoddesc}
\begin{methoddesc}{rename}{oldmailbox, newmailbox}
Rename mailbox named \var{oldmailbox} to \var{newmailbox}.
\end{methoddesc}
\begin{methoddesc}{response}{code}
Return data for response \var{code} if received, or
\code{None}. Returns the given code, instead of the usual type.
\end{methoddesc}
\begin{methoddesc}{search}{charset, criteria}
Search mailbox for matching messages. Returned data contains a space
separated list of matching message numbers.
\end{methoddesc}
\begin{methoddesc}{select}{\optional{mailbox\optional{, readonly}}}
Select a mailbox. Returned data is the count of messages in
\var{mailbox} (\samp{EXISTS} response). The default \var{mailbox}
is \code{'INBOX'}. If the \var{readonly} flag is set, modifications
to the mailbox are not allowed.
\end{methoddesc}
\begin{methoddesc}{status}{mailbox, names}
Request named status conditions for \var{mailbox}.
\end{methoddesc}
\begin{methoddesc}{store}{message_set, command, flag_list}
Alters flag dispositions for messages in mailbox.
\end{methoddesc}
\begin{methoddesc}{subscribe}{mailbox}
Subscribe to new mailbox.
\end{methoddesc}
\begin{methoddesc}{uid}{command, args}
Execute command args with messages identified by UID, rather than
message number. Returns response appropriate to command.
\end{methoddesc}
\begin{methoddesc}{unsubscribe}{mailbox}
Unsubscribe from old mailbox.
\end{methoddesc}
\begin{methoddesc}{xatom}{name\optional{, arg1\optional{, arg2}}}
Allow simple extension commands notified by server in
\samp{CAPABILITY} response.
\end{methoddesc}
The following attributes are defined on instances of \class{IMAP4}:
\begin{memberdesc}{PROTOCOL_VERSION}
The most recent supported protocol in the \samp{CAPABILITY}
response from the server.
\end{memberdesc}
\begin{memberdesc}{debug}
Integer value to control debugging output. The initialize value is
taken from the module variable \code{Debug}. Values greater than
three trace each command.
\end{memberdesc}
\subsection{IMAP4 Example}
\label{imap4-example}
Here is a minimal example (without error checking) that opens a
mailbox and retrieves and prints all messages:
\begin{verbatim}
import getpass, imaplib, string
M = imaplib.IMAP4()
M.LOGIN(getpass.getuser(), getpass.getpass())
M.SELECT()
typ, data = M.SEARCH(None, 'ALL')
for num in string.split(data[0]):
typ, data = M.FETCH(num, '(RFC822)')
print 'Message %s\n%s\n' % (num, data[0][1])
M.LOGOUT()
\end{verbatim}
Note that IMAP4 message numbers change as the mailbox changes, so it
is highly advisable to use UIDs instead, with the UID command.
At the end of the module, there is a test section that contains a more
extensive example of usage.
\begin{seealso}
\seetext{Documents describing the protocol, and sources and binaries
for servers implementing it, can all be found at the University of
Washington's \emph{IMAP Information Center}
(\url{http://www.cac.washington.edu/imap/}).}
\end{seealso}

62
Doc/libimgfile.tex
View File

@ -1,62 +0,0 @@
\section{Built-in Module \module{imgfile}}
\label{module-imgfile}
\bimodindex{imgfile}
The \module{imgfile} module allows Python programs to access SGI imglib image
files (also known as \file{.rgb} files). The module is far from
complete, but is provided anyway since the functionality that there is
is enough in some cases. Currently, colormap files are not supported.
The module defines the following variables and functions:
\begin{excdesc}{error}
This exception is raised on all errors, such as unsupported file type, etc.
\end{excdesc}
\begin{funcdesc}{getsizes}{file}
This function returns a tuple \code{(\var{x}, \var{y}, \var{z})} where
\var{x} and \var{y} are the size of the image in pixels and
\var{z} is the number of
bytes per pixel. Only 3 byte RGB pixels and 1 byte greyscale pixels
are currently supported.
\end{funcdesc}
\begin{funcdesc}{read}{file}
This function reads and decodes the image on the specified file, and
returns it as a Python string. The string has either 1 byte greyscale
pixels or 4 byte RGBA pixels. The bottom left pixel is the first in
the string. This format is suitable to pass to \function{gl.lrectwrite()},
for instance.
\end{funcdesc}
\begin{funcdesc}{readscaled}{file, x, y, filter\optional{, blur}}
This function is identical to read but it returns an image that is
scaled to the given \var{x} and \var{y} sizes. If the \var{filter} and
\var{blur} parameters are omitted scaling is done by
simply dropping or duplicating pixels, so the result will be less than
perfect, especially for computer-generated images.
Alternatively, you can specify a filter to use to smoothen the image
after scaling. The filter forms supported are \code{'impulse'},
\code{'box'}, \code{'triangle'}, \code{'quadratic'} and
\code{'gaussian'}. If a filter is specified \var{blur} is an optional
parameter specifying the blurriness of the filter. It defaults to \code{1.0}.
\function{readscaled()} makes no attempt to keep the aspect ratio
correct, so that is the users' responsibility.
\end{funcdesc}
\begin{funcdesc}{ttob}{flag}
This function sets a global flag which defines whether the scan lines
of the image are read or written from bottom to top (flag is zero,
compatible with SGI GL) or from top to bottom(flag is one,
compatible with X). The default is zero.
\end{funcdesc}
\begin{funcdesc}{write}{file, data, x, y, z}
This function writes the RGB or greyscale data in \var{data} to image
file \var{file}. \var{x} and \var{y} give the size of the image,
\var{z} is 1 for 1 byte greyscale images or 3 for RGB images (which are
stored as 4 byte values of which only the lower three bytes are used).
These are the formats returned by \function{gl.lrectread()}.
\end{funcdesc}

52
Doc/libimghdr.tex
View File

@ -1,52 +0,0 @@
\section{Standard Module \module{imghdr}}
\label{module-imghdr}
\stmodindex{imghdr}
The \module{imghdr} module determines the type of image contained in a
file or byte stream.
The \module{imghdr} module defines the following function:
\begin{funcdesc}{what}{filename\optional{, h}}
Tests the image data contained in the file named by \var{filename},
and returns a string describing the image type. If optional \var{h}
is provided, the \var{filename} is ignored and \var{h} is assumed to
contain the byte stream to test.
\end{funcdesc}
The following image types are recognized, as listed below with the
return value from \function{what()}:
\begin{tableii}{l|l}{code}{Value}{Image format}
\lineii{'rgb'}{SGI ImgLib Files}
\lineii{'gif'}{GIF 87a and 89a Files}
\lineii{'pbm'}{Portable Bitmap Files}
\lineii{'pgm'}{Portable Graymap Files}
\lineii{'ppm'}{Portable Pixmap Files}
\lineii{'tiff'}{TIFF Files}
\lineii{'rast'}{Sun Raster Files}
\lineii{'xbm'}{X Bitmap Files}
\lineii{'jpeg'}{JPEG data in JIFF format}
\end{tableii}
You can extend the list of file types \module{imghdr} can recognize by
appending to this variable:
\begin{datadesc}{tests}
A list of functions performing the individual tests. Each function
takes two arguments: the byte-stream and an open file-like object.
When \function{what()} is called with a byte-stream, the file-like
object will be \code{None}.
The test function should return a string describing the image type if
the test succeeded, or \code{None} if it failed.
\end{datadesc}
Example:
\begin{verbatim}
>>> import imghdr
>>> imghdr.what('/tmp/bass.gif')
'gif'
\end{verbatim}

241
Doc/libimp.tex
View File

@ -1,241 +0,0 @@
\section{Built-in Module \module{imp}}
\label{module-imp}
\bimodindex{imp}
\index{import}
This module provides an interface to the mechanisms used to implement
the \keyword{import} statement. It defines the following constants and
functions:
\begin{funcdesc}{get_magic}{}
Return the magic string value used to recognize byte-compiled code
files (``\code{.pyc} files''). (This value may be different for each
Python version.)
\end{funcdesc}
\begin{funcdesc}{get_suffixes}{}
Return a list of triples, each describing a particular type of module.
Each triple has the form \code{(\var{suffix}, \var{mode},
\var{type})}, where \var{suffix} is a string to be appended to the
module name to form the filename to search for, \var{mode} is the mode
string to pass to the built-in \code{open} function to open the file
(this can be \code{'r'} for text files or \code{'rb'} for binary
files), and \var{type} is the file type, which has one of the values
\constant{PY_SOURCE}, \constant{PY_COMPILED}, or
\constant{C_EXTENSION}, described below.
\end{funcdesc}
\begin{funcdesc}{find_module}{name\optional{, path}}
Try to find the module \var{name} on the search path \var{path}. If
\var{path} is a list of directory names, each directory is searched
for files with any of the suffixes returned by \function{get_suffixes()}
above. Invalid names in the list are silently ignored (but all list
items must be strings). If \var{path} is omitted or \code{None}, the
list of directory names given by \code{sys.path} is searched, but
first it searches a few special places: it tries to find a built-in
module with the given name (\constant{C_BUILTIN}), then a frozen module
(\constant{PY_FROZEN}), and on some systems some other places are looked
in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE});
on Windows, it looks in the registry which may point to a specific
file).
If search is successful, the return value is a triple
\code{(\var{file}, \var{pathname}, \var{description})} where
\var{file} is an open file object positioned at the beginning,
\var{pathname} is the pathname of the
file found, and \var{description} is a triple as contained in the list
returned by \function{get_suffixes()} describing the kind of module found.
If the module does not live in a file, the returned \var{file} is
\code{None}, \var{filename} is the empty string, and the
\var{description} tuple contains empty strings for its suffix and
mode; the module type is as indicate in parentheses dabove. If the
search is unsuccessful, \exception{ImportError} is raised. Other
exceptions indicate problems with the arguments or environment.
This function does not handle hierarchical module names (names
containing dots). In order to find \var{P}.\var{M}, i.e., submodule
\var{M} of package \var{P}, use \function{find_module()} and
\function{load_module()} to find and load package \var{P}, and then use
\function{find_module()} with the \var{path} argument set to
\code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply
this recipe recursively.
\end{funcdesc}
\begin{funcdesc}{load_module}{name, file, filename, description}
Load a module that was previously found by \function{find_module()} (or by
an otherwise conducted search yielding compatible results). This
function does more than importing the module: if the module was
already imported, it is equivalent to a
\function{reload()}\bifuncindex{reload}! The
\var{name} argument indicates the full module name (including the
package name, if this is a submodule of a package). The \var{file}
argument is an open file, and \var{filename} is the corresponding
file name; these can be \code{None} and \code{''}, respectively, when
the module is not being loaded from a file. The \var{description}
argument is a tuple as returned by \function{find_module()} describing
what kind of module must be loaded.
If the load is successful, the return value is the module object;
otherwise, an exception (usually \exception{ImportError}) is raised.
\strong{Important:} the caller is responsible for closing the
\var{file} argument, if it was not \code{None}, even when an exception
is raised. This is best done using a \keyword{try}
... \keyword{finally} statement.
\end{funcdesc}
\begin{funcdesc}{new_module}{name}
Return a new empty module object called \var{name}. This object is
\emph{not} inserted in \code{sys.modules}.
\end{funcdesc}
The following constants with integer values, defined in this module,
are used to indicate the search result of \function{find_module()}.
\begin{datadesc}{PY_SOURCE}
The module was found as a source file.
\end{datadesc}
\begin{datadesc}{PY_COMPILED}
The module was found as a compiled code object file.
\end{datadesc}
\begin{datadesc}{C_EXTENSION}
The module was found as dynamically loadable shared library.
\end{datadesc}
\begin{datadesc}{PY_RESOURCE}
The module was found as a Macintosh resource. This value can only be
returned on a Macintosh.
\end{datadesc}
\begin{datadesc}{PKG_DIRECTORY}
The module was found as a package directory.
\end{datadesc}
\begin{datadesc}{C_BUILTIN}
The module was found as a built-in module.
\end{datadesc}
\begin{datadesc}{PY_FROZEN}
The module was found as a frozen module (see \function{init_frozen()}).
\end{datadesc}
The following constant and functions are obsolete; their functionality
is available through \function{find_module()} or \function{load_module()}.
They are kept around for backward compatibility:
\begin{datadesc}{SEARCH_ERROR}
Unused.
\end{datadesc}
\begin{funcdesc}{init_builtin}{name}
Initialize the built-in module called \var{name} and return its module
object. If the module was already initialized, it will be initialized
\emph{again}. A few modules cannot be initialized twice --- attempting
to initialize these again will raise an \exception{ImportError}
exception. If there is no
built-in module called \var{name}, \code{None} is returned.
\end{funcdesc}
\begin{funcdesc}{init_frozen}{name}
Initialize the frozen module called \var{name} and return its module
object. If the module was already initialized, it will be initialized
\emph{again}. If there is no frozen module called \var{name},
\code{None} is returned. (Frozen modules are modules written in
Python whose compiled byte-code object is incorporated into a
custom-built Python interpreter by Python's \program{freeze} utility.
See \file{Tools/freeze/} for now.)
\end{funcdesc}
\begin{funcdesc}{is_builtin}{name}
Return \code{1} if there is a built-in module called \var{name} which
can be initialized again. Return \code{-1} if there is a built-in
module called \var{name} which cannot be initialized again (see
\function{init_builtin()}). Return \code{0} if there is no built-in
module called \var{name}.
\end{funcdesc}
\begin{funcdesc}{is_frozen}{name}
Return \code{1} if there is a frozen module (see
\function{init_frozen()}) called \var{name}, or \code{0} if there is
no such module.
\end{funcdesc}
\begin{funcdesc}{load_compiled}{name, pathname, file}
Load and initialize a module implemented as a byte-compiled code file
and return its module object. If the module was already initialized,
it will be initialized \emph{again}. The \var{name} argument is used
to create or access a module object. The \var{pathname} argument
points to the byte-compiled code file. The \var{file}
argument is the byte-compiled code file, open for reading in binary
mode, from the beginning.
It must currently be a real file object, not a
user-defined class emulating a file.
\end{funcdesc}
\begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}}
Load and initialize a module implemented as a dynamically loadable
shared library and return its module object. If the module was
already initialized, it will be initialized \emph{again}. Some modules
don't like that and may raise an exception. The \var{pathname}
argument must point to the shared library. The \var{name} argument is
used to construct the name of the initialization function: an external
C function called \samp{init\var{name}()} in the shared library is
called. The optional \var{file} argment is ignored. (Note: using
shared libraries is highly system dependent, and not all systems
support it.)
\end{funcdesc}
\begin{funcdesc}{load_source}{name, pathname, file}
Load and initialize a module implemented as a Python source file and
return its module object. If the module was already initialized, it
will be initialized \emph{again}. The \var{name} argument is used to
create or access a module object. The \var{pathname} argument points
to the source file. The \var{file} argument is the source
file, open for reading as text, from the beginning.
It must currently be a real file
object, not a user-defined class emulating a file. Note that if a
properly matching byte-compiled file (with suffix \file{.pyc}) exists,
it will be used instead of parsing the given source file.
\end{funcdesc}
\subsection{Examples}
\label{examples-imp}
The following function emulates what was the standard import statement
up to Python 1.4 (i.e., no hierarchical module names). (This
\emph{implementation} wouldn't work in that version, since
\function{find_module()} has been extended and
\function{load_module()} has been added in 1.4.)
\begin{verbatim}
import imp import sys
def __import__(name, globals=None, locals=None, fromlist=None):
# Fast path: see if the module has already been imported.
try:
return sys.modules[name]
except KeyError:
pass
# If any of the following calls raises an exception,
# there's a problem we can't handle -- let the caller handle it.
fp, pathname, description = imp.find_module(name)
try:
return imp.load_module(name, fp, pathname, description)
finally:
# Since we may exit via an exception, close fp explicitly.
if fp:
fp.close()
\end{verbatim}
A more complete example that implements hierarchical module names and
includes a \function{reload()}\bifuncindex{reload} function can be
found in the standard module \module{knee}\refstmodindex{knee} (which
is intended as an example only --- don't rely on any part of it being
a standard interface).

48
Doc/libintro.tex
View File

@ -1,48 +0,0 @@
\chapter{Introduction}
\label{intro}
The ``Python library'' contains several different kinds of components.
It contains data types that would normally be considered part of the
``core'' of a language, such as numbers and lists. For these types,
the Python language core defines the form of literals and places some
constraints on their semantics, but does not fully define the
semantics. (On the other hand, the language core does define
syntactic properties like the spelling and priorities of operators.)
The library also contains built-in functions and exceptions ---
objects that can be used by all Python code without the need of an
\keyword{import} statement. Some of these are defined by the core
language, but many are not essential for the core semantics and are
only described here.
The bulk of the library, however, consists of a collection of modules.
There are many ways to dissect this collection. Some modules are
written in C and built in to the Python interpreter; others are
written in Python and imported in source form. Some modules provide
interfaces that are highly specific to Python, like printing a stack
trace; some provide interfaces that are specific to particular
operating systems, like socket I/O; others provide interfaces that are
specific to a particular application domain, like the World-Wide Web.
Some modules are avaiable in all versions and ports of Python; others
are only available when the underlying system supports or requires
them; yet others are available only when a particular configuration
option was chosen at the time when Python was compiled and installed.
This manual is organized ``from the inside out'': it first describes
the built-in data types, then the built-in functions and exceptions,
and finally the modules, grouped in chapters of related modules. The
ordering of the chapters as well as the ordering of the modules within
each chapter is roughly from most relevant to least important.
This means that if you start reading this manual from the start, and
skip to the next chapter when you get bored, you will get a reasonable
overview of the available modules and application areas that are
supported by the Python library. Of course, you don't \emph{have} to
read it like a novel --- you can also browse the table of contents (in
front of the manual), or look for a specific function, module or term
in the index (in the back). And finally, if you enjoy learning about
random subjects, you choose a random page number (see module
\module{rand}) and read a section or two.
Let the show begin!

57
Doc/libjpeg.tex
View File

@ -1,57 +0,0 @@
\section{Built-in Module \module{jpeg}}
\label{module-jpeg}
\bimodindex{jpeg}
The module \module{jpeg} provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group%
\index{Independent JPEG Group}%
. JPEG is a (draft?)
standard for compressing pictures. For details on JPEG or the
Independent JPEG Group software refer to the JPEG standard or the
documentation provided with the software.
The \module{jpeg} module defines an exception and some functions.
\begin{excdesc}{error}
Exception raised by \function{compress()} and \function{decompress()}
in case of errors.
\end{excdesc}
\begin{funcdesc}{compress}{data, w, h, b}
Treat data as a pixmap of width \var{w} and height \var{h}, with
\var{b} bytes per pixel. The data is in SGI GL order, so the first
pixel is in the lower-left corner. This means that \function{gl.lrectread()}
return data can immediately be passed to \function{compress()}.
Currently only 1 byte and 4 byte pixels are allowed, the former being
treated as greyscale and the latter as RGB color.
\function{compress()} returns a string that contains the compressed
picture, in JFIF\index{JFIF} format.
\end{funcdesc}
\begin{funcdesc}{decompress}{data}
Data is a string containing a picture in JFIF\index{JFIF} format. It
returns a tuple \code{(\var{data}, \var{width}, \var{height},
\var{bytesperpixel})}. Again, the data is suitable to pass to
\function{gl.lrectwrite()}.
\end{funcdesc}
\begin{funcdesc}{setoption}{name, value}
Set various options. Subsequent \function{compress()} and
\function{decompress()} calls will use these options. The following
options are available:
\begin{tableii}{l|p{3in}}{code}{Option}{Effect}
\lineii{'forcegray'}{%
Force output to be grayscale, even if input is RGB.}
\lineii{'quality'}{%
Set the quality of the compressed image to a value between
\code{0} and \code{100} (default is \code{75}). This only affects
compression.}
\lineii{'optimize'}{%
Perform Huffman table optimization. Takes longer, but results in
smaller compressed image. This only affects compression.}
\lineii{'smooth'}{%
Perform inter-block smoothing on uncompressed image. Only useful
for low-quality images. This only affects decompression.}
\end{tableii}
\end{funcdesc}

10
Doc/libkeyword.tex
View File

@ -1,10 +0,0 @@
\section{Standard Module \module{keyword}}
\label{module-keyword}
\stmodindex{keyword}
This module allows a Python program to determine if a string is a
keyword. A single function is provided:
\begin{funcdesc}{iskeyword}{s}
Return true if \var{s} is a Python keyword.
\end{funcdesc}

274
Doc/liblocale.tex
View File

@ -1,274 +0,0 @@
\section{Standard Module \module{locale}}
\stmodindex{locale}
\label{module-locale}
The \code{locale} module opens access to the \POSIX{} locale database
and functionality. The \POSIX{} locale mechanism allows applications
to integrate certain cultural aspects into an applications, without
requiring the programmer to know all the specifics of each country
where the software is executed.
The \module{locale} module is implemented on top of the
\module{_locale}\refbimodindex{_locale} module, which in turn uses an
ANSI \C{} locale implementation if available.
The \module{locale} module defines the following exception and
functions:
\begin{funcdesc}{setlocale}{category\optional{, value}}
If \var{value} is specified, modifies the locale setting for the
\var{category}. The available categories are listed in the data
description below. The value is the name of a locale. An empty string
specifies the user's default settings. If the modification of the
locale fails, the exception \exception{Error} is
raised. If successful, the new locale setting is returned.
If no \var{value} is specified, the current setting for the
\var{category} is returned.
\function{setlocale()} is not thread safe on most systems. Applications
typically start with a call of
\begin{verbatim}
import locale
locale.setlocale(locale.LC_ALL,"")
\end{verbatim}
This sets the locale for all categories to the user's default setting
(typically specified in the \code{LANG} environment variable). If the
locale is not changed thereafter, using multithreading should not
cause problems.
\end{funcdesc}
\begin{excdesc}{Error}
Exception raised when \function{setlocale()} fails.
\end{excdesc}
\begin{funcdesc}{localeconv}{}
Returns the database of of the local conventions as a dictionary. This
dictionary has the following strings as keys:
\begin{itemize}
\item \code{decimal_point} specifies the decimal point used in
floating point number representations for the \code{LC_NUMERIC}
category.
\item \code{grouping} is a sequence of numbers specifying at which
relative positions the \code{thousands_sep} is expected. If the
sequence is terminated with \code{locale.CHAR_MAX}, no further
grouping is performed. If the sequence terminates with a \code{0}, the last
group size is repeatedly used.
\item \code{thousands_sep} is the character used between groups.
\item \code{int_curr_symbol} specifies the international currency
symbol from the \code{LC_MONETARY} category.
\item \code{currency_symbol} is the local currency symbol.
\item \code{mon_decimal_point} is the decimal point used in monetary
values.
\item \code{mon_thousands_sep} is the separator for grouping of
monetary values.
\item \code{mon_grouping} has the same format as the \code{grouping}
key; it is used for monetary values.
\item \code{positive_sign} and \code{negative_sign} gives the sign
used for positive and negative monetary quantities.
\item \code{int_frac_digits} and \code{frac_digits} specify the number
of fractional digits used in the international and local formatting
of monetary values.
\item \code{p_cs_precedes} and \code{n_cs_precedes} specifies whether
the currency symbol precedes the value for positive or negative
values.
\item \code{p_sep_by_space} and \code{n_sep_by_space} specifies
whether there is a space between the positive or negative value and
the currency symbol.
\item \code{p_sign_posn} and \code{n_sign_posn} indicate how the
sign should be placed for positive and negative monetary values.
\end{itemize}
The possible values for \code{p_sign_posn} and \code{n_sign_posn}
are given below.
\begin{tableii}{c|l}{code}{Value}{Explanation}
\lineii{0}{Currency and value are surrounded by parentheses.}
\lineii{1}{The sign should precede the value and currency symbol.}
\lineii{2}{The sign should follow the value and currency symbol.}
\lineii{3}{The sign should immediately precede the value.}
\lineii{4}{The sign should immediately follow the value.}
\lineii{LC_MAX}{Nothing is specified in this locale.}
\end{tableii}
\end{funcdesc}
\begin{funcdesc}{strcoll}{string1,string2}
Compares two strings according to the current \constant{LC_COLLATE}
setting. As any other compare function, returns a negative, or a
positive value, or \code{0}, depending on whether \var{string1}
collates before or after \var{string2} or is equal to it.
\end{funcdesc}
\begin{funcdesc}{strxfrm}{string}
Transforms a string to one that can be used for the built-in function
\function{cmp()}\bifuncindex{cmp}, and still returns locale-aware
results. This function can be used when the same string is compared
repeatedly, e.g. when collating a sequence of strings.
\end{funcdesc}
\begin{funcdesc}{format}{format, val, \optional{grouping\code{ = 0}}}
Formats a number \var{val} according to the current
\constant{LC_NUMERIC} setting. The format follows the conventions of
the \code{\%} operator. For floating point values, the decimal point
is modified if appropriate. If \var{grouping} is true, also takes the
grouping into account.
\end{funcdesc}
\begin{funcdesc}{str}{float}
Formats a floating point number using the same format as the built-in
function \code{str(\var{float})}, but takes the decimal point into
account.
\end{funcdesc}
\begin{funcdesc}{atof}{string}
Converts a string to a floating point number, following the
\constant{LC_NUMERIC} settings.
\end{funcdesc}
\begin{funcdesc}{atoi}{string}
Converts a string to an integer, following the \constant{LC_NUMERIC}
conventions.
\end{funcdesc}
\begin{datadesc}{LC_CTYPE}
\refstmodindex{string}
Locale category for the character type functions. Depending on the
settings of this category, the functions of module \module{string}
dealing with case change their behaviour.
\end{datadesc}
\begin{datadesc}{LC_COLLATE}
Locale category for sorting strings. The functions
\function{strcoll()} and \function{strxfrm()} of the \module{locale}
module are affected.
\end{datadesc}
\begin{datadesc}{LC_TIME}
Locale category for the formatting of time. The function
\function{time.strftime()} follows these conventions.
\end{datadesc}
\begin{datadesc}{LC_MONETARY}
Locale category for formatting of monetary values. The available
options are available from the \function{localeconv()} function.
\end{datadesc}
\begin{datadesc}{LC_MESSAGES}
Locale category for message display. Python currently does not support
application specific locale-aware messages. Messages displayed by the
operating system, like those returned by \function{os.strerror()}
might be affected by this category.
\end{datadesc}
\begin{datadesc}{LC_NUMERIC}
Locale category for formatting numbers. The functions
\function{format()}, \function{atoi()}, \function{atof()} and
\function{str()} of the \module{locale} module are affected by that
category. All other numeric formatting operations are not affected.
\end{datadesc}
\begin{datadesc}{LC_ALL}
Combination of all locale settings. If this flag is used when the
locale is changed, setting the locale for all categories is
attempted. If that fails for any category, no category is changed at
all. When the locale is retrieved using this flag, a string indicating
the setting for all categories is returned. This string can be later
used to restore the settings.
\end{datadesc}
\begin{datadesc}{CHAR_MAX}
This is a symbolic constant used for different values returned by
\function{localeconv()}.
\end{datadesc}
Example:
\begin{verbatim}
>>> import locale
>>> loc = locale.setlocale(locale.LC_ALL) # get current locale
>>> locale.setlocale(locale.LC_ALL, "de") # use German locale
>>> locale.strcoll("f\344n", "foo") # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, "") # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, "C") # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
\end{verbatim}
\subsection{Background, details, hints, tips and caveats}
The C standard defines the locale as a program-wide property that may
be relatively expensive to change. On top of that, some
implementation are broken in such a way that frequent locale changes
may cause core dumps. This makes the locale somewhat painful to use
correctly.
Initially, when a program is started, the locale is the \samp{C} locale, no
matter what the user's preferred locale is. The program must
explicitly say that it wants the user's preferred locale settings by
calling \code{setlocale(LC_ALL, "")}.
It is generally a bad idea to call \function{setlocale()} in some library
routine, since as a side effect it affects the entire program. Saving
and restoring it is almost as bad: it is expensive and affects other
threads that happen to run before the settings have been restored.
If, when coding a module for general use, you need a locale
independent version of an operation that is affected by the locale
(e.g. \function{string.lower()}, or certain formats used with
\function{time.strftime()})), you will have to find a way to do it
without using the standard library routine. Even better is convincing
yourself that using locale settings is okay. Only as a last resort
should you document that your module is not compatible with
non-\samp{C} locale settings.
The case conversion functions in the
\module{string}\refstmodindex{string} and
\module{strop}\refbimodindex{strop} modules are affected by the locale
settings. When a call to the \function{setlocale()} function changes
the \constant{LC_CTYPE} settings, the variables
\code{string.lowercase}, \code{string.uppercase} and
\code{string.letters} (and their counterparts in \module{strop}) are
recalculated. Note that this code that uses these variable through
`\keyword{from} ... \keyword{import} ...', e.g. \code{from string
import letters}, is not affected by subsequent \function{setlocale()}
calls.
The only way to perform numeric operations according to the locale
is to use the special functions defined by this module:
\function{atof()}, \function{atoi()}, \function{format()},
\function{str()}.
\subsection{For extension writers and programs that embed Python}
\label{embedding-locale}
Extension modules should never call \function{setlocale()}, except to
find out what the current locale is. But since the return value can
only be used portably to restore it, that is not very useful (except
perhaps to find out whether or not the locale is \samp{C}).
When Python is embedded in an application, if the application sets the
locale to something specific before initializing Python, that is
generally okay, and Python will use whatever locale is set,
\emph{except} that the \constant{LC_NUMERIC} locale should always be
\samp{C}.
The \function{setlocale()} function in the \module{locale} module contains
gives the Python progammer the impression that you can manipulate the
\constant{LC_NUMERIC} locale setting, but this not the case at the \C{}
level: \C{} code will always find that the \constant{LC_NUMERIC} locale
setting is \samp{C}. This is because too much would break when the
decimal point character is set to something else than a period
(e.g. the Python parser would break). Caveat: threads that run
without holding Python's global interpreter lock may occasionally find
that the numeric locale setting differs; this is because the only
portable way to implement this feature is to set the numeric locale
settings to what the user requests, extract the relevant
characteristics, and then restore the \samp{C} numeric locale.
When Python code uses the \module{locale} module to change the locale,
this also affect the embedding application. If the embedding
application doesn't want this to happen, it should remove the
\module{_locale} extension module (which does all the work) from the
table of built-in modules in the \file{config.c} file, and make sure
that the \module{_locale} module is not accessible as a shared library.

39
Doc/libmailbox.tex
View File

@ -1,39 +0,0 @@
\section{Standard Module \module{mailbox}}
\label{module-mailbox}
\stmodindex{mailbox}
This module defines a number of classes that allow easy and uniform
access to mail messages in a (\UNIX{}) mailbox.
\begin{classdesc}{UnixMailbox}{fp}
Access a classic \UNIX{}-style mailbox, where all messages are contained
in a single file and separated by ``From name time'' lines.
The file object \var{fp} points to the mailbox file.
\end{classdesc}
\begin{classdesc}{MmdfMailbox}{fp}
Access an MMDF-style mailbox, where all messages are contained
in a single file and separated by lines consisting of 4 control-A
characters. The file object \var{fp} points to the mailbox file.
\end{classdesc}
\begin{classdesc}{MHMailbox}{dirname}
Access an MH mailbox, a directory with each message in a separate
file with a numeric name.
The name of the mailbox directory is passed in \var{dirname}.
\end{classdesc}
\subsection{Mailbox Objects}
\label{mailbox-objects}
All implementations of Mailbox objects have one externally visible
method:
\begin{methoddesc}[mailbox]{next}{}
Return the next message in the mailbox, as a \class{rfc822.Message} object.
Depending on the mailbox implementation the \var{fp} attribute of this
object may be a true file object or a class instance simulating a file object,
taking care of things like message boundaries if multiple mail messages are
contained in a single file, etc.
\end{methoddesc}

79
Doc/libmailcap.tex
View File

@ -1,79 +0,0 @@
\section{Standard Module \module{mailcap}}
\label{module-mailcap}
\stmodindex{mailcap}
Mailcap files are used to configure how MIME-aware applications such
as mail readers and Web browsers react to files with different MIME
types. (The name ``mailcap'' is derived from the phrase ``mail
capability''.) For example, a mailcap file might contain a line like
\samp{video/mpeg; xmpeg \%s}. Then, if the user encounters an email
message or Web document with the MIME type \mimetype{video/mpeg},
\samp{\%s} will be replaced by a filename (usually one belonging to a
temporary file) and the \program{xmpeg} program can be automatically
started to view the file.
The mailcap format is documented in \rfc{1524}, ``A User Agent
Configuration Mechanism For Multimedia Mail Format Information,'' but
is not an Internet standard. However, mailcap files are supported on
most \UNIX{} systems.
\begin{funcdesc}{findmatch}{caps, MIMEtype%
\optional{, key\optional{,
filename\optional{, plist}}}}
Return a 2-tuple; the first element is a string containing the command
line to be executed
(which can be passed to \code{os.system()}), and the second element is
the mailcap entry for a given MIME type. If no matching MIME
type can be found, \code{(None, None)} is returned.
\var{key} is the name of the field desired, which represents the type
of activity to be performed; the default value is 'view', since in the
most common case you simply want to view the body of the MIME-typed
data. Other possible values might be 'compose' and 'edit', if you
wanted to create a new body of the given MIME type or alter the
existing body data. See \rfc{1524} for a complete list of these
fields.
\var{filename} is the filename to be substituted for \samp{\%s} in the
command line; the default value is
\code{'/dev/null'} which is almost certainly not what you want, so
usually you'll override it by specifying a filename.
\var{plist} can be a list containing named parameters; the default
value is simply an empty list. Each entry in the list must be a
string containing the parameter name, an equals sign (\code{=}), and the
parameter's value. Mailcap entries can contain
named parameters like \code{\%\{foo\}}, which will be replaced by the
value of the parameter named 'foo'. For example, if the command line
\samp{showpartial \%\{id\}\ \%\{number\}\ \%\{total\}}
was in a mailcap file, and \var{plist} was set to \code{['id=1',
'number=2', 'total=3']}, the resulting command line would be
\code{"showpartial 1 2 3"}.
In a mailcap file, the "test" field can optionally be specified to
test some external condition (e.g., the machine architecture, or the
window system in use) to determine whether or not the mailcap line
applies. \code{findmatch()} will automatically check such conditions
and skip the entry if the check fails.
\end{funcdesc}
\begin{funcdesc}{getcaps}{}
Returns a dictionary mapping MIME types to a list of mailcap file
entries. This dictionary must be passed to the \code{findmatch()}
function. An entry is stored as a list of dictionaries, but it
shouldn't be necessary to know the details of this representation.
The information is derived from all of the mailcap files found on the
system. Settings in the user's mailcap file \file{\$HOME/.mailcap}
will override settings in the system mailcap files
\file{/etc/mailcap}, \file{/usr/etc/mailcap}, and
\file{/usr/local/etc/mailcap}.
\end{funcdesc}
An example usage:
\begin{verbatim}
>>> import mailcap
>>> d=mailcap.getcaps()
>>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
\end{verbatim}

6
Doc/libmain.tex
View File

@ -1,6 +0,0 @@
\section{Built-in Module \module{__main__}}
\label{module-main}
\bimodindex{__main__}
This module represents the (otherwise anonymous) scope in which the
interpreter's main program executes --- commands read either from
standard input or from a script file.

90
Doc/libmarshal.tex
View File

@ -1,90 +0,0 @@
\section{Built-in Module \module{marshal}}
\label{module-marshal}
\bimodindex{marshal}
This module contains functions that can read and write Python
values in a binary format. The format is specific to Python, but
independent of machine architecture issues (e.g., you can write a
Python value to a file on a PC, transport the file to a Sun, and read
it back there). Details of the format are undocumented on purpose;
it may change between Python versions (although it rarely does).%
\footnote{The name of this module stems from a bit of terminology used
by the designers of Modula-3 (amongst others), who use the term
``marshalling'' for shipping of data around in a self-contained form.
Strictly speaking, ``to marshal'' means to convert some data from
internal to external form (in an RPC buffer for instance) and
``unmarshalling'' for the reverse process.}
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
mainly to support reading and writing the ``pseudo-compiled'' code for
Python modules of \file{.pyc} files.
\refstmodindex{pickle}
\refstmodindex{shelve}
\obindex{code}
Not all Python object types are supported; in general, only objects
whose value is independent from a particular invocation of Python can
be written and read by this module. The following types are supported:
\code{None}, integers, long integers, floating point numbers,
strings, tuples, lists, dictionaries, and code objects, where it
should be understood that tuples, lists and dictionaries are only
supported as long as the values contained therein are themselves
supported; and recursive lists and dictionaries should not be written
(they will cause infinite loops).
\strong{Caveat:} On machines where C's \code{long int} type has more than
32 bits (such as the DEC Alpha), it
is possible to create plain Python integers that are longer than 32
bits. Since the current \module{marshal} module uses 32 bits to
transfer plain Python integers, such values are silently truncated.
This particularly affects the use of very long integer literals in
Python modules --- these will be accepted by the parser on such
machines, but will be silently be truncated when the module is read
from the \file{.pyc} instead.%
\footnote{A solution would be to refuse such literals in the parser,
since they are inherently non-portable. Another solution would be to
let the \module{marshal} module raise an exception when an integer
value would be truncated. At least one of these solutions will be
implemented in a future version.}
There are functions that read/write files as well as functions
operating on strings.
The module defines these functions:
\begin{funcdesc}{dump}{value, file}
Write the value on the open file. The value must be a supported
type. The file must be an open file object such as
\code{sys.stdout} or returned by \function{open()} or
\function{posix.popen()}.
If the value has (or contains an object that has) an unsupported type,
a \exception{ValueError} exception is raised --- but garbage data
will also be written to the file. The object will not be properly
read back by \function{load()}.
\end{funcdesc}
\begin{funcdesc}{load}{file}
Read one value from the open file and return it. If no valid value
is read, raise \exception{EOFError}, \exception{ValueError} or
\exception{TypeError}. The file must be an open file object.
\strong{Warning:} If an object containing an unsupported type was
marshalled with \function{dump()}, \function{load()} will substitute
\code{None} for the unmarshallable type.
\end{funcdesc}
\begin{funcdesc}{dumps}{value}
Return the string that would be written to a file by
\code{dump(\var{value}, \var{file})}. The value must be a supported
type. Raise a \exception{ValueError} exception if value has (or
contains an object that has) an unsupported type.
\end{funcdesc}
\begin{funcdesc}{loads}{string}
Convert the string to a value. If no valid value is found, raise
\exception{EOFError}, \exception{ValueError} or
\exception{TypeError}. Extra characters in the string are ignored.
\end{funcdesc}

122
Doc/libmath.tex
View File

@ -1,122 +0,0 @@
\section{Built-in Module \module{math}}
\label{module-math}
\bimodindex{math}
This module is always available.
It provides access to the mathematical functions defined by the \C{}
standard.
They are:
\begin{funcdesc}{acos}{x}
Return the arc cosine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{asin}{x}
Return the arc sine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{atan}{x}
Return the arc tangent of \var{x}.
\end{funcdesc}
\begin{funcdesc}{atan2}{x, y}
Return \code{atan(\var{x} / \var{y})}.
\end{funcdesc}
\begin{funcdesc}{ceil}{x}
Return the ceiling of \var{x} as a real.
\end{funcdesc}
\begin{funcdesc}{cos}{x}
Return the cosine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{cosh}{x}
Return the hyperbolic cosine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{exp}{x}
Return \code{e**\var{x}}.
\end{funcdesc}
\begin{funcdesc}{fabs}{x}
Return the absolute value of the real \var{x}.
\end{funcdesc}
\begin{funcdesc}{floor}{x}
Return the floor of \var{x} as a real.
\end{funcdesc}
\begin{funcdesc}{fmod}{x, y}
Return \code{\var{x} \%\ \var{y}}.
\end{funcdesc}
\begin{funcdesc}{frexp}{x}
Return the matissa and exponent for \var{x}. The mantissa is
positive.
\end{funcdesc}
\begin{funcdesc}{hypot}{x, y}
Return the Euclidean distance, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}.
\end{funcdesc}
\begin{funcdesc}{ldexp}{x, i}
Return \code{\var{x} * (2**\var{i})}.
\end{funcdesc}
\begin{funcdesc}{log}{x}
Return the natural logarithm of \var{x}.
\end{funcdesc}
\begin{funcdesc}{log10}{x}
Return the base-10 logarithm of \var{x}.
\end{funcdesc}
\begin{funcdesc}{modf}{x}
Return the fractional and integer parts of \var{x}. Both results
carry the sign of \var{x}. The integer part is returned as a real.
\end{funcdesc}
\begin{funcdesc}{pow}{x, y}
Return \code{\var{x}**\var{y}}.
\end{funcdesc}
\begin{funcdesc}{sin}{x}
Return the sine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{sinh}{x}
Return the hyperbolic sine of \var{x}.
\end{funcdesc}
\begin{funcdesc}{sqrt}{x}
Return the square root of \var{x}.
\end{funcdesc}
\begin{funcdesc}{tan}{x}
Return the tangent of \var{x}.
\end{funcdesc}
\begin{funcdesc}{tanh}{x}
Return the hyperbolic tangent of \var{x}.
\end{funcdesc}
Note that \function{frexp()} and \function{modf()} have a different
call/return pattern than their \C{} equivalents: they take a single
argument and return a pair of values, rather than returning their
second return value through an `output parameter' (there is no such
thing in Python).
The module also defines two mathematical constants:
\begin{datadesc}{pi}
The mathematical constant \emph{pi}.
\end{datadesc}
\begin{datadesc}{e}
The mathematical constant \emph{e}.
\end{datadesc}
\begin{seealso}
\seemodule{cmath}{Complex number versions of many of these functions.}
\end{seealso}

64
Doc/libmd5.tex
View File

@ -1,64 +0,0 @@
\section{Built-in Module \module{md5}}
\label{module-md5}
\bimodindex{md5}
This module implements the interface to RSA's MD5 message digest
\index{message digest, MD5}
algorithm (see also Internet \rfc{1321}). Its use is quite
straightforward:\ use the \function{new()} to create an md5 object.
You can now feed this object with arbitrary strings using the
\method{update()} method, and at any point you can ask it for the
\dfn{digest} (a strong kind of 128-bit checksum,
a.k.a. ``fingerprint'') of the contatenation of the strings fed to it
so far using the \method{digest()} method.
\index{checksum!MD5}
For example, to obtain the digest of the string \code{'Nobody inspects
the spammish repetition'}:
\begin{verbatim}
>>> import md5
>>> m = md5.new()
>>> m.update("Nobody inspects")
>>> m.update(" the spammish repetition")
>>> m.digest()
'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
\end{verbatim}
More condensed:
\begin{verbatim}
>>> md5.new("Nobody inspects the spammish repetition").digest()
'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
\end{verbatim}
\begin{funcdesc}{new}{\optional{arg}}
Return a new md5 object. If \var{arg} is present, the method call
\code{update(\var{arg})} is made.
\end{funcdesc}
\begin{funcdesc}{md5}{\optional{arg}}
For backward compatibility reasons, this is an alternative name for the
\function{new()} function.
\end{funcdesc}
An md5 object has the following methods:
\begin{methoddesc}[md5]{update}{arg}
Update the md5 object with the string \var{arg}. Repeated calls are
equivalent to a single call with the concatenation of all the
arguments, i.e.\ \code{m.update(a); m.update(b)} is equivalent to
\code{m.update(a+b)}.
\end{methoddesc}
\begin{methoddesc}[md5]{digest}{}
Return the digest of the strings passed to the \method{update()}
method so far. This is an 16-byte string which may contain
non-\ASCII{} characters, including null bytes.
\end{methoddesc}
\begin{methoddesc}[md5]{copy}{}
Return a copy (``clone'') of the md5 object. This can be used to
efficiently compute the digests of strings that share a common initial
substring.
\end{methoddesc}

95
Doc/libmimetools.tex
View File

@ -1,95 +0,0 @@
\section{Standard Module \module{mimetools}}
\label{module-mimetools}
\stmodindex{mimetools}
This module defines a subclass of the \class{rfc822.Message} class and
a number of utility functions that are useful for the manipulation for
MIME multipart or encoded message.
It defines the following items:
\begin{classdesc}{Message}{fp\optional{, seekable}}
Return a new instance of the \class{Message} class. This is a
subclass of the \class{rfc822.Message} class, with some additional
methods (see below). The \var{seekable} argument has the same meaning
as for \class{rfc822.Message}.
\end{classdesc}
\begin{funcdesc}{choose_boundary}{}
Return a unique string that has a high likelihood of being usable as a
part boundary. The string has the form
\code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}.
\end{funcdesc}
\begin{funcdesc}{decode}{input, output, encoding}
Read data encoded using the allowed MIME \var{encoding} from open file
object \var{input} and write the decoded data to open file object
\var{output}. Valid values for \var{encoding} include
\code{'base64'}, \code{'quoted-printable'} and \code{'uuencode'}.
\end{funcdesc}
\begin{funcdesc}{encode}{input, output, encoding}
Read data from open file object \var{input} and write it encoded using
the allowed MIME \var{encoding} to open file object \var{output}.
Valid values for \var{encoding} are the same as for \method{decode()}.
\end{funcdesc}
\begin{funcdesc}{copyliteral}{input, output}
Read lines until \EOF{} from open file \var{input} and write them to
open file \var{output}.
\end{funcdesc}
\begin{funcdesc}{copybinary}{input, output}
Read blocks until \EOF{} from open file \var{input} and write them to
open file \var{output}. The block size is currently fixed at 8192.
\end{funcdesc}
\subsection{Additional Methods of Message objects}
\nodename{mimetools.Message Methods}
The \class{Message} class defines the following methods in
addition to the \class{rfc822.Message} methods:
\begin{methoddesc}{getplist}{}
Return the parameter list of the \code{content-type} header. This is
a list if strings. For parameters of the form
\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
\var{value} is not. For example, if the message contains the header
\samp{Content-type: text/html; spam=1; Spam=2; Spam} then
\method{getplist()} will return the Python list \code{['spam=1',
'spam=2', 'Spam']}.
\end{methoddesc}
\begin{methoddesc}{getparam}{name}
Return the \var{value} of the first parameter (as returned by
\method{getplist()} of the form \samp{\var{name}=\var{value}} for the
given \var{name}. If \var{value} is surrounded by quotes of the form
`\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
\end{methoddesc}
\begin{methoddesc}{getencoding}{}
Return the encoding specified in the \code{content-transfer-encoding}
message header. If no such header exists, return \code{'7bit'}. The
encoding is converted to lower case.
\end{methoddesc}
\begin{methoddesc}{gettype}{}
Return the message type (of the form \samp{\var{type}/\var{subtype}})
as specified in the \code{content-type} header. If no such header
exists, return \code{'text/plain'}. The type is converted to lower
case.
\end{methoddesc}
\begin{methoddesc}{getmaintype}{}
Return the main type as specified in the \code{content-type} header.
If no such header exists, return \code{'text'}. The main type is
converted to lower case.
\end{methoddesc}
\begin{methoddesc}{getsubtype}{}
Return the subtype as specified in the \code{content-type} header. If
no such header exists, return \code{'plain'}. The subtype is
converted to lower case.
\end{methoddesc}

83
Doc/libmimify.tex
View File

@ -1,83 +0,0 @@
\section{Standard Module \module{mimify}}
\label{module-mimify}
\stmodindex{mimify}
The mimify module defines two functions to convert mail messages to
and from MIME format. The mail message can be either a simple message
or a so-called multipart message. Each part is treated separately.
Mimifying (a part of) a message entails encoding the message as
quoted-printable if it contains any characters that cannot be
represented using 7-bit ASCII. Unmimifying (a part of) a message
entails undoing the quoted-printable encoding. Mimify and unmimify
are especially useful when a message has to be edited before being
sent. Typical use would be:
\begin{verbatim}
unmimify message
edit message
mimify message
send message
\end{verbatim}
The modules defines the following user-callable functions and
user-settable variables:
\begin{funcdesc}{mimify}{infile, outfile}
Copy the message in \var{infile} to \var{outfile}, converting parts to
quoted-printable and adding MIME mail headers when necessary.
\var{infile} and \var{outfile} can be file objects (actually, any
object that has a \code{readline} method (for \var{infile}) or a
\code{write} method (for \var{outfile})) or strings naming the files.
If \var{infile} and \var{outfile} are both strings, they may have the
same value.
\end{funcdesc}
\begin{funcdesc}{unmimify}{infile, outfile, decode_base64 = 0}
Copy the message in \var{infile} to \var{outfile}, decoding all
quoted-printable parts. \var{infile} and \var{outfile} can be file
objects (actually, any object that has a \code{readline} method (for
\var{infile}) or a \code{write} method (for \var{outfile})) or strings
naming the files. If \var{infile} and \var{outfile} are both strings,
they may have the same value.
If the \var{decode_base64} argument is provided and tests true, any
parts that are coded in the base64 encoding are decoded as well.
\end{funcdesc}
\begin{funcdesc}{mime_decode_header}{line}
Return a decoded version of the encoded header line in \var{line}.
\end{funcdesc}
\begin{funcdesc}{mime_encode_header}{line}
Return a MIME-encoded version of the header line in \var{line}.
\end{funcdesc}
\begin{datadesc}{MAXLEN}
By default, a part will be encoded as quoted-printable when it
contains any non-ASCII characters (i.e., characters with the 8th bit
set), or if there are any lines longer than \code{MAXLEN} characters
(default value 200).
\end{datadesc}
\begin{datadesc}{CHARSET}
When not specified in the mail headers, a character set must be filled
in. The string used is stored in \code{CHARSET}, and the default
value is ISO-8859-1 (also known as Latin1 (latin-one)).
\end{datadesc}
This module can also be used from the command line. Usage is as
follows:
\begin{verbatim}
mimify.py -e [-l length] [infile [outfile]]
mimify.py -d [-b] [infile [outfile]]
\end{verbatim}
to encode (mimify) and decode (unmimify) respectively. \var{infile}
defaults to standard input, \var{outfile} defaults to standard output.
The same file can be specified for input and output.
If the \code{-l} option is given when encoding, if there are any lines
longer than the specified \var{length}, the containing part will be
encoded.
If the \code{-b} option is given when decoding, any base64 parts will
be decoded as well.

63
Doc/libminiae.tex
View File

@ -1,63 +0,0 @@
\section{Standard Module \module{MiniAEFrame}}
\stmodindex{MiniAEFrame}
\label{module-MiniAEFrame}
The module \module{MiniAEFrame} provides a framework for an application
that can function as an Open Scripting Architecture
\index{Open Scripting Architecture}
(OSA) server, i.e. receive and process
AppleEvents\index{AppleEvents}. It can be used in conjunction with
\module{FrameWork}\refstmodindex{FrameWork} or standalone.
This module is temporary, it will eventually be replaced by a module
that handles argument names better and possibly automates making your
application scriptable.
The \module{MiniAEFrame} module defines the following classes:
\begin{classdesc}{AEServer}{}
A class that handles AppleEvent dispatch. Your application should
subclass this class together with either
\class{MiniApplication} or
\class{FrameWork.Application}. Your \method{__init__()} method should
call the \method{__init__()} method for both classes.
\end{classdesc}
\begin{classdesc}{MiniApplication}{}
A class that is more or less compatible with
\class{FrameWork.Application} but with less functionality. Its
event loop supports the apple menu, command-dot and AppleEvents; other
events are passed on to the Python interpreter and/or Sioux.
Useful if your application wants to use \class{AEServer} but does not
provide its own windows, etc.
\end{classdesc}
\subsection{AEServer Objects}
\label{aeserver-objects}
\begin{methoddesc}[AEServer]{installaehandler}{classe, type, callback}
Installs an AppleEvent handler. \var{classe} and \var{type} are the
four-character OSA Class and Type designators, \code{'****'} wildcards
are allowed. When a matching AppleEvent is received the parameters are
decoded and your callback is invoked.
\end{methoddesc}
\begin{methoddesc}[AEServer]{callback}{_object, **kwargs}
Your callback is called with the OSA Direct Object as first positional
parameter. The other parameters are passed as keyword arguments, with
the 4-character designator as name. Three extra keyword parameters are
passed: \code{_class} and \code{_type} are the Class and Type
designators and \code{_attributes} is a dictionary with the AppleEvent
attributes.
The return value of your method is packed with
\function{aetools.packevent()} and sent as reply.
\end{methoddesc}
Note that there are some serious problems with the current
design. AppleEvents which have non-identifier 4-character designators
for arguments are not implementable, and it is not possible to return
an error to the originator. This will be addressed in a future
release.

28
Doc/libmisc.tex
View File

@ -1,28 +0,0 @@
\chapter{Miscellaneous Services}
\label{misc}
The modules described in this chapter provide miscellaneous services
that are available in all Python versions. Here's an overview:
\begin{description}
\item[math]
--- Mathematical functions (\function{sin()} etc.).
\item[cmath]
--- Mathematical functions for complex numbers.
\item[whrandom]
--- Floating point pseudo-random number generator.
\item[random]
--- Generate pseudo-random numbers with various common distributions.
\item[array]
--- Efficient arrays of uniformly typed numeric values.
\item[fileinput]
--- Perl-like iteration over lines from multiple input streams, with
``save in place'' capability.
\end{description}

29
Doc/libmm.tex
View File

@ -1,29 +0,0 @@
\chapter{Multimedia Services}
\label{mmedia}
The modules described in this chapter implement various algorithms or
interfaces that are mainly useful for multimedia applications. They
are available at the discretion of the installation. Here's an overview:
\begin{description}
\item[audioop]
--- Manipulate raw audio data.
\item[imageop]
--- Manipulate raw image data.
\item[aifc]
--- Read and write audio files in AIFF or AIFC format.
\item[jpeg]
--- Read and write image files in compressed JPEG format.
\item[rgbimg]
--- Read and write image files in ``SGI RGB'' format (the module is
\emph{not} SGI specific though)!
\item[imghdr]
--- Determine the type of image contained in a file or byte stream.
\end{description}

89
Doc/libmpz.tex
View File

@ -1,89 +0,0 @@
\section{Built-in Module \module{mpz}}
\label{module-mpz}
\bimodindex{mpz}
This is an optional module. It is only available when Python is
configured to include it, which requires that the GNU MP software is
installed.
\index{MP, GNU library}
\index{arbitrary precision integers}
\index{integer!arbitrary precision}
This module implements the interface to part of the GNU MP library,
which defines arbitrary precision integer and rational number
arithmetic routines. Only the interfaces to the \emph{integer}
(\function{mpz_*()}) routines are provided. If not stated
otherwise, the description in the GNU MP documentation can be applied.
In general, \dfn{mpz}-numbers can be used just like other standard
Python numbers, e.g.\ you can use the built-in operators like \code{+},
\code{*}, etc., as well as the standard built-in functions like
\function{abs()}, \function{int()}, \ldots, \function{divmod()},
\function{pow()}. \strong{Please note:} the \emph{bitwise-xor}
operation has been implemented as a bunch of \emph{and}s,
\emph{invert}s and \emph{or}s, because the library lacks an
\cfunction{mpz_xor()} function, and I didn't need one.
You create an mpz-number by calling the function \function{mpz()} (see
below for an exact description). An mpz-number is printed like this:
\code{mpz(\var{value})}.
\begin{funcdesc}{mpz}{value}
Create a new mpz-number. \var{value} can be an integer, a long,
another mpz-number, or even a string. If it is a string, it is
interpreted as an array of radix-256 digits, least significant digit
first, resulting in a positive number. See also the \method{binary()}
method, described below.
\end{funcdesc}
\begin{datadesc}{MPZType}
The type of the objects returned by \function{mpz()} and most other
functions in this module.
\end{datadesc}
A number of \emph{extra} functions are defined in this module. Non
mpz-arguments are converted to mpz-values first, and the functions
return mpz-numbers.
\begin{funcdesc}{powm}{base, exponent, modulus}
Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
\code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
\C{} library function, this version can handle negative exponents.
\end{funcdesc}
\begin{funcdesc}{gcd}{op1, op2}
Return the greatest common divisor of \var{op1} and \var{op2}.
\end{funcdesc}
\begin{funcdesc}{gcdext}{a, b}
Return a tuple \code{(\var{g}, \var{s}, \var{t})}, such that
\code{\var{a}*\var{s} + \var{b}*\var{t} == \var{g} == gcd(\var{a}, \var{b})}.
\end{funcdesc}
\begin{funcdesc}{sqrt}{op}
Return the square root of \var{op}. The result is rounded towards zero.
\end{funcdesc}
\begin{funcdesc}{sqrtrem}{op}
Return a tuple \code{(\var{root}, \var{remainder})}, such that
\code{\var{root}*\var{root} + \var{remainder} == \var{op}}.
\end{funcdesc}
\begin{funcdesc}{divm}{numerator, denominator, modulus}
Returns a number \var{q} such that
\code{\var{q} * \var{denominator} \%{} \var{modulus} ==
\var{numerator}}. One could also implement this function in Python,
using \function{gcdext()}.
\end{funcdesc}
An mpz-number has one method:
\begin{methoddesc}[mpz]{binary}{}
Convert this mpz-number to a binary string, where the number has been
stored as an array of radix-256 digits, least significant digit first.
The mpz-number must have a value greater than or equal to zero,
otherwise \exception{ValueError} will be raised.
\end{methoddesc}

60
Doc/libni.tex
View File

@ -1,60 +0,0 @@
\section{Standard Module \module{ni}}
\label{module-ni}
\stmodindex{ni}
\strong{Warning: This module is obsolete.} As of Python 1.5a4,
package support (with different semantics for \code{__init__} and no
support for \code{__domain__} or \code{__}) is built in the
interpreter. The ni module is retained only for backward
compatibility. As of Python 1.5b2, it has been renamed to \code{ni1};
if you really need it, you can use \code{import ni1}, but the
recommended approach is to rely on the built-in package support,
converting existing packages if needed. Note that mixing \code{ni}
and the built-in package support doesn't work: once you import
\code{ni}, all packages use it.
The \code{ni} module defines a new importing scheme, which supports
packages containing several Python modules. To enable package
support, execute \code{import ni} before importing any packages. Importing
this module automatically installs the relevant import hooks. There
are no publicly-usable functions or variables in the \code{ni} module.
To create a package named \code{spam} containing sub-modules \code{ham}, \code{bacon} and
\code{eggs}, create a directory \file{spam} somewhere on Python's module search
path, as given in \code{sys.path}. Then, create files called \file{ham.py}, \file{bacon.py} and
\file{eggs.py} inside \file{spam}.
To import module \code{ham} from package \code{spam} and use function
\code{hamneggs()} from that module, you can use any of the following
possibilities:
\begin{verbatim}
import spam.ham # *not* "import spam" !!!
spam.ham.hamneggs()
\end{verbatim}
%
\begin{verbatim}
from spam import ham
ham.hamneggs()
\end{verbatim}
%
\begin{verbatim}
from spam.ham import hamneggs
hamneggs()
\end{verbatim}
%
\code{import spam} creates an
empty package named \code{spam} if one does not already exist, but it does
\emph{not} automatically import \code{spam}'s submodules.
The only submodule that is guaranteed to be imported is
\code{spam.__init__}, if it exists; it would be in a file named
\file{__init__.py} in the \file{spam} directory. Note that
\code{spam.__init__} is a submodule of package spam. It can refer to
spam's namespace as \code{__} (two underscores):
\begin{verbatim}
__.spam_inited = 1 # Set a package-level variable
\end{verbatim}
%
Additional initialization code (setting up variables, importing other
submodules) can be performed in \file{spam/__init__.py}.

246
Doc/libnntplib.tex
View File

@ -1,246 +0,0 @@
\section{Standard Module \module{nntplib}}
\label{module-nntplib}
\stmodindex{nntplib}
\indexii{NNTP}{protocol}
This module defines the class \class{NNTP} which implements the client
side of the NNTP protocol. It can be used to implement a news reader
or poster, or automated news processors. For more information on NNTP
(Network News Transfer Protocol), see Internet \rfc{977}.
Here are two small examples of how it can be used. To list some
statistics about a newsgroup and print the subjects of the last 10
articles:
\begin{verbatim}
>>> s = NNTP('news.cwi.nl')
>>> resp, count, first, last, name = s.group('comp.lang.python')
>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
Group comp.lang.python has 59 articles, range 3742 to 3803
>>> resp, subs = s.xhdr('subject', first + '-' + last)
>>> for id, sub in subs[-10:]: print id, sub
...
3792 Re: Removing elements from a list while iterating...
3793 Re: Who likes Info files?
3794 Emacs and doc strings
3795 a few questions about the Mac implementation
3796 Re: executable python scripts
3797 Re: executable python scripts
3798 Re: a few questions about the Mac implementation
3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules
3802 Re: executable python scripts
3803 Re: \POSIX{} wait and SIGCHLD
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
\end{verbatim}
To post an article from a file (this assumes that the article has
valid headers):
\begin{verbatim}
>>> s = NNTP('news.cwi.nl')
>>> f = open('/tmp/article')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
\end{verbatim}
%
The module itself defines the following items:
\begin{classdesc}{NNTP}{host\optional{, port}}
Return a new instance of the \class{NNTP} class, representing a
connection to the NNTP server running on host \var{host}, listening at
port \var{port}. The default \var{port} is 119.
\end{classdesc}
\begin{excdesc}{error_reply}
Exception raised when an unexpected reply is received from the server.
\end{excdesc}
\begin{excdesc}{error_temp}
Exception raised when an error code in the range 400--499 is received.
\end{excdesc}
\begin{excdesc}{error_perm}
Exception raised when an error code in the range 500--599 is received.
\end{excdesc}
\begin{excdesc}{error_proto}
Exception raised when a reply is received from the server that does
not begin with a digit in the range 1--5.
\end{excdesc}
\subsection{NNTP Objects}
\label{nntp-objects}
NNTP instances have the following methods. The \var{response} that is
returned as the first item in the return tuple of almost all methods
is the server's response: a string beginning with a three-digit code.
If the server's response indicates an error, the method raises one of
the above exceptions.
\begin{methoddesc}{getwelcome}{}
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.)
\end{methoddesc}
\begin{methoddesc}{set_debuglevel}{level}
Set the instance's debugging level. This controls the amount of
debugging output printed. The default, \code{0}, produces no debugging
output. A value of \code{1} produces a moderate amount of debugging
output, generally a single line per request or response. A value of
\code{2} or higher produces the maximum amount of debugging output,
logging each line sent and received on the connection (including
message text).
\end{methoddesc}
\begin{methoddesc}{newgroups}{date, time}
Send a \samp{NEWGROUPS} command. The \var{date} argument should be a
string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the
date, and \var{time} should be a string of the form
\code{"\var{hh}\var{mm}\var{ss}"} indicating the time. Return a pair
\code{(\var{response}, \var{groups})} where \var{groups} is a list of
group names that are new since the given date and time.
\end{methoddesc}
\begin{methoddesc}{newnews}{group, date, time}
Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or
\code{'*'}, and \var{date} and \var{time} have the same meaning as for
\method{newgroups()}. Return a pair \code{(\var{response},
\var{articles})} where \var{articles} is a list of article ids.
\end{methoddesc}
\begin{methoddesc}{list}{}
Send a \samp{LIST} command. Return a pair \code{(\var{response},
\var{list})} where \var{list} is a list of tuples. Each tuple has the
form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
\var{group} is a group name, \var{last} and \var{first} are the last
and first article numbers (as strings), and \var{flag} is \code{'y'}
if posting is allowed, \code{'n'} if not, and \code{'m'} if the
newsgroup is moderated. (Note the ordering: \var{last}, \var{first}.)
\end{methoddesc}
\begin{methoddesc}{group}{name}
Send a \samp{GROUP} command, where \var{name} is the group name.
Return a tuple \code{(}\var{response}\code{,} \var{count}\code{,}
\var{first}\code{,} \var{last}\code{,} \var{name}\code{)} where
\var{count} is the (estimated) number of articles in the group,
\var{first} is the first article number in the group, \var{last} is
the last article number in the group, and \var{name} is the group
name. The numbers are returned as strings.
\end{methoddesc}
\begin{methoddesc}{help}{}
Send a \samp{HELP} command. Return a pair \code{(\var{response},
\var{list})} where \var{list} is a list of help strings.
\end{methoddesc}
\begin{methoddesc}{stat}{id}
Send a \samp{STAT} command, where \var{id} is the message id (enclosed
in \character{<} and \character{>}) or an article number (as a string).
Return a triple \code{(\var{response}, \var{number}, \var{id})} where
\var{number} is the article number (as a string) and \var{id} is the
article id (enclosed in \character{<} and \character{>}).
\end{methoddesc}
\begin{methoddesc}{next}{}
Send a \samp{NEXT} command. Return as for \method{stat()}.
\end{methoddesc}
\begin{methoddesc}{last}{}
Send a \samp{LAST} command. Return as for \method{stat()}.
\end{methoddesc}
\begin{methoddesc}{head}{id}
Send a \samp{HEAD} command, where \var{id} has the same meaning as for
\method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's headers (an uninterpreted
list of lines, without trailing newlines).
\end{methoddesc}
\begin{methoddesc}{body}{id}
Send a \samp{BODY} command, where \var{id} has the same meaning as for
\method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's body text (an
uninterpreted list of lines, without trailing newlines).
\end{methoddesc}
\begin{methoddesc}{article}{id}
Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
for \method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's header and body text (an
uninterpreted list of lines, without trailing newlines).
\end{methoddesc}
\begin{methoddesc}{slave}{}
Send a \samp{SLAVE} command. Return the server's \var{response}.
\end{methoddesc}
\begin{methoddesc}{xhdr}{header, string}
Send an \samp{XHDR} command. This command is not defined in the RFC
but is a common extension. The \var{header} argument is a header
keyword, e.g. \code{'subject'}. The \var{string} argument should have
the form \code{"\var{first}-\var{last}"} where \var{first} and
\var{last} are the first and last article numbers to search. Return a
pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id
(as a string) and \var{text} is the text of the requested header for
that article.
\end{methoddesc}
\begin{methoddesc}{post}{file}
Post an article using the \samp{POST} command. The \var{file}
argument is an open file object which is read until EOF using its
\method{readline()} method. It should be a well-formed news article,
including the required headers. The \method{post()} method
automatically escapes lines beginning with \samp{.}.
\end{methoddesc}
\begin{methoddesc}{ihave}{id, file}
Send an \samp{IHAVE} command. If the response is not an error, treat
\var{file} exactly as for the \method{post()} method.
\end{methoddesc}
\begin{methoddesc}{date}{}
Return a triple \code{(\var{response}, \var{date}, \var{time})},
containing the current date and time in a form suitable for the
\method{newnews()} and \method{newgroups()} methods.
This is an optional NNTP extension, and may not be supported by all
servers.
\end{methoddesc}
\begin{methoddesc}{xgtitle}{name}
Process an \samp{XGTITLE} command, returning a pair \code{(\var{response},
\var{list})}, where \var{list} is a list of tuples containing
\code{(\var{name}, \var{title})}.
% XXX huh? Should that be name, description?
This is an optional NNTP extension, and may not be supported by all
servers.
\end{methoddesc}
\begin{methoddesc}{xover}{start, end}
Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list
of tuples, one for each article in the range delimited by the \var{start}
and \var{end} article numbers. Each tuple is of the form
\code{(}\var{article number}\code{,} \var{subject}\code{,}
\var{poster}\code{,} \var{date}\code{,} \var{id}\code{,}
\var{references}\code{,} \var{size}\code{,} \var{lines}\code{)}.
This is an optional NNTP extension, and may not be supported by all
servers.
\end{methoddesc}
\begin{methoddesc}{xpath}{id}
Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
directory path to the article with message ID \var{id}. This is an
optional NNTP extension, and may not be supported by all servers.
\end{methoddesc}
\begin{methoddesc}{quit}{}
Send a \samp{QUIT} command and close the connection. Once this method
has been called, no other methods of the NNTP object should be called.
\end{methoddesc}

24
Doc/libobjs.tex
View File

@ -1,24 +0,0 @@
\chapter{Built-in Types, Exceptions and Functions}
\nodename{Built-in Objects}
\label{builtin}
Names for built-in exceptions and functions are found in a separate
symbol table. This table is searched last when the interpreter looks
up the meaning of a name, so local and global
user-defined names can override built-in names. Built-in types are
described together here for easy reference.%
\footnote{Most descriptions sorely lack explanations of the exceptions
that may be raised --- this will be fixed in a future version of
this manual.}
\indexii{built-in}{types}
\indexii{built-in}{exceptions}
\indexii{built-in}{functions}
\index{symbol table}
The tables in this chapter document the priorities of operators by
listing them in order of ascending priority (within a table) and
grouping operators that have the same priority in the same box.
Binary operators of the same priority group from left to right.
(Unary operators group from right to left, but there you have no real
choice.) See Chapter 5 of the \emph{Python Reference Manual} for the
complete picture on operator priorities.

132
Doc/liboperator.tex
View File

@ -1,132 +0,0 @@
% Contributed by Skip Montanaro, from the module's doc strings.
\section{Built-in Module \module{operator}}
\label{module-operator}
\bimodindex{operator}
The \module{operator} module exports a set of functions implemented in C
corresponding to the intrinsic operators of Python. For example,
\code{operator.add(x, y)} is equivalent to the expression \code{x+y}. The
function names are those used for special class methods; variants without
leading and trailing \samp{__} are also provided for convenience.
The \module{operator} module defines the following functions:
\begin{funcdesc}{add}{a, b}
\funcline{__add__}{a, b}
Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers.
\end{funcdesc}
\begin{funcdesc}{sub}{a, b}
\funcline{__sub__}{a, b}
Return \var{a} \code{-} \var{b}.
\end{funcdesc}
\begin{funcdesc}{mul}{a, b}
\funcline{__mul__}{a, b}
Return \var{a} \code{*} \var{b}, for \var{a} and \var{b} numbers.
\end{funcdesc}
\begin{funcdesc}{div}{a, b}
\funcline{__div__}{a, b}
Return \var{a} \code{/} \var{b}.
\end{funcdesc}
\begin{funcdesc}{mod}{a, b}
\funcline{__mod__}{a, b}
Return \var{a} \code{\%} \var{b}.
\end{funcdesc}
\begin{funcdesc}{neg}{o}
\funcline{__neg__}{o}
Return \var{o} negated.
\end{funcdesc}
\begin{funcdesc}{pos}{o}
\funcline{__pos__}{o}
Return \var{o} positive.
\end{funcdesc}
\begin{funcdesc}{abs}{o}
\funcline{__abs__}{o}
Return the absolute value of \var{o}.
\end{funcdesc}
\begin{funcdesc}{inv}{o}
\funcline{__inv__}{o}
Return the inverse of \var{o}.
\end{funcdesc}
\begin{funcdesc}{lshift}{a, b}
\funcline{__lshift__}{a, b}
Return \var{a} shifted left by \var{b}.
\end{funcdesc}
\begin{funcdesc}{rshift}{a, b}
\funcline{__rshift__}{a, b}
Return \var{a} shifted right by \var{b}.
\end{funcdesc}
\begin{funcdesc}{and_}{a, b}
\funcline{__and__}{a, b}
Return the bitwise and of \var{a} and \var{b}.
\end{funcdesc}
\begin{funcdesc}{or_}{a, b}
\funcline{__or__}{a, b}
Return the bitwise or of \var{a} and \var{b}.
\end{funcdesc}
\begin{funcdesc}{concat}{a, b}
\funcline{__concat__}{a, b}
Return \var{a} \code{+} \var{b} for \var{a} and \var{b} sequences.
\end{funcdesc}
\begin{funcdesc}{repeat}{a, b}
\funcline{__repeat__}{a, b}
Return \var{a} \code{*} \var{b} where \var{a} is a sequence and
\var{b} is an integer.
\end{funcdesc}
\begin{funcdesc}{getitem}{a, b}
\funcline{__getitem__}{a, b}
Return the value of \var{a} at index \var{b}.
\end{funcdesc}
\begin{funcdesc}{setitem}{a, b, c}
\funcline{__setitem__}{a, b, c}
Set the value of \var{a} at index \var{b} to \var{c}.
\end{funcdesc}
\begin{funcdesc}{delitem}{a, b}
\funcline{__delitem__}{a, b}
Remove the value of \var{a} at index \var{b}.
\end{funcdesc}
\begin{funcdesc}{getslice}{a, b, c}
\funcline{__getslice__}{a, b, c}
Return the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
\end{funcdesc}
\begin{funcdesc}{setslice}{a, b, c, v}
\funcline{__setslice__}{a, b, c, v}
Set the slice of \var{a} from index \var{b} to index \var{c}\code{-1} to the
sequence \var{v}.
\end{funcdesc}
\begin{funcdesc}{delslice}{a, b, c}
\funcline{__delslice__}{a, b, c}
Delete the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
\end{funcdesc}
Example: Build a dictionary that maps the ordinals from \code{0} to
\code{256} to their character equivalents.
\begin{verbatim}
>>> import operator
>>> d = {}
>>> keys = range(256)
>>> vals = map(chr, keys)
>>> map(operator.setitem, [d]*len(keys), keys, vals)
\end{verbatim}

110
Doc/libos.tex
View File

@ -1,110 +0,0 @@
\section{Standard Module \module{os}}
\label{module-os}
\stmodindex{os}
This module provides a more portable way of using operating system
(OS) dependent functionality than importing an OS dependent built-in
module like \module{posix}.
When the optional built-in module \module{posix} is available, this
module exports the same functions and data as \module{posix}; otherwise,
it searches for an OS dependent built-in module like \module{mac} and
exports the same functions and data as found there. The design of all
Python's built-in OS dependent modules is such that as long as the same
functionality is available, it uses the same interface; e.g., the
function \code{os.stat(\var{file})} returns stat info about \var{file}
in a format compatible with the \POSIX{} interface.
Extensions peculiar to a particular OS are also available through the
\module{os} module, but using them is of course a threat to
portability!
Note that after the first time \module{os} is imported, there is
\emph{no} performance penalty in using functions from \module{os}
instead of directly from the OS dependent built-in module, so there
should be \emph{no} reason not to use \module{os}!
In addition to whatever the correct OS dependent module exports, the
following variables and functions are always exported by \module{os}:
\begin{datadesc}{name}
The name of the OS dependent module imported. The following names
have currently been registered: \code{'posix'}, \code{'nt'},
\code{'dos'}, \code{'mac'}.
\end{datadesc}
\begin{datadesc}{path}
The corresponding OS dependent standard module for pathname
operations, e.g., \module{posixpath} or \module{macpath}. Thus, (given
the proper imports), \code{os.path.split(\var{file})} is equivalent to but
more portable than \code{posixpath.split(\var{file})}.
\end{datadesc}
\begin{datadesc}{curdir}
The constant string used by the OS to refer to the current directory,
e.g. \code{'.'} for \POSIX{} or \code{':'} for the Macintosh.
\end{datadesc}
\begin{datadesc}{pardir}
The constant string used by the OS to refer to the parent directory,
e.g. \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh.
\end{datadesc}
\begin{datadesc}{sep}
The character used by the OS to separate pathname components,
e.g. \code{'/'} for \POSIX{} or \code{':'} for the Macintosh. Note that
knowing this is not sufficient to be able to parse or concatenate
pathnames --- better use \function{os.path.split()} and
\function{os.path.join()}---but it is occasionally useful.
\end{datadesc}
\begin{datadesc}{altsep}
An alternative character used by the OS to separate pathname components,
or \code{None} if only one separator character exists. This is set to
\code{'/'} on DOS/Windows systems where \code{sep} is a backslash.
\end{datadesc}
\begin{datadesc}{pathsep}
The character conventionally used by the OS to separate search patch
components (as in \code{\$PATH}), e.g.\ \code{':'} for \POSIX{} or
\code{';'} for MS-DOS.
\end{datadesc}
\begin{datadesc}{defpath}
The default search path used by \code{exec*p*()} if the environment
doesn't have a \code{'PATH'} key.
\end{datadesc}
\begin{funcdesc}{execl}{path, arg0, arg1, ...}
This is equivalent to
\code{execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
\end{funcdesc}
\begin{funcdesc}{execle}{path, arg0, arg1, ..., env}
This is equivalent to
\code{execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
\end{funcdesc}
\begin{funcdesc}{execlp}{path, arg0, arg1, ...}
This is equivalent to
\code{execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
\end{funcdesc}
\begin{funcdesc}{execvp}{path, args}
This is like \code{execv(\var{path}, \var{args})} but duplicates
the shell's actions in searching for an executable file in a list of
directories. The directory list is obtained from
\code{environ['PATH']}.
\end{funcdesc}
\begin{funcdesc}{execvpe}{path, args, env}
This is a cross between \function{execve()} and \function{execvp()}.
The directory list is obtained from \code{\var{env}['PATH']}.
\end{funcdesc}
(The functions \code{execv()} and \code{execve()} are not
documented here, since they are implemented by the OS dependent
module. If the OS dependent module doesn't define either of these,
the functions that rely on it will raise an exception. They are
documented in the section on module \module{posix}, together with all
other functions that \module{os} imports from the OS dependent module.)

68
Doc/libpanel.tex
View File

@ -1,68 +0,0 @@
\section{Standard Module \module{panel}}
\label{module-panel}
\stmodindex{panel}
\strong{Please note:} The FORMS library, to which the
\code{fl}\refbimodindex{fl} module described above interfaces, is a
simpler and more accessible user interface library for use with GL
than the \code{panel} module (besides also being by a Dutch author).
This module should be used instead of the built-in module
\code{pnl}\refbimodindex{pnl}
to interface with the
\emph{Panel Library}.
The module is too large to document here in its entirety.
One interesting function:
\begin{funcdesc}{defpanellist}{filename}
Parses a panel description file containing S-expressions written by the
\emph{Panel Editor}
that accompanies the Panel Library and creates the described panels.
It returns a list of panel objects.
\end{funcdesc}
\strong{Warning:}
the Python interpreter will dump core if you don't create a GL window
before calling
\code{panel.mkpanel()}
or
\code{panel.defpanellist()}.
\section{Standard Module \module{panelparser}}
\label{module-panelparser}
\stmodindex{panelparser}
This module defines a self-contained parser for S-expressions as output
by the Panel Editor (which is written in Scheme so it can't help writing
S-expressions).
The relevant function is
\code{panelparser.parse_file(\var{file})}
which has a file object (not a filename!) as argument and returns a list
of parsed S-expressions.
Each S-expression is converted into a Python list, with atoms converted
to Python strings and sub-expressions (recursively) to Python lists.
For more details, read the module file.
% XXXXJH should be funcdesc, I think
\section{Built-in Module \module{pnl}}
\label{module-pnl}
\bimodindex{pnl}
This module provides access to the
\emph{Panel Library}
built by NASA Ames\index{NASA} (to get it, send e-mail to
\code{panel-request@nas.nasa.gov}).
All access to it should be done through the standard module
\code{panel}\refstmodindex{panel},
which transparantly exports most functions from
\code{pnl}
but redefines
\code{pnl.dopanel()}.
\strong{Warning:}
the Python interpreter will dump core if you don't create a GL window
before calling
\code{pnl.mkpanel()}.
The module is too large to document here in its entirety.

724
Doc/libparser.tex
View File

@ -1,724 +0,0 @@
% libparser.tex
%
% Copyright 1995 Virginia Polytechnic Institute and State University
% and Fred L. Drake, Jr. This copyright notice must be distributed on
% all copies, but this document otherwise may be distributed as part
% of the Python distribution. No fee may be charged for this document
% in any representation, either on paper or electronically. This
% restriction does not affect other elements in a distributed package
% in any way.
%
\section{Built-in Module \module{parser}}
\label{module-parser}
\bimodindex{parser}
\index{parsing!Python source code}
The \module{parser} module provides an interface to Python's internal
parser and byte-code compiler. The primary purpose for this interface
is to allow Python code to edit the parse tree of a Python expression
and create executable code from this. This is better than trying
to parse and modify an arbitrary Python code fragment as a string
because parsing is performed in a manner identical to the code
forming the application. It is also faster.
The \module{parser} module was written and documented by Fred
L. Drake, Jr. (\email{fdrake@acm.org}).%
\index{Drake, Fred L., Jr.}
There are a few things to note about this module which are important
to making use of the data structures created. This is not a tutorial
on editing the parse trees for Python code, but some examples of using
the \module{parser} module are presented.
Most importantly, a good understanding of the Python grammar processed
by the internal parser is required. For full information on the
language syntax, refer to the \emph{Python Language Reference}. The
parser itself is created from a grammar specification defined in the file
\file{Grammar/Grammar} in the standard Python distribution. The parse
trees stored in the AST objects created by this module are the
actual output from the internal parser when created by the
\function{expr()} or \function{suite()} functions, described below. The AST
objects created by \function{sequence2ast()} faithfully simulate those
structures. Be aware that the values of the sequences which are
considered ``correct'' will vary from one version of Python to another
as the formal grammar for the language is revised. However,
transporting code from one Python version to another as source text
will always allow correct parse trees to be created in the target
version, with the only restriction being that migrating to an older
version of the interpreter will not support more recent language
constructs. The parse trees are not typically compatible from one
version to another, whereas source code has always been
forward-compatible.
Each element of the sequences returned by \function{ast2list()} or
\function{ast2tuple()} has a simple form. Sequences representing
non-terminal elements in the grammar always have a length greater than
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
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
keywords used to identify the parent node type, such as the keyword
\keyword{if} in an \constant{if_stmt}, are included in the node tree without
any special treatment. For example, the \keyword{if} keyword is
represented by the tuple \code{(1, 'if')}, where \code{1} is the
numeric value associated with all \code{NAME} tokens, including
variable and function names defined by the user. In an alternate form
returned when line number information is requested, the same token
might be represented as \code{(1, 'if', 12)}, where the \code{12}
represents the line number at which the terminal symbol was found.
Terminal elements are represented in much the same way, but without
any child elements and the addition of the source text which was
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}.
The AST objects are not required to support the functionality of this
module, but are provided for three purposes: to allow an application
to amortize the cost of processing complex parse trees, to provide a
parse tree representation which conserves memory space when compared
to the Python list or tuple representation, and to ease the creation
of additional modules in C which manipulate parse trees. A simple
``wrapper'' class may be created in Python to hide the use of AST
objects.
The \module{parser} module defines functions for a few distinct
purposes. The most important purposes are to create AST objects and
to convert AST objects to other representations such as parse trees
and compiled code objects, but there are also functions which serve to
query the type of parse tree represented by an AST object.
\subsection{Creating AST Objects}
\label{Creating ASTs}
AST objects may be created from source code or from a parse tree.
When creating an AST object from source, different functions are used
to create the \code{'eval'} and \code{'exec'} forms.
\begin{funcdesc}{expr}{string}
The \function{expr()} function parses the parameter \code{\var{string}}
as if it were an input to \samp{compile(\var{string}, 'eval')}. If
the parse succeeds, an AST object is created to hold the internal
parse tree representation, otherwise an appropriate exception is
thrown.
\end{funcdesc}
\begin{funcdesc}{suite}{string}
The \function{suite()} function parses the parameter \code{\var{string}}
as if it were an input to \samp{compile(\var{string}, 'exec')}. If
the parse succeeds, an AST object is created to hold the internal
parse tree representation, otherwise an appropriate exception is
thrown.
\end{funcdesc}
\begin{funcdesc}{sequence2ast}{sequence}
This function accepts a parse tree represented as a sequence and
builds an internal representation if possible. If it can validate
that the tree conforms to the Python grammar and all nodes are valid
node types in the host version of Python, an AST object is created
from the internal representation and returned to the called. If there
is a problem creating the internal representation, or if the tree
cannot be validated, a \exception{ParserError} exception is thrown. An AST
object created this way should not be assumed to compile correctly;
normal exceptions thrown by compilation may still be initiated when
the AST object is passed to \function{compileast()}. This may indicate
problems not related to syntax (such as a \exception{MemoryError}
exception), but may also be due to constructs such as the result of
parsing \code{del f(0)}, which escapes the Python parser but is
checked by the bytecode compiler.
Sequences representing terminal tokens may be represented as either
two-element lists of the form \code{(1, 'name')} or as three-element
lists of the form \code{(1, 'name', 56)}. If the third element is
present, it is assumed to be a valid line number. The line number
may be specified for any subset of the terminal symbols in the input
tree.
\end{funcdesc}
\begin{funcdesc}{tuple2ast}{sequence}
This is the same function as \function{sequence2ast()}. This entry point
is maintained for backward compatibility.
\end{funcdesc}
\subsection{Converting AST Objects}
\label{Converting ASTs}
AST objects, regardless of the input used to create them, may be
converted to parse trees represented as list- or tuple- trees, or may
be compiled into executable code objects. Parse trees may be
extracted with or without line numbering information.
\begin{funcdesc}{ast2list}{ast\optional{, line_info}}
This function accepts an AST object from the caller in
\code{\var{ast}} and returns a Python list representing the
equivelent parse tree. The resulting list representation can be used
for inspection or the creation of a new parse tree in list form. This
function does not fail so long as memory is available to build the
list representation. If the parse tree will only be used for
inspection, \function{ast2tuple()} should be used instead to reduce memory
consumption and fragmentation. When the list representation is
required, this function is significantly faster than retrieving a
tuple representation and converting that to nested lists.
If \code{\var{line_info}} is true, line number information will be
included for all terminal tokens as a third element of the list
representing the token. Note that the line number provided specifies
the line on which the token \emph{ends}. This information is
omitted if the flag is false or omitted.
\end{funcdesc}
\begin{funcdesc}{ast2tuple}{ast\optional{, line_info}}
This function accepts an AST object from the caller in
\code{\var{ast}} and returns a Python tuple representing the
equivelent parse tree. Other than returning a tuple instead of a
list, this function is identical to \function{ast2list()}.
If \code{\var{line_info}} is true, line number information will be
included for all terminal tokens as a third element of the list
representing the token. This information is omitted if the flag is
false or omitted.
\end{funcdesc}
\begin{funcdesc}{compileast}{ast\optional{, filename\code{ = '<ast>'}}}
The Python byte compiler can be invoked on an AST object to produce
code objects which can be used as part of an \code{exec} statement or
a call to the built-in \function{eval()}\bifuncindex{eval} function.
This function provides the interface to the compiler, passing the
internal parse tree from \code{\var{ast}} to the parser, using the
source file name specified by the \code{\var{filename}} parameter.
The default value supplied for \code{\var{filename}} indicates that
the source was an AST object.
Compiling an AST object may result in exceptions related to
compilation; an example would be a \exception{SyntaxError} caused by the
parse tree for \code{del f(0)}: this statement is considered legal
within the formal grammar for Python but is not a legal language
construct. The \exception{SyntaxError} raised for this condition is
actually generated by the Python byte-compiler normally, which is why
it can be raised at this point by the \module{parser} module. Most
causes of compilation failure can be diagnosed programmatically by
inspection of the parse tree.
\end{funcdesc}
\subsection{Queries on AST Objects}
\label{Querying ASTs}
Two functions are provided which allow an application to determine if
an AST was created as an expression or a suite. Neither of these
functions can be used to determine if an AST was created from source
code via \function{expr()} or \function{suite()} or from a parse tree
via \function{sequence2ast()}.
\begin{funcdesc}{isexpr}{ast}
When \code{\var{ast}} represents an \code{'eval'} form, this function
returns true, otherwise it returns false. This is useful, since code
objects normally cannot be queried for this information using existing
built-in functions. Note that the code objects created by
\function{compileast()} cannot be queried like this either, and are
identical to those created by the built-in
\function{compile()}\bifuncindex{compile} function.
\end{funcdesc}
\begin{funcdesc}{issuite}{ast}
This function mirrors \function{isexpr()} in that it reports whether an
AST object represents an \code{'exec'} form, commonly known as a
``suite.'' It is not safe to assume that this function is equivelent
to \samp{not isexpr(\var{ast})}, as additional syntactic fragments may
be supported in the future.
\end{funcdesc}
\subsection{Exceptions and Error Handling}
\label{AST Errors}
The parser module defines a single exception, but may also pass other
built-in exceptions from other portions of the Python runtime
environment. See each function for information about the exceptions
it can raise.
\begin{excdesc}{ParserError}
Exception raised when a failure occurs within the parser module. This
is generally produced for validation failures rather than the built in
\exception{SyntaxError} thrown during normal parsing.
The exception argument is either a string describing the reason of the
failure or a tuple containing a sequence causing the failure from a parse
tree passed to \function{sequence2ast()} and an explanatory string. Calls to
\function{sequence2ast()} need to be able to handle either type of exception,
while calls to other functions in the module will only need to be
aware of the simple string values.
\end{excdesc}
Note that the functions \function{compileast()}, \function{expr()}, and
\function{suite()} may throw exceptions which are normally thrown by the
parsing and compilation process. These include the built in
exceptions \exception{MemoryError}, \exception{OverflowError},
\exception{SyntaxError}, and \exception{SystemError}. In these cases, these
exceptions carry all the meaning normally associated with them. Refer
to the descriptions of each function for detailed information.
\subsection{AST Objects}
\label{AST Objects}
AST objects returned by \function{expr()}, \function{suite()} and
\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
supported.
\begin{datadesc}{ASTType}
The type of the objects returned by \function{expr()},
\function{suite()} and \function{sequence2ast()}.
\end{datadesc}
AST objects have the following methods:
\begin{methoddesc}[AST]{compile}{\optional{filename}}
Same as \code{compileast(\var{ast}, \var{filename})}.
\end{methoddesc}
\begin{methoddesc}[AST]{isexpr}{}
Same as \code{isexpr(\var{ast})}.
\end{methoddesc}
\begin{methoddesc}[AST]{issuite}{}
Same as \code{issuite(\var{ast})}.
\end{methoddesc}
\begin{methoddesc}[AST]{tolist}{\optional{line_info}}
Same as \code{ast2list(\var{ast}, \var{line_info})}.
\end{methoddesc}
\begin{methoddesc}[AST]{totuple}{\optional{line_info}}
Same as \code{ast2tuple(\var{ast}, \var{line_info})}.
\end{methoddesc}
\subsection{Examples}
\nodename{AST Examples}
The parser modules allows operations to be performed on the parse tree
of Python source code before the bytecode is generated, and provides
for inspection of the parse tree for information gathering purposes.
Two examples are presented. The simple example demonstrates emulation
of the \function{compile()}\bifuncindex{compile} built-in function and
the complex example shows the use of a parse tree for information
discovery.
\subsubsection{Emulation of \function{compile()}}
While many useful operations may take place between parsing and
bytecode generation, the simplest operation is to do nothing. For
this purpose, using the \module{parser} module to produce an
intermediate data structure is equivelent to the code
\begin{verbatim}
>>> code = compile('a + 5', 'eval')
>>> a = 5
>>> eval(code)
10
\end{verbatim}
The equivelent operation using the \module{parser} module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
\begin{verbatim}
>>> import parser
>>> ast = parser.expr('a + 5')
>>> code = parser.compileast(ast)
>>> a = 5
>>> eval(code)
10
\end{verbatim}
An application which needs both AST and code objects can package this
code into readily available functions:
\begin{verbatim}
import parser
def load_suite(source_string):
ast = parser.suite(source_string)
code = parser.compileast(ast)
return ast, code
def load_expression(source_string):
ast = parser.expr(source_string)
code = parser.compileast(ast)
return ast, code
\end{verbatim}
\subsubsection{Information Discovery}
Some applications benefit from direct access to the parse tree. The
remainder of this section demonstrates how the parse tree provides
access to module documentation defined in docstrings without requiring
that the code being examined be loaded into a running interpreter via
\keyword{import}. This can be very useful for performing analyses of
untrusted code.
Generally, the example will demonstrate how the parse tree may be
traversed to distill interesting information. Two functions and a set
of classes are developed which provide programmatic access to high
level function and class definitions provided by a module. The
classes extract information from the parse tree and provide access to
the information at a useful semantic level, one function provides a
simple low-level pattern matching capability, and the other function
defines a high-level interface to the classes by handling file
operations on behalf of the caller. All source files mentioned here
which are not part of the Python installation are located in the
\file{Demo/parser/} directory of the distribution.
The dynamic nature of Python allows the programmer a great deal of
flexibility, but most modules need only a limited measure of this when
defining classes, functions, and methods. In this example, the only
definitions that will be considered are those which are defined in the
top level of their context, e.g., a function defined by a \keyword{def}
statement at column zero of a module, but not a function defined
within a branch of an \code{if} ... \code{else} construct, though
there are some good reasons for doing so in some situations. Nesting
of definitions will be handled by the code developed in the example.
To construct the upper-level extraction methods, we need to know what
the parse tree structure looks like and how much of it we actually
need to be concerned about. Python uses a moderately deep parse tree
so there are a large number of intermediate nodes. It is important to
read and understand the formal grammar used by Python. This is
specified in the file \file{Grammar/Grammar} in the distribution.
Consider the simplest case of interest when searching for docstrings:
a module consisting of a docstring and nothing else. (See file
\file{docstring.py}.)
\begin{verbatim}
"""Some documentation.
"""
\end{verbatim}
Using the interpreter to take a look at the parse tree, we find a
bewildering mass of numbers and parentheses, with the documentation
buried deep in nested tuples.
\begin{verbatim}
>>> import parser
>>> import pprint
>>> ast = parser.suite(open('docstring.py').read())
>>> tup = parser.ast2tuple(ast)
>>> pprint.pprint(tup)
(257,
(264,
(265,
(266,
(267,
(307,
(287,
(288,
(289,
(290,
(292,
(293,
(294,
(295,
(296,
(297,
(298,
(299,
(300, (3, '"""Some documentation.\012"""'))))))))))))))))),
(4, ''))),
(4, ''),
(0, ''))
\end{verbatim}
The numbers at the first element of each node in the tree are the node
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
provide symbolic names for the node types and dictionaries which map
from the integers to the symbolic names for the node types.
In the output presented above, the outermost tuple contains four
elements: the integer \code{257} and three additional tuples. Node
type \code{257} has the symbolic name \constant{file_input}. Each of
these inner tuples contains an integer as the first element; these
integers, \code{264}, \code{4}, and \code{0}, represent the node types
\constant{stmt}, \constant{NEWLINE}, and \constant{ENDMARKER},
respectively.
Note that these values may change depending on the version of Python
you are using; consult \file{symbol.py} and \file{token.py} for
details of the mapping. It should be fairly clear that the outermost
node is related primarily to the input source rather than the contents
of the file, and may be disregarded for the moment. The \constant{stmt}
node is much more interesting. In particular, all docstrings are
found in subtrees which are formed exactly as this node is formed,
with the only difference being the string itself. The association
between the docstring in a similar tree and the defined entity (class,
function, or module) which it describes is given by the position of
the docstring subtree within the tree defining the described
structure.
By replacing the actual docstring with something to signify a variable
component of the tree, we allow a simple pattern matching approach to
check any given subtree for equivelence to the general pattern for
docstrings. Since the example demonstrates information extraction, we
can safely require that the tree be in tuple form rather than list
form, allowing a simple variable representation to be
\code{['variable_name']}. A simple recursive function can implement
the pattern matching, returning a boolean and a dictionary of variable
name to value mappings. (See file \file{example.py}.)
\begin{verbatim}
from types import ListType, TupleType
def match(pattern, data, vars=None):
if vars is None:
vars = {}
if type(pattern) is ListType:
vars[pattern[0]] = data
return 1, vars
if type(pattern) is not TupleType:
return (pattern == data), vars
if len(data) != len(pattern):
return 0, vars
for pattern, data in map(None, pattern, data):
same, vars = match(pattern, data, vars)
if not same:
break
return same, vars
\end{verbatim}
Using this simple representation for syntactic variables and the symbolic
node types, the pattern for the candidate docstring subtrees becomes
fairly readable. (See file \file{example.py}.)
\begin{verbatim}
import symbol
import token
DOCSTRING_STMT_PATTERN = (
symbol.stmt,
(symbol.simple_stmt,
(symbol.small_stmt,
(symbol.expr_stmt,
(symbol.testlist,
(symbol.test,
(symbol.and_test,
(symbol.not_test,
(symbol.comparison,
(symbol.expr,
(symbol.xor_expr,
(symbol.and_expr,
(symbol.shift_expr,
(symbol.arith_expr,
(symbol.term,
(symbol.factor,
(symbol.power,
(symbol.atom,
(token.STRING, ['docstring'])
)))))))))))))))),
(token.NEWLINE, '')
))
\end{verbatim}
Using the \function{match()} function with this pattern, extracting the
module docstring from the parse tree created previously is easy:
\begin{verbatim}
>>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
>>> found
1
>>> vars
{'docstring': '"""Some documentation.\012"""'}
\end{verbatim}
Once specific data can be extracted from a location where it is
expected, the question of where information can be expected
needs to be answered. When dealing with docstrings, the answer is
fairly simple: the docstring is the first \constant{stmt} node in a code
block (\constant{file_input} or \constant{suite} node types). A module
consists of a single \constant{file_input} node, and class and function
definitions each contain exactly one \constant{suite} node. Classes and
functions are readily identified as subtrees of code block nodes which
start with \code{(stmt, (compound_stmt, (classdef, ...} or
\code{(stmt, (compound_stmt, (funcdef, ...}. Note that these subtrees
cannot be matched by \function{match()} since it does not support multiple
sibling nodes to match without regard to number. A more elaborate
matching function could be used to overcome this limitation, but this
is sufficient for the example.
Given the ability to determine whether a statement might be a
docstring and extract the actual string from the statement, some work
needs to be performed to walk the parse tree for an entire module and
extract information about the names defined in each context of the
module and associate any docstrings with the names. The code to
perform this work is not complicated, but bears some explanation.
The public interface to the classes is straightforward and should
probably be somewhat more flexible. Each ``major'' block of the
module is described by an object providing several methods for inquiry
and a constructor which accepts at least the subtree of the complete
parse tree which it represents. The \class{ModuleInfo} constructor
accepts an optional \var{name} parameter since it cannot
otherwise determine the name of the module.
The public classes include \class{ClassInfo}, \class{FunctionInfo},
and \class{ModuleInfo}. All objects provide the
methods \method{get_name()}, \method{get_docstring()},
\method{get_class_names()}, and \method{get_class_info()}. The
\class{ClassInfo} objects support \method{get_method_names()} and
\method{get_method_info()} while the other classes provide
\method{get_function_names()} and \method{get_function_info()}.
Within each of the forms of code block that the public classes
represent, most of the required information is in the same form and is
accessed in the same way, with classes having the distinction that
functions defined at the top level are referred to as ``methods.''
Since the difference in nomenclature reflects a real semantic
distinction from functions defined outside of a class, the
implementation needs to maintain the distinction.
Hence, most of the functionality of the public classes can be
implemented in a common base class, \class{SuiteInfoBase}, with the
accessors for function and method information provided elsewhere.
Note that there is only one class which represents function and method
information; this parallels the use of the \keyword{def} statement to
define both types of elements.
Most of the accessor functions are declared in \class{SuiteInfoBase}
and do not need to be overriden by subclasses. More importantly, the
extraction of most information from a parse tree is handled through a
method called by the \class{SuiteInfoBase} constructor. The example
code for most of the classes is clear when read alongside the formal
grammar, but the method which recursively creates new information
objects requires further examination. Here is the relevant part of
the \class{SuiteInfoBase} definition from \file{example.py}:
\begin{verbatim}
class SuiteInfoBase:
_docstring = ''
_name = ''
def __init__(self, tree = None):
self._class_info = {}
self._function_info = {}
if tree:
self._extract_info(tree)
def _extract_info(self, tree):
# extract docstring
if len(tree) == 2:
found, vars = match(DOCSTRING_STMT_PATTERN[1], tree[1])
else:
found, vars = match(DOCSTRING_STMT_PATTERN, tree[3])
if found:
self._docstring = eval(vars['docstring'])
# discover inner definitions
for node in tree[1:]:
found, vars = match(COMPOUND_STMT_PATTERN, node)
if found:
cstmt = vars['compound']
if cstmt[0] == symbol.funcdef:
name = cstmt[2][1]
self._function_info[name] = FunctionInfo(cstmt)
elif cstmt[0] == symbol.classdef:
name = cstmt[2][1]
self._class_info[name] = ClassInfo(cstmt)
\end{verbatim}
After initializing some internal state, the constructor calls the
\method{_extract_info()} method. This method performs the bulk of the
information extraction which takes place in the entire example. The
extraction has two distinct phases: the location of the docstring for
the parse tree passed in, and the discovery of additional definitions
within the code block represented by the parse tree.
The initial \keyword{if} test determines whether the nested suite is of
the ``short form'' or the ``long form.'' The short form is used when
the code block is on the same line as the definition of the code
block, as in
\begin{verbatim}
def square(x): "Square an argument."; return x ** 2
\end{verbatim}
while the long form uses an indented block and allows nested
definitions:
\begin{verbatim}
def make_power(exp):
"Make a function that raises an argument to the exponent `exp'."
def raiser(x, y=exp):
return x ** y
return raiser
\end{verbatim}
When the short form is used, the code block may contain a docstring as
the first, and possibly only, \constant{small_stmt} element. The
extraction of such a docstring is slightly different and requires only
a portion of the complete pattern used in the more common case. As
implemented, the docstring will only be found if there is only
one \constant{small_stmt} node in the \constant{simple_stmt} node.
Since most functions and methods which use the short form do not
provide a docstring, this may be considered sufficient. The
extraction of the docstring proceeds using the \function{match()} function
as described above, and the value of the docstring is stored as an
attribute of the \class{SuiteInfoBase} object.
After docstring extraction, a simple definition discovery
algorithm operates on the \constant{stmt} nodes of the
\constant{suite} node. The special case of the short form is not
tested; since there are no \constant{stmt} nodes in the short form,
the algorithm will silently skip the single \constant{simple_stmt}
node and correctly not discover any nested definitions.
Each statement in the code block is categorized as
a class definition, function or method definition, or
something else. For the definition statements, the name of the
element defined is extracted and a representation object
appropriate to the definition is created with the defining subtree
passed as an argument to the constructor. The repesentation objects
are stored in instance variables and may be retrieved by name using
the appropriate accessor methods.
The public classes provide any accessors required which are more
specific than those provided by the \class{SuiteInfoBase} class, but
the real extraction algorithm remains common to all forms of code
blocks. A high-level function can be used to extract the complete set
of information from a source file. (See file \file{example.py}.)
\begin{verbatim}
def get_docs(fileName):
source = open(fileName).read()
import os
basename = os.path.basename(os.path.splitext(fileName)[0])
import parser
ast = parser.suite(source)
tup = parser.ast2tuple(ast)
return ModuleInfo(tup, basename)
\end{verbatim}
This provides an easy-to-use interface to the documentation of a
module. If information is required which is not extracted by the code
of this example, the code may be extended at clearly defined points to
provide additional capabilities.
\begin{seealso}
\seemodule{symbol}{useful constants representing internal nodes of the
parse tree}
\seemodule{token}{useful constants representing leaf nodes of the
parse tree and functions for testing node values}
\end{seealso}

298
Doc/libpdb.tex
View File

@ -1,298 +0,0 @@
\chapter{The Python Debugger}
\label{module-pdb}
\stmodindex{pdb}
\index{debugging}
The module \code{pdb} defines an interactive source code debugger for
Python programs. It supports setting
(conditional) breakpoints and single stepping
at the source line level, inspection of stack frames, source code
listing, and evaluation of arbitrary Python code in the context of any
stack frame. It also supports post-mortem debugging and can be called
under program control.
The debugger is extensible --- it is actually defined as a class
\class{Pdb}.
\withsubitem{(class in pdb)}{\ttindex{Pdb}}
This is currently undocumented but easily understood by reading the
source. The extension interface uses the (also undocumented) modules
\module{bdb}\refstmodindex{bdb} and \module{cmd}\refstmodindex{cmd}.
A primitive windowing version of the debugger also exists --- this is
module \module{wdb}, which requires \module{stdwin} (see the chapter
on STDWIN specific modules).
\refbimodindex{stdwin}
\refstmodindex{wdb}
The debugger's prompt is \samp{(Pdb) }.
Typical usage to run a program under control of the debugger is:
\begin{verbatim}
>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)
\end{verbatim}
\file{pdb.py} can also be invoked as
a script to debug other scripts. For example:
\begin{verbatim}
python /usr/local/lib/python1.5/pdb.py myscript.py
\end{verbatim}
Typical usage to inspect a crashed program is:
\begin{verbatim}
>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (innermost last):
File "<stdin>", line 1, in ?
File "./mymodule.py", line 4, in test
test2()
File "./mymodule.py", line 3, in test2
print spam
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print spam
(Pdb)
\end{verbatim}
The module defines the following functions; each enters the debugger
in a slightly different way:
\begin{funcdesc}{run}{statement\optional{, globals\optional{, locals}}}
Execute the \var{statement} (given as a string) under debugger
control. The debugger prompt appears before any code is executed; you
can set breakpoints and type \code{continue}, or you can step through
the statement using \code{step} or \code{next} (all these commands are
explained below). The optional \var{globals} and \var{locals}
arguments specify the environment in which the code is executed; by
default the dictionary of the module \code{__main__} is used. (See
the explanation of the \code{exec} statement or the \code{eval()}
built-in function.)
\end{funcdesc}
\begin{funcdesc}{runeval}{expression\optional{, globals\optional{, locals}}}
Evaluate the \var{expression} (given as a a string) under debugger
control. When \code{runeval()} returns, it returns the value of the
expression. Otherwise this function is similar to
\code{run()}.
\end{funcdesc}
\begin{funcdesc}{runcall}{function\optional{, argument, ...}}
Call the \var{function} (a function or method object, not a string)
with the given arguments. When \code{runcall()} returns, it returns
whatever the function call returned. The debugger prompt appears as
soon as the function is entered.
\end{funcdesc}
\begin{funcdesc}{set_trace}{}
Enter the debugger at the calling stack frame. This is useful to
hard-code a breakpoint at a given point in a program, even if the code
is not otherwise being debugged (e.g. when an assertion fails).
\end{funcdesc}
\begin{funcdesc}{post_mortem}{traceback}
Enter post-mortem debugging of the given \var{traceback} object.
\end{funcdesc}
\begin{funcdesc}{pm}{}
Enter post-mortem debugging of the traceback found in
\code{sys.last_traceback}.
\end{funcdesc}
\section{Debugger Commands}
The debugger recognizes the following commands. Most commands can be
abbreviated to one or two letters; e.g. ``\code{h(elp)}'' means that
either ``\code{h}'' or ``\code{help}'' can be used to enter the help
command (but not ``\code{he}'' or ``\code{hel}'', nor ``\code{H}'' or
``\code{Help} or ``\code{HELP}''). Arguments to commands must be
separated by whitespace (spaces or tabs). Optional arguments are
enclosed in square brackets (``\code{[]}'') in the command syntax; the
square brackets must not be typed. Alternatives in the command syntax
are separated by a vertical bar (``\code{|}'').
Entering a blank line repeats the last command entered. Exception: if
the last command was a ``\code{list}'' command, the next 11 lines are
listed.
Commands that the debugger doesn't recognize are assumed to be Python
statements and are executed in the context of the program being
debugged. Python statements can also be prefixed with an exclamation
point (``\code{!}''). This is a powerful way to inspect the program
being debugged; it is even possible to change a variable or call a
function. When an
exception occurs in such a statement, the exception name is printed
but the debugger's state is not changed.
\begin{description}
\item[h(elp) \optional{\var{command}}]
Without argument, print the list of available commands. With a
\var{command} as argument, print help about that command. \samp{help
pdb} displays the full documentation file; if the environment variable
\code{PAGER} is defined, the file is piped through that command
instead. Since the \var{command} argument must be an identifier,
\samp{help exec} must be entered to get help on the \samp{!} command.
\item[w(here)]
Print a stack trace, with the most recent frame at the bottom. An
arrow indicates the current frame, which determines the context of
most commands.
\item[d(own)]
Move the current frame one level down in the stack trace
(to an older frame).
\item[u(p)]
Move the current frame one level up in the stack trace
(to a newer frame).
\item[b(reak) \optional{\var{lineno}\code{\Large|}\var{function}%
\optional{, \code{'}\var{condition}\code{'}}}]
With a \var{lineno} argument, set a break there in the current
file. With a \var{function} argument, set a break at the entry of
that function. Without argument, list all breaks.
If a second argument is present, it is a string (included in string
quotes!) specifying an expression which must evaluate to true before
the breakpoint is honored.
\item[cl(ear) \optional{\var{lineno}}]
With a \var{lineno} argument, clear that break in the current file.
Without argument, clear all breaks (but first ask confirmation).
\item[s(tep)]
Execute the current line, stop at the first possible occasion
(either in a function that is called or on the next line in the
current function).
\item[n(ext)]
Continue execution until the next line in the current function
is reached or it returns. (The difference between \code{next} and
\code{step} is that \code{step} stops inside a called function, while
\code{next} executes called functions at (nearly) full speed, only
stopping at the next line in the current function.)
\item[r(eturn)]
Continue execution until the current function returns.
\item[c(ont(inue))]
Continue execution, only stop when a breakpoint is encountered.
\item[l(ist) \optional{\var{first\optional{, last}}}]
List source code for the current file. Without arguments, list 11
lines around the current line or continue the previous listing. With
one argument, list 11 lines around at that line. With two arguments,
list the given range; if the second argument is less than the first,
it is interpreted as a count.
\item[a(rgs)]
Print the argument list of the current function.
\item[p \var{expression}]
Evaluate the \var{expression} in the current context and print its
value. (Note: \code{print} can also be used, but is not a debugger
command --- this executes the Python \code{print} statement.)
\item[\optional{!}\var{statement}]
Execute the (one-line) \var{statement} in the context of
the current stack frame.
The exclamation point can be omitted unless the first word
of the statement resembles a debugger command.
To set a global variable, you can prefix the assignment
command with a ``\code{global}'' command on the same line, e.g.:
\begin{verbatim}
(Pdb) global list_options; list_options = ['-l']
(Pdb)
\end{verbatim}
\item[q(uit)]
Quit from the debugger.
The program being executed is aborted.
\end{description}
\section{How It Works}
Some changes were made to the interpreter:
\begin{itemize}
\item \code{sys.settrace(\var{func})} sets the global trace function
\item there can also a local trace function (see later)
\end{itemize}
Trace functions have three arguments: \var{frame}, \var{event}, and
\var{arg}. \var{frame} is the current stack frame. \var{event} is a
string: \code{'call'}, \code{'line'}, \code{'return'} or
\code{'exception'}. \var{arg} depends on the event type.
The global trace function is invoked (with \var{event} set to
\code{'call'}) whenever a new local scope is entered; it should return
a reference to the local trace function to be used that scope, or
\code{None} if the scope shouldn't be traced.
The local trace function should return a reference to itself (or to
another function for further tracing in that scope), or \code{None} to
turn off tracing in that scope.
Instance methods are accepted (and very useful!) as trace functions.
The events have the following meaning:
\begin{description}
\item[\code{'call'}]
A function is called (or some other code block entered). The global
trace function is called; arg is the argument list to the function;
the return value specifies the local trace function.
\item[\code{'line'}]
The interpreter is about to execute a new line of code (sometimes
multiple line events on one line exist). The local trace function is
called; arg in None; the return value specifies the new local trace
function.
\item[\code{'return'}]
A function (or other code block) is about to return. The local trace
function is called; arg is the value that will be returned. The trace
function's return value is ignored.
\item[\code{'exception'}]
An exception has occurred. The local trace function is called; arg is
a triple (exception, value, traceback); the return value specifies the
new local trace function
\end{description}
Note that as an exception is propagated down the chain of callers, an
\code{'exception'} event is generated at each level.
For more information on code and frame objects, refer to the
\emph{Python Reference Manual}.

290
Doc/libpickle.tex
View File

@ -1,290 +0,0 @@
\section{Standard Module \module{pickle}}
\label{module-pickle}
\stmodindex{pickle}
\index{persistency}
\indexii{persistent}{objects}
\indexii{serializing}{objects}
\indexii{marshalling}{objects}
\indexii{flattening}{objects}
\indexii{pickling}{objects}
The \module{pickle} module implements a basic but powerful algorithm for
``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly
arbitrary Python objects. This is the act of converting objects to a
stream of bytes (and back: ``unpickling'').
This is a more primitive notion than
persistency --- although \module{pickle} reads and writes file objects,
it does not handle the issue of naming persistent objects, nor the
(even more complicated) area of concurrent access to persistent
objects. The \module{pickle} module can transform a complex object into
a byte stream and it can transform the byte stream into an object with
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}
\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}
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}
\begin{itemize}
\item recursive objects (objects containing references to themselves)
\item object sharing (references to the same object in different places)
\item user-defined classes and their instances
\end{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.
By default, the \module{pickle} data format uses a printable \ASCII{}
representation. This is slightly more voluminous than a binary
representation. The big advantage of using printable \ASCII{} (and of
some other characteristics of \module{pickle}'s representation) is that
for debugging or recovery purposes it is possible for a human to read
the pickled file with a standard text editor.
A binary format, which is slightly more efficient, can be chosen by
specifying a nonzero (true) value for the \var{bin} argument to the
\class{Pickler} constructor or the \function{dump()} and \function{dumps()}
functions. The binary format is not the default because of backwards
compatibility with the Python 1.4 pickle module. In a future version,
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
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
code objects), and at least this avoids the possibility of smuggling
Trojan horses into a program.
\refbimodindex{marshal}
For the benefit of persistency modules written using \module{pickle}, it
supports the notion of a reference to an object outside the pickled
data stream. Such objects are referenced by a name, which is an
arbitrary string of printable \ASCII{} characters. The resolution of
such names is not defined by the \module{pickle} module --- the
persistent object module will have to implement a method
\method{persistent_load()}. To write references to persistent objects,
the persistent module must define a method \method{persistent_id()} which
returns either \code{None} or the persistent ID of the object.
There are some restrictions on the pickling of class instances.
First of all, the class must be defined at the top level in a module.
Furthermore, all its instance variables must be picklable.
\setindexsubitem{(pickle protocol)}
When a pickled class instance is unpickled, its \method{__init__()} method
is normally \emph{not} invoked. \strong{Note:} This is a deviation
from previous versions of this module; the change was introduced in
Python 1.5b2. The reason for the change is that in many cases it is
desirable to have a constructor that requires arguments; it is a
(minor) nuisance to have to provide a \method{__getinitargs__()} method.
If it is desirable that the \method{__init__()} method be called on
unpickling, a class can define a method \method{__getinitargs__()},
which should return a \emph{tuple} containing the arguments to be
passed to the class constructor (\method{__init__()}). This method is
called at pickle time; the tuple it returns is incorporated in the
pickle for the instance.
\ttindex{__getinitargs__()}
\ttindex{__init__()}
Classes can further influence how their instances are pickled --- if the class
defines the method \method{__getstate__()}, it is called and the return
state is pickled as the contents for the instance, and if the class
defines the method \method{__setstate__()}, it is called with the
unpickled state. (Note that these methods can also be used to
implement copying class instances.) If there is no
\method{__getstate__()} method, the instance's \member{__dict__} is
pickled. If there is no \method{__setstate__()} method, the pickled
object must be a dictionary and its items are assigned to the new
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}
\ttindex{__getstate__()}
\ttindex{__setstate__()}
\ttindex{__dict__}
Note that when class instances are pickled, their class's code and
data are not pickled along with them. Only the instance data are
pickled. This is done on purpose, so you can fix bugs in a class or
add methods and still load objects that were created with an earlier
version of the class. If you plan to have long-lived objects that
will see many versions of a class, it may be worthwhile to put a version
number in the objects so that suitable conversions can be made by the
class's \method{__setstate__()} method.
When a class itself is pickled, only its name is pickled --- the class
definition is not pickled, but re-imported by the unpickling process.
Therefore, the restriction that the class must be defined at the top
level in a module applies to pickled classes as well.
\setindexsubitem{(in module pickle)}
The interface can be summarized as follows.
To pickle an object \code{x} onto a file \code{f}, open for writing:
\begin{verbatim}
p = pickle.Pickler(f)
p.dump(x)
\end{verbatim}
A shorthand for this is:
\begin{verbatim}
pickle.dump(x, f)
\end{verbatim}
To unpickle an object \code{x} from a file \code{f}, open for reading:
\begin{verbatim}
u = pickle.Unpickler(f)
x = u.load()
\end{verbatim}
A shorthand is:
\begin{verbatim}
x = pickle.load(f)
\end{verbatim}
The \class{Pickler} class only calls the method \code{f.write()} with a
string argument. The \class{Unpickler} calls the methods \code{f.read()}
(with an integer argument) and \code{f.readline()} (without argument),
both returning a string. It is explicitly allowed to pass non-file
objects here, as long as they have the right methods.
\ttindex{Unpickler}
\ttindex{Pickler}
The constructor for the \class{Pickler} class has an optional second
argument, \var{bin}. If this is present and nonzero, the binary
pickle format is used; if it is zero or absent, the (less efficient,
but backwards compatible) text pickle format is used. The
\class{Unpickler} class does not have an argument to distinguish
between binary and text pickle formats; it accepts either format.
The following types can be pickled:
\begin{itemize}
\item \code{None}
\item integers, long integers, floating point numbers
\item strings
\item tuples, lists and dictionaries containing only picklable objects
\item classes that are defined at the top level in a module
\item instances of such classes whose \member{__dict__} or
\method{__setstate__()} is picklable
\end{itemize}
Attempts to pickle unpicklable objects will raise the
\exception{PicklingError} exception; when this happens, an unspecified
number of bytes may have been written to the file.
It is possible to make multiple calls to the \method{dump()} method of
the same \class{Pickler} instance. These must then be matched to the
same number of calls to the \method{load()} method of the
corresponding \class{Unpickler} instance. If the same object is
pickled by multiple \method{dump()} calls, the \method{load()} will all
yield references to the same object. \emph{Warning}: this is intended
for pickling multiple objects without intervening modifications to the
objects or their parts. If you modify an object and then pickle it
again using the same \class{Pickler} instance, the object is not
pickled again --- a reference to it is pickled and the
\class{Unpickler} will return the old value, not the modified one.
(There are two problems here: (a) detecting changes, and (b)
marshalling a minimal set of changes. I have no answers. Garbage
Collection may also become a problem here.)
Apart from the \class{Pickler} and \class{Unpickler} classes, the
module defines the following functions, and an exception:
\begin{funcdesc}{dump}{object, file\optional{, bin}}
Write a pickled representation of \var{obect} to the open file object
\var{file}. This is equivalent to
\samp{Pickler(\var{file}, \var{bin}).dump(\var{object})}.
If the optional \var{bin} argument is present and nonzero, the binary
pickle format is used; if it is zero or absent, the (less efficient)
text pickle format is used.
\end{funcdesc}
\begin{funcdesc}{load}{file}
Read a pickled object from the open file object \var{file}. This is
equivalent to \samp{Unpickler(\var{file}).load()}.
\end{funcdesc}
\begin{funcdesc}{dumps}{object\optional{, bin}}
Return the pickled representation of the object as a string, instead
of writing it to a file. If the optional \var{bin} argument is
present and nonzero, the binary pickle format is used; if it is zero
or absent, the (less efficient) text pickle format is used.
\end{funcdesc}
\begin{funcdesc}{loads}{string}
Read a pickled object from a string instead of a file. Characters in
the string past the pickled object's representation are ignored.
\end{funcdesc}
\begin{excdesc}{PicklingError}
This exception is raised when an unpicklable object is passed to
\code{Pickler.dump()}.
\end{excdesc}
\begin{seealso}
\seemodule[copyreg]{copy_reg}{pickle interface constructor
registration}
\seemodule{shelve}{indexed databases of objects; uses \module{pickle}}
\seemodule{copy}{shallow and deep object copying}
\seemodule{marshal}{high-performance serialization of built-in types}
\end{seealso}
\section{Built-in Module \module{cPickle}}
\bimodindex{cPickle}
\label{module-cPickle}
% 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
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
\module{cPickle} interchangably with existing pickles.

71
Doc/libpopen2.tex
View File

@ -1,71 +0,0 @@
% This section was contributed by Drew Csillag
% <drew_csillag@geocities.com>, with some re-organization by Fred L.
% Drake, Jr. <fdrake@acm.org>.
\section{Standard Module \module{popen2}}
\label{module-popen2}
\stmodindex{popen2}
This module allows you to spawn processes and connect their
input/output/error pipes and obtain their return codes.
The primary interface offered by this module is a pair of factory
functions:
\begin{funcdesc}{popen2}{cmd\optional{, bufsize}}
Executes \var{cmd} as a sub-process. If \var{bufsize} is specified,
it specifies the buffer size for the I/O pipes. Returns
\code{(\var{child_stdout}, \var{child_stdin})}.
\end{funcdesc}
\begin{funcdesc}{popen2}{cmd\optional{, bufsize}}
Executes \var{cmd} as a sub-process. If \var{bufsize} is specified,
it specifies the buffer size for the I/O pipes. Returns
\code{(\var{child_stdout}, \var{child_stdin}, \var{child_stderr})}.
\end{funcdesc}
The class defining the objects returned by the factory functions is
also available:
\begin{classdesc}{Popen3}{cmd\optional{, capturestderr\optional{, bufsize}}}
This class represents a child process. Normally, \class{Popen3}
instances are created using the factory functions described above.
If not using one off the helper functions to create \class{Popen3}
objects, the parameter \var{cmd} is the shell command to execute in a
sub-process. The \var{capturestderr} flag, if true, specifies that
the object should capture standard error output of the child process.
The default is false. If the \var{bufsize} parameter is specified, it
specifies the size of the I/O buffers to/from the child process.
\end{classdesc}
\subsection{Popen3 Objects}
\label{popen3-objects}
Instances of the \class{Popen3} class have the following methods:
\begin{methoddesc}{poll}{}
Returns \code{-1} if child process hasn't completed yet, or its return
code otherwise.
\end{methoddesc}
\begin{methoddesc}{wait}{}
Waits for and returns the return code of the child process.
\end{methoddesc}
The following attributes of \class{Popen3} objects are also available:
\begin{datadesc}{fromchild}
A file object that provides output from the child process.
\end{datadesc}
\begin{datadesc}{tochild}
A file object that provides input to the child process.
\end{datadesc}
\begin{datadesc}{childerr}
Where the standard error from the child process goes is
\var{capturestderr} was true for the constructor, or \code{None}.
\end{datadesc}

131
Doc/libpoplib.tex
View File

@ -1,131 +0,0 @@
%By Andrew T. Csillag
%Even though I put it into LaTeX, I cannot really claim that I wrote
%it since I just stole most of it from the poplib.py source code and
%the imaplib ``chapter''.
\section{Standard Module \module{poplib}}
\stmodindex{poplib}
\label{module-poplib}
\indexii{POP3}{protocol}
This module defines a class, \class{POP3}, which encapsulates a
connection to an POP3 server and implements protocol as defined in
\rfc{1725}. The \class{POP3} class supports both the minmal and
optional command sets.
A single class is provided by the \module{poplib} module:
\begin{classdesc}{POP3}{host\optional{, port}}
This class implements the actual POP3 protocol. The connection is
created when the instance is initialized.
If \var{port} is omitted, the standard POP3 port (110) is used.
\end{classdesc}
One exception is defined as attributes of the \module{poplib} module:
\begin{excdesc}{error_proto}
Exception raised on any errors. The reason for the exception is
passed to the constructor as a string.
\end{excdesc}
\subsection{POP3 Objects}
\label{pop3-objects}
All POP3 commands are represented by methods of the same name,
in lower-case.
Most commands return the response text sent by the server.
An \class{POP3} instance has the following methods:
\begin{methoddesc}{getwelcome}{}
Returns the greeting string sent by the POP3 server.
\end{methoddesc}
\begin{methoddesc}{user}{username}
Send user commad, response should indicate that a password is required.
\end{methoddesc}
\begin{methoddesc}{pass_}{password}
Send password, response includes message count and mailbox size.
Note: the mailbox on the server is locked until \method{quit()} is
called.
\end{methoddesc}
\begin{methoddesc}{apop}{user, secret}
Use the more secure APOP authentication to log into the POP3 server.
\end{methoddesc}
\begin{methoddesc}{rpop}{user}
Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
\end{methoddesc}
\begin{methoddesc}{stat}{}
Get mailbox status. The result is a tuple of 2 integers:
\code{(\var{message count}, \var{mailbox size})}.
\end{methoddesc}
\begin{methoddesc}{list}{\optional{which}}
Request message list, result is in the form
\code{['response', ['mesg_num octets', ...]]}. If \var{which} is
set, it is the message to list.
\end{methoddesc}
\begin{methoddesc}{retr}{which}
Retrieve whole message number \var{which}. Result is in form
\code{['response', ['line', ...], octets]}.
\end{methoddesc}
\begin{methoddesc}{dele}{which}
Delete message number \var{which}.
\end{methoddesc}
\begin{methoddesc}{rset}{}
Remove any deletion marks for the mailbox.
\end{methoddesc}
\begin{methoddesc}{noop}{}
Do nothing. Might be used as a keep-alive.
\end{methoddesc}
\begin{methoddesc}{quit}{}
Signoff: commit changes, unlock mailbox, drop connection.
\end{methoddesc}
\begin{methoddesc}{top}{which, howmuch}
Retrieves the message header plus \var{howmuch} lines of the message
after the header of message number \var{which}. Result is in form
\code{['response', ['line', ...], octets]}.
\end{methoddesc}
\begin{methoddesc}{uidl}{\optional{which}}
Return message digest (unique id) list.
If \var{which} is specified, result contains unique id for that
message, otherwise result is list \code{['response',
['mesgnum uid', ...], octets]}.
\end{methoddesc}
\subsection{POP3 Example}
\label{pop3-example}
Here is a minimal example (without error checking) that opens a
mailbox and retrieves and prints all messages:
\begin{verbatim}
import getpass, poplib, string
M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
for j in M.retr(i+1)[1]:
sys.stdout.write(j)
\end{verbatim}
At the end of the module, there is a test section that contains a more
extensive example of usage.

509
Doc/libposix.tex
View File

@ -1,509 +0,0 @@
\section{Built-in Module \module{posix}}
\label{module-posix}
\bimodindex{posix}
This module provides access to operating system functionality that is
standardized by the \C{} Standard and the \POSIX{} standard (a thinly
disguised \UNIX{} interface).
\strong{Do not import this module directly.} Instead, import the
module \module{os}, which provides a \emph{portable} version of this
interface. On \UNIX{}, the \module{os} module provides a superset of
the \module{posix} interface. On non-\UNIX{} operating systems the
\module{posix} module is not available, but a subset is always
available through the \module{os} interface. Once \module{os} is
imported, there is \emph{no} performance penalty in using it instead
of \module{posix}. In addition, \module{os} provides some additional
functionality, such as automatically calling \function{putenv()}
when an entry in \code{os.environ} is changed.
\refstmodindex{os}
The descriptions below are very terse; refer to the corresponding
\UNIX{} manual (or \POSIX{} documentation) entry for more information.
Arguments called \var{path} refer to a pathname given as a string.
Errors are reported as exceptions; the usual exceptions are given
for type errors, while errors reported by the system calls raise
\exception{error}, described below.
Module \module{posix} defines the following data items:
\begin{datadesc}{environ}
A dictionary representing the string environment at the time
the interpreter was started.
For example,
\code{posix.environ['HOME']}
is the pathname of your home directory, equivalent to
\code{getenv("HOME")}
in \C{}.
Modifying this dictionary does not affect the string environment
passed on by \function{execv()}, \function{popen()} or
\function{system()}; if you need to change the environment, pass
\code{environ} to \function{execve()} or add variable assignments and
export statements to the command string for \function{system()} or
\function{popen()}.
\emph{However:} If you are using this module via the \module{os}
module (as you should -- see the introduction above), \code{environ}
is a a mapping object that behaves almost like a dictionary but
invokes \function{putenv()} automatically called whenever an item is
changed.
\end{datadesc}
\begin{excdesc}{error}
This exception is raised when a \POSIX{} function returns a
\POSIX{}-related error (e.g., not for illegal argument types). The
accompanying value is a pair containing the numeric error code from
\cdata{errno} and the corresponding string, as would be printed by the
\C{} function \cfunction{perror()}. See the module
\module{errno}\refbimodindex{errno}, which contains names for the
error codes defined by the underlying operating system.
When exceptions are classes, this exception carries two attributes,
\member{errno} and \member{strerror}. The first holds the value of
the \C{} \cdata{errno} variable, and the latter holds the
corresponding error message from \cfunction{strerror()}.
When exceptions are strings, the string for the exception is
\code{'os.error'}; this reflects the more portable access to the
exception through the \module{os} module.
\end{excdesc}
It defines the following functions and constants:
\begin{funcdesc}{chdir}{path}
Change the current working directory to \var{path}.
\end{funcdesc}
\begin{funcdesc}{chmod}{path, mode}
Change the mode of \var{path} to the numeric \var{mode}.
\end{funcdesc}
\begin{funcdesc}{chown}{path, uid, gid}
Change the owner and group id of \var{path} to the numeric \var{uid}
and \var{gid}.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{close}{fd}
Close file descriptor \var{fd}.
Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by \function{open()} or
\function{pipe()}. To close a ``file object'' returned by the
built-in function \function{open()} or by \function{popen()} or
\function{fdopen()}, use its \method{close()} method.
\end{funcdesc}
\begin{funcdesc}{dup}{fd}
Return a duplicate of file descriptor \var{fd}.
\end{funcdesc}
\begin{funcdesc}{dup2}{fd, fd2}
Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
first if necessary.
\end{funcdesc}
\begin{funcdesc}{execv}{path, args}
Execute the executable \var{path} with argument list \var{args},
replacing the current process (i.e., the Python interpreter).
The argument list may be a tuple or list of strings.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{execve}{path, args, env}
Execute the executable \var{path} with argument list \var{args},
and environment \var{env},
replacing the current process (i.e., the Python interpreter).
The argument list may be a tuple or list of strings.
The environment must be a dictionary mapping strings to strings.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{_exit}{n}
Exit to the system with status \var{n}, without calling cleanup
handlers, flushing stdio buffers, etc.
(Not on MS-DOS.)
Note: the standard way to exit is \code{sys.exit(\var{n})}.
\function{_exit()} should normally only be used in the child process
after a \function{fork()}.
\end{funcdesc}
\begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}}
Return an open file object connected to the file descriptor \var{fd}.
The \var{mode} and \var{bufsize} arguments have the same meaning as
the corresponding arguments to the built-in \function{open()} function.
\end{funcdesc}
\begin{funcdesc}{fork}{}
Fork a child process. Return \code{0} in the child, the child's
process id in the parent.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{fstat}{fd}
Return status for file descriptor \var{fd}, like \function{stat()}.
\end{funcdesc}
\begin{funcdesc}{ftruncate}{fd, length}
Truncate the file corresponding to file descriptor \var{fd},
so that it is at most \var{length} bytes in size.
\end{funcdesc}
\begin{funcdesc}{getcwd}{}
Return a string representing the current working directory.
\end{funcdesc}
\begin{funcdesc}{getegid}{}
Return the current process' effective group id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{geteuid}{}
Return the current process' effective user id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{getgid}{}
Return the current process' group id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{getpgrp}{}
Return the current process group id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{getpid}{}
Return the current process id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{getppid}{}
Return the parent's process id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{getuid}{}
Return the current process' user id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{kill}{pid, sig}
Kill the process \var{pid} with signal \var{sig}.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{link}{src, dst}
Create a hard link pointing to \var{src} named \var{dst}.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{listdir}{path}
Return a list containing the names of the entries in the directory.
The list is in arbitrary order. It does not include the special
entries \code{'.'} and \code{'..'} even if they are present in the
directory.
\end{funcdesc}
\begin{funcdesc}{lseek}{fd, pos, how}
Set the current position of file descriptor \var{fd} to position
\var{pos}, modified by \var{how}: \code{0} to set the position
relative to the beginning of the file; \code{1} to set it relative to
the current position; \code{2} to set it relative to the end of the
file.
\end{funcdesc}
\begin{funcdesc}{lstat}{path}
Like \function{stat()}, but do not follow symbolic links. (On systems
without symbolic links, this is identical to \function{stat()}.)
\end{funcdesc}
\begin{funcdesc}{mkfifo}{path\optional{, mode}}
Create a FIFO (a \POSIX{} named pipe) named \var{path} with numeric mode
\var{mode}. The default \var{mode} is \code{0666} (octal). The current
umask value is first masked out from the mode.
(Not on MS-DOS.)
FIFOs are pipes that can be accessed like regular files. FIFOs exist
until they are deleted (for example with \function{os.unlink()}).
Generally, FIFOs are used as rendezvous between ``client'' and
``server'' type processes: the server opens the FIFO for reading, and
the client opens it for writing. Note that \function{mkfifo()}
doesn't open the FIFO --- it just creates the rendezvous point.
\end{funcdesc}
\begin{funcdesc}{mkdir}{path\optional{, mode}}
Create a directory named \var{path} with numeric mode \var{mode}.
The default \var{mode} is \code{0777} (octal). On some systems,
\var{mode} is ignored. Where it is used, the current umask value is
first masked out.
\end{funcdesc}
\begin{funcdesc}{nice}{increment}
Add \var{increment} to the process' ``niceness''. Return the new
niceness. (Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{open}{file, flags\optional{, mode}}
Open the file \var{file} and set various flags according to
\var{flags} and possibly its mode according to \var{mode}.
The default \var{mode} is \code{0777} (octal), and the current umask
value is first masked out. Return the file descriptor for the newly
opened file.
For a description of the flag and mode values, see the \UNIX{} or \C{}
run-time documentation; flag constants (like \constant{O_RDONLY} and
\constant{O_WRONLY}) are defined in this module too (see below).
Note: this function is intended for low-level I/O. For normal usage,
use the built-in function \function{open()}, which returns a ``file
object'' with \method{read()} and \method{write()} methods (and many
more).
\end{funcdesc}
\begin{funcdesc}{pipe}{}
Create a pipe. Return a pair of file descriptors \code{(\var{r},
\var{w})} usable for reading and writing, respectively.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{plock}{op}
Lock program segments into memory. The value of \var{op}
(defined in \code{<sys/lock.h>}) determines which segments are locked.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}}
Open a pipe to or from \var{command}. The return value is an open
file object connected to the pipe, which can be read or written
depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
The \var{bufsize} argument has the same meaning as the corresponding
argument to the built-in \function{open()} function. The exit status of
the command (encoded in the format specified for \function{wait()}) is
available as the return value of the \method{close()} method of the file
object.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{putenv}{varname, value}
\index{environment variables!setting}
Set the environment variable named \var{varname} to the string
\var{value}. Such changes to the environment affect subprocesses
started with \function{os.system()}, \function{os.popen()} or
\function{os.fork()} and \function{os.execv()}. (Not on all systems.)
When \function{putenv()} is
supported, assignments to items in \code{os.environ} are automatically
translated into corresponding calls to \function{putenv()}; however,
calls to \function{putenv()} don't update \code{os.environ}, so it is
actually preferable to assign to items of \code{os.environ}.
\end{funcdesc}
\begin{funcdesc}{strerror}{code}
Return the error message corresponding to the error code in \var{code}.
\end{funcdesc}
\begin{funcdesc}{read}{fd, n}
Read at most \var{n} bytes from file descriptor \var{fd}.
Return a string containing the bytes read.
Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by \function{open()} or
\function{pipe()}. To read a ``file object'' returned by the
built-in function \function{open()} or by \function{popen()} or
\function{fdopen()}, or \code{sys.stdin}, use its
\method{read()} or \method{readline()} methods.
\end{funcdesc}
\begin{funcdesc}{readlink}{path}
Return a string representing the path to which the symbolic link
points. (On systems without symbolic links, this always raises
\exception{error}.)
\end{funcdesc}
\begin{funcdesc}{remove}{path}
Remove the file \var{path}. See \function{rmdir()} below to remove a
directory. This is identical to the \function{unlink()} function
documented below.
\end{funcdesc}
\begin{funcdesc}{rename}{src, dst}
Rename the file or directory \var{src} to \var{dst}.
\end{funcdesc}
\begin{funcdesc}{rmdir}{path}
Remove the directory \var{path}.
\end{funcdesc}
\begin{funcdesc}{setgid}{gid}
Set the current process' group id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{setpgrp}{}
Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0,
0)} depending on which version is implemented (if any). See the
\UNIX{} manual for the semantics.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{setpgid}{pid, pgrp}
Calls the system call \cfunction{setpgid()}. See the \UNIX{} manual
for the semantics.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{setsid}{}
Calls the system call \cfunction{setsid()}. See the \UNIX{} manual
for the semantics.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{setuid}{uid}
Set the current process' user id.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{stat}{path}
Perform a \cfunction{stat()} system call on the given path. The
return value is a tuple of at least 10 integers giving the most
important (and portable) members of the \emph{stat} structure, in the
order
\code{st_mode},
\code{st_ino},
\code{st_dev},
\code{st_nlink},
\code{st_uid},
\code{st_gid},
\code{st_size},
\code{st_atime},
\code{st_mtime},
\code{st_ctime}.
More items may be added at the end by some implementations.
(On MS-DOS, some items are filled with dummy values.)
Note: The standard module \module{stat}\refstmodindex{stat} defines
functions and constants that are useful for extracting information
from a stat structure.
\end{funcdesc}
\begin{funcdesc}{symlink}{src, dst}
Create a symbolic link pointing to \var{src} named \var{dst}. (On
systems without symbolic links, this always raises \exception{error}.)
\end{funcdesc}
\begin{funcdesc}{system}{command}
Execute the command (a string) in a subshell. This is implemented by
calling the Standard \C{} function \cfunction{system()}, and has the
same limitations. Changes to \code{posix.environ}, \code{sys.stdin}
etc.\ are not reflected in the environment of the executed command.
The return value is the exit status of the process encoded in the
format specified for \function{wait()}.
\end{funcdesc}
\begin{funcdesc}{tcgetpgrp}{fd}
Return the process group associated with the terminal given by
\var{fd} (an open file descriptor as returned by \function{open()}).
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{tcsetpgrp}{fd, pg}
Set the process group associated with the terminal given by
\var{fd} (an open file descriptor as returned by \function{open()})
to \var{pg}.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{times}{}
Return a 5-tuple of floating point numbers indicating accumulated (CPU
or other)
times, in seconds. The items are: user time, system time, children's
user time, children's system time, and elapsed real time since a fixed
point in the past, in that order. See the \UNIX{}
manual page \manpage{times}{2}. (Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{umask}{mask}
Set the current numeric umask and returns the previous umask.
(Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{uname}{}
Return a 5-tuple containing information identifying the current
operating system. The tuple contains 5 strings:
\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version},
\var{machine})}. Some systems truncate the nodename to 8
characters or to the leading component; a better way to get the
hostname is \function{socket.gethostname()}%
\withsubitem{(in module socket)}{\ttindex{gethostname()}}
or even
\code{socket.gethostbyaddr(socket.gethostname())}%
\withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}.
(Not on MS-DOS, nor on older \UNIX{} systems.)
\end{funcdesc}
\begin{funcdesc}{unlink}{path}
Remove the file \var{path}. This is the same function as \code{remove};
the \code{unlink} name is its traditional \UNIX{} name.
\end{funcdesc}
\begin{funcdesc}{utime}{path, {\rm (}atime, mtime{\rm )}}
Set the access and modified time of the file to the given values.
(The second argument is a tuple of two items.)
\end{funcdesc}
\begin{funcdesc}{wait}{}
Wait for completion of a child process, and return a tuple containing
its pid and exit status indication: a 16-bit number, whose low byte is
the signal number that killed the process, and whose high byte is the
exit status (if the signal number is zero); the high bit of the low
byte is set if a core file was produced. (Not on MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{waitpid}{pid, options}
Wait for completion of a child process given by proces id, and return
a tuple containing its pid and exit status indication (encoded as for
\function{wait()}). The semantics of the call are affected by the
value of the integer \var{options}, which should be \code{0} for
normal operation. (If the system does not support
\function{waitpid()}, this always raises \exception{error}. Not on
MS-DOS.)
\end{funcdesc}
\begin{funcdesc}{write}{fd, str}
Write the string \var{str} to file descriptor \var{fd}.
Return the number of bytes actually written.
Note: this function is intended for low-level I/O and must be applied
to a file descriptor as returned by \function{open()} or
\function{pipe()}. To write a ``file object'' returned by the
built-in function \function{open()} or by \function{popen()} or
\function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use
its \method{write()} method.
\end{funcdesc}
\begin{datadesc}{WNOHANG}
The option for \function{waitpid()} to avoid hanging if no child
process status is available immediately.
\end{datadesc}
\begin{datadesc}{O_RDONLY}
\dataline{O_WRONLY}
\dataline{O_RDWR}
\dataline{O_NDELAY}
\dataline{O_NONBLOCK}
\dataline{O_APPEND}
\dataline{O_DSYNC}
\dataline{O_RSYNC}
\dataline{O_SYNC}
\dataline{O_NOCTTY}
\dataline{O_CREAT}
\dataline{O_EXCL}
\dataline{O_TRUNC}
Options for the \code{flag} argument to the \function{open()} function.
These can be bit-wise OR'd together.
\end{datadesc}

162
Doc/libposixfile.tex
View File

@ -1,162 +0,0 @@
% Manual text and implementation by Jaap Vermeulen
\section{Standard Module \module{posixfile}}
\label{module-posixfile}
\bimodindex{posixfile}
\indexii{\POSIX{}}{file object}
\emph{Note:} This module will become obsolete in a future release.
The locking operation that it provides is done better and more
portably by the \function{fcntl.lockf()} call.%
\withsubitem{(in module fcntl)}{\ttindex{lockf()}}
This module implements some additional functionality over the built-in
file objects. In particular, it implements file locking, control over
the file flags, and an easy interface to duplicate the file object.
The module defines a new file object, the posixfile object. It
has all the standard file object methods and adds the methods
described below. This module only works for certain flavors of
\UNIX{}, since it uses \function{fcntl.fcntl()} for file locking.%
\withsubitem{(in module fcntl)}{\ttindex{fcntl()}}
To instantiate a posixfile object, use the \function{open()} function
in the \module{posixfile} module. The resulting object looks and
feels roughly the same as a standard file object.
The \module{posixfile} module defines the following constants:
\begin{datadesc}{SEEK_SET}
Offset is calculated from the start of the file.
\end{datadesc}
\begin{datadesc}{SEEK_CUR}
Offset is calculated from the current position in the file.
\end{datadesc}
\begin{datadesc}{SEEK_END}
Offset is calculated from the end of the file.
\end{datadesc}
The \module{posixfile} module defines the following functions:
\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}}
Create a new posixfile object with the given filename and mode. The
\var{filename}, \var{mode} and \var{bufsize} arguments are
interpreted the same way as by the built-in \function{open()}
function.
\end{funcdesc}
\begin{funcdesc}{fileopen}{fileobject}
Create a new posixfile object with the given standard file object.
The resulting object has the same filename and mode as the original
file object.
\end{funcdesc}
The posixfile object defines the following additional methods:
\setindexsubitem{(posixfile method)}
\begin{funcdesc}{lock}{fmt, \optional{len\optional{, start\optional{, whence}}}}
Lock the specified section of the file that the file object is
referring to. The format is explained
below in a table. The \var{len} argument specifies the length of the
section that should be locked. The default is \code{0}. \var{start}
specifies the starting offset of the section, where the default is
\code{0}. The \var{whence} argument specifies where the offset is
relative to. It accepts one of the constants \constant{SEEK_SET},
\constant{SEEK_CUR} or \constant{SEEK_END}. The default is
\constant{SEEK_SET}. For more information about the arguments refer
to the \manpage{fcntl}{2} manual page on your system.
\end{funcdesc}
\begin{funcdesc}{flags}{\optional{flags}}
Set the specified flags for the file that the file object is referring
to. The new flags are ORed with the old flags, unless specified
otherwise. The format is explained below in a table. Without
the \var{flags} argument
a string indicating the current flags is returned (this is
the same as the \samp{?} modifier). For more information about the
flags refer to the \manpage{fcntl}{2} manual page on your system.
\end{funcdesc}
\begin{funcdesc}{dup}{}
Duplicate the file object and the underlying file pointer and file
descriptor. The resulting object behaves as if it were newly
opened.
\end{funcdesc}
\begin{funcdesc}{dup2}{fd}
Duplicate the file object and the underlying file pointer and file
descriptor. The new object will have the given file descriptor.
Otherwise the resulting object behaves as if it were newly opened.
\end{funcdesc}
\begin{funcdesc}{file}{}
Return the standard file object that the posixfile object is based
on. This is sometimes necessary for functions that insist on a
standard file object.
\end{funcdesc}
All methods raise \exception{IOError} when the request fails.
Format characters for the \method{lock()} method have the following
meaning:
\begin{tableii}{c|l}{samp}{Format}{Meaning}
\lineii{u}{unlock the specified region}
\lineii{r}{request a read lock for the specified section}
\lineii{w}{request a write lock for the specified section}
\end{tableii}
In addition the following modifiers can be added to the format:
\begin{tableiii}{c|l|c}{samp}{Modifier}{Meaning}{Notes}
\lineiii{|}{wait until the lock has been granted}{}
\lineiii{?}{return the first lock conflicting with the requested lock, or
\code{None} if there is no conflict.}{(1)}
\end{tableiii}
Note:
(1) The lock returned is in the format \code{(\var{mode}, \var{len},
\var{start}, \var{whence}, \var{pid})} where \var{mode} is a character
representing the type of lock ('r' or 'w'). This modifier prevents a
request from being granted; it is for query purposes only.
Format characters for the \method{flags()} method have the following
meanings:
\begin{tableii}{c|l}{samp}{Format}{Meaning}
\lineii{a}{append only flag}
\lineii{c}{close on exec flag}
\lineii{n}{no delay flag (also called non-blocking flag)}
\lineii{s}{synchronization flag}
\end{tableii}
In addition the following modifiers can be added to the format:
\begin{tableiii}{c|l|c}{samp}{Modifier}{Meaning}{Notes}
\lineiii{!}{turn the specified flags 'off', instead of the default 'on'}{(1)}
\lineiii{=}{replace the flags, instead of the default 'OR' operation}{(1)}
\lineiii{?}{return a string in which the characters represent the flags that
are set.}{(2)}
\end{tableiii}
Note:
(1) The \samp{!} and \samp{=} modifiers are mutually exclusive.
(2) This string represents the flags after they may have been altered
by the same call.
Examples:
\begin{verbatim}
import posixfile
file = posixfile.open('/tmp/test', 'w')
file.lock('w|')
...
file.lock('u')
file.close()
\end{verbatim}

145
Doc/libppath.tex
View File

@ -1,145 +0,0 @@
\section{Standard Module \module{posixpath}}
\label{module-posixpath}
\stmodindex{posixpath}
This module implements some useful functions on \POSIX{} pathnames.
\strong{Do not import this module directly.} Instead, import the
module \module{os} and use \code{os.path}.
\refstmodindex{os}
\begin{funcdesc}{basename}{p}
Return the base name of pathname
\var{p}.
This is the second half of the pair returned by
\code{posixpath.split(\var{p})}.
\end{funcdesc}
\begin{funcdesc}{commonprefix}{list}
Return the longest string that is a prefix of all strings in
\var{list}.
If
\var{list}
is empty, return the empty string (\code{''}).
\end{funcdesc}
\begin{funcdesc}{exists}{p}
Return true if
\var{p}
refers to an existing path.
\end{funcdesc}
\begin{funcdesc}{expanduser}{p}
Return the argument with an initial component of \samp{\~} or
\samp{\~\var{user}} replaced by that \var{user}'s home directory. An
initial \samp{\~{}} is replaced by the environment variable \code{\${}HOME};
an initial \samp{\~\var{user}} is looked up in the password directory through
the built-in module \module{pwd}\refbimodindex{pwd}. If the expansion
fails, or if the path does not begin with a tilde, the path is
returned unchanged.
\end{funcdesc}
\begin{funcdesc}{expandvars}{p}
Return the argument with environment variables expanded. Substrings
of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are
replaced by the value of environment variable \var{name}. Malformed
variable names and references to non-existing variables are left
unchanged.
\end{funcdesc}
\begin{funcdesc}{isabs}{p}
Return true if \var{p} is an absolute pathname (begins with a slash).
\end{funcdesc}
\begin{funcdesc}{isfile}{p}
Return true if \var{p} is an existing regular file. This follows
symbolic links, so both \function{islink()} and \function{isfile()}
can be true for the same path.
\end{funcdesc}
\begin{funcdesc}{isdir}{p}
Return true if \var{p} is an existing directory. This follows
symbolic links, so both \function{islink()} and \function{isdir()} can
be true for the same path.
\end{funcdesc}
\begin{funcdesc}{islink}{p}
Return true if
\var{p}
refers to a directory entry that is a symbolic link.
Always false if symbolic links are not supported.
\end{funcdesc}
\begin{funcdesc}{ismount}{p}
Return true if pathname \var{p} is a \dfn{mount point}: a point in a
file system where a different file system has been mounted. The
function checks whether \var{p}'s parent, \file{\var{p}/..}, is on a
different device than \var{p}, or whether \file{\var{p}/..} and
\var{p} point to the same i-node on the same device --- this should
detect mount points for all \UNIX{} and \POSIX{} variants.
\end{funcdesc}
\begin{funcdesc}{join}{p\optional{, q\optional{, ...}}}
Joins one or more path components intelligently. If any component is
an absolute path, all previous components are thrown away, and joining
continues. The return value is the concatenation of \var{p}, and
optionally \var{q}, etc., with exactly one slash (\code{'/'}) inserted
between components, unless \var{p} is empty.
\end{funcdesc}
\begin{funcdesc}{normcase}{p}
Normalize the case of a pathname. On \UNIX{}, this returns the path
unchanged; on case-insensitive filesystems, it converts the path to
lowercase. On Windows, it also converts forward slashes to backward
slashes.
\end{funcdesc}
\begin{funcdesc}{normpath}{p}
Normalize a pathname. This collapses redundant separators and
up-level references, e.g. \code{A//B}, \code{A/./B} and
\code{A/foo/../B} all become \code{A/B}. It does not normalize the
case (use \function{normcase()} for that). On Windows, it does
converts forward slashes to backward slashes.
\end{funcdesc}
\begin{funcdesc}{samefile}{p, q}
Return true if both pathname arguments refer to the same file or
directory (as indicated by device number and i-node number).
Raise an exception if a \function{os.stat()} call on either pathname
fails.
\end{funcdesc}
\begin{funcdesc}{split}{p}
Split the pathname \var{p} in a pair \code{(\var{head}, \var{tail})},
where \var{tail} is the last pathname component and \var{head} is
everything leading up to that. The \var{tail} part will never contain
a slash; if \var{p} ends in a slash, \var{tail} will be empty. If
there is no slash in \var{p}, \var{head} will be empty. If \var{p} is
empty, both \var{head} and \var{tail} are empty. Trailing slashes are
stripped from \var{head} unless it is the root (one or more slashes
only). In nearly all cases, \code{join(\var{head}, \var{tail})}
equals \var{p} (the only exception being when there were multiple
slashes separating \var{head} from \var{tail}).
\end{funcdesc}
\begin{funcdesc}{splitext}{p}
Split the pathname \var{p} in a pair \code{(\var{root}, \var{ext})}
such that \code{\var{root} + \var{ext} == \var{p}},
and \var{ext} is empty or begins with a period and contains
at most one period.
\end{funcdesc}
\begin{funcdesc}{walk}{p, visit, arg}
Calls the function \var{visit} with arguments
\code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the
directory tree rooted at \var{p} (including \var{p} itself, if it is a
directory). The argument \var{dirname} specifies the visited directory,
the argument \var{names} lists the files in the directory (gotten from
\code{os.listdir(\var{dirname})}).
The \var{visit} function may modify \var{names} to
influence the set of directories visited below \var{dirname}, e.g., to
avoid visiting certain parts of the tree. (The object referred to by
\var{names} must be modified in place, using \keyword{del} or slice
assignment.)
\end{funcdesc}

172
Doc/libpprint.tex
View File

@ -1,172 +0,0 @@
%% Author: Fred L. Drake, Jr. <fdrake@acm.org>
\section{Standard Module \module{pprint}}
\stmodindex{pprint}
\label{module-pprint}
The \module{pprint} module provides a capability to ``pretty-print''
arbitrary Python data structures in a form which can be used as input
to the interpreter. If the formatted structures include objects which
are not fundamental Python types, the representation may not be
loadable. This may be the case if objects such as files, sockets,
classes, or instances are included, as well as many other builtin
objects which are not representable as Python constants.
The formatted representation keeps objects on a single line if it can,
and breaks them onto multiple lines if they don't fit within the
allowed width. Construct \class{PrettyPrinter} objects explicitly if
you need to adjust the width constraint.
The \module{pprint} module defines one class:
% First the implementation class:
\begin{classdesc}{PrettyPrinter}{...}
Construct a \class{PrettyPrinter} instance. This constructor
understands several keyword parameters. An output stream may be set
using the \var{stream} keyword; the only method used on the stream
object is the file protocol's \method{write()} method. If not
specified, the \class{PrettyPrinter} adopts \code{sys.stdout}. Three
additional parameters may be used to control the formatted
representation. The keywords are \var{indent}, \var{depth}, and
\var{width}. The amount of indentation added for each recursive level
is specified by \var{indent}; the default is one. Other values can
cause output to look a little odd, but can make nesting easier to
spot. The number of levels which may be printed is controlled by
\var{depth}; if the data structure being printed is too deep, the next
contained level is replaced by \samp{...}. By default, there is no
constraint on the depth of the objects being formatted. The desired
output width is constrained using the \var{width} parameter; the
default is eighty characters. If a structure cannot be formatted
within the constrained width, a best effort will be made.
\begin{verbatim}
>>> import pprint, sys
>>> stuff = sys.path[:]
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[ [ '',
'/usr/local/lib/python1.5',
'/usr/local/lib/python1.5/test',
'/usr/local/lib/python1.5/sunos5',
'/usr/local/lib/python1.5/sharedmodules',
'/usr/local/lib/python1.5/tkinter'],
'',
'/usr/local/lib/python1.5',
'/usr/local/lib/python1.5/test',
'/usr/local/lib/python1.5/sunos5',
'/usr/local/lib/python1.5/sharedmodules',
'/usr/local/lib/python1.5/tkinter']
>>>
>>> import parser
>>> tup = parser.ast2tuple(
... parser.suite(open('pprint.py').read()))[1][1][1]
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
(266, (267, (307, (287, (288, (...))))))
\end{verbatim}
\end{classdesc}
% Now the derivative functions:
The \class{PrettyPrinter} class supports several derivative functions:
\begin{funcdesc}{pformat}{object}
Return the formatted representation of \var{object} as a string. The
default parameters for formatting are used.
\end{funcdesc}
\begin{funcdesc}{pprint}{object\optional{, stream}}
Prints the formatted representation of \var{object} on \var{stream},
followed by a newline. If \var{stream} is omitted, \code{sys.stdout}
is used. This may be used in the interactive interpreter instead of a
\keyword{print} statement for inspecting values. The default
parameters for formatting are used.
\begin{verbatim}
>>> stuff = sys.path[:]
>>> stuff.insert(0, stuff)
>>> pprint.pprint(stuff)
[<Recursion on list with id=869440>,
'',
'/usr/local/lib/python1.5',
'/usr/local/lib/python1.5/test',
'/usr/local/lib/python1.5/sunos5',
'/usr/local/lib/python1.5/sharedmodules',
'/usr/local/lib/python1.5/tkinter']
\end{verbatim}
\end{funcdesc}
\begin{funcdesc}{isreadable}{object}
Determine if the formatted representation of \var{object} is
``readable,'' or can be used to reconstruct the value using
\function{eval()}\bifuncindex{eval}. This always returns false for
recursive objects.
\begin{verbatim}
>>> pprint.isreadable(stuff)
0
\end{verbatim}
\end{funcdesc}
\begin{funcdesc}{isrecursive}{object}
Determine if \var{object} requires a recursive representation.
\end{funcdesc}
One more support function is also defined:
\begin{funcdesc}{saferepr}{object}
Return a string representation of \var{object}, protected against
recursive data structures. If the representation of \var{object}
exposes a recursive entry, the recursive reference will be represented
as \samp{<Recursion on \var{typename} with id=\var{number}>}. The
representation is not otherwise formatted.
\end{funcdesc}
% This example is outside the {funcdesc} to keep it from running over
% the right margin.
\begin{verbatim}
>>> pprint.saferepr(stuff)
"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"
\end{verbatim}
\subsection{PrettyPrinter Objects}
\label{PrettyPrinter Objects}
\class{PrettyPrinter} instances have the following methods:
\begin{methoddesc}{pformat}{object}
Return the formatted representation of \var{object}. This takes into
Account the options passed to the \class{PrettyPrinter} constructor.
\end{methoddesc}
\begin{methoddesc}{pprint}{object}
Print the formatted representation of \var{object} on the configured
stream, followed by a newline.
\end{methoddesc}
The following methods provide the implementations for the
corresponding functions of the same names. Using these methods on an
instance is slightly more efficient since new \class{PrettyPrinter}
objects don't need to be created.
\begin{methoddesc}{isreadable}{object}
Determine if the formatted representation of the object is
``readable,'' or can be used to reconstruct the value using
\function{eval()}\bifuncindex{eval}. Note that this returns false for
recursive objects. If the \var{depth} parameter of the
\class{PrettyPrinter} is set and the object is deeper than allowed,
this returns false.
\end{methoddesc}
\begin{methoddesc}{isrecursive}{object}
Determine if the object requires a recursive representation.
\end{methoddesc}

767
Doc/libprofile.tex
View File

@ -1,767 +0,0 @@
\chapter{The Python Profiler}
\label{profile}
Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved.
\index{InfoSeek Corporation}
Written by James Roskind\index{Roskind, James}.%
\footnote{
Updated and converted to \LaTeX\ by Guido van Rossum. The references to
the old profiler are left in the text, although it no longer exists.
}
Permission to use, copy, modify, and distribute this Python software
and its associated documentation for any purpose (subject to the
restriction in the following sentence) without fee is hereby granted,
provided that the above copyright notice appears in all copies, and
that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of InfoSeek not be used in
advertising or publicity pertaining to distribution of the software
without specific, written prior permission. This permission is
explicitly restricted to the copying and modification of the software
to remain in Python, compiled Python, or other languages (such as C)
wherein the modified or derived code is exclusively imported into a
Python module.
INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
The profiler was written after only programming in Python for 3 weeks.
As a result, it is probably clumsy code, but I don't know for sure yet
'cause I'm a beginner :-). I did work hard to make the code run fast,
so that profiling would be a reasonable thing to do. I tried not to
repeat code fragments, but I'm sure I did some stuff in really awkward
ways at times. Please send suggestions for improvements to:
\email{jar@netscape.com}. I won't promise \emph{any} support. ...but
I'd appreciate the feedback.
\section{Introduction to the profiler}
\nodename{Profiler Introduction}
A \dfn{profiler} is a program that describes the run time performance
of a program, providing a variety of statistics. This documentation
describes the profiler functionality provided in the modules
\module{profile} and \module{pstats}. This profiler provides
\dfn{deterministic profiling} of any Python programs. It also
provides a series of report generation tools to allow users to rapidly
examine the results of a profile operation.
\index{deterministic profiling}
\index{profiling, deterministic}
\section{How Is This Profiler Different From The Old Profiler?}
\nodename{Profiler Changes}
(This section is of historical importance only; the old profiler
discussed here was last seen in Python 1.1.)
The big changes from old profiling module are that you get more
information, and you pay less CPU time. It's not a trade-off, it's a
trade-up.
To be specific:
\begin{description}
\item[Bugs removed:]
Local stack frame is no longer molested, execution time is now charged
to correct functions.
\item[Accuracy increased:]
Profiler execution time is no longer charged to user's code,
calibration for platform is supported, file reads are not done \emph{by}
profiler \emph{during} profiling (and charged to user's code!).
\item[Speed increased:]
Overhead CPU cost was reduced by more than a factor of two (perhaps a
factor of five), lightweight profiler module is all that must be
loaded, and the report generating module (\module{pstats}) is not needed
during profiling.
\item[Recursive functions support:]
Cumulative times in recursive functions are correctly calculated;
recursive entries are counted.
\item[Large growth in report generating UI:]
Distinct profiles runs can be added together forming a comprehensive
report; functions that import statistics take arbitrary lists of
files; sorting criteria is now based on keywords (instead of 4 integer
options); reports shows what functions were profiled as well as what
profile file was referenced; output format has been improved.
\end{description}
\section{Instant Users Manual}
This section is provided for users that ``don't want to read the
manual.'' It provides a very brief overview, and allows a user to
rapidly perform profiling on an existing application.
To profile an application with a main entry point of \samp{foo()}, you
would add the following to your module:
\begin{verbatim}
import profile
profile.run('foo()')
\end{verbatim}
%
The above action would cause \samp{foo()} to be run, and a series of
informative lines (the profile) to be printed. The above approach is
most useful when working with the interpreter. If you would like to
save the results of a profile into a file for later examination, you
can supply a file name as the second argument to the \function{run()}
function:
\begin{verbatim}
import profile
profile.run('foo()', 'fooprof')
\end{verbatim}
%
The file \file{profile.py} can also be invoked as
a script to profile another script. For example:
\begin{verbatim}
python /usr/local/lib/python1.5/profile.py myscript.py
\end{verbatim}
When you wish to review the profile, you should use the methods in the
\module{pstats} module. Typically you would load the statistics data as
follows:
\begin{verbatim}
import pstats
p = pstats.Stats('fooprof')
\end{verbatim}
%
The class \class{Stats} (the above code just created an instance of
this class) has a variety of methods for manipulating and printing the
data that was just read into \samp{p}. When you ran
\function{profile.run()} above, what was printed was the result of three
method calls:
\begin{verbatim}
p.strip_dirs().sort_stats(-1).print_stats()
\end{verbatim}
%
The first method removed the extraneous path from all the module
names. The second method sorted all the entries according to the
standard module/line/name string that is printed (this is to comply
with the semantics of the old profiler). The third method printed out
all the statistics. You might try the following sort calls:
\begin{verbatim}
p.sort_stats('name')
p.print_stats()
\end{verbatim}
%
The first call will actually sort the list by function name, and the
second call will print out the statistics. The following are some
interesting calls to experiment with:
\begin{verbatim}
p.sort_stats('cumulative').print_stats(10)
\end{verbatim}
%
This sorts the profile by cumulative time in a function, and then only
prints the ten most significant lines. If you want to understand what
algorithms are taking time, the above line is what you would use.
If you were looking to see what functions were looping a lot, and
taking a lot of time, you would do:
\begin{verbatim}
p.sort_stats('time').print_stats(10)
\end{verbatim}
%
to sort according to time spent within each function, and then print
the statistics for the top ten functions.
You might also try:
\begin{verbatim}
p.sort_stats('file').print_stats('__init__')
\end{verbatim}
%
This will sort all the statistics by file name, and then print out
statistics for only the class init methods ('cause they are spelled
with \samp{__init__} in them). As one final example, you could try:
\begin{verbatim}
p.sort_stats('time', 'cum').print_stats(.5, 'init')
\end{verbatim}
%
This line sorts statistics with a primary key of time, and a secondary
key of cumulative time, and then prints out some of the statistics.
To be specific, the list is first culled down to 50\% (re: \samp{.5})
of its original size, then only lines containing \code{init} are
maintained, and that sub-sub-list is printed.
If you wondered what functions called the above functions, you could
now (\samp{p} is still sorted according to the last criteria) do:
\begin{verbatim}
p.print_callers(.5, 'init')
\end{verbatim}
and you would get a list of callers for each of the listed functions.
If you want more functionality, you're going to have to read the
manual, or guess what the following functions do:
\begin{verbatim}
p.print_callees()
p.add('fooprof')
\end{verbatim}
%
\section{What Is Deterministic Profiling?}
\nodename{Deterministic Profiling}
\dfn{Deterministic profiling} is meant to reflect the fact that all
\dfn{function call}, \dfn{function return}, and \dfn{exception} events
are monitored, and precise timings are made for the intervals between
these events (during which time the user's code is executing). In
contrast, \dfn{statistical profiling} (which is not done by this
module) randomly samples the effective instruction pointer, and
deduces where time is being spent. The latter technique traditionally
involves less overhead (as the code does not need to be instrumented),
but provides only relative indications of where time is being spent.
In Python, since there is an interpreter active during execution, the
presence of instrumented code is not required to do deterministic
profiling. Python automatically provides a \dfn{hook} (optional
callback) for each event. In addition, the interpreted nature of
Python tends to add so much overhead to execution, that deterministic
profiling tends to only add small processing overhead in typical
applications. The result is that deterministic profiling is not that
expensive, yet provides extensive run time statistics about the
execution of a Python program.
Call count statistics can be used to identify bugs in code (surprising
counts), and to identify possible inline-expansion points (high call
counts). Internal time statistics can be used to identify ``hot
loops'' that should be carefully optimized. Cumulative time
statistics should be used to identify high level errors in the
selection of algorithms. Note that the unusual handling of cumulative
times in this profiler allows statistics for recursive implementations
of algorithms to be directly compared to iterative implementations.
\section{Reference Manual}
\stmodindex{profile}
\label{module-profile}
The primary entry point for the profiler is the global function
\function{profile.run()}. It is typically used to create any profile
information. The reports are formatted and printed using methods of
the class \class{pstats.Stats}. The following is a description of all
of these standard entry points and functions. For a more in-depth
view of some of the code, consider reading the later section on
Profiler Extensions, which includes discussion of how to derive
``better'' profilers from the classes presented, or reading the source
code for these modules.
\begin{funcdesc}{run}{string\optional{, filename\optional{, ...}}}
This function takes a single argument that has can be passed to the
\keyword{exec} statement, and an optional file name. In all cases this
routine attempts to \keyword{exec} its first argument, and gather profiling
statistics from the execution. If no file name is present, then this
function automatically prints a simple profiling report, sorted by the
standard name string (file/line/function-name) that is presented in
each line. The following is a typical output from such a call:
\begin{verbatim}
main()
2706 function calls (2004 primitive calls) in 4.504 CPU seconds
Ordered by: standard name
ncalls tottime percall cumtime percall filename:lineno(function)
2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)
43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)
...
\end{verbatim}
The first line indicates that this profile was generated by the call:\\
\code{profile.run('main()')}, and hence the exec'ed string is
\code{'main()'}. The second line indicates that 2706 calls were
monitored. Of those calls, 2004 were \dfn{primitive}. We define
\dfn{primitive} to mean that the call was not induced via recursion.
The next line: \code{Ordered by:\ standard name}, indicates that
the text string in the far right column was used to sort the output.
The column headings include:
\begin{description}
\item[ncalls ]
for the number of calls,
\item[tottime ]
for the total time spent in the given function (and excluding time
made in calls to sub-functions),
\item[percall ]
is the quotient of \code{tottime} divided by \code{ncalls}
\item[cumtime ]
is the total time spent in this and all subfunctions (i.e., from
invocation till exit). This figure is accurate \emph{even} for recursive
functions.
\item[percall ]
is the quotient of \code{cumtime} divided by primitive calls
\item[filename:lineno(function) ]
provides the respective data of each function
\end{description}
When there are two numbers in the first column (e.g.: \samp{43/3}),
then the latter is the number of primitive calls, and the former is
the actual number of calls. Note that when the function does not
recurse, these two values are the same, and only the single figure is
printed.
\end{funcdesc}
Analysis of the profiler data is done using this class from the
\module{pstats} module:
% now switch modules....
\stmodindex{pstats}
\begin{classdesc}{Stats}{filename\optional{, ...}}
This class constructor creates an instance of a ``statistics object''
from a \var{filename} (or set of filenames). \class{Stats} objects are
manipulated by methods, in order to print useful reports.
The file selected by the above constructor must have been created by
the corresponding version of \module{profile}. To be specific, there is
\emph{no} file compatibility guaranteed with future versions of this
profiler, and there is no compatibility with files produced by other
profilers (e.g., the old system profiler).
If several files are provided, all the statistics for identical
functions will be coalesced, so that an overall view of several
processes can be considered in a single report. If additional files
need to be combined with data in an existing \class{Stats} object, the
\method{add()} method can be used.
\end{classdesc}
\subsection{The \module{Stats} Class}
\setindexsubitem{(Stats method)}
\begin{methoddesc}{strip_dirs}{}
This method for the \class{Stats} class removes all leading path
information from file names. It is very useful in reducing the size
of the printout to fit within (close to) 80 columns. This method
modifies the object, and the stripped information is lost. After
performing a strip operation, the object is considered to have its
entries in a ``random'' order, as it was just after object
initialization and loading. If \method{strip_dirs()} causes two
function names to be indistinguishable (i.e., they are on the same
line of the same filename, and have the same function name), then the
statistics for these two entries are accumulated into a single entry.
\end{methoddesc}
\begin{methoddesc}{add}{filename\optional{, ...}}
This method of the \class{Stats} class accumulates additional
profiling information into the current profiling object. Its
arguments should refer to filenames created by the corresponding
version of \function{profile.run()}. Statistics for identically named
(re: file, line, name) functions are automatically accumulated into
single function statistics.
\end{methoddesc}
\begin{methoddesc}{sort_stats}{key\optional{, ...}}
This method modifies the \class{Stats} object by sorting it according
to the supplied criteria. The argument is typically a string
identifying the basis of a sort (example: \code{'time'} or
\code{'name'}).
When more than one key is provided, then additional keys are used as
secondary criteria when the there is equality in all keys selected
before them. For example, \samp{sort_stats('name', 'file')} will sort
all the entries according to their function name, and resolve all ties
(identical function names) by sorting by file name.
Abbreviations can be used for any key names, as long as the
abbreviation is unambiguous. The following are the keys currently
defined:
\begin{tableii}{l|l}{code}{Valid Arg}{Meaning}
\lineii{'calls'}{call count}
\lineii{'cumulative'}{cumulative time}
\lineii{'file'}{file name}
\lineii{'module'}{file name}
\lineii{'pcalls'}{primitive call count}
\lineii{'line'}{line number}
\lineii{'name'}{function name}
\lineii{'nfl'}{name/file/line}
\lineii{'stdname'}{standard name}
\lineii{'time'}{internal time}
\end{tableii}
Note that all sorts on statistics are in descending order (placing
most time consuming items first), where as name, file, and line number
searches are in ascending order (i.e., alphabetical). The subtle
distinction between \code{'nfl'} and \code{'stdname'} is that the
standard name is a sort of the name as printed, which means that the
embedded line numbers get compared in an odd way. For example, lines
3, 20, and 40 would (if the file names were the same) appear in the
string order 20, 3 and 40. In contrast, \code{'nfl'} does a numeric
compare of the line numbers. In fact, \code{sort_stats('nfl')} is the
same as \code{sort_stats('name', 'file', 'line')}.
For compatibility with the old profiler, the numeric arguments
\code{-1}, \code{0}, \code{1}, and \code{2} are permitted. They are
interpreted as \code{'stdname'}, \code{'calls'}, \code{'time'}, and
\code{'cumulative'} respectively. If this old style format (numeric)
is used, only one sort key (the numeric key) will be used, and
additional arguments will be silently ignored.
\end{methoddesc}
\begin{methoddesc}{reverse_order}{}
This method for the \class{Stats} class reverses the ordering of the basic
list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable
now that ascending vs descending order is properly selected based on
the sort key of choice.
\end{methoddesc}
\begin{methoddesc}{print_stats}{restriction\optional{, ...}}
This method for the \class{Stats} class prints out a report as described
in the \function{profile.run()} definition.
The order of the printing is based on the last \method{sort_stats()}
operation done on the object (subject to caveats in \method{add()} and
\method{strip_dirs()}.
The arguments provided (if any) can be used to limit the list down to
the significant entries. Initially, the list is taken to be the
complete set of profiled functions. Each restriction is either an
integer (to select a count of lines), or a decimal fraction between
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
provided, then they are applied sequentially. For example:
\begin{verbatim}
print_stats(.1, 'foo:')
\end{verbatim}
would first limit the printing to first 10\% of list, and then only
print functions that were part of filename \samp{.*foo:}. In
contrast, the command:
\begin{verbatim}
print_stats('foo:', .1)
\end{verbatim}
would limit the list to all functions having file names \samp{.*foo:},
and then proceed to only print the first 10\% of them.
\end{methoddesc}
\begin{methoddesc}{print_callers}{restrictions\optional{, ...}}
This method for the \class{Stats} class prints a list of all functions
that called each function in the profiled database. The ordering is
identical to that provided by \method{print_stats()}, and the definition
of the restricting argument is also identical. For convenience, a
number is shown in parentheses after each caller to show how many
times this specific call was made. A second non-parenthesized number
is the cumulative time spent in the function at the right.
\end{methoddesc}
\begin{methoddesc}{print_callees}{restrictions\optional{, ...}}
This method for the \class{Stats} class prints a list of all function
that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and
ordering are identical to the \method{print_callers()} method.
\end{methoddesc}
\begin{methoddesc}{ignore}{}
\deprecated{1.5.1}{This is not needed in modern versions of Python.%
\footnote{
This was once necessary, when Python would print any unused expression
result that was not \code{None}. The method is still defined for
backward compatibility.
}}
\end{methoddesc}
\section{Limitations}
There are two fundamental limitations on this profiler. The first is
that it relies on the Python interpreter to dispatch \dfn{call},
\dfn{return}, and \dfn{exception} events. Compiled \C{} code does not
get interpreted, and hence is ``invisible'' to the profiler. All time
spent in \C{} code (including built-in functions) will be charged to the
Python function that invoked the \C{} code. If the \C{} code calls out
to some native Python code, then those calls will be profiled
properly.
The second limitation has to do with accuracy of timing information.
There is a fundamental problem with deterministic profilers involving
accuracy. The most obvious restriction is that the underlying ``clock''
is only ticking at a rate (typically) of about .001 seconds. Hence no
measurements will be more accurate that that underlying clock. If
enough measurements are taken, then the ``error'' will tend to average
out. Unfortunately, removing this first error induces a second source
of error...
The second problem is that it ``takes a while'' from when an event is
dispatched until the profiler's call to get the time actually
\emph{gets} the state of the clock. Similarly, there is a certain lag
when exiting the profiler event handler from the time that the clock's
value was obtained (and then squirreled away), until the user's code
is once again executing. As a result, functions that are called many
times, or call many functions, will typically accumulate this error.
The error that accumulates in this fashion is typically less than the
accuracy of the clock (i.e., less than one clock tick), but it
\emph{can} accumulate and become very significant. This profiler
provides a means of calibrating itself for a given platform so that
this error can be probabilistically (i.e., on the average) removed.
After the profiler is calibrated, it will be more accurate (in a least
square sense), but it will sometimes produce negative numbers (when
call counts are exceptionally low, and the gods of probability work
against you :-). ) Do \emph{NOT} be alarmed by negative numbers in
the profile. They should \emph{only} appear if you have calibrated
your profiler, and the results are actually better than without
calibration.
\section{Calibration}
The profiler class has a hard coded constant that is added to each
event handling time to compensate for the overhead of calling the time
function, and socking away the results. The following procedure can
be used to obtain this constant for a given platform (see discussion
in section Limitations above).
\begin{verbatim}
import profile
pr = profile.Profile()
print pr.calibrate(100)
print pr.calibrate(100)
print pr.calibrate(100)
\end{verbatim}
The argument to \method{calibrate()} is the number of times to try to
do the sample calls to get the CPU times. If your computer is
\emph{very} fast, you might have to do:
\begin{verbatim}
pr.calibrate(1000)
\end{verbatim}
or even:
\begin{verbatim}
pr.calibrate(10000)
\end{verbatim}
The object of this exercise is to get a fairly consistent result.
When you have a consistent answer, you are ready to use that number in
the source code. For a Sun Sparcstation 1000 running Solaris 2.3, the
magical number is about .00053. If you have a choice, you are better
off with a smaller constant, and your results will ``less often'' show
up as negative in profile statistics.
The following shows how the trace_dispatch() method in the Profile
class should be modified to install the calibration constant on a Sun
Sparcstation 1000:
\begin{verbatim}
def trace_dispatch(self, frame, event, arg):
t = self.timer()
t = t[0] + t[1] - self.t - .00053 # Calibration constant
if self.dispatch[event](frame,t):
t = self.timer()
self.t = t[0] + t[1]
else:
r = self.timer()
self.t = r[0] + r[1] - t # put back unrecorded delta
return
\end{verbatim}
Note that if there is no calibration constant, then the line
containing the callibration constant should simply say:
\begin{verbatim}
t = t[0] + t[1] - self.t # no calibration constant
\end{verbatim}
You can also achieve the same results using a derived class (and the
profiler will actually run equally fast!!), but the above method is
the simplest to use. I could have made the profiler ``self
calibrating'', but it would have made the initialization of the
profiler class slower, and would have required some \emph{very} fancy
coding, or else the use of a variable where the constant \samp{.00053}
was placed in the code shown. This is a \strong{VERY} critical
performance section, and there is no reason to use a variable lookup
at this point, when a constant can be used.
\section{Extensions --- Deriving Better Profilers}
\nodename{Profiler Extensions}
The \class{Profile} class of module \module{profile} was written so that
derived classes could be developed to extend the profiler. Rather
than describing all the details of such an effort, I'll just present
the following two examples of derived classes that can be used to do
profiling. If the reader is an avid Python programmer, then it should
be possible to use these as a model and create similar (and perchance
better) profile classes.
If all you want to do is change how the timer is called, or which
timer function is used, then the basic class has an option for that in
the constructor for the class. Consider passing the name of a
function to call into the constructor:
\begin{verbatim}
pr = profile.Profile(your_time_func)
\end{verbatim}
The resulting profiler will call \code{your_time_func()} instead of
\function{os.times()}. The function should return either a single number
or a list of numbers (like what \function{os.times()} returns). If the
function returns a single time number, or the list of returned numbers
has length 2, then you will get an especially fast version of the
dispatch routine.
Be warned that you \emph{should} calibrate the profiler class for the
timer function that you choose. For most machines, a timer that
returns a lone integer value will provide the best results in terms of
low overhead during profiling. (\function{os.times()} is
\emph{pretty} bad, 'cause it returns a tuple of floating point values,
so all arithmetic is floating point in the profiler!). If you want to
substitute a better timer in the cleanest fashion, you should derive a
class, and simply put in the replacement dispatch method that better
handles your timer call, along with the appropriate calibration
constant :-).
\subsection{OldProfile Class}
The following derived profiler simulates the old style profiler,
providing errant results on recursive functions. The reason for the
usefulness of this profiler is that it runs faster (i.e., less
overhead) than the old profiler. It still creates all the caller
stats, and is quite useful when there is \emph{no} recursion in the
user's code. It is also a lot more accurate than the old profiler, as
it does not charge all its overhead time to the user's code.
\begin{verbatim}
class OldProfile(Profile):
def trace_dispatch_exception(self, frame, t):
rt, rtt, rct, rfn, rframe, rcur = self.cur
if rcur and not rframe is frame:
return self.trace_dispatch_return(rframe, t)
return 0
def trace_dispatch_call(self, frame, t):
fn = `frame.f_code`
self.cur = (t, 0, 0, fn, frame, self.cur)
if self.timings.has_key(fn):
tt, ct, callers = self.timings[fn]
self.timings[fn] = tt, ct, callers
else:
self.timings[fn] = 0, 0, {}
return 1
def trace_dispatch_return(self, frame, t):
rt, rtt, rct, rfn, frame, rcur = self.cur
rtt = rtt + t
sft = rtt + rct
pt, ptt, pct, pfn, pframe, pcur = rcur
self.cur = pt, ptt+rt, pct+sft, pfn, pframe, pcur
tt, ct, callers = self.timings[rfn]
if callers.has_key(pfn):
callers[pfn] = callers[pfn] + 1
else:
callers[pfn] = 1
self.timings[rfn] = tt+rtt, ct + sft, callers
return 1
def snapshot_stats(self):
self.stats = {}
for func in self.timings.keys():
tt, ct, callers = self.timings[func]
nor_func = self.func_normalize(func)
nor_callers = {}
nc = 0
for func_caller in callers.keys():
nor_callers[self.func_normalize(func_caller)] = \
callers[func_caller]
nc = nc + callers[func_caller]
self.stats[nor_func] = nc, nc, tt, ct, nor_callers
\end{verbatim}
\subsection{HotProfile Class}
This profiler is the fastest derived profile example. It does not
calculate caller-callee relationships, and does not calculate
cumulative time under a function. It only calculates time spent in a
function, so it runs very quickly (re: very low overhead). In truth,
the basic profiler is so fast, that is probably not worth the savings
to give up the data, but this class still provides a nice example.
\begin{verbatim}
class HotProfile(Profile):
def trace_dispatch_exception(self, frame, t):
rt, rtt, rfn, rframe, rcur = self.cur
if rcur and not rframe is frame:
return self.trace_dispatch_return(rframe, t)
return 0
def trace_dispatch_call(self, frame, t):
self.cur = (t, 0, frame, self.cur)
return 1
def trace_dispatch_return(self, frame, t):
rt, rtt, frame, rcur = self.cur
rfn = `frame.f_code`
pt, ptt, pframe, pcur = rcur
self.cur = pt, ptt+rt, pframe, pcur
if self.timings.has_key(rfn):
nc, tt = self.timings[rfn]
self.timings[rfn] = nc + 1, rt + rtt + tt
else:
self.timings[rfn] = 1, rt + rtt
return 1
def snapshot_stats(self):
self.stats = {}
for func in self.timings.keys():
nc, tt = self.timings[func]
nor_func = self.func_normalize(func)
self.stats[nor_func] = nc, nc, tt, 0, {}
\end{verbatim}

32
Doc/libpwd.tex
View File

@ -1,32 +0,0 @@
\section{Built-in Module \module{pwd}}
\label{module-pwd}
\bimodindex{pwd}
This module provides access to the \UNIX{} password database.
It is available on all \UNIX{} versions.
Password database entries are reported as 7-tuples containing the
following items from the password database (see \file{<pwd.h>}), in order:
\code{pw_name},
\code{pw_passwd},
\code{pw_uid},
\code{pw_gid},
\code{pw_gecos},
\code{pw_dir},
\code{pw_shell}.
The uid and gid items are integers, all others are strings.
A \code{KeyError} exception is raised if the entry asked for cannot be found.
It defines the following items:
\begin{funcdesc}{getpwuid}{uid}
Return the password database entry for the given numeric user ID.
\end{funcdesc}
\begin{funcdesc}{getpwnam}{name}
Return the password database entry for the given user name.
\end{funcdesc}
\begin{funcdesc}{getpwall}{}
Return a list of all available password database entries, in arbitrary order.
\end{funcdesc}

84
Doc/libpython.tex
View File

@ -1,84 +0,0 @@
\chapter{Python Services}
\label{python}
The modules described in this chapter provide a wide range of services
related to the Python interpreter and its interaction with its
environment. Here's an overview:
\begin{description}
\item[sys]
--- Access system specific parameters and functions.
\item[types]
--- Names for all built-in types.
\item[UserDict]
--- Class wrapper for dictionary objects.
\item[UserList]
--- Class wrapper for list objects.
\item[operator]
--- All Python's standard operators as built-in functions.
\item[traceback]
--- Print or retrieve a stack traceback.
\item[pickle]
--- Convert Python objects to streams of bytes and back.
\item[cPickle]
--- Faster version of \module{pickle}, but not subclassable.
\item[copy_reg]
--- Register \module{pickle} support functions.
\item[shelve]
--- Python object persistency.
\item[copy]
--- Shallow and deep copy operations.
\item[marshal]
--- Convert Python objects to streams of bytes and back (with
different constraints).
\item[imp]
--- Access the implementation of the \keyword{import} statement.
\item[parser]
--- Retrieve and submit parse trees from and to the runtime support
environment.
\item[symbol]
--- Constants representing internal nodes of the parse tree.
\item[token]
--- Constants representing terminal nodes of the parse tree.
\item[keyword]
--- Test whether a string is a keyword in the Python language.
\item[code]
--- Code object services.
\item[pprint]
--- Data pretty printer.
\item[dis]
--- Disassembler.
\item[site]
--- A standard way to reference site-specific modules.
\item[user]
--- A standard way to reference user-specific modules.
\item[__builtin__]
--- The set of built-in functions.
\item[__main__]
--- The environment where the top-level script is run.
\end{description}

68
Doc/libqueue.tex
View File

@ -1,68 +0,0 @@
\section{Standard Module \module{Queue}}
\stmodindex{Queue}
\label{module-Queue}
The \module{Queue} module implements a multi-producer, multi-consumer
FIFO queue. It is especially useful in threads programming when
information must be exchanged safely between multiple threads. The
\class{Queue} class in this module implements all the required locking
semantics. It depends on the availability of thread support in
Python.
The \module{Queue} module defines the following class and exception:
\begin{classdesc}{Queue}{maxsize}
Constructor for the class. \var{maxsize} is an integer that sets the
upperbound limit on the number of items that can be placed in the
queue. Insertion will block once this size has been reached, until
queue items are consumed. If \var{maxsize} is less than or equal to
zero, the queue size is infinite.
\end{classdesc}
\begin{excdesc}{Empty}
Exception raised when non-blocking get (e.g. \method{get_nowait()}) is
called on a \class{Queue} object which is empty, or for which the
emptyiness cannot be determined (i.e. because the appropriate locks
cannot be acquired).
\end{excdesc}
\subsection{Queue Objects}
\label{QueueObjects}
Class \class{Queue} implements queue objects and has the methods
described below. This class can be derived from in order to implement
other queue organizations (e.g. stack) but the inheritable interface
is not described here. See the source code for details. The public
methods are:
\begin{methoddesc}{qsize}{}
Returns the approximate size of the queue. Because of multithreading
semantics, this number is not reliable.
\end{methoddesc}
\begin{methoddesc}{empty}{}
Returns \code{1} if the queue is empty, \code{0} otherwise. Because
of multithreading semantics, this is not reliable.
\end{methoddesc}
\begin{methoddesc}{full}{}
Returns \code{1} if the queue is full, \code{0} otherwise. Because of
multithreading semantics, this is not reliable.
\end{methoddesc}
\begin{methoddesc}{put}{item}
Puts \var{item} into the queue.
\end{methoddesc}
\begin{methoddesc}{get}{}
Gets and returns an item from the queue, blocking if necessary until
one is available.
\end{methoddesc}
\begin{methoddesc}{get_nowait}{}
Gets and returns an item from the queue if one is immediately
available. Raises an \exception{Empty} exception if the queue is
empty or if the queue's emptiness cannot be determined.
\end{methoddesc}

32
Doc/libquopri.tex
View File

@ -1,32 +0,0 @@
\section{Standard Module \module{quopri}}
\label{module-quopri}
\stmodindex{quopri}
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
are many such characters, as when sending a graphics file.
\indexii{quoted-printable}{encoding}
\index{MIME!quoted-printable encoding}
\begin{funcdesc}{decode}{input, output}
Decode the contents of the \var{input} file and write the resulting
decoded binary data to the \var{output} file.
\var{input} and \var{output} must either be file objects or objects that
mimic the file object interface. \var{input} will be read until
\code{\var{input}.read()} returns an empty string.
\end{funcdesc}
\begin{funcdesc}{encode}{input, output, quotetabs}
Encode the contents of the \var{input} file and write the resulting
quoted-printable data to the \var{output} file.
\var{input} and \var{output} must either be file objects or objects that
mimic the file object interface. \var{input} will be read until
\code{\var{input}.read()} returns an empty string.
\end{funcdesc}

28
Doc/librand.tex
View File

@ -1,28 +0,0 @@
\section{Standard Module \module{rand}}
\label{module-rand}
\stmodindex{rand}
The \code{rand} module simulates the C library's \code{rand()}
interface, though the results aren't necessarily compatible with any
given library's implementation. While still supported for
compatibility, the \code{rand} module is now considered obsolete; if
possible, use the \code{whrandom} module instead.
\begin{funcdesc}{choice}{seq}
Returns a random element from the sequence \var{seq}.
\end{funcdesc}
\begin{funcdesc}{rand}{}
Return a random integer between 0 and 32767, inclusive.
\end{funcdesc}
\begin{funcdesc}{srand}{seed}
Set a starting seed value for the random number generator; \var{seed}
can be an arbitrary integer.
\end{funcdesc}
\begin{seealso}
\seemodule{whrandom}{the standard Python random number generator}
\end{seealso}

86
Doc/librandom.tex
View File

@ -1,86 +0,0 @@
\section{Standard Module \module{random}}
\label{module-random}
\stmodindex{random}
This module implements pseudo-random number generators for various
distributions: on the real line, there are functions to compute normal
or Gaussian, lognormal, negative exponential, gamma, and beta
distributions. For generating distribution of angles, the circular
uniform and von Mises distributions are available.
The module exports the following functions, which are exactly
equivalent to those in the \module{whrandom} module:
\function{choice()}, \function{randint()}, \function{random()} and
\function{uniform()}. See the documentation for the \module{whrandom}
module for these functions.
The following functions specific to the \module{random} module are also
defined, and all return real values. Function parameters are named
after the corresponding variables in the distribution's equation, as
used in common mathematical practice; most of these equations can be
found in any statistics text.
\begin{funcdesc}{betavariate}{alpha, beta}
Beta distribution. Conditions on the parameters are
\code{\var{alpha} >- 1} and \code{\var{beta} > -1}.
Returned values will range between 0 and 1.
\end{funcdesc}
\begin{funcdesc}{cunifvariate}{mean, arc}
Circular uniform distribution. \var{mean} is the mean angle, and
\var{arc} is the range of the distribution, centered around the mean
angle. Both values must be expressed in radians, and can range
between 0 and pi. Returned values will range between
\code{\var{mean} - \var{arc}/2} and \code{\var{mean} + \var{arc}/2}.
\end{funcdesc}
\begin{funcdesc}{expovariate}{lambd}
Exponential distribution. \var{lambd} is 1.0 divided by the desired
mean. (The parameter would be called ``lambda'', but that is a
reserved word in Python.) Returned values will range from 0 to
positive infinity.
\end{funcdesc}
\begin{funcdesc}{gamma}{alpha, beta}
Gamma distribution. (\emph{Not} the gamma function!) Conditions on
the parameters are \code{\var{alpha} > -1} and \code{\var{beta} > 0}.
\end{funcdesc}
\begin{funcdesc}{gauss}{mu, sigma}
Gaussian distribution. \var{mu} is the mean, and \var{sigma} is the
standard deviation. This is slightly faster than the
\function{normalvariate()} function defined below.
\end{funcdesc}
\begin{funcdesc}{lognormvariate}{mu, sigma}
Log normal distribution. If you take the natural logarithm of this
distribution, you'll get a normal distribution with mean \var{mu} and
standard deviation \var{sigma}. \var{mu} can have any value, and \var{sigma}
must be greater than zero.
\end{funcdesc}
\begin{funcdesc}{normalvariate}{mu, sigma}
Normal distribution. \var{mu} is the mean, and \var{sigma} is the
standard deviation.
\end{funcdesc}
\begin{funcdesc}{vonmisesvariate}{mu, kappa}
\var{mu} is the mean angle, expressed in radians between 0 and 2*pi,
and \var{kappa} is the concentration parameter, which must be greater
than or equal to zero. If \var{kappa} is equal to zero, this
distribution reduces to a uniform random angle over the range 0 to
2*pi.
\end{funcdesc}
\begin{funcdesc}{paretovariate}{alpha}
Pareto distribution. \var{alpha} is the shape parameter.
\end{funcdesc}
\begin{funcdesc}{weibullvariate}{alpha, beta}
Weibull distribution. \var{alpha} is the scale parameter and
\var{beta} is the shape parameter.
\end{funcdesc}
\begin{seealso}
\seemodule{whrandom}{the standard Python random number generator}
\end{seealso}

634
Doc/libre.tex
View File

@ -1,634 +0,0 @@
\section{Built-in Module \module{re}}
\label{module-re}
\bimodindex{re}
This module provides regular expression matching operations similar to
those found in Perl. It's 8-bit clean: the strings being processed
may contain both null bytes and characters whose high bit is set. Regular
expression patterns may not contain null bytes, but they may contain
characters with the high bit set. The \module{re} module is always
available.
Regular expressions use the backslash character (\character{\e}) to
indicate special forms or to allow special characters to be used
without invoking their special meaning. This collides with Python's
usage of the same character for the same purpose in string literals;
for example, to match a literal backslash, one might have to write
\code{'\e\e\e\e'} as the pattern string, because the regular expression
must be \samp{\e\e}, and each backslash must be expressed as
\samp{\e\e} inside a regular Python string literal.
The solution is to use Python's raw string notation for regular
expression patterns; backslashes are not handled in any special way in
a string literal prefixed with \character{r}. So \code{r"\e n"} is a
two-character string containing \character{\e} and \character{n},
while \code{"\e n"} is a one-character string containing a newline.
Usually patterns will be expressed in Python code using this raw
string notation.
\subsection{Regular Expression Syntax}
\label{re-syntax}
A regular expression (or RE) specifies a set of strings that matches
it; the functions in this module let you check if a particular string
matches a given regular expression (or if a given regular expression
matches a particular string, which comes down to the same thing).
Regular expressions can be concatenated to form new regular
expressions; if \emph{A} and \emph{B} are both regular expressions,
then \emph{AB} is also an regular expression. If a string \emph{p}
matches A and another string \emph{q} matches B, the string \emph{pq}
will match AB. Thus, complex expressions can easily be constructed
from simpler primitive expressions like the ones described here. For
details of the theory and implementation of regular expressions,
consult the Friedl book referenced below, or almost any textbook about
compiler construction.
A brief explanation of the format of regular expressions follows.
%For further information and a gentler presentation, consult XXX somewhere.
Regular expressions can contain both special and ordinary characters.
Most ordinary characters, like \character{A}, \character{a}, or \character{0},
are the simplest regular expressions; they simply match themselves.
You can concatenate ordinary characters, so \regexp{last} matches the
string \code{'last'}. (In the rest of this section, we'll write RE's in
\regexp{this special style}, usually without quotes, and strings to be
matched \code{'in single quotes'}.)
Some characters, like \character{|} or \character{(}, are special. Special
characters either stand for classes of ordinary characters, or affect
how the regular expressions around them are interpreted.
The special characters are:
% define these since they're used twice:
\newcommand{\MyLeftMargin}{0.7in}
\newcommand{\MyLabelWidth}{0.65in}
\begin{list}{}{\leftmargin \MyLeftMargin \labelwidth \MyLabelWidth}
\item[\character{.}] (Dot.) In the default mode, this matches any
character except a newline. If the \constant{DOTALL} flag has been
specified, this matches any character including a newline.
%
\item[\character{\^}] (Caret.) Matches the start of the string, and in
\constant{MULTILINE} mode also matches immediately after each newline.
%
\item[\character{\$}] Matches the end of the string, and in
\constant{MULTILINE} mode also matches before a newline.
\regexp{foo} matches both 'foo' and 'foobar', while the regular
expression \regexp{foo\$} matches only 'foo'.
%
\item[\character{*}] Causes the resulting RE to
match 0 or more repetitions of the preceding RE, as many repetitions
as are possible. \regexp{ab*} will
match 'a', 'ab', or 'a' followed by any number of 'b's.
%
\item[\character{+}] Causes the
resulting RE to match 1 or more repetitions of the preceding RE.
\regexp{ab+} will match 'a' followed by any non-zero number of 'b's; it
will not match just 'a'.
%
\item[\character{?}] Causes the resulting RE to
match 0 or 1 repetitions of the preceding RE. \regexp{ab?} will
match either 'a' or 'ab'.
\item[\code{*?}, \code{+?}, \code{??}] The \character{*}, \character{+}, and
\character{?} qualifiers are all \dfn{greedy}; they match as much text as
possible. Sometimes this behaviour isn't desired; if the RE
\regexp{<.*>} is matched against \code{'<H1>title</H1>'}, it will match the
entire string, and not just \code{'<H1>'}.
Adding \character{?} after the qualifier makes it perform the match in
\dfn{non-greedy} or \dfn{minimal} fashion; as \emph{few} characters as
possible will be matched. Using \regexp{.*?} in the previous
expression will match only \code{'<H1>'}.
%
\item[\code{\{\var{m},\var{n}\}}] Causes the resulting RE to match from
\var{m} to \var{n} repetitions of the preceding RE, attempting to
match as many repetitions as possible. For example, \regexp{a\{3,5\}}
will match from 3 to 5 \character{a} characters. Omitting \var{m} is the same
as specifying 0 for the lower bound; omitting \var{n} specifies an
infinite upper bound.
%
\item[\code{\{\var{m},\var{n}\}?}] Causes the resulting RE to
match from \var{m} to \var{n} repetitions of the preceding RE,
attempting to match as \emph{few} repetitions as possible. This is
the non-greedy version of the previous qualifier. For example, on the
6-character string \code{'aaaaaa'}, \regexp{a\{3,5\}} will match 5 \character{a}
characters, while \regexp{a\{3,5\}?} will only match 3 characters.
%
\item[\character{\e}] Either escapes special characters (permitting you to match
characters like \character{*}, \character{?}, and so forth), or
signals a special sequence; special sequences are discussed below.
If you're not using a raw string to
express the pattern, remember that Python also uses the
backslash as an escape sequence in string literals; if the escape
sequence isn't recognized by Python's parser, the backslash and
subsequent character are included in the resulting string. However,
if Python would recognize the resulting sequence, the backslash should
be repeated twice. This is complicated and hard to understand, so
it's highly recommended that you use raw strings for all but the
simplest expressions.
%
\item[\code{[]}] Used to indicate a set of characters. Characters can
be listed individually, or a range of characters can be indicated by
giving two characters and separating them by a \character{-}. Special
characters are not active inside sets. For example, \regexp{[akm\$]}
will match any of the characters \character{a}, \character{k},
\character{m}, or \character{\$}; \regexp{[a-z]}
will match any lowercase letter, and \code{[a-zA-Z0-9]} matches any
letter or digit. Character classes such as \code{\e w} or \code {\e
S} (defined below) are also acceptable inside a range. If you want to
include a \character{]} or a \character{-} inside a set, precede it with a
backslash, or place it as the first character. The
pattern \regexp{[]]} will match \code{']'}, for example.
You can match the characters not within a range by \dfn{complementing}
the set. This is indicated by including a
\character{\^} as the first character of the set; \character{\^} elsewhere will
simply match the \character{\^} character. For example, \regexp{[\^5]}
will match any character except \character{5}.
%
\item[\character{|}]\code{A|B}, where A and B can be arbitrary REs,
creates a regular expression that will match either A or B. This can
be used inside groups (see below) as well. To match a literal \character{|},
use \regexp{\e|}, or enclose it inside a character class, as in \regexp{[|]}.
%
\item[\code{(...)}] Matches whatever regular expression is inside the
parentheses, and indicates the start and end of a group; the contents
of a group can be retrieved after a match has been performed, and can
be matched later in the string with the \regexp{\e \var{number}} special
sequence, described below. To match the literals \character{(} or \character{')},
use \regexp{\e(} or \regexp{\e)}, or enclose them inside a character
class: \regexp{[(] [)]}.
%
\item[\code{(?...)}] This is an extension notation (a \character{?} following a
\character{(} is not meaningful otherwise). The first character after
the \character{?}
determines what the meaning and further syntax of the construct is.
Extensions usually do not create a new group;
\regexp{(?P<\var{name}>...)} is the only exception to this rule.
Following are the currently supported extensions.
%
\item[\code{(?iLmsx)}] (One or more letters from the set \character{i},
\character{L}, \character{m}, \character{s}, \character{x}.) The group matches
the empty string; the letters set the corresponding flags
(\constant{re.I}, \constant{re.L}, \constant{re.M}, \constant{re.S},
\constant{re.X}) for the entire regular expression. This is useful if
you wish to include the flags as part of the regular expression, instead
of passing a \var{flag} argument to the \function{compile()} function.
%
\item[\code{(?:...)}] A non-grouping version of regular parentheses.
Matches whatever regular expression is inside the parentheses, but the
substring matched by the
group \emph{cannot} be retrieved after performing a match or
referenced later in the pattern.
%
\item[\code{(?P<\var{name}>...)}] Similar to regular parentheses, but
the substring matched by the group is accessible via the symbolic group
name \var{name}. Group names must be valid Python identifiers. A
symbolic group is also a numbered group, just as if the group were not
named. So the group named 'id' in the example above can also be
referenced as the numbered group 1.
For example, if the pattern is
\regexp{(?P<id>[a-zA-Z_]\e w*)}, the group can be referenced by its
name in arguments to methods of match objects, such as \code{m.group('id')}
or \code{m.end('id')}, and also by name in pattern text
(e.g. \regexp{(?P=id)}) and replacement text (e.g. \code{\e g<id>}).
%
\item[\code{(?P=\var{name})}] Matches whatever text was matched by the
earlier group named \var{name}.
%
\item[\code{(?\#...)}] A comment; the contents of the parentheses are
simply ignored.
%
\item[\code{(?=...)}] Matches if \regexp{...} matches next, but doesn't
consume any of the string. This is called a lookahead assertion. For
example, \regexp{Isaac (?=Asimov)} will match \code{'Isaac~'} only if it's
followed by \code{'Asimov'}.
%
\item[\code{(?!...)}] Matches if \regexp{...} doesn't match next. This
is a negative lookahead assertion. For example,
\regexp{Isaac (?!Asimov)} will match \code{'Isaac~'} only if it's \emph{not}
followed by \code{'Asimov'}.
\end{list}
The special sequences consist of \character{\e} and a character from the
list below. If the ordinary character is not on the list, then the
resulting RE will match the second character. For example,
\regexp{\e\$} matches the character \character{\$}.
\begin{list}{}{\leftmargin \MyLeftMargin \labelwidth \MyLabelWidth}
%
\item[\code{\e \var{number}}] Matches the contents of the group of the
same number. Groups are numbered starting from 1. For example,
\regexp{(.+) \e 1} matches \code{'the the'} or \code{'55 55'}, but not
\code{'the end'} (note
the space after the group). This special sequence can only be used to
match one of the first 99 groups. If the first digit of \var{number}
is 0, or \var{number} is 3 octal digits long, it will not be interpreted
as a group match, but as the character with octal value \var{number}.
Inside the \character{[} and \character{]} of a character class, all numeric
escapes are treated as characters.
%
\item[\code{\e A}] Matches only at the start of the string.
%
\item[\code{\e b}] Matches the empty string, but only at the
beginning or end of a word. A word is defined as a sequence of
alphanumeric characters, so the end of a word is indicated by
whitespace or a non-alphanumeric character. Inside a character range,
\regexp{\e b} represents the backspace character, for compatibility with
Python's string literals.
%
\item[\code{\e B}] Matches the empty string, but only when it is
\emph{not} at the beginning or end of a word.
%
\item[\code{\e d}]Matches any decimal digit; this is
equivalent to the set \regexp{[0-9]}.
%
\item[\code{\e D}]Matches any non-digit character; this is
equivalent to the set \regexp{[\^0-9]}.
%
\item[\code{\e s}]Matches any whitespace character; this is
equivalent to the set \regexp{[ \e t\e n\e r\e f\e v]}.
%
\item[\code{\e S}]Matches any non-whitespace character; this is
equivalent to the set \regexp{[\^\ \e t\e n\e r\e f\e v]}.
%
\item[\code{\e w}]When the \constant{LOCALE} flag is not specified,
matches any alphanumeric character; this is equivalent to the set
\regexp{[a-zA-Z0-9_]}. With \constant{LOCALE}, it will match the set
\regexp{[0-9_]} plus whatever characters are defined as letters for the
current locale.
%
\item[\code{\e W}]When the \constant{LOCALE} flag is not specified,
matches any non-alphanumeric character; this is equivalent to the set
\regexp{[\^a-zA-Z0-9_]}. With \constant{LOCALE}, it will match any
character not in the set \regexp{[0-9_]}, and not defined as a letter
for the current locale.
\item[\code{\e Z}]Matches only at the end of the string.
%
\item[\code{\e \e}] Matches a literal backslash.
\end{list}
\subsection{Module Contents}
\nodename{Contents of Module re}
The module defines the following functions and constants, and an exception:
\begin{funcdesc}{compile}{pattern\optional{, flags}}
Compile a regular expression pattern into a regular expression
object, which can be used for matching using its \function{match()} and
\function{search()} methods, described below.
The expression's behaviour can be modified by specifying a
\var{flags} value. Values can be any of the following variables,
combined using bitwise OR (the \code{|} operator).
The sequence
\begin{verbatim}
prog = re.compile(pat)
result = prog.match(str)
\end{verbatim}
is equivalent to
\begin{verbatim}
result = re.match(pat, str)
\end{verbatim}
but the version using \function{compile()} is more efficient when the
expression will be used several times in a single program.
%(The compiled version of the last pattern passed to
%\function{regex.match()} or \function{regex.search()} is cached, so
%programs that use only a single regular expression at a time needn't
%worry about compiling regular expressions.)
\end{funcdesc}
\begin{datadesc}{I}
\dataline{IGNORECASE}
Perform case-insensitive matching; expressions like \regexp{[A-Z]} will match
lowercase letters, too. This is not affected by the current locale.
\end{datadesc}
\begin{datadesc}{L}
\dataline{LOCALE}
Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b},
\regexp{\e B}, dependent on the current locale.
\end{datadesc}
\begin{datadesc}{M}
\dataline{MULTILINE}
When specified, the pattern character \character{\^} matches at the
beginning of the string and at the beginning of each line
(immediately following each newline); and the pattern character
\character{\$} matches at the end of the string and at the end of each line
(immediately preceding each newline).
By default, \character{\^} matches only at the beginning of the string, and
\character{\$} only at the end of the string and immediately before the
newline (if any) at the end of the string.
\end{datadesc}
\begin{datadesc}{S}
\dataline{DOTALL}
Make the \character{.} special character match any character at all, including a
newline; without this flag, \character{.} will match anything \emph{except}
a newline.
\end{datadesc}
\begin{datadesc}{X}
\dataline{VERBOSE}
This flag allows you to write regular expressions that look nicer.
Whitespace within the pattern is ignored,
except when in a character class or preceded by an unescaped
backslash, and, when a line contains a \character{\#} neither in a character
class or preceded by an unescaped backslash, all characters from the
leftmost such \character{\#} through the end of the line are ignored.
% XXX should add an example here
\end{datadesc}
\begin{funcdesc}{escape}{string}
Return \var{string} with all non-alphanumerics backslashed; this is
useful if you want to match an arbitrary literal string that may have
regular expression metacharacters in it.
\end{funcdesc}
\begin{funcdesc}{match}{pattern, string\optional{, flags}}
If zero or more characters at the beginning of \var{string} match
the regular expression \var{pattern}, return a corresponding
\class{MatchObject} instance. Return \code{None} if the string does not
match the pattern; note that this is different from a zero-length
match.
\end{funcdesc}
\begin{funcdesc}{search}{pattern, string\optional{, flags}}
Scan through \var{string} looking for a location where the regular
expression \var{pattern} produces a match, and return a
corresponding \class{MatchObject} instance.
Return \code{None} if no
position in the string matches the pattern; note that this is
different from finding a zero-length match at some point in the string.
\end{funcdesc}
\begin{funcdesc}{split}{pattern, string, \optional{, maxsplit\code{ = 0}}}
Split \var{string} by the occurrences of \var{pattern}. If
capturing parentheses are used in pattern, then occurrences of
patterns or subpatterns are also returned.
If \var{maxsplit} is nonzero, at most \var{maxsplit} splits
occur, and the remainder of the string is returned as the final
element of the list. (Incompatibility note: in the original Python
1.5 release, \var{maxsplit} was ignored. This has been fixed in
later releases.)
%
\begin{verbatim}
>>> re.split('[\W]+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split('([\W]+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split('[\W]+', 'Words, words, words.', 1)
['Words', 'words, words.']
\end{verbatim}
%
This function combines and extends the functionality of
the old \function{regsub.split()} and \function{regsub.splitx()}.
\end{funcdesc}
\begin{funcdesc}{sub}{pattern, repl, string\optional{, count\code{ = 0}}}
Return the string obtained by replacing the leftmost non-overlapping
occurrences of \var{pattern} in \var{string} by the replacement
\var{repl}. If the pattern isn't found, \var{string} is returned
unchanged. \var{repl} can be a string or a function; if a function,
it is called for every non-overlapping occurance of \var{pattern}.
The function takes a single match object argument, and returns the
replacement string. For example:
%
\begin{verbatim}
>>> def dashrepl(matchobj):
.... if matchobj.group(0) == '-': return ' '
.... else: return '-'
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
\end{verbatim}
%
The pattern may be a string or a
regex object; if you need to specify
regular expression flags, you must use a regex object, or use
embedded modifiers in a pattern; e.g.
\samp{sub("(?i)b+", "x", "bbbb BBBB")} returns \code{'x x'}.
The optional argument \var{count} is the maximum number of pattern
occurrences to be replaced; \var{count} must be a non-negative integer, and
the default value of 0 means to replace all occurrences.
Empty matches for the pattern are replaced only when not adjacent to a
previous match, so \samp{sub('x*', '-', 'abc')} returns \code{'-a-b-c-'}.
If \var{repl} is a string, any backslash escapes in it are processed.
That is, \samp{\e n} is converted to a single newline character,
\samp{\e r} is converted to a linefeed, and so forth. Unknown escapes
such as \samp{\e j} are left alone. Backreferences, such as \samp{\e 6}, are
replaced with the substring matched by group 6 in the pattern.
In addition to character escapes and backreferences as described
above, \samp{\e g<name>} will use the substring matched by the group
named \samp{name}, as defined by the \regexp{(?P<name>...)} syntax.
\samp{\e g<number>} uses the corresponding group number; \samp{\e
g<2>} is therefore equivalent to \samp{\e 2}, but isn't ambiguous in a
replacement such as \samp{\e g<2>0}. \samp{\e 20} would be
interpreted as a reference to group 20, not a reference to group 2
followed by the literal character \character{0}.
\end{funcdesc}
\begin{funcdesc}{subn}{pattern, repl, string\optional{, count\code{ = 0}}}
Perform the same operation as \function{sub()}, but return a tuple
\code{(\var{new_string}, \var{number_of_subs_made})}.
\end{funcdesc}
\begin{excdesc}{error}
Exception raised when a string passed to one of the functions here
is not a valid regular expression (e.g., unmatched parentheses) or
when some other error occurs during compilation or matching. It is
never an error if a string contains no match for a pattern.
\end{excdesc}
\subsection{Regular Expression Objects}
\label{re-objects}
Compiled regular expression objects support the following methods and
attributes:
\begin{methoddesc}[RegexObject]{match}{string\optional{, pos}\optional{,
endpos}}
If zero or more characters at the beginning of \var{string} match
this regular expression, return a corresponding
\class{MatchObject} instance. Return \code{None} if the string does not
match the pattern; note that this is different from a zero-length
match.
The optional second parameter \var{pos} gives an index in the string
where the search is to start; it defaults to \code{0}. The
\character{\^} pattern character will not match at the index where the
search is to start.
The optional parameter \var{endpos} limits how far the string will
be searched; it will be as if the string is \var{endpos} characters
long, so only the characters from \var{pos} to \var{endpos} will be
searched for a match.
\end{methoddesc}
\begin{methoddesc}[RegexObject]{search}{string\optional{, pos}\optional{,
endpos}}
Scan through \var{string} looking for a location where this regular
expression produces a match. Return \code{None} if no
position in the string matches the pattern; note that this is
different from finding a zero-length match at some point in the string.
The optional \var{pos} and \var{endpos} parameters have the same
meaning as for the \method{match()} method.
\end{methoddesc}
\begin{methoddesc}[RegexObject]{split}{string, \optional{,
maxsplit\code{ = 0}}}
Identical to the \function{split()} function, using the compiled pattern.
\end{methoddesc}
\begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}}
Identical to the \function{sub()} function, using the compiled pattern.
\end{methoddesc}
\begin{methoddesc}[RegexObject]{subn}{repl, string\optional{,
count\code{ = 0}}}
Identical to the \function{subn()} function, using the compiled pattern.
\end{methoddesc}
\begin{memberdesc}[RegexObject]{flags}
The flags argument used when the regex object was compiled, or
\code{0} if no flags were provided.
\end{memberdesc}
\begin{memberdesc}[RegexObject]{groupindex}
A dictionary mapping any symbolic group names defined by
\regexp{(?P<\var{id}>)} to group numbers. The dictionary is empty if no
symbolic groups were used in the pattern.
\end{memberdesc}
\begin{memberdesc}[RegexObject]{pattern}
The pattern string from which the regex object was compiled.
\end{memberdesc}
\subsection{Match Objects}
\label{match-objects}
\class{MatchObject} instances support the following methods and attributes:
\begin{methoddesc}[MatchObject]{group}{\optional{group1, group2, ...}}
Returns one or more subgroups of the match. If there is a single
argument, the result is a single string; if there are
multiple arguments, the result is a tuple with one item per argument.
Without arguments, \var{group1} defaults to zero (i.e. the whole match
is returned).
If a \var{groupN} argument is zero, the corresponding return value is the
entire matching string; if it is in the inclusive range [1..99], it is
the string matching the the corresponding parenthesized group. If a
group number is negative or larger than the number of groups defined
in the pattern, an \exception{IndexError} exception is raised.
If a group is contained in a part of the pattern that did not match,
the corresponding result is \code{None}. If a group is contained in a
part of the pattern that matched multiple times, the last match is
returned.
If the regular expression uses the \regexp{(?P<\var{name}>...)} syntax,
the \var{groupN} arguments may also be strings identifying groups by
their group name. If a string argument is not used as a group name in
the pattern, an \exception{IndexError} exception is raised.
A moderately complicated example:
\begin{verbatim}
m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14')
\end{verbatim}
After performing this match, \code{m.group(1)} is \code{'3'}, as is
\code{m.group('int')}, and \code{m.group(2)} is \code{'14'}.
\end{methoddesc}
\begin{methoddesc}[MatchObject]{groups}{}
Return a tuple containing all the subgroups of the match, from 1 up to
however many groups are in the pattern. Groups that did not
participate in the match have values of \code{None}. (Incompatibility
note: in the original Python 1.5 release, if the tuple was one element
long, a string would be returned instead. In later versions, a
singleton tuple is returned in such cases.)
\end{methoddesc}
\begin{methoddesc}[MatchObject]{start}{\optional{group}}
\funcline{end}{\optional{group}}
Return the indices of the start and end of the substring
matched by \var{group}; \var{group} defaults to zero (meaning the whole
matched substring).
Return \code{None} if \var{group} exists but
did not contribute to the match. For a match object
\var{m}, and a group \var{g} that did contribute to the match, the
substring matched by group \var{g} (equivalent to
\code{\var{m}.group(\var{g})}) is
\begin{verbatim}
m.string[m.start(g):m.end(g)]
\end{verbatim}
Note that
\code{m.start(\var{group})} will equal \code{m.end(\var{group})} if
\var{group} matched a null string. For example, after \code{\var{m} =
re.search('b(c?)', 'cba')}, \code{\var{m}.start(0)} is 1,
\code{\var{m}.end(0)} is 2, \code{\var{m}.start(1)} and
\code{\var{m}.end(1)} are both 2, and \code{\var{m}.start(2)} raises
an \exception{IndexError} exception.
\end{methoddesc}
\begin{methoddesc}[MatchObject]{span}{\optional{group}}
For \class{MatchObject} \var{m}, return the 2-tuple
\code{(\var{m}.start(\var{group}), \var{m}.end(\var{group}))}.
Note that if \var{group} did not contribute to the match, this is
\code{(None, None)}. Again, \var{group} defaults to zero.
\end{methoddesc}
\begin{memberdesc}[MatchObject]{pos}
The value of \var{pos} which was passed to the
\function{search()} or \function{match()} function. This is the index into
the string at which the regex engine started looking for a match.
\end{memberdesc}
\begin{memberdesc}[MatchObject]{endpos}
The value of \var{endpos} which was passed to the
\function{search()} or \function{match()} function. This is the index into
the string beyond which the regex engine will not go.
\end{memberdesc}
\begin{memberdesc}[MatchObject]{re}
The regular expression object whose \method{match()} or
\method{search()} method produced this \class{MatchObject} instance.
\end{memberdesc}
\begin{memberdesc}[MatchObject]{string}
The string passed to \function{match()} or \function{search()}.
\end{memberdesc}
\begin{seealso}
\seetext{Jeffrey Friedl, \emph{Mastering Regular Expressions},
O'Reilly. The Python material in this book dates from before the
\module{re} module, but it covers writing good regular expression
patterns in great detail.}
\end{seealso}

366
Doc/libregex.tex
View File

@ -1,366 +0,0 @@
\section{Built-in Module \module{regex}}
\label{module-regex}
\bimodindex{regex}
This module provides regular expression matching operations similar to
those found in Emacs.
\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
\code{re}\refstmodindex{re} module, which supports the more powerful
and regular Perl-style regular expressions. Existing code should be
converted. The standard library module
\code{reconvert}\refstmodindex{reconvert} helps in converting
\code{regex} style regular expressions to \code{re}\refstmodindex{re}
style regular expressions. (For more conversion help, see Andrew
Kuchling's\index{Kuchling, Andrew} ``\module{regex-to-re} HOWTO'' at
\url{http://www.python.org/doc/howto/regex-to-re/}.)
By default the patterns are Emacs-style regular expressions
(with one exception). There is
a way to change the syntax to match that of several well-known
\UNIX{} utilities. The exception is that Emacs' \samp{\e s}
pattern is not supported, since the original implementation references
the Emacs syntax tables.
This module is 8-bit clean: both patterns and strings may contain null
bytes and characters whose high bit is set.
\strong{Please note:} There is a little-known fact about Python string
literals which means that you don't usually have to worry about
doubling backslashes, even though they are used to escape special
characters in string literals as well as in regular expressions. This
is because Python doesn't remove backslashes from string literals if
they are followed by an unrecognized escape character.
\emph{However}, if you want to include a literal \dfn{backslash} in a
regular expression represented as a string literal, you have to
\emph{quadruple} it or enclose it in a singleton character class.
E.g.\ to extract \LaTeX\ \samp{\e section\{{\rm
\ldots}\}} headers from a document, you can use this pattern:
\code{'[\e ]section\{\e (.*\e )\}'}. \emph{Another exception:}
the escape sequece \samp{\e b} is significant in string literals
(where it means the ASCII bell character) as well as in Emacs regular
expressions (where it stands for a word boundary), so in order to
search for a word boundary, you should use the pattern \code{'\e \e b'}.
Similarly, a backslash followed by a digit 0-7 should be doubled to
avoid interpretation as an octal escape.
\subsection{Regular Expressions}
A regular expression (or RE) specifies a set of strings that matches
it; the functions in this module let you check if a particular string
matches a given regular expression (or if a given regular expression
matches a particular string, which comes down to the same thing).
Regular expressions can be concatenated to form new regular
expressions; if \emph{A} and \emph{B} are both regular expressions,
then \emph{AB} is also an regular expression. If a string \emph{p}
matches A and another string \emph{q} matches B, the string \emph{pq}
will match AB. Thus, complex expressions can easily be constructed
from simpler ones like the primitives described here. For details of
the theory and implementation of regular expressions, consult almost
any textbook about compiler construction.
% XXX The reference could be made more specific, say to
% "Compilers: Principles, Techniques and Tools", by Alfred V. Aho,
% Ravi Sethi, and Jeffrey D. Ullman, or some FA text.
A brief explanation of the format of regular expressions follows.
Regular expressions can contain both special and ordinary characters.
Ordinary characters, like '\code{A}', '\code{a}', or '\code{0}', are
the simplest regular expressions; they simply match themselves. You
can concatenate ordinary characters, so '\code{last}' matches the
characters 'last'. (In the rest of this section, we'll write RE's in
\code{this special font}, usually without quotes, and strings to be
matched 'in single quotes'.)
Special characters either stand for classes of ordinary characters, or
affect how the regular expressions around them are interpreted.
The special characters are:
\begin{itemize}
\item[\code{.}] (Dot.) Matches any character except a newline.
\item[\code{\^}] (Caret.) Matches the start of the string.
\item[\code{\$}] Matches the end of the string.
\code{foo} matches both 'foo' and 'foobar', while the regular
expression '\code{foo\$}' matches only 'foo'.
\item[\code{*}] Causes the resulting RE to
match 0 or more repetitions of the preceding RE. \code{ab*} will
match 'a', 'ab', or 'a' followed by any number of 'b's.
\item[\code{+}] Causes the
resulting RE to match 1 or more repetitions of the preceding RE.
\code{ab+} will match 'a' followed by any non-zero number of 'b's; it
will not match just 'a'.
\item[\code{?}] Causes the resulting RE to
match 0 or 1 repetitions of the preceding RE. \code{ab?} will
match either 'a' or 'ab'.
\item[\code{\e}] Either escapes special characters (permitting you to match
characters like '*?+\&\$'), or signals a special sequence; special
sequences are discussed below. Remember that Python also uses the
backslash as an escape sequence in string literals; if the escape
sequence isn't recognized by Python's parser, the backslash and
subsequent character are included in the resulting string. However,
if Python would recognize the resulting sequence, the backslash should
be repeated twice.
\item[\code{[]}] Used to indicate a set of characters. Characters can
be listed individually, or a range is indicated by giving two
characters and separating them by a '-'. Special characters are
not active inside sets. For example, \code{[akm\$]}
will match any of the characters 'a', 'k', 'm', or '\$'; \code{[a-z]} will
match any lowercase letter.
If you want to include a \code{]} inside a
set, it must be the first character of the set; to include a \code{-},
place it as the first or last character.
Characters \emph{not} within a range can be matched by including a
\code{\^} as the first character of the set; \code{\^} elsewhere will
simply match the '\code{\^}' character.
\end{itemize}
The special sequences consist of '\code{\e}' and a character
from the list below. If the ordinary character is not on the list,
then the resulting RE will match the second character. For example,
\code{\e\$} matches the character '\$'. Ones where the backslash
should be doubled in string literals are indicated.
\begin{itemize}
\item[\code{\e|}]\code{A\e|B}, where A and B can be arbitrary REs,
creates a regular expression that will match either A or B. This can
be used inside groups (see below) as well.
%
\item[\code{\e( \e)}] Indicates the start and end of a group; the
contents of a group can be matched later in the string with the
\code{\e [1-9]} special sequence, described next.
\end{itemize}
\begin{fulllineitems}
\item[\code{\e \e 1, ... \e \e 7, \e 8, \e 9}]
Matches the contents of the group of the same
number. For example, \code{\e (.+\e ) \e \e 1} matches 'the the' or
'55 55', but not 'the end' (note the space after the group). This
special sequence can only be used to match one of the first 9 groups;
groups with higher numbers can be matched using the \code{\e v}
sequence. (\code{\e 8} and \code{\e 9} don't need a double backslash
because they are not octal digits.)
\end{fulllineitems}
\begin{itemize}
\item[\code{\e \e b}] Matches the empty string, but only at the
beginning or end of a word. A word is defined as a sequence of
alphanumeric characters, so the end of a word is indicated by
whitespace or a non-alphanumeric character.
%
\item[\code{\e B}] Matches the empty string, but when it is \emph{not} at the
beginning or end of a word.
%
\item[\code{\e v}] Must be followed by a two digit decimal number, and
matches the contents of the group of the same number. The group
number must be between 1 and 99, inclusive.
%
\item[\code{\e w}]Matches any alphanumeric character; this is
equivalent to the set \code{[a-zA-Z0-9]}.
%
\item[\code{\e W}] Matches any non-alphanumeric character; this is
equivalent to the set \code{[\^a-zA-Z0-9]}.
\item[\code{\e <}] Matches the empty string, but only at the beginning of a
word. A word is defined as a sequence of alphanumeric characters, so
the end of a word is indicated by whitespace or a non-alphanumeric
character.
\item[\code{\e >}] Matches the empty string, but only at the end of a
word.
\item[\code{\e \e \e \e}] Matches a literal backslash.
% In Emacs, the following two are start of buffer/end of buffer. In
% Python they seem to be synonyms for ^$.
\item[\code{\e `}] Like \code{\^}, this only matches at the start of the
string.
\item[\code{\e \e '}] Like \code{\$}, this only matches at the end of
the string.
% end of buffer
\end{itemize}
\subsection{Module Contents}
\nodename{Contents of Module regex}
The module defines these functions, and an exception:
\begin{funcdesc}{match}{pattern, string}
Return how many characters at the beginning of \var{string} match
the regular expression \var{pattern}. Return \code{-1} if the
string does not match the pattern (this is different from a
zero-length match!).
\end{funcdesc}
\begin{funcdesc}{search}{pattern, string}
Return the first position in \var{string} that matches the regular
expression \var{pattern}. Return \code{-1} if no position in the string
matches the pattern (this is different from a zero-length match
anywhere!).
\end{funcdesc}
\begin{funcdesc}{compile}{pattern\optional{, translate}}
Compile a regular expression pattern into a regular expression
object, which can be used for matching using its \code{match()} and
\code{search()} methods, described below. The optional argument
\var{translate}, if present, must be a 256-character string
indicating how characters (both of the pattern and of the strings to
be matched) are translated before comparing them; the \var{i}-th
element of the string gives the translation for the character with
\ASCII{} code \var{i}. This can be used to implement
case-insensitive matching; see the \code{casefold} data item below.
The sequence
\begin{verbatim}
prog = regex.compile(pat)
result = prog.match(str)
\end{verbatim}
%
is equivalent to
\begin{verbatim}
result = regex.match(pat, str)
\end{verbatim}
but the version using \code{compile()} is more efficient when multiple
regular expressions are used concurrently in a single program. (The
compiled version of the last pattern passed to \code{regex.match()} or
\code{regex.search()} is cached, so programs that use only a single
regular expression at a time needn't worry about compiling regular
expressions.)
\end{funcdesc}
\begin{funcdesc}{set_syntax}{flags}
Set the syntax to be used by future calls to \code{compile()},
\code{match()} and \code{search()}. (Already compiled expression
objects are not affected.) The argument is an integer which is the
OR of several flag bits. The return value is the previous value of
the syntax flags. Names for the flags are defined in the standard
module \code{regex_syntax}\refstmodindex{regex_syntax}; read the
file \file{regex_syntax.py} for more information.
\end{funcdesc}
\begin{funcdesc}{get_syntax}{}
Returns the current value of the syntax flags as an integer.
\end{funcdesc}
\begin{funcdesc}{symcomp}{pattern\optional{, translate}}
This is like \code{compile()}, but supports symbolic group names: if a
parenthesis-enclosed group begins with a group name in angular
brackets, e.g. \code{'\e(<id>[a-z][a-z0-9]*\e)'}, the group can
be referenced by its name in arguments to the \code{group()} method of
the resulting compiled regular expression object, like this:
\code{p.group('id')}. Group names may contain alphanumeric characters
and \code{'_'} only.
\end{funcdesc}
\begin{excdesc}{error}
Exception raised when a string passed to one of the functions here
is not a valid regular expression (e.g., unmatched parentheses) or
when some other error occurs during compilation or matching. (It is
never an error if a string contains no match for a pattern.)
\end{excdesc}
\begin{datadesc}{casefold}
A string suitable to pass as the \var{translate} argument to
\code{compile()} to map all upper case characters to their lowercase
equivalents.
\end{datadesc}
\noindent
Compiled regular expression objects support these methods:
\setindexsubitem{(regex method)}
\begin{funcdesc}{match}{string\optional{, pos}}
Return how many characters at the beginning of \var{string} match
the compiled regular expression. Return \code{-1} if the string
does not match the pattern (this is different from a zero-length
match!).
The optional second parameter, \var{pos}, gives an index in the string
where the search is to start; it defaults to \code{0}. This is not
completely equivalent to slicing the string; the \code{'\^'} pattern
character matches at the real begin of the string and at positions
just after a newline, not necessarily at the index where the search
is to start.
\end{funcdesc}
\begin{funcdesc}{search}{string\optional{, pos}}
Return the first position in \var{string} that matches the regular
expression \code{pattern}. Return \code{-1} if no position in the
string matches the pattern (this is different from a zero-length
match anywhere!).
The optional second parameter has the same meaning as for the
\code{match()} method.
\end{funcdesc}
\begin{funcdesc}{group}{index, index, ...}
This method is only valid when the last call to the \code{match()}
or \code{search()} method found a match. It returns one or more
groups of the match. If there is a single \var{index} argument,
the result is a single string; if there are multiple arguments, the
result is a tuple with one item per argument. If the \var{index} is
zero, the corresponding return value is the entire matching string; if
it is in the inclusive range [1..99], it is the string matching the
the corresponding parenthesized group (using the default syntax,
groups are parenthesized using \code{{\e}(} and \code{{\e})}). If no
such group exists, the corresponding result is \code{None}.
If the regular expression was compiled by \code{symcomp()} instead of
\code{compile()}, the \var{index} arguments may also be strings
identifying groups by their group name.
\end{funcdesc}
\noindent
Compiled regular expressions support these data attributes:
\setindexsubitem{(regex attribute)}
\begin{datadesc}{regs}
When the last call to the \code{match()} or \code{search()} method found a
match, this is a tuple of pairs of indexes corresponding to the
beginning and end of all parenthesized groups in the pattern. Indices
are relative to the string argument passed to \code{match()} or
\code{search()}. The 0-th tuple gives the beginning and end or the
whole pattern. When the last match or search failed, this is
\code{None}.
\end{datadesc}
\begin{datadesc}{last}
When the last call to the \code{match()} or \code{search()} method found a
match, this is the string argument passed to that method. When the
last match or search failed, this is \code{None}.
\end{datadesc}
\begin{datadesc}{translate}
This is the value of the \var{translate} argument to
\code{regex.compile()} that created this regular expression object. If
the \var{translate} argument was omitted in the \code{regex.compile()}
call, this is \code{None}.
\end{datadesc}
\begin{datadesc}{givenpat}
The regular expression pattern as passed to \code{compile()} or
\code{symcomp()}.
\end{datadesc}
\begin{datadesc}{realpat}
The regular expression after stripping the group names for regular
expressions compiled with \code{symcomp()}. Same as \code{givenpat}
otherwise.
\end{datadesc}
\begin{datadesc}{groupindex}
A dictionary giving the mapping from symbolic group names to numerical
group indexes for regular expressions compiled with \code{symcomp()}.
\code{None} otherwise.
\end{datadesc}

70
Doc/libregsub.tex
View File

@ -1,70 +0,0 @@
\section{Standard Module \module{regsub}}
\label{module-regsub}
\stmodindex{regsub}
This module defines a number of functions useful for working with
regular expressions (see built-in module \code{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
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
conversion help, see Andrew Kuchling's\index{Kuchling, Andrew}
``regex-to-re HOWTO'' at
\url{http://www.python.org/doc/howto/regex-to-re/}.)
\begin{funcdesc}{sub}{pat, repl, str}
Replace the first occurrence of pattern \var{pat} in string
\var{str} by replacement \var{repl}. If the pattern isn't found,
the string is returned unchanged. The pattern may be a string or an
already compiled pattern. The replacement may contain references
\samp{\e \var{digit}} to subpatterns and escaped backslashes.
\end{funcdesc}
\begin{funcdesc}{gsub}{pat, repl, str}
Replace all (non-overlapping) occurrences of pattern \var{pat} in
string \var{str} by replacement \var{repl}. The same rules as for
\code{sub()} apply. Empty matches for the pattern are replaced only
when not adjacent to a previous match, so e.g.
\code{gsub('', '-', 'abc')} returns \code{'-a-b-c-'}.
\end{funcdesc}
\begin{funcdesc}{split}{str, pat\optional{, maxsplit}}
Split the string \var{str} in fields separated by delimiters matching
the pattern \var{pat}, and return a list containing the fields. Only
non-empty matches for the pattern are considered, so e.g.
\code{split('a:b', ':*')} returns \code{['a', 'b']} and
\code{split('abc', '')} returns \code{['abc']}. The \var{maxsplit}
defaults to 0. If it is nonzero, only \var{maxsplit} number of splits
occur, and the remainder of the string is returned as the final
element of the list.
\end{funcdesc}
\begin{funcdesc}{splitx}{str, pat\optional{, maxsplit}}
Split the string \var{str} in fields separated by delimiters matching
the pattern \var{pat}, and return a list containing the fields as well
as the separators. For example, \code{splitx('a:::b', ':*')} returns
\code{['a', ':::', 'b']}. Otherwise, this function behaves the same
as \code{split}.
\end{funcdesc}
\begin{funcdesc}{capwords}{s\optional{, pat}}
Capitalize words separated by optional pattern \var{pat}. The default
pattern uses any characters except letters, digits and underscores as
word delimiters. Capitalization is done by changing the first
character of each word to upper case.
\end{funcdesc}
\begin{funcdesc}{clear_cache}{}
The regsub module maintains a cache of compiled regular expressions,
keyed on the regular expression string and the syntax of the regex
module at the time the expression was compiled. This function clears
that cache.
\end{funcdesc}

200
Doc/libresource.tex
View File

@ -1,200 +0,0 @@
\section{Built-in Module \module{resource}}
\label{module-resource}
\bimodindex{resource}
This module provides basic mechanisms for measuring and controlling
system resources utilized by a program.
Symbolic constants are used to specify particular system resources and
to request usage information about either the current process or its
children.
A single exception is defined for errors:
\begin{excdesc}{error}
The functions described below may raise this error if the underlying
system call failures unexpectedly.
\end{excdesc}
\subsection{Resource Limits}
Resources usage can be limited using the \function{setrlimit()} function
described below. Each resource is controlled by a pair of limits: a
soft limit and a hard limit. The soft limit is the current limit, and
may be lowered or raised by a process over time. The soft limit can
never exceed the hard limit. The hard limit can be lowered to any
value greater than the soft limit, but not raised. (Only processes with
the effective UID of the super-user can raise a hard limit.)
The specific resources that can be limited are system dependent. They
are described in the \manpage{getrlimit}{2} man page. The resources
listed below are supported when the underlying operating system
supports them; resources which cannot be checked or controlled by the
operating system are not defined in this module for those platforms.
\begin{funcdesc}{getrlimit}{resource}
Returns a tuple \code{(\var{soft}, \var{hard})} with the current
soft and hard limits of \var{resource}. Raises \exception{ValueError} if
an invalid resource is specified, or \exception{error} if the
underyling system call fails unexpectedly.
\end{funcdesc}
\begin{funcdesc}{setrlimit}{resource, limits}
Sets new limits of consumption of \var{resource}. The \var{limits}
argument must be a tuple \code{(\var{soft}, \var{hard})} of two
integers describing the new limits. A value of \code{-1} can be used to
specify the maximum possible upper limit.
Raises \exception{ValueError} if an invalid resource is specified,
if the new soft limit exceeds the hard limit, or if a process tries
to raise its hard limit (unless the process has an effective UID of
super-user). Can also raise \exception{error} if the underyling
system call fails.
\end{funcdesc}
These symbols define resources whose consumption can be controlled
using the \function{setrlimit()} and \function{getrlimit()} functions
described below. The values of these symbols are exactly the constants
used by \C{} programs.
The \UNIX{} man page for \manpage{getrlimit}{2} lists the available
resources. Note that not all systems use the same symbol or same
value to denote the same resource.
\begin{datadesc}{RLIMIT_CORE}
The maximum size (in bytes) of a core file that the current process
can create. This may result in the creation of a partial core file
if a larger core would be required to contain the entire process
image.
\end{datadesc}
\begin{datadesc}{RLIMIT_CPU}
The maximum amount of CPU time (in seconds) that a process can
use. If this limit is exceeded, a \constant{SIGXCPU} signal is sent to
the process. (See the \module{signal} module documentation for
information about how to catch this signal and do something useful,
e.g. flush open files to disk.)
\end{datadesc}
\begin{datadesc}{RLIMIT_FSIZE}
The maximum size of a file which the process may create. This only
affects the stack of the main thread in a multi-threaded process.
\end{datadesc}
\begin{datadesc}{RLIMIT_DATA}
The maximum size (in bytes) of the process's heap.
\end{datadesc}
\begin{datadesc}{RLIMIT_STACK}
The maximum size (in bytes) of the call stack for the current
process.
\end{datadesc}
\begin{datadesc}{RLIMIT_RSS}
The maximum resident set size that should be made available to the
process.
\end{datadesc}
\begin{datadesc}{RLIMIT_NPROC}
The maximum number of processes the current process may create.
\end{datadesc}
\begin{datadesc}{RLIMIT_NOFILE}
The maximum number of open file descriptors for the current
process.
\end{datadesc}
\begin{datadesc}{RLIMIT_OFILE}
The BSD name for \constant{RLIMIT_NOFILE}.
\end{datadesc}
\begin{datadesc}{RLIMIT_MEMLOC}
The maximm address space which may be locked in memory.
\end{datadesc}
\begin{datadesc}{RLIMIT_VMEM}
The largest area of mapped memory which the process may occupy.
\end{datadesc}
\begin{datadesc}{RLIMIT_AS}
The maximum area (in bytes) of address space which may be taken by
the process.
\end{datadesc}
\subsection{Resource Usage}
These functiona are used to retrieve resource usage information:
\begin{funcdesc}{getrusage}{who}
This function returns a large tuple that describes the resources
consumed by either the current process or its children, as specified
by the \var{who} parameter. The \var{who} parameter should be
specified using one of the \code{RUSAGE_*} constants described
below.
The elements of the return value each
describe how a particular system resource has been used, e.g. amount
of time spent running is user mode or number of times the process was
swapped out of main memory. Some values are dependent on the clock
tick internal, e.g. the amount of memory the process is using.
The first two elements of the return value are floating point values
representing the amount of time spent executing in user mode and the
amount of time spent executing in system mode, respectively. The
remaining values are integers. Consult the \manpage{getrusage}{2}
man page for detailed information about these values. A brief
summary is presented here:
\begin{tableii}{r|l}{code}{Offset}{Resource}
\lineii{0}{time in user mode (float)}
\lineii{1}{time in system mode (float)}
\lineii{2}{maximum resident set size}
\lineii{3}{shared memory size}
\lineii{4}{unshared memory size}
\lineii{5}{unshared stack size}
\lineii{6}{page faults not requiring I/O}
\lineii{7}{page faults requiring I/O}
\lineii{8}{number of swap outs}
\lineii{9}{block input operations}
\lineii{10}{block output operations}
\lineii{11}{messages sent}
\lineii{12}{messages received}
\lineii{13}{signals received}
\lineii{14}{voluntary context switches}
\lineii{15}{involuntary context switches}
\end{tableii}
This function will raise a \exception{ValueError} if an invalid
\var{who} parameter is specified. It may also raise
\exception{error} exception in unusual circumstances.
\end{funcdesc}
\begin{funcdesc}{getpagesize}{}
Returns the number of bytes in a system page. (This need not be the
same as the hardware page size.) This function is useful for
determining the number of bytes of memory a process is using. The
third element of the tuple returned by \function{getrusage()} describes
memory usage in pages; multiplying by page size produces number of
bytes.
\end{funcdesc}
The following \code{RUSAGE_*} symbols are passed to the
\function{getrusage()} function to specify which processes information
should be provided for.
\begin{datadesc}{RUSAGE_SELF}
\constant{RUSAGE_SELF} should be used to
request information pertaining only to the process itself.
\end{datadesc}
\begin{datadesc}{RUSAGE_CHILDREN}
Pass to \function{getrusage()} to request resource information for
child processes of the calling process.
\end{datadesc}
\begin{datadesc}{RUSAGE_BOTH}
Pass to \function{getrusage()} to request resources consumed by both
the current process and child processes. May not be available on all
systems.
\end{datadesc}

79
Doc/librestricted.tex
View File

@ -1,79 +0,0 @@
\chapter{Restricted Execution}
\label{restricted}
In general, Python programs have complete access to the underlying
operating system throug the various functions and classes, For
example, a Python program can open any file for reading and writing by
using the \code{open()} built-in function (provided the underlying OS
gives you permission!). This is exactly what you want for most
applications.
There exists a class of applications for which this ``openness'' is
inappropriate. Take Grail: a web browser that accepts ``applets'',
snippets of Python code, from anywhere on the Internet for execution
on the local system. This can be used to improve the user interface
of forms, for instance. Since the originator of the code is unknown,
it is obvious that it cannot be trusted with the full resources of the
local machine.
\emph{Restricted execution} is the basic framework in Python that allows
for the segregation of trusted and untrusted code. It is based on the
notion that trusted Python code (a \emph{supervisor}) can create a
``padded cell' (or environment) with limited permissions, and run the
untrusted code within this cell. The untrusted code cannot break out
of its cell, and can only interact with sensitive system resources
through interfaces defined and managed by the trusted code. The term
``restricted execution'' is favored over ``safe-Python''
since true safety is hard to define, and is determined by the way the
restricted environment is created. Note that the restricted
environments can be nested, with inner cells creating subcells of
lesser, but never greater, privilege.
An interesting aspect of Python's restricted execution model is that
the interfaces presented to untrusted code usually have the same names
as those presented to trusted code. Therefore no special interfaces
need to be learned to write code designed to run in a restricted
environment. And because the exact nature of the padded cell is
determined by the supervisor, different restrictions can be imposed,
depending on the application. For example, it might be deemed
``safe'' for untrusted code to read any file within a specified
directory, but never to write a file. In this case, the supervisor
may redefine the built-in
\code{open()} function so that it raises an exception whenever the
\var{mode} parameter is \code{'w'}. It might also perform a
\code{chroot()}-like operation on the \var{filename} parameter, such
that root is always relative to some safe ``sandbox'' area of the
filesystem. In this case, the untrusted code would still see an
built-in \code{open()} function in its environment, with the same
calling interface. The semantics would be identical too, with
\code{IOError}s being raised when the supervisor determined that an
unallowable parameter is being used.
The Python run-time determines whether a particular code block is
executing in restricted execution mode based on the identity of the
\code{__builtins__} object in its global variables: if this is (the
dictionary of) the standard \code{__builtin__} module, the code is
deemed to be unrestricted, else it is deemed to be restricted.
Python code executing in restricted mode faces a number of limitations
that are designed to prevent it from escaping from the padded cell.
For instance, the function object attribute \code{func_globals} and the
class and instance object attribute \code{__dict__} are unavailable.
Two modules provide the framework for setting up restricted execution
environments:
\begin{description}
\item[rexec]
--- Basic restricted execution framework.
\item[Bastion]
--- Providing restricted access to objects.
\end{description}
\begin{seealso}
\seetext{Andrew Kuchling, ``Restricted Execution HOWTO.'' Available
online at \url{http://www.python.org/doc/howto/rexec/}.}
\end{seealso}

221
Doc/librexec.tex
View File

@ -1,221 +0,0 @@
\section{Standard Module \module{rexec}}
\label{module-rexec}
\stmodindex{rexec}
This module contains the \class{RExec} class, which supports
\method{r_exec()}, \method{r_eval()}, \method{r_execfile()}, and
\method{r_import()} methods, which are restricted versions of the standard
Python functions \method{exec()}, \method{eval()}, \method{execfile()}, and
the \keyword{import} statement.
Code executed in this restricted environment will
only have access to modules and functions that are deemed safe; you
can subclass \class{RExec} to add or remove capabilities as desired.
\emph{Note:} The \class{RExec} class can prevent code from performing
unsafe operations like reading or writing disk files, or using TCP/IP
sockets. However, it does not protect against code using extremely
large amounts of memory or CPU time.
\begin{classdesc}{RExec}{\optional{hooks\optional{, verbose}}}
Returns an instance of the \class{RExec} class.
\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
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,
the \class{RExec} object doesn't make these calls --- they are made by
a module loader object that's part of the \class{RExec} object. This
allows another level of flexibility, e.g. using packages.)
By providing an alternate \class{RHooks} object, we can control the
file system accesses made to import a module, without changing the
actual algorithm that controls the order in which those accesses are
made. For instance, we could substitute an \class{RHooks} object that
passes all filesystem requests to a file server elsewhere, via some
RPC mechanism such as ILU. Grail's applet loader uses this to support
importing applets from a URL for a directory.
If \var{verbose} is true, additional debugging output may be sent to
standard output.
\end{classdesc}
The \class{RExec} class has the following class attributes, which are
used by the \method{__init__()} method. Changing them on an existing
instance won't have any effect; instead, create a subclass of
\class{RExec} and assign them new values in the class definition.
Instances of the new class will then use those new values. All these
attributes are tuples of strings.
\begin{memberdesc}{nok_builtin_names}
Contains the names of built-in functions which will \emph{not} be
available to programs running in the restricted environment. The
value for \class{RExec} is \code{('open',} \code{'reload',}
\code{'__import__')}. (This gives the exceptions, because by far the
majority of built-in functions are harmless. A subclass that wants to
override this variable should probably start with the value from the
base class and concatenate additional forbidden functions --- when new
dangerous built-in functions are added to Python, they will also be
added to this module.)
\end{memberdesc}
\begin{memberdesc}{ok_builtin_modules}
Contains the names of built-in modules which can be safely imported.
The value for \class{RExec} is \code{('audioop',} \code{'array',}
\code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',}
\code{'marshal',} \code{'math',} \code{'md5',} \code{'operator',}
\code{'parser',} \code{'regex',} \code{'rotor',} \code{'select',}
\code{'strop',} \code{'struct',} \code{'time')}. A similar remark
about overriding this variable applies --- use the value from the base
class as a starting point.
\end{memberdesc}
\begin{memberdesc}{ok_path}
Contains the directories which will be searched when an \keyword{import}
is performed in the restricted environment.
The value for \class{RExec} is the same as \code{sys.path} (at the time
the module is loaded) for unrestricted code.
\end{memberdesc}
\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
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',}
\code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',}
\code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',}
\code{'getegid')}.
\end{memberdesc}
\begin{memberdesc}{ok_sys_names}
Contains the names of the functions and variables in the \module{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',}
\code{'exit',} \code{'maxint')}.
\end{memberdesc}
\class{RExec} instances support the following methods:
\begin{methoddesc}{r_eval}{code}
\var{code} must either be a string containing a Python expression, or
a compiled code object, which will be evaluated in the restricted
environment's \module{__main__} module. The value of the expression or
code object will be returned.
\end{methoddesc}
\begin{methoddesc}{r_exec}{code}
\var{code} must either be a string containing one or more lines of
Python code, or a compiled code object, which will be executed in the
restricted environment's \module{__main__} module.
\end{methoddesc}
\begin{methoddesc}{r_execfile}{filename}
Execute the Python code contained in the file \var{filename} in the
restricted environment's \module{__main__} module.
\end{methoddesc}
Methods whose names begin with \samp{s_} are similar to the functions
beginning with \samp{r_}, but the code will be granted access to
restricted versions of the standard I/O streams \code{sys.stdin},
\code{sys.stderr}, and \code{sys.stdout}.
\begin{methoddesc}{s_eval}{code}
\var{code} must be a string containing a Python expression, which will
be evaluated in the restricted environment.
\end{methoddesc}
\begin{methoddesc}{s_exec}{code}
\var{code} must be a string containing one or more lines of Python code,
which will be executed in the restricted environment.
\end{methoddesc}
\begin{methoddesc}{s_execfile}{code}
Execute the Python code contained in the file \var{filename} in the
restricted environment.
\end{methoddesc}
\class{RExec} objects must also support various methods which will be
implicitly called by code executing in the restricted environment.
Overriding these methods in a subclass is used to change the policies
enforced by a restricted environment.
\begin{methoddesc}{r_import}{modulename\optional{, globals\optional{,
locals\optional{, fromlist}}}}
Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe.
\end{methoddesc}
\begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
Method called when \function{open()} is called in the restricted
environment. The arguments are identical to those of \function{open()},
and a file object (or a class instance compatible with file objects)
should be returned. \class{RExec}'s default behaviour is allow opening
any file for reading, but forbidding any attempt to write a file. See
the example below for an implementation of a less restrictive
\method{r_open()}.
\end{methoddesc}
\begin{methoddesc}{r_reload}{module}
Reload the module object \var{module}, re-parsing and re-initializing it.
\end{methoddesc}
\begin{methoddesc}{r_unload}{module}
Unload the module object \var{module} (i.e., remove it from the
restricted environment's \code{sys.modules} dictionary).
\end{methoddesc}
And their equivalents with access to restricted standard I/O streams:
\begin{methoddesc}{s_import}{modulename\optional{, globals\optional{,
locals\optional{, fromlist}}}}
Import the module \var{modulename}, raising an \exception{ImportError}
exception if the module is considered unsafe.
\end{methoddesc}
\begin{methoddesc}{s_reload}{module}
Reload the module object \var{module}, re-parsing and re-initializing it.
\end{methoddesc}
\begin{methoddesc}{s_unload}{module}
Unload the module object \var{module}.
% XXX what are the semantics of this?
\end{methoddesc}
\subsection{An example}
Let us say that we want a slightly more relaxed policy than the
standard \class{RExec} class. For example, if we're willing to allow
files in \file{/tmp} to be written, we can subclass the \class{RExec}
class:
\begin{verbatim}
class TmpWriterRExec(rexec.RExec):
def r_open(self, file, mode='r', buf=-1):
if mode in ('r', 'rb'):
pass
elif mode in ('w', 'wb', 'a', 'ab'):
# check filename : must begin with /tmp/
if file[:5]!='/tmp/':
raise IOError, "can't write outside /tmp"
elif (string.find(file, '/../') >= 0 or
file[:3] == '../' or file[-3:] == '/..'):
raise IOError, "'..' in filename forbidden"
else: raise IOError, "Illegal open() mode"
return open(file, mode, buf)
\end{verbatim}
%
Notice that the above code will occasionally forbid a perfectly valid
filename; for example, code in the restricted environment won't be
able to open a file called \file{/tmp/foo/../bar}. To fix this, the
\method{r_open()} method would have to simplify the filename to
\file{/tmp/bar}, which would require splitting apart the filename and
performing various operations on it. In cases where security is at
stake, it may be preferable to write simple code which is sometimes
overly restrictive, instead of more general code that is also more
complex and may harbor a subtle security hole.

165
Doc/librfc822.tex
View File

@ -1,165 +0,0 @@
\section{Standard Module \module{rfc822}}
\label{module-rfc822}
\stmodindex{rfc822}
This module defines a class, \class{Message}, which represents a
collection of ``email headers'' as defined by the Internet standard
\rfc{822}. It is used in various contexts, usually to read such
headers from a file.
Note that there's a separate module to read \UNIX{}, MH, and MMDF
style mailbox files: \module{mailbox}\refstmodindex{mailbox}.
\begin{classdesc}{Message}{file\optional{, seekable}}
A \class{Message} instance is instantiated with an open file object as
parameter. The optional \var{seekable} parameter indicates if the
file object is seekable; the default value is \code{1} for true.
Instantiation reads headers from the file up to a blank line and
stores them in the instance; after instantiation, the file is
positioned directly after the blank line that terminates the headers.
Input lines as read from the file may either be terminated by CR-LF or
by a single linefeed; a terminating CR-LF is replaced by a single
linefeed before the line is stored.
All header matching is done independent of upper or lower case;
e.g. \code{\var{m}['From']}, \code{\var{m}['from']} and
\code{\var{m}['FROM']} all yield the same result.
\end{classdesc}
\begin{funcdesc}{parsedate}{date}
Attempts to parse a date according to the rules in \rfc{822}.
however, some mailers don't follow that format as specified, so
\function{parsedate()} tries to guess correctly in such cases.
\var{date} is a string containing an \rfc{822} date, such as
\code{'Mon, 20 Nov 1995 19:12:08 -0500'}. If it succeeds in parsing
the date, \function{parsedate()} returns a 9-tuple that can be passed
directly to \function{time.mktime()}; otherwise \code{None} will be
returned.
\end{funcdesc}
\begin{funcdesc}{parsedate_tz}{date}
Performs the same function as \function{parsedate()}, but returns
either \code{None} or a 10-tuple; the first 9 elements make up a tuple
that can be passed directly to \function{time.mktime()}, and the tenth
is the offset of the date's timezone from UTC (which is the official
term for Greenwich Mean Time). (Note that the sign of the timezone
offset is the opposite of the sign of the \code{time.timezone}
variable for the same timezone; the latter variable follows the
\POSIX{} standard while this module follows \rfc{822}.) If the input
string has no timezone, the last element of the tuple returned is
\code{None}.
\end{funcdesc}
\begin{funcdesc}{mktime_tz}{tuple}
Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC
timestamp. It the timezone item in the tuple is \code{None}, assume
local time. Minor deficiency: this first interprets the first 8
elements as a local time and then compensates for the timezone
difference; this may yield a slight error around daylight savings time
switch dates. Not enough to worry about for common use.
\end{funcdesc}
\subsection{Message Objects}
\label{message-objects}
A \class{Message} instance has the following methods:
\begin{methoddesc}{rewindbody}{}
Seek to the start of the message body. This only works if the file
object is seekable.
\end{methoddesc}
\begin{methoddesc}{getallmatchingheaders}{name}
Return a list of lines consisting of all headers matching
\var{name}, if any. Each physical line, whether it is a continuation
line or not, is a separate list item. Return the empty list if no
header matches \var{name}.
\end{methoddesc}
\begin{methoddesc}{getfirstmatchingheader}{name}
Return a list of lines comprising the first header matching
\var{name}, and its continuation line(s), if any. Return \code{None}
if there is no header matching \var{name}.
\end{methoddesc}
\begin{methoddesc}{getrawheader}{name}
Return a single string consisting of the text after the colon in the
first header matching \var{name}. This includes leading whitespace,
the trailing linefeed, and internal linefeeds and whitespace if there
any continuation line(s) were present. Return \code{None} if there is
no header matching \var{name}.
\end{methoddesc}
\begin{methoddesc}{getheader}{name}
Like \code{getrawheader(\var{name})}, but strip leading and trailing
whitespace. Internal whitespace is not stripped.
\end{methoddesc}
\begin{methoddesc}{getaddr}{name}
Return a pair \code{(\var{full name}, \var{email address})} parsed
from the string returned by \code{getheader(\var{name})}. If no
header matching \var{name} exists, return \code{(None, None)};
otherwise both the full name and the address are (possibly empty)
strings.
Example: If \var{m}'s first \code{From} header contains the string
\code{'jack@cwi.nl (Jack Jansen)'}, then
\code{m.getaddr('From')} will yield the pair
\code{('Jack Jansen', 'jack@cwi.nl')}.
If the header contained
\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the
exact same result.
\end{methoddesc}
\begin{methoddesc}{getaddrlist}{name}
This is similar to \code{getaddr(\var{list})}, but parses a header
containing a list of email addresses (e.g. a \code{To} header) and
returns a list of \code{(\var{full name}, \var{email address})} pairs
(even if there was only one address in the header). If there is no
header matching \var{name}, return an empty list.
XXX The current version of this function is not really correct. It
yields bogus results if a full name contains a comma.
\end{methoddesc}
\begin{methoddesc}{getdate}{name}
Retrieve a header using \method{getheader()} and parse it into a 9-tuple
compatible with \function{time.mktime()}. If there is no header matching
\var{name}, or it is unparsable, return \code{None}.
Date parsing appears to be a black art, and not all mailers adhere to
the standard. While it has been tested and found correct on a large
collection of email from many sources, it is still possible that this
function may occasionally yield an incorrect result.
\end{methoddesc}
\begin{methoddesc}{getdate_tz}{name}
Retrieve a header using \method{getheader()} and parse it into a
10-tuple; the first 9 elements will make a tuple compatible with
\function{time.mktime()}, and the 10th is a number giving the offset
of the date's timezone from UTC. Similarly to \method{getdate()}, if
there is no header matching \var{name}, or it is unparsable, return
\code{None}.
\end{methoddesc}
\class{Message} instances also support a read-only mapping interface.
In particular: \code{\var{m}[name]} is like
\code{\var{m}.getheader(name)} but raises \exception{KeyError} if
there is no matching header; and \code{len(\var{m})},
\code{\var{m}.has_key(name)}, \code{\var{m}.keys()},
\code{\var{m}.values()} and \code{\var{m}.items()} act as expected
(and consistently).
Finally, \class{Message} instances have two public instance variables:
\begin{memberdesc}{headers}
A list containing the entire set of header lines, in the order in
which they were read. Each line contains a trailing newline. The
blank line terminating the headers is not contained in the list.
\end{memberdesc}
\begin{memberdesc}{fp}
The file object passed at instantiation time.
\end{memberdesc}

45
Doc/librgbimg.tex
View File

@ -1,45 +0,0 @@
\section{Built-in Module \module{rgbimg}}
\label{module-rgbimg}
\bimodindex{rgbimg}
The \module{rgbimg} module allows Python programs to access SGI imglib image
files (also known as \file{.rgb} files). The module is far from
complete, but is provided anyway since the functionality that there is
enough in some cases. Currently, colormap files are not supported.
The module defines the following variables and functions:
\begin{excdesc}{error}
This exception is raised on all errors, such as unsupported file type, etc.
\end{excdesc}
\begin{funcdesc}{sizeofimage}{file}
This function returns a tuple \code{(\var{x}, \var{y})} where
\var{x} and \var{y} are the size of the image in pixels.
Only 4 byte RGBA pixels, 3 byte RGB pixels, and 1 byte greyscale pixels
are currently supported.
\end{funcdesc}
\begin{funcdesc}{longimagedata}{file}
This function reads and decodes the image on the specified file, and
returns it as a Python string. The string has 4 byte RGBA pixels.
The bottom left pixel is the first in
the string. This format is suitable to pass to \function{gl.lrectwrite()},
for instance.
\end{funcdesc}
\begin{funcdesc}{longstoimage}{data, x, y, z, file}
This function writes the RGBA data in \var{data} to image
file \var{file}. \var{x} and \var{y} give the size of the image.
\var{z} is 1 if the saved image should be 1 byte greyscale, 3 if the
saved image should be 3 byte RGB data, or 4 if the saved images should
be 4 byte RGBA data. The input data always contains 4 bytes per pixel.
These are the formats returned by \function{gl.lrectread()}.
\end{funcdesc}
\begin{funcdesc}{ttob}{flag}
This function sets a global flag which defines whether the scan lines
of the image are read or written from bottom to top (flag is zero,
compatible with SGI GL) or from top to bottom(flag is one,
compatible with X)\@. The default is zero.
\end{funcdesc}

104
Doc/librotor.tex
View File

@ -1,104 +0,0 @@
\section{Built-in Module \module{rotor}}
\label{module-rotor}
\bimodindex{rotor}
This module implements a rotor-based encryption algorithm, contributed by
Lance Ellinghouse\index{Ellinghouse, Lance}. The design is derived
from the Enigma device\indexii{Enigma}{device}, a machine
used during World War II to encipher messages. A rotor is simply a
permutation. For example, if the character `A' is the origin of the rotor,
then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
To encrypt, we choose several different rotors, and set the origins of the
rotors to known positions; their initial position is the ciphering key. To
encipher a character, we permute the original character by the first rotor,
and then apply the second rotor's permutation to the result. We continue
until we've applied all the rotors; the resulting character is our
ciphertext. We then change the origin of the final rotor by one position,
from `A' to `B'; if the final rotor has made a complete revolution, then we
rotate the next-to-last rotor by one position, and apply the same procedure
recursively. In other words, after enciphering one character, we advance
the rotors in the same fashion as a car's odometer. Decoding works in the
same way, except we reverse the permutations and apply them in the opposite
order.
\indexii{Enigma}{cipher}
The available functions in this module are:
\begin{funcdesc}{newrotor}{key\optional{, numrotors}}
Return a rotor object. \var{key} is a string containing the encryption key
for the object; it can contain arbitrary binary data. The key will be used
to randomly generate the rotor permutations and their initial positions.
\var{numrotors} is the number of rotor permutations in the returned object;
if it is omitted, a default value of 6 will be used.
\end{funcdesc}
Rotor objects have the following methods:
\begin{methoddesc}[rotor]{setkey}{key}
Sets the rotor's key to \var{key}.
\end{methoddesc}
\begin{methoddesc}[rotor]{encrypt}{plaintext}
Reset the rotor object to its initial state and encrypt \var{plaintext},
returning a string containing the ciphertext. The ciphertext is always the
same length as the original plaintext.
\end{methoddesc}
\begin{methoddesc}[rotor]{encryptmore}{plaintext}
Encrypt \var{plaintext} without resetting the rotor object, and return a
string containing the ciphertext.
\end{methoddesc}
\begin{methoddesc}[rotor]{decrypt}{ciphertext}
Reset the rotor object to its initial state and decrypt \var{ciphertext},
returning a string containing the ciphertext. The plaintext string will
always be the same length as the ciphertext.
\end{methoddesc}
\begin{methoddesc}[rotor]{decryptmore}{ciphertext}
Decrypt \var{ciphertext} without resetting the rotor object, and return a
string containing the ciphertext.
\end{methoddesc}
An example usage:
\begin{verbatim}
>>> import rotor
>>> rt = rotor.newrotor('key', 12)
>>> rt.encrypt('bar')
'\2534\363'
>>> rt.encryptmore('bar')
'\357\375$'
>>> rt.encrypt('bar')
'\2534\363'
>>> rt.decrypt('\2534\363')
'bar'
>>> rt.decryptmore('\357\375$')
'bar'
>>> rt.decrypt('\357\375$')
'l(\315'
>>> del rt
\end{verbatim}
The module's code is not an exact simulation of the original Enigma
device; it implements the rotor encryption scheme differently from the
original. The most important difference is that in the original
Enigma, there were only 5 or 6 different rotors in existence, and they
were applied twice to each character; the cipher key was the order in
which they were placed in the machine. The Python \module{rotor}
module uses the supplied key to initialize a random number generator;
the rotor permutations and their initial positions are then randomly
generated. The original device only enciphered the letters of the
alphabet, while this module can handle any 8-bit binary data; it also
produces binary output. This module can also operate with an
arbitrary number of rotors.
The original Enigma cipher was broken in 1944. % XXX: Is this right?
The version implemented here is probably a good deal more difficult to crack
(especially if you use many rotors), but it won't be impossible for
a truly skilful and determined attacker to break the cipher. So if you want
to keep the NSA out of your files, this rotor cipher may well be unsafe, but
for discouraging casual snooping through your files, it will probably be
just fine, and may be somewhat safer than using the \UNIX{} \program{crypt}
command.
\index{NSA}
\index{National Security Agency}

46
Doc/libselect.tex
View File

@ -1,46 +0,0 @@
\section{Built-in Module \module{select}}
\label{module-select}
\bimodindex{select}
This module provides access to the function \cfunction{select()}
available in most \UNIX{} versions. It defines the following:
\begin{excdesc}{error}
The exception raised when an error occurs. The accompanying value is
a pair containing the numeric error code from \cdata{errno} and the
corresponding string, as would be printed by the \C{} function
\cfunction{perror()}.
\end{excdesc}
\begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}}
This is a straightforward interface to the \UNIX{} \cfunction{select()}
system call. The first three arguments are lists of `waitable
objects': either integers representing \UNIX{} file descriptors or
objects with a parameterless method named \method{fileno()} returning
such an integer. The three lists of waitable objects are for input,
output and `exceptional conditions', respectively. Empty lists are
allowed. The optional \var{timeout} argument specifies a time-out as a
floating point number in seconds. When the \var{timeout} argument
is omitted the function blocks until at least one file descriptor is
ready. A time-out value of zero specifies a poll and never blocks.
The return value is a triple of lists of objects that are ready:
subsets of the first three arguments. When the time-out is reached
without a file descriptor becoming ready, three empty lists are
returned.
Amongst the acceptable object types in the lists are Python file
objects (e.g. \code{sys.stdin}, or objects returned by
\function{open()} or \function{os.popen()}), socket objects
returned by \function{socket.socket()},%
\withsubitem{(in module socket)}{\ttindex{socket()}}
\withsubitem{(in module posix)}{\ttindex{popen()}}
\withsubitem{(in module os)}{\ttindex{popen()}}
and the module \module{stdwin}\refbimodindex{stdwin} which happens to
define a function \function{fileno()}%
\withsubitem{(in module stdwin)}{\ttindex{fileno()}}
for just this purpose. You may
also define a \dfn{wrapper} class yourself, as long as it has an
appropriate \method{fileno()} method (that really returns a \UNIX{}
file descriptor, not just a random integer).
\end{funcdesc}

Some files were not shown because too many files have changed in this diff Show More