AMK's megapatch:
* \bcode, \ecode added everywhere
* \label{module-foo} added everywhere
* A few \seealso sections added.
* Indentation fixed inside verbatim in lib*tex files
diff --git a/Doc/ext.tex b/Doc/ext.tex
index d168aa6..af4a667 100644
--- a/Doc/ext.tex
+++ b/Doc/ext.tex
@@ -82,11 +82,11 @@
returns an integer. We want this function to be callable from Python
as follows:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import spam
>>> status = spam.system("ls -l")
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Begin by creating a file \samp{spammodule.c}. (In general, if a
module is called \samp{spam}, the C file containing its implementation
is called \file{spammodule.c}; if the module name is very long, like
@@ -94,10 +94,10 @@
The first line of our file can be:
-\begin{verbatim}
+\bcode\begin{verbatim}
#include "Python.h"
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
which pulls in the Python API (you can add a comment describing the
purpose of the module and a copyright notice if you like).
@@ -114,7 +114,7 @@
be called when the Python expression \samp{spam.system(\var{string})}
is evaluated (we'll see shortly how it ends up being called):
-\begin{verbatim}
+\bcode\begin{verbatim}
static PyObject *
spam_system(self, args)
PyObject *self;
@@ -127,8 +127,8 @@
sts = system(command);
return Py_BuildValue("i", sts);
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
There is a straightforward translation from the argument list in
Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
passed to the C function. The C function always has two arguments,
@@ -252,15 +252,15 @@
For this, you usually declare a static object variable at the
beginning of your file, e.g.
-\begin{verbatim}
+\bcode\begin{verbatim}
static PyObject *SpamError;
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
and initialize it in your module's initialization function
(\code{initspam()}) with a string object, e.g. (leaving out the error
checking for now):
-\begin{verbatim}
+\bcode\begin{verbatim}
void
initspam()
{
@@ -270,8 +270,8 @@
SpamError = PyString_FromString("spam.error");
PyDict_SetItemString(d, "error", SpamError);
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Note that the Python name for the exception object is
\code{spam.error}. It is conventional for module and exception names
to be spelled in lower case. It is also conventional that the
@@ -284,11 +284,11 @@
Going back to our example function, you should now be able to
understand this statement:
-\begin{verbatim}
+\bcode\begin{verbatim}
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
It returns \code{NULL} (the error indicator for functions returning
object pointers) if an error is detected in the argument list, relying
on the exception set by \code{PyArg_ParseTuple()}. Otherwise the
@@ -301,10 +301,10 @@
The next statement is a call to the \UNIX{} function \code{system()},
passing it the string we just got from \code{PyArg_ParseTuple()}:
-\begin{verbatim}
+\bcode\begin{verbatim}
sts = system(command);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Our \code{spam.system()} function must return the value of \code{sts}
as a Python object. This is done using the function
\code{Py_BuildValue()}, which is something like the inverse of
@@ -312,10 +312,10 @@
number of C values, and returns a new Python object. More info on
\code{Py_BuildValue()} is given later.
-\begin{verbatim}
+\bcode\begin{verbatim}
return Py_BuildValue("i", sts);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
In this case, it will return an integer object. (Yes, even integers
are objects on the heap in Python!)
@@ -323,11 +323,11 @@
returning \code{void}), the corresponding Python function must return
\code{None}. You need this idiom to do so:
-\begin{verbatim}
+\bcode\begin{verbatim}
Py_INCREF(Py_None);
return Py_None;
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\code{Py_None} is the C name for the special Python object
\code{None}. It is a genuine Python object (not a \code{NULL}
pointer, which means ``error'' in most contexts, as we have seen).
@@ -339,15 +339,15 @@
programs. First, we need to list its name and address in a ``method
table'':
-\begin{verbatim}
+\bcode\begin{verbatim}
static PyMethodDef SpamMethods[] = {
...
{"system", spam_system, 1},
...
{NULL, NULL} /* Sentinel */
};
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Note the third entry (\samp{1}). This is a flag telling the
interpreter the calling convention to be used for the C function. It
should normally always be \samp{1}; a value of \samp{0} means that an
@@ -357,14 +357,14 @@
initialization function (which should be the only non-\code{static}
item defined in the module file):
-\begin{verbatim}
+\bcode\begin{verbatim}
void
initspam()
{
(void) Py_InitModule("spam", SpamMethods);
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
When the Python program imports module \code{spam} for the first time,
\code{initspam()} is called. It calls \code{Py_InitModule()}, which
creates a ``module object'' (which is inserted in the dictionary
@@ -392,10 +392,10 @@
the \file{Modules} directory, add a line to the file
\file{Modules/Setup} describing your file:
-\begin{verbatim}
+\bcode\begin{verbatim}
spam spammodule.o
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
and rebuild the interpreter by running \code{make} in the toplevel
directory. You can also run \code{make} in the \file{Modules}
subdirectory, but then you must first rebuilt the \file{Makefile}
@@ -405,11 +405,10 @@
If your module requires additional libraries to link with, these can
be listed on the line in the \file{Setup} file as well, for instance:
-\begin{verbatim}
+\bcode\begin{verbatim}
spam spammodule.o -lX11
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\section{Calling Python Functions From C}
So far we have concentrated on making C functions callable from
@@ -434,7 +433,7 @@
For example, the following function might be part of a module
definition:
-\begin{verbatim}
+\bcode\begin{verbatim}
static PyObject *my_callback = NULL;
static PyObject *
@@ -448,8 +447,8 @@
Py_INCREF(Py_None);
return Py_None;
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement
the reference count of an object and are safe in the presence of
\code{NULL} pointers. More info on them in the section on Reference
@@ -465,7 +464,7 @@
format string consists of zero or more format codes between
parentheses. For example:
-\begin{verbatim}
+\bcode\begin{verbatim}
int arg;
PyObject *arglist;
PyObject *result;
@@ -476,8 +475,8 @@
arglist = Py_BuildValue("(i)", arg);
result = PyEval_CallObject(my_callback, arglist);
Py_DECREF(arglist);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\code{PyEval_CallObject()} returns a Python object pointer: this is
the return value of the Python function. \code{PyEval_CallObject()} is
``reference-count-neutral'' with respect to its arguments. In the
@@ -499,13 +498,13 @@
or desirable, the exception should be cleared by calling
\code{PyErr_Clear()}. For example:
-\begin{verbatim}
+\bcode\begin{verbatim}
if (result == NULL)
return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Depending on the desired interface to the Python callback function,
you may also have to provide an argument list to \code{PyEval_CallObject()}.
In some cases the argument list is also provided by the Python
@@ -516,7 +515,7 @@
call \code{Py_BuildValue()}. For example, if you want to pass an integral
event code, you might use the following code:
-\begin{verbatim}
+\bcode\begin{verbatim}
PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
@@ -526,8 +525,8 @@
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Note the placement of \code{Py_DECREF(argument)} immediately after the call,
before the error check! Also note that strictly spoken this code is
not complete: \code{Py_BuildValue()} may run out of memory, and this should
@@ -538,10 +537,10 @@
The \code{PyArg_ParseTuple()} function is declared as follows:
-\begin{verbatim}
+\bcode\begin{verbatim}
int PyArg_ParseTuple(PyObject *arg, char *format, ...);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The \var{arg} argument must be a tuple object containing an argument
list passed from Python to a C function. The \var{format} argument
must be a format string, whose syntax is explained below. The
@@ -686,7 +685,7 @@
Some example calls:
-\begin{verbatim}
+\bcode\begin{verbatim}
int ok;
int i, j;
long k, l;
@@ -726,18 +725,17 @@
/* Possible Python call:
f(((0, 0), (400, 300)), (10, 10)) */
}
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\section{The {\tt Py_BuildValue()} Function}
This function is the counterpart to \code{PyArg_ParseTuple()}. It is
declared as follows:
-\begin{verbatim}
+\bcode\begin{verbatim}
PyObject *Py_BuildValue(char *format, ...);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
It recognizes a set of format units similar to the ones recognized by
\code{PyArg_ParseTuple()}, but the arguments (which are input to the
function, not output) must not be pointers, just values. It returns a
@@ -839,7 +837,7 @@
Examples (to the left the call, to the right the resulting Python value):
-\begin{verbatim}
+\bcode\begin{verbatim}
Py_BuildValue("") None
Py_BuildValue("i", 123) 123
Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
@@ -855,9 +853,8 @@
"abc", 123, "def", 456) {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\section{Reference Counts}
\subsection{Introduction}
@@ -1026,14 +1023,14 @@
\code{Py_DECREF()} on an unrelated object while borrowing a reference
to a list item. For instance:
-\begin{verbatim}
+\bcode\begin{verbatim}
bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
PyList_SetItem(list, 1, PyInt_FromLong(0L));
PyObject_Print(item, stdout, 0); /* BUG! */
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
This function first borrows a reference to \code{list[0]}, then
replaces \code{list[1]} with the value \code{0}, and finally prints
the borrowed reference. Looks harmless, right? But it's not!
@@ -1059,7 +1056,7 @@
temporarily increment the reference count. The correct version of the
function reads:
-\begin{verbatim}
+\bcode\begin{verbatim}
no_bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
Py_INCREF(item);
@@ -1067,8 +1064,8 @@
PyObject_Print(item, stdout, 0);
Py_DECREF(item);
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
This is a true story. An older version of Python contained variants
of this bug and someone spent a considerable amount of time in a C
debugger to figure out why his \code{__del__()} methods would fail...
@@ -1084,7 +1081,7 @@
complete. Obviously, the following function has the same problem as
the previous one:
-\begin{verbatim}
+\bcode\begin{verbatim}
bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
Py_BEGIN_ALLOW_THREADS
@@ -1092,8 +1089,8 @@
Py_END_ALLOW_THREADS
PyObject_Print(item, stdout, 0); /* BUG! */
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\subsection{NULL Pointers}
In general, functions that take object references as arguments don't
@@ -1300,20 +1297,20 @@
ld}(1). Unfortunately the invocation differs slightly per system.
On SunOS 4, use
-\begin{verbatim}
+\bcode\begin{verbatim}
ld spammodule.o -o spammodule.so
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
On Solaris 2, use
-\begin{verbatim}
+\bcode\begin{verbatim}
ld -G spammodule.o -o spammodule.so
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
On SGI IRIX 5, use
-\begin{verbatim}
+\bcode\begin{verbatim}
ld -shared spammodule.o -o spammodule.so
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
On other systems, consult the manual page for \code{ld}(1) to find what
flags, if any, must be used.
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
index d168aa6..af4a667 100644
--- a/Doc/ext/ext.tex
+++ b/Doc/ext/ext.tex
@@ -82,11 +82,11 @@
returns an integer. We want this function to be callable from Python
as follows:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import spam
>>> status = spam.system("ls -l")
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Begin by creating a file \samp{spammodule.c}. (In general, if a
module is called \samp{spam}, the C file containing its implementation
is called \file{spammodule.c}; if the module name is very long, like
@@ -94,10 +94,10 @@
The first line of our file can be:
-\begin{verbatim}
+\bcode\begin{verbatim}
#include "Python.h"
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
which pulls in the Python API (you can add a comment describing the
purpose of the module and a copyright notice if you like).
@@ -114,7 +114,7 @@
be called when the Python expression \samp{spam.system(\var{string})}
is evaluated (we'll see shortly how it ends up being called):
-\begin{verbatim}
+\bcode\begin{verbatim}
static PyObject *
spam_system(self, args)
PyObject *self;
@@ -127,8 +127,8 @@
sts = system(command);
return Py_BuildValue("i", sts);
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
There is a straightforward translation from the argument list in
Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
passed to the C function. The C function always has two arguments,
@@ -252,15 +252,15 @@
For this, you usually declare a static object variable at the
beginning of your file, e.g.
-\begin{verbatim}
+\bcode\begin{verbatim}
static PyObject *SpamError;
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
and initialize it in your module's initialization function
(\code{initspam()}) with a string object, e.g. (leaving out the error
checking for now):
-\begin{verbatim}
+\bcode\begin{verbatim}
void
initspam()
{
@@ -270,8 +270,8 @@
SpamError = PyString_FromString("spam.error");
PyDict_SetItemString(d, "error", SpamError);
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Note that the Python name for the exception object is
\code{spam.error}. It is conventional for module and exception names
to be spelled in lower case. It is also conventional that the
@@ -284,11 +284,11 @@
Going back to our example function, you should now be able to
understand this statement:
-\begin{verbatim}
+\bcode\begin{verbatim}
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
It returns \code{NULL} (the error indicator for functions returning
object pointers) if an error is detected in the argument list, relying
on the exception set by \code{PyArg_ParseTuple()}. Otherwise the
@@ -301,10 +301,10 @@
The next statement is a call to the \UNIX{} function \code{system()},
passing it the string we just got from \code{PyArg_ParseTuple()}:
-\begin{verbatim}
+\bcode\begin{verbatim}
sts = system(command);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Our \code{spam.system()} function must return the value of \code{sts}
as a Python object. This is done using the function
\code{Py_BuildValue()}, which is something like the inverse of
@@ -312,10 +312,10 @@
number of C values, and returns a new Python object. More info on
\code{Py_BuildValue()} is given later.
-\begin{verbatim}
+\bcode\begin{verbatim}
return Py_BuildValue("i", sts);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
In this case, it will return an integer object. (Yes, even integers
are objects on the heap in Python!)
@@ -323,11 +323,11 @@
returning \code{void}), the corresponding Python function must return
\code{None}. You need this idiom to do so:
-\begin{verbatim}
+\bcode\begin{verbatim}
Py_INCREF(Py_None);
return Py_None;
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\code{Py_None} is the C name for the special Python object
\code{None}. It is a genuine Python object (not a \code{NULL}
pointer, which means ``error'' in most contexts, as we have seen).
@@ -339,15 +339,15 @@
programs. First, we need to list its name and address in a ``method
table'':
-\begin{verbatim}
+\bcode\begin{verbatim}
static PyMethodDef SpamMethods[] = {
...
{"system", spam_system, 1},
...
{NULL, NULL} /* Sentinel */
};
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Note the third entry (\samp{1}). This is a flag telling the
interpreter the calling convention to be used for the C function. It
should normally always be \samp{1}; a value of \samp{0} means that an
@@ -357,14 +357,14 @@
initialization function (which should be the only non-\code{static}
item defined in the module file):
-\begin{verbatim}
+\bcode\begin{verbatim}
void
initspam()
{
(void) Py_InitModule("spam", SpamMethods);
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
When the Python program imports module \code{spam} for the first time,
\code{initspam()} is called. It calls \code{Py_InitModule()}, which
creates a ``module object'' (which is inserted in the dictionary
@@ -392,10 +392,10 @@
the \file{Modules} directory, add a line to the file
\file{Modules/Setup} describing your file:
-\begin{verbatim}
+\bcode\begin{verbatim}
spam spammodule.o
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
and rebuild the interpreter by running \code{make} in the toplevel
directory. You can also run \code{make} in the \file{Modules}
subdirectory, but then you must first rebuilt the \file{Makefile}
@@ -405,11 +405,10 @@
If your module requires additional libraries to link with, these can
be listed on the line in the \file{Setup} file as well, for instance:
-\begin{verbatim}
+\bcode\begin{verbatim}
spam spammodule.o -lX11
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\section{Calling Python Functions From C}
So far we have concentrated on making C functions callable from
@@ -434,7 +433,7 @@
For example, the following function might be part of a module
definition:
-\begin{verbatim}
+\bcode\begin{verbatim}
static PyObject *my_callback = NULL;
static PyObject *
@@ -448,8 +447,8 @@
Py_INCREF(Py_None);
return Py_None;
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement
the reference count of an object and are safe in the presence of
\code{NULL} pointers. More info on them in the section on Reference
@@ -465,7 +464,7 @@
format string consists of zero or more format codes between
parentheses. For example:
-\begin{verbatim}
+\bcode\begin{verbatim}
int arg;
PyObject *arglist;
PyObject *result;
@@ -476,8 +475,8 @@
arglist = Py_BuildValue("(i)", arg);
result = PyEval_CallObject(my_callback, arglist);
Py_DECREF(arglist);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\code{PyEval_CallObject()} returns a Python object pointer: this is
the return value of the Python function. \code{PyEval_CallObject()} is
``reference-count-neutral'' with respect to its arguments. In the
@@ -499,13 +498,13 @@
or desirable, the exception should be cleared by calling
\code{PyErr_Clear()}. For example:
-\begin{verbatim}
+\bcode\begin{verbatim}
if (result == NULL)
return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Depending on the desired interface to the Python callback function,
you may also have to provide an argument list to \code{PyEval_CallObject()}.
In some cases the argument list is also provided by the Python
@@ -516,7 +515,7 @@
call \code{Py_BuildValue()}. For example, if you want to pass an integral
event code, you might use the following code:
-\begin{verbatim}
+\bcode\begin{verbatim}
PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
@@ -526,8 +525,8 @@
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Note the placement of \code{Py_DECREF(argument)} immediately after the call,
before the error check! Also note that strictly spoken this code is
not complete: \code{Py_BuildValue()} may run out of memory, and this should
@@ -538,10 +537,10 @@
The \code{PyArg_ParseTuple()} function is declared as follows:
-\begin{verbatim}
+\bcode\begin{verbatim}
int PyArg_ParseTuple(PyObject *arg, char *format, ...);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The \var{arg} argument must be a tuple object containing an argument
list passed from Python to a C function. The \var{format} argument
must be a format string, whose syntax is explained below. The
@@ -686,7 +685,7 @@
Some example calls:
-\begin{verbatim}
+\bcode\begin{verbatim}
int ok;
int i, j;
long k, l;
@@ -726,18 +725,17 @@
/* Possible Python call:
f(((0, 0), (400, 300)), (10, 10)) */
}
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\section{The {\tt Py_BuildValue()} Function}
This function is the counterpart to \code{PyArg_ParseTuple()}. It is
declared as follows:
-\begin{verbatim}
+\bcode\begin{verbatim}
PyObject *Py_BuildValue(char *format, ...);
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
It recognizes a set of format units similar to the ones recognized by
\code{PyArg_ParseTuple()}, but the arguments (which are input to the
function, not output) must not be pointers, just values. It returns a
@@ -839,7 +837,7 @@
Examples (to the left the call, to the right the resulting Python value):
-\begin{verbatim}
+\bcode\begin{verbatim}
Py_BuildValue("") None
Py_BuildValue("i", 123) 123
Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
@@ -855,9 +853,8 @@
"abc", 123, "def", 456) {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\section{Reference Counts}
\subsection{Introduction}
@@ -1026,14 +1023,14 @@
\code{Py_DECREF()} on an unrelated object while borrowing a reference
to a list item. For instance:
-\begin{verbatim}
+\bcode\begin{verbatim}
bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
PyList_SetItem(list, 1, PyInt_FromLong(0L));
PyObject_Print(item, stdout, 0); /* BUG! */
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
This function first borrows a reference to \code{list[0]}, then
replaces \code{list[1]} with the value \code{0}, and finally prints
the borrowed reference. Looks harmless, right? But it's not!
@@ -1059,7 +1056,7 @@
temporarily increment the reference count. The correct version of the
function reads:
-\begin{verbatim}
+\bcode\begin{verbatim}
no_bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
Py_INCREF(item);
@@ -1067,8 +1064,8 @@
PyObject_Print(item, stdout, 0);
Py_DECREF(item);
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
This is a true story. An older version of Python contained variants
of this bug and someone spent a considerable amount of time in a C
debugger to figure out why his \code{__del__()} methods would fail...
@@ -1084,7 +1081,7 @@
complete. Obviously, the following function has the same problem as
the previous one:
-\begin{verbatim}
+\bcode\begin{verbatim}
bug(PyObject *list) {
PyObject *item = PyList_GetItem(list, 0);
Py_BEGIN_ALLOW_THREADS
@@ -1092,8 +1089,8 @@
Py_END_ALLOW_THREADS
PyObject_Print(item, stdout, 0); /* BUG! */
}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\subsection{NULL Pointers}
In general, functions that take object references as arguments don't
@@ -1300,20 +1297,20 @@
ld}(1). Unfortunately the invocation differs slightly per system.
On SunOS 4, use
-\begin{verbatim}
+\bcode\begin{verbatim}
ld spammodule.o -o spammodule.so
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
On Solaris 2, use
-\begin{verbatim}
+\bcode\begin{verbatim}
ld -G spammodule.o -o spammodule.so
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
On SGI IRIX 5, use
-\begin{verbatim}
+\bcode\begin{verbatim}
ld -shared spammodule.o -o spammodule.so
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
On other systems, consult the manual page for \code{ld}(1) to find what
flags, if any, must be used.
diff --git a/Doc/lib/libaifc.tex b/Doc/lib/libaifc.tex
index 04ed2e4..590f0d4 100644
--- a/Doc/lib/libaifc.tex
+++ b/Doc/lib/libaifc.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{aifc}}
+\label{module-aifc}
\stmodindex{aifc}
This module provides support for reading and writing AIFF and AIFF-C
diff --git a/Doc/lib/libal.tex b/Doc/lib/libal.tex
index 6a812dd..5655be6 100644
--- a/Doc/lib/libal.tex
+++ b/Doc/lib/libal.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{al}}
+\label{module-al}
\bimodindex{al}
This module provides access to the audio facilities of the SGI Indy
diff --git a/Doc/lib/libamoeba.tex b/Doc/lib/libamoeba.tex
index 54a9dfb..1ff5bd4 100644
--- a/Doc/lib/libamoeba.tex
+++ b/Doc/lib/libamoeba.tex
@@ -82,7 +82,7 @@
aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
>>>
\end{verbatim}\ecode
-
+%
The following methods are defined for capability objects.
\renewcommand{\indexsubitem}{(capability method)}
diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex
index 1b028b3..eb76251 100644
--- a/Doc/lib/libarray.tex
+++ b/Doc/lib/libarray.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{array}}
+\label{module-array}
\bimodindex{array}
\index{arrays}
diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex
index 40ef0f4..fb6c944 100644
--- a/Doc/lib/libaudioop.tex
+++ b/Doc/lib/libaudioop.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{audioop}}
+\label{module-audioop}
\bimodindex{audioop}
The \code{audioop} module contains some useful operations on sound fragments.
@@ -210,7 +211,7 @@
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
\end{verbatim}\ecode
-
+%
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
diff --git a/Doc/lib/libbase64.tex b/Doc/lib/libbase64.tex
index c487576..ab00ded 100644
--- a/Doc/lib/libbase64.tex
+++ b/Doc/lib/libbase64.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{base64}}
+\label{module-base64}
\stmodindex{base64}
This module perform base-64 encoding and decoding of arbitrary binary
diff --git a/Doc/lib/libbastion.tex b/Doc/lib/libbastion.tex
index 158ec08..dd30284 100644
--- a/Doc/lib/libbastion.tex
+++ b/Doc/lib/libbastion.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{Bastion}}
+\label{module-Bastion}
\stmodindex{Bastion}
\renewcommand{\indexsubitem}{(in module Bastion)}
diff --git a/Doc/lib/libbinascii.tex b/Doc/lib/libbinascii.tex
index 4e3d674..33974c8 100644
--- a/Doc/lib/libbinascii.tex
+++ b/Doc/lib/libbinascii.tex
@@ -1,4 +1,5 @@
\section{Standard module \sectcode{binhex}}
+\label{module-binhex}
\stmodindex{binhex}
This module encodes and decodes files in binhex4 format, a format
diff --git a/Doc/lib/libbltin.tex b/Doc/lib/libbltin.tex
index 63b7c63..6afcac9 100644
--- a/Doc/lib/libbltin.tex
+++ b/Doc/lib/libbltin.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{__builtin__}}
+\label{module-builtin}
\bimodindex{__builtin__}
This module provides direct access to all `built-in' identifiers of
diff --git a/Doc/lib/libcd.tex b/Doc/lib/libcd.tex
index 98ed560..6e64b77 100644
--- a/Doc/lib/libcd.tex
+++ b/Doc/lib/libcd.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{cd}}
+\label{module-cd}
\bimodindex{cd}
This module provides an interface to the Silicon Graphics CD library.
diff --git a/Doc/lib/libcgi.tex b/Doc/lib/libcgi.tex
index 4768f0f..56643d0 100644
--- a/Doc/lib/libcgi.tex
+++ b/Doc/lib/libcgi.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{cgi}}
+\label{module-cgi}
\stmodindex{cgi}
\indexii{WWW}{server}
\indexii{CGI}{protocol}
@@ -39,21 +40,21 @@
telling the client what kind of data is following. Python code to
generate a minimal header section looks like this:
-\begin{verbatim}
- print "Content-type: text/html" # HTML is following
- print # blank line, end of headers
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print "Content-type: text/html" # HTML is following
+print # blank line, end of headers
+\end{verbatim}\ecode
+%
The second section is usually HTML, which allows the client software
to display nicely formatted text with header, in-line images, etc.
Here's Python code that prints a simple piece of HTML:
-\begin{verbatim}
- print "<TITLE>CGI script output</TITLE>"
- print "<H1>This is my first CGI script</H1>"
- print "Hello, world!"
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print "<TITLE>CGI script output</TITLE>"
+print "<H1>This is my first CGI script</H1>"
+print "Hello, world!"
+\end{verbatim}\ecode
+%
(It may not be fully legal HTML according to the letter of the
standard, but any browser will understand it.)
@@ -76,19 +77,19 @@
\code{Content-type} header and blank line have already been printed) checks that
the fields \code{name} and \code{addr} are both set to a non-empty string:
-\begin{verbatim}
- form = cgi.FieldStorage()
- form_ok = 0
- if form.has_key("name") and form.has_key("addr"):
- if form["name"].value != "" and form["addr"].value != "":
- form_ok = 1
- if not form_ok:
- print "<H1>Error</H1>"
- print "Please fill in the name and addr fields."
- return
- ...further form processing here...
-\end{verbatim}
-
+\bcode\begin{verbatim}
+form = cgi.FieldStorage()
+form_ok = 0
+if form.has_key("name") and form.has_key("addr"):
+ if form["name"].value != "" and form["addr"].value != "":
+ form_ok = 1
+if not form_ok:
+ print "<H1>Error</H1>"
+ print "Please fill in the name and addr fields."
+ return
+...further form processing here...
+\end{verbatim}\ecode
+%
Here the fields, accessed through \code{form[key]}, are themselves instances
of \code{FieldStorage} (or \code{MiniFieldStorage}, depending on the form encoding).
@@ -100,40 +101,40 @@
instance or a list of instances. For example, here's code that
concatenates any number of username fields, separated by commas:
-\begin{verbatim}
- username = form["username"]
- if type(username) is type([]):
- # Multiple username fields specified
- usernames = ""
- for item in username:
- if usernames:
- # Next item -- insert comma
- usernames = usernames + "," + item.value
- else:
- # First item -- don't insert comma
- usernames = item.value
- else:
- # Single username field specified
- usernames = username.value
-\end{verbatim}
-
+\bcode\begin{verbatim}
+username = form["username"]
+if type(username) is type([]):
+ # Multiple username fields specified
+ usernames = ""
+ for item in username:
+ if usernames:
+ # Next item -- insert comma
+ usernames = usernames + "," + item.value
+ else:
+ # First item -- don't insert comma
+ usernames = item.value
+else:
+ # Single username field specified
+ usernames = username.value
+\end{verbatim}\ecode
+%
If a field represents an uploaded file, the value attribute reads the
entire file in memory as a string. This may not be what you want. You can
test for an uploaded file by testing either the filename attribute or the
file attribute. You can then read the data at leasure from the file
attribute:
-\begin{verbatim}
- fileitem = form["userfile"]
- if fileitem.file:
- # It's an uploaded file; count lines
- linecount = 0
- while 1:
- line = fileitem.file.readline()
- if not line: break
- linecount = linecount + 1
-\end{verbatim}
-
+\bcode\begin{verbatim}
+fileitem = form["userfile"]
+if fileitem.file:
+ # It's an uploaded file; count lines
+ linecount = 0
+ while 1:
+ line = fileitem.file.readline()
+ if not line: break
+ linecount = linecount + 1
+\end{verbatim}\ecode
+%
The file upload draft standard entertains the possibility of uploading
multiple files from one field (using a recursive \code{multipart/*}
encoding). When this occurs, the item will be a dictionary-like
@@ -251,10 +252,10 @@
that the first line of the script contains \code{\#!} starting in column 1
followed by the pathname of the Python interpreter, for instance:
-\begin{verbatim}
- #!/usr/local/bin/python
-\end{verbatim}
-
+\bcode\begin{verbatim}
+#!/usr/local/bin/python
+\end{verbatim}\ecode
+%
Make sure the Python interpreter exists and is executable by ``others''.
Make sure that any files your script needs to read or write are
@@ -273,12 +274,12 @@
default module search path, you can change the path in your script,
before importing other modules, e.g.:
-\begin{verbatim}
- import sys
- sys.path.insert(0, "/usr/home/joe/lib/python")
- sys.path.insert(0, "/usr/local/lib/python")
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+sys.path.insert(0, "/usr/home/joe/lib/python")
+sys.path.insert(0, "/usr/local/lib/python")
+\end{verbatim}\ecode
+%
(This way, the directory inserted last will be searched first!)
Instructions for non-Unix systems will vary; check your HTTP server's
@@ -311,10 +312,10 @@
in the standard \code{cgi-bin} directory, it should be possible to send it a
request by entering a URL into your browser of the form:
-\begin{verbatim}
- http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
-\end{verbatim}
-
+\bcode\begin{verbatim}
+http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
+\end{verbatim}\ecode
+%
If this gives an error of type 404, the server cannot find the script
-- perhaps you need to install it in a different directory. If it
gives another error (e.g. 500), there's an installation problem that
@@ -328,10 +329,10 @@
The next step could be to call the \code{cgi} module's test() function from
your script: replace its main code with the single statement
-\begin{verbatim}
- cgi.test()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+cgi.test()
+\end{verbatim}\ecode
+%
This should produce the same results as those gotten from installing
the \code{cgi.py} file itself.
@@ -363,19 +364,19 @@
For example:
-\begin{verbatim}
- import sys
- import traceback
- print "Content-type: text/html"
- print
- sys.stderr = sys.stdout
- try:
- ...your code here...
- except:
- print "\n\n<PRE>"
- traceback.print_exc()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+import traceback
+print "Content-type: text/html"
+print
+sys.stderr = sys.stdout
+try:
+ ...your code here...
+except:
+ print "\n\n<PRE>"
+ traceback.print_exc()
+\end{verbatim}\ecode
+%
Notes: The assignment to \code{sys.stderr} is needed because the traceback
prints to \code{sys.stderr}. The \code{print "$\backslash$n$\backslash$n<PRE>"} statement is necessary to
disable the word wrapping in HTML.
@@ -384,14 +385,14 @@
module, you can use an even more robust approach (which only uses
built-in modules):
-\begin{verbatim}
- import sys
- sys.stderr = sys.stdout
- print "Content-type: text/plain"
- print
- ...your code here...
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+sys.stderr = sys.stdout
+print "Content-type: text/plain"
+print
+...your code here...
+\end{verbatim}\ecode
+%
This relies on the Python interpreter to print the traceback. The
content type of the output is set to plain text, which disables all
HTML processing. If your script works, the raw HTML will be displayed
diff --git a/Doc/lib/libcopy.tex b/Doc/lib/libcopy.tex
index 4c0ce72..8f5e03c 100644
--- a/Doc/lib/libcopy.tex
+++ b/Doc/lib/libcopy.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{copy}}
+\label{module-copy}
\stmodindex{copy}
\renewcommand{\indexsubitem}{(copy function)}
\ttindex{copy}
@@ -8,13 +9,13 @@
Interface summary:
-\begin{verbatim}
+\bcode\begin{verbatim}
import copy
x = copy.copy(y) # make a shallow copy of y
x = copy.deepcopy(y) # make a deep copy of y
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
For module specific errors, \code{copy.error} is raised.
The difference between shallow and deep copying is only relevant for
diff --git a/Doc/lib/libcrypt.tex b/Doc/lib/libcrypt.tex
index 132ae51..8a4ec92 100644
--- a/Doc/lib/libcrypt.tex
+++ b/Doc/lib/libcrypt.tex
@@ -1,4 +1,5 @@
-\section{Built-in module {\tt crypt}}
+\section{Built-in Module {\tt crypt}}
+\label{module-crypt}
\bimodindex{crypt}
This module implements an interface to the crypt({\bf 3}) routine,
diff --git a/Doc/lib/libdbm.tex b/Doc/lib/libdbm.tex
index bae388b..977e05c 100644
--- a/Doc/lib/libdbm.tex
+++ b/Doc/lib/libdbm.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{dbm}}
+\label{module-dbm}
\bimodindex{dbm}
The \code{dbm} module provides an interface to the \UNIX{}
diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex
index 3a51ce1..b76a28c 100644
--- a/Doc/lib/libfcntl.tex
+++ b/Doc/lib/libfcntl.tex
@@ -65,7 +65,7 @@
lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
\end{verbatim}\ecode
-
+%
Note that in the first example the return value variable \code{rv} will
hold an integer value; in the second example it will hold a string
value. The structure lay-out for the \var{lockadata} variable is
diff --git a/Doc/lib/libfl.tex b/Doc/lib/libfl.tex
index d5332a0..bacbf76 100644
--- a/Doc/lib/libfl.tex
+++ b/Doc/lib/libfl.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{fl}}
+\label{module-fl}
\bimodindex{fl}
This module provides an interface to the FORMS Library by Mark
@@ -471,7 +472,7 @@
import fl
from FL import *
\end{verbatim}\ecode
-
+%
\section{Standard Module \sectcode{flp}}
\stmodindex{flp}
diff --git a/Doc/lib/libfm.tex b/Doc/lib/libfm.tex
index 45d820c..6f1e685 100644
--- a/Doc/lib/libfm.tex
+++ b/Doc/lib/libfm.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{fm}}
+\label{module-fm}
\bimodindex{fm}
This module provides access to the IRIS {\em Font Manager} library.
diff --git a/Doc/lib/libfnmatch.tex b/Doc/lib/libfnmatch.tex
index 78b21a4..86c9073 100644
--- a/Doc/lib/libfnmatch.tex
+++ b/Doc/lib/libfnmatch.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{fnmatch}}
+\label{module-fnmatch}
\stmodindex{fnmatch}
This module provides support for Unix shell-style wildcards, which are
diff --git a/Doc/lib/libformatter.tex b/Doc/lib/libformatter.tex
index 86e6db1..430c9d7 100644
--- a/Doc/lib/libformatter.tex
+++ b/Doc/lib/libformatter.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{formatter}}
+\label{module-formatter}
\stmodindex{formatter}
\renewcommand{\indexsubitem}{(in module formatter)}
diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex
index ba18119..dfbaa2b 100644
--- a/Doc/lib/libftplib.tex
+++ b/Doc/lib/libftplib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{ftplib}}
+\label{module-ftplib}
\stmodindex{ftplib}
\renewcommand{\indexsubitem}{(in module ftplib)}
@@ -13,7 +14,7 @@
Here's a sample session using the \code{ftplib} module:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
>>> ftp.login() # user anonymous, passwd user@hostname
@@ -26,8 +27,8 @@
.
.
>>> ftp.quit()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The module defines the following items:
\begin{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, acct}}}
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 712cb6f..0ef8201 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -119,7 +119,7 @@
2
>>>
\end{verbatim}\ecode
-
+%
This function can also be used to execute arbitrary code objects
(e.g.\ created by \code{compile()}). In this case pass a code
object instead of a string. The code object must have been compiled
diff --git a/Doc/lib/libgetopt.tex b/Doc/lib/libgetopt.tex
index 7ab46e4..0d2f4a0 100644
--- a/Doc/lib/libgetopt.tex
+++ b/Doc/lib/libgetopt.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{getopt}}
+\label{module-getopt}
\stmodindex{getopt}
This module helps scripts to parse the command line arguments in
@@ -56,7 +57,7 @@
['a1', 'a2']
>>>
\end{verbatim}\ecode
-
+%
Using long option names is equally easy:
\bcode\begin{verbatim}
@@ -72,7 +73,7 @@
['a1', 'a2']
>>>
\end{verbatim}\ecode
-
+%
The exception
\code{getopt.error = 'getopt.error'}
is raised when an unrecognized option is found in the argument list or
diff --git a/Doc/lib/libgl.tex b/Doc/lib/libgl.tex
index c32ea6f..3445465 100644
--- a/Doc/lib/libgl.tex
+++ b/Doc/lib/libgl.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{gl}}
+\label{module-gl}
\bimodindex{gl}
This module provides access to the Silicon Graphics
@@ -43,13 +44,13 @@
\bcode\begin{verbatim}
lmdef(deftype, index, np, props)
\end{verbatim}\ecode
-
+%
is translated to Python as
\bcode\begin{verbatim}
lmdef(deftype, index, props)
\end{verbatim}\ecode
-
+%
\item
Output arguments are omitted from the argument list; they are
transmitted as function return values instead.
@@ -62,13 +63,13 @@
\bcode\begin{verbatim}
getmcolor(i, &red, &green, &blue)
\end{verbatim}\ecode
-
+%
is translated to Python as
\bcode\begin{verbatim}
red, green, blue = getmcolor(i)
\end{verbatim}\ecode
-
+%
\end{itemize}
The following functions are non-standard or have special argument
@@ -183,7 +184,7 @@
main()
\end{verbatim}\ecode
-
+%
\section{Standard Modules \sectcode{GL} and \sectcode{DEVICE}}
\nodename{GL and DEVICE}
\stmodindex{GL}
diff --git a/Doc/lib/libglob.tex b/Doc/lib/libglob.tex
index 142afd8..b63d153 100644
--- a/Doc/lib/libglob.tex
+++ b/Doc/lib/libglob.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{glob}}
+\label{module-glob}
\stmodindex{glob}
\renewcommand{\indexsubitem}{(in module glob)}
@@ -24,7 +25,7 @@
will produce the following results. Notice how any leading components
of the path are preserved.
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
@@ -32,4 +33,4 @@
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/lib/libgopherlib.tex b/Doc/lib/libgopherlib.tex
index e94e1f9..6ae913c 100644
--- a/Doc/lib/libgopherlib.tex
+++ b/Doc/lib/libgopherlib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{gopherlib}}
+\label{module-gopherlib}
\stmodindex{gopherlib}
\renewcommand{\indexsubitem}{(in module gopherlib)}
diff --git a/Doc/lib/libgrp.tex b/Doc/lib/libgrp.tex
index 90a2ed3..2942a1b 100644
--- a/Doc/lib/libgrp.tex
+++ b/Doc/lib/libgrp.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{grp}}
+\label{module-grp}
\bimodindex{grp}
This module provides access to the \UNIX{} group database.
diff --git a/Doc/lib/libhtmllib.tex b/Doc/lib/libhtmllib.tex
index bf57ea9..aaa2072 100644
--- a/Doc/lib/libhtmllib.tex
+++ b/Doc/lib/libhtmllib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{htmllib}}
+\label{module-htmllib}
\stmodindex{htmllib}
\index{HTML}
\index{hypertext}
@@ -38,11 +39,11 @@
unprocessed data, call the \code{close()} method.
For example, to parse the entire contents of a file, use:
-\begin{verbatim}
+\bcode\begin{verbatim}
parser.feed(open('myfile.html').read())
parser.close()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\item
The interface to define semantics for HTML tags is very simple: derive
a class and define methods called \code{start_\var{tag}()},
diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex
index 70bcb3c..7671ab3 100644
--- a/Doc/lib/libhttplib.tex
+++ b/Doc/lib/libhttplib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{httplib}}
+\label{module-httplib}
\stmodindex{httplib}
\index{HTTP}
@@ -19,12 +20,12 @@
following calls all create instances that connect to the server at the
same host and port:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> h1 = httplib.HTTP('www.cwi.nl')
>>> h2 = httplib.HTTP('www.cwi.nl:80')
>>> h3 = httplib.HTTP('www.cwi.nl', 80)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Once an \code{HTTP} instance has been connected to an HTTP server, it
should be used as follows:
@@ -111,7 +112,7 @@
Here is an example session:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import httplib
>>> h = httplib.HTTP('www.cwi.nl')
>>> h.putrequest('GET', '/index.html')
@@ -124,4 +125,4 @@
>>> data f.read() # Get the raw HTML
>>> f.close()
>>>
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/lib/libimageop.tex b/Doc/lib/libimageop.tex
index 4e15117..48f9188 100644
--- a/Doc/lib/libimageop.tex
+++ b/Doc/lib/libimageop.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{imageop}}
+\label{module-imageop}
\bimodindex{imageop}
The \code{imageop} module contains some useful operations on images.
diff --git a/Doc/lib/libimgfile.tex b/Doc/lib/libimgfile.tex
index 1e8b2aa..96afc9b 100644
--- a/Doc/lib/libimgfile.tex
+++ b/Doc/lib/libimgfile.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{imgfile}}
+\label{module-imgfile}
\bimodindex{imgfile}
The imgfile module allows python programs to access SGI imglib image
diff --git a/Doc/lib/libimghdr.tex b/Doc/lib/libimghdr.tex
index 22d4d0d..0dec8a1 100644
--- a/Doc/lib/libimghdr.tex
+++ b/Doc/lib/libimghdr.tex
@@ -1,4 +1,5 @@
\section{Standard module \sectcode{imghdr}}
+\label{module-imghdr}
\stmodindex{imghdr}
The \code{imghdr} module determines the type of image contained in a
@@ -53,8 +54,8 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import imghdr
>>> imghdr.what('/tmp/bass.gif')
'gif'
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex
index e1e4a53..0f63524 100644
--- a/Doc/lib/libimp.tex
+++ b/Doc/lib/libimp.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{imp}}
+\label{module-imp}
\bimodindex{imp}
\index{import}
@@ -132,7 +133,7 @@
\subsection{Examples}
The following function emulates the default import statement:
-\begin{verbatim}
+\bcode\begin{verbatim}
import imp
import sys
@@ -171,4 +172,4 @@
finally:
# Since we may exit via an exception, close fp explicitly.
fp.close()
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/lib/libjpeg.tex b/Doc/lib/libjpeg.tex
index 8215cad..0d1dc1c 100644
--- a/Doc/lib/libjpeg.tex
+++ b/Doc/lib/libjpeg.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{jpeg}}
+\label{module-jpeg}
\bimodindex{jpeg}
The module \code{jpeg} provides access to the jpeg compressor and
diff --git a/Doc/lib/libmailcap.tex b/Doc/lib/libmailcap.tex
index 7fea9b5..d7d47c4 100644
--- a/Doc/lib/libmailcap.tex
+++ b/Doc/lib/libmailcap.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{mailcap}}
+\label{module-mailcap}
\stmodindex{mailcap}
\renewcommand{\indexsubitem}{(in module mailcap)}
@@ -67,9 +68,9 @@
\end{funcdesc}
An example usage:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import mailcap
>>> d=mailcap.getcaps()
>>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/lib/libmain.tex b/Doc/lib/libmain.tex
index c730a03..8ce73a8 100644
--- a/Doc/lib/libmain.tex
+++ b/Doc/lib/libmain.tex
@@ -1,5 +1,5 @@
\section{Built-in Module \sectcode{__main__}}
-
+\label{module-main}
\bimodindex{__main__}
This module represents the (otherwise anonymous) scope in which the
interpreter's main program executes --- commands read either from
diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex
index 58becdb..16472db 100644
--- a/Doc/lib/libmarshal.tex
+++ b/Doc/lib/libmarshal.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{marshal}}
+\label{module-marshal}
\bimodindex{marshal}
This module contains functions that can read and write Python
diff --git a/Doc/lib/libmath.tex b/Doc/lib/libmath.tex
index 765fcdf..935b940 100644
--- a/Doc/lib/libmath.tex
+++ b/Doc/lib/libmath.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{math}}
+\label{module-math}
\bimodindex{math}
\renewcommand{\indexsubitem}{(in module math)}
@@ -70,3 +71,7 @@
\else
\code{pi} and \code{e}.
\fi
+
+\begin{seealso}
+\seealso{cmath}{versions of these functions that can handle complex numbers}
+\end{seealso}
diff --git a/Doc/lib/libmd5.tex b/Doc/lib/libmd5.tex
index 773f93c..d71bacd 100644
--- a/Doc/lib/libmd5.tex
+++ b/Doc/lib/libmd5.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{md5}}
+\label{module-md5}
\bimodindex{md5}
This module implements the interface to RSA's MD5 message digest
@@ -21,14 +22,14 @@
>>> m.digest()
'\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("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}}
diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex
index ecf50dc..41a62ba 100644
--- a/Doc/lib/libmimetools.tex
+++ b/Doc/lib/libmimetools.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{mimetools}}
+\label{module-mimetools}
\stmodindex{mimetools}
\renewcommand{\indexsubitem}{(in module mimetools)}
diff --git a/Doc/lib/libmpz.tex b/Doc/lib/libmpz.tex
index 46a2d47..9fb165b 100644
--- a/Doc/lib/libmpz.tex
+++ b/Doc/lib/libmpz.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{mpz}}
+\label{module-mpz}
\bimodindex{mpz}
This is an optional module. It is only available when Python is
diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex
index 2641d82..41539b4 100644
--- a/Doc/lib/libnntplib.tex
+++ b/Doc/lib/libnntplib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{nntplib}}
+\label{module-nntplib}
\stmodindex{nntplib}
\renewcommand{\indexsubitem}{(in module nntplib)}
@@ -13,7 +14,7 @@
articles:
\small{
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> s = NNTP('news.cwi.nl')
>>> resp, count, first, last, name = s.group('comp.lang.python')
>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
@@ -34,13 +35,13 @@
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
-\end{verbatim}
+\end{verbatim}\ecode
}
To post an article from a file (this assumes that the article has
valid headers):
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> s = NNTP('news.cwi.nl')
>>> f = open('/tmp/article')
>>> s.post(f)
@@ -48,8 +49,8 @@
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The module itself defines the following items:
\begin{funcdesc}{NNTP}{host\optional{\, port}}
diff --git a/Doc/lib/liboperator.tex b/Doc/lib/liboperator.tex
index 7fed767..d7c11fc 100644
--- a/Doc/lib/liboperator.tex
+++ b/Doc/lib/liboperator.tex
@@ -184,10 +184,10 @@
Example: Build a dictionary that maps the ordinals from 0 to 256 to their
character equivalents.
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import operator
>>> d = {}
>>> keys = range(256)
>>> vals = map(chr, keys)
>>> map(operator.setitem, [d]*len(keys), keys, vals)
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index 51442ef..f17ce95 100644
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{os}}
+\label{module-os}
\stmodindex{os}
This module provides a more portable way of using operating system
diff --git a/Doc/lib/libpanel.tex b/Doc/lib/libpanel.tex
index b82bf98..a696f30 100644
--- a/Doc/lib/libpanel.tex
+++ b/Doc/lib/libpanel.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{panel}}
+\label{module-panel}
\stmodindex{panel}
\strong{Please note:} The FORMS library, to which the \code{fl} module described
diff --git a/Doc/lib/libparser.tex b/Doc/lib/libparser.tex
index a51b01b..4503358 100644
--- a/Doc/lib/libparser.tex
+++ b/Doc/lib/libparser.tex
@@ -288,30 +288,30 @@
this purpose, using the \code{parser} module to produce an
intermediate data structure is equivelent to the code
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> code = compile('a + 5', 'eval')
>>> a = 5
>>> eval(code)
10
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The equivelent operation using the \code{parser} module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import parser
>>> ast = parser.expr('a + 5')
>>> code = parser.compileast(ast)
>>> a = 5
>>> eval(code)
10
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
An application which needs both AST and code objects can package this
code into readily available functions:
-\begin{verbatim}
+\bcode\begin{verbatim}
import parser
def load_suite(source_string):
@@ -323,8 +323,8 @@
ast = parser.expr(source_string)
code = parser.compileast(ast)
return ast, code
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\subsubsection{Information Discovery}
Some applications benefit from direct access to the parse tree. The
@@ -366,16 +366,16 @@
a module consisting of a docstring and nothing else. (See file
\file{docstring.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
"""Some documentation.
"""
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Using the interpreter to take a look at the parse tree, we find a
bewildering mass of numbers and parentheses, with the documentation
buried deep in nested tuples.
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import parser
>>> import pprint
>>> ast = parser.suite(open('docstring.py').read())
@@ -403,8 +403,8 @@
(4, ''))),
(4, ''),
(0, ''))
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The numbers at the first element of each node in the tree are the node
types; they map directly to terminal and non-terminal symbols in the
grammar. Unfortunately, they are represented as integers in the
@@ -442,7 +442,7 @@
the pattern matching, returning a boolean and a dictionary of variable
name to value mappings. (See file \file{example.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
from types import ListType, TupleType
def match(pattern, data, vars=None):
@@ -460,13 +460,13 @@
if not same:
break
return same, vars
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Using this simple representation for syntactic variables and the symbolic
node types, the pattern for the candidate docstring subtrees becomes
fairly readable. (See file \file{example.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
import symbol
import token
@@ -493,19 +493,19 @@
)))))))))))))))),
(token.NEWLINE, '')
))
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Using the \code{match()} function with this pattern, extracting the
module docstring from the parse tree created previously is easy:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
>>> found
1
>>> vars
{'docstring': '"""Some documentation.\012"""'}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Once specific data can be extracted from a location where it is
expected, the question of where information can be expected
needs to be answered. When dealing with docstrings, the answer is
@@ -567,7 +567,7 @@
objects requires further examination. Here is the relevant part of
the \code{SuiteInfoBase} definition from \file{example.py}:
-\begin{verbatim}
+\bcode\begin{verbatim}
class SuiteInfoBase:
_docstring = ''
_name = ''
@@ -597,8 +597,8 @@
elif cstmt[0] == symbol.classdef:
name = cstmt[2][1]
self._class_info[name] = ClassInfo(cstmt)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
After initializing some internal state, the constructor calls the
\code{_extract_info()} method. This method performs the bulk of the
information extraction which takes place in the entire example. The
@@ -611,21 +611,21 @@
the code block is on the same line as the definition of the code
block, as in
-\begin{verbatim}
+\bcode\begin{verbatim}
def square(x): "Square an argument."; return x ** 2
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
while the long form uses an indented block and allows nested
definitions:
-\begin{verbatim}
+\bcode\begin{verbatim}
def make_power(exp):
"Make a function that raises an argument to the exponent `exp'."
def raiser(x, y=exp):
return x ** y
return raiser
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
When the short form is used, the code block may contain a docstring as
the first, and possibly only, \code{small_stmt} element. The
extraction of such a docstring is slightly different and requires only
@@ -660,7 +660,7 @@
blocks. A high-level function can be used to extract the complete set
of information from a source file. (See file \file{example.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
def get_docs(fileName):
source = open(fileName).read()
import os
@@ -669,8 +669,8 @@
ast = parser.suite(source)
tup = parser.ast2tuple(ast)
return ModuleInfo(tup, basename)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
This provides an easy-to-use interface to the documentation of a
module. If information is required which is not extracted by the code
of this example, the code may be extended at clearly defined points to
diff --git a/Doc/lib/libpdb.tex b/Doc/lib/libpdb.tex
index 84ae332..9785a40 100644
--- a/Doc/lib/libpdb.tex
+++ b/Doc/lib/libpdb.tex
@@ -29,7 +29,7 @@
The debugger's prompt is ``\code{(Pdb) }''.
Typical usage to run a program under control of the debugger is:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
@@ -40,15 +40,15 @@
NameError: 'spam'
> <string>(1)?()
(Pdb)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\code{pdb.py} can also be invoked as
a script to debug other scripts. For example:
\code{python /usr/local/lib/python1.4/pdb.py myscript.py}
Typical usage to inspect a crashed program is:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import pdb
>>> import mymodule
>>> mymodule.test()
@@ -63,8 +63,8 @@
> ./mymodule.py(3)test2()
-> print spam
(Pdb)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The module defines the following functions; each enters the debugger
in a slightly different way:
@@ -224,11 +224,11 @@
of the statement resembles a debugger command.
To set a global variable, you can prefix the assignment
command with a ``\code{global}'' command on the same line, e.g.:
-\begin{verbatim}
+\bcode\begin{verbatim}
(Pdb) global list_options; list_options = ['-l']
(Pdb)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\item[q(uit)]
Quit from the debugger.
diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex
index 128b29d..cb054a7 100644
--- a/Doc/lib/libpickle.tex
+++ b/Doc/lib/libpickle.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{pickle}}
+\label{module-pickle}
\stmodindex{pickle}
\index{persistency}
\indexii{persistent}{objects}
@@ -133,30 +134,30 @@
To pickle an object \code{x} onto a file \code{f}, open for writing:
-\begin{verbatim}
+\bcode\begin{verbatim}
p = pickle.Pickler(f)
p.dump(x)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
A shorthand for this is:
-\begin{verbatim}
+\bcode\begin{verbatim}
pickle.dump(x, f)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
To unpickle an object \code{x} from a file \code{f}, open for reading:
-\begin{verbatim}
+\bcode\begin{verbatim}
u = pickle.Unpickler(f)
x = u.load()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
A shorthand is:
-\begin{verbatim}
+\bcode\begin{verbatim}
x = pickle.load(f)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
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),
diff --git a/Doc/lib/libposix.tex b/Doc/lib/libposix.tex
index 7edd93e..e545c7a 100644
--- a/Doc/lib/libposix.tex
+++ b/Doc/lib/libposix.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{posix}}
+\label{module-posix}
\bimodindex{posix}
This module provides access to operating system functionality that is
diff --git a/Doc/lib/libppath.tex b/Doc/lib/libppath.tex
index 9078560..6bd8a20 100644
--- a/Doc/lib/libppath.tex
+++ b/Doc/lib/libppath.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{posixpath}}
+\label{module-posixpath}
\stmodindex{posixpath}
This module implements some useful functions on POSIX pathnames.
diff --git a/Doc/lib/libprofile.tex b/Doc/lib/libprofile.tex
index 7cd3c6b..2f69170 100644
--- a/Doc/lib/libprofile.tex
+++ b/Doc/lib/libprofile.tex
@@ -103,11 +103,11 @@
To profile an application with a main entry point of \samp{foo()}, you
would add the following to your module:
-\begin{verbatim}
- import profile
- profile.run("foo()")
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import profile
+profile.run("foo()")
+\end{verbatim}\ecode
+%
The above action would cause \samp{foo()} to be run, and a series of
informative lines (the profile) to be printed. The above approach is
most useful when working with the interpreter. If you would like to
@@ -115,11 +115,11 @@
can supply a file name as the second argument to the \code{run()}
function:
-\begin{verbatim}
- import profile
- profile.run("foo()", 'fooprof')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import profile
+profile.run("foo()", 'fooprof')
+\end{verbatim}\ecode
+%
\code{profile.py} can also be invoked as
a script to profile another script. For example:
\code{python /usr/local/lib/python1.4/profile.py myscript.py}
@@ -128,40 +128,40 @@
\code{pstats} module. Typically you would load the statistics data as
follows:
-\begin{verbatim}
- import pstats
- p = pstats.Stats('fooprof')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import pstats
+p = pstats.Stats('fooprof')
+\end{verbatim}\ecode
+%
The class \code{Stats} (the above code just created an instance of
this class) has a variety of methods for manipulating and printing the
data that was just read into \samp{p}. When you ran
\code{profile.run()} above, what was printed was the result of three
method calls:
-\begin{verbatim}
- p.strip_dirs().sort_stats(-1).print_stats()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.strip_dirs().sort_stats(-1).print_stats()
+\end{verbatim}\ecode
+%
The first method removed the extraneous path from all the module
names. The second method sorted all the entries according to the
standard module/line/name string that is printed (this is to comply
with the semantics of the old profiler). The third method printed out
all the statistics. You might try the following sort calls:
-\begin{verbatim}
- p.sort_stats('name')
- p.print_stats()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('name')
+p.print_stats()
+\end{verbatim}\ecode
+%
The first call will actually sort the list by function name, and the
second call will print out the statistics. The following are some
interesting calls to experiment with:
-\begin{verbatim}
- p.sort_stats('cumulative').print_stats(10)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('cumulative').print_stats(10)
+\end{verbatim}\ecode
+%
This sorts the profile by cumulative time in a function, and then only
prints the ten most significant lines. If you want to understand what
algorithms are taking time, the above line is what you would use.
@@ -169,27 +169,27 @@
If you were looking to see what functions were looping a lot, and
taking a lot of time, you would do:
-\begin{verbatim}
- p.sort_stats('time').print_stats(10)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('time').print_stats(10)
+\end{verbatim}\ecode
+%
to sort according to time spent within each function, and then print
the statistics for the top ten functions.
You might also try:
-\begin{verbatim}
- p.sort_stats('file').print_stats('__init__')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('file').print_stats('__init__')
+\end{verbatim}\ecode
+%
This will sort all the statistics by file name, and then print out
statistics for only the class init methods ('cause they are spelled
with \code{__init__} in them). As one final example, you could try:
-\begin{verbatim}
- p.sort_stats('time', 'cum').print_stats(.5, 'init')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('time', 'cum').print_stats(.5, 'init')
+\end{verbatim}\ecode
+%
This line sorts statistics with a primary key of time, and a secondary
key of cumulative time, and then prints out some of the statistics.
To be specific, the list is first culled down to 50\% (re: \samp{.5})
@@ -199,21 +199,20 @@
If you wondered what functions called the above functions, you could
now (\samp{p} is still sorted according to the last criteria) do:
-\begin{verbatim}
- p.print_callers(.5, 'init')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.print_callers(.5, 'init')
+\end{verbatim}\ecode
+%
and you would get a list of callers for each of the listed functions.
If you want more functionality, you're going to have to read the
manual, or guess what the following functions do:
-\begin{verbatim}
- p.print_callees()
- p.add('fooprof')
-\end{verbatim}
-
-
+\bcode\begin{verbatim}
+p.print_callees()
+p.add('fooprof')
+\end{verbatim}\ecode
+%
\section{What Is Deterministic Profiling?}
\nodename{Deterministic Profiling}
@@ -272,7 +271,7 @@
each line. The following is a typical output from such a call:
\small{
-\begin{verbatim}
+\bcode\begin{verbatim}
main()
2706 function calls (2004 primitive calls) in 4.504 CPU seconds
@@ -282,7 +281,7 @@
2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)
43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)
...
-\end{verbatim}
+\end{verbatim}\ecode
}
The first line indicates that this profile was generated by the call:\\
@@ -446,18 +445,18 @@
several restrictions are provided, then they are applied sequentially.
For example:
-\begin{verbatim}
- print_stats(.1, "foo:")
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print_stats(.1, "foo:")
+\end{verbatim}\ecode
+%
would first limit the printing to first 10\% of list, and then only
print functions that were part of filename \samp{.*foo:}. In
contrast, the command:
-\begin{verbatim}
- print_stats("foo:", .1)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print_stats("foo:", .1)
+\end{verbatim}\ecode
+%
would limit the list to all functions having file names \samp{.*foo:},
and then proceed to only print the first 10\% of them.
\end{funcdesc}
@@ -486,11 +485,11 @@
return the instance that is being processed, so that the commands can
be strung together. For example:
-\begin{verbatim}
+\bcode\begin{verbatim}
pstats.Stats('foofile').strip_dirs().sort_stats('cum') \
.print_stats().ignore()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
would perform all the indicated functions, but it would not return
the final reference to the \code{Stats} instance.%
\footnote{
@@ -550,28 +549,28 @@
be used to obtain this constant for a given platform (see discussion
in section Limitations above).
-\begin{verbatim}
- import profile
- pr = profile.Profile()
- pr.calibrate(100)
- pr.calibrate(100)
- pr.calibrate(100)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import profile
+pr = profile.Profile()
+pr.calibrate(100)
+pr.calibrate(100)
+pr.calibrate(100)
+\end{verbatim}\ecode
+%
The argument to calibrate() is the number of times to try to do the
sample calls to get the CPU times. If your computer is \emph{very}
fast, you might have to do:
-\begin{verbatim}
- pr.calibrate(1000)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+pr.calibrate(1000)
+\end{verbatim}\ecode
+%
or even:
-\begin{verbatim}
- pr.calibrate(10000)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+pr.calibrate(10000)
+\end{verbatim}\ecode
+%
The object of this exercise is to get a fairly consistent result.
When you have a consistent answer, you are ready to use that number in
the source code. For a Sun Sparcstation 1000 running Solaris 2.3, the
@@ -583,27 +582,27 @@
class should be modified to install the calibration constant on a Sun
Sparcstation 1000:
-\begin{verbatim}
- def trace_dispatch(self, frame, event, arg):
+\bcode\begin{verbatim}
+def trace_dispatch(self, frame, event, arg):
+ t = self.timer()
+ t = t[0] + t[1] - self.t - .00053 # Calibration constant
+
+ if self.dispatch[event](frame,t):
t = self.timer()
- t = t[0] + t[1] - self.t - .00053 # Calibration constant
-
- if self.dispatch[event](frame,t):
- t = self.timer()
- self.t = t[0] + t[1]
- else:
- r = self.timer()
- self.t = r[0] + r[1] - t # put back unrecorded delta
- return
-\end{verbatim}
-
+ self.t = t[0] + t[1]
+ else:
+ r = self.timer()
+ self.t = r[0] + r[1] - t # put back unrecorded delta
+ return
+\end{verbatim}\ecode
+%
Note that if there is no calibration constant, then the line
containing the callibration constant should simply say:
-\begin{verbatim}
- t = t[0] + t[1] - self.t # no calibration constant
-\end{verbatim}
-
+\bcode\begin{verbatim}
+t = t[0] + t[1] - self.t # no calibration constant
+\end{verbatim}\ecode
+%
You can also achieve the same results using a derived class (and the
profiler will actually run equally fast!!), but the above method is
the simplest to use. I could have made the profiler ``self
@@ -631,10 +630,10 @@
the constructor for the class. Consider passing the name of a
function to call into the constructor:
-\begin{verbatim}
- pr = profile.Profile(your_time_func)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+pr = profile.Profile(your_time_func)
+\end{verbatim}\ecode
+%
The resulting profiler will call \code{your_time_func()} instead of
\code{os.times()}. The function should return either a single number
or a list of numbers (like what \code{os.times()} returns). If the
@@ -663,7 +662,7 @@
user's code. It is also a lot more accurate than the old profiler, as
it does not charge all its overhead time to the user's code.
-\begin{verbatim}
+\bcode\begin{verbatim}
class OldProfile(Profile):
def trace_dispatch_exception(self, frame, t):
@@ -713,9 +712,8 @@
callers[func_caller]
nc = nc + callers[func_caller]
self.stats[nor_func] = nc, nc, tt, ct, nor_callers
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\subsection{HotProfile Class}
This profiler is the fastest derived profile example. It does not
@@ -725,7 +723,7 @@
the basic profiler is so fast, that is probably not worth the savings
to give up the data, but this class still provides a nice example.
-\begin{verbatim}
+\bcode\begin{verbatim}
class HotProfile(Profile):
def trace_dispatch_exception(self, frame, t):
@@ -761,4 +759,4 @@
nc, tt = self.timings[func]
nor_func = self.func_normalize(func)
self.stats[nor_func] = nc, nc, tt, 0, {}
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/lib/libpwd.tex b/Doc/lib/libpwd.tex
index 7bb30d8..073c19a 100644
--- a/Doc/lib/libpwd.tex
+++ b/Doc/lib/libpwd.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{pwd}}
+\label{module-pwd}
\bimodindex{pwd}
This module provides access to the \UNIX{} password database.
diff --git a/Doc/lib/libquopri.tex b/Doc/lib/libquopri.tex
index 0314f8a..2fbd35a 100644
--- a/Doc/lib/libquopri.tex
+++ b/Doc/lib/libquopri.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{quopri}}
+\label{module-quopri}
\stmodindex{quopri}
This module performs quoted-printable transport encoding and decoding,
diff --git a/Doc/lib/librand.tex b/Doc/lib/librand.tex
index 5a4df3e..0660566 100644
--- a/Doc/lib/librand.tex
+++ b/Doc/lib/librand.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{rand}}
+\label{module-rand}
\stmodindex{rand}
The \code{rand} module simulates the C library's \code{rand()}
@@ -20,3 +21,7 @@
can be an arbitrary integer.
\end{funcdesc}
+\begin{seealso}
+\seemodule{whrandom}{the standard Python random number generator}
+\end{seealso}
+
diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex
index 3bc92ce..b8d5f78 100644
--- a/Doc/lib/librandom.tex
+++ b/Doc/lib/librandom.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{random}}
+\label{module-random}
\stmodindex{random}
This module implements pseudo-random number generators for various
@@ -69,3 +70,8 @@
distribution reduces to a uniform random angle over the range 0 to
\code{2*pi}.
\end{funcdesc}
+
+
+\begin{seealso}
+\seemodule{whrandom}{the standard Python random number generator}
+\end{seealso}
diff --git a/Doc/lib/libregex.tex b/Doc/lib/libregex.tex
index d3f44ba..ee1563d 100644
--- a/Doc/lib/libregex.tex
+++ b/Doc/lib/libregex.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{regex}}
+\label{module-regex}
\bimodindex{regex}
This module provides regular expression matching operations similar to
@@ -204,13 +205,13 @@
prog = regex.compile(pat)
result = prog.match(str)
\end{verbatim}\ecode
-
+%
is equivalent to
\bcode\begin{verbatim}
result = regex.match(pat, str)
\end{verbatim}\ecode
-
+%
but the version using \code{compile()} is more efficient when multiple
regular expressions are used concurrently in a single program. (The
compiled version of the last pattern passed to \code{regex.match()} or
diff --git a/Doc/lib/libregsub.tex b/Doc/lib/libregsub.tex
index d075e99..6d48986 100644
--- a/Doc/lib/libregsub.tex
+++ b/Doc/lib/libregsub.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{regsub}}
+\label{module-regsub}
\stmodindex{regsub}
This module defines a number of functions useful for working with
diff --git a/Doc/lib/libresource.tex b/Doc/lib/libresource.tex
index ff78025..5c93fa6 100644
--- a/Doc/lib/libresource.tex
+++ b/Doc/lib/libresource.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{resource}}
+\label{module-resource}
\bimodindex{resource}
This module provides basic mechanisms for measuring and controlling
diff --git a/Doc/lib/librexec.tex b/Doc/lib/librexec.tex
index 4b1a100..742e32b 100644
--- a/Doc/lib/librexec.tex
+++ b/Doc/lib/librexec.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{rexec}}
+\label{module-rexec}
\stmodindex{rexec}
\renewcommand{\indexsubitem}{(in module rexec)}
@@ -206,7 +207,7 @@
else: raise IOError, "Illegal open() mode"
return open(file, mode, buf)
\end{verbatim}\ecode
-
+%
Notice that the above code will occasionally forbid a perfectly valid
filename; for example, code in the restricted environment won't be
able to open a file called \file{/tmp/foo/../bar}. To fix this, the
diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex
index 3617e8a..cd3d271 100644
--- a/Doc/lib/librfc822.tex
+++ b/Doc/lib/librfc822.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{rfc822}}
+\label{module-rfc822}
\stmodindex{rfc822}
\renewcommand{\indexsubitem}{(in module rfc822)}
diff --git a/Doc/lib/librgbimg.tex b/Doc/lib/librgbimg.tex
index ace426f..d923fc2 100644
--- a/Doc/lib/librgbimg.tex
+++ b/Doc/lib/librgbimg.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{rgbimg}}
+\label{module-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 c333686..a3431fc 100644
--- a/Doc/lib/librotor.tex
+++ b/Doc/lib/librotor.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{rotor}}
+\label{module-rotor}
\bimodindex{rotor}
This module implements a rotor-based encryption algorithm, contributed by
@@ -79,7 +80,7 @@
'l(\315'
>>> del rt
\end{verbatim}\ecode
-
+%
The module's code is not an exact simulation of the original Enigma device;
it implements the rotor encryption scheme differently from the original. The
most important difference is that in the original Enigma, there were only 5
diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex
index 0b50101..4291dbf 100644
--- a/Doc/lib/libselect.tex
+++ b/Doc/lib/libselect.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{select}}
+\label{module-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 dc3582b..19ce91c 100644
--- a/Doc/lib/libsgmllib.tex
+++ b/Doc/lib/libsgmllib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{sgmllib}}
+\label{module-sgmllib}
\stmodindex{sgmllib}
\index{SGML}
diff --git a/Doc/lib/libshelve.tex b/Doc/lib/libshelve.tex
index a232add..05b3a93 100644
--- a/Doc/lib/libshelve.tex
+++ b/Doc/lib/libshelve.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{shelve}}
+\label{module-shelve}
\stmodindex{shelve}
\stmodindex{pickle}
\bimodindex{dbm}
@@ -14,7 +15,7 @@
To summarize the interface (\code{key} is a string, \code{data} is an
arbitrary object):
-\begin{verbatim}
+\bcode\begin{verbatim}
import shelve
d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
@@ -29,8 +30,8 @@
list = d.keys() # a list of all existing keys (slow!)
d.close() # close it
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Restrictions:
\begin{itemize}
diff --git a/Doc/lib/libsignal.tex b/Doc/lib/libsignal.tex
index 802c4d1..2844b57 100644
--- a/Doc/lib/libsignal.tex
+++ b/Doc/lib/libsignal.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{signal}}
+\label{module-signal}
\bimodindex{signal}
This module provides mechanisms to use signal handlers in Python.
diff --git a/Doc/lib/libsite.tex b/Doc/lib/libsite.tex
index c97fd4e..9b7eb91 100644
--- a/Doc/lib/libsite.tex
+++ b/Doc/lib/libsite.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{site}}
+\label{module-site}
\stmodindex{site}
Scripts or modules that need to use site-specific modules should
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
index 9d5536c..5422796 100644
--- a/Doc/lib/libsocket.tex
+++ b/Doc/lib/libsocket.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{socket}}
+\label{module-socket}
\bimodindex{socket}
This module provides access to the BSD {\em socket} interface.
@@ -336,7 +337,7 @@
conn.send(data)
conn.close()
\end{verbatim}\ecode
-
+%
\bcode\begin{verbatim}
# Echo client program
from socket import *
@@ -349,3 +350,7 @@
s.close()
print 'Received', `data`
\end{verbatim}\ecode
+%
+\begin{seealso}
+\seemodule{SocketServer}{classes that simplify writing network servers}
+\end{seealso}
diff --git a/Doc/lib/libsoundex.tex b/Doc/lib/libsoundex.tex
index 4c15c55..373da38 100644
--- a/Doc/lib/libsoundex.tex
+++ b/Doc/lib/libsoundex.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{soundex}}
+\label{module-soundex}
\stmodindex{soundex}
\renewcommand{\indexsubitem}{(in module soundex)}
diff --git a/Doc/lib/libstat.tex b/Doc/lib/libstat.tex
index 67335a5..bb3b66a 100644
--- a/Doc/lib/libstat.tex
+++ b/Doc/lib/libstat.tex
@@ -81,7 +81,7 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
import os, sys
from stat import *
@@ -103,4 +103,4 @@
print 'frobbed', file
if __name__ == '__main__': process(sys.argv[1], f)
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/lib/libstdwin.tex b/Doc/lib/libstdwin.tex
index 2f2bd42..514252f 100644
--- a/Doc/lib/libstdwin.tex
+++ b/Doc/lib/libstdwin.tex
@@ -774,7 +774,7 @@
main()
\end{verbatim}\ecode
-
+%
\section{Standard Module \sectcode{stdwinevents}}
\stmodindex{stdwinevents}
@@ -788,7 +788,7 @@
>>> from stdwinevents import *
>>>
\end{verbatim}\ecode
-
+%
\section{Standard Module \sectcode{rect}}
\stmodindex{rect}
@@ -801,7 +801,7 @@
\bcode\begin{verbatim}
(10, 20), (90, 80)
\end{verbatim}\ecode
-
+%
is a rectangle whose left, top, right and bottom edges are 10, 20, 90
and 80, respectively.
Note that the positive vertical axis points down (as in
diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex
index 7b91717..930ce22 100644
--- a/Doc/lib/libstring.tex
+++ b/Doc/lib/libstring.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{string}}
+\label{module-string}
\stmodindex{string}
diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
index f7879f1..d57a2b7 100644
--- a/Doc/lib/libstruct.tex
+++ b/Doc/lib/libstruct.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{struct}}
+\label{module-struct}
\bimodindex{struct}
\indexii{C}{structures}
@@ -126,7 +127,7 @@
8
>>>
\end{verbatim}\ecode
-
+%
Hint: to align the end of a structure to the alignment requirement of
a particular type, end the format with the code for that type with a
repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two
diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex
index ae02d8d..f137052 100644
--- a/Doc/lib/libsys.tex
+++ b/Doc/lib/libsys.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{sys}}
+\label{module-sys}
\bimodindex{sys}
This module provides access to some variables used or maintained by the
diff --git a/Doc/lib/libsyslog.tex b/Doc/lib/libsyslog.tex
index 5b4fdde..37d6b66 100644
--- a/Doc/lib/libsyslog.tex
+++ b/Doc/lib/libsyslog.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{syslog}}
+\label{module-syslog}
\bimodindex{syslog}
This module provides an interface to the Unix \code{syslog} library
diff --git a/Doc/lib/libtempfile.tex b/Doc/lib/libtempfile.tex
index 0a582e1..e033f70 100644
--- a/Doc/lib/libtempfile.tex
+++ b/Doc/lib/libtempfile.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{tempfile}}
+\label{module-tempfile}
\stmodindex{tempfile}
\indexii{temporary}{file name}
\indexii{temporary}{file}
diff --git a/Doc/lib/libtemplate.tex b/Doc/lib/libtemplate.tex
index cd49a8f..1edc21d 100644
--- a/Doc/lib/libtemplate.tex
+++ b/Doc/lib/libtemplate.tex
@@ -96,13 +96,13 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import spam
>>> can = spam.open('/etc/passwd')
>>> can.empty()
>>> can.close()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
% ==== 5. ====
% If your module defines new object types (for a built-in module) or
% classes (for a module written in Python), you should list the
diff --git a/Doc/lib/libtermios.tex b/Doc/lib/libtermios.tex
index 3d007c3..2d233f2 100644
--- a/Doc/lib/libtermios.tex
+++ b/Doc/lib/libtermios.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{termios}}
+\label{module-termios}
\bimodindex{termios}
\indexii{Posix}{I/O control}
\indexii{tty}{I/O control}
@@ -76,7 +77,7 @@
and a \code{try \ldots{} finally} statement to ensure that the old tty
attributes are restored exactly no matter what happens:
-\begin{verbatim}
+\bcode\begin{verbatim}
def getpass(prompt = "Password: "):
import termios, TERMIOS, sys
fd = sys.stdin.fileno()
@@ -89,9 +90,8 @@
finally:
termios.tcsetattr(fd, TERMIOS.TCSADRAIN, old)
return passwd
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\section{Standard Module \sectcode{TERMIOS}}
\stmodindex{TERMIOS}
\indexii{Posix}{I/O control}
diff --git a/Doc/lib/libthread.tex b/Doc/lib/libthread.tex
index f745384..080a35c 100644
--- a/Doc/lib/libthread.tex
+++ b/Doc/lib/libthread.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{thread}}
+\label{module-thread}
\bimodindex{thread}
This module provides low-level primitives for working with multiple
diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex
index 7ee886d..e352505 100644
--- a/Doc/lib/libtime.tex
+++ b/Doc/lib/libtime.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{time}}
+\label{module-time}
\bimodindex{time}
This module provides various time-related functions.
diff --git a/Doc/lib/libtraceback.tex b/Doc/lib/libtraceback.tex
index ca9c374..4fcc4d1 100644
--- a/Doc/lib/libtraceback.tex
+++ b/Doc/lib/libtraceback.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{traceback}}
+\label{module-traceback}
\stmodindex{traceback}
\renewcommand{\indexsubitem}{(in module traceback)}
diff --git a/Doc/lib/libtypes2.tex b/Doc/lib/libtypes2.tex
index d0f20c9..afb02e5 100644
--- a/Doc/lib/libtypes2.tex
+++ b/Doc/lib/libtypes2.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{types}}
+\label{module-types}
\stmodindex{types}
\renewcommand{\indexsubitem}{(in module types)}
@@ -13,15 +14,15 @@
Typical use is for functions that do different things depending on
their argument types, like the following:
-\begin{verbatim}
+\bcode\begin{verbatim}
from types import *
def delete(list, item):
if type(item) is IntType:
del list[item]
else:
list.remove(item)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The module defines the following names:
\begin{datadesc}{NoneType}
diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex
index 8fe7132..51a700a 100644
--- a/Doc/lib/liburllib.tex
+++ b/Doc/lib/liburllib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{urllib}}
+\label{module-urllib}
\stmodindex{urllib}
\index{WWW}
\index{World-Wide Web}
diff --git a/Doc/lib/liburlparse.tex b/Doc/lib/liburlparse.tex
index 36ca949..76fd9f8 100644
--- a/Doc/lib/liburlparse.tex
+++ b/Doc/lib/liburlparse.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{urlparse}}
+\label{module-urlparse}
\stmodindex{urlparse}
\index{WWW}
\index{World-Wide Web}
@@ -34,16 +35,16 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
yields the tuple
-\begin{verbatim}
+\bcode\begin{verbatim}
('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
If the \var{default_scheme} argument is specified, it gives the
default addressing scheme, to be used only if the URL string does not
specify one. The default value for this argument is the empty string.
@@ -69,16 +70,16 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
yields the string
-\begin{verbatim}
+\bcode\begin{verbatim}
'http://www.cwi.nl/%7Eguido/FAQ.html'
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The \var{allow_fragments} argument has the same meaning as for
\code{urlparse}.
\end{funcdesc}
diff --git a/Doc/lib/libwhichdb.tex b/Doc/lib/libwhichdb.tex
index fbdfa8c..19bca3a 100644
--- a/Doc/lib/libwhichdb.tex
+++ b/Doc/lib/libwhichdb.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{whichdb}}
+\label{module-whichdb}
\stmodindex{whichdb}
The single function in this module attempts to guess which of the
diff --git a/Doc/lib/libwhrandom.tex b/Doc/lib/libwhrandom.tex
index 6094462..09d7816 100644
--- a/Doc/lib/libwhrandom.tex
+++ b/Doc/lib/libwhrandom.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{whrandom}}
+\label{module-whrandom}
\stmodindex{whrandom}
This module implements a Wichmann-Hill pseudo-random number generator
@@ -36,7 +37,14 @@
the \code{whrandom} class, and makes the methods of that instance
available at the module level. Therefore one can write either
\code{N = whrandom.random()} or:
-\begin{verbatim}
+\bcode\begin{verbatim}
generator = whrandom.whrandom()
N = generator.random()
-\end{verbatim}
+\end{verbatim}\ecode
+%
+\begin{seealso}
+\seemodule{random}{generators for various random distributions}
+\seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
+An efficient and portable pseudo-random number generator'',
+Applied Statistics 31 (1982) 188-190}
+\end{seealso}
diff --git a/Doc/lib/libxdrlib.tex b/Doc/lib/libxdrlib.tex
index 1221fff..0de5695 100644
--- a/Doc/lib/libxdrlib.tex
+++ b/Doc/lib/libxdrlib.tex
@@ -1,4 +1,5 @@
\section{Standard module \sectcode{xdrlib}}
+\label{module-xdrlib}
\stmodindex{xdrlib}
\index{XDR}
@@ -221,15 +222,15 @@
Here is an example of how you would catch one of these exceptions:
-\begin{verbatim}
+\bcode\begin{verbatim}
import xdrlib
p = xdrlib.Packer()
try:
p.pack_double(8.01)
except xdrlib.ConversionError, instance:
print 'packing the double failed:', instance.msg
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\subsection{Supporting Floating Point Data}
Packing and unpacking floating point data,
diff --git a/Doc/lib/libzlib.tex b/Doc/lib/libzlib.tex
index ab30a32..28365ae 100644
--- a/Doc/lib/libzlib.tex
+++ b/Doc/lib/libzlib.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{zlib}}
+\label{module-zlib}
\bimodindex{zlib}
For applications that require data compression, the functions in this
@@ -95,5 +96,8 @@
action is to delete the object.
\end{funcdesc}
+\begin{seealso}
+\seemodule{gzip}{reading and writing \file{gzip}-format files}
+\end{seealso}
diff --git a/Doc/libaifc.tex b/Doc/libaifc.tex
index 04ed2e4..590f0d4 100644
--- a/Doc/libaifc.tex
+++ b/Doc/libaifc.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{aifc}}
+\label{module-aifc}
\stmodindex{aifc}
This module provides support for reading and writing AIFF and AIFF-C
diff --git a/Doc/libal.tex b/Doc/libal.tex
index 6a812dd..5655be6 100644
--- a/Doc/libal.tex
+++ b/Doc/libal.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{al}}
+\label{module-al}
\bimodindex{al}
This module provides access to the audio facilities of the SGI Indy
diff --git a/Doc/libamoeba.tex b/Doc/libamoeba.tex
index 54a9dfb..1ff5bd4 100644
--- a/Doc/libamoeba.tex
+++ b/Doc/libamoeba.tex
@@ -82,7 +82,7 @@
aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
>>>
\end{verbatim}\ecode
-
+%
The following methods are defined for capability objects.
\renewcommand{\indexsubitem}{(capability method)}
diff --git a/Doc/libarray.tex b/Doc/libarray.tex
index 1b028b3..eb76251 100644
--- a/Doc/libarray.tex
+++ b/Doc/libarray.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{array}}
+\label{module-array}
\bimodindex{array}
\index{arrays}
diff --git a/Doc/libaudio.tex b/Doc/libaudio.tex
index 47c0b64..f84252e 100644
--- a/Doc/libaudio.tex
+++ b/Doc/libaudio.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{audio}}
+\label{module-audio}
\bimodindex{audio}
\strong{Note:} This module is obsolete, since the hardware to which it
diff --git a/Doc/libaudioop.tex b/Doc/libaudioop.tex
index 40ef0f4..fb6c944 100644
--- a/Doc/libaudioop.tex
+++ b/Doc/libaudioop.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{audioop}}
+\label{module-audioop}
\bimodindex{audioop}
The \code{audioop} module contains some useful operations on sound fragments.
@@ -210,7 +211,7 @@
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
\end{verbatim}\ecode
-
+%
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
diff --git a/Doc/libbase64.tex b/Doc/libbase64.tex
index c487576..ab00ded 100644
--- a/Doc/libbase64.tex
+++ b/Doc/libbase64.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{base64}}
+\label{module-base64}
\stmodindex{base64}
This module perform base-64 encoding and decoding of arbitrary binary
diff --git a/Doc/libbastion.tex b/Doc/libbastion.tex
index 158ec08..dd30284 100644
--- a/Doc/libbastion.tex
+++ b/Doc/libbastion.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{Bastion}}
+\label{module-Bastion}
\stmodindex{Bastion}
\renewcommand{\indexsubitem}{(in module Bastion)}
diff --git a/Doc/libbinascii.tex b/Doc/libbinascii.tex
index 4e3d674..33974c8 100644
--- a/Doc/libbinascii.tex
+++ b/Doc/libbinascii.tex
@@ -1,4 +1,5 @@
\section{Standard module \sectcode{binhex}}
+\label{module-binhex}
\stmodindex{binhex}
This module encodes and decodes files in binhex4 format, a format
diff --git a/Doc/libbltin.tex b/Doc/libbltin.tex
index 63b7c63..6afcac9 100644
--- a/Doc/libbltin.tex
+++ b/Doc/libbltin.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{__builtin__}}
+\label{module-builtin}
\bimodindex{__builtin__}
This module provides direct access to all `built-in' identifiers of
diff --git a/Doc/libcd.tex b/Doc/libcd.tex
index 98ed560..6e64b77 100644
--- a/Doc/libcd.tex
+++ b/Doc/libcd.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{cd}}
+\label{module-cd}
\bimodindex{cd}
This module provides an interface to the Silicon Graphics CD library.
diff --git a/Doc/libcgi.tex b/Doc/libcgi.tex
index 4768f0f..56643d0 100644
--- a/Doc/libcgi.tex
+++ b/Doc/libcgi.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{cgi}}
+\label{module-cgi}
\stmodindex{cgi}
\indexii{WWW}{server}
\indexii{CGI}{protocol}
@@ -39,21 +40,21 @@
telling the client what kind of data is following. Python code to
generate a minimal header section looks like this:
-\begin{verbatim}
- print "Content-type: text/html" # HTML is following
- print # blank line, end of headers
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print "Content-type: text/html" # HTML is following
+print # blank line, end of headers
+\end{verbatim}\ecode
+%
The second section is usually HTML, which allows the client software
to display nicely formatted text with header, in-line images, etc.
Here's Python code that prints a simple piece of HTML:
-\begin{verbatim}
- print "<TITLE>CGI script output</TITLE>"
- print "<H1>This is my first CGI script</H1>"
- print "Hello, world!"
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print "<TITLE>CGI script output</TITLE>"
+print "<H1>This is my first CGI script</H1>"
+print "Hello, world!"
+\end{verbatim}\ecode
+%
(It may not be fully legal HTML according to the letter of the
standard, but any browser will understand it.)
@@ -76,19 +77,19 @@
\code{Content-type} header and blank line have already been printed) checks that
the fields \code{name} and \code{addr} are both set to a non-empty string:
-\begin{verbatim}
- form = cgi.FieldStorage()
- form_ok = 0
- if form.has_key("name") and form.has_key("addr"):
- if form["name"].value != "" and form["addr"].value != "":
- form_ok = 1
- if not form_ok:
- print "<H1>Error</H1>"
- print "Please fill in the name and addr fields."
- return
- ...further form processing here...
-\end{verbatim}
-
+\bcode\begin{verbatim}
+form = cgi.FieldStorage()
+form_ok = 0
+if form.has_key("name") and form.has_key("addr"):
+ if form["name"].value != "" and form["addr"].value != "":
+ form_ok = 1
+if not form_ok:
+ print "<H1>Error</H1>"
+ print "Please fill in the name and addr fields."
+ return
+...further form processing here...
+\end{verbatim}\ecode
+%
Here the fields, accessed through \code{form[key]}, are themselves instances
of \code{FieldStorage} (or \code{MiniFieldStorage}, depending on the form encoding).
@@ -100,40 +101,40 @@
instance or a list of instances. For example, here's code that
concatenates any number of username fields, separated by commas:
-\begin{verbatim}
- username = form["username"]
- if type(username) is type([]):
- # Multiple username fields specified
- usernames = ""
- for item in username:
- if usernames:
- # Next item -- insert comma
- usernames = usernames + "," + item.value
- else:
- # First item -- don't insert comma
- usernames = item.value
- else:
- # Single username field specified
- usernames = username.value
-\end{verbatim}
-
+\bcode\begin{verbatim}
+username = form["username"]
+if type(username) is type([]):
+ # Multiple username fields specified
+ usernames = ""
+ for item in username:
+ if usernames:
+ # Next item -- insert comma
+ usernames = usernames + "," + item.value
+ else:
+ # First item -- don't insert comma
+ usernames = item.value
+else:
+ # Single username field specified
+ usernames = username.value
+\end{verbatim}\ecode
+%
If a field represents an uploaded file, the value attribute reads the
entire file in memory as a string. This may not be what you want. You can
test for an uploaded file by testing either the filename attribute or the
file attribute. You can then read the data at leasure from the file
attribute:
-\begin{verbatim}
- fileitem = form["userfile"]
- if fileitem.file:
- # It's an uploaded file; count lines
- linecount = 0
- while 1:
- line = fileitem.file.readline()
- if not line: break
- linecount = linecount + 1
-\end{verbatim}
-
+\bcode\begin{verbatim}
+fileitem = form["userfile"]
+if fileitem.file:
+ # It's an uploaded file; count lines
+ linecount = 0
+ while 1:
+ line = fileitem.file.readline()
+ if not line: break
+ linecount = linecount + 1
+\end{verbatim}\ecode
+%
The file upload draft standard entertains the possibility of uploading
multiple files from one field (using a recursive \code{multipart/*}
encoding). When this occurs, the item will be a dictionary-like
@@ -251,10 +252,10 @@
that the first line of the script contains \code{\#!} starting in column 1
followed by the pathname of the Python interpreter, for instance:
-\begin{verbatim}
- #!/usr/local/bin/python
-\end{verbatim}
-
+\bcode\begin{verbatim}
+#!/usr/local/bin/python
+\end{verbatim}\ecode
+%
Make sure the Python interpreter exists and is executable by ``others''.
Make sure that any files your script needs to read or write are
@@ -273,12 +274,12 @@
default module search path, you can change the path in your script,
before importing other modules, e.g.:
-\begin{verbatim}
- import sys
- sys.path.insert(0, "/usr/home/joe/lib/python")
- sys.path.insert(0, "/usr/local/lib/python")
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+sys.path.insert(0, "/usr/home/joe/lib/python")
+sys.path.insert(0, "/usr/local/lib/python")
+\end{verbatim}\ecode
+%
(This way, the directory inserted last will be searched first!)
Instructions for non-Unix systems will vary; check your HTTP server's
@@ -311,10 +312,10 @@
in the standard \code{cgi-bin} directory, it should be possible to send it a
request by entering a URL into your browser of the form:
-\begin{verbatim}
- http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
-\end{verbatim}
-
+\bcode\begin{verbatim}
+http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
+\end{verbatim}\ecode
+%
If this gives an error of type 404, the server cannot find the script
-- perhaps you need to install it in a different directory. If it
gives another error (e.g. 500), there's an installation problem that
@@ -328,10 +329,10 @@
The next step could be to call the \code{cgi} module's test() function from
your script: replace its main code with the single statement
-\begin{verbatim}
- cgi.test()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+cgi.test()
+\end{verbatim}\ecode
+%
This should produce the same results as those gotten from installing
the \code{cgi.py} file itself.
@@ -363,19 +364,19 @@
For example:
-\begin{verbatim}
- import sys
- import traceback
- print "Content-type: text/html"
- print
- sys.stderr = sys.stdout
- try:
- ...your code here...
- except:
- print "\n\n<PRE>"
- traceback.print_exc()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+import traceback
+print "Content-type: text/html"
+print
+sys.stderr = sys.stdout
+try:
+ ...your code here...
+except:
+ print "\n\n<PRE>"
+ traceback.print_exc()
+\end{verbatim}\ecode
+%
Notes: The assignment to \code{sys.stderr} is needed because the traceback
prints to \code{sys.stderr}. The \code{print "$\backslash$n$\backslash$n<PRE>"} statement is necessary to
disable the word wrapping in HTML.
@@ -384,14 +385,14 @@
module, you can use an even more robust approach (which only uses
built-in modules):
-\begin{verbatim}
- import sys
- sys.stderr = sys.stdout
- print "Content-type: text/plain"
- print
- ...your code here...
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+sys.stderr = sys.stdout
+print "Content-type: text/plain"
+print
+...your code here...
+\end{verbatim}\ecode
+%
This relies on the Python interpreter to print the traceback. The
content type of the output is set to plain text, which disables all
HTML processing. If your script works, the raw HTML will be displayed
diff --git a/Doc/libcopy.tex b/Doc/libcopy.tex
index 4c0ce72..8f5e03c 100644
--- a/Doc/libcopy.tex
+++ b/Doc/libcopy.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{copy}}
+\label{module-copy}
\stmodindex{copy}
\renewcommand{\indexsubitem}{(copy function)}
\ttindex{copy}
@@ -8,13 +9,13 @@
Interface summary:
-\begin{verbatim}
+\bcode\begin{verbatim}
import copy
x = copy.copy(y) # make a shallow copy of y
x = copy.deepcopy(y) # make a deep copy of y
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
For module specific errors, \code{copy.error} is raised.
The difference between shallow and deep copying is only relevant for
diff --git a/Doc/libcrypt.tex b/Doc/libcrypt.tex
index 132ae51..8a4ec92 100644
--- a/Doc/libcrypt.tex
+++ b/Doc/libcrypt.tex
@@ -1,4 +1,5 @@
-\section{Built-in module {\tt crypt}}
+\section{Built-in Module {\tt crypt}}
+\label{module-crypt}
\bimodindex{crypt}
This module implements an interface to the crypt({\bf 3}) routine,
diff --git a/Doc/libctb.tex b/Doc/libctb.tex
index a5aab71..073c649 100644
--- a/Doc/libctb.tex
+++ b/Doc/libctb.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{ctb}}
+\label{module-ctb}
\bimodindex{ctb}
\renewcommand{\indexsubitem}{(in module ctb)}
diff --git a/Doc/libdbm.tex b/Doc/libdbm.tex
index bae388b..977e05c 100644
--- a/Doc/libdbm.tex
+++ b/Doc/libdbm.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{dbm}}
+\label{module-dbm}
\bimodindex{dbm}
The \code{dbm} module provides an interface to the \UNIX{}
diff --git a/Doc/libfcntl.tex b/Doc/libfcntl.tex
index 3a51ce1..b76a28c 100644
--- a/Doc/libfcntl.tex
+++ b/Doc/libfcntl.tex
@@ -65,7 +65,7 @@
lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata)
\end{verbatim}\ecode
-
+%
Note that in the first example the return value variable \code{rv} will
hold an integer value; in the second example it will hold a string
value. The structure lay-out for the \var{lockadata} variable is
diff --git a/Doc/libfl.tex b/Doc/libfl.tex
index d5332a0..bacbf76 100644
--- a/Doc/libfl.tex
+++ b/Doc/libfl.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{fl}}
+\label{module-fl}
\bimodindex{fl}
This module provides an interface to the FORMS Library by Mark
@@ -471,7 +472,7 @@
import fl
from FL import *
\end{verbatim}\ecode
-
+%
\section{Standard Module \sectcode{flp}}
\stmodindex{flp}
diff --git a/Doc/libfm.tex b/Doc/libfm.tex
index 45d820c..6f1e685 100644
--- a/Doc/libfm.tex
+++ b/Doc/libfm.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{fm}}
+\label{module-fm}
\bimodindex{fm}
This module provides access to the IRIS {\em Font Manager} library.
diff --git a/Doc/libfnmatch.tex b/Doc/libfnmatch.tex
index 78b21a4..86c9073 100644
--- a/Doc/libfnmatch.tex
+++ b/Doc/libfnmatch.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{fnmatch}}
+\label{module-fnmatch}
\stmodindex{fnmatch}
This module provides support for Unix shell-style wildcards, which are
diff --git a/Doc/libformatter.tex b/Doc/libformatter.tex
index 86e6db1..430c9d7 100644
--- a/Doc/libformatter.tex
+++ b/Doc/libformatter.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{formatter}}
+\label{module-formatter}
\stmodindex{formatter}
\renewcommand{\indexsubitem}{(in module formatter)}
diff --git a/Doc/libftplib.tex b/Doc/libftplib.tex
index ba18119..dfbaa2b 100644
--- a/Doc/libftplib.tex
+++ b/Doc/libftplib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{ftplib}}
+\label{module-ftplib}
\stmodindex{ftplib}
\renewcommand{\indexsubitem}{(in module ftplib)}
@@ -13,7 +14,7 @@
Here's a sample session using the \code{ftplib} module:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl') # connect to host, default port
>>> ftp.login() # user anonymous, passwd user@hostname
@@ -26,8 +27,8 @@
.
.
>>> ftp.quit()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The module defines the following items:
\begin{funcdesc}{FTP}{\optional{host\optional{\, user\, passwd\, acct}}}
diff --git a/Doc/libfuncs.tex b/Doc/libfuncs.tex
index 712cb6f..0ef8201 100644
--- a/Doc/libfuncs.tex
+++ b/Doc/libfuncs.tex
@@ -119,7 +119,7 @@
2
>>>
\end{verbatim}\ecode
-
+%
This function can also be used to execute arbitrary code objects
(e.g.\ created by \code{compile()}). In this case pass a code
object instead of a string. The code object must have been compiled
diff --git a/Doc/libgetopt.tex b/Doc/libgetopt.tex
index 7ab46e4..0d2f4a0 100644
--- a/Doc/libgetopt.tex
+++ b/Doc/libgetopt.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{getopt}}
+\label{module-getopt}
\stmodindex{getopt}
This module helps scripts to parse the command line arguments in
@@ -56,7 +57,7 @@
['a1', 'a2']
>>>
\end{verbatim}\ecode
-
+%
Using long option names is equally easy:
\bcode\begin{verbatim}
@@ -72,7 +73,7 @@
['a1', 'a2']
>>>
\end{verbatim}\ecode
-
+%
The exception
\code{getopt.error = 'getopt.error'}
is raised when an unrecognized option is found in the argument list or
diff --git a/Doc/libgl.tex b/Doc/libgl.tex
index c32ea6f..3445465 100644
--- a/Doc/libgl.tex
+++ b/Doc/libgl.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{gl}}
+\label{module-gl}
\bimodindex{gl}
This module provides access to the Silicon Graphics
@@ -43,13 +44,13 @@
\bcode\begin{verbatim}
lmdef(deftype, index, np, props)
\end{verbatim}\ecode
-
+%
is translated to Python as
\bcode\begin{verbatim}
lmdef(deftype, index, props)
\end{verbatim}\ecode
-
+%
\item
Output arguments are omitted from the argument list; they are
transmitted as function return values instead.
@@ -62,13 +63,13 @@
\bcode\begin{verbatim}
getmcolor(i, &red, &green, &blue)
\end{verbatim}\ecode
-
+%
is translated to Python as
\bcode\begin{verbatim}
red, green, blue = getmcolor(i)
\end{verbatim}\ecode
-
+%
\end{itemize}
The following functions are non-standard or have special argument
@@ -183,7 +184,7 @@
main()
\end{verbatim}\ecode
-
+%
\section{Standard Modules \sectcode{GL} and \sectcode{DEVICE}}
\nodename{GL and DEVICE}
\stmodindex{GL}
diff --git a/Doc/libglob.tex b/Doc/libglob.tex
index 142afd8..b63d153 100644
--- a/Doc/libglob.tex
+++ b/Doc/libglob.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{glob}}
+\label{module-glob}
\stmodindex{glob}
\renewcommand{\indexsubitem}{(in module glob)}
@@ -24,7 +25,7 @@
will produce the following results. Notice how any leading components
of the path are preserved.
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
@@ -32,4 +33,4 @@
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libgopherlib.tex b/Doc/libgopherlib.tex
index e94e1f9..6ae913c 100644
--- a/Doc/libgopherlib.tex
+++ b/Doc/libgopherlib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{gopherlib}}
+\label{module-gopherlib}
\stmodindex{gopherlib}
\renewcommand{\indexsubitem}{(in module gopherlib)}
diff --git a/Doc/libgrp.tex b/Doc/libgrp.tex
index 90a2ed3..2942a1b 100644
--- a/Doc/libgrp.tex
+++ b/Doc/libgrp.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{grp}}
+\label{module-grp}
\bimodindex{grp}
This module provides access to the \UNIX{} group database.
diff --git a/Doc/libhtmllib.tex b/Doc/libhtmllib.tex
index bf57ea9..aaa2072 100644
--- a/Doc/libhtmllib.tex
+++ b/Doc/libhtmllib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{htmllib}}
+\label{module-htmllib}
\stmodindex{htmllib}
\index{HTML}
\index{hypertext}
@@ -38,11 +39,11 @@
unprocessed data, call the \code{close()} method.
For example, to parse the entire contents of a file, use:
-\begin{verbatim}
+\bcode\begin{verbatim}
parser.feed(open('myfile.html').read())
parser.close()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\item
The interface to define semantics for HTML tags is very simple: derive
a class and define methods called \code{start_\var{tag}()},
diff --git a/Doc/libhttplib.tex b/Doc/libhttplib.tex
index 70bcb3c..7671ab3 100644
--- a/Doc/libhttplib.tex
+++ b/Doc/libhttplib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{httplib}}
+\label{module-httplib}
\stmodindex{httplib}
\index{HTTP}
@@ -19,12 +20,12 @@
following calls all create instances that connect to the server at the
same host and port:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> h1 = httplib.HTTP('www.cwi.nl')
>>> h2 = httplib.HTTP('www.cwi.nl:80')
>>> h3 = httplib.HTTP('www.cwi.nl', 80)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Once an \code{HTTP} instance has been connected to an HTTP server, it
should be used as follows:
@@ -111,7 +112,7 @@
Here is an example session:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import httplib
>>> h = httplib.HTTP('www.cwi.nl')
>>> h.putrequest('GET', '/index.html')
@@ -124,4 +125,4 @@
>>> data f.read() # Get the raw HTML
>>> f.close()
>>>
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libimageop.tex b/Doc/libimageop.tex
index 4e15117..48f9188 100644
--- a/Doc/libimageop.tex
+++ b/Doc/libimageop.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{imageop}}
+\label{module-imageop}
\bimodindex{imageop}
The \code{imageop} module contains some useful operations on images.
diff --git a/Doc/libimgfile.tex b/Doc/libimgfile.tex
index 1e8b2aa..96afc9b 100644
--- a/Doc/libimgfile.tex
+++ b/Doc/libimgfile.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{imgfile}}
+\label{module-imgfile}
\bimodindex{imgfile}
The imgfile module allows python programs to access SGI imglib image
diff --git a/Doc/libimghdr.tex b/Doc/libimghdr.tex
index 22d4d0d..0dec8a1 100644
--- a/Doc/libimghdr.tex
+++ b/Doc/libimghdr.tex
@@ -1,4 +1,5 @@
\section{Standard module \sectcode{imghdr}}
+\label{module-imghdr}
\stmodindex{imghdr}
The \code{imghdr} module determines the type of image contained in a
@@ -53,8 +54,8 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import imghdr
>>> imghdr.what('/tmp/bass.gif')
'gif'
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libimp.tex b/Doc/libimp.tex
index e1e4a53..0f63524 100644
--- a/Doc/libimp.tex
+++ b/Doc/libimp.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{imp}}
+\label{module-imp}
\bimodindex{imp}
\index{import}
@@ -132,7 +133,7 @@
\subsection{Examples}
The following function emulates the default import statement:
-\begin{verbatim}
+\bcode\begin{verbatim}
import imp
import sys
@@ -171,4 +172,4 @@
finally:
# Since we may exit via an exception, close fp explicitly.
fp.close()
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libjpeg.tex b/Doc/libjpeg.tex
index 8215cad..0d1dc1c 100644
--- a/Doc/libjpeg.tex
+++ b/Doc/libjpeg.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{jpeg}}
+\label{module-jpeg}
\bimodindex{jpeg}
The module \code{jpeg} provides access to the jpeg compressor and
diff --git a/Doc/libmacconsole.tex b/Doc/libmacconsole.tex
index 42d4e51..4f67ab1 100644
--- a/Doc/libmacconsole.tex
+++ b/Doc/libmacconsole.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{macconsole}}
+\label{module-macconsole}
\bimodindex{macconsole}
\renewcommand{\indexsubitem}{(in module macconsole)}
diff --git a/Doc/libmacdnr.tex b/Doc/libmacdnr.tex
index ab45788..5ae59a6 100644
--- a/Doc/libmacdnr.tex
+++ b/Doc/libmacdnr.tex
@@ -1,5 +1,5 @@
-
\section{Built-in Module \sectcode{macdnr}}
+\label{module-macdnr}
\bimodindex{macdnr}
This module provides an interface to the Macintosh Domain Name
@@ -111,9 +111,9 @@
The simplest way to use the module to convert names to dotted-decimal
strings, without worrying about idle time, etc:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> def gethostname(name):
... import macdnr
... dnrr = macdnr.StrToAddr(name)
... return macdnr.AddrToStr(dnrr.ip0)
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libmacfs.tex b/Doc/libmacfs.tex
index be566cb..6f63a47 100644
--- a/Doc/libmacfs.tex
+++ b/Doc/libmacfs.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{macfs}}
+\label{module-macfs}
\bimodindex{macfs}
\renewcommand{\indexsubitem}{(in module macfs)}
diff --git a/Doc/libmacos.tex b/Doc/libmacos.tex
index 2b7628f..6975380 100644
--- a/Doc/libmacos.tex
+++ b/Doc/libmacos.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{MacOS}}
+\label{module-MacOS}
\bimodindex{MacOS}
\renewcommand{\indexsubitem}{(in module MacOS)}
diff --git a/Doc/libmacostools.tex b/Doc/libmacostools.tex
index 3a3c3a3..680b4ed 100644
--- a/Doc/libmacostools.tex
+++ b/Doc/libmacostools.tex
@@ -1,5 +1,5 @@
-
\section{Standard module \sectcode{macostools}}
+\label{module-macostools}
\stmodindex{macostools}
This module contains some convenience routines for file-manipulation
diff --git a/Doc/libmacspeech.tex b/Doc/libmacspeech.tex
index fc35520..d3b6e96 100644
--- a/Doc/libmacspeech.tex
+++ b/Doc/libmacspeech.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{macspeech}}
+\label{module-macspeech}
\bimodindex{macspeech}
\renewcommand{\indexsubitem}{(in module macspeech)}
diff --git a/Doc/libmactcp.tex b/Doc/libmactcp.tex
index 80e19ca..4d6d5ba 100644
--- a/Doc/libmactcp.tex
+++ b/Doc/libmactcp.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{mactcp}}
+\label{module-mactcp}
\bimodindex{mactcp}
\renewcommand{\indexsubitem}{(in module mactcp)}
diff --git a/Doc/libmacui.tex b/Doc/libmacui.tex
index 56a00c3..d519bf5 100644
--- a/Doc/libmacui.tex
+++ b/Doc/libmacui.tex
@@ -1,4 +1,5 @@
\section{Standard module \sectcode{EasyDialogs}}
+\label{module-EasyDialogs}
\stmodindex{EasyDialogs}
The \code{EasyDialogs} module contains some simple dialogs for
diff --git a/Doc/libmailcap.tex b/Doc/libmailcap.tex
index 7fea9b5..d7d47c4 100644
--- a/Doc/libmailcap.tex
+++ b/Doc/libmailcap.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{mailcap}}
+\label{module-mailcap}
\stmodindex{mailcap}
\renewcommand{\indexsubitem}{(in module mailcap)}
@@ -67,9 +68,9 @@
\end{funcdesc}
An example usage:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import mailcap
>>> d=mailcap.getcaps()
>>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223')
('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'})
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libmain.tex b/Doc/libmain.tex
index c730a03..8ce73a8 100644
--- a/Doc/libmain.tex
+++ b/Doc/libmain.tex
@@ -1,5 +1,5 @@
\section{Built-in Module \sectcode{__main__}}
-
+\label{module-main}
\bimodindex{__main__}
This module represents the (otherwise anonymous) scope in which the
interpreter's main program executes --- commands read either from
diff --git a/Doc/libmarshal.tex b/Doc/libmarshal.tex
index 58becdb..16472db 100644
--- a/Doc/libmarshal.tex
+++ b/Doc/libmarshal.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{marshal}}
+\label{module-marshal}
\bimodindex{marshal}
This module contains functions that can read and write Python
diff --git a/Doc/libmath.tex b/Doc/libmath.tex
index 765fcdf..935b940 100644
--- a/Doc/libmath.tex
+++ b/Doc/libmath.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{math}}
+\label{module-math}
\bimodindex{math}
\renewcommand{\indexsubitem}{(in module math)}
@@ -70,3 +71,7 @@
\else
\code{pi} and \code{e}.
\fi
+
+\begin{seealso}
+\seealso{cmath}{versions of these functions that can handle complex numbers}
+\end{seealso}
diff --git a/Doc/libmd5.tex b/Doc/libmd5.tex
index 773f93c..d71bacd 100644
--- a/Doc/libmd5.tex
+++ b/Doc/libmd5.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{md5}}
+\label{module-md5}
\bimodindex{md5}
This module implements the interface to RSA's MD5 message digest
@@ -21,14 +22,14 @@
>>> m.digest()
'\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("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}}
diff --git a/Doc/libmimetools.tex b/Doc/libmimetools.tex
index ecf50dc..41a62ba 100644
--- a/Doc/libmimetools.tex
+++ b/Doc/libmimetools.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{mimetools}}
+\label{module-mimetools}
\stmodindex{mimetools}
\renewcommand{\indexsubitem}{(in module mimetools)}
diff --git a/Doc/libmpz.tex b/Doc/libmpz.tex
index 46a2d47..9fb165b 100644
--- a/Doc/libmpz.tex
+++ b/Doc/libmpz.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{mpz}}
+\label{module-mpz}
\bimodindex{mpz}
This is an optional module. It is only available when Python is
diff --git a/Doc/libnntplib.tex b/Doc/libnntplib.tex
index 2641d82..41539b4 100644
--- a/Doc/libnntplib.tex
+++ b/Doc/libnntplib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{nntplib}}
+\label{module-nntplib}
\stmodindex{nntplib}
\renewcommand{\indexsubitem}{(in module nntplib)}
@@ -13,7 +14,7 @@
articles:
\small{
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> s = NNTP('news.cwi.nl')
>>> resp, count, first, last, name = s.group('comp.lang.python')
>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
@@ -34,13 +35,13 @@
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
-\end{verbatim}
+\end{verbatim}\ecode
}
To post an article from a file (this assumes that the article has
valid headers):
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> s = NNTP('news.cwi.nl')
>>> f = open('/tmp/article')
>>> s.post(f)
@@ -48,8 +49,8 @@
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The module itself defines the following items:
\begin{funcdesc}{NNTP}{host\optional{\, port}}
diff --git a/Doc/liboperator.tex b/Doc/liboperator.tex
index 7fed767..d7c11fc 100644
--- a/Doc/liboperator.tex
+++ b/Doc/liboperator.tex
@@ -184,10 +184,10 @@
Example: Build a dictionary that maps the ordinals from 0 to 256 to their
character equivalents.
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import operator
>>> d = {}
>>> keys = range(256)
>>> vals = map(chr, keys)
>>> map(operator.setitem, [d]*len(keys), keys, vals)
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libos.tex b/Doc/libos.tex
index 51442ef..f17ce95 100644
--- a/Doc/libos.tex
+++ b/Doc/libos.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{os}}
+\label{module-os}
\stmodindex{os}
This module provides a more portable way of using operating system
diff --git a/Doc/libpanel.tex b/Doc/libpanel.tex
index b82bf98..a696f30 100644
--- a/Doc/libpanel.tex
+++ b/Doc/libpanel.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{panel}}
+\label{module-panel}
\stmodindex{panel}
\strong{Please note:} The FORMS library, to which the \code{fl} module described
diff --git a/Doc/libparser.tex b/Doc/libparser.tex
index a51b01b..4503358 100644
--- a/Doc/libparser.tex
+++ b/Doc/libparser.tex
@@ -288,30 +288,30 @@
this purpose, using the \code{parser} module to produce an
intermediate data structure is equivelent to the code
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> code = compile('a + 5', 'eval')
>>> a = 5
>>> eval(code)
10
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The equivelent operation using the \code{parser} module is somewhat
longer, and allows the intermediate internal parse tree to be retained
as an AST object:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import parser
>>> ast = parser.expr('a + 5')
>>> code = parser.compileast(ast)
>>> a = 5
>>> eval(code)
10
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
An application which needs both AST and code objects can package this
code into readily available functions:
-\begin{verbatim}
+\bcode\begin{verbatim}
import parser
def load_suite(source_string):
@@ -323,8 +323,8 @@
ast = parser.expr(source_string)
code = parser.compileast(ast)
return ast, code
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\subsubsection{Information Discovery}
Some applications benefit from direct access to the parse tree. The
@@ -366,16 +366,16 @@
a module consisting of a docstring and nothing else. (See file
\file{docstring.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
"""Some documentation.
"""
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Using the interpreter to take a look at the parse tree, we find a
bewildering mass of numbers and parentheses, with the documentation
buried deep in nested tuples.
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import parser
>>> import pprint
>>> ast = parser.suite(open('docstring.py').read())
@@ -403,8 +403,8 @@
(4, ''))),
(4, ''),
(0, ''))
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The numbers at the first element of each node in the tree are the node
types; they map directly to terminal and non-terminal symbols in the
grammar. Unfortunately, they are represented as integers in the
@@ -442,7 +442,7 @@
the pattern matching, returning a boolean and a dictionary of variable
name to value mappings. (See file \file{example.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
from types import ListType, TupleType
def match(pattern, data, vars=None):
@@ -460,13 +460,13 @@
if not same:
break
return same, vars
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Using this simple representation for syntactic variables and the symbolic
node types, the pattern for the candidate docstring subtrees becomes
fairly readable. (See file \file{example.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
import symbol
import token
@@ -493,19 +493,19 @@
)))))))))))))))),
(token.NEWLINE, '')
))
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Using the \code{match()} function with this pattern, extracting the
module docstring from the parse tree created previously is easy:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
>>> found
1
>>> vars
{'docstring': '"""Some documentation.\012"""'}
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Once specific data can be extracted from a location where it is
expected, the question of where information can be expected
needs to be answered. When dealing with docstrings, the answer is
@@ -567,7 +567,7 @@
objects requires further examination. Here is the relevant part of
the \code{SuiteInfoBase} definition from \file{example.py}:
-\begin{verbatim}
+\bcode\begin{verbatim}
class SuiteInfoBase:
_docstring = ''
_name = ''
@@ -597,8 +597,8 @@
elif cstmt[0] == symbol.classdef:
name = cstmt[2][1]
self._class_info[name] = ClassInfo(cstmt)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
After initializing some internal state, the constructor calls the
\code{_extract_info()} method. This method performs the bulk of the
information extraction which takes place in the entire example. The
@@ -611,21 +611,21 @@
the code block is on the same line as the definition of the code
block, as in
-\begin{verbatim}
+\bcode\begin{verbatim}
def square(x): "Square an argument."; return x ** 2
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
while the long form uses an indented block and allows nested
definitions:
-\begin{verbatim}
+\bcode\begin{verbatim}
def make_power(exp):
"Make a function that raises an argument to the exponent `exp'."
def raiser(x, y=exp):
return x ** y
return raiser
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
When the short form is used, the code block may contain a docstring as
the first, and possibly only, \code{small_stmt} element. The
extraction of such a docstring is slightly different and requires only
@@ -660,7 +660,7 @@
blocks. A high-level function can be used to extract the complete set
of information from a source file. (See file \file{example.py}.)
-\begin{verbatim}
+\bcode\begin{verbatim}
def get_docs(fileName):
source = open(fileName).read()
import os
@@ -669,8 +669,8 @@
ast = parser.suite(source)
tup = parser.ast2tuple(ast)
return ModuleInfo(tup, basename)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
This provides an easy-to-use interface to the documentation of a
module. If information is required which is not extracted by the code
of this example, the code may be extended at clearly defined points to
diff --git a/Doc/libpdb.tex b/Doc/libpdb.tex
index 84ae332..9785a40 100644
--- a/Doc/libpdb.tex
+++ b/Doc/libpdb.tex
@@ -29,7 +29,7 @@
The debugger's prompt is ``\code{(Pdb) }''.
Typical usage to run a program under control of the debugger is:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
@@ -40,15 +40,15 @@
NameError: 'spam'
> <string>(1)?()
(Pdb)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\code{pdb.py} can also be invoked as
a script to debug other scripts. For example:
\code{python /usr/local/lib/python1.4/pdb.py myscript.py}
Typical usage to inspect a crashed program is:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import pdb
>>> import mymodule
>>> mymodule.test()
@@ -63,8 +63,8 @@
> ./mymodule.py(3)test2()
-> print spam
(Pdb)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The module defines the following functions; each enters the debugger
in a slightly different way:
@@ -224,11 +224,11 @@
of the statement resembles a debugger command.
To set a global variable, you can prefix the assignment
command with a ``\code{global}'' command on the same line, e.g.:
-\begin{verbatim}
+\bcode\begin{verbatim}
(Pdb) global list_options; list_options = ['-l']
(Pdb)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\item[q(uit)]
Quit from the debugger.
diff --git a/Doc/libpickle.tex b/Doc/libpickle.tex
index 128b29d..cb054a7 100644
--- a/Doc/libpickle.tex
+++ b/Doc/libpickle.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{pickle}}
+\label{module-pickle}
\stmodindex{pickle}
\index{persistency}
\indexii{persistent}{objects}
@@ -133,30 +134,30 @@
To pickle an object \code{x} onto a file \code{f}, open for writing:
-\begin{verbatim}
+\bcode\begin{verbatim}
p = pickle.Pickler(f)
p.dump(x)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
A shorthand for this is:
-\begin{verbatim}
+\bcode\begin{verbatim}
pickle.dump(x, f)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
To unpickle an object \code{x} from a file \code{f}, open for reading:
-\begin{verbatim}
+\bcode\begin{verbatim}
u = pickle.Unpickler(f)
x = u.load()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
A shorthand is:
-\begin{verbatim}
+\bcode\begin{verbatim}
x = pickle.load(f)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
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),
diff --git a/Doc/libposix.tex b/Doc/libposix.tex
index 7edd93e..e545c7a 100644
--- a/Doc/libposix.tex
+++ b/Doc/libposix.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{posix}}
+\label{module-posix}
\bimodindex{posix}
This module provides access to operating system functionality that is
diff --git a/Doc/libppath.tex b/Doc/libppath.tex
index 9078560..6bd8a20 100644
--- a/Doc/libppath.tex
+++ b/Doc/libppath.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{posixpath}}
+\label{module-posixpath}
\stmodindex{posixpath}
This module implements some useful functions on POSIX pathnames.
diff --git a/Doc/libprofile.tex b/Doc/libprofile.tex
index 7cd3c6b..2f69170 100644
--- a/Doc/libprofile.tex
+++ b/Doc/libprofile.tex
@@ -103,11 +103,11 @@
To profile an application with a main entry point of \samp{foo()}, you
would add the following to your module:
-\begin{verbatim}
- import profile
- profile.run("foo()")
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import profile
+profile.run("foo()")
+\end{verbatim}\ecode
+%
The above action would cause \samp{foo()} to be run, and a series of
informative lines (the profile) to be printed. The above approach is
most useful when working with the interpreter. If you would like to
@@ -115,11 +115,11 @@
can supply a file name as the second argument to the \code{run()}
function:
-\begin{verbatim}
- import profile
- profile.run("foo()", 'fooprof')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import profile
+profile.run("foo()", 'fooprof')
+\end{verbatim}\ecode
+%
\code{profile.py} can also be invoked as
a script to profile another script. For example:
\code{python /usr/local/lib/python1.4/profile.py myscript.py}
@@ -128,40 +128,40 @@
\code{pstats} module. Typically you would load the statistics data as
follows:
-\begin{verbatim}
- import pstats
- p = pstats.Stats('fooprof')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import pstats
+p = pstats.Stats('fooprof')
+\end{verbatim}\ecode
+%
The class \code{Stats} (the above code just created an instance of
this class) has a variety of methods for manipulating and printing the
data that was just read into \samp{p}. When you ran
\code{profile.run()} above, what was printed was the result of three
method calls:
-\begin{verbatim}
- p.strip_dirs().sort_stats(-1).print_stats()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.strip_dirs().sort_stats(-1).print_stats()
+\end{verbatim}\ecode
+%
The first method removed the extraneous path from all the module
names. The second method sorted all the entries according to the
standard module/line/name string that is printed (this is to comply
with the semantics of the old profiler). The third method printed out
all the statistics. You might try the following sort calls:
-\begin{verbatim}
- p.sort_stats('name')
- p.print_stats()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('name')
+p.print_stats()
+\end{verbatim}\ecode
+%
The first call will actually sort the list by function name, and the
second call will print out the statistics. The following are some
interesting calls to experiment with:
-\begin{verbatim}
- p.sort_stats('cumulative').print_stats(10)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('cumulative').print_stats(10)
+\end{verbatim}\ecode
+%
This sorts the profile by cumulative time in a function, and then only
prints the ten most significant lines. If you want to understand what
algorithms are taking time, the above line is what you would use.
@@ -169,27 +169,27 @@
If you were looking to see what functions were looping a lot, and
taking a lot of time, you would do:
-\begin{verbatim}
- p.sort_stats('time').print_stats(10)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('time').print_stats(10)
+\end{verbatim}\ecode
+%
to sort according to time spent within each function, and then print
the statistics for the top ten functions.
You might also try:
-\begin{verbatim}
- p.sort_stats('file').print_stats('__init__')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('file').print_stats('__init__')
+\end{verbatim}\ecode
+%
This will sort all the statistics by file name, and then print out
statistics for only the class init methods ('cause they are spelled
with \code{__init__} in them). As one final example, you could try:
-\begin{verbatim}
- p.sort_stats('time', 'cum').print_stats(.5, 'init')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.sort_stats('time', 'cum').print_stats(.5, 'init')
+\end{verbatim}\ecode
+%
This line sorts statistics with a primary key of time, and a secondary
key of cumulative time, and then prints out some of the statistics.
To be specific, the list is first culled down to 50\% (re: \samp{.5})
@@ -199,21 +199,20 @@
If you wondered what functions called the above functions, you could
now (\samp{p} is still sorted according to the last criteria) do:
-\begin{verbatim}
- p.print_callers(.5, 'init')
-\end{verbatim}
-
+\bcode\begin{verbatim}
+p.print_callers(.5, 'init')
+\end{verbatim}\ecode
+%
and you would get a list of callers for each of the listed functions.
If you want more functionality, you're going to have to read the
manual, or guess what the following functions do:
-\begin{verbatim}
- p.print_callees()
- p.add('fooprof')
-\end{verbatim}
-
-
+\bcode\begin{verbatim}
+p.print_callees()
+p.add('fooprof')
+\end{verbatim}\ecode
+%
\section{What Is Deterministic Profiling?}
\nodename{Deterministic Profiling}
@@ -272,7 +271,7 @@
each line. The following is a typical output from such a call:
\small{
-\begin{verbatim}
+\bcode\begin{verbatim}
main()
2706 function calls (2004 primitive calls) in 4.504 CPU seconds
@@ -282,7 +281,7 @@
2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)
43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)
...
-\end{verbatim}
+\end{verbatim}\ecode
}
The first line indicates that this profile was generated by the call:\\
@@ -446,18 +445,18 @@
several restrictions are provided, then they are applied sequentially.
For example:
-\begin{verbatim}
- print_stats(.1, "foo:")
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print_stats(.1, "foo:")
+\end{verbatim}\ecode
+%
would first limit the printing to first 10\% of list, and then only
print functions that were part of filename \samp{.*foo:}. In
contrast, the command:
-\begin{verbatim}
- print_stats("foo:", .1)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print_stats("foo:", .1)
+\end{verbatim}\ecode
+%
would limit the list to all functions having file names \samp{.*foo:},
and then proceed to only print the first 10\% of them.
\end{funcdesc}
@@ -486,11 +485,11 @@
return the instance that is being processed, so that the commands can
be strung together. For example:
-\begin{verbatim}
+\bcode\begin{verbatim}
pstats.Stats('foofile').strip_dirs().sort_stats('cum') \
.print_stats().ignore()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
would perform all the indicated functions, but it would not return
the final reference to the \code{Stats} instance.%
\footnote{
@@ -550,28 +549,28 @@
be used to obtain this constant for a given platform (see discussion
in section Limitations above).
-\begin{verbatim}
- import profile
- pr = profile.Profile()
- pr.calibrate(100)
- pr.calibrate(100)
- pr.calibrate(100)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import profile
+pr = profile.Profile()
+pr.calibrate(100)
+pr.calibrate(100)
+pr.calibrate(100)
+\end{verbatim}\ecode
+%
The argument to calibrate() is the number of times to try to do the
sample calls to get the CPU times. If your computer is \emph{very}
fast, you might have to do:
-\begin{verbatim}
- pr.calibrate(1000)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+pr.calibrate(1000)
+\end{verbatim}\ecode
+%
or even:
-\begin{verbatim}
- pr.calibrate(10000)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+pr.calibrate(10000)
+\end{verbatim}\ecode
+%
The object of this exercise is to get a fairly consistent result.
When you have a consistent answer, you are ready to use that number in
the source code. For a Sun Sparcstation 1000 running Solaris 2.3, the
@@ -583,27 +582,27 @@
class should be modified to install the calibration constant on a Sun
Sparcstation 1000:
-\begin{verbatim}
- def trace_dispatch(self, frame, event, arg):
+\bcode\begin{verbatim}
+def trace_dispatch(self, frame, event, arg):
+ t = self.timer()
+ t = t[0] + t[1] - self.t - .00053 # Calibration constant
+
+ if self.dispatch[event](frame,t):
t = self.timer()
- t = t[0] + t[1] - self.t - .00053 # Calibration constant
-
- if self.dispatch[event](frame,t):
- t = self.timer()
- self.t = t[0] + t[1]
- else:
- r = self.timer()
- self.t = r[0] + r[1] - t # put back unrecorded delta
- return
-\end{verbatim}
-
+ self.t = t[0] + t[1]
+ else:
+ r = self.timer()
+ self.t = r[0] + r[1] - t # put back unrecorded delta
+ return
+\end{verbatim}\ecode
+%
Note that if there is no calibration constant, then the line
containing the callibration constant should simply say:
-\begin{verbatim}
- t = t[0] + t[1] - self.t # no calibration constant
-\end{verbatim}
-
+\bcode\begin{verbatim}
+t = t[0] + t[1] - self.t # no calibration constant
+\end{verbatim}\ecode
+%
You can also achieve the same results using a derived class (and the
profiler will actually run equally fast!!), but the above method is
the simplest to use. I could have made the profiler ``self
@@ -631,10 +630,10 @@
the constructor for the class. Consider passing the name of a
function to call into the constructor:
-\begin{verbatim}
- pr = profile.Profile(your_time_func)
-\end{verbatim}
-
+\bcode\begin{verbatim}
+pr = profile.Profile(your_time_func)
+\end{verbatim}\ecode
+%
The resulting profiler will call \code{your_time_func()} instead of
\code{os.times()}. The function should return either a single number
or a list of numbers (like what \code{os.times()} returns). If the
@@ -663,7 +662,7 @@
user's code. It is also a lot more accurate than the old profiler, as
it does not charge all its overhead time to the user's code.
-\begin{verbatim}
+\bcode\begin{verbatim}
class OldProfile(Profile):
def trace_dispatch_exception(self, frame, t):
@@ -713,9 +712,8 @@
callers[func_caller]
nc = nc + callers[func_caller]
self.stats[nor_func] = nc, nc, tt, ct, nor_callers
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\subsection{HotProfile Class}
This profiler is the fastest derived profile example. It does not
@@ -725,7 +723,7 @@
the basic profiler is so fast, that is probably not worth the savings
to give up the data, but this class still provides a nice example.
-\begin{verbatim}
+\bcode\begin{verbatim}
class HotProfile(Profile):
def trace_dispatch_exception(self, frame, t):
@@ -761,4 +759,4 @@
nc, tt = self.timings[func]
nor_func = self.func_normalize(func)
self.stats[nor_func] = nc, nc, tt, 0, {}
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libpwd.tex b/Doc/libpwd.tex
index 7bb30d8..073c19a 100644
--- a/Doc/libpwd.tex
+++ b/Doc/libpwd.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{pwd}}
+\label{module-pwd}
\bimodindex{pwd}
This module provides access to the \UNIX{} password database.
diff --git a/Doc/libquopri.tex b/Doc/libquopri.tex
index 0314f8a..2fbd35a 100644
--- a/Doc/libquopri.tex
+++ b/Doc/libquopri.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{quopri}}
+\label{module-quopri}
\stmodindex{quopri}
This module performs quoted-printable transport encoding and decoding,
diff --git a/Doc/librand.tex b/Doc/librand.tex
index 5a4df3e..0660566 100644
--- a/Doc/librand.tex
+++ b/Doc/librand.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{rand}}
+\label{module-rand}
\stmodindex{rand}
The \code{rand} module simulates the C library's \code{rand()}
@@ -20,3 +21,7 @@
can be an arbitrary integer.
\end{funcdesc}
+\begin{seealso}
+\seemodule{whrandom}{the standard Python random number generator}
+\end{seealso}
+
diff --git a/Doc/librandom.tex b/Doc/librandom.tex
index 3bc92ce..b8d5f78 100644
--- a/Doc/librandom.tex
+++ b/Doc/librandom.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{random}}
+\label{module-random}
\stmodindex{random}
This module implements pseudo-random number generators for various
@@ -69,3 +70,8 @@
distribution reduces to a uniform random angle over the range 0 to
\code{2*pi}.
\end{funcdesc}
+
+
+\begin{seealso}
+\seemodule{whrandom}{the standard Python random number generator}
+\end{seealso}
diff --git a/Doc/libregex.tex b/Doc/libregex.tex
index d3f44ba..ee1563d 100644
--- a/Doc/libregex.tex
+++ b/Doc/libregex.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{regex}}
+\label{module-regex}
\bimodindex{regex}
This module provides regular expression matching operations similar to
@@ -204,13 +205,13 @@
prog = regex.compile(pat)
result = prog.match(str)
\end{verbatim}\ecode
-
+%
is equivalent to
\bcode\begin{verbatim}
result = regex.match(pat, str)
\end{verbatim}\ecode
-
+%
but the version using \code{compile()} is more efficient when multiple
regular expressions are used concurrently in a single program. (The
compiled version of the last pattern passed to \code{regex.match()} or
diff --git a/Doc/libregsub.tex b/Doc/libregsub.tex
index d075e99..6d48986 100644
--- a/Doc/libregsub.tex
+++ b/Doc/libregsub.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{regsub}}
+\label{module-regsub}
\stmodindex{regsub}
This module defines a number of functions useful for working with
diff --git a/Doc/libresource.tex b/Doc/libresource.tex
index ff78025..5c93fa6 100644
--- a/Doc/libresource.tex
+++ b/Doc/libresource.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{resource}}
+\label{module-resource}
\bimodindex{resource}
This module provides basic mechanisms for measuring and controlling
diff --git a/Doc/librexec.tex b/Doc/librexec.tex
index 4b1a100..742e32b 100644
--- a/Doc/librexec.tex
+++ b/Doc/librexec.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{rexec}}
+\label{module-rexec}
\stmodindex{rexec}
\renewcommand{\indexsubitem}{(in module rexec)}
@@ -206,7 +207,7 @@
else: raise IOError, "Illegal open() mode"
return open(file, mode, buf)
\end{verbatim}\ecode
-
+%
Notice that the above code will occasionally forbid a perfectly valid
filename; for example, code in the restricted environment won't be
able to open a file called \file{/tmp/foo/../bar}. To fix this, the
diff --git a/Doc/librfc822.tex b/Doc/librfc822.tex
index 3617e8a..cd3d271 100644
--- a/Doc/librfc822.tex
+++ b/Doc/librfc822.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{rfc822}}
+\label{module-rfc822}
\stmodindex{rfc822}
\renewcommand{\indexsubitem}{(in module rfc822)}
diff --git a/Doc/librgbimg.tex b/Doc/librgbimg.tex
index ace426f..d923fc2 100644
--- a/Doc/librgbimg.tex
+++ b/Doc/librgbimg.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{rgbimg}}
+\label{module-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 c333686..a3431fc 100644
--- a/Doc/librotor.tex
+++ b/Doc/librotor.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{rotor}}
+\label{module-rotor}
\bimodindex{rotor}
This module implements a rotor-based encryption algorithm, contributed by
@@ -79,7 +80,7 @@
'l(\315'
>>> del rt
\end{verbatim}\ecode
-
+%
The module's code is not an exact simulation of the original Enigma device;
it implements the rotor encryption scheme differently from the original. The
most important difference is that in the original Enigma, there were only 5
diff --git a/Doc/libselect.tex b/Doc/libselect.tex
index 0b50101..4291dbf 100644
--- a/Doc/libselect.tex
+++ b/Doc/libselect.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{select}}
+\label{module-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 dc3582b..19ce91c 100644
--- a/Doc/libsgmllib.tex
+++ b/Doc/libsgmllib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{sgmllib}}
+\label{module-sgmllib}
\stmodindex{sgmllib}
\index{SGML}
diff --git a/Doc/libshelve.tex b/Doc/libshelve.tex
index a232add..05b3a93 100644
--- a/Doc/libshelve.tex
+++ b/Doc/libshelve.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{shelve}}
+\label{module-shelve}
\stmodindex{shelve}
\stmodindex{pickle}
\bimodindex{dbm}
@@ -14,7 +15,7 @@
To summarize the interface (\code{key} is a string, \code{data} is an
arbitrary object):
-\begin{verbatim}
+\bcode\begin{verbatim}
import shelve
d = shelve.open(filename) # open, with (g)dbm filename -- no suffix
@@ -29,8 +30,8 @@
list = d.keys() # a list of all existing keys (slow!)
d.close() # close it
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
Restrictions:
\begin{itemize}
diff --git a/Doc/libsignal.tex b/Doc/libsignal.tex
index 802c4d1..2844b57 100644
--- a/Doc/libsignal.tex
+++ b/Doc/libsignal.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{signal}}
+\label{module-signal}
\bimodindex{signal}
This module provides mechanisms to use signal handlers in Python.
diff --git a/Doc/libsite.tex b/Doc/libsite.tex
index c97fd4e..9b7eb91 100644
--- a/Doc/libsite.tex
+++ b/Doc/libsite.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{site}}
+\label{module-site}
\stmodindex{site}
Scripts or modules that need to use site-specific modules should
diff --git a/Doc/libsocket.tex b/Doc/libsocket.tex
index 9d5536c..5422796 100644
--- a/Doc/libsocket.tex
+++ b/Doc/libsocket.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{socket}}
+\label{module-socket}
\bimodindex{socket}
This module provides access to the BSD {\em socket} interface.
@@ -336,7 +337,7 @@
conn.send(data)
conn.close()
\end{verbatim}\ecode
-
+%
\bcode\begin{verbatim}
# Echo client program
from socket import *
@@ -349,3 +350,7 @@
s.close()
print 'Received', `data`
\end{verbatim}\ecode
+%
+\begin{seealso}
+\seemodule{SocketServer}{classes that simplify writing network servers}
+\end{seealso}
diff --git a/Doc/libsoundex.tex b/Doc/libsoundex.tex
index 4c15c55..373da38 100644
--- a/Doc/libsoundex.tex
+++ b/Doc/libsoundex.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{soundex}}
+\label{module-soundex}
\stmodindex{soundex}
\renewcommand{\indexsubitem}{(in module soundex)}
diff --git a/Doc/libstat.tex b/Doc/libstat.tex
index 67335a5..bb3b66a 100644
--- a/Doc/libstat.tex
+++ b/Doc/libstat.tex
@@ -81,7 +81,7 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
import os, sys
from stat import *
@@ -103,4 +103,4 @@
print 'frobbed', file
if __name__ == '__main__': process(sys.argv[1], f)
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/libstdwin.tex b/Doc/libstdwin.tex
index 2f2bd42..514252f 100644
--- a/Doc/libstdwin.tex
+++ b/Doc/libstdwin.tex
@@ -774,7 +774,7 @@
main()
\end{verbatim}\ecode
-
+%
\section{Standard Module \sectcode{stdwinevents}}
\stmodindex{stdwinevents}
@@ -788,7 +788,7 @@
>>> from stdwinevents import *
>>>
\end{verbatim}\ecode
-
+%
\section{Standard Module \sectcode{rect}}
\stmodindex{rect}
@@ -801,7 +801,7 @@
\bcode\begin{verbatim}
(10, 20), (90, 80)
\end{verbatim}\ecode
-
+%
is a rectangle whose left, top, right and bottom edges are 10, 20, 90
and 80, respectively.
Note that the positive vertical axis points down (as in
diff --git a/Doc/libstring.tex b/Doc/libstring.tex
index 7b91717..930ce22 100644
--- a/Doc/libstring.tex
+++ b/Doc/libstring.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{string}}
+\label{module-string}
\stmodindex{string}
diff --git a/Doc/libstruct.tex b/Doc/libstruct.tex
index f7879f1..d57a2b7 100644
--- a/Doc/libstruct.tex
+++ b/Doc/libstruct.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{struct}}
+\label{module-struct}
\bimodindex{struct}
\indexii{C}{structures}
@@ -126,7 +127,7 @@
8
>>>
\end{verbatim}\ecode
-
+%
Hint: to align the end of a structure to the alignment requirement of
a particular type, end the format with the code for that type with a
repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two
diff --git a/Doc/libsys.tex b/Doc/libsys.tex
index ae02d8d..f137052 100644
--- a/Doc/libsys.tex
+++ b/Doc/libsys.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{sys}}
+\label{module-sys}
\bimodindex{sys}
This module provides access to some variables used or maintained by the
diff --git a/Doc/libsyslog.tex b/Doc/libsyslog.tex
index 5b4fdde..37d6b66 100644
--- a/Doc/libsyslog.tex
+++ b/Doc/libsyslog.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{syslog}}
+\label{module-syslog}
\bimodindex{syslog}
This module provides an interface to the Unix \code{syslog} library
diff --git a/Doc/libtempfile.tex b/Doc/libtempfile.tex
index 0a582e1..e033f70 100644
--- a/Doc/libtempfile.tex
+++ b/Doc/libtempfile.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{tempfile}}
+\label{module-tempfile}
\stmodindex{tempfile}
\indexii{temporary}{file name}
\indexii{temporary}{file}
diff --git a/Doc/libtemplate.tex b/Doc/libtemplate.tex
index cd49a8f..1edc21d 100644
--- a/Doc/libtemplate.tex
+++ b/Doc/libtemplate.tex
@@ -96,13 +96,13 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import spam
>>> can = spam.open('/etc/passwd')
>>> can.empty()
>>> can.close()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
% ==== 5. ====
% If your module defines new object types (for a built-in module) or
% classes (for a module written in Python), you should list the
diff --git a/Doc/libtermios.tex b/Doc/libtermios.tex
index 3d007c3..2d233f2 100644
--- a/Doc/libtermios.tex
+++ b/Doc/libtermios.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{termios}}
+\label{module-termios}
\bimodindex{termios}
\indexii{Posix}{I/O control}
\indexii{tty}{I/O control}
@@ -76,7 +77,7 @@
and a \code{try \ldots{} finally} statement to ensure that the old tty
attributes are restored exactly no matter what happens:
-\begin{verbatim}
+\bcode\begin{verbatim}
def getpass(prompt = "Password: "):
import termios, TERMIOS, sys
fd = sys.stdin.fileno()
@@ -89,9 +90,8 @@
finally:
termios.tcsetattr(fd, TERMIOS.TCSADRAIN, old)
return passwd
-\end{verbatim}
-
-
+\end{verbatim}\ecode
+%
\section{Standard Module \sectcode{TERMIOS}}
\stmodindex{TERMIOS}
\indexii{Posix}{I/O control}
diff --git a/Doc/libthread.tex b/Doc/libthread.tex
index f745384..080a35c 100644
--- a/Doc/libthread.tex
+++ b/Doc/libthread.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{thread}}
+\label{module-thread}
\bimodindex{thread}
This module provides low-level primitives for working with multiple
diff --git a/Doc/libtime.tex b/Doc/libtime.tex
index 7ee886d..e352505 100644
--- a/Doc/libtime.tex
+++ b/Doc/libtime.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{time}}
+\label{module-time}
\bimodindex{time}
This module provides various time-related functions.
diff --git a/Doc/libtraceback.tex b/Doc/libtraceback.tex
index ca9c374..4fcc4d1 100644
--- a/Doc/libtraceback.tex
+++ b/Doc/libtraceback.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{traceback}}
+\label{module-traceback}
\stmodindex{traceback}
\renewcommand{\indexsubitem}{(in module traceback)}
diff --git a/Doc/libtypes2.tex b/Doc/libtypes2.tex
index d0f20c9..afb02e5 100644
--- a/Doc/libtypes2.tex
+++ b/Doc/libtypes2.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{types}}
+\label{module-types}
\stmodindex{types}
\renewcommand{\indexsubitem}{(in module types)}
@@ -13,15 +14,15 @@
Typical use is for functions that do different things depending on
their argument types, like the following:
-\begin{verbatim}
+\bcode\begin{verbatim}
from types import *
def delete(list, item):
if type(item) is IntType:
del list[item]
else:
list.remove(item)
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The module defines the following names:
\begin{datadesc}{NoneType}
diff --git a/Doc/liburllib.tex b/Doc/liburllib.tex
index 8fe7132..51a700a 100644
--- a/Doc/liburllib.tex
+++ b/Doc/liburllib.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{urllib}}
+\label{module-urllib}
\stmodindex{urllib}
\index{WWW}
\index{World-Wide Web}
diff --git a/Doc/liburlparse.tex b/Doc/liburlparse.tex
index 36ca949..76fd9f8 100644
--- a/Doc/liburlparse.tex
+++ b/Doc/liburlparse.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{urlparse}}
+\label{module-urlparse}
\stmodindex{urlparse}
\index{WWW}
\index{World-Wide Web}
@@ -34,16 +35,16 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
yields the tuple
-\begin{verbatim}
+\bcode\begin{verbatim}
('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
If the \var{default_scheme} argument is specified, it gives the
default addressing scheme, to be used only if the URL string does not
specify one. The default value for this argument is the empty string.
@@ -69,16 +70,16 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
yields the string
-\begin{verbatim}
+\bcode\begin{verbatim}
'http://www.cwi.nl/%7Eguido/FAQ.html'
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
The \var{allow_fragments} argument has the same meaning as for
\code{urlparse}.
\end{funcdesc}
diff --git a/Doc/libwhichdb.tex b/Doc/libwhichdb.tex
index fbdfa8c..19bca3a 100644
--- a/Doc/libwhichdb.tex
+++ b/Doc/libwhichdb.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{whichdb}}
+\label{module-whichdb}
\stmodindex{whichdb}
The single function in this module attempts to guess which of the
diff --git a/Doc/libwhrandom.tex b/Doc/libwhrandom.tex
index 6094462..09d7816 100644
--- a/Doc/libwhrandom.tex
+++ b/Doc/libwhrandom.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{whrandom}}
+\label{module-whrandom}
\stmodindex{whrandom}
This module implements a Wichmann-Hill pseudo-random number generator
@@ -36,7 +37,14 @@
the \code{whrandom} class, and makes the methods of that instance
available at the module level. Therefore one can write either
\code{N = whrandom.random()} or:
-\begin{verbatim}
+\bcode\begin{verbatim}
generator = whrandom.whrandom()
N = generator.random()
-\end{verbatim}
+\end{verbatim}\ecode
+%
+\begin{seealso}
+\seemodule{random}{generators for various random distributions}
+\seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
+An efficient and portable pseudo-random number generator'',
+Applied Statistics 31 (1982) 188-190}
+\end{seealso}
diff --git a/Doc/libxdrlib.tex b/Doc/libxdrlib.tex
index 1221fff..0de5695 100644
--- a/Doc/libxdrlib.tex
+++ b/Doc/libxdrlib.tex
@@ -1,4 +1,5 @@
\section{Standard module \sectcode{xdrlib}}
+\label{module-xdrlib}
\stmodindex{xdrlib}
\index{XDR}
@@ -221,15 +222,15 @@
Here is an example of how you would catch one of these exceptions:
-\begin{verbatim}
+\bcode\begin{verbatim}
import xdrlib
p = xdrlib.Packer()
try:
p.pack_double(8.01)
except xdrlib.ConversionError, instance:
print 'packing the double failed:', instance.msg
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
\subsection{Supporting Floating Point Data}
Packing and unpacking floating point data,
diff --git a/Doc/libzlib.tex b/Doc/libzlib.tex
index ab30a32..28365ae 100644
--- a/Doc/libzlib.tex
+++ b/Doc/libzlib.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{zlib}}
+\label{module-zlib}
\bimodindex{zlib}
For applications that require data compression, the functions in this
@@ -95,5 +96,8 @@
action is to delete the object.
\end{funcdesc}
+\begin{seealso}
+\seemodule{gzip}{reading and writing \file{gzip}-format files}
+\end{seealso}
diff --git a/Doc/mac/libctb.tex b/Doc/mac/libctb.tex
index a5aab71..073c649 100644
--- a/Doc/mac/libctb.tex
+++ b/Doc/mac/libctb.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{ctb}}
+\label{module-ctb}
\bimodindex{ctb}
\renewcommand{\indexsubitem}{(in module ctb)}
diff --git a/Doc/mac/libmacconsole.tex b/Doc/mac/libmacconsole.tex
index 42d4e51..4f67ab1 100644
--- a/Doc/mac/libmacconsole.tex
+++ b/Doc/mac/libmacconsole.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{macconsole}}
+\label{module-macconsole}
\bimodindex{macconsole}
\renewcommand{\indexsubitem}{(in module macconsole)}
diff --git a/Doc/mac/libmacdnr.tex b/Doc/mac/libmacdnr.tex
index ab45788..5ae59a6 100644
--- a/Doc/mac/libmacdnr.tex
+++ b/Doc/mac/libmacdnr.tex
@@ -1,5 +1,5 @@
-
\section{Built-in Module \sectcode{macdnr}}
+\label{module-macdnr}
\bimodindex{macdnr}
This module provides an interface to the Macintosh Domain Name
@@ -111,9 +111,9 @@
The simplest way to use the module to convert names to dotted-decimal
strings, without worrying about idle time, etc:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> def gethostname(name):
... import macdnr
... dnrr = macdnr.StrToAddr(name)
... return macdnr.AddrToStr(dnrr.ip0)
-\end{verbatim}
+\end{verbatim}\ecode
diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex
index be566cb..6f63a47 100644
--- a/Doc/mac/libmacfs.tex
+++ b/Doc/mac/libmacfs.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{macfs}}
+\label{module-macfs}
\bimodindex{macfs}
\renewcommand{\indexsubitem}{(in module macfs)}
diff --git a/Doc/mac/libmacos.tex b/Doc/mac/libmacos.tex
index 2b7628f..6975380 100644
--- a/Doc/mac/libmacos.tex
+++ b/Doc/mac/libmacos.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{MacOS}}
+\label{module-MacOS}
\bimodindex{MacOS}
\renewcommand{\indexsubitem}{(in module MacOS)}
diff --git a/Doc/mac/libmacostools.tex b/Doc/mac/libmacostools.tex
index 3a3c3a3..680b4ed 100644
--- a/Doc/mac/libmacostools.tex
+++ b/Doc/mac/libmacostools.tex
@@ -1,5 +1,5 @@
-
\section{Standard module \sectcode{macostools}}
+\label{module-macostools}
\stmodindex{macostools}
This module contains some convenience routines for file-manipulation
diff --git a/Doc/mac/libmacspeech.tex b/Doc/mac/libmacspeech.tex
index fc35520..d3b6e96 100644
--- a/Doc/mac/libmacspeech.tex
+++ b/Doc/mac/libmacspeech.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{macspeech}}
+\label{module-macspeech}
\bimodindex{macspeech}
\renewcommand{\indexsubitem}{(in module macspeech)}
diff --git a/Doc/mac/libmactcp.tex b/Doc/mac/libmactcp.tex
index 80e19ca..4d6d5ba 100644
--- a/Doc/mac/libmactcp.tex
+++ b/Doc/mac/libmactcp.tex
@@ -1,4 +1,5 @@
\section{Built-in Module \sectcode{mactcp}}
+\label{module-mactcp}
\bimodindex{mactcp}
\renewcommand{\indexsubitem}{(in module mactcp)}
diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex
index 56a00c3..d519bf5 100644
--- a/Doc/mac/libmacui.tex
+++ b/Doc/mac/libmacui.tex
@@ -1,4 +1,5 @@
\section{Standard module \sectcode{EasyDialogs}}
+\label{module-EasyDialogs}
\stmodindex{EasyDialogs}
The \code{EasyDialogs} module contains some simple dialogs for
diff --git a/Doc/templates/module.tex b/Doc/templates/module.tex
index cd49a8f..1edc21d 100644
--- a/Doc/templates/module.tex
+++ b/Doc/templates/module.tex
@@ -96,13 +96,13 @@
Example:
-\begin{verbatim}
+\bcode\begin{verbatim}
>>> import spam
>>> can = spam.open('/etc/passwd')
>>> can.empty()
>>> can.close()
-\end{verbatim}
-
+\end{verbatim}\ecode
+%
% ==== 5. ====
% If your module defines new object types (for a built-in module) or
% classes (for a module written in Python), you should list the