diff options
Diffstat (limited to 'Doc')
59 files changed, 1252 insertions, 520 deletions
diff --git a/Doc/lib/internet.tex b/Doc/lib/internet.tex index 52985dc..b426132 100644 --- a/Doc/lib/internet.tex +++ b/Doc/lib/internet.tex @@ -6,8 +6,8 @@ The modules described in this chapter implement Internet protocols and support for related technology. They are all implemented in Python. -Some of these modules require the presence of the system-dependent -module \refmodule{socket}\refbimodindex{socket}, which is currently only -fully supported on \UNIX{} and Windows NT. Here is an overview: +Most of these modules require the presence of the system-dependent +module \refmodule{socket}\refbimodindex{socket}, which is currently +supported on most popular platforms. Here is an overview: \localmoduletable diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex index 84b2812..0e1a411 100644 --- a/Doc/lib/libarray.tex +++ b/Doc/lib/libarray.tex @@ -76,11 +76,11 @@ numbers are valid as long as the array exists and no length-changing operations are applied to it. \end{methoddesc} -\begin{methoddesc}[array]{byteswap}{x} +\begin{methoddesc}[array]{byteswap}{} ``Byteswap'' all items of the array. This is only supported for -integer values; for other types of values, \exception{RuntimeError} is -raised. It is useful when reading data from a file written on a -machine with a different byte order. +values which are 1, 2, 4, or 8 bytes in size; for other types of +values, \exception{RuntimeError} is raised. It is useful when reading +data from a file written on a machine with a different byte order. \end{methoddesc} \begin{methoddesc}[array]{fromfile}{f, n} @@ -150,7 +150,8 @@ represented as \code{array(\var{typecode}, \var{initializer})}. The string if the \var{typecode} is \code{'c'}, otherwise it is a list of numbers. The string is guaranteed to be able to be converted back to an array with the same type and value using reverse quotes -(\code{``}). Examples: +(\code{``}), so long as the \function{array()} function has been +imported using \samp{from array import array}. Examples: \begin{verbatim} array('l') @@ -163,4 +164,10 @@ array('d', [1.0, 2.0, 3.14]) \begin{seealso} \seemodule{struct}{packing and unpacking of heterogeneous binary data} \seemodule{xdrlib}{packing and unpacking of XDR data} + \seetext{The Numeric Python extension (NumPy) defines another array + type; see \emph{The Numerical Python Manual} for additional + information (available online at + \url{ftp://ftp-icf.llnl.gov/pub/python/numericalpython.pdf}). + Further information about NumPy is available at + \url{http://www.python.org/topics/scicomp/numpy.html}.} \end{seealso} diff --git a/Doc/lib/libasyncore.tex b/Doc/lib/libasyncore.tex index 5a57146..4bcd496 100644 --- a/Doc/lib/libasyncore.tex +++ b/Doc/lib/libasyncore.tex @@ -1,18 +1,16 @@ \section{\module{asyncore} --- - Asyncronous socket handler} + Asynchronous socket handler} \declaremodule{builtin}{asyncore} -\modulesynopsis{A base class for developing asyncronous socket +\modulesynopsis{A base class for developing asynchronous socket handling services.} \moduleauthor{Sam Rushing}{rushing@nightmare.com} \sectionauthor{Christopher Petrilli}{petrilli@amber.org} % Heavily adapted from original documentation by Sam Rushing. -This module provides the basic infrastructure for writing asyncronous +This module provides the basic infrastructure for writing asynchronous socket service clients and servers. -%\subsection{Why Asyncronous?} - There are only two ways to have a program on a single processor do ``more than one thing at a time.'' Multi-threaded programming is the simplest and most popular way to do it, but there is another very diff --git a/Doc/lib/libbase64.tex b/Doc/lib/libbase64.tex index a59332b..bede708 100644 --- a/Doc/lib/libbase64.tex +++ b/Doc/lib/libbase64.tex @@ -10,14 +10,14 @@ This module performs base64 encoding and decoding of arbitrary binary strings into text strings that can be safely emailed or posted. The -encoding scheme is defined in \rfc{1421} (``Privacy Enhancement for -Internet Electronic Mail: Part I: Message Encryption and -Authentication Procedures'', section 4.3.2.4, ``Step 4: Printable -Encoding'') and is used for MIME email and -various other Internet-related applications; it is not the same as the -output produced by the \program{uuencode} program. For example, the -string \code{'www.python.org'} is encoded as the string -\code{'d3d3LnB5dGhvbi5vcmc=\e n'}. +encoding scheme is defined in \rfc{1521} (\emph{MIME +(Multipurpose Internet Mail Extensions) Part One: Mechanisms for +Specifying and Describing the Format of Internet Message Bodies}, +section 5.2, ``Base64 Content-Transfer-Encoding'') and is used for +MIME email and various other Internet-related applications; it is not +the same as the output produced by the \program{uuencode} program. +For example, the string \code{'www.python.org'} is encoded as the +string \code{'d3d3LnB5dGhvbi5vcmc=\e n'}. \begin{funcdesc}{decode}{input, output} @@ -52,4 +52,9 @@ base64 encoded data. \begin{seealso} \seemodule{binascii}{support module containing \ASCII{}-to-binary and binary-to-\ASCII{} conversions} + \seetext{Internet \rfc{1521}, \emph{MIME (Multipurpose Internet + Mail Extensions) Part One: Mechanisms for Specifying and + Describing the Format of Internet Message Bodies}, section + 5.2, ``Base64 Content-Transfer-Encoding,'' provides the + definition of the base64 encoding.} \end{seealso} diff --git a/Doc/lib/libbisect.tex b/Doc/lib/libbisect.tex index 2b3f117..555e3a7 100644 --- a/Doc/lib/libbisect.tex +++ b/Doc/lib/libbisect.tex @@ -1,12 +1,12 @@ -% LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an -% example based on the PyModules FAQ entry by Aaron Watters -% <arw@pythonpros.com>. - \section{\module{bisect} --- Array bisection algorithm} \declaremodule{standard}{bisect} \modulesynopsis{Array bisection algorithms for binary searching.} +\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} +% LaTeX produced by Fred L. Drake, Jr. <fdrake@acm.org>, with an +% example based on the PyModules FAQ entry by Aaron Watters +% <arw@pythonpros.com>. This module provides support for maintaining a list in sorted order diff --git a/Doc/lib/libbsddb.tex b/Doc/lib/libbsddb.tex index cd0dc07..6a27a3b 100644 --- a/Doc/lib/libbsddb.tex +++ b/Doc/lib/libbsddb.tex @@ -7,59 +7,71 @@ \sectionauthor{Skip Montanaro}{skip@mojam.com} -The \module{bsddb} module provides an interface to the Berkeley DB library. -Users can create hash, btree or record based library files using the -appropriate open call. Bsddb objects behave generally like dictionaries. -Keys and values must be strings, however, so to use other objects as keys or -to store other kinds of objects the user must serialize them somehow, -typically using marshal.dumps or pickle.dumps. - -The \module{bsddb} module is only available on \UNIX{} systems, so it is not -built by default in the standard Python distribution. Also, there are two -incompatible versions of the underlying library. Version 1.85 is widely -available, but has some known bugs. Version 2 is not quite as widely used, -but does offer some improvements. The \module{bsddb} module uses the 1.85 -interface. Users wishing to use version 2 of the Berkeley DB library will -have to modify the source for the module to include db_185.h instead of -db.h. +The \module{bsddb} module provides an interface to the Berkeley DB +library. Users can create hash, btree or record based library files +using the appropriate open call. Bsddb objects behave generally like +dictionaries. Keys and values must be strings, however, so to use +other objects as keys or to store other kinds of objects the user must +serialize them somehow, typically using marshal.dumps or pickle.dumps. + +The \module{bsddb} module is only available on \UNIX{} systems, so it +is not built by default in the standard Python distribution. Also, +there are two incompatible versions of the underlying library. +Version 1.85 is widely available, but has some known bugs. Version 2 +is not quite as widely used, but does offer some improvements. The +\module{bsddb} module uses the 1.85 interface. Users wishing to use +version 2 of the Berkeley DB library will have to modify the source +for the module to include \file{db_185.h} instead of +\file{db.h} (\file{db_185.h} contains the version 1.85 compatibility +interface). The \module{bsddb} module defines the following functions that create -objects that access the appropriate type of Berkeley DB file. The first two -arguments of each function are the same. For ease of portability, only the -first two arguments should be used in most instances. +objects that access the appropriate type of Berkeley DB file. The +first two arguments of each function are the same. For ease of +portability, only the first two arguments should be used in most +instances. \begin{funcdesc}{hashopen}{filename\optional{, flag\optional{, -mode\optional{, bsize\optional{, ffactor\optional{, nelem\optional{, -cachesize\optional{, hash\optional{, lorder}}}}}}}}} -Open the hash format file named \var{filename}. The optional \var{flag} -identifies the mode used to open the file. It may be ``r'' (read only), -``w'' (read-write), ``c'' (read-write - create if necessary) or ``n'' -(read-write - truncate to zero length). The other arguments are rarely used -and are just passed to the low-level dbopen function. Consult the -Berkeley DB documentation for their use and interpretation. + mode\optional{, bsize\optional{, + ffactor\optional{, nelem\optional{, + cachesize\optional{, hash\optional{, + lorder}}}}}}}}} +Open the hash format file named \var{filename}. The optional +\var{flag} identifies the mode used to open the file. It may be +\character{r} (read only), \character{w} (read-write), +\character{c} (read-write - create if necessary) or +\character{n} (read-write - truncate to zero length). The other +arguments are rarely used and are just passed to the low-level +\cfunction{dbopen()} function. Consult the Berkeley DB documentation +for their use and interpretation. \end{funcdesc} - \begin{funcdesc}{btopen}{filename\optional{, flag\optional{, mode\optional{, btflags\optional{, cachesize\optional{, maxkeypage\optional{, minkeypage\optional{, psize\optional{, lorder}}}}}}}}} -Open the btree format file named \var{filename}. The optional \var{flag} -identifies the mode used to open the file. It may be ``r'' (read only), -``w'' (read-write), ``c'' (read-write - create if necessary) or ``n'' -(read-write - truncate to zero length). The other arguments are rarely used -and are just passed to the low-level dbopen function. Consult the -Berkeley DB documentation for their use and interpretation. + +Open the btree format file named \var{filename}. The optional +\var{flag} identifies the mode used to open the file. It may be +\character{r} (read only), \character{w} (read-write), +\character{c} (read-write - create if necessary) or +\character{n} (read-write - truncate to zero length). The other +arguments are rarely used and are just passed to the low-level dbopen +function. Consult the Berkeley DB documentation for their use and +interpretation. \end{funcdesc} \begin{funcdesc}{rnopen}{filename\optional{, flag\optional{, mode\optional{, rnflags\optional{, cachesize\optional{, psize\optional{, lorder\optional{, reclen\optional{, bval\optional{, bfname}}}}}}}}}} -Open a DB record format file named \var{filename}. The optional \var{flag} -identifies the mode used to open the file. It may be ``r'' (read only), -``w'' (read-write), ``c'' (read-write - create if necessary) or ``n'' -(read-write - truncate to zero length). The other arguments are rarely used -and are just passed to the low-level dbopen function. Consult the -Berkeley DB documentation for their use and interpretation. + +Open a DB record format file named \var{filename}. The optional +\var{flag} identifies the mode used to open the file. It may be +\character{r} (read only), \character{w} (read-write), +\character{c} (read-write - create if necessary) or +\character{n} (read-write - truncate to zero length). The other +arguments are rarely used and are just passed to the low-level dbopen +function. Consult the Berkeley DB documentation for their use and +interpretation. \end{funcdesc} @@ -86,7 +98,7 @@ list returned is different for different file formats. \end{methoddesc} \begin{methoddesc}{has_key}{key} -Return 1 if the DB file contains the argument as a key. +Return \code{1} if the DB file contains the argument as a key. \end{methoddesc} \begin{methoddesc}{set_location}{key} diff --git a/Doc/lib/libcalendar.tex b/Doc/lib/libcalendar.tex index 59e3443..ef715f5 100644 --- a/Doc/lib/libcalendar.tex +++ b/Doc/lib/libcalendar.tex @@ -1,18 +1,18 @@ -% This section was contributed by Drew Csillag <drew_csillag@geocities.com>. - \section{\module{calendar} --- - Functions that emulate the \UNIX{} \program{cal} program.} -\declaremodule{standard}{calendar} - -\modulesynopsis{Functions that emulate the \UNIX{} \program{cal} -program.} + General calendar-related functions} +\declaremodule{standard}{calendar} +\modulesynopsis{General functions for working with the calendar, + including some emulation of the \UNIX{} \program{cal} + program.} +\sectionauthor{Drew Csillag}{drew_csillag@geocities.com} This module allows you to output calendars like the \UNIX{} -\manpage{cal}{1} program. +\program{cal} program, and provides additional useful functions +related to the calendar. \begin{funcdesc}{isleap}{year} -Returns \code{1} if \var{year} is a leap year. +Returns true if \var{year} is a leap year. \end{funcdesc} \begin{funcdesc}{leapdays}{year1, year2} @@ -48,9 +48,14 @@ Prints the calendar for the year \var{year}. \end{funcdesc} \begin{funcdesc}{timegm}{tuple} -An unrelated but handy function that takes a time tuple such are -returned by the \function{gmtime()} function in the \module{time} +An unrelated but handy function that takes a time tuple such as +returned by the \function{gmtime()} function in the \refmodule{time} module, and returns the corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In fact, -\function{gmtime()} and \function{timegm()} are each others inverse. +\function{time.gmtime()} and \function{timegm()} are each others' inverse. \end{funcdesc} + + +\begin{seealso} + \seemodule{time}{Low-level time related functions.} +\end{seealso} diff --git a/Doc/lib/libcfgparser.tex b/Doc/lib/libcfgparser.tex index fa76b22..50af056 100644 --- a/Doc/lib/libcfgparser.tex +++ b/Doc/lib/libcfgparser.tex @@ -3,6 +3,8 @@ \declaremodule{standard}{ConfigParser} \modulesynopsis{Configuration file parser.} +\moduleauthor{Ken Manheimer}{klm@digicool.com} +\moduleauthor{Barry Warsaw}{bwarsaw@python.org} \sectionauthor{Christopher G. Petrilli}{petrilli@amber.org} This module defines the class \class{ConfigParser}. @@ -16,24 +18,27 @@ programs which can be customized by end users easily. The configuration file consists of sections, lead by a \samp{[section]} header and followed by \samp{name: value} entries, with continuations in the style of \rfc{822}; \samp{name=value} is -also accepted. The optional values can contain format strings which -refer to other values in the same section, or values in a special +also accepted. Note that leading whitespace is removed from values. +The optional values can contain format strings which refer to other +values in the same section, or values in a special \code{DEFAULT} section. Additional defaults can be provided upon -initialization and retrieval. Lines beginning with \character{\#} are -ignored and may be used to provide comments. +initialization and retrieval. Lines beginning with \character{\#} or +\character{;} are ignored and may be used to provide comments. For example: \begin{verbatim} foodir: %(dir)s/whatever +dir=frob \end{verbatim} -would resolve the \samp{\%(dir)s} to the value of dir. All reference -expansions are done late, on demand. +would resolve the \samp{\%(dir)s} to the value of +\samp{dir} (\samp{frob} in this case). All reference expansions are +done on demand. -Intrinsic defaults can be specified by passing them into the -\class{ConfigParser} constructor as a dictionary. Additional defaults -may be passed into the \method{get} method which will override all +Default values can be specified by passing them into the +\class{ConfigParser} constructor as a dictionary. Additional defaults +may be passed into the \method{get()} method which will override all others. \begin{classdesc}{ConfigParser}{\optional{defaults}} @@ -50,7 +55,9 @@ Exception raised when a specified section is not found. \end{excdesc} \begin{excdesc}{DuplicateSectionError} -Exception raised when mutliple sections with the same name are found. +Exception raised when mutliple sections with the same name are found, +or if \method{add_section()} is called with the name of a section that +is already present. \end{excdesc} \begin{excdesc}{NoOptionError} @@ -87,7 +94,14 @@ Return a dictionairy containing the instance-wide defaults. \end{methoddesc} \begin{methoddesc}{sections}{} -Return a list of the sections available. +Return a list of the sections available; \code{DEFAULT} is not +included in the list. +\end{methoddesc} + +\begin{methoddesc}{add_section}{section} +Add a section named \var{section} to the instance. If a section by +the given name already exists, \exception{DuplicateSectionError} is +raised. \end{methoddesc} \begin{methoddesc}{has_section}{section} @@ -123,6 +137,6 @@ A convenience method which coerces the \var{option} in the specified \begin{methoddesc}{getboolean}{section, option} A convenience method which coerces the \var{option} in the specified \var{section} to a boolean value. Note that the only accepted values -for the option are \code{0} and \code{1}, any others will raise +for the option are \samp{0} and \samp{1}, any others will raise \exception{ValueError}. \end{methoddesc} diff --git a/Doc/lib/libcgi.tex b/Doc/lib/libcgi.tex index 1c565fd..3b755a0 100644 --- a/Doc/lib/libcgi.tex +++ b/Doc/lib/libcgi.tex @@ -195,7 +195,7 @@ Parse a query in the environment or from a file (default Parse a query string given as a string argument (data of type \mimetype{application/x-www-form-urlencoded}). Data are returned as a dictionary. The dictionary keys are the unique query -variable names and the values are lists of vales for each name. +variable names and the values are lists of values for each name. The optional argument \var{keep_blank_values} is a flag indicating whether blank values in diff --git a/Doc/lib/libcgihttp.tex b/Doc/lib/libcgihttp.tex index fd8e09b..a2f453a 100644 --- a/Doc/lib/libcgihttp.tex +++ b/Doc/lib/libcgihttp.tex @@ -3,6 +3,7 @@ \declaremodule{standard}{CGIHTTPServer} + \platform{Unix} \sectionauthor{Moshe Zadka}{mzadka@geocities.com} \modulesynopsis{This module provides a request handler for HTTP servers which can run CGI scripts.} @@ -14,6 +15,9 @@ interface compatible with from \class{SimpleHTTPServer.SimpleHTTPRequestHandler} but can also run CGI scripts. +\strong{Note:} This module is \UNIX{} dependent since it creates the +CGI process using \function{os.fork()} and \function{os.exec()}. + The \module{CGIHTTPServer} module defines the following class: \begin{classdesc}{CGIHTTPRequestHandler}{request, client_address, server} diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex index 877b7a4..4b66394 100644 --- a/Doc/lib/libcode.tex +++ b/Doc/lib/libcode.tex @@ -1,30 +1,173 @@ \section{\module{code} --- - Code object services.} + Interpreter base classes} \declaremodule{standard}{code} -\modulesynopsis{Code object services.} +\modulesynopsis{Base classes for interactive Python interpreters.} -The \code{code} module defines operations pertaining to Python code -objects. It defines the following function: +The \code{code} module provides facilities to implement +read-eval-print loops in Python. Two classes and convenience +functions are included which can be used to build applications which +provide an interactive interpreter prompt. -\begin{funcdesc}{compile_command}{source, \optional{filename\optional{, symbol}}} +\begin{classdesc}{InteractiveInterpreter}{\optional{locals}} +This class deals with parsing and interpreter state (the user's +namespace); it does not deal with input buffering or prompting or +input file naming (the filename is always passed in explicitly). +The optional \var{locals} argument specifies the dictionary in +which code will be executed; it defaults to a newly created +dictionary with key \code{'__name__'} set to \code{'__console__'} +and key \code{'__doc__'} set to \code{None}. +\end{classdesc} + +\begin{classdesc}{InteractiveConsole}{\optional{locals\optional{, filename}}} +Closely emulate the behavior of the interactive Python interpreter. +This class builds on \class{InteractiveInterpreter} and adds +prompting using the familiar \code{sys.ps1} and \code{sys.ps2}, and +input buffering. +\end{classdesc} + + +\begin{funcdesc}{interact}{\optional{banner\optional{, + readfunc\optional{, local}}}} +Convenience function to run a read-eval-print loop. This creates a +new instance of \class{InteractiveConsole} and sets \var{readfunc} +to be used as the \method{raw_input()} method, if provided. If +\var{local} is provided, it is passed to the +\class{InteractiveConsole} constructor for use as the default +namespace for the interpreter loop. The \method{interact()} method +of the instance is then run with \var{banner} passed as the banner +to use, if provided. The console object is discarded after use. +\end{funcdesc} + +\begin{funcdesc}{compile_command}{source\optional{, + filename\optional{, symbol}}} This function is useful for programs that want to emulate Python's interpreter main loop (a.k.a. the read-eval-print loop). The tricky part is to determine when the user has entered an incomplete command -that can be completed by entering more text (as opposed to a complete -command or a syntax error). This function \emph{almost} always makes -the same decision as the real interpreter main loop. - -Arguments: \var{source} is the source string; \var{filename} is the -optional filename from which source was read, defaulting to -\code{'<input>'}; and \var{symbol} is the optional grammar start -symbol, which should be either \code{'single'} (the default) or -\code{'eval'}. - -Return a code object (the same as \code{compile(\var{source}, -\var{filename}, \var{symbol})}) if the command is complete and valid; -return \code{None} if the command is incomplete; raise -\exception{SyntaxError} if the command is a syntax error. +that can be completed by entering more text (as opposed to a +complete command or a syntax error). This function +\emph{almost} always makes the same decision as the real interpreter +main loop. + +\var{source} is the source string; \var{filename} is the optional +filename from which source was read, defaulting to \code{'<input>'}; +and \var{symbol} is the optional grammar start symbol, which should +be either \code{'single'} (the default) or \code{'eval'}. + +Returns a code object (the same as \code{compile(\var{source}, +\var{filename}, \var{symbol})}) if the command is complete and +valid; \code{None} if the command is incomplete; raises +\exception{SyntaxError} if the command is complete and contains a +syntax error, or raises \exception{OverflowError} if the command +includes a numeric constant which exceeds the range of the +appropriate numeric type. \end{funcdesc} + + +\subsection{Interactive Interpreter Objects + \label{interpreter-objects}} + +\begin{methoddesc}{runsource}{source\optional{, filename\optional{, symbol}}} +Compile and run some source in the interpreter. +Arguments are the same as for \function{compile_command()}; the +default for \var{filename} is \code{'<input>'}, and for +\var{symbol} is \code{'single'}. One several things can happen: + +\begin{itemize} +\item +The input is incorrect; \function{compile_command()} raised an +exception (\exception{SyntaxError} or \exception{OverflowError}). A +syntax traceback will be printed by calling the +\method{showsyntaxerror()} method. \method{runsource()} returns +\code{0}. + +\item +The input is incomplete, and more input is required; +\function{compile_command()} returned \code{None}. +\method{runsource()} returns \code{1}. + +\item +The input is complete; \function{compile_command()} returned a code +object. The code is executed by calling the \method{runcode()} (which +also handles run-time exceptions, except for \exception{SystemExit}). +\method{runsource()} returns \code{0}. +\end{itemize} + +The return value can be used to decide whether to use +\code{sys.ps1} or \code{sys.ps2} to prompt the next line. +\end{methoddesc} + +\begin{methoddesc}{runcode}{code} +Execute a code object. +When an exception occurs, \method{showtraceback()} is called to +display a traceback. All exceptions are caught except +\exception{SystemExit}, which is allowed to propogate. + +A note about \exception{KeyboardInterrupt}: this exception may occur +elsewhere in this code, and may not always be caught. The caller +should be prepared to deal with it. +\end{methoddesc} + +\begin{methoddesc}{showsyntaxerror}{\optional{filename}} +Display the syntax error that just occurred. This does not display +a stack trace because there isn't one for syntax errors. +If \var{filename} is given, it is stuffed into the exception instead +of the default filename provided by Python's parser, because it +always uses \code{'<string>'} when reading from a string. +The output is written by the \method{write()} method. +\end{methoddesc} + +\begin{methoddesc}{showtraceback}{} +Display the exception that just occurred. We remove the first stack +item because it is within the interpreter object implementation. +The output is written by the \method{write()} method. +\end{methoddesc} + +\begin{methoddesc}{write}{data} +Write a string to standard output. Derived classes should override +this to provide the appropriate output handling as needed. +\end{methoddesc} + + +\subsection{Interactive Console Objects + \label{console-objects}} + +The \class{InteractiveConsole} class is a subclass of +\class{InteractiveInterpreter}, and so offers all the methods of the +interpreter objects as well as the following additions. + +\begin{methoddesc}{interact}{\optional{banner}} +Closely emulate the interactive Python console. +The optional banner argument specify the banner to print before the +first interaction; by default it prints a banner similar to the one +printed by the standard Python interpreter, followed by the class +name of the console object in parentheses (so as not to confuse this +with the real interpreter -- since it's so close!). +\end{methoddesc} + +\begin{methoddesc}{push}{line} +Push a line of source text to the interpreter. +The line should not have a trailing newline; it may have internal +newlines. The line is appended to a buffer and the interpreter's +\method{runsource()} method is called with the concatenated contents +of the buffer as source. If this indicates that the command was +executed or invalid, the buffer is reset; otherwise, the command is +incomplete, and the buffer is left as it was after the line was +appended. The return value is \code{1} if more input is required, +\code{0} if the line was dealt with in some way (this is the same as +\method{runsource()}). +\end{methoddesc} + +\begin{methoddesc}{resetbuffer}{} +Remove any unhandled source text from the input buffer. +\end{methoddesc} + +\begin{methoddesc}{raw_input}{\optional{prompt}} +Write a prompt and read a line. The returned line does not include +the trailing newline. When the user enters the \EOF{} key sequence, +\exception{EOFError} is raised. The base implementation uses the +built-in function \function{raw_input()}; a subclass may replace this +with a different implementation. +\end{methoddesc} diff --git a/Doc/lib/libcodeop.tex b/Doc/lib/libcodeop.tex index a0b58a5..cd9cb63 100644 --- a/Doc/lib/libcodeop.tex +++ b/Doc/lib/libcodeop.tex @@ -1,13 +1,14 @@ -% LaTeXed from excellent doc-string. \section{\module{codeop} --- Compile Python code} +% LaTeXed from excellent doc-string. + \declaremodule{standard}{codeop} \sectionauthor{Moshe Zadka}{mzadka@geocities.com} \modulesynopsis{Compile (possibly incomplete) Python code.} The \module{codeop} module provides a function to compile Python code -with hints on whether it certainly complete, possible complete or +with hints on whether it is certainly complete, possibly complete or definitely incomplete. This is used by the \refmodule{code} module and should not normally be used directly. @@ -15,25 +16,22 @@ The \module{codeop} module defines the following function: \begin{funcdesc}{compile_command} {source\optional{, filename\optional{, symbol}}} - -Try to compile \var{source}, which should be a string of Python -code. Return a code object if \var{source} is valid +Tries to compile \var{source}, which should be a string of Python +code and return a code object if \var{source} is valid Python code. In that case, the filename attribute of the code object will be \var{filename}, which defaults to \code{'<input>'}. - -Return \code{None} if \var{source} is \emph{not} valid Python +Returns \code{None} if \var{source} is \emph{not} valid Python code, but is a prefix of valid Python code. -Raise an exception if there is a problem with \var{source}: -\begin{itemize} - \item \exception{SyntaxError} - if there is invalid Python syntax. - \item \exception{OverflowError} - if there is an invalid numeric constant. -\end{itemize} +If there is a problem with \var{source}, an exception will be raised. +\exception{SyntaxError} is raised if there is invalid Python syntax, +and \exception{OverflowError} if there is an invalid numeric +constant. -The \var{symbol} argument means whether to compile it as a statement -(\code{'single'}, the default) or as an expression (\code{'eval'}). +The \var{symbol} argument determines whether \var{source} is compiled +as a statement (\code{'single'}, the default) or as an expression +(\code{'eval'}). Any other value will cause \exception{ValueError} to +be raised. \strong{Caveat:} It is possible (but not likely) that the parser stops parsing diff --git a/Doc/lib/libcompileall.tex b/Doc/lib/libcompileall.tex index 64e8a9e..a731245 100644 --- a/Doc/lib/libcompileall.tex +++ b/Doc/lib/libcompileall.tex @@ -1,13 +1,9 @@ -% Documentation based on module docstrings, by Fred L. Drake, Jr. -% <fdrake@acm.org> - \section{\module{compileall} --- - Byte-compile Python libraries.} + Byte-compile Python libraries} \declaremodule{standard}{compileall} - \modulesynopsis{Tools for byte-compiling all Python source files in a -directory tree.} + directory tree.} This module provides some utility functions to support installing @@ -20,19 +16,24 @@ compile Python sources in directories named on the command line or in \code{sys.path}. -\begin{funcdesc}{compile_dir}{dir\optional{, maxlevels\optional{, ddir}}} +\begin{funcdesc}{compile_dir}{dir\optional{, maxlevels\optional{, + ddir\optional{, force}}}} Recursively descend the directory tree named by \var{dir}, compiling all \file{.py} files along the way. The \var{maxlevels} parameter is used to limit the depth of the recursion; it defaults to \code{10}. If \var{ddir} is given, it is used as the base path from - which the filenames used in error messages will be generated. + which the filenames used in error messages will be generated. If + \var{force} is true, modules are re-compiled even if the timestamps + are up to date. \end{funcdesc} -\begin{funcdesc}{compile_path}{\optional{skip_curdir\optional{, maxlevels}}} +\begin{funcdesc}{compile_path}{\optional{skip_curdir\optional{, + maxlevels\optional{, force}}}} Byte-compile all the \file{.py} files found along \code{sys.path}. - If \var{skip_curdir} is true (the default), the current directory is - not included in the search. The \var{maxlevels} parameter defaults - to \code{0} and is passed to the \function{compile_dir()} function. + If \var{skip_curdir} is true (the default), the current directory is + not included in the search. The \var{maxlevels} and + \var{force} parameters default to \code{0} and are passed to the + \function{compile_dir()} function. \end{funcdesc} diff --git a/Doc/lib/libcrypt.tex b/Doc/lib/libcrypt.tex index f9d1615..e3936b7 100644 --- a/Doc/lib/libcrypt.tex +++ b/Doc/lib/libcrypt.tex @@ -1,29 +1,46 @@ \section{\module{crypt} --- - Function used to check \UNIX{} passwords} + Function to check \UNIX{} passwords} \declaremodule{builtin}{crypt} \platform{Unix} -\modulesynopsis{The \cfunction{crypt()} function used to check \UNIX{} - passwords.} +\modulesynopsis{The \cfunction{crypt()} function used to check + \UNIX{} passwords.} \moduleauthor{Steven D. Majewski}{sdm7g@virginia.edu} \sectionauthor{Steven D. Majewski}{sdm7g@virginia.edu} +\sectionauthor{Peter Funk}{pf@artcom-gmbh.de} -This module implements an interface to the \manpage{crypt}{3} routine, -which is a one-way hash function based upon a modified DES algorithm; -see the \UNIX{} man page for further details. Possible uses include +This module implements an interface to the +\manpage{crypt}{3}\index{crypt(3)} routine, which is a one-way hash +function based upon a modified DES\indexii{cipher}{DES} algorithm; see +the \UNIX{} man page for further details. Possible uses include allowing Python scripts to accept typed passwords from the user, or attempting to crack \UNIX{} passwords with a dictionary. -\index{crypt(3)} \begin{funcdesc}{crypt}{word, salt} -\var{word} will usually be a user's password. \var{salt} is a -2-character string which will be used to select one of 4096 variations -of DES\indexii{cipher}{DES}. The characters in \var{salt} must be -either \character{.}, \character{/}, or an alphanumeric character. -Returns the hashed password as a string, which will be composed of -characters from the same alphabet as the salt. + \var{word} will usually be a user's password as typed at a prompt or + in a graphical interface. \var{salt} is usually a random + two-character string which will be used to perturb the DES algorithm + in one of 4096 ways. The characters in \var{salt} must be in the + set \regexp{[./a-zA-Z0-9]}. Returns the hashed password as a + string, which will be composed of characters from the same alphabet + as the salt (the first two characters represent the salt itself). \end{funcdesc} -The module and documentation were written by Steve Majewski. -\index{Majewski, Steve} + +A simple example illustrating typical use: + +\begin{verbatim} +import crypt, getpass, pwd + +def login(): + username = raw_input('Python login:') + cryptedpasswd = pwd.getpwnam(username)[1] + if cryptedpasswd: + if cryptedpasswd == 'x' or cryptedpasswd == '*': + raise "Sorry, currently no support for shadow passwords" + cleartext = getpass.getpass() + return crypt.crypt(cleartext, cryptedpasswd[:2]) == cryptedpasswd + else: + return 1 +\end{verbatim} diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex index 1c57ee8..81532ce 100644 --- a/Doc/lib/libexcs.tex +++ b/Doc/lib/libexcs.tex @@ -11,18 +11,6 @@ and users are encouraged to do the same. The source code for those exceptions is present in the standard library module \module{exceptions}; this module never needs to be imported explicitly. -For backward compatibility, when Python is invoked with the -\programopt{-X} option, most of the standard exceptions are -strings\footnote{ - For forward-compatibility the new exceptions \exception{Exception}, - \exception{LookupError}, \exception{ArithmeticError}, - \exception{EnvironmentError}, and \exception{StandardError} are - tuples. -}. This option may be used to run code that breaks because of the -different semantics of class based exceptions. The -\programopt{-X} option will become obsolete in future Python versions, -so the recommended solution is to fix the code. - Two distinct string objects with the same value are considered different exceptions. This is done to force programmers to use exception names rather than their string value when specifying exception handlers. @@ -30,29 +18,27 @@ The string value of all built-in exceptions is their name, but this is not a requirement for user-defined exceptions or exceptions defined by library modules. -For class exceptions, in a \keyword{try} statement with an \keyword{except} -clause that mentions a particular class, that clause also handles -any exception classes derived from that class (but not exception -classes from which \emph{it} is derived). Two exception classes -that are not related via subclassing are never equivalent, even if -they have the same name. -\stindex{try} -\stindex{except} +For class exceptions, in a \keyword{try}\stindex{try} statement with +an \keyword{except}\stindex{except} clause that mentions a particular +class, that clause also handles any exception classes derived from +that class (but not exception classes from which \emph{it} is +derived). Two exception classes that are not related via subclassing +are never equivalent, even if they have the same name. The built-in exceptions listed below can be generated by the interpreter or built-in functions. Except where mentioned, they have an ``associated value'' indicating the detailed cause of the error. This may be a string or a tuple containing several items of information (e.g., an error code and a string explaining the code). -The associated value is the second argument to the \keyword{raise} -statement. For string exceptions, the associated value itself will be -stored in the variable named as the second argument of the -\keyword{except} clause (if any). For class exceptions, that variable -receives the exception instance. If the exception class is derived -from the standard root class \exception{Exception}, the associated -value is present as the exception instance's \member{args} attribute, -and possibly on other attributes as well. -\stindex{raise} +The associated value is the second argument to the +\keyword{raise}\stindex{raise} statement. For string exceptions, the +associated value itself will be stored in the variable named as the +second argument of the \keyword{except} clause (if any). For class +exceptions, that variable receives the exception instance. If the +exception class is derived from the standard root class +\exception{Exception}, the associated value is present as the +exception instance's \member{args} attribute, and possibly on other +attributes as well. User code can raise built-in exceptions. This can be used to test an exception handler or to report an error condition ``just like'' the @@ -65,6 +51,7 @@ inappropriate error. The following exceptions are only used as base classes for other exceptions. When string-based standard exceptions are used, they are tuples containing the directly derived classes. +\strong{Note:} These will always be classes in Python 1.6. \begin{excdesc}{Exception} The root class for exceptions. All built-in exceptions are derived @@ -128,8 +115,8 @@ They are class objects, except when the \programopt{-X} option is used to revert back to string-based standard exceptions. \begin{excdesc}{AssertionError} -Raised when an \keyword{assert} statement fails. \stindex{assert} +Raised when an \keyword{assert} statement fails. \end{excdesc} \begin{excdesc}{AttributeError} diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex index 6312222..ea17665 100644 --- a/Doc/lib/libfcntl.tex +++ b/Doc/lib/libfcntl.tex @@ -1,10 +1,10 @@ -% Manual text by Jaap Vermeulen \section{\module{fcntl} --- The \function{fcntl()} and \function{ioctl()} system calls} \declaremodule{builtin}{fcntl} \platform{Unix} \modulesynopsis{The \function{fcntl()} and \function{ioctl()} system calls.} +\sectionauthor{Jaap Vermeulen}{} \indexii{UNIX@\UNIX{}}{file control} \indexii{UNIX@\UNIX{}}{I/O control} diff --git a/Doc/lib/libfileinput.tex b/Doc/lib/libfileinput.tex index 8bc93af..97caaf9 100644 --- a/Doc/lib/libfileinput.tex +++ b/Doc/lib/libfileinput.tex @@ -75,11 +75,13 @@ The following functions use the global state created by \end{funcdesc} \begin{funcdesc}{isfirstline}{} - Return true iff the line just read is the first line of its file. + Returns true the line just read is the first line of its file, + otherwise returns false. \end{funcdesc} \begin{funcdesc}{isstdin}{} - Returns true iff the last line was read from \code{sys.stdin}. + Returns true if the last line was read from \code{sys.stdin}, + otherwise returns false. \end{funcdesc} \begin{funcdesc}{nextfile}{} diff --git a/Doc/lib/libfnmatch.tex b/Doc/lib/libfnmatch.tex index 7d97461..527358b 100644 --- a/Doc/lib/libfnmatch.tex +++ b/Doc/lib/libfnmatch.tex @@ -5,42 +5,45 @@ \modulesynopsis{\UNIX{} shell style filename pattern matching.} +\index{filenames!wildcard expansion} + This module provides support for \UNIX{} shell-style wildcards, which are \emph{not} the same as regular expressions (which are documented in the \refmodule{re}\refstmodindex{re} module). The special characters used in shell-style wildcards are: -\index{filenames!wildcard expansion} -\begin{list}{}{\leftmargin 0.5in \labelwidth 0.45in} -\item[\code{*}] matches everything -\item[\code{?}] matches any single character -\item[\code{[}\var{seq}\code{]}] matches any character in \var{seq} -\item[\code{[!}\var{seq}\code{]}] matches any character not in \var{seq} -\end{list} +\begin{tableii}{c|l}{code}{Pattern}{Meaning} + \lineii{*}{matches everything} + \lineii{?}{matches any single character} + \lineii{[\var{seq}]}{matches any character in \var{seq}} + \lineii{[!\var{seq}]}{matches any character not in \var{seq}} +\end{tableii} Note that the filename separator (\code{'/'} on \UNIX{}) is \emph{not} special to this module. See module \refmodule{glob}\refstmodindex{glob} for pathname expansion -(\refmodule{glob} uses \function{fnmatch()} to match filename -segments). +(\refmodule{glob} uses \function{fnmatch()} to match pathname +segments). Similarly, filenames starting with a period are +not special for this module, and are matched by the \code{*} and +\code{?} patterns. \begin{funcdesc}{fnmatch}{filename, pattern} Test whether the \var{filename} string matches the \var{pattern} string, returning true or false. If the operating system is case-insensitive, then both parameters will be normalized to all -lower- or upper-case before the comparision is performed. If you -require a case-sensitive comparision regardless of whether that's +lower- or upper-case before the comparison is performed. If you +require a case-sensitive comparison regardless of whether that's standard for your operating system, use \function{fnmatchcase()} instead. \end{funcdesc} \begin{funcdesc}{fnmatchcase}{filename, pattern} Test whether \var{filename} matches \var{pattern}, returning true or -false; the comparision is case-sensitive. +false; the comparison is case-sensitive. \end{funcdesc} \begin{seealso} - \seemodule{glob}{Shell-style path expansion} + \seemodule{glob}{\UNIX{} shell-style path expansion.} \end{seealso} diff --git a/Doc/lib/libgetopt.tex b/Doc/lib/libgetopt.tex index 1c17ab5..56a8b3c 100644 --- a/Doc/lib/libgetopt.tex +++ b/Doc/lib/libgetopt.tex @@ -33,9 +33,10 @@ The return value consists of two elements: the first is a 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., \code{'-x'}), and the option -argument as its second element, or an empty string if the option has -no argument. +element, prefixed with a hyphen for short options (e.g., \code{'-x'}) +or two hyphens for long options (e.g., \code{'-}\code{-long-option'}), +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. Long and short options may be mixed. diff --git a/Doc/lib/libgrp.tex b/Doc/lib/libgrp.tex index 10f12e8..2925297 100644 --- a/Doc/lib/libgrp.tex +++ b/Doc/lib/libgrp.tex @@ -11,10 +11,14 @@ It is available on all \UNIX{} versions. Group database entries are reported as 4-tuples containing the following items from the group database (see \code{<grp.h>}), in order: -\code{gr_name}, -\code{gr_passwd}, -\code{gr_gid}, -\code{gr_mem}. + +\begin{tableiii}{r|l|l}{textrm}{Index}{Field}{Meaning} + \lineiii{0}{gr_name}{the name of the group} + \lineiii{1}{gr_passwd}{the (encrypted) group password; often empty} + \lineiii{2}{gr_gid}{the numerical group ID} + \lineiii{3}{gr_mem}{all the group member's user names} +\end{tableiii} + The gid is an integer, name and password are strings, and the member list is a list of strings. (Note that most users are not explicitly listed as members of the @@ -34,3 +38,8 @@ Return the group database entry for the given group name. \begin{funcdesc}{getgrall}{} Return a list of all available group entries, in arbitrary order. \end{funcdesc} + + +\begin{seealso} + \seemodule{pwd}{An interface to the user database, similar to this.} +\end{seealso} diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex index 80bd01e..5725fd3 100644 --- a/Doc/lib/libimaplib.tex +++ b/Doc/lib/libimaplib.tex @@ -1,6 +1,3 @@ -% Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>; -% converted by Fred L. Drake, Jr. <fdrake@acm.org>. - \section{\module{imaplib} --- IMAP4 protocol client} @@ -9,6 +6,9 @@ \moduleauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au} \sectionauthor{Piers Lauder}{piers@staff.cs.usyd.edu.au} +% Based on HTML documentation by Piers Lauder <piers@staff.cs.usyd.edu.au>; +% converted by Fred L. Drake, Jr. <fdrake@acm.org>. + \indexii{IMAP4}{protocol} This module defines a class, \class{IMAP4}, which encapsulates a diff --git a/Doc/lib/libintro.tex b/Doc/lib/libintro.tex index a4bc67e..70c7c70 100644 --- a/Doc/lib/libintro.tex +++ b/Doc/lib/libintro.tex @@ -22,14 +22,15 @@ written in C and built in to the Python interpreter; others are written in Python and imported in source form. Some modules provide interfaces that are highly specific to Python, like printing a stack trace; some provide interfaces that are specific to particular -operating systems, like socket I/O; others provide interfaces that are +operating systems, such as access to specific hardware; others provide +interfaces that are specific to a particular application domain, like the World-Wide Web. Some modules are avaiable in all versions and ports of Python; others are only available when the underlying system supports or requires them; yet others are available only when a particular configuration option was chosen at the time when Python was compiled and installed. -This manual is organized ``from the inside out'': it first describes +This manual is organized ``from the inside out:'' it first describes the built-in data types, then the built-in functions and exceptions, and finally the modules, grouped in chapters of related modules. The ordering of the chapters as well as the ordering of the modules within diff --git a/Doc/lib/liblinecache.tex b/Doc/lib/liblinecache.tex index fb71d7a..1273521 100644 --- a/Doc/lib/liblinecache.tex +++ b/Doc/lib/liblinecache.tex @@ -17,7 +17,9 @@ The \module{linecache} module defines the following functions: \begin{funcdesc}{getline}{filename, lineno} Get line \var{lineno} from file named \var{filename}. This function -will never throw an exception --- it will return \code{''} on errors. +will never throw an exception --- it will return \code{''} on errors +(the terminating newline character will be included for lines that are +found). If a file named \var{filename} is not found, the function will look for it in the module\indexiii{module}{search}{path} search path, @@ -25,9 +27,8 @@ for it in the module\indexiii{module}{search}{path} search path, \end{funcdesc} \begin{funcdesc}{clearcache}{} -Clear the cache. Use this function if you know that you do not need -to read lines from many of files you already read from using this -module. +Clear the cache. Use this function if you no longer need lines from +files previously read using \function{getline()}. \end{funcdesc} \begin{funcdesc}{checkcache}{} diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex index be2a717..f24399e 100644 --- a/Doc/lib/libmarshal.tex +++ b/Doc/lib/libmarshal.tex @@ -62,7 +62,8 @@ The module defines these functions: Write the value on the open file. The value must be a supported type. The file must be an open file object such as \code{sys.stdout} or returned by \function{open()} or - \function{posix.popen()}. + \function{posix.popen()}. It must be opened in binary mode + (\code{'wb'} or \code{'w+b'}). If the value has (or contains an object that has) an unsupported type, a \exception{ValueError} exception is raised --- but garbage data @@ -73,7 +74,8 @@ The module defines these functions: \begin{funcdesc}{load}{file} Read one value from the open file and return it. If no valid value is read, raise \exception{EOFError}, \exception{ValueError} or - \exception{TypeError}. The file must be an open file object. + \exception{TypeError}. The file must be an open file object opened + in binary mode (\code{'rb'} or \code{'r+b'}). \strong{Warning:} If an object containing an unsupported type was marshalled with \function{dump()}, \function{load()} will substitute diff --git a/Doc/lib/libmath.tex b/Doc/lib/libmath.tex index 0a45fb3..af1ac10 100644 --- a/Doc/lib/libmath.tex +++ b/Doc/lib/libmath.tex @@ -5,7 +5,19 @@ \modulesynopsis{Mathematical functions (\function{sin()} etc.).} This module is always available. It provides access to the -mathematical functions defined by the C standard. They are: +mathematical functions defined by the C standard. + +These functions cannot be used with complex numbers; use the functions +of the same name from the \refmodule{cmath} module if you require +support for complex numbers. The distinction between functions which +support complex numbers and those which don't is made since most users +do not want to learn quite as much mathematics as required to +understand complex numbers. Receiving an exception instead of a +complex result allows earlier detection of the unexpected complex +number used as a parameter, so that the programmer can determine how +and why it was generated in the first place. + +The following functions provided by this module: \begin{funcdesc}{acos}{x} Return the arc cosine of \var{x}. diff --git a/Doc/lib/libmhlib.tex b/Doc/lib/libmhlib.tex index 27b71b0..3e70663 100644 --- a/Doc/lib/libmhlib.tex +++ b/Doc/lib/libmhlib.tex @@ -1,9 +1,9 @@ -% LaTeX'ized from the comments in the module by Skip Montanaro -% <skip@mojam.com>. - \section{\module{mhlib} --- Access to MH mailboxes} +% LaTeX'ized from the comments in the module by Skip Montanaro +% <skip@mojam.com>. + \declaremodule{standard}{mhlib} \modulesynopsis{Manipulate MH mailboxes from Python.} diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex index 82b42ac..eb469b1 100644 --- a/Doc/lib/libmimetools.tex +++ b/Doc/lib/libmimetools.tex @@ -2,7 +2,7 @@ Tools for parsing MIME messages} \declaremodule{standard}{mimetools} -\modulesynopsis{Tools for parsing MIME style message bodies.} +\modulesynopsis{Tools for parsing MIME-style message bodies.} This module defines a subclass of the \class{rfc822.Message} class and @@ -38,7 +38,7 @@ Valid values for \var{encoding} are the same as for \method{decode()}. \end{funcdesc} \begin{funcdesc}{copyliteral}{input, output} -Read lines until \EOF{} from open file \var{input} and write them to +Read lines from open file \var{input} until \EOF{} and write them to open file \var{output}. \end{funcdesc} @@ -48,6 +48,12 @@ open file \var{output}. The block size is currently fixed at 8192. \end{funcdesc} +\begin{seealso} + \seemodule{rfc822}{Provides the base class for + \class{mimetools.Message}.} +\end{seealso} + + \subsection{Additional Methods of Message objects} \nodename{mimetools.Message Methods} diff --git a/Doc/lib/libmimetypes.tex b/Doc/lib/libmimetypes.tex index c85eb6f..b0c0bb8 100644 --- a/Doc/lib/libmimetypes.tex +++ b/Doc/lib/libmimetypes.tex @@ -1,7 +1,3 @@ -% This document section was written by Fred L. Drake, Jr. -% <fdrake@acm.org>, based in part on original docstrings in the -% mimetypes module. - \section{\module{mimetypes} --- Map filenames to MIME types} diff --git a/Doc/lib/libmimewriter.tex b/Doc/lib/libmimewriter.tex index ec57584..fbf2490 100644 --- a/Doc/lib/libmimewriter.tex +++ b/Doc/lib/libmimewriter.tex @@ -54,7 +54,7 @@ insert at the start. boundary\optional{, plist\optional{, prefix}}}} Returns a file-like object which can be used to write to the body of the message. Additionally, this method initializes the -multi-part code, where \var{subtype} provides the mutlipart subtype, +multi-part code, where \var{subtype} provides the multipart subtype, \var{boundary} may provide a user-defined boundary specification, and \var{plist} provides optional parameters for the subtype. \var{prefix} functions as in \method{startbody()}. Subparts should be diff --git a/Doc/lib/libnetrc.tex b/Doc/lib/libnetrc.tex index 47b704b..9ad8d70 100644 --- a/Doc/lib/libnetrc.tex +++ b/Doc/lib/libnetrc.tex @@ -1,5 +1,3 @@ -% Module and documentation by Eric S. Raymond, 21 Dec 1998 - \section{\module{netrc} --- netrc file processing} @@ -45,7 +43,7 @@ Dump the class data as a string in the format of a netrc file. Instances of \class{netrc} have public instance variables: \begin{memberdesc}{hosts} -Dictionmary mapping host names to \code{(\var{login}, \var{account}, +Dictionary mapping host names to \code{(\var{login}, \var{account}, \var{password})} tuples. The `default' entry, if any, is represented as a pseudo-host by that name. \end{memberdesc} diff --git a/Doc/lib/libnis.tex b/Doc/lib/libnis.tex index 0181b06..d7060fa 100644 --- a/Doc/lib/libnis.tex +++ b/Doc/lib/libnis.tex @@ -5,7 +5,7 @@ \platform{UNIX} \moduleauthor{Fred Gansevles}{Fred.Gansevles@cs.utwente.nl} \sectionauthor{Moshe Zadka}{mzadka@geocities.com} -\modulesynopsis{Interface to Sun's N.I.S. (a.k.a. Yellow Pages) library.} +\modulesynopsis{Interface to Sun's NIS (a.k.a. Yellow Pages) library.} The \module{nis} module gives a thin wrapper around the NIS library, useful for central administration of several hosts. @@ -23,8 +23,6 @@ Return value is an arbitary array of bytes (i.e., may contain \code{NULL} and other joys). Note that \var{mapname} is first checked if it is an alias to another name. -XXX Describe list of all aliases? Internal for the C code, so - I'm not sure it's a good idea. \end{funcdesc} \begin{funcdesc}{cat}{mapname} diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex index 5239fcb..4001447 100644 --- a/Doc/lib/libos.tex +++ b/Doc/lib/libos.tex @@ -262,7 +262,9 @@ argument to the built-in \function{open()} function. The exit status of the command (encoded in the format specified for \function{wait()}) is available as the return value of the \method{close()} method of the file object, except that when the exit status is zero (termination without -errors), \code{None} is returned. +errors), \code{None} is returned. \strong{Note:} This function +behaves unreliably under Windows due to the native implementation of +\cfunction{popen()}. Availability: \UNIX{}, Windows. \end{funcdesc} @@ -443,12 +445,35 @@ Availability: Macintosh, \UNIX{}, Windows. \subsection{Files and Directories \label{os-file-dir}} \begin{funcdesc}{access}{path, mode} -Check read/write/execute permissions for this process or extance of file -\var{path}. Return \code{1} if access is granted, \code{0} if not. -See the \UNIX{} manual for the semantics. +Check read/write/execute permissions for this process or existence of +file \var{path}. \var{mode} should be \constant{F_OK} to test the +existence of \var{path}, or it can be the inclusive OR of one or more +of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to test +permissions. Return \code{1} if access is allowed, \code{0} if not. +See the \UNIX{} man page \manpage{access}{2} for more information. Availability: \UNIX{}. \end{funcdesc} +\begin{datadesc}{F_OK} + Value to pass as the \var{mode} parameter of \function{access()} to + test the existence of \var{path}. +\end{datadesc} + +\begin{datadesc}{R_OK} + Value to include in the \var{mode} parameter of \function{access()} + to test the readability of \var{path}. +\end{datadesc} + +\begin{datadesc}{W_OK} + Value to include in the \var{mode} parameter of \function{access()} + to test the writability of \var{path}. +\end{datadesc} + +\begin{datadesc}{X_OK} + Value to include in the \var{mode} parameter of \function{access()} + to determine if \var{path} can be executed. +\end{datadesc} + \begin{funcdesc}{chdir}{path} \index{directory!changing} Change the current working directory to \var{path}. @@ -877,9 +902,10 @@ process status is available immediately. Availability: \UNIX{}. \end{datadesc} -The following functions take a process stats code as returned by -\function{waitpid()} as a parameter. They may be used to determine -the disposition of a process. +The following functions take a process status code as returned by +\function{system()}, \function{wait()}, or \function{waitpid()} as a +parameter. They may be used to determine the disposition of a +process. \begin{funcdesc}{WIFSTOPPED}{status} Return true if the process has been stopped. diff --git a/Doc/lib/libparser.tex b/Doc/lib/libparser.tex index db49d89..ce84513 100644 --- a/Doc/lib/libparser.tex +++ b/Doc/lib/libparser.tex @@ -1,5 +1,6 @@ -% libparser.tex -% +\section{\module{parser} --- + Access Python parse trees} + % Copyright 1995 Virginia Polytechnic Institute and State University % and Fred L. Drake, Jr. This copyright notice must be distributed on % all copies, but this document otherwise may be distributed as part @@ -7,10 +8,6 @@ % in any representation, either on paper or electronically. This % restriction does not affect other elements in a distributed package % in any way. -% - -\section{\module{parser} --- - Access Python parse trees} \declaremodule{builtin}{parser} \modulesynopsis{Access parse trees for Python source code.} @@ -166,7 +163,7 @@ extracted with or without line numbering information. \begin{funcdesc}{ast2list}{ast\optional{, line_info}} This function accepts an AST object from the caller in \var{ast} and returns a Python list representing the -equivelent parse tree. The resulting list representation can be used +equivalent parse tree. The resulting list representation can be used for inspection or the creation of a new parse tree in list form. This function does not fail so long as memory is available to build the list representation. If the parse tree will only be used for @@ -185,7 +182,7 @@ omitted if the flag is false or omitted. \begin{funcdesc}{ast2tuple}{ast\optional{, line_info}} This function accepts an AST object from the caller in \var{ast} and returns a Python tuple representing the -equivelent parse tree. Other than returning a tuple instead of a +equivalent parse tree. Other than returning a tuple instead of a list, this function is identical to \function{ast2list()}. If \var{line_info} is true, line number information will be @@ -238,7 +235,7 @@ identical to those created by the built-in \begin{funcdesc}{issuite}{ast} This function mirrors \function{isexpr()} in that it reports whether an AST object represents an \code{'exec'} form, commonly known as a -``suite.'' It is not safe to assume that this function is equivelent +``suite.'' It is not safe to assume that this function is equivalent to \samp{not isexpr(\var{ast})}, as additional syntactic fragments may be supported in the future. \end{funcdesc} @@ -274,9 +271,6 @@ to the descriptions of each function for detailed information. \subsection{AST Objects \label{AST Objects}} -AST objects returned by \function{expr()}, \function{suite()} and -\function{sequence2ast()} have no methods of their own. - Ordered and equality comparisons are supported between AST objects. Pickling of AST objects (using the \refmodule{pickle} module) is also supported. @@ -326,7 +320,7 @@ discovery. While many useful operations may take place between parsing and bytecode generation, the simplest operation is to do nothing. For this purpose, using the \module{parser} module to produce an -intermediate data structure is equivelent to the code +intermediate data structure is equivalent to the code \begin{verbatim} >>> code = compile('a + 5', 'eval') @@ -335,7 +329,7 @@ intermediate data structure is equivelent to the code 10 \end{verbatim} -The equivelent operation using the \module{parser} module is somewhat +The equivalent operation using the \module{parser} module is somewhat longer, and allows the intermediate internal parse tree to be retained as an AST object: @@ -474,7 +468,7 @@ structure. By replacing the actual docstring with something to signify a variable component of the tree, we allow a simple pattern matching approach to -check any given subtree for equivelence to the general pattern for +check any given subtree for equivalence to the general pattern for docstrings. Since the example demonstrates information extraction, we can safely require that the tree be in tuple form rather than list form, allowing a simple variable representation to be diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex index f6374d8..dca7820 100644 --- a/Doc/lib/libpickle.tex +++ b/Doc/lib/libpickle.tex @@ -3,6 +3,7 @@ \declaremodule{standard}{pickle} \modulesynopsis{Convert Python objects to streams of bytes and back.} +% Substantial improvements by Jim Kerr <jbkerr@sr.hp.com>. \index{persistency} \indexii{persistent}{objects} @@ -37,17 +38,29 @@ interface except that \class{Pickler} and \class{Unpickler} are factory functions, not classes (so they cannot be used as base classes for inheritance). -Unlike the built-in module \refmodule{marshal}\refbimodindex{marshal}, -\module{pickle} handles the following correctly: - +Although the \module{pickle} module can use the built-in module +\refmodule{marshal}\refbimodindex{marshal} internally, it differs from +\refmodule{marshal} in the way it handles certain kinds of data: \begin{itemize} -\item recursive objects (objects containing references to themselves) +\item Recursive objects (objects containing references to themselves): + \module{pickle} keeps track of the objects it has already + serialized, so later references to the same object won't be + serialized again. (The \refmodule{marshal} module breaks for + this.) -\item object sharing (references to the same object in different places) +\item Object sharing (references to the same object in different + places): This is similar to self-referencing objects; + \module{pickle} stores the object once, and ensures that all + other references point to the master copy. Shared objects + remain shared, which can be very important for mutable objects. -\item user-defined classes and their instances +\item User-defined classes and their instances: \refmodule{marshal} + does not support these at all, but \module{pickle} can save + and restore class instances transparently. The class definition + must be importable and live in the same module as when the + object was stored. \end{itemize} @@ -177,16 +190,15 @@ x = pickle.load(f) \end{verbatim} The \class{Pickler} class only calls the method \code{f.write()} with a -\withsubitem{(class in pickle)}{ - \ttindex{Unpickler}\ttindex{Pickler}} +\withsubitem{(class in pickle)}{\ttindex{Unpickler}\ttindex{Pickler}} string argument. The \class{Unpickler} calls the methods \code{f.read()} (with an integer argument) and \code{f.readline()} (without argument), both returning a string. It is explicitly allowed to pass non-file objects here, as long as they have the right methods. The constructor for the \class{Pickler} class has an optional second -argument, \var{bin}. If this is present and nonzero, the binary -pickle format is used; if it is zero or absent, the (less efficient, +argument, \var{bin}. If this is present and true, the binary +pickle format is used; if it is absent or false, the (less efficient, but backwards compatible) text pickle format is used. The \class{Unpickler} class does not have an argument to distinguish between binary and text pickle formats; it accepts either format. @@ -203,6 +215,11 @@ The following types can be pickled: \item tuples, lists and dictionaries containing only picklable objects +\item functions defined at the top level of a module (by name + reference, not storage of the implementation) + +\item built-in functions + \item classes that are defined at the top level in a module \item instances of such classes whose \member{__dict__} or @@ -276,11 +293,80 @@ This exception is raised when an unpicklable object is passed to \end{seealso} +\subsection{Example \label{pickle-example}} + +Here's a simple example of how to modify pickling behavior for a +class. The \class{TextReader} class opens a text file, and returns +the line number and line contents each time its \method{readline()} +method is called. If a \class{TextReader} instance is pickled, all +attributes \emph{except} the file object member are saved. When the +instance is unpickled, the file is reopened, and reading resumes from +the last location. The \method{__setstate__()} and +\method{__getstate__()} methods are used to implement this behavior. + +\begin{verbatim} +# illustrate __setstate__ and __getstate__ methods +# used in pickling. + +class TextReader: + "Print and number lines in a text file." + def __init__(self,file): + self.file = file + self.fh = open(file,'r') + self.lineno = 0 + + def readline(self): + self.lineno = self.lineno + 1 + line = self.fh.readline() + if not line: + return None + return "%d: %s" % (self.lineno,line[:-1]) + + # return data representation for pickled object + def __getstate__(self): + odict = self.__dict__ # get attribute dictionary + del odict['fh'] # remove filehandle entry + return odict + + # restore object state from data representation generated + # by __getstate__ + def __setstate__(self,dict): + fh = open(dict['file']) # reopen file + count = dict['lineno'] # read from file... + while count: # until line count is restored + fh.readline() + count = count - 1 + dict['fh'] = fh # create filehandle entry + self.__dict__ = dict # make dict our attribute dictionary +\end{verbatim} + +A sample usage might be something like this: + +\begin{verbatim} +>>> import TextReader +>>> obj = TextReader.TextReader("TextReader.py") +>>> obj.readline() +'1: #!/usr/local/bin/python' +>>> # (more invocations of obj.readline() here) +... obj.readline() +'7: class TextReader:' +>>> import pickle +>>> pickle.dump(obj,open('save.p','w')) + + (start another Python session) + +>>> import pickle +>>> reader = pickle.load(open('save.p')) +>>> reader.readline() +'8: "Print and number lines in a text file."' +\end{verbatim} + + \section{\module{cPickle} --- Alternate implementation of \module{pickle}} \declaremodule{builtin}{cPickle} -\modulesynopsis{Faster version of \module{pickle}, but not subclassable.} +\modulesynopsis{Faster version of \refmodule{pickle}, but not subclassable.} \moduleauthor{Jim Fulton}{jfulton@digicool.com} \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex index fc73a31..4408ef3 100644 --- a/Doc/lib/libpoplib.tex +++ b/Doc/lib/libpoplib.tex @@ -1,14 +1,14 @@ -%By Andrew T. Csillag -%Even though I put it into LaTeX, I cannot really claim that I wrote -%it since I just stole most of it from the poplib.py source code and -%the imaplib ``chapter''. - \section{\module{poplib} --- POP3 protocol client} \declaremodule{standard}{poplib} \modulesynopsis{POP3 protocol client (requires sockets).} +%By Andrew T. Csillag +%Even though I put it into LaTeX, I cannot really claim that I wrote +%it since I just stole most of it from the poplib.py source code and +%the imaplib ``chapter''. + \indexii{POP3}{protocol} This module defines a class, \class{POP3}, which encapsulates a diff --git a/Doc/lib/libposixpath.tex b/Doc/lib/libposixpath.tex index 7ab3713..4981ac0 100644 --- a/Doc/lib/libposixpath.tex +++ b/Doc/lib/libposixpath.tex @@ -127,8 +127,8 @@ slashes. Normalize a pathname. This collapses redundant separators and up-level references, e.g. \code{A//B}, \code{A/./B} and \code{A/foo/../B} all become \code{A/B}. It does not normalize the -case (use \function{normcase()} for that). On Windows, it does -converts forward slashes to backward slashes. +case (use \function{normcase()} for that). On Windows, it converts +forward slashes to backward slashes. \end{funcdesc} \begin{funcdesc}{samefile}{path1, path2} diff --git a/Doc/lib/libpty.tex b/Doc/lib/libpty.tex index 85dd526..5ef3d0f 100644 --- a/Doc/lib/libpty.tex +++ b/Doc/lib/libpty.tex @@ -1,11 +1,7 @@ -%%%% LaTeX'ed and enhanced from comments in file -%%%% Skipped some functions which seemed to be for private -%%%% usage (decision debatable). - \section{\module{pty} --- Pseudo-terminal utilities} \declaremodule{standard}{pty} - \platform{IRIX, Linux} %XXX Is that the right way??? + \platform{IRIX, Linux} \modulesynopsis{Pseudo-Terminal Handling for SGI and Linux.} \moduleauthor{Steen Lumholt}{} \sectionauthor{Moshe Zadka}{mzadka@geocities.com} diff --git a/Doc/lib/libpwd.tex b/Doc/lib/libpwd.tex index fb8d693..784f478 100644 --- a/Doc/lib/libpwd.tex +++ b/Doc/lib/libpwd.tex @@ -5,21 +5,33 @@ \platform{Unix} \modulesynopsis{The password database (\function{getpwnam()} and friends).} -This module provides access to the \UNIX{} password database. -It is available on all \UNIX{} versions. +This module provides access to the \UNIX{} user account and password +database. It is available on all \UNIX{} versions. Password database entries are reported as 7-tuples containing the following items from the password database (see \code{<pwd.h>}), in order: -\code{pw_name}, -\code{pw_passwd}, -\code{pw_uid}, -\code{pw_gid}, -\code{pw_gecos}, -\code{pw_dir}, -\code{pw_shell}. + +\begin{tableiii}{r|l|l}{textrm}{Index}{Field}{Meaning} + \lineiii{0}{\code{pw_name}}{Login name} + \lineiii{1}{\code{pw_passwd}}{Optional encrypted password} + \lineiii{2}{\code{pw_uid}}{Numerical user ID} + \lineiii{3}{\code{pw_gid}}{Numerical group ID} + \lineiii{4}{\code{pw_gecos}}{User name or comment field} + \lineiii{5}{\code{pw_dir}}{User home directory} + \lineiii{6}{\code{pw_shell}}{User command interpreter} +\end{tableiii} + The uid and gid items are integers, all others are strings. \exception{KeyError} is raised if the entry asked for cannot be found. +\strong{Note:} In traditional \UNIX{} the field \code{pw_passwd} usually +contains a password encrypted with a DES derived algorithm (see module +\refmodule{crypt}\refbimodindex{crypt}). However most modern unices +use a so-called \emph{shadow password} system. On those unices the +field \code{pw_passwd} only contains a asterisk (\code{'*'}) or the +letter \character{x} where the encrypted password is stored in a file +\file{/etc/shadow} which is not world readable. + It defines the following items: \begin{funcdesc}{getpwuid}{uid} @@ -33,3 +45,8 @@ Return the password database entry for the given user name. \begin{funcdesc}{getpwall}{} Return a list of all available password database entries, in arbitrary order. \end{funcdesc} + + +\begin{seealso} + \seemodule{grp}{An interface to the group database, similar to this.} +\end{seealso} diff --git a/Doc/lib/libpycompile.tex b/Doc/lib/libpycompile.tex index fad749b..ebbc9b9 100644 --- a/Doc/lib/libpycompile.tex +++ b/Doc/lib/libpycompile.tex @@ -1,9 +1,9 @@ +\section{\module{py_compile} --- + Compile Python source files} + % Documentation based on module docstrings, by Fred L. Drake, Jr. % <fdrake@acm.org> -\section{\module{py_compile} --- - Compile Python source files.} - \declaremodule[pycompile]{standard}{py_compile} \modulesynopsis{Compile Python source files to byte-code files.} diff --git a/Doc/lib/libqueue.tex b/Doc/lib/libqueue.tex index a846036..2bb6a2f 100644 --- a/Doc/lib/libqueue.tex +++ b/Doc/lib/libqueue.tex @@ -32,7 +32,7 @@ empty or locked. \begin{excdesc}{Full} Exception raised when non-blocking \method{put()} (or -\method{get_nowait()}) is called on a \class{Queue} object which is +\method{put_nowait()}) is called on a \class{Queue} object which is full or locked. \end{excdesc} diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex index 1c39c15..e7f0d58 100644 --- a/Doc/lib/librandom.tex +++ b/Doc/lib/librandom.tex @@ -12,22 +12,25 @@ 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 \refmodule{whrandom} module: -\function{choice()}, \function{randint()}, \function{random()} and -\function{uniform()}. See the documentation for the -\refmodule{whrandom} module for these functions. - -The following functions specific to the \module{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. + +The \module{random} module supports the \emph{Random Number +Generator} interface, described in section \ref{rng-objects}. This +interface of the module, as well as the distribution-specific +functions described below, all use the pseudo-random generator +provided by the \refmodule{whrandom} module. + + +The following functions are defined to support specific distributions, +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. These are expected to become part of the Random +Number Generator interface in a future release. \begin{funcdesc}{betavariate}{alpha, beta} Beta distribution. Conditions on the parameters are -\code{\var{alpha} >- 1} and \code{\var{beta} > -1}. -Returned values will range between 0 and 1. +\code{\var{alpha} > -1} and \code{\var{beta} > -1}. +Returned values range between 0 and 1. \end{funcdesc} \begin{funcdesc}{cunifvariate}{mean, arc} @@ -59,8 +62,8 @@ standard deviation. This is slightly faster than the \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. +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} @@ -86,5 +89,40 @@ Weibull distribution. \var{alpha} is the scale parameter and \end{funcdesc} \begin{seealso} - \seemodule{whrandom}{the standard Python random number generator} + \seemodule{whrandom}{The standard Python random number generator.} \end{seealso} + + +\subsection{The Random Number Generator Interface + \label{rng-objects}} + +% XXX This *must* be updated before a future release! + +The \dfn{Random Number Generator} interface describes the methods +which are available for all random number generators. This will be +enhanced in future releases of Python. + +In this release of Python, the modules \refmodule{random}, +\refmodule{whrandom}, and instances of the +\class{whrandom.whrandom} class all conform to this interface. + + +\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} + +\begin{funcdesc}{uniform}{a, b} +Returns a random real number \var{N} such that +\code{\var{a} <= \var{N} < \var{b}}. +\end{funcdesc} diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex index 6fecced..547923d 100644 --- a/Doc/lib/librfc822.tex +++ b/Doc/lib/librfc822.tex @@ -8,10 +8,11 @@ This module defines a class, \class{Message}, which represents a collection of ``email headers'' as defined by the Internet standard \rfc{822}. It is used in various contexts, usually to read such headers from a file. This module also defines a helper class -\class{AddressList} for parsing \rfc{822} addresses. +\class{AddressList} for parsing \rfc{822} addresses. Please refer to +the RFC for information on the specific syntax of \rfc{822} headers. -Note that there's a separate module to read \UNIX{}, MH, and MMDF -style mailbox files: \refmodule{mailbox}\refstmodindex{mailbox}. +The \refmodule{mailbox}\refstmodindex{mailbox} module provides classes +to read mailboxes produced by various end-user mail programs. \begin{classdesc}{Message}{file\optional{, seekable}} A \class{Message} instance is instantiated with an input object as @@ -61,7 +62,8 @@ however, some mailers don't follow that format as specified, so \code{'Mon, 20 Nov 1995 19:12:08 -0500'}. If it succeeds in parsing the date, \function{parsedate()} returns a 9-tuple that can be passed directly to \function{time.mktime()}; otherwise \code{None} will be -returned. +returned. Note that fields 6, 7, and 8 of the result tuple are not +usable. \end{funcdesc} \begin{funcdesc}{parsedate_tz}{date} @@ -74,7 +76,8 @@ offset is the opposite of the sign of the \code{time.timezone} variable for the same timezone; the latter variable follows the \POSIX{} standard while this module follows \rfc{822}.) If the input string has no timezone, the last element of the tuple returned is -\code{None}. +\code{None}. Note that fields 6, 7, and 8 of the result tuple are not +usable. \end{funcdesc} \begin{funcdesc}{mktime_tz}{tuple} @@ -87,6 +90,12 @@ switch dates. Not enough to worry about for common use. \end{funcdesc} +\begin{seealso} + \seemodule{mailbox}{Classes to read various mailbox formats produced + by end-user mail programs.} +\end{seealso} + + \subsection{Message Objects \label{message-objects}} A \class{Message} instance has the following methods: @@ -180,7 +189,8 @@ continuation lines the named headers contain are also parsed. \begin{methoddesc}{getdate}{name} Retrieve a header using \method{getheader()} and parse it into a 9-tuple -compatible with \function{time.mktime()}. If there is no header matching +compatible with \function{time.mktime()}; note that fields 6, 7, and 8 +are not usable. If there is no header matching \var{name}, or it is unparsable, return \code{None}. Date parsing appears to be a black art, and not all mailers adhere to @@ -193,7 +203,8 @@ function may occasionally yield an incorrect result. Retrieve a header using \method{getheader()} and parse it into a 10-tuple; the first 9 elements will make a tuple compatible with \function{time.mktime()}, and the 10th is a number giving the offset -of the date's timezone from UTC. Similarly to \method{getdate()}, if +of the date's timezone from UTC. Note that fields 6, 7, and 8 +are not usable. Similarly to \method{getdate()}, if there is no header matching \var{name}, or it is unparsable, return \code{None}. \end{methoddesc} diff --git a/Doc/lib/libsched.tex b/Doc/lib/libsched.tex index baa2ffe..21366f5 100644 --- a/Doc/lib/libsched.tex +++ b/Doc/lib/libsched.tex @@ -1,7 +1,8 @@ -% LaTeXed and enhanced from comments in file \section{\module{sched} --- Event scheduler} +% LaTeXed and enhanced from comments in file + \declaremodule{standard}{sched} \sectionauthor{Moshe Zadka}{mzadka@geocities.com} \modulesynopsis{General purpose event scheduler.} @@ -49,7 +50,8 @@ From print_time 930343700.273 \begin{methoddesc}{enterabs}{time, priority, action, argument} Schedule a new event. The \var{time} argument should be a numeric type -compatible to the return value of \var{timefunc}. Events scheduled for +compatible with the return value of the \var{timefunc} function passed +to the constructor. Events scheduled for the same \var{time} will be executed in the order of their \var{priority}. diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex index 23b8b8d..f33dc44 100644 --- a/Doc/lib/libselect.tex +++ b/Doc/lib/libselect.tex @@ -9,7 +9,7 @@ This module provides access to the function \cfunction{select()} available in most operating systems. Note that on Windows, it only works for sockets; on other operating systems, it also works for other file types (in particular, on \UNIX{}, it works on pipes). It cannot -be used or regular files to determine whether a file has grown since +be used on regular files to determine whether a file has grown since it was last read. The module defines the following: diff --git a/Doc/lib/libshlex.tex b/Doc/lib/libshlex.tex index f33fa2a..174a39f 100644 --- a/Doc/lib/libshlex.tex +++ b/Doc/lib/libshlex.tex @@ -1,5 +1,3 @@ -% Module and documentation by Eric S. Raymond, 21 Dec 1998 - \section{\module{shlex} --- Simple lexical analysis} diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex index d366cca..445a417 100644 --- a/Doc/lib/libsmtplib.tex +++ b/Doc/lib/libsmtplib.tex @@ -74,6 +74,17 @@ A nice selection of exceptions is defined as well: \end{excdesc} +\begin{seealso} + \seetext{Internet \rfc{821}, \emph{Simple Mail Transfer Protocol}. + Available online at + \url{http://info.internet.isi.edu/in-notes/rfc/files/rfc821.txt}.} + + \seetext{Internet \rfc{1869}, \emph{SMTP Service Extensions}. + Available online at + \url{http://info.internet.isi.edu/in-notes/rfc/files/rfc1869.txt}.} +\end{seealso} + + \subsection{SMTP Objects \label{SMTP-objects}} An \class{SMTP} instance has the following methods: @@ -160,6 +171,10 @@ need to use different ESMTP options to different recipients you have to use the low-level methods such as \method{mail}, \method{rcpt} and \method{data} to send the message.) +\strong{Note:} The \var{from_addr} and \var{to_addrs} parameters are +used to construct the message envelope used by the transport agents. +The \class{SMTP} does not modify the message headers in any way. + If there has been no previous \samp{EHLO} or \samp{HELO} command this session, this method tries ESMTP \samp{EHLO} first. If the server does ESMTP, message size and each of the specified options will be passed @@ -177,27 +192,25 @@ message sent by the server. This method may raise the following exceptions: -\begin{itemize} +\begin{description} \item[\exception{SMTPRecipientsRefused}] All recipients were refused. Nobody got the mail. The -\var{recipients} attribute of the exception object is a dictionary +\member{recipients} attribute of the exception object is a dictionary with information about the refused recipients (like the one returned when at least one recipient was accepted). \item[\exception{SMTPHeloError}] -The server didn't reply properly to -the helo greeting. +The server didn't reply properly to the \samp{HELO} greeting. \item[\exception{SMTPSenderRefused}] -The server didn't accept the from_addr. +The server didn't accept the \var{from_addr}. \item[\exception{SMTPDataError}] -The server replied with an unexpected -error code (other than a refusal of -a recipient). -\end{itemize} +The server replied with an unexpected error code (other than a refusal +of a recipient). +\end{description} -Unless otherwise noted the connection will be open even after +Unless otherwise noted, the connection will be open even after an exception is raised. \end{methoddesc} @@ -216,33 +229,37 @@ consult the module code. \subsection{SMTP Example \label{SMTP-example}} This example prompts the user for addresses needed in the message -envelop (`To' and `From' addresses), and the message to be +envelope (`To' and `From' addresses), and the message to be delivered. Note that the headers to be included with the message must be included in the message as entered; this example doesn't do any processing of the \rfc{822} headers. In particular, the `To' and `From' addresses must be included in the message headers explicitly. \begin{verbatim} -import rfc822, string, sys import smtplib +import string def prompt(prompt): - sys.stdout.write(prompt + ": ") - return string.strip(sys.stdin.readline()) + return string.strip(raw_input(prompt)) -fromaddr = prompt("From") -toaddrs = string.splitfields(prompt("To"), ',') +fromaddr = prompt("From: ") +toaddrs = string.split(prompt("To: ")) print "Enter message, end with ^D:" -msg = "" + +# Add the From: and To: headers at the start! +msg = ("From: %s\r\nTo: %s\r\n\r\n" + % (fromaddr, string.join(toaddrs, ", "))) while 1: - line = sys.stdin.readline() + line = raw_input() if not line: break msg = msg + line + print "Message length is " + `len(msg)` server = smtplib.SMTP('localhost') server.set_debuglevel(1) +server.connect() server.sendmail(fromaddr, toaddrs, msg) server.quit() \end{verbatim} diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex index 4abe805..bcbb76f 100644 --- a/Doc/lib/libsocket.tex +++ b/Doc/lib/libsocket.tex @@ -6,16 +6,19 @@ This module provides access to the BSD \emph{socket} interface. -It is available on \UNIX{} systems that support this interface. +It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS, +OS/2, and probably additional platforms. For an introduction to socket programming (in C), see the following papers: \citetitle{An Introductory 4.3BSD Interprocess Communication Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD Interprocess Communication Tutorial}, by Samuel J. Leffler et al, both in the \citetitle{\UNIX{} Programmer's Manual, Supplementary Documents 1} -(sections PS1:7 and PS1:8). The \UNIX{} manual pages for the various -socket-related system calls are also a valuable source of information -on the details of socket semantics. +(sections PS1:7 and PS1:8). The platform-specific reference material +for the various socket-related system calls are also a valuable source +of information on the details of socket semantics. For \UNIX, refer +to the manual pages; for Windows, see the WinSock (or Winsock 2) +specification. The Python interface is a straightforward transliteration of the \UNIX{} system call and library interface for sockets to Python's diff --git a/Doc/lib/libstatvfs.tex b/Doc/lib/libstatvfs.tex index e71ad72..ca96212 100644 --- a/Doc/lib/libstatvfs.tex +++ b/Doc/lib/libstatvfs.tex @@ -22,6 +22,10 @@ Preferred file system block size. Fundamental file system block size. \end{datadesc} +\begin{datadesc}{F_BLOCKS} +Total number of blocks in the filesystem. +\end{datadesc} + \begin{datadesc}{F_BFREE} Total number of free blocks. \end{datadesc} @@ -39,7 +43,7 @@ Total number of free file nodes. \end{datadesc} \begin{datadesc}{F_FAVAIL} -Free nodes available to non-superuser. +Free nodes available to non-super user. \end{datadesc} \begin{datadesc}{F_FLAG} diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index 6ae216b..f4c0c8a 100644 --- a/Doc/lib/libstdtypes.tex +++ b/Doc/lib/libstdtypes.tex @@ -30,15 +30,17 @@ The following values are considered false: \item \code{None} \withsubitem{(Built-in object)}{\ttindex{None}} -\item zero of any numeric type, e.g., \code{0}, \code{0L}, \code{0.0}. +\item zero of any numeric type, for example, \code{0}, \code{0L}, + \code{0.0}, \code{0j}. -\item any empty sequence, e.g., \code{''}, \code{()}, \code{[]}. +\item any empty sequence, for example, \code{''}, \code{()}, \code{[]}. -\item any empty mapping, e.g., \code{\{\}}. +\item any empty mapping, for example, \code{\{\}}. \item instances of user-defined classes, if the class defines a \method{__nonzero__()} or \method{__len__()} method, when that - method returns zero. + method returns zero.\footnote{Additional information on these +special methods may be found in the \emph{Python Reference Manual}.} \end{itemize} @@ -77,9 +79,9 @@ Notes: 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. +\samp{not} has a lower priority than non-Boolean operators, so +\code{not \var{a} == \var{b}} is interpreted as \code{not (\var{a} == +\var{b})}, and \code{\var{a} == not \var{b}} is a syntax error. \end{description} @@ -88,10 +90,11 @@ These only evaluate their second argument if needed for their outcome. 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). +Comparisons can be chained arbitrarily; for example, \code{\var{x} < +\var{y} <= \var{z}} is equivalent to \code{\var{x} < \var{y} and +\var{y} <= \var{z}}, except that \var{y} is evaluated only once (but +in both cases \var{z} is not evaluated at all when \code{\var{x} < +\var{y}} is found to be false). \indexii{chaining}{comparisons} This table summarizes the comparison operations: @@ -123,26 +126,33 @@ Notes: \index{ABC language@\ABC{} language} \index{language!ABC@\ABC{}} \indexii{C@\C{}}{language} +\code{!=} is the preferred spelling; \code{<>} is obsolescent. \end{description} Objects of different types, except different numeric types, never compare equal; such objects are ordered consistently but arbitrarily (so that sorting a heterogeneous array yields a consistent result). -Furthermore, some types (e.g., windows) support only a degenerate -notion of comparison where any two objects of that type are unequal. -Again, such objects are ordered arbitrarily but consistently. -\indexii{types}{numeric} +Furthermore, some types (for example, file objects) support only a +degenerate notion of comparison where any two objects of that type are +unequal. Again, such objects are ordered arbitrarily but +consistently. +\indexii{object}{numeric} \indexii{objects}{comparing} -(Implementation note: objects of different types except numbers are -ordered by their type names; objects of the same types that don't -support proper comparison are ordered by their address.) +Instances of a class normally compare as non-equal unless the class +\withsubitem{(instance method)}{\ttindex{__cmp__()}} +defines the \method{__cmp__()} method. Refer to the \emph{Python +Reference Manual} for information on the use of this method to effect +object comparisons. -Two more operations with the same syntactic priority, \samp{in} and -\samp{not in}, are supported only by sequence types (below). -\opindex{in} -\opindex{not in} +\strong{Implementation note:} Objects of different types except +numbers are ordered by their type names; objects of the same types +that don't support proper comparison are ordered by their address. + +Two more operations with the same syntactic priority, +\samp{in}\opindex{in} and \samp{not in}\opindex{not in}, are supported +only by sequence types (below). \subsection{Numeric Types \label{typesnumeric}} @@ -150,9 +160,9 @@ Two more operations with the same syntactic priority, \samp{in} and There are four numeric types: \dfn{plain integers}, \dfn{long integers}, \dfn{floating point numbers}, and \dfn{complex numbers}. Plain integers (also just called \dfn{integers}) -are implemented using \ctype{long} in \C{}, which gives them at least 32 +are implemented using \ctype{long} in C, which gives them at least 32 bits of precision. Long integers have unlimited precision. Floating -point numbers are implemented using \ctype{double} in \C{}. All bets on +point numbers are implemented using \ctype{double} in C. All bets on their precision are off unless you happen to know the machine you are working with. \indexii{numeric}{types} @@ -161,20 +171,20 @@ working with. \indexiii{long}{integer}{type} \indexii{floating point}{type} \indexii{complex number}{type} -\indexii{C@\C{}}{language} +\indexii{C}{language} Complex numbers have a real and imaginary part, which are both -implemented using \ctype{double} in \C{}. To extract these parts from +implemented using \ctype{double} in C. To extract these parts from a complex number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}. Numbers are created by numeric literals or as the result of built-in functions and operators. Unadorned integer literals (including hex -and octal numbers) yield plain integers. Integer literals with an \samp{L} -or \samp{l} suffix yield long integers -(\samp{L} is preferred because \samp{1l} looks too much like eleven!). -Numeric literals containing a decimal point or an exponent sign yield -floating point numbers. Appending \samp{j} or \samp{J} to a numeric -literal yields a complex number. +and octal numbers) yield plain integers. Integer literals with an +\character{L} or \character{l} suffix yield long integers +(\character{L} is preferred because \samp{1l} looks too much like +eleven!). Numeric literals containing a decimal point or an exponent +sign yield floating point numbers. Appending \character{j} or +\character{J} to a numeric literal yields a complex number. \indexii{numeric}{literals} \indexii{integer}{literals} \indexiii{long}{integer}{literals} @@ -236,21 +246,23 @@ Notes: \item[(1)] For (plain or long) integer division, the result is an integer. The result is always rounded towards minus infinity: 1/2 is 0, -(-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. +(-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result +is a long integer if either operand is a long integer, regardless of +the numeric value. \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 \function{floor()} and \function{ceil()} in -module \module{math} for well-defined conversions. +module \refmodule{math}\refbimodindex{math} for well-defined conversions. \withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}} \indexii{numeric}{conversions} -\refbimodindex{math} \indexii{C@\C{}}{language} \item[(3)] -See the section on built-in functions for an exact definition. +See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full +description. \end{description} % XXXJH exceptions: overflow (when? what operations?) zerodivision @@ -302,7 +314,7 @@ division by \code{pow(2, \var{n})} without overflow check. There are three sequence types: strings, lists and tuples. Strings literals are written in single or double quotes: -\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the +\code{'xyzzy'}, \code{"frobozz"}. See chapter 2 of the \citetitle[../ref/ref.html]{Python Reference Manual} for more about string literals. Lists are constructed with square brackets, separating items with commas: \code{[a, b, c]}. Tuples are @@ -332,10 +344,10 @@ and \var{j} are integers: equal to \var{x}, else \code{1}}{} \hline \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{} - \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{(3)} + \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{(1)} \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)} + \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(2)} + \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(2), (3)} \hline \lineiii{len(\var{s})}{length of \var{s}}{} \lineiii{min(\var{s})}{smallest item of \var{s}}{} @@ -356,23 +368,21 @@ equal to \var{x}, else \code{1}}{} Notes: \begin{description} - -\item[(1)] If \var{i} or \var{j} is negative, the index is relative to +\item[(1)] Values of \var{n} less than \code{0} are treated as + \code{0} (which yields an empty sequence of the same type as + \var{s}). + +\item[(2)] If \var{i} or \var{j} is negative, the index is relative to the end of the string, i.e., \code{len(\var{s}) + \var{i}} or \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is still \code{0}. -\item[(2)] The slice of \var{s} from \var{i} to \var{j} is defined as +\item[(3)] The slice of \var{s} from \var{i} to \var{j} is defined as the sequence of items with index \var{k} such that \code{\var{i} <= \var{k} < \var{j}}. If \var{i} or \var{j} is greater than \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted, use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If \var{i} is greater than or equal to \var{j}, the slice is empty. - -\item[(3)] Values of \var{n} less than \code{0} are treated as - \code{0} (which yields an empty sequence of the same type as - \var{s}). - \end{description} @@ -452,24 +462,24 @@ The following operations are defined on mutable sequence types (where \lineiii{del \var{s}[\var{i}:\var{j}]} {same as \code{\var{s}[\var{i}:\var{j}] = []}}{} \lineiii{\var{s}.append(\var{x})} - {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{} + {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(1)} \lineiii{\var{s}.extend(\var{x})} - {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(5)} + {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(2)} \lineiii{\var{s}.count(\var{x})} {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{} \lineiii{\var{s}.index(\var{x})} - {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(1)} + {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(3)} \lineiii{\var{s}.insert(\var{i}, \var{x})} {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]} if \code{\var{i} >= 0}}{} \lineiii{\var{s}.pop(\optional{\var{i}})} {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(4)} \lineiii{\var{s}.remove(\var{x})} - {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(1)} + {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(3)} \lineiii{\var{s}.reverse()} - {reverses the items of \var{s} in place}{(3)} + {reverses the items of \var{s} in place}{(5)} \lineiii{\var{s}.sort(\optional{\var{cmpfunc}})} - {sort the items of \var{s} in place}{(2), (3)} + {sort the items of \var{s} in place}{(5), (6)} \end{tableiii} \indexiv{operations on}{mutable}{sequence}{types} \indexiii{operations on}{sequence}{types} @@ -484,10 +494,29 @@ The following operations are defined on mutable sequence types (where \noindent Notes: \begin{description} -\item[(1)] Raises \exception{ValueError} when \var{x} is not found in +\item[(1)] The C implementation of Python has historically accepted + multiple parameters and implicitly joined them into a tuple; this + will no longer work in Python 1.6. Use of this misfeature has been + deprecated since Python 1.4. + +\item[(2)] Raises an exception when \var{x} is not a list object. The + \method{extend()} method is experimental and not supported by + mutable sequence types other than lists. + +\item[(3)] Raises \exception{ValueError} when \var{x} is not found in \var{s}. -\item[(2)] The \method{sort()} method takes an optional argument +\item[(4)] The \method{pop()} method is experimental and not supported + by other mutable sequence types than lists. The optional argument + \var{i} defaults to \code{-1}, so that by default the last item is + removed and returned. + +\item[(5)] The \method{sort()} and \method{reverse()} methods modify the + list in place for economy of space when sorting or reversing a large + list. They don't return the sorted or reversed list to remind you + of this side effect. + +\item[(6)] The \method{sort()} method takes an optional argument specifying a comparison function of two arguments (list items) which should return \code{-1}, \code{0} or \code{1} depending on whether the first argument is considered smaller than, equal to, or larger @@ -497,24 +526,12 @@ Notes: \method{reverse()} than to use the built-in function \function{sort()} with a comparison function that reverses the ordering of the elements. - -\item[(3)] The \method{sort()} and \method{reverse()} methods modify the - list in place for economy of space when sorting or reversing a large - list. They don't return the sorted or reversed list to remind you - of this side effect. - -\item[(4)] The \method{pop()} method is experimental and not supported - by other mutable sequence types than lists. The optional argument - \var{i} defaults to \code{-1}, so that by default the last item is - removed and returned. - -\item[(5)] Raises an exception when \var{x} is not a list object. The - \method{extend()} method is experimental and not supported by - mutable types other than lists. \end{description} \subsection{Mapping Types \label{typesmapping}} +\indexii{mapping}{types} +\indexii{dictionary}{type} A \dfn{mapping} object maps values of one type (the key type) to arbitrary objects. Mappings are mutable objects. There is currently @@ -527,9 +544,6 @@ comparison: if two numbers compare equal (e.g. \code{1} and \code{1.0}) then they can be used interchangeably to index the same dictionary entry. -\indexii{mapping}{types} -\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 @@ -586,12 +600,17 @@ Notes: \item[(1)] Raises a \exception{KeyError} exception if \var{k} is not in the map. -\item[(2)] Keys and values are listed in random order. +\item[(2)] Keys and values are listed in random order. If +\method{keys()} and \method{values()} are called with no intervening +modifications to the dictionary, the two lists will directly +correspond. This allows the creation of \code{(\var{value}, +\var{key})} pairs using \function{map()}: \samp{pairs = map(None, +\var{a}.values(), \var{a}.keys())}. \item[(3)] \var{b} must be of the same type as \var{a}. \item[(4)] Never raises an exception if \var{k} is not in the map, -instead it returns \var{f}. \var{f} is optional; when \var{f} is not +instead it returns \var{x}. \var{x} is optional; when \var{x} is not provided and \var{k} is not in the map, \code{None} is returned. \end{description} @@ -629,7 +648,7 @@ written as \code{<module 'os' from '/usr/local/lib/python1.5/os.pyc'>}. \subsubsection{Classes and Class Instances \label{typesobjects}} \nodename{Classes and Instances} -See Chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python +See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python Reference Manual} for these. @@ -730,7 +749,7 @@ It is written as \code{Ellipsis}. File objects are implemented using \C{}'s \code{stdio} package and can be created with the built-in function -\function{open()}\bifuncindex{open} described section +\function{open()}\bifuncindex{open} described in section \ref{built-in-funcs}, ``Built-in Functions.'' They are also returned by some other built-in functions and methods, e.g., \function{posix.popen()} and \function{posix.fdopen()} and the @@ -793,7 +812,7 @@ descriptors, e.g. module \module{fcntl} or \function{os.read()} and friends. non-negative, it is a maximum byte count (including the trailing newline) and an incomplete line may be returned. An empty string is returned when \EOF{} is hit - immediately. Note: unlike \code{stdio}'s \cfunction{fgets()}, the returned + immediately. Note: Unlike \code{stdio}'s \cfunction{fgets()}, the returned string contains null characters (\code{'\e 0'}) if they occurred in the input. \end{methoddesc} @@ -823,12 +842,12 @@ descriptors, e.g. module \module{fcntl} or \function{os.read()} and friends. Truncate the file's size. If the optional size argument present, the file is truncated to (at most) that size. The size defaults to the current position. Availability of this function depends on the -operating system version (e.g., not all \UNIX{} versions support this +operating system version (for example, not all \UNIX{} versions support this operation). \end{methoddesc} \begin{methoddesc}[file]{write}{str} -Write a string to the file. There is no return value. Note: due to +Write a string to the file. There is no return value. Note: Due to buffering, the string may not actually show up in the file until the \method{flush()} or \method{close()} method is called. \end{methoddesc} diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex index eef84a4..434b433 100644 --- a/Doc/lib/libstruct.tex +++ b/Doc/lib/libstruct.tex @@ -45,23 +45,35 @@ The module defines the following exception and functions: Format characters have the following meaning; the conversion between C and Python values should be obvious given their types: -\begin{tableiii}{c|l|l}{samp}{Format}{C Type}{Python} - \lineiii{x}{pad byte}{no value} - \lineiii{c}{\ctype{char}}{string of length 1} - \lineiii{b}{\ctype{signed char}}{integer} - \lineiii{B}{\ctype{unsigned char}}{integer} - \lineiii{h}{\ctype{short}}{integer} - \lineiii{H}{\ctype{unsigned short}}{integer} - \lineiii{i}{\ctype{int}}{integer} - \lineiii{I}{\ctype{unsigned int}}{integer} - \lineiii{l}{\ctype{long}}{integer} - \lineiii{L}{\ctype{unsigned long}}{integer} - \lineiii{f}{\ctype{float}}{float} - \lineiii{d}{\ctype{double}}{float} - \lineiii{s}{\ctype{char[]}}{string} - \lineiii{p}{\ctype{char[]}}{string} - \lineiii{P}{\ctype{void *}}{integer} -\end{tableiii} +\begin{tableiv}{c|l|l|c}{samp}{Format}{C Type}{Python}{Notes} + \lineiv{x}{pad byte}{no value}{} + \lineiv{c}{\ctype{char}}{string of length 1}{} + \lineiv{b}{\ctype{signed char}}{integer}{} + \lineiv{B}{\ctype{unsigned char}}{integer}{} + \lineiv{h}{\ctype{short}}{integer}{} + \lineiv{H}{\ctype{unsigned short}}{integer}{} + \lineiv{i}{\ctype{int}}{integer}{} + \lineiv{I}{\ctype{unsigned int}}{long}{(1)} + \lineiv{l}{\ctype{long}}{integer}{} + \lineiv{L}{\ctype{unsigned long}}{long}{} + \lineiv{f}{\ctype{float}}{float}{} + \lineiv{d}{\ctype{double}}{float}{} + \lineiv{s}{\ctype{char[]}}{string}{} + \lineiv{p}{\ctype{char[]}}{string}{} + \lineiv{P}{\ctype{void *}}{integer}{} +\end{tableiv} + +\noindent +Notes: + +\begin{description} +\item[(1)] + The \character{I} conversion code will convert to a Python long if + the C \ctype{int} is the same size as a C \ctype{long}, which is + typical on most modern systems. If a C \ctype{int} is smaller than + a C \ctype{long}, an Python integer will be created instead. +\end{description} + A format character may be preceded by an integral repeat count; e.g.\ the format string \code{'4h'} means exactly the same as diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex index 08f49c7..af2d21f 100644 --- a/Doc/lib/libsys.tex +++ b/Doc/lib/libsys.tex @@ -31,6 +31,11 @@ It is always available. A string containing the copyright pertaining to the Python interpreter. \end{datadesc} +\begin{datadesc}{dllhandle} +Integer specifying the handle of the Python DLL. +Availability: Windows. +\end{datadesc} + \begin{funcdesc}{exc_info}{} This function returns a tuple of three values that give information about the exception that is currently being handled. The information @@ -285,5 +290,26 @@ exception type and value are printed. \end{datadesc} \begin{datadesc}{version} -A string containing the version number of the Python interpreter. +A string containing the version number of the Python interpreter plus +additional information on the build number and compiler used. It has +a value of the form \code{'\var{version} (\#\var{build_number}, +\var{build_date}, \var{build_time}) [\var{compiler}]'}. The first +three characters are used to identify the version in the installation +directories (where appropriate on each platform). An example: + +\begin{verbatim} +>>> import sys +>>> sys.version +'1.5.2 (#0 Apr 13 1999, 10:51:12) [MSC 32 bit (Intel)]' +\end{verbatim} +\end{datadesc} + +\begin{datadesc}{winver} +The version number used to form registry keys on Windows platforms. +This is stored as string resource 1000 in the Python DLL. The value +is normally the first three characters of \constant{version}. It is +provided in the \module{sys} module for informational purposes; +modifying this value has no effect on the registry keys used by +Python. +Availability: Windows. \end{datadesc} diff --git a/Doc/lib/libtelnetlib.tex b/Doc/lib/libtelnetlib.tex index f28833e..de88953 100644 --- a/Doc/lib/libtelnetlib.tex +++ b/Doc/lib/libtelnetlib.tex @@ -1,12 +1,9 @@ -% LaTeX'ized from the comments in the module by Skip Montanaro -% <skip@mojam.com>. - \section{\module{telnetlib} --- Telnet client} \declaremodule{standard}{telnetlib} \modulesynopsis{Telnet client class.} - +\sectionauthor{Skip Montanaro}{skip@mojam.com} The \module{telnetlib} module provides a \class{Telnet} class that implements the Telnet protocol. See \rfc{854} for details about the @@ -149,3 +146,32 @@ If a regular expression ends with a greedy match (e.g. \regexp{.*}) or if more than one expression can match the same input, the results are undeterministic, and may depend on the I/O timing. \end{methoddesc} + + +\subsection{Telnet Example \label{telnet-example}} +\sectionauthor{Peter Funk}{pf@artcom-gmbh.de} + +A simple example illustrating typical use: + +\begin{verbatim} +import getpass +import sys +import telnetlib + +HOST = "localhost" +user = raw_input("Enter your remote account: ") +password = getpass.getpass() + +tn = telnetlib.Telnet(HOST) + +tn.read_until("login: ") +tn.write(user + "\n") +if password: + tn.read_until("Password: ") + tn.write(password + "\n") + +tn.write("ls\n") +tn.write("exit\n") + +print tn.read_all() +\end{verbatim} diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex index 0c28bf2..bca946d 100644 --- a/Doc/lib/libtime.tex +++ b/Doc/lib/libtime.tex @@ -1,12 +1,13 @@ \section{\module{time} --- - Time access and conversions.} -\declaremodule{builtin}{time} + Time access and conversions} +\declaremodule{builtin}{time} \modulesynopsis{Time access and conversions.} This module provides various time-related functions. -It is always available. +It is always available, but not all functions are available +on all platforms. An explanation of some terminology and conventions is in order. @@ -72,17 +73,29 @@ nonzero fraction (\UNIX{} \cfunction{select()} is used to implement this, where available). \item + The time tuple as returned by \function{gmtime()}, \function{localtime()}, and \function{strptime()}, and accepted by \function{asctime()}, \function{mktime()} and \function{strftime()}, -is a tuple of 9 integers: year (e.g.\ 1993), month (1--12), day -(1--31), hour (0--23), minute (0--59), second (0--59), weekday (0--6, -monday is 0), Julian day (1--366) and daylight savings flag (-1, 0 or -1). Note that unlike the C structure, the month value is a range -of 1-12, not 0-11. A year value will be handled as descibed under -``Year 2000 (Y2K) issues'' above. A \code{-1} argument as daylight -savings flag, passed to \function{mktime()} will usually result in the -correct daylight savings state to be filled in. +is a tuple of 9 integers: + +\begin{tableiii}{r|l|l}{textrm}{Index}{Field}{Values} + \lineiii{0}{year}{(e.g.\ 1993)} + \lineiii{1}{month}{range [1,12]} + \lineiii{2}{day}{range [1,31]} + \lineiii{3}{hour}{range [0,23]} + \lineiii{4}{minute}{range [0,59]} + \lineiii{5}{second}{range [0,61]; see \strong{(1)} in \function{strftime()} description} + \lineiii{6}{weekday}{range [0,6], monday is 0} + \lineiii{7}{Julian day}{range [1,366]} + \lineiii{8}{daylight savings flag}{0, 1 or -1; see below} +\end{tableiii} + +Note that unlike the C structure, the month value is a +range of 1-12, not 0-11. A year value will be handled as described +under ``Year 2000 (Y2K) issues'' above. A \code{-1} argument as +daylight savings flag, passed to \function{mktime()} will usually +result in the correct daylight savings state to be filled in. \end{itemize} @@ -168,34 +181,43 @@ They are shown without the optional field width and precision specification, and are replaced by the indicated characters in the \function{strftime()} result: -\begin{tableii}{c|p{24em}}{code}{Directive}{Meaning} - \lineii{\%a}{Locale's abbreviated weekday name.} - \lineii{\%A}{Locale's full weekday name.} - \lineii{\%b}{Locale's abbreviated month name.} - \lineii{\%B}{Locale's full month name.} - \lineii{\%c}{Locale's appropriate date and time representation.} - \lineii{\%d}{Day of the month as a decimal number [01,31].} - \lineii{\%H}{Hour (24-hour clock) as a decimal number [00,23].} - \lineii{\%I}{Hour (12-hour clock) as a decimal number [01,12].} - \lineii{\%j}{Day of the year as a decimal number [001,366].} - \lineii{\%m}{Month as a decimal number [01,12].} - \lineii{\%M}{Minute as a decimal number [00,59].} - \lineii{\%p}{Locale's equivalent of either AM or PM.} - \lineii{\%S}{Second as a decimal number [00,61].} - \lineii{\%U}{Week number of the year (Sunday as the first day of the - week) as a decimal number [00,53]. All days in a new year - preceding the first Sunday are considered to be in week 0.} - \lineii{\%w}{Weekday as a decimal number [0(Sunday),6].} - \lineii{\%W}{Week number of the year (Monday as the first day of the - week) as a decimal number [00,53]. All days in a new year - preceding the first Sunday are considered to be in week 0.} - \lineii{\%x}{Locale's appropriate date representation.} - \lineii{\%X}{Locale's appropriate time representation.} - \lineii{\%y}{Year without century as a decimal number [00,99].} - \lineii{\%Y}{Year with century as a decimal number.} - \lineii{\%Z}{Time zone name (or by no characters if no time zone exists).} - \lineii{\%\%}{\%} -\end{tableii} +\begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes} + \lineiii{\%a}{Locale's abbreviated weekday name.}{} + \lineiii{\%A}{Locale's full weekday name.}{} + \lineiii{\%b}{Locale's abbreviated month name.}{} + \lineiii{\%B}{Locale's full month name.}{} + \lineiii{\%c}{Locale's appropriate date and time representation.}{} + \lineiii{\%d}{Day of the month as a decimal number [01,31].}{} + \lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{} + \lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{} + \lineiii{\%j}{Day of the year as a decimal number [001,366].}{} + \lineiii{\%m}{Month as a decimal number [01,12].}{} + \lineiii{\%M}{Minute as a decimal number [00,59].}{} + \lineiii{\%p}{Locale's equivalent of either AM or PM.}{} + \lineiii{\%S}{Second as a decimal number [00,61].}{(1)} + \lineiii{\%U}{Week number of the year (Sunday as the first day of the + week) as a decimal number [00,53]. All days in a new year + preceding the first Sunday are considered to be in week 0.}{} + \lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{} + \lineiii{\%W}{Week number of the year (Monday as the first day of the + week) as a decimal number [00,53]. All days in a new year + preceding the first Sunday are considered to be in week 0.}{} + \lineiii{\%x}{Locale's appropriate date representation.}{} + \lineiii{\%X}{Locale's appropriate time representation.}{} + \lineiii{\%y}{Year without century as a decimal number [00,99].}{} + \lineiii{\%Y}{Year with century as a decimal number.}{} + \lineiii{\%Z}{Time zone name (or by no characters if no time zone exists).}{} + \lineiii{\%\%}{A literal \character{\%} character.}{} +\end{tableiii} + +\noindent +Notes: + +\begin{description} + \item[(1)] + The range really is \code{0} to \code{61}; this accounts for leap + seconds and the (very rare) double leap seconds. +\end{description} Additional directives may be supported on certain platforms, but only the ones listed here have a meaning standardized by ANSI C. @@ -215,8 +237,9 @@ directives as those used by \function{strftime()}; it defaults to returned by \function{ctime()}. The same platform caveats apply; see the local \UNIX{} documentation for restrictions or additional supported directives. If \var{string} cannot be parsed according to -\var{format}, \exception{ValueError} is raised. This function may not -be defined on all platforms. +\var{format}, \exception{ValueError} is raised. + +Availability: Most modern \UNIX{} systems. \end{funcdesc} \begin{funcdesc}{time}{} @@ -238,3 +261,9 @@ timezone, the second is the name of the local DST timezone. If no DST timezone is defined, the second string should not be used. \end{datadesc} + +\begin{seealso} + \seemodule{locale}{Internationalization services. The locale + settings can affect the return values for some of + the functions in the \module{time} module.} +\end{seealso} diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex index 5f9034c..e48fcaf 100644 --- a/Doc/lib/libtypes.tex +++ b/Doc/lib/libtypes.tex @@ -1,11 +1,10 @@ \section{\module{types} --- - Names for all built-in types.} -\declaremodule{standard}{types} + Names for all built-in types} +\declaremodule{standard}{types} \modulesynopsis{Names for all built-in types.} - This module defines names for all object types that are used by the standard Python interpreter, but not for the types defined by various extension modules. It is safe to use \samp{from types import *} --- @@ -141,3 +140,8 @@ The type of traceback objects such as found in The type of frame objects such as found in \code{tb.tb_frame} if \code{tb} is a traceback object. \end{datadesc} + +\begin{datadesc}{BufferType} +The type of buffer objects created by the +\function{buffer()}\bifuncindex{buffer} function. +\end{datadesc} diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex index 5be93dd..fac635a 100644 --- a/Doc/lib/libundoc.tex +++ b/Doc/lib/libundoc.tex @@ -23,6 +23,9 @@ reference material. \item[\module{Tkdnd}] --- Drag-and-drop support for \module{Tkinter}. +\item[\module{turtle}] +--- Turtle graphics in a Tk window. + \item[\module{test}] --- Regression testing framework. This is used for the Python regression test, but is useful for other Python libraries as well. @@ -35,6 +38,11 @@ This is a package rather than a module. Some of these are very old and/or not very robust; marked with ``hmm.'' \begin{description} +\item[\module{dircmp}] +--- Class to build directory diff tools on (may become a demo or tool). +\deprecated{1.6}{The \refmodule{filecmp} module will replace +\module{dircmp}.} + \item[\module{bdb}] --- A generic Python debugger base class (used by pdb) @@ -72,7 +80,7 @@ document these. --- Platform-independent API for playing audio data \item[\module{sunaudio}] ---- interpret sun audio headers (may become obsolete or a tool/demo) +--- Interpret Sun audio headers (may become obsolete or a tool/demo) \item[\module{toaiff}] --- Convert "arbitrary" sound files to AIFF files; should probably @@ -80,14 +88,23 @@ become a tool or demo. Requires the external program \program{sox}. \end{description} -\section{Obsolete} +\section{Obsolete \label{obsolete-modules}} + +These modules are not normally available for import; additional work +must be done to make them available. + +Those which are written in Python will be installed into the directory +\file{lib-old/} installed as part of the standard library. To use +these, the directory must be added to \code{sys.path}, possibly using +\envvar{PYTHONPATH}. + +Obsolete extension modules written in C are not built by default. +Under \UNIX, these must be enabled by uncommenting the appropriate +lines in \file{Modules/Setup} in the build tree and either rebuilding +Python if the modules are statically linked, or building and +installing the shared object if using dynamically-loaded extensions. -These modules are not on the standard module search path; -\indexiii{module}{search}{path} -but are available in the directory \file{lib-old/} installed under -\file{\textrm{\$prefix}/lib/python1.5/}. % $ <-- bow to font lock -To use any of these modules, add that directory to \code{sys.path}, -possibly using \envvar{PYTHONPATH}. +% XXX need Windows instructions! \begin{description} \item[\module{addpack}] diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex index 73898f5..38ee09e 100644 --- a/Doc/lib/liburllib.tex +++ b/Doc/lib/liburllib.tex @@ -1,8 +1,8 @@ \section{\module{urllib} --- - Open an arbitrary object given by URL.} -\declaremodule{standard}{urllib} + Open an arbitrary resource by URL} -\modulesynopsis{Open an arbitrary object given by URL (requires sockets).} +\declaremodule{standard}{urllib} +\modulesynopsis{Open an arbitrary network resource by URL (requires sockets).} \index{WWW} \index{World-Wide Web} @@ -62,6 +62,37 @@ If the \var{url} uses the \file{http:} scheme identifier, the optional must in standard \file{application/x-www-form-urlencoded} format; see the \function{urlencode()} function below. +The \function{urlopen()} function works transparently with proxies. +In a \UNIX{} or Windows environment, set the \envvar{http_proxy}, +\envvar{ftp_proxy} or \envvar{gopher_proxy} environment variables to a +URL that identifies the proxy server before starting the Python +interpreter. For example (the \character{\%} is the command prompt): + +\begin{verbatim} +% http_proxy="http://www.someproxy.com:3128" +% export http_proxy +% python +... +\end{verbatim} + +In a Macintosh environment, \function{urlopen()} will retrieve proxy +information from Internet\index{Internet Config} Config. + +The \function{urlopen()} function works transparently with proxies. +In a \UNIX{} or Windows environment, set the \envvar{http_proxy}, +\envvar{ftp_proxy} or \envvar{gopher_proxy} environment variables to a +URL that identifies the proxy server before starting the Python +interpreter, e.g.: + +\begin{verbatim} +% http_proxy="http://www.someproxy.com:3128" +% export http_proxy +% python +... +\end{verbatim} + +In a Macintosh environment, \function{urlopen()} will retrieve proxy +information from Internet Config. \end{funcdesc} \begin{funcdesc}{urlretrieve}{url\optional{, filename\optional{, hook}}} @@ -127,6 +158,55 @@ characters, where both \var{key} and \var{value} are quoted using \function{quote_plus()} above. \end{funcdesc} +The public functions \function{urlopen()} and \function{urlretrieve()} +create an instance of the \class{FancyURLopener} class and use it to perform +their requested actions. To override this functionality, programmers can +create a subclass of \class{URLopener} or \class{FancyURLopener}, then +assign that class to the \var{urllib._urlopener} variable before calling the +desired function. For example, applications may want to specify a different +\code{user-agent} header than \class{URLopener} defines. This can be +accomplished with the following code: + +\begin{verbatim} +class AppURLopener(urllib.FancyURLopener): + def __init__(self, *args): + apply(urllib.FancyURLopener.__init__, (self,) + args) + self.version = "App/1.7" + +urllib._urlopener = AppURLopener +\end{verbatim} + +\begin{classdesc}{URLopener}{\optional{proxies\optional{, **x509}}} +Base class for opening and reading URLs. Unless you need to support +opening objects using schemes other than \file{http:}, \file{ftp:}, +\file{gopher:} or \file{file:}, you probably want to use +\class{FancyURLopener}. + +By default, the \class{URLopener} class sends a +\code{user-agent} header of \samp{urllib/\var{VVV}}, where +\var{VVV} is the \module{urllib} version number. Applications can +define their own \code{user-agent} header by subclassing +\class{URLopener} or \class{FancyURLopener} and setting the instance +attribute \var{version} to an appropriate string value before the +\method{open()} method is called. + +Additional keyword parameters, collected in \var{x509}, are used for +authentication with the \file{https:} scheme. The keywords +\var{key_file} and \var{cert_file} are supported; both are needed to +actually retrieve a resource at an \file{https:} URL. +\end{classdesc} + +\begin{classdesc}{FancyURLopener}{...} +\class{FancyURLopener} subclasses \class{URLopener} providing default +handling for the following HTTP response codes: 301, 302 or 401. For +301 and 302 response codes, the \code{location} header is used to +fetch the actual URL. For 401 response codes (authentication +required), basic HTTP authentication is performed. + +The parameters to the constructor are the same as those for +\class{URLopener}. +\end{classdesc} + Restrictions: \begin{itemize} @@ -175,3 +255,60 @@ to parse and unparse URL strings, the recommended interface for URL manipulation is in module \refmodule{urlparse}\refstmodindex{urlparse}. \end{itemize} + + +\subsection{URLopener Objects \label{urlopener-objs}} +\sectionauthor{Skip Montanaro}{skip@mojam.com} + +\class{URLopener} and \class{FancyURLopener} objects have the +following methodsL + +\begin{methoddesc}{open}{fullurl\optional{, data}} +Open \var{fullurl} using the appropriate protocol. This method sets +up cache and proxy information, then calls the appropriate open method with +its input arguments. If the scheme is not recognized, +\method{open_unknown()} is called. The \var{data} argument +has the same meaning as the \var{data} argument of \function{urlopen()}. +\end{methoddesc} + +\begin{methoddesc}{open_unknown}{fullurl\optional{, data}} +Overridable interface to open unknown URL types. +\end{methoddesc} + +\begin{methoddesc}{retrieve}{url\optional{, filename\optional{, reporthook}}} +Retrieves the contents of \var{url} and places it in \var{filename}. The +return value is a tuple consisting of a local filename and either a +\class{mimetools.Message} object containing the response headers (for remote +URLs) or None (for local URLs). The caller must then open and read the +contents of \var{filename}. If \var{filename} is not given and the URL +refers to a local file, the input filename is returned. If the URL is +non-local and \var{filename} is not given, the filename is the output of +\function{tempfile.mktemp()} with a suffix that matches the suffix of the last +path component of the input URL. If \var{reporthook} is given, it must be +a function accepting three numeric parameters. It will be called after each +chunk of data is read from the network. \var{reporthook} is ignored for +local URLs. +\end{methoddesc} + + +\subsection{Examples} +\nodename{Urllib Examples} + +Here is an example session that uses the \samp{GET} method to retrieve +a URL containing parameters: + +\begin{verbatim} +>>> import urllib +>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0}) +>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params) +>>> print f.read() +\end{verbatim} + +The following example uses the \samp{POST} method instead: + +\begin{verbatim} +>>> import urllib +>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0}) +>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query", params) +>>> print f.read() +\end{verbatim} diff --git a/Doc/lib/libwhrandom.tex b/Doc/lib/libwhrandom.tex index b79377d..b745f5b 100644 --- a/Doc/lib/libwhrandom.tex +++ b/Doc/lib/libwhrandom.tex @@ -1,13 +1,27 @@ \section{\module{whrandom} --- - Floating point pseudo-random number generator.} -\declaremodule{standard}{whrandom} + Pseudo-random number generator} +\declaremodule{standard}{whrandom} \modulesynopsis{Floating point pseudo-random number generator.} 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: +class that is also named \class{whrandom}. Instances of the +\class{whrandom} class conform to the Random Number Generator +interface described in section \ref{rng-objects}. They also offer the +following method, specific to the Wichmann-Hill algorithm: + +\begin{methoddesc}[whrandom]{seed}{\optional{x, y, z}} + Initializes the random number generator from the integers \var{x}, + \var{y} and \var{z}. When the module is first imported, the random + number is initialized using values derived from the current time. + If \var{x}, \var{y}, and \var{z} are either omitted or \code{0}, the + seed will be computed from the current system time. If one or two + of the parameters are \code{0}, but not all three, the zero values + are replaced by ones. This causes some apparently different seeds + to be equal, with the corresponding result on the pseudo-random + series produced by the generator. +\end{methoddesc} \begin{funcdesc}{choice}{seq} Chooses a random element from the non-empty sequence \var{seq} and returns it. @@ -31,17 +45,23 @@ number is initialized using values derived from the current time. 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 +When imported, the \module{whrandom} module also creates an instance of +the \class{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} +Note that using separate instances of the generator leads to +independent sequences of pseudo-random numbers. + \begin{seealso} - \seemodule{random}{generators for various random distributions} + \seemodule{random}{Generators for various random distributions and + documentation for the Random Number Generator + interface.} \seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183: An efficient and portable pseudo-random number generator'', \citetitle{Applied Statistics} 31 (1982) 188-190.} diff --git a/Doc/lib/libxmllib.tex b/Doc/lib/libxmllib.tex index c407629..afda815 100644 --- a/Doc/lib/libxmllib.tex +++ b/Doc/lib/libxmllib.tex @@ -98,11 +98,12 @@ passed to \method{handle_xml()} default to \code{None} and the string \code{'no'} respectively. \end{methoddesc} -\begin{methoddesc}{handle_doctype}{tag, data} +\begin{methoddesc}{handle_doctype}{tag, pubid, syslit, data} This method is called when the \samp{<!DOCTYPE...>} tag is processed. -The arguments are the name of the root element and the uninterpreted -contents of the tag, starting after the white space after the name of -the root element. +The arguments are the name of the root element, the Formal Public +Identifier (or \code{None} if not specified), the system identifier, +and the uninterpreted contents of the internal DTD subset as a string +(or \code{None} if not present). \end{methoddesc} \begin{methoddesc}{handle_starttag}{tag, method, attributes} @@ -226,6 +227,12 @@ implementation calls \method{syntax_error()} to signal an error. \begin{seealso} + \seetext{The XML specification, published by the World Wide Web + Consortium (W3C), is available online at + \url{http://www.w3.org/TR/REC-xml}. References to + additional material on XML are available at + \url{http://www.w3.org/XML/}.} + \seetext{The Python XML Topic Guide provides a great deal of information on using XML from Python and links to other sources of information on XML. It's located on the Web at diff --git a/Doc/lib/libzlib.tex b/Doc/lib/libzlib.tex index d31af04..66fac4e 100644 --- a/Doc/lib/libzlib.tex +++ b/Doc/lib/libzlib.tex @@ -1,6 +1,3 @@ -% XXX The module has been extended (by Jeremy and Andrew) but this -% documentation is incorrect in some cases. - \section{\module{zlib} --- Compression compatible with \program{gzip}} @@ -17,10 +14,6 @@ most recent version as of April 1999; use a later version if one is available. There are known incompatibilities between the Python module and earlier versions of the zlib library. -The documentation for this module is woefully out of date. In some -cases, the doc strings have been updated more recently. In other -cases, they are both stale. - The available exception and functions in this module are: \begin{excdesc}{error} @@ -68,12 +61,29 @@ The available exception and functions in this module are: should not be used for authentication or digital signatures. \end{funcdesc} -\begin{funcdesc}{decompress}{string\optional{, wbits\optional{, buffsize}}} +\begin{funcdesc}{decompress}{string\optional{, wbits\optional{, bufsize}}} Decompresses the data in \var{string}, returning a string containing the uncompressed data. The \var{wbits} parameter controls the size of - the window buffer. If \var{buffsize} is given, it is used as the + the window buffer. If \var{bufsize} is given, it is used as the initial size of the output buffer. Raises the \exception{error} exception if any error occurs. + +The absolute value of \var{wbits} is the base two logarithm of the +size of the history buffer (the ``window size'') used when compressing +data. Its absolute value should be between 8 and 15 for the most +recent versions of the zlib library, larger values resulting in better +compression at the expense of greater memory usage. The default value +is 15. When \var{wbits} is negative, the standard +\program{gzip} header is suppressed; this is an undocumented feature +of the zlib library, used for compatibility with \program{unzip}'s +compression file format. + +\var{bufsize} is the initial size of the buffer used to hold +decompressed data. If more space is required, the buffer size will be +increased as needed, so you don't have to get this value exactly +right; tuning it will only save a few calls to \cfunction{malloc()}. The +default size is 16384. + \end{funcdesc} \begin{funcdesc}{decompressobj}{\optional{wbits}} @@ -106,7 +116,20 @@ prevents compressing any more data. After calling action is to delete the object. \end{methoddesc} -Decompression objects support the following methods: +Decompression objects support the following methods, and a single attribute: + +\begin{memberdesc}{unused_data} +A string which contains any unused data from the last string fed to +this decompression object. If the whole string turned out to contain +compressed data, this is \code{""}, the empty string. + +The only way to determine where a string of compressed data ends is by +actually decompressing it. This means that when compressed data is +contained part of a larger file, you can only find the end of it by +reading data and feeding it into a decompression object's +\method{decompress} method until the \member{unused_data} attribute is +no longer the empty string. +\end{memberdesc} \begin{methoddesc}[Decompress]{decompress}{string} Decompress \var{string}, returning a string containing the |