Python 0.9.1 as posted in alt.sources

1 files changed, 484 insertions, 0 deletions

diff --git a/doc/mod3.tex b/doc/mod3.tex
new file mode 100644
index 0000000..d1a99b1
--- /dev/null
+++ b/doc/mod3.tex
@@ -0,0 +1,484 @@
+\section{Standard Modules}
+
+The following standard modules are defined.
+They are available in one of the directories in the default module
+search path (try printing
+{\tt sys.path}
+to find out the default search path.)
+
+\subsection{Standard Module {\tt string}}
+
+This module defines some constants useful for checking character
+classes, some exceptions, and some useful string functions.
+The constants are:
+\begin{description}
+\funcitem{digits}
+The string
+{\tt '0123456789'}.
+\funcitem{hexdigits}
+The string
+{\tt '0123456789abcdefABCDEF'}.
+\funcitem{letters}
+The concatenation of the strings
+{\tt lowercase}
+and
+{\tt uppercase}
+described below.
+\funcitem{lowercase}
+The string
+{\tt 'abcdefghijklmnopqrstuvwxyz'}.
+\funcitem{octdigits}
+The string
+{\tt '01234567'}.
+\funcitem{uppercase}
+The string
+{\tt 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
+\funcitem{whitespace}
+A string containing all characters that are considered whitespace,
+i.e.,
+space, tab and newline.
+This definition is used by
+{\tt split()}
+and
+{\tt strip()}.
+\end{description}
+
+The exceptions are:
+\begin{description}
+\excitem{atoi\_error}{non-numeric argument to string.atoi}
+%.br
+Exception raised by
+{\tt atoi}
+when a non-numeric string argument is detected.
+The exception argument is the offending string.
+\excitem{index\_error}{substring not found in string.index}
+%.br
+Exception raised by
+{\tt index}
+when
+{\tt sub}
+is not found.
+The argument are the offending arguments to index: {\tt (s, sub)}.
+\end{description}
+
+The functions are:
+\begin{description}
+\funcitem{atoi}{s}
+Converts a string to a number.
+The string must consist of one or more digits, optionally preceded by a
+sign ({\tt '+'} or {\tt '-'}).
+\funcitem{index}{s, sub}
+Returns the lowest index in
+{\tt s}
+where the substring
+{\tt sub}
+is found.
+\funcitem{lower}{s}
+Convert letters to lower case.
+\funcitem{split}{s}
+Returns a list of the whitespace-delimited words of the string
+{\tt s}.
+\funcitem{splitfields}{s, sep}
+%.br
+Returns a list containing the fields of the string
+{\tt s},
+using the string
+{\tt sep}
+as a separator.
+The list will have one more items than the number of non-overlapping
+occurrences of the separator in the string.
+Thus,
+{\tt string.splitfields(s, ' ')}
+is not the same as
+{\tt string.split(s)},
+as the latter only returns non-empty words.
+\funcitem{strip}{s}
+Removes leading and trailing whitespace from the string
+{\tt s}.
+\funcitem{swapcase}{s}
+Converts lower case letters to upper case and vice versa.
+\funcitem{upper}{s}
+Convert letters to upper case.
+\funcitem{ljust(s, width), rjust(s, width), center}{s, width}
+%.br
+These functions respectively left-justify, right-justify and center a
+string in a field of given width.
+They return a string that is at least
+{\tt width}
+characters wide, created by padding the string
+{\tt s}
+with spaces until the given width on the right, left or both sides.
+The string is never truncated.
+\end{description}
+
+\subsection{Standard Module {\tt path}}
+
+This module implements some useful functions on POSIX pathnames.
+\begin{description}
+\funcitem{basename}{p}
+Returns the base name of pathname
+{\tt p}.
+This is the second half of the pair returned by
+{\tt path.split(p)}.
+\funcitem{cat}{p, q}
+Performs intelligent pathname concatenation on paths
+{\tt p}
+and
+{\tt q}:
+If
+{\tt q}
+is an absolute path, the return value is
+{\tt q}.
+Otherwise, the concatenation of
+{\tt p}
+and
+{\tt q}
+is returned, with a slash ({\tt '/'}) inserted unless
+{\tt p}
+is empty or ends in a slash.
+\funcitem{commonprefix}{list}
+%.br
+Returns the longest string that is a prefix of all strings in
+{\tt list}.
+If
+{\tt list}
+is empty, the empty string ({\tt ''}) is returned.
+\funcitem{exists}{p}
+Returns true if
+{\tt p}
+refers to an existing path.
+\funcitem{isdir}{p}
+Returns true if
+{\tt p}
+refers to an existing directory.
+\funcitem{islink}{p}
+Returns true if
+{\tt p}
+refers to a directory entry that is a symbolic link.
+Always false if symbolic links are not supported.
+\funcitem{ismount}{p}
+Returns true if
+{\tt p}
+is an absolute path that occurs in the mount table as output by the
+{\tt /etc/mount}
+utility.
+This output is read once when the function is used for the first
+time.%
+\footnote{
+Is there a better way to check for mount points?
+}
+\funcitem{split}{p}
+Returns a pair
+{\tt (head,~tail)}
+such that
+{\tt tail}
+contains no slashes and
+{\tt path.cat(head, tail)}
+is equal to
+{\tt p}.
+\funcitem{walk}{p, visit, arg}
+%.br
+Calls the function
+{\tt visit}
+with arguments
+{\tt (arg, dirname, names)}
+for each directory in the directory tree rooted at
+{\tt p}
+(including
+{\tt p}
+itself, if it is a directory).
+The argument
+{\tt dirname}
+specifies the visited directory, the argument
+{\tt names}
+lists the files in the directory (gotten from
+{\tt posix.listdir(dirname)}).
+The
+{\tt visit}
+function may modify
+{\tt names}
+to influence the set of directories visited below
+{\tt dirname},
+e.g.,
+to avoid visiting certain parts of the tree.
+(The object referred to by
+{\tt names}
+must be modified in place, using
+{\tt del}
+or slice assignment.)
+\end{description}
+
+\subsection{Standard Module {\tt getopt}}
+
+This module helps scripts to parse the command line arguments in
+{\tt sys.argv}.
+It uses the same conventions as the {\UNIX}
+{\tt getopt()}
+function.
+It defines the function
+{\tt getopt.getopt(args, options)}
+and the exception
+{\tt getopt.error}.
+
+The first argument to
+{\tt getopt()}
+is the argument list passed to the script with its first element
+chopped off (i.e.,
+{\tt sys.argv[1:]}).
+The second argument is the string of option letters that the
+script wants to recognize, with options that require an argument
+followed by a colon (i.e., the same format that {\UNIX}
+{\tt getopt()}
+uses).
+The return value consists of two elements: the first is a list of
+option-and-value pairs; the second is the list of program arguments
+left after the option list was stripped (this is a trailing slice of the
+first argument).
+Each option-and-value pair returned has the option as its first element,
+prefixed with a hyphen (e.g.,
+{\tt '-x'}),
+and the option argument as its second element, or an empty string if the
+option has no argument.
+The options occur in the list in the same order in which they were
+found, thus allowing multiple occurrences.
+Example:
+\bcode\begin{verbatim}
+>>> import getopt, string
+>>> args = string.split('-a -b -cfoo -d bar a1 a2')
+>>> args
+['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
+>>> optlist, args = getopt.getopt(args, 'abc:d:')
+>>> optlist
+[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
+>>> args
+['a1', 'a2']
+>>>
+\end{verbatim}\ecode
+The exception
+{\tt getopt.error = 'getopt error'}
+is raised when an unrecognized option is found in the argument list or
+when an option requiring an argument is given none.
+The argument to the exception is a string indicating the cause of the
+error.
+
+\subsection{Standard Module {\tt rand}}
+
+This module implements a pseudo-random number generator similar to
+{\tt rand()}
+in C.
+It defines the following functions:
+\begin{description}
+\funcitem{rand}{}
+Returns an integer random number in the range [0 ... 32768).
+\funcitem{choice}{s}
+Returns a random element from the sequence (string, tuple or list)
+{\tt s.}
+\funcitem{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.
+\end{description}
+
+\subsection{Standard Module {\tt whrandom}}
+
+This module implements a Wichmann-Hill pseudo-random number generator.
+It defines the following functions:
+\begin{description}
+\funcitem{random}{}
+Returns the next random floating point number in the range [0.0 ... 1.0).
+\funcitem{seed}{x, y, z}
+Initializes the random number generator from the integers
+{\tt x},
+{\tt y}
+and
+{\tt z}.
+When the module is first imported, the random number is initialized
+using values derived from the current time.
+\end{description}
+
+\subsection{Standard Module {\tt stdwinevents}}
+
+This module defines constants used by STDWIN for event types
+({\tt WE\_ACTIVATE} etc.), command codes ({\tt WC\_LEFT} etc.)
+and selection types ({\tt WS\_PRIMARY} etc.).
+Read the file for details.
+Suggested usage is
+\bcode\begin{verbatim}
+>>> from stdwinevents import *
+>>>
+\end{verbatim}\ecode
+
+\subsection{Standard Module {\tt rect}}
+
+This module contains useful operations on rectangles.
+A rectangle is defined as in module
+{\tt stdwin}:
+a pair of points, where a point is a pair of integers.
+For example, the rectangle
+\bcode\begin{verbatim}
+(10, 20), (90, 80)
+\end{verbatim}\ecode
+is a rectangle whose left, top, right and bottom edges are 10, 20, 90
+and 80, respectively.
+Note that the positive vertical axis points down (as in
+{\tt stdwin}).
+
+The module defines the following objects:
+\begin{description}
+\excitem{error}{rect.error}
+%.br
+The exception raised by functions in this module when they detect an
+error.
+The exception argument is a string describing the problem in more
+detail.
+\funcitem{empty}
+%.br
+The rectangle returned when some operations return an empty result.
+This makes it possible to quickly check whether a result is empty:
+\bcode\begin{verbatim}
+>>> import rect
+>>> r1 = (10, 20), (90, 80)
+>>> r2 = (0, 0), (10, 20)
+>>> r3 = rect.intersect(r1, r2)
+>>> if r3 is rect.empty: print 'Empty intersection'
+Empty intersection
+>>>
+\end{verbatim}\ecode
+\funcitem{is\_empty}{r}
+%.br
+Returns true if the given rectangle is empty.
+A rectangle
+{\em (left,~top), (right,~bottom)}
+is empty if
+{\em left~$\geq$~right}
+or
+{\em top~$\leq$~bottom}.
+\funcitem{intersect}{list}
+%.br
+Returns the intersection of all rectangles in the list argument.
+It may also be called with a tuple argument or with two or more
+rectangles as arguments.
+Raises
+{\tt rect.error}
+if the list is empty.
+Returns
+{\tt rect.empty}
+if the intersection of the rectangles is empty.
+\funcitem{union}{list}
+%.br
+Returns the smallest rectangle that contains all non-empty rectangles in
+the list argument.
+It may also be called with a tuple argument or with two or more
+rectangles as arguments.
+Returns
+{\tt rect.empty}
+if the list is empty or all its rectangles are empty.
+\funcitem{pointinrect}{point, rect}
+%.br
+Returns true if the point is inside the rectangle.
+By definition, a point
+{\em (h,~v)}
+is inside a rectangle
+{\em (left,~top),}
+{\em (right,~bottom)}
+if
+{\em left~$\leq$~h~$<$~right}
+and
+{\em top~$\leq$~v~$<$~bottom}.
+\funcitem{inset(rect, }{dh, dv)}
+%.br
+Returns a rectangle that lies inside the
+{\tt rect}
+argument by
+{\tt dh}
+pixels horizontally
+and
+{\tt dv}
+pixels
+vertically.
+If
+{\tt dh}
+or
+{\tt dv}
+is negative, the result lies outside
+{\tt rect}.
+\funcitem{rect2geom}{rect}
+%.br
+Converts a rectangle to geometry representation:
+{\em (left,~top),}
+{\em (width,~height)}.
+\funcitem{geom2rect}{geom}
+%.br
+Converts a rectangle given in geometry representation back to the
+standard rectangle representation
+{\em (left,~top),}
+{\em (right,~bottom)}.
+\end{description}
+
+\subsection{Standard Modules {\tt GL} and {\tt DEVICE}}
+
+These modules define the constants used by the Silicon Graphics
+{\em Graphics Library}
+that C programmers find in the header files
+{\tt <gl/gl.h>}
+and
+{\tt <gl/device.h>}.
+Read the module files for details.
+
+\subsection{Standard Module {\tt panel}}
+
+This module should be used instead of the built-in module
+{\tt pnl}
+to interface with the
+{\em Panel Library}.
+
+The module is too large to document here in its entirety.
+One interesting function:
+\begin{description}
+\funcitem{defpanellist}{filename}
+%.br
+Parses a panel description file containing S-expressions written by the
+{\em Panel Editor}
+that accompanies the Panel Library and creates the described panels.
+It returns a list of panel objects.
+\end{description}
+
+{\bf Warning:}
+the {\Python} interpreter will dump core if you don't create a GL window
+before calling
+{\tt panel.mkpanel()}
+or
+{\tt panel.defpanellist()}.
+
+\subsection{Standard Module {\tt panelparser}}
+
+This module defines a self-contained parser for S-expressions as output
+by the Panel Editor (which is written in Scheme so it can't help writing
+S-expressions).
+The relevant function is
+{\tt panelparser.parse\_file(file)}
+which has a file object (not a filename!) as argument and returns a list
+of parsed S-expressions.
+Each S-expression is converted into a {\Python} list, with atoms converted
+to {\Python} strings and sub-expressions (recursively) to {\Python} lists.
+For more details, read the module file.
+
+\section{P.M.}
+
+\begin{verse}
+
+commands
+
+cmp?
+
+*cache?
+
+localtime?
+
+calendar?
+
+\_\_dict?
+
+mac?
+
+\end{verse}