diff options
Diffstat (limited to 'Doc')
55 files changed, 883 insertions, 259 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index 57ec616..25727e1 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -98,7 +98,8 @@ ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \ # LaTeX source files for the Python Library Reference LIBFILES = lib.tex \ -libal.tex libaifc.tex libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \ +libal.tex libaifc.tex liballos.tex \ + libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \ libbltin.tex \ libcd.tex \ libcgi.tex libcopy.tex libctb.tex libcrypto.tex \ @@ -112,16 +113,17 @@ libjpeg.tex \ libmac.tex libmacconsole.tex libmacdnr.tex \ libmacfs.tex libmactcp.tex libmacspeech.tex \ libmain.tex libmarshal.tex libmath.tex \ - libmd5.tex libmimetools.tex libmm.tex libmods.tex libmpz.tex \ + libmd5.tex libmimetools.tex libmisc.tex \ + libmm.tex libmods.tex libmpz.tex \ libnntplib.tex \ libobjs.tex libos.tex \ libpanel.tex libpickle.tex libposix.tex libposixfile.tex \ - libppath.tex libprofile.tex libpwd.tex \ + libppath.tex libprofile.tex libpwd.tex libpython.tex \ librand.tex libregex.tex libregsub.tex \ librfc822.tex librgbimg.tex librotor.tex \ libselect.tex libsgi.tex libsgmllib.tex \ - libshelve.tex libsocket.tex libstd.tex libstdwin.tex \ - libstring.tex libstruct.tex libsun.tex libsys.tex \ + libshelve.tex libsocket.tex libsomeos.tex libstd.tex libstdwin.tex \ + libstring.tex libstrings.tex libstruct.tex libsun.tex libsys.tex \ libtempfile.tex libthread.tex libtime.tex \ libtraceback.tex libtypes.tex libtypes2.tex \ libunix.tex liburllib.tex liburlparse.tex \ diff --git a/Doc/lib.tex b/Doc/lib.tex index 8d6db1c..bf0f3ad 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -22,8 +22,8 @@ \begin{abstract} \noindent -This document describes the built-in types, exceptions and functions -and the standard modules that come with the Python system. It assumes +This document describes the built-in and standard types, exceptions, +functions and modules that come with the Python system. It assumes basic knowledge about the Python language. For an informal introduction to the language, see the {\em Python Tutorial}. The {\em Python Reference Manual} gives a more formal definition of the @@ -51,52 +51,58 @@ language. \input{libexcs} \input{libfuncs} -\input{libmods} % Built-in modules +\input{libpython} % Python Services \input{libsys} -\input{libbltin} % really __builtin__ +\input{libtypes2} % types is already taken :-( +\input{libtraceback} +\input{libpickle} +\input{libshelve} +\input{libcopy} +\input{libmarshal} \input{libimp} +\input{libbltin} % really __builtin__ \input{libmain} % really __main__ -\input{libarray} -\input{libmath} -\input{libtime} + +\input{libstrings} % String Services +\input{libstring} \input{libregex} -\input{libmarshal} +\input{libregsub} \input{libstruct} -\input{libstd} % Standard Modules -\input{libgetopt} -\input{libos} +\input{libmisc} % Miscellaneous Services +\input{libmath} \input{librand} -\input{libregsub} -\input{libstring} \input{libwhrandom} -\input{libaifc} -\input{libpickle} -\input{libshelve} -\input{libcopy} -\input{libtypes2} % types is already taken :-( -\input{libtempfile} -\input{libtraceback} +\input{libarray} -\input{libpdb} % The Python Debugger +\input{liballos} % Generic Operating System Services +\input{libos} +\input{libtime} +\input{libgetopt} +\input{libtempfile} -\input{libprofile} % The Python Profiler +\input{libsomeos} % Optional Operating System Services +\input{libsignal} +\input{libsocket} +\input{libselect} +\input{libthread} -\input{libunix} % UNIX ONLY +\input{libunix} % UNIX Specific Services +\input{libposix} +\input{libppath} % == posixpath +\input{libpwd} +\input{libgrp} \input{libdbm} -\input{libfcntl} \input{libgdbm} -\input{libgrp} -\input{libposix} +\input{libtermios} +\input{libfcntl} \input{libposixfile} -\input{libppath} % really posixpath -\input{libpwd} -\input{libselect} -\input{libsignal} -\input{libsocket} -\input{libthread} -\input{libwww} % WWW EXTENSIONS +\input{libpdb} % The Python Debugger + +\input{libprofile} % The Python Profiler + +\input{libwww} % Internet and WWW Services \input{libcgi} \input{liburllib} \input{libhttplib} @@ -109,13 +115,14 @@ language. \input{librfc822} \input{libmimetools} -\input{libmm} % MULTIMEDIA EXTENSIONS +\input{libmm} % Multimedia Services \input{libaudioop} \input{libimageop} +\input{libaifc} \input{libjpeg} \input{librgbimg} -\input{libcrypto} % CRYPTOGRAPHIC EXTENSIONS +\input{libcrypto} % Cryptographic Services \input{libmd5} \input{libmpz} \input{librotor} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 8d6db1c..bf0f3ad 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -22,8 +22,8 @@ \begin{abstract} \noindent -This document describes the built-in types, exceptions and functions -and the standard modules that come with the Python system. It assumes +This document describes the built-in and standard types, exceptions, +functions and modules that come with the Python system. It assumes basic knowledge about the Python language. For an informal introduction to the language, see the {\em Python Tutorial}. The {\em Python Reference Manual} gives a more formal definition of the @@ -51,52 +51,58 @@ language. \input{libexcs} \input{libfuncs} -\input{libmods} % Built-in modules +\input{libpython} % Python Services \input{libsys} -\input{libbltin} % really __builtin__ +\input{libtypes2} % types is already taken :-( +\input{libtraceback} +\input{libpickle} +\input{libshelve} +\input{libcopy} +\input{libmarshal} \input{libimp} +\input{libbltin} % really __builtin__ \input{libmain} % really __main__ -\input{libarray} -\input{libmath} -\input{libtime} + +\input{libstrings} % String Services +\input{libstring} \input{libregex} -\input{libmarshal} +\input{libregsub} \input{libstruct} -\input{libstd} % Standard Modules -\input{libgetopt} -\input{libos} +\input{libmisc} % Miscellaneous Services +\input{libmath} \input{librand} -\input{libregsub} -\input{libstring} \input{libwhrandom} -\input{libaifc} -\input{libpickle} -\input{libshelve} -\input{libcopy} -\input{libtypes2} % types is already taken :-( -\input{libtempfile} -\input{libtraceback} +\input{libarray} -\input{libpdb} % The Python Debugger +\input{liballos} % Generic Operating System Services +\input{libos} +\input{libtime} +\input{libgetopt} +\input{libtempfile} -\input{libprofile} % The Python Profiler +\input{libsomeos} % Optional Operating System Services +\input{libsignal} +\input{libsocket} +\input{libselect} +\input{libthread} -\input{libunix} % UNIX ONLY +\input{libunix} % UNIX Specific Services +\input{libposix} +\input{libppath} % == posixpath +\input{libpwd} +\input{libgrp} \input{libdbm} -\input{libfcntl} \input{libgdbm} -\input{libgrp} -\input{libposix} +\input{libtermios} +\input{libfcntl} \input{libposixfile} -\input{libppath} % really posixpath -\input{libpwd} -\input{libselect} -\input{libsignal} -\input{libsocket} -\input{libthread} -\input{libwww} % WWW EXTENSIONS +\input{libpdb} % The Python Debugger + +\input{libprofile} % The Python Profiler + +\input{libwww} % Internet and WWW Services \input{libcgi} \input{liburllib} \input{libhttplib} @@ -109,13 +115,14 @@ language. \input{librfc822} \input{libmimetools} -\input{libmm} % MULTIMEDIA EXTENSIONS +\input{libmm} % Multimedia Services \input{libaudioop} \input{libimageop} +\input{libaifc} \input{libjpeg} \input{librgbimg} -\input{libcrypto} % CRYPTOGRAPHIC EXTENSIONS +\input{libcrypto} % Cryptographic Services \input{libmd5} \input{libmpz} \input{librotor} diff --git a/Doc/lib/libaifc.tex b/Doc/lib/libaifc.tex index 7e595ef..04ed2e4 100644 --- a/Doc/lib/libaifc.tex +++ b/Doc/lib/libaifc.tex @@ -11,8 +11,14 @@ The sampling rate or frame rate is the number of times per second the sound is sampled. The number of channels indicate if the audio is mono, stereo, or quadro. Each frame consists of one sample per channel. The sample size is the size in bytes of each sample. Thus a -frame consists of \var{nchannels}*\var{framesize} bytes, and a second's worth of -audio consists of \var{nchannels}*\var{framesize}*\var{framerate} bytes. +frame consists of \var{nchannels}*\var{samplesize} bytes, and a +second's worth of audio consists of +\var{nchannels}*\var{samplesize}*\var{framerate} bytes. + +For example, CD quality audio has a sample size of two bytes (16 +bits), uses two channels (stereo) and has a frame rate of 44,100 +frames/second. This gives a frame size of 4 bytes (2*2), and a +second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes. Module \code{aifc} defines the following function: @@ -148,7 +154,7 @@ string. Currently the following compression types are supported: NONE, ULAW, ALAW, G722. \end{funcdesc} -\begin{funcdesc}{setparams}{(nchannels\, sampwidth\, framerate\, comptype\, compname)} +\begin{funcdesc}{setparams}{nchannels\, sampwidth\, framerate\, comptype\, compname} Set all the above parameters at once. The argument is a tuple consisting of the various parameters. This means that it is possible to use the result of a \code{getparams} call as argument to diff --git a/Doc/lib/liballos.tex b/Doc/lib/liballos.tex new file mode 100644 index 0000000..b5a207e --- /dev/null +++ b/Doc/lib/liballos.tex @@ -0,0 +1,23 @@ +\chapter{Generic Operating System Services} + +The modules described in this chapter provide interfaces to operating +system features that are available on (almost) all operating systems, +such as files and a clock. The interfaces are generally modelled +after the \UNIX{} or C interfaces but they are available on most other +systems as well. Here's an overview: + +\begin{description} + +\item[os] +--- Miscellaneous OS interfaces. + +\item[time] +--- Time access and conversions. + +\item[getopt] +--- Parser for command line options. + +\item[tempfile] +--- Generate temporary file names. + +\end{description} diff --git a/Doc/lib/libamoeba.tex b/Doc/lib/libamoeba.tex index 1e31bc6..54a9dfb 100644 --- a/Doc/lib/libamoeba.tex +++ b/Doc/lib/libamoeba.tex @@ -1,4 +1,4 @@ -\chapter{AMOEBA ONLY} +\chapter{Amoeba Specific Services} \section{Built-in Module \sectcode{amoeba}} diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex index 9e37d55..8122f49 100644 --- a/Doc/lib/libarray.tex +++ b/Doc/lib/libarray.tex @@ -23,6 +23,9 @@ The actual representation of values is determined by the machine architecture (strictly speaking, by the C implementation). The actual size can be accessed through the \var{itemsize} attribute. +See also built-in module \code{struct}. +\bimodindex{struct} + The module defines the following function: \renewcommand{\indexsubitem}{(in module array)} diff --git a/Doc/lib/libcrypto.tex b/Doc/lib/libcrypto.tex index 972106c..cc38e5b 100644 --- a/Doc/lib/libcrypto.tex +++ b/Doc/lib/libcrypto.tex @@ -1,9 +1,22 @@ -\chapter{CRYPTOGRAPHIC EXTENSIONS} +\chapter{Cryptographic Services} +\index{cryptography} The modules described in this chapter implement various algorithms of a cryptographic nature. They are available at the discretion of the -installation. -\index{cryptography} +installation. Here's an overview: + +\begin{description} + +\item[md5] +--- RSA's MD5 message digest algorithm. + +\item[mpz] +--- Interface to the GNU MP library for arbitrary precision arithmetic. + +\item[rotor] +--- Enigma-like encryption and decryption. + +\end{description} Hardcore cypherpunks will probably find the Python Cryptography Kit of further interest; the package adds built-in modules for DES and IDEA diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex index 4778c7d..b526fcc 100644 --- a/Doc/lib/libfuncs.tex +++ b/Doc/lib/libfuncs.tex @@ -197,7 +197,8 @@ removed. Convert a number to a plain integer. The argument may be a plain or long integer or a floating point number. Conversion of floating point numbers to integers is defined by the C semantics; normally - the conversion truncates towards zero. + the conversion truncates towards zero.\footnote{This is ugly --- the + language definition should require truncation towards zero.} \end{funcdesc} \begin{funcdesc}{len}{s} diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex index 4587ac1..d2e2420 100644 --- a/Doc/lib/libhttplib.tex +++ b/Doc/lib/libhttplib.tex @@ -46,8 +46,12 @@ file object that it returns. \end{enumerate} +\subsection{HTTP Objects} + \code{HTTP} instances have the following methods: +\renewcommand{\indexsubitem}{(HTTP method)} + \begin{funcdesc}{set_debuglevel}{level} Set the debugging level (the amount of debugging output printed). The default debug level is \code{0}, meaning no debugging output is diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex index 91e250b..f995979 100644 --- a/Doc/lib/libimp.tex +++ b/Doc/lib/libimp.tex @@ -51,7 +51,7 @@ object. If the module was already initialized, it will be initialized \code{None} is returned. (Frozen modules are modules written in Python whose compiled byte-code object is incorporated into a custom-built Python interpreter by Python's \code{freeze} utility. -See \code{Demo/freeze} for now.) +See \code{Tools/freeze} for now.) \end{funcdesc} \begin{funcdesc}{is_builtin}{name} diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex index 03f9247..decb890 100644 --- a/Doc/lib/libmimetools.tex +++ b/Doc/lib/libmimetools.tex @@ -45,7 +45,7 @@ file \var{output}. The block size is currently fixed at 8192. \end{funcdesc} -\subsection{Additional Methods of \sectcode{Message} objects} +\subsection{Additional Methods of Message objects} \nodename{mimetools.Message Methods} The \code{mimetools.Message} class defines the following methods in diff --git a/Doc/lib/libmisc.tex b/Doc/lib/libmisc.tex new file mode 100644 index 0000000..b7a726e --- /dev/null +++ b/Doc/lib/libmisc.tex @@ -0,0 +1,20 @@ +\chapter{Miscellaneous Services} + +The modules described in this chapter provide miscellaneous services +that are available in all Python versions. Here's an overview: + +\begin{description} + +\item[math] +--- Mathematical functions (\code{sin()} etc.). + +\item[rand] +--- Integer random number generator. + +\item[whrandom] +--- Floating point random number generator. + +\item[array] +--- Efficient arrays of uniformly typed numeric values. + +\end{description} diff --git a/Doc/lib/libmm.tex b/Doc/lib/libmm.tex index c17aa55..d5abc6f 100644 --- a/Doc/lib/libmm.tex +++ b/Doc/lib/libmm.tex @@ -1,5 +1,25 @@ -\chapter{MULTIMEDIA EXTENSIONS} +\chapter{Multimedia Services} -The modules described in this chapter implement various algorithms -that are mainly useful for multimedia applications. They are -available at the discretion of the installation. +The modules described in this chapter implement various algorithms or +interfaces that are mainly useful for multimedia applications. They +are available at the discretion of the installation. Here's an overview: + +\begin{description} + +\item[audioop] +--- Manipulate raw audio data. + +\item[imageop] +--- Manipulate raw image data. + +\item[aifc] +--- Read and write audio files in AIFF or AIFC format. + +\item[jpeg] +--- Read and write image files in compressed JPEG format. + +\item[rgbimg] +--- Read and write image files in ``SGI RGB'' format (the module is +\emph{not} SGI specific though)! + +\end{description} diff --git a/Doc/lib/libobjs.tex b/Doc/lib/libobjs.tex index 49a86fc..9006b8a 100644 --- a/Doc/lib/libobjs.tex +++ b/Doc/lib/libobjs.tex @@ -4,16 +4,21 @@ Names for built-in exceptions and functions are found in a separate symbol table. This table is searched last, so local and global -user-defined names can override built-in names. Built-in types have -no names but are created easily by constructing an object of the -desired type (e.g., using a literal) and applying the built-in -function \code{type()} to it. They are described together here for -easy reference.% -\footnote{Some descriptions sorely lack explanations of the exceptions +user-defined names can override built-in names. Built-in types are +described together here for easy reference. % +\footnote{Most descriptions sorely lack explanations of the exceptions that may be raised --- this will be fixed in a future version of - this document.} + this manual.} \indexii{built-in}{types} \indexii{built-in}{exceptions} \indexii{built-in}{functions} \index{symbol table} \bifuncindex{type} + +The tables in this chapter document the priorities of operators by +listing them in order of ascending priority (within a table) and +grouping operators that have the same priority in the same box. +Binary operators of the same priority group from left to right. +(Unary operators group from right to left, but there you have no real +choice.) See Chapter 5 of the Python Reference Manual for the +complete picture on operator priorities. diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex index 8dc29e4..92020a2 100644 --- a/Doc/lib/libpickle.tex +++ b/Doc/lib/libpickle.tex @@ -11,7 +11,9 @@ The \code{pickle} module implements a basic but powerful algorithm for ``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly -arbitrary Python objects. This is a more primitive notion than +arbitrary Python objects. This is the act of converting objects to a +stream of bytes (and back: ``unpickling''). +This is a more primitive notion than persistency --- although \code{pickle} reads and writes file objects, it does not handle the issue of naming persistent objects, nor the (even more complicated) area of concurrent access to persistent @@ -54,7 +56,8 @@ advantage of using printable \ASCII{} (and of some other characteristics of \code{pickle}'s representation) is that for debugging or recovery purposes it is possible for a human to read the pickled file with a standard text editor. (I could have gone a step further and used a -notation like S-expressions, but the parser would have been +notation like S-expressions, but the parser +(currently written in Python) would have been considerably more complicated and slower, and the files would probably have become much larger.) diff --git a/Doc/lib/libpython.tex b/Doc/lib/libpython.tex new file mode 100644 index 0000000..ed253f5 --- /dev/null +++ b/Doc/lib/libpython.tex @@ -0,0 +1,40 @@ +\chapter{Python Services} + +The modules described in this chapter provide a wide range of services +related to the Python interpreter and its interaction with its +environment. Here's an overview: + +\begin{description} + +\item[sys] +--- Access system specific parameters and functions. + +\item[types] +--- Names for all built-in types. + +\item[traceback] +--- Print or retrieve a stack traceback. + +\item[pickle] +--- Convert Python objects to streams of bytes and back. + +\item[shelve] +--- Python object persistency. + +\item[copy] +--- Shallow and deep copy operations. + +\item[marshal] +--- Convert Python objects to streams of bytes and back (with +different constraints). + +\item[imp] +--- Access the implementation of the \code{import} statement. + +\item[__builtin__] +--- The set of built-in functions. + +\item[__main__] +--- The environment where the top-level script is run. + +\end{description} diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex index d819238..e2d182e 100644 --- a/Doc/lib/librfc822.tex +++ b/Doc/lib/librfc822.tex @@ -21,6 +21,8 @@ All header matching is done independent of upper or lower case; e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield the same result. +\subsection{Message Objects} + A \code{Message} instance has the following methods: \begin{funcdesc}{rewindbody}{} diff --git a/Doc/lib/libsgi.tex b/Doc/lib/libsgi.tex index f8c87b0..8deede8 100644 --- a/Doc/lib/libsgi.tex +++ b/Doc/lib/libsgi.tex @@ -1,4 +1,4 @@ -\chapter{SGI IRIX ONLY} +\chapter{SGI IRIX Specific Services} The modules described in this chapter provide interfaces to features that are unique to SGI's IRIX operating system (versions 4 and 5). diff --git a/Doc/lib/libsomeos.tex b/Doc/lib/libsomeos.tex new file mode 100644 index 0000000..f9aedfe --- /dev/null +++ b/Doc/lib/libsomeos.tex @@ -0,0 +1,23 @@ +\chapter{Optional Operating System Services} + +The modules described in this chapter provide interfaces to operating +system features that are available on selected operating systems only. +The interfaces are generally modelled after the \UNIX{} or C +interfaces but they are available on some other systems as well +(e.g. Windows or NT). Here's an overview: + +\begin{description} + +\item[signal] +--- Set handlers for asynchronous events. + +\item[socket] +--- Low-level networking interface. + +\item[select] +--- Wait for I/O completion on multiple streams. + +\item[thread] +--- Create multiple threads of control within one namespace. + +\end{description} diff --git a/Doc/lib/libstdwin.tex b/Doc/lib/libstdwin.tex index ae7e8b9..e009e3f 100644 --- a/Doc/lib/libstdwin.tex +++ b/Doc/lib/libstdwin.tex @@ -1,13 +1,24 @@ -\chapter{STDWIN ONLY} +\chapter{Standard Windowing Interface} + +The modules in this chapter are available only on those systems where +the STDWIN library is available. STDWIN runs on \UNIX{} under X11 and +on the Macintosh. See CWI report CS-R8817. + +\strong{Warning:} Using STDWIN is not recommended for new +applications. It has never been ported to Microsoft Windows or +Windows NT, and for X11 or the Macintosh it lacks important +functionality --- in particular, it has no tools for the construction +of dialogs. For most platforms, alternative, native solutions exist +(though none are currently documented in this manual): Tkinter for +\UNIX{} under X11, native Xt with Motif or Athena widgets for \UNIX{} +under X11, Win32 for Windows and Windows NT, and a collection of +native toolkit interfaces for the Macintosh. \section{Built-in Module \sectcode{stdwin}} \bimodindex{stdwin} This module defines several new object types and functions that -provide access to the functionality of the Standard Window System -Interface, STDWIN [CWI report CR-R8817]. -It is available on systems to which STDWIN has been ported (which is -most systems). +provide access to the functionality of STDWIN. On Unix running X11, it can only be used if the \code{DISPLAY} environment variable is set or an explicit \samp{-display diff --git a/Doc/lib/libstrings.tex b/Doc/lib/libstrings.tex new file mode 100644 index 0000000..ea9a0999 --- /dev/null +++ b/Doc/lib/libstrings.tex @@ -0,0 +1,20 @@ +\chapter{String Services} + +The modules described in this chapter provide a wide range of string +manipulation operations. Here's an overview: + +\begin{description} + +\item[string] +--- Common string operations. + +\item[regex] +--- Regular expression search and match operations. + +\item[regsub] +--- Substitution and splitting operations that use regular expressions. + +\item[struct] +--- Interpret strings as packed binary data. + +\end{description} diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex index a2c1b10..4a08c78b 100644 --- a/Doc/lib/libstruct.tex +++ b/Doc/lib/libstruct.tex @@ -7,6 +7,9 @@ structs represented as Python strings. It uses \dfn{format strings} (explained below) as compact descriptions of the lay-out of the C structs and the intended conversion to/from Python values. +See also built-in module \code{array}. +\bimodindex{array} + The module defines the following exception and functions: \renewcommand{\indexsubitem}{(in module struct)} diff --git a/Doc/lib/libsun.tex b/Doc/lib/libsun.tex index d297b9c..5628369 100644 --- a/Doc/lib/libsun.tex +++ b/Doc/lib/libsun.tex @@ -1,8 +1,8 @@ -\chapter{SUNOS ONLY} +\chapter{SunOS Specific Services} The modules described in this chapter provide interfaces to features that are unique to the SunOS operating system (versions 4 and 5; the -latter is also known as SOLARIS version 2). +latter is also known as Solaris version 2). \section{Built-in Module \sectcode{sunaudiodev}} \bimodindex{sunaudiodev} diff --git a/Doc/lib/libtermios.tex b/Doc/lib/libtermios.tex new file mode 100644 index 0000000..8fe6f51 --- /dev/null +++ b/Doc/lib/libtermios.tex @@ -0,0 +1,3 @@ +\section{Built-in Module \sectcode{termios}} + +To be provided. diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex index 51c775e..422a2d6 100644 --- a/Doc/lib/libtypes.tex +++ b/Doc/lib/libtypes.tex @@ -17,7 +17,7 @@ implicitly used when an object is written by the \code{print} statement. Any object can be tested for truth value, for use in an \code{if} or \code{while} condition or as operand of the Boolean operations below. -The following values are false: +The following values are considered false: \stindex{if} \stindex{while} \indexii{truth}{value} @@ -36,21 +36,32 @@ The following values are false: \item any empty mapping, e.g., \code{\{\}}. +\item instances of user-defined classes, if the class defines a + \code{__nonzero__()} or \code{__len__()} method, when that + method returns zero. + \end{itemize} -\emph{All} other values are true --- so objects of many types are +All other values are considered true --- so objects of many types are always true. \index{true} +Operations and built-in functions that have a Boolean result always +return \code{0} for false and \code{1} for true, unless otherwise +stated. (Important exception: the Boolean operations \samp{or} and +\samp{and} always return one of their operands.) + \subsection{Boolean Operations} -These are the Boolean operations: +These are the Boolean operations, ordered by ascending priority: \indexii{Boolean}{operations} \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} \lineiii{\var{x} or \var{y}}{if \var{x} is false, then \var{y}, else \var{x}}{(1)} + \hline \lineiii{\var{x} and \var{y}}{if \var{x} is false, then \var{x}, else \var{y}}{(1)} - \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{} + \hline + \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{(2)} \end{tableiii} \opindex{and} \opindex{or} @@ -64,11 +75,24 @@ Notes: \item[(1)] These only evaluate their second argument if needed for their outcome. +\item[(2)] +\samp{not} has a lower priority than non-Boolean operators, so e.g. +\code{not a == b} is interpreted as \code{not(a == b)}, and +\code{a == not b} is a syntax error. + \end{description} \subsection{Comparisons} -Comparison operations are supported by all objects: +Comparison operations are supported by all objects. They all have the +same priority (which is higher than that of the Boolean operations). +Comparisons can be chained arbitrarily, e.g. \code{x < y <= z} is +equivalent to \code{x < y and y <= z}, except that \code{y} is +evaluated only once (but in both cases \code{z} is not evaluated at +all when \code{x < y} is found to be false). +\indexii{chaining}{comparisons} + +This table summarizes the comparison operations: \begin{tableiii}{|c|l|c|}{code}{Operation}{Meaning}{Notes} \lineiii{<}{strictly less than}{} @@ -161,20 +185,26 @@ to coerce numbers to a specific type. \bifuncindex{long} \bifuncindex{float} -All numeric types support the following operations: +All numeric types support the following operations, sorted by +ascending priority (operations in the same box have the same +priority; all numeric operations have a higher priority than +comparison operations): \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} - \lineiii{abs(\var{x})}{absolute value of \var{x}}{} - \lineiii{int(\var{x})}{\var{x} converted to integer}{(1)} - \lineiii{long(\var{x})}{\var{x} converted to long integer}{(1)} - \lineiii{float(\var{x})}{\var{x} converted to floating point}{} - \lineiii{-\var{x}}{\var{x} negated}{} - \lineiii{+\var{x}}{\var{x} unchanged}{} \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{} \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{} + \hline \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{} - \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(2)} + \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)} \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{} + \hline + \lineiii{-\var{x}}{\var{x} negated}{} + \lineiii{+\var{x}}{\var{x} unchanged}{} + \hline + \lineiii{abs(\var{x})}{absolute value of \var{x}}{} + \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)} + \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)} + \lineiii{float(\var{x})}{\var{x} converted to floating point}{} \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)} \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{} \end{tableiii} @@ -183,22 +213,24 @@ All numeric types support the following operations: \noindent Notes: \begin{description} -\item[(1)] -Conversion from floating point to (long or plain) integer may round or -% XXXJH xref here -truncate as in \C{}; see functions \code{floor} and \code{ceil} in module -\code{math} for well-defined conversions. -\indexii{numeric}{conversions} -\stmodindex{math} -\indexii{\C{}}{language} -\item[(2)] +\item[(1)] For (plain or long) integer division, the result is an integer; it always truncates towards zero. % XXXJH integer division is better defined nowadays \indexii{integer}{division} \indexiii{long}{integer}{division} +\item[(2)] +Conversion from floating point to (long or plain) integer may round or +truncate as in \C{}; see functions \code{floor()} and \code{ceil()} in +module \code{math} for well-defined conversions. +\bifuncindex{floor} +\bifuncindex{ceil} +\indexii{numeric}{conversions} +\stmodindex{math} +\indexii{\C{}}{language} + \item[(3)] See the section on built-in functions for an exact definition. @@ -210,52 +242,89 @@ See the section on built-in functions for an exact definition. Plain and long integer types support additional operations that make sense only for bit-strings. Negative numbers are treated as their 2's -complement value: +complement value (for long integers, this assumes a sufficiently large +number of bits that no overflow occurs during the operation). + +The priorities of the binary bit-wise operations are all lower than +the numeric operations and higher than the comparisons; the unary +operation \samp{~} has the same priority as the other unary numeric +operations (\samp{+} and \samp{-}). + +This table lists the bit-string operations sorted in ascending +priority (operations in the same box have the same priority): \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} - \lineiii{\~\var{x}}{the bits of \var{x} inverted}{} + \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{} + \hline \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{} + \hline \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{} - \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{} - \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{} - \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{} + \hline + \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)} + \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)} + \hline + \hline + \lineiii{\~\var{x}}{the bits of \var{x} inverted}{} \end{tableiii} -% XXXJH what's `left'? `right'? maybe better use lsb or msb or something \indexiii{operations on}{integer}{types} \indexii{bit-string}{operations} \indexii{shifting}{operations} \indexii{masking}{operations} +\noindent +Notes: +\begin{description} +\item[(1)] Negative shift counts are illegal. +\item[(2)] A left shift by \var{n} bits is equivalent to +multiplication by \code{pow(2, \var{n})} without overflow check. +\item[(3)] A right shift by \var{n} bits is equivalent to +division by \code{pow(2, \var{n})} without overflow check. +\end{description} + \subsection{Sequence Types} There are three sequence types: strings, lists and tuples. -Strings literals are written in single quotes: \code{'xyzzy'}. -Lists are constructed with square brackets, -separating items with commas: -\code{[a, b, c]}. -Tuples are constructed by the comma operator -(not within square brackets), with or without enclosing parentheses, -but an empty tuple must have the enclosing parentheses, e.g., -\code{a, b, c} or \code{()}. A single item tuple must have a trailing comma, -e.g., \code{(d,)}. + +Strings literals are written in single or double quotes: +\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the Python +Reference Manual for more about string literals. Lists are +constructed with square brackets, separating items with commas: +\code{[a, b, c]}. Tuples are constructed by the comma operator (not +within square brackets), with or without enclosing parentheses, but an +empty tuple must have the enclosing parentheses, e.g., +\code{a, b, c} or \code{()}. A single item tuple must have a trailing +comma, e.g., \code{(d,)}. \indexii{sequence}{types} \indexii{string}{type} \indexii{tuple}{type} \indexii{list}{type} -Sequence types support the following operations (\var{s} and \var{t} are -sequences of the same type; \var{n}, \var{i} and \var{j} are integers): +Sequence types support the following operations. The \samp{in} and +\samp{not\,in} operations have the same priorities as the comparison +operations. The \samp{+} and \samp{*} operations have the same +priority as the corresponding numeric operations.\footnote{They must +have since the parser can't tell the type of the operands.} + +This table lists the sequece operations sorted in ascending priority +(operations in the same box have the same priority). In the table, +\var{s} and \var{t} are sequences of the same type; \var{n}, \var{i} +and \var{j} are integers: \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} - \lineiii{len(\var{s})}{length of \var{s}}{} - \lineiii{min(\var{s})}{smallest item of \var{s}}{} - \lineiii{max(\var{s})}{largest item of \var{s}}{} \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{} - \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is equal to \var{x}, else \code{1}}{} + \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is +equal to \var{x}, else \code{1}}{} + \hline \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{} + \hline \lineiii{\var{s} * \var{n}{\rm ,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{} + \hline \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(1)} \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(1), (2)} + \hline + \lineiii{len(\var{s})}{length of \var{s}}{} + \lineiii{min(\var{s})}{smallest item of \var{s}}{} + \lineiii{max(\var{s})}{largest item of \var{s}}{} \end{tableiii} \indexiii{operations on}{sequence}{types} \bifuncindex{len} @@ -271,7 +340,6 @@ sequences of the same type; \var{n}, \var{i} and \var{j} are integers): \noindent Notes: -% XXXJH all TeX-math expressions replaced by python-syntax expressions \begin{description} \item[(1)] If \var{i} or \var{j} is negative, the index is relative to @@ -423,9 +491,9 @@ can be used interchangeably to index the same dictionary entry. \indexii{dictionary}{type} Dictionaries are created by placing a comma-separated list of -\code{\var{key}:\ \var{value}} pairs within braces, for example: -\code{\{'jack':\ 4098, 'sjoerd':\ 4127\}} or -\code{\{4098:\ 'jack', 4127:\ 'sjoerd'\}}. +\code{\var{key}:\,var{value}} pairs within braces, for example: +\code{\{'jack':\,4098, 'sjoerd':\,4127\}} or +\code{\{4098:\,'jack', 4127:\,'sjoerd'\}}. The following operations are defined on mappings (where \var{a} is a mapping, \var{k} is a key and \var{x} is an arbitrary object): @@ -448,8 +516,6 @@ mapping, \var{k} is a key and \var{x} is an arbitrary object): \ttindex{keys} \ttindex{has_key} -% XXXJH some lines above, you talk about `true', elsewhere you -% explicitely states \code{0} or \code{1}. \noindent Notes: \begin{description} @@ -485,8 +551,8 @@ Modules are written like this: \code{<module 'sys'>}. \subsubsection{Classes and Class Instances} \nodename{Classes and Instances} -% XXXJH cross ref here -(See the Python Reference Manual for these.) + +(See Chapters 3 and 7 of the Python Reference Manual for these.) \subsubsection{Functions} @@ -547,9 +613,11 @@ source string) to the \code{exec} statement or the built-in \subsubsection{Type Objects} Type objects represent the various object types. An object's type is -% XXXJH xref here accessed by the built-in function \code{type()}. There are no special -operations on types. +operations on types. The standard module \code{types} defines names +for all standard built-in types. +\bifuncindex{type} +\stmodindex{types} Types are written like this: \code{<type 'int'>}. @@ -564,9 +632,15 @@ It is written as \code{None}. \subsubsection{File Objects} File objects are implemented using \C{}'s \code{stdio} package and can be -% XXXJH xref here created with the built-in function \code{open()} described under -Built-in Functions below. +Built-in Functions below. They are also returned by some other +built-in functions and methods, e.g.\ \code{posix.popen()} and +\code{posix.fdopen()} and the \code{makefile()} method of socket +objects. +\bifuncindex{open} +\bifuncindex{popen} +\bifuncindex{fdopen} +\bifuncindex{makefile} When a file operation fails for an I/O-related reason, the exception \code{IOError} is raised. This includes situations where the @@ -661,8 +735,7 @@ object's (writable) attributes; \item \code{\var{x}.__methods__} lists the methods of many built-in object types, -e.g., \code{[].__methods__} is -% XXXJH results in?, yields?, written down as an example +e.g., \code{[].__methods__} yields \code{['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort']}; \item diff --git a/Doc/lib/libunix.tex b/Doc/lib/libunix.tex index eca2371..fe92d97 100644 --- a/Doc/lib/libunix.tex +++ b/Doc/lib/libunix.tex @@ -1,5 +1,36 @@ -\chapter{UNIX ONLY} +\chapter{UNIX Specific Services} The modules described in this chapter provide interfaces to features that are unique to the \UNIX{} operating system, or in some cases to -some or many variants of it. +some or many variants of it. Here's an overview: + +\begin{description} + +\item[posix] +--- The most common Posix system calls (normally used via module \code{os}). + +\item[posixpath] +--- Common Posix pathname manipulations (normally used via \code{os.path}). + +\item[pwd] +--- The password database (\code{getpwnam()} and friends). + +\item[grp] +--- The group database (\code{getgrnam()} and friends). + +\item[dbm] +--- The standard ``database'' interface, based on \code{ndbm}. + +\item[gdbm] +--- GNU's reinterpretation of dbm. + +\item[termios] +--- Posix style tty control. + +\item[fcntl] +--- The \code{fcntl()} and \code{ioctl()} system calls. + +\item[posixfile] +--- A file-like object with support for locking. + +\end{description} diff --git a/Doc/lib/libwww.tex b/Doc/lib/libwww.tex index d6aaeab..009c79b 100644 --- a/Doc/lib/libwww.tex +++ b/Doc/lib/libwww.tex @@ -1,4 +1,4 @@ -\chapter{THE INTERNET AND THE WORLD-WIDE WEB} +\chapter{Internet and WWW Services} \nodename{Internet and WWW} \index{WWW} \index{Internet} diff --git a/Doc/libaifc.tex b/Doc/libaifc.tex index 7e595ef..04ed2e4 100644 --- a/Doc/libaifc.tex +++ b/Doc/libaifc.tex @@ -11,8 +11,14 @@ The sampling rate or frame rate is the number of times per second the sound is sampled. The number of channels indicate if the audio is mono, stereo, or quadro. Each frame consists of one sample per channel. The sample size is the size in bytes of each sample. Thus a -frame consists of \var{nchannels}*\var{framesize} bytes, and a second's worth of -audio consists of \var{nchannels}*\var{framesize}*\var{framerate} bytes. +frame consists of \var{nchannels}*\var{samplesize} bytes, and a +second's worth of audio consists of +\var{nchannels}*\var{samplesize}*\var{framerate} bytes. + +For example, CD quality audio has a sample size of two bytes (16 +bits), uses two channels (stereo) and has a frame rate of 44,100 +frames/second. This gives a frame size of 4 bytes (2*2), and a +second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes. Module \code{aifc} defines the following function: @@ -148,7 +154,7 @@ string. Currently the following compression types are supported: NONE, ULAW, ALAW, G722. \end{funcdesc} -\begin{funcdesc}{setparams}{(nchannels\, sampwidth\, framerate\, comptype\, compname)} +\begin{funcdesc}{setparams}{nchannels\, sampwidth\, framerate\, comptype\, compname} Set all the above parameters at once. The argument is a tuple consisting of the various parameters. This means that it is possible to use the result of a \code{getparams} call as argument to diff --git a/Doc/liballos.tex b/Doc/liballos.tex new file mode 100644 index 0000000..b5a207e --- /dev/null +++ b/Doc/liballos.tex @@ -0,0 +1,23 @@ +\chapter{Generic Operating System Services} + +The modules described in this chapter provide interfaces to operating +system features that are available on (almost) all operating systems, +such as files and a clock. The interfaces are generally modelled +after the \UNIX{} or C interfaces but they are available on most other +systems as well. Here's an overview: + +\begin{description} + +\item[os] +--- Miscellaneous OS interfaces. + +\item[time] +--- Time access and conversions. + +\item[getopt] +--- Parser for command line options. + +\item[tempfile] +--- Generate temporary file names. + +\end{description} diff --git a/Doc/libamoeba.tex b/Doc/libamoeba.tex index 1e31bc6..54a9dfb 100644 --- a/Doc/libamoeba.tex +++ b/Doc/libamoeba.tex @@ -1,4 +1,4 @@ -\chapter{AMOEBA ONLY} +\chapter{Amoeba Specific Services} \section{Built-in Module \sectcode{amoeba}} diff --git a/Doc/libarray.tex b/Doc/libarray.tex index 9e37d55..8122f49 100644 --- a/Doc/libarray.tex +++ b/Doc/libarray.tex @@ -23,6 +23,9 @@ The actual representation of values is determined by the machine architecture (strictly speaking, by the C implementation). The actual size can be accessed through the \var{itemsize} attribute. +See also built-in module \code{struct}. +\bimodindex{struct} + The module defines the following function: \renewcommand{\indexsubitem}{(in module array)} diff --git a/Doc/libcrypto.tex b/Doc/libcrypto.tex index 972106c..cc38e5b 100644 --- a/Doc/libcrypto.tex +++ b/Doc/libcrypto.tex @@ -1,9 +1,22 @@ -\chapter{CRYPTOGRAPHIC EXTENSIONS} +\chapter{Cryptographic Services} +\index{cryptography} The modules described in this chapter implement various algorithms of a cryptographic nature. They are available at the discretion of the -installation. -\index{cryptography} +installation. Here's an overview: + +\begin{description} + +\item[md5] +--- RSA's MD5 message digest algorithm. + +\item[mpz] +--- Interface to the GNU MP library for arbitrary precision arithmetic. + +\item[rotor] +--- Enigma-like encryption and decryption. + +\end{description} Hardcore cypherpunks will probably find the Python Cryptography Kit of further interest; the package adds built-in modules for DES and IDEA diff --git a/Doc/libfuncs.tex b/Doc/libfuncs.tex index 4778c7d..b526fcc 100644 --- a/Doc/libfuncs.tex +++ b/Doc/libfuncs.tex @@ -197,7 +197,8 @@ removed. Convert a number to a plain integer. The argument may be a plain or long integer or a floating point number. Conversion of floating point numbers to integers is defined by the C semantics; normally - the conversion truncates towards zero. + the conversion truncates towards zero.\footnote{This is ugly --- the + language definition should require truncation towards zero.} \end{funcdesc} \begin{funcdesc}{len}{s} diff --git a/Doc/libhttplib.tex b/Doc/libhttplib.tex index 4587ac1..d2e2420 100644 --- a/Doc/libhttplib.tex +++ b/Doc/libhttplib.tex @@ -46,8 +46,12 @@ file object that it returns. \end{enumerate} +\subsection{HTTP Objects} + \code{HTTP} instances have the following methods: +\renewcommand{\indexsubitem}{(HTTP method)} + \begin{funcdesc}{set_debuglevel}{level} Set the debugging level (the amount of debugging output printed). The default debug level is \code{0}, meaning no debugging output is diff --git a/Doc/libimp.tex b/Doc/libimp.tex index 91e250b..f995979 100644 --- a/Doc/libimp.tex +++ b/Doc/libimp.tex @@ -51,7 +51,7 @@ object. If the module was already initialized, it will be initialized \code{None} is returned. (Frozen modules are modules written in Python whose compiled byte-code object is incorporated into a custom-built Python interpreter by Python's \code{freeze} utility. -See \code{Demo/freeze} for now.) +See \code{Tools/freeze} for now.) \end{funcdesc} \begin{funcdesc}{is_builtin}{name} diff --git a/Doc/libmac.tex b/Doc/libmac.tex index 545b62c..af07142 100644 --- a/Doc/libmac.tex +++ b/Doc/libmac.tex @@ -1,4 +1,4 @@ -\chapter{MACINTOSH ONLY} +\chapter{Macintosh Specific Services} The modules in this chapter are available on the Apple Macintosh only. diff --git a/Doc/libmimetools.tex b/Doc/libmimetools.tex index 03f9247..decb890 100644 --- a/Doc/libmimetools.tex +++ b/Doc/libmimetools.tex @@ -45,7 +45,7 @@ file \var{output}. The block size is currently fixed at 8192. \end{funcdesc} -\subsection{Additional Methods of \sectcode{Message} objects} +\subsection{Additional Methods of Message objects} \nodename{mimetools.Message Methods} The \code{mimetools.Message} class defines the following methods in diff --git a/Doc/libmisc.tex b/Doc/libmisc.tex new file mode 100644 index 0000000..b7a726e --- /dev/null +++ b/Doc/libmisc.tex @@ -0,0 +1,20 @@ +\chapter{Miscellaneous Services} + +The modules described in this chapter provide miscellaneous services +that are available in all Python versions. Here's an overview: + +\begin{description} + +\item[math] +--- Mathematical functions (\code{sin()} etc.). + +\item[rand] +--- Integer random number generator. + +\item[whrandom] +--- Floating point random number generator. + +\item[array] +--- Efficient arrays of uniformly typed numeric values. + +\end{description} diff --git a/Doc/libmm.tex b/Doc/libmm.tex index c17aa55..d5abc6f 100644 --- a/Doc/libmm.tex +++ b/Doc/libmm.tex @@ -1,5 +1,25 @@ -\chapter{MULTIMEDIA EXTENSIONS} +\chapter{Multimedia Services} -The modules described in this chapter implement various algorithms -that are mainly useful for multimedia applications. They are -available at the discretion of the installation. +The modules described in this chapter implement various algorithms or +interfaces that are mainly useful for multimedia applications. They +are available at the discretion of the installation. Here's an overview: + +\begin{description} + +\item[audioop] +--- Manipulate raw audio data. + +\item[imageop] +--- Manipulate raw image data. + +\item[aifc] +--- Read and write audio files in AIFF or AIFC format. + +\item[jpeg] +--- Read and write image files in compressed JPEG format. + +\item[rgbimg] +--- Read and write image files in ``SGI RGB'' format (the module is +\emph{not} SGI specific though)! + +\end{description} diff --git a/Doc/libobjs.tex b/Doc/libobjs.tex index 49a86fc..9006b8a 100644 --- a/Doc/libobjs.tex +++ b/Doc/libobjs.tex @@ -4,16 +4,21 @@ Names for built-in exceptions and functions are found in a separate symbol table. This table is searched last, so local and global -user-defined names can override built-in names. Built-in types have -no names but are created easily by constructing an object of the -desired type (e.g., using a literal) and applying the built-in -function \code{type()} to it. They are described together here for -easy reference.% -\footnote{Some descriptions sorely lack explanations of the exceptions +user-defined names can override built-in names. Built-in types are +described together here for easy reference. % +\footnote{Most descriptions sorely lack explanations of the exceptions that may be raised --- this will be fixed in a future version of - this document.} + this manual.} \indexii{built-in}{types} \indexii{built-in}{exceptions} \indexii{built-in}{functions} \index{symbol table} \bifuncindex{type} + +The tables in this chapter document the priorities of operators by +listing them in order of ascending priority (within a table) and +grouping operators that have the same priority in the same box. +Binary operators of the same priority group from left to right. +(Unary operators group from right to left, but there you have no real +choice.) See Chapter 5 of the Python Reference Manual for the +complete picture on operator priorities. diff --git a/Doc/libpickle.tex b/Doc/libpickle.tex index 8dc29e4..92020a2 100644 --- a/Doc/libpickle.tex +++ b/Doc/libpickle.tex @@ -11,7 +11,9 @@ The \code{pickle} module implements a basic but powerful algorithm for ``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly -arbitrary Python objects. This is a more primitive notion than +arbitrary Python objects. This is the act of converting objects to a +stream of bytes (and back: ``unpickling''). +This is a more primitive notion than persistency --- although \code{pickle} reads and writes file objects, it does not handle the issue of naming persistent objects, nor the (even more complicated) area of concurrent access to persistent @@ -54,7 +56,8 @@ advantage of using printable \ASCII{} (and of some other characteristics of \code{pickle}'s representation) is that for debugging or recovery purposes it is possible for a human to read the pickled file with a standard text editor. (I could have gone a step further and used a -notation like S-expressions, but the parser would have been +notation like S-expressions, but the parser +(currently written in Python) would have been considerably more complicated and slower, and the files would probably have become much larger.) diff --git a/Doc/libpython.tex b/Doc/libpython.tex new file mode 100644 index 0000000..ed253f5 --- /dev/null +++ b/Doc/libpython.tex @@ -0,0 +1,40 @@ +\chapter{Python Services} + +The modules described in this chapter provide a wide range of services +related to the Python interpreter and its interaction with its +environment. Here's an overview: + +\begin{description} + +\item[sys] +--- Access system specific parameters and functions. + +\item[types] +--- Names for all built-in types. + +\item[traceback] +--- Print or retrieve a stack traceback. + +\item[pickle] +--- Convert Python objects to streams of bytes and back. + +\item[shelve] +--- Python object persistency. + +\item[copy] +--- Shallow and deep copy operations. + +\item[marshal] +--- Convert Python objects to streams of bytes and back (with +different constraints). + +\item[imp] +--- Access the implementation of the \code{import} statement. + +\item[__builtin__] +--- The set of built-in functions. + +\item[__main__] +--- The environment where the top-level script is run. + +\end{description} diff --git a/Doc/librfc822.tex b/Doc/librfc822.tex index d819238..e2d182e 100644 --- a/Doc/librfc822.tex +++ b/Doc/librfc822.tex @@ -21,6 +21,8 @@ All header matching is done independent of upper or lower case; e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield the same result. +\subsection{Message Objects} + A \code{Message} instance has the following methods: \begin{funcdesc}{rewindbody}{} diff --git a/Doc/libsgi.tex b/Doc/libsgi.tex index f8c87b0..8deede8 100644 --- a/Doc/libsgi.tex +++ b/Doc/libsgi.tex @@ -1,4 +1,4 @@ -\chapter{SGI IRIX ONLY} +\chapter{SGI IRIX Specific Services} The modules described in this chapter provide interfaces to features that are unique to SGI's IRIX operating system (versions 4 and 5). diff --git a/Doc/libsomeos.tex b/Doc/libsomeos.tex new file mode 100644 index 0000000..f9aedfe --- /dev/null +++ b/Doc/libsomeos.tex @@ -0,0 +1,23 @@ +\chapter{Optional Operating System Services} + +The modules described in this chapter provide interfaces to operating +system features that are available on selected operating systems only. +The interfaces are generally modelled after the \UNIX{} or C +interfaces but they are available on some other systems as well +(e.g. Windows or NT). Here's an overview: + +\begin{description} + +\item[signal] +--- Set handlers for asynchronous events. + +\item[socket] +--- Low-level networking interface. + +\item[select] +--- Wait for I/O completion on multiple streams. + +\item[thread] +--- Create multiple threads of control within one namespace. + +\end{description} diff --git a/Doc/libstdwin.tex b/Doc/libstdwin.tex index ae7e8b9..e009e3f 100644 --- a/Doc/libstdwin.tex +++ b/Doc/libstdwin.tex @@ -1,13 +1,24 @@ -\chapter{STDWIN ONLY} +\chapter{Standard Windowing Interface} + +The modules in this chapter are available only on those systems where +the STDWIN library is available. STDWIN runs on \UNIX{} under X11 and +on the Macintosh. See CWI report CS-R8817. + +\strong{Warning:} Using STDWIN is not recommended for new +applications. It has never been ported to Microsoft Windows or +Windows NT, and for X11 or the Macintosh it lacks important +functionality --- in particular, it has no tools for the construction +of dialogs. For most platforms, alternative, native solutions exist +(though none are currently documented in this manual): Tkinter for +\UNIX{} under X11, native Xt with Motif or Athena widgets for \UNIX{} +under X11, Win32 for Windows and Windows NT, and a collection of +native toolkit interfaces for the Macintosh. \section{Built-in Module \sectcode{stdwin}} \bimodindex{stdwin} This module defines several new object types and functions that -provide access to the functionality of the Standard Window System -Interface, STDWIN [CWI report CR-R8817]. -It is available on systems to which STDWIN has been ported (which is -most systems). +provide access to the functionality of STDWIN. On Unix running X11, it can only be used if the \code{DISPLAY} environment variable is set or an explicit \samp{-display diff --git a/Doc/libstrings.tex b/Doc/libstrings.tex new file mode 100644 index 0000000..ea9a0999 --- /dev/null +++ b/Doc/libstrings.tex @@ -0,0 +1,20 @@ +\chapter{String Services} + +The modules described in this chapter provide a wide range of string +manipulation operations. Here's an overview: + +\begin{description} + +\item[string] +--- Common string operations. + +\item[regex] +--- Regular expression search and match operations. + +\item[regsub] +--- Substitution and splitting operations that use regular expressions. + +\item[struct] +--- Interpret strings as packed binary data. + +\end{description} diff --git a/Doc/libstruct.tex b/Doc/libstruct.tex index a2c1b10..4a08c78b 100644 --- a/Doc/libstruct.tex +++ b/Doc/libstruct.tex @@ -7,6 +7,9 @@ structs represented as Python strings. It uses \dfn{format strings} (explained below) as compact descriptions of the lay-out of the C structs and the intended conversion to/from Python values. +See also built-in module \code{array}. +\bimodindex{array} + The module defines the following exception and functions: \renewcommand{\indexsubitem}{(in module struct)} diff --git a/Doc/libsun.tex b/Doc/libsun.tex index d297b9c..5628369 100644 --- a/Doc/libsun.tex +++ b/Doc/libsun.tex @@ -1,8 +1,8 @@ -\chapter{SUNOS ONLY} +\chapter{SunOS Specific Services} The modules described in this chapter provide interfaces to features that are unique to the SunOS operating system (versions 4 and 5; the -latter is also known as SOLARIS version 2). +latter is also known as Solaris version 2). \section{Built-in Module \sectcode{sunaudiodev}} \bimodindex{sunaudiodev} diff --git a/Doc/libtermios.tex b/Doc/libtermios.tex new file mode 100644 index 0000000..8fe6f51 --- /dev/null +++ b/Doc/libtermios.tex @@ -0,0 +1,3 @@ +\section{Built-in Module \sectcode{termios}} + +To be provided. diff --git a/Doc/libtypes.tex b/Doc/libtypes.tex index 51c775e..422a2d6 100644 --- a/Doc/libtypes.tex +++ b/Doc/libtypes.tex @@ -17,7 +17,7 @@ implicitly used when an object is written by the \code{print} statement. Any object can be tested for truth value, for use in an \code{if} or \code{while} condition or as operand of the Boolean operations below. -The following values are false: +The following values are considered false: \stindex{if} \stindex{while} \indexii{truth}{value} @@ -36,21 +36,32 @@ The following values are false: \item any empty mapping, e.g., \code{\{\}}. +\item instances of user-defined classes, if the class defines a + \code{__nonzero__()} or \code{__len__()} method, when that + method returns zero. + \end{itemize} -\emph{All} other values are true --- so objects of many types are +All other values are considered true --- so objects of many types are always true. \index{true} +Operations and built-in functions that have a Boolean result always +return \code{0} for false and \code{1} for true, unless otherwise +stated. (Important exception: the Boolean operations \samp{or} and +\samp{and} always return one of their operands.) + \subsection{Boolean Operations} -These are the Boolean operations: +These are the Boolean operations, ordered by ascending priority: \indexii{Boolean}{operations} \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} \lineiii{\var{x} or \var{y}}{if \var{x} is false, then \var{y}, else \var{x}}{(1)} + \hline \lineiii{\var{x} and \var{y}}{if \var{x} is false, then \var{x}, else \var{y}}{(1)} - \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{} + \hline + \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{(2)} \end{tableiii} \opindex{and} \opindex{or} @@ -64,11 +75,24 @@ Notes: \item[(1)] These only evaluate their second argument if needed for their outcome. +\item[(2)] +\samp{not} has a lower priority than non-Boolean operators, so e.g. +\code{not a == b} is interpreted as \code{not(a == b)}, and +\code{a == not b} is a syntax error. + \end{description} \subsection{Comparisons} -Comparison operations are supported by all objects: +Comparison operations are supported by all objects. They all have the +same priority (which is higher than that of the Boolean operations). +Comparisons can be chained arbitrarily, e.g. \code{x < y <= z} is +equivalent to \code{x < y and y <= z}, except that \code{y} is +evaluated only once (but in both cases \code{z} is not evaluated at +all when \code{x < y} is found to be false). +\indexii{chaining}{comparisons} + +This table summarizes the comparison operations: \begin{tableiii}{|c|l|c|}{code}{Operation}{Meaning}{Notes} \lineiii{<}{strictly less than}{} @@ -161,20 +185,26 @@ to coerce numbers to a specific type. \bifuncindex{long} \bifuncindex{float} -All numeric types support the following operations: +All numeric types support the following operations, sorted by +ascending priority (operations in the same box have the same +priority; all numeric operations have a higher priority than +comparison operations): \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} - \lineiii{abs(\var{x})}{absolute value of \var{x}}{} - \lineiii{int(\var{x})}{\var{x} converted to integer}{(1)} - \lineiii{long(\var{x})}{\var{x} converted to long integer}{(1)} - \lineiii{float(\var{x})}{\var{x} converted to floating point}{} - \lineiii{-\var{x}}{\var{x} negated}{} - \lineiii{+\var{x}}{\var{x} unchanged}{} \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{} \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{} + \hline \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{} - \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(2)} + \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)} \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{} + \hline + \lineiii{-\var{x}}{\var{x} negated}{} + \lineiii{+\var{x}}{\var{x} unchanged}{} + \hline + \lineiii{abs(\var{x})}{absolute value of \var{x}}{} + \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)} + \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)} + \lineiii{float(\var{x})}{\var{x} converted to floating point}{} \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)} \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{} \end{tableiii} @@ -183,22 +213,24 @@ All numeric types support the following operations: \noindent Notes: \begin{description} -\item[(1)] -Conversion from floating point to (long or plain) integer may round or -% XXXJH xref here -truncate as in \C{}; see functions \code{floor} and \code{ceil} in module -\code{math} for well-defined conversions. -\indexii{numeric}{conversions} -\stmodindex{math} -\indexii{\C{}}{language} -\item[(2)] +\item[(1)] For (plain or long) integer division, the result is an integer; it always truncates towards zero. % XXXJH integer division is better defined nowadays \indexii{integer}{division} \indexiii{long}{integer}{division} +\item[(2)] +Conversion from floating point to (long or plain) integer may round or +truncate as in \C{}; see functions \code{floor()} and \code{ceil()} in +module \code{math} for well-defined conversions. +\bifuncindex{floor} +\bifuncindex{ceil} +\indexii{numeric}{conversions} +\stmodindex{math} +\indexii{\C{}}{language} + \item[(3)] See the section on built-in functions for an exact definition. @@ -210,52 +242,89 @@ See the section on built-in functions for an exact definition. Plain and long integer types support additional operations that make sense only for bit-strings. Negative numbers are treated as their 2's -complement value: +complement value (for long integers, this assumes a sufficiently large +number of bits that no overflow occurs during the operation). + +The priorities of the binary bit-wise operations are all lower than +the numeric operations and higher than the comparisons; the unary +operation \samp{~} has the same priority as the other unary numeric +operations (\samp{+} and \samp{-}). + +This table lists the bit-string operations sorted in ascending +priority (operations in the same box have the same priority): \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} - \lineiii{\~\var{x}}{the bits of \var{x} inverted}{} + \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{} + \hline \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{} + \hline \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{} - \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{} - \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{} - \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{} + \hline + \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)} + \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)} + \hline + \hline + \lineiii{\~\var{x}}{the bits of \var{x} inverted}{} \end{tableiii} -% XXXJH what's `left'? `right'? maybe better use lsb or msb or something \indexiii{operations on}{integer}{types} \indexii{bit-string}{operations} \indexii{shifting}{operations} \indexii{masking}{operations} +\noindent +Notes: +\begin{description} +\item[(1)] Negative shift counts are illegal. +\item[(2)] A left shift by \var{n} bits is equivalent to +multiplication by \code{pow(2, \var{n})} without overflow check. +\item[(3)] A right shift by \var{n} bits is equivalent to +division by \code{pow(2, \var{n})} without overflow check. +\end{description} + \subsection{Sequence Types} There are three sequence types: strings, lists and tuples. -Strings literals are written in single quotes: \code{'xyzzy'}. -Lists are constructed with square brackets, -separating items with commas: -\code{[a, b, c]}. -Tuples are constructed by the comma operator -(not within square brackets), with or without enclosing parentheses, -but an empty tuple must have the enclosing parentheses, e.g., -\code{a, b, c} or \code{()}. A single item tuple must have a trailing comma, -e.g., \code{(d,)}. + +Strings literals are written in single or double quotes: +\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the Python +Reference Manual for more about string literals. Lists are +constructed with square brackets, separating items with commas: +\code{[a, b, c]}. Tuples are constructed by the comma operator (not +within square brackets), with or without enclosing parentheses, but an +empty tuple must have the enclosing parentheses, e.g., +\code{a, b, c} or \code{()}. A single item tuple must have a trailing +comma, e.g., \code{(d,)}. \indexii{sequence}{types} \indexii{string}{type} \indexii{tuple}{type} \indexii{list}{type} -Sequence types support the following operations (\var{s} and \var{t} are -sequences of the same type; \var{n}, \var{i} and \var{j} are integers): +Sequence types support the following operations. The \samp{in} and +\samp{not\,in} operations have the same priorities as the comparison +operations. The \samp{+} and \samp{*} operations have the same +priority as the corresponding numeric operations.\footnote{They must +have since the parser can't tell the type of the operands.} + +This table lists the sequece operations sorted in ascending priority +(operations in the same box have the same priority). In the table, +\var{s} and \var{t} are sequences of the same type; \var{n}, \var{i} +and \var{j} are integers: \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} - \lineiii{len(\var{s})}{length of \var{s}}{} - \lineiii{min(\var{s})}{smallest item of \var{s}}{} - \lineiii{max(\var{s})}{largest item of \var{s}}{} \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{} - \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is equal to \var{x}, else \code{1}}{} + \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is +equal to \var{x}, else \code{1}}{} + \hline \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{} + \hline \lineiii{\var{s} * \var{n}{\rm ,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{} + \hline \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(1)} \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(1), (2)} + \hline + \lineiii{len(\var{s})}{length of \var{s}}{} + \lineiii{min(\var{s})}{smallest item of \var{s}}{} + \lineiii{max(\var{s})}{largest item of \var{s}}{} \end{tableiii} \indexiii{operations on}{sequence}{types} \bifuncindex{len} @@ -271,7 +340,6 @@ sequences of the same type; \var{n}, \var{i} and \var{j} are integers): \noindent Notes: -% XXXJH all TeX-math expressions replaced by python-syntax expressions \begin{description} \item[(1)] If \var{i} or \var{j} is negative, the index is relative to @@ -423,9 +491,9 @@ can be used interchangeably to index the same dictionary entry. \indexii{dictionary}{type} Dictionaries are created by placing a comma-separated list of -\code{\var{key}:\ \var{value}} pairs within braces, for example: -\code{\{'jack':\ 4098, 'sjoerd':\ 4127\}} or -\code{\{4098:\ 'jack', 4127:\ 'sjoerd'\}}. +\code{\var{key}:\,var{value}} pairs within braces, for example: +\code{\{'jack':\,4098, 'sjoerd':\,4127\}} or +\code{\{4098:\,'jack', 4127:\,'sjoerd'\}}. The following operations are defined on mappings (where \var{a} is a mapping, \var{k} is a key and \var{x} is an arbitrary object): @@ -448,8 +516,6 @@ mapping, \var{k} is a key and \var{x} is an arbitrary object): \ttindex{keys} \ttindex{has_key} -% XXXJH some lines above, you talk about `true', elsewhere you -% explicitely states \code{0} or \code{1}. \noindent Notes: \begin{description} @@ -485,8 +551,8 @@ Modules are written like this: \code{<module 'sys'>}. \subsubsection{Classes and Class Instances} \nodename{Classes and Instances} -% XXXJH cross ref here -(See the Python Reference Manual for these.) + +(See Chapters 3 and 7 of the Python Reference Manual for these.) \subsubsection{Functions} @@ -547,9 +613,11 @@ source string) to the \code{exec} statement or the built-in \subsubsection{Type Objects} Type objects represent the various object types. An object's type is -% XXXJH xref here accessed by the built-in function \code{type()}. There are no special -operations on types. +operations on types. The standard module \code{types} defines names +for all standard built-in types. +\bifuncindex{type} +\stmodindex{types} Types are written like this: \code{<type 'int'>}. @@ -564,9 +632,15 @@ It is written as \code{None}. \subsubsection{File Objects} File objects are implemented using \C{}'s \code{stdio} package and can be -% XXXJH xref here created with the built-in function \code{open()} described under -Built-in Functions below. +Built-in Functions below. They are also returned by some other +built-in functions and methods, e.g.\ \code{posix.popen()} and +\code{posix.fdopen()} and the \code{makefile()} method of socket +objects. +\bifuncindex{open} +\bifuncindex{popen} +\bifuncindex{fdopen} +\bifuncindex{makefile} When a file operation fails for an I/O-related reason, the exception \code{IOError} is raised. This includes situations where the @@ -661,8 +735,7 @@ object's (writable) attributes; \item \code{\var{x}.__methods__} lists the methods of many built-in object types, -e.g., \code{[].__methods__} is -% XXXJH results in?, yields?, written down as an example +e.g., \code{[].__methods__} yields \code{['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort']}; \item diff --git a/Doc/libunix.tex b/Doc/libunix.tex index eca2371..fe92d97 100644 --- a/Doc/libunix.tex +++ b/Doc/libunix.tex @@ -1,5 +1,36 @@ -\chapter{UNIX ONLY} +\chapter{UNIX Specific Services} The modules described in this chapter provide interfaces to features that are unique to the \UNIX{} operating system, or in some cases to -some or many variants of it. +some or many variants of it. Here's an overview: + +\begin{description} + +\item[posix] +--- The most common Posix system calls (normally used via module \code{os}). + +\item[posixpath] +--- Common Posix pathname manipulations (normally used via \code{os.path}). + +\item[pwd] +--- The password database (\code{getpwnam()} and friends). + +\item[grp] +--- The group database (\code{getgrnam()} and friends). + +\item[dbm] +--- The standard ``database'' interface, based on \code{ndbm}. + +\item[gdbm] +--- GNU's reinterpretation of dbm. + +\item[termios] +--- Posix style tty control. + +\item[fcntl] +--- The \code{fcntl()} and \code{ioctl()} system calls. + +\item[posixfile] +--- A file-like object with support for locking. + +\end{description} diff --git a/Doc/libwww.tex b/Doc/libwww.tex index d6aaeab..009c79b 100644 --- a/Doc/libwww.tex +++ b/Doc/libwww.tex @@ -1,4 +1,4 @@ -\chapter{THE INTERNET AND THE WORLD-WIDE WEB} +\chapter{Internet and WWW Services} \nodename{Internet and WWW} \index{WWW} \index{Internet} diff --git a/Doc/mac/libmac.tex b/Doc/mac/libmac.tex index 545b62c..af07142 100644 --- a/Doc/mac/libmac.tex +++ b/Doc/mac/libmac.tex @@ -1,4 +1,4 @@ -\chapter{MACINTOSH ONLY} +\chapter{Macintosh Specific Services} The modules in this chapter are available on the Apple Macintosh only. |