Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-10-31 13:41:24 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merged changes from the 1.5.2p2 release.

Browse source 
(Very rough.)
This commit is contained in:
Fred Drake 2000-04-03 20:13:55 +00:00
parent 659ebfa79e
commit 38e5d27cae
59 changed files with 1248 additions and 516 deletions
Download patch file Download diff file Expand all files Collapse all files

6
Doc/lib/internet.tex
View file

@ -6,8 +6,8 @@
The modules described in this chapter implement Internet protocols and
support for related technology. They are all implemented in Python.
Some of these modules require the presence of the system-dependent
module \refmodule{socket}\refbimodindex{socket}, which is currently only
fully supported on \UNIX{} and Windows NT. Here is an overview:
Most of these modules require the presence of the system-dependent
module \refmodule{socket}\refbimodindex{socket}, which is currently
supported on most popular platforms. Here is an overview:
\localmoduletable

17
Doc/lib/libarray.tex
View file

@ -76,11 +76,11 @@ 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}
\begin{methoddesc}[array]{byteswap}{}
``Byteswap'' all items of the array. This is only supported for
integer values; for other types of values, \exception{RuntimeError} is
raised. It is useful when reading data from a file written on a
machine with a different byte order.
values which are 1, 2, 4, or 8 bytes in size; for other types of
values, \exception{RuntimeError} is raised. 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}
@ -150,7 +150,8 @@ represented as \code{array(\var{typecode}, \var{initializer})}. The
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:
(\code{``}), so long as the \function{array()} function has been
imported using \samp{from array import array}. Examples:
\begin{verbatim}
array('l')
@ -163,4 +164,10 @@ array('d', [1.0, 2.0, 3.14])
\begin{seealso}
\seemodule{struct}{packing and unpacking of heterogeneous binary data}
\seemodule{xdrlib}{packing and unpacking of XDR data}
\seetext{The Numeric Python extension (NumPy) defines another array
type; see \emph{The Numerical Python Manual} for additional
information (available online at
\url{ftp://ftp-icf.llnl.gov/pub/python/numericalpython.pdf}).
Further information about NumPy is available at
\url{http://www.python.org/topics/scicomp/numpy.html}.}
\end{seealso}

8
Doc/lib/libasyncore.tex
View file

@ -1,18 +1,16 @@
\section{\module{asyncore} ---
Asyncronous socket handler}
Asynchronous socket handler}
\declaremodule{builtin}{asyncore}
\modulesynopsis{A base class for developing asyncronous socket
\modulesynopsis{A base class for developing asynchronous socket
handling services.}
\moduleauthor{Sam Rushing}{rushing@nightmare.com}
\sectionauthor{Christopher Petrilli}{petrilli@amber.org}
% Heavily adapted from original documentation by Sam Rushing.
This module provides the basic infrastructure for writing asyncronous
This module provides the basic infrastructure for writing asynchronous
socket service clients and servers.
%\subsection{Why Asyncronous?}
There are only two ways to have a program on a single processor do
``more than one thing at a time.'' Multi-threaded programming is the
simplest and most popular way to do it, but there is another very

21
Doc/lib/libbase64.tex
View file

@ -10,14 +10,14 @@
This module performs 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'}.
encoding scheme is defined in \rfc{1521} (\emph{MIME
(Multipurpose Internet Mail Extensions) Part One: Mechanisms for
Specifying and Describing the Format of Internet Message Bodies},
section 5.2, ``Base64 Content-Transfer-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}
@ -52,4 +52,9 @@ base64 encoded data.
\begin{seealso}
\seemodule{binascii}{support module containing \ASCII{}-to-binary
and binary-to-\ASCII{} conversions}
\seetext{Internet \rfc{1521}, \emph{MIME (Multipurpose Internet
Mail Extensions) Part One: Mechanisms for Specifying and
Describing the Format of Internet Message Bodies}, section
5.2, ``Base64 Content-Transfer-Encoding,'' provides the
definition of the base64 encoding.}
\end{seealso}

8
Doc/lib/libbisect.tex
View file

@ -1,12 +1,12 @@
% 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{\module{bisect} ---
Array bisection algorithm}
\declaremodule{standard}{bisect}
\modulesynopsis{Array bisection algorithms for binary searching.}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
% 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>.
This module provides support for maintaining a list in sorted order

90
Doc/lib/libbsddb.tex
View file

@ -7,59 +7,71 @@
\sectionauthor{Skip Montanaro}{skip@mojam.com}
The \module{bsddb} module provides an interface to the Berkeley DB library.
Users can create hash, btree or record based library files using the
appropriate open call. Bsddb objects behave generally like dictionaries.
Keys and values must be strings, however, so to use other objects as keys or
to store other kinds of objects the user must serialize them somehow,
typically using marshal.dumps or pickle.dumps.
The \module{bsddb} module provides an interface to the Berkeley DB
library. Users can create hash, btree or record based library files
using the appropriate open call. Bsddb objects behave generally like
dictionaries. Keys and values must be strings, however, so to use
other objects as keys or to store other kinds of objects the user must
serialize them somehow, typically using marshal.dumps or pickle.dumps.
The \module{bsddb} module is only available on \UNIX{} systems, so it is not
built by default in the standard Python distribution. Also, there are two
incompatible versions of the underlying library. Version 1.85 is widely
available, but has some known bugs. Version 2 is not quite as widely used,
but does offer some improvements. The \module{bsddb} module uses the 1.85
interface. Users wishing to use version 2 of the Berkeley DB library will
have to modify the source for the module to include db_185.h instead of
db.h.
The \module{bsddb} module is only available on \UNIX{} systems, so it
is not built by default in the standard Python distribution. Also,
there are two incompatible versions of the underlying library.
Version 1.85 is widely available, but has some known bugs. Version 2
is not quite as widely used, but does offer some improvements. The
\module{bsddb} module uses the 1.85 interface. Users wishing to use
version 2 of the Berkeley DB library will have to modify the source
for the module to include \file{db_185.h} instead of
\file{db.h} (\file{db_185.h} contains the version 1.85 compatibility
interface).
The \module{bsddb} module defines the following functions that create
objects that access the appropriate type of Berkeley DB file. The first two
arguments of each function are the same. For ease of portability, only the
first two arguments should be used in most instances.
objects that access the appropriate type of Berkeley DB file. The
first two arguments of each function are the same. For ease of
portability, only the first two arguments should be used in most
instances.
\begin{funcdesc}{hashopen}{filename\optional{, flag\optional{,
mode\optional{, bsize\optional{, ffactor\optional{, nelem\optional{,
cachesize\optional{, hash\optional{, lorder}}}}}}}}}
Open the hash format file named \var{filename}. The optional \var{flag}
identifies the mode used to open the file. It may be ``r'' (read only),
``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
(read-write - truncate to zero length). The other arguments are rarely used
and are just passed to the low-level dbopen function. Consult the
Berkeley DB documentation for their use and interpretation.
mode\optional{, bsize\optional{,
ffactor\optional{, nelem\optional{,
cachesize\optional{, hash\optional{,
lorder}}}}}}}}}
Open the hash format file named \var{filename}. The optional
\var{flag} identifies the mode used to open the file. It may be
\character{r} (read only), \character{w} (read-write),
\character{c} (read-write - create if necessary) or
\character{n} (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level
\cfunction{dbopen()} function. Consult the Berkeley DB documentation
for their use and interpretation.
\end{funcdesc}
\begin{funcdesc}{btopen}{filename\optional{, flag\optional{,
mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{,
minkeypage\optional{, psize\optional{, lorder}}}}}}}}}
Open the btree format file named \var{filename}. The optional \var{flag}
identifies the mode used to open the file. It may be ``r'' (read only),
``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
(read-write - truncate to zero length). The other arguments are rarely used
and are just passed to the low-level dbopen function. Consult the
Berkeley DB documentation for their use and interpretation.
Open the btree format file named \var{filename}. The optional
\var{flag} identifies the mode used to open the file. It may be
\character{r} (read only), \character{w} (read-write),
\character{c} (read-write - create if necessary) or
\character{n} (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level dbopen
function. Consult the Berkeley DB documentation for their use and
interpretation.
\end{funcdesc}
\begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{,
rnflags\optional{, cachesize\optional{, psize\optional{, lorder\optional{,
reclen\optional{, bval\optional{, bfname}}}}}}}}}}
Open a DB record format file named \var{filename}. The optional \var{flag}
identifies the mode used to open the file. It may be ``r'' (read only),
``w'' (read-write), ``c'' (read-write - create if necessary) or ``n''
(read-write - truncate to zero length). The other arguments are rarely used
and are just passed to the low-level dbopen function. Consult the
Berkeley DB documentation for their use and interpretation.
Open a DB record format file named \var{filename}. The optional
\var{flag} identifies the mode used to open the file. It may be
\character{r} (read only), \character{w} (read-write),
\character{c} (read-write - create if necessary) or
\character{n} (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level dbopen
function. Consult the Berkeley DB documentation for their use and
interpretation.
\end{funcdesc}
@ -86,7 +98,7 @@ list returned is different for different file formats.
\end{methoddesc}
\begin{methoddesc}{has_key}{key}
Return 1 if the DB file contains the argument as a key.
Return \code{1} if the DB file contains the argument as a key.
\end{methoddesc}
\begin{methoddesc}{set_location}{key}

27
Doc/lib/libcalendar.tex
View file

@ -1,18 +1,18 @@
% This section was contributed by Drew Csillag <drew_csillag@geocities.com>.
\section{\module{calendar} ---
Functions that emulate the \UNIX{} \program{cal} program.}
General calendar-related functions}
\declaremodule{standard}{calendar}
\modulesynopsis{Functions that emulate the \UNIX{} \program{cal}
\modulesynopsis{General functions for working with the calendar,
including some emulation of the \UNIX{} \program{cal}
program.}
\sectionauthor{Drew Csillag}{drew_csillag@geocities.com}
This module allows you to output calendars like the \UNIX{}
\manpage{cal}{1} program.
\program{cal} program, and provides additional useful functions
related to the calendar.
\begin{funcdesc}{isleap}{year}
Returns \code{1} if \var{year} is a leap year.
Returns true if \var{year} is a leap year.
\end{funcdesc}
\begin{funcdesc}{leapdays}{year1, year2}
@ -48,9 +48,14 @@ Prints the calendar for the year \var{year}.
\end{funcdesc}
\begin{funcdesc}{timegm}{tuple}
An unrelated but handy function that takes a time tuple such are
returned by the \function{gmtime()} function in the \module{time}
An unrelated but handy function that takes a time tuple such as
returned by the \function{gmtime()} function in the \refmodule{time}
module, and returns the corresponding Unix timestamp value, assuming
an epoch of 1970, and the POSIX encoding. In fact,
\function{gmtime()} and \function{timegm()} are each others inverse.
\function{time.gmtime()} and \function{timegm()} are each others' inverse.
\end{funcdesc}
\begin{seealso}
\seemodule{time}{Low-level time related functions.}
\end{seealso}

36
Doc/lib/libcfgparser.tex
View file

@ -3,6 +3,8 @@
\declaremodule{standard}{ConfigParser}
\modulesynopsis{Configuration file parser.}
\moduleauthor{Ken Manheimer}{klm@digicool.com}
\moduleauthor{Barry Warsaw}{bwarsaw@python.org}
\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
This module defines the class \class{ConfigParser}.
@ -16,24 +18,27 @@ programs which can be customized by end users easily.
The configuration file consists of sections, lead by a
\samp{[section]} header and followed by \samp{name: value} entries,
with continuations in the style of \rfc{822}; \samp{name=value} is
also accepted. The optional values can contain format strings which
refer to other values in the same section, or values in a special
also accepted. Note that leading whitespace is removed from values.
The optional values can contain format strings which refer to other
values in the same section, or values in a special
\code{DEFAULT} section. Additional defaults can be provided upon
initialization and retrieval. Lines beginning with \character{\#} are
ignored and may be used to provide comments.
initialization and retrieval. Lines beginning with \character{\#} or
\character{;} are ignored and may be used to provide comments.
For example:
\begin{verbatim}
foodir: %(dir)s/whatever
dir=frob
\end{verbatim}
would resolve the \samp{\%(dir)s} to the value of dir. All reference
expansions are done late, on demand.
would resolve the \samp{\%(dir)s} to the value of
\samp{dir} (\samp{frob} in this case). All reference expansions are
done on demand.
Intrinsic defaults can be specified by passing them into the
Default values can be specified by passing them into the
\class{ConfigParser} constructor as a dictionary. Additional defaults
may be passed into the \method{get} method which will override all
may be passed into the \method{get()} method which will override all
others.
\begin{classdesc}{ConfigParser}{\optional{defaults}}
@ -50,7 +55,9 @@ Exception raised when a specified section is not found.
\end{excdesc}
\begin{excdesc}{DuplicateSectionError}
Exception raised when mutliple sections with the same name are found.
Exception raised when mutliple sections with the same name are found,
or if \method{add_section()} is called with the name of a section that
is already present.
\end{excdesc}
\begin{excdesc}{NoOptionError}
@ -87,7 +94,14 @@ Return a dictionairy containing the instance-wide defaults.
\end{methoddesc}
\begin{methoddesc}{sections}{}
Return a list of the sections available.
Return a list of the sections available; \code{DEFAULT} is not
included in the list.
\end{methoddesc}
\begin{methoddesc}{add_section}{section}
Add a section named \var{section} to the instance. If a section by
the given name already exists, \exception{DuplicateSectionError} is
raised.
\end{methoddesc}
\begin{methoddesc}{has_section}{section}
@ -123,6 +137,6 @@ A convenience method which coerces the \var{option} in the specified
\begin{methoddesc}{getboolean}{section, option}
A convenience method which coerces the \var{option} in the specified
\var{section} to a boolean value. Note that the only accepted values
for the option are \code{0} and \code{1}, any others will raise
for the option are \samp{0} and \samp{1}, any others will raise
\exception{ValueError}.
\end{methoddesc}

2
Doc/lib/libcgi.tex
View file

@ -195,7 +195,7 @@ Parse a query in the environment or from a file (default
Parse a query string given as a string argument (data of type
\mimetype{application/x-www-form-urlencoded}). Data are
returned as a dictionary. The dictionary keys are the unique query
variable names and the values are lists of vales for each name.
variable names and the values are lists of values for each name.
The optional argument \var{keep_blank_values} is
a flag indicating whether blank values in

4
Doc/lib/libcgihttp.tex
View file

@ -3,6 +3,7 @@
\declaremodule{standard}{CGIHTTPServer}
\platform{Unix}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
\modulesynopsis{This module provides a request handler for HTTP servers
which can run CGI scripts.}
@ -14,6 +15,9 @@ interface compatible with
from \class{SimpleHTTPServer.SimpleHTTPRequestHandler} but can also
run CGI scripts.
\strong{Note:} This module is \UNIX{} dependent since it creates the
CGI process using \function{os.fork()} and \function{os.exec()}.
The \module{CGIHTTPServer} module defines the following class:
\begin{classdesc}{CGIHTTPRequestHandler}{request, client_address, server}

177
Doc/lib/libcode.tex
View file

@ -1,30 +1,173 @@
\section{\module{code} ---
Code object services.}
Interpreter base classes}
\declaremodule{standard}{code}
\modulesynopsis{Code object services.}
\modulesynopsis{Base classes for interactive Python interpreters.}
The \code{code} module defines operations pertaining to Python code
objects. It defines the following function:
The \code{code} module provides facilities to implement
read-eval-print loops in Python. Two classes and convenience
functions are included which can be used to build applications which
provide an interactive interpreter prompt.
\begin{funcdesc}{compile_command}{source, \optional{filename\optional{, symbol}}}
\begin{classdesc}{InteractiveInterpreter}{\optional{locals}}
This class deals with parsing and interpreter state (the user's
namespace); it does not deal with input buffering or prompting or
input file naming (the filename is always passed in explicitly).
The optional \var{locals} argument specifies the dictionary in
which code will be executed; it defaults to a newly created
dictionary with key \code{'__name__'} set to \code{'__console__'}
and key \code{'__doc__'} set to \code{None}.
\end{classdesc}
\begin{classdesc}{InteractiveConsole}{\optional{locals\optional{, filename}}}
Closely emulate the behavior of the interactive Python interpreter.
This class builds on \class{InteractiveInterpreter} and adds
prompting using the familiar \code{sys.ps1} and \code{sys.ps2}, and
input buffering.
\end{classdesc}
\begin{funcdesc}{interact}{\optional{banner\optional{,
readfunc\optional{, local}}}}
Convenience function to run a read-eval-print loop. This creates a
new instance of \class{InteractiveConsole} and sets \var{readfunc}
to be used as the \method{raw_input()} method, if provided. If
\var{local} is provided, it is passed to the
\class{InteractiveConsole} constructor for use as the default
namespace for the interpreter loop. The \method{interact()} method
of the instance is then run with \var{banner} passed as the banner
to use, if provided. The console object is discarded after use.
\end{funcdesc}
\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.
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'}.
\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
\exception{SyntaxError} if the command is a syntax error.
Returns a code object (the same as \code{compile(\var{source},
\var{filename}, \var{symbol})}) if the command is complete and
valid; \code{None} if the command is incomplete; raises
\exception{SyntaxError} if the command is complete and contains a
syntax error, or raises \exception{OverflowError} if the command
includes a numeric constant which exceeds the range of the
appropriate numeric type.
\end{funcdesc}
\subsection{Interactive Interpreter Objects
\label{interpreter-objects}}
\begin{methoddesc}{runsource}{source\optional{, filename\optional{, symbol}}}
Compile and run some source in the interpreter.
Arguments are the same as for \function{compile_command()}; the
default for \var{filename} is \code{'<input>'}, and for
\var{symbol} is \code{'single'}. One several things can happen:
\begin{itemize}
\item
The input is incorrect; \function{compile_command()} raised an
exception (\exception{SyntaxError} or \exception{OverflowError}). A
syntax traceback will be printed by calling the
\method{showsyntaxerror()} method. \method{runsource()} returns
\code{0}.
\item
The input is incomplete, and more input is required;
\function{compile_command()} returned \code{None}.
\method{runsource()} returns \code{1}.
\item
The input is complete; \function{compile_command()} returned a code
object. The code is executed by calling the \method{runcode()} (which
also handles run-time exceptions, except for \exception{SystemExit}).
\method{runsource()} returns \code{0}.
\end{itemize}
The return value can be used to decide whether to use
\code{sys.ps1} or \code{sys.ps2} to prompt the next line.
\end{methoddesc}
\begin{methoddesc}{runcode}{code}
Execute a code object.
When an exception occurs, \method{showtraceback()} is called to
display a traceback. All exceptions are caught except
\exception{SystemExit}, which is allowed to propogate.
A note about \exception{KeyboardInterrupt}: this exception may occur
elsewhere in this code, and may not always be caught. The caller
should be prepared to deal with it.
\end{methoddesc}
\begin{methoddesc}{showsyntaxerror}{\optional{filename}}
Display the syntax error that just occurred. This does not display
a stack trace because there isn't one for syntax errors.
If \var{filename} is given, it is stuffed into the exception instead
of the default filename provided by Python's parser, because it
always uses \code{'<string>'} when reading from a string.
The output is written by the \method{write()} method.
\end{methoddesc}
\begin{methoddesc}{showtraceback}{}
Display the exception that just occurred. We remove the first stack
item because it is within the interpreter object implementation.
The output is written by the \method{write()} method.
\end{methoddesc}
\begin{methoddesc}{write}{data}
Write a string to standard output. Derived classes should override
this to provide the appropriate output handling as needed.
\end{methoddesc}
\subsection{Interactive Console Objects
\label{console-objects}}
The \class{InteractiveConsole} class is a subclass of
\class{InteractiveInterpreter}, and so offers all the methods of the
interpreter objects as well as the following additions.
\begin{methoddesc}{interact}{\optional{banner}}
Closely emulate the interactive Python console.
The optional banner argument specify the banner to print before the
first interaction; by default it prints a banner similar to the one
printed by the standard Python interpreter, followed by the class
name of the console object in parentheses (so as not to confuse this
with the real interpreter -- since it's so close!).
\end{methoddesc}
\begin{methoddesc}{push}{line}
Push a line of source text to the interpreter.
The line should not have a trailing newline; it may have internal
newlines. The line is appended to a buffer and the interpreter's
\method{runsource()} method is called with the concatenated contents
of the buffer as source. If this indicates that the command was
executed or invalid, the buffer is reset; otherwise, the command is
incomplete, and the buffer is left as it was after the line was
appended. The return value is \code{1} if more input is required,
\code{0} if the line was dealt with in some way (this is the same as
\method{runsource()}).
\end{methoddesc}
\begin{methoddesc}{resetbuffer}{}
Remove any unhandled source text from the input buffer.
\end{methoddesc}
\begin{methoddesc}{raw_input}{\optional{prompt}}
Write a prompt and read a line. The returned line does not include
the trailing newline. When the user enters the \EOF{} key sequence,
\exception{EOFError} is raised. The base implementation uses the
built-in function \function{raw_input()}; a subclass may replace this
with a different implementation.
\end{methoddesc}

30
Doc/lib/libcodeop.tex
View file

@ -1,13 +1,14 @@
% LaTeXed from excellent doc-string.
\section{\module{codeop} ---
Compile Python code}
% LaTeXed from excellent doc-string.
\declaremodule{standard}{codeop}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
\modulesynopsis{Compile (possibly incomplete) Python code.}
The \module{codeop} module provides a function to compile Python code
with hints on whether it certainly complete, possible complete or
with hints on whether it is certainly complete, possibly complete or
definitely incomplete. This is used by the \refmodule{code} module
and should not normally be used directly.
@ -15,25 +16,22 @@ The \module{codeop} module defines the following function:
\begin{funcdesc}{compile_command}
{source\optional{, filename\optional{, symbol}}}
Try to compile \var{source}, which should be a string of Python
code. Return a code object if \var{source} is valid
Tries to compile \var{source}, which should be a string of Python
code and return a code object if \var{source} is valid
Python code. In that case, the filename attribute of the code object
will be \var{filename}, which defaults to \code{'<input>'}.
Return \code{None} if \var{source} is \emph{not} valid Python
Returns \code{None} if \var{source} is \emph{not} valid Python
code, but is a prefix of valid Python code.
Raise an exception if there is a problem with \var{source}:
\begin{itemize}
\item \exception{SyntaxError}
if there is invalid Python syntax.
\item \exception{OverflowError}
if there is an invalid numeric constant.
\end{itemize}
If there is a problem with \var{source}, an exception will be raised.
\exception{SyntaxError} is raised if there is invalid Python syntax,
and \exception{OverflowError} if there is an invalid numeric
constant.
The \var{symbol} argument means whether to compile it as a statement
(\code{'single'}, the default) or as an expression (\code{'eval'}).
The \var{symbol} argument determines whether \var{source} is compiled
as a statement (\code{'single'}, the default) or as an expression
(\code{'eval'}). Any other value will cause \exception{ValueError} to
be raised.
\strong{Caveat:}
It is possible (but not likely) that the parser stops parsing

21
Doc/lib/libcompileall.tex
View file

@ -1,11 +1,7 @@
% Documentation based on module docstrings, by Fred L. Drake, Jr.
% <fdrake@acm.org>
\section{\module{compileall} ---
Byte-compile Python libraries.}
Byte-compile Python libraries}
\declaremodule{standard}{compileall}
\modulesynopsis{Tools for byte-compiling all Python source files in a
directory tree.}
@ -20,19 +16,24 @@ compile Python sources in directories named on the command line or in
\code{sys.path}.
\begin{funcdesc}{compile_dir}{dir\optional{, maxlevels\optional{, ddir}}}
\begin{funcdesc}{compile_dir}{dir\optional{, maxlevels\optional{,
ddir\optional{, force}}}}
Recursively descend the directory tree named by \var{dir}, compiling
all \file{.py} files along the way. The \var{maxlevels} parameter
is used to limit the depth of the recursion; it defaults to
\code{10}. If \var{ddir} is given, it is used as the base path from
which the filenames used in error messages will be generated.
which the filenames used in error messages will be generated. If
\var{force} is true, modules are re-compiled even if the timestamps
are up to date.
\end{funcdesc}
\begin{funcdesc}{compile_path}{\optional{skip_curdir\optional{, maxlevels}}}
\begin{funcdesc}{compile_path}{\optional{skip_curdir\optional{,
maxlevels\optional{, force}}}}
Byte-compile all the \file{.py} files found along \code{sys.path}.
If \var{skip_curdir} is true (the default), the current directory is
not included in the search. The \var{maxlevels} parameter defaults
to \code{0} and is passed to the \function{compile_dir()} function.
not included in the search. The \var{maxlevels} and
\var{force} parameters default to \code{0} and are passed to the
\function{compile_dir()} function.
\end{funcdesc}

47
Doc/lib/libcrypt.tex
View file

@ -1,29 +1,46 @@
\section{\module{crypt} ---
Function used to check \UNIX{} passwords}
Function to check \UNIX{} passwords}
\declaremodule{builtin}{crypt}
\platform{Unix}
\modulesynopsis{The \cfunction{crypt()} function used to check \UNIX{}
passwords.}
\modulesynopsis{The \cfunction{crypt()} function used to check
\UNIX{} passwords.}
\moduleauthor{Steven D. Majewski}{sdm7g@virginia.edu}
\sectionauthor{Steven D. Majewski}{sdm7g@virginia.edu}
\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
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
This module implements an interface to the
\manpage{crypt}{3}\index{crypt(3)} routine, which is a one-way hash
function based upon a modified DES\indexii{cipher}{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 \character{.}, \character{/}, or an alphanumeric character.
Returns the hashed password as a string, which will be composed of
characters from the same alphabet as the salt.
\var{word} will usually be a user's password as typed at a prompt or
in a graphical interface. \var{salt} is usually a random
two-character string which will be used to perturb the DES algorithm
in one of 4096 ways. The characters in \var{salt} must be in the
set \regexp{[./a-zA-Z0-9]}. Returns the hashed password as a
string, which will be composed of characters from the same alphabet
as the salt (the first two characters represent the salt itself).
\end{funcdesc}
The module and documentation were written by Steve Majewski.
\index{Majewski, Steve}
A simple example illustrating typical use:
\begin{verbatim}
import crypt, getpass, pwd
def login():
username = raw_input('Python login:')
cryptedpasswd = pwd.getpwnam(username)[1]
if cryptedpasswd:
if cryptedpasswd == 'x' or cryptedpasswd == '*':
raise "Sorry, currently no support for shadow passwords"
cleartext = getpass.getpass()
return crypt.crypt(cleartext, cryptedpasswd[:2]) == cryptedpasswd
else:
return 1
\end{verbatim}

47
Doc/lib/libexcs.tex
View file

@ -11,18 +11,6 @@ and users are encouraged to do the same. The source code for those
exceptions is present in the standard library module
\module{exceptions}; this module never needs to be imported explicitly.
For backward compatibility, when Python is invoked with the
\programopt{-X} option, most of the standard exceptions are
strings\footnote{
For forward-compatibility the new exceptions \exception{Exception},
\exception{LookupError}, \exception{ArithmeticError},
\exception{EnvironmentError}, and \exception{StandardError} are
tuples.
}. This option may be used to run code that breaks because of the
different semantics of class based exceptions. The
\programopt{-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.
@ -30,29 +18,27 @@ 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 \keyword{try} statement with an \keyword{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}
For class exceptions, in a \keyword{try}\stindex{try} statement with
an \keyword{except}\stindex{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.
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 \keyword{raise}
statement. For string exceptions, the associated value itself will be
stored in the variable named as the second argument of the
\keyword{except} clause (if any). For class exceptions, that variable
receives the exception instance. If the exception class is derived
from the standard root class \exception{Exception}, the associated
value is present as the exception instance's \member{args} attribute,
and possibly on other attributes as well.
\stindex{raise}
The associated value is the second argument to the
\keyword{raise}\stindex{raise} statement. For string exceptions, the
associated value itself will be stored in the variable named as the
second argument of the \keyword{except} clause (if any). For class
exceptions, that variable receives the exception instance. If the
exception class is derived from the standard root class
\exception{Exception}, the associated value is present as the
exception instance's \member{args} attribute, and possibly on other
attributes as well.
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
@ -65,6 +51,7 @@ inappropriate error.
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.
\strong{Note:} These will always be classes in Python 1.6.
\begin{excdesc}{Exception}
The root class for exceptions. All built-in exceptions are derived
@ -128,8 +115,8 @@ They are class objects, except when the \programopt{-X} option is used
to revert back to string-based standard exceptions.
\begin{excdesc}{AssertionError}
Raised when an \keyword{assert} statement fails.
\stindex{assert}
Raised when an \keyword{assert} statement fails.
\end{excdesc}
\begin{excdesc}{AttributeError}

2
Doc/lib/libfcntl.tex
View file

@ -1,10 +1,10 @@
% Manual text by Jaap Vermeulen
\section{\module{fcntl} ---
The \function{fcntl()} and \function{ioctl()} system calls}
\declaremodule{builtin}{fcntl}
\platform{Unix}
\modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.}
\sectionauthor{Jaap Vermeulen}{}
\indexii{UNIX@\UNIX{}}{file control}
\indexii{UNIX@\UNIX{}}{I/O control}

6
Doc/lib/libfileinput.tex
View file

@ -75,11 +75,13 @@ The following functions use the global state created by
\end{funcdesc}
\begin{funcdesc}{isfirstline}{}
Return true iff the line just read is the first line of its file.
Returns true the line just read is the first line of its file,
otherwise returns false.
\end{funcdesc}
\begin{funcdesc}{isstdin}{}
Returns true iff the last line was read from \code{sys.stdin}.
Returns true if the last line was read from \code{sys.stdin},
otherwise returns false.
\end{funcdesc}
\begin{funcdesc}{nextfile}{}

29
Doc/lib/libfnmatch.tex
View file

@ -5,42 +5,45 @@
\modulesynopsis{\UNIX{} shell style filename pattern matching.}
\index{filenames!wildcard expansion}
This module provides support for \UNIX{} shell-style wildcards, which
are \emph{not} the same as regular expressions (which are documented
in the \refmodule{re}\refstmodindex{re} module). The special
characters used in shell-style wildcards are:
\index{filenames!wildcard expansion}
\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}
\begin{tableii}{c|l}{code}{Pattern}{Meaning}
\lineii{*}{matches everything}
\lineii{?}{matches any single character}
\lineii{[\var{seq}]}{matches any character in \var{seq}}
\lineii{[!\var{seq}]}{matches any character not in \var{seq}}
\end{tableii}
Note that the filename separator (\code{'/'} on \UNIX{}) is \emph{not}
special to this module. See module
\refmodule{glob}\refstmodindex{glob} for pathname expansion
(\refmodule{glob} uses \function{fnmatch()} to match filename
segments).
(\refmodule{glob} uses \function{fnmatch()} to match pathname
segments). Similarly, filenames starting with a period are
not special for this module, and are matched by the \code{*} and
\code{?} patterns.
\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
lower- or upper-case before the comparison is performed. If you
require a case-sensitive comparison 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.
false; the comparison is case-sensitive.
\end{funcdesc}
\begin{seealso}
\seemodule{glob}{Shell-style path expansion}
\seemodule{glob}{\UNIX{} shell-style path expansion.}
\end{seealso}

7
Doc/lib/libgetopt.tex
View file

@ -33,9 +33,10 @@ The return value consists of two elements: the first is a 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.
element, prefixed with a hyphen for short options (e.g., \code{'-x'})
or two hyphens for long options (e.g., \code{'-}\code{-long-option'}),
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.

17
Doc/lib/libgrp.tex
View file

@ -11,10 +11,14 @@ It is available on all \UNIX{} versions.
Group database entries are reported as 4-tuples containing the
following items from the group database (see \code{<grp.h>}), in order:
\code{gr_name},
\code{gr_passwd},
\code{gr_gid},
\code{gr_mem}.
\begin{tableiii}{r|l|l}{textrm}{Index}{Field}{Meaning}
\lineiii{0}{gr_name}{the name of the group}
\lineiii{1}{gr_passwd}{the (encrypted) group password; often empty}
\lineiii{2}{gr_gid}{the numerical group ID}
\lineiii{3}{gr_mem}{all the group member's user names}
\end{tableiii}
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
@ -34,3 +38,8 @@ Return the group database entry for the given group name.
\begin{funcdesc}{getgrall}{}
Return a list of all available group entries, in arbitrary order.
\end{funcdesc}
\begin{seealso}
\seemodule{pwd}{An interface to the user database, similar to this.}
\end{seealso}

6
Doc/lib/libimaplib.tex
View file

@ -1,6 +1,3 @@
% Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
\section{\module{imaplib} ---
IMAP4 protocol client}
@ -9,6 +6,9 @@
\moduleauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au}
\sectionauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au}
% Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>;
% converted by Fred L. Drake, Jr. <fdrake@acm.org>.
\indexii{IMAP4}{protocol}
This module defines a class, \class{IMAP4}, which encapsulates a

5
Doc/lib/libintro.tex
View file

@ -22,14 +22,15 @@ 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
operating systems, such as access to specific hardware; 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
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

9
Doc/lib/liblinecache.tex
View file

@ -17,7 +17,9 @@ The \module{linecache} module defines the following functions:
\begin{funcdesc}{getline}{filename, lineno}
Get line \var{lineno} from file named \var{filename}. This function
will never throw an exception --- it will return \code{''} on errors.
will never throw an exception --- it will return \code{''} on errors
(the terminating newline character will be included for lines that are
found).
If a file named \var{filename} is not found, the function will look
for it in the module\indexiii{module}{search}{path} search path,
@ -25,9 +27,8 @@ for it in the module\indexiii{module}{search}{path} search path,
\end{funcdesc}
\begin{funcdesc}{clearcache}{}
Clear the cache. Use this function if you know that you do not need
to read lines from many of files you already read from using this
module.
Clear the cache. Use this function if you no longer need lines from
files previously read using \function{getline()}.
\end{funcdesc}
\begin{funcdesc}{checkcache}{}

6
Doc/lib/libmarshal.tex
View file

@ -62,7 +62,8 @@ The module defines these functions:
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()}.
\function{posix.popen()}. It must be opened in binary mode
(\code{'wb'} or \code{'w+b'}).
If the value has (or contains an object that has) an unsupported type,
a \exception{ValueError} exception is raised --- but garbage data
@ -73,7 +74,8 @@ The module defines these functions:
\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.
\exception{TypeError}. The file must be an open file object opened
in binary mode (\code{'rb'} or \code{'r+b'}).
\strong{Warning:} If an object containing an unsupported type was
marshalled with \function{dump()}, \function{load()} will substitute

14
Doc/lib/libmath.tex
View file

@ -5,7 +5,19 @@
\modulesynopsis{Mathematical functions (\function{sin()} etc.).}
This module is always available. It provides access to the
mathematical functions defined by the C standard. They are:
mathematical functions defined by the C standard.
These functions cannot be used with complex numbers; use the functions
of the same name from the \refmodule{cmath} module if you require
support for complex numbers. The distinction between functions which
support complex numbers and those which don't is made since most users
do not want to learn quite as much mathematics as required to
understand complex numbers. Receiving an exception instead of a
complex result allows earlier detection of the unexpected complex
number used as a parameter, so that the programmer can determine how
and why it was generated in the first place.
The following functions provided by this module:
\begin{funcdesc}{acos}{x}
Return the arc cosine of \var{x}.

6
Doc/lib/libmhlib.tex
View file

@ -1,9 +1,9 @@
% LaTeX'ized from the comments in the module by Skip Montanaro
% <skip@mojam.com>.
\section{\module{mhlib} ---
Access to MH mailboxes}
% LaTeX'ized from the comments in the module by Skip Montanaro
% <skip@mojam.com>.
\declaremodule{standard}{mhlib}
\modulesynopsis{Manipulate MH mailboxes from Python.}

10
Doc/lib/libmimetools.tex
View file

@ -2,7 +2,7 @@
Tools for parsing MIME messages}
\declaremodule{standard}{mimetools}
\modulesynopsis{Tools for parsing MIME style message bodies.}
\modulesynopsis{Tools for parsing MIME-style message bodies.}
This module defines a subclass of the \class{rfc822.Message} class and
@ -38,7 +38,7 @@ 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
Read lines from open file \var{input} until \EOF{} and write them to
open file \var{output}.
\end{funcdesc}
@ -48,6 +48,12 @@ open file \var{output}. The block size is currently fixed at 8192.
\end{funcdesc}
\begin{seealso}
\seemodule{rfc822}{Provides the base class for
\class{mimetools.Message}.}
\end{seealso}
\subsection{Additional Methods of Message objects}
\nodename{mimetools.Message Methods}

4
Doc/lib/libmimetypes.tex
View file

@ -1,7 +1,3 @@
% This document section was written by Fred L. Drake, Jr.
% <fdrake@acm.org>, based in part on original docstrings in the
% mimetypes module.
\section{\module{mimetypes} ---
Map filenames to MIME types}

2
Doc/lib/libmimewriter.tex
View file

@ -54,7 +54,7 @@ insert at the start.
boundary\optional{, plist\optional{, prefix}}}}
Returns a file-like object which can be used to write to the
body of the message. Additionally, this method initializes the
multi-part code, where \var{subtype} provides the mutlipart subtype,
multi-part code, where \var{subtype} provides the multipart subtype,
\var{boundary} may provide a user-defined boundary specification, and
\var{plist} provides optional parameters for the subtype.
\var{prefix} functions as in \method{startbody()}. Subparts should be

4
Doc/lib/libnetrc.tex
View file

@ -1,5 +1,3 @@
% Module and documentation by Eric S. Raymond, 21 Dec 1998
\section{\module{netrc} ---
netrc file processing}
@ -45,7 +43,7 @@ Dump the class data as a string in the format of a netrc file.
Instances of \class{netrc} have public instance variables:
\begin{memberdesc}{hosts}
Dictionmary mapping host names to \code{(\var{login}, \var{account},
Dictionary mapping host names to \code{(\var{login}, \var{account},
\var{password})} tuples. The `default' entry, if any, is represented
as a pseudo-host by that name.
\end{memberdesc}

4
Doc/lib/libnis.tex
View file

@ -5,7 +5,7 @@
\platform{UNIX}
\moduleauthor{Fred Gansevles}{Fred.Gansevles@cs.utwente.nl}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
\modulesynopsis{Interface to Sun's N.I.S. (a.k.a. Yellow Pages) library.}
\modulesynopsis{Interface to Sun's NIS (a.k.a. Yellow Pages) library.}
The \module{nis} module gives a thin wrapper around the NIS library, useful
for central administration of several hosts.
@ -23,8 +23,6 @@ Return value is an arbitary array of bytes (i.e., may contain \code{NULL}
and other joys).
Note that \var{mapname} is first checked if it is an alias to another name.
XXX Describe list of all aliases? Internal for the C code, so
I'm not sure it's a good idea.
\end{funcdesc}
\begin{funcdesc}{cat}{mapname}

40
Doc/lib/libos.tex
View file

@ -262,7 +262,9 @@ 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, except that when the exit status is zero (termination without
errors), \code{None} is returned.
errors), \code{None} is returned. \strong{Note:} This function
behaves unreliably under Windows due to the native implementation of
\cfunction{popen()}.
Availability: \UNIX{}, Windows.
\end{funcdesc}
@ -443,12 +445,35 @@ Availability: Macintosh, \UNIX{}, Windows.
\subsection{Files and Directories \label{os-file-dir}}
\begin{funcdesc}{access}{path, mode}
Check read/write/execute permissions for this process or extance of file
\var{path}. Return \code{1} if access is granted, \code{0} if not.
See the \UNIX{} manual for the semantics.
Check read/write/execute permissions for this process or existence of
file \var{path}. \var{mode} should be \constant{F_OK} to test the
existence of \var{path}, or it can be the inclusive OR of one or more
of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to test
permissions. Return \code{1} if access is allowed, \code{0} if not.
See the \UNIX{} man page \manpage{access}{2} for more information.
Availability: \UNIX{}.
\end{funcdesc}
\begin{datadesc}{F_OK}
Value to pass as the \var{mode} parameter of \function{access()} to
test the existence of \var{path}.
\end{datadesc}
\begin{datadesc}{R_OK}
Value to include in the \var{mode} parameter of \function{access()}
to test the readability of \var{path}.
\end{datadesc}
\begin{datadesc}{W_OK}
Value to include in the \var{mode} parameter of \function{access()}
to test the writability of \var{path}.
\end{datadesc}
\begin{datadesc}{X_OK}
Value to include in the \var{mode} parameter of \function{access()}
to determine if \var{path} can be executed.
\end{datadesc}
\begin{funcdesc}{chdir}{path}
\index{directory!changing}
Change the current working directory to \var{path}.
@ -877,9 +902,10 @@ process status is available immediately.
Availability: \UNIX{}.
\end{datadesc}
The following functions take a process stats code as returned by
\function{waitpid()} as a parameter. They may be used to determine
the disposition of a process.
The following functions take a process status code as returned by
\function{system()}, \function{wait()}, or \function{waitpid()} as a
parameter. They may be used to determine the disposition of a
process.
\begin{funcdesc}{WIFSTOPPED}{status}
Return true if the process has been stopped.

24
Doc/lib/libparser.tex
View file

@ -1,5 +1,6 @@
% libparser.tex
%
\section{\module{parser} ---
Access Python parse trees}
% 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
@ -7,10 +8,6 @@
% in any representation, either on paper or electronically. This
% restriction does not affect other elements in a distributed package
% in any way.
%
\section{\module{parser} ---
Access Python parse trees}
\declaremodule{builtin}{parser}
\modulesynopsis{Access parse trees for Python source code.}
@ -166,7 +163,7 @@ extracted with or without line numbering information.
\begin{funcdesc}{ast2list}{ast\optional{, line_info}}
This function accepts an AST object from the caller in
\var{ast} and returns a Python list representing the
equivelent parse tree. The resulting list representation can be used
equivalent 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
@ -185,7 +182,7 @@ omitted if the flag is false or omitted.
\begin{funcdesc}{ast2tuple}{ast\optional{, line_info}}
This function accepts an AST object from the caller in
\var{ast} and returns a Python tuple representing the
equivelent parse tree. Other than returning a tuple instead of a
equivalent parse tree. Other than returning a tuple instead of a
list, this function is identical to \function{ast2list()}.
If \var{line_info} is true, line number information will be
@ -238,7 +235,7 @@ identical to those created by the built-in
\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
``suite.'' It is not safe to assume that this function is equivalent
to \samp{not isexpr(\var{ast})}, as additional syntactic fragments may
be supported in the future.
\end{funcdesc}
@ -274,9 +271,6 @@ 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 \refmodule{pickle} module) is also
supported.
@ -326,7 +320,7 @@ discovery.
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
intermediate data structure is equivalent to the code
\begin{verbatim}
>>> code = compile('a + 5', 'eval')
@ -335,7 +329,7 @@ intermediate data structure is equivelent to the code
10
\end{verbatim}
The equivelent operation using the \module{parser} module is somewhat
The equivalent operation using the \module{parser} module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
@ -474,7 +468,7 @@ 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
check any given subtree for equivalence 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

108
Doc/lib/libpickle.tex
View file

@ -3,6 +3,7 @@
\declaremodule{standard}{pickle}
\modulesynopsis{Convert Python objects to streams of bytes and back.}
% Substantial improvements by Jim Kerr <jbkerr@sr.hp.com>.
\index{persistency}
\indexii{persistent}{objects}
@ -37,17 +38,29 @@ interface except that \class{Pickler} and \class{Unpickler} are
factory functions, not classes (so they cannot be used as base classes
for inheritance).
Unlike the built-in module \refmodule{marshal}\refbimodindex{marshal},
\module{pickle} handles the following correctly:
Although the \module{pickle} module can use the built-in module
\refmodule{marshal}\refbimodindex{marshal} internally, it differs from
\refmodule{marshal} in the way it handles certain kinds of data:
\begin{itemize}
\item recursive objects (objects containing references to themselves)
\item Recursive objects (objects containing references to themselves):
\module{pickle} keeps track of the objects it has already
serialized, so later references to the same object won't be
serialized again. (The \refmodule{marshal} module breaks for
this.)
\item object sharing (references to the same object in different places)
\item Object sharing (references to the same object in different
places): This is similar to self-referencing objects;
\module{pickle} stores the object once, and ensures that all
other references point to the master copy. Shared objects
remain shared, which can be very important for mutable objects.
\item user-defined classes and their instances
\item User-defined classes and their instances: \refmodule{marshal}
does not support these at all, but \module{pickle} can save
and restore class instances transparently. The class definition
must be importable and live in the same module as when the
object was stored.
\end{itemize}
@ -177,16 +190,15 @@ x = pickle.load(f)
\end{verbatim}
The \class{Pickler} class only calls the method \code{f.write()} with a
\withsubitem{(class in pickle)}{
\ttindex{Unpickler}\ttindex{Pickler}}
\withsubitem{(class in pickle)}{\ttindex{Unpickler}\ttindex{Pickler}}
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.
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,
argument, \var{bin}. If this is present and true, the binary
pickle format is used; if it is absent or false, 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.
@ -203,6 +215,11 @@ The following types can be pickled:
\item tuples, lists and dictionaries containing only picklable objects
\item functions defined at the top level of a module (by name
reference, not storage of the implementation)
\item built-in functions
\item classes that are defined at the top level in a module
\item instances of such classes whose \member{__dict__} or
@ -276,11 +293,80 @@ This exception is raised when an unpicklable object is passed to
\end{seealso}
\subsection{Example \label{pickle-example}}
Here's a simple example of how to modify pickling behavior for a
class. The \class{TextReader} class opens a text file, and returns
the line number and line contents each time its \method{readline()}
method is called. If a \class{TextReader} instance is pickled, all
attributes \emph{except} the file object member are saved. When the
instance is unpickled, the file is reopened, and reading resumes from
the last location. The \method{__setstate__()} and
\method{__getstate__()} methods are used to implement this behavior.
\begin{verbatim}
# illustrate __setstate__ and __getstate__ methods
# used in pickling.
class TextReader:
"Print and number lines in a text file."
def __init__(self,file):
self.file = file
self.fh = open(file,'r')
self.lineno = 0
def readline(self):
self.lineno = self.lineno + 1
line = self.fh.readline()
if not line:
return None
return "%d: %s" % (self.lineno,line[:-1])
# return data representation for pickled object
def __getstate__(self):
odict = self.__dict__ # get attribute dictionary
del odict['fh'] # remove filehandle entry
return odict
# restore object state from data representation generated
# by __getstate__
def __setstate__(self,dict):
fh = open(dict['file']) # reopen file
count = dict['lineno'] # read from file...
while count: # until line count is restored
fh.readline()
count = count - 1
dict['fh'] = fh # create filehandle entry
self.__dict__ = dict # make dict our attribute dictionary
\end{verbatim}
A sample usage might be something like this:
\begin{verbatim}
>>> import TextReader
>>> obj = TextReader.TextReader("TextReader.py")
>>> obj.readline()
'1: #!/usr/local/bin/python'
>>> # (more invocations of obj.readline() here)
... obj.readline()
'7: class TextReader:'
>>> import pickle
>>> pickle.dump(obj,open('save.p','w'))
(start another Python session)
>>> import pickle
>>> reader = pickle.load(open('save.p'))
>>> reader.readline()
'8: "Print and number lines in a text file."'
\end{verbatim}
\section{\module{cPickle} ---
Alternate implementation of \module{pickle}}
\declaremodule{builtin}{cPickle}
\modulesynopsis{Faster version of \module{pickle}, but not subclassable.}
\modulesynopsis{Faster version of \refmodule{pickle}, but not subclassable.}
\moduleauthor{Jim Fulton}{jfulton@digicool.com}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}

10
Doc/lib/libpoplib.tex
View file

@ -1,14 +1,14 @@
%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{\module{poplib} ---
POP3 protocol client}
\declaremodule{standard}{poplib}
\modulesynopsis{POP3 protocol client (requires sockets).}
%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''.
\indexii{POP3}{protocol}
This module defines a class, \class{POP3}, which encapsulates a

4
Doc/lib/libposixpath.tex
View file

@ -127,8 +127,8 @@ slashes.
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.
case (use \function{normcase()} for that). On Windows, it converts
forward slashes to backward slashes.
\end{funcdesc}
\begin{funcdesc}{samefile}{path1, path2}

6
Doc/lib/libpty.tex
View file

@ -1,11 +1,7 @@
%%%% LaTeX'ed and enhanced from comments in file
%%%% Skipped some functions which seemed to be for private
%%%% usage (decision debatable).
\section{\module{pty} ---
Pseudo-terminal utilities}
\declaremodule{standard}{pty}
\platform{IRIX, Linux} %XXX Is that the right way???
\platform{IRIX, Linux}
\modulesynopsis{Pseudo-Terminal Handling for SGI and Linux.}
\moduleauthor{Steen Lumholt}{}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}

35
Doc/lib/libpwd.tex
View file

@ -5,21 +5,33 @@
\platform{Unix}
\modulesynopsis{The password database (\function{getpwnam()} and friends).}
This module provides access to the \UNIX{} password database.
It is available on all \UNIX{} versions.
This module provides access to the \UNIX{} user account and 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 \code{<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}.
\begin{tableiii}{r|l|l}{textrm}{Index}{Field}{Meaning}
\lineiii{0}{\code{pw_name}}{Login name}
\lineiii{1}{\code{pw_passwd}}{Optional encrypted password}
\lineiii{2}{\code{pw_uid}}{Numerical user ID}
\lineiii{3}{\code{pw_gid}}{Numerical group ID}
\lineiii{4}{\code{pw_gecos}}{User name or comment field}
\lineiii{5}{\code{pw_dir}}{User home directory}
\lineiii{6}{\code{pw_shell}}{User command interpreter}
\end{tableiii}
The uid and gid items are integers, all others are strings.
\exception{KeyError} is raised if the entry asked for cannot be found.
\strong{Note:} In traditional \UNIX{} the field \code{pw_passwd} usually
contains a password encrypted with a DES derived algorithm (see module
\refmodule{crypt}\refbimodindex{crypt}). However most modern unices
use a so-called \emph{shadow password} system. On those unices the
field \code{pw_passwd} only contains a asterisk (\code{'*'}) or the
letter \character{x} where the encrypted password is stored in a file
\file{/etc/shadow} which is not world readable.
It defines the following items:
\begin{funcdesc}{getpwuid}{uid}
@ -33,3 +45,8 @@ Return the password database entry for the given user name.
\begin{funcdesc}{getpwall}{}
Return a list of all available password database entries, in arbitrary order.
\end{funcdesc}
\begin{seealso}
\seemodule{grp}{An interface to the group database, similar to this.}
\end{seealso}

6
Doc/lib/libpycompile.tex
View file

@ -1,9 +1,9 @@
\section{\module{py_compile} ---
Compile Python source files}
% Documentation based on module docstrings, by Fred L. Drake, Jr.
% <fdrake@acm.org>
\section{\module{py_compile} ---
Compile Python source files.}
\declaremodule[pycompile]{standard}{py_compile}
\modulesynopsis{Compile Python source files to byte-code files.}

2
Doc/lib/libqueue.tex
View file

@ -32,7 +32,7 @@ empty or locked.
\begin{excdesc}{Full}
Exception raised when non-blocking \method{put()} (or
\method{get_nowait()}) is called on a \class{Queue} object which is
\method{put_nowait()}) is called on a \class{Queue} object which is
full or locked.
\end{excdesc}

66
Doc/lib/librandom.tex
View file

@ -12,22 +12,25 @@ 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 \refmodule{whrandom} module:
\function{choice()}, \function{randint()}, \function{random()} and
\function{uniform()}. See the documentation for the
\refmodule{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.
The \module{random} module supports the \emph{Random Number
Generator} interface, described in section \ref{rng-objects}. This
interface of the module, as well as the distribution-specific
functions described below, all use the pseudo-random generator
provided by the \refmodule{whrandom} module.
The following functions are defined to support specific distributions,
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. These are expected to become part of the Random
Number Generator interface in a future release.
\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.
Returned values range between 0 and 1.
\end{funcdesc}
\begin{funcdesc}{cunifvariate}{mean, arc}
@ -59,8 +62,8 @@ standard deviation. This is slightly faster than the
\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.
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}
@ -86,5 +89,40 @@ Weibull distribution. \var{alpha} is the scale parameter and
\end{funcdesc}
\begin{seealso}
\seemodule{whrandom}{the standard Python random number generator}
\seemodule{whrandom}{The standard Python random number generator.}
\end{seealso}
\subsection{The Random Number Generator Interface
\label{rng-objects}}
% XXX This *must* be updated before a future release!
The \dfn{Random Number Generator} interface describes the methods
which are available for all random number generators. This will be
enhanced in future releases of Python.
In this release of Python, the modules \refmodule{random},
\refmodule{whrandom}, and instances of the
\class{whrandom.whrandom} class all conform to this interface.
\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}{uniform}{a, b}
Returns a random real number \var{N} such that
\code{\var{a} <= \var{N} < \var{b}}.
\end{funcdesc}

25
Doc/lib/librfc822.tex
View file

@ -8,10 +8,11 @@ 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. This module also defines a helper class
\class{AddressList} for parsing \rfc{822} addresses.
\class{AddressList} for parsing \rfc{822} addresses. Please refer to
the RFC for information on the specific syntax of \rfc{822} headers.
Note that there's a separate module to read \UNIX{}, MH, and MMDF
style mailbox files: \refmodule{mailbox}\refstmodindex{mailbox}.
The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes
to read mailboxes produced by various end-user mail programs.
\begin{classdesc}{Message}{file\optional{, seekable}}
A \class{Message} instance is instantiated with an input object as
@ -61,7 +62,8 @@ however, some mailers don't follow that format as specified, so
\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.
returned. Note that fields 6, 7, and 8 of the result tuple are not
usable.
\end{funcdesc}
\begin{funcdesc}{parsedate_tz}{date}
@ -74,7 +76,8 @@ 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}.
\code{None}. Note that fields 6, 7, and 8 of the result tuple are not
usable.
\end{funcdesc}
\begin{funcdesc}{mktime_tz}{tuple}
@ -87,6 +90,12 @@ switch dates. Not enough to worry about for common use.
\end{funcdesc}
\begin{seealso}
\seemodule{mailbox}{Classes to read various mailbox formats produced
by end-user mail programs.}
\end{seealso}
\subsection{Message Objects \label{message-objects}}
A \class{Message} instance has the following methods:
@ -180,7 +189,8 @@ continuation lines the named headers contain are also parsed.
\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
compatible with \function{time.mktime()}; note that fields 6, 7, and 8
are not usable. 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
@ -193,7 +203,8 @@ function may occasionally yield an incorrect result.
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
of the date's timezone from UTC. Note that fields 6, 7, and 8
are not usable. Similarly to \method{getdate()}, if
there is no header matching \var{name}, or it is unparsable, return
\code{None}.
\end{methoddesc}

6
Doc/lib/libsched.tex
View file

@ -1,7 +1,8 @@
% LaTeXed and enhanced from comments in file
\section{\module{sched} ---
Event scheduler}
% LaTeXed and enhanced from comments in file
\declaremodule{standard}{sched}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
\modulesynopsis{General purpose event scheduler.}
@ -49,7 +50,8 @@ From print_time 930343700.273
\begin{methoddesc}{enterabs}{time, priority, action, argument}
Schedule a new event. The \var{time} argument should be a numeric type
compatible to the return value of \var{timefunc}. Events scheduled for
compatible with the return value of the \var{timefunc} function passed
to the constructor. Events scheduled for
the same \var{time} will be executed in the order of their
\var{priority}.

2
Doc/lib/libselect.tex
View file

@ -9,7 +9,7 @@ This module provides access to the function \cfunction{select()}
available in most operating systems. Note that on Windows, it only
works for sockets; on other operating systems, it also works for other
file types (in particular, on \UNIX{}, it works on pipes). It cannot
be used or regular files to determine whether a file has grown since
be used on regular files to determine whether a file has grown since
it was last read.
The module defines the following:

2
Doc/lib/libshlex.tex
View file

@ -1,5 +1,3 @@
% Module and documentation by Eric S. Raymond, 21 Dec 1998
\section{\module{shlex} ---
Simple lexical analysis}

53
Doc/lib/libsmtplib.tex
View file

@ -74,6 +74,17 @@ A nice selection of exceptions is defined as well:
\end{excdesc}
\begin{seealso}
\seetext{Internet \rfc{821}, \emph{Simple Mail Transfer Protocol}.
Available online at
\url{http://info.internet.isi.edu/in-notes/rfc/files/rfc821.txt}.}
\seetext{Internet \rfc{1869}, \emph{SMTP Service Extensions}.
Available online at
\url{http://info.internet.isi.edu/in-notes/rfc/files/rfc1869.txt}.}
\end{seealso}
\subsection{SMTP Objects \label{SMTP-objects}}
An \class{SMTP} instance has the following methods:
@ -160,6 +171,10 @@ need to use different ESMTP options to different recipients you have
to use the low-level methods such as \method{mail}, \method{rcpt} and
\method{data} to send the message.)
\strong{Note:} The \var{from_addr} and \var{to_addrs} parameters are
used to construct the message envelope used by the transport agents.
The \class{SMTP} does not modify the message headers in any way.
If there has been no previous \samp{EHLO} or \samp{HELO} command this
session, this method tries ESMTP \samp{EHLO} first. If the server does
ESMTP, message size and each of the specified options will be passed
@ -177,27 +192,25 @@ message sent by the server.
This method may raise the following exceptions:
\begin{itemize}
\begin{description}
\item[\exception{SMTPRecipientsRefused}]
All recipients were refused. Nobody got the mail. The
\var{recipients} attribute of the exception object is a dictionary
\member{recipients} attribute of the exception object is a dictionary
with information about the refused recipients (like the one returned
when at least one recipient was accepted).
\item[\exception{SMTPHeloError}]
The server didn't reply properly to
the helo greeting.
The server didn't reply properly to the \samp{HELO} greeting.
\item[\exception{SMTPSenderRefused}]
The server didn't accept the from_addr.
The server didn't accept the \var{from_addr}.
\item[\exception{SMTPDataError}]
The server replied with an unexpected
error code (other than a refusal of
a recipient).
\end{itemize}
The server replied with an unexpected error code (other than a refusal
of a recipient).
\end{description}
Unless otherwise noted the connection will be open even after
Unless otherwise noted, the connection will be open even after
an exception is raised.
\end{methoddesc}
@ -216,33 +229,37 @@ consult the module code.
\subsection{SMTP Example \label{SMTP-example}}
This example prompts the user for addresses needed in the message
envelop (`To' and `From' addresses), and the message to be
envelope (`To' and `From' addresses), and the message to be
delivered. Note that the headers to be included with the message must
be included in the message as entered; this example doesn't do any
processing of the \rfc{822} headers. In particular, the `To' and
`From' addresses must be included in the message headers explicitly.
\begin{verbatim}
import rfc822, string, sys
import smtplib
import string
def prompt(prompt):
sys.stdout.write(prompt + ": ")
return string.strip(sys.stdin.readline())
return string.strip(raw_input(prompt))
fromaddr = prompt("From")
toaddrs = string.splitfields(prompt("To"), ',')
fromaddr = prompt("From: ")
toaddrs = string.split(prompt("To: "))
print "Enter message, end with ^D:"
msg = ""
# Add the From: and To: headers at the start!
msg = ("From: %s\r\nTo: %s\r\n\r\n"
% (fromaddr, string.join(toaddrs, ", ")))
while 1:
line = sys.stdin.readline()
line = raw_input()
if not line:
break
msg = msg + line
print "Message length is " + `len(msg)`
server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.connect()
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
\end{verbatim}

11
Doc/lib/libsocket.tex
View file

@ -6,16 +6,19 @@
This module provides access to the BSD \emph{socket} interface.
It is available on \UNIX{} systems that support this interface.
It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS,
OS/2, and probably additional platforms.
For an introduction to socket programming (in C), see the following
papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
Interprocess Communication Tutorial}, by Samuel J. Leffler et al,
both in the \citetitle{\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.
(sections PS1:7 and PS1:8). The platform-specific reference material
for the various socket-related system calls are also a valuable source
of information on the details of socket semantics. For \UNIX, refer
to the manual pages; for Windows, see the WinSock (or Winsock 2)
specification.
The Python interface is a straightforward transliteration of the
\UNIX{} system call and library interface for sockets to Python's

4
Doc/lib/libstatvfs.tex
View file

@ -22,6 +22,10 @@ Preferred file system block size.
Fundamental file system block size.
\end{datadesc}
\begin{datadesc}{F_BLOCKS}
Total number of blocks in the filesystem.
\end{datadesc}
\begin{datadesc}{F_BFREE}
Total number of free blocks.
\end{datadesc}

177
Doc/lib/libstdtypes.tex
View file

@ -30,15 +30,17 @@ The following values are considered false:
\item \code{None}
\withsubitem{(Built-in object)}{\ttindex{None}}
\item zero of any numeric type, e.g., \code{0}, \code{0L}, \code{0.0}.
\item zero of any numeric type, for example, \code{0}, \code{0L},
\code{0.0}, \code{0j}.
\item any empty sequence, e.g., \code{''}, \code{()}, \code{[]}.
\item any empty sequence, for example, \code{''}, \code{()}, \code{[]}.
\item any empty mapping, e.g., \code{\{\}}.
\item any empty mapping, for example, \code{\{\}}.
\item instances of user-defined classes, if the class defines a
\method{__nonzero__()} or \method{__len__()} method, when that
method returns zero.
method returns zero.\footnote{Additional information on these
special methods may be found in the \emph{Python Reference Manual}.}
\end{itemize}
@ -77,9 +79,9 @@ Notes:
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.
\samp{not} has a lower priority than non-Boolean operators, so
\code{not \var{a} == \var{b}} is interpreted as \code{not (\var{a} ==
\var{b})}, and \code{\var{a} == not \var{b}} is a syntax error.
\end{description}
@ -88,10 +90,11 @@ These only evaluate their second argument if needed for their outcome.
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).
Comparisons can be chained arbitrarily; for example, \code{\var{x} <
\var{y} <= \var{z}} is equivalent to \code{\var{x} < \var{y} and
\var{y} <= \var{z}}, except that \var{y} is evaluated only once (but
in both cases \var{z} is not evaluated at all when \code{\var{x} <
\var{y}} is found to be false).
\indexii{chaining}{comparisons}
This table summarizes the comparison operations:
@ -123,26 +126,33 @@ Notes:
\index{ABC language@\ABC{} language}
\index{language!ABC@\ABC{}}
\indexii{C@\C{}}{language}
\code{!=} is the preferred spelling; \code{<>} is obsolescent.
\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}
Furthermore, some types (for example, file objects) 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{object}{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.)
Instances of a class normally compare as non-equal unless the class
\withsubitem{(instance method)}{\ttindex{__cmp__()}}
defines the \method{__cmp__()} method. Refer to the \emph{Python
Reference Manual} for information on the use of this method to effect
object comparisons.
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}
\strong{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}\opindex{in} and \samp{not in}\opindex{not in}, are supported
only by sequence types (below).
\subsection{Numeric Types \label{typesnumeric}}
@ -150,9 +160,9 @@ Two more operations with the same syntactic priority, \samp{in} and
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 \ctype{long} in \C{}, which gives them at least 32
are implemented using \ctype{long} in C, which gives them at least 32
bits of precision. Long integers have unlimited precision. Floating
point numbers are implemented using \ctype{double} in \C{}. All bets on
point numbers are implemented using \ctype{double} in C. All bets on
their precision are off unless you happen to know the machine you are
working with.
\indexii{numeric}{types}
@ -161,20 +171,20 @@ working with.
\indexiii{long}{integer}{type}
\indexii{floating point}{type}
\indexii{complex number}{type}
\indexii{C@\C{}}{language}
\indexii{C}{language}
Complex numbers have a real and imaginary part, which are both
implemented using \ctype{double} in \C{}. To extract these parts from
implemented using \ctype{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.
and octal numbers) yield plain integers. Integer literals with an
\character{L} or \character{l} suffix yield long integers
(\character{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 \character{j} or
\character{J} to a numeric literal yields a complex number.
\indexii{numeric}{literals}
\indexii{integer}{literals}
\indexiii{long}{integer}{literals}
@ -236,21 +246,23 @@ Notes:
\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.
(-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result
is a long integer if either operand is a long integer, regardless of
the numeric value.
\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 \function{floor()} and \function{ceil()} in
module \module{math} for well-defined conversions.
module \refmodule{math}\refbimodindex{math} for well-defined conversions.
\withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}}
\indexii{numeric}{conversions}
\refbimodindex{math}
\indexii{C@\C{}}{language}
\item[(3)]
See the section on built-in functions for an exact definition.
See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full
description.
\end{description}
% XXXJH exceptions: overflow (when? what operations?) zerodivision
@ -302,7 +314,7 @@ division by \code{pow(2, \var{n})} without overflow check.
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
\code{'xyzzy'}, \code{"frobozz"}. See chapter 2 of the
\citetitle[../ref/ref.html]{Python Reference Manual} for more about
string literals. Lists are constructed with square brackets,
separating items with commas: \code{[a, b, c]}. Tuples are
@ -332,10 +344,10 @@ and \var{j} are integers:
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}\textrm{,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{(3)}
\lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{(1)}
\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)}
\lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(2)}
\lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(2), (3)}
\hline
\lineiii{len(\var{s})}{length of \var{s}}{}
\lineiii{min(\var{s})}{smallest item of \var{s}}{}
@ -356,23 +368,21 @@ equal to \var{x}, else \code{1}}{}
Notes:
\begin{description}
\item[(1)] 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}).
\item[(1)] If \var{i} or \var{j} is negative, the index is relative to
\item[(2)] 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
\item[(3)] 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}
@ -452,24 +462,24 @@ The following operations are defined on mutable sequence types (where
\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}]}}{}
{same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(1)}
\lineiii{\var{s}.extend(\var{x})}
{same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(5)}
{same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(2)}
\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)}
{return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(3)}
\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}.pop(\optional{\var{i}})}
{same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(4)}
\lineiii{\var{s}.remove(\var{x})}
{same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(1)}
{same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(3)}
\lineiii{\var{s}.reverse()}
{reverses the items of \var{s} in place}{(3)}
{reverses the items of \var{s} in place}{(5)}
\lineiii{\var{s}.sort(\optional{\var{cmpfunc}})}
{sort the items of \var{s} in place}{(2), (3)}
{sort the items of \var{s} in place}{(5), (6)}
\end{tableiii}
\indexiv{operations on}{mutable}{sequence}{types}
\indexiii{operations on}{sequence}{types}
@ -484,10 +494,29 @@ The following operations are defined on mutable sequence types (where
\noindent
Notes:
\begin{description}
\item[(1)] Raises \exception{ValueError} when \var{x} is not found in
\item[(1)] The C implementation of Python has historically accepted
multiple parameters and implicitly joined them into a tuple; this
will no longer work in Python 1.6. Use of this misfeature has been
deprecated since Python 1.4.
\item[(2)] Raises an exception when \var{x} is not a list object. The
\method{extend()} method is experimental and not supported by
mutable sequence types other than lists.
\item[(3)] Raises \exception{ValueError} when \var{x} is not found in
\var{s}.
\item[(2)] The \method{sort()} method takes an optional argument
\item[(4)] The \method{pop()} method is experimental and not supported
by other mutable sequence types than lists. The optional argument
\var{i} defaults to \code{-1}, so that by default the last item is
removed and returned.
\item[(5)] The \method{sort()} and \method{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.
\item[(6)] The \method{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
@ -497,24 +526,12 @@ Notes:
\method{reverse()} than to use the built-in function
\function{sort()} with a comparison function that reverses the
ordering of the elements.
\item[(3)] The \method{sort()} and \method{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.
\item[(4)] The \method{pop()} method is experimental and not supported
by other mutable sequence types than lists. The optional argument
\var{i} defaults to \code{-1}, so that by default the last item is
removed and returned.
\item[(5)] Raises an exception when \var{x} is not a list object. The
\method{extend()} method is experimental and not supported by
mutable types other than lists.
\end{description}
\subsection{Mapping Types \label{typesmapping}}
\indexii{mapping}{types}
\indexii{dictionary}{type}
A \dfn{mapping} object maps values of one type (the key type) to
arbitrary objects. Mappings are mutable objects. There is currently
@ -527,9 +544,6 @@ 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
@ -586,12 +600,17 @@ Notes:
\item[(1)] Raises a \exception{KeyError} exception if \var{k} is not
in the map.
\item[(2)] Keys and values are listed in random order.
\item[(2)] Keys and values are listed in random order. If
\method{keys()} and \method{values()} are called with no intervening
modifications to the dictionary, the two lists will directly
correspond. This allows the creation of \code{(\var{value},
\var{key})} pairs using \function{map()}: \samp{pairs = map(None,
\var{a}.values(), \var{a}.keys())}.
\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 \var{f} is not
instead it returns \var{x}. \var{x} is optional; when \var{x} is not
provided and \var{k} is not in the map, \code{None} is returned.
\end{description}
@ -629,7 +648,7 @@ written as \code{<module 'os' from '/usr/local/lib/python1.5/os.pyc'>}.
\subsubsection{Classes and Class Instances \label{typesobjects}}
\nodename{Classes and Instances}
See Chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python
Reference Manual} for these.
@ -730,7 +749,7 @@ It is written as \code{Ellipsis}.
File objects are implemented using \C{}'s \code{stdio}
package and can be created with the built-in function
\function{open()}\bifuncindex{open} described section
\function{open()}\bifuncindex{open} described in section
\ref{built-in-funcs}, ``Built-in Functions.'' They are also returned
by some other built-in functions and methods, e.g.,
\function{posix.popen()} and \function{posix.fdopen()} and the
@ -793,7 +812,7 @@ descriptors, e.g. module \module{fcntl} or \function{os.read()} and friends.
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
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}
@ -823,12 +842,12 @@ descriptors, e.g. module \module{fcntl} or \function{os.read()} and friends.
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
operating system version (for example, 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
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}

46
Doc/lib/libstruct.tex
View file

@ -45,23 +45,35 @@ The module defines the following exception and functions:
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}{\ctype{char}}{string of length 1}
\lineiii{b}{\ctype{signed char}}{integer}
\lineiii{B}{\ctype{unsigned char}}{integer}
\lineiii{h}{\ctype{short}}{integer}
\lineiii{H}{\ctype{unsigned short}}{integer}
\lineiii{i}{\ctype{int}}{integer}
\lineiii{I}{\ctype{unsigned int}}{integer}
\lineiii{l}{\ctype{long}}{integer}
\lineiii{L}{\ctype{unsigned long}}{integer}
\lineiii{f}{\ctype{float}}{float}
\lineiii{d}{\ctype{double}}{float}
\lineiii{s}{\ctype{char[]}}{string}
\lineiii{p}{\ctype{char[]}}{string}
\lineiii{P}{\ctype{void *}}{integer}
\end{tableiii}
\begin{tableiv}{c|l|l|c}{samp}{Format}{C Type}{Python}{Notes}
\lineiv{x}{pad byte}{no value}{}
\lineiv{c}{\ctype{char}}{string of length 1}{}
\lineiv{b}{\ctype{signed char}}{integer}{}
\lineiv{B}{\ctype{unsigned char}}{integer}{}
\lineiv{h}{\ctype{short}}{integer}{}
\lineiv{H}{\ctype{unsigned short}}{integer}{}
\lineiv{i}{\ctype{int}}{integer}{}
\lineiv{I}{\ctype{unsigned int}}{long}{(1)}
\lineiv{l}{\ctype{long}}{integer}{}
\lineiv{L}{\ctype{unsigned long}}{long}{}
\lineiv{f}{\ctype{float}}{float}{}
\lineiv{d}{\ctype{double}}{float}{}
\lineiv{s}{\ctype{char[]}}{string}{}
\lineiv{p}{\ctype{char[]}}{string}{}
\lineiv{P}{\ctype{void *}}{integer}{}
\end{tableiv}
\noindent
Notes:
\begin{description}
\item[(1)]
The \character{I} conversion code will convert to a Python long if
the C \ctype{int} is the same size as a C \ctype{long}, which is
typical on most modern systems. If a C \ctype{int} is smaller than
a C \ctype{long}, an Python integer will be created instead.
\end{description}
A format character may be preceded by an integral repeat count;
e.g.\ the format string \code{'4h'} means exactly the same as

28
Doc/lib/libsys.tex
View file

@ -31,6 +31,11 @@ It is always available.
A string containing the copyright pertaining to the Python interpreter.
\end{datadesc}
\begin{datadesc}{dllhandle}
Integer specifying the handle of the Python DLL.
Availability: Windows.
\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
@ -285,5 +290,26 @@ exception type and value are printed.
\end{datadesc}
\begin{datadesc}{version}
A string containing the version number of the Python interpreter.
A string containing the version number of the Python interpreter plus
additional information on the build number and compiler used. It has
a value of the form \code{'\var{version} (\#\var{build_number},
\var{build_date}, \var{build_time}) [\var{compiler}]'}. The first
three characters are used to identify the version in the installation
directories (where appropriate on each platform). An example:
\begin{verbatim}
>>> import sys
>>> sys.version
'1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]'
\end{verbatim}
\end{datadesc}
\begin{datadesc}{winver}
The version number used to form registry keys on Windows platforms.
This is stored as string resource 1000 in the Python DLL. The value
is normally the first three characters of \constant{version}. It is
provided in the \module{sys} module for informational purposes;
modifying this value has no effect on the registry keys used by
Python.
Availability: Windows.
\end{datadesc}

34
Doc/lib/libtelnetlib.tex
View file

@ -1,12 +1,9 @@
% LaTeX'ized from the comments in the module by Skip Montanaro
% <skip@mojam.com>.
\section{\module{telnetlib} ---
Telnet client}
\declaremodule{standard}{telnetlib}
\modulesynopsis{Telnet client class.}
\sectionauthor{Skip Montanaro}{skip@mojam.com}
The \module{telnetlib} module provides a \class{Telnet} class that
implements the Telnet protocol. See \rfc{854} for details about the
@ -149,3 +146,32 @@ If a regular expression ends with a greedy match (e.g. \regexp{.*})
or if more than one expression can match the same input, the
results are undeterministic, and may depend on the I/O timing.
\end{methoddesc}
\subsection{Telnet Example \label{telnet-example}}
\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
A simple example illustrating typical use:
\begin{verbatim}
import getpass
import sys
import telnetlib
HOST = "localhost"
user = raw_input("Enter your remote account: ")
password = getpass.getpass()
tn = telnetlib.Telnet(HOST)
tn.read_until("login: ")
tn.write(user + "\n")
if password:
tn.read_until("Password: ")
tn.write(password + "\n")
tn.write("ls\n")
tn.write("exit\n")
print tn.read_all()
\end{verbatim}

107
Doc/lib/libtime.tex
View file

@ -1,12 +1,13 @@
\section{\module{time} ---
Time access and conversions.}
\declaremodule{builtin}{time}
Time access and conversions}
\declaremodule{builtin}{time}
\modulesynopsis{Time access and conversions.}
This module provides various time-related functions.
It is always available.
It is always available, but not all functions are available
on all platforms.
An explanation of some terminology and conventions is in order.
@ -72,17 +73,29 @@ nonzero fraction (\UNIX{} \cfunction{select()} is used to implement
this, where available).
\item
The time tuple as returned by \function{gmtime()},
\function{localtime()}, and \function{strptime()}, and accepted by
\function{asctime()}, \function{mktime()} and \function{strftime()},
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 will be handled as descibed under
``Year 2000 (Y2K) issues'' above. 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.
is a tuple of 9 integers:
\begin{tableiii}{r|l|l}{textrm}{Index}{Field}{Values}
\lineiii{0}{year}{(e.g.\ 1993)}
\lineiii{1}{month}{range [1,12]}
\lineiii{2}{day}{range [1,31]}
\lineiii{3}{hour}{range [0,23]}
\lineiii{4}{minute}{range [0,59]}
\lineiii{5}{second}{range [0,61]; see \strong{(1)} in \function{strftime()} description}
\lineiii{6}{weekday}{range [0,6], monday is 0}
\lineiii{7}{Julian day}{range [1,366]}
\lineiii{8}{daylight savings flag}{0, 1 or -1; see below}
\end{tableiii}
Note that unlike the C structure, the month value is a
range of 1-12, not 0-11. A year value will be handled as described
under ``Year 2000 (Y2K) issues'' above. 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}
@ -168,34 +181,43 @@ They are shown without the optional field width and precision
specification, and are replaced by the indicated characters in the
\function{strftime()} result:
\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
\begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
\lineiii{\%a}{Locale's abbreviated weekday name.}{}
\lineiii{\%A}{Locale's full weekday name.}{}
\lineiii{\%b}{Locale's abbreviated month name.}{}
\lineiii{\%B}{Locale's full month name.}{}
\lineiii{\%c}{Locale's appropriate date and time representation.}{}
\lineiii{\%d}{Day of the month as a decimal number [01,31].}{}
\lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{}
\lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{}
\lineiii{\%j}{Day of the year as a decimal number [001,366].}{}
\lineiii{\%m}{Month as a decimal number [01,12].}{}
\lineiii{\%M}{Minute as a decimal number [00,59].}{}
\lineiii{\%p}{Locale's equivalent of either AM or PM.}{}
\lineiii{\%S}{Second as a decimal number [00,61].}{(1)}
\lineiii{\%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
preceding the first Sunday are considered to be in week 0.}{}
\lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{}
\lineiii{\%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}
preceding the first Sunday are considered to be in week 0.}{}
\lineiii{\%x}{Locale's appropriate date representation.}{}
\lineiii{\%X}{Locale's appropriate time representation.}{}
\lineiii{\%y}{Year without century as a decimal number [00,99].}{}
\lineiii{\%Y}{Year with century as a decimal number.}{}
\lineiii{\%Z}{Time zone name (or by no characters if no time zone exists).}{}
\lineiii{\%\%}{A literal \character{\%} character.}{}
\end{tableiii}
\noindent
Notes:
\begin{description}
\item[(1)]
The range really is \code{0} to \code{61}; this accounts for leap
seconds and the (very rare) double leap seconds.
\end{description}
Additional directives may be supported on certain platforms, but
only the ones listed here have a meaning standardized by ANSI C.
@ -215,8 +237,9 @@ directives as those used by \function{strftime()}; it defaults to
returned by \function{ctime()}. The same platform caveats apply; see
the local \UNIX{} documentation for restrictions or additional
supported directives. If \var{string} cannot be parsed according to
\var{format}, \exception{ValueError} is raised. This function may not
be defined on all platforms.
\var{format}, \exception{ValueError} is raised.
Availability: Most modern \UNIX{} systems.
\end{funcdesc}
\begin{funcdesc}{time}{}
@ -238,3 +261,9 @@ 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}
\begin{seealso}
\seemodule{locale}{Internationalization services. The locale
settings can affect the return values for some of
the functions in the \module{time} module.}
\end{seealso}

10
Doc/lib/libtypes.tex
View file

@ -1,11 +1,10 @@
\section{\module{types} ---
Names for all built-in types.}
Names for all built-in types}
\declaremodule{standard}{types}
\modulesynopsis{Names for all built-in 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 *} ---
@ -141,3 +140,8 @@ The type of traceback objects such as found in
The type of frame objects such as found in \code{tb.tb_frame} if
\code{tb} is a traceback object.
\end{datadesc}
\begin{datadesc}{BufferType}
The type of buffer objects created by the
\function{buffer()}\bifuncindex{buffer} function.
\end{datadesc}

33
Doc/lib/libundoc.tex
View file

@ -23,6 +23,9 @@ reference material.
\item[\module{Tkdnd}]
--- Drag-and-drop support for \module{Tkinter}.
\item[\module{turtle}]
--- Turtle graphics in a Tk window.
\item[\module{test}]
--- Regression testing framework. This is used for the Python
regression test, but is useful for other Python libraries as well.
@ -35,6 +38,11 @@ This is a package rather than a module.
Some of these are very old and/or not very robust; marked with ``hmm.''
\begin{description}
\item[\module{dircmp}]
--- Class to build directory diff tools on (may become a demo or tool).
\deprecated{1.6}{The \refmodule{filecmp} module will replace
\module{dircmp}.}
\item[\module{bdb}]
--- A generic Python debugger base class (used by pdb)
@ -72,7 +80,7 @@ document these.
--- Platform-independent API for playing audio data
\item[\module{sunaudio}]
--- interpret sun audio headers (may become obsolete or a tool/demo)
--- Interpret Sun audio headers (may become obsolete or a tool/demo)
\item[\module{toaiff}]
--- Convert "arbitrary" sound files to AIFF files; should probably
@ -80,14 +88,23 @@ become a tool or demo. Requires the external program \program{sox}.
\end{description}
\section{Obsolete}
\section{Obsolete \label{obsolete-modules}}
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/}. % $ <-- bow to font lock
To use any of these modules, add that directory to \code{sys.path},
possibly using \envvar{PYTHONPATH}.
These modules are not normally available for import; additional work
must be done to make them available.
Those which are written in Python will be installed into the directory
\file{lib-old/} installed as part of the standard library. To use
these, the directory must be added to \code{sys.path}, possibly using
\envvar{PYTHONPATH}.
Obsolete extension modules written in C are not built by default.
Under \UNIX, these must be enabled by uncommenting the appropriate
lines in \file{Modules/Setup} in the build tree and either rebuilding
Python if the modules are statically linked, or building and
installing the shared object if using dynamically-loaded extensions.
% XXX need Windows instructions!
\begin{description}
\item[\module{addpack}]

143
Doc/lib/liburllib.tex
View file

@ -1,8 +1,8 @@
\section{\module{urllib} ---
Open an arbitrary object given by URL.}
\declaremodule{standard}{urllib}
Open an arbitrary resource by URL}
\modulesynopsis{Open an arbitrary object given by URL (requires sockets).}
\declaremodule{standard}{urllib}
\modulesynopsis{Open an arbitrary network resource by URL (requires sockets).}
\index{WWW}
\index{World-Wide Web}
@ -62,6 +62,37 @@ If the \var{url} uses the \file{http:} scheme identifier, the optional
must in standard \file{application/x-www-form-urlencoded} format;
see the \function{urlencode()} function below.
The \function{urlopen()} function works transparently with proxies.
In a \UNIX{} or Windows environment, set the \envvar{http_proxy},
\envvar{ftp_proxy} or \envvar{gopher_proxy} environment variables to a
URL that identifies the proxy server before starting the Python
interpreter. For example (the \character{\%} is the command prompt):
\begin{verbatim}
% http_proxy="http://www.someproxy.com:3128"
% export http_proxy
% python
...
\end{verbatim}
In a Macintosh environment, \function{urlopen()} will retrieve proxy
information from Internet\index{Internet Config} Config.
The \function{urlopen()} function works transparently with proxies.
In a \UNIX{} or Windows environment, set the \envvar{http_proxy},
\envvar{ftp_proxy} or \envvar{gopher_proxy} environment variables to a
URL that identifies the proxy server before starting the Python
interpreter, e.g.:
\begin{verbatim}
% http_proxy="http://www.someproxy.com:3128"
% export http_proxy
% python
...
\end{verbatim}
In a Macintosh environment, \function{urlopen()} will retrieve proxy
information from Internet Config.
\end{funcdesc}
\begin{funcdesc}{urlretrieve}{url\optional{, filename\optional{, hook}}}
@ -127,6 +158,55 @@ characters, where both \var{key} and \var{value} are quoted using
\function{quote_plus()} above.
\end{funcdesc}
The public functions \function{urlopen()} and \function{urlretrieve()}
create an instance of the \class{FancyURLopener} class and use it to perform
their requested actions. To override this functionality, programmers can
create a subclass of \class{URLopener} or \class{FancyURLopener}, then
assign that class to the \var{urllib._urlopener} variable before calling the
desired function. For example, applications may want to specify a different
\code{user-agent} header than \class{URLopener} defines. This can be
accomplished with the following code:
\begin{verbatim}
class AppURLopener(urllib.FancyURLopener):
def __init__(self, *args):
apply(urllib.FancyURLopener.__init__, (self,) + args)
self.version = "App/1.7"
urllib._urlopener = AppURLopener
\end{verbatim}
\begin{classdesc}{URLopener}{\optional{proxies\optional{, **x509}}}
Base class for opening and reading URLs. Unless you need to support
opening objects using schemes other than \file{http:}, \file{ftp:},
\file{gopher:} or \file{file:}, you probably want to use
\class{FancyURLopener}.
By default, the \class{URLopener} class sends a
\code{user-agent} header of \samp{urllib/\var{VVV}}, where
\var{VVV} is the \module{urllib} version number. Applications can
define their own \code{user-agent} header by subclassing
\class{URLopener} or \class{FancyURLopener} and setting the instance
attribute \var{version} to an appropriate string value before the
\method{open()} method is called.
Additional keyword parameters, collected in \var{x509}, are used for
authentication with the \file{https:} scheme. The keywords
\var{key_file} and \var{cert_file} are supported; both are needed to
actually retrieve a resource at an \file{https:} URL.
\end{classdesc}
\begin{classdesc}{FancyURLopener}{...}
\class{FancyURLopener} subclasses \class{URLopener} providing default
handling for the following HTTP response codes: 301, 302 or 401. For
301 and 302 response codes, the \code{location} header is used to
fetch the actual URL. For 401 response codes (authentication
required), basic HTTP authentication is performed.
The parameters to the constructor are the same as those for
\class{URLopener}.
\end{classdesc}
Restrictions:
\begin{itemize}
@ -175,3 +255,60 @@ to parse and unparse URL strings, the recommended interface for URL
manipulation is in module \refmodule{urlparse}\refstmodindex{urlparse}.
\end{itemize}
\subsection{URLopener Objects \label{urlopener-objs}}
\sectionauthor{Skip Montanaro}{skip@mojam.com}
\class{URLopener} and \class{FancyURLopener} objects have the
following methodsL
\begin{methoddesc}{open}{fullurl\optional{, data}}
Open \var{fullurl} using the appropriate protocol. This method sets
up cache and proxy information, then calls the appropriate open method with
its input arguments. If the scheme is not recognized,
\method{open_unknown()} is called. The \var{data} argument
has the same meaning as the \var{data} argument of \function{urlopen()}.
\end{methoddesc}
\begin{methoddesc}{open_unknown}{fullurl\optional{, data}}
Overridable interface to open unknown URL types.
\end{methoddesc}
\begin{methoddesc}{retrieve}{url\optional{, filename\optional{, reporthook}}}
Retrieves the contents of \var{url} and places it in \var{filename}. The
return value is a tuple consisting of a local filename and either a
\class{mimetools.Message} object containing the response headers (for remote
URLs) or None (for local URLs). The caller must then open and read the
contents of \var{filename}. If \var{filename} is not given and the URL
refers to a local file, the input filename is returned. If the URL is
non-local and \var{filename} is not given, the filename is the output of
\function{tempfile.mktemp()} with a suffix that matches the suffix of the last
path component of the input URL. If \var{reporthook} is given, it must be
a function accepting three numeric parameters. It will be called after each
chunk of data is read from the network. \var{reporthook} is ignored for
local URLs.
\end{methoddesc}
\subsection{Examples}
\nodename{Urllib Examples}
Here is an example session that uses the \samp{GET} method to retrieve
a URL containing parameters:
\begin{verbatim}
>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
>>> print f.read()
\end{verbatim}
The following example uses the \samp{POST} method instead:
\begin{verbatim}
>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query", params)
>>> print f.read()
\end{verbatim}

34
Doc/lib/libwhrandom.tex
View file

@ -1,13 +1,27 @@
\section{\module{whrandom} ---
Floating point pseudo-random number generator.}
\declaremodule{standard}{whrandom}
Pseudo-random number generator}
\declaremodule{standard}{whrandom}
\modulesynopsis{Floating point pseudo-random number generator.}
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:
class that is also named \class{whrandom}. Instances of the
\class{whrandom} class conform to the Random Number Generator
interface described in section \ref{rng-objects}. They also offer the
following method, specific to the Wichmann-Hill algorithm:
\begin{methoddesc}[whrandom]{seed}{\optional{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.
If \var{x}, \var{y}, and \var{z} are either omitted or \code{0}, the
seed will be computed from the current system time. If one or two
of the parameters are \code{0}, but not all three, the zero values
are replaced by ones. This causes some apparently different seeds
to be equal, with the corresponding result on the pseudo-random
series produced by the generator.
\end{methoddesc}
\begin{funcdesc}{choice}{seq}
Chooses a random element from the non-empty sequence \var{seq} and returns it.
@ -31,17 +45,23 @@ number is initialized using values derived from the current time.
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
When imported, the \module{whrandom} module also creates an instance of
the \class{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}
Note that using separate instances of the generator leads to
independent sequences of pseudo-random numbers.
\begin{seealso}
\seemodule{random}{generators for various random distributions}
\seemodule{random}{Generators for various random distributions and
documentation for the Random Number Generator
interface.}
\seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
An efficient and portable pseudo-random number generator'',
\citetitle{Applied Statistics} 31 (1982) 188-190.}

15
Doc/lib/libxmllib.tex
View file

@ -98,11 +98,12 @@ passed to \method{handle_xml()} default to \code{None} and the string
\code{'no'} respectively.
\end{methoddesc}
\begin{methoddesc}{handle_doctype}{tag, data}
\begin{methoddesc}{handle_doctype}{tag, pubid, syslit, 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.
The arguments are the name of the root element, the Formal Public
Identifier (or \code{None} if not specified), the system identifier,
and the uninterpreted contents of the internal DTD subset as a string
(or \code{None} if not present).
\end{methoddesc}
\begin{methoddesc}{handle_starttag}{tag, method, attributes}
@ -226,6 +227,12 @@ implementation calls \method{syntax_error()} to signal an error.
\begin{seealso}
\seetext{The XML specification, published by the World Wide Web
Consortium (W3C), is available online at
\url{http://www.w3.org/TR/REC-xml}. References to
additional material on XML are available at
\url{http://www.w3.org/XML/}.}
\seetext{The Python XML Topic Guide provides a great deal of information
on using XML from Python and links to other sources of information
on XML. It's located on the Web at

43
Doc/lib/libzlib.tex
View file

@ -1,6 +1,3 @@
% XXX The module has been extended (by Jeremy and Andrew) but this
% documentation is incorrect in some cases.
\section{\module{zlib} ---
Compression compatible with \program{gzip}}
@ -17,10 +14,6 @@ most recent version as of April 1999; use a later version if one
is available. There are known incompatibilities between the Python
module and earlier versions of the zlib library.
The documentation for this module is woefully out of date. In some
cases, the doc strings have been updated more recently. In other
cases, they are both stale.
The available exception and functions in this module are:
\begin{excdesc}{error}
@ -68,12 +61,29 @@ The available exception and functions in this module are:
should not be used for authentication or digital signatures.
\end{funcdesc}
\begin{funcdesc}{decompress}{string\optional{, wbits\optional{, buffsize}}}
\begin{funcdesc}{decompress}{string\optional{, wbits\optional{, bufsize}}}
Decompresses the data in \var{string}, returning a string containing
the uncompressed data. The \var{wbits} parameter controls the size of
the window buffer. If \var{buffsize} is given, it is used as the
the window buffer. If \var{bufsize} is given, it is used as the
initial size of the output buffer. Raises the \exception{error}
exception if any error occurs.
The absolute value of \var{wbits} is the base two logarithm of the
size of the history buffer (the ``window size'') used when compressing
data. Its absolute value should be between 8 and 15 for the most
recent versions of the zlib library, larger values resulting in better
compression at the expense of greater memory usage. The default value
is 15. When \var{wbits} is negative, the standard
\program{gzip} header is suppressed; this is an undocumented feature
of the zlib library, used for compatibility with \program{unzip}'s
compression file format.
\var{bufsize} is the initial size of the buffer used to hold
decompressed data. If more space is required, the buffer size will be
increased as needed, so you don't have to get this value exactly
right; tuning it will only save a few calls to \cfunction{malloc()}. The
default size is 16384.
\end{funcdesc}
\begin{funcdesc}{decompressobj}{\optional{wbits}}
@ -106,7 +116,20 @@ prevents compressing any more data. After calling
action is to delete the object.
\end{methoddesc}
Decompression objects support the following methods:
Decompression objects support the following methods, and a single attribute:
\begin{memberdesc}{unused_data}
A string which contains any unused data from the last string fed to
this decompression object. If the whole string turned out to contain
compressed data, this is \code{""}, the empty string.
The only way to determine where a string of compressed data ends is by
actually decompressing it. This means that when compressed data is
contained part of a larger file, you can only find the end of it by
reading data and feeding it into a decompression object's
\method{decompress} method until the \member{unused_data} attribute is
no longer the empty string.
\end{memberdesc}
\begin{methoddesc}[Decompress]{decompress}{string}
Decompress \var{string}, returning a string containing the