mass changes; fix titles; add examples; correct typos; clarifications;
unified style; etc.
diff --git a/Doc/lib/libaifc.tex b/Doc/lib/libaifc.tex
index 7b4e4c8..7e595ef 100644
--- a/Doc/lib/libaifc.tex
+++ b/Doc/lib/libaifc.tex
@@ -21,8 +21,11 @@
Open an AIFF or AIFF-C file and return an object instance with
methods that are described below. The argument file is either a
string naming a file or a file object. The mode is either the string
-'r' when the file must be opened for reading, or 'w' when the file
-must be opened for writing.
+\code{'r'} when the file must be opened for reading, or \code{'w'}
+when the file must be opened for writing. When used for writing, the
+file object should be seekable, unless you know ahead of time how many
+samples you are going to write in total and use
+\code{writeframesraw()} and \code{setnframes()}.
\end{funcdesc}
Objects returned by \code{aifc.open()} when a file is opened for
diff --git a/Doc/lib/libal.tex b/Doc/lib/libal.tex
index 51a0312..6a812dd 100644
--- a/Doc/lib/libal.tex
+++ b/Doc/lib/libal.tex
@@ -1,13 +1,15 @@
\section{Built-in Module \sectcode{al}}
\bimodindex{al}
-This module provides access to the audio facilities of the Indigo and
-4D/35 workstations, described in section 3A of the IRIX 4.0 man pages
-(and also available as an option in IRIX 3.3). You'll need to read
-those man pages to understand what these functions do!
-Some of the functions are not available in releases below 4.0.5.
-Again, see the manual to check whether a specific function is
-available on your platform.
+This module provides access to the audio facilities of the SGI Indy
+and Indigo workstations. See section 3A of the IRIX man pages for
+details. You'll need to read those man pages to understand what these
+functions do! Some of the functions are not available in IRIX
+releases before 4.0.5. Again, see the manual to check whether a
+specific function is available on your platform.
+
+All functions and methods defined in this module are equivalent to
+the C functions with \samp{AL} prefixed to their name.
Symbolic constants from the C header file \file{<audio.h>} are defined
in the standard module \code{AL}, see below.
@@ -20,145 +22,138 @@
(One example is specifying an excessive queue size --- there is no
documented upper limit.)
-Module \code{al} defines the following functions:
+The module defines the following functions:
\renewcommand{\indexsubitem}{(in module al)}
+
\begin{funcdesc}{openport}{name\, direction\optional{\, config}}
-Equivalent to the C function ALopenport(). The name and direction
-arguments are strings. The optional config argument is an opaque
-configuration object as returned by \code{al.newconfig()}. The return
-value is an opaque port object; methods of port objects are described
-below.
+The name and direction arguments are strings. The optional config
+argument is a configuration object as returned by
+\code{al.newconfig()}. The return value is an \dfn{port object};
+methods of port objects are described below.
\end{funcdesc}
\begin{funcdesc}{newconfig}{}
-Equivalent to the C function ALnewconfig(). The return value is a new
-opaque configuration object; methods of configuration objects are
-described below.
+The return value is a new \dfn{configuration object}; methods of
+configuration objects are described below.
\end{funcdesc}
\begin{funcdesc}{queryparams}{device}
-Equivalent to the C function ALqueryparams(). The device argument is
-an integer. The return value is a list of integers containing the
-data returned by ALqueryparams().
+The device argument is an integer. The return value is a list of
+integers containing the data returned by ALqueryparams().
\end{funcdesc}
\begin{funcdesc}{getparams}{device\, list}
-Equivalent to the C function ALgetparams(). The device argument is an
-integer. The list argument is a list such as returned by
-\code{queryparams}; it is modified in place (!).
+The device argument is an integer. The list argument is a list such
+as returned by \code{queryparams}; it is modified in place (!).
\end{funcdesc}
\begin{funcdesc}{setparams}{device\, list}
-Equivalent to the C function ALsetparams(). The device argument is an
-integer.The list argument is a list such as returned by
-\code{al.queryparams}.
+The device argument is an integer. The list argument is a list such
+as returned by \code{al.queryparams}.
\end{funcdesc}
+\subsection{Configuration Objects}
+
Configuration objects (returned by \code{al.newconfig()} have the
following methods:
\renewcommand{\indexsubitem}{(audio configuration object method)}
+
\begin{funcdesc}{getqueuesize}{}
-Return the queue size; equivalent to the C function ALgetqueuesize().
+Return the queue size.
\end{funcdesc}
\begin{funcdesc}{setqueuesize}{size}
-Set the queue size; equivalent to the C function ALsetqueuesize().
+Set the queue size.
\end{funcdesc}
\begin{funcdesc}{getwidth}{}
-Get the sample width; equivalent to the C function ALgetwidth().
+Get the sample width.
\end{funcdesc}
-\begin{funcdesc}{getwidth}{width}
-Set the sample width; equivalent to the C function ALsetwidth().
+\begin{funcdesc}{setwidth}{width}
+Set the sample width.
\end{funcdesc}
\begin{funcdesc}{getchannels}{}
-Get the channel count; equivalent to the C function ALgetchannels().
+Get the channel count.
\end{funcdesc}
\begin{funcdesc}{setchannels}{nchannels}
-Set the channel count; equivalent to the C function ALsetchannels().
+Set the channel count.
\end{funcdesc}
\begin{funcdesc}{getsampfmt}{}
-Get the sample format; equivalent to the C function ALgetsampfmt().
+Get the sample format.
\end{funcdesc}
\begin{funcdesc}{setsampfmt}{sampfmt}
-Set the sample format; equivalent to the C function ALsetsampfmt().
+Set the sample format.
\end{funcdesc}
\begin{funcdesc}{getfloatmax}{}
-Get the maximum value for floating sample formats;
-equivalent to the C function ALgetfloatmax().
+Get the maximum value for floating sample formats.
\end{funcdesc}
\begin{funcdesc}{setfloatmax}{floatmax}
-Set the maximum value for floating sample formats;
-equivalent to the C function ALsetfloatmax().
+Set the maximum value for floating sample formats.
\end{funcdesc}
+\subsection{Port Objects}
+
Port objects (returned by \code{al.openport()} have the following
methods:
\renewcommand{\indexsubitem}{(audio port object method)}
+
\begin{funcdesc}{closeport}{}
-Close the port; equivalent to the C function ALcloseport().
+Close the port.
\end{funcdesc}
\begin{funcdesc}{getfd}{}
-Return the file descriptor as an int; equivalent to the C function
-ALgetfd().
+Return the file descriptor as an int.
\end{funcdesc}
\begin{funcdesc}{getfilled}{}
-Return the number of filled samples; equivalent to the C function
-ALgetfilled().
+Return the number of filled samples.
\end{funcdesc}
\begin{funcdesc}{getfillable}{}
-Return the number of fillable samples; equivalent to the C function
-ALgetfillable().
+Return the number of fillable samples.
\end{funcdesc}
\begin{funcdesc}{readsamps}{nsamples}
-Read a number of samples from the queue, blocking if necessary;
-equivalent to the C function ALreadsamples. The data is returned as a
-string containing the raw data (e.g. 2 bytes per sample in big-endian
-byte order (high byte, low byte) if you have set the sample width to 2
-bytes.
+Read a number of samples from the queue, blocking if necessary.
+Return the data as a string containing the raw data, (e.g., 2 bytes per
+sample in big-endian byte order (high byte, low byte) if you have set
+the sample width to 2 bytes).
\end{funcdesc}
\begin{funcdesc}{writesamps}{samples}
-Write samples into the queue, blocking if necessary; equivalent to the
-C function ALwritesamples. The samples are encoded as described for
-the \code{readsamps} return value.
+Write samples into the queue, blocking if necessary. The samples are
+encoded as described for the \code{readsamps} return value.
\end{funcdesc}
\begin{funcdesc}{getfillpoint}{}
-Return the `fill point'; equivalent to the C function ALgetfillpoint().
+Return the `fill point'.
\end{funcdesc}
\begin{funcdesc}{setfillpoint}{fillpoint}
-Set the `fill point'; equivalent to the C function ALsetfillpoint().
+Set the `fill point'.
\end{funcdesc}
\begin{funcdesc}{getconfig}{}
Return a configuration object containing the current configuration of
-the port; equivalent to the C function ALgetconfig().
+the port.
\end{funcdesc}
\begin{funcdesc}{setconfig}{config}
-Set the configuration from the argument, a configuration object;
-equivalent to the C function ALsetconfig().
+Set the configuration from the argument, a configuration object.
\end{funcdesc}
\begin{funcdesc}{getstatus}{list}
-Get status information on last error
-equivalent to C function ALgetstatus().
+Get status information on last error.
\end{funcdesc}
\section{Standard Module \sectcode{AL}}
diff --git a/Doc/lib/libamoeba.tex b/Doc/lib/libamoeba.tex
index db4fefd..1e31bc6 100644
--- a/Doc/lib/libamoeba.tex
+++ b/Doc/lib/libamoeba.tex
@@ -70,7 +70,7 @@
\subsection{Capability Operations}
-Capabilities are written in a convenient ASCII format, also used by the
+Capabilities are written in a convenient \ASCII{} format, also used by the
Amoeba utilities
{\it c2a}(U)
and
diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex
index ea68fb1..9e37d55 100644
--- a/Doc/lib/libarray.tex
+++ b/Doc/lib/libarray.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{array}}
+\section{Built-in Module \sectcode{array}}
\bimodindex{array}
\index{arrays}
@@ -21,7 +21,7 @@
The actual representation of values is determined by the machine
architecture (strictly speaking, by the C implementation). The actual
-size can be accessed through the \var{typecode} attribute.
+size can be accessed through the \var{itemsize} attribute.
The module defines the following function:
@@ -59,7 +59,9 @@
Read \var{n} items (as machine values) from the file object \var{f}
and append them to the end of the array. If less than \var{n} items
are available, \code{EOFError} is raised, but the items that were
-available are still inserted into the array.
+available are still inserted into the array. \var{f} must be a real
+built-in file object; something else with a \code{read()} method won't
+do.
\end{funcdesc}
\begin{funcdesc}{fromlist}{list}
diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex
index 03e074d..6a74a0b 100644
--- a/Doc/lib/libaudioop.tex
+++ b/Doc/lib/libaudioop.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{audioop}}
+\section{Built-in Module \sectcode{audioop}}
\bimodindex{audioop}
The \code{audioop} module contains some useful operations on sound fragments.
@@ -19,139 +19,139 @@
\end{excdesc}
\begin{funcdesc}{add}{fragment1\, fragment2\, width}
-This function returns a fragment which is the addition of the two samples
-passed as parameters. \var{width} is the sample width in bytes, either
-\code{1}, \code{2} or \code{4}. Both fragments should have the same length.
+Return a fragment which is the addition of the two samples passed as
+parameters. \var{width} is the sample width in bytes, either
+\code{1}, \code{2} or \code{4}. Both fragments should have the same
+length.
\end{funcdesc}
\begin{funcdesc}{adpcm2lin}{adpcmfragment\, width\, state}
-This routine decodes an Intel/DVI ADPCM coded fragment to a linear
-fragment. See the description of \code{lin2adpcm} for details on ADPCM
-coding. The routine returns a tuple
-\code{(\var{sample}, \var{newstate})}
-where the sample has the width specified in \var{width}.
+Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
+the description of \code{lin2adpcm} for details on ADPCM coding.
+Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
+has the width specified in \var{width}.
\end{funcdesc}
\begin{funcdesc}{adpcm32lin}{adpcmfragment\, width\, state}
-This routine decodes an alternative 3-bit ADPCM code. See
-\code{lin2adpcm3} for details.
+Decode an alternative 3-bit ADPCM code. See \code{lin2adpcm3} for
+details.
\end{funcdesc}
\begin{funcdesc}{avg}{fragment\, width}
-This function returns the average over all samples in the fragment.
+Return the average over all samples in the fragment.
\end{funcdesc}
\begin{funcdesc}{avgpp}{fragment\, width}
-This function returns the average peak-peak value over all samples in
-the fragment. No filtering is done, so the usefulness of this routine
-is questionable.
+Return the average peak-peak value over all samples in the fragment.
+No filtering is done, so the usefulness of this routine is
+questionable.
\end{funcdesc}
\begin{funcdesc}{bias}{fragment\, width\, bias}
-This function returns a fragment that is the original fragment with a
-bias added to each sample.
+Return a fragment that is the original fragment with a bias added to
+each sample.
\end{funcdesc}
\begin{funcdesc}{cross}{fragment\, width}
-This function returns the number of zero crossings in the fragment
-passed as an argument.
+Return the number of zero crossings in the fragment passed as an
+argument.
\end{funcdesc}
\begin{funcdesc}{findfactor}{fragment\, reference}
-This routine (which only accepts 2-byte sample fragments) calculates a
-factor \var{F} such that \code{rms(add(fragment, mul(reference, -F)))}
-is minimal, i.e.\ it calculates the factor with which you should
-multiply \var{reference} to make it match as well as possible to
-\var{fragment}. The fragments should be the same size.
+Return a factor \var{F} such that
+\code{rms(add(fragment, mul(reference, -F)))} is minimal, i.e.,
+return the factor with which you should multiply \var{reference} to
+make it match as well as possible to \var{fragment}. The fragments
+should both contain 2-byte samples.
The time taken by this routine is proportional to \code{len(fragment)}.
\end{funcdesc}
\begin{funcdesc}{findfit}{fragment\, reference}
-This routine (which only accepts 2-byte sample fragments) tries to
-match \var{reference} as well as possible to a portion of
-\var{fragment} (which should be the longer fragment). It
-(conceptually) does this by taking slices out of \var{fragment}, using
+This routine (which only accepts 2-byte sample fragments)
+
+Try to match \var{reference} as well as possible to a portion of
+\var{fragment} (which should be the longer fragment). This is
+(conceptually) done by taking slices out of \var{fragment}, using
\code{findfactor} to compute the best match, and minimizing the
-result.
-It returns a tuple \code{(\var{offset}, \var{factor})} with \var{offset} the
+result. The fragments should both contain 2-byte samples. Return a
+tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
(integer) offset into \var{fragment} where the optimal match started
-and \var{factor} the floating-point factor as per \code{findfactor}.
+and \var{factor} is the (floating-point) factor as per
+\code{findfactor}.
\end{funcdesc}
\begin{funcdesc}{findmax}{fragment\, length}
-This routine (which only accepts 2-byte sample fragments) searches
-\var{fragment} for a slice of length \var{length} samples (not bytes!)\
-with maximum energy, i.e.\ it returns \var{i} for which
-\code{rms(fragment[i*2:(i+length)*2])} is maximal.
+Search \var{fragment} for a slice of length \var{length} samples (not
+bytes!)\ with maximum energy, i.e., return \var{i} for which
+\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
+should both contain 2-byte samples.
The routine takes time proportional to \code{len(fragment)}.
\end{funcdesc}
\begin{funcdesc}{getsample}{fragment\, width\, index}
-This function returns the value of sample \var{index} from the
-fragment.
+Return the value of sample \var{index} from the fragment.
\end{funcdesc}
\begin{funcdesc}{lin2lin}{fragment\, width\, newwidth}
-This function converts samples between 1-, 2- and 4-byte formats.
+Convert samples between 1-, 2- and 4-byte formats.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm}{fragment\, width\, state}
-This function converts samples to 4 bit Intel/DVI ADPCM encoding.
-ADPCM coding is an adaptive coding scheme, whereby each 4 bit number
-is the difference between one sample and the next, divided by a
-(varying) step. The Intel/DVI ADPCM algorithm has been selected for
-use by the IMA, so it may well become a standard.
+Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an
+adaptive coding scheme, whereby each 4 bit number is the difference
+between one sample and the next, divided by a (varying) step. The
+Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
+may well become a standard.
-\code{State} is a tuple containing the state of the coder. The coder
+\code{State} is a tuple containing the state of the coder. The coder
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
\var{newstate} should be passed to the next call of lin2adpcm. In the
-initial call \code{None} can be passed as the state. \var{adpcmfrag} is
-the ADPCM coded fragment packed 2 4-bit values per byte.
+initial call \code{None} can be passed as the state. \var{adpcmfrag}
+is the ADPCM coded fragment packed 2 4-bit values per byte.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm3}{fragment\, width\, state}
This is an alternative ADPCM coder that uses only 3 bits per sample.
It is not compatible with the Intel/DVI ADPCM coder and its output is
-not packed (due to laziness on the side of the author). Its use is
+not packed (due to laziness on the side of the author). Its use is
discouraged.
\end{funcdesc}
\begin{funcdesc}{lin2ulaw}{fragment\, width}
-This function converts samples in the audio fragment to U-LAW encoding
-and returns this as a Python string. U-LAW is an audio encoding format
-whereby you get a dynamic range of about 14 bits using only 8 bit
-samples. It is used by the Sun audio hardware, among others.
+Convert samples in the audio fragment to U-LAW encoding and return
+this as a Python string. U-LAW is an audio encoding format whereby
+you get a dynamic range of about 14 bits using only 8 bit samples. It
+is used by the Sun audio hardware, among others.
\end{funcdesc}
\begin{funcdesc}{minmax}{fragment\, width}
-This function returns a tuple consisting of the minimum and maximum
-values of all samples in the sound fragment.
+Return a tuple consisting of the minimum and maximum values of all
+samples in the sound fragment.
\end{funcdesc}
\begin{funcdesc}{max}{fragment\, width}
-This function returns the maximum of the {\em absolute value} of all
-samples in a fragment.
+Return the maximum of the {\em absolute value} of all samples in a
+fragment.
\end{funcdesc}
\begin{funcdesc}{maxpp}{fragment\, width}
-This function returns the maximum peak-peak value in the sound fragment.
+Return the maximum peak-peak value in the sound fragment.
\end{funcdesc}
\begin{funcdesc}{mul}{fragment\, width\, factor}
Return a fragment that has all samples in the original framgent
-multiplied by the floating-point value \var{factor}. Overflow is
+multiplied by the floating-point value \var{factor}. Overflow is
silently ignored.
\end{funcdesc}
\begin{funcdesc}{reverse}{fragment\, width}
-This function reverses the samples in a fragment and returns the
-modified fragment.
+Reverse the samples in a fragment and returns the modified fragment.
\end{funcdesc}
-\begin{funcdesc}{rms}{fragment\, width\, factor}
-Returns the root-mean-square of the fragment, i.e.
+\begin{funcdesc}{rms}{fragment\, width}
+Return the root-mean-square of the fragment, i.e.
\iftexi
the square root of the quotient of the sum of all squared sample value,
divided by the sumber of samples.
@@ -166,22 +166,22 @@
\end{funcdesc}
\begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor}
-This function converts a stereo fragment to a mono fragment. The left
-channel is multiplied by \var{lfactor} and the right channel by
-\var{rfactor} before adding the two channels to give a mono signal.
+Convert a stereo fragment to a mono fragment. The left channel is
+multiplied by \var{lfactor} and the right channel by \var{rfactor}
+before adding the two channels to give a mono signal.
\end{funcdesc}
\begin{funcdesc}{tostereo}{fragment\, width\, lfactor\, rfactor}
-This function generates a stereo fragment from a mono fragment. Each
-pair of samples in the stereo fragment are computed from the mono
-sample, whereby left channel samples are multiplied by \var{lfactor}
-and right channel samples by \var{rfactor}.
+Generate a stereo fragment from a mono fragment. Each pair of samples
+in the stereo fragment are computed from the mono sample, whereby left
+channel samples are multiplied by \var{lfactor} and right channel
+samples by \var{rfactor}.
\end{funcdesc}
\begin{funcdesc}{ulaw2lin}{fragment\, width}
-This function converts sound fragments in ULAW encoding to linearly
-encoded sound fragments. ULAW encoding always uses 8 bits samples, so
-\var{width} refers only to the sample width of the output fragment here.
+Convert sound fragments in ULAW encoding to linearly encoded sound
+fragments. ULAW encoding always uses 8 bits samples, so \var{width}
+refers only to the sample width of the output fragment here.
\end{funcdesc}
Note that operations such as \code{mul} or \code{max} make no
@@ -202,20 +202,20 @@
If you use the ADPCM coder to build network packets and you want your
protocol to be stateless (i.e.\ to be able to tolerate packet loss)
-you should not only transmit the data but also the state. Note that
+you should not only transmit the data but also the state. Note that
you should send the \var{initial} state (the one you passed to
\code{lin2adpcm}) along to the decoder, not the final state (as returned by
-the coder). If you want to use \code{struct} to store the state in
+the coder). If you want to use \code{struct} to store the state in
binary you can code the first element (the predicted value) in 16 bits
and the second (the delta index) in 8.
The ADPCM coders have never been tried against other ADPCM coders,
-only against themselves. It could well be that I misinterpreted the
+only against themselves. It could well be that I misinterpreted the
standards in which case they will not be interoperable with the
respective standards.
The \code{find...} routines might look a bit funny at first sight.
-They are primarily meant for doing echo cancellation. A reasonably
+They are primarily meant to do echo cancellation. A reasonably
fast way to do this is to pick the most energetic piece of the output
sample, locate that in the input sample and subtract the whole output
sample from the input sample:
diff --git a/Doc/lib/libbltin.tex b/Doc/lib/libbltin.tex
index 04cea20..63b7c63 100644
--- a/Doc/lib/libbltin.tex
+++ b/Doc/lib/libbltin.tex
@@ -1,6 +1,7 @@
\section{Built-in Module \sectcode{__builtin__}}
\bimodindex{__builtin__}
-This module provides direct access to all `built-in' identifier of
+This module provides direct access to all `built-in' identifiers of
Python; e.g. \code{__builtin__.open} is the full name for the built-in
-function \code{open}.
+function \code{open}. See the section on Built-in Functions in the
+previous chapter.
diff --git a/Doc/lib/libcgi.tex b/Doc/lib/libcgi.tex
index 082a2a1..1950895 100644
--- a/Doc/lib/libcgi.tex
+++ b/Doc/lib/libcgi.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{cgi}}
+\section{Standard Module \sectcode{cgi}}
\stmodindex{cgi}
\indexii{WWW}{server}
\indexii{CGI}{protocol}
@@ -134,3 +134,85 @@
The shell environment, exactly as received from the http server. See
the CGI documentation for a description of the various fields.
\end{datadesc}
+
+\subsection{Example}
+
+This example assumes that you have a WWW server up and running,
+e.g.\ NCSA's \code{httpd}.
+
+Place the following file in a convenient spot in the WWW server's
+directory tree. E.g., if you place it in the subdirectory \file{test}
+of the root directory and call it \file{test.html}, its URL will be
+\file{http://\var{yourservername}/test/test.html}.
+
+\begin{verbatim}
+<TITLE>Test Form Input</TITLE>
+<H1>Test Form Input</H1>
+<FORM METHOD="POST" ACTION="/cgi-bin/test.py">
+<INPUT NAME=Name> (Name)<br>
+<INPUT NAME=Address> (Address)<br>
+<INPUT TYPE=SUBMIT>
+</FORM>
+\end{verbatim}
+
+Selecting this file's URL from a forms-capable browser such as Mosaic
+or Netscape will bring up a simple form with two text input fields and
+a ``submit'' button.
+
+But wait. Before pressing ``submit'', a script that responds to the
+form must also be installed. The test file as shown assumes that the
+script is called \file{test.py} and lives in the server's
+\code{cgi-bin} directory. Here's the test script:
+
+\begin{verbatim}
+#!/usr/local/bin/python
+
+import cgi
+
+print "Content-type: text/html"
+print # End of headers!
+print "<TITLE>Test Form Output</TITLE>"
+print "<H1>Test Form Output</H1>"
+
+form = cgi.SvFormContentDict() # Load the form
+
+name = addr = None # Default: no name and address
+
+# Extract name and address from the form, if given
+
+if form.has_key('Name'):
+ name = form['Name']
+if form.has_key('Address'):
+ addr = form['Address']
+
+# Print an unnumbered list of the name and address, if present
+
+print "<UL>"
+if name is not None:
+ print "<LI>Name:", cgi.escape(name)
+if addr is not None:
+ print "<LI>Address:", cgi.escape(addr)
+print "</UL>"
+\end{verbatim}
+
+The script should be made executable (\samp{chmod +x \var{script}}).
+If the Python interpreter is not located at
+\file{/usr/local/bin/python} but somewhere else, the first line of the
+script should be modified accordingly.
+
+Now that everything is installed correctly, we can try out the form.
+Bring up the test form in your WWW browser, fill in a name and address
+in the form, and press the ``submit'' button. The script should now
+run and its output is sent back to your browser. This should roughly
+look as follows:
+
+\strong{Test Form Output}
+
+\begin{itemize}
+\item Name: \var{the name you entered}
+\item Address: \var{the address you entered}
+\end{itemize}
+
+If you didn't enter a name or address, the corresponding line will be
+missing (since the browser doesn't send empty form fields to the
+server).
diff --git a/Doc/lib/libcopy.tex b/Doc/lib/libcopy.tex
index c141e05..4c0ce72 100644
--- a/Doc/lib/libcopy.tex
+++ b/Doc/lib/libcopy.tex
@@ -1,5 +1,6 @@
-\section{Built-in module \sectcode{copy}}
+\section{Standard Module \sectcode{copy}}
\stmodindex{copy}
+\renewcommand{\indexsubitem}{(copy function)}
\ttindex{copy}
\ttindex{deepcopy}
@@ -14,7 +15,7 @@
x = copy.deepcopy(y) # make a deep copy of y
\end{verbatim}
-For module specific errors, \code{copy.Error} is raised.
+For module specific errors, \code{copy.error} is raised.
The difference between shallow and deep copying is only relevant for
compound objects (objects that contain other objects, like lists or
@@ -74,6 +75,7 @@
\code{__setstate__()}. See the description of module \code{pickle}
for information on these methods.
\stmodindex{pickle}
+\renewcommand{\indexsubitem}{(copy protocol)}
\ttindex{__getinitargs__}
\ttindex{__getstate__}
\ttindex{__setstate__}
diff --git a/Doc/lib/libcrypto.tex b/Doc/lib/libcrypto.tex
index 302b50d..972106c 100644
--- a/Doc/lib/libcrypto.tex
+++ b/Doc/lib/libcrypto.tex
@@ -5,8 +5,13 @@
installation.
\index{cryptography}
-%Hardcore cypherpunks will probably find the Python Cryptography Kit of
-%further interest; the package adds built-in modules for DES and IDEA
-%encryption, and provides a Python module for reading and decrypting PGP files.
-%\index{PGP}\indexii{DES}{cipher}\indexii{IDEA}{cipher}
-%\index{Python Cryptography Kit}
+Hardcore cypherpunks will probably find the Python Cryptography Kit of
+further interest; the package adds built-in modules for DES and IDEA
+encryption, and provides a Python module for reading and decrypting
+PGP files. The Python Cryptography Kit is not distributed with Python
+but available separately. See the URL
+\file{http://www.cs.mcgill.ca/\%7Efnord/crypt.html} for more information.
+\index{PGP}
+\indexii{DES}{cipher}
+\indexii{IDEA}{cipher}
+\index{Python Cryptography Kit}
diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex
index 33083cd..7cc9195 100644
--- a/Doc/lib/libexcs.tex
+++ b/Doc/lib/libexcs.tex
@@ -24,7 +24,7 @@
\begin{excdesc}{AttributeError}
% xref to attribute reference?
Raised when an attribute reference or assignment fails. (When an
- object does not support attributes references or attribute assignments
+ object does not support attribute references or attribute assignments
at all, \code{TypeError} is raised.)
\end{excdesc}
diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
index 46b41a5..147fb8c 100644
--- a/Doc/lib/libfcntl.tex
+++ b/Doc/lib/libfcntl.tex
@@ -1,5 +1,5 @@
% Manual text by Jaap Vermeulen
-\section{Built-in module \sectcode{fcntl}}
+\section{Built-in Module \sectcode{fcntl}}
\bimodindex{fcntl}
\indexii{\UNIX{}}{file control}
\indexii{\UNIX{}}{I/O control}
diff --git a/Doc/lib/libfl.tex b/Doc/lib/libfl.tex
index 5af1a04..47f10c7 100644
--- a/Doc/lib/libfl.tex
+++ b/Doc/lib/libfl.tex
@@ -2,17 +2,18 @@
\bimodindex{fl}
This module provides an interface to the FORMS Library by Mark
-Overmars, version 2.0b. For more info about FORMS, write to
-{\tt markov@cs.ruu.nl}.
+Overmars. The source for the library can be retrieved by anonymous
+ftp from host \samp{ftp.cs.ruu.nl}, directory \file{SGI/FORMS}. It
+was last tested with version 2.0b.
Most functions are literal translations of their C equivalents,
-dropping the initial \samp{fl_} from their name. Constants used by the
-library are defined in module \code{FL} described below.
+dropping the initial \samp{fl_} from their name. Constants used by
+the library are defined in module \code{FL} described below.
The creation of objects is a little different in Python than in C:
instead of the `current form' maintained by the library to which new
FORMS objects are added, all functions that add a FORMS object to a
-button are methods of the Python object representing the form.
+form are methods of the Python object representing the form.
Consequently, there are no Python equivalents for the C functions
\code{fl_addto_form} and \code{fl_end_form}, and the equivalent of
\code{fl_bgn_form} is called \code{fl.make_form}.
@@ -26,13 +27,13 @@
There are no `free objects' in the Python interface to FORMS, nor is
there an easy way to add object classes written in Python. The FORMS
-interface to GL event handling is avaiable, though, so you can mix
+interface to GL event handling is available, though, so you can mix
FORMS with pure GL windows.
\strong{Please note:} importing \code{fl} implies a call to the GL function
\code{foreground()} and to the FORMS routine \code{fl_init()}.
-\subsection{Functions defined in module \sectcode{fl}}
+\subsection{Functions Defined in Module \sectcode{fl}}
Module \code{fl} defines the following functions. For more information
about what they do, see the description of the equivalent C function
@@ -92,7 +93,7 @@
\end{funcdesc}
\begin{funcdesc}{show_file_selector}{message\, directory\, pattern\, default}
-Show a dialog box inm which the user can select a file. It returns
+Show a dialog box in which the user can select a file. It returns
the absolute filename selected by the user, or \code{None} if the user
presses Cancel.
\end{funcdesc}
@@ -130,7 +131,7 @@
\code{fl_mapcolor} and \code{fl_getmcolor}.
\end{funcdesc}
-\subsection{Form object methods and data attributes}
+\subsection{Form Objects}
Form objects (returned by \code{fl.make_form()} above) have the
following methods. Each method corresponds to a C function whose name
@@ -382,7 +383,7 @@
\lineiii{doublebuf}{int}{nonzero if double buffering on}
\end{tableiii}
-\subsection{FORMS object methods and data attributes}
+\subsection{FORMS Objects}
Besides methods specific to particular kinds of FORMS objects, all
FORMS objects also have the following methods:
diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex
index acd8784..f5f7ef3 100644
--- a/Doc/lib/libftplib.tex
+++ b/Doc/lib/libftplib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{ftplib}}
+\section{Standard Module \sectcode{ftplib}}
\stmodindex{ftplib}
\renewcommand{\indexsubitem}{(in module ftplib)}
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 0eb6857..4778c7d 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -92,8 +92,8 @@
\var{expression} argument is parsed and evaluated as a Python
expression (technically speaking, a condition list) using the
\var{globals} and \var{locals} dictionaries as global and local name
- space. If the \var{globals} dictionary is omitted it defaults to
- the \var{locals} dictionary. If both dictionaries are omitted, the
+ space. If the \var{locals} dictionary is omitted it defaults to
+ the \var{globals} dictionary. If both dictionaries are omitted, the
expression is executed in the environment where \code{eval} is
called. The return value is the result of the evaluated expression.
Syntax errors are reported as exceptions. Example:
@@ -119,20 +119,21 @@
\end{funcdesc}
\begin{funcdesc}{execfile}{file\optional{\, globals\optional{\, locals}}}
- This function is similar to the \code{eval()} function or the
+ This function is similar to the
\code{exec} statement, but parses a file instead of a string. It is
different from the \code{import} statement in that it does not use
the module administration --- it reads the file unconditionally and
- does not create a new module.
+ does not create a new module.\footnote{It is used relatively rarely
+ so does not warrant being made into a statement.}
The arguments are a file name and two optional dictionaries. The
file is parsed and evaluated as a sequence of Python statements
(similarly to a module) using the \var{globals} and \var{locals}
- dictionaries as global and local name space. If the \var{globals}
- dictionary is omitted it defaults to the \var{locals} dictionary.
+ dictionaries as global and local name space. If the \var{locals}
+ dictionary is omitted it defaults to the \var{globals} dictionary.
If both dictionaries are omitted, the expression is executed in the
- environment where \code{execfile} is called. The return value is
- None.
+ environment where \code{execfile()} is called. The return value is
+ \code{None}.
\end{funcdesc}
\begin{funcdesc}{filter}{function\, list}
@@ -173,8 +174,8 @@
\end{funcdesc}
\begin{funcdesc}{hex}{x}
- Convert a number to a hexadecimal string. The result is a valid
- Python expression.
+ Convert an integer number (of any size) to a hexadecimal string.
+ The result is a valid Python expression.
\end{funcdesc}
\begin{funcdesc}{id}{object}
@@ -194,7 +195,9 @@
\begin{funcdesc}{int}{x}
Convert a number to a plain integer. The argument may be a plain or
- long integer or a floating point number.
+ long integer or a floating point number. Conversion of floating
+ point numbers to integers is defined by the C semantics; normally
+ the conversion truncates towards zero.
\end{funcdesc}
\begin{funcdesc}{len}{s}
@@ -231,8 +234,8 @@
\end{funcdesc}
\begin{funcdesc}{oct}{x}
- Convert a number to an octal string. The result is a valid Python
- expression.
+ Convert an integer number (of any size) to an octal string. The
+ result is a valid Python expression.
\end{funcdesc}
\begin{funcdesc}{open}{filename\optional{\, mode\optional{\, bufsize}}}
@@ -290,7 +293,8 @@
the last element is the largest \code{\var{start} + \var{i} *
\var{step}} less than \var{end}; if \var{step} is negative, the last
element is the largest \code{\var{start} + \var{i} * \var{step}}
- greater than \var{end}. \var{step} must not be zero. Example:
+ greater than \var{end}. \var{step} must not be zero (or else an
+ exception is raised). Example:
\bcode\begin{verbatim}
>>> range(10)
@@ -321,7 +325,7 @@
>>> s = raw_input('--> ')
--> Monty Python's Flying Circus
>>> s
-'Monty Python\'s Flying Circus'
+"Monty Python's Flying Circus"
>>>
\end{verbatim}\ecode
\end{funcdesc}
@@ -337,17 +341,48 @@
\end{funcdesc}
\begin{funcdesc}{reload}{module}
- Re-parse and re-initialize an already imported \var{module}. The
- argument must be a module object, so it must have been successfully
- imported before. This is useful if you have edited the module source
- file using an external editor and want to try out the new version
- without leaving the Python interpreter. Note that if a module is
- syntactically correct but its initialization fails, the first
- \code{import} statement for it does not import the name, but does
- create a (partially initialized) module object; to reload the module
- you must first \code{import} it again (this will just make the
- partially initialized module object available) before you can
- \code{reload()} it.
+Re-parse and re-initialize an already imported \var{module}. The
+argument must be a module object, so it must have been successfully
+imported before. This is useful if you have edited the module source
+file using an external editor and want to try out the new version
+without leaving the Python interpreter. The return value is the
+module object (i.e.\ the same as the \var{module} argument).
+
+There are a number of caveats:
+
+If a module is syntactically correct but its initialization fails, the
+first \code{import} statement for it does not bind its name locally,
+but does store a (partially initialized) module object in
+\code{sys.modules}. To reload the module you must first
+\code{import} it again (this will bind the name to the partially
+initialized module object) before you can \code{reload()} it.
+
+When a module is reloaded, its dictionary (containing the module's
+global variables) is retained. Redefinitions of names will override
+the old definitions, so this is generally not a problem. If the new
+version of a module does not define a name that was defined by the old
+version, the old definition remains. This feature can be used to the
+module's advantage if it maintains a global table or cache of objects
+--- with a \code{try} statement it can test for the table's presence
+and skip its initialization if desired.
+
+It is legal though generally not very useful to reload built-in or
+dynamically loaded modules, except for \code{sys}, \code{__main__} and
+\code{__builtin__}. In certain cases, however, extension modules are
+not designed to be initialized more than once, and may fail in
+arbitrary ways when reloaded.
+
+If a module imports objects from another module using \code{from}
+{\ldots} \code{import} {\ldots}, calling \code{reload()} for the other
+module does not redefine the objects imported from it --- one way
+around this is to re-execute the \code{from} statement, another is to
+use \code{import} and qualified names (\var{module}.\var{name})
+instead.
+
+If a module instantiates instances of a class, reloading the module
+that defines the class does not affect the method definitions of the
+instances --- they continue to use the old class definition. The same
+is true for derived classes.
\end{funcdesc}
\begin{funcdesc}{repr}{object}
@@ -385,23 +420,25 @@
its goal is to return a printable string.
\end{funcdesc}
-\begin{funcdesc}{tuple}{object}
+\begin{funcdesc}{tuple}{sequence}
Return a tuple whose items are the same and in the same order as
-\var{object}'s items. If \var{object} is alread a tuple, it
+\var{sequence}'s items. If \var{sequence} is alread a tuple, it
is returned unchanged. For instance, \code{tuple('abc')} returns
returns \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns
\code{(1, 2, 3)}.
\end{funcdesc}
\begin{funcdesc}{type}{object}
-% XXXJH xref to buil-in objects here?
- Return the type of an \var{object}. The return value is a type
- object. There is not much you can do with type objects except compare
- them to other type objects; e.g., the following checks if a variable
- is a string:
+Return the type of an \var{object}. The return value is a type
+object. The standard module \code{types} defines names for all
+built-in types.
+\stmodindex{types}
+\obindex{type}
+For instance:
\bcode\begin{verbatim}
->>> if type(x) == type(''): print 'It is a string'
+>>> import types
+>>> if type(x) == types.StringType: print "It's a string"
\end{verbatim}\ecode
\end{funcdesc}
@@ -424,7 +461,7 @@
actually storing them all simultaneously. The advantage of
\code{xrange()} over \code{range()} is minimal (since \code{xrange()}
still has to create the values when asked for them) except when a very
-large range is used on a memory-starved machine (e.g. DOS) or when all
+large range is used on a memory-starved machine (e.g. MS-DOS) or when all
of the range's elements are never used (e.g. when the loop is usually
terminated with \code{break}).
\end{funcdesc}
diff --git a/Doc/lib/libgetopt.tex b/Doc/lib/libgetopt.tex
index 250d31f..3f9592a 100644
--- a/Doc/lib/libgetopt.tex
+++ b/Doc/lib/libgetopt.tex
@@ -5,7 +5,8 @@
\code{sys.argv}.
It uses the same conventions as the \UNIX{}
\code{getopt()}
-function.
+function (including the special meanings of arguments of the form
+\samp{-} and \samp{--}).
It defines the function
\code{getopt.getopt(args, options)}
and the exception
diff --git a/Doc/lib/libgopherlib.tex b/Doc/lib/libgopherlib.tex
index 904a64b..eb50fdd 100644
--- a/Doc/lib/libgopherlib.tex
+++ b/Doc/lib/libgopherlib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{gopherlib}}
+\section{Standard Module \sectcode{gopherlib}}
\stmodindex{gopherlib}
\renewcommand{\indexsubitem}{(in module gopherlib)}
diff --git a/Doc/lib/libgrp.tex b/Doc/lib/libgrp.tex
index 6310498..90a2ed3 100644
--- a/Doc/lib/libgrp.tex
+++ b/Doc/lib/libgrp.tex
@@ -13,7 +13,7 @@
The gid is an integer, name and password are strings, and the member
list is a list of strings.
(Note that most users are not explicitly listed as members of the
-group(s) they are in.)
+group they are in according to the password database.)
An exception is raised if the entry asked for cannot be found.
It defines the following items:
diff --git a/Doc/lib/libhtmllib.tex b/Doc/lib/libhtmllib.tex
index 8882246..aeb4ce9 100644
--- a/Doc/lib/libhtmllib.tex
+++ b/Doc/lib/libhtmllib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{htmllib}}
+\section{Standard Module \sectcode{htmllib}}
\stmodindex{htmllib}
\index{HTML}
\index{hypertext}
@@ -27,12 +27,14 @@
\item
The interface to feed data to an instance is through the \code{feed()}
method, which takes a string argument. This can be called with as
-little or as much text at a time as desired. When the data contains complete
+little or as much text at a time as desired;
+\code{p.feed(a); p.feed(b)} has the same effect as \code{p.feed(a+b)}.
+When the data contains complete
HTML elements, these are processed immediately; incomplete elements
are saved in a buffer. To force processing of all unprocessed data,
call the \code{close()} method.
-Example: to parse the entire contents of a file, do
+Example: to parse the entire contents of a file, do\\
\code{parser.feed(open(file).read()); parser.close()}.
\item
@@ -142,7 +144,7 @@
\index{style sheet}
\begin{datadesc}{NullStylesheet}
-A style sheet for use on a dumb output device such as an ASCII
+A style sheet for use on a dumb output device such as an \ASCII{}
terminal.
\end{datadesc}
@@ -242,9 +244,9 @@
\end{funcdesc}
\begin{datadesc}{nospace}
-If this instance variable is true, empty words are ignored by
-\code{addword}. It is set to false after a non-empty word has been
-added.
+If this instance variable is true, empty words should be ignored by
+\code{addword}. It should be set to false after a non-empty word has
+been added.
\end{datadesc}
\begin{funcdesc}{setjust}{justification}
diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex
index 0d7ac4f..46d791b 100644
--- a/Doc/lib/libhttplib.tex
+++ b/Doc/lib/libhttplib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{httplib}}
+\section{Standard Module \sectcode{httplib}}
\stmodindex{httplib}
\index{HTTP}
@@ -15,7 +15,15 @@
number is passed, the port is extracted from the host string if it has
the form \code{host:port}, else the default HTTP port (80) is used.
If no host is passed, no connection is made, and the \code{connect}
-method should be used to connect to a server.
+method should be used to connect to a server. For example, the
+following calls all create instances that connect to the server at the
+same host and port:
+
+\begin{verbatim}
+>>> h1 = httplib.HTTP('www.cwi.nl')
+>>> h2 = httplib.HTTP('www.cwi.nl:80')
+>>> h3 = httplib.HTTP('www.cwi.nl', 80)
+\end{verbatim}
Once an \code{HTTP} instance has been connected to an HTTP server, it
should be used as follows:
@@ -27,7 +35,7 @@
\item[2.] Make zero or more calls to the \code{putheader()} method.
\item[3.] Call the \code{endheaders()} method (this can be omitted if
-step 4. makes no calls).
+step 4 makes no calls).
\item[4.] Optional calls to the \code{send()} method.
@@ -93,3 +101,22 @@
read, using the \code{read()}, \code{readline()} or \code{readlines()}
methods.
\end{funcdesc}
+
+\subsection{Example}
+
+Here is an example session:
+
+\begin{verbatim}
+>>> import httplib
+>>> h = httplib.HTTP('www.cwi.nl')
+>>> h.putrequest('GET', '/index.html')
+>>> h.putheader('Accept', 'text/html')
+>>> h.putheader('Accept', 'text/plain')
+>>> h.endheaders()
+>>> errcode, errmsg, headers = h.getreply()
+>>> print errcode # Should be 200
+>>> f = h.getfile()
+>>> data f.read() # Get the raw HTML
+>>> f.close()
+>>>
+\end{verbatim}
diff --git a/Doc/lib/libimageop.tex b/Doc/lib/libimageop.tex
index 836ae76..4e15117 100644
--- a/Doc/lib/libimageop.tex
+++ b/Doc/lib/libimageop.tex
@@ -1,9 +1,9 @@
-\section{Built-in module \sectcode{imageop}}
+\section{Built-in Module \sectcode{imageop}}
\bimodindex{imageop}
The \code{imageop} module contains some useful operations on images.
It operates on images consisting of 8 or 32 bit pixels
-stored in Python strings. This is the same format as used
+stored in Python strings. This is the same format as used
by \code{gl.lrectwrite} and the \code{imgfile} module.
The module defines the following variables and functions:
@@ -17,49 +17,48 @@
\begin{funcdesc}{crop}{image\, psize\, width\, height\, x0\, y0\, x1\, y1}
-This function takes the image in \var{image}, which should by
+Return the selected part of \var{image}, which should by
\var{width} by \var{height} in size and consist of pixels of
-\var{psize} bytes, and returns the selected part of that image. \var{x0},
-\var{y0}, \var{x1} and \var{y1} are like the \code{lrectread}
-parameters, i.e. the boundary is included in the new image.
-The new boundaries need not be inside the picture. Pixels that fall
-outside the old image will have their value set to zero.
-If \var{x0} is bigger than \var{x1} the new image is mirrored. The
-same holds for the y coordinates.
+\var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like
+the \code{lrectread} parameters, i.e.\ the boundary is included in the
+new image. The new boundaries need not be inside the picture. Pixels
+that fall outside the old image will have their value set to zero. If
+\var{x0} is bigger than \var{x1} the new image is mirrored. The same
+holds for the y coordinates.
\end{funcdesc}
\begin{funcdesc}{scale}{image\, psize\, width\, height\, newwidth\, newheight}
-This function returns an \var{image} scaled to size \var{newwidth} by
-\var{newheight}. No interpolation is done, scaling is done by
-simple-minded pixel duplication or removal. Therefore, computer-generated
-images or dithered images will not look nice after scaling.
+Return \var{image} scaled to size \var{newwidth} by \var{newheight}.
+No interpolation is done, scaling is done by simple-minded pixel
+duplication or removal. Therefore, computer-generated images or
+dithered images will not look nice after scaling.
\end{funcdesc}
\begin{funcdesc}{tovideo}{image\, psize\, width\, height}
-This function runs a vertical low-pass filter over an image. It does
-so by computing each destination pixel as the average of two
-vertically-aligned source pixels. The main use of this routine is to
-forestall excessive flicker if the image is displayed on a video
-device that uses interlacing, hence the name.
+Run a vertical low-pass filter over an image. It does so by computing
+each destination pixel as the average of two vertically-aligned source
+pixels. The main use of this routine is to forestall excessive
+flicker if the image is displayed on a video device that uses
+interlacing, hence the name.
\end{funcdesc}
\begin{funcdesc}{grey2mono}{image\, width\, height\, threshold}
-This function converts a 8-bit deep greyscale image to a 1-bit deep
-image by tresholding all the pixels. The resulting image is tightly
-packed and is probably only useful as an argument to \code{mono2grey}.
+Convert a 8-bit deep greyscale image to a 1-bit deep image by
+tresholding all the pixels. The resulting image is tightly packed and
+is probably only useful as an argument to \code{mono2grey}.
\end{funcdesc}
\begin{funcdesc}{dither2mono}{image\, width\, height}
-This function also converts an 8-bit greyscale image to a 1-bit
-monochrome image but it uses a (simple-minded) dithering algorithm.
+Convert an 8-bit greyscale image to a 1-bit monochrome image using a
+(simple-minded) dithering algorithm.
\end{funcdesc}
\begin{funcdesc}{mono2grey}{image\, width\, height\, p0\, p1}
-This function converts a 1-bit monochrome image to an 8 bit greyscale
-or color image. All pixels that are zero-valued on input get value
-\var{p0} on output and all one-value input pixels get value \var{p1}
-on output. To convert a monochrome black-and-white image to greyscale
-pass the values \code{0} and \code{255} respectively.
+Convert a 1-bit monochrome image to an 8 bit greyscale or color image.
+All pixels that are zero-valued on input get value \var{p0} on output
+and all one-value input pixels get value \var{p1} on output. To
+convert a monochrome black-and-white image to greyscale pass the
+values \code{0} and \code{255} respectively.
\end{funcdesc}
\begin{funcdesc}{grey2grey4}{image\, width\, height}
@@ -74,7 +73,7 @@
\begin{funcdesc}{dither2grey2}{image\, width\, height}
Convert an 8-bit greyscale image to a 2-bit greyscale image with
-dithering. As for \code{dither2mono}, the dithering algorithm is
+dithering. As for \code{dither2mono}, the dithering algorithm is
currently very simple.
\end{funcdesc}
diff --git a/Doc/lib/libimgfile.tex b/Doc/lib/libimgfile.tex
index 2da8d9d..1e8b2aa 100644
--- a/Doc/lib/libimgfile.tex
+++ b/Doc/lib/libimgfile.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{imgfile}}
+\section{Built-in Module \sectcode{imgfile}}
\bimodindex{imgfile}
The imgfile module allows python programs to access SGI imglib image
diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex
index 9ead176..91e250b 100644
--- a/Doc/lib/libimp.tex
+++ b/Doc/lib/libimp.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{imp}}
+\section{Built-in Module \sectcode{imp}}
\bimodindex{imp}
\index{import}
@@ -9,7 +9,7 @@
\renewcommand{\indexsubitem}{(in module struct)}
\begin{funcdesc}{get_magic}{}
-Return the magic string used to recognize value byte-compiled code
+Return the magic string value used to recognize byte-compiled code
files (``\code{.pyc} files'').
\end{funcdesc}
@@ -22,15 +22,15 @@
(this can be \code{'r'} for text files or \code{'rb'} for binary
files), and \var{type} is the file type, which has one of the values
\code{PY_SOURCE}, \code{PY_COMPILED} or \code{C_EXTENSION}, defined
-below.
+below. (System-dependent values may also be returned.)
\end{funcdesc}
\begin{funcdesc}{find_module}{name\, \optional{path}}
Try to find the module \var{name} on the search path \var{path}. The
default \var{path} is \code{sys.path}. The return value is a triple
\code{(\var{file}, \var{pathname}, \var{description})} where
-\var{file} is an open file object positioned at the beginning
-corresponding to the file found, \var{pathname} is the pathname of the
+\var{file} is an open file object positioned at the beginning,
+\var{pathname} is the pathname of the
file found, and \var{description} is a triple as contained in the list
returned by \code{get_suffixes} describing the kind of file found.
\end{funcdesc}
@@ -134,33 +134,27 @@
\begin{verbatim}
import imp
-from sys import modules
+import sys
def __import__(name, globals=None, locals=None, fromlist=None):
- # Fast path: let's see if it's already in sys.modules.
- # Two speed optimizations are worth mentioning:
- # - We use 'modules' instead of 'sys.modules'; this saves a
- # dictionary look-up per call.
- # - It's also faster to use a try-except statement than
- # to use modules.has_key(name) to check if it's there.
- try:
- return modules[name]
- except KeyError:
- pass
+ # Fast path: see if the module has already been imported.
+ if sys.modules.has_key(name):
+ return sys.modules[name]
- # See if it's a built-in module
+ # If any of the following calls raises an exception,
+ # there's a problem we con't handle -- let the caller handle it.
+
+ # See if it's a built-in module.
m = imp.init_builtin(name)
if m:
return m
- # See if it's a frozen module
+ # See if it's a frozen module.
m = imp.init_frozen(name)
if m:
return m
# Search the default path (i.e. sys.path).
- # If this raises an exception, the module is not found --
- # let the caller handle the exception.
fp, pathname, (suffix, mode, type) = imp.find_module(name)
# See what we got.
@@ -170,7 +164,7 @@
if type == imp.PY_SOURCE:
return imp.load_source(name, pathname, fp)
if type == imp.PY_COMPILED:
- return imp.load_source(name, pathname, fp)
+ return imp.load_compiled(name, pathname, fp)
# Shouldn't get here at all.
raise ImportError, '%s: unknown module type (%d)' % (name, type)
diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex
index 2b0a400..319c195 100644
--- a/Doc/lib/libmarshal.tex
+++ b/Doc/lib/libmarshal.tex
@@ -4,9 +4,9 @@
This module contains functions that can read and write Python
values in a binary format. The format is specific to Python, but
independent of machine architecture issues (e.g., you can write a
-Python value to a file on a VAX, transport the file to a Mac, and read
-it back there). Details of the format not explained here; read the
-source if you're interested.%
+Python value to a file on a PC, transport the file to a Sun, and read
+it back there). Details of the format are undocumented on purpose;
+it may change between Python versions (although it rarely does).%
\footnote{The name of this module stems from a bit of terminology used
by the designers of Modula-3 (amongst others), who use the term
``marshalling'' for shipping of data around in a self-contained form.
@@ -14,6 +14,14 @@
internal to external form (in an RPC buffer for instance) and
``unmarshalling'' for the reverse process.}
+This is not a general ``persistency'' module. For general persistency
+and transfer of Python objects through RPC calls, see the modules
+\code{pickle} and \code{shelve}. The \code{marshal} module exists
+mainly to support reading and writing the ``pseudo-compiled'' code for
+Python modules of \samp{.pyc} files.
+\stmodindex{pickle}
+\stmodindex{shelve}
+\obindex{code}
Not all Python object types are supported; in general, only objects
whose value is independent from a particular invocation of Python can
@@ -23,7 +31,22 @@
should be understood that tuples, lists and dictionaries are only
supported as long as the values contained therein are themselves
supported; and recursive lists and dictionaries should not be written
-(they will cause an infinite loop).
+(they will cause infinite loops).
+
+{\bf Caveat:} On machines where C's \code{long int} type has more than
+32 bits (such as the DEC Alpha or the HP Precision Architecture), it
+is possible to create plain Python integers that are longer than 32
+bits. Since the current \code{marshal} module uses 32 bits to
+transfer plain Python integers, such values are silently truncated.
+This particularly affects the use of very long integer literals in
+Python modules --- these will be accepted by the parser on such
+machines, but will be silently be truncated when the module is read
+from the \code{.pyc} instead.%
+\footnote{A solution would be to refuse such literals in the parser,
+since they are inherently non-portable. Another solution would be to
+let the \code{marshal} module raise an exception when an integer value
+would be truncated. At least one of these solutions will be
+implemented in a future version.}
There are functions that read/write files as well as functions
operating on strings.
@@ -31,6 +54,7 @@
The module defines these functions:
\renewcommand{\indexsubitem}{(in module marshal)}
+
\begin{funcdesc}{dump}{value\, file}
Write the value on the open file. The value must be a supported
type. The file must be an open file object such as
diff --git a/Doc/lib/libmd5.tex b/Doc/lib/libmd5.tex
index 0dfa65e..bd26f02 100644
--- a/Doc/lib/libmd5.tex
+++ b/Doc/lib/libmd5.tex
@@ -1,61 +1,64 @@
-\section{Built-in module \sectcode{md5}}
+\section{Built-in Module \sectcode{md5}}
\bimodindex{md5}
This module implements the interface to RSA's MD5 message digest
-algorithm (see also the file \file{md5.doc}). Its use is quite
-straightforward:\ use the function \code{new} to create an
-\dfn{md5}-object. You can now ``feed'' this object with arbitrary
-strings.
+algorithm (see also Internet RFC 1321). Its use is quite
+straightforward:\ use the \code{md5.new()} to create an md5 object.
+You can now feed this object with arbitrary strings using the
+\code{update()} method, and at any point you can ask it for the
+\dfn{digest} (a strong kind of 128-bit checksum,
+a.k.a. ``fingerprint'') of the contatenation of the strings fed to it
+so far using the \code{digest()} method.
-At any time you can ask for the ``final'' digest of the object. Internally,
-a temporary copy of the object is made and the digest is computed and
-returned. Because of the copy, the digest operation is not destructive
-for the object. Before a more exact description of the module's use, a small
-example will be helpful:
-to obtain the digest of the string \code{'abc'}, use \ldots
+For example, to obtain the digest of the string {\tt"Nobody inspects
+the spammish repetition"}:
\bcode\begin{verbatim}
>>> import md5
>>> m = md5.new()
->>> m.update('abc')
+>>> m.update("Nobody inspects")
+>>> m.update(" the spammish repetition")
>>> m.digest()
-'\220\001P\230<\322O\260\326\226?}(\341\177r'
+'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
\end{verbatim}\ecode
More condensed:
\bcode\begin{verbatim}
->>> md5.new('abc').digest()
-'\220\001P\230<\322O\260\326\226?}(\341\177r'
+>>> md5.new("Nobody inspects the spammish repetition").digest()
+'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
\end{verbatim}\ecode
\renewcommand{\indexsubitem}{(in module md5)}
\begin{funcdesc}{new}{\optional{arg}}
- Create a new md5-object. If \var{arg} is present, an initial
- \code{update} method is called with \var{arg} as argument.
+Return a new md5 object. If \var{arg} is present, the method call
+\code{update(\var{arg})} is made.
\end{funcdesc}
\begin{funcdesc}{md5}{\optional{arg}}
For backward compatibility reasons, this is an alternative name for the
-\code{new} function.
+\code{new()} function.
\end{funcdesc}
-An md5-object has the following methods:
+An md5 object has the following methods:
\renewcommand{\indexsubitem}{(md5 method)}
\begin{funcdesc}{update}{arg}
- Update this md5-object with the string \var{arg}.
+Update the md5 object with the string \var{arg}. Repeated calls are
+equivalent to a single call with the concatenation of all the
+arguments, i.e.\ \code{m.update(a); m.update(b)} is equivalent to
+\code{m.update(a+b)}.
\end{funcdesc}
\begin{funcdesc}{digest}{}
-% XXX The following is not quite clear; what does MD5Final do?
- Return the \dfn{digest} of this md5-object. Internally, a copy is made
- and the \C-function \code{MD5Final} is called. Finally the digest is
- returned.
+Return the digest of the strings passed to the \code{update()}
+method so far. This is an 8-byte string which may contain
+non-\ASCII{} characters, including null bytes.
\end{funcdesc}
\begin{funcdesc}{copy}{}
- Return a separate copy of this md5-object. An \code{update} to this
- copy won't affect the original object.
+Return a copy (``clone'') of the md5 object. This can be used to
+efficiently compute the digests of strings that share a common initial
+substring.
\end{funcdesc}
diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex
index 0d1a81b..361e0d0 100644
--- a/Doc/lib/libmimetools.tex
+++ b/Doc/lib/libmimetools.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{mimetools}}
+\section{Standard Module \sectcode{mimetools}}
\stmodindex{mimetools}
\renewcommand{\indexsubitem}{(in module mimetools)}
diff --git a/Doc/lib/libmpz.tex b/Doc/lib/libmpz.tex
index 1fd03f7..d274a03 100644
--- a/Doc/lib/libmpz.tex
+++ b/Doc/lib/libmpz.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{mpz}}
+\section{Built-in Module \sectcode{mpz}}
\bimodindex{mpz}
This module implements the interface to part of the GNU MP library.
diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex
index 6aac671..b1a891d 100644
--- a/Doc/lib/libnntplib.tex
+++ b/Doc/lib/libnntplib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{nntplib}}
+\section{Standard Module \sectcode{nntplib}}
\stmodindex{nntplib}
\renewcommand{\indexsubitem}{(in module nntplib)}
diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index 5109f5d..51442ef 100644
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -26,9 +26,11 @@
following variables and functions are always exported by \code{os}:
\renewcommand{\indexsubitem}{(in module os)}
+
\begin{datadesc}{name}
-The name of the OS dependent module imported, e.g. \code{'posix'} or
-\code{'mac'}.
+The name of the OS dependent module imported. The following names
+have currently been registered: \code{'posix'}, \code{'nt'},
+\code{'dos'}, \code{'mac'}.
\end{datadesc}
\begin{datadesc}{path}
@@ -49,29 +51,54 @@
\end{datadesc}
\begin{datadesc}{sep}
-The character used by the OS to separate pathname components, e.g.
+The character used by the OS to separate pathname components, e.g.\
\code{'/'} for POSIX or \code{':'} for the Mac. Note that knowing this
is not sufficient to be able to parse or concatenate pathnames---better
use \code{os.path.split()} and \code{os.path.join()}---but it is
occasionally useful.
\end{datadesc}
+\begin{datadesc}{pathsep}
+The character conventionally used by the OS to separate search patch
+components (as in \code{\$PATH}), e.g.\ \code{':'} for POSIX or
+\code{';'} for MS-DOS.
+\end{datadesc}
+
+\begin{datadesc}{defpath}
+The default search path used by \code{os.exec*p*()} if the environment
+doesn't have a \code{'PATH'} key.
+\end{datadesc}
+
\begin{funcdesc}{execl}{path\, arg0\, arg1\, ...}
-This is equivalent to a call to \code{os.execv} with an \var{argv}
-of \code{[\var{arg0}, \var{arg1}, ...]}.
+This is equivalent to
+\code{os.execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
\end{funcdesc}
\begin{funcdesc}{execle}{path\, arg0\, arg1\, ...\, env}
-This is equivalent to a call to \code{os.execve} with an \var{argv}
-of \code{[\var{arg0}, \var{arg1}, ...]}.
+This is equivalent to
+\code{os.execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
\end{funcdesc}
\begin{funcdesc}{execlp}{path\, arg0\, arg1\, ...}
-This is like \code{execl} but duplicates the shell's actions in
-searching for an executable file in a list of directories. The
-directory list is obtained from \code{environ['PATH']}.
+This is equivalent to
+\code{os.execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
\end{funcdesc}
-\begin{funcdesc}{execvp}{path\, arg0\, arg1\, ...}
-\code{execvp} is for \code{execv} what \code{execlp} is for \code{execl}.
+\begin{funcdesc}{execvp}{path\, args}
+This is like \code{os.execv(\var{path}, \var{args})} but duplicates
+the shell's actions in searching for an executable file in a list of
+directories. The directory list is obtained from
+\code{os.environ['PATH']}.
\end{funcdesc}
+
+\begin{funcdesc}{execvpe}{path\, args\, env}
+This is a cross between \code{os.execve()} and \code{os.execvp()}.
+The directory list is obtained from \code{\var{env}['PATH']}.
+\end{funcdesc}
+
+(The functions \code{os.execv()} and \code{execve()} are not
+documented here, since they are implemented by the OS dependent
+module. If the OS dependent module doesn't define either of these,
+the functions that rely on it will raise an exception. They are
+documented in the section on module \code{posix}, together with all
+other functions that \code{os} imports from the OS dependent module.)
diff --git a/Doc/lib/libpdb.tex b/Doc/lib/libpdb.tex
index 7b3f1d4..54a3f58 100644
--- a/Doc/lib/libpdb.tex
+++ b/Doc/lib/libpdb.tex
@@ -91,7 +91,7 @@
\code{sys.last_traceback}.
\end{funcdesc}
-\subsection{Debugger Commands}
+\section{Debugger Commands}
The debugger recognizes the following commands. Most commands can be
abbreviated to one or two letters; e.g. ``\code{h(elp)}'' means that
@@ -117,7 +117,7 @@
\begin{description}
-\item[{h(elp) [\var{command}]}]
+\item[h(elp) [\var{command}]]
Without argument, print the list of available commands.
With a \var{command} as argument, print help about that command.
@@ -127,40 +127,40 @@
an identifier, ``\code{help exec}'' must be entered to get help on the
``\code{!}'' command.
-\item[{w(here)}]
+\item[w(here)]
Print a stack trace, with the most recent frame at the bottom.
An arrow indicates the current frame, which determines the
context of most commands.
-\item[{d(own)}]
+\item[d(own)]
Move the current frame one level down in the stack trace
(to an older frame).
-\item[{u(p)}]
+\item[u(p)]
Move the current frame one level up in the stack trace
(to a newer frame).
-\item[{b(reak) [\var{lineno}\code{|}\var{function}]}]
+\item[b(reak) [\var{lineno}\code{|}\var{function}]]
With a \var{lineno} argument, set a break there in the current
file. With a \var{function} argument, set a break at the entry of
that function. Without argument, list all breaks.
-\item[{cl(ear) [\var{lineno}]}]
+\item[cl(ear) [\var{lineno}]]
With a \var{lineno} argument, clear that break in the current file.
Without argument, clear all breaks (but first ask confirmation).
-\item[{s(tep)}]
+\item[s(tep)]
Execute the current line, stop at the first possible occasion
(either in a function that is called or on the next line in the
current function).
-\item[{n(ext)}]
+\item[n(ext)]
Continue execution until the next line in the current function
is reached or it returns. (The difference between \code{next} and
@@ -168,15 +168,15 @@
\code{next} executes called functions at (nearly) full speed, only
stopping at the next line in the current function.)
-\item[{r(eturn)}]
+\item[r(eturn)]
Continue execution until the current function returns.
-\item[{c(ont(inue))}]
+\item[c(ont(inue))]
Continue execution, only stop when a breakpoint is encountered.
-\item[{l(ist) [\var{first} [, \var{last}]]}]
+\item[l(ist) [\var{first} [, \var{last}]]]
List source code for the current file. Without arguments, list 11
lines around the current line or continue the previous listing. With
@@ -184,17 +184,17 @@
list the given range; if the second argument is less than the first,
it is interpreted as a count.
-\item[{a(rgs)}]
+\item[a(rgs)]
Print the argument list of the current function.
-\item[{p \var{expression}}]
+\item[p \var{expression}]
Evaluate the \var{expression} in the current context and print its
value. (Note: \code{print} can also be used, but is not a debugger
command --- this executes the Python \code{print} statement.)
-\item[{[!] \var{statement}}]
+\item[[!] \var{statement}]
Execute the (one-line) \var{statement} in the context of
the current stack frame.
@@ -207,9 +207,83 @@
(Pdb)
\end{verbatim}
-\item[{q(uit)}]
+\item[q(uit)]
Quit from the debugger.
The program being executed is aborted.
\end{description}
+
+\section{How It Works}
+
+Some changes were made to the interpreter:
+
+\begin{itemize}
+\item sys.settrace(func) sets the global trace function
+\item there can also a local trace function (see later)
+\end{itemize}
+
+Trace functions have three arguments: (\var{frame}, \var{event}, \var{arg})
+
+\begin{description}
+
+\item[\var{frame}] is the current stack frame
+
+\item[\var{event}] is a string: \code{'call'}, \code{'line'}, \code{'return'}
+or \code{'exception'}
+
+\item[\var{arg}] is dependent on the event type
+
+\end{description}
+
+A trace function should return a new trace function or None.
+Class methods are accepted (and most useful!) as trace methods.
+
+The events have the following meaning:
+
+\begin{description}
+
+\item[\code{'call'}]
+A function is called (or some other code block entered). The global
+trace function is called; arg is the argument list to the function;
+the return value specifies the local trace function.
+
+\item[\code{'line'}]
+The interpreter is about to execute a new line of code (sometimes
+multiple line events on one line exist). The local trace function is
+called; arg in None; the return value specifies the new local trace
+function.
+
+\item[\code{'return'}]
+A function (or other code block) is about to return. The local trace
+function is called; arg is the value that will be returned. The trace
+function's return value is ignored.
+
+\item[\code{'exception'}]
+An exception has occurred. The local trace function is called; arg is
+a triple (exception, value, traceback); the return value specifies the
+new local trace function
+
+\end{description}
+
+Note that as an exception is propagated down the chain of callers, an
+\code{'exception'} event is generated at each level.
+
+Stack frame objects have the following read-only attributes:
+
+\begin{description}
+\item[f_code] the code object being executed
+\item[f_lineno] the current line number (\code{-1} for \code{'call'} events)
+\item[f_back] the stack frame of the caller, or None
+\item[f_locals] dictionary containing local name bindings
+\item[f_globals] dictionary containing global name bindings
+\end{description}
+
+Code objects have the following read-only attributes:
+
+\begin{description}
+\item[co_code] the code string
+\item[co_names] the list of names used by the code
+\item[co_consts] the list of (literal) constants used by the code
+\item[co_filename] the filename from which the code was compiled
+\end{description}
diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex
index 5c01d36..8dc29e4 100644
--- a/Doc/lib/libpickle.tex
+++ b/Doc/lib/libpickle.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{pickle}}
+\section{Standard Module \sectcode{pickle}}
\stmodindex{pickle}
\index{persistency}
\indexii{persistent}{objects}
@@ -7,6 +7,8 @@
\indexii{flattening}{objects}
\indexii{pickling}{objects}
+\renewcommand{\indexsubitem}{(in module pickle)}
+
The \code{pickle} module implements a basic but powerful algorithm for
``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly
arbitrary Python objects. This is a more primitive notion than
@@ -28,11 +30,11 @@
\begin{itemize}
-\item recursive objects
+\item recursive objects (objects containing references to themselves)
-\item pointer sharing
+\item object sharing (references to the same object in different places)
-\item instances of user-defined classes
+\item user-defined classes and their instances
\end{itemize}
@@ -42,13 +44,13 @@
sharing or recursive objects); however it means that non-Python
programs may not be able to reconstruct pickled Python objects.
-The \code{pickle} data format uses a printable ASCII representation.
+The \code{pickle} data format uses a printable \ASCII{} representation.
This is slightly more voluminous than a binary representation.
However, small integers actually take {\em less} space when
represented as minimal-size decimal strings than when represented as
32-bit binary numbers, and strings are only much longer if they
contain many control characters or 8-bit characters. The big
-advantage of using printable ASCII (and of some other characteristics
+advantage of using printable \ASCII{} (and of some other characteristics
of \code{pickle}'s representation) is that for debugging or recovery
purposes it is possible for a human to read the pickled file with a
standard text editor. (I could have gone a step further and used a
@@ -67,7 +69,7 @@
For the benefit of persistency modules written using \code{pickle}, it
supports the notion of a reference to an object outside the pickled
data stream. Such objects are referenced by a name, which is an
-arbitrary string of printable ASCII characters. The resolution of
+arbitrary string of printable \ASCII{} characters. The resolution of
such names is not defined by the \code{pickle} module --- the
persistent object module will have to implement a method
\code{persistent_load}. To write references to persistent objects,
@@ -78,6 +80,8 @@
First of all, the class must be defined at the top level in a module.
+\renewcommand{\indexsubitem}{(pickle protocol)}
+
Next, it must normally be possible to create class instances by
calling the class without arguments. If this is undesirable, the
class can define a method \code{__getinitargs__()}, which should
@@ -86,7 +90,7 @@
\ttindex{__getinitargs__}
\ttindex{__init__}
-Classes can further influence how they are pickled --- if the class
+Classes can further influence how their instances are pickled --- if the class
defines the method \code{__getstate__()}, it is called and the return
state is pickled as the contents for the instance, and if the class
defines the method \code{__setstate__()}, it is called with the
@@ -113,6 +117,13 @@
number in the objects so that suitable conversions can be made by the
class's \code{__setstate__()} method.
+When a class itself is pickled, only its name is pickled --- the class
+definition is not pickled, but re-imported by the unpickling process.
+Therefore, the restriction that the class must be defined at the top
+level in a module applies to pickled classes as well.
+
+\renewcommand{\indexsubitem}{(in module pickle)}
+
The interface can be summarized as follows.
To pickle an object \code{x} onto a file \code{f}, open for writing:
@@ -122,6 +133,12 @@
p.dump(x)
\end{verbatim}
+A shorthand for this is:
+
+\begin{verbatim}
+pickle.dump(x, f)
+\end{verbatim}
+
To unpickle an object \code{x} from a file \code{f}, open for reading:
\begin{verbatim}
@@ -129,11 +146,19 @@
x = u.load(x)
\end{verbatim}
+A shorthand is:
+
+\begin{verbatim}
+x = pickle.load(f)
+\end{verbatim}
+
The \code{Pickler} class only calls the method \code{f.write} with a
string argument. The \code{Unpickler} calls the methods \code{f.read}
(with an integer argument) and \code{f.readline} (without argument),
both returning a string. It is explicitly allowed to pass non-file
objects here, as long as they have the right methods.
+\ttindex{Unpickler}
+\ttindex{Pickler}
The following types can be pickled:
\begin{itemize}
@@ -146,25 +171,56 @@
\item tuples, lists and dictionaries containing only picklable objects
-\item class instances whose \code{__dict__} or \code{__setstate__()}
-is picklable
+\item classes that are defined at the top level in a module
+
+\item instances of such classes whose \code{__dict__} or
+\code{__setstate__()} is picklable
\end{itemize}
-Attempts to pickle unpicklable objects will raise an exception; when
-this happens, an unspecified number of bytes may have been written to
-the file argument.
+Attempts to pickle unpicklable objects will raise the
+\code{PicklingError} exception; when this happens, an unspecified
+number of bytes may have been written to the file.
-It is possible to make multiple calls to \code{Pickler.dump()} or to
-\code{Unpickler.load()}, as long as there is a one-to-one
-correspondence between \code{Pickler} and \code{Unpickler} objects and
-between \code{dump} and \code{load} calls for any pair of
-corresponding \code{Pickler} and \code{Unpicklers}. {\em Warning}:
-this is intended for pickling multiple objects without intervening
-modifications to the objects or their parts. If you modify an object
-and then pickle it again using the same \code{Pickler} instance, the
-object is not pickled again --- a reference to it is pickled and the
-\code{Unpickler} will return the old value, not the modified one. (There
-are two problems here: (a) detecting changes, and (b) marshalling a
-minimal set of changes. I have no answers. Garbage Collection may
-also become a problem here.)
+It is possible to make multiple calls to the \code{dump()} method of
+the same \code{Pickler} instance. These must then be matched to the
+same number of calls to the \code{load()} instance of the
+corresponding \code{Unpickler} instance. If the same object is
+pickled by multiple \code{dump()} calls, the \code{load()} will all
+yield references to the same object. {\em Warning}: this is intended
+for pickling multiple objects without intervening modifications to the
+objects or their parts. If you modify an object and then pickle it
+again using the same \code{Pickler} instance, the object is not
+pickled again --- a reference to it is pickled and the
+\code{Unpickler} will return the old value, not the modified one.
+(There are two problems here: (a) detecting changes, and (b)
+marshalling a minimal set of changes. I have no answers. Garbage
+Collection may also become a problem here.)
+
+Apart from the \code{Pickler} and \code{Unpickler} classes, the
+module defines the following functions, and an exception:
+
+\begin{funcdesc}{dump}{object\, file}
+Write a pickled representation of \var{obect} to the open file object
+\var{file}. This is equivalent to \code{Pickler(file).dump(object)}.
+\end{funcdesc}
+
+\begin{funcdesc}{load}{file}
+Read a pickled object from the open file object \var{file}. This is
+equivalent to \code{Unpickler(file).load()}.
+\end{funcdesc}
+
+\begin{funcdesc}{dumps}{object}
+Return the pickled representation of the object as a string, instead
+of writing it to a file.
+\end{funcdesc}
+
+\begin{funcdesc}{loads}{string}
+Read a pickled object from a string instead of a file. Characters in
+the string past the pickled object's representation are ignored.
+\end{funcdesc}
+
+\begin{excdesc}{PicklingError}
+This exception is raised when an unpicklable object is passed to
+\code{Pickler.dump()}.
+\end{excdesc}
diff --git a/Doc/lib/libposix.tex b/Doc/lib/libposix.tex
index c749d74..ae041c4 100644
--- a/Doc/lib/libposix.tex
+++ b/Doc/lib/libposix.tex
@@ -1,12 +1,20 @@
\section{Built-in Module \sectcode{posix}}
-
\bimodindex{posix}
This module provides access to operating system functionality that is
standardized by the C Standard and the POSIX standard (a thinly disguised
\UNIX{} interface).
-It is available in all Python versions except on the Macintosh;
-the MS-DOS version does not support certain functions.
+
+\strong{Do not import this module directly.} Instead, import the
+module \code{os}, which provides a \emph{portable} version of this
+interface. On \UNIX{}, the \code{os} module provides a superset of
+the \code{posix} interface. On non-\UNIX{} operating systems the
+\code{posix} module is not available, but a subset is always available
+through the \code{os} interface. Once \code{os} is imported, there is
+\emph{no} performance penalty in using it instead of
+\code{posix}.
+\stmodindex{os}
+
The descriptions below are very terse; refer to the
corresponding \UNIX{} manual entry for more information.
@@ -20,13 +28,18 @@
\begin{datadesc}{environ}
A dictionary representing the string environment at the time
the interpreter was started.
-(Modifying this dictionary does not affect the string environment of the
-interpreter.)
For example,
\code{posix.environ['HOME']}
is the pathname of your home directory, equivalent to
\code{getenv("HOME")}
in C.
+Modifying this dictionary does not affect the string environment
+passed on by \code{execv()}, \code{popen()} or \code{system()}; if you
+need to change the environment, pass \code{environ} to \code{execve()}
+or add variable assignments and export statements to the command
+string for \code{system()} or \code{popen()}.%
+\footnote{The problem with automatically passing on \code{environ} is
+that there is no portable way of changing the environment.}
\end{datadesc}
\renewcommand{\indexsubitem}{(exception in module posix)}
diff --git a/Doc/lib/libposixfile.tex b/Doc/lib/libposixfile.tex
index 050ba5a..c472c95 100644
--- a/Doc/lib/libposixfile.tex
+++ b/Doc/lib/libposixfile.tex
@@ -7,12 +7,13 @@
file objects. In particular, it implements file locking, control over
the file flags, and an easy interface to duplicate the file object.
The module defines a new file object, the posixfile object. It
-inherits all the standard file object methods and adds the methods
-described below.
+has all the standard file object methods and adds the methods
+described below. This module only works for certain flavors of
+\UNIX{}, since it uses \code{fcntl()} for file locking.
To instantiate a posixfile object, use the \code{open()} function in
-the posixfile module. The resulting object looks and feels the same as
-a standard file object.
+the posixfile module. The resulting object looks and feels roughly
+the same as a standard file object.
The posixfile module defines the following constants:
@@ -32,10 +33,11 @@
The posixfile module defines the following functions:
\renewcommand{\indexsubitem}{(in module posixfile)}
-\begin{funcdesc}{open}{filename\, mode}
+
+\begin{funcdesc}{open}{filename\optional{\, mode\optional{\, bufsize}}}
Create a new posixfile object with the given filename and mode. The
- filename and mode are interpreted the same way as the \code{open()}
- builtin function.
+ \var{filename}, \var{mode} and \var{bufsize} arguments are
+ interpreted the same way as by the \code{open()} builtin function.
\end{funcdesc}
\begin{funcdesc}{fileopen}{fileobject}
@@ -102,8 +104,8 @@
\begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes}
\lineiii{|}{wait until the lock has been granted}{}
- \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)}
- {}&{\hskip0.5cm or \code{None} if there is no conflict.}&{}\\
+ \lineiii{?}{return the first lock conflicting with the requested lock, or
+ \code{None} if there is no conflict.}{(1)}
\end{tableiii}
Note:
diff --git a/Doc/lib/libppath.tex b/Doc/lib/libppath.tex
index c7c2b63..0d3bbe5 100644
--- a/Doc/lib/libppath.tex
+++ b/Doc/lib/libppath.tex
@@ -1,9 +1,14 @@
\section{Standard Module \sectcode{posixpath}}
-
\stmodindex{posixpath}
+
This module implements some useful functions on POSIX pathnames.
+\strong{Do not import this module directly.} Instead, import the
+module \code{os} and use \code{os.path}.
+\stmodindex{os}
+
\renewcommand{\indexsubitem}{(in module posixpath)}
+
\begin{funcdesc}{basename}{p}
Return the base name of pathname
\var{p}.
@@ -66,10 +71,12 @@
\end{funcdesc}
\begin{funcdesc}{ismount}{p}
-Return true if \var{p} is a mount point. (This currently checks whether
-\code{\var{p}/..} is on a different device from \var{p} or whether
-\code{\var{p}/..} and \var{p} point to the same i-node on the same
-device --- is this test correct for all \UNIX{} and POSIX variants?)
+Return true if pathname \var{p} is a \dfn{mount point}: a point in a
+file system where a different file system has been mounted. The
+function checks whether \var{p}'s parent, \file{\var{p}/..}, is on a
+different device than \var{p}, or whether \file{\var{p}/..} and
+\var{p} point to the same i-node on the same device --- this should
+detect mount points for all \UNIX{} and POSIX variants.
\end{funcdesc}
\begin{funcdesc}{join}{p\, q}
@@ -128,9 +135,10 @@
directory tree rooted at \var{p} (including \var{p} itself, if it is a
directory). The argument \var{dirname} specifies the visited directory,
the argument \var{names} lists the files in the directory (gotten from
-\code{posix.listdir(\var{dirname})}). The \var{visit} function may
-modify \var{names} to influence the set of directories visited below
-\var{dirname}, e.g., to avoid visiting certain parts of the tree. (The
-object referred to by \var{names} must be modified in place, using
-\code{del} or slice assignment.)
+\code{posix.listdir(\var{dirname})}, so including \samp{.} and
+\samp{..}). The \var{visit} function may modify \var{names} to
+influence the set of directories visited below \var{dirname}, e.g., to
+avoid visiting certain parts of the tree. (The object referred to by
+\var{names} must be modified in place, using \code{del} or slice
+assignment.)
\end{funcdesc}
diff --git a/Doc/lib/libprofile.tex b/Doc/lib/libprofile.tex
index 29cd01b..b14116d 100644
--- a/Doc/lib/libprofile.tex
+++ b/Doc/lib/libprofile.tex
@@ -2,7 +2,7 @@
\stmodindex{profile}
\stmodindex{pstats}
-Copyright 1994, by InfoSeek Corporation, all rights reserved.
+Copyright \copyright\ 1994, by InfoSeek Corporation, all rights reserved.
Written by James Roskind%
\footnote{
@@ -42,7 +42,7 @@
I'd appreciate the feedback.
-\section{Introduction}
+\section{Introduction to the profiler}
A \dfn{profiler} is a program that describes the run time performance
of a program, providing a variety of statistics. This documentation
@@ -242,7 +242,7 @@
\section{Reference Manual}
-\renewcommand{\indexsubitem}{}
+\renewcommand{\indexsubitem}{(profiler function)}
The primary entry point for the profiler is the global function
\code{profile.run()}. It is typically used to create any profile
@@ -254,7 +254,7 @@
``better'' profilers from the classes presented, or reading the source
code for these modules.
-\begin{funcdesc}{profile.run}{string\optional{\, filename}}
+\begin{funcdesc}{profile.run}{string\optional{\, filename\optional{\, ...}}}
This function takes a single argument that has can be passed to the
\code{exec} statement, and an optional file name. In all cases this
@@ -336,12 +336,12 @@
\end{funcdesc}
-\subsection{Methods Of The \sectcode{Stats} Class}
+\subsection{The \sectcode{Stats} Class}
\renewcommand{\indexsubitem}{(Stats method)}
\begin{funcdesc}{strip_dirs}{}
-This method for the code{Stats} class removes all leading path information
+This method for the \code{Stats} class removes all leading path information
from file names. It is very useful in reducing the size of the
printout to fit within (close to) 80 columns. This method modifies
the object, and the stripped information is lost. After performing a
@@ -355,7 +355,7 @@
\begin{funcdesc}{add}{filename\optional{\, ...}}
-This method of the code{Stats} class accumulates additional profiling
+This method of the \code{Stats} class accumulates additional profiling
information into the current profiling object. Its arguments should
refer to filenames created by the corresponding version of
\code{profile.run()}. Statistics for identically named (re: file,
@@ -364,7 +364,7 @@
\end{funcdesc}
\begin{funcdesc}{sort_stats}{key\optional{\, ...}}
-This method modifies the code{Stats} object by sorting it according to the
+This method modifies the \code{Stats} object by sorting it according to the
supplied criteria. The argument is typically a string identifying the
basis of a sort (example: \code{"time"} or \code{"name"}).
@@ -412,7 +412,7 @@
\begin{funcdesc}{reverse_order}{}
-This method for the code{Stats} class reverses the ordering of the basic
+This method for the \code{Stats} class reverses the ordering of the basic
list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable
now that ascending vs descending order is properly selected based on
@@ -420,7 +420,7 @@
\end{funcdesc}
\begin{funcdesc}{print_stats}{restriction\optional{\, ...}}
-This method for the code{Stats} class prints out a report as described
+This method for the \code{Stats} class prints out a report as described
in the \code{profile.run()} definition.
The order of the printing is based on the last \code{sort_stats()}
@@ -454,7 +454,7 @@
\begin{funcdesc}{print_callers}{restrictions\optional{\, ...}}
-This method for the code{Stats} class prints a list of all functions
+This method for the \code{Stats} class prints a list of all functions
that called each function in the profiled database. The ordering is
identical to that provided by \code{print_stats()}, and the definition
of the restricting argument is also identical. For convenience, a
@@ -464,14 +464,14 @@
\end{funcdesc}
\begin{funcdesc}{print_callees}{restrictions\optional{\, ...}}
-This method for the code{Stats} class prints a list of all function
+This method for the \code{Stats} class prints a list of all function
that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and
ordering are identical to the \code{print_callers()} method.
\end{funcdesc}
\begin{funcdesc}{ignore}{}
-This method of the code{Stats} class is used to dispose of the value
+This method of the \code{Stats} class is used to dispose of the value
returned by earlier methods. All standard methods in this class
return the instance that is being processed, so that the commands can
be strung together. For example:
@@ -481,7 +481,7 @@
\end{verbatim}
would perform all the indicated functions, but it would not return
-the final reference to the code{Stats} instance.%
+the final reference to the \code{Stats} instance.%
\footnote{
This was once necessary, when Python would print any unused expression
result that was not \code{None}. The method is still defined for
@@ -604,7 +604,7 @@
at this point, when a constant can be used.
-\section{Extensions: Deriving Better Profilers}
+\section{Extensions - Deriving Better Profilers}
The \code{Profile} class of module \code{profile} was written so that
derived classes could be developed to extend the profiler. Rather
diff --git a/Doc/lib/libregex.tex b/Doc/lib/libregex.tex
index dae6666..1b18679 100644
--- a/Doc/lib/libregex.tex
+++ b/Doc/lib/libregex.tex
@@ -44,12 +44,13 @@
\begin{funcdesc}{compile}{pattern\optional{\, translate}}
Compile a regular expression pattern into a regular expression
object, which can be used for matching using its \code{match} and
- \code{search} methods, described below. The optional
+ \code{search} methods, described below. The optional argument
\var{translate}, if present, must be a 256-character string
indicating how characters (both of the pattern and of the strings to
be matched) are translated before comparing them; the \code{i}-th
element of the string gives the translation for the character with
- ASCII code \code{i}.
+ \ASCII{} code \code{i}. This can be used to implement
+ case-insensitive matching; see the \code{casefold} data item below.
The sequence
diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex
index 602b6ef..d819238 100644
--- a/Doc/lib/librfc822.tex
+++ b/Doc/lib/librfc822.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{rfc822}}
+\section{Standard Module \sectcode{rfc822}}
\stmodindex{rfc822}
\renewcommand{\indexsubitem}{(in module rfc822)}
@@ -60,12 +60,12 @@
\var{name} exists, return \code{None, None}; otherwise both the full
name and the address are (possibly empty )strings.
-Example: If \code{m}'s first \code{From} header contains the string
-\code{'guido@cwi.nl (Guido van Rossum)'}, then
+Example: If \code{m}'s first \code{From} header contains the string\\
+\code{'jack@cwi.nl (Jack Jansen)'}, then
\code{m.getaddr('From')} will yield the pair
-\code{('Guido van Rossum', 'guido@cwi.nl')}.
+\code{('Jack Jansen', 'jack@cwi.nl')}.
If the header contained
-\code{'Guido van Rossum <guido@cwi.nl>'} instead, it would yield the
+\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the
exact same result.
\end{funcdesc}
diff --git a/Doc/lib/librgbimg.tex b/Doc/lib/librgbimg.tex
index f25921e..ace426f 100644
--- a/Doc/lib/librgbimg.tex
+++ b/Doc/lib/librgbimg.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{rgbimg}}
+\section{Built-in Module \sectcode{rgbimg}}
\bimodindex{rgbimg}
The rgbimg module allows python programs to access SGI imglib image
diff --git a/Doc/lib/librotor.tex b/Doc/lib/librotor.tex
index f2ea074..6befb05 100644
--- a/Doc/lib/librotor.tex
+++ b/Doc/lib/librotor.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{rotor}}
+\section{Built-in Module \sectcode{rotor}}
\bimodindex{rotor}
This module implements a rotor-based encryption algorithm, contributed by
diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex
index d47face..421d1aa 100644
--- a/Doc/lib/libselect.tex
+++ b/Doc/lib/libselect.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{select}}
+\section{Built-in Module \sectcode{select}}
\bimodindex{select}
This module provides access to the function \code{select} available in
diff --git a/Doc/lib/libsgmllib.tex b/Doc/lib/libsgmllib.tex
index 8abcb41..129bdd9 100644
--- a/Doc/lib/libsgmllib.tex
+++ b/Doc/lib/libsgmllib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{sgmllib}}
+\section{Standard Module \sectcode{sgmllib}}
\stmodindex{sgmllib}
\index{SGML}
@@ -66,7 +66,7 @@
\begin{funcdesc}{handle_charref}{ref}
This method is called to process a character reference of the form
``\code{\&\#\var{ref};}'' where \var{ref} is a decimal number in the
-range 0-255. It translates the character to ASCII and calls the
+range 0-255. It translates the character to \ASCII{} and calls the
method \code{handle_data()} with the character as argument. If
\var{ref} is invalid or out of range, the method
\code{unknown_charref(\var{ref})} is called instead.
diff --git a/Doc/lib/libshelve.tex b/Doc/lib/libshelve.tex
index 0dec230..a232add 100644
--- a/Doc/lib/libshelve.tex
+++ b/Doc/lib/libshelve.tex
@@ -1,7 +1,8 @@
-\section{Built-in module \sectcode{shelve}}
+\section{Standard Module \sectcode{shelve}}
\stmodindex{shelve}
\stmodindex{pickle}
\bimodindex{dbm}
+\bimodindex{gdbm}
A ``shelf'' is a persistent, dictionary-like object. The difference
with ``dbm'' databases is that the values (not the keys!) in a shelf
@@ -48,8 +49,11 @@
or may not be necessary to flush changes to disk.
\item
-The \code{shelve} module does not support {\em concurrent} access to
-shelved objects. Two programs should not try to simultaneously access
-the same shelf.
+The \code{shelve} module does not support {\em concurrent} read/write
+access to shelved objects. (Multiple simultaneous read accesses are
+safe.) When a program has a shelf open for writing, no other program
+should have it open for reading or writing. \UNIX{} file locking can
+be used to solve this, but this differs across \UNIX{} versions and
+requires knowledge about the database implementation used.
\end{itemize}
diff --git a/Doc/lib/libsignal.tex b/Doc/lib/libsignal.tex
index 13139d7..63b671f 100644
--- a/Doc/lib/libsignal.tex
+++ b/Doc/lib/libsignal.tex
@@ -20,7 +20,7 @@
``atomic'' instructions of the Python interpreter. This means that
signals arriving during long calculations implemented purely in C
(e.g.\ regular expression matches on large bodies of text) may be
-delayed for an arbitrary time.
+delayed for an arbitrary amount of time.
\item
When a signal arrives during an I/O operation, it is possible that the
@@ -48,8 +48,10 @@
in the main thread of execution. Any thread can perform an
\code{alarm()}, \code{getsignal()}, or \code{pause()}; only the main
thread can set a new signal handler, and the main thread will be the
-only one to receive signals. This means that signals can't be used as
-a means of interthread communication. Use locks instead.
+only one to receive signals (this is enforced by the Python signal
+module, even if the underlying thread implementation supports sending
+signals to individual threads). This means that signals can't be used
+as a means of interthread communication. Use locks instead.
\end{itemize}
@@ -126,4 +128,9 @@
When threads are enabled, this function can only be called from the
main thread; attempting to call it from other threads will cause a
\code{ValueError} exception to be raised.
+
+ The \var{handler} is called with two arguments: the signal number
+ and the current stack frame (\code{None} or a frame object; see the
+ reference manual for a description of frame objects).
+\obindex{frame}
\end{funcdesc}
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
index b826601..9b3c228 100644
--- a/Doc/lib/libsocket.tex
+++ b/Doc/lib/libsocket.tex
@@ -37,8 +37,8 @@
argument types and out-of-memory conditions can be raised; errors
related to socket or address semantics raise the error \code{socket.error}.
-Non-blocking and asynchronous mode are not supported; see module
-\code{select} for a way to do non-blocking socket I/O.
+Non-blocking mode is supported through the \code{setblocking()}
+method.
The module \code{socket} exports the following constants and functions:
@@ -95,7 +95,7 @@
Return a string containing the hostname of the machine where
the Python interpreter is currently executing. If you want to know the
current machine's IP address, use
-\code{socket.gethostbyname(socket.gethostname())} instead.
+\code{socket.gethostbyname(socket.gethostname())}.
\end{funcdesc}
\begin{funcdesc}{gethostbyaddr}{ip_address}
@@ -133,7 +133,7 @@
daemon).
\end{funcdesc}
-\subsection{Socket Object Methods}
+\subsection{Socket Objects}
\noindent
Socket objects have the following methods. Except for
@@ -187,28 +187,30 @@
\begin{funcdesc}{getsockopt}{level\, optname\optional{\, buflen}}
Return the value of the given socket option (see the \UNIX{} man page
-{\it getsockopt}(2)). The needed symbolic constants are defined in
-the \code{socket} module (\code{SO_*} etc.). If the optional third
-argument is absent, an integer option is assumed and its integer value
+{\it getsockopt}(2)). The needed symbolic constants (\code{SO_*} etc.)
+are defined in this module. If \var{buflen}
+is absent, an integer option is assumed and its integer value
is returned by the function. If \var{buflen} is present, it specifies
the maximum length of the buffer used to receive the option in, and
-this buffer is returned as a string. It's up to the caller to decode
+this buffer is returned as a string. It is up to the caller to decode
the contents of the buffer (see the optional built-in module
\code{struct} for a way to decode C structures encoded as strings).
\end{funcdesc}
\begin{funcdesc}{listen}{backlog}
-Listen for connections made to the socket.
-The argument specifies the maximum number of queued connections and
-should be at least 1; the maximum value is system-dependent.
+Listen for connections made to the socket. The \var{backlog} argument
+specifies the maximum number of queued connections and should be at
+least 1; the maximum value is system-dependent (usually 5).
\end{funcdesc}
-\begin{funcdesc}{makefile}{mode}
-Return a \dfn{file object} associated with the socket.
-(File objects were described earlier under Built-in Types.)
-The file object references a \code{dup}ped version of the socket file
-descriptor, so the file object and socket object may be closed or
-garbage-collected independently.
+\begin{funcdesc}{makefile}{\optional{mode\optional{\, bufsize}}}
+Return a \dfn{file object} associated with the socket. (File objects
+were described earlier under Built-in Types.) The file object
+references a \code{dup()}ped version of the socket file descriptor, so
+the file object and socket object may be closed or garbage-collected
+independently. The optional \var{mode} and \var{bufsize} arguments
+are interpreted the same way as by the built-in
+\code{open()} function.
\end{funcdesc}
\begin{funcdesc}{recv}{bufsize\optional{\, flags}}
@@ -219,23 +221,26 @@
zero.
\end{funcdesc}
-\begin{funcdesc}{recvfrom}{bufsize}
+\begin{funcdesc}{recvfrom}{bufsize\optional{\, flags}}
Receive data from the socket. The return value is a pair
\code{(\var{string}, \var{address})} where \var{string} is a string
representing the data received and \var{address} is the address of the
-socket sending the data.
+socket sending the data. The optional \var{flags} argument has the
+same meaning as for \code{recv()} above.
(The format of \var{address} depends on the address family --- see above.)
\end{funcdesc}
-\begin{funcdesc}{send}{string}
+\begin{funcdesc}{send}{string\optional{\, flags}}
Send data to the socket. The socket must be connected to a remote
-socket. Return the number of bytes sent.
+socket. The optional \var{flags} argument has the same meaning as for
+\code{recv()} above. Return the number of bytes sent.
\end{funcdesc}
-\begin{funcdesc}{sendto}{string\, address}
+\begin{funcdesc}{sendto}{string\optional{\, flags}\, address}
Send data to the socket. The socket should not be connected to a
remote socket, since the destination socket is specified by
-\code{address}. Return the number of bytes sent.
+\code{address}. The optional \var{flags} argument has the same
+meaning as for \code{recv()} above. Return the number of bytes sent.
(The format of \var{address} depends on the address family --- see above.)
\end{funcdesc}
diff --git a/Doc/lib/libstdwin.tex b/Doc/lib/libstdwin.tex
index df37707..29b047a 100644
--- a/Doc/lib/libstdwin.tex
+++ b/Doc/lib/libstdwin.tex
@@ -8,9 +8,10 @@
Interface, STDWIN [CWI report CR-R8817].
It is available on systems to which STDWIN has been ported (which is
most systems).
-It is only available if the \code{DISPLAY} environment variable is set
-or an explicit \samp{-display \var{displayname}} argument is passed to
-the interpreter.
+
+On Unix running X11, it can only be used if the \code{DISPLAY}
+environment variable is set or an explicit \samp{-display
+\var{displayname}} argument is passed to the Python interpreter.
Functions have names that usually resemble their C STDWIN counterparts
with the initial `w' dropped.
@@ -63,6 +64,7 @@
in resource definitions), i.e. the wildcard character \code{'*'}
matches any sequence of characters (including none) and \code{'?'}
matches any single character.
+On the Macintosh this function currently returns an empty list.
\end{funcdesc}
\begin{funcdesc}{setdefscrollbars}{hflag\, vflag}
@@ -164,6 +166,7 @@
\begin{funcdesc}{newbitmap}{width\, height}
Create a new bitmap object of the given dimensions.
Methods of bitmap objects are described below.
+Not available on the Macintosh.
\end{funcdesc}
\begin{funcdesc}{fleep}{}
@@ -294,7 +297,7 @@
\ttindex{select}
\end{funcdesc}
-\subsection{Window Object Methods}
+\subsection{Window Objects}
Window objects are created by \code{stdwin.open()}. They are closed
by their \code{close()} method or when they are garbage-collected.
@@ -440,7 +443,7 @@
Discard the window object. It should not be used again.
\end{funcdesc}
-\subsection{Drawing Object Methods}
+\subsection{Drawing Objects}
Drawing objects are created exclusively by the window method
\code{begindrawing()}.
@@ -560,6 +563,7 @@
in the bitmap, in the foreground color, or \code{None}, to draw all
bits (ones are drawn in the foreground color, zeros in the background
color).
+Not available on the Macintosh.
\end{funcdesc}
\begin{funcdesc}{cliprect}{rect}
@@ -582,7 +586,7 @@
Discard the drawing object. It should not be used again.
\end{funcdesc}
-\subsection{Menu Object Methods}
+\subsection{Menu Objects}
A menu object represents a menu.
The menu is destroyed when the menu object is deleted.
@@ -617,11 +621,13 @@
Discard the menu object. It should not be used again.
\end{funcdesc}
-\subsection{Bitmap Object Methods}
+\subsection{Bitmap Objects}
A bitmap represents a rectangular array of bits.
The top left bit has coordinate (0, 0).
A bitmap can be drawn with the \code{bitmap} method of a drawing object.
+Bitmaps are currently not available on the Macintosh.
+
The following methods are defined:
\renewcommand{\indexsubitem}{(bitmap method)}
@@ -644,7 +650,7 @@
Discard the bitmap object. It should not be used again.
\end{funcdesc}
-\subsection{Text-edit Object Methods}
+\subsection{Text-edit Objects}
A text-edit object represents a text-edit block.
For semantics, see the STDWIN documentation for C programmers.
diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex
index 0c9ad7d..960e94b 100644
--- a/Doc/lib/libstring.tex
+++ b/Doc/lib/libstring.tex
@@ -61,14 +61,25 @@
preceded by a sign (\samp{+} or \samp{-}).
\end{funcdesc}
-\begin{funcdesc}{atoi}{s}
-Convert a string to an integer. The string must consist of one or more
-digits, optionally preceded by a sign (\samp{+} or \samp{-}).
+\begin{funcdesc}{atoi}{s\optional{\, base}}
+Convert string \var{s} to an integer in the given \var{base}. The
+string must consist of one or more digits, optionally preceded by a
+sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it is
+0, a default base is chosen depending on the leading characters of the
+string (after stripping the sign): \samp{0x} or \samp{0X} means 16,
+\samp{0} means 8, anything else means 10. If \var{base} is 16, a
+leading \samp{0x} or \samp{0X} is always accepted. (Note: for a more
+flexible interpretation of numeric literals, use the built-in function
+\code{eval()}.
+\bifuncindex{eval}
\end{funcdesc}
-\begin{funcdesc}{atol}{s}
-Convert a string to a long integer. The string must consist of one
-or more digits, optionally preceded by a sign (\samp{+} or \samp{-}).
+\begin{funcdesc}{atol}{s\optional{\, base}}
+Convert string \var{s} to a long integer in the given \var{base}. The
+string must consist of one or more digits, optionally preceded by a
+sign (\samp{+} or \samp{-}). The \var{base} argument has the same
+meaning as for \code{atoi()}. A trailing \samp{l} or \samp{L} is not
+allowed.
\end{funcdesc}
\begin{funcdesc}{expandtabs}{s\, tabsize}
@@ -101,10 +112,11 @@
not found.
\end{funcdesc}
-\begin{funcdesc}{count}{s\, sub\optional{\, i}}
+\begin{funcdesc}{count}{s\, sub\optional{\, start}}
Return the number of (non-overlapping) occurrences of substring
-\var{sub} in string \var{s} with index at least \var{i}.
-If \var{i} is omitted, it defaults to \code{0}.
+\var{sub} in string \var{s} with index at least \var{start}.
+If \var{start} is omitted, it defaults to \code{0}. If \var{start} is
+negative, \code{len(\var{s})} is added.
\end{funcdesc}
\begin{funcdesc}{lower}{s}
diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
index 280fe55..a2c1b10 100644
--- a/Doc/lib/libstruct.tex
+++ b/Doc/lib/libstruct.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{struct}}
+\section{Built-in Module \sectcode{struct}}
\bimodindex{struct}
\indexii{C}{structures}
diff --git a/Doc/lib/libsun.tex b/Doc/lib/libsun.tex
index 9624b9c..d297b9c 100644
--- a/Doc/lib/libsun.tex
+++ b/Doc/lib/libsun.tex
@@ -4,7 +4,7 @@
that are unique to the SunOS operating system (versions 4 and 5; the
latter is also known as SOLARIS version 2).
-\section{Built-in module \sectcode{sunaudiodev}}
+\section{Built-in Module \sectcode{sunaudiodev}}
\bimodindex{sunaudiodev}
This module allows you to access the sun audio interface. The sun
@@ -30,7 +30,7 @@
only for the activity needed. See the audio manpage for details.
\end{funcdesc}
-\subsection{Audio device object methods}
+\subsection{Audio Device Objects}
The audio device objects are returned by \code{open} define the
following methods (except \code{control} objects which only provide
@@ -108,6 +108,5 @@
\file{<sun/audioio.h>}, with the leading string \samp{AUDIO_} stripped.
Useability of the control device is limited at the moment, since there
-is no way to use the 'wait for something to happen' feature the device
-provides. This is because that feature makes heavy use of signals, and
-these do not map too well onto Python.
+is no way to use the ``wait for something to happen'' feature the
+device provides.
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
index ffda68d..8899052 100644
--- a/Doc/lib/libsys.tex
+++ b/Doc/lib/libsys.tex
@@ -6,11 +6,16 @@
It is always available.
\renewcommand{\indexsubitem}{(in module sys)}
+
\begin{datadesc}{argv}
The list of command line arguments passed to a Python script.
- \code{sys.argv[0]} is the script name.
+ \code{sys.argv[0]} is the script name (it is operating system
+ dependent whether this is a full pathname or not).
+ If the command was executed using the \samp{-c} command line option
+ to the interpreter, \code{sys.argv[0]} is set to the string
+ \code{"-c"}.
If no script name was passed to the Python interpreter,
- \code{sys.argv} is empty.
+ \code{sys.argv} has zero length.
\end{datadesc}
\begin{datadesc}{builtin_module_names}
@@ -28,9 +33,11 @@
invoked. Their meaning is: \code{exc_type} gets the exception type of
the exception being handled; \code{exc_value} gets the exception
parameter (its \dfn{associated value} or the second argument to
- \code{raise}); \code{exc_traceback} gets a traceback object which
+ \code{raise}); \code{exc_traceback} gets a traceback object (see the
+ Reference Manual) which
encapsulates the call stack at the point where the exception
originally occurred.
+\obindex{traceback}
\end{datadesc}
\begin{funcdesc}{exit}{n}
@@ -45,7 +52,7 @@
This value is not actually defined by the module, but can be set by
the user (or by a program) to specify a clean-up action at program
exit. When set, it should be a parameterless function. This function
- will be called when the interpreter exits in any way (but not when a
+ will be called when the interpreter exits in any way (except not when a
fatal error occurs: in that case the interpreter's internal state
cannot be trusted).
\end{datadesc}
@@ -94,26 +101,23 @@
\begin{funcdesc}{settrace}{tracefunc}
Set the system's trace function, which allows you to implement a
- Python source code debugger in Python. The standard modules
- \code{pdb} and \code{wdb} are such debuggers; the difference is that
- \code{wdb} uses windows and needs STDWIN, while \code{pdb} has a
- line-oriented interface not unlike dbx. See the file \file{pdb.doc}
- in the Python library source directory for more documentation (both
- about \code{pdb} and \code{sys.trace}).
+ Python source code debugger in Python. See section ``How It Works''
+ in the chapter on the Python Debugger.
\end{funcdesc}
-\ttindex{pdb}
-\ttindex{wdb}
\index{trace function}
+\index{debugger}
\begin{funcdesc}{setprofile}{profilefunc}
Set the system's profile function, which allows you to implement a
- Python source code profiler in Python. The system's profile function
+ Python source code profiler in Python. See the chapter on the
+ Python Profiler. The system's profile function
is called similarly to the system's trace function (see
\code{sys.settrace}), but it isn't called for each executed line of
code (only on call and return and when an exception occurs). Also,
its return value is not used, so it can just return \code{None}.
\end{funcdesc}
\index{profile function}
+\index{profiler}
\begin{datadesc}{stdin}
\dataline{stdout}
@@ -127,7 +131,11 @@
own prompts and (almost all of) its error messages go to
\code{sys.stderr}. \code{sys.stdout} and \code{sys.stderr} needn't
be built-in file objects: any object is acceptable as long as it has
- a \code{write} method that takes a string argument.
+ a \code{write} method that takes a string argument. (Changing these
+ objects doesn't affect the standard I/O streams of processes
+ executed by \code{popen()}, \code{system()} or the \code{exec*()}
+ family of functions in the \code{os} module.)
+\stmodindex{os}
\end{datadesc}
\begin{datadesc}{tracebacklimit}
diff --git a/Doc/lib/libtempfile.tex b/Doc/lib/libtempfile.tex
index f67821d..0a582e1 100644
--- a/Doc/lib/libtempfile.tex
+++ b/Doc/lib/libtempfile.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{tempfile}}
+\section{Standard Module \sectcode{tempfile}}
\stmodindex{tempfile}
\indexii{temporary}{file name}
\indexii{temporary}{file}
diff --git a/Doc/lib/libtemplate.tex b/Doc/lib/libtemplate.tex
index a7f70ae..9b85178 100644
--- a/Doc/lib/libtemplate.tex
+++ b/Doc/lib/libtemplate.tex
@@ -7,7 +7,7 @@
% \section{} generates the section header,
% \bimodindex{} or \stmodundex{} generates an index entry for this module
-\section{Built-in module \sectcode{spam}} % If implemented in C
+\section{Built-in Module \sectcode{spam}} % If implemented in C
\bimodindex[spam}
\section{Standard module \sectcode{spam}} % If implemented in Python
@@ -110,7 +110,7 @@
% separate subsection. It is important to redefine ``indexsubitem''
% for each subsection.
-\subsection{Spam methods}
+\subsection{Spam Objects}
Spam objects (returned by \code{open()} above) have the following
methods.
diff --git a/Doc/lib/libthread.tex b/Doc/lib/libthread.tex
index 7147ebf..bd81d7c 100644
--- a/Doc/lib/libthread.tex
+++ b/Doc/lib/libthread.tex
@@ -26,18 +26,22 @@
then the thread exits (but other threads continue to run).
\end{funcdesc}
-\begin{funcdesc}{exit_thread}{}
-Exit the current thread silently. Other threads continue to run.
-\strong{Caveat:} code in pending \code{finally} clauses is not executed.
+\begin{funcdesc}{exit}{}
+This is a shorthand for \code{thread.exit_thread()}.
\end{funcdesc}
-\begin{funcdesc}{exit_prog}{status}
-Exit all threads and report the value of the integer argument
-\var{status} as the exit status of the entire program.
-\strong{Caveat:} code in pending \code{finally} clauses, in this thread
-or in other threads, is not executed.
+\begin{funcdesc}{exit_thread}{}
+Raise the \code{SystemExit} exception. When not caught, this will
+cause the thread to exit silently.
\end{funcdesc}
+%\begin{funcdesc}{exit_prog}{status}
+%Exit all threads and report the value of the integer argument
+%\var{status} as the exit status of the entire program.
+%\strong{Caveat:} code in pending \code{finally} clauses, in this thread
+%or in other threads, is not executed.
+%\end{funcdesc}
+
\begin{funcdesc}{allocate_lock}{}
Return a new lock object. Methods of locks are described below. The
lock is initially unlocked.
@@ -82,18 +86,16 @@
\item
Threads interact strangely with interrupts: the
\code{KeyboardInterrupt} exception will be received by an arbitrary
-thread.
+thread. (When the \code{signal} module is available, interrupts
+always go to the main thread.)
\item
-Calling \code{sys.exit(\var{status})} or executing
-\code{raise SystemExit, \var{status}} is almost equivalent to calling
-\code{thread.exit_prog(\var{status})}, except that the former ways of
-exiting the entire program do honor \code{finally} clauses in the
-current thread (but not in other threads).
+Calling \code{sys.exit()} or raising the \code{SystemExit} is
+equivalent to calling \code{thread.exit_thread()}.
\item
Not all built-in functions that may block waiting for I/O allow other
-threads to run, although the most popular ones (\code{sleep},
-\code{read}, \code{select}) work as expected.
+threads to run. (The most popular ones (\code{sleep}, \code{read},
+\code{select}) work as expected.)
\end{itemize}
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
index 1bc5ffa..746e21e 100644
--- a/Doc/lib/libtime.tex
+++ b/Doc/lib/libtime.tex
@@ -11,8 +11,7 @@
\item
The ``epoch'' is the point where the time starts. On January 1st of that
year, at 0 hours, the ``time since the epoch'' is zero. For UNIX, the
-epoch is 1970. To find out what the epoch is, look at the first
-element of \code{gmtime(0)}.
+epoch is 1970. To find out what the epoch is, look at \code{gmtime(0)}.
\item
UTC is Coordinated Universal Time (formerly known as Greenwich Mean
@@ -30,19 +29,20 @@
\item
The precision of the various real-time functions may be less than
suggested by the units in which their value or argument is expressed.
-E.g.\ on most UNIX systems, the clock ``ticks'' only every 1/50th or
-1/100th of a second, and on the Mac, it ticks 60 times a second.
+E.g.\ on most UNIX systems, the clock ``ticks'' only 50 or 100 times a
+second, and on the Mac, times are only accurate to whole seconds.
\end{itemize}
-Functions and data items are:
+The module defines the following functions and data items:
\renewcommand{\indexsubitem}{(in module time)}
\begin{datadesc}{altzone}
The offset of the local DST timezone, in seconds west of the 0th
-meridian, if one is defined. Only use this if \code{daylight} is
-nonzero.
+meridian, if one is defined. Negative if the local DST timezone is
+east of the 0th meridian (as in Western Europe, including the UK).
+Only use this if \code{daylight} is nonzero.
\end{datadesc}
@@ -56,8 +56,8 @@
\begin{funcdesc}{clock}{}
Return the current CPU time as a floating point number expressed in
-seconds. The precision depends on that of the C function by the same
-name.
+seconds. The precision, and in fact the very definiton of the meaning
+of ``CPU time'', depends on that of the C function of the same name.
\end{funcdesc}
diff --git a/Doc/lib/libtraceback.tex b/Doc/lib/libtraceback.tex
index 38d91ea..ca9c374 100644
--- a/Doc/lib/libtraceback.tex
+++ b/Doc/lib/libtraceback.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{traceback}}
+\section{Standard Module \sectcode{traceback}}
\stmodindex{traceback}
\renewcommand{\indexsubitem}{(in module traceback)}
diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex
index d93c402..a438d44 100644
--- a/Doc/lib/libtypes.tex
+++ b/Doc/lib/libtypes.tex
@@ -189,7 +189,7 @@
truncate as in \C{}; see functions \code{floor} and \code{ceil} in module
\code{math} for well-defined conversions.
\indexii{numeric}{conversions}
-\ttindex{math}
+\stmodindex{math}
\indexii{\C{}}{language}
\item[(2)]
@@ -205,7 +205,7 @@
\end{description}
% XXXJH exceptions: overflow (when? what operations?) zerodivision
-\subsubsection{Bit-string Operations on Integer Types.}
+\subsubsection{Bit-string Operations on Integer Types}
Plain and long integer types support additional operations that make
sense only for bit-strings. Negative numbers are treated as their 2's
@@ -287,7 +287,7 @@
\end{description}
-\subsubsection{More String Operations.}
+\subsubsection{More String Operations}
String objects have one unique built-in operation: the \code{\%}
operator (modulo) with a string left argument interprets this string
@@ -307,7 +307,7 @@
object and converts it to a string using \code{str()} before
formatting it. The ANSI features \code{\%p} and \code{\%n}
are not supported. Since Python strings have an explicit length,
-\code{\%s} conversions don't assume that \code{'\\0'} is the end of
+\code{\%s} conversions don't assume that \code{'\e0'} is the end of
the string.
For safety reasons, floating point precisions are clipped to 50;
@@ -330,14 +330,15 @@
Python has 002 quote types.
>>>
\end{verbatim}
-In this case no * specifiers may occur in a format.
+In this case no * specifiers may occur in a format (since they a
+require sequential parameter list).
Additional string operations are defined in standard module
\code{string} and in built-in module \code{regex}.
\index{string}
\index{regex}
-\subsubsection{Mutable Sequence Types.}
+\subsubsection{Mutable Sequence Types}
List objects support additional operations that allow in-place
modification of the object.
@@ -399,7 +400,7 @@
should return \code{-1}, \code{0} or \code{1} depending on whether the
first argument is considered smaller than, equal to, or larger than the
second argument. Note that this slows the sorting process down
- considerably; e.g. to sort an array in reverse order it is much faster
+ considerably; e.g. to sort a list in reverse order it is much faster
to use calls to \code{sort()} and \code{reverse()} than to use
\code{sort()} with a comparison function that reverses the ordering of
the elements.
@@ -409,7 +410,7 @@
A \dfn{mapping} object maps values of one type (the key type) to
arbitrary objects. Mappings are mutable objects. There is currently
-only one mapping type, the \dfn{dictionary}. A dictionary's keys are
+only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
almost arbitrary values. The only types of values not acceptable as
keys are values containing lists or dictionaries or other mutable
types that are compared by value rather than by object identity.
@@ -421,9 +422,9 @@
\indexii{dictionary}{type}
Dictionaries are created by placing a comma-separated list of
-\code{\var{key}: \var{value}} pairs within braces, for example:
-\code{\{'jack': 4098, 'sjoerd: 4127\}} or
-\code{\{4098: 'jack', 4127: 'sjoerd\}}.
+\code{\var{key}:\ \var{value}} pairs within braces, for example:
+\code{\{'jack':\ 4098, 'sjoerd':\ 4127\}} or
+\code{\{4098:\ 'jack', 4127:\ 'sjoerd'\}}.
The following operations are defined on mappings (where \var{a} is a
mapping, \var{k} is a key and \var{x} is an arbitrary object):
@@ -453,9 +454,7 @@
\begin{description}
\item[(1)] Raises an exception if \var{k} is not in the map.
-\item[(2)] Keys and values are listed in random order, but at any
-moment the ordering of the \code{keys()}, \code{values()} and
-\code{items()} lists is the consistent with each other.
+\item[(2)] Keys and values are listed in random order.
\end{description}
\subsection{Other Built-in Types}
@@ -463,7 +462,7 @@
The interpreter supports several other kinds of objects.
Most of these support only one or two operations.
-\subsubsection{Modules.}
+\subsubsection{Modules}
The only special operation on a module is attribute access:
\code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} accesses
@@ -483,11 +482,11 @@
Modules are written like this: \code{<module 'sys'>}.
-\subsubsection{Classes and Class Instances.}
+\subsubsection{Classes and Class Instances}
% XXXJH cross ref here
(See the Python Reference Manual for these.)
-\subsubsection{Functions.}
+\subsubsection{Functions}
Function objects are created by function definitions. The only
operation on a function object is to call it:
@@ -504,7 +503,7 @@
global name space (this is the same as \code{\var{m}.__dict__} where
\var{m} is the module in which the function \var{f} was defined).
-\subsubsection{Methods.}
+\subsubsection{Methods}
\obindex{method}
Methods are functions that are called using the attribute notation.
@@ -522,7 +521,7 @@
(See the Python Reference Manual for more info.)
-\subsubsection{Code Objects.}
+\subsubsection{Code Objects}
\obindex{code}
Code objects are used by the implementation to represent
@@ -543,7 +542,7 @@
(See the Python Reference Manual for more info.)
-\subsubsection{Type Objects.}
+\subsubsection{Type Objects}
Type objects represent the various object types. An object's type is
% XXXJH xref here
@@ -552,7 +551,7 @@
Types are written like this: \code{<type 'int'>}.
-\subsubsection{The Null Object.}
+\subsubsection{The Null Object}
This object is returned by functions that don't explicitly return a
value. It supports no special operations. There is exactly one null
@@ -560,7 +559,7 @@
It is written as \code{None}.
-\subsubsection{File Objects.}
+\subsubsection{File Objects}
File objects are implemented using \C{}'s \code{stdio} package and can be
% XXXJH xref here
@@ -643,7 +642,7 @@
does not add line separators.)
\end{funcdesc}
-\subsubsection{Internal Objects.}
+\subsubsection{Internal Objects}
(See the Python Reference Manual for these.)
diff --git a/Doc/lib/libtypes2.tex b/Doc/lib/libtypes2.tex
index 2280ed7..d0f20c9 100644
--- a/Doc/lib/libtypes2.tex
+++ b/Doc/lib/libtypes2.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{types}}
+\section{Standard Module \sectcode{types}}
\stmodindex{types}
\renewcommand{\indexsubitem}{(in module types)}
diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex
index aa672d4..b26228f 100644
--- a/Doc/lib/liburllib.tex
+++ b/Doc/lib/liburllib.tex
@@ -1,7 +1,7 @@
-\section{Built-in module \sectcode{urllib}}
+\section{Standard Module \sectcode{urllib}}
\stmodindex{urllib}
\index{WWW}
-\indexii{World-Wide}{Web}
+\index{World-Wide Web}
\index{URL}
\renewcommand{\indexsubitem}{(in module urllib)}
@@ -17,7 +17,7 @@
\begin{funcdesc}{urlopen}{url}
Open a network object denoted by a URL for reading. If the URL does
-not have a scheme identifier, or if it has \code{file:} as its scheme
+not have a scheme identifier, or if it has \samp{file:} as its scheme
identifier, this opens a local file; otherwise it opens a socket to a
server somewhere on the network. If the connection cannot be made, or
if the server returns an error code, the \code{IOError} exception is
@@ -26,7 +26,9 @@
\code{readlines()}, \code{fileno()}, \code{close()} and \code{info()}.
Except for the last one, these methods have the same interface as for
file objects --- see the section on File Objects earlier in this
-manual.
+manual. (It's not a built-in file object, however, so it can't be
+used at those few places where a true built-in file object is
+required.)
The \code{info()} method returns an instance of the class
\code{rfc822.Message} containing the headers received from the server,
diff --git a/Doc/lib/liburlparse.tex b/Doc/lib/liburlparse.tex
index 6fa2a37..c35d032 100644
--- a/Doc/lib/liburlparse.tex
+++ b/Doc/lib/liburlparse.tex
@@ -1,7 +1,7 @@
-\section{Built-in module \sectcode{urlparse}}
+\section{Standard Module \sectcode{urlparse}}
\stmodindex{urlparse}
\index{WWW}
-\indexii{World-Wide}{Web}
+\index{World-Wide Web}
\index{URL}
\indexii{URL}{parsing}
\indexii{relative}{URL}
@@ -28,14 +28,14 @@
Each tuple item is a string, possibly empty.
The components are not broken up in smaller parts (e.g. the network
location is a single string), and \% escapes are not expanded.
-The delimiters as shown above are not part of the tuple items, {\em
-except} for a leading slash in the \var{path} component, which is
-kept if present.
+The delimiters as shown above are not part of the tuple items,
+except for a leading slash in the \var{path} component, which is
+retained if present.
Example:
\code{urlparse('http://www.cwi.nl:80/\%7eguido/Python.html')}
yields the tuple
-\code{('http', 'www.cwi.nl:80', '/\%e7guido/Python.html', '', '', '')}.
+\code{('http', 'www.cwi.nl:80', '/\%7eguido/Python.html', '', '', '')}.
If the \var{default_scheme} argument is specified, it gives the
default addressing scheme, to be used only if the URL string does not
diff --git a/Doc/lib/libwww.tex b/Doc/lib/libwww.tex
index 9e09aa1..60dc62f 100644
--- a/Doc/lib/libwww.tex
+++ b/Doc/lib/libwww.tex
@@ -1,6 +1,7 @@
-\chapter{WORLD-WIDE WEB EXTENSIONS}
+\chapter{THE INTERNET AND THE WORLD-WIDE WEB}
\index{WWW}
-\indexii{World-Wide}{Web}
+\index{Internet}
+\index{World-Wide Web}
The modules described in this chapter provide various services to
World-Wide Web (WWW) clients and/or services, and a few modules
diff --git a/Doc/libaifc.tex b/Doc/libaifc.tex
index 7b4e4c8..7e595ef 100644
--- a/Doc/libaifc.tex
+++ b/Doc/libaifc.tex
@@ -21,8 +21,11 @@
Open an AIFF or AIFF-C file and return an object instance with
methods that are described below. The argument file is either a
string naming a file or a file object. The mode is either the string
-'r' when the file must be opened for reading, or 'w' when the file
-must be opened for writing.
+\code{'r'} when the file must be opened for reading, or \code{'w'}
+when the file must be opened for writing. When used for writing, the
+file object should be seekable, unless you know ahead of time how many
+samples you are going to write in total and use
+\code{writeframesraw()} and \code{setnframes()}.
\end{funcdesc}
Objects returned by \code{aifc.open()} when a file is opened for
diff --git a/Doc/libal.tex b/Doc/libal.tex
index 51a0312..6a812dd 100644
--- a/Doc/libal.tex
+++ b/Doc/libal.tex
@@ -1,13 +1,15 @@
\section{Built-in Module \sectcode{al}}
\bimodindex{al}
-This module provides access to the audio facilities of the Indigo and
-4D/35 workstations, described in section 3A of the IRIX 4.0 man pages
-(and also available as an option in IRIX 3.3). You'll need to read
-those man pages to understand what these functions do!
-Some of the functions are not available in releases below 4.0.5.
-Again, see the manual to check whether a specific function is
-available on your platform.
+This module provides access to the audio facilities of the SGI Indy
+and Indigo workstations. See section 3A of the IRIX man pages for
+details. You'll need to read those man pages to understand what these
+functions do! Some of the functions are not available in IRIX
+releases before 4.0.5. Again, see the manual to check whether a
+specific function is available on your platform.
+
+All functions and methods defined in this module are equivalent to
+the C functions with \samp{AL} prefixed to their name.
Symbolic constants from the C header file \file{<audio.h>} are defined
in the standard module \code{AL}, see below.
@@ -20,145 +22,138 @@
(One example is specifying an excessive queue size --- there is no
documented upper limit.)
-Module \code{al} defines the following functions:
+The module defines the following functions:
\renewcommand{\indexsubitem}{(in module al)}
+
\begin{funcdesc}{openport}{name\, direction\optional{\, config}}
-Equivalent to the C function ALopenport(). The name and direction
-arguments are strings. The optional config argument is an opaque
-configuration object as returned by \code{al.newconfig()}. The return
-value is an opaque port object; methods of port objects are described
-below.
+The name and direction arguments are strings. The optional config
+argument is a configuration object as returned by
+\code{al.newconfig()}. The return value is an \dfn{port object};
+methods of port objects are described below.
\end{funcdesc}
\begin{funcdesc}{newconfig}{}
-Equivalent to the C function ALnewconfig(). The return value is a new
-opaque configuration object; methods of configuration objects are
-described below.
+The return value is a new \dfn{configuration object}; methods of
+configuration objects are described below.
\end{funcdesc}
\begin{funcdesc}{queryparams}{device}
-Equivalent to the C function ALqueryparams(). The device argument is
-an integer. The return value is a list of integers containing the
-data returned by ALqueryparams().
+The device argument is an integer. The return value is a list of
+integers containing the data returned by ALqueryparams().
\end{funcdesc}
\begin{funcdesc}{getparams}{device\, list}
-Equivalent to the C function ALgetparams(). The device argument is an
-integer. The list argument is a list such as returned by
-\code{queryparams}; it is modified in place (!).
+The device argument is an integer. The list argument is a list such
+as returned by \code{queryparams}; it is modified in place (!).
\end{funcdesc}
\begin{funcdesc}{setparams}{device\, list}
-Equivalent to the C function ALsetparams(). The device argument is an
-integer.The list argument is a list such as returned by
-\code{al.queryparams}.
+The device argument is an integer. The list argument is a list such
+as returned by \code{al.queryparams}.
\end{funcdesc}
+\subsection{Configuration Objects}
+
Configuration objects (returned by \code{al.newconfig()} have the
following methods:
\renewcommand{\indexsubitem}{(audio configuration object method)}
+
\begin{funcdesc}{getqueuesize}{}
-Return the queue size; equivalent to the C function ALgetqueuesize().
+Return the queue size.
\end{funcdesc}
\begin{funcdesc}{setqueuesize}{size}
-Set the queue size; equivalent to the C function ALsetqueuesize().
+Set the queue size.
\end{funcdesc}
\begin{funcdesc}{getwidth}{}
-Get the sample width; equivalent to the C function ALgetwidth().
+Get the sample width.
\end{funcdesc}
-\begin{funcdesc}{getwidth}{width}
-Set the sample width; equivalent to the C function ALsetwidth().
+\begin{funcdesc}{setwidth}{width}
+Set the sample width.
\end{funcdesc}
\begin{funcdesc}{getchannels}{}
-Get the channel count; equivalent to the C function ALgetchannels().
+Get the channel count.
\end{funcdesc}
\begin{funcdesc}{setchannels}{nchannels}
-Set the channel count; equivalent to the C function ALsetchannels().
+Set the channel count.
\end{funcdesc}
\begin{funcdesc}{getsampfmt}{}
-Get the sample format; equivalent to the C function ALgetsampfmt().
+Get the sample format.
\end{funcdesc}
\begin{funcdesc}{setsampfmt}{sampfmt}
-Set the sample format; equivalent to the C function ALsetsampfmt().
+Set the sample format.
\end{funcdesc}
\begin{funcdesc}{getfloatmax}{}
-Get the maximum value for floating sample formats;
-equivalent to the C function ALgetfloatmax().
+Get the maximum value for floating sample formats.
\end{funcdesc}
\begin{funcdesc}{setfloatmax}{floatmax}
-Set the maximum value for floating sample formats;
-equivalent to the C function ALsetfloatmax().
+Set the maximum value for floating sample formats.
\end{funcdesc}
+\subsection{Port Objects}
+
Port objects (returned by \code{al.openport()} have the following
methods:
\renewcommand{\indexsubitem}{(audio port object method)}
+
\begin{funcdesc}{closeport}{}
-Close the port; equivalent to the C function ALcloseport().
+Close the port.
\end{funcdesc}
\begin{funcdesc}{getfd}{}
-Return the file descriptor as an int; equivalent to the C function
-ALgetfd().
+Return the file descriptor as an int.
\end{funcdesc}
\begin{funcdesc}{getfilled}{}
-Return the number of filled samples; equivalent to the C function
-ALgetfilled().
+Return the number of filled samples.
\end{funcdesc}
\begin{funcdesc}{getfillable}{}
-Return the number of fillable samples; equivalent to the C function
-ALgetfillable().
+Return the number of fillable samples.
\end{funcdesc}
\begin{funcdesc}{readsamps}{nsamples}
-Read a number of samples from the queue, blocking if necessary;
-equivalent to the C function ALreadsamples. The data is returned as a
-string containing the raw data (e.g. 2 bytes per sample in big-endian
-byte order (high byte, low byte) if you have set the sample width to 2
-bytes.
+Read a number of samples from the queue, blocking if necessary.
+Return the data as a string containing the raw data, (e.g., 2 bytes per
+sample in big-endian byte order (high byte, low byte) if you have set
+the sample width to 2 bytes).
\end{funcdesc}
\begin{funcdesc}{writesamps}{samples}
-Write samples into the queue, blocking if necessary; equivalent to the
-C function ALwritesamples. The samples are encoded as described for
-the \code{readsamps} return value.
+Write samples into the queue, blocking if necessary. The samples are
+encoded as described for the \code{readsamps} return value.
\end{funcdesc}
\begin{funcdesc}{getfillpoint}{}
-Return the `fill point'; equivalent to the C function ALgetfillpoint().
+Return the `fill point'.
\end{funcdesc}
\begin{funcdesc}{setfillpoint}{fillpoint}
-Set the `fill point'; equivalent to the C function ALsetfillpoint().
+Set the `fill point'.
\end{funcdesc}
\begin{funcdesc}{getconfig}{}
Return a configuration object containing the current configuration of
-the port; equivalent to the C function ALgetconfig().
+the port.
\end{funcdesc}
\begin{funcdesc}{setconfig}{config}
-Set the configuration from the argument, a configuration object;
-equivalent to the C function ALsetconfig().
+Set the configuration from the argument, a configuration object.
\end{funcdesc}
\begin{funcdesc}{getstatus}{list}
-Get status information on last error
-equivalent to C function ALgetstatus().
+Get status information on last error.
\end{funcdesc}
\section{Standard Module \sectcode{AL}}
diff --git a/Doc/libamoeba.tex b/Doc/libamoeba.tex
index db4fefd..1e31bc6 100644
--- a/Doc/libamoeba.tex
+++ b/Doc/libamoeba.tex
@@ -70,7 +70,7 @@
\subsection{Capability Operations}
-Capabilities are written in a convenient ASCII format, also used by the
+Capabilities are written in a convenient \ASCII{} format, also used by the
Amoeba utilities
{\it c2a}(U)
and
diff --git a/Doc/libarray.tex b/Doc/libarray.tex
index ea68fb1..9e37d55 100644
--- a/Doc/libarray.tex
+++ b/Doc/libarray.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{array}}
+\section{Built-in Module \sectcode{array}}
\bimodindex{array}
\index{arrays}
@@ -21,7 +21,7 @@
The actual representation of values is determined by the machine
architecture (strictly speaking, by the C implementation). The actual
-size can be accessed through the \var{typecode} attribute.
+size can be accessed through the \var{itemsize} attribute.
The module defines the following function:
@@ -59,7 +59,9 @@
Read \var{n} items (as machine values) from the file object \var{f}
and append them to the end of the array. If less than \var{n} items
are available, \code{EOFError} is raised, but the items that were
-available are still inserted into the array.
+available are still inserted into the array. \var{f} must be a real
+built-in file object; something else with a \code{read()} method won't
+do.
\end{funcdesc}
\begin{funcdesc}{fromlist}{list}
diff --git a/Doc/libaudioop.tex b/Doc/libaudioop.tex
index 03e074d..6a74a0b 100644
--- a/Doc/libaudioop.tex
+++ b/Doc/libaudioop.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{audioop}}
+\section{Built-in Module \sectcode{audioop}}
\bimodindex{audioop}
The \code{audioop} module contains some useful operations on sound fragments.
@@ -19,139 +19,139 @@
\end{excdesc}
\begin{funcdesc}{add}{fragment1\, fragment2\, width}
-This function returns a fragment which is the addition of the two samples
-passed as parameters. \var{width} is the sample width in bytes, either
-\code{1}, \code{2} or \code{4}. Both fragments should have the same length.
+Return a fragment which is the addition of the two samples passed as
+parameters. \var{width} is the sample width in bytes, either
+\code{1}, \code{2} or \code{4}. Both fragments should have the same
+length.
\end{funcdesc}
\begin{funcdesc}{adpcm2lin}{adpcmfragment\, width\, state}
-This routine decodes an Intel/DVI ADPCM coded fragment to a linear
-fragment. See the description of \code{lin2adpcm} for details on ADPCM
-coding. The routine returns a tuple
-\code{(\var{sample}, \var{newstate})}
-where the sample has the width specified in \var{width}.
+Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
+the description of \code{lin2adpcm} for details on ADPCM coding.
+Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
+has the width specified in \var{width}.
\end{funcdesc}
\begin{funcdesc}{adpcm32lin}{adpcmfragment\, width\, state}
-This routine decodes an alternative 3-bit ADPCM code. See
-\code{lin2adpcm3} for details.
+Decode an alternative 3-bit ADPCM code. See \code{lin2adpcm3} for
+details.
\end{funcdesc}
\begin{funcdesc}{avg}{fragment\, width}
-This function returns the average over all samples in the fragment.
+Return the average over all samples in the fragment.
\end{funcdesc}
\begin{funcdesc}{avgpp}{fragment\, width}
-This function returns the average peak-peak value over all samples in
-the fragment. No filtering is done, so the usefulness of this routine
-is questionable.
+Return the average peak-peak value over all samples in the fragment.
+No filtering is done, so the usefulness of this routine is
+questionable.
\end{funcdesc}
\begin{funcdesc}{bias}{fragment\, width\, bias}
-This function returns a fragment that is the original fragment with a
-bias added to each sample.
+Return a fragment that is the original fragment with a bias added to
+each sample.
\end{funcdesc}
\begin{funcdesc}{cross}{fragment\, width}
-This function returns the number of zero crossings in the fragment
-passed as an argument.
+Return the number of zero crossings in the fragment passed as an
+argument.
\end{funcdesc}
\begin{funcdesc}{findfactor}{fragment\, reference}
-This routine (which only accepts 2-byte sample fragments) calculates a
-factor \var{F} such that \code{rms(add(fragment, mul(reference, -F)))}
-is minimal, i.e.\ it calculates the factor with which you should
-multiply \var{reference} to make it match as well as possible to
-\var{fragment}. The fragments should be the same size.
+Return a factor \var{F} such that
+\code{rms(add(fragment, mul(reference, -F)))} is minimal, i.e.,
+return the factor with which you should multiply \var{reference} to
+make it match as well as possible to \var{fragment}. The fragments
+should both contain 2-byte samples.
The time taken by this routine is proportional to \code{len(fragment)}.
\end{funcdesc}
\begin{funcdesc}{findfit}{fragment\, reference}
-This routine (which only accepts 2-byte sample fragments) tries to
-match \var{reference} as well as possible to a portion of
-\var{fragment} (which should be the longer fragment). It
-(conceptually) does this by taking slices out of \var{fragment}, using
+This routine (which only accepts 2-byte sample fragments)
+
+Try to match \var{reference} as well as possible to a portion of
+\var{fragment} (which should be the longer fragment). This is
+(conceptually) done by taking slices out of \var{fragment}, using
\code{findfactor} to compute the best match, and minimizing the
-result.
-It returns a tuple \code{(\var{offset}, \var{factor})} with \var{offset} the
+result. The fragments should both contain 2-byte samples. Return a
+tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
(integer) offset into \var{fragment} where the optimal match started
-and \var{factor} the floating-point factor as per \code{findfactor}.
+and \var{factor} is the (floating-point) factor as per
+\code{findfactor}.
\end{funcdesc}
\begin{funcdesc}{findmax}{fragment\, length}
-This routine (which only accepts 2-byte sample fragments) searches
-\var{fragment} for a slice of length \var{length} samples (not bytes!)\
-with maximum energy, i.e.\ it returns \var{i} for which
-\code{rms(fragment[i*2:(i+length)*2])} is maximal.
+Search \var{fragment} for a slice of length \var{length} samples (not
+bytes!)\ with maximum energy, i.e., return \var{i} for which
+\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
+should both contain 2-byte samples.
The routine takes time proportional to \code{len(fragment)}.
\end{funcdesc}
\begin{funcdesc}{getsample}{fragment\, width\, index}
-This function returns the value of sample \var{index} from the
-fragment.
+Return the value of sample \var{index} from the fragment.
\end{funcdesc}
\begin{funcdesc}{lin2lin}{fragment\, width\, newwidth}
-This function converts samples between 1-, 2- and 4-byte formats.
+Convert samples between 1-, 2- and 4-byte formats.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm}{fragment\, width\, state}
-This function converts samples to 4 bit Intel/DVI ADPCM encoding.
-ADPCM coding is an adaptive coding scheme, whereby each 4 bit number
-is the difference between one sample and the next, divided by a
-(varying) step. The Intel/DVI ADPCM algorithm has been selected for
-use by the IMA, so it may well become a standard.
+Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an
+adaptive coding scheme, whereby each 4 bit number is the difference
+between one sample and the next, divided by a (varying) step. The
+Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
+may well become a standard.
-\code{State} is a tuple containing the state of the coder. The coder
+\code{State} is a tuple containing the state of the coder. The coder
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
\var{newstate} should be passed to the next call of lin2adpcm. In the
-initial call \code{None} can be passed as the state. \var{adpcmfrag} is
-the ADPCM coded fragment packed 2 4-bit values per byte.
+initial call \code{None} can be passed as the state. \var{adpcmfrag}
+is the ADPCM coded fragment packed 2 4-bit values per byte.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm3}{fragment\, width\, state}
This is an alternative ADPCM coder that uses only 3 bits per sample.
It is not compatible with the Intel/DVI ADPCM coder and its output is
-not packed (due to laziness on the side of the author). Its use is
+not packed (due to laziness on the side of the author). Its use is
discouraged.
\end{funcdesc}
\begin{funcdesc}{lin2ulaw}{fragment\, width}
-This function converts samples in the audio fragment to U-LAW encoding
-and returns this as a Python string. U-LAW is an audio encoding format
-whereby you get a dynamic range of about 14 bits using only 8 bit
-samples. It is used by the Sun audio hardware, among others.
+Convert samples in the audio fragment to U-LAW encoding and return
+this as a Python string. U-LAW is an audio encoding format whereby
+you get a dynamic range of about 14 bits using only 8 bit samples. It
+is used by the Sun audio hardware, among others.
\end{funcdesc}
\begin{funcdesc}{minmax}{fragment\, width}
-This function returns a tuple consisting of the minimum and maximum
-values of all samples in the sound fragment.
+Return a tuple consisting of the minimum and maximum values of all
+samples in the sound fragment.
\end{funcdesc}
\begin{funcdesc}{max}{fragment\, width}
-This function returns the maximum of the {\em absolute value} of all
-samples in a fragment.
+Return the maximum of the {\em absolute value} of all samples in a
+fragment.
\end{funcdesc}
\begin{funcdesc}{maxpp}{fragment\, width}
-This function returns the maximum peak-peak value in the sound fragment.
+Return the maximum peak-peak value in the sound fragment.
\end{funcdesc}
\begin{funcdesc}{mul}{fragment\, width\, factor}
Return a fragment that has all samples in the original framgent
-multiplied by the floating-point value \var{factor}. Overflow is
+multiplied by the floating-point value \var{factor}. Overflow is
silently ignored.
\end{funcdesc}
\begin{funcdesc}{reverse}{fragment\, width}
-This function reverses the samples in a fragment and returns the
-modified fragment.
+Reverse the samples in a fragment and returns the modified fragment.
\end{funcdesc}
-\begin{funcdesc}{rms}{fragment\, width\, factor}
-Returns the root-mean-square of the fragment, i.e.
+\begin{funcdesc}{rms}{fragment\, width}
+Return the root-mean-square of the fragment, i.e.
\iftexi
the square root of the quotient of the sum of all squared sample value,
divided by the sumber of samples.
@@ -166,22 +166,22 @@
\end{funcdesc}
\begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor}
-This function converts a stereo fragment to a mono fragment. The left
-channel is multiplied by \var{lfactor} and the right channel by
-\var{rfactor} before adding the two channels to give a mono signal.
+Convert a stereo fragment to a mono fragment. The left channel is
+multiplied by \var{lfactor} and the right channel by \var{rfactor}
+before adding the two channels to give a mono signal.
\end{funcdesc}
\begin{funcdesc}{tostereo}{fragment\, width\, lfactor\, rfactor}
-This function generates a stereo fragment from a mono fragment. Each
-pair of samples in the stereo fragment are computed from the mono
-sample, whereby left channel samples are multiplied by \var{lfactor}
-and right channel samples by \var{rfactor}.
+Generate a stereo fragment from a mono fragment. Each pair of samples
+in the stereo fragment are computed from the mono sample, whereby left
+channel samples are multiplied by \var{lfactor} and right channel
+samples by \var{rfactor}.
\end{funcdesc}
\begin{funcdesc}{ulaw2lin}{fragment\, width}
-This function converts sound fragments in ULAW encoding to linearly
-encoded sound fragments. ULAW encoding always uses 8 bits samples, so
-\var{width} refers only to the sample width of the output fragment here.
+Convert sound fragments in ULAW encoding to linearly encoded sound
+fragments. ULAW encoding always uses 8 bits samples, so \var{width}
+refers only to the sample width of the output fragment here.
\end{funcdesc}
Note that operations such as \code{mul} or \code{max} make no
@@ -202,20 +202,20 @@
If you use the ADPCM coder to build network packets and you want your
protocol to be stateless (i.e.\ to be able to tolerate packet loss)
-you should not only transmit the data but also the state. Note that
+you should not only transmit the data but also the state. Note that
you should send the \var{initial} state (the one you passed to
\code{lin2adpcm}) along to the decoder, not the final state (as returned by
-the coder). If you want to use \code{struct} to store the state in
+the coder). If you want to use \code{struct} to store the state in
binary you can code the first element (the predicted value) in 16 bits
and the second (the delta index) in 8.
The ADPCM coders have never been tried against other ADPCM coders,
-only against themselves. It could well be that I misinterpreted the
+only against themselves. It could well be that I misinterpreted the
standards in which case they will not be interoperable with the
respective standards.
The \code{find...} routines might look a bit funny at first sight.
-They are primarily meant for doing echo cancellation. A reasonably
+They are primarily meant to do echo cancellation. A reasonably
fast way to do this is to pick the most energetic piece of the output
sample, locate that in the input sample and subtract the whole output
sample from the input sample:
diff --git a/Doc/libbltin.tex b/Doc/libbltin.tex
index 04cea20..63b7c63 100644
--- a/Doc/libbltin.tex
+++ b/Doc/libbltin.tex
@@ -1,6 +1,7 @@
\section{Built-in Module \sectcode{__builtin__}}
\bimodindex{__builtin__}
-This module provides direct access to all `built-in' identifier of
+This module provides direct access to all `built-in' identifiers of
Python; e.g. \code{__builtin__.open} is the full name for the built-in
-function \code{open}.
+function \code{open}. See the section on Built-in Functions in the
+previous chapter.
diff --git a/Doc/libcgi.tex b/Doc/libcgi.tex
index 082a2a1..1950895 100644
--- a/Doc/libcgi.tex
+++ b/Doc/libcgi.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{cgi}}
+\section{Standard Module \sectcode{cgi}}
\stmodindex{cgi}
\indexii{WWW}{server}
\indexii{CGI}{protocol}
@@ -134,3 +134,85 @@
The shell environment, exactly as received from the http server. See
the CGI documentation for a description of the various fields.
\end{datadesc}
+
+\subsection{Example}
+
+This example assumes that you have a WWW server up and running,
+e.g.\ NCSA's \code{httpd}.
+
+Place the following file in a convenient spot in the WWW server's
+directory tree. E.g., if you place it in the subdirectory \file{test}
+of the root directory and call it \file{test.html}, its URL will be
+\file{http://\var{yourservername}/test/test.html}.
+
+\begin{verbatim}
+<TITLE>Test Form Input</TITLE>
+<H1>Test Form Input</H1>
+<FORM METHOD="POST" ACTION="/cgi-bin/test.py">
+<INPUT NAME=Name> (Name)<br>
+<INPUT NAME=Address> (Address)<br>
+<INPUT TYPE=SUBMIT>
+</FORM>
+\end{verbatim}
+
+Selecting this file's URL from a forms-capable browser such as Mosaic
+or Netscape will bring up a simple form with two text input fields and
+a ``submit'' button.
+
+But wait. Before pressing ``submit'', a script that responds to the
+form must also be installed. The test file as shown assumes that the
+script is called \file{test.py} and lives in the server's
+\code{cgi-bin} directory. Here's the test script:
+
+\begin{verbatim}
+#!/usr/local/bin/python
+
+import cgi
+
+print "Content-type: text/html"
+print # End of headers!
+print "<TITLE>Test Form Output</TITLE>"
+print "<H1>Test Form Output</H1>"
+
+form = cgi.SvFormContentDict() # Load the form
+
+name = addr = None # Default: no name and address
+
+# Extract name and address from the form, if given
+
+if form.has_key('Name'):
+ name = form['Name']
+if form.has_key('Address'):
+ addr = form['Address']
+
+# Print an unnumbered list of the name and address, if present
+
+print "<UL>"
+if name is not None:
+ print "<LI>Name:", cgi.escape(name)
+if addr is not None:
+ print "<LI>Address:", cgi.escape(addr)
+print "</UL>"
+\end{verbatim}
+
+The script should be made executable (\samp{chmod +x \var{script}}).
+If the Python interpreter is not located at
+\file{/usr/local/bin/python} but somewhere else, the first line of the
+script should be modified accordingly.
+
+Now that everything is installed correctly, we can try out the form.
+Bring up the test form in your WWW browser, fill in a name and address
+in the form, and press the ``submit'' button. The script should now
+run and its output is sent back to your browser. This should roughly
+look as follows:
+
+\strong{Test Form Output}
+
+\begin{itemize}
+\item Name: \var{the name you entered}
+\item Address: \var{the address you entered}
+\end{itemize}
+
+If you didn't enter a name or address, the corresponding line will be
+missing (since the browser doesn't send empty form fields to the
+server).
diff --git a/Doc/libcopy.tex b/Doc/libcopy.tex
index c141e05..4c0ce72 100644
--- a/Doc/libcopy.tex
+++ b/Doc/libcopy.tex
@@ -1,5 +1,6 @@
-\section{Built-in module \sectcode{copy}}
+\section{Standard Module \sectcode{copy}}
\stmodindex{copy}
+\renewcommand{\indexsubitem}{(copy function)}
\ttindex{copy}
\ttindex{deepcopy}
@@ -14,7 +15,7 @@
x = copy.deepcopy(y) # make a deep copy of y
\end{verbatim}
-For module specific errors, \code{copy.Error} is raised.
+For module specific errors, \code{copy.error} is raised.
The difference between shallow and deep copying is only relevant for
compound objects (objects that contain other objects, like lists or
@@ -74,6 +75,7 @@
\code{__setstate__()}. See the description of module \code{pickle}
for information on these methods.
\stmodindex{pickle}
+\renewcommand{\indexsubitem}{(copy protocol)}
\ttindex{__getinitargs__}
\ttindex{__getstate__}
\ttindex{__setstate__}
diff --git a/Doc/libcrypto.tex b/Doc/libcrypto.tex
index 302b50d..972106c 100644
--- a/Doc/libcrypto.tex
+++ b/Doc/libcrypto.tex
@@ -5,8 +5,13 @@
installation.
\index{cryptography}
-%Hardcore cypherpunks will probably find the Python Cryptography Kit of
-%further interest; the package adds built-in modules for DES and IDEA
-%encryption, and provides a Python module for reading and decrypting PGP files.
-%\index{PGP}\indexii{DES}{cipher}\indexii{IDEA}{cipher}
-%\index{Python Cryptography Kit}
+Hardcore cypherpunks will probably find the Python Cryptography Kit of
+further interest; the package adds built-in modules for DES and IDEA
+encryption, and provides a Python module for reading and decrypting
+PGP files. The Python Cryptography Kit is not distributed with Python
+but available separately. See the URL
+\file{http://www.cs.mcgill.ca/\%7Efnord/crypt.html} for more information.
+\index{PGP}
+\indexii{DES}{cipher}
+\indexii{IDEA}{cipher}
+\index{Python Cryptography Kit}
diff --git a/Doc/libctb.tex b/Doc/libctb.tex
index 3928498..1cda336 100644
--- a/Doc/libctb.tex
+++ b/Doc/libctb.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{ctb}}
+\section{Built-in Module \sectcode{ctb}}
\bimodindex{ctb}
\renewcommand{\indexsubitem}{(in module ctb)}
@@ -44,7 +44,7 @@
For all connection methods that take a \var{timeout} argument, a value
of \code{-1} is indefinite, meaning that the command runs to completion.
-\renewcommand{\indexsubitem}{(connection object method)}
+\renewcommand{\indexsubitem}{(connection object attribute)}
\begin{datadesc}{callback}
If this member is set to a value other than \code{None} it should point
@@ -59,6 +59,8 @@
\end{datadesc}
+\renewcommand{\indexsubitem}{(connection object method)}
+
\begin{funcdesc}{Open}{timeout}
Open an outgoing connection, waiting at most \var{timeout} seconds for
the connection to be established.
diff --git a/Doc/libexcs.tex b/Doc/libexcs.tex
index 33083cd..7cc9195 100644
--- a/Doc/libexcs.tex
+++ b/Doc/libexcs.tex
@@ -24,7 +24,7 @@
\begin{excdesc}{AttributeError}
% xref to attribute reference?
Raised when an attribute reference or assignment fails. (When an
- object does not support attributes references or attribute assignments
+ object does not support attribute references or attribute assignments
at all, \code{TypeError} is raised.)
\end{excdesc}
diff --git a/Doc/libfcntl.tex b/Doc/libfcntl.tex
index 46b41a5..147fb8c 100644
--- a/Doc/libfcntl.tex
+++ b/Doc/libfcntl.tex
@@ -1,5 +1,5 @@
% Manual text by Jaap Vermeulen
-\section{Built-in module \sectcode{fcntl}}
+\section{Built-in Module \sectcode{fcntl}}
\bimodindex{fcntl}
\indexii{\UNIX{}}{file control}
\indexii{\UNIX{}}{I/O control}
diff --git a/Doc/libfl.tex b/Doc/libfl.tex
index 5af1a04..47f10c7 100644
--- a/Doc/libfl.tex
+++ b/Doc/libfl.tex
@@ -2,17 +2,18 @@
\bimodindex{fl}
This module provides an interface to the FORMS Library by Mark
-Overmars, version 2.0b. For more info about FORMS, write to
-{\tt markov@cs.ruu.nl}.
+Overmars. The source for the library can be retrieved by anonymous
+ftp from host \samp{ftp.cs.ruu.nl}, directory \file{SGI/FORMS}. It
+was last tested with version 2.0b.
Most functions are literal translations of their C equivalents,
-dropping the initial \samp{fl_} from their name. Constants used by the
-library are defined in module \code{FL} described below.
+dropping the initial \samp{fl_} from their name. Constants used by
+the library are defined in module \code{FL} described below.
The creation of objects is a little different in Python than in C:
instead of the `current form' maintained by the library to which new
FORMS objects are added, all functions that add a FORMS object to a
-button are methods of the Python object representing the form.
+form are methods of the Python object representing the form.
Consequently, there are no Python equivalents for the C functions
\code{fl_addto_form} and \code{fl_end_form}, and the equivalent of
\code{fl_bgn_form} is called \code{fl.make_form}.
@@ -26,13 +27,13 @@
There are no `free objects' in the Python interface to FORMS, nor is
there an easy way to add object classes written in Python. The FORMS
-interface to GL event handling is avaiable, though, so you can mix
+interface to GL event handling is available, though, so you can mix
FORMS with pure GL windows.
\strong{Please note:} importing \code{fl} implies a call to the GL function
\code{foreground()} and to the FORMS routine \code{fl_init()}.
-\subsection{Functions defined in module \sectcode{fl}}
+\subsection{Functions Defined in Module \sectcode{fl}}
Module \code{fl} defines the following functions. For more information
about what they do, see the description of the equivalent C function
@@ -92,7 +93,7 @@
\end{funcdesc}
\begin{funcdesc}{show_file_selector}{message\, directory\, pattern\, default}
-Show a dialog box inm which the user can select a file. It returns
+Show a dialog box in which the user can select a file. It returns
the absolute filename selected by the user, or \code{None} if the user
presses Cancel.
\end{funcdesc}
@@ -130,7 +131,7 @@
\code{fl_mapcolor} and \code{fl_getmcolor}.
\end{funcdesc}
-\subsection{Form object methods and data attributes}
+\subsection{Form Objects}
Form objects (returned by \code{fl.make_form()} above) have the
following methods. Each method corresponds to a C function whose name
@@ -382,7 +383,7 @@
\lineiii{doublebuf}{int}{nonzero if double buffering on}
\end{tableiii}
-\subsection{FORMS object methods and data attributes}
+\subsection{FORMS Objects}
Besides methods specific to particular kinds of FORMS objects, all
FORMS objects also have the following methods:
diff --git a/Doc/libftplib.tex b/Doc/libftplib.tex
index acd8784..f5f7ef3 100644
--- a/Doc/libftplib.tex
+++ b/Doc/libftplib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{ftplib}}
+\section{Standard Module \sectcode{ftplib}}
\stmodindex{ftplib}
\renewcommand{\indexsubitem}{(in module ftplib)}
diff --git a/Doc/libfuncs.tex b/Doc/libfuncs.tex
index 0eb6857..4778c7d 100644
--- a/Doc/libfuncs.tex
+++ b/Doc/libfuncs.tex
@@ -92,8 +92,8 @@
\var{expression} argument is parsed and evaluated as a Python
expression (technically speaking, a condition list) using the
\var{globals} and \var{locals} dictionaries as global and local name
- space. If the \var{globals} dictionary is omitted it defaults to
- the \var{locals} dictionary. If both dictionaries are omitted, the
+ space. If the \var{locals} dictionary is omitted it defaults to
+ the \var{globals} dictionary. If both dictionaries are omitted, the
expression is executed in the environment where \code{eval} is
called. The return value is the result of the evaluated expression.
Syntax errors are reported as exceptions. Example:
@@ -119,20 +119,21 @@
\end{funcdesc}
\begin{funcdesc}{execfile}{file\optional{\, globals\optional{\, locals}}}
- This function is similar to the \code{eval()} function or the
+ This function is similar to the
\code{exec} statement, but parses a file instead of a string. It is
different from the \code{import} statement in that it does not use
the module administration --- it reads the file unconditionally and
- does not create a new module.
+ does not create a new module.\footnote{It is used relatively rarely
+ so does not warrant being made into a statement.}
The arguments are a file name and two optional dictionaries. The
file is parsed and evaluated as a sequence of Python statements
(similarly to a module) using the \var{globals} and \var{locals}
- dictionaries as global and local name space. If the \var{globals}
- dictionary is omitted it defaults to the \var{locals} dictionary.
+ dictionaries as global and local name space. If the \var{locals}
+ dictionary is omitted it defaults to the \var{globals} dictionary.
If both dictionaries are omitted, the expression is executed in the
- environment where \code{execfile} is called. The return value is
- None.
+ environment where \code{execfile()} is called. The return value is
+ \code{None}.
\end{funcdesc}
\begin{funcdesc}{filter}{function\, list}
@@ -173,8 +174,8 @@
\end{funcdesc}
\begin{funcdesc}{hex}{x}
- Convert a number to a hexadecimal string. The result is a valid
- Python expression.
+ Convert an integer number (of any size) to a hexadecimal string.
+ The result is a valid Python expression.
\end{funcdesc}
\begin{funcdesc}{id}{object}
@@ -194,7 +195,9 @@
\begin{funcdesc}{int}{x}
Convert a number to a plain integer. The argument may be a plain or
- long integer or a floating point number.
+ long integer or a floating point number. Conversion of floating
+ point numbers to integers is defined by the C semantics; normally
+ the conversion truncates towards zero.
\end{funcdesc}
\begin{funcdesc}{len}{s}
@@ -231,8 +234,8 @@
\end{funcdesc}
\begin{funcdesc}{oct}{x}
- Convert a number to an octal string. The result is a valid Python
- expression.
+ Convert an integer number (of any size) to an octal string. The
+ result is a valid Python expression.
\end{funcdesc}
\begin{funcdesc}{open}{filename\optional{\, mode\optional{\, bufsize}}}
@@ -290,7 +293,8 @@
the last element is the largest \code{\var{start} + \var{i} *
\var{step}} less than \var{end}; if \var{step} is negative, the last
element is the largest \code{\var{start} + \var{i} * \var{step}}
- greater than \var{end}. \var{step} must not be zero. Example:
+ greater than \var{end}. \var{step} must not be zero (or else an
+ exception is raised). Example:
\bcode\begin{verbatim}
>>> range(10)
@@ -321,7 +325,7 @@
>>> s = raw_input('--> ')
--> Monty Python's Flying Circus
>>> s
-'Monty Python\'s Flying Circus'
+"Monty Python's Flying Circus"
>>>
\end{verbatim}\ecode
\end{funcdesc}
@@ -337,17 +341,48 @@
\end{funcdesc}
\begin{funcdesc}{reload}{module}
- Re-parse and re-initialize an already imported \var{module}. The
- argument must be a module object, so it must have been successfully
- imported before. This is useful if you have edited the module source
- file using an external editor and want to try out the new version
- without leaving the Python interpreter. Note that if a module is
- syntactically correct but its initialization fails, the first
- \code{import} statement for it does not import the name, but does
- create a (partially initialized) module object; to reload the module
- you must first \code{import} it again (this will just make the
- partially initialized module object available) before you can
- \code{reload()} it.
+Re-parse and re-initialize an already imported \var{module}. The
+argument must be a module object, so it must have been successfully
+imported before. This is useful if you have edited the module source
+file using an external editor and want to try out the new version
+without leaving the Python interpreter. The return value is the
+module object (i.e.\ the same as the \var{module} argument).
+
+There are a number of caveats:
+
+If a module is syntactically correct but its initialization fails, the
+first \code{import} statement for it does not bind its name locally,
+but does store a (partially initialized) module object in
+\code{sys.modules}. To reload the module you must first
+\code{import} it again (this will bind the name to the partially
+initialized module object) before you can \code{reload()} it.
+
+When a module is reloaded, its dictionary (containing the module's
+global variables) is retained. Redefinitions of names will override
+the old definitions, so this is generally not a problem. If the new
+version of a module does not define a name that was defined by the old
+version, the old definition remains. This feature can be used to the
+module's advantage if it maintains a global table or cache of objects
+--- with a \code{try} statement it can test for the table's presence
+and skip its initialization if desired.
+
+It is legal though generally not very useful to reload built-in or
+dynamically loaded modules, except for \code{sys}, \code{__main__} and
+\code{__builtin__}. In certain cases, however, extension modules are
+not designed to be initialized more than once, and may fail in
+arbitrary ways when reloaded.
+
+If a module imports objects from another module using \code{from}
+{\ldots} \code{import} {\ldots}, calling \code{reload()} for the other
+module does not redefine the objects imported from it --- one way
+around this is to re-execute the \code{from} statement, another is to
+use \code{import} and qualified names (\var{module}.\var{name})
+instead.
+
+If a module instantiates instances of a class, reloading the module
+that defines the class does not affect the method definitions of the
+instances --- they continue to use the old class definition. The same
+is true for derived classes.
\end{funcdesc}
\begin{funcdesc}{repr}{object}
@@ -385,23 +420,25 @@
its goal is to return a printable string.
\end{funcdesc}
-\begin{funcdesc}{tuple}{object}
+\begin{funcdesc}{tuple}{sequence}
Return a tuple whose items are the same and in the same order as
-\var{object}'s items. If \var{object} is alread a tuple, it
+\var{sequence}'s items. If \var{sequence} is alread a tuple, it
is returned unchanged. For instance, \code{tuple('abc')} returns
returns \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns
\code{(1, 2, 3)}.
\end{funcdesc}
\begin{funcdesc}{type}{object}
-% XXXJH xref to buil-in objects here?
- Return the type of an \var{object}. The return value is a type
- object. There is not much you can do with type objects except compare
- them to other type objects; e.g., the following checks if a variable
- is a string:
+Return the type of an \var{object}. The return value is a type
+object. The standard module \code{types} defines names for all
+built-in types.
+\stmodindex{types}
+\obindex{type}
+For instance:
\bcode\begin{verbatim}
->>> if type(x) == type(''): print 'It is a string'
+>>> import types
+>>> if type(x) == types.StringType: print "It's a string"
\end{verbatim}\ecode
\end{funcdesc}
@@ -424,7 +461,7 @@
actually storing them all simultaneously. The advantage of
\code{xrange()} over \code{range()} is minimal (since \code{xrange()}
still has to create the values when asked for them) except when a very
-large range is used on a memory-starved machine (e.g. DOS) or when all
+large range is used on a memory-starved machine (e.g. MS-DOS) or when all
of the range's elements are never used (e.g. when the loop is usually
terminated with \code{break}).
\end{funcdesc}
diff --git a/Doc/libgetopt.tex b/Doc/libgetopt.tex
index 250d31f..3f9592a 100644
--- a/Doc/libgetopt.tex
+++ b/Doc/libgetopt.tex
@@ -5,7 +5,8 @@
\code{sys.argv}.
It uses the same conventions as the \UNIX{}
\code{getopt()}
-function.
+function (including the special meanings of arguments of the form
+\samp{-} and \samp{--}).
It defines the function
\code{getopt.getopt(args, options)}
and the exception
diff --git a/Doc/libgopherlib.tex b/Doc/libgopherlib.tex
index 904a64b..eb50fdd 100644
--- a/Doc/libgopherlib.tex
+++ b/Doc/libgopherlib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{gopherlib}}
+\section{Standard Module \sectcode{gopherlib}}
\stmodindex{gopherlib}
\renewcommand{\indexsubitem}{(in module gopherlib)}
diff --git a/Doc/libgrp.tex b/Doc/libgrp.tex
index 6310498..90a2ed3 100644
--- a/Doc/libgrp.tex
+++ b/Doc/libgrp.tex
@@ -13,7 +13,7 @@
The gid is an integer, name and password are strings, and the member
list is a list of strings.
(Note that most users are not explicitly listed as members of the
-group(s) they are in.)
+group they are in according to the password database.)
An exception is raised if the entry asked for cannot be found.
It defines the following items:
diff --git a/Doc/libhtmllib.tex b/Doc/libhtmllib.tex
index 8882246..aeb4ce9 100644
--- a/Doc/libhtmllib.tex
+++ b/Doc/libhtmllib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{htmllib}}
+\section{Standard Module \sectcode{htmllib}}
\stmodindex{htmllib}
\index{HTML}
\index{hypertext}
@@ -27,12 +27,14 @@
\item
The interface to feed data to an instance is through the \code{feed()}
method, which takes a string argument. This can be called with as
-little or as much text at a time as desired. When the data contains complete
+little or as much text at a time as desired;
+\code{p.feed(a); p.feed(b)} has the same effect as \code{p.feed(a+b)}.
+When the data contains complete
HTML elements, these are processed immediately; incomplete elements
are saved in a buffer. To force processing of all unprocessed data,
call the \code{close()} method.
-Example: to parse the entire contents of a file, do
+Example: to parse the entire contents of a file, do\\
\code{parser.feed(open(file).read()); parser.close()}.
\item
@@ -142,7 +144,7 @@
\index{style sheet}
\begin{datadesc}{NullStylesheet}
-A style sheet for use on a dumb output device such as an ASCII
+A style sheet for use on a dumb output device such as an \ASCII{}
terminal.
\end{datadesc}
@@ -242,9 +244,9 @@
\end{funcdesc}
\begin{datadesc}{nospace}
-If this instance variable is true, empty words are ignored by
-\code{addword}. It is set to false after a non-empty word has been
-added.
+If this instance variable is true, empty words should be ignored by
+\code{addword}. It should be set to false after a non-empty word has
+been added.
\end{datadesc}
\begin{funcdesc}{setjust}{justification}
diff --git a/Doc/libhttplib.tex b/Doc/libhttplib.tex
index 0d7ac4f..46d791b 100644
--- a/Doc/libhttplib.tex
+++ b/Doc/libhttplib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{httplib}}
+\section{Standard Module \sectcode{httplib}}
\stmodindex{httplib}
\index{HTTP}
@@ -15,7 +15,15 @@
number is passed, the port is extracted from the host string if it has
the form \code{host:port}, else the default HTTP port (80) is used.
If no host is passed, no connection is made, and the \code{connect}
-method should be used to connect to a server.
+method should be used to connect to a server. For example, the
+following calls all create instances that connect to the server at the
+same host and port:
+
+\begin{verbatim}
+>>> h1 = httplib.HTTP('www.cwi.nl')
+>>> h2 = httplib.HTTP('www.cwi.nl:80')
+>>> h3 = httplib.HTTP('www.cwi.nl', 80)
+\end{verbatim}
Once an \code{HTTP} instance has been connected to an HTTP server, it
should be used as follows:
@@ -27,7 +35,7 @@
\item[2.] Make zero or more calls to the \code{putheader()} method.
\item[3.] Call the \code{endheaders()} method (this can be omitted if
-step 4. makes no calls).
+step 4 makes no calls).
\item[4.] Optional calls to the \code{send()} method.
@@ -93,3 +101,22 @@
read, using the \code{read()}, \code{readline()} or \code{readlines()}
methods.
\end{funcdesc}
+
+\subsection{Example}
+
+Here is an example session:
+
+\begin{verbatim}
+>>> import httplib
+>>> h = httplib.HTTP('www.cwi.nl')
+>>> h.putrequest('GET', '/index.html')
+>>> h.putheader('Accept', 'text/html')
+>>> h.putheader('Accept', 'text/plain')
+>>> h.endheaders()
+>>> errcode, errmsg, headers = h.getreply()
+>>> print errcode # Should be 200
+>>> f = h.getfile()
+>>> data f.read() # Get the raw HTML
+>>> f.close()
+>>>
+\end{verbatim}
diff --git a/Doc/libimageop.tex b/Doc/libimageop.tex
index 836ae76..4e15117 100644
--- a/Doc/libimageop.tex
+++ b/Doc/libimageop.tex
@@ -1,9 +1,9 @@
-\section{Built-in module \sectcode{imageop}}
+\section{Built-in Module \sectcode{imageop}}
\bimodindex{imageop}
The \code{imageop} module contains some useful operations on images.
It operates on images consisting of 8 or 32 bit pixels
-stored in Python strings. This is the same format as used
+stored in Python strings. This is the same format as used
by \code{gl.lrectwrite} and the \code{imgfile} module.
The module defines the following variables and functions:
@@ -17,49 +17,48 @@
\begin{funcdesc}{crop}{image\, psize\, width\, height\, x0\, y0\, x1\, y1}
-This function takes the image in \var{image}, which should by
+Return the selected part of \var{image}, which should by
\var{width} by \var{height} in size and consist of pixels of
-\var{psize} bytes, and returns the selected part of that image. \var{x0},
-\var{y0}, \var{x1} and \var{y1} are like the \code{lrectread}
-parameters, i.e. the boundary is included in the new image.
-The new boundaries need not be inside the picture. Pixels that fall
-outside the old image will have their value set to zero.
-If \var{x0} is bigger than \var{x1} the new image is mirrored. The
-same holds for the y coordinates.
+\var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like
+the \code{lrectread} parameters, i.e.\ the boundary is included in the
+new image. The new boundaries need not be inside the picture. Pixels
+that fall outside the old image will have their value set to zero. If
+\var{x0} is bigger than \var{x1} the new image is mirrored. The same
+holds for the y coordinates.
\end{funcdesc}
\begin{funcdesc}{scale}{image\, psize\, width\, height\, newwidth\, newheight}
-This function returns an \var{image} scaled to size \var{newwidth} by
-\var{newheight}. No interpolation is done, scaling is done by
-simple-minded pixel duplication or removal. Therefore, computer-generated
-images or dithered images will not look nice after scaling.
+Return \var{image} scaled to size \var{newwidth} by \var{newheight}.
+No interpolation is done, scaling is done by simple-minded pixel
+duplication or removal. Therefore, computer-generated images or
+dithered images will not look nice after scaling.
\end{funcdesc}
\begin{funcdesc}{tovideo}{image\, psize\, width\, height}
-This function runs a vertical low-pass filter over an image. It does
-so by computing each destination pixel as the average of two
-vertically-aligned source pixels. The main use of this routine is to
-forestall excessive flicker if the image is displayed on a video
-device that uses interlacing, hence the name.
+Run a vertical low-pass filter over an image. It does so by computing
+each destination pixel as the average of two vertically-aligned source
+pixels. The main use of this routine is to forestall excessive
+flicker if the image is displayed on a video device that uses
+interlacing, hence the name.
\end{funcdesc}
\begin{funcdesc}{grey2mono}{image\, width\, height\, threshold}
-This function converts a 8-bit deep greyscale image to a 1-bit deep
-image by tresholding all the pixels. The resulting image is tightly
-packed and is probably only useful as an argument to \code{mono2grey}.
+Convert a 8-bit deep greyscale image to a 1-bit deep image by
+tresholding all the pixels. The resulting image is tightly packed and
+is probably only useful as an argument to \code{mono2grey}.
\end{funcdesc}
\begin{funcdesc}{dither2mono}{image\, width\, height}
-This function also converts an 8-bit greyscale image to a 1-bit
-monochrome image but it uses a (simple-minded) dithering algorithm.
+Convert an 8-bit greyscale image to a 1-bit monochrome image using a
+(simple-minded) dithering algorithm.
\end{funcdesc}
\begin{funcdesc}{mono2grey}{image\, width\, height\, p0\, p1}
-This function converts a 1-bit monochrome image to an 8 bit greyscale
-or color image. All pixels that are zero-valued on input get value
-\var{p0} on output and all one-value input pixels get value \var{p1}
-on output. To convert a monochrome black-and-white image to greyscale
-pass the values \code{0} and \code{255} respectively.
+Convert a 1-bit monochrome image to an 8 bit greyscale or color image.
+All pixels that are zero-valued on input get value \var{p0} on output
+and all one-value input pixels get value \var{p1} on output. To
+convert a monochrome black-and-white image to greyscale pass the
+values \code{0} and \code{255} respectively.
\end{funcdesc}
\begin{funcdesc}{grey2grey4}{image\, width\, height}
@@ -74,7 +73,7 @@
\begin{funcdesc}{dither2grey2}{image\, width\, height}
Convert an 8-bit greyscale image to a 2-bit greyscale image with
-dithering. As for \code{dither2mono}, the dithering algorithm is
+dithering. As for \code{dither2mono}, the dithering algorithm is
currently very simple.
\end{funcdesc}
diff --git a/Doc/libimgfile.tex b/Doc/libimgfile.tex
index 2da8d9d..1e8b2aa 100644
--- a/Doc/libimgfile.tex
+++ b/Doc/libimgfile.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{imgfile}}
+\section{Built-in Module \sectcode{imgfile}}
\bimodindex{imgfile}
The imgfile module allows python programs to access SGI imglib image
diff --git a/Doc/libimp.tex b/Doc/libimp.tex
index 9ead176..91e250b 100644
--- a/Doc/libimp.tex
+++ b/Doc/libimp.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{imp}}
+\section{Built-in Module \sectcode{imp}}
\bimodindex{imp}
\index{import}
@@ -9,7 +9,7 @@
\renewcommand{\indexsubitem}{(in module struct)}
\begin{funcdesc}{get_magic}{}
-Return the magic string used to recognize value byte-compiled code
+Return the magic string value used to recognize byte-compiled code
files (``\code{.pyc} files'').
\end{funcdesc}
@@ -22,15 +22,15 @@
(this can be \code{'r'} for text files or \code{'rb'} for binary
files), and \var{type} is the file type, which has one of the values
\code{PY_SOURCE}, \code{PY_COMPILED} or \code{C_EXTENSION}, defined
-below.
+below. (System-dependent values may also be returned.)
\end{funcdesc}
\begin{funcdesc}{find_module}{name\, \optional{path}}
Try to find the module \var{name} on the search path \var{path}. The
default \var{path} is \code{sys.path}. The return value is a triple
\code{(\var{file}, \var{pathname}, \var{description})} where
-\var{file} is an open file object positioned at the beginning
-corresponding to the file found, \var{pathname} is the pathname of the
+\var{file} is an open file object positioned at the beginning,
+\var{pathname} is the pathname of the
file found, and \var{description} is a triple as contained in the list
returned by \code{get_suffixes} describing the kind of file found.
\end{funcdesc}
@@ -134,33 +134,27 @@
\begin{verbatim}
import imp
-from sys import modules
+import sys
def __import__(name, globals=None, locals=None, fromlist=None):
- # Fast path: let's see if it's already in sys.modules.
- # Two speed optimizations are worth mentioning:
- # - We use 'modules' instead of 'sys.modules'; this saves a
- # dictionary look-up per call.
- # - It's also faster to use a try-except statement than
- # to use modules.has_key(name) to check if it's there.
- try:
- return modules[name]
- except KeyError:
- pass
+ # Fast path: see if the module has already been imported.
+ if sys.modules.has_key(name):
+ return sys.modules[name]
- # See if it's a built-in module
+ # If any of the following calls raises an exception,
+ # there's a problem we con't handle -- let the caller handle it.
+
+ # See if it's a built-in module.
m = imp.init_builtin(name)
if m:
return m
- # See if it's a frozen module
+ # See if it's a frozen module.
m = imp.init_frozen(name)
if m:
return m
# Search the default path (i.e. sys.path).
- # If this raises an exception, the module is not found --
- # let the caller handle the exception.
fp, pathname, (suffix, mode, type) = imp.find_module(name)
# See what we got.
@@ -170,7 +164,7 @@
if type == imp.PY_SOURCE:
return imp.load_source(name, pathname, fp)
if type == imp.PY_COMPILED:
- return imp.load_source(name, pathname, fp)
+ return imp.load_compiled(name, pathname, fp)
# Shouldn't get here at all.
raise ImportError, '%s: unknown module type (%d)' % (name, type)
diff --git a/Doc/libmac.tex b/Doc/libmac.tex
index 62babda..545b62c 100644
--- a/Doc/libmac.tex
+++ b/Doc/libmac.tex
@@ -2,7 +2,7 @@
The modules in this chapter are available on the Apple Macintosh only.
-\section{Built-in module \sectcode{mac}}
+\section{Built-in Module \sectcode{mac}}
\bimodindex{mac}
This module provides a subset of the operating system dependent
@@ -22,7 +22,7 @@
\code{unlink},
as well as the exception \code{error}.
-\section{Standard module \sectcode{macpath}}
+\section{Standard Module \sectcode{macpath}}
\stmodindex{macpath}
This module provides a subset of the pathname manipulation functions
diff --git a/Doc/libmacconsole.tex b/Doc/libmacconsole.tex
index 2f60890..42d4e51 100644
--- a/Doc/libmacconsole.tex
+++ b/Doc/libmacconsole.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macconsole}}
+\section{Built-in Module \sectcode{macconsole}}
\bimodindex{macconsole}
\renewcommand{\indexsubitem}{(in module macconsole)}
@@ -62,7 +62,7 @@
\subsection{console window object}
-\renewcommand{\indexsubitem}{(console window method)}
+\renewcommand{\indexsubitem}{(console window attribute)}
\begin{datadesc}{file}
The file object corresponding to this console window. If the file is
@@ -70,6 +70,8 @@
and \code{read()} calls.
\end{datadesc}
+\renewcommand{\indexsubitem}{(console window method)}
+
\begin{funcdesc}{setmode}{mode}
Set the input mode of the console to \var{C_ECHO}, etc.
\end{funcdesc}
diff --git a/Doc/libmacdnr.tex b/Doc/libmacdnr.tex
index ca75971..cd3625c 100644
--- a/Doc/libmacdnr.tex
+++ b/Doc/libmacdnr.tex
@@ -1,5 +1,5 @@
-\section{Built-in module \sectcode{macdnr}}
+\section{Built-in Module \sectcode{macdnr}}
\bimodindex{macdnr}
This module provides an interface to the Macintosh Domain Name
@@ -75,6 +75,8 @@
Return 1 if the query is complete.
\end{funcdesc}
+\renewcommand{\indexsubitem}{(dnr result object attribute)}
+
\begin{datadesc}{rtnCode}
The error code returned by the query.
\end{datadesc}
diff --git a/Doc/libmacfs.tex b/Doc/libmacfs.tex
index 80ec76d..74d1970 100644
--- a/Doc/libmacfs.tex
+++ b/Doc/libmacfs.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macfs}}
+\section{Built-in Module \sectcode{macfs}}
\bimodindex{macfs}
\renewcommand{\indexsubitem}{(in module macfs)}
@@ -18,11 +18,14 @@
\begin{funcdesc}{RawFSSpec}{data}
Create an FSSpec object given the raw data for the C structure for the
-FSSpec.
+FSSpec as a string. This is mainly useful if you have obtained an
+FSSpec structure over a network.
\end{funcdesc}
\begin{funcdesc}{RawAlias}{data}
-Create an Alias object given the raw data for the alias.
+Create an Alias object given the raw data for the C structure for the
+alias as a string. This is mainly useful if you have obtained an
+FSSpec structure over a network.
\end{funcdesc}
\begin{funcdesc}{ResolveAliasFile}{file}
@@ -56,12 +59,13 @@
\subsection{FSSpec objects}
-\renewcommand{\indexsubitem}{(FSSpec object method)}
+\renewcommand{\indexsubitem}{(FSSpec object attribute)}
\begin{datadesc}{data}
The raw data from the FSSpec object, suitable for passing
to other applications, for instance.
\end{datadesc}
+\renewcommand{\indexsubitem}{(FSSpec object method)}
\begin{funcdesc}{as_pathname}{}
Return the full pathname of the file described by the FSSpec object.
\end{funcdesc}
@@ -91,12 +95,13 @@
\subsection{alias objects}
-\renewcommand{\indexsubitem}{(alias object method)}
+\renewcommand{\indexsubitem}{(alias object attribute)}
\begin{datadesc}{data}
The raw data for the Alias record, suitable for storing in a resource
or transmitting to other programs.
\end{datadesc}
+\renewcommand{\indexsubitem}{(alias object method)}
\begin{funcdesc}{Resolve}{\optional{file}}
Resolve the alias. If the alias was created as a relative alias you
should pass the file relative to which it is. Return the FSSpec for
diff --git a/Doc/libmacspeech.tex b/Doc/libmacspeech.tex
index 737016e..7480482 100644
--- a/Doc/libmacspeech.tex
+++ b/Doc/libmacspeech.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macspeech}}
+\section{Built-in Module \sectcode{macspeech}}
\bimodindex{macspeech}
\renewcommand{\indexsubitem}{(in module macspeech)}
diff --git a/Doc/libmactcp.tex b/Doc/libmactcp.tex
index 11c0114..561284b 100644
--- a/Doc/libmactcp.tex
+++ b/Doc/libmactcp.tex
@@ -1,5 +1,6 @@
-\section{Built-in module \sectcode{mactcp}}
+\section{Built-in Module \sectcode{mactcp}}
\bimodindex{mactcp}
+
\renewcommand{\indexsubitem}{(in module mactcp)}
This module provides an interface to the Macintosh TCP/IP driver
@@ -37,8 +38,9 @@
datagrams on, a value of zero will make MacTCP select a free port.
\end{funcdesc}
-\subsection{TCP stream objects}
-\renewcommand{\indexsubitem}{(TCP stream method)}
+\subsection{TCP Stream Objects}
+
+\renewcommand{\indexsubitem}{(TCP stream attribute)}
\begin{datadesc}{asr}
When set to a value different than \code{None} this should point to a
@@ -50,6 +52,8 @@
It is safe to do further calls from the \code{asr}.
\end{datadesc}
+\renewcommand{\indexsubitem}{(TCP stream method)}
+
\begin{funcdesc}{PassiveOpen}{port}
Wait for an incoming connection on TCP port \var{port} (zero makes the
system pick a free port). The call returns immediately, and you should
@@ -104,15 +108,17 @@
\end{funcdesc}
\begin{funcdesc}{Status}{}
-Return a TCP status object for this stream.
+Return a TCP status object for this stream giving the current status
+(see below).
\end{funcdesc}
-\subsection{TCP status objects}
+\subsection{TCP Status Objects}
This object has no methods, only some members holding information on
the connection. A complete description of all fields in this objects
can be found in the Apple documentation. The most interesting ones are:
-\renewcommand{\indexsubitem}{(TCP status method)}
+\renewcommand{\indexsubitem}{(TCP status attribute)}
+
\begin{datadesc}{localHost}
\dataline{localPort}
\dataline{remoteHost}
@@ -137,11 +143,11 @@
-\subsection{UDP stream objects}
+\subsection{UDP Stream Objects}
Note that, unlike the name suggests, there is nothing stream-like
about UDP.
-\renewcommand{\indexsubitem}{(UDP stream method)}
+\renewcommand{\indexsubitem}{(UDP stream attribute)}
\begin{datadesc}{asr}
The asynchronous service routine to be called on events such as
@@ -153,9 +159,11 @@
A read-only member giving the port number of this UDP stream.
\end{datadesc}
+\renewcommand{\indexsubitem}{(UDP stream method)}
+
\begin{funcdesc}{Read}{timeout}
Read a datagram, waiting at most \var{timeout} seconds ($-1$ is
-indefinite). Return the data.
+infinite). Return the data.
\end{funcdesc}
\begin{funcdesc}{Write}{host\, port\, buf}
diff --git a/Doc/libmarshal.tex b/Doc/libmarshal.tex
index 2b0a400..319c195 100644
--- a/Doc/libmarshal.tex
+++ b/Doc/libmarshal.tex
@@ -4,9 +4,9 @@
This module contains functions that can read and write Python
values in a binary format. The format is specific to Python, but
independent of machine architecture issues (e.g., you can write a
-Python value to a file on a VAX, transport the file to a Mac, and read
-it back there). Details of the format not explained here; read the
-source if you're interested.%
+Python value to a file on a PC, transport the file to a Sun, and read
+it back there). Details of the format are undocumented on purpose;
+it may change between Python versions (although it rarely does).%
\footnote{The name of this module stems from a bit of terminology used
by the designers of Modula-3 (amongst others), who use the term
``marshalling'' for shipping of data around in a self-contained form.
@@ -14,6 +14,14 @@
internal to external form (in an RPC buffer for instance) and
``unmarshalling'' for the reverse process.}
+This is not a general ``persistency'' module. For general persistency
+and transfer of Python objects through RPC calls, see the modules
+\code{pickle} and \code{shelve}. The \code{marshal} module exists
+mainly to support reading and writing the ``pseudo-compiled'' code for
+Python modules of \samp{.pyc} files.
+\stmodindex{pickle}
+\stmodindex{shelve}
+\obindex{code}
Not all Python object types are supported; in general, only objects
whose value is independent from a particular invocation of Python can
@@ -23,7 +31,22 @@
should be understood that tuples, lists and dictionaries are only
supported as long as the values contained therein are themselves
supported; and recursive lists and dictionaries should not be written
-(they will cause an infinite loop).
+(they will cause infinite loops).
+
+{\bf Caveat:} On machines where C's \code{long int} type has more than
+32 bits (such as the DEC Alpha or the HP Precision Architecture), it
+is possible to create plain Python integers that are longer than 32
+bits. Since the current \code{marshal} module uses 32 bits to
+transfer plain Python integers, such values are silently truncated.
+This particularly affects the use of very long integer literals in
+Python modules --- these will be accepted by the parser on such
+machines, but will be silently be truncated when the module is read
+from the \code{.pyc} instead.%
+\footnote{A solution would be to refuse such literals in the parser,
+since they are inherently non-portable. Another solution would be to
+let the \code{marshal} module raise an exception when an integer value
+would be truncated. At least one of these solutions will be
+implemented in a future version.}
There are functions that read/write files as well as functions
operating on strings.
@@ -31,6 +54,7 @@
The module defines these functions:
\renewcommand{\indexsubitem}{(in module marshal)}
+
\begin{funcdesc}{dump}{value\, file}
Write the value on the open file. The value must be a supported
type. The file must be an open file object such as
diff --git a/Doc/libmd5.tex b/Doc/libmd5.tex
index 0dfa65e..bd26f02 100644
--- a/Doc/libmd5.tex
+++ b/Doc/libmd5.tex
@@ -1,61 +1,64 @@
-\section{Built-in module \sectcode{md5}}
+\section{Built-in Module \sectcode{md5}}
\bimodindex{md5}
This module implements the interface to RSA's MD5 message digest
-algorithm (see also the file \file{md5.doc}). Its use is quite
-straightforward:\ use the function \code{new} to create an
-\dfn{md5}-object. You can now ``feed'' this object with arbitrary
-strings.
+algorithm (see also Internet RFC 1321). Its use is quite
+straightforward:\ use the \code{md5.new()} to create an md5 object.
+You can now feed this object with arbitrary strings using the
+\code{update()} method, and at any point you can ask it for the
+\dfn{digest} (a strong kind of 128-bit checksum,
+a.k.a. ``fingerprint'') of the contatenation of the strings fed to it
+so far using the \code{digest()} method.
-At any time you can ask for the ``final'' digest of the object. Internally,
-a temporary copy of the object is made and the digest is computed and
-returned. Because of the copy, the digest operation is not destructive
-for the object. Before a more exact description of the module's use, a small
-example will be helpful:
-to obtain the digest of the string \code{'abc'}, use \ldots
+For example, to obtain the digest of the string {\tt"Nobody inspects
+the spammish repetition"}:
\bcode\begin{verbatim}
>>> import md5
>>> m = md5.new()
->>> m.update('abc')
+>>> m.update("Nobody inspects")
+>>> m.update(" the spammish repetition")
>>> m.digest()
-'\220\001P\230<\322O\260\326\226?}(\341\177r'
+'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
\end{verbatim}\ecode
More condensed:
\bcode\begin{verbatim}
->>> md5.new('abc').digest()
-'\220\001P\230<\322O\260\326\226?}(\341\177r'
+>>> md5.new("Nobody inspects the spammish repetition").digest()
+'\273d\234\203\335\036\245\311\331\336\311\241\215\360\377\351'
\end{verbatim}\ecode
\renewcommand{\indexsubitem}{(in module md5)}
\begin{funcdesc}{new}{\optional{arg}}
- Create a new md5-object. If \var{arg} is present, an initial
- \code{update} method is called with \var{arg} as argument.
+Return a new md5 object. If \var{arg} is present, the method call
+\code{update(\var{arg})} is made.
\end{funcdesc}
\begin{funcdesc}{md5}{\optional{arg}}
For backward compatibility reasons, this is an alternative name for the
-\code{new} function.
+\code{new()} function.
\end{funcdesc}
-An md5-object has the following methods:
+An md5 object has the following methods:
\renewcommand{\indexsubitem}{(md5 method)}
\begin{funcdesc}{update}{arg}
- Update this md5-object with the string \var{arg}.
+Update the md5 object with the string \var{arg}. Repeated calls are
+equivalent to a single call with the concatenation of all the
+arguments, i.e.\ \code{m.update(a); m.update(b)} is equivalent to
+\code{m.update(a+b)}.
\end{funcdesc}
\begin{funcdesc}{digest}{}
-% XXX The following is not quite clear; what does MD5Final do?
- Return the \dfn{digest} of this md5-object. Internally, a copy is made
- and the \C-function \code{MD5Final} is called. Finally the digest is
- returned.
+Return the digest of the strings passed to the \code{update()}
+method so far. This is an 8-byte string which may contain
+non-\ASCII{} characters, including null bytes.
\end{funcdesc}
\begin{funcdesc}{copy}{}
- Return a separate copy of this md5-object. An \code{update} to this
- copy won't affect the original object.
+Return a copy (``clone'') of the md5 object. This can be used to
+efficiently compute the digests of strings that share a common initial
+substring.
\end{funcdesc}
diff --git a/Doc/libmimetools.tex b/Doc/libmimetools.tex
index 0d1a81b..361e0d0 100644
--- a/Doc/libmimetools.tex
+++ b/Doc/libmimetools.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{mimetools}}
+\section{Standard Module \sectcode{mimetools}}
\stmodindex{mimetools}
\renewcommand{\indexsubitem}{(in module mimetools)}
diff --git a/Doc/libmpz.tex b/Doc/libmpz.tex
index 1fd03f7..d274a03 100644
--- a/Doc/libmpz.tex
+++ b/Doc/libmpz.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{mpz}}
+\section{Built-in Module \sectcode{mpz}}
\bimodindex{mpz}
This module implements the interface to part of the GNU MP library.
diff --git a/Doc/libnntplib.tex b/Doc/libnntplib.tex
index 6aac671..b1a891d 100644
--- a/Doc/libnntplib.tex
+++ b/Doc/libnntplib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{nntplib}}
+\section{Standard Module \sectcode{nntplib}}
\stmodindex{nntplib}
\renewcommand{\indexsubitem}{(in module nntplib)}
diff --git a/Doc/libos.tex b/Doc/libos.tex
index 5109f5d..51442ef 100644
--- a/Doc/libos.tex
+++ b/Doc/libos.tex
@@ -26,9 +26,11 @@
following variables and functions are always exported by \code{os}:
\renewcommand{\indexsubitem}{(in module os)}
+
\begin{datadesc}{name}
-The name of the OS dependent module imported, e.g. \code{'posix'} or
-\code{'mac'}.
+The name of the OS dependent module imported. The following names
+have currently been registered: \code{'posix'}, \code{'nt'},
+\code{'dos'}, \code{'mac'}.
\end{datadesc}
\begin{datadesc}{path}
@@ -49,29 +51,54 @@
\end{datadesc}
\begin{datadesc}{sep}
-The character used by the OS to separate pathname components, e.g.
+The character used by the OS to separate pathname components, e.g.\
\code{'/'} for POSIX or \code{':'} for the Mac. Note that knowing this
is not sufficient to be able to parse or concatenate pathnames---better
use \code{os.path.split()} and \code{os.path.join()}---but it is
occasionally useful.
\end{datadesc}
+\begin{datadesc}{pathsep}
+The character conventionally used by the OS to separate search patch
+components (as in \code{\$PATH}), e.g.\ \code{':'} for POSIX or
+\code{';'} for MS-DOS.
+\end{datadesc}
+
+\begin{datadesc}{defpath}
+The default search path used by \code{os.exec*p*()} if the environment
+doesn't have a \code{'PATH'} key.
+\end{datadesc}
+
\begin{funcdesc}{execl}{path\, arg0\, arg1\, ...}
-This is equivalent to a call to \code{os.execv} with an \var{argv}
-of \code{[\var{arg0}, \var{arg1}, ...]}.
+This is equivalent to
+\code{os.execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
\end{funcdesc}
\begin{funcdesc}{execle}{path\, arg0\, arg1\, ...\, env}
-This is equivalent to a call to \code{os.execve} with an \var{argv}
-of \code{[\var{arg0}, \var{arg1}, ...]}.
+This is equivalent to
+\code{os.execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
\end{funcdesc}
\begin{funcdesc}{execlp}{path\, arg0\, arg1\, ...}
-This is like \code{execl} but duplicates the shell's actions in
-searching for an executable file in a list of directories. The
-directory list is obtained from \code{environ['PATH']}.
+This is equivalent to
+\code{os.execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
\end{funcdesc}
-\begin{funcdesc}{execvp}{path\, arg0\, arg1\, ...}
-\code{execvp} is for \code{execv} what \code{execlp} is for \code{execl}.
+\begin{funcdesc}{execvp}{path\, args}
+This is like \code{os.execv(\var{path}, \var{args})} but duplicates
+the shell's actions in searching for an executable file in a list of
+directories. The directory list is obtained from
+\code{os.environ['PATH']}.
\end{funcdesc}
+
+\begin{funcdesc}{execvpe}{path\, args\, env}
+This is a cross between \code{os.execve()} and \code{os.execvp()}.
+The directory list is obtained from \code{\var{env}['PATH']}.
+\end{funcdesc}
+
+(The functions \code{os.execv()} and \code{execve()} are not
+documented here, since they are implemented by the OS dependent
+module. If the OS dependent module doesn't define either of these,
+the functions that rely on it will raise an exception. They are
+documented in the section on module \code{posix}, together with all
+other functions that \code{os} imports from the OS dependent module.)
diff --git a/Doc/libpdb.tex b/Doc/libpdb.tex
index 7b3f1d4..54a3f58 100644
--- a/Doc/libpdb.tex
+++ b/Doc/libpdb.tex
@@ -91,7 +91,7 @@
\code{sys.last_traceback}.
\end{funcdesc}
-\subsection{Debugger Commands}
+\section{Debugger Commands}
The debugger recognizes the following commands. Most commands can be
abbreviated to one or two letters; e.g. ``\code{h(elp)}'' means that
@@ -117,7 +117,7 @@
\begin{description}
-\item[{h(elp) [\var{command}]}]
+\item[h(elp) [\var{command}]]
Without argument, print the list of available commands.
With a \var{command} as argument, print help about that command.
@@ -127,40 +127,40 @@
an identifier, ``\code{help exec}'' must be entered to get help on the
``\code{!}'' command.
-\item[{w(here)}]
+\item[w(here)]
Print a stack trace, with the most recent frame at the bottom.
An arrow indicates the current frame, which determines the
context of most commands.
-\item[{d(own)}]
+\item[d(own)]
Move the current frame one level down in the stack trace
(to an older frame).
-\item[{u(p)}]
+\item[u(p)]
Move the current frame one level up in the stack trace
(to a newer frame).
-\item[{b(reak) [\var{lineno}\code{|}\var{function}]}]
+\item[b(reak) [\var{lineno}\code{|}\var{function}]]
With a \var{lineno} argument, set a break there in the current
file. With a \var{function} argument, set a break at the entry of
that function. Without argument, list all breaks.
-\item[{cl(ear) [\var{lineno}]}]
+\item[cl(ear) [\var{lineno}]]
With a \var{lineno} argument, clear that break in the current file.
Without argument, clear all breaks (but first ask confirmation).
-\item[{s(tep)}]
+\item[s(tep)]
Execute the current line, stop at the first possible occasion
(either in a function that is called or on the next line in the
current function).
-\item[{n(ext)}]
+\item[n(ext)]
Continue execution until the next line in the current function
is reached or it returns. (The difference between \code{next} and
@@ -168,15 +168,15 @@
\code{next} executes called functions at (nearly) full speed, only
stopping at the next line in the current function.)
-\item[{r(eturn)}]
+\item[r(eturn)]
Continue execution until the current function returns.
-\item[{c(ont(inue))}]
+\item[c(ont(inue))]
Continue execution, only stop when a breakpoint is encountered.
-\item[{l(ist) [\var{first} [, \var{last}]]}]
+\item[l(ist) [\var{first} [, \var{last}]]]
List source code for the current file. Without arguments, list 11
lines around the current line or continue the previous listing. With
@@ -184,17 +184,17 @@
list the given range; if the second argument is less than the first,
it is interpreted as a count.
-\item[{a(rgs)}]
+\item[a(rgs)]
Print the argument list of the current function.
-\item[{p \var{expression}}]
+\item[p \var{expression}]
Evaluate the \var{expression} in the current context and print its
value. (Note: \code{print} can also be used, but is not a debugger
command --- this executes the Python \code{print} statement.)
-\item[{[!] \var{statement}}]
+\item[[!] \var{statement}]
Execute the (one-line) \var{statement} in the context of
the current stack frame.
@@ -207,9 +207,83 @@
(Pdb)
\end{verbatim}
-\item[{q(uit)}]
+\item[q(uit)]
Quit from the debugger.
The program being executed is aborted.
\end{description}
+
+\section{How It Works}
+
+Some changes were made to the interpreter:
+
+\begin{itemize}
+\item sys.settrace(func) sets the global trace function
+\item there can also a local trace function (see later)
+\end{itemize}
+
+Trace functions have three arguments: (\var{frame}, \var{event}, \var{arg})
+
+\begin{description}
+
+\item[\var{frame}] is the current stack frame
+
+\item[\var{event}] is a string: \code{'call'}, \code{'line'}, \code{'return'}
+or \code{'exception'}
+
+\item[\var{arg}] is dependent on the event type
+
+\end{description}
+
+A trace function should return a new trace function or None.
+Class methods are accepted (and most useful!) as trace methods.
+
+The events have the following meaning:
+
+\begin{description}
+
+\item[\code{'call'}]
+A function is called (or some other code block entered). The global
+trace function is called; arg is the argument list to the function;
+the return value specifies the local trace function.
+
+\item[\code{'line'}]
+The interpreter is about to execute a new line of code (sometimes
+multiple line events on one line exist). The local trace function is
+called; arg in None; the return value specifies the new local trace
+function.
+
+\item[\code{'return'}]
+A function (or other code block) is about to return. The local trace
+function is called; arg is the value that will be returned. The trace
+function's return value is ignored.
+
+\item[\code{'exception'}]
+An exception has occurred. The local trace function is called; arg is
+a triple (exception, value, traceback); the return value specifies the
+new local trace function
+
+\end{description}
+
+Note that as an exception is propagated down the chain of callers, an
+\code{'exception'} event is generated at each level.
+
+Stack frame objects have the following read-only attributes:
+
+\begin{description}
+\item[f_code] the code object being executed
+\item[f_lineno] the current line number (\code{-1} for \code{'call'} events)
+\item[f_back] the stack frame of the caller, or None
+\item[f_locals] dictionary containing local name bindings
+\item[f_globals] dictionary containing global name bindings
+\end{description}
+
+Code objects have the following read-only attributes:
+
+\begin{description}
+\item[co_code] the code string
+\item[co_names] the list of names used by the code
+\item[co_consts] the list of (literal) constants used by the code
+\item[co_filename] the filename from which the code was compiled
+\end{description}
diff --git a/Doc/libpickle.tex b/Doc/libpickle.tex
index 5c01d36..8dc29e4 100644
--- a/Doc/libpickle.tex
+++ b/Doc/libpickle.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{pickle}}
+\section{Standard Module \sectcode{pickle}}
\stmodindex{pickle}
\index{persistency}
\indexii{persistent}{objects}
@@ -7,6 +7,8 @@
\indexii{flattening}{objects}
\indexii{pickling}{objects}
+\renewcommand{\indexsubitem}{(in module pickle)}
+
The \code{pickle} module implements a basic but powerful algorithm for
``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly
arbitrary Python objects. This is a more primitive notion than
@@ -28,11 +30,11 @@
\begin{itemize}
-\item recursive objects
+\item recursive objects (objects containing references to themselves)
-\item pointer sharing
+\item object sharing (references to the same object in different places)
-\item instances of user-defined classes
+\item user-defined classes and their instances
\end{itemize}
@@ -42,13 +44,13 @@
sharing or recursive objects); however it means that non-Python
programs may not be able to reconstruct pickled Python objects.
-The \code{pickle} data format uses a printable ASCII representation.
+The \code{pickle} data format uses a printable \ASCII{} representation.
This is slightly more voluminous than a binary representation.
However, small integers actually take {\em less} space when
represented as minimal-size decimal strings than when represented as
32-bit binary numbers, and strings are only much longer if they
contain many control characters or 8-bit characters. The big
-advantage of using printable ASCII (and of some other characteristics
+advantage of using printable \ASCII{} (and of some other characteristics
of \code{pickle}'s representation) is that for debugging or recovery
purposes it is possible for a human to read the pickled file with a
standard text editor. (I could have gone a step further and used a
@@ -67,7 +69,7 @@
For the benefit of persistency modules written using \code{pickle}, it
supports the notion of a reference to an object outside the pickled
data stream. Such objects are referenced by a name, which is an
-arbitrary string of printable ASCII characters. The resolution of
+arbitrary string of printable \ASCII{} characters. The resolution of
such names is not defined by the \code{pickle} module --- the
persistent object module will have to implement a method
\code{persistent_load}. To write references to persistent objects,
@@ -78,6 +80,8 @@
First of all, the class must be defined at the top level in a module.
+\renewcommand{\indexsubitem}{(pickle protocol)}
+
Next, it must normally be possible to create class instances by
calling the class without arguments. If this is undesirable, the
class can define a method \code{__getinitargs__()}, which should
@@ -86,7 +90,7 @@
\ttindex{__getinitargs__}
\ttindex{__init__}
-Classes can further influence how they are pickled --- if the class
+Classes can further influence how their instances are pickled --- if the class
defines the method \code{__getstate__()}, it is called and the return
state is pickled as the contents for the instance, and if the class
defines the method \code{__setstate__()}, it is called with the
@@ -113,6 +117,13 @@
number in the objects so that suitable conversions can be made by the
class's \code{__setstate__()} method.
+When a class itself is pickled, only its name is pickled --- the class
+definition is not pickled, but re-imported by the unpickling process.
+Therefore, the restriction that the class must be defined at the top
+level in a module applies to pickled classes as well.
+
+\renewcommand{\indexsubitem}{(in module pickle)}
+
The interface can be summarized as follows.
To pickle an object \code{x} onto a file \code{f}, open for writing:
@@ -122,6 +133,12 @@
p.dump(x)
\end{verbatim}
+A shorthand for this is:
+
+\begin{verbatim}
+pickle.dump(x, f)
+\end{verbatim}
+
To unpickle an object \code{x} from a file \code{f}, open for reading:
\begin{verbatim}
@@ -129,11 +146,19 @@
x = u.load(x)
\end{verbatim}
+A shorthand is:
+
+\begin{verbatim}
+x = pickle.load(f)
+\end{verbatim}
+
The \code{Pickler} class only calls the method \code{f.write} with a
string argument. The \code{Unpickler} calls the methods \code{f.read}
(with an integer argument) and \code{f.readline} (without argument),
both returning a string. It is explicitly allowed to pass non-file
objects here, as long as they have the right methods.
+\ttindex{Unpickler}
+\ttindex{Pickler}
The following types can be pickled:
\begin{itemize}
@@ -146,25 +171,56 @@
\item tuples, lists and dictionaries containing only picklable objects
-\item class instances whose \code{__dict__} or \code{__setstate__()}
-is picklable
+\item classes that are defined at the top level in a module
+
+\item instances of such classes whose \code{__dict__} or
+\code{__setstate__()} is picklable
\end{itemize}
-Attempts to pickle unpicklable objects will raise an exception; when
-this happens, an unspecified number of bytes may have been written to
-the file argument.
+Attempts to pickle unpicklable objects will raise the
+\code{PicklingError} exception; when this happens, an unspecified
+number of bytes may have been written to the file.
-It is possible to make multiple calls to \code{Pickler.dump()} or to
-\code{Unpickler.load()}, as long as there is a one-to-one
-correspondence between \code{Pickler} and \code{Unpickler} objects and
-between \code{dump} and \code{load} calls for any pair of
-corresponding \code{Pickler} and \code{Unpicklers}. {\em Warning}:
-this is intended for pickling multiple objects without intervening
-modifications to the objects or their parts. If you modify an object
-and then pickle it again using the same \code{Pickler} instance, the
-object is not pickled again --- a reference to it is pickled and the
-\code{Unpickler} will return the old value, not the modified one. (There
-are two problems here: (a) detecting changes, and (b) marshalling a
-minimal set of changes. I have no answers. Garbage Collection may
-also become a problem here.)
+It is possible to make multiple calls to the \code{dump()} method of
+the same \code{Pickler} instance. These must then be matched to the
+same number of calls to the \code{load()} instance of the
+corresponding \code{Unpickler} instance. If the same object is
+pickled by multiple \code{dump()} calls, the \code{load()} will all
+yield references to the same object. {\em Warning}: this is intended
+for pickling multiple objects without intervening modifications to the
+objects or their parts. If you modify an object and then pickle it
+again using the same \code{Pickler} instance, the object is not
+pickled again --- a reference to it is pickled and the
+\code{Unpickler} will return the old value, not the modified one.
+(There are two problems here: (a) detecting changes, and (b)
+marshalling a minimal set of changes. I have no answers. Garbage
+Collection may also become a problem here.)
+
+Apart from the \code{Pickler} and \code{Unpickler} classes, the
+module defines the following functions, and an exception:
+
+\begin{funcdesc}{dump}{object\, file}
+Write a pickled representation of \var{obect} to the open file object
+\var{file}. This is equivalent to \code{Pickler(file).dump(object)}.
+\end{funcdesc}
+
+\begin{funcdesc}{load}{file}
+Read a pickled object from the open file object \var{file}. This is
+equivalent to \code{Unpickler(file).load()}.
+\end{funcdesc}
+
+\begin{funcdesc}{dumps}{object}
+Return the pickled representation of the object as a string, instead
+of writing it to a file.
+\end{funcdesc}
+
+\begin{funcdesc}{loads}{string}
+Read a pickled object from a string instead of a file. Characters in
+the string past the pickled object's representation are ignored.
+\end{funcdesc}
+
+\begin{excdesc}{PicklingError}
+This exception is raised when an unpicklable object is passed to
+\code{Pickler.dump()}.
+\end{excdesc}
diff --git a/Doc/libposix.tex b/Doc/libposix.tex
index c749d74..ae041c4 100644
--- a/Doc/libposix.tex
+++ b/Doc/libposix.tex
@@ -1,12 +1,20 @@
\section{Built-in Module \sectcode{posix}}
-
\bimodindex{posix}
This module provides access to operating system functionality that is
standardized by the C Standard and the POSIX standard (a thinly disguised
\UNIX{} interface).
-It is available in all Python versions except on the Macintosh;
-the MS-DOS version does not support certain functions.
+
+\strong{Do not import this module directly.} Instead, import the
+module \code{os}, which provides a \emph{portable} version of this
+interface. On \UNIX{}, the \code{os} module provides a superset of
+the \code{posix} interface. On non-\UNIX{} operating systems the
+\code{posix} module is not available, but a subset is always available
+through the \code{os} interface. Once \code{os} is imported, there is
+\emph{no} performance penalty in using it instead of
+\code{posix}.
+\stmodindex{os}
+
The descriptions below are very terse; refer to the
corresponding \UNIX{} manual entry for more information.
@@ -20,13 +28,18 @@
\begin{datadesc}{environ}
A dictionary representing the string environment at the time
the interpreter was started.
-(Modifying this dictionary does not affect the string environment of the
-interpreter.)
For example,
\code{posix.environ['HOME']}
is the pathname of your home directory, equivalent to
\code{getenv("HOME")}
in C.
+Modifying this dictionary does not affect the string environment
+passed on by \code{execv()}, \code{popen()} or \code{system()}; if you
+need to change the environment, pass \code{environ} to \code{execve()}
+or add variable assignments and export statements to the command
+string for \code{system()} or \code{popen()}.%
+\footnote{The problem with automatically passing on \code{environ} is
+that there is no portable way of changing the environment.}
\end{datadesc}
\renewcommand{\indexsubitem}{(exception in module posix)}
diff --git a/Doc/libposixfile.tex b/Doc/libposixfile.tex
index 050ba5a..c472c95 100644
--- a/Doc/libposixfile.tex
+++ b/Doc/libposixfile.tex
@@ -7,12 +7,13 @@
file objects. In particular, it implements file locking, control over
the file flags, and an easy interface to duplicate the file object.
The module defines a new file object, the posixfile object. It
-inherits all the standard file object methods and adds the methods
-described below.
+has all the standard file object methods and adds the methods
+described below. This module only works for certain flavors of
+\UNIX{}, since it uses \code{fcntl()} for file locking.
To instantiate a posixfile object, use the \code{open()} function in
-the posixfile module. The resulting object looks and feels the same as
-a standard file object.
+the posixfile module. The resulting object looks and feels roughly
+the same as a standard file object.
The posixfile module defines the following constants:
@@ -32,10 +33,11 @@
The posixfile module defines the following functions:
\renewcommand{\indexsubitem}{(in module posixfile)}
-\begin{funcdesc}{open}{filename\, mode}
+
+\begin{funcdesc}{open}{filename\optional{\, mode\optional{\, bufsize}}}
Create a new posixfile object with the given filename and mode. The
- filename and mode are interpreted the same way as the \code{open()}
- builtin function.
+ \var{filename}, \var{mode} and \var{bufsize} arguments are
+ interpreted the same way as by the \code{open()} builtin function.
\end{funcdesc}
\begin{funcdesc}{fileopen}{fileobject}
@@ -102,8 +104,8 @@
\begin{tableiii}{|c|l|c|}{samp}{Modifier}{Meaning}{Notes}
\lineiii{|}{wait until the lock has been granted}{}
- \lineiii{?}{return the first lock conflicting with the requested lock,}{(1)}
- {}&{\hskip0.5cm or \code{None} if there is no conflict.}&{}\\
+ \lineiii{?}{return the first lock conflicting with the requested lock, or
+ \code{None} if there is no conflict.}{(1)}
\end{tableiii}
Note:
diff --git a/Doc/libppath.tex b/Doc/libppath.tex
index c7c2b63..0d3bbe5 100644
--- a/Doc/libppath.tex
+++ b/Doc/libppath.tex
@@ -1,9 +1,14 @@
\section{Standard Module \sectcode{posixpath}}
-
\stmodindex{posixpath}
+
This module implements some useful functions on POSIX pathnames.
+\strong{Do not import this module directly.} Instead, import the
+module \code{os} and use \code{os.path}.
+\stmodindex{os}
+
\renewcommand{\indexsubitem}{(in module posixpath)}
+
\begin{funcdesc}{basename}{p}
Return the base name of pathname
\var{p}.
@@ -66,10 +71,12 @@
\end{funcdesc}
\begin{funcdesc}{ismount}{p}
-Return true if \var{p} is a mount point. (This currently checks whether
-\code{\var{p}/..} is on a different device from \var{p} or whether
-\code{\var{p}/..} and \var{p} point to the same i-node on the same
-device --- is this test correct for all \UNIX{} and POSIX variants?)
+Return true if pathname \var{p} is a \dfn{mount point}: a point in a
+file system where a different file system has been mounted. The
+function checks whether \var{p}'s parent, \file{\var{p}/..}, is on a
+different device than \var{p}, or whether \file{\var{p}/..} and
+\var{p} point to the same i-node on the same device --- this should
+detect mount points for all \UNIX{} and POSIX variants.
\end{funcdesc}
\begin{funcdesc}{join}{p\, q}
@@ -128,9 +135,10 @@
directory tree rooted at \var{p} (including \var{p} itself, if it is a
directory). The argument \var{dirname} specifies the visited directory,
the argument \var{names} lists the files in the directory (gotten from
-\code{posix.listdir(\var{dirname})}). The \var{visit} function may
-modify \var{names} to influence the set of directories visited below
-\var{dirname}, e.g., to avoid visiting certain parts of the tree. (The
-object referred to by \var{names} must be modified in place, using
-\code{del} or slice assignment.)
+\code{posix.listdir(\var{dirname})}, so including \samp{.} and
+\samp{..}). The \var{visit} function may modify \var{names} to
+influence the set of directories visited below \var{dirname}, e.g., to
+avoid visiting certain parts of the tree. (The object referred to by
+\var{names} must be modified in place, using \code{del} or slice
+assignment.)
\end{funcdesc}
diff --git a/Doc/libprofile.tex b/Doc/libprofile.tex
index 29cd01b..b14116d 100644
--- a/Doc/libprofile.tex
+++ b/Doc/libprofile.tex
@@ -2,7 +2,7 @@
\stmodindex{profile}
\stmodindex{pstats}
-Copyright 1994, by InfoSeek Corporation, all rights reserved.
+Copyright \copyright\ 1994, by InfoSeek Corporation, all rights reserved.
Written by James Roskind%
\footnote{
@@ -42,7 +42,7 @@
I'd appreciate the feedback.
-\section{Introduction}
+\section{Introduction to the profiler}
A \dfn{profiler} is a program that describes the run time performance
of a program, providing a variety of statistics. This documentation
@@ -242,7 +242,7 @@
\section{Reference Manual}
-\renewcommand{\indexsubitem}{}
+\renewcommand{\indexsubitem}{(profiler function)}
The primary entry point for the profiler is the global function
\code{profile.run()}. It is typically used to create any profile
@@ -254,7 +254,7 @@
``better'' profilers from the classes presented, or reading the source
code for these modules.
-\begin{funcdesc}{profile.run}{string\optional{\, filename}}
+\begin{funcdesc}{profile.run}{string\optional{\, filename\optional{\, ...}}}
This function takes a single argument that has can be passed to the
\code{exec} statement, and an optional file name. In all cases this
@@ -336,12 +336,12 @@
\end{funcdesc}
-\subsection{Methods Of The \sectcode{Stats} Class}
+\subsection{The \sectcode{Stats} Class}
\renewcommand{\indexsubitem}{(Stats method)}
\begin{funcdesc}{strip_dirs}{}
-This method for the code{Stats} class removes all leading path information
+This method for the \code{Stats} class removes all leading path information
from file names. It is very useful in reducing the size of the
printout to fit within (close to) 80 columns. This method modifies
the object, and the stripped information is lost. After performing a
@@ -355,7 +355,7 @@
\begin{funcdesc}{add}{filename\optional{\, ...}}
-This method of the code{Stats} class accumulates additional profiling
+This method of the \code{Stats} class accumulates additional profiling
information into the current profiling object. Its arguments should
refer to filenames created by the corresponding version of
\code{profile.run()}. Statistics for identically named (re: file,
@@ -364,7 +364,7 @@
\end{funcdesc}
\begin{funcdesc}{sort_stats}{key\optional{\, ...}}
-This method modifies the code{Stats} object by sorting it according to the
+This method modifies the \code{Stats} object by sorting it according to the
supplied criteria. The argument is typically a string identifying the
basis of a sort (example: \code{"time"} or \code{"name"}).
@@ -412,7 +412,7 @@
\begin{funcdesc}{reverse_order}{}
-This method for the code{Stats} class reverses the ordering of the basic
+This method for the \code{Stats} class reverses the ordering of the basic
list within the object. This method is provided primarily for
compatibility with the old profiler. Its utility is questionable
now that ascending vs descending order is properly selected based on
@@ -420,7 +420,7 @@
\end{funcdesc}
\begin{funcdesc}{print_stats}{restriction\optional{\, ...}}
-This method for the code{Stats} class prints out a report as described
+This method for the \code{Stats} class prints out a report as described
in the \code{profile.run()} definition.
The order of the printing is based on the last \code{sort_stats()}
@@ -454,7 +454,7 @@
\begin{funcdesc}{print_callers}{restrictions\optional{\, ...}}
-This method for the code{Stats} class prints a list of all functions
+This method for the \code{Stats} class prints a list of all functions
that called each function in the profiled database. The ordering is
identical to that provided by \code{print_stats()}, and the definition
of the restricting argument is also identical. For convenience, a
@@ -464,14 +464,14 @@
\end{funcdesc}
\begin{funcdesc}{print_callees}{restrictions\optional{\, ...}}
-This method for the code{Stats} class prints a list of all function
+This method for the \code{Stats} class prints a list of all function
that were called by the indicated function. Aside from this reversal
of direction of calls (re: called vs was called by), the arguments and
ordering are identical to the \code{print_callers()} method.
\end{funcdesc}
\begin{funcdesc}{ignore}{}
-This method of the code{Stats} class is used to dispose of the value
+This method of the \code{Stats} class is used to dispose of the value
returned by earlier methods. All standard methods in this class
return the instance that is being processed, so that the commands can
be strung together. For example:
@@ -481,7 +481,7 @@
\end{verbatim}
would perform all the indicated functions, but it would not return
-the final reference to the code{Stats} instance.%
+the final reference to the \code{Stats} instance.%
\footnote{
This was once necessary, when Python would print any unused expression
result that was not \code{None}. The method is still defined for
@@ -604,7 +604,7 @@
at this point, when a constant can be used.
-\section{Extensions: Deriving Better Profilers}
+\section{Extensions - Deriving Better Profilers}
The \code{Profile} class of module \code{profile} was written so that
derived classes could be developed to extend the profiler. Rather
diff --git a/Doc/libregex.tex b/Doc/libregex.tex
index dae6666..1b18679 100644
--- a/Doc/libregex.tex
+++ b/Doc/libregex.tex
@@ -44,12 +44,13 @@
\begin{funcdesc}{compile}{pattern\optional{\, translate}}
Compile a regular expression pattern into a regular expression
object, which can be used for matching using its \code{match} and
- \code{search} methods, described below. The optional
+ \code{search} methods, described below. The optional argument
\var{translate}, if present, must be a 256-character string
indicating how characters (both of the pattern and of the strings to
be matched) are translated before comparing them; the \code{i}-th
element of the string gives the translation for the character with
- ASCII code \code{i}.
+ \ASCII{} code \code{i}. This can be used to implement
+ case-insensitive matching; see the \code{casefold} data item below.
The sequence
diff --git a/Doc/librfc822.tex b/Doc/librfc822.tex
index 602b6ef..d819238 100644
--- a/Doc/librfc822.tex
+++ b/Doc/librfc822.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{rfc822}}
+\section{Standard Module \sectcode{rfc822}}
\stmodindex{rfc822}
\renewcommand{\indexsubitem}{(in module rfc822)}
@@ -60,12 +60,12 @@
\var{name} exists, return \code{None, None}; otherwise both the full
name and the address are (possibly empty )strings.
-Example: If \code{m}'s first \code{From} header contains the string
-\code{'guido@cwi.nl (Guido van Rossum)'}, then
+Example: If \code{m}'s first \code{From} header contains the string\\
+\code{'jack@cwi.nl (Jack Jansen)'}, then
\code{m.getaddr('From')} will yield the pair
-\code{('Guido van Rossum', 'guido@cwi.nl')}.
+\code{('Jack Jansen', 'jack@cwi.nl')}.
If the header contained
-\code{'Guido van Rossum <guido@cwi.nl>'} instead, it would yield the
+\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the
exact same result.
\end{funcdesc}
diff --git a/Doc/librgbimg.tex b/Doc/librgbimg.tex
index f25921e..ace426f 100644
--- a/Doc/librgbimg.tex
+++ b/Doc/librgbimg.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{rgbimg}}
+\section{Built-in Module \sectcode{rgbimg}}
\bimodindex{rgbimg}
The rgbimg module allows python programs to access SGI imglib image
diff --git a/Doc/librotor.tex b/Doc/librotor.tex
index f2ea074..6befb05 100644
--- a/Doc/librotor.tex
+++ b/Doc/librotor.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{rotor}}
+\section{Built-in Module \sectcode{rotor}}
\bimodindex{rotor}
This module implements a rotor-based encryption algorithm, contributed by
diff --git a/Doc/libselect.tex b/Doc/libselect.tex
index d47face..421d1aa 100644
--- a/Doc/libselect.tex
+++ b/Doc/libselect.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{select}}
+\section{Built-in Module \sectcode{select}}
\bimodindex{select}
This module provides access to the function \code{select} available in
diff --git a/Doc/libsgmllib.tex b/Doc/libsgmllib.tex
index 8abcb41..129bdd9 100644
--- a/Doc/libsgmllib.tex
+++ b/Doc/libsgmllib.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{sgmllib}}
+\section{Standard Module \sectcode{sgmllib}}
\stmodindex{sgmllib}
\index{SGML}
@@ -66,7 +66,7 @@
\begin{funcdesc}{handle_charref}{ref}
This method is called to process a character reference of the form
``\code{\&\#\var{ref};}'' where \var{ref} is a decimal number in the
-range 0-255. It translates the character to ASCII and calls the
+range 0-255. It translates the character to \ASCII{} and calls the
method \code{handle_data()} with the character as argument. If
\var{ref} is invalid or out of range, the method
\code{unknown_charref(\var{ref})} is called instead.
diff --git a/Doc/libshelve.tex b/Doc/libshelve.tex
index 0dec230..a232add 100644
--- a/Doc/libshelve.tex
+++ b/Doc/libshelve.tex
@@ -1,7 +1,8 @@
-\section{Built-in module \sectcode{shelve}}
+\section{Standard Module \sectcode{shelve}}
\stmodindex{shelve}
\stmodindex{pickle}
\bimodindex{dbm}
+\bimodindex{gdbm}
A ``shelf'' is a persistent, dictionary-like object. The difference
with ``dbm'' databases is that the values (not the keys!) in a shelf
@@ -48,8 +49,11 @@
or may not be necessary to flush changes to disk.
\item
-The \code{shelve} module does not support {\em concurrent} access to
-shelved objects. Two programs should not try to simultaneously access
-the same shelf.
+The \code{shelve} module does not support {\em concurrent} read/write
+access to shelved objects. (Multiple simultaneous read accesses are
+safe.) When a program has a shelf open for writing, no other program
+should have it open for reading or writing. \UNIX{} file locking can
+be used to solve this, but this differs across \UNIX{} versions and
+requires knowledge about the database implementation used.
\end{itemize}
diff --git a/Doc/libsignal.tex b/Doc/libsignal.tex
index 13139d7..63b671f 100644
--- a/Doc/libsignal.tex
+++ b/Doc/libsignal.tex
@@ -20,7 +20,7 @@
``atomic'' instructions of the Python interpreter. This means that
signals arriving during long calculations implemented purely in C
(e.g.\ regular expression matches on large bodies of text) may be
-delayed for an arbitrary time.
+delayed for an arbitrary amount of time.
\item
When a signal arrives during an I/O operation, it is possible that the
@@ -48,8 +48,10 @@
in the main thread of execution. Any thread can perform an
\code{alarm()}, \code{getsignal()}, or \code{pause()}; only the main
thread can set a new signal handler, and the main thread will be the
-only one to receive signals. This means that signals can't be used as
-a means of interthread communication. Use locks instead.
+only one to receive signals (this is enforced by the Python signal
+module, even if the underlying thread implementation supports sending
+signals to individual threads). This means that signals can't be used
+as a means of interthread communication. Use locks instead.
\end{itemize}
@@ -126,4 +128,9 @@
When threads are enabled, this function can only be called from the
main thread; attempting to call it from other threads will cause a
\code{ValueError} exception to be raised.
+
+ The \var{handler} is called with two arguments: the signal number
+ and the current stack frame (\code{None} or a frame object; see the
+ reference manual for a description of frame objects).
+\obindex{frame}
\end{funcdesc}
diff --git a/Doc/libsocket.tex b/Doc/libsocket.tex
index b826601..9b3c228 100644
--- a/Doc/libsocket.tex
+++ b/Doc/libsocket.tex
@@ -37,8 +37,8 @@
argument types and out-of-memory conditions can be raised; errors
related to socket or address semantics raise the error \code{socket.error}.
-Non-blocking and asynchronous mode are not supported; see module
-\code{select} for a way to do non-blocking socket I/O.
+Non-blocking mode is supported through the \code{setblocking()}
+method.
The module \code{socket} exports the following constants and functions:
@@ -95,7 +95,7 @@
Return a string containing the hostname of the machine where
the Python interpreter is currently executing. If you want to know the
current machine's IP address, use
-\code{socket.gethostbyname(socket.gethostname())} instead.
+\code{socket.gethostbyname(socket.gethostname())}.
\end{funcdesc}
\begin{funcdesc}{gethostbyaddr}{ip_address}
@@ -133,7 +133,7 @@
daemon).
\end{funcdesc}
-\subsection{Socket Object Methods}
+\subsection{Socket Objects}
\noindent
Socket objects have the following methods. Except for
@@ -187,28 +187,30 @@
\begin{funcdesc}{getsockopt}{level\, optname\optional{\, buflen}}
Return the value of the given socket option (see the \UNIX{} man page
-{\it getsockopt}(2)). The needed symbolic constants are defined in
-the \code{socket} module (\code{SO_*} etc.). If the optional third
-argument is absent, an integer option is assumed and its integer value
+{\it getsockopt}(2)). The needed symbolic constants (\code{SO_*} etc.)
+are defined in this module. If \var{buflen}
+is absent, an integer option is assumed and its integer value
is returned by the function. If \var{buflen} is present, it specifies
the maximum length of the buffer used to receive the option in, and
-this buffer is returned as a string. It's up to the caller to decode
+this buffer is returned as a string. It is up to the caller to decode
the contents of the buffer (see the optional built-in module
\code{struct} for a way to decode C structures encoded as strings).
\end{funcdesc}
\begin{funcdesc}{listen}{backlog}
-Listen for connections made to the socket.
-The argument specifies the maximum number of queued connections and
-should be at least 1; the maximum value is system-dependent.
+Listen for connections made to the socket. The \var{backlog} argument
+specifies the maximum number of queued connections and should be at
+least 1; the maximum value is system-dependent (usually 5).
\end{funcdesc}
-\begin{funcdesc}{makefile}{mode}
-Return a \dfn{file object} associated with the socket.
-(File objects were described earlier under Built-in Types.)
-The file object references a \code{dup}ped version of the socket file
-descriptor, so the file object and socket object may be closed or
-garbage-collected independently.
+\begin{funcdesc}{makefile}{\optional{mode\optional{\, bufsize}}}
+Return a \dfn{file object} associated with the socket. (File objects
+were described earlier under Built-in Types.) The file object
+references a \code{dup()}ped version of the socket file descriptor, so
+the file object and socket object may be closed or garbage-collected
+independently. The optional \var{mode} and \var{bufsize} arguments
+are interpreted the same way as by the built-in
+\code{open()} function.
\end{funcdesc}
\begin{funcdesc}{recv}{bufsize\optional{\, flags}}
@@ -219,23 +221,26 @@
zero.
\end{funcdesc}
-\begin{funcdesc}{recvfrom}{bufsize}
+\begin{funcdesc}{recvfrom}{bufsize\optional{\, flags}}
Receive data from the socket. The return value is a pair
\code{(\var{string}, \var{address})} where \var{string} is a string
representing the data received and \var{address} is the address of the
-socket sending the data.
+socket sending the data. The optional \var{flags} argument has the
+same meaning as for \code{recv()} above.
(The format of \var{address} depends on the address family --- see above.)
\end{funcdesc}
-\begin{funcdesc}{send}{string}
+\begin{funcdesc}{send}{string\optional{\, flags}}
Send data to the socket. The socket must be connected to a remote
-socket. Return the number of bytes sent.
+socket. The optional \var{flags} argument has the same meaning as for
+\code{recv()} above. Return the number of bytes sent.
\end{funcdesc}
-\begin{funcdesc}{sendto}{string\, address}
+\begin{funcdesc}{sendto}{string\optional{\, flags}\, address}
Send data to the socket. The socket should not be connected to a
remote socket, since the destination socket is specified by
-\code{address}. Return the number of bytes sent.
+\code{address}. The optional \var{flags} argument has the same
+meaning as for \code{recv()} above. Return the number of bytes sent.
(The format of \var{address} depends on the address family --- see above.)
\end{funcdesc}
diff --git a/Doc/libstdwin.tex b/Doc/libstdwin.tex
index df37707..29b047a 100644
--- a/Doc/libstdwin.tex
+++ b/Doc/libstdwin.tex
@@ -8,9 +8,10 @@
Interface, STDWIN [CWI report CR-R8817].
It is available on systems to which STDWIN has been ported (which is
most systems).
-It is only available if the \code{DISPLAY} environment variable is set
-or an explicit \samp{-display \var{displayname}} argument is passed to
-the interpreter.
+
+On Unix running X11, it can only be used if the \code{DISPLAY}
+environment variable is set or an explicit \samp{-display
+\var{displayname}} argument is passed to the Python interpreter.
Functions have names that usually resemble their C STDWIN counterparts
with the initial `w' dropped.
@@ -63,6 +64,7 @@
in resource definitions), i.e. the wildcard character \code{'*'}
matches any sequence of characters (including none) and \code{'?'}
matches any single character.
+On the Macintosh this function currently returns an empty list.
\end{funcdesc}
\begin{funcdesc}{setdefscrollbars}{hflag\, vflag}
@@ -164,6 +166,7 @@
\begin{funcdesc}{newbitmap}{width\, height}
Create a new bitmap object of the given dimensions.
Methods of bitmap objects are described below.
+Not available on the Macintosh.
\end{funcdesc}
\begin{funcdesc}{fleep}{}
@@ -294,7 +297,7 @@
\ttindex{select}
\end{funcdesc}
-\subsection{Window Object Methods}
+\subsection{Window Objects}
Window objects are created by \code{stdwin.open()}. They are closed
by their \code{close()} method or when they are garbage-collected.
@@ -440,7 +443,7 @@
Discard the window object. It should not be used again.
\end{funcdesc}
-\subsection{Drawing Object Methods}
+\subsection{Drawing Objects}
Drawing objects are created exclusively by the window method
\code{begindrawing()}.
@@ -560,6 +563,7 @@
in the bitmap, in the foreground color, or \code{None}, to draw all
bits (ones are drawn in the foreground color, zeros in the background
color).
+Not available on the Macintosh.
\end{funcdesc}
\begin{funcdesc}{cliprect}{rect}
@@ -582,7 +586,7 @@
Discard the drawing object. It should not be used again.
\end{funcdesc}
-\subsection{Menu Object Methods}
+\subsection{Menu Objects}
A menu object represents a menu.
The menu is destroyed when the menu object is deleted.
@@ -617,11 +621,13 @@
Discard the menu object. It should not be used again.
\end{funcdesc}
-\subsection{Bitmap Object Methods}
+\subsection{Bitmap Objects}
A bitmap represents a rectangular array of bits.
The top left bit has coordinate (0, 0).
A bitmap can be drawn with the \code{bitmap} method of a drawing object.
+Bitmaps are currently not available on the Macintosh.
+
The following methods are defined:
\renewcommand{\indexsubitem}{(bitmap method)}
@@ -644,7 +650,7 @@
Discard the bitmap object. It should not be used again.
\end{funcdesc}
-\subsection{Text-edit Object Methods}
+\subsection{Text-edit Objects}
A text-edit object represents a text-edit block.
For semantics, see the STDWIN documentation for C programmers.
diff --git a/Doc/libstring.tex b/Doc/libstring.tex
index 0c9ad7d..960e94b 100644
--- a/Doc/libstring.tex
+++ b/Doc/libstring.tex
@@ -61,14 +61,25 @@
preceded by a sign (\samp{+} or \samp{-}).
\end{funcdesc}
-\begin{funcdesc}{atoi}{s}
-Convert a string to an integer. The string must consist of one or more
-digits, optionally preceded by a sign (\samp{+} or \samp{-}).
+\begin{funcdesc}{atoi}{s\optional{\, base}}
+Convert string \var{s} to an integer in the given \var{base}. The
+string must consist of one or more digits, optionally preceded by a
+sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it is
+0, a default base is chosen depending on the leading characters of the
+string (after stripping the sign): \samp{0x} or \samp{0X} means 16,
+\samp{0} means 8, anything else means 10. If \var{base} is 16, a
+leading \samp{0x} or \samp{0X} is always accepted. (Note: for a more
+flexible interpretation of numeric literals, use the built-in function
+\code{eval()}.
+\bifuncindex{eval}
\end{funcdesc}
-\begin{funcdesc}{atol}{s}
-Convert a string to a long integer. The string must consist of one
-or more digits, optionally preceded by a sign (\samp{+} or \samp{-}).
+\begin{funcdesc}{atol}{s\optional{\, base}}
+Convert string \var{s} to a long integer in the given \var{base}. The
+string must consist of one or more digits, optionally preceded by a
+sign (\samp{+} or \samp{-}). The \var{base} argument has the same
+meaning as for \code{atoi()}. A trailing \samp{l} or \samp{L} is not
+allowed.
\end{funcdesc}
\begin{funcdesc}{expandtabs}{s\, tabsize}
@@ -101,10 +112,11 @@
not found.
\end{funcdesc}
-\begin{funcdesc}{count}{s\, sub\optional{\, i}}
+\begin{funcdesc}{count}{s\, sub\optional{\, start}}
Return the number of (non-overlapping) occurrences of substring
-\var{sub} in string \var{s} with index at least \var{i}.
-If \var{i} is omitted, it defaults to \code{0}.
+\var{sub} in string \var{s} with index at least \var{start}.
+If \var{start} is omitted, it defaults to \code{0}. If \var{start} is
+negative, \code{len(\var{s})} is added.
\end{funcdesc}
\begin{funcdesc}{lower}{s}
diff --git a/Doc/libstruct.tex b/Doc/libstruct.tex
index 280fe55..a2c1b10 100644
--- a/Doc/libstruct.tex
+++ b/Doc/libstruct.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{struct}}
+\section{Built-in Module \sectcode{struct}}
\bimodindex{struct}
\indexii{C}{structures}
diff --git a/Doc/libsun.tex b/Doc/libsun.tex
index 9624b9c..d297b9c 100644
--- a/Doc/libsun.tex
+++ b/Doc/libsun.tex
@@ -4,7 +4,7 @@
that are unique to the SunOS operating system (versions 4 and 5; the
latter is also known as SOLARIS version 2).
-\section{Built-in module \sectcode{sunaudiodev}}
+\section{Built-in Module \sectcode{sunaudiodev}}
\bimodindex{sunaudiodev}
This module allows you to access the sun audio interface. The sun
@@ -30,7 +30,7 @@
only for the activity needed. See the audio manpage for details.
\end{funcdesc}
-\subsection{Audio device object methods}
+\subsection{Audio Device Objects}
The audio device objects are returned by \code{open} define the
following methods (except \code{control} objects which only provide
@@ -108,6 +108,5 @@
\file{<sun/audioio.h>}, with the leading string \samp{AUDIO_} stripped.
Useability of the control device is limited at the moment, since there
-is no way to use the 'wait for something to happen' feature the device
-provides. This is because that feature makes heavy use of signals, and
-these do not map too well onto Python.
+is no way to use the ``wait for something to happen'' feature the
+device provides.
diff --git a/Doc/libsys.tex b/Doc/libsys.tex
index ffda68d..8899052 100644
--- a/Doc/libsys.tex
+++ b/Doc/libsys.tex
@@ -6,11 +6,16 @@
It is always available.
\renewcommand{\indexsubitem}{(in module sys)}
+
\begin{datadesc}{argv}
The list of command line arguments passed to a Python script.
- \code{sys.argv[0]} is the script name.
+ \code{sys.argv[0]} is the script name (it is operating system
+ dependent whether this is a full pathname or not).
+ If the command was executed using the \samp{-c} command line option
+ to the interpreter, \code{sys.argv[0]} is set to the string
+ \code{"-c"}.
If no script name was passed to the Python interpreter,
- \code{sys.argv} is empty.
+ \code{sys.argv} has zero length.
\end{datadesc}
\begin{datadesc}{builtin_module_names}
@@ -28,9 +33,11 @@
invoked. Their meaning is: \code{exc_type} gets the exception type of
the exception being handled; \code{exc_value} gets the exception
parameter (its \dfn{associated value} or the second argument to
- \code{raise}); \code{exc_traceback} gets a traceback object which
+ \code{raise}); \code{exc_traceback} gets a traceback object (see the
+ Reference Manual) which
encapsulates the call stack at the point where the exception
originally occurred.
+\obindex{traceback}
\end{datadesc}
\begin{funcdesc}{exit}{n}
@@ -45,7 +52,7 @@
This value is not actually defined by the module, but can be set by
the user (or by a program) to specify a clean-up action at program
exit. When set, it should be a parameterless function. This function
- will be called when the interpreter exits in any way (but not when a
+ will be called when the interpreter exits in any way (except not when a
fatal error occurs: in that case the interpreter's internal state
cannot be trusted).
\end{datadesc}
@@ -94,26 +101,23 @@
\begin{funcdesc}{settrace}{tracefunc}
Set the system's trace function, which allows you to implement a
- Python source code debugger in Python. The standard modules
- \code{pdb} and \code{wdb} are such debuggers; the difference is that
- \code{wdb} uses windows and needs STDWIN, while \code{pdb} has a
- line-oriented interface not unlike dbx. See the file \file{pdb.doc}
- in the Python library source directory for more documentation (both
- about \code{pdb} and \code{sys.trace}).
+ Python source code debugger in Python. See section ``How It Works''
+ in the chapter on the Python Debugger.
\end{funcdesc}
-\ttindex{pdb}
-\ttindex{wdb}
\index{trace function}
+\index{debugger}
\begin{funcdesc}{setprofile}{profilefunc}
Set the system's profile function, which allows you to implement a
- Python source code profiler in Python. The system's profile function
+ Python source code profiler in Python. See the chapter on the
+ Python Profiler. The system's profile function
is called similarly to the system's trace function (see
\code{sys.settrace}), but it isn't called for each executed line of
code (only on call and return and when an exception occurs). Also,
its return value is not used, so it can just return \code{None}.
\end{funcdesc}
\index{profile function}
+\index{profiler}
\begin{datadesc}{stdin}
\dataline{stdout}
@@ -127,7 +131,11 @@
own prompts and (almost all of) its error messages go to
\code{sys.stderr}. \code{sys.stdout} and \code{sys.stderr} needn't
be built-in file objects: any object is acceptable as long as it has
- a \code{write} method that takes a string argument.
+ a \code{write} method that takes a string argument. (Changing these
+ objects doesn't affect the standard I/O streams of processes
+ executed by \code{popen()}, \code{system()} or the \code{exec*()}
+ family of functions in the \code{os} module.)
+\stmodindex{os}
\end{datadesc}
\begin{datadesc}{tracebacklimit}
diff --git a/Doc/libtempfile.tex b/Doc/libtempfile.tex
index f67821d..0a582e1 100644
--- a/Doc/libtempfile.tex
+++ b/Doc/libtempfile.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{tempfile}}
+\section{Standard Module \sectcode{tempfile}}
\stmodindex{tempfile}
\indexii{temporary}{file name}
\indexii{temporary}{file}
diff --git a/Doc/libtemplate.tex b/Doc/libtemplate.tex
index a7f70ae..9b85178 100644
--- a/Doc/libtemplate.tex
+++ b/Doc/libtemplate.tex
@@ -7,7 +7,7 @@
% \section{} generates the section header,
% \bimodindex{} or \stmodundex{} generates an index entry for this module
-\section{Built-in module \sectcode{spam}} % If implemented in C
+\section{Built-in Module \sectcode{spam}} % If implemented in C
\bimodindex[spam}
\section{Standard module \sectcode{spam}} % If implemented in Python
@@ -110,7 +110,7 @@
% separate subsection. It is important to redefine ``indexsubitem''
% for each subsection.
-\subsection{Spam methods}
+\subsection{Spam Objects}
Spam objects (returned by \code{open()} above) have the following
methods.
diff --git a/Doc/libthread.tex b/Doc/libthread.tex
index 7147ebf..bd81d7c 100644
--- a/Doc/libthread.tex
+++ b/Doc/libthread.tex
@@ -26,18 +26,22 @@
then the thread exits (but other threads continue to run).
\end{funcdesc}
-\begin{funcdesc}{exit_thread}{}
-Exit the current thread silently. Other threads continue to run.
-\strong{Caveat:} code in pending \code{finally} clauses is not executed.
+\begin{funcdesc}{exit}{}
+This is a shorthand for \code{thread.exit_thread()}.
\end{funcdesc}
-\begin{funcdesc}{exit_prog}{status}
-Exit all threads and report the value of the integer argument
-\var{status} as the exit status of the entire program.
-\strong{Caveat:} code in pending \code{finally} clauses, in this thread
-or in other threads, is not executed.
+\begin{funcdesc}{exit_thread}{}
+Raise the \code{SystemExit} exception. When not caught, this will
+cause the thread to exit silently.
\end{funcdesc}
+%\begin{funcdesc}{exit_prog}{status}
+%Exit all threads and report the value of the integer argument
+%\var{status} as the exit status of the entire program.
+%\strong{Caveat:} code in pending \code{finally} clauses, in this thread
+%or in other threads, is not executed.
+%\end{funcdesc}
+
\begin{funcdesc}{allocate_lock}{}
Return a new lock object. Methods of locks are described below. The
lock is initially unlocked.
@@ -82,18 +86,16 @@
\item
Threads interact strangely with interrupts: the
\code{KeyboardInterrupt} exception will be received by an arbitrary
-thread.
+thread. (When the \code{signal} module is available, interrupts
+always go to the main thread.)
\item
-Calling \code{sys.exit(\var{status})} or executing
-\code{raise SystemExit, \var{status}} is almost equivalent to calling
-\code{thread.exit_prog(\var{status})}, except that the former ways of
-exiting the entire program do honor \code{finally} clauses in the
-current thread (but not in other threads).
+Calling \code{sys.exit()} or raising the \code{SystemExit} is
+equivalent to calling \code{thread.exit_thread()}.
\item
Not all built-in functions that may block waiting for I/O allow other
-threads to run, although the most popular ones (\code{sleep},
-\code{read}, \code{select}) work as expected.
+threads to run. (The most popular ones (\code{sleep}, \code{read},
+\code{select}) work as expected.)
\end{itemize}
diff --git a/Doc/libtime.tex b/Doc/libtime.tex
index 1bc5ffa..746e21e 100644
--- a/Doc/libtime.tex
+++ b/Doc/libtime.tex
@@ -11,8 +11,7 @@
\item
The ``epoch'' is the point where the time starts. On January 1st of that
year, at 0 hours, the ``time since the epoch'' is zero. For UNIX, the
-epoch is 1970. To find out what the epoch is, look at the first
-element of \code{gmtime(0)}.
+epoch is 1970. To find out what the epoch is, look at \code{gmtime(0)}.
\item
UTC is Coordinated Universal Time (formerly known as Greenwich Mean
@@ -30,19 +29,20 @@
\item
The precision of the various real-time functions may be less than
suggested by the units in which their value or argument is expressed.
-E.g.\ on most UNIX systems, the clock ``ticks'' only every 1/50th or
-1/100th of a second, and on the Mac, it ticks 60 times a second.
+E.g.\ on most UNIX systems, the clock ``ticks'' only 50 or 100 times a
+second, and on the Mac, times are only accurate to whole seconds.
\end{itemize}
-Functions and data items are:
+The module defines the following functions and data items:
\renewcommand{\indexsubitem}{(in module time)}
\begin{datadesc}{altzone}
The offset of the local DST timezone, in seconds west of the 0th
-meridian, if one is defined. Only use this if \code{daylight} is
-nonzero.
+meridian, if one is defined. Negative if the local DST timezone is
+east of the 0th meridian (as in Western Europe, including the UK).
+Only use this if \code{daylight} is nonzero.
\end{datadesc}
@@ -56,8 +56,8 @@
\begin{funcdesc}{clock}{}
Return the current CPU time as a floating point number expressed in
-seconds. The precision depends on that of the C function by the same
-name.
+seconds. The precision, and in fact the very definiton of the meaning
+of ``CPU time'', depends on that of the C function of the same name.
\end{funcdesc}
diff --git a/Doc/libtraceback.tex b/Doc/libtraceback.tex
index 38d91ea..ca9c374 100644
--- a/Doc/libtraceback.tex
+++ b/Doc/libtraceback.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{traceback}}
+\section{Standard Module \sectcode{traceback}}
\stmodindex{traceback}
\renewcommand{\indexsubitem}{(in module traceback)}
diff --git a/Doc/libtypes.tex b/Doc/libtypes.tex
index d93c402..a438d44 100644
--- a/Doc/libtypes.tex
+++ b/Doc/libtypes.tex
@@ -189,7 +189,7 @@
truncate as in \C{}; see functions \code{floor} and \code{ceil} in module
\code{math} for well-defined conversions.
\indexii{numeric}{conversions}
-\ttindex{math}
+\stmodindex{math}
\indexii{\C{}}{language}
\item[(2)]
@@ -205,7 +205,7 @@
\end{description}
% XXXJH exceptions: overflow (when? what operations?) zerodivision
-\subsubsection{Bit-string Operations on Integer Types.}
+\subsubsection{Bit-string Operations on Integer Types}
Plain and long integer types support additional operations that make
sense only for bit-strings. Negative numbers are treated as their 2's
@@ -287,7 +287,7 @@
\end{description}
-\subsubsection{More String Operations.}
+\subsubsection{More String Operations}
String objects have one unique built-in operation: the \code{\%}
operator (modulo) with a string left argument interprets this string
@@ -307,7 +307,7 @@
object and converts it to a string using \code{str()} before
formatting it. The ANSI features \code{\%p} and \code{\%n}
are not supported. Since Python strings have an explicit length,
-\code{\%s} conversions don't assume that \code{'\\0'} is the end of
+\code{\%s} conversions don't assume that \code{'\e0'} is the end of
the string.
For safety reasons, floating point precisions are clipped to 50;
@@ -330,14 +330,15 @@
Python has 002 quote types.
>>>
\end{verbatim}
-In this case no * specifiers may occur in a format.
+In this case no * specifiers may occur in a format (since they a
+require sequential parameter list).
Additional string operations are defined in standard module
\code{string} and in built-in module \code{regex}.
\index{string}
\index{regex}
-\subsubsection{Mutable Sequence Types.}
+\subsubsection{Mutable Sequence Types}
List objects support additional operations that allow in-place
modification of the object.
@@ -399,7 +400,7 @@
should return \code{-1}, \code{0} or \code{1} depending on whether the
first argument is considered smaller than, equal to, or larger than the
second argument. Note that this slows the sorting process down
- considerably; e.g. to sort an array in reverse order it is much faster
+ considerably; e.g. to sort a list in reverse order it is much faster
to use calls to \code{sort()} and \code{reverse()} than to use
\code{sort()} with a comparison function that reverses the ordering of
the elements.
@@ -409,7 +410,7 @@
A \dfn{mapping} object maps values of one type (the key type) to
arbitrary objects. Mappings are mutable objects. There is currently
-only one mapping type, the \dfn{dictionary}. A dictionary's keys are
+only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are
almost arbitrary values. The only types of values not acceptable as
keys are values containing lists or dictionaries or other mutable
types that are compared by value rather than by object identity.
@@ -421,9 +422,9 @@
\indexii{dictionary}{type}
Dictionaries are created by placing a comma-separated list of
-\code{\var{key}: \var{value}} pairs within braces, for example:
-\code{\{'jack': 4098, 'sjoerd: 4127\}} or
-\code{\{4098: 'jack', 4127: 'sjoerd\}}.
+\code{\var{key}:\ \var{value}} pairs within braces, for example:
+\code{\{'jack':\ 4098, 'sjoerd':\ 4127\}} or
+\code{\{4098:\ 'jack', 4127:\ 'sjoerd'\}}.
The following operations are defined on mappings (where \var{a} is a
mapping, \var{k} is a key and \var{x} is an arbitrary object):
@@ -453,9 +454,7 @@
\begin{description}
\item[(1)] Raises an exception if \var{k} is not in the map.
-\item[(2)] Keys and values are listed in random order, but at any
-moment the ordering of the \code{keys()}, \code{values()} and
-\code{items()} lists is the consistent with each other.
+\item[(2)] Keys and values are listed in random order.
\end{description}
\subsection{Other Built-in Types}
@@ -463,7 +462,7 @@
The interpreter supports several other kinds of objects.
Most of these support only one or two operations.
-\subsubsection{Modules.}
+\subsubsection{Modules}
The only special operation on a module is attribute access:
\code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} accesses
@@ -483,11 +482,11 @@
Modules are written like this: \code{<module 'sys'>}.
-\subsubsection{Classes and Class Instances.}
+\subsubsection{Classes and Class Instances}
% XXXJH cross ref here
(See the Python Reference Manual for these.)
-\subsubsection{Functions.}
+\subsubsection{Functions}
Function objects are created by function definitions. The only
operation on a function object is to call it:
@@ -504,7 +503,7 @@
global name space (this is the same as \code{\var{m}.__dict__} where
\var{m} is the module in which the function \var{f} was defined).
-\subsubsection{Methods.}
+\subsubsection{Methods}
\obindex{method}
Methods are functions that are called using the attribute notation.
@@ -522,7 +521,7 @@
(See the Python Reference Manual for more info.)
-\subsubsection{Code Objects.}
+\subsubsection{Code Objects}
\obindex{code}
Code objects are used by the implementation to represent
@@ -543,7 +542,7 @@
(See the Python Reference Manual for more info.)
-\subsubsection{Type Objects.}
+\subsubsection{Type Objects}
Type objects represent the various object types. An object's type is
% XXXJH xref here
@@ -552,7 +551,7 @@
Types are written like this: \code{<type 'int'>}.
-\subsubsection{The Null Object.}
+\subsubsection{The Null Object}
This object is returned by functions that don't explicitly return a
value. It supports no special operations. There is exactly one null
@@ -560,7 +559,7 @@
It is written as \code{None}.
-\subsubsection{File Objects.}
+\subsubsection{File Objects}
File objects are implemented using \C{}'s \code{stdio} package and can be
% XXXJH xref here
@@ -643,7 +642,7 @@
does not add line separators.)
\end{funcdesc}
-\subsubsection{Internal Objects.}
+\subsubsection{Internal Objects}
(See the Python Reference Manual for these.)
diff --git a/Doc/libtypes2.tex b/Doc/libtypes2.tex
index 2280ed7..d0f20c9 100644
--- a/Doc/libtypes2.tex
+++ b/Doc/libtypes2.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{types}}
+\section{Standard Module \sectcode{types}}
\stmodindex{types}
\renewcommand{\indexsubitem}{(in module types)}
diff --git a/Doc/liburllib.tex b/Doc/liburllib.tex
index aa672d4..b26228f 100644
--- a/Doc/liburllib.tex
+++ b/Doc/liburllib.tex
@@ -1,7 +1,7 @@
-\section{Built-in module \sectcode{urllib}}
+\section{Standard Module \sectcode{urllib}}
\stmodindex{urllib}
\index{WWW}
-\indexii{World-Wide}{Web}
+\index{World-Wide Web}
\index{URL}
\renewcommand{\indexsubitem}{(in module urllib)}
@@ -17,7 +17,7 @@
\begin{funcdesc}{urlopen}{url}
Open a network object denoted by a URL for reading. If the URL does
-not have a scheme identifier, or if it has \code{file:} as its scheme
+not have a scheme identifier, or if it has \samp{file:} as its scheme
identifier, this opens a local file; otherwise it opens a socket to a
server somewhere on the network. If the connection cannot be made, or
if the server returns an error code, the \code{IOError} exception is
@@ -26,7 +26,9 @@
\code{readlines()}, \code{fileno()}, \code{close()} and \code{info()}.
Except for the last one, these methods have the same interface as for
file objects --- see the section on File Objects earlier in this
-manual.
+manual. (It's not a built-in file object, however, so it can't be
+used at those few places where a true built-in file object is
+required.)
The \code{info()} method returns an instance of the class
\code{rfc822.Message} containing the headers received from the server,
diff --git a/Doc/liburlparse.tex b/Doc/liburlparse.tex
index 6fa2a37..c35d032 100644
--- a/Doc/liburlparse.tex
+++ b/Doc/liburlparse.tex
@@ -1,7 +1,7 @@
-\section{Built-in module \sectcode{urlparse}}
+\section{Standard Module \sectcode{urlparse}}
\stmodindex{urlparse}
\index{WWW}
-\indexii{World-Wide}{Web}
+\index{World-Wide Web}
\index{URL}
\indexii{URL}{parsing}
\indexii{relative}{URL}
@@ -28,14 +28,14 @@
Each tuple item is a string, possibly empty.
The components are not broken up in smaller parts (e.g. the network
location is a single string), and \% escapes are not expanded.
-The delimiters as shown above are not part of the tuple items, {\em
-except} for a leading slash in the \var{path} component, which is
-kept if present.
+The delimiters as shown above are not part of the tuple items,
+except for a leading slash in the \var{path} component, which is
+retained if present.
Example:
\code{urlparse('http://www.cwi.nl:80/\%7eguido/Python.html')}
yields the tuple
-\code{('http', 'www.cwi.nl:80', '/\%e7guido/Python.html', '', '', '')}.
+\code{('http', 'www.cwi.nl:80', '/\%7eguido/Python.html', '', '', '')}.
If the \var{default_scheme} argument is specified, it gives the
default addressing scheme, to be used only if the URL string does not
diff --git a/Doc/libwww.tex b/Doc/libwww.tex
index 9e09aa1..60dc62f 100644
--- a/Doc/libwww.tex
+++ b/Doc/libwww.tex
@@ -1,6 +1,7 @@
-\chapter{WORLD-WIDE WEB EXTENSIONS}
+\chapter{THE INTERNET AND THE WORLD-WIDE WEB}
\index{WWW}
-\indexii{World-Wide}{Web}
+\index{Internet}
+\index{World-Wide Web}
The modules described in this chapter provide various services to
World-Wide Web (WWW) clients and/or services, and a few modules
diff --git a/Doc/mac/libctb.tex b/Doc/mac/libctb.tex
index 3928498..1cda336 100644
--- a/Doc/mac/libctb.tex
+++ b/Doc/mac/libctb.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{ctb}}
+\section{Built-in Module \sectcode{ctb}}
\bimodindex{ctb}
\renewcommand{\indexsubitem}{(in module ctb)}
@@ -44,7 +44,7 @@
For all connection methods that take a \var{timeout} argument, a value
of \code{-1} is indefinite, meaning that the command runs to completion.
-\renewcommand{\indexsubitem}{(connection object method)}
+\renewcommand{\indexsubitem}{(connection object attribute)}
\begin{datadesc}{callback}
If this member is set to a value other than \code{None} it should point
@@ -59,6 +59,8 @@
\end{datadesc}
+\renewcommand{\indexsubitem}{(connection object method)}
+
\begin{funcdesc}{Open}{timeout}
Open an outgoing connection, waiting at most \var{timeout} seconds for
the connection to be established.
diff --git a/Doc/mac/libmac.tex b/Doc/mac/libmac.tex
index 62babda..545b62c 100644
--- a/Doc/mac/libmac.tex
+++ b/Doc/mac/libmac.tex
@@ -2,7 +2,7 @@
The modules in this chapter are available on the Apple Macintosh only.
-\section{Built-in module \sectcode{mac}}
+\section{Built-in Module \sectcode{mac}}
\bimodindex{mac}
This module provides a subset of the operating system dependent
@@ -22,7 +22,7 @@
\code{unlink},
as well as the exception \code{error}.
-\section{Standard module \sectcode{macpath}}
+\section{Standard Module \sectcode{macpath}}
\stmodindex{macpath}
This module provides a subset of the pathname manipulation functions
diff --git a/Doc/mac/libmacconsole.tex b/Doc/mac/libmacconsole.tex
index 2f60890..42d4e51 100644
--- a/Doc/mac/libmacconsole.tex
+++ b/Doc/mac/libmacconsole.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macconsole}}
+\section{Built-in Module \sectcode{macconsole}}
\bimodindex{macconsole}
\renewcommand{\indexsubitem}{(in module macconsole)}
@@ -62,7 +62,7 @@
\subsection{console window object}
-\renewcommand{\indexsubitem}{(console window method)}
+\renewcommand{\indexsubitem}{(console window attribute)}
\begin{datadesc}{file}
The file object corresponding to this console window. If the file is
@@ -70,6 +70,8 @@
and \code{read()} calls.
\end{datadesc}
+\renewcommand{\indexsubitem}{(console window method)}
+
\begin{funcdesc}{setmode}{mode}
Set the input mode of the console to \var{C_ECHO}, etc.
\end{funcdesc}
diff --git a/Doc/mac/libmacdnr.tex b/Doc/mac/libmacdnr.tex
index ca75971..cd3625c 100644
--- a/Doc/mac/libmacdnr.tex
+++ b/Doc/mac/libmacdnr.tex
@@ -1,5 +1,5 @@
-\section{Built-in module \sectcode{macdnr}}
+\section{Built-in Module \sectcode{macdnr}}
\bimodindex{macdnr}
This module provides an interface to the Macintosh Domain Name
@@ -75,6 +75,8 @@
Return 1 if the query is complete.
\end{funcdesc}
+\renewcommand{\indexsubitem}{(dnr result object attribute)}
+
\begin{datadesc}{rtnCode}
The error code returned by the query.
\end{datadesc}
diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex
index 80ec76d..74d1970 100644
--- a/Doc/mac/libmacfs.tex
+++ b/Doc/mac/libmacfs.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macfs}}
+\section{Built-in Module \sectcode{macfs}}
\bimodindex{macfs}
\renewcommand{\indexsubitem}{(in module macfs)}
@@ -18,11 +18,14 @@
\begin{funcdesc}{RawFSSpec}{data}
Create an FSSpec object given the raw data for the C structure for the
-FSSpec.
+FSSpec as a string. This is mainly useful if you have obtained an
+FSSpec structure over a network.
\end{funcdesc}
\begin{funcdesc}{RawAlias}{data}
-Create an Alias object given the raw data for the alias.
+Create an Alias object given the raw data for the C structure for the
+alias as a string. This is mainly useful if you have obtained an
+FSSpec structure over a network.
\end{funcdesc}
\begin{funcdesc}{ResolveAliasFile}{file}
@@ -56,12 +59,13 @@
\subsection{FSSpec objects}
-\renewcommand{\indexsubitem}{(FSSpec object method)}
+\renewcommand{\indexsubitem}{(FSSpec object attribute)}
\begin{datadesc}{data}
The raw data from the FSSpec object, suitable for passing
to other applications, for instance.
\end{datadesc}
+\renewcommand{\indexsubitem}{(FSSpec object method)}
\begin{funcdesc}{as_pathname}{}
Return the full pathname of the file described by the FSSpec object.
\end{funcdesc}
@@ -91,12 +95,13 @@
\subsection{alias objects}
-\renewcommand{\indexsubitem}{(alias object method)}
+\renewcommand{\indexsubitem}{(alias object attribute)}
\begin{datadesc}{data}
The raw data for the Alias record, suitable for storing in a resource
or transmitting to other programs.
\end{datadesc}
+\renewcommand{\indexsubitem}{(alias object method)}
\begin{funcdesc}{Resolve}{\optional{file}}
Resolve the alias. If the alias was created as a relative alias you
should pass the file relative to which it is. Return the FSSpec for
diff --git a/Doc/mac/libmacspeech.tex b/Doc/mac/libmacspeech.tex
index 737016e..7480482 100644
--- a/Doc/mac/libmacspeech.tex
+++ b/Doc/mac/libmacspeech.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{macspeech}}
+\section{Built-in Module \sectcode{macspeech}}
\bimodindex{macspeech}
\renewcommand{\indexsubitem}{(in module macspeech)}
diff --git a/Doc/mac/libmactcp.tex b/Doc/mac/libmactcp.tex
index 11c0114..561284b 100644
--- a/Doc/mac/libmactcp.tex
+++ b/Doc/mac/libmactcp.tex
@@ -1,5 +1,6 @@
-\section{Built-in module \sectcode{mactcp}}
+\section{Built-in Module \sectcode{mactcp}}
\bimodindex{mactcp}
+
\renewcommand{\indexsubitem}{(in module mactcp)}
This module provides an interface to the Macintosh TCP/IP driver
@@ -37,8 +38,9 @@
datagrams on, a value of zero will make MacTCP select a free port.
\end{funcdesc}
-\subsection{TCP stream objects}
-\renewcommand{\indexsubitem}{(TCP stream method)}
+\subsection{TCP Stream Objects}
+
+\renewcommand{\indexsubitem}{(TCP stream attribute)}
\begin{datadesc}{asr}
When set to a value different than \code{None} this should point to a
@@ -50,6 +52,8 @@
It is safe to do further calls from the \code{asr}.
\end{datadesc}
+\renewcommand{\indexsubitem}{(TCP stream method)}
+
\begin{funcdesc}{PassiveOpen}{port}
Wait for an incoming connection on TCP port \var{port} (zero makes the
system pick a free port). The call returns immediately, and you should
@@ -104,15 +108,17 @@
\end{funcdesc}
\begin{funcdesc}{Status}{}
-Return a TCP status object for this stream.
+Return a TCP status object for this stream giving the current status
+(see below).
\end{funcdesc}
-\subsection{TCP status objects}
+\subsection{TCP Status Objects}
This object has no methods, only some members holding information on
the connection. A complete description of all fields in this objects
can be found in the Apple documentation. The most interesting ones are:
-\renewcommand{\indexsubitem}{(TCP status method)}
+\renewcommand{\indexsubitem}{(TCP status attribute)}
+
\begin{datadesc}{localHost}
\dataline{localPort}
\dataline{remoteHost}
@@ -137,11 +143,11 @@
-\subsection{UDP stream objects}
+\subsection{UDP Stream Objects}
Note that, unlike the name suggests, there is nothing stream-like
about UDP.
-\renewcommand{\indexsubitem}{(UDP stream method)}
+\renewcommand{\indexsubitem}{(UDP stream attribute)}
\begin{datadesc}{asr}
The asynchronous service routine to be called on events such as
@@ -153,9 +159,11 @@
A read-only member giving the port number of this UDP stream.
\end{datadesc}
+\renewcommand{\indexsubitem}{(UDP stream method)}
+
\begin{funcdesc}{Read}{timeout}
Read a datagram, waiting at most \var{timeout} seconds ($-1$ is
-indefinite). Return the data.
+infinite). Return the data.
\end{funcdesc}
\begin{funcdesc}{Write}{host\, port\, buf}
diff --git a/Doc/templates/module.tex b/Doc/templates/module.tex
index a7f70ae..9b85178 100644
--- a/Doc/templates/module.tex
+++ b/Doc/templates/module.tex
@@ -7,7 +7,7 @@
% \section{} generates the section header,
% \bimodindex{} or \stmodundex{} generates an index entry for this module
-\section{Built-in module \sectcode{spam}} % If implemented in C
+\section{Built-in Module \sectcode{spam}} % If implemented in C
\bimodindex[spam}
\section{Standard module \sectcode{spam}} % If implemented in Python
@@ -110,7 +110,7 @@
% separate subsection. It is important to redefine ``indexsubitem''
% for each subsection.
-\subsection{Spam methods}
+\subsection{Spam Objects}
Spam objects (returned by \code{open()} above) have the following
methods.