diff options
Diffstat (limited to 'Doc')
142 files changed, 0 insertions, 21211 deletions
diff --git a/Doc/lib.tex b/Doc/lib.tex deleted file mode 100644 index 5ee098e..0000000 --- a/Doc/lib.tex +++ /dev/null @@ -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} diff --git a/Doc/libaifc.tex b/Doc/libaifc.tex deleted file mode 100644 index f86b1d8..0000000 --- a/Doc/libaifc.tex +++ /dev/null @@ -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} diff --git a/Doc/libal.tex b/Doc/libal.tex deleted file mode 100644 index ed675a9..0000000 --- a/Doc/libal.tex +++ /dev/null @@ -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} diff --git a/Doc/liballos.tex b/Doc/liballos.tex deleted file mode 100644 index fca7567..0000000 --- a/Doc/liballos.tex +++ /dev/null @@ -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} diff --git a/Doc/libamoeba.tex b/Doc/libamoeba.tex deleted file mode 100644 index 0d3df2b..0000000 --- a/Doc/libamoeba.tex +++ /dev/null @@ -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} diff --git a/Doc/libanydbm.tex b/Doc/libanydbm.tex deleted file mode 100644 index bba7714..0000000 --- a/Doc/libanydbm.tex +++ /dev/null @@ -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} diff --git a/Doc/libarray.tex b/Doc/libarray.tex deleted file mode 100644 index 180be34..0000000 --- a/Doc/libarray.tex +++ /dev/null @@ -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} diff --git a/Doc/libaudioop.tex b/Doc/libaudioop.tex deleted file mode 100644 index ff76e72..0000000 --- a/Doc/libaudioop.tex +++ /dev/null @@ -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} diff --git a/Doc/libbase64.tex b/Doc/libbase64.tex deleted file mode 100644 index dca25d0..0000000 --- a/Doc/libbase64.tex +++ /dev/null @@ -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} diff --git a/Doc/libbasehttp.tex b/Doc/libbasehttp.tex deleted file mode 100644 index 7ee55df..0000000 --- a/Doc/libbasehttp.tex +++ /dev/null @@ -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} diff --git a/Doc/libbastion.tex b/Doc/libbastion.tex deleted file mode 100644 index ddf6d9e..0000000 --- a/Doc/libbastion.tex +++ /dev/null @@ -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} diff --git a/Doc/libbinascii.tex b/Doc/libbinascii.tex deleted file mode 100644 index 77366ed..0000000 --- a/Doc/libbinascii.tex +++ /dev/null @@ -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} diff --git a/Doc/libbinhex.tex b/Doc/libbinhex.tex deleted file mode 100644 index 6a7d3c6..0000000 --- a/Doc/libbinhex.tex +++ /dev/null @@ -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. diff --git a/Doc/libbisect.tex b/Doc/libbisect.tex deleted file mode 100644 index 81cb550..0000000 --- a/Doc/libbisect.tex +++ /dev/null @@ -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} diff --git a/Doc/libbltin.tex b/Doc/libbltin.tex deleted file mode 100644 index a4a0dd0..0000000 --- a/Doc/libbltin.tex +++ /dev/null @@ -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.'' diff --git a/Doc/libcalendar.tex b/Doc/libcalendar.tex deleted file mode 100644 index 1f3931e..0000000 --- a/Doc/libcalendar.tex +++ /dev/null @@ -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} diff --git a/Doc/libcd.tex b/Doc/libcd.tex deleted file mode 100644 index 44111a3..0000000 --- a/Doc/libcd.tex +++ /dev/null @@ -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} diff --git a/Doc/libcgi.tex b/Doc/libcgi.tex deleted file mode 100644 index cb0a6fb..0000000 --- a/Doc/libcgi.tex +++ /dev/null @@ -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} - diff --git a/Doc/libcmath.tex b/Doc/libcmath.tex deleted file mode 100644 index adce12f..0000000 --- a/Doc/libcmath.tex +++ /dev/null @@ -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). diff --git a/Doc/libcode.tex b/Doc/libcode.tex deleted file mode 100644 index 023d276..0000000 --- a/Doc/libcode.tex +++ /dev/null @@ -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} diff --git a/Doc/libcommands.tex b/Doc/libcommands.tex deleted file mode 100644 index 7ca3ede..0000000 --- a/Doc/libcommands.tex +++ /dev/null @@ -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} diff --git a/Doc/libcopy.tex b/Doc/libcopy.tex deleted file mode 100644 index 4e43585..0000000 --- a/Doc/libcopy.tex +++ /dev/null @@ -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__} diff --git a/Doc/libcopyreg.tex b/Doc/libcopyreg.tex deleted file mode 100644 index 7dabf42..0000000 --- a/Doc/libcopyreg.tex +++ /dev/null @@ -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} diff --git a/Doc/libcrypt.tex b/Doc/libcrypt.tex deleted file mode 100644 index 8e9a7d3..0000000 --- a/Doc/libcrypt.tex +++ /dev/null @@ -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} diff --git a/Doc/libcrypto.tex b/Doc/libcrypto.tex deleted file mode 100644 index 8ea33a2..0000000 --- a/Doc/libcrypto.tex +++ /dev/null @@ -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} diff --git a/Doc/libdbm.tex b/Doc/libdbm.tex deleted file mode 100644 index c4317fe..0000000 --- a/Doc/libdbm.tex +++ /dev/null @@ -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} diff --git a/Doc/libdis.tex b/Doc/libdis.tex deleted file mode 100644 index eb60150..0000000 --- a/Doc/libdis.tex +++ /dev/null @@ -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} diff --git a/Doc/liberrno.tex b/Doc/liberrno.tex deleted file mode 100644 index 40ab90d..0000000 --- a/Doc/liberrno.tex +++ /dev/null @@ -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} - diff --git a/Doc/libexcs.tex b/Doc/libexcs.tex deleted file mode 100644 index 7d2d85f..0000000 --- a/Doc/libexcs.tex +++ /dev/null @@ -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} diff --git a/Doc/libfcntl.tex b/Doc/libfcntl.tex deleted file mode 100644 index 1c64af9..0000000 --- a/Doc/libfcntl.tex +++ /dev/null @@ -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. diff --git a/Doc/libfileinput.tex b/Doc/libfileinput.tex deleted file mode 100644 index 0c0e81b..0000000 --- a/Doc/libfileinput.tex +++ /dev/null @@ -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. diff --git a/Doc/libfl.tex b/Doc/libfl.tex deleted file mode 100644 index 7ebec7d..0000000 --- a/Doc/libfl.tex +++ /dev/null @@ -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! diff --git a/Doc/libfm.tex b/Doc/libfm.tex deleted file mode 100644 index abcbaa4..0000000 --- a/Doc/libfm.tex +++ /dev/null @@ -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} diff --git a/Doc/libfnmatch.tex b/Doc/libfnmatch.tex deleted file mode 100644 index f2f82ba..0000000 --- a/Doc/libfnmatch.tex +++ /dev/null @@ -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} diff --git a/Doc/libformatter.tex b/Doc/libformatter.tex deleted file mode 100644 index 6a97f80..0000000 --- a/Doc/libformatter.tex +++ /dev/null @@ -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} diff --git a/Doc/libframework.tex b/Doc/libframework.tex deleted file mode 100644 index 5bd2e2a..0000000 --- a/Doc/libframework.tex +++ /dev/null @@ -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} diff --git a/Doc/libftplib.tex b/Doc/libftplib.tex deleted file mode 100644 index 8ba2c61..0000000 --- a/Doc/libftplib.tex +++ /dev/null @@ -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} diff --git a/Doc/libfuncs.tex b/Doc/libfuncs.tex deleted file mode 100644 index 1345734..0000000 --- a/Doc/libfuncs.tex +++ /dev/null @@ -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} diff --git a/Doc/libgdbm.tex b/Doc/libgdbm.tex deleted file mode 100644 index 8f2d7d1..0000000 --- a/Doc/libgdbm.tex +++ /dev/null @@ -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} - diff --git a/Doc/libgetopt.tex b/Doc/libgetopt.tex deleted file mode 100644 index be00fef..0000000 --- a/Doc/libgetopt.tex +++ /dev/null @@ -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} diff --git a/Doc/libgl.tex b/Doc/libgl.tex deleted file mode 100644 index abbaf10..0000000 --- a/Doc/libgl.tex +++ /dev/null @@ -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. diff --git a/Doc/libglob.tex b/Doc/libglob.tex deleted file mode 100644 index 10f667a..0000000 --- a/Doc/libglob.tex +++ /dev/null @@ -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} diff --git a/Doc/libgopherlib.tex b/Doc/libgopherlib.tex deleted file mode 100644 index 156d6d7..0000000 --- a/Doc/libgopherlib.tex +++ /dev/null @@ -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. diff --git a/Doc/libgrp.tex b/Doc/libgrp.tex deleted file mode 100644 index 551171b..0000000 --- a/Doc/libgrp.tex +++ /dev/null @@ -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} diff --git a/Doc/libgzip.tex b/Doc/libgzip.tex deleted file mode 100644 index fd2bc28..0000000 --- a/Doc/libgzip.tex +++ /dev/null @@ -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} - diff --git a/Doc/libhtmllib.tex b/Doc/libhtmllib.tex deleted file mode 100644 index c856b42..0000000 --- a/Doc/libhtmllib.tex +++ /dev/null @@ -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} diff --git a/Doc/libhttplib.tex b/Doc/libhttplib.tex deleted file mode 100644 index 55ec9b98..0000000 --- a/Doc/libhttplib.tex +++ /dev/null @@ -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} diff --git a/Doc/libimageop.tex b/Doc/libimageop.tex deleted file mode 100644 index c21be48..0000000 --- a/Doc/libimageop.tex +++ /dev/null @@ -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} diff --git a/Doc/libimaplib.tex b/Doc/libimaplib.tex deleted file mode 100644 index fa3ec68..0000000 --- a/Doc/libimaplib.tex +++ /dev/null @@ -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} diff --git a/Doc/libimgfile.tex b/Doc/libimgfile.tex deleted file mode 100644 index e74fe9e..0000000 --- a/Doc/libimgfile.tex +++ /dev/null @@ -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} diff --git a/Doc/libimghdr.tex b/Doc/libimghdr.tex deleted file mode 100644 index 2f21a25..0000000 --- a/Doc/libimghdr.tex +++ /dev/null @@ -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} diff --git a/Doc/libimp.tex b/Doc/libimp.tex deleted file mode 100644 index 7d4f8d1..0000000 --- a/Doc/libimp.tex +++ /dev/null @@ -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). diff --git a/Doc/libintro.tex b/Doc/libintro.tex deleted file mode 100644 index cc0fd86..0000000 --- a/Doc/libintro.tex +++ /dev/null @@ -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! diff --git a/Doc/libjpeg.tex b/Doc/libjpeg.tex deleted file mode 100644 index 76e70af..0000000 --- a/Doc/libjpeg.tex +++ /dev/null @@ -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} diff --git a/Doc/libkeyword.tex b/Doc/libkeyword.tex deleted file mode 100644 index 7a263ef..0000000 --- a/Doc/libkeyword.tex +++ /dev/null @@ -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} diff --git a/Doc/liblocale.tex b/Doc/liblocale.tex deleted file mode 100644 index 07361b8..0000000 --- a/Doc/liblocale.tex +++ /dev/null @@ -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. diff --git a/Doc/libmailbox.tex b/Doc/libmailbox.tex deleted file mode 100644 index 4ff2dedb..0000000 --- a/Doc/libmailbox.tex +++ /dev/null @@ -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} diff --git a/Doc/libmailcap.tex b/Doc/libmailcap.tex deleted file mode 100644 index 0ea762a..0000000 --- a/Doc/libmailcap.tex +++ /dev/null @@ -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} diff --git a/Doc/libmain.tex b/Doc/libmain.tex deleted file mode 100644 index df1fbfb..0000000 --- a/Doc/libmain.tex +++ /dev/null @@ -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. diff --git a/Doc/libmarshal.tex b/Doc/libmarshal.tex deleted file mode 100644 index 5878cfa..0000000 --- a/Doc/libmarshal.tex +++ /dev/null @@ -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} diff --git a/Doc/libmath.tex b/Doc/libmath.tex deleted file mode 100644 index 1cc6b20..0000000 --- a/Doc/libmath.tex +++ /dev/null @@ -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} diff --git a/Doc/libmd5.tex b/Doc/libmd5.tex deleted file mode 100644 index d1e7367..0000000 --- a/Doc/libmd5.tex +++ /dev/null @@ -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} diff --git a/Doc/libmimetools.tex b/Doc/libmimetools.tex deleted file mode 100644 index 54d1fe0..0000000 --- a/Doc/libmimetools.tex +++ /dev/null @@ -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} diff --git a/Doc/libmimify.tex b/Doc/libmimify.tex deleted file mode 100644 index 366e940..0000000 --- a/Doc/libmimify.tex +++ /dev/null @@ -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. - diff --git a/Doc/libminiae.tex b/Doc/libminiae.tex deleted file mode 100644 index a1cd6f4..0000000 --- a/Doc/libminiae.tex +++ /dev/null @@ -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. diff --git a/Doc/libmisc.tex b/Doc/libmisc.tex deleted file mode 100644 index 24881a8..0000000 --- a/Doc/libmisc.tex +++ /dev/null @@ -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} diff --git a/Doc/libmm.tex b/Doc/libmm.tex deleted file mode 100644 index 8660909..0000000 --- a/Doc/libmm.tex +++ /dev/null @@ -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} diff --git a/Doc/libmpz.tex b/Doc/libmpz.tex deleted file mode 100644 index 707a3a8..0000000 --- a/Doc/libmpz.tex +++ /dev/null @@ -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} diff --git a/Doc/libni.tex b/Doc/libni.tex deleted file mode 100644 index 14ff395..0000000 --- a/Doc/libni.tex +++ /dev/null @@ -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}. diff --git a/Doc/libnntplib.tex b/Doc/libnntplib.tex deleted file mode 100644 index ba1d788..0000000 --- a/Doc/libnntplib.tex +++ /dev/null @@ -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} diff --git a/Doc/libobjs.tex b/Doc/libobjs.tex deleted file mode 100644 index 8668eff..0000000 --- a/Doc/libobjs.tex +++ /dev/null @@ -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. diff --git a/Doc/liboperator.tex b/Doc/liboperator.tex deleted file mode 100644 index 2169ea8..0000000 --- a/Doc/liboperator.tex +++ /dev/null @@ -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} diff --git a/Doc/libos.tex b/Doc/libos.tex deleted file mode 100644 index 810e40c..0000000 --- a/Doc/libos.tex +++ /dev/null @@ -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.) diff --git a/Doc/libpanel.tex b/Doc/libpanel.tex deleted file mode 100644 index 3553808..0000000 --- a/Doc/libpanel.tex +++ /dev/null @@ -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. diff --git a/Doc/libparser.tex b/Doc/libparser.tex deleted file mode 100644 index 6759a9f..0000000 --- a/Doc/libparser.tex +++ /dev/null @@ -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} diff --git a/Doc/libpdb.tex b/Doc/libpdb.tex deleted file mode 100644 index 50a841e..0000000 --- a/Doc/libpdb.tex +++ /dev/null @@ -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}. diff --git a/Doc/libpickle.tex b/Doc/libpickle.tex deleted file mode 100644 index edd496f..0000000 --- a/Doc/libpickle.tex +++ /dev/null @@ -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. diff --git a/Doc/libpopen2.tex b/Doc/libpopen2.tex deleted file mode 100644 index 9e8a0ca..0000000 --- a/Doc/libpopen2.tex +++ /dev/null @@ -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} diff --git a/Doc/libpoplib.tex b/Doc/libpoplib.tex deleted file mode 100644 index 12882e9..0000000 --- a/Doc/libpoplib.tex +++ /dev/null @@ -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. diff --git a/Doc/libposix.tex b/Doc/libposix.tex deleted file mode 100644 index bccc283..0000000 --- a/Doc/libposix.tex +++ /dev/null @@ -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} diff --git a/Doc/libposixfile.tex b/Doc/libposixfile.tex deleted file mode 100644 index a1f853d..0000000 --- a/Doc/libposixfile.tex +++ /dev/null @@ -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} diff --git a/Doc/libppath.tex b/Doc/libppath.tex deleted file mode 100644 index 86b5a34..0000000 --- a/Doc/libppath.tex +++ /dev/null @@ -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} diff --git a/Doc/libpprint.tex b/Doc/libpprint.tex deleted file mode 100644 index 0ad1dc5..0000000 --- a/Doc/libpprint.tex +++ /dev/null @@ -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} diff --git a/Doc/libprofile.tex b/Doc/libprofile.tex deleted file mode 100644 index 61da988..0000000 --- a/Doc/libprofile.tex +++ /dev/null @@ -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} diff --git a/Doc/libpwd.tex b/Doc/libpwd.tex deleted file mode 100644 index 5275acd..0000000 --- a/Doc/libpwd.tex +++ /dev/null @@ -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} diff --git a/Doc/libpython.tex b/Doc/libpython.tex deleted file mode 100644 index 944f80f..0000000 --- a/Doc/libpython.tex +++ /dev/null @@ -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} diff --git a/Doc/libqueue.tex b/Doc/libqueue.tex deleted file mode 100644 index 680238d..0000000 --- a/Doc/libqueue.tex +++ /dev/null @@ -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} diff --git a/Doc/libquopri.tex b/Doc/libquopri.tex deleted file mode 100644 index abe07df..0000000 --- a/Doc/libquopri.tex +++ /dev/null @@ -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} - - - diff --git a/Doc/librand.tex b/Doc/librand.tex deleted file mode 100644 index a48ea22..0000000 --- a/Doc/librand.tex +++ /dev/null @@ -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} - diff --git a/Doc/librandom.tex b/Doc/librandom.tex deleted file mode 100644 index b76822e..0000000 --- a/Doc/librandom.tex +++ /dev/null @@ -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} diff --git a/Doc/libre.tex b/Doc/libre.tex deleted file mode 100644 index a47723f..0000000 --- a/Doc/libre.tex +++ /dev/null @@ -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} - diff --git a/Doc/libregex.tex b/Doc/libregex.tex deleted file mode 100644 index fabc182..0000000 --- a/Doc/libregex.tex +++ /dev/null @@ -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} diff --git a/Doc/libregsub.tex b/Doc/libregsub.tex deleted file mode 100644 index c390a49..0000000 --- a/Doc/libregsub.tex +++ /dev/null @@ -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} diff --git a/Doc/libresource.tex b/Doc/libresource.tex deleted file mode 100644 index bb0bff2..0000000 --- a/Doc/libresource.tex +++ /dev/null @@ -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} diff --git a/Doc/librestricted.tex b/Doc/librestricted.tex deleted file mode 100644 index f78d7bb..0000000 --- a/Doc/librestricted.tex +++ /dev/null @@ -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} diff --git a/Doc/librexec.tex b/Doc/librexec.tex deleted file mode 100644 index baddece..0000000 --- a/Doc/librexec.tex +++ /dev/null @@ -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. diff --git a/Doc/librfc822.tex b/Doc/librfc822.tex deleted file mode 100644 index 945aef2..0000000 --- a/Doc/librfc822.tex +++ /dev/null @@ -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} diff --git a/Doc/librgbimg.tex b/Doc/librgbimg.tex deleted file mode 100644 index 73e4aae..0000000 --- a/Doc/librgbimg.tex +++ /dev/null @@ -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} diff --git a/Doc/librotor.tex b/Doc/librotor.tex deleted file mode 100644 index 63dc56e..0000000 --- a/Doc/librotor.tex +++ /dev/null @@ -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} diff --git a/Doc/libselect.tex b/Doc/libselect.tex deleted file mode 100644 index b7a8c85..0000000 --- a/Doc/libselect.tex +++ /dev/null @@ -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} diff --git a/Doc/libsgi.tex b/Doc/libsgi.tex deleted file mode 100644 index b1bb5cb..0000000 --- a/Doc/libsgi.tex +++ /dev/null @@ -1,5 +0,0 @@ -\chapter{SGI IRIX Specific Services} -\label{sgi} - -The modules described in this chapter provide interfaces to features -that are unique to SGI's IRIX operating system (versions 4 and 5). diff --git a/Doc/libsgmllib.tex b/Doc/libsgmllib.tex deleted file mode 100644 index f086b4b..0000000 --- a/Doc/libsgmllib.tex +++ /dev/null @@ -1,198 +0,0 @@ -\section{Standard Module \module{sgmllib}} -\label{module-sgmllib} -\stmodindex{sgmllib} -\index{SGML} - -This module defines a class \class{SGMLParser} which serves as the -basis for parsing text files formatted in SGML (Standard Generalized -Mark-up Language). In fact, it does not provide a full SGML parser ---- it only parses SGML insofar as it is used by HTML, and the module -only exists as a base for the \module{htmllib}\refstmodindex{htmllib} -module. - - -\begin{classdesc}{SGMLParser}{} -The \class{SGMLParser} class is instantiated without arguments. -The parser is hardcoded to recognize the following -constructs: - -\begin{itemize} -\item -Opening and closing tags of the form -\samp{<\var{tag} \var{attr}="\var{value}" ...>} and -\samp{</\var{tag}>}, respectively. - -\item -Numeric character references of the form \samp{\&\#\var{name};}. - -\item -Entity references of the form \samp{\&\var{name};}. - -\item -SGML comments of the form \samp{<!--\var{text}-->}. Note that -spaces, tabs, and newlines are allowed between the trailing -\samp{>} and the immediately preceeding \samp{--}. - -\end{itemize} -\end{classdesc} - -\class{SGMLParser} instances have the following interface methods: - - -\begin{methoddesc}{reset}{} -Reset the instance. Loses all unprocessed data. This is called -implicitly at instantiation time. -\end{methoddesc} - -\begin{methoddesc}{setnomoretags}{} -Stop processing tags. Treat all following input as literal input -(CDATA). (This is only provided so the HTML tag \code{<PLAINTEXT>} -can be implemented.) -\end{methoddesc} - -\begin{methoddesc}{setliteral}{} -Enter literal mode (CDATA mode). -\end{methoddesc} - -\begin{methoddesc}{feed}{data} -Feed some text to the parser. It is processed insofar as it consists -of complete elements; incomplete data is buffered until more data is -fed or \method{close()} is called. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Force processing of all buffered data as if it were followed by an -end-of-file mark. This method may be redefined by a derived class to -define additional processing at the end of the input, but the -redefined version should always call \method{close()}. -\end{methoddesc} - -\begin{methoddesc}{handle_starttag}{tag, method, attributes} -This method is called to handle start tags for which either a -\code{start_\var{tag}()} or \code{do_\var{tag}()} method has been -defined. The \var{tag} argument is the name of the tag converted to -lower case, and the \var{method} argument is the bound method which -should be used to support semantic interpretation of the start tag. -The \var{attributes} argument is a list of \code{(\var{name}, \var{value})} -pairs containing the attributes found inside the tag's \code{<>} -brackets. The \var{name} has been translated to lower case and double -quotes and backslashes in the \var{value} have been interpreted. For -instance, for the tag \code{<A HREF="http://www.cwi.nl/">}, this -method would be called as \samp{unknown_starttag('a', [('href', -'http://www.cwi.nl/')])}. The base implementation simply calls -\var{method} with \var{attributes} as the only argument. -\end{methoddesc} - -\begin{methoddesc}{handle_endtag}{tag, method} -This method is called to handle endtags for which an -\code{end_\var{tag}()} method has been defined. The \var{tag} -argument is the name of the tag converted to lower case, and the -\var{method} argument is the bound method which should be used to -support semantic interpretation of the end tag. If no -\code{end_\var{tag}()} method is defined for the closing element, -this handler is not called. The base implementation simply calls -\var{method}. -\end{methoddesc} - -\begin{methoddesc}{handle_data}{data} -This method is called to process arbitrary data. It is intended to be -overridden by a derived class; the base class implementation does -nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_charref}{ref} -This method is called to process a character reference of the form -\samp{\&\#\var{ref};}. In the base implementation, \var{ref} must -be a decimal number in the -range 0-255. It translates the character to \ASCII{} and calls the -method \method{handle_data()} with the character as argument. If -\var{ref} is invalid or out of range, the method -\code{unknown_charref(\var{ref})} is called to handle the error. A -subclass must override this method to provide support for named -character entities. -\end{methoddesc} - -\begin{methoddesc}{handle_entityref}{ref} -This method is called to process a general entity reference of the -form \samp{\&\var{ref};} where \var{ref} is an general entity -reference. It looks for \var{ref} in the instance (or class) -variable \member{entitydefs} which should be a mapping from entity -names to corresponding translations. -If a translation is found, it calls the method \method{handle_data()} -with the translation; otherwise, it calls the method -\code{unknown_entityref(\var{ref})}. The default \member{entitydefs} -defines translations for \code{\&}, \code{\&apos}, \code{\>}, -\code{\<}, and \code{\"}. -\end{methoddesc} - -\begin{methoddesc}{handle_comment}{comment} -This method is called when a comment is encountered. The -\var{comment} argument is a string containing the text between the -\samp{<!--} and \samp{-->} delimiters, but not the delimiters -themselves. For example, the comment \samp{<!--text-->} will -cause this method to be called with the argument \code{'text'}. The -default method does nothing. -\end{methoddesc} - -\begin{methoddesc}{report_unbalanced}{tag} -This method is called when an end tag is found which does not -correspond to any open element. -\end{methoddesc} - -\begin{methoddesc}{unknown_starttag}{tag, attributes} -This method is called to process an unknown start tag. It is intended -to be overridden by a derived class; the base class implementation -does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_endtag}{tag} -This method is called to process an unknown end tag. It is intended -to be overridden by a derived class; the base class implementation -does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_charref}{ref} -This method is called to process unresolvable numeric character -references. Refer to \method{handle_charref()} to determine what is -handled by default. It is intended to be overridden by a derived -class; the base class implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_entityref}{ref} -This method is called to process an unknown entity reference. It is -intended to be overridden by a derived class; the base class -implementation does nothing. -\end{methoddesc} - -Apart from overriding or extending the methods listed above, derived -classes may also define methods of the following form to define -processing of specific tags. Tag names in the input stream are case -independent; the \var{tag} occurring in method names must be in lower -case: - -\begin{methoddescni}{start_\var{tag}}{attributes} -This method is called to process an opening tag \var{tag}. It has -preference over \code{do_\var{tag}()}. The \var{attributes} -argument has the same meaning as described for -\method{handle_starttag()} above. -\end{methoddescni} - -\begin{methoddescni}{do_\var{tag}}{attributes} -This method is called to process an opening tag \var{tag} that does -not come with a matching closing tag. The \var{attributes} argument -has the same meaning as described for \method{handle_starttag()} above. -\end{methoddescni} - -\begin{methoddescni}{end_\var{tag}}{} -This method is called to process a closing tag \var{tag}. -\end{methoddescni} - -Note that the parser maintains a stack of open elements for which no -end tag has been found yet. Only tags processed by -\code{start_\var{tag}()} are pushed on this stack. Definition of an -\code{end_\var{tag}()} method is optional for these tags. For tags -processed by \code{do_\var{tag}()} or by \method{unknown_tag()}, no -\code{end_\var{tag}()} method must be defined; if defined, it will not -be used. If both \code{start_\var{tag}()} and \code{do_\var{tag}()} -methods exist for a tag, the \code{start_\var{tag}()} method takes -precedence. diff --git a/Doc/libshelve.tex b/Doc/libshelve.tex deleted file mode 100644 index 90afbc6..0000000 --- a/Doc/libshelve.tex +++ /dev/null @@ -1,61 +0,0 @@ -\section{Standard Module \module{shelve}} -\label{module-shelve} -\stmodindex{shelve} - -A ``shelf'' is a persistent, dictionary-like object. The difference -with ``dbm'' databases is that the values (not the keys!) in a shelf -can be essentially arbitrary Python objects --- anything that the -\code{pickle} module can handle. This includes most class instances, -recursive data types, and objects containing lots of shared -sub-objects. The keys are ordinary strings. -\refstmodindex{pickle} - -To summarize the interface (\code{key} is a string, \code{data} is an -arbitrary object): - -\begin{verbatim} -import shelve - -d = shelve.open(filename) # open, with (g)dbm filename -- no suffix - -d[key] = data # store data at key (overwrites old data if - # using an existing key) -data = d[key] # retrieve data at key (raise KeyError if no - # such key) -del d[key] # delete data stored at key (raises KeyError - # if no such key) -flag = d.has_key(key) # true if the key exists -list = d.keys() # a list of all existing keys (slow!) - -d.close() # close it -\end{verbatim} -% -Restrictions: - -\begin{itemize} - -\item -The choice of which database package will be used (e.g. \code{dbm} or -\code{gdbm}) -depends on which interface is available. Therefore it isn't safe to -open the database directly using \code{dbm}. The database is also -(unfortunately) subject to the limitations of \code{dbm}, if it is used --- -this means that (the pickled representation of) the objects stored in -the database should be fairly small, and in rare cases key collisions -may cause the database to refuse updates. -\refbimodindex{dbm} -\refbimodindex{gdbm} - -\item -Dependent on the implementation, closing a persistent dictionary may -or may not be necessary to flush changes to disk. - -\item -The \code{shelve} module does not support \emph{concurrent} read/write -access to shelved objects. (Multiple simultaneous read accesses are -safe.) When a program has a shelf open for writing, no other program -should have it open for reading or writing. \UNIX{} file locking can -be used to solve this, but this differs across \UNIX{} versions and -requires knowledge about the database implementation used. - -\end{itemize} diff --git a/Doc/libsignal.tex b/Doc/libsignal.tex deleted file mode 100644 index 49eb62e..0000000 --- a/Doc/libsignal.tex +++ /dev/null @@ -1,142 +0,0 @@ -\section{Built-in Module \module{signal}} -\label{module-signal} - -\bimodindex{signal} -This module provides mechanisms to use signal handlers in Python. -Some general rules for working with signals handlers: - -\begin{itemize} - -\item -A handler for a particular signal, once set, remains installed until -it is explicitly reset (i.e. Python emulates the BSD style interface -regardless of the underlying implementation), with the exception of -the handler for \constant{SIGCHLD}, which follows the underlying -implementation. - -\item -There is no way to ``block'' signals temporarily from critical -sections (since this is not supported by all \UNIX{} flavors). - -\item -Although Python signal handlers are called asynchronously as far as -the Python user is concerned, they can only occur between the -``atomic'' instructions of the Python interpreter. This means that -signals arriving during long calculations implemented purely in \C{} -(e.g.\ regular expression matches on large bodies of text) may be -delayed for an arbitrary amount of time. - -\item -When a signal arrives during an I/O operation, it is possible that the -I/O operation raises an exception after the signal handler returns. -This is dependent on the underlying \UNIX{} system's semantics regarding -interrupted system calls. - -\item -Because the \C{} signal handler always returns, it makes little sense to -catch synchronous errors like \constant{SIGFPE} or \constant{SIGSEGV}. - -\item -Python installs a small number of signal handlers by default: -\constant{SIGPIPE} is ignored (so write errors on pipes and sockets can be -reported as ordinary Python exceptions), \constant{SIGINT} is translated -into a \exception{KeyboardInterrupt} exception, and \constant{SIGTERM} is -caught so that necessary cleanup (especially \code{sys.exitfunc}) can -be performed before actually terminating. All of these can be -overridden. - -\item -Some care must be taken if both signals and threads are used in the -same program. The fundamental thing to remember in using signals and -threads simultaneously is:\ always perform \function{signal()} operations -in the main thread of execution. Any thread can perform an -\function{alarm()}, \function{getsignal()}, or \function{pause()}; -only the main thread can set a new signal handler, and the main thread -will be the only one to receive signals (this is enforced by the -Python \module{signal} module, even if the underlying thread -implementation supports sending signals to individual threads). This -means that signals can't be used as a means of interthread -communication. Use locks instead. - -\end{itemize} - -The variables defined in the \module{signal} module are: - -\begin{datadesc}{SIG_DFL} - This is one of two standard signal handling options; it will simply - perform the default function for the signal. For example, on most - systems the default action for \constant{SIGQUIT} is to dump core - and exit, while the default action for \constant{SIGCLD} is to - simply ignore it. -\end{datadesc} - -\begin{datadesc}{SIG_IGN} - This is another standard signal handler, which will simply ignore - the given signal. -\end{datadesc} - -\begin{datadesc}{SIG*} - All the signal numbers are defined symbolically. For example, the - hangup signal is defined as \constant{signal.SIGHUP}; the variable names - are identical to the names used in C programs, as found in - \file{<signal.h>}. - The \UNIX{} man page for `\cfunction{signal()}' lists the existing - signals (on some systems this is \manpage{signal}{2}, on others the - list is in \manpage{signal}{7}). - Note that not all systems define the same set of signal names; only - those names defined by the system are defined by this module. -\end{datadesc} - -\begin{datadesc}{NSIG} - One more than the number of the highest signal number. -\end{datadesc} - -The \module{signal} module defines the following functions: - -\begin{funcdesc}{alarm}{time} - If \var{time} is non-zero, this function requests that a - \constant{SIGALRM} signal be sent to the process in \var{time} seconds. - Any previously scheduled alarm is canceled (i.e.\ only one alarm can - be scheduled at any time). The returned value is then the number of - seconds before any previously set alarm was to have been delivered. - If \var{time} is zero, no alarm id scheduled, and any scheduled - alarm is canceled. The return value is the number of seconds - remaining before a previously scheduled alarm. If the return value - is zero, no alarm is currently scheduled. (See the \UNIX{} man page - \manpage{alarm}{2}.) -\end{funcdesc} - -\begin{funcdesc}{getsignal}{signalnum} - Return the current signal handler for the signal \var{signalnum}. - The returned value may be a callable Python object, or one of the - special values \constant{signal.SIG_IGN}, \constant{signal.SIG_DFL} or - \constant{None}. Here, \constant{signal.SIG_IGN} means that the - signal was previously ignored, \constant{signal.SIG_DFL} means that the - default way of handling the signal was previously in use, and - \code{None} means that the previous signal handler was not installed - from Python. -\end{funcdesc} - -\begin{funcdesc}{pause}{} - Cause the process to sleep until a signal is received; the - appropriate handler will then be called. Returns nothing. (See the - \UNIX{} man page \manpage{signal}{2}.) -\end{funcdesc} - -\begin{funcdesc}{signal}{signalnum, handler} - Set the handler for signal \var{signalnum} to the function - \var{handler}. \var{handler} can be any callable Python object, or - one of the special values \constant{signal.SIG_IGN} or - \constant{signal.SIG_DFL}. The previous signal handler will be returned - (see the description of \function{getsignal()} above). (See the - \UNIX{} man page \manpage{signal}{2}.) - - When threads are enabled, this function can only be called from the - main thread; attempting to call it from other threads will cause a - \exception{ValueError} exception to be raised. - - The \var{handler} is called with two arguments: the signal number - and the current stack frame (\code{None} or a frame object; see the - reference manual for a description of frame objects). -\obindex{frame} -\end{funcdesc} diff --git a/Doc/libsite.tex b/Doc/libsite.tex deleted file mode 100644 index 84b1e64..0000000 --- a/Doc/libsite.tex +++ /dev/null @@ -1,85 +0,0 @@ -\section{Standard Module \module{site}} -\label{module-site} -\stmodindex{site} - -\strong{This module is automatically imported during initialization.} - -In earlier versions of Python (up to and including 1.5a3), scripts or -modules that needed to use site-specific modules would place -\samp{import site} somewhere near the top of their code. This is no -longer necessary. - -This will append site-specific paths to to the module search path. -\indexiii{module}{search}{path} - -It starts by constructing up to four directories from a head and a -tail part. For the head part, it uses \code{sys.prefix} and -\code{sys.exec_prefix}; empty heads are skipped. For -the tail part, it uses the empty string (on Macintosh or Windows) or -it uses first \file{lib/python\var{version}/site-packages} and then -\file{lib/site-python} (on \UNIX{}). For each of the distinct -head-tail combinations, it sees if it refers to an existing directory, -and if so, adds to \code{sys.path}, and also inspected for path -configuration files. -\indexii{site-python}{directory} -\indexii{site-packages}{directory} - -A path configuration file is a file whose name has the form -\file{\var{package}.pth}; its contents are additional items (one -per line) to be added to \code{sys.path}. Non-existing items are -never added to \code{sys.path}, but no check is made that the item -refers to a directory (rather than a file). No item is added to -\code{sys.path} more than once. Blank lines and lines beginning with -\code{\#} are skipped. -\index{package} -\indexiii{path}{configuration}{file} - -For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are -set to \file{/usr/local}. The Python \version\ library is then -installed in \file{/usr/local/lib/python1.5} (note that only the first -three characters of \code{sys.version} are used to form the path -name). Suppose this has a subdirectory -\file{/usr/local/lib/python1.5/site-packages} with three -subsubdirectories, \file{foo}, \file{bar} and \file{spam}, and two -path configuration files, \file{foo.pth} and \file{bar.pth}. Assume -\file{foo.pth} contains the following: - -\begin{verbatim} -# foo package configuration - -foo -bar -bletch -\end{verbatim} - -and \file{bar.pth} contains: - -\begin{verbatim} -# bar package configuration - -bar -\end{verbatim} - -Then the following directories are added to \code{sys.path}, in this -order: - -\begin{verbatim} -/usr/local/lib/python1.5/site-packages/bar -/usr/local/lib/python1.5/site-packages/foo -\end{verbatim} - -Note that \file{bletch} is omitted because it doesn't exist; the -\file{bar} directory precedes the \file{foo} directory because -\file{bar.pth} comes alphabetically before \file{foo.pth}; and -\file{spam} is omitted because it is not mentioned in either path -configuration file. - -After these path manipulations, an attempt is made to import a module -named \module{sitecustomize}\refmodindex{sitecustomize}, which can -perform arbitrary site-specific customizations. If this import fails -with an \exception{ImportError} exception, it is silently ignored. - -Note that for some non-\UNIX{} systems, \code{sys.prefix} and -\code{sys.exec_prefix} are empty, and the path manipulations are -skipped; however the import of -\module{sitecustomize}\refmodindex{sitecustomize} is still attempted. diff --git a/Doc/libsocket.tex b/Doc/libsocket.tex deleted file mode 100644 index 76d2b1a..0000000 --- a/Doc/libsocket.tex +++ /dev/null @@ -1,380 +0,0 @@ -\section{Built-in Module \module{socket}} -\label{module-socket} -\bimodindex{socket} - -This module provides access to the BSD \emph{socket} interface. -It is available on \UNIX{} systems that support this interface. - -For an introduction to socket programming (in C), see the following -papers: \emph{An Introductory 4.3BSD Interprocess Communication -Tutorial}, by Stuart Sechrest and \emph{An Advanced 4.3BSD Interprocess -Communication Tutorial}, by Samuel J. Leffler et al, both in the -\UNIX{} Programmer's Manual, Supplementary Documents 1 (sections PS1:7 -and PS1:8). The \UNIX{} manual pages for the various socket-related -system calls are also a valuable source of information on the details of -socket semantics. - -The Python interface is a straightforward transliteration of the -\UNIX{} system call and library interface for sockets to Python's -object-oriented style: the \function{socket()} function returns a -\dfn{socket object} whose methods implement the various socket system -calls. Parameter types are somewhat higher-level than in the C -interface: as with \method{read()} and \method{write()} operations on -Python files, buffer allocation on receive operations is automatic, -and buffer length is implicit on send operations. - -Socket addresses are represented as a single string for the -\constant{AF_UNIX} address family and as a pair -\code{(\var{host}, \var{port})} for the \constant{AF_INET} address -family, where \var{host} is a string representing -either a hostname in Internet domain notation like -\code{'daring.cwi.nl'} or an IP address like \code{'100.50.200.5'}, -and \var{port} is an integral port number. Other address families are -currently not supported. The address format required by a particular -socket object is automatically selected based on the address family -specified when the socket object was created. - -For IP addresses, two special forms are accepted instead of a host -address: the empty string represents \constant{INADDR_ANY}, and the string -\code{"<broadcast>"} represents \constant{INADDR_BROADCAST}. - -All errors raise exceptions. The normal exceptions for invalid -argument types and out-of-memory conditions can be raised; errors -related to socket or address semantics raise the error \code{socket.error}. - -Non-blocking mode is supported through the \code{setblocking()} -method. - -The module \module{socket} exports the following constants and functions: - - -\begin{excdesc}{error} -This exception is raised for socket- or address-related errors. -The accompanying value is either a string telling what went wrong or a -pair \code{(\var{errno}, \var{string})} -representing an error returned by a system -call, similar to the value accompanying \code{os.error}. -See the module \module{errno}\refbimodindex{errno}, which contains -names for the error codes defined by the underlying operating system. -\end{excdesc} - -\begin{datadesc}{AF_UNIX} -\dataline{AF_INET} -These constants represent the address (and protocol) families, -used for the first argument to \function{socket()}. If the -\constant{AF_UNIX} constant is not defined then this protocol is -unsupported. -\end{datadesc} - -\begin{datadesc}{SOCK_STREAM} -\dataline{SOCK_DGRAM} -\dataline{SOCK_RAW} -\dataline{SOCK_RDM} -\dataline{SOCK_SEQPACKET} -These constants represent the socket types, -used for the second argument to \function{socket()}. -(Only \constant{SOCK_STREAM} and -\constant{SOCK_DGRAM} appear to be generally useful.) -\end{datadesc} - -\begin{datadesc}{SO_*} -\dataline{SOMAXCONN} -\dataline{MSG_*} -\dataline{SOL_*} -\dataline{IPPROTO_*} -\dataline{IPPORT_*} -\dataline{INADDR_*} -\dataline{IP_*} -Many constants of these forms, documented in the \UNIX{} documentation on -sockets and/or the IP protocol, are also defined in the socket module. -They are generally used in arguments to the \method{setsockopt()} and -\method{getsockopt()} methods of socket objects. In most cases, only -those symbols that are defined in the \UNIX{} header files are defined; -for a few symbols, default values are provided. -\end{datadesc} - -\begin{funcdesc}{gethostbyname}{hostname} -Translate a host name to IP address format. The IP address is -returned as a string, e.g., \code{'100.50.200.5'}. If the host name -is an IP address itself it is returned unchanged. -\end{funcdesc} - -\begin{funcdesc}{gethostname}{} -Return a string containing the hostname of the machine where -the Python interpreter is currently executing. If you want to know the -current machine's IP address, use \code{gethostbyname(gethostname())}. -Note: \function{gethostname()} doesn't always return the fully qualified -domain name; use \code{gethostbyaddr(gethostname())} -(see below). -\end{funcdesc} - -\begin{funcdesc}{gethostbyaddr}{ip_address} -Return a triple \code{(\var{hostname}, \var{aliaslist}, -\var{ipaddrlist})} where \var{hostname} is the primary host name -responding to the given \var{ip_address}, \var{aliaslist} is a -(possibly empty) list of alternative host names for the same address, -and \var{ipaddrlist} is a list of IP addresses for the same interface -on the same host (most likely containing only a single address). -To find the fully qualified domain name, check \var{hostname} and the -items of \var{aliaslist} for an entry containing at least one period. -\end{funcdesc} - -\begin{funcdesc}{getprotobyname}{protocolname} -Translate an Internet protocol name (e.g. \code{'icmp'}) to a constant -suitable for passing as the (optional) third argument to the -\function{socket()} function. This is usually only needed for sockets -opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket -modes, the correct protocol is chosen automatically if the protocol is -omitted or zero. -\end{funcdesc} - -\begin{funcdesc}{getservbyname}{servicename, protocolname} -Translate an Internet service name and protocol name to a port number -for that service. The protocol name should be \code{'tcp'} or -\code{'udp'}. -\end{funcdesc} - -\begin{funcdesc}{socket}{family, type\optional{, proto}} -Create a new socket using the given address family, socket type and -protocol number. The address family should be \constant{AF_INET} or -\constant{AF_UNIX}. The socket type should be \constant{SOCK_STREAM}, -\constant{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants. -The protocol number is usually zero and may be omitted in that case. -\end{funcdesc} - -\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}} -Build a socket object from an existing file descriptor (an integer as -returned by a file object's \method{fileno()} method). Address family, -socket type and protocol number are as for the \code{socket} function -above. The file descriptor should refer to a socket, but this is not -checked --- subsequent operations on the object may fail if the file -descriptor is invalid. This function is rarely needed, but can be -used to get or set socket options on a socket passed to a program as -standard input or output (e.g.\ a server started by the \UNIX{} inet -daemon). -\end{funcdesc} - -\begin{funcdesc}{ntohl}{x} -Convert 32-bit integers from network to host byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 4-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{ntohs}{x} -Convert 16-bit integers from network to host byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 2-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{htonl}{x} -Convert 32-bit integers from host to network byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 4-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{htons}{x} -Convert 16-bit integers from host to network byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 2-byte swap operation. -\end{funcdesc} - -\begin{datadesc}{SocketType} -This is a Python type object that represents the socket object type. -It is the same as \code{type(socket(...))}. -\end{datadesc} - -\subsection{Socket Objects} - -Socket objects have the following methods. Except for -\method{makefile()} these correspond to \UNIX{} system calls -applicable to sockets. - -\begin{methoddesc}[socket]{accept}{} -Accept a connection. -The socket must be bound to an address and listening for connections. -The return value is a pair \code{(\var{conn}, \var{address})} -where \var{conn} is a \emph{new} socket object usable to send and -receive data on the connection, and \var{address} is the address bound -to the socket on the other end of the connection. -\end{methoddesc} - -\begin{methoddesc}[socket]{bind}{address} -Bind the socket to \var{address}. The socket must not already be bound. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{close}{} -Close the socket. All future operations on the socket object will fail. -The remote end will receive no more data (after queued data is flushed). -Sockets are automatically closed when they are garbage-collected. -\end{methoddesc} - -\begin{methoddesc}[socket]{connect}{address} -Connect to a remote socket at \var{address}. -(The format of \var{address} depends on the address family --- see -above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{connect_ex}{address} -Like \code{connect(\var{address})}, but return an error indicator -instead of raising an exception. The error indicator is 0 if the -operation succeeded, otherwise the value of the \cdata{errno} -variable. This is useful, e.g., for asynchronous connects. -\end{methoddesc} - -\begin{methoddesc}[socket]{fileno}{} -Return the socket's file descriptor (a small integer). This is useful -with \function{select.select()}. -\end{methoddesc} - -\begin{methoddesc}[socket]{getpeername}{} -Return the remote address to which the socket is connected. This is -useful to find out the port number of a remote IP socket, for instance. -(The format of the address returned depends on the address family --- -see above.) On some systems this function is not supported. -\end{methoddesc} - -\begin{methoddesc}[socket]{getsockname}{} -Return the socket's own address. This is useful to find out the port -number of an IP socket, for instance. -(The format of the address returned depends on the address family --- -see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}} -Return the value of the given socket option (see the \UNIX{} man page -\manpage{getsockopt}{2}). The needed symbolic constants -(\constant{SO_*} etc.) are defined in this module. If \var{buflen} -is absent, an integer option is assumed and its integer value -is returned by the function. If \var{buflen} is present, it specifies -the maximum length of the buffer used to receive the option in, and -this buffer is returned as a string. It is up to the caller to decode -the contents of the buffer (see the optional built-in module -\module{struct} for a way to decode C structures encoded as strings). -\end{methoddesc} - -\begin{methoddesc}[socket]{listen}{backlog} -Listen for connections made to the socket. The \var{backlog} argument -specifies the maximum number of queued connections and should be at -least 1; the maximum value is system-dependent (usually 5). -\end{methoddesc} - -\begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}} -Return a \dfn{file object} associated with the socket. (File objects -were described earlier in \ref{bltin-file-objects}, ``File Objects.'') -The file object references a \cfunction{dup()}ped version of the -socket file descriptor, so the file object and socket object may be -closed or garbage-collected independently. The optional \var{mode} -and \var{bufsize} arguments are interpreted the same way as by the -built-in \function{open()} function. -\end{methoddesc} - -\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}} -Receive data from the socket. The return value is a string representing -the data received. The maximum amount of data to be received -at once is specified by \var{bufsize}. See the \UNIX{} manual page -\manpage{recv}{2} for the meaning of the optional argument -\var{flags}; it defaults to zero. -\end{methoddesc} - -\begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}} -Receive data from the socket. The return value is a pair -\code{(\var{string}, \var{address})} where \var{string} is a string -representing the data received and \var{address} is the address of the -socket sending the data. The optional \var{flags} argument has the -same meaning as for \method{recv()} above. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{send}{string\optional{, flags}} -Send data to the socket. The socket must be connected to a remote -socket. The optional \var{flags} argument has the same meaning as for -\method{recv()} above. Returns the number of bytes sent. -\end{methoddesc} - -\begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address} -Send data to the socket. The socket should not be connected to a -remote socket, since the destination socket is specified by -\var{address}. The optional \var{flags} argument has the same -meaning as for \method{recv()} above. Return the number of bytes sent. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{setblocking}{flag} -Set blocking or non-blocking mode of the socket: if \var{flag} is 0, -the socket is set to non-blocking, else to blocking mode. Initially -all sockets are in blocking mode. In non-blocking mode, if a -\method{recv()} call doesn't find any data, or if a \code{send} call can't -immediately dispose of the data, a \exception{error} exception is -raised; in blocking mode, the calls block until they can proceed. -\end{methoddesc} - -\begin{methoddesc}[socket]{setsockopt}{level, optname, value} -Set the value of the given socket option (see the \UNIX{} man page -\manpage{setsockopt}{2}). The needed symbolic constants are defined in -the \module{socket} module (\code{SO_*} etc.). The value can be an -integer or a string representing a buffer. In the latter case it is -up to the caller to ensure that the string contains the proper bits -(see the optional built-in module -\module{struct}\refbimodindex{struct} for a way to encode C structures -as strings). -\end{methoddesc} - -\begin{methoddesc}[socket]{shutdown}{how} -Shut down one or both halves of the connection. If \var{how} is -\code{0}, further receives are disallowed. If \var{how} is \code{1}, -further sends are disallowed. If \var{how} is \code{2}, further sends -and receives are disallowed. -\end{methoddesc} - -Note that there are no methods \method{read()} or \method{write()}; -use \method{recv()} and \method{send()} without \var{flags} argument -instead. - -\subsection{Example} -\nodename{Socket Example} - -Here are two minimal example programs using the TCP/IP protocol:\ a -server that echoes all data that it receives back (servicing only one -client), and a client using it. Note that a server must perform the -sequence \function{socket()}, \method{bind()}, \method{listen()}, -\method{accept()} (possibly repeating the \method{accept()} to service -more than one client), while a client only needs the sequence -\function{socket()}, \method{connect()}. Also note that the server -does not \method{send()}/\method{recv()} on the -socket it is listening on but on the new socket returned by -\method{accept()}. - -\begin{verbatim} -# Echo server program -from socket import * -HOST = '' # Symbolic name meaning the local host -PORT = 50007 # Arbitrary non-privileged server -s = socket(AF_INET, SOCK_STREAM) -s.bind(HOST, PORT) -s.listen(1) -conn, addr = s.accept() -print 'Connected by', addr -while 1: - data = conn.recv(1024) - if not data: break - conn.send(data) -conn.close() -\end{verbatim} - -\begin{verbatim} -# Echo client program -from socket import * -HOST = 'daring.cwi.nl' # The remote host -PORT = 50007 # The same port as used by the server -s = socket(AF_INET, SOCK_STREAM) -s.connect(HOST, PORT) -s.send('Hello, world') -data = s.recv(1024) -s.close() -print 'Received', `data` -\end{verbatim} - -\begin{seealso} -\seemodule{SocketServer}{classes that simplify writing network servers} -\end{seealso} diff --git a/Doc/libsocksvr.tex b/Doc/libsocksvr.tex deleted file mode 100644 index 8769c36..0000000 --- a/Doc/libsocksvr.tex +++ /dev/null @@ -1,196 +0,0 @@ -\section{Standard Module \module{SocketServer}} -\label{module-SocketServer} -\stmodindex{SocketServer} - -The \module{SocketServer} module simplifies the task of writing network -servers. - -There are four basic server classes: \class{TCPServer} uses the -Internet TCP protocol, which provides for continuous streams of data -between the client and server. \class{UDPServer} uses datagrams, which -are discrete packets of information that may arrive out of order or be -lost while in transit. The more infrequently used -\class{UnixStreamServer} and \class{UnixDatagramServer} classes are -similar, but use \UNIX{} domain sockets; they're not available on -non-\UNIX{} platforms. For more details on network programming, consult -a book such as W. Richard Steven's \emph{UNIX Network Programming} -or Ralph Davis's \emph{Win32 Network Programming}. - -These four classes process requests \dfn{synchronously}; each request -must be completed before the next request can be started. This isn't -suitable if each request takes a long time to complete, because it -requires a lot of computation, or because it returns a lot of data -which the client is slow to process. The solution is to create a -separate process or thread to handle each request; the -\class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes can be -used to support asynchronous behaviour. - -Creating a server requires several steps. First, you must create a -request handler class by subclassing the \class{BaseRequestHandler} -class and overriding its \method{handle()} method; this method will -process incoming requests. Second, you must instantiate one of the -server classes, passing it the server's address and the request -handler class. Finally, call the \method{handle_request()} or -\method{serve_forever()} method of the server object to process one or -many requests. - -Server classes have the same external methods and attributes, no -matter what network protocol they use: - -\setindexsubitem{(SocketServer protocol)} - -%XXX should data and methods be intermingled, or separate? -% how should the distinction between class and instance variables be -% drawn? - -\begin{funcdesc}{fileno}{} -Return an integer file descriptor for the socket on which the server -is listening. This function is most commonly passed to -\function{select.select()}, to allow monitoring multiple servers in the -same process. -\end{funcdesc} - -\begin{funcdesc}{handle_request}{} -Process a single request. This function calls the following methods -in order: \method{get_request()}, \method{verify_request()}, and -\method{process_request()}. If the user-provided \method{handle()} -method of the handler class raises an exception, the server's -\method{handle_error()} method will be called. -\end{funcdesc} - -\begin{funcdesc}{serve_forever}{} -Handle an infinite number of requests. This simply calls -\method{handle_request()} inside an infinite loop. -\end{funcdesc} - -\begin{datadesc}{address_family} -The family of protocols to which the server's socket belongs. -\constant{socket.AF_INET} and \constant{socket.AF_UNIX} are two -possible values. -\end{datadesc} - -\begin{datadesc}{RequestHandlerClass} -The user-provided request handler class; an instance of this class is -created for each request. -\end{datadesc} - -\begin{datadesc}{server_address} -The address on which the server is listening. The format of addresses -varies depending on the protocol family; see the documentation for the -socket module for details. For Internet protocols, this is a tuple -containing a string giving the address, and an integer port number: -\code{('127.0.0.1', 80)}, for example. -\end{datadesc} - -\begin{datadesc}{socket} -The socket object on which the server will listen for incoming requests. -\end{datadesc} - -% XXX should class variables be covered before instance variables, or -% vice versa? - -The server classes support the following class variables: - -\begin{datadesc}{request_queue_size} -The size of the request queue. If it takes a long time to process a -single request, any requests that arrive while the server is busy are -placed into a queue, up to \member{request_queue_size} requests. Once -the queue is full, further requests from clients will get a -``Connection denied'' error. The default value is usually 5, but this -can be overridden by subclasses. -\end{datadesc} - -\begin{datadesc}{socket_type} -The type of socket used by the server; \constant{socket.SOCK_STREAM} -and \constant{socket.SOCK_DGRAM} are two possible values. -\end{datadesc} - -There are various server methods that can be overridden by subclasses -of base server classes like \class{TCPServer}; these methods aren't -useful to external users of the server object. - -% should the default implementations of these be documented, or should -% it be assumed that the user will look at SocketServer.py? - -\begin{funcdesc}{finish_request}{} -Actually processes the request by instantiating -\member{RequestHandlerClass} and calling its \method{handle()} method. -\end{funcdesc} - -\begin{funcdesc}{get_request}{} -Must accept a request from the socket, and return a 2-tuple containing -the \emph{new} socket object to be used to communicate with the -client, and the client's address. -\end{funcdesc} - -\begin{funcdesc}{handle_error}{request, client_address} -This function is called if the \member{RequestHandlerClass}'s -\method{handle()} method raises an exception. The default action is -to print the traceback to standard output and continue handling -further requests. -\end{funcdesc} - -\begin{funcdesc}{process_request}{request, client_address} -Calls \method{finish_request()} to create an instance of the -\member{RequestHandlerClass}. If desired, this function can create a -new process or thread to handle the request; the \class{ForkingMixIn} -and \class{ThreadingMixIn} classes do this. -\end{funcdesc} - -% Is there any point in documenting the following two functions? -% What would the purpose of overriding them be: initializing server -% instance variables, adding new network families? - -\begin{funcdesc}{server_activate}{} -Called by the server's constructor to activate the server. -May be overridden. -\end{funcdesc} - -\begin{funcdesc}{server_bind}{} -Called by the server's constructor to bind the socket to the desired -address. May be overridden. -\end{funcdesc} - -\begin{funcdesc}{verify_request}{request, client_address} -Must return a Boolean value; if the value is true, the request will be -processed, and if it's false, the request will be denied. -This function can be overridden to implement access controls for a server. -The default implementation always return true. -\end{funcdesc} - -The request handler class must define a new \method{handle()} method, -and can override any of the following methods. A new instance is -created for each request. - -\begin{funcdesc}{finish}{} -Called after the \method{handle()} method to perform any clean-up -actions required. The default implementation does nothing. If -\method{setup()} or \method{handle()} raise an exception, this -function will not be called. -\end{funcdesc} - -\begin{funcdesc}{handle}{} -This function must do all the work required to service a request. -Several instance attributes are available to it; the request is -available as \member{self.request}; the client address as -\member{self.client_request}; and the server instance as -\member{self.server}, in case it needs access to per-server -information. - -The type of \member{self.request} is different for datagram or stream -services. For stream services, \member{self.request} is a socket -object; for datagram services, \member{self.request} is a string. -However, this can be hidden by using the mix-in request handler -classes -\class{StreamRequestHandler} or \class{DatagramRequestHandler}, which -override the \method{setup()} and \method{finish()} methods, and -provides \member{self.rfile} and \member{self.wfile} attributes. -\member{self.rfile} and \member{self.wfile} can be read or written, -respectively, to get the request data or return data to the client. -\end{funcdesc} - -\begin{funcdesc}{setup}{} -Called before the \method{handle()} method to perform any -initialization actions required. The default implementation does -nothing. -\end{funcdesc} diff --git a/Doc/libsomeos.tex b/Doc/libsomeos.tex deleted file mode 100644 index 1e282f5..0000000 --- a/Doc/libsomeos.tex +++ /dev/null @@ -1,39 +0,0 @@ -\chapter{Optional Operating System Services} -\label{someos} - -The modules described in this chapter provide interfaces to operating -system features that are available on selected operating systems only. -The interfaces are generally modelled after the \UNIX{} or \C{} -interfaces but they are available on some other systems as well -(e.g. Windows or NT). Here's an overview: - -\begin{description} - -\item[signal] ---- Set handlers for asynchronous events. - -\item[socket] ---- Low-level networking interface. - -\item[select] ---- Wait for I/O completion on multiple streams. - -\item[thread] ---- Create multiple threads of control within one namespace. - -\item[Queue] ---- A stynchronized queue class. - -\item[anydbm] ---- Generic interface to DBM-style database modules. - -\item[whichdb] ---- Guess which DBM-style module created a given database. - -\item[zlib] -\item[gzip] ---- Compression and decompression compatible with the -\program{gzip} program (\module{zlib} is the low-level interface, -\module{gzip} the high-level one). - -\end{description} diff --git a/Doc/libsoundex.tex b/Doc/libsoundex.tex deleted file mode 100644 index fdecbab..0000000 --- a/Doc/libsoundex.tex +++ /dev/null @@ -1,41 +0,0 @@ -\section{Built-in Module \module{soundex}} -\label{module-soundex} -\bimodindex{soundex} - - -The soundex algorithm takes an English word, and returns an -easily-computed hash of it; this hash is intended to be the same for -words that sound alike. This module provides an interface to the -soundex algorithm. - -Note that the soundex algorithm is quite simple-minded, and isn't -perfect by any measure. Its main purpose is to help looking up names -in databases, when the name may be misspelled --- soundex hashes common -misspellings together. - -\begin{funcdesc}{get_soundex}{string} -Return the soundex hash value for a word; it will always be a -6-character string. \var{string} must contain the word to be hashed, -with no leading whitespace; the case of the word is ignored. (Note -that the original algorithm produces a 4-character result.) -\end{funcdesc} - -\begin{funcdesc}{sound_similar}{string1, string2} -Compare the word in \var{string1} with the word in \var{string2}; this -is equivalent to -\code{get_soundex(\var{string1})} \code{==} -\code{get_soundex(\var{string2})}. -\end{funcdesc} - - -\begin{seealso} - -\seetext{Donald E. Knuth, \emph{Sorting and Searching,} vol. 3 in -``The Art of Computer Programming.'' Addison-Wesley Publishing -Company: Reading, MA: 1973. pp.\ 391-392. Discusses the origin and -usefulness of the algorithm, as well as the algorithm itself. Knuth -gives his sources as \emph{U.S. Patents 1261167} (1918) and -\emph{1435663} (1922), attributing the algorithm to Margaret K. Odell -and Robert C. Russel. Additional references are provided.} - -\end{seealso} diff --git a/Doc/libstat.tex b/Doc/libstat.tex deleted file mode 100644 index 5e76335..0000000 --- a/Doc/libstat.tex +++ /dev/null @@ -1,110 +0,0 @@ -% By Skip Montanaro - -\section{Standard Module \module{stat}} -\stmodindex{stat} -\label{module-stat} - -The \code{stat} module defines constants and functions for interpreting the -results of \code{os.stat()} and \code{os.lstat()} (if they exist). -For complete details about the \code{stat()} and \code{lstat()} system -calls, consult your local man pages. - -The \code{stat} module defines the following functions: - - -\begin{funcdesc}{S_ISDIR}{mode} -Return non-zero if the mode was gotten from a directory. -\end{funcdesc} - -\begin{funcdesc}{S_ISCHR}{mode} -Return non-zero if the mode was gotten from a character special device. -\end{funcdesc} - -\begin{funcdesc}{S_ISBLK}{mode} -Return non-zero if the mode was gotten from a block special device. -\end{funcdesc} - -\begin{funcdesc}{S_ISREG}{mode} -Return non-zero if the mode was gotten from a regular file. -\end{funcdesc} - -\begin{funcdesc}{S_ISFIFO}{mode} -Return non-zero if the mode was gotten from a FIFO. -\end{funcdesc} - -\begin{funcdesc}{S_ISLNK}{mode} -Return non-zero if the mode was gotten from a symbolic link. -\end{funcdesc} - -\begin{funcdesc}{S_ISSOCK}{mode} -Return non-zero if the mode was gotten from a socket. -\end{funcdesc} - -All the data items below are simply symbolic indexes into the 10-tuple -returned by \code{os.stat()} or \code{os.lstat()}. - -\begin{datadesc}{ST_MODE} -Inode protection mode. -\end{datadesc} - -\begin{datadesc}{ST_INO} -Inode number. -\end{datadesc} - -\begin{datadesc}{ST_DEV} -Device inode resides on. -\end{datadesc} - -\begin{datadesc}{ST_NLINK} -Number of links to the inode. -\end{datadesc} - -\begin{datadesc}{ST_UID} -User id of the owner. -\end{datadesc} - -\begin{datadesc}{ST_GID} -Group id of the owner. -\end{datadesc} - -\begin{datadesc}{ST_SIZE} -File size in bytes. -\end{datadesc} - -\begin{datadesc}{ST_ATIME} -Time of last access. -\end{datadesc} - -\begin{datadesc}{ST_MTIME} -Time of last modification. -\end{datadesc} - -\begin{datadesc}{ST_CTIME} -Time of last status change (see manual pages for details). -\end{datadesc} - -Example: - -\begin{verbatim} -import os, sys -from stat import * - -def process(dir, func): - '''recursively descend the directory rooted at dir, calling func for - each regular file''' - - for f in os.listdir(dir): - mode = os.stat('%s/%s' % (dir, f))[ST_MODE] - if S_ISDIR(mode): - # recurse into directory - process('%s/%s' % (dir, f), func) - elif S_ISREG(mode): - func('%s/%s' % (dir, f)) - else: - print 'Skipping %s/%s' % (dir, f) - -def f(file): - print 'frobbed', file - -if __name__ == '__main__': process(sys.argv[1], f) -\end{verbatim} diff --git a/Doc/libstdwin.tex b/Doc/libstdwin.tex deleted file mode 100644 index 146457a..0000000 --- a/Doc/libstdwin.tex +++ /dev/null @@ -1,920 +0,0 @@ -\chapter{Standard Windowing Interface} - -The modules in this chapter are available only on those systems where -the STDWIN library is available. STDWIN runs on \UNIX{} under X11 and -on the Macintosh. See CWI report CS-R8817. - -\strong{Warning:} Using STDWIN is not recommended for new -applications. It has never been ported to Microsoft Windows or -Windows NT, and for X11 or the Macintosh it lacks important -functionality --- in particular, it has no tools for the construction -of dialogs. For most platforms, alternative, native solutions exist -(though none are currently documented in this manual): Tkinter for -\UNIX{} under X11, native Xt with Motif or Athena widgets for \UNIX{} -under X11, Win32 for Windows and Windows NT, and a collection of -native toolkit interfaces for the Macintosh. - -\section{Built-in Module \module{stdwin}} -\label{module-stdwin} -\bimodindex{stdwin} - -This module defines several new object types and functions that -provide access to the functionality of STDWIN. - -On \UNIX{} running X11, it can only be used if the \code{DISPLAY} -environment variable is set or an explicit \samp{-display -\var{displayname}} argument is passed to the Python interpreter. - -Functions have names that usually resemble their C STDWIN counterparts -with the initial `w' dropped. -Points are represented by pairs of integers; rectangles -by pairs of points. -For a complete description of STDWIN please refer to the documentation -of STDWIN for C programmers (aforementioned CWI report). - -\subsection{Functions Defined in Module \module{stdwin}} -\nodename{STDWIN Functions} - -The following functions are defined in the \code{stdwin} module: - -\begin{funcdesc}{open}{title} -Open a new window whose initial title is given by the string argument. -Return a window object; window object methods are described below.% -\footnote{The Python version of STDWIN does not support draw procedures; all - drawing requests are reported as draw events.} -\end{funcdesc} - -\begin{funcdesc}{getevent}{} -Wait for and return the next event. -An event is returned as a triple: the first element is the event -type, a small integer; the second element is the window object to which -the event applies, or -\code{None} -if it applies to no window in particular; -the third element is type-dependent. -Names for event types and command codes are defined in the standard -module -\code{stdwinevent}. -\end{funcdesc} - -\begin{funcdesc}{pollevent}{} -Return the next event, if one is immediately available. -If no event is available, return \code{()}. -\end{funcdesc} - -\begin{funcdesc}{getactive}{} -Return the window that is currently active, or \code{None} if no -window is currently active. (This can be emulated by monitoring -WE_ACTIVATE and WE_DEACTIVATE events.) -\end{funcdesc} - -\begin{funcdesc}{listfontnames}{pattern} -Return the list of font names in the system that match the pattern (a -string). The pattern should normally be \code{'*'}; returns all -available fonts. If the underlying window system is X11, other -patterns follow the standard X11 font selection syntax (as used e.g. -in resource definitions), i.e. the wildcard character \code{'*'} -matches any sequence of characters (including none) and \code{'?'} -matches any single character. -On the Macintosh this function currently returns an empty list. -\end{funcdesc} - -\begin{funcdesc}{setdefscrollbars}{hflag, vflag} -Set the flags controlling whether subsequently opened windows will -have horizontal and/or vertical scroll bars. -\end{funcdesc} - -\begin{funcdesc}{setdefwinpos}{h, v} -Set the default window position for windows opened subsequently. -\end{funcdesc} - -\begin{funcdesc}{setdefwinsize}{width, height} -Set the default window size for windows opened subsequently. -\end{funcdesc} - -\begin{funcdesc}{getdefscrollbars}{} -Return the flags controlling whether subsequently opened windows will -have horizontal and/or vertical scroll bars. -\end{funcdesc} - -\begin{funcdesc}{getdefwinpos}{} -Return the default window position for windows opened subsequently. -\end{funcdesc} - -\begin{funcdesc}{getdefwinsize}{} -Return the default window size for windows opened subsequently. -\end{funcdesc} - -\begin{funcdesc}{getscrsize}{} -Return the screen size in pixels. -\end{funcdesc} - -\begin{funcdesc}{getscrmm}{} -Return the screen size in millimeters. -\end{funcdesc} - -\begin{funcdesc}{fetchcolor}{colorname} -Return the pixel value corresponding to the given color name. -Return the default foreground color for unknown color names. -Hint: the following code tests whether you are on a machine that -supports more than two colors: -\begin{verbatim} -if stdwin.fetchcolor('black') <> \ - stdwin.fetchcolor('red') <> \ - stdwin.fetchcolor('white'): - print 'color machine' -else: - print 'monochrome machine' -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{setfgcolor}{pixel} -Set the default foreground color. -This will become the default foreground color of windows opened -subsequently, including dialogs. -\end{funcdesc} - -\begin{funcdesc}{setbgcolor}{pixel} -Set the default background color. -This will become the default background color of windows opened -subsequently, including dialogs. -\end{funcdesc} - -\begin{funcdesc}{getfgcolor}{} -Return the pixel value of the current default foreground color. -\end{funcdesc} - -\begin{funcdesc}{getbgcolor}{} -Return the pixel value of the current default background color. -\end{funcdesc} - -\begin{funcdesc}{setfont}{fontname} -Set the current default font. -This will become the default font for windows opened subsequently, -and is also used by the text measuring functions \code{textwidth}, -\code{textbreak}, \code{lineheight} and \code{baseline} below. -This accepts two more optional parameters, size and style: -Size is the font size (in `points'). -Style is a single character specifying the style, as follows: -\code{'b'} = bold, -\code{'i'} = italic, -\code{'o'} = bold + italic, -\code{'u'} = underline; -default style is roman. -Size and style are ignored under X11 but used on the Macintosh. -(Sorry for all this complexity --- a more uniform interface is being designed.) -\end{funcdesc} - -\begin{funcdesc}{menucreate}{title} -Create a menu object referring to a global menu (a menu that appears in -all windows). -Methods of menu objects are described below. -Note: normally, menus are created locally; see the window method -\code{menucreate} below. -\strong{Warning:} the menu only appears in a window as long as the object -returned by this call exists. -\end{funcdesc} - -\begin{funcdesc}{newbitmap}{width, height} -Create a new bitmap object of the given dimensions. -Methods of bitmap objects are described below. -Not available on the Macintosh. -\end{funcdesc} - -\begin{funcdesc}{fleep}{} -Cause a beep or bell (or perhaps a `visual bell' or flash, hence the -name). -\end{funcdesc} - -\begin{funcdesc}{message}{string} -Display a dialog box containing the string. -The user must click OK before the function returns. -\end{funcdesc} - -\begin{funcdesc}{askync}{prompt, default} -Display a dialog that prompts the user to answer a question with yes or -no. -Return 0 for no, 1 for yes. -If the user hits the Return key, the default (which must be 0 or 1) is -returned. -If the user cancels the dialog, the -\code{KeyboardInterrupt} -exception is raised. -\end{funcdesc} - -\begin{funcdesc}{askstr}{prompt, default} -Display a dialog that prompts the user for a string. -If the user hits the Return key, the default string is returned. -If the user cancels the dialog, the -\code{KeyboardInterrupt} -exception is raised. -\end{funcdesc} - -\begin{funcdesc}{askfile}{prompt, default, new} -Ask the user to specify a filename. -If -\var{new} -is zero it must be an existing file; otherwise, it must be a new file. -If the user cancels the dialog, the -\code{KeyboardInterrupt} -exception is raised. -\end{funcdesc} - -\begin{funcdesc}{setcutbuffer}{i, string} -Store the string in the system's cut buffer number -\var{i}, -where it can be found (for pasting) by other applications. -On X11, there are 8 cut buffers (numbered 0..7). -Cut buffer number 0 is the `clipboard' on the Macintosh. -\end{funcdesc} - -\begin{funcdesc}{getcutbuffer}{i} -Return the contents of the system's cut buffer number -\var{i}. -\end{funcdesc} - -\begin{funcdesc}{rotatecutbuffers}{n} -On X11, rotate the 8 cut buffers by -\var{n}. -Ignored on the Macintosh. -\end{funcdesc} - -\begin{funcdesc}{getselection}{i} -Return X11 selection number -\var{i.} -Selections are not cut buffers. -Selection numbers are defined in module -\code{stdwinevents}. -Selection \code{WS_PRIMARY} is the -\dfn{primary} -selection (used by -xterm, -for instance); -selection \code{WS_SECONDARY} is the -\dfn{secondary} -selection; selection \code{WS_CLIPBOARD} is the -\dfn{clipboard} -selection (used by -xclipboard). -On the Macintosh, this always returns an empty string. -\end{funcdesc} - -\begin{funcdesc}{resetselection}{i} -Reset selection number -\var{i}, -if this process owns it. -(See window method -\code{setselection()}). -\end{funcdesc} - -\begin{funcdesc}{baseline}{} -Return the baseline of the current font (defined by STDWIN as the -vertical distance between the baseline and the top of the -characters). -\end{funcdesc} - -\begin{funcdesc}{lineheight}{} -Return the total line height of the current font. -\end{funcdesc} - -\begin{funcdesc}{textbreak}{str, width} -Return the number of characters of the string that fit into a space of -\var{width} -bits wide when drawn in the curent font. -\end{funcdesc} - -\begin{funcdesc}{textwidth}{str} -Return the width in bits of the string when drawn in the current font. -\end{funcdesc} - -\begin{funcdesc}{connectionnumber}{} -\funcline{fileno}{} -(X11 under \UNIX{} only) Return the ``connection number'' used by the -underlying X11 implementation. (This is normally the file number of -the socket.) Both functions return the same value; -\code{connectionnumber()} is named after the corresponding function in -X11 and STDWIN, while \code{fileno()} makes it possible to use the -\code{stdwin} module as a ``file'' object parameter to -\code{select.select()}. Note that if \code{select()} implies that -input is possible on \code{stdwin}, this does not guarantee that an -event is ready --- it may be some internal communication going on -between the X server and the client library. Thus, you should call -\code{stdwin.pollevent()} until it returns \code{None} to check for -events if you don't want your program to block. Because of internal -buffering in X11, it is also possible that \code{stdwin.pollevent()} -returns an event while \code{select()} does not find \code{stdwin} to -be ready, so you should read any pending events with -\code{stdwin.pollevent()} until it returns \code{None} before entering -a blocking \code{select()} call. -\ttindex{select} -\end{funcdesc} - -\subsection{Window Objects} -\nodename{STDWIN Window Objects} - -Window objects are created by \code{stdwin.open()}. They are closed -by their \code{close()} method or when they are garbage-collected. -Window objects have the following methods: - -\setindexsubitem{(window method)} - -\begin{funcdesc}{begindrawing}{} -Return a drawing object, whose methods (described below) allow drawing -in the window. -\end{funcdesc} - -\begin{funcdesc}{change}{rect} -Invalidate the given rectangle; this may cause a draw event. -\end{funcdesc} - -\begin{funcdesc}{gettitle}{} -Returns the window's title string. -\end{funcdesc} - -\begin{funcdesc}{getdocsize}{} -\begin{sloppypar} -Return a pair of integers giving the size of the document as set by -\code{setdocsize()}. -\end{sloppypar} -\end{funcdesc} - -\begin{funcdesc}{getorigin}{} -Return a pair of integers giving the origin of the window with respect -to the document. -\end{funcdesc} - -\begin{funcdesc}{gettitle}{} -Return the window's title string. -\end{funcdesc} - -\begin{funcdesc}{getwinsize}{} -Return a pair of integers giving the size of the window. -\end{funcdesc} - -\begin{funcdesc}{getwinpos}{} -Return a pair of integers giving the position of the window's upper -left corner (relative to the upper left corner of the screen). -\end{funcdesc} - -\begin{funcdesc}{menucreate}{title} -Create a menu object referring to a local menu (a menu that appears -only in this window). -Methods of menu objects are described below. -\strong{Warning:} the menu only appears as long as the object -returned by this call exists. -\end{funcdesc} - -\begin{funcdesc}{scroll}{rect, point} -Scroll the given rectangle by the vector given by the point. -\end{funcdesc} - -\begin{funcdesc}{setdocsize}{point} -Set the size of the drawing document. -\end{funcdesc} - -\begin{funcdesc}{setorigin}{point} -Move the origin of the window (its upper left corner) -to the given point in the document. -\end{funcdesc} - -\begin{funcdesc}{setselection}{i, str} -Attempt to set X11 selection number -\var{i} -to the string -\var{str}. -(See stdwin method -\code{getselection()} -for the meaning of -\var{i}.) -Return true if it succeeds. -If succeeds, the window ``owns'' the selection until -(a) another application takes ownership of the selection; or -(b) the window is deleted; or -(c) the application clears ownership by calling -\code{stdwin.resetselection(\var{i})}. -When another application takes ownership of the selection, a -\code{WE_LOST_SEL} -event is received for no particular window and with the selection number -as detail. -Ignored on the Macintosh. -\end{funcdesc} - -\begin{funcdesc}{settimer}{dsecs} -Schedule a timer event for the window in -\code{\var{dsecs}/10} -seconds. -\end{funcdesc} - -\begin{funcdesc}{settitle}{title} -Set the window's title string. -\end{funcdesc} - -\begin{funcdesc}{setwincursor}{name} -\begin{sloppypar} -Set the window cursor to a cursor of the given name. -It raises the -\code{RuntimeError} -exception if no cursor of the given name exists. -Suitable names include -\code{'ibeam'}, -\code{'arrow'}, -\code{'cross'}, -\code{'watch'} -and -\code{'plus'}. -On X11, there are many more (see -\file{<X11/cursorfont.h>}). -\end{sloppypar} -\end{funcdesc} - -\begin{funcdesc}{setwinpos}{h, v} -Set the the position of the window's upper left corner (relative to -the upper left corner of the screen). -\end{funcdesc} - -\begin{funcdesc}{setwinsize}{width, height} -Set the window's size. -\end{funcdesc} - -\begin{funcdesc}{show}{rect} -Try to ensure that the given rectangle of the document is visible in -the window. -\end{funcdesc} - -\begin{funcdesc}{textcreate}{rect} -Create a text-edit object in the document at the given rectangle. -Methods of text-edit objects are described below. -\end{funcdesc} - -\begin{funcdesc}{setactive}{} -Attempt to make this window the active window. If successful, this -will generate a WE_ACTIVATE event (and a WE_DEACTIVATE event in case -another window in this application became inactive). -\end{funcdesc} - -\begin{funcdesc}{close}{} -Discard the window object. It should not be used again. -\end{funcdesc} - -\subsection{Drawing Objects} - -Drawing objects are created exclusively by the window method -\code{begindrawing()}. -Only one drawing object can exist at any given time; the drawing object -must be deleted to finish drawing. -No drawing object may exist when -\code{stdwin.getevent()} -is called. -Drawing objects have the following methods: - -\setindexsubitem{(drawing method)} - -\begin{funcdesc}{box}{rect} -Draw a box just inside a rectangle. -\end{funcdesc} - -\begin{funcdesc}{circle}{center, radius} -Draw a circle with given center point and radius. -\end{funcdesc} - -\begin{funcdesc}{elarc}{center, \(rh, rv\), \(a1, a2\)} -Draw an elliptical arc with given center point. -\code{(\var{rh}, \var{rv})} -gives the half sizes of the horizontal and vertical radii. -\code{(\var{a1}, \var{a2})} -gives the angles (in degrees) of the begin and end points. -0 degrees is at 3 o'clock, 90 degrees is at 12 o'clock. -\end{funcdesc} - -\begin{funcdesc}{erase}{rect} -Erase a rectangle. -\end{funcdesc} - -\begin{funcdesc}{fillcircle}{center, radius} -Draw a filled circle with given center point and radius. -\end{funcdesc} - -\begin{funcdesc}{fillelarc}{center, \(rh, rv\), \(a1, a2\)} -Draw a filled elliptical arc; arguments as for \code{elarc}. -\end{funcdesc} - -\begin{funcdesc}{fillpoly}{points} -Draw a filled polygon given by a list (or tuple) of points. -\end{funcdesc} - -\begin{funcdesc}{invert}{rect} -Invert a rectangle. -\end{funcdesc} - -\begin{funcdesc}{line}{p1, p2} -Draw a line from point -\var{p1} -to -\var{p2}. -\end{funcdesc} - -\begin{funcdesc}{paint}{rect} -Fill a rectangle. -\end{funcdesc} - -\begin{funcdesc}{poly}{points} -Draw the lines connecting the given list (or tuple) of points. -\end{funcdesc} - -\begin{funcdesc}{shade}{rect, percent} -Fill a rectangle with a shading pattern that is about -\var{percent} -percent filled. -\end{funcdesc} - -\begin{funcdesc}{text}{p, str} -Draw a string starting at point p (the point specifies the -top left coordinate of the string). -\end{funcdesc} - -\begin{funcdesc}{xorcircle}{center, radius} -\funcline{xorelarc}{center, \(rh, rv\), \(a1, a2\)} -\funcline{xorline}{p1, p2} -\funcline{xorpoly}{points} -Draw a circle, an elliptical arc, a line or a polygon, respectively, -in XOR mode. -\end{funcdesc} - -\begin{funcdesc}{setfgcolor}{} -\funcline{setbgcolor}{} -\funcline{getfgcolor}{} -\funcline{getbgcolor}{} -These functions are similar to the corresponding functions described -above for the -\code{stdwin} -module, but affect or return the colors currently used for drawing -instead of the global default colors. -When a drawing object is created, its colors are set to the window's -default colors, which are in turn initialized from the global default -colors when the window is created. -\end{funcdesc} - -\begin{funcdesc}{setfont}{} -\funcline{baseline}{} -\funcline{lineheight}{} -\funcline{textbreak}{} -\funcline{textwidth}{} -These functions are similar to the corresponding functions described -above for the -\code{stdwin} -module, but affect or use the current drawing font instead of -the global default font. -When a drawing object is created, its font is set to the window's -default font, which is in turn initialized from the global default -font when the window is created. -\end{funcdesc} - -\begin{funcdesc}{bitmap}{point, bitmap, mask} -Draw the \var{bitmap} with its top left corner at \var{point}. -If the optional \var{mask} argument is present, it should be either -the same object as \var{bitmap}, to draw only those bits that are set -in the bitmap, in the foreground color, or \code{None}, to draw all -bits (ones are drawn in the foreground color, zeros in the background -color). -Not available on the Macintosh. -\end{funcdesc} - -\begin{funcdesc}{cliprect}{rect} -Set the ``clipping region'' to a rectangle. -The clipping region limits the effect of all drawing operations, until -it is changed again or until the drawing object is closed. When a -drawing object is created the clipping region is set to the entire -window. When an object to be drawn falls partly outside the clipping -region, the set of pixels drawn is the intersection of the clipping -region and the set of pixels that would be drawn by the same operation -in the absence of a clipping region. -\end{funcdesc} - -\begin{funcdesc}{noclip}{} -Reset the clipping region to the entire window. -\end{funcdesc} - -\begin{funcdesc}{close}{} -\funcline{enddrawing}{} -Discard the drawing object. It should not be used again. -\end{funcdesc} - -\subsection{Menu Objects} - -A menu object represents a menu. -The menu is destroyed when the menu object is deleted. -The following methods are defined: - -\setindexsubitem{(menu method)} - -\begin{funcdesc}{additem}{text, shortcut} -Add a menu item with given text. -The shortcut must be a string of length 1, or omitted (to specify no -shortcut). -\end{funcdesc} - -\begin{funcdesc}{setitem}{i, text} -Set the text of item number -\var{i}. -\end{funcdesc} - -\begin{funcdesc}{enable}{i, flag} -Enable or disables item -\var{i}. -\end{funcdesc} - -\begin{funcdesc}{check}{i, flag} -Set or clear the -\dfn{check mark} -for item -\var{i}. -\end{funcdesc} - -\begin{funcdesc}{close}{} -Discard the menu object. It should not be used again. -\end{funcdesc} - -\subsection{Bitmap Objects} - -A bitmap represents a rectangular array of bits. -The top left bit has coordinate (0, 0). -A bitmap can be drawn with the \code{bitmap} method of a drawing object. -Bitmaps are currently not available on the Macintosh. - -The following methods are defined: - -\setindexsubitem{(bitmap method)} - -\begin{funcdesc}{getsize}{} -Return a tuple representing the width and height of the bitmap. -(This returns the values that have been passed to the \code{newbitmap} -function.) -\end{funcdesc} - -\begin{funcdesc}{setbit}{point, bit} -Set the value of the bit indicated by \var{point} to \var{bit}. -\end{funcdesc} - -\begin{funcdesc}{getbit}{point} -Return the value of the bit indicated by \var{point}. -\end{funcdesc} - -\begin{funcdesc}{close}{} -Discard the bitmap object. It should not be used again. -\end{funcdesc} - -\subsection{Text-edit Objects} - -A text-edit object represents a text-edit block. -For semantics, see the STDWIN documentation for C programmers. -The following methods exist: - -\setindexsubitem{(text-edit method)} - -\begin{funcdesc}{arrow}{code} -Pass an arrow event to the text-edit block. -The -\var{code} -must be one of -\code{WC_LEFT}, -\code{WC_RIGHT}, -\code{WC_UP} -or -\code{WC_DOWN} -(see module -\code{stdwinevents}). -\end{funcdesc} - -\begin{funcdesc}{draw}{rect} -Pass a draw event to the text-edit block. -The rectangle specifies the redraw area. -\end{funcdesc} - -\begin{funcdesc}{event}{type, window, detail} -Pass an event gotten from -\code{stdwin.getevent()} -to the text-edit block. -Return true if the event was handled. -\end{funcdesc} - -\begin{funcdesc}{getfocus}{} -Return 2 integers representing the start and end positions of the -focus, usable as slice indices on the string returned by -\code{gettext()}. -\end{funcdesc} - -\begin{funcdesc}{getfocustext}{} -Return the text in the focus. -\end{funcdesc} - -\begin{funcdesc}{getrect}{} -Return a rectangle giving the actual position of the text-edit block. -(The bottom coordinate may differ from the initial position because -the block automatically shrinks or grows to fit.) -\end{funcdesc} - -\begin{funcdesc}{gettext}{} -Return the entire text buffer. -\end{funcdesc} - -\begin{funcdesc}{move}{rect} -Specify a new position for the text-edit block in the document. -\end{funcdesc} - -\begin{funcdesc}{replace}{str} -Replace the text in the focus by the given string. -The new focus is an insert point at the end of the string. -\end{funcdesc} - -\begin{funcdesc}{setfocus}{i, j} -Specify the new focus. -Out-of-bounds values are silently clipped. -\end{funcdesc} - -\begin{funcdesc}{settext}{str} -Replace the entire text buffer by the given string and set the focus -to \code{(0, 0)}. -\end{funcdesc} - -\begin{funcdesc}{setview}{rect} -Set the view rectangle to \var{rect}. If \var{rect} is \code{None}, -viewing mode is reset. In viewing mode, all output from the text-edit -object is clipped to the viewing rectangle. This may be useful to -implement your own scrolling text subwindow. -\end{funcdesc} - -\begin{funcdesc}{close}{} -Discard the text-edit object. It should not be used again. -\end{funcdesc} - -\subsection{Example} -\nodename{STDWIN Example} - -Here is a minimal example of using STDWIN in Python. -It creates a window and draws the string ``Hello world'' in the top -left corner of the window. -The window will be correctly redrawn when covered and re-exposed. -The program quits when the close icon or menu item is requested. - -\begin{verbatim} -import stdwin -from stdwinevents import * - -def main(): - mywin = stdwin.open('Hello') - # - while 1: - (type, win, detail) = stdwin.getevent() - if type == WE_DRAW: - draw = win.begindrawing() - draw.text((0, 0), 'Hello, world') - del draw - elif type == WE_CLOSE: - break - -main() -\end{verbatim} -% -\section{Standard Module \module{stdwinevents}} -\label{module-stdwinevents} -\stmodindex{stdwinevents} - -This module defines constants used by STDWIN for event types -(\code{WE_ACTIVATE} etc.), command codes (\code{WC_LEFT} etc.) -and selection types (\code{WS_PRIMARY} etc.). -Read the file for details. -Suggested usage is - -\begin{verbatim} ->>> from stdwinevents import * ->>> -\end{verbatim} -% -\section{Standard Module \module{rect}} -\label{module-rect} -\stmodindex{rect} - -This module contains useful operations on rectangles. -A rectangle is defined as in module -\code{stdwin}: -a pair of points, where a point is a pair of integers. -For example, the rectangle - -\begin{verbatim} -(10, 20), (90, 80) -\end{verbatim} -% -is a rectangle whose left, top, right and bottom edges are 10, 20, 90 -and 80, respectively. -Note that the positive vertical axis points down (as in -\code{stdwin}). - -The module defines the following objects: - -\begin{excdesc}{error} -The exception raised by functions in this module when they detect an -error. -The exception argument is a string describing the problem in more -detail. -\end{excdesc} - -\begin{datadesc}{empty} -The rectangle returned when some operations return an empty result. -This makes it possible to quickly check whether a result is empty: - -\begin{verbatim} ->>> import rect ->>> r1 = (10, 20), (90, 80) ->>> r2 = (0, 0), (10, 20) ->>> r3 = rect.intersect([r1, r2]) ->>> if r3 is rect.empty: print 'Empty intersection' -Empty intersection ->>> -\end{verbatim} -\end{datadesc} - -\begin{funcdesc}{is_empty}{r} -Returns true if the given rectangle is empty. -A rectangle -\code{(\var{left}, \var{top}), (\var{right}, \var{bottom})} -is empty if -%begin{latexonly} -\iftexi -%end{latexonly} -\code{\var{left} >= \var{right}} or \code{\var{top} => \var{bottom}}. -%begin{latexonly} -\else -$\var{left} \geq \var{right}$ or $\var{top} \geq \var{bottom}$. -%%JHXXX\emph{left~$\geq$~right} or \emph{top~$\leq$~bottom}. -\fi -%end{latexonly} -\end{funcdesc} - -\begin{funcdesc}{intersect}{list} -Returns the intersection of all rectangles in the list argument. -It may also be called with a tuple argument. -Raises -\code{rect.error} -if the list is empty. -Returns -\code{rect.empty} -if the intersection of the rectangles is empty. -\end{funcdesc} - -\begin{funcdesc}{union}{list} -Returns the smallest rectangle that contains all non-empty rectangles in -the list argument. -It may also be called with a tuple argument or with two or more -rectangles as arguments. -Returns -\code{rect.empty} -if the list is empty or all its rectangles are empty. -\end{funcdesc} - -\begin{funcdesc}{pointinrect}{point, rect} -Returns true if the point is inside the rectangle. -By definition, a point -\code{(\var{h}, \var{v})} -is inside a rectangle -\code{(\var{left}, \var{top}), (\var{right}, \var{bottom})} if -%begin{latexonly} -\iftexi -%end{latexonly} -\code{\var{left} <= \var{h} < \var{right}} and -\code{\var{top} <= \var{v} < \var{bottom}}. -%begin{latexonly} -\else -$\var{left} \leq \var{h} < \var{right}$ and -$\var{top} \leq \var{v} < \var{bottom}$. -\fi -%end{latexonly} -\end{funcdesc} - -\begin{funcdesc}{inset}{rect, \(dh, dv\)} -Returns a rectangle that lies inside the -\code{rect} -argument by -\var{dh} -pixels horizontally -and -\var{dv} -pixels -vertically. -If -\var{dh} -or -\var{dv} -is negative, the result lies outside -\var{rect}. -\end{funcdesc} - -\begin{funcdesc}{rect2geom}{rect} -Converts a rectangle to geometry representation: -\code{(\var{left}, \var{top}), (\var{width}, \var{height})}. -\end{funcdesc} - -\begin{funcdesc}{geom2rect}{geom} -Converts a rectangle given in geometry representation back to the -standard rectangle representation -\code{(\var{left}, \var{top}), (\var{right}, \var{bottom})}. -\end{funcdesc} diff --git a/Doc/libstring.tex b/Doc/libstring.tex deleted file mode 100644 index 3939229..0000000 --- a/Doc/libstring.tex +++ /dev/null @@ -1,242 +0,0 @@ -\section{Standard Module \module{string}} -\label{module-string} -\stmodindex{string} - -This module defines some constants useful for checking character -classes and some useful string functions. See the module -\module{re}\refstmodindex{re} for string functions based on regular -expressions. - -The constants defined in this module are are: - -\begin{datadesc}{digits} - The string \code{'0123456789'}. -\end{datadesc} - -\begin{datadesc}{hexdigits} - The string \code{'0123456789abcdefABCDEF'}. -\end{datadesc} - -\begin{datadesc}{letters} - The concatenation of the strings \function{lowercase()} and - \function{uppercase()} described below. -\end{datadesc} - -\begin{datadesc}{lowercase} - A string containing all the characters that are considered lowercase - letters. On most systems this is the string - \code{'abcdefghijklmnopqrstuvwxyz'}. Do not change its definition --- - the effect on the routines \function{upper()} and - \function{swapcase()} is undefined. -\end{datadesc} - -\begin{datadesc}{octdigits} - The string \code{'01234567'}. -\end{datadesc} - -\begin{datadesc}{uppercase} - A string containing all the characters that are considered uppercase - letters. On most systems this is the string - \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. Do not change its definition --- - the effect on the routines \function{lower()} and - \function{swapcase()} is undefined. -\end{datadesc} - -\begin{datadesc}{whitespace} - A string containing all characters that are considered whitespace. - On most systems this includes the characters space, tab, linefeed, - return, formfeed, and vertical tab. Do not change its definition --- - the effect on the routines \function{strip()} and \function{split()} - is undefined. -\end{datadesc} - -The functions defined in this module are: - - -\begin{funcdesc}{atof}{s} -Convert a string to a floating point number. The string must have -the standard syntax for a floating point literal in Python, optionally -preceded by a sign (\samp{+} or \samp{-}). Note that this behaves -identical to the built-in function -\function{float()}\bifuncindex{float} when passed a string. -\end{funcdesc} - -\begin{funcdesc}{atoi}{s\optional{, base}} -Convert string \var{s} to an integer in the given \var{base}. The -string must consist of one or more digits, optionally preceded by a -sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it is -0, a default base is chosen depending on the leading characters of the -string (after stripping the sign): \samp{0x} or \samp{0X} means 16, -\samp{0} means 8, anything else means 10. If \var{base} is 16, a -leading \samp{0x} or \samp{0X} is always accepted. Note that when -invoked without \var{base} or with \var{base} set to 10, this behaves -identical to the built-in function \function{int()} when passed a string. -(Also note: for a more flexible interpretation of numeric literals, -use the built-in function \function{eval()}\bifuncindex{eval}.) -\end{funcdesc} - -\begin{funcdesc}{atol}{s\optional{, base}} -Convert string \var{s} to a long integer in the given \var{base}. The -string must consist of one or more digits, optionally preceded by a -sign (\samp{+} or \samp{-}). The \var{base} argument has the same -meaning as for \function{atoi()}. A trailing \samp{l} or \samp{L} is -not allowed, except if the base is 0. Note that when invoked without -\var{base} or with \var{base} set to 10, this behaves identical to the -built-in function \function{long()}\bifuncindex{long} when passed a -string. -\end{funcdesc} - -\begin{funcdesc}{capitalize}{word} -Capitalize the first character of the argument. -\end{funcdesc} - -\begin{funcdesc}{capwords}{s} -Split the argument into words using \function{split()}, capitalize -each word using \function{capitalize()}, and join the capitalized -words using \function{join()}. Note that this replaces runs of -whitespace characters by a single space, and removes leading and -trailing whitespace. -\end{funcdesc} - -\begin{funcdesc}{expandtabs}{s, tabsize} -Expand tabs in a string, i.e.\ replace them by one or more spaces, -depending on the current column and the given tab size. The column -number is reset to zero after each newline occurring in the string. -This doesn't understand other non-printing characters or escape -sequences. -\end{funcdesc} - -\begin{funcdesc}{find}{s, sub\optional{, start\optional{,end}}} -Return the lowest index in \var{s} where the substring \var{sub} is -found such that \var{sub} is wholly contained in -\code{\var{s}[\var{start}:\var{end}]}. Return \code{-1} on failure. -Defaults for \var{start} and \var{end} and interpretation of negative -values is the same as for slices. -\end{funcdesc} - -\begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}} -Like \function{find()} but find the highest index. -\end{funcdesc} - -\begin{funcdesc}{index}{s, sub\optional{, start\optional{, end}}} -Like \function{find()} but raise \exception{ValueError} when the -substring is not found. -\end{funcdesc} - -\begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}} -Like \function{rfind()} but raise \exception{ValueError} when the -substring is not found. -\end{funcdesc} - -\begin{funcdesc}{count}{s, sub\optional{, start\optional{, end}}} -Return the number of (non-overlapping) occurrences of substring -\var{sub} in string \code{\var{s}[\var{start}:\var{end}]}. -Defaults for \var{start} and \var{end} and interpretation of negative -values is the same as for slices. -\end{funcdesc} - -\begin{funcdesc}{lower}{s} -Convert letters to lower case. -\end{funcdesc} - -\begin{funcdesc}{maketrans}{from, to} -Return a translation table suitable for passing to -\function{translate()} or \function{regex.compile()}, that will map -each character in \var{from} into the character at the same position -in \var{to}; \var{from} and \var{to} must have the same length. -\end{funcdesc} - -\begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}} -Return a list of the words of the string \var{s}. If the optional -second argument \var{sep} is absent or \code{None}, the words are -separated by arbitrary strings of whitespace characters (space, tab, -newline, return, formfeed). If the second argument \var{sep} is -present and not \code{None}, it specifies a string to be used as the -word separator. The returned list will then have one more items than -the number of non-overlapping occurrences of the separator in the -string. The optional third argument \var{maxsplit} defaults to 0. If -it is nonzero, at most \var{maxsplit} number of splits occur, and the -remainder of the string is returned as the final element of the list -(thus, the list will have at most \code{\var{maxsplit}+1} elements). -\end{funcdesc} - -\begin{funcdesc}{splitfields}{s\optional{, sep\optional{, maxsplit}}} -This function behaves identically to \function{split()}. (In the -past, \function{split()} was only used with one argument, while -\function{splitfields()} was only used with two arguments.) -\end{funcdesc} - -\begin{funcdesc}{join}{words\optional{, sep}} -Concatenate a list or tuple of words with intervening occurrences of -\var{sep}. The default value for \var{sep} is a single space -character. It is always true that -\samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})} -equals \var{s}. -\end{funcdesc} - -\begin{funcdesc}{joinfields}{words\optional{, sep}} -This function behaves identical to \function{join()}. (In the past, -\function{join()} was only used with one argument, while -\function{joinfields()} was only used with two arguments.) -\end{funcdesc} - -\begin{funcdesc}{lstrip}{s} -Remove leading whitespace from the string \var{s}. -\end{funcdesc} - -\begin{funcdesc}{rstrip}{s} -Remove trailing whitespace from the string \var{s}. -\end{funcdesc} - -\begin{funcdesc}{strip}{s} -Remove leading and trailing whitespace from the string \var{s}. -\end{funcdesc} - -\begin{funcdesc}{swapcase}{s} -Convert lower case letters to upper case and vice versa. -\end{funcdesc} - -\begin{funcdesc}{translate}{s, table\optional{, deletechars}} -Delete all characters from \var{s} that are in \var{deletechars} (if -present), and then translate the characters using \var{table}, which -must be a 256-character string giving the translation for each -character value, indexed by its ordinal. -\end{funcdesc} - -\begin{funcdesc}{upper}{s} -Convert letters to upper case. -\end{funcdesc} - -\begin{funcdesc}{ljust}{s, width} -\funcline{rjust}{s, width} -\funcline{center}{s, width} -These functions respectively left-justify, right-justify and center a -string in a field of given width. -They return a string that is at least -\var{width} -characters wide, created by padding the string -\var{s} -with spaces until the given width on the right, left or both sides. -The string is never truncated. -\end{funcdesc} - -\begin{funcdesc}{zfill}{s, width} -Pad a numeric string on the left with zero digits until the given -width is reached. Strings starting with a sign are handled correctly. -\end{funcdesc} - -\begin{funcdesc}{replace}{str, old, new\optional{, maxsplit}} -Return a copy of string \var{str} with all occurrences of substring -\var{old} replaced by \var{new}. If the optional argument -\var{maxsplit} is given, the first \var{maxsplit} occurrences are -replaced. -\end{funcdesc} - -This module is implemented in Python. Much of its functionality has -been reimplemented in the built-in module -\module{strop}\refbimodindex{strop}. However, you -should \emph{never} import the latter module directly. When -\module{string} discovers that \module{strop} exists, it transparently -replaces parts of itself with the implementation from \module{strop}. -After initialization, there is \emph{no} overhead in using -\module{string} instead of \module{strop}. diff --git a/Doc/libstrings.tex b/Doc/libstrings.tex deleted file mode 100644 index 7294002..0000000 --- a/Doc/libstrings.tex +++ /dev/null @@ -1,30 +0,0 @@ -\chapter{String Services} -\label{strings} - -The modules described in this chapter provide a wide range of string -manipulation operations. Here's an overview: - -\begin{description} - -\item[string] ---- Common string operations. - -\item[re] ---- New Perl-style regular expression search and match operations. - -\item[regex] ---- Regular expression search and match operations. - -\item[regsub] ---- Substitution and splitting operations that use regular expressions. - -\item[struct] ---- Interpret strings as packed binary data. - -\item[StringIO] ---- Read and write strings as if they were files. - -\item[cStringIO] ---- Faster version of \module{StringIO}, but not subclassable. - -\end{description} diff --git a/Doc/libstrio.tex b/Doc/libstrio.tex deleted file mode 100644 index 86ebf46..0000000 --- a/Doc/libstrio.tex +++ /dev/null @@ -1,42 +0,0 @@ -\section{Standard Module \module{StringIO}} -\label{module-StringIO} - -\stmodindex{StringIO} - -This module implements a file-like class, \class{StringIO}, -that reads and writes a string buffer (also known as \emph{memory -files}). See the description on file objects for operations. - -\begin{classdesc}{StringIO}{\optional{buffer}} -When a \class{StringIO} object is created, it can be initialized -to an existing string by passing the string to the constructor. -If no string is given, the \class{StringIO} will start empty. -\end{classdesc} - -The following methods of \class{StringIO} objects require special -mention: - -\begin{methoddesc}{getvalue}{} -Retrieve the entire contents of the ``file'' at any time before the -\class{StringIO} object's \method{close()} method is called. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Free the memory buffer. -\end{methoddesc} - - -\section{Built-in Module \module{cStringIO}} -\bimodindex{cStringIO} -\label{module-cStringIO} - -% This section was written by Fred L. Drake, Jr. <fdrake@acm.org> - -The module \module{cStringIO} provides an interface similar to that of -the \module{StringIO} module. Heavy use of \class{StringIO.StringIO} -objects can be made more efficient by using the function -\function{StringIO()} from this module instead. - -Since this module provides a factory function which returns objects of -built-in types, there's no way to build your own version using -subclassing. Use the original \module{StringIO} module in that case. diff --git a/Doc/libstruct.tex b/Doc/libstruct.tex deleted file mode 100644 index 5925328..0000000 --- a/Doc/libstruct.tex +++ /dev/null @@ -1,140 +0,0 @@ -\section{Built-in Module \module{struct}} -\label{module-struct} -\bimodindex{struct} -\indexii{C@\C{}}{structures} - -This module performs conversions between Python values and C -structs represented as Python strings. It uses \dfn{format strings} -(explained below) as compact descriptions of the lay-out of the C -structs and the intended conversion to/from Python values. - -The module defines the following exception and functions: - - -\begin{excdesc}{error} - Exception raised on various occasions; argument is a string - describing what is wrong. -\end{excdesc} - -\begin{funcdesc}{pack}{fmt, v1, v2, {\rm \ldots}} - Return a string containing the values - \code{\var{v1}, \var{v2}, {\rm \ldots}} packed according to the given - format. The arguments must match the values required by the format - exactly. -\end{funcdesc} - -\begin{funcdesc}{unpack}{fmt, string} - Unpack the string (presumably packed by \code{pack(\var{fmt}, {\rm \ldots})}) - according to the given format. The result is a tuple even if it - contains exactly one item. The string must contain exactly the - amount of data required by the format (i.e. \code{len(\var{string})} must - equal \code{calcsize(\var{fmt})}). -\end{funcdesc} - -\begin{funcdesc}{calcsize}{fmt} - Return the size of the struct (and hence of the string) - corresponding to the given format. -\end{funcdesc} - -Format characters have the following meaning; the conversion between C -and Python values should be obvious given their types: - -\begin{tableiii}{c|l|l}{samp}{Format}{C Type}{Python} - \lineiii{x}{pad byte}{no value} - \lineiii{c}{char}{string of length 1} - \lineiii{b}{signed char}{integer} - \lineiii{B}{unsigned char}{integer} - \lineiii{h}{short}{integer} - \lineiii{H}{unsigned short}{integer} - \lineiii{i}{int}{integer} - \lineiii{I}{unsigned int}{integer} - \lineiii{l}{long}{integer} - \lineiii{L}{unsigned long}{integer} - \lineiii{f}{float}{float} - \lineiii{d}{double}{float} - \lineiii{s}{char[]}{string} -\end{tableiii} - -A format character may be preceded by an integral repeat count; e.g.\ -the format string \code{'4h'} means exactly the same as \code{'hhhh'}. - -Whitespace characters between formats are ignored; a count and its -format must not contain whitespace though. - -For the \code{'s'} format character, the count is interpreted as the -size of the string, not a repeat count like for the other format -characters; e.g. \code{'10s'} means a single 10-byte string, while -\code{'10c'} means 10 characters. For packing, the string is -truncated or padded with null bytes as appropriate to make it fit. -For unpacking, the resulting string always has exactly the specified -number of bytes. As a special case, \code{'0s'} means a single, empty -string (while \code{'0c'} means 0 characters). - -For the \code{'I'} and \code{'L'} format characters, the return -value is a Python long integer. - -By default, C numbers are represented in the machine's native format -and byte order, and properly aligned by skipping pad bytes if -necessary (according to the rules used by the C compiler). - -Alternatively, the first character of the format string can be used to -indicate the byte order, size and alignment of the packed data, -according to the following table: - -\begin{tableiii}{c|l|l}{samp}{Character}{Byte order}{Size and alignment} - \lineiii{@}{native}{native} - \lineiii{=}{native}{standard} - \lineiii{<}{little-endian}{standard} - \lineiii{>}{big-endian}{standard} - \lineiii{!}{network (= big-endian)}{standard} -\end{tableiii} - -If the first character is not one of these, \code{'@'} is assumed. - -Native byte order is big-endian or little-endian, depending on the -host system (e.g. Motorola and Sun are big-endian; Intel and DEC are -little-endian). - -Native size and alignment are determined using the C compiler's sizeof -expression. This is always combined with native byte order. - -Standard size and alignment are as follows: no alignment is required -for any type (so you have to use pad bytes); short is 2 bytes; int and -long are 4 bytes. Float and double are 32-bit and 64-bit IEEE floating -point numbers, respectively. - -Note the difference between \code{'@'} and \code{'='}: both use native -byte order, but the size and alignment of the latter is standardized. - -The form \code{'!'} is available for those poor souls who claim they -can't remember whether network byte order is big-endian or -little-endian. - -There is no way to indicate non-native byte order (i.e. force -byte-swapping); use the appropriate choice of \code{'<'} or -\code{'>'}. - -Examples (all using native byte order, size and alignment, on a -big-endian machine): - -\begin{verbatim} ->>> from struct import * ->>> pack('hhl', 1, 2, 3) -'\000\001\000\002\000\000\000\003' ->>> unpack('hhl', '\000\001\000\002\000\000\000\003') -(1, 2, 3) ->>> calcsize('hhl') -8 ->>> -\end{verbatim} -% -Hint: to align the end of a structure to the alignment requirement of -a particular type, end the format with the code for that type with a -repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two -pad bytes at the end, assuming longs are aligned on 4-byte boundaries. -This only works when native size and alignment are in effect; -standard size and alignment does not enforce any alignment. - -\begin{seealso} -\seemodule{array}{packed binary storage of homogeneous data} -\end{seealso} diff --git a/Doc/libsun.tex b/Doc/libsun.tex deleted file mode 100644 index 25826cd..0000000 --- a/Doc/libsun.tex +++ /dev/null @@ -1,6 +0,0 @@ -\chapter{SunOS Specific Services} -\label{sunos} - -The modules described in this chapter provide interfaces to features -that are unique to the SunOS operating system (versions 4 and 5; the -latter is also known as Solaris version 2). diff --git a/Doc/libsunaudio.tex b/Doc/libsunaudio.tex deleted file mode 100644 index c43d611..0000000 --- a/Doc/libsunaudio.tex +++ /dev/null @@ -1,108 +0,0 @@ -\section{Built-in Module \module{sunaudiodev}} -\label{module-sunaudiodev} -\bimodindex{sunaudiodev} - -This module allows you to access the sun audio interface. The sun -audio hardware is capable of recording and playing back audio data -in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A -full description can be found in the \manpage{audio}{7I} manual page. - -The module defines the following variables and functions: - -\begin{excdesc}{error} -This exception is raised on all errors. The argument is a string -describing what went wrong. -\end{excdesc} - -\begin{funcdesc}{open}{mode} -This function opens the audio device and returns a sun audio device -object. This object can then be used to do I/O on. The \var{mode} parameter -is one of \code{'r'} for record-only access, \code{'w'} for play-only -access, \code{'rw'} for both and \code{'control'} for access to the -control device. Since only one process is allowed to have the recorder -or player open at the same time it is a good idea to open the device -only for the activity needed. See \manpage{audio}{7I} for details. -\end{funcdesc} - - -\subsection{Audio Device Objects} -\label{audio-device-objects} - -The audio device objects are returned by \function{open()} define the -following methods (except \code{control} objects which only provide -\method{getinfo()}, \method{setinfo()} and \method{drain()}): - -\begin{methoddesc}[audio device]{close}{} -This method explicitly closes the device. It is useful in situations -where deleting the object does not immediately close it since there -are other references to it. A closed device should not be used again. -\end{methoddesc} - -\begin{methoddesc}[audio device]{drain}{} -This method waits until all pending output is processed and then returns. -Calling this method is often not necessary: destroying the object will -automatically close the audio device and this will do an implicit drain. -\end{methoddesc} - -\begin{methoddesc}[audio device]{flush}{} -This method discards all pending output. It can be used avoid the -slow response to a user's stop request (due to buffering of up to one -second of sound). -\end{methoddesc} - -\begin{methoddesc}[audio device]{getinfo}{} -This method retrieves status information like input and output volume, -etc. and returns it in the form of -an audio status object. This object has no methods but it contains a -number of attributes describing the current device status. The names -and meanings of the attributes are described in -\file{/usr/include/sun/audioio.h} and in the \manpage{audio}{7I} -manual page. Member names -are slightly different from their \C{} counterparts: a status object is -only a single structure. Members of the \cdata{play} substructure have -\samp{o_} prepended to their name and members of the \cdata{record} -structure have \samp{i_}. So, the \C{} member \cdata{play.sample_rate} is -accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain} -and \cdata{monitor_gain} plainly as \member{monitor_gain}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{ibufcount}{} -This method returns the number of samples that are buffered on the -recording side, i.e.\ the program will not block on a -\function{read()} call of so many samples. -\end{methoddesc} - -\begin{methoddesc}[audio device]{obufcount}{} -This method returns the number of samples buffered on the playback -side. Unfortunately, this number cannot be used to determine a number -of samples that can be written without blocking since the kernel -output queue length seems to be variable. -\end{methoddesc} - -\begin{methoddesc}[audio device]{read}{size} -This method reads \var{size} samples from the audio input and returns -them as a Python string. The function blocks until enough data is available. -\end{methoddesc} - -\begin{methoddesc}[audio device]{setinfo}{status} -This method sets the audio device status parameters. The \var{status} -parameter is an device status object as returned by \function{getinfo()} and -possibly modified by the program. -\end{methoddesc} - -\begin{methoddesc}[audio device]{write}{samples} -Write is passed a Python string containing audio samples to be played. -If there is enough buffer space free it will immediately return, -otherwise it will block. -\end{methoddesc} - -There is a companion module, -\module{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV}, which defines useful -symbolic constants like \constant{MIN_GAIN}, \constant{MAX_GAIN}, -\constant{SPEAKER}, etc. The names of the constants are the same names -as used in the \C{} include file \code{<sun/audioio.h>}, with the -leading string \samp{AUDIO_} stripped. - -Useability of the control device is limited at the moment, since there -is no way to use the ``wait for something to happen'' feature the -device provides. diff --git a/Doc/libsymbol.tex b/Doc/libsymbol.tex deleted file mode 100644 index 0761405..0000000 --- a/Doc/libsymbol.tex +++ /dev/null @@ -1,24 +0,0 @@ -\section{Standard Module \module{symbol}} -\label{module-symbol} -\stmodindex{symbol} - -This module provides constants which represent the numeric values of -internal nodes of the parse tree. Unlike most Python constants, these -use lower-case names. Refer to the file \file{Grammar/Grammar} in the -Python distribution for the defintions of the names in the context of -the language grammar. The specific numeric values which the names map -to may change between Python versions. - -This module also provides one additional data object: - - - -\begin{datadesc}{sym_name} -Dictionary mapping the numeric values of the constants defined in this -module back to name strings, allowing more human-readable -representation of parse trees to be generated. -\end{datadesc} - -\begin{seealso} -\seemodule{parser}{second example uses this module} -\end{seealso} diff --git a/Doc/libsys.tex b/Doc/libsys.tex deleted file mode 100644 index 1dac264..0000000 --- a/Doc/libsys.tex +++ /dev/null @@ -1,249 +0,0 @@ -\section{Built-in Module \module{sys}} -\label{module-sys} - -\bimodindex{sys} -This module provides access to some variables used or maintained by the -interpreter and to functions that interact strongly with the interpreter. -It is always available. - - -\begin{datadesc}{argv} - The list of command line arguments passed to a Python script. - \code{argv[0]} is the script name (it is operating system - dependent whether this is a full pathname or not). - If the command was executed using the \samp{-c} command line option - to the interpreter, \code{argv[0]} is set to the string - \code{"-c"}. - If no script name was passed to the Python interpreter, - \code{argv} has zero length. -\end{datadesc} - -\begin{datadesc}{builtin_module_names} - A tuple of strings giving the names of all modules that are compiled - into this Python interpreter. (This information is not available in - any other way --- \code{modules.keys()} only lists the imported - modules.) -\end{datadesc} - -\begin{funcdesc}{exc_info}{} -This function returns a tuple of three values that give information -about the exception that is currently being handled. The information -returned is specific both to the current thread and to the current -stack frame. If the current stack frame is not handling an exception, -the information is taken from the calling stack frame, or its caller, -and so on until a stack frame is found that is handling an exception. -Here, ``handling an exception'' is defined as ``executing or having -executed an except clause.'' For any stack frame, only -information about the most recently handled exception is accessible. - -If no exception is being handled anywhere on the stack, a tuple -containing three \code{None} values is returned. Otherwise, the -values returned are -\code{(\var{type}, \var{value}, \var{traceback})}. -Their meaning is: \var{type} gets the exception type of the exception -being handled (a string or class object); \var{value} gets the -exception parameter (its \dfn{associated value} or the second argument -to \keyword{raise}, which is always a class instance if the exception -type is a class object); \var{traceback} gets a traceback object (see -the Reference Manual) which encapsulates the call stack at the point -where the exception originally occurred. -\obindex{traceback} - -\strong{Warning:} assigning the \var{traceback} return value to a -local variable in a function that is handling an exception will cause -a circular reference. This will prevent anything referenced by a local -variable in the same function or by the traceback from being garbage -collected. Since most functions don't need access to the traceback, -the best solution is to use something like -\code{type, value = sys.exc_info()[:2]} -to extract only the exception type and value. If you do need the -traceback, make sure to delete it after use (best done with a -\keyword{try} ... \keyword{finally} statement) or to call -\function{exc_info()} in a function that does not itself handle an -exception. -\end{funcdesc} - -\begin{datadesc}{exc_type} -\dataline{exc_value} -\dataline{exc_traceback} -\deprecated {1.5} - {Use \function{exc_info()} instead.} -Since they are global variables, they are not specific to the current -thread, so their use is not safe in a multi-threaded program. When no -exception is being handled, \code{exc_type} is set to \code{None} and -the other two are undefined. -\end{datadesc} - -\begin{datadesc}{exec_prefix} -A string giving the site-specific -directory prefix where the platform-dependent Python files are -installed; by default, this is also \code{"/usr/local"}. This can be -set at build time with the \code{-}\code{-exec-prefix} argument to the -\program{configure} script. Specifically, all configuration files -(e.g. the \file{config.h} header file) are installed in the directory -\code{exec_prefix + "/lib/python\var{version}/config"}, and shared library -modules are installed in -\code{exec_prefix + "/lib/python\var{version}/lib-dynload"}, -where \var{version} is equal to \code{version[:3]}. -\end{datadesc} - -\begin{funcdesc}{exit}{n} - Exit from Python with numeric exit status \var{n}. This is - implemented by raising the \exception{SystemExit} exception, so cleanup - actions specified by finally clauses of \keyword{try} statements - are honored, and it is possible to catch the exit attempt at an outer - level. -\end{funcdesc} - -\begin{datadesc}{exitfunc} - This value is not actually defined by the module, but can be set by - the user (or by a program) to specify a clean-up action at program - exit. When set, it should be a parameterless function. This function - will be called when the interpreter exits in any way (except when a - fatal error occurs: in that case the interpreter's internal state - cannot be trusted). -\end{datadesc} - -\begin{funcdesc}{getrefcount}{object} -Return the reference count of the \var{object}. The count returned is -generally one higher than you might expect, because it includes the -(temporary) reference as an argument to \code{getrefcount()}. -\end{funcdesc} - -\begin{datadesc}{last_type} -\dataline{last_value} -\dataline{last_traceback} -These three variables are not always defined; they are set when an -exception is not handled and the interpreter prints an error message -and a stack traceback. Their intended use is to allow an interactive -user to import a debugger module and engage in post-mortem debugging -without having to re-execute the command that caused the error. -(Typical use is \samp{import pdb; pdb.pm()} to enter the post-mortem -debugger; see the chapter ``The Python Debugger'' for more -information.) -\refstmodindex{pdb} - -The meaning of the variables is the same -as that of the return values from \function{exc_info()} above. -(Since there is only one interactive thread, thread-safety is not a -concern for these variables, unlike for \code{exc_type} etc.) -\end{datadesc} - -\begin{datadesc}{modules} - This is a dictionary that maps module names to modules which have - already been loaded. This can be manipulated to force reloading of - modules and other tricks. Note that removing a module from this - dictionary is \emph{not} the same as calling - \function{reload()}\bifuncindex{reload} on the corresponding module - object. -\end{datadesc} - -\begin{datadesc}{path} -\indexiii{module}{search}{path} - A list of strings that specifies the search path for modules. - Initialized from the environment variable \code{\$PYTHONPATH}, or an - installation-dependent default. - -The first item of this list, \code{path[0]}, is the -directory containing the script that was used to invoke the Python -interpreter. If the script directory is not available (e.g. if the -interpreter is invoked interactively or if the script is read from -standard input), \code{path[0]} is the empty string, which directs -Python to search modules in the current directory first. Notice that -the script directory is inserted \emph{before} the entries inserted as -a result of \code{\$PYTHONPATH}. -\end{datadesc} - -\begin{datadesc}{platform} -This string contains a platform identifier, e.g. \code{'sunos5'} or -\code{'linux1'}. This can be used to append platform-specific -components to \code{path}, for instance. -\end{datadesc} - -\begin{datadesc}{prefix} -A string giving the site-specific directory prefix where the platform -independent Python files are installed; by default, this is the string -\code{"/usr/local"}. This can be set at build time with the -\code{-}\code{-prefix} argument to the \program{configure} script. The main -collection of Python library modules is installed in the directory -\code{prefix + "/lib/python\var{version}"} while the platform -independent header files (all except \file{config.h}) are stored in -\code{prefix + "/include/python\var{version}"}, -where \var{version} is equal to \code{version[:3]}. - -\end{datadesc} - -\begin{datadesc}{ps1} -\dataline{ps2} -\index{interpreter prompts} -\index{prompts, interpreter} - Strings specifying the primary and secondary prompt of the - interpreter. These are only defined if the interpreter is in - interactive mode. Their initial values in this case are - \code{'>>> '} and \code{'... '}. If a non-string object is assigned - to either variable, its \function{str()} is re-evaluated each time - the interpreter prepares to read a new interactive command; this can - be used to implement a dynamic prompt. -\end{datadesc} - -\begin{funcdesc}{setcheckinterval}{interval} -Set the interpreter's ``check interval''. This integer value -determines how often the interpreter checks for periodic things such -as thread switches and signal handlers. The default is \code{10}, meaning -the check is performed every 10 Python virtual instructions. Setting -it to a larger value may increase performance for programs using -threads. Setting it to a value \code{<=} 0 checks every virtual instruction, -maximizing responsiveness as well as overhead. -\end{funcdesc} - -\begin{funcdesc}{settrace}{tracefunc} - Set the system's trace function, which allows you to implement a - Python source code debugger in Python. See section ``How It Works'' - in the chapter on the Python Debugger. -\end{funcdesc} -\index{trace function} -\index{debugger} - -\begin{funcdesc}{setprofile}{profilefunc} - Set the system's profile function, which allows you to implement a - Python source code profiler in Python. See the chapter on the - Python Profiler. The system's profile function - is called similarly to the system's trace function (see - \function{settrace()}), but it isn't called for each executed line of - code (only on call and return and when an exception occurs). Also, - its return value is not used, so it can just return \code{None}. -\end{funcdesc} -\index{profile function} -\index{profiler} - -\begin{datadesc}{stdin} -\dataline{stdout} -\dataline{stderr} - File objects corresponding to the interpreter's standard input, - output and error streams. \code{stdin} is used for all - interpreter input except for scripts but including calls to - \function{input()}\bifuncindex{input} and - \function{raw_input()}\bifuncindex{raw_input}. \code{stdout} is used - for the output of \keyword{print} and expression statements and for the - prompts of \function{input()} and \function{raw_input()}. The interpreter's - own prompts and (almost all of) its error messages go to - \code{stderr}. \code{stdout} and \code{stderr} needn't - be built-in file objects: any object is acceptable as long as it has - a \method{write()} method that takes a string argument. (Changing these - objects doesn't affect the standard I/O streams of processes - executed by \function{os.popen()}, \function{os.system()} or the - \function{exec*()} family of functions in the \module{os} module.) -\refstmodindex{os} -\end{datadesc} - -\begin{datadesc}{tracebacklimit} -When this variable is set to an integer value, it determines the -maximum number of levels of traceback information printed when an -unhandled exception occurs. The default is \code{1000}. When set to -0 or less, all traceback information is suppressed and only the -exception type and value are printed. -\end{datadesc} - -\begin{datadesc}{version} -A string containing the version number of the Python interpreter. -\end{datadesc} diff --git a/Doc/libsyslog.tex b/Doc/libsyslog.tex deleted file mode 100644 index 3e5b166..0000000 --- a/Doc/libsyslog.tex +++ /dev/null @@ -1,71 +0,0 @@ -\section{Built-in Module \module{syslog}} -\label{module-syslog} -\bimodindex{syslog} - -This module provides an interface to the \UNIX{} \code{syslog} library -routines. Refer to the \UNIX{} manual pages for a detailed description -of the \code{syslog} facility. - -The module defines the following functions: - - -\begin{funcdesc}{syslog}{\optional{priority,} message} -Send the string \var{message} to the system logger. A trailing -newline is added if necessary. Each message is tagged with a priority -composed of a \var{facility} and a \var{level}. The optional -\var{priority} argument, which defaults to \constant{LOG_INFO}, -determines the message priority. If the facility is not encoded in -\var{priority} using logical-or (\code{LOG_INFO | LOG_USER}), the -value given in the \function{openlog()} call is used. -\end{funcdesc} - -\begin{funcdesc}{openlog}{ident\optional{, logopt\optional{, facility}}} -Logging options other than the defaults can be set by explicitly -opening the log file with \function{openlog()} prior to calling -\function{syslog()}. The defaults are (usually) \var{ident} = -\code{'syslog'}, \var{logopt} = \code{0}, \var{facility} = -\constant{LOG_USER}. The \var{ident} argument is a string which is -prepended to every message. The optional \var{logopt} argument is a -bit field - see below for possible values to combine. The optional -\var{facility} argument sets the default facility for messages which -do not have a facility explicitly encoded. -\end{funcdesc} - -\begin{funcdesc}{closelog}{} -Close the log file. -\end{funcdesc} - -\begin{funcdesc}{setlogmask}{maskpri} -This function set the priority mask to \var{maskpri} and returns the -previous mask value. Calls to \function{syslog()} with a priority -level not set in \var{maskpri} are ignored. The default is to log all -priorities. The function \code{LOG_MASK(\var{pri})} calculates the -mask for the individual priority \var{pri}. The function -\code{LOG_UPTO(\var{pri})} calculates the mask for all priorities up -to and including \var{pri}. -\end{funcdesc} - -The module defines the following constants: - -\begin{description} - -\item[Priority levels (high to low):] - -\constant{LOG_EMERG}, \constant{LOG_ALERT}, \constant{LOG_CRIT}, -\constant{LOG_ERR}, \constant{LOG_WARNING}, \constant{LOG_NOTICE}, -\constant{LOG_INFO}, \constant{LOG_DEBUG}. - -\item[Facilities:] - -\constant{LOG_KERN}, \constant{LOG_USER}, \constant{LOG_MAIL}, -\constant{LOG_DAEMON}, \constant{LOG_AUTH}, \constant{LOG_LPR}, -\constant{LOG_NEWS}, \constant{LOG_UUCP}, \constant{LOG_CRON} and -\constant{LOG_LOCAL0} to \constant{LOG_LOCAL7}. - -\item[Log options:] - -\constant{LOG_PID}, \constant{LOG_CONS}, \constant{LOG_NDELAY}, -\constant{LOG_NOWAIT} and \constant{LOG_PERROR} if defined in -\code{<syslog.h>}. - -\end{description} diff --git a/Doc/libtempfile.tex b/Doc/libtempfile.tex deleted file mode 100644 index 93577e7..0000000 --- a/Doc/libtempfile.tex +++ /dev/null @@ -1,49 +0,0 @@ -\section{Standard Module \module{tempfile}} -\label{module-tempfile} -\stmodindex{tempfile} -\indexii{temporary}{file name} -\indexii{temporary}{file} - - -This module generates temporary file names. It is not \UNIX{} specific, -but it may require some help on non-\UNIX{} systems. - -Note: the modules does not create temporary files, nor does it -automatically remove them when the current process exits or dies. - -The module defines a single user-callable function: - -\begin{funcdesc}{mktemp}{} -Return a unique temporary filename. This is an absolute pathname of a -file that does not exist at the time the call is made. No two calls -will return the same filename. -\end{funcdesc} - -The module uses two global variables that tell it how to construct a -temporary name. The caller may assign values to them; by default they -are initialized at the first call to \function{mktemp()}. - -\begin{datadesc}{tempdir} -When set to a value other than \code{None}, this variable defines the -directory in which filenames returned by \function{mktemp()} reside. -The default is taken from the environment variable \envvar{TMPDIR}; if -this is not set, either \file{/usr/tmp} is used (on \UNIX{}), or the -current working directory (all other systems). No check is made to -see whether its value is valid. -\end{datadesc} - -\begin{datadesc}{template} -When set to a value other than \code{None}, this variable defines the -prefix of the final component of the filenames returned by -\function{mktemp()}. A string of decimal digits is added to generate -unique filenames. The default is either \file{@\var{pid}.} where -\var{pid} is the current process ID (on \UNIX{}), or \file{tmp} (all -other systems). -\end{datadesc} - -\strong{Warning:} if a \UNIX{} process uses \code{mktemp()}, then -calls \function{fork()} and both parent and child continue to use -\function{mktemp()}, the processes will generate conflicting temporary -names. To resolve this, the child process should assign \code{None} -to \code{template}, to force recomputing the default on the next call -to \function{mktemp()}. diff --git a/Doc/libtemplate.tex b/Doc/libtemplate.tex deleted file mode 100644 index d190506..0000000 --- a/Doc/libtemplate.tex +++ /dev/null @@ -1,140 +0,0 @@ -% Template for a library manual section. -% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE - - -% ==== 1. ==== -% Choose one of the following section headers and index entries; -% \section generates the section header, -% \bimodindex or \stmodindex generates an index entry for this -% module. Note that these should only be used for the defining entry -% for the module. Other references to the module should use -% \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as -% appropriate. (Just prepend "ref" to the csname of the \*modindex -% macro used in the module definition.) -% -% The \label{module-spam} line is for the \seealso command. - -\section{Built-in Module \module{spam}} % If implemented in C, in -\bimodindex{spam} % standard library - -\section{Standard Module \module{spam}} % If implemented in Python, in -\stmodindex{spam} % standard library - -\section{Extension Module \module{spam}}% If implemented in C, but not -\exmodindex{spam} % in standard library - -\section{Module \module{spam}} % If implemented in Python, but not -\modindex{spam} % in standard library - -\label{module-spam} - -% ==== 2. ==== -% Give a short overview of what the module does. -% If it is platform specific, mention this. -% Mention other important restrictions or general operating principles. -% For example: - -The \module{spam} module defines operations for handling cans of Spam. -It knows the four generally available Spam varieties and understands -both can sizes. - -Because spamification requires \UNIX{} process management, the module -is only available on genuine \UNIX{} systems. - - -% ==== 3. ==== -% List the public functions defined by the module. Begin with a -% standard phrase. You may also list the exceptions and other data -% items defined in the module, insofar as they are important for the -% user. - -The \module{spam} module defines the following functions: - -% ---- 3.1. ---- -% For each function, use a ``funcdesc'' block. This has exactly two -% parameters (each parameters is contained in a set of curly braces): -% the first parameter is the function name (this automatically -% generates an index entry); the second parameter is the function's -% argument list. If there are no arguments, use an empty pair of -% curly braces. If there is more than one argument, separate the -% arguments with backslash-comma. Optional parts of the parameter -% list are contained in \optional{...} (this generates a set of square -% brackets around its parameter). Arguments are automatically set in -% italics in the parameter list. Each argument should be mentioned at -% least once in the description; each usage (even inside \code{...}) -% should be enclosed in \var{...}. - -\begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}} -Open the file \var{filename} as a can of Spam. The optional -\var{mode} and \var{buffersize} arguments specify the read-write mode -(\code{'r'} (default) or \code{'w'}) and the buffer size (default: -system dependent). -\end{funcdesc} - -% ---- 3.2. ---- -% Data items are described using a ``datadesc'' block. This has only -% one parameter: the item's name. - -\begin{datadesc}{cansize} -The default can size, in ounces. Legal values are 7 and 12. The -default varies per supermarket. This variable should not be changed -once the \function{open()} function has been called. -\end{datadesc} - -% --- 3.3. --- -% Exceptions are described using a ``excdesc'' block. This has only -% one parameter: the exception name. - -\begin{excdesc}{error} -Exception raised when an operation fails for a Spam specific reason. -The exception argument is a string describing the reason of the -failure. -\end{excdesc} - -% ---- 3.4. ---- -% Other standard environments: -% -% classdesc - Python classes; same arguments are funcdesc -% methoddesc - methods, like funcdesc but has an optional parameter -% to give the type name: \begin{methoddesc}[mytype]{name}{args} -% By default, the type name will be the name of the -% last class defined using classdesc. The type name -% is required if the type is implemented in C (because -% there's no classdesc) or if the class isn't directly -% documented (if it's private). -% memberdesc - data members, like datadesc, but with an optional -% type name like methoddesc. - - -% ==== 4. ==== -% Now is probably a good time for a complete example. (Alternatively, -% an example giving the flavor of the module may be given before the -% detailed list of functions.) - -Example: - -\begin{verbatim} ->>> import spam ->>> can = spam.open('/etc/passwd') ->>> can.empty() ->>> can.close() -\end{verbatim} -% Note that there is no trailing ">>> " prompt shown. - -% ==== 5. ==== -% If your module defines new object types (for a built-in module) or -% classes (for a module written in Python), you should list the -% methods and instance variables (if any) of each type or class in a -% separate subsection. - -\subsection{Spam Objects} -\label{spam-objects} -% This label is generally useful for referencing this section, but is -% also used to give a filename when generating HTML. - -Spam objects, as returned by \function{open()} above, have the -following methods: - -\begin{methoddesc}[spam]{empty}{} -Empty the can into the trash. -\end{methoddesc} diff --git a/Doc/libtermios.tex b/Doc/libtermios.tex deleted file mode 100644 index 5e2ce1e..0000000 --- a/Doc/libtermios.tex +++ /dev/null @@ -1,109 +0,0 @@ -\section{Built-in Module \module{termios}} -\label{module-termios} -\bimodindex{termios} -\indexii{\POSIX{}}{I/O control} -\indexii{tty}{I/O control} - - -This module provides an interface to the \POSIX{} calls for tty I/O -control. For a complete description of these calls, see the \POSIX{} or -\UNIX{} manual pages. It is only available for those \UNIX{} versions -that support \POSIX{} \emph{termios} style tty I/O control (and then -only if configured at installation time). - -All functions in this module take a file descriptor \var{fd} as their -first argument. This must be an integer file descriptor, such as -returned by \code{sys.stdin.fileno()}. - -This module should be used in conjunction with the -\module{TERMIOS}\refstmodindex{TERMIOS} module, which defines the -relevant symbolic constants (see the next section). - -The module defines the following functions: - -\begin{funcdesc}{tcgetattr}{fd} -Return a list containing the tty attributes for file descriptor -\var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag}, -\var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where -\var{cc} is a list of the tty special characters (each a string of -length 1, except the items with indices \constant{TERMIOS.VMIN} and -\constant{TERMIOS.VTIME}, which are integers when these fields are -defined). The interpretation of the flags and the speeds as well as -the indexing in the \var{cc} array must be done using the symbolic -constants defined in the \module{TERMIOS} module. -\end{funcdesc} - -\begin{funcdesc}{tcsetattr}{fd, when, attributes} -Set the tty attributes for file descriptor \var{fd} from the -\var{attributes}, which is a list like the one returned by -\function{tcgetattr()}. The \var{when} argument determines when the -attributes are changed: \constant{TERMIOS.TCSANOW} to change -immediately, \constant{TERMIOS.TCSADRAIN} to change after transmitting -all queued output, or \constant{TERMIOS.TCSAFLUSH} to change after -transmitting all queued output and discarding all queued input. -\end{funcdesc} - -\begin{funcdesc}{tcsendbreak}{fd, duration} -Send a break on file descriptor \var{fd}. A zero \var{duration} sends -a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system -dependent meaning. -\end{funcdesc} - -\begin{funcdesc}{tcdrain}{fd} -Wait until all output written to file descriptor \var{fd} has been -transmitted. -\end{funcdesc} - -\begin{funcdesc}{tcflush}{fd, queue} -Discard queued data on file descriptor \var{fd}. The \var{queue} -selector specifies which queue: \constant{TERMIOS.TCIFLUSH} for the -input queue, \constant{TERMIOS.TCOFLUSH} for the output queue, or -\constant{TERMIOS.TCIOFLUSH} for both queues. -\end{funcdesc} - -\begin{funcdesc}{tcflow}{fd, action} -Suspend or resume input or output on file descriptor \var{fd}. The -\var{action} argument can be \constant{TERMIOS.TCOOFF} to suspend -output, \constant{TERMIOS.TCOON} to restart output, -\constant{TERMIOS.TCIOFF} to suspend input, or -\constant{TERMIOS.TCION} to restart input. -\end{funcdesc} - -\subsection{Example} -\nodename{termios Example} - -Here's a function that prompts for a password with echoing turned -off. Note the technique using a separate \function{tcgetattr()} call -and a \keyword{try} ... \keyword{finally} statement to ensure that the -old tty attributes are restored exactly no matter what happens: - -\begin{verbatim} -def getpass(prompt = "Password: "): - import termios, TERMIOS, sys - fd = sys.stdin.fileno() - old = termios.tcgetattr(fd) - new = termios.tcgetattr(fd) - new[3] = new[3] & ~TERMIOS.ECHO # lflags - try: - termios.tcsetattr(fd, TERMIOS.TCSADRAIN, new) - passwd = raw_input(prompt) - finally: - termios.tcsetattr(fd, TERMIOS.TCSADRAIN, old) - return passwd -\end{verbatim} - -\section{Standard Module \module{TERMIOS}} -\label{module-TERMIOSuppercase} -\stmodindex{TERMIOS} -\indexii{\POSIX{}}{I/O control} -\indexii{tty}{I/O control} - - -This module defines the symbolic constants required to use the -\module{termios}\refbimodindex{termios} module (see the previous -section). See the \POSIX{} or \UNIX{} manual pages (or the source) -for a list of those constants. - -Note: this module resides in a system-dependent subdirectory of the -Python library directory. You may have to generate it for your -particular system using the script \file{Tools/scripts/h2py.py}. diff --git a/Doc/libthread.tex b/Doc/libthread.tex deleted file mode 100644 index 9e9d8ba..0000000 --- a/Doc/libthread.tex +++ /dev/null @@ -1,127 +0,0 @@ -\section{Built-in Module \module{thread}} -\label{module-thread} -\bimodindex{thread} - -This module provides low-level primitives for working with multiple -threads (a.k.a.\ \dfn{light-weight processes} or \dfn{tasks}) --- multiple -threads of control sharing their global data space. For -synchronization, simple locks (a.k.a.\ \dfn{mutexes} or \dfn{binary -semaphores}) are provided. -\index{light-weight processes} -\index{processes, light-weight} -\index{binary semaphores} -\index{semaphores, binary} - -The module is optional. It is supported on Windows NT and '95, SGI -IRIX, Solaris 2.x, as well as on systems that have a \POSIX{} thread -(a.k.a. ``pthread'') implementation. -\index{pthreads} -\indexii{threads}{\POSIX{}} - -It defines the following constant and functions: - -\begin{excdesc}{error} -Raised on thread-specific errors. -\end{excdesc} - -\begin{funcdesc}{start_new_thread}{func, arg} -Start a new thread. The thread executes the function \var{func} -with the argument list \var{arg} (which must be a tuple). When the -function returns, the thread silently exits. When the function -terminates with an unhandled exception, a stack trace is printed and -then the thread exits (but other threads continue to run). -\end{funcdesc} - -\begin{funcdesc}{exit}{} -This is a shorthand for \function{exit_thread()}. -\end{funcdesc} - -\begin{funcdesc}{exit_thread}{} -Raise the \exception{SystemExit} exception. When not caught, this -will cause the thread to exit silently. -\end{funcdesc} - -%\begin{funcdesc}{exit_prog}{status} -%Exit all threads and report the value of the integer argument -%\var{status} as the exit status of the entire program. -%\strong{Caveat:} code in pending \code{finally} clauses, in this thread -%or in other threads, is not executed. -%\end{funcdesc} - -\begin{funcdesc}{allocate_lock}{} -Return a new lock object. Methods of locks are described below. The -lock is initially unlocked. -\end{funcdesc} - -\begin{funcdesc}{get_ident}{} -Return the `thread identifier' of the current thread. This is a -nonzero integer. Its value has no direct meaning; it is intended as a -magic cookie to be used e.g. to index a dictionary of thread-specific -data. Thread identifiers may be recycled when a thread exits and -another thread is created. -\end{funcdesc} - - -Lock objects have the following methods: - -\begin{methoddesc}[lock]{acquire}{\optional{waitflag}} -Without the optional argument, this method acquires the lock -unconditionally, if necessary waiting until it is released by another -thread (only one thread at a time can acquire a lock --- that's their -reason for existence), and returns \code{None}. If the integer -\var{waitflag} argument is present, the action depends on its value:\ -if it is zero, the lock is only acquired if it can be acquired -immediately without waiting, while if it is nonzero, the lock is -acquired unconditionally as before. If an argument is present, the -return value is \code{1} if the lock is acquired successfully, -\code{0} if not. -\end{methoddesc} - -\begin{methoddesc}[lock]{release}{} -Releases the lock. The lock must have been acquired earlier, but not -necessarily by the same thread. -\end{methoddesc} - -\begin{methoddesc}[lock]{locked}{} -Return the status of the lock:\ \code{1} if it has been acquired by -some thread, \code{0} if not. -\end{methoddesc} - -\strong{Caveats:} - -\begin{itemize} -\item -Threads interact strangely with interrupts: the -\exception{KeyboardInterrupt} exception will be received by an -arbitrary thread. (When the \module{signal}\refbimodindex{signal} -module is available, interrupts always go to the main thread.) - -\item -Calling \function{sys.exit()} or raising the \exception{SystemExit} -exception is equivalent to calling \function{exit_thread()}. - -\item -Not all built-in functions that may block waiting for I/O allow other -threads to run. (The most popular ones (\function{time.sleep()}, -\method{\var{file}.read()}, \function{select.select()}) work as -expected.) - -\item -It is not possible to interrupt the \method{acquire()} method on a lock ---- the \exception{KeyboardInterrupt} exception will happen after the -lock has been acquired. - -\item -When the main thread exits, it is system defined whether the other -threads survive. On SGI IRIX using the native thread implementation, -they survive. On most other systems, they are killed without -executing \keyword{try} ... \keyword{finally} clauses or executing -object destructors. -\indexii{threads}{IRIX} - -\item -When the main thread exits, it does not do any of its usual cleanup -(except that \keyword{try} ... \keyword{finally} clauses are honored), -and the standard I/O files are not flushed. - -\end{itemize} diff --git a/Doc/libtime.tex b/Doc/libtime.tex deleted file mode 100644 index ed4f4ef..0000000 --- a/Doc/libtime.tex +++ /dev/null @@ -1,189 +0,0 @@ -\section{Built-in Module \module{time}} -\label{module-time} -\bimodindex{time} - -This module provides various time-related functions. -It is always available. - -An explanation of some terminology and conventions is in order. - -\begin{itemize} - -\item -The \dfn{epoch}\index{epoch} is the point where the time starts. On -January 1st of that year, at 0 hours, the ``time since the epoch'' is -zero. For \UNIX{}, the epoch is 1970. To find out what the epoch is, -look at \code{gmtime(0)}. - -\item -UTC is Coordinated Universal Time (formerly known as Greenwich Mean -Time). The acronym UTC is not a mistake but a compromise between -English and French.% -\index{UTC}% -\index{Coordinated Universal Time}% -\index{Greenwich Mean Time} - -\item -DST is Daylight Saving Time, an adjustment of the timezone by -(usually) one hour during part of the year. DST rules are magic -(determined by local law) and can change from year to year. The \C{} -library has a table containing the local rules (often it is read from -a system file for flexibility) and is the only source of True Wisdom -in this respect.% -\index{Daylight Saving Time} - -\item -The precision of the various real-time functions may be less than -suggested by the units in which their value or argument is expressed. -E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a -second, and on the Mac, times are only accurate to whole seconds. - -\item -On the other hand, the precision of \function{time()} and -\function{sleep()} is better than their \UNIX{} equivalents: times are -expressed as floating point numbers, \function{time()} returns the -most accurate time available (using \UNIX{} \cfunction{gettimeofday()} -where available), and \function{sleep()} will accept a time with a -nonzero fraction (\UNIX{} \cfunction{select()} is used to implement -this, where available). - -\item -The time tuple as returned by \function{gmtime()} and -\function{localtime()}, or as accpted by \function{mktime()} is a -tuple of 9 integers: year (e.g.\ 1993), month (1--12), day (1--31), -hour (0--23), minute (0--59), second (0--59), weekday (0--6, monday is -0), Julian day (1--366) and daylight savings flag (-1, 0 or 1). -Note that unlike the \C{} structure, the month value is a range of 1-12, not -0-11. A year value less than 100 will typically be silently converted to -1900 plus the year value. A \code{-1} argument as daylight savings -flag, passed to \function{mktime()} will usually result in the correct -daylight savings state to be filled in. - -\end{itemize} - -The module defines the following functions and data items: - - -\begin{datadesc}{altzone} -The offset of the local DST timezone, in seconds west of the 0th -meridian, if one is defined. Negative if the local DST timezone is -east of the 0th meridian (as in Western Europe, including the UK). -Only use this if \code{daylight} is nonzero. -\end{datadesc} - -\begin{funcdesc}{asctime}{tuple} -Convert a tuple representing a time as returned by \code{gmtime()} or -\code{localtime()} to a 24-character string of the following form: -\code{'Sun Jun 20 23:21:05 1993'}. Note: unlike the C function of -the same name, there is no trailing newline. -\end{funcdesc} - -\begin{funcdesc}{clock}{} -Return the current CPU time as a floating point number expressed in -seconds. The precision, and in fact the very definiton of the meaning -of ``CPU time''\index{CPU time}, depends on that of the \C{} function -of the same name, but in any case, this is the function to use for -benchmarking\index{benchmarking} Python or timing algorithms. -\end{funcdesc} - -\begin{funcdesc}{ctime}{secs} -Convert a time expressed in seconds since the epoch to a string -representing local time. \code{ctime(\var{secs})} is equivalent to -\code{asctime(localtime(\var{secs}))}. -\end{funcdesc} - -\begin{datadesc}{daylight} -Nonzero if a DST timezone is defined. -\end{datadesc} - -\begin{funcdesc}{gmtime}{secs} -Convert a time expressed in seconds since the epoch to a time tuple -in UTC in which the dst flag is always zero. Fractions of a second are -ignored. -\end{funcdesc} - -\begin{funcdesc}{localtime}{secs} -Like \function{gmtime()} but converts to local time. The dst flag is -set to \code{1} when DST applies to the given time. -\end{funcdesc} - -\begin{funcdesc}{mktime}{tuple} -This is the inverse function of \code{localtime}. Its argument is the -full 9-tuple (since the dst flag is needed --- pass \code{-1} as the -dst flag if it is unknown) which expresses the time -in \emph{local} time, not UTC. It returns a floating -point number, for compatibility with \function{time()}. If the input -value cannot be represented as a valid time, \exception{OverflowError} -is raised. -\end{funcdesc} - -\begin{funcdesc}{sleep}{secs} -Suspend execution for the given number of seconds. The argument may -be a floating point number to indicate a more precise sleep time. -\end{funcdesc} - -\begin{funcdesc}{strftime}{format, tuple} -Convert a tuple representing a time as returned by \code{gmtime()} or -\code{localtime()} to a string as specified by the format argument. - -The following directives, shown without the optional field width and -precision specification, are replaced by the indicated characters: - -\begin{tableii}{c|p{24em}}{code}{Directive}{Meaning} - \lineii{\%a}{Locale's abbreviated weekday name.} - \lineii{\%A}{Locale's full weekday name.} - \lineii{\%b}{Locale's abbreviated month name.} - \lineii{\%B}{Locale's full month name.} - \lineii{\%c}{Locale's appropriate date and time representation.} - \lineii{\%d}{Day of the month as a decimal number [01,31].} - \lineii{\%H}{Hour (24-hour clock) as a decimal number [00,23].} - \lineii{\%I}{Hour (12-hour clock) as a decimal number [01,12].} - \lineii{\%j}{Day of the year as a decimal number [001,366].} - \lineii{\%m}{Month as a decimal number [01,12].} - \lineii{\%M}{Minute as a decimal number [00,59].} - \lineii{\%p}{Locale's equivalent of either AM or PM.} - \lineii{\%S}{Second as a decimal number [00,61].} - \lineii{\%U}{Week number of the year (Sunday as the first day of the - week) as a decimal number [00,53]. All days in a new year - preceding the first Sunday are considered to be in week 0.} - \lineii{\%w}{Weekday as a decimal number [0(Sunday),6].} - \lineii{\%W}{Week number of the year (Monday as the first day of the - week) as a decimal number [00,53]. All days in a new year - preceding the first Sunday are considered to be in week 0.} - \lineii{\%x}{Locale's appropriate date representation.} - \lineii{\%X}{Locale's appropriate time representation.} - \lineii{\%y}{Year without century as a decimal number [00,99].} - \lineii{\%Y}{Year with century as a decimal number.} - \lineii{\%Z}{Time zone name (or by no characters if no time zone exists).} - \lineii{\%\%}{\%} -\end{tableii} - -Additional directives may be supported on certain platforms, but -only the ones listed here have a meaning standardized by ANSI C. - -On some platforms, an optional field width and precision -specification can immediately follow the initial \code{\%} of a -directive in the following order; this is also not portable. -The field width is normally 2 except for \code{\%j} where it is 3. - -\end{funcdesc} - -\begin{funcdesc}{time}{} -Return the time as a floating point number expressed in seconds since -the epoch, in UTC. Note that even though the time is always returned -as a floating point number, not all systems provide time with a better -precision than 1 second. -\end{funcdesc} - -\begin{datadesc}{timezone} -The offset of the local (non-DST) timezone, in seconds west of the 0th -meridian (i.e. negative in most of Western Europe, positive in the US, -zero in the UK). -\end{datadesc} - -\begin{datadesc}{tzname} -A tuple of two strings: the first is the name of the local non-DST -timezone, the second is the name of the local DST timezone. If no DST -timezone is defined, the second string should not be used. -\end{datadesc} - diff --git a/Doc/libtoken.tex b/Doc/libtoken.tex deleted file mode 100644 index 15ab2a4..0000000 --- a/Doc/libtoken.tex +++ /dev/null @@ -1,37 +0,0 @@ -\section{Standard Module \module{token}} -\label{module-token} -\stmodindex{token} - -This module provides constants which represent the numeric values of -leaf nodes of the parse tree (terminal tokens). Refer to the file -\file{Grammar/Grammar} in the Python distribution for the defintions -of the names in the context of the language grammar. The specific -numeric values which the names map to may change between Python -versions. - -This module also provides one data object and some functions. The -functions mirror definitions in the Python C header files. - - - -\begin{datadesc}{tok_name} -Dictionary mapping the numeric values of the constants defined in this -module back to name strings, allowing more human-readable -representation of parse trees to be generated. -\end{datadesc} - -\begin{funcdesc}{ISTERMINAL}{x} -Return true for terminal token values. -\end{funcdesc} - -\begin{funcdesc}{ISNONTERMINAL}{x} -Return true for non-terminal token values. -\end{funcdesc} - -\begin{funcdesc}{ISEOF}{x} -Return true if \var{x} is the marker indicating the end of input. -\end{funcdesc} - -\begin{seealso} -\seemodule{parser}{second example uses this module} -\end{seealso} diff --git a/Doc/libtraceback.tex b/Doc/libtraceback.tex deleted file mode 100644 index f9aa74a..0000000 --- a/Doc/libtraceback.tex +++ /dev/null @@ -1,55 +0,0 @@ -\section{Standard Module \module{traceback}} -\label{module-traceback} -\stmodindex{traceback} - - -This module provides a standard interface to format and print stack -traces of Python programs. It exactly mimics the behavior of the -Python interpreter when it prints a stack trace. This is useful when -you want to print stack traces under program control, e.g. in a -``wrapper'' around the interpreter. - -The module uses traceback objects --- this is the object type -that is stored in the variables \code{sys.exc_traceback} and -\code{sys.last_traceback}. -\obindex{traceback} - -The module defines the following functions: - -\begin{funcdesc}{print_tb}{traceback\optional{, limit}} -Print up to \var{limit} stack trace entries from \var{traceback}. If -\var{limit} is omitted or \code{None}, all entries are printed. -\end{funcdesc} - -\begin{funcdesc}{extract_tb}{traceback\optional{, limit}} -Return a list of up to \var{limit} ``pre-processed'' stack trace -entries extracted from \var{traceback}. It is useful for alternate -formatting of stack traces. If \var{limit} is omitted or \code{None}, -all entries are extracted. A ``pre-processed'' stack trace entry is a -quadruple (\var{filename}, \var{line number}, \var{function name}, -\var{line text}) representing the information that is usually printed -for a stack trace. The \var{line text} is a string with leading and -trailing whitespace stripped; if the source is not available it is -\code{None}. -\end{funcdesc} - -\begin{funcdesc}{print_exception}{type, value, traceback\optional{, limit}} -Print exception information and up to \var{limit} stack trace entries -from \var{traceback}. This differs from \function{print_tb()} in the -following ways: (1) if \var{traceback} is not \code{None}, it prints a -header \samp{Traceback (innermost last):}; (2) it prints the -exception \var{type} and \var{value} after the stack trace; (3) if -\var{type} is \exception{SyntaxError} and \var{value} has the appropriate -format, it prints the line where the syntax error occurred with a -caret indicating the approximate position of the error. -\end{funcdesc} - -\begin{funcdesc}{print_exc}{\optional{limit}} -This is a shorthand for `\code{print_exception(sys.exc_type,} -\code{sys.exc_value,} \code{sys.exc_traceback,} \var{limit}\code{)}'. -\end{funcdesc} - -\begin{funcdesc}{print_last}{\optional{limit}} -This is a shorthand for `\code{print_exception(sys.last_type,} -\code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{)}'. -\end{funcdesc} diff --git a/Doc/libtypes.tex b/Doc/libtypes.tex deleted file mode 100644 index 2dfe742..0000000 --- a/Doc/libtypes.tex +++ /dev/null @@ -1,863 +0,0 @@ -\section{Built-in Types} -\label{types} - -The following sections describe the standard types that are built into -the interpreter. These are the numeric types, sequence types, and -several others, including types themselves. There is no explicit -Boolean type; use integers instead. -\indexii{built-in}{types} -\indexii{Boolean}{type} - -Some operations are supported by several object types; in particular, -all objects can be compared, tested for truth value, and converted to -a string (with the \code{`{\rm \ldots}`} notation). The latter conversion is -implicitly used when an object is written by the \code{print} statement. -\stindex{print} - - -\subsection{Truth Value Testing} -\label{truth} - -Any object can be tested for truth value, for use in an \code{if} or -\code{while} condition or as operand of the Boolean operations below. -The following values are considered false: -\stindex{if} -\stindex{while} -\indexii{truth}{value} -\indexii{Boolean}{operations} -\index{false} - -\setindexsubitem{(Built-in object)} -\begin{itemize} - -\item \code{None} - \ttindex{None} - -\item zero of any numeric type, e.g., \code{0}, \code{0L}, \code{0.0}. - -\item any empty sequence, e.g., \code{''}, \code{()}, \code{[]}. - -\item any empty mapping, e.g., \code{\{\}}. - -\item instances of user-defined classes, if the class defines a - \code{__nonzero__()} or \code{__len__()} method, when that - method returns zero. - -\end{itemize} - -All other values are considered true --- so objects of many types are -always true. -\index{true} - -Operations and built-in functions that have a Boolean result always -return \code{0} for false and \code{1} for true, unless otherwise -stated. (Important exception: the Boolean operations -\samp{or}\opindex{or} and \samp{and}\opindex{and} always return one of -their operands.) - - -\subsection{Boolean Operations} -\label{boolean} - -These are the Boolean operations, ordered by ascending priority: -\indexii{Boolean}{operations} - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{x} or \var{y}}{if \var{x} is false, then \var{y}, else \var{x}}{(1)} - \lineiii{\var{x} and \var{y}}{if \var{x} is false, then \var{x}, else \var{y}}{(1)} - \hline - \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{(2)} -\end{tableiii} -\opindex{and} -\opindex{or} -\opindex{not} - -\noindent -Notes: - -\begin{description} - -\item[(1)] -These only evaluate their second argument if needed for their outcome. - -\item[(2)] -\samp{not} has a lower priority than non-Boolean operators, so e.g. -\code{not a == b} is interpreted as \code{not(a == b)}, and -\code{a == not b} is a syntax error. - -\end{description} - - -\subsection{Comparisons} -\label{comparisons} - -Comparison operations are supported by all objects. They all have the -same priority (which is higher than that of the Boolean operations). -Comparisons can be chained arbitrarily, e.g. \code{x < y <= z} is -equivalent to \code{x < y and y <= z}, except that \code{y} is -evaluated only once (but in both cases \code{z} is not evaluated at -all when \code{x < y} is found to be false). -\indexii{chaining}{comparisons} - -This table summarizes the comparison operations: - -\begin{tableiii}{c|l|c}{code}{Operation}{Meaning}{Notes} - \lineiii{<}{strictly less than}{} - \lineiii{<=}{less than or equal}{} - \lineiii{>}{strictly greater than}{} - \lineiii{>=}{greater than or equal}{} - \lineiii{==}{equal}{} - \lineiii{<>}{not equal}{(1)} - \lineiii{!=}{not equal}{(1)} - \lineiii{is}{object identity}{} - \lineiii{is not}{negated object identity}{} -\end{tableiii} -\indexii{operator}{comparison} -\opindex{==} % XXX *All* others have funny characters < ! > -\opindex{is} -\opindex{is not} - -\noindent -Notes: - -\begin{description} - -\item[(1)] -\code{<>} and \code{!=} are alternate spellings for the same operator. -(I couldn't choose between \ABC{} and \C{}! :-) -\index{ABC language@\ABC{} language} -\index{language!ABC@\ABC{}} -\indexii{C@\C{}}{language} - -\end{description} - -Objects of different types, except different numeric types, never -compare equal; such objects are ordered consistently but arbitrarily -(so that sorting a heterogeneous array yields a consistent result). -Furthermore, some types (e.g., windows) support only a degenerate -notion of comparison where any two objects of that type are unequal. -Again, such objects are ordered arbitrarily but consistently. -\indexii{types}{numeric} -\indexii{objects}{comparing} - -(Implementation note: objects of different types except numbers are -ordered by their type names; objects of the same types that don't -support proper comparison are ordered by their address.) - -Two more operations with the same syntactic priority, \samp{in} and -\samp{not in}, are supported only by sequence types (below). -\opindex{in} -\opindex{not in} - - -\subsection{Numeric Types} -\label{typesnumeric} - -There are four numeric types: \dfn{plain integers}, \dfn{long integers}, -\dfn{floating point numbers}, and \dfn{complex numbers}. -Plain integers (also just called \dfn{integers}) -are implemented using \code{long} in \C{}, which gives them at least 32 -bits of precision. Long integers have unlimited precision. Floating -point numbers are implemented using \code{double} in \C{}. All bets on -their precision are off unless you happen to know the machine you are -working with. -\indexii{numeric}{types} -\indexii{integer}{types} -\indexii{integer}{type} -\indexiii{long}{integer}{type} -\indexii{floating point}{type} -\indexii{complex number}{type} -\indexii{C@\C{}}{language} - -Complex numbers have a real and imaginary part, which are both -implemented using \code{double} in \C{}. To extract these parts from -a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}. - -Numbers are created by numeric literals or as the result of built-in -functions and operators. Unadorned integer literals (including hex -and octal numbers) yield plain integers. Integer literals with an \samp{L} -or \samp{l} suffix yield long integers -(\samp{L} is preferred because \samp{1l} looks too much like eleven!). -Numeric literals containing a decimal point or an exponent sign yield -floating point numbers. Appending \samp{j} or \samp{J} to a numeric -literal yields a complex number. -\indexii{numeric}{literals} -\indexii{integer}{literals} -\indexiii{long}{integer}{literals} -\indexii{floating point}{literals} -\indexii{complex number}{literals} -\indexii{hexadecimal}{literals} -\indexii{octal}{literals} - -Python fully supports mixed arithmetic: when a binary arithmetic -operator has operands of different numeric types, the operand with the -``smaller'' type is converted to that of the other, where plain -integer is smaller than long integer is smaller than floating point is -smaller than complex. -Comparisons between numbers of mixed type use the same rule.% -\footnote{As a consequence, the list \code{[1, 2]} is considered equal - to \code{[1.0, 2.0]}, and similar for tuples.} -The functions \code{int()}, \code{long()}, \code{float()}, -and \code{complex()} can be used -to coerce numbers to a specific type. -\index{arithmetic} -\bifuncindex{int} -\bifuncindex{long} -\bifuncindex{float} -\bifuncindex{complex} - -All numeric types support the following operations, sorted by -ascending priority (operations in the same box have the same -priority; all numeric operations have a higher priority than -comparison operations): - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{} - \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{} - \hline - \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{} - \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)} - \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{} - \hline - \lineiii{-\var{x}}{\var{x} negated}{} - \lineiii{+\var{x}}{\var{x} unchanged}{} - \hline - \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{} - \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)} - \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)} - \lineiii{float(\var{x})}{\var{x} converted to floating point}{} - \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{} - \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)} - \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{} - \lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{} -\end{tableiii} -\indexiii{operations on}{numeric}{types} - -\noindent -Notes: -\begin{description} - -\item[(1)] -For (plain or long) integer division, the result is an integer. -The result is always rounded towards minus infinity: 1/2 is 0, -(-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. -\indexii{integer}{division} -\indexiii{long}{integer}{division} - -\item[(2)] -Conversion from floating point to (long or plain) integer may round or -truncate as in \C{}; see functions \code{floor()} and \code{ceil()} in -module \code{math} for well-defined conversions. -\bifuncindex{floor} -\bifuncindex{ceil} -\indexii{numeric}{conversions} -\refbimodindex{math} -\indexii{C@\C{}}{language} - -\item[(3)] -See the section on built-in functions for an exact definition. - -\end{description} -% XXXJH exceptions: overflow (when? what operations?) zerodivision - -\subsubsection{Bit-string Operations on Integer Types} -\nodename{Bit-string Operations} - -Plain and long integer types support additional operations that make -sense only for bit-strings. Negative numbers are treated as their 2's -complement value (for long integers, this assumes a sufficiently large -number of bits that no overflow occurs during the operation). - -The priorities of the binary bit-wise operations are all lower than -the numeric operations and higher than the comparisons; the unary -operation \samp{\~} has the same priority as the other unary numeric -operations (\samp{+} and \samp{-}). - -This table lists the bit-string operations sorted in ascending -priority (operations in the same box have the same priority): - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{} - \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{} - \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{} - \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)} - \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)} - \hline - \lineiii{\~\var{x}}{the bits of \var{x} inverted}{} -\end{tableiii} -\indexiii{operations on}{integer}{types} -\indexii{bit-string}{operations} -\indexii{shifting}{operations} -\indexii{masking}{operations} - -\noindent -Notes: -\begin{description} -\item[(1)] Negative shift counts are illegal and cause a -\exception{ValueError} to be raised. -\item[(2)] A left shift by \var{n} bits is equivalent to -multiplication by \code{pow(2, \var{n})} without overflow check. -\item[(3)] A right shift by \var{n} bits is equivalent to -division by \code{pow(2, \var{n})} without overflow check. -\end{description} - - -\subsection{Sequence Types} -\label{typesseq} - -There are three sequence types: strings, lists and tuples. - -Strings literals are written in single or double quotes: -\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the \emph{Python -Reference Manual} for more about string literals. Lists are -constructed with square brackets, separating items with commas: -\code{[a, b, c]}. Tuples are constructed by the comma operator (not -within square brackets), with or without enclosing parentheses, but an -empty tuple must have the enclosing parentheses, e.g., -\code{a, b, c} or \code{()}. A single item tuple must have a trailing -comma, e.g., \code{(d,)}. -\indexii{sequence}{types} -\indexii{string}{type} -\indexii{tuple}{type} -\indexii{list}{type} - -Sequence types support the following operations. The \samp{in} and -\samp{not in} operations have the same priorities as the comparison -operations. The \samp{+} and \samp{*} operations have the same -priority as the corresponding numeric operations.\footnote{They must -have since the parser can't tell the type of the operands.} - -This table lists the sequence operations sorted in ascending priority -(operations in the same box have the same priority). In the table, -\var{s} and \var{t} are sequences of the same type; \var{n}, \var{i} -and \var{j} are integers: - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{} - \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is -equal to \var{x}, else \code{1}}{} - \hline - \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{} - \lineiii{\var{s} * \var{n}{\rm ,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{(3)} - \hline - \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(1)} - \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(1), (2)} - \hline - \lineiii{len(\var{s})}{length of \var{s}}{} - \lineiii{min(\var{s})}{smallest item of \var{s}}{} - \lineiii{max(\var{s})}{largest item of \var{s}}{} -\end{tableiii} -\indexiii{operations on}{sequence}{types} -\bifuncindex{len} -\bifuncindex{min} -\bifuncindex{max} -\indexii{concatenation}{operation} -\indexii{repetition}{operation} -\indexii{subscript}{operation} -\indexii{slice}{operation} -\opindex{in} -\opindex{not in} - -\noindent -Notes: - -\begin{description} - -\item[(1)] If \var{i} or \var{j} is negative, the index is relative to - the end of the string, i.e., \code{len(\var{s}) + \var{i}} or - \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is - still \code{0}. - -\item[(2)] The slice of \var{s} from \var{i} to \var{j} is defined as - the sequence of items with index \var{k} such that \code{\var{i} <= - \var{k} < \var{j}}. If \var{i} or \var{j} is greater than - \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted, - use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If - \var{i} is greater than or equal to \var{j}, the slice is empty. - -\item[(3)] Values of \var{n} less than \code{0} are treated as - \code{0} (which yields an empty sequence of the same type as - \var{s}). - -\end{description} - -\subsubsection{More String Operations} - -String objects have one unique built-in operation: the \code{\%} -operator (modulo) with a string left argument interprets this string -as a \C{} \cfunction{sprintf()} format string to be applied to the -right argument, and returns the string resulting from this formatting -operation. - -The right argument should be a tuple with one item for each argument -required by the format string; if the string requires a single -argument, the right argument may also be a single non-tuple object.% -\footnote{A tuple object in this case should be a singleton.} -The following format characters are understood: -\code{\%}, \code{c}, \code{s}, \code{i}, \code{d}, \code{u}, \code{o}, -\code{x}, \code{X}, \code{e}, \code{E}, \code{f}, \code{g}, \code{G}. -Width and precision may be a \code{*} to specify that an integer argument -specifies the actual width or precision. The flag characters -\code{-}, \code{+}, blank, \code{\#} and \code{0} are understood. The -size specifiers \code{h}, \code{l} or \code{L} may be -present but are ignored. The \code{\%s} conversion takes any Python -object and converts it to a string using \code{str()} before -formatting it. The ANSI features \code{\%p} and \code{\%n} -are not supported. Since Python strings have an explicit length, -\code{\%s} conversions don't assume that \code{'\e0'} is the end of -the string. - -For safety reasons, floating point precisions are clipped to 50; -\code{\%f} conversions for numbers whose absolute value is over 1e25 -are replaced by \code{\%g} conversions.% -\footnote{These numbers are fairly arbitrary. They are intended to -avoid printing endless strings of meaningless digits without hampering -correct use and without having to know the exact precision of floating -point values on a particular machine.} -All other errors raise exceptions. - -If the right argument is a dictionary (or any kind of mapping), then -the formats in the string must have a parenthesized key into that -dictionary inserted immediately after the \character{\%} character, -and each format formats the corresponding entry from the mapping. -For example: - -\begin{verbatim} ->>> count = 2 ->>> language = 'Python' ->>> print '%(language)s has %(count)03d quote types.' % vars() -Python has 002 quote types. -\end{verbatim} - -In this case no \code{*} specifiers may occur in a format (since they -require a sequential parameter list). - -Additional string operations are defined in standard module -\module{string} and in built-in module \module{re}. -\refstmodindex{string} -\refbimodindex{re} - -\subsubsection{Mutable Sequence Types} - -List objects support additional operations that allow in-place -modification of the object. -These operations would be supported by other mutable sequence types -(when added to the language) as well. -Strings and tuples are immutable sequence types and such objects cannot -be modified once created. -The following operations are defined on mutable sequence types (where -\var{x} is an arbitrary object): -\indexiii{mutable}{sequence}{types} -\indexii{list}{type} - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{s}[\var{i}] = \var{x}} - {item \var{i} of \var{s} is replaced by \var{x}}{} - \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}} - {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{} - \lineiii{del \var{s}[\var{i}:\var{j}]} - {same as \code{\var{s}[\var{i}:\var{j}] = []}}{} - \lineiii{\var{s}.append(\var{x})} - {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{} - \lineiii{\var{s}.count(\var{x})} - {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{} - \lineiii{\var{s}.index(\var{x})} - {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(1)} - \lineiii{\var{s}.insert(\var{i}, \var{x})} - {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]} - if \code{\var{i} >= 0}}{} - \lineiii{\var{s}.remove(\var{x})} - {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(1)} - \lineiii{\var{s}.reverse()} - {reverses the items of \var{s} in place}{(3)} - \lineiii{\var{s}.sort()} - {sort the items of \var{s} in place}{(2), (3)} -\end{tableiii} -\indexiv{operations on}{mutable}{sequence}{types} -\indexiii{operations on}{sequence}{types} -\indexiii{operations on}{list}{type} -\indexii{subscript}{assignment} -\indexii{slice}{assignment} -\stindex{del} -\setindexsubitem{(list method)} -\ttindex{append} -\ttindex{count} -\ttindex{index} -\ttindex{insert} -\ttindex{remove} -\ttindex{reverse} -\ttindex{sort} - -\noindent -Notes: -\begin{description} -\item[(1)] Raises an exception when \var{x} is not found in \var{s}. - -\item[(2)] The \code{sort()} method takes an optional argument - specifying a comparison function of two arguments (list items) which - should return \code{-1}, \code{0} or \code{1} depending on whether the - first argument is considered smaller than, equal to, or larger than the - second argument. Note that this slows the sorting process down - considerably; e.g. to sort a list in reverse order it is much faster - to use calls to \code{sort()} and \code{reverse()} than to use - \code{sort()} with a comparison function that reverses the ordering of - the elements. - -\item[(3)] The \code{sort()} and \code{reverse()} methods modify the -list in place for economy of space when sorting or reversing a large -list. They don't return the sorted or reversed list to remind you of -this side effect. - -\end{description} - - -\subsection{Mapping Types} -\label{typesmapping} - -A \dfn{mapping} object maps values of one type (the key type) to -arbitrary objects. Mappings are mutable objects. There is currently -only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are -almost arbitrary values. The only types of values not acceptable as -keys are values containing lists or dictionaries or other mutable -types that are compared by value rather than by object identity. -Numeric types used for keys obey the normal rules for numeric -comparison: if two numbers compare equal (e.g. \code{1} and -\code{1.0}) then they can be used interchangeably to index the same -dictionary entry. - -\indexii{mapping}{types} -\indexii{dictionary}{type} - -Dictionaries are created by placing a comma-separated list of -\code{\var{key}: \var{value}} pairs within braces, for example: -\code{\{'jack': 4098, 'sjoerd': 4127\}} or -\code{\{4098: 'jack', 4127: 'sjoerd'\}}. - -The following operations are defined on mappings (where \var{a} is a -mapping, \var{k} is a key and \var{x} is an arbitrary object): - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{len(\var{a})}{the number of items in \var{a}}{} - \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1)} - \lineiii{\var{a}[\var{k}] = \var{x}}{set \code{\var{a}[\var{k}]} to \var{x}}{} - \lineiii{del \var{a}[\var{k}]}{remove \code{\var{a}[\var{k}]} from \var{a}}{(1)} - \lineiii{\var{a}.clear()}{remove all items from \code{a}}{} - \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{} - \lineiii{\var{a}.has_key(\var{k})}{\code{1} if \var{a} has a key \var{k}, else \code{0}}{} - \lineiii{\var{a}.items()}{a copy of \var{a}'s list of (key, item) pairs}{(2)} - \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(2)} - \lineiii{\var{a}.update(\var{b})}{\code{for k, v in \var{b}.items(): \var{a}[k] = v}}{(3)} - \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(2)} - \lineiii{\var{a}.get(\var{k}\optional{, \var{f}})}{the item of \var{a} with key \var{k}}{(4)} -\end{tableiii} -\indexiii{operations on}{mapping}{types} -\indexiii{operations on}{dictionary}{type} -\stindex{del} -\bifuncindex{len} -\setindexsubitem{(dictionary method)} -\ttindex{keys} -\ttindex{has_key} - -\noindent -Notes: -\begin{description} -\item[(1)] Raises an exception if \var{k} is not in the map. - -\item[(2)] Keys and values are listed in random order. - -\item[(3)] \var{b} must be of the same type as \var{a}. - -\item[(4)] Never raises an exception if \var{k} is not in the map, -instead it returns \var{f}. \var{f} is optional, when not provided -and \var{k} is not in the map, \code{None} is returned. -\end{description} - - -\subsection{Other Built-in Types} -\label{typesother} - -The interpreter supports several other kinds of objects. -Most of these support only one or two operations. - -\subsubsection{Modules} - -The only special operation on a module is attribute access: -\code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} -accesses a name defined in \var{m}'s symbol table. Module attributes -can be assigned to. (Note that the \code{import} statement is not, -strictly spoking, an operation on a module object; \code{import -\var{foo}} does not require a module object named \var{foo} to exist, -rather it requires an (external) \emph{definition} for a module named -\var{foo} somewhere.) - -A special member of every module is \code{__dict__}. -This is the dictionary containing the module's symbol table. -Modifying this dictionary will actually change the module's symbol -table, but direct assignment to the \code{__dict__} attribute is not -possible (i.e., you can write \code{\var{m}.__dict__['a'] = 1}, which -defines \code{\var{m}.a} to be \code{1}, but you can't write -\code{\var{m}.__dict__ = \{\}}. - -Modules are written like this: \code{<module 'sys'>}. - -\subsubsection{Classes and Class Instances} -\nodename{Classes and Instances} - -See Chapters 3 and 7 of the \emph{Python Reference Manual} for these. - -\subsubsection{Functions} - -Function objects are created by function definitions. The only -operation on a function object is to call it: -\code{\var{func}(\var{argument-list})}. - -There are really two flavors of function objects: built-in functions -and user-defined functions. Both support the same operation (to call -the function), but the implementation is different, hence the -different object types. - -The implementation adds two special read-only attributes: -\code{\var{f}.func_code} is a function's \dfn{code -object}\obindex{code} (see below) and \code{\var{f}.func_globals} is -the dictionary used as the function's global name space (this is the -same as \code{\var{m}.__dict__} where \var{m} is the module in which -the function \var{f} was defined). - - -\subsubsection{Methods} -\obindex{method} - -Methods are functions that are called using the attribute notation. -There are two flavors: built-in methods (such as \code{append()} on -lists) and class instance methods. Built-in methods are described -with the types that support them. - -The implementation adds two special read-only attributes to class -instance methods: \code{\var{m}.im_self} is the object whose method this -is, and \code{\var{m}.im_func} is the function implementing the method. -Calling \code{\var{m}(\var{arg-1}, \var{arg-2}, {\rm \ldots}, -\var{arg-n})} is completely equivalent to calling -\code{\var{m}.im_func(\var{m}.im_self, \var{arg-1}, \var{arg-2}, {\rm -\ldots}, \var{arg-n})}. - -See the \emph{Python Reference Manual} for more information. - -\subsubsection{Code Objects} -\obindex{code} - -Code objects are used by the implementation to represent -``pseudo-compiled'' executable Python code such as a function body. -They differ from function objects because they don't contain a -reference to their global execution environment. Code objects are -returned by the built-in \code{compile()} function and can be -extracted from function objects through their \code{func_code} -attribute. -\bifuncindex{compile} -\ttindex{func_code} - -A code object can be executed or evaluated by passing it (instead of a -source string) to the \code{exec} statement or the built-in -\code{eval()} function. -\stindex{exec} -\bifuncindex{eval} - -See the \emph{Python Reference Manual} for more information. - -\subsubsection{Type Objects} -\label{bltin-type-objects} - -Type objects represent the various object types. An object's type is -accessed by the built-in function \code{type()}. There are no special -operations on types. The standard module \code{types} defines names -for all standard built-in types. -\bifuncindex{type} -\refstmodindex{types} - -Types are written like this: \code{<type 'int'>}. - -\subsubsection{The Null Object} -\label{bltin-null-object} - -This object is returned by functions that don't explicitly return a -value. It supports no special operations. There is exactly one null -object, named \code{None} (a built-in name). - -It is written as \code{None}. - -\subsubsection{File Objects} -\label{bltin-file-objects} - -File objects are implemented using \C{}'s \code{stdio} package and can be -created with the built-in function \code{open()} described under -Built-in Functions below. They are also returned by some other -built-in functions and methods, e.g.\ \code{posix.popen()} and -\code{posix.fdopen()} and the \code{makefile()} method of socket -objects. -\bifuncindex{open} -\refbimodindex{posix} -\refbimodindex{socket} - -When a file operation fails for an I/O-related reason, the exception -\code{IOError} is raised. This includes situations where the -operation is not defined for some reason, like \code{seek()} on a tty -device or writing a file opened for reading. - -Files have the following methods: - - -\begin{methoddesc}[file]{close}{} - Close the file. A closed file cannot be read or written anymore. -\end{methoddesc} - -\begin{methoddesc}[file]{flush}{} - Flush the internal buffer, like \code{stdio}'s \code{fflush()}. -\end{methoddesc} - -\begin{methoddesc}[file]{isatty}{} - Return \code{1} if the file is connected to a tty(-like) device, else - \code{0}. -\end{methoddesc} - -\begin{methoddesc}[file]{fileno}{} -Return the integer ``file descriptor'' that is used by the underlying -implementation to request I/O operations from the operating system. -This can be useful for other, lower level interfaces that use file -descriptors, e.g. module \code{fcntl} or \code{os.read()} and friends. -\refbimodindex{fcntl} -\end{methoddesc} - -\begin{methoddesc}[file]{read}{\optional{size}} - Read at most \var{size} bytes from the file (less if the read hits - \EOF{} or no more data is immediately available on a pipe, tty or - similar device). If the \var{size} argument is negative or omitted, - read all data until \EOF{} is reached. The bytes are returned as a string - object. An empty string is returned when \EOF{} is encountered - immediately. (For certain files, like ttys, it makes sense to - continue reading after an \EOF{} is hit.) -\end{methoddesc} - -\begin{methoddesc}[file]{readline}{\optional{size}} - Read one entire line from the file. A trailing newline character is - kept in the string% -\footnote{The advantage of leaving the newline on is that an empty string - can be returned to mean \EOF{} without being ambiguous. Another - advantage is that (in cases where it might matter, e.g. if you - want to make an exact copy of a file while scanning its lines) - you can tell whether the last line of a file ended in a newline - or not (yes this happens!).} - (but may be absent when a file ends with an - incomplete line). If the \var{size} argument is present and - non-negative, it is a maximum byte count (including the trailing - newline) and an incomplete line may be returned. - An empty string is returned when \EOF{} is hit - immediately. Note: unlike \code{stdio}'s \cfunction{fgets()}, the returned - string contains null characters (\code{'\e 0'}) if they occurred in the - input. -\end{methoddesc} - -\begin{methoddesc}[file]{readlines}{\optional{sizehint}} - Read until \EOF{} using \method{readline()} and return a list containing - the lines thus read. If the optional \var{sizehint} argument is - present, instead of reading up to \EOF{}, whole lines totalling - approximately \var{sizehint} bytes (possibly after rounding up to an - internal buffer size) are read. -\end{methoddesc} - -\begin{methoddesc}[file]{seek}{offset, whence} - Set the file's current position, like \code{stdio}'s \cfunction{fseek()}. - The \var{whence} argument is optional and defaults to \code{0} - (absolute file positioning); other values are \code{1} (seek - relative to the current position) and \code{2} (seek relative to the - file's end). There is no return value. -\end{methoddesc} - -\begin{methoddesc}[file]{tell}{} - Return the file's current position, like \code{stdio}'s - \cfunction{ftell()}. -\end{methoddesc} - -\begin{methoddesc}[file]{truncate}{\optional{size}} -Truncate the file's size. If the optional size argument present, the -file is truncated to (at most) that size. The size defaults to the -current position. Availability of this function depends on the -operating system version (e.g., not all \UNIX{} versions support this -operation). -\end{methoddesc} - -\begin{methoddesc}[file]{write}{str} -Write a string to the file. There is no return value. Note: due to -buffering, the string may not actually show up in the file until -the \method{flush()} or \method{close()} method is called. -\end{methoddesc} - -\begin{methoddesc}[file]{writelines}{list} -Write a list of strings to the file. There is no return value. -(The name is intended to match \method{readlines()}; -\method{writelines()} does not add line separators.) -\end{methoddesc} - - -File objects also offer the following attributes: - -\begin{memberdesc}[file]{closed} -Boolean indicating the current state of the file object. This is a -read-only attribute; the \method{close()} method changes the value. -\end{memberdesc} - -\begin{memberdesc}[file]{mode} -The I/O mode for the file. If the file was created using the -\function{open()} built-in function, this will be the value of the -\var{mode} parameter. This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[file]{name} -If the file object was created using \function{open()}, the name of -the file. Otherwise, some string that indicates the source of the -file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only -attribute. -\end{memberdesc} - -\begin{memberdesc}[file]{softspace} -Boolean that indicates whether a space character needs to be printed -before another value when using the \keyword{print} statement. -Classes that are trying to simulate a file object should also have a -writable \member{softspace} attribute, which should be initialized to -zero. This will be automatic for classes implemented in Python; types -implemented in \C{} will have to provide a writable \member{softspace} -attribute. -\end{memberdesc} - -\subsubsection{Internal Objects} - -See the \emph{Python Reference Manual} for this information. It -describes code objects, stack frame objects, traceback objects, and -slice objects. - - -\subsection{Special Attributes} -\label{specialattrs} - -The implementation adds a few special read-only attributes to several -object types, where they are relevant: - -\begin{itemize} - -\item -\code{\var{x}.__dict__} is a dictionary of some sort used to store an -object's (writable) attributes; - -\item -\code{\var{x}.__methods__} lists the methods of many built-in object types, -e.g., \code{[].__methods__} yields -\code{['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort']}; - -\item -\code{\var{x}.__members__} lists data attributes; - -\item -\code{\var{x}.__class__} is the class to which a class instance belongs; - -\item -\code{\var{x}.__bases__} is the tuple of base classes of a class object. - -\end{itemize} diff --git a/Doc/libtypes2.tex b/Doc/libtypes2.tex deleted file mode 100644 index a9bba64..0000000 --- a/Doc/libtypes2.tex +++ /dev/null @@ -1,127 +0,0 @@ -\section{Standard Module \module{types}} -\label{module-types} -\stmodindex{types} - - -This module defines names for all object types that are used by the -standard Python interpreter, but not for the types defined by various -extension modules. It is safe to use \samp{from types import *} --- -the module does not export any names besides the ones listed here. -New names exported by future versions of this module will all end in -\samp{Type}. - -Typical use is for functions that do different things depending on -their argument types, like the following: - -\begin{verbatim} -from types import * -def delete(list, item): - if type(item) is IntType: - del list[item] - else: - list.remove(item) -\end{verbatim} - -The module defines the following names: - -\begin{datadesc}{NoneType} -The type of \code{None}. -\end{datadesc} - -\begin{datadesc}{TypeType} -The type of type objects (such as returned by -\function{type()}\bifuncindex{type}). -\end{datadesc} - -\begin{datadesc}{IntType} -The type of integers (e.g. \code{1}). -\end{datadesc} - -\begin{datadesc}{LongType} -The type of long integers (e.g. \code{1L}). -\end{datadesc} - -\begin{datadesc}{FloatType} -The type of floating point numbers (e.g. \code{1.0}). -\end{datadesc} - -\begin{datadesc}{StringType} -The type of character strings (e.g. \code{'Spam'}). -\end{datadesc} - -\begin{datadesc}{TupleType} -The type of tuples (e.g. \code{(1, 2, 3, 'Spam')}). -\end{datadesc} - -\begin{datadesc}{ListType} -The type of lists (e.g. \code{[0, 1, 2, 3]}). -\end{datadesc} - -\begin{datadesc}{DictType} -The type of dictionaries (e.g. \code{\{'Bacon': 1, 'Ham': 0\}}). -\end{datadesc} - -\begin{datadesc}{DictionaryType} -An alternate name for \code{DictType}. -\end{datadesc} - -\begin{datadesc}{FunctionType} -The type of user-defined functions and lambdas. -\end{datadesc} - -\begin{datadesc}{LambdaType} -An alternate name for \code{FunctionType}. -\end{datadesc} - -\begin{datadesc}{CodeType} -The type for code objects such as returned by -\function{compile()}\bifuncindex{compile}. -\end{datadesc} - -\begin{datadesc}{ClassType} -The type of user-defined classes. -\end{datadesc} - -\begin{datadesc}{InstanceType} -The type of instances of user-defined classes. -\end{datadesc} - -\begin{datadesc}{MethodType} -The type of methods of user-defined class instances. -\end{datadesc} - -\begin{datadesc}{UnboundMethodType} -An alternate name for \code{MethodType}. -\end{datadesc} - -\begin{datadesc}{BuiltinFunctionType} -The type of built-in functions like \function{len()} or -\function{sys.exit()}. -\end{datadesc} - -\begin{datadesc}{BuiltinMethodType} -An alternate name for \code{BuiltinFunction}. -\end{datadesc} - -\begin{datadesc}{ModuleType} -The type of modules. -\end{datadesc} - -\begin{datadesc}{FileType} -The type of open file objects such as \code{sys.stdout}. -\end{datadesc} - -\begin{datadesc}{XRangeType} -The type of range objects returned by -\function{xrange()}\bifuncindex{xrange}. -\end{datadesc} - -\begin{datadesc}{TracebackType} -The type of traceback objects such as found in -\code{sys.exc_traceback}. -\end{datadesc} - -\begin{datadesc}{FrameType} -The type of frame objects such as found in \code{tb.tb_frame} if -\code{tb} is a traceback object. -\end{datadesc} diff --git a/Doc/libundoc.tex b/Doc/libundoc.tex deleted file mode 100644 index f807fec..0000000 --- a/Doc/libundoc.tex +++ /dev/null @@ -1,312 +0,0 @@ -\chapter{Undocumented Modules} -\label{undoc} - -Here's a quick listing of modules that are currently undocumented, but -that should be documented. Feel free to contribute documentation for -them! (The idea and most contents for this chapter were taken from a -posting by Fredrik Lundh; I have revised some modules' status.) - - -\section{Frameworks; somewhat harder to document, but well worth the effort} - -\begin{description} -\item[Tkinter.py] ---- Interface to Tcl/Tk for graphical user interfaces; -Fredrik Lundh is working on this one! - -\item[Tkdnd.py] ---- Drag-and-drop support for \module{Tkinter}. - -\item[CGIHTTPServer.py] ---- CGI-savvy HTTP Server - -\item[SimpleHTTPServer.py] ---- Simple HTTP Server -\end{description} - - -\section{Stuff useful to a lot of people, including the CGI crowd} - -\begin{description} -\item[MimeWriter.py] ---- Generic MIME writer - -\item[multifile.py] ---- make each part of a multipart message ``feel'' like - -\item[smtplib.py] ---- Simple Mail Transfer Protocol (SMTP) client code. -\end{description} - - -\section{Miscellaneous useful utilities} - -Some of these are very old and/or not very robust; marked with ``hmm''. - -\begin{description} -\item[ConfigParser.py] ---- Parse a file of sectioned configuration parameters - -\item[cmp.py] ---- Efficiently compare files - -\item[cmpcache.py] ---- Efficiently compare files (uses statcache) - -\item[dircache.py] ---- like os.listdir, but caches results - -\item[dircmp.py] ---- class to build directory diff tools on - -\item[getpass.py] ---- Utilities to get a password and/or the current user name. - -\item[linecache.py] ---- Cache lines from files (used by pdb) - -\item[pipes.py] ---- Conversion pipeline templates (hmm) - -\item[statcache.py] ---- Maintain a cache of file stats - -\item[colorsys.py] ---- Conversion between RGB and other color systems - -\item[dbhash.py] ---- (g)dbm-like wrapper for bsdhash.hashopen - -\item[mhlib.py] ---- MH interface - -\item[pty.py] ---- Pseudo terminal utilities - -\item[tty.py] ---- Terminal utilities - -\item[cmd.py] ---- build line-oriented command interpreters (used by pdb) - -\item[bdb.py] ---- A generic Python debugger base class (used by pdb) - -\item[wdb.py] ---- A primitive windowing debugger based on STDWIN. - -\item[ihooks.py] ---- Import hook support (for rexec) -\end{description} - - -\section{Parsing Python} - -(One could argue that these should all be documented together with the -parser module.) - -\begin{description} -\item[tokenize.py] ---- regular expression that recognizes Python tokens; also -contains helper code for colorizing Python source code. - -\item[pyclbr.py] ---- Parse a Python file and retrieve classes and methods -\end{description} - - -\section{Platform specific modules} - -\begin{description} -\item[ntpath.py] ---- equivalent of posixpath on 32-bit Windows - -\item[dospath.py] ---- equivalent of posixpath on MS-DOS -\end{description} - - -\section{Code objects and files, debugger etc.} - -\begin{description} -\item[compileall.py] ---- force "compilation" of all .py files in a directory - -\item[py_compile.py] ---- "compile" a .py file to a .pyc file - -\item[repr.py] ---- Redo the `...` (representation) but with limits on most -sizes (used by pdb) -\end{description} - - -\section{Multimedia} - -\begin{description} -\item[audiodev.py] ---- Plays audio files - -\item[sunau.py] ---- parse Sun and NeXT audio files - -\item[sunaudio.py] ---- interpret sun audio headers - -\item[toaiff.py] ---- Convert "arbitrary" sound files to AIFF files - -\item[sndhdr.py] ---- recognizing sound files - -\item[wave.py] ---- parse WAVE files - -\item[whatsound.py] ---- recognizing sound files -\end{description} - - -\section{Oddities} - -These modules are probably also obsolete, or just not very useful. - -\begin{description} -\item[dump.py] ---- Print python code that reconstructs a variable - -\item[find.py] ---- find files matching pattern in directory tree - -\item[fpformat.py] ---- General floating point formatting functions --- -interesting demonstration of how to do this without using the \C{} -library - -\item[grep.py] ---- grep - -\item[mutex.py] ---- Mutual exclusion --- for use with module sched - -\item[packmail.py] ---- create a self-unpacking \UNIX{} shell archive - -\item[poly.py] ---- Polynomials - -\item[sched.py] ---- event scheduler class - -\item[shutil.py] ---- utility functions usable in a shell-like program - -\item[util.py] ---- useful functions that don't fit elsewhere - -\item[zmod.py] ---- Compute properties of mathematical "fields" - -\item[tzparse.py] ---- Parse a timezone specification (unfinished) -\end{description} - - -\section{Obsolete} - -These modules are not on the standard module search path; -\indexiii{module}{search}{path} -but are available in the directory \file{lib-old/} installed under -\file{\textrm{\$prefix}/lib/python1.5/}. To use any of these -modules, add that directory to \code{sys.path}, possibly using -\envvar{PYTHONPATH}. - -\begin{description} -\item[newdir.py] ---- New dir() function (the standard dir() is now just as good) - -\item[addpack.py] ---- standard support for "packages" - -\item[fmt.py] ---- text formatting abstractions (too slow) - -\item[Para.py] ---- helper for fmt.py - -\item[lockfile.py] ---- wrapper around FCNTL file locking (use -fcntl.lockf/flock intead) - -\item[tb.py] ---- Print tracebacks, with a dump of local variables (use -pdb.pm() or traceback.py instead) - -\item[codehack.py] ---- extract function name or line number from a function -code object (these are now accessible as attributes: co.co_name, -func.func_name, co.co_firstlineno) -\end{description} - -The following modules were documented in previous versions of this -manual, but are now considered obsolete: - -\begin{description} -\item[ni] ---- Import modules in ``packages.'' - -\item[rand] ---- Old interface to the random number generator. - -\item[soundex] ---- Algorithm for collapsing names which sound similar to a shared -key. (This is an extension module.) -\end{description} - - -\section{Extension modules} - -\begin{description} -\item[bsddbmodule.c] ---- Interface to the Berkeley DB interface (yet another -dbm clone). - -\item[cursesmodule.c] ---- Curses interface. - -\item[dlmodule.c] ---- A highly experimental and dangerous device for calling -arbitrary C functions in arbitrary shared libraries. - -\item[newmodule.c] ---- Tommy Burnette's `new' module (creates new empty objects of -certain kinds) --- dangerous. - -\item[nismodule.c] ---- NIS (a.k.a. Sun's Yellow Pages) interface. - -\item[timingmodule.c] ---- Measure time intervals to high resolution (obsolete --- use -time.clock() instead). - -\item[stdwinmodule.c] ---- Interface to STDWIN (an old, unsupported -platform-independent GUI package). Obsolete; use Tkinter for a -platform-independent GUI instead. - -The following are SGI specific: - -\item[clmodule.c] ---- Interface to the SGI compression library. - -\item[svmodule.c] ---- Interface to the ``simple video'' board on SGI Indigo -(obsolete hardware). - -The following is Windows specific: - -\item[msvcrtmodule.c] -(in directory \file{PC/}) --- define a number of Windows -specific goodies like \code{khbit()}, \code{getch()} and -\code{setmode()}. (Windows 95 and NT only.) -\end{description} diff --git a/Doc/libunix.tex b/Doc/libunix.tex deleted file mode 100644 index c836515..0000000 --- a/Doc/libunix.tex +++ /dev/null @@ -1,58 +0,0 @@ -\chapter{Unix Specific Services} -\label{unix} - -The modules described in this chapter provide interfaces to features -that are unique to the \UNIX{} operating system, or in some cases to -some or many variants of it. Here's an overview: - -\begin{description} - -\item[posix] ---- The most common \POSIX{} system calls (normally used via module -\module{os}). - -\item[posixpath] ---- Common \POSIX{} pathname manipulations (normally used via \code{os.path}). - -\item[pwd] ---- The password database (\function{getpwnam()} and friends). - -\item[grp] ---- The group database (\function{getgrnam()} and friends). - -\item[crypt] ---- The \cfunction{crypt()} function used to check \UNIX{} passwords. - -\item[dbm] ---- The standard ``database'' interface, based on \code{ndbm}. - -\item[gdbm] ---- GNU's reinterpretation of dbm. - -\item[termios] ---- \POSIX{} style tty control. - -\item[TERMIOS] ---- The symbolic constants required to use the \module{termios} module. - -\item[fcntl] ---- The \function{fcntl()} and \function{ioctl()} system calls. - -\item[posixfile] ---- A file-like object with support for locking. - -\item[resource] ---- An interface to provide resource usage information on the current -process. - -\item[syslog] ---- An interface to the \UNIX{} \code{syslog} library routines. - -\item[stat] ---- Constants and functions for interpreting the results of -\function{os.stat()}, \function{os.lstat()} and \function{os.fstat()}. - -\item[commands] ---- Wrapper functions for \function{os.popen()}. - -\end{description} diff --git a/Doc/liburllib.tex b/Doc/liburllib.tex deleted file mode 100644 index 8995798..0000000 --- a/Doc/liburllib.tex +++ /dev/null @@ -1,132 +0,0 @@ -\section{Standard Module \module{urllib}} -\label{module-urllib} -\stmodindex{urllib} -\index{WWW} -\index{World-Wide Web} -\index{URL} - - -This module provides a high-level interface for fetching data across -the World-Wide Web. In particular, the \function{urlopen()} function -is similar to the built-in function \function{open()}, but accepts -Universal Resource Locators (URLs) instead of filenames. Some -restrictions apply --- it can only open URLs for reading, and no seek -operations are available. - -It defines the following public functions: - -\begin{funcdesc}{urlopen}{url} -Open a network object denoted by a URL for reading. If the URL does -not have a scheme identifier, or if it has \file{file:} as its scheme -identifier, this opens a local file; otherwise it opens a socket to a -server somewhere on the network. If the connection cannot be made, or -if the server returns an error code, the \exception{IOError} exception -is raised. If all went well, a file-like object is returned. This -supports the following methods: \method{read()}, \method{readline()}, -\method{readlines()}, \method{fileno()}, \method{close()} and -\method{info()}. -Except for the last one, these methods have the same interface as for -file objects --- see section \ref{bltin-file-objects} in this -manual. (It is not a built-in file object, however, so it can't be -used at those few places where a true built-in file object is -required.) - -The \method{info()} method returns an instance of the class -\class{mimetools.Message} containing the headers received from the -server, if the protocol uses such headers (currently the only -supported protocol that uses this is HTTP). See the description of -the \module{mimetools}\refstmodindex{mimetools} module. -\end{funcdesc} - -\begin{funcdesc}{urlretrieve}{url} -Copy a network object denoted by a URL to a local file, if necessary. -If the URL points to a local file, or a valid cached copy of the -object exists, the object is not copied. Return a tuple -\code{(\var{filename}, \var{headers})} where \var{filename} is the -local file name under which the object can be found, and \var{headers} -is either \code{None} (for a local object) or whatever the -\method{info()} method of the object returned by \function{urlopen()} -returned (for a remote object, possibly cached). Exceptions are the -same as for \function{urlopen()}. -\end{funcdesc} - -\begin{funcdesc}{urlcleanup}{} -Clear the cache that may have been built up by previous calls to -\function{urlretrieve()}. -\end{funcdesc} - -\begin{funcdesc}{quote}{string\optional{, addsafe}} -Replace special characters in \var{string} using the \samp{\%xx} escape. -Letters, digits, and the characters \character{_,.-} are never quoted. -The optional \var{addsafe} parameter specifies additional characters -that should not be quoted --- its default value is \code{'/'}. - -Example: \code{quote('/\~connolly/')} yields \code{'/\%7econnolly/'}. -\end{funcdesc} - -\begin{funcdesc}{quote_plus}{string\optional{, addsafe}} -Like \function{quote()}, but also replaces spaces by plus signs, as -required for quoting HTML form values. -\end{funcdesc} - -\begin{funcdesc}{unquote}{string} -Replace \samp{\%xx} escapes by their single-character equivalent. - -Example: \code{unquote('/\%7Econnolly/')} yields \code{'/\~connolly/'}. -\end{funcdesc} - -\begin{funcdesc}{unquote_plus}{string} -Like \function{unquote()}, but also replaces plus signs by spaces, as -required for unquoting HTML form values. -\end{funcdesc} - -Restrictions: - -\begin{itemize} - -\item -Currently, only the following protocols are supported: HTTP, (versions -0.9 and 1.0), Gopher (but not Gopher-+), FTP, and local files. -\indexii{HTTP}{protocol} -\indexii{Gopher}{protocol} -\indexii{FTP}{protocol} - -\item -The caching feature of \function{urlretrieve()} has been disabled -until I find the time to hack proper processing of Expiration time -headers. - -\item -There should be a function to query whether a particular URL is in -the cache. - -\item -For backward compatibility, if a URL appears to point to a local file -but the file can't be opened, the URL is re-interpreted using the FTP -protocol. This can sometimes cause confusing error messages. - -\item -The \function{urlopen()} and \function{urlretrieve()} functions can -cause arbitrarily long delays while waiting for a network connection -to be set up. This means that it is difficult to build an interactive -web client using these functions without using threads. - -\item -The data returned by \function{urlopen()} or \function{urlretrieve()} -is the raw data returned by the server. This may be binary data -(e.g. an image), plain text or (for example) HTML. The HTTP protocol -provides type information in the reply header, which can be inspected -by looking at the \code{content-type} header. For the Gopher protocol, -type information is encoded in the URL; there is currently no easy way -to extract it. If the returned data is HTML, you can use the module -\module{htmllib}\refstmodindex{htmllib} to parse it. -\index{HTML} -\indexii{HTTP}{protocol} -\indexii{Gopher}{protocol} - -\item -Although the \module{urllib} module contains (undocumented) routines -to parse and unparse URL strings, the recommended interface for URL -manipulation is in module \module{urlparse}\refstmodindex{urlparse}. - -\end{itemize} diff --git a/Doc/liburlparse.tex b/Doc/liburlparse.tex deleted file mode 100644 index 3d98688..0000000 --- a/Doc/liburlparse.tex +++ /dev/null @@ -1,84 +0,0 @@ -\section{Standard Module \module{urlparse}} -\label{module-urlparse} -\stmodindex{urlparse} -\index{WWW} -\index{World-Wide Web} -\index{URL} -\indexii{URL}{parsing} -\indexii{relative}{URL} - - -This module defines a standard interface to break URL strings up in -components (addessing scheme, network location, path etc.), to combine -the components back into a URL string, and to convert a ``relative -URL'' to an absolute URL given a ``base URL''. - -The module has been designed to match the Internet RFC on Relative -Uniform Resource Locators (and discovered a bug in an earlier -draft!). Refer to \rfc{1808} for details on relative -URLs and \rfc{1738} for information on basic URL syntax. - -It defines the following functions: - -\begin{funcdesc}{urlparse}{urlstring\optional{, default_scheme\optional{, allow_fragments}}} -Parse a URL into 6 components, returning a 6-tuple: (addressing -scheme, network location, path, parameters, query, fragment -identifier). This corresponds to the general structure of a URL: -\code{\var{scheme}://\var{netloc}/\var{path};\var{parameters}?\var{query}\#\var{fragment}}. -Each tuple item is a string, possibly empty. -The components are not broken up in smaller parts (e.g. the network -location is a single string), and \% escapes are not expanded. -The delimiters as shown above are not part of the tuple items, -except for a leading slash in the \var{path} component, which is -retained if present. - -Example: - -\begin{verbatim} -urlparse('http://www.cwi.nl:80/%7Eguido/Python.html') -\end{verbatim} -% -yields the tuple - -\begin{verbatim} -('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '') -\end{verbatim} -% -If the \var{default_scheme} argument is specified, it gives the -default addressing scheme, to be used only if the URL string does not -specify one. The default value for this argument is the empty string. - -If the \var{allow_fragments} argument is zero, fragment identifiers -are not allowed, even if the URL's addressing scheme normally does -support them. The default value for this argument is \code{1}. -\end{funcdesc} - -\begin{funcdesc}{urlunparse}{tuple} -Construct a URL string from a tuple as returned by \code{urlparse()}. -This may result in a slightly different, but equivalent URL, if the -URL that was parsed originally had redundant delimiters, e.g. a ? with -an empty query (the draft states that these are equivalent). -\end{funcdesc} - -\begin{funcdesc}{urljoin}{base, url\optional{, allow_fragments}} -Construct a full (``absolute'') URL by combining a ``base URL'' -(\var{base}) with a ``relative URL'' (\var{url}). Informally, this -uses components of the base URL, in particular the addressing scheme, -the network location and (part of) the path, to provide missing -components in the relative URL. - -Example: - -\begin{verbatim} -urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html') -\end{verbatim} -% -yields the string - -\begin{verbatim} -'http://www.cwi.nl/%7Eguido/FAQ.html' -\end{verbatim} -% -The \var{allow_fragments} argument has the same meaning as for -\code{urlparse()}. -\end{funcdesc} diff --git a/Doc/libuser.tex b/Doc/libuser.tex deleted file mode 100644 index e545972..0000000 --- a/Doc/libuser.tex +++ /dev/null @@ -1,66 +0,0 @@ -\section{Standard Module \module{user}} -\label{module-user} -\stmodindex{user} -\indexii{.pythonrc.py}{file} -\indexiii{user}{configuration}{file} - -As a policy, Python doesn't run user-specified code on startup of -Python programs. (Only interactive sessions execute the script -specified in the \envvar{PYTHONSTARTUP} environment variable if it -exists). - -However, some programs or sites may find it convenient to allow users -to have a standard customization file, which gets run when a program -requests it. This module implements such a mechanism. A program -that wishes to use the mechanism must execute the statement - -\begin{verbatim} -import user -\end{verbatim} - -The \module{user} module looks for a file \file{.pythonrc.py} in the user's -home directory and if it can be opened, exececutes it (using -\function{execfile()}\bifuncindex{execfile}) in its own (i.e. the -module \module{user}'s) global namespace. Errors during this phase -are not caught; that's up to the program that imports the -\module{user} module, if it wishes. The home directory is assumed to -be named by the \envvar{HOME} environment variable; if this is not set, -the current directory is used. - -The user's \file{.pythonrc.py} could conceivably test for -\code{sys.version} if it wishes to do different things depending on -the Python version. - -A warning to users: be very conservative in what you place in your -\file{.pythonrc.py} file. Since you don't know which programs will -use it, changing the behavior of standard modules or functions is -generally not a good idea. - -A suggestion for programmers who wish to use this mechanism: a simple -way to let users specify options for your package is to have them -define variables in their \file{.pythonrc.py} file that you test in -your module. For example, a module \module{spam} that has a verbosity -level can look for a variable \code{user.spam_verbose}, as follows: - -\begin{verbatim} -import user -try: - verbose = user.spam_verbose # user's verbosity preference -except AttributeError: - verbose = 0 # default verbosity -\end{verbatim} - -Programs with extensive customization needs are better off reading a -program-specific customization file. - -Programs with security or privacy concerns should \emph{not} import -this module; a user can easily break into a a program by placing -arbitrary code in the \file{.pythonrc.py} file. - -Modules for general use should \emph{not} import this module; it may -interfere with the operation of the importing program. - -\begin{seealso} -\seemodule{site}{site-wide customization mechanism} -\refstmodindex{site} -\end{seealso} diff --git a/Doc/libuserdict.tex b/Doc/libuserdict.tex deleted file mode 100644 index 3bde716..0000000 --- a/Doc/libuserdict.tex +++ /dev/null @@ -1,49 +0,0 @@ -\section{Standard Module \module{UserDict}} -\stmodindex{UserDict} -\label{module-UserDict} - -This module defines a class that acts as a wrapper around -dictionary objects. It is a useful base class for -your own dictionary-like classes, which can inherit from -them and override existing methods or add new ones. In this way one -can add new behaviours to dictionaries. - -The \module{UserDict} module defines the \class{UserDict} class: - -\begin{classdesc}{UserDict}{} -Return a class instance that simulates a dictionary. The instance's -contents are kept in a regular dictionary, which is accessible via the -\member{data} attribute of \class{UserDict} instances. -\end{classdesc} - -\begin{memberdesc}{data} -A real dictionary used to store the contents of the \class{UserDict} -class. -\end{memberdesc} - - -\section{Standard Module \module{UserList}} -\stmodindex{UserList} -\label{module-UserList} - -This module defines a class that acts as a wrapper around -list objects. It is a useful base class for -your own list-like classes, which can inherit from -them and override existing methods or add new ones. In this way one -can add new behaviours to lists. - -The \module{UserList} module defines the \class{UserList} class: - -\begin{classdesc}{UserList}{\optional{list}} -Return a class instance that simulates a list. The instance's -contents are kept in a regular list, which is accessible via the -\member{data} attribute of \class{UserList} instances. The instance's -contents are initially set to a copy of \var{list}, defaulting to the -empty list \code{[]}. \var{list} can be either a regular Python list, -or an instance of \class{UserList} (or a subclass). -\end{classdesc} - -\begin{memberdesc}{data} -A real Python list object used to store the contents of the -\class{UserList} class. -\end{memberdesc} diff --git a/Doc/libuu.tex b/Doc/libuu.tex deleted file mode 100644 index 5c9e06c..0000000 --- a/Doc/libuu.tex +++ /dev/null @@ -1,35 +0,0 @@ -\section{Standard Module \module{uu}} -\label{module-uu} -\stmodindex{uu} - -This module encodes and decodes files in uuencode format, allowing -arbitrary binary data to be transferred over ascii-only connections. -Wherever a file argument is expected, the methods accept a file-like -object. For backwards compatibility, a string containing a pathname -is also accepted, and the corresponding file will be opened for -reading and writing; the pathname \code{'-'} is understood to mean the -standard input or output. However, this interface is deprecated; it's -better for the caller to open the file itself, and be sure that, when -required, the mode is \code{'rb'} or \code{'wb'} on Windows or DOS. - -This code was contributed by Lance Ellinghouse, and modified by Jack -Jansen. -\index{Jansen, Jack} -\index{Ellinghouse, Lance} - -The \module{uu} module defines the following functions: - -\begin{funcdesc}{encode}{in_file, out_file\optional{, name\optional{, mode}}} -Uuencode file \var{in_file} into file \var{out_file}. The uuencoded -file will have the header specifying \var{name} and \var{mode} as the -defaults for the results of decoding the file. The default defaults -are taken from \var{in_file}, or \code{'-'} and \code{0666} -respectively. -\end{funcdesc} - -\begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode}}} -This call decodes uuencoded file \var{in_file} placing the result on -file \var{out_file}. If \var{out_file} is a pathname the \var{mode} is -also set. Defaults for \var{out_file} and \var{mode} are taken from -the uuencode header. -\end{funcdesc} diff --git a/Doc/libwhichdb.tex b/Doc/libwhichdb.tex deleted file mode 100644 index 2caace2..0000000 --- a/Doc/libwhichdb.tex +++ /dev/null @@ -1,16 +0,0 @@ -\section{Standard Module \module{whichdb}} -\label{module-whichdb} -\stmodindex{whichdb} - -The single function in this module attempts to guess which of the -several simple database modules available--dbm, gdbm, or -dbhash--should be used to open a given file. - -\begin{funcdesc}{whichdb}{filename} -Returns one of the following values: \code{None} if the file can't be -opened because it's unreadable or doesn't exist; the empty string -(\code{""}) if the file's format can't be guessed; or a string -containing the required module name, such as \code{"dbm"} or -\code{"gdbm"}. -\end{funcdesc} - diff --git a/Doc/libwhrandom.tex b/Doc/libwhrandom.tex deleted file mode 100644 index 0645b6f..0000000 --- a/Doc/libwhrandom.tex +++ /dev/null @@ -1,49 +0,0 @@ -\section{Standard Module \module{whrandom}} -\label{module-whrandom} -\stmodindex{whrandom} - -This module implements a Wichmann-Hill pseudo-random number generator -class that is also named \code{whrandom}. Instances of the -\code{whrandom} class have the following methods: - -\begin{funcdesc}{choice}{seq} -Chooses a random element from the non-empty sequence \var{seq} and returns it. -\end{funcdesc} - -\begin{funcdesc}{randint}{a, b} -Returns a random integer \var{N} such that \code{\var{a}<=\var{N}<=\var{b}}. -\end{funcdesc} - -\begin{funcdesc}{random}{} -Returns the next random floating point number in the range [0.0 ... 1.0). -\end{funcdesc} - -\begin{funcdesc}{seed}{x, y, z} -Initializes the random number generator from the integers -\var{x}, -\var{y} -and -\var{z}. -When the module is first imported, the random number is initialized -using values derived from the current time. -\end{funcdesc} - -\begin{funcdesc}{uniform}{a, b} -Returns a random real number \var{N} such that \code{\var{a}<=\var{N}<\var{b}}. -\end{funcdesc} - -When imported, the \code{whrandom} module also creates an instance of -the \code{whrandom} class, and makes the methods of that instance -available at the module level. Therefore one can write either -\code{N = whrandom.random()} or: -\begin{verbatim} -generator = whrandom.whrandom() -N = generator.random() -\end{verbatim} -% -\begin{seealso} -\seemodule{random}{generators for various random distributions} -\seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183: -An efficient and portable pseudo-random number generator'', -\emph{Applied Statistics} 31 (1982) 188-190} -\end{seealso} diff --git a/Doc/libwww.tex b/Doc/libwww.tex deleted file mode 100644 index 5e698e4..0000000 --- a/Doc/libwww.tex +++ /dev/null @@ -1,99 +0,0 @@ -\chapter{Internet and WWW Services} -\nodename{Internet and WWW} -\label{www} -\index{WWW} -\index{Internet} -\index{World-Wide Web} - -The modules described in this chapter provide various services to -World-Wide Web (WWW) clients and/or services, and a few modules -related to news and email. They are all implemented in Python. Some -of these modules require the presence of the system-dependent module -\code{sockets}\refbimodindex{socket}, which is currently only fully -supported on \UNIX{} and Windows NT. Here is an overview: - -\begin{description} - -\item[cgi] ---- Common Gateway Interface, used to interpret forms in server-side -scripts. - -\item[urllib] ---- Open an arbitrary object given by URL (requires sockets). - -\item[httplib] ---- HTTP protocol client (requires sockets). - -\item[ftplib] ---- FTP protocol client (requires sockets). - -\item[gopherlib] ---- Gopher protocol client (requires sockets). - -\item[poplib] ---- POP3 protocol client (requires sockets). - -\item[imaplib] ---- IMAP4 protocol client (requires sockets). - -\item[nntplib] ---- NNTP protocol client (requires sockets). - -\item[urlparse] ---- Parse a URL string into a tuple (addressing scheme identifier, network -location, path, parameters, query string, fragment identifier). - -\item[sgmllib] ---- Only as much of an SGML parser as needed to parse HTML. - -\item[htmllib] ---- A parser for HTML documents. - -\item[xmllib] ---- A parser for XML documents. - -\item[formatter] ---- Generic output formatter and device interface. - -\item[rfc822] ---- Parse \rfc{822} style mail headers. - -\item[mimetools] ---- Tools for parsing MIME style message bodies. - -\item[binhex] ---- Encode and decode files in binhex4 format. - -\item[uu] ---- Encode and decode files in uuencode format. - -\item[binascii] ---- Tools for converting between binary and various ascii-encoded binary -representation - -\item[xdrlib] ---- The External Data Representation Standard as described in \rfc{1014}, -written by Sun Microsystems, Inc. June 1987. - -\item[mailcap] ---- Mailcap file handling. See \rfc{1524}. - -\item[base64] ---- Encode/decode binary files using the MIME base64 encoding. - -\item[quopri] ---- Encode/decode binary files using the MIME quoted-printable encoding. - -\item[SocketServer] ---- A framework for network servers. - -\item[mailbox] ---- Read various mailbox formats. - -\item[mimify] ---- Mimification and unmimification of mail messages. - -\item[BaseHTTPServer] ---- Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer). - -\end{description} diff --git a/Doc/libxdrlib.tex b/Doc/libxdrlib.tex deleted file mode 100644 index 56459f8..0000000 --- a/Doc/libxdrlib.tex +++ /dev/null @@ -1,232 +0,0 @@ -\section{Standard Module \module{xdrlib}} -\label{module-xdrlib} -\stmodindex{xdrlib} -\index{XDR} -\index{External Data Representation} - - - -The \module{xdrlib} module supports the External Data Representation -Standard as described in \rfc{1014}, written by Sun Microsystems, -Inc. June 1987. It supports most of the data types described in the -RFC. - -The \module{xdrlib} module defines two classes, one for packing -variables into XDR representation, and another for unpacking from XDR -representation. There are also two exception classes. - -\begin{classdesc}{Packer}{} -\class{Packer} is the class for packing data into XDR representation. -The \class{Packer} class is instantiated with no arguments. -\end{classdesc} - -\begin{classdesc}{Unpacker}{data} -\code{Unpacker} is the complementary class which unpacks XDR data -values from a string buffer. The input buffer is given as -\var{data}. -\end{classdesc} - - -\subsection{Packer Objects} -\label{xdr-packer-objects} - -\class{Packer} instances have the following methods: - -\begin{methoddesc}[Packer]{get_buffer}{} -Returns the current pack buffer as a string. -\end{methoddesc} - -\begin{methoddesc}[Packer]{reset}{} -Resets the pack buffer to the empty string. -\end{methoddesc} - -In general, you can pack any of the most common XDR data types by -calling the appropriate \code{pack_\var{type}()} method. Each method -takes a single argument, the value to pack. The following simple data -type packing methods are supported: \method{pack_uint()}, -\method{pack_int()}, \method{pack_enum()}, \method{pack_bool()}, -\method{pack_uhyper()}, and \method{pack_hyper()}. - -\begin{methoddesc}[Packer]{pack_float}{value} -Packs the single-precision floating point number \var{value}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_double}{value} -Packs the double-precision floating point number \var{value}. -\end{methoddesc} - -The following methods support packing strings, bytes, and opaque data: - -\begin{methoddesc}[Packer]{pack_fstring}{n, s} -Packs a fixed length string, \var{s}. \var{n} is the length of the -string but it is \emph{not} packed into the data buffer. The string -is padded with null bytes if necessary to guaranteed 4 byte alignment. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_fopaque}{n, data} -Packs a fixed length opaque data stream, similarly to -\method{pack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_string}{s} -Packs a variable length string, \var{s}. The length of the string is -first packed as an unsigned integer, then the string data is packed -with \method{pack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_opaque}{data} -Packs a variable length opaque data string, similarly to -\method{pack_string()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_bytes}{bytes} -Packs a variable length byte stream, similarly to \method{pack_string()}. -\end{methoddesc} - -The following methods support packing arrays and lists: - -\begin{methoddesc}[Packer]{pack_list}{list, pack_item} -Packs a \var{list} of homogeneous items. This method is useful for -lists with an indeterminate size; i.e. the size is not available until -the entire list has been walked. For each item in the list, an -unsigned integer \code{1} is packed first, followed by the data value -from the list. \var{pack_item} is the function that is called to pack -the individual item. At the end of the list, an unsigned integer -\code{0} is packed. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_farray}{n, array, pack_item} -Packs a fixed length list (\var{array}) of homogeneous items. \var{n} -is the length of the list; it is \emph{not} packed into the buffer, -but a \exception{ValueError} exception is raised if -\code{len(\var{array})} is not equal to \var{n}. As above, -\var{pack_item} is the function used to pack each element. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_array}{list, pack_item} -Packs a variable length \var{list} of homogeneous items. First, the -length of the list is packed as an unsigned integer, then each element -is packed as in \method{pack_farray()} above. -\end{methoddesc} - - -\subsection{Unpacker Objects} -\label{xdr-unpacker-objects} - -The \class{Unpacker} class offers the following methods: - -\begin{methoddesc}[Unpacker]{reset}{data} -Resets the string buffer with the given \var{data}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{get_position}{} -Returns the current unpack position in the data buffer. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{set_position}{position} -Sets the data buffer unpack position to \var{position}. You should be -careful about using \method{get_position()} and \method{set_position()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{get_buffer}{} -Returns the current unpack data buffer as a string. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{done}{} -Indicates unpack completion. Raises an \exception{Error} exception -if all of the data has not been unpacked. -\end{methoddesc} - -In addition, every data type that can be packed with a \class{Packer}, -can be unpacked with an \class{Unpacker}. Unpacking methods are of the -form \code{unpack_\var{type}()}, and take no arguments. They return the -unpacked object. - -\begin{methoddesc}[Unpacker]{unpack_float}{} -Unpacks a single-precision floating point number. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_double}{} -Unpacks a double-precision floating point number, similarly to -\method{unpack_float()}. -\end{methoddesc} - -In addition, the following methods unpack strings, bytes, and opaque -data: - -\begin{methoddesc}[Unpacker]{unpack_fstring}{n} -Unpacks and returns a fixed length string. \var{n} is the number of -characters expected. Padding with null bytes to guaranteed 4 byte -alignment is assumed. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_fopaque}{n} -Unpacks and returns a fixed length opaque data stream, similarly to -\method{unpack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_string}{} -Unpacks and returns a variable length string. The length of the -string is first unpacked as an unsigned integer, then the string data -is unpacked with \method{unpack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_opaque}{} -Unpacks and returns a variable length opaque data string, similarly to -\method{unpack_string()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_bytes}{} -Unpacks and returns a variable length byte stream, similarly to -\method{unpack_string()}. -\end{methoddesc} - -The following methods support unpacking arrays and lists: - -\begin{methoddesc}[Unpacker]{unpack_list}{unpack_item} -Unpacks and returns a list of homogeneous items. The list is unpacked -one element at a time -by first unpacking an unsigned integer flag. If the flag is \code{1}, -then the item is unpacked and appended to the list. A flag of -\code{0} indicates the end of the list. \var{unpack_item} is the -function that is called to unpack the items. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_farray}{n, unpack_item} -Unpacks and returns (as a list) a fixed length array of homogeneous -items. \var{n} is number of list elements to expect in the buffer. -As above, \var{unpack_item} is the function used to unpack each element. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_array}{unpack_item} -Unpacks and returns a variable length \var{list} of homogeneous items. -First, the length of the list is unpacked as an unsigned integer, then -each element is unpacked as in \method{unpack_farray()} above. -\end{methoddesc} - - -\subsection{Exceptions} -\nodename{xdr-exceptions} - -Exceptions in this module are coded as class instances: - -\begin{excdesc}{Error} -The base exception class. \exception{Error} has a single public data -member \member{msg} containing the description of the error. -\end{excdesc} - -\begin{excdesc}{ConversionError} -Class derived from \exception{Error}. Contains no additional instance -variables. -\end{excdesc} - -Here is an example of how you would catch one of these exceptions: - -\begin{verbatim} -import xdrlib -p = xdrlib.Packer() -try: - p.pack_double(8.01) -except xdrlib.ConversionError, instance: - print 'packing the double failed:', instance.msg -\end{verbatim} diff --git a/Doc/libxmllib.tex b/Doc/libxmllib.tex deleted file mode 100644 index 4306aca..0000000 --- a/Doc/libxmllib.tex +++ /dev/null @@ -1,223 +0,0 @@ -\section{Standard Module \module{xmllib}} -% Author: Sjoerd Mullender -\label{module-xmllib} -\stmodindex{xmllib} -\index{XML} - -This module defines a class \class{XMLParser} which serves as the basis -for parsing text files formatted in XML (eXtended Markup Language). - -\begin{classdesc}{XMLParser}{} -The \class{XMLParser} class must be instantiated without arguments. -\end{classdesc} - -This class provides the following interface methods: - -\begin{methoddesc}{reset}{} -Reset the instance. Loses all unprocessed data. This is called -implicitly at the instantiation time. -\end{methoddesc} - -\begin{methoddesc}{setnomoretags}{} -Stop processing tags. Treat all following input as literal input -(CDATA). -\end{methoddesc} - -\begin{methoddesc}{setliteral}{} -Enter literal mode (CDATA mode). -\end{methoddesc} - -\begin{methoddesc}{feed}{data} -Feed some text to the parser. It is processed insofar as it consists -of complete elements; incomplete data is buffered until more data is -fed or \method{close()} is called. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Force processing of all buffered data as if it were followed by an -end-of-file mark. This method may be redefined by a derived class to -define additional processing at the end of the input, but the -redefined version should always call \method{close()}. -\end{methoddesc} - -\begin{methoddesc}{translate_references}{data} -Translate all entity and character references in \var{data} and -returns the translated string. -\end{methoddesc} - -\begin{methoddesc}{handle_xml}{encoding, standalone} -This method is called when the \samp{<?xml ...?>} tag is processed. -The arguments are the values of the encoding and standalone attributes -in the tag. Both encoding and standalone are optional. The values -passed to \method{handle_xml()} default to \code{None} and the string -\code{'no'} respectively. -\end{methoddesc} - -\begin{methoddesc}{handle_doctype}{tag, data} -This method is called when the \samp{<!DOCTYPE...>} tag is processed. -The arguments are the name of the root element and the uninterpreted -contents of the tag, starting after the white space after the name of -the root element. -\end{methoddesc} - -\begin{methoddesc}{handle_starttag}{tag, method, attributes} -This method is called to handle start tags for which a -\method{start_\var{tag}()} method has been defined. The \var{tag} -argument is the name of the tag, and the \var{method} argument is the -bound method which should be used to support semantic interpretation -of the start tag. The \var{attributes} argument is a dictionary of -attributes, the key being the \var{name} and the value being the -\var{value} of the attribute found inside the tag's \code{<>} brackets. -Character and entity references in the \var{value} have -been interpreted. For instance, for the tag -\code{<A HREF="http://www.cwi.nl/">}, this method would be called as -\code{handle_starttag('A', self.start_A, \{'HREF': 'http://www.cwi.nl/'\})}. -The base implementation simply calls \var{method} with \var{attributes} -as the only argument. -\end{methoddesc} - -\begin{methoddesc}{handle_endtag}{tag, method} -This method is called to handle endtags for which an -\method{end_\var{tag}()} method has been defined. The \var{tag} -argument is the name of the tag, and the -\var{method} argument is the bound method which should be used to -support semantic interpretation of the end tag. If no -\method{end_\var{tag}()} method is defined for the closing element, this -handler is not called. The base implementation simply calls -\var{method}. -\end{methoddesc} - -\begin{methoddesc}{handle_data}{data} -This method is called to process arbitrary data. It is intended to be -overridden by a derived class; the base class implementation does -nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_charref}{ref} -This method is called to process a character reference of the form -\samp{\&\#\var{ref};}. \var{ref} can either be a decimal number, -or a hexadecimal number when preceded by an \character{x}. -In the base implementation, \var{ref} must be a number in the -range 0-255. It translates the character to \ASCII{} and calls the -method \method{handle_data()} with the character as argument. If -\var{ref} is invalid or out of range, the method -\code{unknown_charref(\var{ref})} is called to handle the error. A -subclass must override this method to provide support for character -references outside of the \ASCII{} range. -\end{methoddesc} - -\begin{methoddesc}{handle_entityref}{ref} -This method is called to process a general entity reference of the -form \samp{\&\var{ref};} where \var{ref} is an general entity -reference. It looks for \var{ref} in the instance (or class) -variable \member{entitydefs} which should be a mapping from entity -names to corresponding translations. -If a translation is found, it calls the method \method{handle_data()} -with the translation; otherwise, it calls the method -\code{unknown_entityref(\var{ref})}. The default \member{entitydefs} -defines translations for \code{\&}, \code{\&apos}, \code{\>}, -\code{\<}, and \code{\"}. -\end{methoddesc} - -\begin{methoddesc}{handle_comment}{comment} -This method is called when a comment is encountered. The -\var{comment} argument is a string containing the text between the -\samp{<!--} and \samp{-->} delimiters, but not the delimiters -themselves. For example, the comment \samp{<!--text-->} will -cause this method to be called with the argument \code{'text'}. The -default method does nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_cdata}{data} -This method is called when a CDATA element is encountered. The -\var{data} argument is a string containing the text between the -\samp{<![CDATA[} and \samp{]]>} delimiters, but not the delimiters -themselves. For example, the entity \samp{<![CDATA[text]]>} will -cause this method to be called with the argument \code{'text'}. The -default method does nothing, and is intended to be overridden. -\end{methoddesc} - -\begin{methoddesc}{handle_proc}{name, data} -This method is called when a processing instruction (PI) is -encountered. The \var{name} is the PI target, and the \var{data} -argument is a string containing the text between the PI target and the -closing delimiter, but not the delimiter itself. For example, the -instruction \samp{<?XML text?>} will cause this method to be called -with the arguments \code{'XML'} and \code{'text'}. The default method -does nothing. Note that if a document starts with \samp{<?xml -...?>}, \method{handle_xml()} is called to handle it. -\end{methoddesc} - -\begin{methoddesc}{handle_special}{data} -This method is called when a declaration is encountered. The -\var{data} argument is a string containing the text between the -\samp{<!} and \samp{>} delimiters, but not the delimiters -themselves. For example, the entity \samp{<!ENTITY text>} will -cause this method to be called with the argument \code{'ENTITY text'}. The -default method does nothing. Note that \samp{<!DOCTYPE ...>} is -handled separately if it is located at the start of the document. -\end{methoddesc} - -\begin{methoddesc}{syntax_error}{message} -This method is called when a syntax error is encountered. The -\var{message} is a description of what was wrong. The default method -raises a \exception{RuntimeError} exception. If this method is -overridden, it is permissable for it to return. This method is only -called when the error can be recovered from. Unrecoverable errors -raise a \exception{RuntimeError} without first calling -\method{syntax_error()}. -\end{methoddesc} - -\begin{methoddesc}{unknown_starttag}{tag, attributes} -This method is called to process an unknown start tag. It is intended -to be overridden by a derived class; the base class implementation -does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_endtag}{tag} -This method is called to process an unknown end tag. It is intended -to be overridden by a derived class; the base class implementation -does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_charref}{ref} -This method is called to process unresolvable numeric character -references. It is intended to be overridden by a derived class; the -base class implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_entityref}{ref} -This method is called to process an unknown entity reference. It is -intended to be overridden by a derived class; the base class -implementation does nothing. -\end{methoddesc} - -Apart from overriding or extending the methods listed above, derived -classes may also define methods and variables of the following form to -define processing of specific tags. Tag names in the input stream are -case dependent; the \var{tag} occurring in method names must be in the -correct case: - -\begin{methoddescni}{start_\var{tag}}{attributes} -This method is called to process an opening tag \var{tag}. The -\var{attributes} argument has the same meaning as described for -\method{handle_starttag()} above. In fact, the base implementation of -\method{handle_starttag()} calls this method. -\end{methoddescni} - -\begin{methoddescni}{end_\var{tag}}{} -This method is called to process a closing tag \var{tag}. -\end{methoddescni} - -\begin{memberdescni}{\var{tag}_attributes} -If a class or instance variable \member{\var{tag}_attributes} exists, it -should be a list or a dictionary. If a list, the elements of the list -are the valid attributes for the element \var{tag}; if a dictionary, -the keys are the valid attributes for the element \var{tag}, and the -values the default values of the attributes, or \code{None} if there -is no default. -In addition to the attributes that were present in the tag, the -attribute dictionary that is passed to \method{handle_starttag()} and -\method{unknown_starttag()} contains values for all attributes that -have a default value. -\end{memberdescni} diff --git a/Doc/libzlib.tex b/Doc/libzlib.tex deleted file mode 100644 index f38a21c..0000000 --- a/Doc/libzlib.tex +++ /dev/null @@ -1,114 +0,0 @@ -% XXX The module has been extended (by Jeremy) but this documentation -% hasn't been updated yet - -\section{Built-in Module \module{zlib}} -\label{module-zlib} -\bimodindex{zlib} - -For applications that require data compression, the functions in this -module allow compression and decompression, using the zlib library. -The zlib library has its own home page at -\url{http://www.cdrom.com/pub/infozip/zlib/}. Version 1.0.4 is the -most recent version as of December, 1997; use a later version if one -is available. - -The available exception and functions in this module are: - -\begin{excdesc}{error} - Exception raised on compression and decompression errors. -\end{excdesc} - - -\begin{funcdesc}{adler32}{string\optional{, value}} - Computes a Adler-32 checksum of \var{string}. (An Adler-32 - checksum is almost as reliable as a CRC32 but can be computed much - more quickly.) If \var{value} is present, it is used as the - starting value of the checksum; otherwise, a fixed default value is - used. This allows computing a running checksum over the - concatenation of several input strings. The algorithm is not - cryptographically strong, and should not be used for - authentication or digital signatures. -\end{funcdesc} - -\begin{funcdesc}{compress}{string\optional{, level}} -Compresses the data in \var{string}, returning a string contained -compressed data. \var{level} is an integer from \code{1} to \code{9} -controlling the level of compression; \code{1} is fastest and produces -the least compression, \code{9} is slowest and produces the most. The -default value is \code{6}. Raises the \exception{error} -exception if any error occurs. -\end{funcdesc} - -\begin{funcdesc}{compressobj}{\optional{level}} - Returns a compression object, to be used for compressing data streams - that won't fit into memory at once. \var{level} is an integer from - \code{1} to \code{9} controlling the level of compression; \code{1} is - fastest and produces the least compression, \code{9} is slowest and - produces the most. The default value is \code{6}. -\end{funcdesc} - -\begin{funcdesc}{crc32}{string\optional{, value}} - Computes a CRC (Cyclic Redundancy Check)% - \index{Cyclic Redundancy Check} - \index{checksum!Cyclic Redundancy Check} - checksum of \var{string}. If - \var{value} is present, it is used as the starting value of the - checksum; otherwise, a fixed default value is used. This allows - computing a running checksum over the concatenation of several - input strings. The algorithm is not cryptographically strong, and - should not be used for authentication or digital signatures. -\end{funcdesc} - -\begin{funcdesc}{decompress}{string} -Decompresses the data in \var{string}, returning a string containing -the uncompressed data. Raises the \exception{error} exception if any -error occurs. -\end{funcdesc} - -\begin{funcdesc}{decompressobj}{\optional{wbits}} -Returns a compression object, to be used for decompressing data streams -that won't fit into memory at once. The \var{wbits} parameter -controls the size of the window buffer; usually this can be left -alone. -\end{funcdesc} - -Compression objects support the following methods: - -\begin{methoddesc}[Compress]{compress}{string} -Compress \var{string}, returning a string containing compressed data -for at least part of the data in \var{string}. This data should be -concatenated to the output produced by any preceding calls to the -\method{compress()} method. Some input may be kept in internal buffers -for later processing. -\end{methoddesc} - -\begin{methoddesc}[Compress]{flush}{} -All pending input is processed, and an string containing the remaining -compressed output is returned. After calling \method{flush()}, the -\method{compress()} method cannot be called again; the only realistic -action is to delete the object. -\end{methoddesc} - -Decompression objects support the following methods: - -\begin{methoddesc}[Decompress]{decompress}{string} -Decompress \var{string}, returning a string containing the -uncompressed data corresponding to at least part of the data in -\var{string}. This data should be concatenated to the output produced -by any preceding calls to the -\method{decompress()} method. Some of the input data may be preserved -in internal buffers for later processing. -\end{methoddesc} - -\begin{methoddesc}[Decompress]{flush}{} -All pending input is processed, and a string containing the remaining -uncompressed output is returned. After calling \method{flush()}, the -\method{decompress()} method cannot be called again; the only realistic -action is to delete the object. -\end{methoddesc} - -\begin{seealso} -\seemodule{gzip}{reading and writing \program{gzip}-format files} -\end{seealso} - - |