Merged changes from the 1.5.2p2 release.
(Very rough.)
diff --git a/Doc/lib/internet.tex b/Doc/lib/internet.tex
index 52985dc..b426132 100644
--- a/Doc/lib/internet.tex
+++ b/Doc/lib/internet.tex
@@ -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
diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex
index 84b2812..0e1a411 100644
--- a/Doc/lib/libarray.tex
+++ b/Doc/lib/libarray.tex
@@ -76,11 +76,11 @@
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 @@
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 @@
\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}
diff --git a/Doc/lib/libasyncore.tex b/Doc/lib/libasyncore.tex
index 5a57146..4bcd496 100644
--- a/Doc/lib/libasyncore.tex
+++ b/Doc/lib/libasyncore.tex
@@ -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
diff --git a/Doc/lib/libbase64.tex b/Doc/lib/libbase64.tex
index a59332b..bede708 100644
--- a/Doc/lib/libbase64.tex
+++ b/Doc/lib/libbase64.tex
@@ -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 @@
\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}
diff --git a/Doc/lib/libbisect.tex b/Doc/lib/libbisect.tex
index 2b3f117..555e3a7 100644
--- a/Doc/lib/libbisect.tex
+++ b/Doc/lib/libbisect.tex
@@ -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
diff --git a/Doc/lib/libbsddb.tex b/Doc/lib/libbsddb.tex
index cd0dc07..6a27a3b 100644
--- a/Doc/lib/libbsddb.tex
+++ b/Doc/lib/libbsddb.tex
@@ -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 @@
\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}
diff --git a/Doc/lib/libcalendar.tex b/Doc/lib/libcalendar.tex
index 59e3443..ef715f5 100644
--- a/Doc/lib/libcalendar.tex
+++ b/Doc/lib/libcalendar.tex
@@ -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}
-program.}
-
+\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 @@
\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}
diff --git a/Doc/lib/libcfgparser.tex b/Doc/lib/libcfgparser.tex
index fa76b22..50af056 100644
--- a/Doc/lib/libcfgparser.tex
+++ b/Doc/lib/libcfgparser.tex
@@ -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 @@
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
-\class{ConfigParser} constructor as a dictionary. Additional defaults
-may be passed into the \method{get} method which will override all
+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
others.
\begin{classdesc}{ConfigParser}{\optional{defaults}}
@@ -50,7 +55,9 @@
\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 @@
\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 @@
\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}
diff --git a/Doc/lib/libcgi.tex b/Doc/lib/libcgi.tex
index 1c565fd..3b755a0 100644
--- a/Doc/lib/libcgi.tex
+++ b/Doc/lib/libcgi.tex
@@ -195,7 +195,7 @@
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
diff --git a/Doc/lib/libcgihttp.tex b/Doc/lib/libcgihttp.tex
index fd8e09b..a2f453a 100644
--- a/Doc/lib/libcgihttp.tex
+++ b/Doc/lib/libcgihttp.tex
@@ -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 @@
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}
diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex
index 877b7a4..4b66394 100644
--- a/Doc/lib/libcode.tex
+++ b/Doc/lib/libcode.tex
@@ -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}
diff --git a/Doc/lib/libcodeop.tex b/Doc/lib/libcodeop.tex
index a0b58a5..cd9cb63 100644
--- a/Doc/lib/libcodeop.tex
+++ b/Doc/lib/libcodeop.tex
@@ -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 @@
\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
diff --git a/Doc/lib/libcompileall.tex b/Doc/lib/libcompileall.tex
index 64e8a9e..a731245 100644
--- a/Doc/lib/libcompileall.tex
+++ b/Doc/lib/libcompileall.tex
@@ -1,13 +1,9 @@
-% 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.}
+ directory tree.}
This module provides some utility functions to support installing
@@ -20,19 +16,24 @@
\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.
+ If \var{skip_curdir} is true (the default), the current directory is
+ 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}
diff --git a/Doc/lib/libcrypt.tex b/Doc/lib/libcrypt.tex
index f9d1615..e3936b7 100644
--- a/Doc/lib/libcrypt.tex
+++ b/Doc/lib/libcrypt.tex
@@ -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}
diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex
index 1c57ee8..81532ce 100644
--- a/Doc/lib/libexcs.tex
+++ b/Doc/lib/libexcs.tex
@@ -11,18 +11,6 @@
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 @@
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 @@
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 @@
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}
diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
index 6312222..ea17665 100644
--- a/Doc/lib/libfcntl.tex
+++ b/Doc/lib/libfcntl.tex
@@ -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}
diff --git a/Doc/lib/libfileinput.tex b/Doc/lib/libfileinput.tex
index 8bc93af..97caaf9 100644
--- a/Doc/lib/libfileinput.tex
+++ b/Doc/lib/libfileinput.tex
@@ -75,11 +75,13 @@
\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}{}
diff --git a/Doc/lib/libfnmatch.tex b/Doc/lib/libfnmatch.tex
index 7d97461..527358b 100644
--- a/Doc/lib/libfnmatch.tex
+++ b/Doc/lib/libfnmatch.tex
@@ -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}
diff --git a/Doc/lib/libgetopt.tex b/Doc/lib/libgetopt.tex
index 1c17ab5..56a8b3c 100644
--- a/Doc/lib/libgetopt.tex
+++ b/Doc/lib/libgetopt.tex
@@ -33,9 +33,10 @@
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.
diff --git a/Doc/lib/libgrp.tex b/Doc/lib/libgrp.tex
index 10f12e8..2925297 100644
--- a/Doc/lib/libgrp.tex
+++ b/Doc/lib/libgrp.tex
@@ -11,10 +11,14 @@
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 @@
\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}
diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex
index 80bd01e..5725fd3 100644
--- a/Doc/lib/libimaplib.tex
+++ b/Doc/lib/libimaplib.tex
@@ -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
diff --git a/Doc/lib/libintro.tex b/Doc/lib/libintro.tex
index a4bc67e..70c7c70 100644
--- a/Doc/lib/libintro.tex
+++ b/Doc/lib/libintro.tex
@@ -22,14 +22,15 @@
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
diff --git a/Doc/lib/liblinecache.tex b/Doc/lib/liblinecache.tex
index fb71d7a..1273521 100644
--- a/Doc/lib/liblinecache.tex
+++ b/Doc/lib/liblinecache.tex
@@ -17,7 +17,9 @@
\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 @@
\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}{}
diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex
index be2a717..f24399e 100644
--- a/Doc/lib/libmarshal.tex
+++ b/Doc/lib/libmarshal.tex
@@ -62,7 +62,8 @@
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 @@
\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
diff --git a/Doc/lib/libmath.tex b/Doc/lib/libmath.tex
index 0a45fb3..af1ac10 100644
--- a/Doc/lib/libmath.tex
+++ b/Doc/lib/libmath.tex
@@ -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}.
diff --git a/Doc/lib/libmhlib.tex b/Doc/lib/libmhlib.tex
index 27b71b0..3e70663 100644
--- a/Doc/lib/libmhlib.tex
+++ b/Doc/lib/libmhlib.tex
@@ -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.}
diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex
index 82b42ac..eb469b1 100644
--- a/Doc/lib/libmimetools.tex
+++ b/Doc/lib/libmimetools.tex
@@ -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 @@
\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 @@
\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}
diff --git a/Doc/lib/libmimetypes.tex b/Doc/lib/libmimetypes.tex
index c85eb6f..b0c0bb8 100644
--- a/Doc/lib/libmimetypes.tex
+++ b/Doc/lib/libmimetypes.tex
@@ -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}
diff --git a/Doc/lib/libmimewriter.tex b/Doc/lib/libmimewriter.tex
index ec57584..fbf2490 100644
--- a/Doc/lib/libmimewriter.tex
+++ b/Doc/lib/libmimewriter.tex
@@ -54,7 +54,7 @@
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
diff --git a/Doc/lib/libnetrc.tex b/Doc/lib/libnetrc.tex
index 47b704b..9ad8d70 100644
--- a/Doc/lib/libnetrc.tex
+++ b/Doc/lib/libnetrc.tex
@@ -1,5 +1,3 @@
-% Module and documentation by Eric S. Raymond, 21 Dec 1998
-
\section{\module{netrc} ---
netrc file processing}
@@ -45,7 +43,7 @@
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}
diff --git a/Doc/lib/libnis.tex b/Doc/lib/libnis.tex
index 0181b06..d7060fa 100644
--- a/Doc/lib/libnis.tex
+++ b/Doc/lib/libnis.tex
@@ -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 @@
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}
diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index 5239fcb..4001447 100644
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -262,7 +262,9 @@
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 @@
\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 @@
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.
diff --git a/Doc/lib/libparser.tex b/Doc/lib/libparser.tex
index db49d89..ce84513 100644
--- a/Doc/lib/libparser.tex
+++ b/Doc/lib/libparser.tex
@@ -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 @@
\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 @@
\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 @@
\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 @@
\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 @@
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 @@
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 @@
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
diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex
index f6374d8..dca7820 100644
--- a/Doc/lib/libpickle.tex
+++ b/Doc/lib/libpickle.tex
@@ -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 @@
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 @@
\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 @@
\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 @@
\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}
diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex
index fc73a31..4408ef3 100644
--- a/Doc/lib/libpoplib.tex
+++ b/Doc/lib/libpoplib.tex
@@ -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
diff --git a/Doc/lib/libposixpath.tex b/Doc/lib/libposixpath.tex
index 7ab3713..4981ac0 100644
--- a/Doc/lib/libposixpath.tex
+++ b/Doc/lib/libposixpath.tex
@@ -127,8 +127,8 @@
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}
diff --git a/Doc/lib/libpty.tex b/Doc/lib/libpty.tex
index 85dd526..5ef3d0f 100644
--- a/Doc/lib/libpty.tex
+++ b/Doc/lib/libpty.tex
@@ -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}
diff --git a/Doc/lib/libpwd.tex b/Doc/lib/libpwd.tex
index fb8d693..784f478 100644
--- a/Doc/lib/libpwd.tex
+++ b/Doc/lib/libpwd.tex
@@ -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 @@
\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}
diff --git a/Doc/lib/libpycompile.tex b/Doc/lib/libpycompile.tex
index fad749b..ebbc9b9 100644
--- a/Doc/lib/libpycompile.tex
+++ b/Doc/lib/libpycompile.tex
@@ -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.}
diff --git a/Doc/lib/libqueue.tex b/Doc/lib/libqueue.tex
index a846036..2bb6a2f 100644
--- a/Doc/lib/libqueue.tex
+++ b/Doc/lib/libqueue.tex
@@ -32,7 +32,7 @@
\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}
diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex
index 1c39c15..e7f0d58 100644
--- a/Doc/lib/librandom.tex
+++ b/Doc/lib/librandom.tex
@@ -12,22 +12,25 @@
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.
+\code{\var{alpha} > -1} and \code{\var{beta} > -1}.
+Returned values range between 0 and 1.
\end{funcdesc}
\begin{funcdesc}{cunifvariate}{mean, arc}
@@ -59,8 +62,8 @@
\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 @@
\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}
diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex
index 6fecced..547923d 100644
--- a/Doc/lib/librfc822.tex
+++ b/Doc/lib/librfc822.tex
@@ -8,10 +8,11 @@
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 @@
\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 @@
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 @@
\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 @@
\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 @@
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}
diff --git a/Doc/lib/libsched.tex b/Doc/lib/libsched.tex
index baa2ffe..21366f5 100644
--- a/Doc/lib/libsched.tex
+++ b/Doc/lib/libsched.tex
@@ -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 @@
\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}.
diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex
index 23b8b8d..f33dc44 100644
--- a/Doc/lib/libselect.tex
+++ b/Doc/lib/libselect.tex
@@ -9,7 +9,7 @@
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:
diff --git a/Doc/lib/libshlex.tex b/Doc/lib/libshlex.tex
index f33fa2a..174a39f 100644
--- a/Doc/lib/libshlex.tex
+++ b/Doc/lib/libshlex.tex
@@ -1,5 +1,3 @@
-% Module and documentation by Eric S. Raymond, 21 Dec 1998
-
\section{\module{shlex} ---
Simple lexical analysis}
diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex
index d366cca..445a417 100644
--- a/Doc/lib/libsmtplib.tex
+++ b/Doc/lib/libsmtplib.tex
@@ -74,6 +74,17 @@
\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 @@
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 @@
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 @@
\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}
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
index 4abe805..bcbb76f 100644
--- a/Doc/lib/libsocket.tex
+++ b/Doc/lib/libsocket.tex
@@ -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
diff --git a/Doc/lib/libstatvfs.tex b/Doc/lib/libstatvfs.tex
index e71ad72..ca96212 100644
--- a/Doc/lib/libstatvfs.tex
+++ b/Doc/lib/libstatvfs.tex
@@ -22,6 +22,10 @@
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}
@@ -39,7 +43,7 @@
\end{datadesc}
\begin{datadesc}{F_FAVAIL}
-Free nodes available to non-superuser.
+Free nodes available to non-super user.
\end{datadesc}
\begin{datadesc}{F_FLAG}
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index 6ae216b..f4c0c8a 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -30,15 +30,17 @@
\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 @@
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 @@
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 @@
\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 @@
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 @@
\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 @@
\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 @@
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 @@
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 @@
Notes:
\begin{description}
-
-\item[(1)] If \var{i} or \var{j} is negative, the index is relative to
+\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[(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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
\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 @@
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 @@
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 @@
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}
diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
index eef84a4..434b433 100644
--- a/Doc/lib/libstruct.tex
+++ b/Doc/lib/libstruct.tex
@@ -45,23 +45,35 @@
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
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
index 08f49c7..af2d21f 100644
--- a/Doc/lib/libsys.tex
+++ b/Doc/lib/libsys.tex
@@ -31,6 +31,11 @@
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 @@
\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}
diff --git a/Doc/lib/libtelnetlib.tex b/Doc/lib/libtelnetlib.tex
index f28833e..de88953 100644
--- a/Doc/lib/libtelnetlib.tex
+++ b/Doc/lib/libtelnetlib.tex
@@ -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 @@
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}
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
index 0c28bf2..bca946d 100644
--- a/Doc/lib/libtime.tex
+++ b/Doc/lib/libtime.tex
@@ -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 @@
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 @@
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
- week) as a decimal number [00,53]. All days in a new year
- preceding the first Sunday are considered to be in week 0.}
- \lineii{\%w}{Weekday as a decimal number [0(Sunday),6].}
- \lineii{\%W}{Week number of the year (Monday as the first day of the
- week) as a decimal number [00,53]. All days in a new year
- preceding the first Sunday are considered to be in week 0.}
- \lineii{\%x}{Locale's appropriate date representation.}
- \lineii{\%X}{Locale's appropriate time representation.}
- \lineii{\%y}{Year without century as a decimal number [00,99].}
- \lineii{\%Y}{Year with century as a decimal number.}
- \lineii{\%Z}{Time zone name (or by no characters if no time zone exists).}
- \lineii{\%\%}{\%}
-\end{tableii}
+\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.}{}
+ \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.}{}
+ \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 @@
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 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}
diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex
index 5f9034c..e48fcaf 100644
--- a/Doc/lib/libtypes.tex
+++ b/Doc/lib/libtypes.tex
@@ -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 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}
diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex
index 5be93dd..fac635a 100644
--- a/Doc/lib/libundoc.tex
+++ b/Doc/lib/libundoc.tex
@@ -23,6 +23,9 @@
\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 @@
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 @@
--- 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 @@
\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}]
diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex
index 73898f5..38ee09e 100644
--- a/Doc/lib/liburllib.tex
+++ b/Doc/lib/liburllib.tex
@@ -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 @@
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 @@
\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 @@
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}
diff --git a/Doc/lib/libwhrandom.tex b/Doc/lib/libwhrandom.tex
index b79377d..b745f5b 100644
--- a/Doc/lib/libwhrandom.tex
+++ b/Doc/lib/libwhrandom.tex
@@ -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 @@
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.}
diff --git a/Doc/lib/libxmllib.tex b/Doc/lib/libxmllib.tex
index c407629..afda815 100644
--- a/Doc/lib/libxmllib.tex
+++ b/Doc/lib/libxmllib.tex
@@ -98,11 +98,12 @@
\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 @@
\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
diff --git a/Doc/lib/libzlib.tex b/Doc/lib/libzlib.tex
index d31af04..66fac4e 100644
--- a/Doc/lib/libzlib.tex
+++ b/Doc/lib/libzlib.tex
@@ -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 @@
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 @@
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 @@
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