New stuff by AMK.

Doc/Makefile

@@ -114,7 +114,7 @@ LIBFILES = lib.tex \
     librestricted.tex librexec.tex libbastion.tex \
     libformatter.tex liboperator.tex libsoundex.tex libresource.tex \
     libstat.tex libstrio.tex libundoc.tex libmailcap.tex libglob.tex \
-    libuser.tex
+    libuser.tex libanydbm.tex librandom.tex libsite.tex libwhichdb.tex
 
 # Library document
 lib.dvi: $(LIBFILES)

Doc/lib.tex

@@ -86,6 +86,7 @@ to Python and how to embed it in other applications.
 \input{libmarshal}
 \input{libimp}
 \input{libparser}
+\input{libsite}
 \input{libbltin}		% really __builtin__
 \input{libmain}			% really __main__
 
@@ -99,8 +100,9 @@ to Python and how to embed it in other applications.
 
 \input{libmisc}			% Miscellaneous Services
 \input{libmath}
-\input{librand}
 \input{libwhrandom}
+\input{librandom}
+\input{librand}
 \input{libarray}
 
 \input{liballos}		% Generic Operating System Services
@@ -116,6 +118,8 @@ to Python and how to embed it in other applications.
 \input{libsocket}
 \input{libselect}
 \input{libthread}
+\input{libanydbm}
+\input{libwhichdb}
 
 \input{libunix}			% UNIX Specific Services
 \input{libposix}

Doc/lib/lib.tex

@@ -86,6 +86,7 @@ to Python and how to embed it in other applications.
 \input{libmarshal}
 \input{libimp}
 \input{libparser}
+\input{libsite}
 \input{libbltin}		% really __builtin__
 \input{libmain}			% really __main__
 
@@ -99,8 +100,9 @@ to Python and how to embed it in other applications.
 
 \input{libmisc}			% Miscellaneous Services
 \input{libmath}
-\input{librand}
 \input{libwhrandom}
+\input{librandom}
+\input{librand}
 \input{libarray}
 
 \input{liballos}		% Generic Operating System Services
@@ -116,6 +118,8 @@ to Python and how to embed it in other applications.
 \input{libsocket}
 \input{libselect}
 \input{libthread}
+\input{libanydbm}
+\input{libwhichdb}
 
 \input{libunix}			% UNIX Specific Services
 \input{libposix}

Doc/lib/libanydbm.tex

+\section{Standard Module \sectcode{anydbm}}
+\stmodindex{anydbm}
+\stmodindex{dumbdbm}
+
+\code{anydbm} is a generic interface to variants of the DBM
+database--DBM, GDBM, or dbhash.  If none of these modules is
+installed, the slow-but-simple implementation in \file{dumbdbm.py}
+will be used.   
+
+\begin{funcdesc}{open}{filename\optional{\, flag\, mode}}
+Open the database file \var{filename} and return a corresponding object.  
+The optional \var{flag} argument can be
+\code{'r'} to open an existing database for reading only,
+\code{'w'} to open an existing database for reading and writing,
+\code{'c'} to create the database if it doesn't exist, or
+\code{'n'}, which will always create a new empty database.  If not
+specified, the default value is \code{'r'}.
+
+The optional \var{mode} argument is the \UNIX{} mode of the file, used
+only when the database has to be created.  It defaults to octal
+\code{0666}.
+\end{funcdesc}
+
+THe object returned by \code{open()} supports most of the same
+functionality as dictionaries; keys and their corresponding values can
+be stored, retrieved, and deleted, and the \code{has_key()} and
+\code{keys()} methods are available. Keys and values must always be strings.
+
+

Doc/lib/libmisc.tex

@@ -8,11 +8,14 @@ that are available in all Python versions.  Here's an overview:
 \item[math]
 --- Mathematical functions (\code{sin()} etc.).
 
-\item[rand]
---- Integer random number generator.
-
 \item[whrandom]
---- Floating point random number generator.
+--- Floating point pseudo-random number generator.
+
+\item[random]
+--- Generate pseudo-random numbers with various common distributions.
+
+\item[rand]
+--- Integer pseudo-random number generator (obsolete).
 
 \item[array]
 --- Efficient arrays of uniformly typed numeric values.

Doc/lib/librand.tex

 \section{Standard Module \sectcode{rand}}
+\stmodindex{rand}
 
-\stmodindex{rand} This module implements a pseudo-random number
-generator with an interface similar to \code{rand()} in C\@.  It defines
-the following functions:
+The \code{rand} module simulates the C library's \code{rand()}
+interface, though the results aren't necessarily compatible with any
+given library's implementation.  While still supported for
+compatibility, the \code{rand} module is now considered obsolete; if
+possible, use the \code{whrandom} module instead.
 
-\renewcommand{\indexsubitem}{(in module rand)}
-\begin{funcdesc}{rand}{}
-Returns an integer random number in the range [0 ... 32768).
+\begin{funcdesc}{choice}{seq}
+Returns a random element from the sequence \var{seq}.
 \end{funcdesc}
 
-\begin{funcdesc}{choice}{s}
-Returns a random element from the sequence (string, tuple or list)
-\var{s}.
+\begin{funcdesc}{rand}{}
+Return a random integer between 0 and 32767, inclusive.
 \end{funcdesc}
 
 \begin{funcdesc}{srand}{seed}
-Initializes the random number generator with the given integral seed.
-When the module is first imported, the random number is initialized with
-the current time.
+Set a starting seed value for the random number generator; \var{seed}
+can be an arbitrary integer. 
 \end{funcdesc}
+

Doc/lib/librandom.tex

+\section{Standard Module \sectcode{random}}
+\stmodindex{random}
+
+This module implements pseudo-random number generators for various
+distributions: on the real line, there are functions to compute normal
+or Gaussian, lognormal, negative exponential, gamma, and beta
+distributions.  For generating distribution of angles, the circular
+uniform and von Mises distributions are available.
+
+The module exports the following functions, which are exactly
+equivalent to those in the \code{whrandom} module: \code{choice},
+\code{randint}, \code{random}, \code{uniform}.  See the documentation
+for the \code{whrandom} module for these functions.
+
+The following functions specific to the \code{random} module are also
+defined, and all return real values.  Function parameters are named
+after the corresponding variables in the distribution's equation, as
+used in common mathematical practice; most of these equations can be
+found in any statistics text.
+
+\renewcommand{\indexsubitem}{(in module random)}
+\begin{funcdesc}{betavariate}{alpha\, beta}
+Beta distribution.  Conditions on the parameters are \code{alpha>-1}
+and \code{beta>-1}.
+Returned values will range between 0 and 1.
+\end{funcdesc}
+
+\begin{funcdesc}{cunifvariate}{mean\, arc}
+Circular uniform distribution.  \var{mean} is the mean angle, and
+\var{arc} is the range of the distribution, centered around the mean
+angle.  Both values must be expressed in radians, and can range
+between 0 and \code{pi}.  Returned values will range between
+\code{mean - arc/2} and \code{mean + arc/2}.
+\end{funcdesc}
+
+\begin{funcdesc}{expovariate}{lambd}
+Exponential distribution.  \var{lambd} is 1.0 divided by the desired mean.
+(The parameter would be called ``lambda'', but that's also a reserved
+word in Python.)  Returned values will range from 0 to positive infinity.
+\end{funcdesc}
+
+\begin{funcdesc}{gamma}{alpha\, beta}
+Gamma distribution.  (\emph{Not} the gamma function!) 
+Conditions on the parameters are \code{alpha>-1} and \code{beta>0}.
+\end{funcdesc}
+
+\begin{funcdesc}{gauss}{mu\, sigma}
+Gaussian distribution.  \var{mu} is the mean, and \var{sigma} is the
+standard deviation.  This is slightly faster than the
+\code{normalvariate} function defined below.
+\end{funcdesc}
+
+\begin{funcdesc}{lognormvariate}{mu\, sigma}
+Log normal distribution.  If you take the natural logarithm of this
+distribution, you'll get a normal distribution with mean \var{mu} and
+standard deviation \var{sigma}  \var{mu} can have any value, and \var{sigma}
+must be greater than zero.  
+\end{funcdesc}
+
+\begin{funcdesc}{normalvariate}{mu\, sigma}
+Normal distribution.  \var{mu} is the mean, and \var{sigma} is the
+standard deviation.
+\end{funcdesc}
+
+\begin{funcdesc}{vonmisesvariate}{mu\, kappa}
+\var{mu} is the mean angle, expressed in radians between 0 and pi,
+and \var{kappa} is the concentration parameter, which must be greater
+then or equal to zero.  If \var{kappa} is equal to zero, this
+distribution reduces to a uniform random angle over the range 0 to
+\code{2*pi}.
+\end{funcdesc}

Doc/lib/libsite.tex

+\section{Standard Module \sectcode{site}}
+\stmodindex{site}
+
+Scripts or modules that need to use site-specific modules should
+execute \code{import site} somewhere near the top of their code.  This
+will append up to two site-specific paths (\code{sys.prefix +
+'/lib/site-python'} and
+\code{sys.exec_prefix + '/lib/site-python'}) to the module search path. 
+\code{sys.prefix} and \code{sys.exec_prefix} are configured when Python is installed; the default value is \file{/usr/local}.   
+
+Because of Python's import semantics, it is okay for more than one
+module to import \code{site} -- only the first one will execute the
+site customizations.  The directories are only appended to the path if
+they exist and are not already on it.
+
+Sites that wish to provide site-specific modules should place them in
+one of the site specific directories; \code{sys.prefix +
+'/lib/site-python'} is for Python source code and
+\code{sys.exec_prefix + '/lib/site-python'} is for dynamically
+loadable extension modules (shared libraries).
+
+After these path manipulations, an attempt is made to import a module
+named \code{sitecustomize}, which can perform arbitrary site-specific
+customizations.  If this import fails with an \code{ImportError}
+exception, it is ignored.
+
+Note that for non-Unix systems, \code{sys.prefix} and
+\code{sys.exec_prefix} are empty, and the path manipulations are
+skipped; however the import of \code{sitecustomize} is still attempted.

Doc/lib/libsomeos.tex

@@ -20,4 +20,9 @@ interfaces but they are available on some other systems as well
 \item[thread]
 --- Create multiple threads of control within one namespace.
 
+\item[anydbm]
+--- Generic interface to DBM-style database modules.
+\item[whichdbm]
+--- Guess which DBM-style module created a given database.
+
 \end{description}

Doc/lib/libwhichdb.tex

+\section{Standard Module \sectcode{whichdb}}
+\stmodindex{whichdb}
+
+The single function in this module attempts to guess which of the
+several simple database modules available--dbm, gdbm, or
+dbhash--should be used to open a given file.
+
+\renewcommand{\indexsubitem}{(in module whichdb)}
+\begin{funcdesc}{whichdb}{filename}
+Returns one of the following values: \code{None} if the file can't be
+opened because it's unreadable or doesn't exist; the empty string
+(\code{""}) if the file's format can't be guessed; or a string
+containing the required module name, such as \code{"dbm"} or
+\code{"gdbm"}.
+\end{funcdesc}
+

Doc/lib/libwhrandom.tex

 \section{Standard Module \sectcode{whrandom}}
-
 \stmodindex{whrandom}
-This module implements a Wichmann-Hill pseudo-random number generator.
-It defines the following functions:
 
+This module implements a Wichmann-Hill pseudo-random number generator
+class that is also named \code{whrandom}.  Instances of the
+\code{whrandom} class have the following methods:
 \renewcommand{\indexsubitem}{(in module whrandom)}
+
+\begin{funcdesc}{choice}{seq}
+Chooses a random element from the non-empty sequence \var{seq} and returns it.
+\end{funcdesc}
+
+\begin{funcdesc}{randint}{a\, b}
+Returns a random integer \var{N} such that \code{\var{a}<=\var{N}<=\var{b}}.
+\end{funcdesc}
+
 \begin{funcdesc}{random}{}
 Returns the next random floating point number in the range [0.0 ... 1.0).
 \end{funcdesc}
@@ -18,3 +27,16 @@ and
 When the module is first imported, the random number is initialized
 using values derived from the current time.
 \end{funcdesc}
+
+\begin{funcdesc}{uniform}{a\, b}
+Returns a random real number \var{N} such that \code{\var{a}<=\var{N}<\var{b}}.
+\end{funcdesc}
+
+When imported, the \code{whrandom} module also creates an instance of
+the \code{whrandom} class, and makes the methods of that instance
+available at the module level.  Therefore one can write either 
+\code{N = whrandom.random()} or:
+\begin{verbatim}
+generator = whrandom.whrandom()
+N = generator.random()
+\end{verbatim}

Doc/libanydbm.tex

+\section{Standard Module \sectcode{anydbm}}
+\stmodindex{anydbm}
+\stmodindex{dumbdbm}
+
+\code{anydbm} is a generic interface to variants of the DBM
+database--DBM, GDBM, or dbhash.  If none of these modules is
+installed, the slow-but-simple implementation in \file{dumbdbm.py}
+will be used.   
+
+\begin{funcdesc}{open}{filename\optional{\, flag\, mode}}
+Open the database file \var{filename} and return a corresponding object.  
+The optional \var{flag} argument can be
+\code{'r'} to open an existing database for reading only,
+\code{'w'} to open an existing database for reading and writing,
+\code{'c'} to create the database if it doesn't exist, or
+\code{'n'}, which will always create a new empty database.  If not
+specified, the default value is \code{'r'}.
+
+The optional \var{mode} argument is the \UNIX{} mode of the file, used
+only when the database has to be created.  It defaults to octal
+\code{0666}.
+\end{funcdesc}
+
+THe object returned by \code{open()} supports most of the same
+functionality as dictionaries; keys and their corresponding values can
+be stored, retrieved, and deleted, and the \code{has_key()} and
+\code{keys()} methods are available. Keys and values must always be strings.
+
+

Doc/libmisc.tex

@@ -8,11 +8,14 @@ that are available in all Python versions.  Here's an overview:
 \item[math]
 --- Mathematical functions (\code{sin()} etc.).
 
-\item[rand]
---- Integer random number generator.
-
 \item[whrandom]
---- Floating point random number generator.
+--- Floating point pseudo-random number generator.
+
+\item[random]
+--- Generate pseudo-random numbers with various common distributions.
+
+\item[rand]
+--- Integer pseudo-random number generator (obsolete).
 
 \item[array]
 --- Efficient arrays of uniformly typed numeric values.

Doc/librand.tex

 \section{Standard Module \sectcode{rand}}
+\stmodindex{rand}
 
-\stmodindex{rand} This module implements a pseudo-random number
-generator with an interface similar to \code{rand()} in C\@.  It defines
-the following functions:
+The \code{rand} module simulates the C library's \code{rand()}
+interface, though the results aren't necessarily compatible with any
+given library's implementation.  While still supported for
+compatibility, the \code{rand} module is now considered obsolete; if
+possible, use the \code{whrandom} module instead.
 
-\renewcommand{\indexsubitem}{(in module rand)}
-\begin{funcdesc}{rand}{}
-Returns an integer random number in the range [0 ... 32768).
+\begin{funcdesc}{choice}{seq}
+Returns a random element from the sequence \var{seq}.
 \end{funcdesc}
 
-\begin{funcdesc}{choice}{s}
-Returns a random element from the sequence (string, tuple or list)
-\var{s}.
+\begin{funcdesc}{rand}{}
+Return a random integer between 0 and 32767, inclusive.
 \end{funcdesc}
 
 \begin{funcdesc}{srand}{seed}
-Initializes the random number generator with the given integral seed.
-When the module is first imported, the random number is initialized with
-the current time.
+Set a starting seed value for the random number generator; \var{seed}
+can be an arbitrary integer. 
 \end{funcdesc}
+

Doc/librandom.tex

+\section{Standard Module \sectcode{random}}
+\stmodindex{random}
+
+This module implements pseudo-random number generators for various
+distributions: on the real line, there are functions to compute normal
+or Gaussian, lognormal, negative exponential, gamma, and beta
+distributions.  For generating distribution of angles, the circular
+uniform and von Mises distributions are available.
+
+The module exports the following functions, which are exactly
+equivalent to those in the \code{whrandom} module: \code{choice},
+\code{randint}, \code{random}, \code{uniform}.  See the documentation
+for the \code{whrandom} module for these functions.
+
+The following functions specific to the \code{random} module are also
+defined, and all return real values.  Function parameters are named
+after the corresponding variables in the distribution's equation, as
+used in common mathematical practice; most of these equations can be
+found in any statistics text.
+
+\renewcommand{\indexsubitem}{(in module random)}
+\begin{funcdesc}{betavariate}{alpha\, beta}
+Beta distribution.  Conditions on the parameters are \code{alpha>-1}
+and \code{beta>-1}.
+Returned values will range between 0 and 1.
+\end{funcdesc}
+
+\begin{funcdesc}{cunifvariate}{mean\, arc}
+Circular uniform distribution.  \var{mean} is the mean angle, and
+\var{arc} is the range of the distribution, centered around the mean
+angle.  Both values must be expressed in radians, and can range
+between 0 and \code{pi}.  Returned values will range between
+\code{mean - arc/2} and \code{mean + arc/2}.
+\end{funcdesc}
+
+\begin{funcdesc}{expovariate}{lambd}
+Exponential distribution.  \var{lambd} is 1.0 divided by the desired mean.
+(The parameter would be called ``lambda'', but that's also a reserved
+word in Python.)  Returned values will range from 0 to positive infinity.
+\end{funcdesc}
+
+\begin{funcdesc}{gamma}{alpha\, beta}
+Gamma distribution.  (\emph{Not} the gamma function!) 
+Conditions on the parameters are \code{alpha>-1} and \code{beta>0}.
+\end{funcdesc}
+
+\begin{funcdesc}{gauss}{mu\, sigma}
+Gaussian distribution.  \var{mu} is the mean, and \var{sigma} is the
+standard deviation.  This is slightly faster than the
+\code{normalvariate} function defined below.
+\end{funcdesc}
+
+\begin{funcdesc}{lognormvariate}{mu\, sigma}
+Log normal distribution.  If you take the natural logarithm of this
+distribution, you'll get a normal distribution with mean \var{mu} and
+standard deviation \var{sigma}  \var{mu} can have any value, and \var{sigma}
+must be greater than zero.  
+\end{funcdesc}
+
+\begin{funcdesc}{normalvariate}{mu\, sigma}
+Normal distribution.  \var{mu} is the mean, and \var{sigma} is the
+standard deviation.
+\end{funcdesc}
+
+\begin{funcdesc}{vonmisesvariate}{mu\, kappa}
+\var{mu} is the mean angle, expressed in radians between 0 and pi,
+and \var{kappa} is the concentration parameter, which must be greater
+then or equal to zero.  If \var{kappa} is equal to zero, this
+distribution reduces to a uniform random angle over the range 0 to
+\code{2*pi}.
+\end{funcdesc}

Doc/libsite.tex

+\section{Standard Module \sectcode{site}}
+\stmodindex{site}
+
+Scripts or modules that need to use site-specific modules should
+execute \code{import site} somewhere near the top of their code.  This
+will append up to two site-specific paths (\code{sys.prefix +
+'/lib/site-python'} and
+\code{sys.exec_prefix + '/lib/site-python'}) to the module search path. 
+\code{sys.prefix} and \code{sys.exec_prefix} are configured when Python is installed; the default value is \file{/usr/local}.   
+
+Because of Python's import semantics, it is okay for more than one
+module to import \code{site} -- only the first one will execute the
+site customizations.  The directories are only appended to the path if
+they exist and are not already on it.
+
+Sites that wish to provide site-specific modules should place them in
+one of the site specific directories; \code{sys.prefix +
+'/lib/site-python'} is for Python source code and
+\code{sys.exec_prefix + '/lib/site-python'} is for dynamically
+loadable extension modules (shared libraries).
+
+After these path manipulations, an attempt is made to import a module
+named \code{sitecustomize}, which can perform arbitrary site-specific
+customizations.  If this import fails with an \code{ImportError}
+exception, it is ignored.
+
+Note that for non-Unix systems, \code{sys.prefix} and
+\code{sys.exec_prefix} are empty, and the path manipulations are
+skipped; however the import of \code{sitecustomize} is still attempted.

Doc/libsomeos.tex

@@ -20,4 +20,9 @@ interfaces but they are available on some other systems as well
 \item[thread]
 --- Create multiple threads of control within one namespace.
 
+\item[anydbm]
+--- Generic interface to DBM-style database modules.
+\item[whichdbm]
+--- Guess which DBM-style module created a given database.
+
 \end{description}

Doc/libwhichdb.tex

+\section{Standard Module \sectcode{whichdb}}
+\stmodindex{whichdb}
+
+The single function in this module attempts to guess which of the
+several simple database modules available--dbm, gdbm, or
+dbhash--should be used to open a given file.
+
+\renewcommand{\indexsubitem}{(in module whichdb)}
+\begin{funcdesc}{whichdb}{filename}
+Returns one of the following values: \code{None} if the file can't be
+opened because it's unreadable or doesn't exist; the empty string
+(\code{""}) if the file's format can't be guessed; or a string
+containing the required module name, such as \code{"dbm"} or
+\code{"gdbm"}.
+\end{funcdesc}
+

Doc/libwhrandom.tex

 \section{Standard Module \sectcode{whrandom}}
-
 \stmodindex{whrandom}
-This module implements a Wichmann-Hill pseudo-random number generator.
-It defines the following functions:
 
+This module implements a Wichmann-Hill pseudo-random number generator
+class that is also named \code{whrandom}.  Instances of the
+\code{whrandom} class have the following methods:
 \renewcommand{\indexsubitem}{(in module whrandom)}
+
+\begin{funcdesc}{choice}{seq}
+Chooses a random element from the non-empty sequence \var{seq} and returns it.
+\end{funcdesc}
+
+\begin{funcdesc}{randint}{a\, b}
+Returns a random integer \var{N} such that \code{\var{a}<=\var{N}<=\var{b}}.
+\end{funcdesc}
+
 \begin{funcdesc}{random}{}
 Returns the next random floating point number in the range [0.0 ... 1.0).
 \end{funcdesc}
@@ -18,3 +27,16 @@ and
 When the module is first imported, the random number is initialized
 using values derived from the current time.
 \end{funcdesc}
+
+\begin{funcdesc}{uniform}{a\, b}
+Returns a random real number \var{N} such that \code{\var{a}<=\var{N}<\var{b}}.
+\end{funcdesc}
+
+When imported, the \code{whrandom} module also creates an instance of
+the \code{whrandom} class, and makes the methods of that instance
+available at the module level.  Therefore one can write either 
+\code{N = whrandom.random()} or:
+\begin{verbatim}
+generator = whrandom.whrandom()
+N = generator.random()
+\end{verbatim}