# 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 \
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 \
\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
\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}
\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}
\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
\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}
\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}
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:
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
--- /dev/null
+\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}
-\chapter{AMOEBA ONLY}
+\chapter{Amoeba Specific Services}
\section{Built-in Module \sectcode{amoeba}}
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)}
-\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
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}
\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
\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}
\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
--- /dev/null
+\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}
-\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}
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.
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
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.)
--- /dev/null
+\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}
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}{}
-\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).
--- /dev/null
+\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}
-\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
--- /dev/null
+\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}
(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)}
-\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}
--- /dev/null
+\section{Built-in Module \sectcode{termios}}
+
+To be provided.
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}
\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}
\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}{}
\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}
\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.
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}
\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
\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):
\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}
\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}
\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'>}.
\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
\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
-\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}
-\chapter{THE INTERNET AND THE WORLD-WIDE WEB}
+\chapter{Internet and WWW Services}
\nodename{Internet and WWW}
\index{WWW}
\index{Internet}
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:
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
--- /dev/null
+\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}
-\chapter{AMOEBA ONLY}
+\chapter{Amoeba Specific Services}
\section{Built-in Module \sectcode{amoeba}}
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)}
-\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
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}
\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
\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}
-\chapter{MACINTOSH ONLY}
+\chapter{Macintosh Specific Services}
The modules in this chapter are available on the Apple Macintosh only.
\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
--- /dev/null
+\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}
-\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}
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.
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
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.)
--- /dev/null
+\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}
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}{}
-\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).
--- /dev/null
+\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}
-\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
--- /dev/null
+\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}
(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)}
-\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}
--- /dev/null
+\section{Built-in Module \sectcode{termios}}
+
+To be provided.
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}
\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}
\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}{}
\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}
\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.
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}
\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
\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):
\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}
\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}
\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'>}.
\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
\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
-\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}
-\chapter{THE INTERNET AND THE WORLD-WIDE WEB}
+\chapter{Internet and WWW Services}
\nodename{Internet and WWW}
\index{WWW}
\index{Internet}
-\chapter{MACINTOSH ONLY}
+\chapter{Macintosh Specific Services}
The modules in this chapter are available on the Apple Macintosh only.
projects / thirdparty / Python / cpython.git / commitdiff
