diff options
196 files changed, 1068 insertions, 859 deletions
diff --git a/Doc/ext.tex b/Doc/ext.tex index d168aa671d..af4a66791f 100644 --- a/Doc/ext.tex +++ b/Doc/ext.tex @@ -82,11 +82,11 @@ This function takes a null-terminated character string as argument and 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 @@ is called \file{spammodule.c}; if the module name is very long, like 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 @@ The next thing we add to our module file is the C function that will 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 @@ is evaluated (we'll see shortly how it ends up being called): 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 @@ You can also define a new exception that is unique to your module. 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 @@ checking for now): 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 @@ the string \code{"spam.error"}. 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 @@ to modify the string to which it points (so in Standard C, the variable 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 @@ as a Python object. This is done using the function 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 @@ If you have a C function that returns no useful argument (a function 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 @@ I promised to show how \code{spam_system()} is called from Python 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 @@ The method table must be passed to the interpreter in the module's 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 @@ very simple: just place your file (\file{spammodule.c} for example) in 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 @@ you change the \file{Setup} file.) 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 @@ called, save a pointer to the Python function object (be careful to 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 @@ definition: 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 @@ a singleton tuple. \code{Py_BuildValue()} returns a tuple when its 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 @@ parentheses. For example: 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 @@ calling Python code can handle the exception. If this is not possible 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 @@ tuple to pass as the argument list. The simplest way to do this is to 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 @@ event code, you might use the following code: 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 @@ be checked. 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 @@ Clearly, \samp{:} and \samp{;} mutually exclude each other. Some example calls: -\begin{verbatim} +\bcode\begin{verbatim} int ok; int i, j; long k, l; @@ -726,18 +725,17 @@ Some example calls: /* 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 @@ If there is an error in the format string, the 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 @@ Examples (to the left the call, to the right the resulting Python value): "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 @@ The first and most important case to know about is using \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 @@ The solution, once you know the source of the problem, is easy: 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 @@ no_bug(PyObject *list) { 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 @@ calls, to let other threads use the CPU while waiting for the I/O to 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 @@ bug(PyObject *list) { 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 @@ done using a special invocation of the \UNIX{} loader/linker, {\em 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 d168aa671d..af4a66791f 100644 --- a/Doc/ext/ext.tex +++ b/Doc/ext/ext.tex @@ -82,11 +82,11 @@ This function takes a null-terminated character string as argument and 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 @@ is called \file{spammodule.c}; if the module name is very long, like 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 @@ The next thing we add to our module file is the C function that will 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 @@ is evaluated (we'll see shortly how it ends up being called): 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 @@ You can also define a new exception that is unique to your module. 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 @@ checking for now): 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 @@ the string \code{"spam.error"}. 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 @@ to modify the string to which it points (so in Standard C, the variable 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 @@ as a Python object. This is done using the function 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 @@ If you have a C function that returns no useful argument (a function 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 @@ I promised to show how \code{spam_system()} is called from Python 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 @@ The method table must be passed to the interpreter in the module's 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 @@ very simple: just place your file (\file{spammodule.c} for example) in 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 @@ you change the \file{Setup} file.) 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 @@ called, save a pointer to the Python function object (be careful to 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 @@ definition: 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 @@ a singleton tuple. \code{Py_BuildValue()} returns a tuple when its 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 @@ parentheses. For example: 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 @@ calling Python code can handle the exception. If this is not possible 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 @@ tuple to pass as the argument list. The simplest way to do this is to 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 @@ event code, you might use the following code: 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 @@ be checked. 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 @@ Clearly, \samp{:} and \samp{;} mutually exclude each other. Some example calls: -\begin{verbatim} +\bcode\begin{verbatim} int ok; int i, j; long k, l; @@ -726,18 +725,17 @@ Some example calls: /* 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 @@ If there is an error in the format string, the 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 @@ Examples (to the left the call, to the right the resulting Python value): "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 @@ The first and most important case to know about is using \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 @@ The solution, once you know the source of the problem, is easy: 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 @@ no_bug(PyObject *list) { 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 @@ calls, to let other threads use the CPU while waiting for the I/O to 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 @@ bug(PyObject *list) { 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 @@ done using a special invocation of the \UNIX{} loader/linker, {\em 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 04ed2e421a..590f0d42eb 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 6a812ddab0..5655be66a9 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 54a9dfbd53..1ff5bd424a 100644 --- a/Doc/lib/libamoeba.tex +++ b/Doc/lib/libamoeba.tex @@ -82,7 +82,7 @@ For example: 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 1b028b339d..eb76251645 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 40ef0f4c4d..fb6c944662 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 @@ def mul_stereo(sample, width, lfactor, rfactor): 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 c487576ae6..ab00ded922 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 158ec081c3..dd302844d4 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 4e3d67414c..33974c8c52 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 63b7c6394a..6afcac946a 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 98ed560261..6e64b77760 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 4768f0f3c8..56643d05fc 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 @@ by a blank line. The first section contains a number of headers, telling the client what kind of data is following. Python code to generate a minimal header section looks like this: -\begin{verbatim} - print "Content-type: text/html" # HTML is following - print # blank line, end of headers -\end{verbatim} - +\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 @@ dictionary. For instance, the following code (which assumes that the \code{Content-type} header and blank line have already been printed) checks that the fields \code{name} and \code{addr} are both set to a non-empty string: -\begin{verbatim} - form = cgi.FieldStorage() - form_ok = 0 - if form.has_key("name") and form.has_key("addr"): - if form["name"].value != "" and form["addr"].value != "": - form_ok = 1 - if not form_ok: - print "<H1>Error</H1>" - print "Please fill in the name and addr fields." - return - ...further form processing here... -\end{verbatim} - +\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 @@ name), use the \code{type()} function to determine whether you have a single instance or a list of instances. For example, here's code that concatenates any number of username fields, separated by commas: -\begin{verbatim} - username = form["username"] - if type(username) is type([]): - # Multiple username fields specified - usernames = "" - for item in username: - if usernames: - # Next item -- insert comma - usernames = usernames + "," + item.value - else: - # First item -- don't insert comma - usernames = item.value - else: - # Single username field specified - usernames = username.value -\end{verbatim} - +\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 @@ Unix file mode should be 755 (use \code{chmod 755 filename}). Make sure that the first line of the script contains \code{\#!} starting in column 1 followed by the pathname of the Python interpreter, for instance: -\begin{verbatim} - #!/usr/local/bin/python -\end{verbatim} - +\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 @@ If you need to load modules from a directory which is not on Python's default module search path, you can change the path in your script, before importing other modules, e.g.: -\begin{verbatim} - import sys - sys.path.insert(0, "/usr/home/joe/lib/python") - sys.path.insert(0, "/usr/local/lib/python") -\end{verbatim} - +\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 @@ Give it the right mode etc, and send it a request. If it's installed 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 @@ script, you should now be able to debug it. 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 @@ Here are the rules: 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 @@ If you suspect that there may be a problem in importing the traceback module, you can use an even more robust approach (which only uses built-in modules): -\begin{verbatim} - import sys - sys.stderr = sys.stdout - print "Content-type: text/plain" - print - ...your code here... -\end{verbatim} - +\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 4c0ce72bbd..8f5e03cf02 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 @@ This module provides generic (shallow and deep) copying operations. 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 132ae514ee..8a4ec92752 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 bae388b97a..977e05c829 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 3a51ce1c6e..b76a28cfad 100644 --- a/Doc/lib/libfcntl.tex +++ b/Doc/lib/libfcntl.tex @@ -65,7 +65,7 @@ rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1) lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0) rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata) \end{verbatim}\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 d5332a0602..bacbf76868 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 @@ the defined names. Suggested use: 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 45d820c0b0..6f1e685193 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 78b21a478d..86c907373b 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 86e6db16fb..430c9d7164 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 ba18119a6b..dfbaa2be07 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 @@ more information on FTP (File Transfer Protocol), see Internet RFC 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 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. . . >>> 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 712cb6f83d..0ef8201781 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -119,7 +119,7 @@ be added to the end of the the argument list. 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 7ab46e4052..0d2f4a0bfb 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 @@ An example using only \UNIX{} style options: ['a1', 'a2'] >>> \end{verbatim}\ecode - +% Using long option names is equally easy: \bcode\begin{verbatim} @@ -72,7 +73,7 @@ Using long option names is equally easy: ['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 c32ea6f581..34454657b1 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 @@ For example, the C call \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 @@ Examples: the C call \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 @@ def main(): 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 142afd8021..b63d153969 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 @@ For example, consider a directory containing only the following files: 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 @@ of the path are preserved. ['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 e94e1f9c6c..6ae913c5ec 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 90a2ed3339..2942a1bc6b 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 bf57ea90ef..aaa2072d38 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 @@ incomplete elements are saved in a buffer. To force processing of all 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 70bcb3c8d2..7671ab3622 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 @@ method should be used to connect to a server. For example, the following calls all create instances that connect to the server at the same host and port: -\begin{verbatim} +\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 @@ methods. 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 @@ Here is an example session: >>> 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 4e151170d0..48f9188009 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 1e8b2aaa9b..96afc9bb07 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 22d4d0d5e3..0dec8a16bf 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 @@ the test succeeded, or \code{None} if it failed. 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 e1e4a53779..0f63524ec1 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 @@ The module was found as dynamically loadable shared library. \subsection{Examples} The following function emulates the default import statement: -\begin{verbatim} +\bcode\begin{verbatim} import imp import sys @@ -171,4 +172,4 @@ def __import__(name, globals=None, locals=None, fromlist=None): 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 8215cada56..0d1dc1ce4c 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 7fea9b5abb..d7d47c4c92 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 @@ will override settings in the system mailcap files \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 c730a03a11..8ce73a8081 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 58becdb336..16472db622 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 765fcdf5c6..935b9403c1 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 @@ The module also defines two mathematical constants: \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 773f93c660..d71bacda08 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 @@ the spammish repetition"}: >>> 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 ecf50dc5fa..41a62bab66 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 46a2d474dc..9fb165ba37 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 2641d82cd8..41539b4113 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 @@ statistics about a newsgroup and print the subjects of the last 10 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 @@ Group comp.lang.python has 59 articles, range 3742 to 3803 >>> 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 @@ valid headers): >>> 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 7fed767c14..d7c11fc84d 100644 --- a/Doc/lib/liboperator.tex +++ b/Doc/lib/liboperator.tex @@ -184,10 +184,10 @@ Delete the slice of a from index b to index c-1. 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 51442efcfc..f17ce9574f 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 b82bf98bfe..a696f30bde 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 a51b01b7c0..4503358b96 100644 --- a/Doc/lib/libparser.tex +++ b/Doc/lib/libparser.tex @@ -288,30 +288,30 @@ bytecode generation, the simplest operation is to do nothing. For 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 @@ def load_expression(source_string): 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 @@ Consider the simplest case of interest when searching for docstrings: a module consisting of a docstring and nothing else. (See file \file{docstring.py}.) -\begin{verbatim} +\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 @@ buried deep in nested tuples. (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 @@ form, allowing a simple variable representation to be 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 @@ def match(pattern, data, vars=None): 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 @@ DOCSTRING_STMT_PATTERN = ( )))))))))))))))), (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 @@ grammar, but the method which recursively creates new information 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 @@ class SuiteInfoBase: 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 ``short form'' or the ``long form.'' The short form is used when the code block is on the same line as the definition of the code block, as in -\begin{verbatim} +\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 @@ the real extraction algorithm remains common to all forms of code blocks. A high-level function can be used to extract the complete set of information from a source file. (See file \file{example.py}.) -\begin{verbatim} +\bcode\begin{verbatim} def get_docs(fileName): source = open(fileName).read() import os @@ -669,8 +669,8 @@ def get_docs(fileName): 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 84ae3321ef..9785a406d3 100644 --- a/Doc/lib/libpdb.tex +++ b/Doc/lib/libpdb.tex @@ -29,7 +29,7 @@ specific modules). 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 @@ Typical usage to run a program under control of the debugger is: 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 @@ NameError: spam > ./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 @@ The exclamation point can be omitted unless the first word of the statement resembles a debugger command. To set a global variable, you can prefix the assignment command with a ``\code{global}'' command on the same line, e.g.: -\begin{verbatim} +\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 128b29de46..cb054a78a9 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 @@ The interface can be summarized as follows. 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 7edd93e14b..e545c7a7b4 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 9078560b70..6bd8a20ea0 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 7cd3c6b352..2f691708b1 100644 --- a/Doc/lib/libprofile.tex +++ b/Doc/lib/libprofile.tex @@ -103,11 +103,11 @@ rapidly perform profiling on an existing application. To profile an application with a main entry point of \samp{foo()}, you would add the following to your module: -\begin{verbatim} - import profile - profile.run("foo()") -\end{verbatim} - +\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 @@ save the results of a profile into a file for later examination, you 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 @@ When you wish to review the profile, you should use the methods in the \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 @@ algorithms are taking time, the above line is what you would use. If you were looking to see what functions were looping a lot, and taking a lot of time, you would do: -\begin{verbatim} - p.sort_stats('time').print_stats(10) -\end{verbatim} - +\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 @@ maintained, and that sub-sub-list is printed. If you wondered what functions called the above functions, you could now (\samp{p} is still sorted according to the last criteria) do: -\begin{verbatim} - p.print_callers(.5, 'init') -\end{verbatim} - +\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 @@ standard name string (file/line/function-name) that is presented in 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 @@ ncalls tottime percall cumtime percall filename:lineno(function) 2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects) 43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate) ... -\end{verbatim} +\end{verbatim}\ecode } The first line indicates that this profile was generated by the call:\\ @@ -446,18 +445,18 @@ expression (to pattern match the standard name that is printed). If 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 @@ returned by earlier methods. All standard methods in this class return the instance that is being processed, so that the commands can be strung together. For example: -\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 @@ function, and socking away the results. The following procedure can be used to obtain this constant for a given platform (see discussion in section Limitations above). -\begin{verbatim} - import profile - pr = profile.Profile() - 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 @@ The following shows how the trace_dispatch() method in the Profile class should be modified to install the calibration constant on a Sun Sparcstation 1000: -\begin{verbatim} - def trace_dispatch(self, frame, event, arg): - t = self.timer() - t = t[0] + t[1] - self.t - .00053 # Calibration constant - - if self.dispatch[event](frame,t): - t = self.timer() - self.t = t[0] + t[1] - else: - r = self.timer() - self.t = r[0] + r[1] - t # put back unrecorded delta - return -\end{verbatim} +\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() + 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 @@ timer function is used, then the basic class has an option for that in the constructor for the class. Consider passing the name of a function to call into the constructor: -\begin{verbatim} - pr = profile.Profile(your_time_func) -\end{verbatim} - +\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 @@ stats, and is quite useful when there is \emph{no} recursion in the user's code. It is also a lot more accurate than the old profiler, as it does not charge all its overhead time to the user's code. -\begin{verbatim} +\bcode\begin{verbatim} class OldProfile(Profile): def trace_dispatch_exception(self, frame, t): @@ -713,9 +712,8 @@ class OldProfile(Profile): 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 @@ function, so it runs very quickly (re: very low overhead). In truth, the basic profiler is so fast, that is probably not worth the savings to give up the data, but this class still provides a nice example. -\begin{verbatim} +\bcode\begin{verbatim} class HotProfile(Profile): def trace_dispatch_exception(self, frame, t): @@ -761,4 +759,4 @@ class HotProfile(Profile): 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 7bb30d80e2..073c19a4b6 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 0314f8ab92..2fbd35aa89 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 5a4df3eb50..06605661ca 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 @@ Set a starting seed value for the random number generator; \var{seed} can be an arbitrary integer. \end{funcdesc} +\begin{seealso} +\seemodule{whrandom}{the standard Python random number generator} +\end{seealso} + diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex index 3bc92ce3bc..b8d5f78137 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 @@ then or equal to zero. If \var{kappa} is equal to zero, this 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 d3f44ba862..ee1563d566 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 @@ The module defines these functions, and an exception: 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 d075e99e8c..6d489861d7 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 ff78025ca3..5c93fa6097 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 4b1a10028c..742e32bad5 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 @@ class TmpWriterRExec(rexec.RExec): 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 3617e8aa65..cd3d271cdf 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 ace426fa98..d923fc28e8 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 c333686a24..a3431fc874 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 @@ An example usage: '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 0b50101395..4291dbfae4 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 dc3582b078..19ce91c803 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 a232add09d..05b3a93d3e 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 @@ sub-objects. The keys are ordinary strings. 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 @@ flag = d.has_key(key) # true if the key exists list = d.keys() # a list of all existing keys (slow!) d.close() # close it -\end{verbatim} - +\end{verbatim}\ecode +% Restrictions: \begin{itemize} diff --git a/Doc/lib/libsignal.tex b/Doc/lib/libsignal.tex index 802c4d107f..2844b57891 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 c97fd4e1c9..9b7eb91ff2 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 9d5536cc50..5422796a0b 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 @@ while 1: conn.send(data) conn.close() \end{verbatim}\ecode - +% \bcode\begin{verbatim} # Echo client program from socket import * @@ -349,3 +350,7 @@ data = s.recv(1024) 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 4c15c55aaa..373da3890a 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 67335a54ac..bb3b66a27d 100644 --- a/Doc/lib/libstat.tex +++ b/Doc/lib/libstat.tex @@ -81,7 +81,7 @@ Time of creation. Example: -\begin{verbatim} +\bcode\begin{verbatim} import os, sys from stat import * @@ -103,4 +103,4 @@ def f(file): 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 2f2bd42924..514252f442 100644 --- a/Doc/lib/libstdwin.tex +++ b/Doc/lib/libstdwin.tex @@ -774,7 +774,7 @@ def main(): main() \end{verbatim}\ecode - +% \section{Standard Module \sectcode{stdwinevents}} \stmodindex{stdwinevents} @@ -788,7 +788,7 @@ Suggested usage is >>> from stdwinevents import * >>> \end{verbatim}\ecode - +% \section{Standard Module \sectcode{rect}} \stmodindex{rect} @@ -801,7 +801,7 @@ For example, the rectangle \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 7b91717e22..930ce22d1d 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 f7879f1eda..d57a2b790a 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 @@ big-endian machine): 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 ae02d8da89..f137052301 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 5b4fdded4b..37d6b6614a 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 0a582e12dc..e033f70f93 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 cd49a8f74e..1edc21d3b5 100644 --- a/Doc/lib/libtemplate.tex +++ b/Doc/lib/libtemplate.tex @@ -96,13 +96,13 @@ failure. 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 3d007c3e1d..2d233f2022 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 @@ Note the technique using a separate \code{termios.tcgetattr()} call 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 @@ def getpass(prompt = "Password: "): 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 f7453844db..080a35cf1f 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 7ee886d69f..e3525057ee 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 ca9c374859..4fcc4d145d 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 d0f20c9db7..afb02e5cfb 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 @@ all end in \code{Type}. 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 8fe71322e9..51a700a72b 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 36ca949ba6..76fd9f8263 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 @@ retained if present. 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 @@ components in the relative URL. 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 fbdfa8c805..19bca3a159 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 6094462890..09d7816521 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 @@ When imported, the \code{whrandom} module also creates an instance of the \code{whrandom} class, and makes the methods of that instance available at the module level. Therefore one can write either \code{N = whrandom.random()} or: -\begin{verbatim} +\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 1221fffd08..0de56957a5 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 @@ variables. 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 ab30a32498..28365ae3bb 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 @@ uncompressed output is returned. After calling \code{flush()}, the 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 04ed2e421a..590f0d42eb 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 6a812ddab0..5655be66a9 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 54a9dfbd53..1ff5bd424a 100644 --- a/Doc/libamoeba.tex +++ b/Doc/libamoeba.tex @@ -82,7 +82,7 @@ For example: 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 1b028b339d..eb76251645 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 47c0b643c7..f84252e5b4 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 40ef0f4c4d..fb6c944662 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 @@ def mul_stereo(sample, width, lfactor, rfactor): 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 c487576ae6..ab00ded922 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 158ec081c3..dd302844d4 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 4e3d67414c..33974c8c52 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 63b7c6394a..6afcac946a 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 98ed560261..6e64b77760 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 4768f0f3c8..56643d05fc 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 @@ by a blank line. The first section contains a number of headers, telling the client what kind of data is following. Python code to generate a minimal header section looks like this: -\begin{verbatim} - print "Content-type: text/html" # HTML is following - print # blank line, end of headers -\end{verbatim} - +\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 @@ dictionary. For instance, the following code (which assumes that the \code{Content-type} header and blank line have already been printed) checks that the fields \code{name} and \code{addr} are both set to a non-empty string: -\begin{verbatim} - form = cgi.FieldStorage() - form_ok = 0 - if form.has_key("name") and form.has_key("addr"): - if form["name"].value != "" and form["addr"].value != "": - form_ok = 1 - if not form_ok: - print "<H1>Error</H1>" - print "Please fill in the name and addr fields." - return - ...further form processing here... -\end{verbatim} - +\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 @@ name), use the \code{type()} function to determine whether you have a single instance or a list of instances. For example, here's code that concatenates any number of username fields, separated by commas: -\begin{verbatim} - username = form["username"] - if type(username) is type([]): - # Multiple username fields specified - usernames = "" - for item in username: - if usernames: - # Next item -- insert comma - usernames = usernames + "," + item.value - else: - # First item -- don't insert comma - usernames = item.value - else: - # Single username field specified - usernames = username.value -\end{verbatim} - +\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 @@ Unix file mode should be 755 (use \code{chmod 755 filename}). Make sure that the first line of the script contains \code{\#!} starting in column 1 followed by the pathname of the Python interpreter, for instance: -\begin{verbatim} - #!/usr/local/bin/python -\end{verbatim} - +\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 @@ If you need to load modules from a directory which is not on Python's default module search path, you can change the path in your script, before importing other modules, e.g.: -\begin{verbatim} - import sys - sys.path.insert(0, "/usr/home/joe/lib/python") - sys.path.insert(0, "/usr/local/lib/python") -\end{verbatim} - +\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 @@ Give it the right mode etc, and send it a request. If it's installed 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 @@ script, you should now be able to debug it. 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 @@ Here are the rules: 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 @@ If you suspect that there may be a problem in importing the traceback module, you can use an even more robust approach (which only uses built-in modules): -\begin{verbatim} - import sys - sys.stderr = sys.stdout - print "Content-type: text/plain" - print - ...your code here... -\end{verbatim} - +\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 4c0ce72bbd..8f5e03cf02 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 @@ This module provides generic (shallow and deep) copying operations. 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 132ae514ee..8a4ec92752 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 a5aab71421..073c649346 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 bae388b97a..977e05c829 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 3a51ce1c6e..b76a28cfad 100644 --- a/Doc/libfcntl.tex +++ b/Doc/libfcntl.tex @@ -65,7 +65,7 @@ rv = fcntl(file.fileno(), FCNTL.O_NDELAY, 1) lockdata = struct.pack('hhllhh', FCNTL.F_WRLCK, 0, 0, 0, 0, 0) rv = fcntl(file.fileno(), FCNTL.F_SETLKW, lockdata) \end{verbatim}\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 d5332a0602..bacbf76868 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 @@ the defined names. Suggested use: 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 45d820c0b0..6f1e685193 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 78b21a478d..86c907373b 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 86e6db16fb..430c9d7164 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 ba18119a6b..dfbaa2be07 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 @@ more information on FTP (File Transfer Protocol), see Internet RFC 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 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. . . >>> 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 712cb6f83d..0ef8201781 100644 --- a/Doc/libfuncs.tex +++ b/Doc/libfuncs.tex @@ -119,7 +119,7 @@ be added to the end of the the argument list. 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 7ab46e4052..0d2f4a0bfb 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 @@ An example using only \UNIX{} style options: ['a1', 'a2'] >>> \end{verbatim}\ecode - +% Using long option names is equally easy: \bcode\begin{verbatim} @@ -72,7 +73,7 @@ Using long option names is equally easy: ['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 c32ea6f581..34454657b1 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 @@ For example, the C call \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 @@ Examples: the C call \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 @@ def main(): 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 142afd8021..b63d153969 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 @@ For example, consider a directory containing only the following files: 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 @@ of the path are preserved. ['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 e94e1f9c6c..6ae913c5ec 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 90a2ed3339..2942a1bc6b 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 bf57ea90ef..aaa2072d38 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 @@ incomplete elements are saved in a buffer. To force processing of all 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 70bcb3c8d2..7671ab3622 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 @@ method should be used to connect to a server. For example, the following calls all create instances that connect to the server at the same host and port: -\begin{verbatim} +\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 @@ methods. 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 @@ Here is an example session: >>> 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 4e151170d0..48f9188009 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 1e8b2aaa9b..96afc9bb07 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 22d4d0d5e3..0dec8a16bf 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 @@ the test succeeded, or \code{None} if it failed. 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 e1e4a53779..0f63524ec1 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 @@ The module was found as dynamically loadable shared library. \subsection{Examples} The following function emulates the default import statement: -\begin{verbatim} +\bcode\begin{verbatim} import imp import sys @@ -171,4 +172,4 @@ def __import__(name, globals=None, locals=None, fromlist=None): 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 8215cada56..0d1dc1ce4c 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 42d4e51a06..4f67ab1400 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 ab45788210..5ae59a6c23 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 @@ will only return a single mx record. Mx queries only. 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 be566cbe9d..6f63a47b79 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 2b7628fd2c..6975380224 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 3a3c3a3e52..680b4edd2c 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 fc35520b64..d3b6e960a2 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 80e19cae0b..4d6d5ba855 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 56a00c3b18..d519bf5c80 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 7fea9b5abb..d7d47c4c92 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 @@ will override settings in the system mailcap files \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 c730a03a11..8ce73a8081 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 58becdb336..16472db622 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 765fcdf5c6..935b9403c1 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 @@ The module also defines two mathematical constants: \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 773f93c660..d71bacda08 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 @@ the spammish repetition"}: >>> 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 ecf50dc5fa..41a62bab66 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 46a2d474dc..9fb165ba37 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 2641d82cd8..41539b4113 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 @@ statistics about a newsgroup and print the subjects of the last 10 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 @@ Group comp.lang.python has 59 articles, range 3742 to 3803 >>> 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 @@ valid headers): >>> 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 7fed767c14..d7c11fc84d 100644 --- a/Doc/liboperator.tex +++ b/Doc/liboperator.tex @@ -184,10 +184,10 @@ Delete the slice of a from index b to index c-1. 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 51442efcfc..f17ce9574f 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 b82bf98bfe..a696f30bde 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 a51b01b7c0..4503358b96 100644 --- a/Doc/libparser.tex +++ b/Doc/libparser.tex @@ -288,30 +288,30 @@ bytecode generation, the simplest operation is to do nothing. For 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 @@ def load_expression(source_string): 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 @@ Consider the simplest case of interest when searching for docstrings: a module consisting of a docstring and nothing else. (See file \file{docstring.py}.) -\begin{verbatim} +\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 @@ buried deep in nested tuples. (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 @@ form, allowing a simple variable representation to be 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 @@ def match(pattern, data, vars=None): 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 @@ DOCSTRING_STMT_PATTERN = ( )))))))))))))))), (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 @@ grammar, but the method which recursively creates new information 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 @@ class SuiteInfoBase: 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 ``short form'' or the ``long form.'' The short form is used when the code block is on the same line as the definition of the code block, as in -\begin{verbatim} +\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 @@ the real extraction algorithm remains common to all forms of code blocks. A high-level function can be used to extract the complete set of information from a source file. (See file \file{example.py}.) -\begin{verbatim} +\bcode\begin{verbatim} def get_docs(fileName): source = open(fileName).read() import os @@ -669,8 +669,8 @@ def get_docs(fileName): 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 84ae3321ef..9785a406d3 100644 --- a/Doc/libpdb.tex +++ b/Doc/libpdb.tex @@ -29,7 +29,7 @@ specific modules). 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 @@ Typical usage to run a program under control of the debugger is: 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 @@ NameError: spam > ./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 @@ The exclamation point can be omitted unless the first word of the statement resembles a debugger command. To set a global variable, you can prefix the assignment command with a ``\code{global}'' command on the same line, e.g.: -\begin{verbatim} +\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 128b29de46..cb054a78a9 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 @@ The interface can be summarized as follows. 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 7edd93e14b..e545c7a7b4 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 9078560b70..6bd8a20ea0 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 7cd3c6b352..2f691708b1 100644 --- a/Doc/libprofile.tex +++ b/Doc/libprofile.tex @@ -103,11 +103,11 @@ rapidly perform profiling on an existing application. To profile an application with a main entry point of \samp{foo()}, you would add the following to your module: -\begin{verbatim} - import profile - profile.run("foo()") -\end{verbatim} - +\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 @@ save the results of a profile into a file for later examination, you 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 @@ When you wish to review the profile, you should use the methods in the \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 @@ algorithms are taking time, the above line is what you would use. If you were looking to see what functions were looping a lot, and taking a lot of time, you would do: -\begin{verbatim} - p.sort_stats('time').print_stats(10) -\end{verbatim} - +\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 @@ maintained, and that sub-sub-list is printed. If you wondered what functions called the above functions, you could now (\samp{p} is still sorted according to the last criteria) do: -\begin{verbatim} - p.print_callers(.5, 'init') -\end{verbatim} - +\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 @@ standard name string (file/line/function-name) that is presented in 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 @@ ncalls tottime percall cumtime percall filename:lineno(function) 2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects) 43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate) ... -\end{verbatim} +\end{verbatim}\ecode } The first line indicates that this profile was generated by the call:\\ @@ -446,18 +445,18 @@ expression (to pattern match the standard name that is printed). If 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 @@ returned by earlier methods. All standard methods in this class return the instance that is being processed, so that the commands can be strung together. For example: -\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 @@ function, and socking away the results. The following procedure can be used to obtain this constant for a given platform (see discussion in section Limitations above). -\begin{verbatim} - import profile - pr = profile.Profile() - 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 @@ The following shows how the trace_dispatch() method in the Profile class should be modified to install the calibration constant on a Sun Sparcstation 1000: -\begin{verbatim} - def trace_dispatch(self, frame, event, arg): - t = self.timer() - t = t[0] + t[1] - self.t - .00053 # Calibration constant - - if self.dispatch[event](frame,t): - t = self.timer() - self.t = t[0] + t[1] - else: - r = self.timer() - self.t = r[0] + r[1] - t # put back unrecorded delta - return -\end{verbatim} +\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() + 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 @@ timer function is used, then the basic class has an option for that in the constructor for the class. Consider passing the name of a function to call into the constructor: -\begin{verbatim} - pr = profile.Profile(your_time_func) -\end{verbatim} - +\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 @@ stats, and is quite useful when there is \emph{no} recursion in the user's code. It is also a lot more accurate than the old profiler, as it does not charge all its overhead time to the user's code. -\begin{verbatim} +\bcode\begin{verbatim} class OldProfile(Profile): def trace_dispatch_exception(self, frame, t): @@ -713,9 +712,8 @@ class OldProfile(Profile): 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 @@ function, so it runs very quickly (re: very low overhead). In truth, the basic profiler is so fast, that is probably not worth the savings to give up the data, but this class still provides a nice example. -\begin{verbatim} +\bcode\begin{verbatim} class HotProfile(Profile): def trace_dispatch_exception(self, frame, t): @@ -761,4 +759,4 @@ class HotProfile(Profile): 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 7bb30d80e2..073c19a4b6 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 0314f8ab92..2fbd35aa89 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 5a4df3eb50..06605661ca 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 @@ Set a starting seed value for the random number generator; \var{seed} can be an arbitrary integer. \end{funcdesc} +\begin{seealso} +\seemodule{whrandom}{the standard Python random number generator} +\end{seealso} + diff --git a/Doc/librandom.tex b/Doc/librandom.tex index 3bc92ce3bc..b8d5f78137 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 @@ then or equal to zero. If \var{kappa} is equal to zero, this 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 d3f44ba862..ee1563d566 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 @@ The module defines these functions, and an exception: 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 d075e99e8c..6d489861d7 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 ff78025ca3..5c93fa6097 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 4b1a10028c..742e32bad5 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 @@ class TmpWriterRExec(rexec.RExec): 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 3617e8aa65..cd3d271cdf 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 ace426fa98..d923fc28e8 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 c333686a24..a3431fc874 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 @@ An example usage: '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 0b50101395..4291dbfae4 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 dc3582b078..19ce91c803 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 a232add09d..05b3a93d3e 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 @@ sub-objects. The keys are ordinary strings. 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 @@ flag = d.has_key(key) # true if the key exists list = d.keys() # a list of all existing keys (slow!) d.close() # close it -\end{verbatim} - +\end{verbatim}\ecode +% Restrictions: \begin{itemize} diff --git a/Doc/libsignal.tex b/Doc/libsignal.tex index 802c4d107f..2844b57891 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 c97fd4e1c9..9b7eb91ff2 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 9d5536cc50..5422796a0b 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 @@ while 1: conn.send(data) conn.close() \end{verbatim}\ecode - +% \bcode\begin{verbatim} # Echo client program from socket import * @@ -349,3 +350,7 @@ data = s.recv(1024) 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 4c15c55aaa..373da3890a 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 67335a54ac..bb3b66a27d 100644 --- a/Doc/libstat.tex +++ b/Doc/libstat.tex @@ -81,7 +81,7 @@ Time of creation. Example: -\begin{verbatim} +\bcode\begin{verbatim} import os, sys from stat import * @@ -103,4 +103,4 @@ def f(file): 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 2f2bd42924..514252f442 100644 --- a/Doc/libstdwin.tex +++ b/Doc/libstdwin.tex @@ -774,7 +774,7 @@ def main(): main() \end{verbatim}\ecode - +% \section{Standard Module \sectcode{stdwinevents}} \stmodindex{stdwinevents} @@ -788,7 +788,7 @@ Suggested usage is >>> from stdwinevents import * >>> \end{verbatim}\ecode - +% \section{Standard Module \sectcode{rect}} \stmodindex{rect} @@ -801,7 +801,7 @@ For example, the rectangle \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 7b91717e22..930ce22d1d 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 f7879f1eda..d57a2b790a 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 @@ big-endian machine): 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 ae02d8da89..f137052301 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 5b4fdded4b..37d6b6614a 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 0a582e12dc..e033f70f93 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 cd49a8f74e..1edc21d3b5 100644 --- a/Doc/libtemplate.tex +++ b/Doc/libtemplate.tex @@ -96,13 +96,13 @@ failure. 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 3d007c3e1d..2d233f2022 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 @@ Note the technique using a separate \code{termios.tcgetattr()} call 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 @@ def getpass(prompt = "Password: "): 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 f7453844db..080a35cf1f 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 7ee886d69f..e3525057ee 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 ca9c374859..4fcc4d145d 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 d0f20c9db7..afb02e5cfb 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 @@ all end in \code{Type}. 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 8fe71322e9..51a700a72b 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 36ca949ba6..76fd9f8263 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 @@ retained if present. 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 @@ components in the relative URL. 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 fbdfa8c805..19bca3a159 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 6094462890..09d7816521 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 @@ When imported, the \code{whrandom} module also creates an instance of the \code{whrandom} class, and makes the methods of that instance available at the module level. Therefore one can write either \code{N = whrandom.random()} or: -\begin{verbatim} +\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 1221fffd08..0de56957a5 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 @@ variables. 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 ab30a32498..28365ae3bb 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 @@ uncompressed output is returned. After calling \code{flush()}, the 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 a5aab71421..073c649346 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 42d4e51a06..4f67ab1400 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 ab45788210..5ae59a6c23 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 @@ will only return a single mx record. Mx queries only. 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 be566cbe9d..6f63a47b79 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 2b7628fd2c..6975380224 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 3a3c3a3e52..680b4edd2c 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 fc35520b64..d3b6e960a2 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 80e19cae0b..4d6d5ba855 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 56a00c3b18..d519bf5c80 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 cd49a8f74e..1edc21d3b5 100644 --- a/Doc/templates/module.tex +++ b/Doc/templates/module.tex @@ -96,13 +96,13 @@ failure. 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 |