diff options
Diffstat (limited to 'Doc/lib')
307 files changed, 0 insertions, 75014 deletions
diff --git a/Doc/lib/archiving.tex b/Doc/lib/archiving.tex deleted file mode 100644 index 93f5bf7..0000000 --- a/Doc/lib/archiving.tex +++ /dev/null @@ -1,8 +0,0 @@ -\chapter{Data Compression and Archiving} -\label{archiving} - -The modules described in this chapter support data compression -with the zlib, gzip, and bzip2 algorithms, and -the creation of ZIP- and tar-format archives. - -\localmoduletable diff --git a/Doc/lib/asttable.tex b/Doc/lib/asttable.tex deleted file mode 100644 index 326bbbb..0000000 --- a/Doc/lib/asttable.tex +++ /dev/null @@ -1,280 +0,0 @@ -\begin{longtableiii}{lll}{class}{Node type}{Attribute}{Value} - -\lineiii{Add}{\member{left}}{left operand} -\lineiii{}{\member{right}}{right operand} -\hline - -\lineiii{And}{\member{nodes}}{list of operands} -\hline - -\lineiii{AssAttr}{}{\emph{attribute as target of assignment}} -\lineiii{}{\member{expr}}{expression on the left-hand side of the dot} -\lineiii{}{\member{attrname}}{the attribute name, a string} -\lineiii{}{\member{flags}}{XXX} -\hline - -\lineiii{AssList}{\member{nodes}}{list of list elements being assigned to} -\hline - -\lineiii{AssName}{\member{name}}{name being assigned to} -\lineiii{}{\member{flags}}{XXX} -\hline - -\lineiii{AssTuple}{\member{nodes}}{list of tuple elements being assigned to} -\hline - -\lineiii{Assert}{\member{test}}{the expression to be tested} -\lineiii{}{\member{fail}}{the value of the \exception{AssertionError}} -\hline - -\lineiii{Assign}{\member{nodes}}{a list of assignment targets, one per equal sign} -\lineiii{}{\member{expr}}{the value being assigned} -\hline - -\lineiii{AugAssign}{\member{node}}{} -\lineiii{}{\member{op}}{} -\lineiii{}{\member{expr}}{} -\hline - -\lineiii{Bitand}{\member{nodes}}{} -\hline - -\lineiii{Bitor}{\member{nodes}}{} -\hline - -\lineiii{Bitxor}{\member{nodes}}{} -\hline - -\lineiii{Break}{}{} -\hline - -\lineiii{CallFunc}{\member{node}}{expression for the callee} -\lineiii{}{\member{args}}{a list of arguments} -\lineiii{}{\member{star_args}}{the extended *-arg value} -\lineiii{}{\member{dstar_args}}{the extended **-arg value} -\hline - -\lineiii{Class}{\member{name}}{the name of the class, a string} -\lineiii{}{\member{bases}}{a list of base classes} -\lineiii{}{\member{doc}}{doc string, a string or \code{None}} -\lineiii{}{\member{code}}{the body of the class statement} -\hline - -\lineiii{Compare}{\member{expr}}{} -\lineiii{}{\member{ops}}{} -\hline - -\lineiii{Const}{\member{value}}{} -\hline - -\lineiii{Continue}{}{} -\hline - -\lineiii{Decorators}{\member{nodes}}{List of function decorator expressions} -\hline - -\lineiii{Dict}{\member{items}}{} -\hline - -\lineiii{Discard}{\member{expr}}{} -\hline - -\lineiii{Div}{\member{left}}{} -\lineiii{}{\member{right}}{} -\hline - -\lineiii{Ellipsis}{}{} -\hline - -\lineiii{Expression}{\member{node}}{} - -\lineiii{Exec}{\member{expr}}{} -\lineiii{}{\member{locals}}{} -\lineiii{}{\member{globals}}{} -\hline - -\lineiii{FloorDiv}{\member{left}}{} -\lineiii{}{\member{right}}{} -\hline - -\lineiii{For}{\member{assign}}{} -\lineiii{}{\member{list}}{} -\lineiii{}{\member{body}}{} -\lineiii{}{\member{else_}}{} -\hline - -\lineiii{From}{\member{modname}}{} -\lineiii{}{\member{names}}{} -\hline - -\lineiii{Function}{\member{decorators}}{\class{Decorators} or \code{None}} -\lineiii{}{\member{name}}{name used in def, a string} -\lineiii{}{\member{argnames}}{list of argument names, as strings} -\lineiii{}{\member{defaults}}{list of default values} -\lineiii{}{\member{flags}}{xxx} -\lineiii{}{\member{doc}}{doc string, a string or \code{None}} -\lineiii{}{\member{code}}{the body of the function} -\hline - -\lineiii{GenExpr}{\member{code}}{} -\hline - -\lineiii{GenExprFor}{\member{assign}}{} -\lineiii{}{\member{iter}}{} -\lineiii{}{\member{ifs}}{} -\hline - -\lineiii{GenExprIf}{\member{test}}{} -\hline - -\lineiii{GenExprInner}{\member{expr}}{} -\lineiii{}{\member{quals}}{} -\hline - -\lineiii{Getattr}{\member{expr}}{} -\lineiii{}{\member{attrname}}{} -\hline - -\lineiii{Global}{\member{names}}{} -\hline - -\lineiii{If}{\member{tests}}{} -\lineiii{}{\member{else_}}{} -\hline - -\lineiii{Import}{\member{names}}{} -\hline - -\lineiii{Invert}{\member{expr}}{} -\hline - -\lineiii{Keyword}{\member{name}}{} -\lineiii{}{\member{expr}}{} -\hline - -\lineiii{Lambda}{\member{argnames}}{} -\lineiii{}{\member{defaults}}{} -\lineiii{}{\member{flags}}{} -\lineiii{}{\member{code}}{} -\hline - -\lineiii{LeftShift}{\member{left}}{} -\lineiii{}{\member{right}}{} -\hline - -\lineiii{List}{\member{nodes}}{} -\hline - -\lineiii{ListComp}{\member{expr}}{} -\lineiii{}{\member{quals}}{} -\hline - -\lineiii{ListCompFor}{\member{assign}}{} -\lineiii{}{\member{list}}{} -\lineiii{}{\member{ifs}}{} -\hline - -\lineiii{ListCompIf}{\member{test}}{} -\hline - -\lineiii{Mod}{\member{left}}{} -\lineiii{}{\member{right}}{} -\hline - -\lineiii{Module}{\member{doc}}{doc string, a string or \code{None}} -\lineiii{}{\member{node}}{body of the module, a \class{Stmt}} -\hline - -\lineiii{Mul}{\member{left}}{} -\lineiii{}{\member{right}}{} -\hline - -\lineiii{Name}{\member{name}}{} -\hline - -\lineiii{Not}{\member{expr}}{} -\hline - -\lineiii{Or}{\member{nodes}}{} -\hline - -\lineiii{Pass}{}{} -\hline - -\lineiii{Power}{\member{left}}{} -\lineiii{}{\member{right}}{} -\hline - -\lineiii{Print}{\member{nodes}}{} -\lineiii{}{\member{dest}}{} -\hline - -\lineiii{Printnl}{\member{nodes}}{} -\lineiii{}{\member{dest}}{} -\hline - -\lineiii{Raise}{\member{expr1}}{} -\lineiii{}{\member{expr2}}{} -\lineiii{}{\member{expr3}}{} -\hline - -\lineiii{Return}{\member{value}}{} -\hline - -\lineiii{RightShift}{\member{left}}{} -\lineiii{}{\member{right}}{} -\hline - -\lineiii{Slice}{\member{expr}}{} -\lineiii{}{\member{flags}}{} -\lineiii{}{\member{lower}}{} -\lineiii{}{\member{upper}}{} -\hline - -\lineiii{Sliceobj}{\member{nodes}}{list of statements} -\hline - -\lineiii{Stmt}{\member{nodes}}{} -\hline - -\lineiii{Sub}{\member{left}}{} -\lineiii{}{\member{right}}{} -\hline - -\lineiii{Subscript}{\member{expr}}{} -\lineiii{}{\member{flags}}{} -\lineiii{}{\member{subs}}{} -\hline - -\lineiii{TryExcept}{\member{body}}{} -\lineiii{}{\member{handlers}}{} -\lineiii{}{\member{else_}}{} -\hline - -\lineiii{TryFinally}{\member{body}}{} -\lineiii{}{\member{final}}{} -\hline - -\lineiii{Tuple}{\member{nodes}}{} -\hline - -\lineiii{UnaryAdd}{\member{expr}}{} -\hline - -\lineiii{UnarySub}{\member{expr}}{} -\hline - -\lineiii{While}{\member{test}}{} -\lineiii{}{\member{body}}{} -\lineiii{}{\member{else_}}{} -\hline - -\lineiii{With}{\member{expr}}{} -\lineiii{}{\member{vars}}{} -\lineiii{}{\member{body}}{} -\hline - -\lineiii{Yield}{\member{value}}{} -\hline - -\end{longtableiii} diff --git a/Doc/lib/caseless.py b/Doc/lib/caseless.py deleted file mode 100755 index cae94be..0000000 --- a/Doc/lib/caseless.py +++ /dev/null @@ -1,60 +0,0 @@ -from optparse import Option, OptionParser, _match_abbrev - -# This case-insensitive option parser relies on having a -# case-insensitive dictionary type available. Here's one -# for Python 2.2. Note that a *real* case-insensitive -# dictionary type would also have to implement __new__(), -# update(), and setdefault() -- but that's not the point -# of this exercise. - -class caseless_dict (dict): - def __setitem__ (self, key, value): - dict.__setitem__(self, key.lower(), value) - - def __getitem__ (self, key): - return dict.__getitem__(self, key.lower()) - - def get (self, key, default=None): - return dict.get(self, key.lower()) - - def has_key (self, key): - return dict.has_key(self, key.lower()) - - -class CaselessOptionParser (OptionParser): - - def _create_option_list (self): - self.option_list = [] - self._short_opt = caseless_dict() - self._long_opt = caseless_dict() - self._long_opts = [] - self.defaults = {} - - def _match_long_opt (self, opt): - return _match_abbrev(opt.lower(), self._long_opt.keys()) - - -if __name__ == "__main__": - from optik.errors import OptionConflictError - - # test 1: no options to start with - parser = CaselessOptionParser() - try: - parser.add_option("-H", dest="blah") - except OptionConflictError: - print "ok: got OptionConflictError for -H" - else: - print "not ok: no conflict between -h and -H" - - parser.add_option("-f", "--file", dest="file") - #print repr(parser.get_option("-f")) - #print repr(parser.get_option("-F")) - #print repr(parser.get_option("--file")) - #print repr(parser.get_option("--fIlE")) - (options, args) = parser.parse_args(["--FiLe", "foo"]) - assert options.file == "foo", options.file - print "ok: case insensitive long options work" - - (options, args) = parser.parse_args(["-F", "bar"]) - assert options.file == "bar", options.file - print "ok: case insensitive short options work" diff --git a/Doc/lib/custominterp.tex b/Doc/lib/custominterp.tex deleted file mode 100644 index 555b888..0000000 --- a/Doc/lib/custominterp.tex +++ /dev/null @@ -1,13 +0,0 @@ -\chapter{Custom Python Interpreters} -\label{custominterp} - -The modules described in this chapter allow writing interfaces similar -to Python's interactive interpreter. If you want a Python interpreter -that supports some special feature in addition to the Python language, -you should look at the \module{code} module. (The \module{codeop} -module is lower-level, used to support compiling a possibly-incomplete -chunk of Python code.) - -The full list of modules described in this chapter is: - -\localmoduletable diff --git a/Doc/lib/datatypes.tex b/Doc/lib/datatypes.tex deleted file mode 100644 index 0fe03c7..0000000 --- a/Doc/lib/datatypes.tex +++ /dev/null @@ -1,10 +0,0 @@ -\chapter{Data Types} -\label{datatypes} - -The modules described in this chapter provide a variety of specialized -data types such as dates and times, fixed-type arrays, heap queues, -synchronized queues, and sets. - -The following modules are documented in this chapter: - -\localmoduletable diff --git a/Doc/lib/development.tex b/Doc/lib/development.tex deleted file mode 100644 index 4b4fadc..0000000 --- a/Doc/lib/development.tex +++ /dev/null @@ -1,13 +0,0 @@ -\chapter{Development Tools} -\label{development} - -The modules described in this chapter help you write software. For -example, the \module{pydoc} module takes a module and generates -documentation based on the module's contents. The \module{doctest} -and \module{unittest} modules contains frameworks for writing unit tests -that automatically exercise code and verify that the expected output -is produced. - -The list of modules described in this chapter is: - -\localmoduletable diff --git a/Doc/lib/distutils.tex b/Doc/lib/distutils.tex deleted file mode 100644 index 3de9dde..0000000 --- a/Doc/lib/distutils.tex +++ /dev/null @@ -1,38 +0,0 @@ -\section{\module{distutils} --- - Building and installing Python modules} - -\declaremodule{standard}{distutils} -\modulesynopsis{Support for building and installing Python modules - into an existing Python installation.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -The \module{distutils} package provides support for building and -installing additional modules into a Python installation. The new -modules may be either 100\%{}-pure Python, or may be extension modules -written in C, or may be collections of Python packages which include -modules coded in both Python and C. - -This package is discussed in two separate documents which are included -in the Python documentation package. To learn about distributing new -modules using the \module{distutils} facilities, read -\citetitle[../dist/dist.html]{Distributing Python Modules}; this -includes documentation needed to extend distutils. To learn -about installing Python modules, whether or not the author made use of -the \module{distutils} package, read -\citetitle[../inst/inst.html]{Installing Python Modules}. - - -\begin{seealso} - \seetitle[../dist/dist.html]{Distributing Python Modules}{The manual - for developers and packagers of Python modules. This - describes how to prepare \module{distutils}-based packages - so that they may be easily installed into an existing - Python installation.} - - \seetitle[../inst/inst.html]{Installing Python Modules}{An - ``administrators'' manual which includes information on - installing modules into an existing Python installation. - You do not need to be a Python programmer to read this - manual.} -\end{seealso} diff --git a/Doc/lib/email-dir.py b/Doc/lib/email-dir.py deleted file mode 100644 index c04f57d..0000000 --- a/Doc/lib/email-dir.py +++ /dev/null @@ -1,115 +0,0 @@ -#!/usr/bin/env python - -"""Send the contents of a directory as a MIME message.""" - -import os -import sys -import smtplib -# For guessing MIME type based on file name extension -import mimetypes - -from optparse import OptionParser - -from email import encoders -from email.message import Message -from email.mime.audio import MIMEAudio -from email.mime.base import MIMEBase -from email.mime.image import MIMEImage -from email.mime.multipart import MIMEMultipart -from email.mime.text import MIMEText - -COMMASPACE = ', ' - - -def main(): - parser = OptionParser(usage="""\ -Send the contents of a directory as a MIME message. - -Usage: %prog [options] - -Unless the -o option is given, the email is sent by forwarding to your local -SMTP server, which then does the normal delivery process. Your local machine -must be running an SMTP server. -""") - parser.add_option('-d', '--directory', - type='string', action='store', - help="""Mail the contents of the specified directory, - otherwise use the current directory. Only the regular - files in the directory are sent, and we don't recurse to - subdirectories.""") - parser.add_option('-o', '--output', - type='string', action='store', metavar='FILE', - help="""Print the composed message to FILE instead of - sending the message to the SMTP server.""") - parser.add_option('-s', '--sender', - type='string', action='store', metavar='SENDER', - help='The value of the From: header (required)') - parser.add_option('-r', '--recipient', - type='string', action='append', metavar='RECIPIENT', - default=[], dest='recipients', - help='A To: header value (at least one required)') - opts, args = parser.parse_args() - if not opts.sender or not opts.recipients: - parser.print_help() - sys.exit(1) - directory = opts.directory - if not directory: - directory = '.' - # Create the enclosing (outer) message - outer = MIMEMultipart() - outer['Subject'] = 'Contents of directory %s' % os.path.abspath(directory) - outer['To'] = COMMASPACE.join(opts.recipients) - outer['From'] = opts.sender - outer.preamble = 'You will not see this in a MIME-aware mail reader.\n' - - for filename in os.listdir(directory): - path = os.path.join(directory, filename) - if not os.path.isfile(path): - continue - # Guess the content type based on the file's extension. Encoding - # will be ignored, although we should check for simple things like - # gzip'd or compressed files. - ctype, encoding = mimetypes.guess_type(path) - if ctype is None or encoding is not None: - # No guess could be made, or the file is encoded (compressed), so - # use a generic bag-of-bits type. - ctype = 'application/octet-stream' - maintype, subtype = ctype.split('/', 1) - if maintype == 'text': - fp = open(path) - # Note: we should handle calculating the charset - msg = MIMEText(fp.read(), _subtype=subtype) - fp.close() - elif maintype == 'image': - fp = open(path, 'rb') - msg = MIMEImage(fp.read(), _subtype=subtype) - fp.close() - elif maintype == 'audio': - fp = open(path, 'rb') - msg = MIMEAudio(fp.read(), _subtype=subtype) - fp.close() - else: - fp = open(path, 'rb') - msg = MIMEBase(maintype, subtype) - msg.set_payload(fp.read()) - fp.close() - # Encode the payload using Base64 - encoders.encode_base64(msg) - # Set the filename parameter - msg.add_header('Content-Disposition', 'attachment', filename=filename) - outer.attach(msg) - # Now send or store the message - composed = outer.as_string() - if opts.output: - fp = open(opts.output, 'w') - fp.write(composed) - fp.close() - else: - s = smtplib.SMTP() - s.connect() - s.sendmail(opts.sender, opts.recipients, composed) - s.close() - - -if __name__ == '__main__': - main() diff --git a/Doc/lib/email-mime.py b/Doc/lib/email-mime.py deleted file mode 100644 index 5097253..0000000 --- a/Doc/lib/email-mime.py +++ /dev/null @@ -1,32 +0,0 @@ -# Import smtplib for the actual sending function -import smtplib - -# Here are the email package modules we'll need -from email.mime.image import MIMEImage -from email.mime.multipart import MIMEMultipart - -COMMASPACE = ', ' - -# Create the container (outer) email message. -msg = MIMEMultipart() -msg['Subject'] = 'Our family reunion' -# me == the sender's email address -# family = the list of all recipients' email addresses -msg['From'] = me -msg['To'] = COMMASPACE.join(family) -msg.preamble = 'Our family reunion' - -# Assume we know that the image files are all in PNG format -for file in pngfiles: - # Open the files in binary mode. Let the MIMEImage class automatically - # guess the specific image type. - fp = open(file, 'rb') - img = MIMEImage(fp.read()) - fp.close() - msg.attach(img) - -# Send the email via our own SMTP server. -s = smtplib.SMTP() -s.connect() -s.sendmail(me, family, msg.as_string()) -s.close() diff --git a/Doc/lib/email-simple.py b/Doc/lib/email-simple.py deleted file mode 100644 index 44152a4..0000000 --- a/Doc/lib/email-simple.py +++ /dev/null @@ -1,25 +0,0 @@ -# Import smtplib for the actual sending function -import smtplib - -# Import the email modules we'll need -from email.mime.text import MIMEText - -# Open a plain text file for reading. For this example, assume that -# the text file contains only ASCII characters. -fp = open(textfile, 'rb') -# Create a text/plain message -msg = MIMEText(fp.read()) -fp.close() - -# me == the sender's email address -# you == the recipient's email address -msg['Subject'] = 'The contents of %s' % textfile -msg['From'] = me -msg['To'] = you - -# Send the message via our own SMTP server, but don't include the -# envelope header. -s = smtplib.SMTP() -s.connect() -s.sendmail(me, [you], msg.as_string()) -s.close() diff --git a/Doc/lib/email-unpack.py b/Doc/lib/email-unpack.py deleted file mode 100644 index e596b98..0000000 --- a/Doc/lib/email-unpack.py +++ /dev/null @@ -1,68 +0,0 @@ -#!/usr/bin/env python - -"""Unpack a MIME message into a directory of files.""" - -import os -import sys -import email -import errno -import mimetypes - -from optparse import OptionParser - - -def main(): - parser = OptionParser(usage="""\ -Unpack a MIME message into a directory of files. - -Usage: %prog [options] msgfile -""") - parser.add_option('-d', '--directory', - type='string', action='store', - help="""Unpack the MIME message into the named - directory, which will be created if it doesn't already - exist.""") - opts, args = parser.parse_args() - if not opts.directory: - parser.print_help() - sys.exit(1) - - try: - msgfile = args[0] - except IndexError: - parser.print_help() - sys.exit(1) - - try: - os.mkdir(opts.directory) - except OSError as e: - # Ignore directory exists error - if e.errno != errno.EEXIST: - raise - - fp = open(msgfile) - msg = email.message_from_file(fp) - fp.close() - - counter = 1 - for part in msg.walk(): - # multipart/* are just containers - if part.get_content_maintype() == 'multipart': - continue - # Applications should really sanitize the given filename so that an - # email message can't be used to overwrite important files - filename = part.get_filename() - if not filename: - ext = mimetypes.guess_extension(part.get_type()) - if not ext: - # Use a generic bag-of-bits extension - ext = '.bin' - filename = 'part-%03d%s' % (counter, ext) - counter += 1 - fp = open(os.path.join(opts.directory, filename), 'wb') - fp.write(part.get_payload(decode=True)) - fp.close() - - -if __name__ == '__main__': - main() diff --git a/Doc/lib/email.tex b/Doc/lib/email.tex deleted file mode 100644 index 3de3df3..0000000 --- a/Doc/lib/email.tex +++ /dev/null @@ -1,402 +0,0 @@ -% Copyright (C) 2001-2007 Python Software Foundation -% Author: barry@python.org (Barry Warsaw) - -\section{\module{email} --- - An email and MIME handling package} - -\declaremodule{standard}{email} -\modulesynopsis{Package supporting the parsing, manipulating, and - generating email messages, including MIME documents.} -\moduleauthor{Barry A. Warsaw}{barry@python.org} -\sectionauthor{Barry A. Warsaw}{barry@python.org} - -\versionadded{2.2} - -The \module{email} package is a library for managing email messages, -including MIME and other \rfc{2822}-based message documents. It -subsumes most of the functionality in several older standard modules -such as \refmodule{rfc822}, \refmodule{mimetools}, -\refmodule{multifile}, and other non-standard packages such as -\module{mimecntl}. It is specifically \emph{not} designed to do any -sending of email messages to SMTP (\rfc{2821}), NNTP, or other servers; those -are functions of modules such as \refmodule{smtplib} and \refmodule{nntplib}. -The \module{email} package attempts to be as RFC-compliant as possible, -supporting in addition to \rfc{2822}, such MIME-related RFCs as -\rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}. - -The primary distinguishing feature of the \module{email} package is -that it splits the parsing and generating of email messages from the -internal \emph{object model} representation of email. Applications -using the \module{email} package deal primarily with objects; you can -add sub-objects to messages, remove sub-objects from messages, -completely re-arrange the contents, etc. There is a separate parser -and a separate generator which handles the transformation from flat -text to the object model, and then back to flat text again. There -are also handy subclasses for some common MIME object types, and a few -miscellaneous utilities that help with such common tasks as extracting -and parsing message field values, creating RFC-compliant dates, etc. - -The following sections describe the functionality of the -\module{email} package. The ordering follows a progression that -should be common in applications: an email message is read as flat -text from a file or other source, the text is parsed to produce the -object structure of the email message, this structure is manipulated, -and finally, the object tree is rendered back into flat text. - -It is perfectly feasible to create the object structure out of whole -cloth --- i.e. completely from scratch. From there, a similar -progression can be taken as above. - -Also included are detailed specifications of all the classes and -modules that the \module{email} package provides, the exception -classes you might encounter while using the \module{email} package, -some auxiliary utilities, and a few examples. For users of the older -\module{mimelib} package, or previous versions of the \module{email} -package, a section on differences and porting is provided. - -\begin{seealso} - \seemodule{smtplib}{SMTP protocol client} - \seemodule{nntplib}{NNTP protocol client} -\end{seealso} - -\subsection{Representing an email message} -\input{emailmessage} - -\subsection{Parsing email messages} -\input{emailparser} - -\subsection{Generating MIME documents} -\input{emailgenerator} - -\subsection{Creating email and MIME objects from scratch} -\input{emailmimebase} - -\subsection{Internationalized headers} -\input{emailheaders} - -\subsection{Representing character sets} -\input{emailcharsets} - -\subsection{Encoders} -\input{emailencoders} - -\subsection{Exception and Defect classes} -\input{emailexc} - -\subsection{Miscellaneous utilities} -\input{emailutil} - -\subsection{Iterators} -\input{emailiter} - -\subsection{Package History\label{email-pkg-history}} - -This table describes the release history of the email package, corresponding -to the version of Python that the package was released with. For purposes of -this document, when you see a note about change or added versions, these refer -to the Python version the change was made in, \emph{not} the email package -version. This table also describes the Python compatibility of each version -of the package. - -\begin{tableiii}{l|l|l}{constant}{email version}{distributed with}{compatible with} -\lineiii{1.x}{Python 2.2.0 to Python 2.2.1}{\emph{no longer supported}} -\lineiii{2.5}{Python 2.2.2+ and Python 2.3}{Python 2.1 to 2.5} -\lineiii{3.0}{Python 2.4}{Python 2.3 to 2.5} -\lineiii{4.0}{Python 2.5}{Python 2.3 to 2.5} -\end{tableiii} - -Here are the major differences between \module{email} version 4 and version 3: - -\begin{itemize} -\item All modules have been renamed according to \pep{8} standards. For - example, the version 3 module \module{email.Message} was renamed to - \module{email.message} in version 4. - -\item A new subpackage \module{email.mime} was added and all the version 3 - \module{email.MIME*} modules were renamed and situated into the - \module{email.mime} subpackage. For example, the version 3 module - \module{email.MIMEText} was renamed to \module{email.mime.text}. - - \emph{Note that the version 3 names will continue to work until Python - 2.6}. - -\item The \module{email.mime.application} module was added, which contains the - \class{MIMEApplication} class. - -\item Methods that were deprecated in version 3 have been removed. These - include \method{Generator.__call__()}, \method{Message.get_type()}, - \method{Message.get_main_type()}, \method{Message.get_subtype()}. - -\item Fixes have been added for \rfc{2231} support which can change some of - the return types for \function{Message.get_param()} and friends. Under - some circumstances, values which used to return a 3-tuple now return - simple strings (specifically, if all extended parameter segments were - unencoded, there is no language and charset designation expected, so the - return type is now a simple string). Also, \%-decoding used to be done - for both encoded and unencoded segments; this decoding is now done only - for encoded segments. -\end{itemize} - -Here are the major differences between \module{email} version 3 and version 2: - -\begin{itemize} -\item The \class{FeedParser} class was introduced, and the \class{Parser} - class was implemented in terms of the \class{FeedParser}. All parsing - therefore is non-strict, and parsing will make a best effort never to - raise an exception. Problems found while parsing messages are stored in - the message's \var{defect} attribute. - -\item All aspects of the API which raised \exception{DeprecationWarning}s in - version 2 have been removed. These include the \var{_encoder} argument - to the \class{MIMEText} constructor, the \method{Message.add_payload()} - method, the \function{Utils.dump_address_pair()} function, and the - functions \function{Utils.decode()} and \function{Utils.encode()}. - -\item New \exception{DeprecationWarning}s have been added to: - \method{Generator.__call__()}, \method{Message.get_type()}, - \method{Message.get_main_type()}, \method{Message.get_subtype()}, and - the \var{strict} argument to the \class{Parser} class. These are - expected to be removed in future versions. - -\item Support for Pythons earlier than 2.3 has been removed. -\end{itemize} - -Here are the differences between \module{email} version 2 and version 1: - -\begin{itemize} -\item The \module{email.Header} and \module{email.Charset} modules - have been added. - -\item The pickle format for \class{Message} instances has changed. - Since this was never (and still isn't) formally defined, this - isn't considered a backward incompatibility. However if your - application pickles and unpickles \class{Message} instances, be - aware that in \module{email} version 2, \class{Message} - instances now have private variables \var{_charset} and - \var{_default_type}. - -\item Several methods in the \class{Message} class have been - deprecated, or their signatures changed. Also, many new methods - have been added. See the documentation for the \class{Message} - class for details. The changes should be completely backward - compatible. - -\item The object structure has changed in the face of - \mimetype{message/rfc822} content types. In \module{email} - version 1, such a type would be represented by a scalar payload, - i.e. the container message's \method{is_multipart()} returned - false, \method{get_payload()} was not a list object, but a single - \class{Message} instance. - - This structure was inconsistent with the rest of the package, so - the object representation for \mimetype{message/rfc822} content - types was changed. In \module{email} version 2, the container - \emph{does} return \code{True} from \method{is_multipart()}, and - \method{get_payload()} returns a list containing a single - \class{Message} item. - - Note that this is one place that backward compatibility could - not be completely maintained. However, if you're already - testing the return type of \method{get_payload()}, you should be - fine. You just need to make sure your code doesn't do a - \method{set_payload()} with a \class{Message} instance on a - container with a content type of \mimetype{message/rfc822}. - -\item The \class{Parser} constructor's \var{strict} argument was - added, and its \method{parse()} and \method{parsestr()} methods - grew a \var{headersonly} argument. The \var{strict} flag was - also added to functions \function{email.message_from_file()} - and \function{email.message_from_string()}. - -\item \method{Generator.__call__()} is deprecated; use - \method{Generator.flatten()} instead. The \class{Generator} - class has also grown the \method{clone()} method. - -\item The \class{DecodedGenerator} class in the - \module{email.Generator} module was added. - -\item The intermediate base classes \class{MIMENonMultipart} and - \class{MIMEMultipart} have been added, and interposed in the - class hierarchy for most of the other MIME-related derived - classes. - -\item The \var{_encoder} argument to the \class{MIMEText} constructor - has been deprecated. Encoding now happens implicitly based - on the \var{_charset} argument. - -\item The following functions in the \module{email.Utils} module have - been deprecated: \function{dump_address_pairs()}, - \function{decode()}, and \function{encode()}. The following - functions have been added to the module: - \function{make_msgid()}, \function{decode_rfc2231()}, - \function{encode_rfc2231()}, and \function{decode_params()}. - -\item The non-public function \function{email.Iterators._structure()} - was added. -\end{itemize} - -\subsection{Differences from \module{mimelib}} - -The \module{email} package was originally prototyped as a separate -library called -\ulink{\texttt{mimelib}}{http://mimelib.sf.net/}. -Changes have been made so that -method names are more consistent, and some methods or modules have -either been added or removed. The semantics of some of the methods -have also changed. For the most part, any functionality available in -\module{mimelib} is still available in the \refmodule{email} package, -albeit often in a different way. Backward compatibility between -the \module{mimelib} package and the \module{email} package was not a -priority. - -Here is a brief description of the differences between the -\module{mimelib} and the \refmodule{email} packages, along with hints on -how to port your applications. - -Of course, the most visible difference between the two packages is -that the package name has been changed to \refmodule{email}. In -addition, the top-level package has the following differences: - -\begin{itemize} -\item \function{messageFromString()} has been renamed to - \function{message_from_string()}. - -\item \function{messageFromFile()} has been renamed to - \function{message_from_file()}. - -\end{itemize} - -The \class{Message} class has the following differences: - -\begin{itemize} -\item The method \method{asString()} was renamed to \method{as_string()}. - -\item The method \method{ismultipart()} was renamed to - \method{is_multipart()}. - -\item The \method{get_payload()} method has grown a \var{decode} - optional argument. - -\item The method \method{getall()} was renamed to \method{get_all()}. - -\item The method \method{addheader()} was renamed to \method{add_header()}. - -\item The method \method{gettype()} was renamed to \method{get_type()}. - -\item The method \method{getmaintype()} was renamed to - \method{get_main_type()}. - -\item The method \method{getsubtype()} was renamed to - \method{get_subtype()}. - -\item The method \method{getparams()} was renamed to - \method{get_params()}. - Also, whereas \method{getparams()} returned a list of strings, - \method{get_params()} returns a list of 2-tuples, effectively - the key/value pairs of the parameters, split on the \character{=} - sign. - -\item The method \method{getparam()} was renamed to \method{get_param()}. - -\item The method \method{getcharsets()} was renamed to - \method{get_charsets()}. - -\item The method \method{getfilename()} was renamed to - \method{get_filename()}. - -\item The method \method{getboundary()} was renamed to - \method{get_boundary()}. - -\item The method \method{setboundary()} was renamed to - \method{set_boundary()}. - -\item The method \method{getdecodedpayload()} was removed. To get - similar functionality, pass the value 1 to the \var{decode} flag - of the {get_payload()} method. - -\item The method \method{getpayloadastext()} was removed. Similar - functionality - is supported by the \class{DecodedGenerator} class in the - \refmodule{email.generator} module. - -\item The method \method{getbodyastext()} was removed. You can get - similar functionality by creating an iterator with - \function{typed_subpart_iterator()} in the - \refmodule{email.iterators} module. -\end{itemize} - -The \class{Parser} class has no differences in its public interface. -It does have some additional smarts to recognize -\mimetype{message/delivery-status} type messages, which it represents as -a \class{Message} instance containing separate \class{Message} -subparts for each header block in the delivery status -notification\footnote{Delivery Status Notifications (DSN) are defined -in \rfc{1894}.}. - -The \class{Generator} class has no differences in its public -interface. There is a new class in the \refmodule{email.generator} -module though, called \class{DecodedGenerator} which provides most of -the functionality previously available in the -\method{Message.getpayloadastext()} method. - -The following modules and classes have been changed: - -\begin{itemize} -\item The \class{MIMEBase} class constructor arguments \var{_major} - and \var{_minor} have changed to \var{_maintype} and - \var{_subtype} respectively. - -\item The \code{Image} class/module has been renamed to - \code{MIMEImage}. The \var{_minor} argument has been renamed to - \var{_subtype}. - -\item The \code{Text} class/module has been renamed to - \code{MIMEText}. The \var{_minor} argument has been renamed to - \var{_subtype}. - -\item The \code{MessageRFC822} class/module has been renamed to - \code{MIMEMessage}. Note that an earlier version of - \module{mimelib} called this class/module \code{RFC822}, but - that clashed with the Python standard library module - \refmodule{rfc822} on some case-insensitive file systems. - - Also, the \class{MIMEMessage} class now represents any kind of - MIME message with main type \mimetype{message}. It takes an - optional argument \var{_subtype} which is used to set the MIME - subtype. \var{_subtype} defaults to \mimetype{rfc822}. -\end{itemize} - -\module{mimelib} provided some utility functions in its -\module{address} and \module{date} modules. All of these functions -have been moved to the \refmodule{email.utils} module. - -The \code{MsgReader} class/module has been removed. Its functionality -is most closely supported in the \function{body_line_iterator()} -function in the \refmodule{email.iterators} module. - -\subsection{Examples} - -Here are a few examples of how to use the \module{email} package to -read, write, and send simple email messages, as well as more complex -MIME messages. - -First, let's see how to create and send a simple text message: - -\verbatiminput{email-simple.py} - -Here's an example of how to send a MIME message containing a bunch of -family pictures that may be residing in a directory: - -\verbatiminput{email-mime.py} - -Here's an example of how to send the entire contents of a directory as -an email message: -\footnote{Thanks to Matthew Dixon Cowles for the original inspiration - and examples.} - -\verbatiminput{email-dir.py} - -And finally, here's an example of how to unpack a MIME message like -the one above, into a directory of files: - -\verbatiminput{email-unpack.py} diff --git a/Doc/lib/emailcharsets.tex b/Doc/lib/emailcharsets.tex deleted file mode 100644 index e0be68a..0000000 --- a/Doc/lib/emailcharsets.tex +++ /dev/null @@ -1,244 +0,0 @@ -\declaremodule{standard}{email.charset} -\modulesynopsis{Character Sets} - -This module provides a class \class{Charset} for representing -character sets and character set conversions in email messages, as -well as a character set registry and several convenience methods for -manipulating this registry. Instances of \class{Charset} are used in -several other modules within the \module{email} package. - -Import this class from the \module{email.charset} module. - -\versionadded{2.2.2} - -\begin{classdesc}{Charset}{\optional{input_charset}} -Map character sets to their email properties. - -This class provides information about the requirements imposed on -email for a specific character set. It also provides convenience -routines for converting between character sets, given the availability -of the applicable codecs. Given a character set, it will do its best -to provide information on how to use that character set in an email -message in an RFC-compliant way. - -Certain character sets must be encoded with quoted-printable or base64 -when used in email headers or bodies. Certain character sets must be -converted outright, and are not allowed in email. - -Optional \var{input_charset} is as described below; it is always -coerced to lower case. After being alias normalized it is also used -as a lookup into the registry of character sets to find out the header -encoding, body encoding, and output conversion codec to be used for -the character set. For example, if -\var{input_charset} is \code{iso-8859-1}, then headers and bodies will -be encoded using quoted-printable and no output conversion codec is -necessary. If \var{input_charset} is \code{euc-jp}, then headers will -be encoded with base64, bodies will not be encoded, but output text -will be converted from the \code{euc-jp} character set to the -\code{iso-2022-jp} character set. -\end{classdesc} - -\class{Charset} instances have the following data attributes: - -\begin{datadesc}{input_charset} -The initial character set specified. Common aliases are converted to -their \emph{official} email names (e.g. \code{latin_1} is converted to -\code{iso-8859-1}). Defaults to 7-bit \code{us-ascii}. -\end{datadesc} - -\begin{datadesc}{header_encoding} -If the character set must be encoded before it can be used in an -email header, this attribute will be set to \code{Charset.QP} (for -quoted-printable), \code{Charset.BASE64} (for base64 encoding), or -\code{Charset.SHORTEST} for the shortest of QP or BASE64 encoding. -Otherwise, it will be \code{None}. -\end{datadesc} - -\begin{datadesc}{body_encoding} -Same as \var{header_encoding}, but describes the encoding for the -mail message's body, which indeed may be different than the header -encoding. \code{Charset.SHORTEST} is not allowed for -\var{body_encoding}. -\end{datadesc} - -\begin{datadesc}{output_charset} -Some character sets must be converted before they can be used in -email headers or bodies. If the \var{input_charset} is one of -them, this attribute will contain the name of the character set -output will be converted to. Otherwise, it will be \code{None}. -\end{datadesc} - -\begin{datadesc}{input_codec} -The name of the Python codec used to convert the \var{input_charset} to -Unicode. If no conversion codec is necessary, this attribute will be -\code{None}. -\end{datadesc} - -\begin{datadesc}{output_codec} -The name of the Python codec used to convert Unicode to the -\var{output_charset}. If no conversion codec is necessary, this -attribute will have the same value as the \var{input_codec}. -\end{datadesc} - -\class{Charset} instances also have the following methods: - -\begin{methoddesc}[Charset]{get_body_encoding}{} -Return the content transfer encoding used for body encoding. - -This is either the string \samp{quoted-printable} or \samp{base64} -depending on the encoding used, or it is a function, in which case you -should call the function with a single argument, the Message object -being encoded. The function should then set the -\mailheader{Content-Transfer-Encoding} header itself to whatever is -appropriate. - -Returns the string \samp{quoted-printable} if -\var{body_encoding} is \code{QP}, returns the string -\samp{base64} if \var{body_encoding} is \code{BASE64}, and returns the -string \samp{7bit} otherwise. -\end{methoddesc} - -\begin{methoddesc}{convert}{s} -Convert the string \var{s} from the \var{input_codec} to the -\var{output_codec}. -\end{methoddesc} - -\begin{methoddesc}{to_splittable}{s} -Convert a possibly multibyte string to a safely splittable format. -\var{s} is the string to split. - -Uses the \var{input_codec} to try and convert the string to Unicode, -so it can be safely split on character boundaries (even for multibyte -characters). - -Returns the string as-is if it isn't known how to convert \var{s} to -Unicode with the \var{input_charset}. - -Characters that could not be converted to Unicode will be replaced -with the Unicode replacement character \character{U+FFFD}. -\end{methoddesc} - -\begin{methoddesc}{from_splittable}{ustr\optional{, to_output}} -Convert a splittable string back into an encoded string. \var{ustr} -is a Unicode string to ``unsplit''. - -This method uses the proper codec to try and convert the string from -Unicode back into an encoded format. Return the string as-is if it is -not Unicode, or if it could not be converted from Unicode. - -Characters that could not be converted from Unicode will be replaced -with an appropriate character (usually \character{?}). - -If \var{to_output} is \code{True} (the default), uses -\var{output_codec} to convert to an -encoded format. If \var{to_output} is \code{False}, it uses -\var{input_codec}. -\end{methoddesc} - -\begin{methoddesc}{get_output_charset}{} -Return the output character set. - -This is the \var{output_charset} attribute if that is not \code{None}, -otherwise it is \var{input_charset}. -\end{methoddesc} - -\begin{methoddesc}{encoded_header_len}{} -Return the length of the encoded header string, properly calculating -for quoted-printable or base64 encoding. -\end{methoddesc} - -\begin{methoddesc}{header_encode}{s\optional{, convert}} -Header-encode the string \var{s}. - -If \var{convert} is \code{True}, the string will be converted from the -input charset to the output charset automatically. This is not useful -for multibyte character sets, which have line length issues (multibyte -characters must be split on a character, not a byte boundary); use the -higher-level \class{Header} class to deal with these issues (see -\refmodule{email.header}). \var{convert} defaults to \code{False}. - -The type of encoding (base64 or quoted-printable) will be based on -the \var{header_encoding} attribute. -\end{methoddesc} - -\begin{methoddesc}{body_encode}{s\optional{, convert}} -Body-encode the string \var{s}. - -If \var{convert} is \code{True} (the default), the string will be -converted from the input charset to output charset automatically. -Unlike \method{header_encode()}, there are no issues with byte -boundaries and multibyte charsets in email bodies, so this is usually -pretty safe. - -The type of encoding (base64 or quoted-printable) will be based on -the \var{body_encoding} attribute. -\end{methoddesc} - -The \class{Charset} class also provides a number of methods to support -standard operations and built-in functions. - -\begin{methoddesc}[Charset]{__str__}{} -Returns \var{input_charset} as a string coerced to lower case. -\method{__repr__()} is an alias for \method{__str__()}. -\end{methoddesc} - -\begin{methoddesc}[Charset]{__eq__}{other} -This method allows you to compare two \class{Charset} instances for equality. -\end{methoddesc} - -\begin{methoddesc}[Header]{__ne__}{other} -This method allows you to compare two \class{Charset} instances for inequality. -\end{methoddesc} - -The \module{email.charset} module also provides the following -functions for adding new entries to the global character set, alias, -and codec registries: - -\begin{funcdesc}{add_charset}{charset\optional{, header_enc\optional{, - body_enc\optional{, output_charset}}}} -Add character properties to the global registry. - -\var{charset} is the input character set, and must be the canonical -name of a character set. - -Optional \var{header_enc} and \var{body_enc} is either -\code{Charset.QP} for quoted-printable, \code{Charset.BASE64} for -base64 encoding, \code{Charset.SHORTEST} for the shortest of -quoted-printable or base64 encoding, or \code{None} for no encoding. -\code{SHORTEST} is only valid for \var{header_enc}. The default is -\code{None} for no encoding. - -Optional \var{output_charset} is the character set that the output -should be in. Conversions will proceed from input charset, to -Unicode, to the output charset when the method -\method{Charset.convert()} is called. The default is to output in the -same character set as the input. - -Both \var{input_charset} and \var{output_charset} must have Unicode -codec entries in the module's character set-to-codec mapping; use -\function{add_codec()} to add codecs the module does -not know about. See the \refmodule{codecs} module's documentation for -more information. - -The global character set registry is kept in the module global -dictionary \code{CHARSETS}. -\end{funcdesc} - -\begin{funcdesc}{add_alias}{alias, canonical} -Add a character set alias. \var{alias} is the alias name, -e.g. \code{latin-1}. \var{canonical} is the character set's canonical -name, e.g. \code{iso-8859-1}. - -The global charset alias registry is kept in the module global -dictionary \code{ALIASES}. -\end{funcdesc} - -\begin{funcdesc}{add_codec}{charset, codecname} -Add a codec that map characters in the given character set to and from -Unicode. - -\var{charset} is the canonical name of a character set. -\var{codecname} is the name of a Python codec, as appropriate for the -second argument to the \function{unicode()} built-in, or to the -\method{encode()} method of a Unicode string. -\end{funcdesc} diff --git a/Doc/lib/emailencoders.tex b/Doc/lib/emailencoders.tex deleted file mode 100644 index 3d05c2a..0000000 --- a/Doc/lib/emailencoders.tex +++ /dev/null @@ -1,47 +0,0 @@ -\declaremodule{standard}{email.encoders} -\modulesynopsis{Encoders for email message payloads.} - -When creating \class{Message} objects from scratch, you often need to -encode the payloads for transport through compliant mail servers. -This is especially true for \mimetype{image/*} and \mimetype{text/*} -type messages containing binary data. - -The \module{email} package provides some convenient encodings in its -\module{encoders} module. These encoders are actually used by the -\class{MIMEAudio} and \class{MIMEImage} class constructors to provide default -encodings. All encoder functions take exactly one argument, the message -object to encode. They usually extract the payload, encode it, and reset the -payload to this newly encoded value. They should also set the -\mailheader{Content-Transfer-Encoding} header as appropriate. - -Here are the encoding functions provided: - -\begin{funcdesc}{encode_quopri}{msg} -Encodes the payload into quoted-printable form and sets the -\mailheader{Content-Transfer-Encoding} header to -\code{quoted-printable}\footnote{Note that encoding with -\method{encode_quopri()} also encodes all tabs and space characters in -the data.}. -This is a good encoding to use when most of your payload is normal -printable data, but contains a few unprintable characters. -\end{funcdesc} - -\begin{funcdesc}{encode_base64}{msg} -Encodes the payload into base64 form and sets the -\mailheader{Content-Transfer-Encoding} header to -\code{base64}. This is a good encoding to use when most of your payload -is unprintable data since it is a more compact form than -quoted-printable. The drawback of base64 encoding is that it -renders the text non-human readable. -\end{funcdesc} - -\begin{funcdesc}{encode_7or8bit}{msg} -This doesn't actually modify the message's payload, but it does set -the \mailheader{Content-Transfer-Encoding} header to either \code{7bit} or -\code{8bit} as appropriate, based on the payload data. -\end{funcdesc} - -\begin{funcdesc}{encode_noop}{msg} -This does nothing; it doesn't even set the -\mailheader{Content-Transfer-Encoding} header. -\end{funcdesc} diff --git a/Doc/lib/emailexc.tex b/Doc/lib/emailexc.tex deleted file mode 100644 index 3cef1d5..0000000 --- a/Doc/lib/emailexc.tex +++ /dev/null @@ -1,87 +0,0 @@ -\declaremodule{standard}{email.errors} -\modulesynopsis{The exception classes used by the email package.} - -The following exception classes are defined in the -\module{email.errors} module: - -\begin{excclassdesc}{MessageError}{} -This is the base class for all exceptions that the \module{email} -package can raise. It is derived from the standard -\exception{Exception} class and defines no additional methods. -\end{excclassdesc} - -\begin{excclassdesc}{MessageParseError}{} -This is the base class for exceptions thrown by the \class{Parser} -class. It is derived from \exception{MessageError}. -\end{excclassdesc} - -\begin{excclassdesc}{HeaderParseError}{} -Raised under some error conditions when parsing the \rfc{2822} headers of -a message, this class is derived from \exception{MessageParseError}. -It can be raised from the \method{Parser.parse()} or -\method{Parser.parsestr()} methods. - -Situations where it can be raised include finding an envelope -header after the first \rfc{2822} header of the message, finding a -continuation line before the first \rfc{2822} header is found, or finding -a line in the headers which is neither a header or a continuation -line. -\end{excclassdesc} - -\begin{excclassdesc}{BoundaryError}{} -Raised under some error conditions when parsing the \rfc{2822} headers of -a message, this class is derived from \exception{MessageParseError}. -It can be raised from the \method{Parser.parse()} or -\method{Parser.parsestr()} methods. - -Situations where it can be raised include not being able to find the -starting or terminating boundary in a \mimetype{multipart/*} message -when strict parsing is used. -\end{excclassdesc} - -\begin{excclassdesc}{MultipartConversionError}{} -Raised when a payload is added to a \class{Message} object using -\method{add_payload()}, but the payload is already a scalar and the -message's \mailheader{Content-Type} main type is not either -\mimetype{multipart} or missing. \exception{MultipartConversionError} -multiply inherits from \exception{MessageError} and the built-in -\exception{TypeError}. - -Since \method{Message.add_payload()} is deprecated, this exception is -rarely raised in practice. However the exception may also be raised -if the \method{attach()} method is called on an instance of a class -derived from \class{MIMENonMultipart} (e.g. \class{MIMEImage}). -\end{excclassdesc} - -Here's the list of the defects that the \class{FeedParser} can find while -parsing messages. Note that the defects are added to the message where the -problem was found, so for example, if a message nested inside a -\mimetype{multipart/alternative} had a malformed header, that nested message -object would have a defect, but the containing messages would not. - -All defect classes are subclassed from \class{email.errors.MessageDefect}, but -this class is \emph{not} an exception! - -\versionadded[All the defect classes were added]{2.4} - -\begin{itemize} -\item \class{NoBoundaryInMultipartDefect} -- A message claimed to be a - multipart, but had no \mimetype{boundary} parameter. - -\item \class{StartBoundaryNotFoundDefect} -- The start boundary claimed in the - \mailheader{Content-Type} header was never found. - -\item \class{FirstHeaderLineIsContinuationDefect} -- The message had a - continuation line as its first header line. - -\item \class{MisplacedEnvelopeHeaderDefect} - A ``Unix From'' header was found - in the middle of a header block. - -\item \class{MalformedHeaderDefect} -- A header was found that was missing a - colon, or was otherwise malformed. - -\item \class{MultipartInvariantViolationDefect} -- A message claimed to be a - \mimetype{multipart}, but no subparts were found. Note that when a - message has this defect, its \method{is_multipart()} method may return - false even though its content type claims to be \mimetype{multipart}. -\end{itemize} diff --git a/Doc/lib/emailgenerator.tex b/Doc/lib/emailgenerator.tex deleted file mode 100644 index 7ab0a53..0000000 --- a/Doc/lib/emailgenerator.tex +++ /dev/null @@ -1,133 +0,0 @@ -\declaremodule{standard}{email.generator} -\modulesynopsis{Generate flat text email messages from a message structure.} - -One of the most common tasks is to generate the flat text of the email -message represented by a message object structure. You will need to do -this if you want to send your message via the \refmodule{smtplib} -module or the \refmodule{nntplib} module, or print the message on the -console. Taking a message object structure and producing a flat text -document is the job of the \class{Generator} class. - -Again, as with the \refmodule{email.parser} module, you aren't limited -to the functionality of the bundled generator; you could write one -from scratch yourself. However the bundled generator knows how to -generate most email in a standards-compliant way, should handle MIME -and non-MIME email messages just fine, and is designed so that the -transformation from flat text, to a message structure via the -\class{Parser} class, and back to flat text, is idempotent (the input -is identical to the output). - -Here are the public methods of the \class{Generator} class, imported from the -\module{email.generator} module: - -\begin{classdesc}{Generator}{outfp\optional{, mangle_from_\optional{, - maxheaderlen}}} -The constructor for the \class{Generator} class takes a file-like -object called \var{outfp} for an argument. \var{outfp} must support -the \method{write()} method and be usable as the output file in a -Python extended print statement. - -Optional \var{mangle_from_} is a flag that, when \code{True}, puts a -\samp{>} character in front of any line in the body that starts exactly as -\samp{From }, i.e. \code{From} followed by a space at the beginning of the -line. This is the only guaranteed portable way to avoid having such -lines be mistaken for a \UNIX{} mailbox format envelope header separator (see -\ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD} -{http://www.jwz.org/doc/content-length.html} -for details). \var{mangle_from_} defaults to \code{True}, but you -might want to set this to \code{False} if you are not writing \UNIX{} -mailbox format files. - -Optional \var{maxheaderlen} specifies the longest length for a -non-continued header. When a header line is longer than -\var{maxheaderlen} (in characters, with tabs expanded to 8 spaces), -the header will be split as defined in the \module{email.header.Header} -class. Set to zero to disable header wrapping. The default is 78, as -recommended (but not required) by \rfc{2822}. -\end{classdesc} - -The other public \class{Generator} methods are: - -\begin{methoddesc}[Generator]{flatten}{msg\optional{, unixfrom}} -Print the textual representation of the message object structure rooted at -\var{msg} to the output file specified when the \class{Generator} -instance was created. Subparts are visited depth-first and the -resulting text will be properly MIME encoded. - -Optional \var{unixfrom} is a flag that forces the printing of the -envelope header delimiter before the first \rfc{2822} header of the -root message object. If the root object has no envelope header, a -standard one is crafted. By default, this is set to \code{False} to -inhibit the printing of the envelope delimiter. - -Note that for subparts, no envelope header is ever printed. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Generator]{clone}{fp} -Return an independent clone of this \class{Generator} instance with -the exact same options. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Generator]{write}{s} -Write the string \var{s} to the underlying file object, -i.e. \var{outfp} passed to \class{Generator}'s constructor. This -provides just enough file-like API for \class{Generator} instances to -be used in extended print statements. -\end{methoddesc} - -As a convenience, see the methods \method{Message.as_string()} and -\code{str(aMessage)}, a.k.a. \method{Message.__str__()}, which -simplify the generation of a formatted string representation of a -message object. For more detail, see \refmodule{email.message}. - -The \module{email.generator} module also provides a derived class, -called \class{DecodedGenerator} which is like the \class{Generator} -base class, except that non-\mimetype{text} parts are substituted with -a format string representing the part. - -\begin{classdesc}{DecodedGenerator}{outfp\optional{, mangle_from_\optional{, - maxheaderlen\optional{, fmt}}}} - -This class, derived from \class{Generator} walks through all the -subparts of a message. If the subpart is of main type -\mimetype{text}, then it prints the decoded payload of the subpart. -Optional \var{_mangle_from_} and \var{maxheaderlen} are as with the -\class{Generator} base class. - -If the subpart is not of main type \mimetype{text}, optional \var{fmt} -is a format string that is used instead of the message payload. -\var{fmt} is expanded with the following keywords, \samp{\%(keyword)s} -format: - -\begin{itemize} -\item \code{type} -- Full MIME type of the non-\mimetype{text} part - -\item \code{maintype} -- Main MIME type of the non-\mimetype{text} part - -\item \code{subtype} -- Sub-MIME type of the non-\mimetype{text} part - -\item \code{filename} -- Filename of the non-\mimetype{text} part - -\item \code{description} -- Description associated with the - non-\mimetype{text} part - -\item \code{encoding} -- Content transfer encoding of the - non-\mimetype{text} part - -\end{itemize} - -The default value for \var{fmt} is \code{None}, meaning - -\begin{verbatim} -[Non-text (%(type)s) part of message omitted, filename %(filename)s] -\end{verbatim} - -\versionadded{2.2.2} -\end{classdesc} - -\versionchanged[The previously deprecated method \method{__call__()} was -removed]{2.5} diff --git a/Doc/lib/emailheaders.tex b/Doc/lib/emailheaders.tex deleted file mode 100644 index 524d08c..0000000 --- a/Doc/lib/emailheaders.tex +++ /dev/null @@ -1,178 +0,0 @@ -\declaremodule{standard}{email.header} -\modulesynopsis{Representing non-ASCII headers} - -\rfc{2822} is the base standard that describes the format of email -messages. It derives from the older \rfc{822} standard which came -into widespread use at a time when most email was composed of \ASCII{} -characters only. \rfc{2822} is a specification written assuming email -contains only 7-bit \ASCII{} characters. - -Of course, as email has been deployed worldwide, it has become -internationalized, such that language specific character sets can now -be used in email messages. The base standard still requires email -messages to be transferred using only 7-bit \ASCII{} characters, so a -slew of RFCs have been written describing how to encode email -containing non-\ASCII{} characters into \rfc{2822}-compliant format. -These RFCs include \rfc{2045}, \rfc{2046}, \rfc{2047}, and \rfc{2231}. -The \module{email} package supports these standards in its -\module{email.header} and \module{email.charset} modules. - -If you want to include non-\ASCII{} characters in your email headers, -say in the \mailheader{Subject} or \mailheader{To} fields, you should -use the \class{Header} class and assign the field in the -\class{Message} object to an instance of \class{Header} instead of -using a string for the header value. Import the \class{Header} class from the -\module{email.header} module. For example: - -\begin{verbatim} ->>> from email.message import Message ->>> from email.header import Header ->>> msg = Message() ->>> h = Header('p\xf6stal', 'iso-8859-1') ->>> msg['Subject'] = h ->>> print msg.as_string() -Subject: =?iso-8859-1?q?p=F6stal?= - - -\end{verbatim} - -Notice here how we wanted the \mailheader{Subject} field to contain a -non-\ASCII{} character? We did this by creating a \class{Header} -instance and passing in the character set that the byte string was -encoded in. When the subsequent \class{Message} instance was -flattened, the \mailheader{Subject} field was properly \rfc{2047} -encoded. MIME-aware mail readers would show this header using the -embedded ISO-8859-1 character. - -\versionadded{2.2.2} - -Here is the \class{Header} class description: - -\begin{classdesc}{Header}{\optional{s\optional{, charset\optional{, - maxlinelen\optional{, header_name\optional{, continuation_ws\optional{, - errors}}}}}}} -Create a MIME-compliant header that can contain strings in different -character sets. - -Optional \var{s} is the initial header value. If \code{None} (the -default), the initial header value is not set. You can later append -to the header with \method{append()} method calls. \var{s} may be a -byte string or a Unicode string, but see the \method{append()} -documentation for semantics. - -Optional \var{charset} serves two purposes: it has the same meaning as -the \var{charset} argument to the \method{append()} method. It also -sets the default character set for all subsequent \method{append()} -calls that omit the \var{charset} argument. If \var{charset} is not -provided in the constructor (the default), the \code{us-ascii} -character set is used both as \var{s}'s initial charset and as the -default for subsequent \method{append()} calls. - -The maximum line length can be specified explicit via -\var{maxlinelen}. For splitting the first line to a shorter value (to -account for the field header which isn't included in \var{s}, -e.g. \mailheader{Subject}) pass in the name of the field in -\var{header_name}. The default \var{maxlinelen} is 76, and the -default value for \var{header_name} is \code{None}, meaning it is not -taken into account for the first line of a long, split header. - -Optional \var{continuation_ws} must be \rfc{2822}-compliant folding -whitespace, and is usually either a space or a hard tab character. -This character will be prepended to continuation lines. -\end{classdesc} - -Optional \var{errors} is passed straight through to the -\method{append()} method. - -\begin{methoddesc}[Header]{append}{s\optional{, charset\optional{, errors}}} -Append the string \var{s} to the MIME header. - -Optional \var{charset}, if given, should be a \class{Charset} instance -(see \refmodule{email.charset}) or the name of a character set, which -will be converted to a \class{Charset} instance. A value of -\code{None} (the default) means that the \var{charset} given in the -constructor is used. - -\var{s} may be a byte string or a Unicode string. If it is a byte -string (i.e. \code{isinstance(s, str)} is true), then -\var{charset} is the encoding of that byte string, and a -\exception{UnicodeError} will be raised if the string cannot be -decoded with that character set. - -If \var{s} is a Unicode string, then \var{charset} is a hint -specifying the character set of the characters in the string. In this -case, when producing an \rfc{2822}-compliant header using \rfc{2047} -rules, the Unicode string will be encoded using the following charsets -in order: \code{us-ascii}, the \var{charset} hint, \code{utf-8}. The -first character set to not provoke a \exception{UnicodeError} is used. - -Optional \var{errors} is passed through to any \function{unicode()} or -\function{ustr.encode()} call, and defaults to ``strict''. -\end{methoddesc} - -\begin{methoddesc}[Header]{encode}{\optional{splitchars}} -Encode a message header into an RFC-compliant format, possibly -wrapping long lines and encapsulating non-\ASCII{} parts in base64 or -quoted-printable encodings. Optional \var{splitchars} is a string -containing characters to split long ASCII lines on, in rough support -of \rfc{2822}'s \emph{highest level syntactic breaks}. This doesn't -affect \rfc{2047} encoded lines. -\end{methoddesc} - -The \class{Header} class also provides a number of methods to support -standard operators and built-in functions. - -\begin{methoddesc}[Header]{__str__}{} -A synonym for \method{Header.encode()}. Useful for -\code{str(aHeader)}. -\end{methoddesc} - -\begin{methoddesc}[Header]{__unicode__}{} -A helper for the built-in \function{unicode()} function. Returns the -header as a Unicode string. -\end{methoddesc} - -\begin{methoddesc}[Header]{__eq__}{other} -This method allows you to compare two \class{Header} instances for equality. -\end{methoddesc} - -\begin{methoddesc}[Header]{__ne__}{other} -This method allows you to compare two \class{Header} instances for inequality. -\end{methoddesc} - -The \module{email.header} module also provides the following -convenient functions. - -\begin{funcdesc}{decode_header}{header} -Decode a message header value without converting the character set. -The header value is in \var{header}. - -This function returns a list of \code{(decoded_string, charset)} pairs -containing each of the decoded parts of the header. \var{charset} is -\code{None} for non-encoded parts of the header, otherwise a lower -case string containing the name of the character set specified in the -encoded string. - -Here's an example: - -\begin{verbatim} ->>> from email.header import decode_header ->>> decode_header('=?iso-8859-1?q?p=F6stal?=') -[('p\xf6stal', 'iso-8859-1')] -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{make_header}{decoded_seq\optional{, maxlinelen\optional{, - header_name\optional{, continuation_ws}}}} -Create a \class{Header} instance from a sequence of pairs as returned -by \function{decode_header()}. - -\function{decode_header()} takes a header value string and returns a -sequence of pairs of the format \code{(decoded_string, charset)} where -\var{charset} is the name of the character set. - -This function takes one of those sequence of pairs and returns a -\class{Header} instance. Optional \var{maxlinelen}, -\var{header_name}, and \var{continuation_ws} are as in the -\class{Header} constructor. -\end{funcdesc} diff --git a/Doc/lib/emailiter.tex b/Doc/lib/emailiter.tex deleted file mode 100644 index ef8ef6f..0000000 --- a/Doc/lib/emailiter.tex +++ /dev/null @@ -1,65 +0,0 @@ -\declaremodule{standard}{email.iterators} -\modulesynopsis{Iterate over a message object tree.} - -Iterating over a message object tree is fairly easy with the -\method{Message.walk()} method. The \module{email.iterators} module -provides some useful higher level iterations over message object -trees. - -\begin{funcdesc}{body_line_iterator}{msg\optional{, decode}} -This iterates over all the payloads in all the subparts of \var{msg}, -returning the string payloads line-by-line. It skips over all the -subpart headers, and it skips over any subpart with a payload that -isn't a Python string. This is somewhat equivalent to reading the -flat text representation of the message from a file using -\method{readline()}, skipping over all the intervening headers. - -Optional \var{decode} is passed through to \method{Message.get_payload()}. -\end{funcdesc} - -\begin{funcdesc}{typed_subpart_iterator}{msg\optional{, - maintype\optional{, subtype}}} -This iterates over all the subparts of \var{msg}, returning only those -subparts that match the MIME type specified by \var{maintype} and -\var{subtype}. - -Note that \var{subtype} is optional; if omitted, then subpart MIME -type matching is done only with the main type. \var{maintype} is -optional too; it defaults to \mimetype{text}. - -Thus, by default \function{typed_subpart_iterator()} returns each -subpart that has a MIME type of \mimetype{text/*}. -\end{funcdesc} - -The following function has been added as a useful debugging tool. It -should \emph{not} be considered part of the supported public interface -for the package. - -\begin{funcdesc}{_structure}{msg\optional{, fp\optional{, level}}} -Prints an indented representation of the content types of the -message object structure. For example: - -\begin{verbatim} ->>> msg = email.message_from_file(somefile) ->>> _structure(msg) -multipart/mixed - text/plain - text/plain - multipart/digest - message/rfc822 - text/plain - message/rfc822 - text/plain - message/rfc822 - text/plain - message/rfc822 - text/plain - message/rfc822 - text/plain - text/plain -\end{verbatim} - -Optional \var{fp} is a file-like object to print the output to. It -must be suitable for Python's extended print statement. \var{level} -is used internally. -\end{funcdesc} diff --git a/Doc/lib/emailmessage.tex b/Doc/lib/emailmessage.tex deleted file mode 100644 index 7bd7dd8..0000000 --- a/Doc/lib/emailmessage.tex +++ /dev/null @@ -1,561 +0,0 @@ -\declaremodule{standard}{email.message} -\modulesynopsis{The base class representing email messages.} - -The central class in the \module{email} package is the -\class{Message} class, imported from the \module{email.message} module. It is -the base class for the \module{email} object model. \class{Message} provides -the core functionality for setting and querying header fields, and for -accessing message bodies. - -Conceptually, a \class{Message} object consists of \emph{headers} and -\emph{payloads}. Headers are \rfc{2822} style field names and -values where the field name and value are separated by a colon. The -colon is not part of either the field name or the field value. - -Headers are stored and returned in case-preserving form but are -matched case-insensitively. There may also be a single envelope -header, also known as the \emph{Unix-From} header or the -\code{From_} header. The payload is either a string in the case of -simple message objects or a list of \class{Message} objects for -MIME container documents (e.g. \mimetype{multipart/*} and -\mimetype{message/rfc822}). - -\class{Message} objects provide a mapping style interface for -accessing the message headers, and an explicit interface for accessing -both the headers and the payload. It provides convenience methods for -generating a flat text representation of the message object tree, for -accessing commonly used header parameters, and for recursively walking -over the object tree. - -Here are the methods of the \class{Message} class: - -\begin{classdesc}{Message}{} -The constructor takes no arguments. -\end{classdesc} - -\begin{methoddesc}[Message]{as_string}{\optional{unixfrom}} -Return the entire message flatten as a string. When optional -\var{unixfrom} is \code{True}, the envelope header is included in the -returned string. \var{unixfrom} defaults to \code{False}. - -Note that this method is provided as a convenience and may not always format -the message the way you want. For example, by default it mangles lines that -begin with \code{From }. For more flexibility, instantiate a -\class{Generator} instance and use its -\method{flatten()} method directly. For example: - -\begin{verbatim} -from cStringIO import StringIO -from email.generator import Generator -fp = StringIO() -g = Generator(fp, mangle_from_=False, maxheaderlen=60) -g.flatten(msg) -text = fp.getvalue() -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[Message]{__str__}{} -Equivalent to \method{as_string(unixfrom=True)}. -\end{methoddesc} - -\begin{methoddesc}[Message]{is_multipart}{} -Return \code{True} if the message's payload is a list of -sub-\class{Message} objects, otherwise return \code{False}. When -\method{is_multipart()} returns False, the payload should be a string -object. -\end{methoddesc} - -\begin{methoddesc}[Message]{set_unixfrom}{unixfrom} -Set the message's envelope header to \var{unixfrom}, which should be a string. -\end{methoddesc} - -\begin{methoddesc}[Message]{get_unixfrom}{} -Return the message's envelope header. Defaults to \code{None} if the -envelope header was never set. -\end{methoddesc} - -\begin{methoddesc}[Message]{attach}{payload} -Add the given \var{payload} to the current payload, which must be -\code{None} or a list of \class{Message} objects before the call. -After the call, the payload will always be a list of \class{Message} -objects. If you want to set the payload to a scalar object (e.g. a -string), use \method{set_payload()} instead. -\end{methoddesc} - -\begin{methoddesc}[Message]{get_payload}{\optional{i\optional{, decode}}} -Return a reference the current payload, which will be a list of -\class{Message} objects when \method{is_multipart()} is \code{True}, or a -string when \method{is_multipart()} is \code{False}. If the -payload is a list and you mutate the list object, you modify the -message's payload in place. - -With optional argument \var{i}, \method{get_payload()} will return the -\var{i}-th element of the payload, counting from zero, if -\method{is_multipart()} is \code{True}. An \exception{IndexError} -will be raised if \var{i} is less than 0 or greater than or equal to -the number of items in the payload. If the payload is a string -(i.e. \method{is_multipart()} is \code{False}) and \var{i} is given, a -\exception{TypeError} is raised. - -Optional \var{decode} is a flag indicating whether the payload should be -decoded or not, according to the \mailheader{Content-Transfer-Encoding} header. -When \code{True} and the message is not a multipart, the payload will be -decoded if this header's value is \samp{quoted-printable} or -\samp{base64}. If some other encoding is used, or -\mailheader{Content-Transfer-Encoding} header is -missing, or if the payload has bogus base64 data, the payload is -returned as-is (undecoded). If the message is a multipart and the -\var{decode} flag is \code{True}, then \code{None} is returned. The -default for \var{decode} is \code{False}. -\end{methoddesc} - -\begin{methoddesc}[Message]{set_payload}{payload\optional{, charset}} -Set the entire message object's payload to \var{payload}. It is the -client's responsibility to ensure the payload invariants. Optional -\var{charset} sets the message's default character set; see -\method{set_charset()} for details. - -\versionchanged[\var{charset} argument added]{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{set_charset}{charset} -Set the character set of the payload to \var{charset}, which can -either be a \class{Charset} instance (see \refmodule{email.charset}), a -string naming a character set, -or \code{None}. If it is a string, it will be converted to a -\class{Charset} instance. If \var{charset} is \code{None}, the -\code{charset} parameter will be removed from the -\mailheader{Content-Type} header. Anything else will generate a -\exception{TypeError}. - -The message will be assumed to be of type \mimetype{text/*} encoded with -\var{charset.input_charset}. It will be converted to -\var{charset.output_charset} -and encoded properly, if needed, when generating the plain text -representation of the message. MIME headers -(\mailheader{MIME-Version}, \mailheader{Content-Type}, -\mailheader{Content-Transfer-Encoding}) will be added as needed. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_charset}{} -Return the \class{Charset} instance associated with the message's payload. -\versionadded{2.2.2} -\end{methoddesc} - -The following methods implement a mapping-like interface for accessing -the message's \rfc{2822} headers. Note that there are some -semantic differences between these methods and a normal mapping -(i.e. dictionary) interface. For example, in a dictionary there are -no duplicate keys, but here there may be duplicate message headers. Also, -in dictionaries there is no guaranteed order to the keys returned by -\method{keys()}, but in a \class{Message} object, headers are always -returned in the order they appeared in the original message, or were -added to the message later. Any header deleted and then re-added are -always appended to the end of the header list. - -These semantic differences are intentional and are biased toward -maximal convenience. - -Note that in all cases, any envelope header present in the message is -not included in the mapping interface. - -\begin{methoddesc}[Message]{__len__}{} -Return the total number of headers, including duplicates. -\end{methoddesc} - -\begin{methoddesc}[Message]{__contains__}{name} -Return true if the message object has a field named \var{name}. -Matching is done case-insensitively and \var{name} should not include the -trailing colon. Used for the \code{in} operator, -e.g.: - -\begin{verbatim} -if 'message-id' in myMessage: - print 'Message-ID:', myMessage['message-id'] -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[Message]{__getitem__}{name} -Return the value of the named header field. \var{name} should not -include the colon field separator. If the header is missing, -\code{None} is returned; a \exception{KeyError} is never raised. - -Note that if the named field appears more than once in the message's -headers, exactly which of those field values will be returned is -undefined. Use the \method{get_all()} method to get the values of all -the extant named headers. -\end{methoddesc} - -\begin{methoddesc}[Message]{__setitem__}{name, val} -Add a header to the message with field name \var{name} and value -\var{val}. The field is appended to the end of the message's existing -fields. - -Note that this does \emph{not} overwrite or delete any existing header -with the same name. If you want to ensure that the new header is the -only one present in the message with field name -\var{name}, delete the field first, e.g.: - -\begin{verbatim} -del msg['subject'] -msg['subject'] = 'Python roolz!' -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[Message]{__delitem__}{name} -Delete all occurrences of the field with name \var{name} from the -message's headers. No exception is raised if the named field isn't -present in the headers. -\end{methoddesc} - -\begin{methoddesc}[Message]{has_key}{name} -Return true if the message contains a header field named \var{name}, -otherwise return false. -\end{methoddesc} - -\begin{methoddesc}[Message]{keys}{} -Return a list of all the message's header field names. -\end{methoddesc} - -\begin{methoddesc}[Message]{values}{} -Return a list of all the message's field values. -\end{methoddesc} - -\begin{methoddesc}[Message]{items}{} -Return a list of 2-tuples containing all the message's field headers -and values. -\end{methoddesc} - -\begin{methoddesc}[Message]{get}{name\optional{, failobj}} -Return the value of the named header field. This is identical to -\method{__getitem__()} except that optional \var{failobj} is returned -if the named header is missing (defaults to \code{None}). -\end{methoddesc} - -Here are some additional useful methods: - -\begin{methoddesc}[Message]{get_all}{name\optional{, failobj}} -Return a list of all the values for the field named \var{name}. -If there are no such named headers in the message, \var{failobj} is -returned (defaults to \code{None}). -\end{methoddesc} - -\begin{methoddesc}[Message]{add_header}{_name, _value, **_params} -Extended header setting. This method is similar to -\method{__setitem__()} except that additional header parameters can be -provided as keyword arguments. \var{_name} is the header field to add -and \var{_value} is the \emph{primary} value for the header. - -For each item in the keyword argument dictionary \var{_params}, the -key is taken as the parameter name, with underscores converted to -dashes (since dashes are illegal in Python identifiers). Normally, -the parameter will be added as \code{key="value"} unless the value is -\code{None}, in which case only the key will be added. - -Here's an example: - -\begin{verbatim} -msg.add_header('Content-Disposition', 'attachment', filename='bud.gif') -\end{verbatim} - -This will add a header that looks like - -\begin{verbatim} -Content-Disposition: attachment; filename="bud.gif" -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[Message]{replace_header}{_name, _value} -Replace a header. Replace the first header found in the message that -matches \var{_name}, retaining header order and field name case. If -no matching header was found, a \exception{KeyError} is raised. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_content_type}{} -Return the message's content type. The returned string is coerced to -lower case of the form \mimetype{maintype/subtype}. If there was no -\mailheader{Content-Type} header in the message the default type as -given by \method{get_default_type()} will be returned. Since -according to \rfc{2045}, messages always have a default type, -\method{get_content_type()} will always return a value. - -\rfc{2045} defines a message's default type to be -\mimetype{text/plain} unless it appears inside a -\mimetype{multipart/digest} container, in which case it would be -\mimetype{message/rfc822}. If the \mailheader{Content-Type} header -has an invalid type specification, \rfc{2045} mandates that the -default type be \mimetype{text/plain}. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_content_maintype}{} -Return the message's main content type. This is the -\mimetype{maintype} part of the string returned by -\method{get_content_type()}. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_content_subtype}{} -Return the message's sub-content type. This is the \mimetype{subtype} -part of the string returned by \method{get_content_type()}. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_default_type}{} -Return the default content type. Most messages have a default content -type of \mimetype{text/plain}, except for messages that are subparts -of \mimetype{multipart/digest} containers. Such subparts have a -default content type of \mimetype{message/rfc822}. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{set_default_type}{ctype} -Set the default content type. \var{ctype} should either be -\mimetype{text/plain} or \mimetype{message/rfc822}, although this is -not enforced. The default content type is not stored in the -\mailheader{Content-Type} header. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{, - header\optional{, unquote}}}} -Return the message's \mailheader{Content-Type} parameters, as a list. The -elements of the returned list are 2-tuples of key/value pairs, as -split on the \character{=} sign. The left hand side of the -\character{=} is the key, while the right hand side is the value. If -there is no \character{=} sign in the parameter the value is the empty -string, otherwise the value is as described in \method{get_param()} and is -unquoted if optional \var{unquote} is \code{True} (the default). - -Optional \var{failobj} is the object to return if there is no -\mailheader{Content-Type} header. Optional \var{header} is the header to -search instead of \mailheader{Content-Type}. - -\versionchanged[\var{unquote} argument added]{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_param}{param\optional{, - failobj\optional{, header\optional{, unquote}}}} -Return the value of the \mailheader{Content-Type} header's parameter -\var{param} as a string. If the message has no \mailheader{Content-Type} -header or if there is no such parameter, then \var{failobj} is -returned (defaults to \code{None}). - -Optional \var{header} if given, specifies the message header to use -instead of \mailheader{Content-Type}. - -Parameter keys are always compared case insensitively. The return -value can either be a string, or a 3-tuple if the parameter was -\rfc{2231} encoded. When it's a 3-tuple, the elements of the value are of -the form \code{(CHARSET, LANGUAGE, VALUE)}. Note that both \code{CHARSET} and -\code{LANGUAGE} can be \code{None}, in which case you should consider -\code{VALUE} to be encoded in the \code{us-ascii} charset. You can -usually ignore \code{LANGUAGE}. - -If your application doesn't care whether the parameter was encoded as in -\rfc{2231}, you can collapse the parameter value by calling -\function{email.Utils.collapse_rfc2231_value()}, passing in the return value -from \method{get_param()}. This will return a suitably decoded Unicode string -whn the value is a tuple, or the original string unquoted if it isn't. For -example: - -\begin{verbatim} -rawparam = msg.get_param('foo') -param = email.Utils.collapse_rfc2231_value(rawparam) -\end{verbatim} - -In any case, the parameter value (either the returned string, or the -\code{VALUE} item in the 3-tuple) is always unquoted, unless -\var{unquote} is set to \code{False}. - -\versionchanged[\var{unquote} argument added, and 3-tuple return value -possible]{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{set_param}{param, value\optional{, - header\optional{, requote\optional{, charset\optional{, language}}}}} - -Set a parameter in the \mailheader{Content-Type} header. If the -parameter already exists in the header, its value will be replaced -with \var{value}. If the \mailheader{Content-Type} header as not yet -been defined for this message, it will be set to \mimetype{text/plain} -and the new parameter value will be appended as per \rfc{2045}. - -Optional \var{header} specifies an alternative header to -\mailheader{Content-Type}, and all parameters will be quoted as -necessary unless optional \var{requote} is \code{False} (the default -is \code{True}). - -If optional \var{charset} is specified, the parameter will be encoded -according to \rfc{2231}. Optional \var{language} specifies the RFC -2231 language, defaulting to the empty string. Both \var{charset} and -\var{language} should be strings. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{del_param}{param\optional{, header\optional{, - requote}}} -Remove the given parameter completely from the -\mailheader{Content-Type} header. The header will be re-written in -place without the parameter or its value. All values will be quoted -as necessary unless \var{requote} is \code{False} (the default is -\code{True}). Optional \var{header} specifies an alternative to -\mailheader{Content-Type}. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{set_type}{type\optional{, header}\optional{, - requote}} -Set the main type and subtype for the \mailheader{Content-Type} -header. \var{type} must be a string in the form -\mimetype{maintype/subtype}, otherwise a \exception{ValueError} is -raised. - -This method replaces the \mailheader{Content-Type} header, keeping all -the parameters in place. If \var{requote} is \code{False}, this -leaves the existing header's quoting as is, otherwise the parameters -will be quoted (the default). - -An alternative header can be specified in the \var{header} argument. -When the \mailheader{Content-Type} header is set a -\mailheader{MIME-Version} header is also added. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_filename}{\optional{failobj}} -Return the value of the \code{filename} parameter of the -\mailheader{Content-Disposition} header of the message. If the header does -not have a \code{filename} parameter, this method falls back to looking for -the \code{name} parameter. If neither is found, or the header is missing, -then \var{failobj} is returned. The returned string will always be unquoted -as per \method{Utils.unquote()}. -\end{methoddesc} - -\begin{methoddesc}[Message]{get_boundary}{\optional{failobj}} -Return the value of the \code{boundary} parameter of the -\mailheader{Content-Type} header of the message, or \var{failobj} if either -the header is missing, or has no \code{boundary} parameter. The -returned string will always be unquoted as per -\method{Utils.unquote()}. -\end{methoddesc} - -\begin{methoddesc}[Message]{set_boundary}{boundary} -Set the \code{boundary} parameter of the \mailheader{Content-Type} -header to \var{boundary}. \method{set_boundary()} will always quote -\var{boundary} if necessary. A \exception{HeaderParseError} is raised -if the message object has no \mailheader{Content-Type} header. - -Note that using this method is subtly different than deleting the old -\mailheader{Content-Type} header and adding a new one with the new boundary -via \method{add_header()}, because \method{set_boundary()} preserves the -order of the \mailheader{Content-Type} header in the list of headers. -However, it does \emph{not} preserve any continuation lines which may -have been present in the original \mailheader{Content-Type} header. -\end{methoddesc} - -\begin{methoddesc}[Message]{get_content_charset}{\optional{failobj}} -Return the \code{charset} parameter of the \mailheader{Content-Type} -header, coerced to lower case. If there is no -\mailheader{Content-Type} header, or if that header has no -\code{charset} parameter, \var{failobj} is returned. - -Note that this method differs from \method{get_charset()} which -returns the \class{Charset} instance for the default encoding of the -message body. - -\versionadded{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Message]{get_charsets}{\optional{failobj}} -Return a list containing the character set names in the message. If -the message is a \mimetype{multipart}, then the list will contain one -element for each subpart in the payload, otherwise, it will be a list -of length 1. - -Each item in the list will be a string which is the value of the -\code{charset} parameter in the \mailheader{Content-Type} header for the -represented subpart. However, if the subpart has no -\mailheader{Content-Type} header, no \code{charset} parameter, or is not of -the \mimetype{text} main MIME type, then that item in the returned list -will be \var{failobj}. -\end{methoddesc} - -\begin{methoddesc}[Message]{walk}{} -The \method{walk()} method is an all-purpose generator which can be -used to iterate over all the parts and subparts of a message object -tree, in depth-first traversal order. You will typically use -\method{walk()} as the iterator in a \code{for} loop; each -iteration returns the next subpart. - -Here's an example that prints the MIME type of every part of a -multipart message structure: - -\begin{verbatim} ->>> for part in msg.walk(): -... print part.get_content_type() -multipart/report -text/plain -message/delivery-status -text/plain -text/plain -message/rfc822 -\end{verbatim} -\end{methoddesc} - -\versionchanged[The previously deprecated methods \method{get_type()}, -\method{get_main_type()}, and \method{get_subtype()} were removed]{2.5} - -\class{Message} objects can also optionally contain two instance -attributes, which can be used when generating the plain text of a MIME -message. - -\begin{datadesc}{preamble} -The format of a MIME document allows for some text between the blank -line following the headers, and the first multipart boundary string. -Normally, this text is never visible in a MIME-aware mail reader -because it falls outside the standard MIME armor. However, when -viewing the raw text of the message, or when viewing the message in a -non-MIME aware reader, this text can become visible. - -The \var{preamble} attribute contains this leading extra-armor text -for MIME documents. When the \class{Parser} discovers some text after -the headers but before the first boundary string, it assigns this text -to the message's \var{preamble} attribute. When the \class{Generator} -is writing out the plain text representation of a MIME message, and it -finds the message has a \var{preamble} attribute, it will write this -text in the area between the headers and the first boundary. See -\refmodule{email.parser} and \refmodule{email.generator} for details. - -Note that if the message object has no preamble, the -\var{preamble} attribute will be \code{None}. -\end{datadesc} - -\begin{datadesc}{epilogue} -The \var{epilogue} attribute acts the same way as the \var{preamble} -attribute, except that it contains text that appears between the last -boundary and the end of the message. - -\versionchanged[You do not need to set the epilogue to the empty string in -order for the \class{Generator} to print a newline at the end of the -file]{2.5} -\end{datadesc} - -\begin{datadesc}{defects} -The \var{defects} attribute contains a list of all the problems found when -parsing this message. See \refmodule{email.errors} for a detailed description -of the possible parsing defects. - -\versionadded{2.4} -\end{datadesc} diff --git a/Doc/lib/emailmimebase.tex b/Doc/lib/emailmimebase.tex deleted file mode 100644 index 4735be3..0000000 --- a/Doc/lib/emailmimebase.tex +++ /dev/null @@ -1,186 +0,0 @@ -\declaremodule{standard}{email.mime} -\declaremodule{standard}{email.mime.base} -\declaremodule{standard}{email.mime.nonmultipart} -\declaremodule{standard}{email.mime.multipart} -\declaremodule{standard}{email.mime.audio} -\declaremodule{standard}{email.mime.image} -\declaremodule{standard}{email.mime.message} -\declaremodule{standard}{email.mime.text} -Ordinarily, you get a message object structure by passing a file or -some text to a parser, which parses the text and returns the root -message object. However you can also build a complete message -structure from scratch, or even individual \class{Message} objects by -hand. In fact, you can also take an existing structure and add new -\class{Message} objects, move them around, etc. This makes a very -convenient interface for slicing-and-dicing MIME messages. - -You can create a new object structure by creating \class{Message} instances, -adding attachments and all the appropriate headers manually. For MIME -messages though, the \module{email} package provides some convenient -subclasses to make things easier. - -Here are the classes: - -\begin{classdesc}{MIMEBase}{_maintype, _subtype, **_params} -Module: \module{email.mime.base} - -This is the base class for all the MIME-specific subclasses of -\class{Message}. Ordinarily you won't create instances specifically -of \class{MIMEBase}, although you could. \class{MIMEBase} is provided -primarily as a convenient base class for more specific MIME-aware -subclasses. - -\var{_maintype} is the \mailheader{Content-Type} major type -(e.g. \mimetype{text} or \mimetype{image}), and \var{_subtype} is the -\mailheader{Content-Type} minor type -(e.g. \mimetype{plain} or \mimetype{gif}). \var{_params} is a parameter -key/value dictionary and is passed directly to -\method{Message.add_header()}. - -The \class{MIMEBase} class always adds a \mailheader{Content-Type} header -(based on \var{_maintype}, \var{_subtype}, and \var{_params}), and a -\mailheader{MIME-Version} header (always set to \code{1.0}). -\end{classdesc} - -\begin{classdesc}{MIMENonMultipart}{} -Module: \module{email.mime.nonmultipart} - -A subclass of \class{MIMEBase}, this is an intermediate base class for -MIME messages that are not \mimetype{multipart}. The primary purpose -of this class is to prevent the use of the \method{attach()} method, -which only makes sense for \mimetype{multipart} messages. If -\method{attach()} is called, a \exception{MultipartConversionError} -exception is raised. - -\versionadded{2.2.2} -\end{classdesc} - -\begin{classdesc}{MIMEMultipart}{\optional{subtype\optional{, - boundary\optional{, _subparts\optional{, _params}}}}} -Module: \module{email.mime.multipart} - -A subclass of \class{MIMEBase}, this is an intermediate base class for -MIME messages that are \mimetype{multipart}. Optional \var{_subtype} -defaults to \mimetype{mixed}, but can be used to specify the subtype -of the message. A \mailheader{Content-Type} header of -\mimetype{multipart/}\var{_subtype} will be added to the message -object. A \mailheader{MIME-Version} header will also be added. - -Optional \var{boundary} is the multipart boundary string. When -\code{None} (the default), the boundary is calculated when needed. - -\var{_subparts} is a sequence of initial subparts for the payload. It -must be possible to convert this sequence to a list. You can always -attach new subparts to the message by using the -\method{Message.attach()} method. - -Additional parameters for the \mailheader{Content-Type} header are -taken from the keyword arguments, or passed into the \var{_params} -argument, which is a keyword dictionary. - -\versionadded{2.2.2} -\end{classdesc} - -\begin{classdesc}{MIMEApplication}{_data\optional{, _subtype\optional{, - _encoder\optional{, **_params}}}} -Module: \module{email.mime.application} - -A subclass of \class{MIMENonMultipart}, the \class{MIMEApplication} class is -used to represent MIME message objects of major type \mimetype{application}. -\var{_data} is a string containing the raw byte data. Optional \var{_subtype} -specifies the MIME subtype and defaults to \mimetype{octet-stream}. - -Optional \var{_encoder} is a callable (i.e. function) which will -perform the actual encoding of the data for transport. This -callable takes one argument, which is the \class{MIMEApplication} instance. -It should use \method{get_payload()} and \method{set_payload()} to -change the payload to encoded form. It should also add any -\mailheader{Content-Transfer-Encoding} or other headers to the message -object as necessary. The default encoding is base64. See the -\refmodule{email.encoders} module for a list of the built-in encoders. - -\var{_params} are passed straight through to the base class constructor. -\versionadded{2.5} -\end{classdesc} - -\begin{classdesc}{MIMEAudio}{_audiodata\optional{, _subtype\optional{, - _encoder\optional{, **_params}}}} -Module: \module{email.mime.audio} - -A subclass of \class{MIMENonMultipart}, the \class{MIMEAudio} class -is used to create MIME message objects of major type \mimetype{audio}. -\var{_audiodata} is a string containing the raw audio data. If this -data can be decoded by the standard Python module \refmodule{sndhdr}, -then the subtype will be automatically included in the -\mailheader{Content-Type} header. Otherwise you can explicitly specify the -audio subtype via the \var{_subtype} parameter. If the minor type could -not be guessed and \var{_subtype} was not given, then \exception{TypeError} -is raised. - -Optional \var{_encoder} is a callable (i.e. function) which will -perform the actual encoding of the audio data for transport. This -callable takes one argument, which is the \class{MIMEAudio} instance. -It should use \method{get_payload()} and \method{set_payload()} to -change the payload to encoded form. It should also add any -\mailheader{Content-Transfer-Encoding} or other headers to the message -object as necessary. The default encoding is base64. See the -\refmodule{email.encoders} module for a list of the built-in encoders. - -\var{_params} are passed straight through to the base class constructor. -\end{classdesc} - -\begin{classdesc}{MIMEImage}{_imagedata\optional{, _subtype\optional{, - _encoder\optional{, **_params}}}} -Module: \module{email.mime.image} - -A subclass of \class{MIMENonMultipart}, the \class{MIMEImage} class is -used to create MIME message objects of major type \mimetype{image}. -\var{_imagedata} is a string containing the raw image data. If this -data can be decoded by the standard Python module \refmodule{imghdr}, -then the subtype will be automatically included in the -\mailheader{Content-Type} header. Otherwise you can explicitly specify the -image subtype via the \var{_subtype} parameter. If the minor type could -not be guessed and \var{_subtype} was not given, then \exception{TypeError} -is raised. - -Optional \var{_encoder} is a callable (i.e. function) which will -perform the actual encoding of the image data for transport. This -callable takes one argument, which is the \class{MIMEImage} instance. -It should use \method{get_payload()} and \method{set_payload()} to -change the payload to encoded form. It should also add any -\mailheader{Content-Transfer-Encoding} or other headers to the message -object as necessary. The default encoding is base64. See the -\refmodule{email.encoders} module for a list of the built-in encoders. - -\var{_params} are passed straight through to the \class{MIMEBase} -constructor. -\end{classdesc} - -\begin{classdesc}{MIMEMessage}{_msg\optional{, _subtype}} -Module: \module{email.mime.message} - -A subclass of \class{MIMENonMultipart}, the \class{MIMEMessage} class -is used to create MIME objects of main type \mimetype{message}. -\var{_msg} is used as the payload, and must be an instance of class -\class{Message} (or a subclass thereof), otherwise a -\exception{TypeError} is raised. - -Optional \var{_subtype} sets the subtype of the message; it defaults -to \mimetype{rfc822}. -\end{classdesc} - -\begin{classdesc}{MIMEText}{_text\optional{, _subtype\optional{, _charset}}} -Module: \module{email.mime.text} - -A subclass of \class{MIMENonMultipart}, the \class{MIMEText} class is -used to create MIME objects of major type \mimetype{text}. -\var{_text} is the string for the payload. \var{_subtype} is the -minor type and defaults to \mimetype{plain}. \var{_charset} is the -character set of the text and is passed as a parameter to the -\class{MIMENonMultipart} constructor; it defaults to \code{us-ascii}. No -guessing or encoding is performed on the text data. - -\versionchanged[The previously deprecated \var{_encoding} argument has -been removed. Encoding happens implicitly based on the \var{_charset} -argument]{2.4} -\end{classdesc} diff --git a/Doc/lib/emailparser.tex b/Doc/lib/emailparser.tex deleted file mode 100644 index 609fa40..0000000 --- a/Doc/lib/emailparser.tex +++ /dev/null @@ -1,208 +0,0 @@ -\declaremodule{standard}{email.parser} -\modulesynopsis{Parse flat text email messages to produce a message - object structure.} - -Message object structures can be created in one of two ways: they can be -created from whole cloth by instantiating \class{Message} objects and -stringing them together via \method{attach()} and -\method{set_payload()} calls, or they can be created by parsing a flat text -representation of the email message. - -The \module{email} package provides a standard parser that understands -most email document structures, including MIME documents. You can -pass the parser a string or a file object, and the parser will return -to you the root \class{Message} instance of the object structure. For -simple, non-MIME messages the payload of this root object will likely -be a string containing the text of the message. For MIME -messages, the root object will return \code{True} from its -\method{is_multipart()} method, and the subparts can be accessed via -the \method{get_payload()} and \method{walk()} methods. - -There are actually two parser interfaces available for use, the classic -\class{Parser} API and the incremental \class{FeedParser} API. The classic -\class{Parser} API is fine if you have the entire text of the message in -memory as a string, or if the entire message lives in a file on the file -system. \class{FeedParser} is more appropriate for when you're reading the -message from a stream which might block waiting for more input (e.g. reading -an email message from a socket). The \class{FeedParser} can consume and parse -the message incrementally, and only returns the root object when you close the -parser\footnote{As of email package version 3.0, introduced in -Python 2.4, the classic \class{Parser} was re-implemented in terms of the -\class{FeedParser}, so the semantics and results are identical between the two -parsers.}. - -Note that the parser can be extended in limited ways, and of course -you can implement your own parser completely from scratch. There is -no magical connection between the \module{email} package's bundled -parser and the \class{Message} class, so your custom parser can create -message object trees any way it finds necessary. - -\subsubsection{FeedParser API} - -\versionadded{2.4} - -The \class{FeedParser}, imported from the \module{email.feedparser} module, -provides an API that is conducive to incremental parsing of email messages, -such as would be necessary when reading the text of an email message from a -source that can block (e.g. a socket). The -\class{FeedParser} can of course be used to parse an email message fully -contained in a string or a file, but the classic \class{Parser} API may be -more convenient for such use cases. The semantics and results of the two -parser APIs are identical. - -The \class{FeedParser}'s API is simple; you create an instance, feed it a -bunch of text until there's no more to feed it, then close the parser to -retrieve the root message object. The \class{FeedParser} is extremely -accurate when parsing standards-compliant messages, and it does a very good -job of parsing non-compliant messages, providing information about how a -message was deemed broken. It will populate a message object's \var{defects} -attribute with a list of any problems it found in a message. See the -\refmodule{email.errors} module for the list of defects that it can find. - -Here is the API for the \class{FeedParser}: - -\begin{classdesc}{FeedParser}{\optional{_factory}} -Create a \class{FeedParser} instance. Optional \var{_factory} is a -no-argument callable that will be called whenever a new message object is -needed. It defaults to the \class{email.message.Message} class. -\end{classdesc} - -\begin{methoddesc}[FeedParser]{feed}{data} -Feed the \class{FeedParser} some more data. \var{data} should be a -string containing one or more lines. The lines can be partial and the -\class{FeedParser} will stitch such partial lines together properly. The -lines in the string can have any of the common three line endings, carriage -return, newline, or carriage return and newline (they can even be mixed). -\end{methoddesc} - -\begin{methoddesc}[FeedParser]{close}{} -Closing a \class{FeedParser} completes the parsing of all previously fed data, -and returns the root message object. It is undefined what happens if you feed -more data to a closed \class{FeedParser}. -\end{methoddesc} - -\subsubsection{Parser class API} - -The \class{Parser} class, imported from the \module{email.parser} module, -provides an API that can be used to parse a message when the complete contents -of the message are available in a string or file. The -\module{email.parser} module also provides a second class, called -\class{HeaderParser} which can be used if you're only interested in -the headers of the message. \class{HeaderParser} can be much faster in -these situations, since it does not attempt to parse the message body, -instead setting the payload to the raw body as a string. -\class{HeaderParser} has the same API as the \class{Parser} class. - -\begin{classdesc}{Parser}{\optional{_class}} -The constructor for the \class{Parser} class takes an optional -argument \var{_class}. This must be a callable factory (such as a -function or a class), and it is used whenever a sub-message object -needs to be created. It defaults to \class{Message} (see -\refmodule{email.message}). The factory will be called without -arguments. - -The optional \var{strict} flag is ignored. \deprecated{2.4}{Because the -\class{Parser} class is a backward compatible API wrapper around the -new-in-Python 2.4 \class{FeedParser}, \emph{all} parsing is effectively -non-strict. You should simply stop passing a \var{strict} flag to the -\class{Parser} constructor.} - -\versionchanged[The \var{strict} flag was added]{2.2.2} -\versionchanged[The \var{strict} flag was deprecated]{2.4} -\end{classdesc} - -The other public \class{Parser} methods are: - -\begin{methoddesc}[Parser]{parse}{fp\optional{, headersonly}} -Read all the data from the file-like object \var{fp}, parse the -resulting text, and return the root message object. \var{fp} must -support both the \method{readline()} and the \method{read()} methods -on file-like objects. - -The text contained in \var{fp} must be formatted as a block of \rfc{2822} -style headers and header continuation lines, optionally preceded by a -envelope header. The header block is terminated either by the -end of the data or by a blank line. Following the header block is the -body of the message (which may contain MIME-encoded subparts). - -Optional \var{headersonly} is as with the \method{parse()} method. - -\versionchanged[The \var{headersonly} flag was added]{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[Parser]{parsestr}{text\optional{, headersonly}} -Similar to the \method{parse()} method, except it takes a string -object instead of a file-like object. Calling this method on a string -is exactly equivalent to wrapping \var{text} in a \class{StringIO} -instance first and calling \method{parse()}. - -Optional \var{headersonly} is a flag specifying whether to stop -parsing after reading the headers or not. The default is \code{False}, -meaning it parses the entire contents of the file. - -\versionchanged[The \var{headersonly} flag was added]{2.2.2} -\end{methoddesc} - -Since creating a message object structure from a string or a file -object is such a common task, two functions are provided as a -convenience. They are available in the top-level \module{email} -package namespace. - -\begin{funcdesc}{message_from_string}{s\optional{, _class\optional{, strict}}} -Return a message object structure from a string. This is exactly -equivalent to \code{Parser().parsestr(s)}. Optional \var{_class} and -\var{strict} are interpreted as with the \class{Parser} class constructor. - -\versionchanged[The \var{strict} flag was added]{2.2.2} -\end{funcdesc} - -\begin{funcdesc}{message_from_file}{fp\optional{, _class\optional{, strict}}} -Return a message object structure tree from an open file object. This -is exactly equivalent to \code{Parser().parse(fp)}. Optional -\var{_class} and \var{strict} are interpreted as with the -\class{Parser} class constructor. - -\versionchanged[The \var{strict} flag was added]{2.2.2} -\end{funcdesc} - -Here's an example of how you might use this at an interactive Python -prompt: - -\begin{verbatim} ->>> import email ->>> msg = email.message_from_string(myString) -\end{verbatim} - -\subsubsection{Additional notes} - -Here are some notes on the parsing semantics: - -\begin{itemize} -\item Most non-\mimetype{multipart} type messages are parsed as a single - message object with a string payload. These objects will return - \code{False} for \method{is_multipart()}. Their - \method{get_payload()} method will return a string object. - -\item All \mimetype{multipart} type messages will be parsed as a - container message object with a list of sub-message objects for - their payload. The outer container message will return - \code{True} for \method{is_multipart()} and their - \method{get_payload()} method will return the list of - \class{Message} subparts. - -\item Most messages with a content type of \mimetype{message/*} - (e.g. \mimetype{message/delivery-status} and - \mimetype{message/rfc822}) will also be parsed as container - object containing a list payload of length 1. Their - \method{is_multipart()} method will return \code{True}. The - single element in the list payload will be a sub-message object. - -\item Some non-standards compliant messages may not be internally consistent - about their \mimetype{multipart}-edness. Such messages may have a - \mailheader{Content-Type} header of type \mimetype{multipart}, but their - \method{is_multipart()} method may return \code{False}. If such - messages were parsed with the \class{FeedParser}, they will have an - instance of the \class{MultipartInvariantViolationDefect} class in their - \var{defects} attribute list. See \refmodule{email.errors} for - details. -\end{itemize} diff --git a/Doc/lib/emailutil.tex b/Doc/lib/emailutil.tex deleted file mode 100644 index f9fe2d4..0000000 --- a/Doc/lib/emailutil.tex +++ /dev/null @@ -1,157 +0,0 @@ -\declaremodule{standard}{email.utils} -\modulesynopsis{Miscellaneous email package utilities.} - -There are several useful utilities provided in the \module{email.utils} -module: - -\begin{funcdesc}{quote}{str} -Return a new string with backslashes in \var{str} replaced by two -backslashes, and double quotes replaced by backslash-double quote. -\end{funcdesc} - -\begin{funcdesc}{unquote}{str} -Return a new string which is an \emph{unquoted} version of \var{str}. -If \var{str} ends and begins with double quotes, they are stripped -off. Likewise if \var{str} ends and begins with angle brackets, they -are stripped off. -\end{funcdesc} - -\begin{funcdesc}{parseaddr}{address} -Parse address -- which should be the value of some address-containing -field such as \mailheader{To} or \mailheader{Cc} -- into its constituent -\emph{realname} and \emph{email address} parts. Returns a tuple of that -information, unless the parse fails, in which case a 2-tuple of -\code{('', '')} is returned. -\end{funcdesc} - -\begin{funcdesc}{formataddr}{pair} -The inverse of \method{parseaddr()}, this takes a 2-tuple of the form -\code{(realname, email_address)} and returns the string value suitable -for a \mailheader{To} or \mailheader{Cc} header. If the first element of -\var{pair} is false, then the second element is returned unmodified. -\end{funcdesc} - -\begin{funcdesc}{getaddresses}{fieldvalues} -This method returns a list of 2-tuples of the form returned by -\code{parseaddr()}. \var{fieldvalues} is a sequence of header field -values as might be returned by \method{Message.get_all()}. Here's a -simple example that gets all the recipients of a message: - -\begin{verbatim} -from email.utils import getaddresses - -tos = msg.get_all('to', []) -ccs = msg.get_all('cc', []) -resent_tos = msg.get_all('resent-to', []) -resent_ccs = msg.get_all('resent-cc', []) -all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs) -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{parsedate}{date} -Attempts to parse a date according to the rules in \rfc{2822}. -however, some mailers don't follow that format as specified, so -\function{parsedate()} tries to guess correctly in such cases. -\var{date} is a string containing an \rfc{2822} date, such as -\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. Note that indexes 6, 7, and 8 of the result tuple are not -usable. -\end{funcdesc} - -\begin{funcdesc}{parsedate_tz}{date} -Performs the same function as \function{parsedate()}, but returns -either \code{None} or a 10-tuple; the first 9 elements make up a tuple -that can be passed directly to \function{time.mktime()}, and the tenth -is the offset of the date's timezone from UTC (which is the official -term for Greenwich Mean Time)\footnote{Note that the sign of the timezone -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{2822}.}. If the input -string has no timezone, the last element of the tuple returned is -\code{None}. Note that indexes 6, 7, and 8 of the result tuple are not -usable. -\end{funcdesc} - -\begin{funcdesc}{mktime_tz}{tuple} -Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC -timestamp. It the timezone item in the tuple is \code{None}, assume -local time. Minor deficiency: \function{mktime_tz()} interprets the -first 8 elements of \var{tuple} as a local time and then compensates -for the timezone difference. This may yield a slight error around -changes in daylight savings time, though not worth worrying about for -common use. -\end{funcdesc} - -\begin{funcdesc}{formatdate}{\optional{timeval\optional{, localtime}\optional{, usegmt}}} -Returns a date string as per \rfc{2822}, e.g.: - -\begin{verbatim} -Fri, 09 Nov 2001 01:08:47 -0000 -\end{verbatim} - -Optional \var{timeval} if given is a floating point time value as -accepted by \function{time.gmtime()} and \function{time.localtime()}, -otherwise the current time is used. - -Optional \var{localtime} is a flag that when \code{True}, interprets -\var{timeval}, and returns a date relative to the local timezone -instead of UTC, properly taking daylight savings time into account. -The default is \code{False} meaning UTC is used. - -Optional \var{usegmt} is a flag that when \code{True}, outputs a -date string with the timezone as an ascii string \code{GMT}, rather -than a numeric \code{-0000}. This is needed for some protocols (such -as HTTP). This only applies when \var{localtime} is \code{False}. -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{make_msgid}{\optional{idstring}} -Returns a string suitable for an \rfc{2822}-compliant -\mailheader{Message-ID} header. Optional \var{idstring} if given, is -a string used to strengthen the uniqueness of the message id. -\end{funcdesc} - -\begin{funcdesc}{decode_rfc2231}{s} -Decode the string \var{s} according to \rfc{2231}. -\end{funcdesc} - -\begin{funcdesc}{encode_rfc2231}{s\optional{, charset\optional{, language}}} -Encode the string \var{s} according to \rfc{2231}. Optional -\var{charset} and \var{language}, if given is the character set name -and language name to use. If neither is given, \var{s} is returned -as-is. If \var{charset} is given but \var{language} is not, the -string is encoded using the empty string for \var{language}. -\end{funcdesc} - -\begin{funcdesc}{collapse_rfc2231_value}{value\optional{, errors\optional{, - fallback_charset}}} -When a header parameter is encoded in \rfc{2231} format, -\method{Message.get_param()} may return a 3-tuple containing the character -set, language, and value. \function{collapse_rfc2231_value()} turns this into -a unicode string. Optional \var{errors} is passed to the \var{errors} -argument of the built-in \function{unicode()} function; it defaults to -\code{replace}. Optional \var{fallback_charset} specifies the character set -to use if the one in the \rfc{2231} header is not known by Python; it defaults -to \code{us-ascii}. - -For convenience, if the \var{value} passed to -\function{collapse_rfc2231_value()} is not a tuple, it should be a string and -it is returned unquoted. -\end{funcdesc} - -\begin{funcdesc}{decode_params}{params} -Decode parameters list according to \rfc{2231}. \var{params} is a -sequence of 2-tuples containing elements of the form -\code{(content-type, string-value)}. -\end{funcdesc} - -\versionchanged[The \function{dump_address_pair()} function has been removed; -use \function{formataddr()} instead]{2.4} - -\versionchanged[The \function{decode()} function has been removed; use the -\method{Header.decode_header()} method instead]{2.4} - -\versionchanged[The \function{encode()} function has been removed; use the -\method{Header.encode()} method instead]{2.4} diff --git a/Doc/lib/fileformats.tex b/Doc/lib/fileformats.tex deleted file mode 100644 index 9f9c116..0000000 --- a/Doc/lib/fileformats.tex +++ /dev/null @@ -1,7 +0,0 @@ -\chapter{File Formats} -\label{fileformats} - -The modules described in this chapter parse various miscellaneous file -formats that aren't markup languages or are related to e-mail. - -\localmoduletable diff --git a/Doc/lib/filesys.tex b/Doc/lib/filesys.tex deleted file mode 100644 index 0c682c8..0000000 --- a/Doc/lib/filesys.tex +++ /dev/null @@ -1,18 +0,0 @@ -\chapter{File and Directory Access} -\label{filesys} - -The modules described in this chapter deal with disk files and -directories. For example, there are modules for reading the -properties of files, manipulating paths in a portable way, and -creating temporary files. The full list of modules in this chapter is: - -\localmoduletable - -% XXX can this be included in the seealso environment? --amk -Also see section \ref{bltin-file-objects} for a description -of Python's built-in file objects. - -\begin{seealso} - \seemodule{os}{Operating system interfaces, including functions to - work with files at a lower level than the built-in file object.} -\end{seealso} diff --git a/Doc/lib/frameworks.tex b/Doc/lib/frameworks.tex deleted file mode 100644 index ffe300e..0000000 --- a/Doc/lib/frameworks.tex +++ /dev/null @@ -1,10 +0,0 @@ -\chapter{Program Frameworks} -\label{frameworks} - -The modules described in this chapter are frameworks that will largely -dictate the structure of your program. Currently the modules described -here are all oriented toward writing command-line interfaces. - -The full list of modules described in this chapter is: - -\localmoduletable diff --git a/Doc/lib/i18n.tex b/Doc/lib/i18n.tex deleted file mode 100644 index 699a60c..0000000 --- a/Doc/lib/i18n.tex +++ /dev/null @@ -1,11 +0,0 @@ -\chapter{Internationalization} -\label{i18n} - -The modules described in this chapter help you write -software that is independent of language and locale -by providing mechanisms for selecting a language to be used in -program messages or by tailoring output to match local conventions. - -The list of modules described in this chapter is: - -\localmoduletable diff --git a/Doc/lib/internet.tex b/Doc/lib/internet.tex deleted file mode 100644 index 72ac4b3..0000000 --- a/Doc/lib/internet.tex +++ /dev/null @@ -1,13 +0,0 @@ -\chapter{Internet Protocols and Support \label{internet}} - -\index{WWW} -\index{Internet} -\index{World Wide Web} - -The modules described in this chapter implement Internet protocols and -support for related technology. They are all implemented in Python. -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/ipc.tex b/Doc/lib/ipc.tex deleted file mode 100644 index cd95056..0000000 --- a/Doc/lib/ipc.tex +++ /dev/null @@ -1,14 +0,0 @@ -\chapter{Interprocess Communication and Networking} -\label{ipc} - -The modules described in this chapter provide mechanisms for different -processes to communicate. - -Some modules only work for two processes that are on the same machine, -e.g. \module{signal} and \module{subprocess}. Other modules support -networking protocols that two or more processes can used to -communicate across machines. - -The list of modules described in this chapter is: - -\localmoduletable diff --git a/Doc/lib/language.tex b/Doc/lib/language.tex deleted file mode 100644 index 5cdb113..0000000 --- a/Doc/lib/language.tex +++ /dev/null @@ -1,10 +0,0 @@ -\chapter{Python Language Services - \label{language}} - -Python provides a number of modules to assist in working with the -Python language. These modules support tokenizing, parsing, syntax -analysis, bytecode disassembly, and various other facilities. - -These modules include: - -\localmoduletable diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex deleted file mode 100644 index 445ac55..0000000 --- a/Doc/lib/lib.tex +++ /dev/null @@ -1,452 +0,0 @@ -\documentclass{manual} - -% NOTE: this file controls which chapters/sections of the library -% manual are actually printed. It is easy to customize your manual -% by commenting out sections that you're not interested in. - -\title{Python Library Reference} - -\input{boilerplate} - -\makeindex % tell \index to actually write the - % .idx file -\makemodindex % ... and the module index as well. - - -\begin{document} - -\maketitle - -\ifhtml -\chapter*{Front Matter\label{front}} -\fi - -\input{copyright} - -\begin{abstract} - -\noindent -Python is an extensible, interpreted, object-oriented programming -language. It supports a wide range of applications, from simple text -processing scripts to interactive Web browsers. - -While the \citetitle[../ref/ref.html]{Python Reference Manual} -describes the exact syntax and semantics of the language, it does not -describe the standard library that is distributed with the language, -and which greatly enhances its immediate usability. This library -contains built-in modules (written in C) that provide access to system -functionality such as file I/O that would otherwise be inaccessible to -Python programmers, as well as modules written in Python that provide -standardized solutions for many problems that occur in everyday -programming. Some of these modules are explicitly designed to -encourage and enhance the portability of Python programs. - -This library reference manual documents Python's standard library, as -well as many optional library modules (which may or may not be -available, depending on whether the underlying platform supports them -and on the configuration choices made at compile time). It also -documents the standard types of the language and its built-in -functions and exceptions, many of which are not or incompletely -documented in the Reference Manual. - -This manual assumes basic knowledge about the Python language. For an -informal introduction to Python, see the -\citetitle[../tut/tut.html]{Python Tutorial}; the -\citetitle[../ref/ref.html]{Python Reference Manual} remains the -highest authority on syntactic and semantic questions. Finally, the -manual entitled \citetitle[../ext/ext.html]{Extending and Embedding -the Python Interpreter} describes how to add new extensions to Python -and how to embed it in other applications. - -\end{abstract} - -\tableofcontents - - % Chapter title: - -\input{libintro} % Introduction - - -% ============= -% BUILT-INs -% ============= - -\input{libobjs} % Built-in Exceptions and Functions -\input{libfuncs} -\input{libexcs} -\input{libconsts} - -\input{libstdtypes} % Built-in types - - -% ============= -% BASIC/GENERAL-PURPOSE OBJECTS -% ============= - -% Strings -\input{libstrings} % String Services -\input{libstring} -\input{libre} -\input{libstruct} % XXX also/better in File Formats? -\input{libdifflib} -\input{libstringio} -\input{libtextwrap} -\input{libcodecs} -\input{libunicodedata} -\input{libstringprep} -\input{libfpformat} - - -\input{datatypes} % Data types and structures -\input{libdatetime} -\input{libcalendar} -\input{libcollections} -\input{libheapq} -\input{libbisect} -\input{libarray} -\input{libsched} -\input{libmutex} -\input{libqueue} -\input{libweakref} -\input{libuserdict} - -% General object services -% XXX intro -\input{libtypes} -\input{libnew} -\input{libcopy} -\input{libpprint} -\input{librepr} - - -\input{numeric} % Numeric/Mathematical modules -\input{libmath} -\input{libcmath} -\input{libdecimal} -\input{librandom} - -% Functions, Functional, Generators and Iterators -% XXX intro functional -\input{libitertools} -\input{libfunctools} -\input{liboperator} % from runtime - better with itertools and functools - - -% ============= -% DATA FORMATS -% ============= - -% Big move - include all the markup and internet formats here - -% MIME & email stuff -\input{netdata} % Internet Data Handling -\input{email} -\input{libmailcap} -\input{libmailbox} -\input{libmhlib} -\input{libmimetools} -\input{libmimetypes} -\input{libmultifile} -\input{librfc822} - -% encoding stuff -\input{libbase64} -\input{libbinhex} -\input{libbinascii} -\input{libquopri} -\input{libuu} - -\input{markup} % Structured Markup Processing Tools -\input{libhtmlparser} -\input{libsgmllib} -\input{libhtmllib} -\input{libpyexpat} -\input{xmldom} -\input{xmldomminidom} -\input{xmldompulldom} -\input{xmlsax} -\input{xmlsaxhandler} -\input{xmlsaxutils} -\input{xmlsaxreader} -\input{libetree} - -\input{fileformats} % Miscellaneous file formats -\input{libcsv} -\input{libcfgparser} -\input{librobotparser} -\input{libnetrc} -\input{libxdrlib} - -\input{libcrypto} % Cryptographic Services -\input{libhashlib} -\input{libhmac} - -% ============= -% FILE & DATABASE STORAGE -% ============= - -\input{filesys} % File/directory support -\input{libposixpath} % os.path -\input{libfileinput} -\input{libstat} -\input{libstatvfs} -\input{libfilecmp} -\input{libtempfile} -\input{libglob} -\input{libfnmatch} -\input{liblinecache} -\input{libshutil} -\input{libdircache} - - -\input{archiving} % Data compression and archiving -\input{libzlib} -\input{libgzip} -\input{libbz2} -\input{libzipfile} -\input{libtarfile} - - -\input{persistence} % Persistent storage -\input{libpickle} -\input{libcopyreg} % really copy_reg % from runtime... -\input{libshelve} -\input{libmarshal} -\input{libanydbm} -\input{libwhichdb} -\input{libdbm} -\input{libgdbm} -\input{libdbhash} -\input{libbsddb} -\input{libdumbdbm} -\input{libsqlite3} - - -% ============= -% OS -% ============= - - -\input{liballos} % Generic Operating System Services -\input{libos} -\input{libtime} -\input{liboptparse} -\input{libgetopt} -\input{liblogging} -\input{libgetpass} -\input{libcurses} -\input{libascii} % curses.ascii -\input{libcursespanel} -\input{libplatform} -\input{liberrno} -\input{libctypes} - -\input{libsomeos} % Optional Operating System Services -\input{libselect} -\input{libthread} -\input{libthreading} -\input{libdummythread} -\input{libdummythreading} -\input{libmmap} -\input{libreadline} -\input{librlcompleter} - -\input{libunix} % UNIX Specific Services -\input{libposix} -\input{libpwd} -\input{libspwd} -\input{libgrp} -\input{libcrypt} -\input{libdl} -\input{libtermios} -\input{libtty} -\input{libpty} -\input{libfcntl} -\input{libpipes} -\input{libresource} -\input{libnis} -\input{libsyslog} -\input{libcommands} - - -% ============= -% NETWORK & COMMUNICATIONS -% ============= - -\input{ipc} % Interprocess communication/networking -\input{libsubprocess} -\input{libsocket} -\input{libsignal} -\input{libasyncore} -\input{libasynchat} - -\input{internet} % Internet Protocols -\input{libwebbrowser} -\input{libcgi} -\input{libcgitb} -\input{libwsgiref} -\input{liburllib} -\input{liburllib2} -\input{libhttplib} -\input{libftplib} -\input{libpoplib} -\input{libimaplib} -\input{libnntplib} -\input{libsmtplib} -\input{libsmtpd} -\input{libtelnetlib} -\input{libuuid} -\input{liburlparse} -\input{libsocksvr} -\input{libbasehttp} -\input{libsimplehttp} -\input{libcgihttp} -\input{libcookielib} -\input{libcookie} -\input{libxmlrpclib} -\input{libsimplexmlrpc} -\input{libdocxmlrpc} - -% ============= -% MULTIMEDIA -% ============= - -\input{libmm} % Multimedia Services -\input{libaudioop} -\input{libaifc} -\input{libsunau} -\input{libwave} -\input{libchunk} -\input{libcolorsys} -\input{libimghdr} -\input{libsndhdr} -\input{libossaudiodev} - -% Tkinter is a chapter in its own right. -\input{tkinter} - -% % Internationalization -\input{i18n} -\input{libgettext} -\input{liblocale} - -% ============= -% PROGRAM FRAMEWORKS -% ============= -\input{frameworks} -\input{libcmd} -\input{libshlex} - - -% ============= -% DEVELOPMENT TOOLS -% ============= -% % Software development support -\input{development} -\input{libpydoc} -\input{libdoctest} -\input{libunittest} -\input{libtest} - -\input{libpdb} % The Python Debugger - -\input{libprofile} % The Python Profiler -\input{libhotshot} % unmaintained C profiler -\input{libtimeit} -\input{libtrace} - -% ============= -% PYTHON ENGINE -% ============= - -% Runtime services -\input{libpython} % Python Runtime Services -\input{libsys} -\input{libbltin} % really __builtin__ -\input{libmain} % really __main__ -\input{libwarnings} -\input{libcontextlib} -\input{libatexit} -\input{libtraceback} -\input{libfuture} % really __future__ -\input{libgc} -\input{libinspect} -\input{libsite} -\input{libuser} -\input{libfpectl} - - -\input{custominterp} % Custom interpreter -\input{libcode} -\input{libcodeop} - - -\input{modules} % Importing Modules -\input{libimp} -\input{libzipimport} -\input{libpkgutil} -\input{libmodulefinder} -\input{librunpy} - - -% ============= -% PYTHON LANGUAGE & COMPILER -% ============= - -\input{language} % Python Language Services -\input{libparser} -\input{libsymbol} -\input{libtoken} -\input{libkeyword} -\input{libtokenize} -\input{libtabnanny} -\input{libpyclbr} -\input{libpycompile} % really py_compile -\input{libcompileall} -\input{libdis} -\input{libpickletools} -\input{distutils} - -\input{libast} - -\input{libmisc} % Miscellaneous Services -\input{libformatter} - -% ============= -% OTHER PLATFORM-SPECIFIC STUFF -% ============= - -\input{windows} % MS Windows ONLY -\input{libmsilib} -\input{libmsvcrt} -\input{libwinreg} -\input{libwinsound} - -\appendix -\input{libundoc} - -%\chapter{Obsolete Modules} - -\chapter{Reporting Bugs} -\input{reportingbugs} - -\chapter{History and License} -\input{license} - -% -% The ugly "%begin{latexonly}" pseudo-environments are really just to -% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're -% not really valuable. -% - -%begin{latexonly} -\renewcommand{\indexname}{Module Index} -%end{latexonly} -\input{modlib.ind} % Module Index - -%begin{latexonly} -\renewcommand{\indexname}{Index} -%end{latexonly} -\input{lib.ind} % Index - -\end{document} diff --git a/Doc/lib/libaifc.tex b/Doc/lib/libaifc.tex deleted file mode 100644 index 65abe84..0000000 --- a/Doc/lib/libaifc.tex +++ /dev/null @@ -1,202 +0,0 @@ -\section{\module{aifc} --- - Read and write AIFF and AIFC files} - -\declaremodule{standard}{aifc} -\modulesynopsis{Read and write audio files in AIFF or AIFC format.} - - -This module provides support for reading and writing AIFF and AIFF-C -files. AIFF is Audio Interchange File Format, a format for storing -digital audio samples in a file. AIFF-C is a newer version of the -format that includes the ability to compress the audio data. -\index{Audio Interchange File Format} -\index{AIFF} -\index{AIFF-C} - -\strong{Caveat:} Some operations may only work under IRIX; these will -raise \exception{ImportError} when attempting to import the -\module{cl} module, which is only available on IRIX. - -Audio files have a number of parameters that describe the audio data. -The sampling rate or frame rate is the number of times per second the -sound is sampled. The number of channels indicate if the audio is -mono, stereo, or quadro. Each frame consists of one sample per -channel. The sample size is the size in bytes of each sample. Thus a -frame consists of \var{nchannels}*\var{samplesize} bytes, and a -second's worth of audio consists of -\var{nchannels}*\var{samplesize}*\var{framerate} bytes. - -For example, CD quality audio has a sample size of two bytes (16 -bits), uses two channels (stereo) and has a frame rate of 44,100 -frames/second. This gives a frame size of 4 bytes (2*2), and a -second's worth occupies 2*2*44100 bytes (176,400 bytes). - -Module \module{aifc} defines the following function: - -\begin{funcdesc}{open}{file\optional{, mode}} -Open an AIFF or AIFF-C file and return an object instance with -methods that are described below. The argument \var{file} is either a -string naming a file or a file object. \var{mode} must be \code{'r'} -or \code{'rb'} when the file must be opened for reading, or \code{'w'} -or \code{'wb'} when the file must be opened for writing. If omitted, -\code{\var{file}.mode} is used if it exists, otherwise \code{'rb'} is -used. When used for writing, the file object should be seekable, -unless you know ahead of time how many samples you are going to write -in total and use \method{writeframesraw()} and \method{setnframes()}. -\end{funcdesc} - -Objects returned by \function{open()} when a file is opened for -reading have the following methods: - -\begin{methoddesc}[aifc]{getnchannels}{} -Return the number of audio channels (1 for mono, 2 for stereo). -\end{methoddesc} - -\begin{methoddesc}[aifc]{getsampwidth}{} -Return the size in bytes of individual samples. -\end{methoddesc} - -\begin{methoddesc}[aifc]{getframerate}{} -Return the sampling rate (number of audio frames per second). -\end{methoddesc} - -\begin{methoddesc}[aifc]{getnframes}{} -Return the number of audio frames in the file. -\end{methoddesc} - -\begin{methoddesc}[aifc]{getcomptype}{} -Return a four-character string describing the type of compression used -in the audio file. For AIFF files, the returned value is -\code{'NONE'}. -\end{methoddesc} - -\begin{methoddesc}[aifc]{getcompname}{} -Return a human-readable description of the type of compression used in -the audio file. For AIFF files, the returned value is \code{'not -compressed'}. -\end{methoddesc} - -\begin{methoddesc}[aifc]{getparams}{} -Return a tuple consisting of all of the above values in the above -order. -\end{methoddesc} - -\begin{methoddesc}[aifc]{getmarkers}{} -Return a list of markers in the audio file. A marker consists of a -tuple of three elements. The first is the mark ID (an integer), the -second is the mark position in frames from the beginning of the data -(an integer), the third is the name of the mark (a string). -\end{methoddesc} - -\begin{methoddesc}[aifc]{getmark}{id} -Return the tuple as described in \method{getmarkers()} for the mark -with the given \var{id}. -\end{methoddesc} - -\begin{methoddesc}[aifc]{readframes}{nframes} -Read and return the next \var{nframes} frames from the audio file. The -returned data is a string containing for each frame the uncompressed -samples of all channels. -\end{methoddesc} - -\begin{methoddesc}[aifc]{rewind}{} -Rewind the read pointer. The next \method{readframes()} will start from -the beginning. -\end{methoddesc} - -\begin{methoddesc}[aifc]{setpos}{pos} -Seek to the specified frame number. -\end{methoddesc} - -\begin{methoddesc}[aifc]{tell}{} -Return the current frame number. -\end{methoddesc} - -\begin{methoddesc}[aifc]{close}{} -Close the AIFF file. After calling this method, the object can no -longer be used. -\end{methoddesc} - -Objects returned by \function{open()} when a file is opened for -writing have all the above methods, except for \method{readframes()} and -\method{setpos()}. In addition the following methods exist. The -\method{get*()} methods can only be called after the corresponding -\method{set*()} methods have been called. Before the first -\method{writeframes()} or \method{writeframesraw()}, all parameters -except for the number of frames must be filled in. - -\begin{methoddesc}[aifc]{aiff}{} -Create an AIFF file. The default is that an AIFF-C file is created, -unless the name of the file ends in \code{'.aiff'} in which case the -default is an AIFF file. -\end{methoddesc} - -\begin{methoddesc}[aifc]{aifc}{} -Create an AIFF-C file. The default is that an AIFF-C file is created, -unless the name of the file ends in \code{'.aiff'} in which case the -default is an AIFF file. -\end{methoddesc} - -\begin{methoddesc}[aifc]{setnchannels}{nchannels} -Specify the number of channels in the audio file. -\end{methoddesc} - -\begin{methoddesc}[aifc]{setsampwidth}{width} -Specify the size in bytes of audio samples. -\end{methoddesc} - -\begin{methoddesc}[aifc]{setframerate}{rate} -Specify the sampling frequency in frames per second. -\end{methoddesc} - -\begin{methoddesc}[aifc]{setnframes}{nframes} -Specify the number of frames that are to be written to the audio file. -If this parameter is not set, or not set correctly, the file needs to -support seeking. -\end{methoddesc} - -\begin{methoddesc}[aifc]{setcomptype}{type, name} -Specify the compression type. If not specified, the audio data will -not be compressed. In AIFF files, compression is not possible. The -name parameter should be a human-readable description of the -compression type, the type parameter should be a four-character -string. Currently the following compression types are supported: -NONE, ULAW, ALAW, G722. -\index{u-LAW} -\index{A-LAW} -\index{G.722} -\end{methoddesc} - -\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname} -Set all the above parameters at once. The argument is a tuple -consisting of the various parameters. This means that it is possible -to use the result of a \method{getparams()} call as argument to -\method{setparams()}. -\end{methoddesc} - -\begin{methoddesc}[aifc]{setmark}{id, pos, name} -Add a mark with the given id (larger than 0), and the given name at -the given position. This method can be called at any time before -\method{close()}. -\end{methoddesc} - -\begin{methoddesc}[aifc]{tell}{} -Return the current write position in the output file. Useful in -combination with \method{setmark()}. -\end{methoddesc} - -\begin{methoddesc}[aifc]{writeframes}{data} -Write data to the output file. This method can only be called after -the audio file parameters have been set. -\end{methoddesc} - -\begin{methoddesc}[aifc]{writeframesraw}{data} -Like \method{writeframes()}, except that the header of the audio file -is not updated. -\end{methoddesc} - -\begin{methoddesc}[aifc]{close}{} -Close the AIFF file. The header of the file is updated to reflect the -actual size of the audio data. After calling this method, the object -can no longer be used. -\end{methoddesc} diff --git a/Doc/lib/liballos.tex b/Doc/lib/liballos.tex deleted file mode 100644 index dd046c9..0000000 --- a/Doc/lib/liballos.tex +++ /dev/null @@ -1,9 +0,0 @@ -\chapter{Generic Operating System Services \label{allos}} - -The modules described in this chapter provide interfaces to operating -system features that are available on (almost) all operating systems, -such as files and a clock. The interfaces are generally modeled -after the \UNIX{} or C interfaces, but they are available on most -other systems as well. Here's an overview: - -\localmoduletable diff --git a/Doc/lib/libanydbm.tex b/Doc/lib/libanydbm.tex deleted file mode 100644 index badc6ec..0000000 --- a/Doc/lib/libanydbm.tex +++ /dev/null @@ -1,85 +0,0 @@ -\section{\module{anydbm} --- - Generic access to DBM-style databases} - -\declaremodule{standard}{anydbm} -\modulesynopsis{Generic interface to DBM-style database modules.} - - -\module{anydbm} is a generic interface to variants of the DBM -database --- \refmodule{dbhash}\refstmodindex{dbhash} (requires -\refmodule{bsddb}\refbimodindex{bsddb}), -\refmodule{gdbm}\refbimodindex{gdbm}, or -\refmodule{dbm}\refbimodindex{dbm}. If none of these modules is -installed, the slow-but-simple implementation in module -\refmodule{dumbdbm}\refstmodindex{dumbdbm} will be used. - -\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}} -Open the database file \var{filename} and return a corresponding object. - -If the database file already exists, the \refmodule{whichdb} module is -used to determine its type and the appropriate module is used; if it -does not exist, the first module listed above that can be imported is -used. - -The optional \var{flag} argument can be -\code{'r'} to open an existing database for reading only, -\code{'w'} to open an existing database for reading and writing, -\code{'c'} to create the database if it doesn't exist, or -\code{'n'}, which will always create a new empty database. If not -specified, the default value is \code{'r'}. - -The optional \var{mode} argument is the \UNIX{} mode of the file, used -only when the database has to be created. It defaults to octal -\code{0666} (and will be modified by the prevailing umask). -\end{funcdesc} - -\begin{excdesc}{error} -A tuple containing the exceptions that can be raised by each of the -supported modules, with a unique exception \exception{anydbm.error} as -the first item --- the latter is used when \exception{anydbm.error} is -raised. -\end{excdesc} - -The object returned by \function{open()} supports most of the same -functionality as dictionaries; keys and their corresponding values can -be stored, retrieved, and deleted, and the \method{has_key()} and -\method{keys()} methods are available. Keys and values must always be -strings. - -The following example records some hostnames and a corresponding title, -and then prints out the contents of the database: - -\begin{verbatim} -import anydbm - -# Open database, creating it if necessary. -db = anydbm.open('cache', 'c') - -# Record some values -db['www.python.org'] = 'Python Website' -db['www.cnn.com'] = 'Cable News Network' - -# Loop through contents. Other dictionary methods -# such as .keys(), .values() also work. -for k, v in db.iteritems(): - print k, '\t', v - -# Storing a non-string key or value will raise an exception (most -# likely a TypeError). -db['www.yahoo.com'] = 4 - -# Close when done. -db.close() -\end{verbatim} - - -\begin{seealso} - \seemodule{dbhash}{BSD \code{db} database interface.} - \seemodule{dbm}{Standard \UNIX{} database interface.} - \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.} - \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.} - \seemodule{shelve}{General object persistence built on top of - the Python \code{dbm} interface.} - \seemodule{whichdb}{Utility module used to determine the type of an - existing database.} -\end{seealso} diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex deleted file mode 100644 index eaf5888..0000000 --- a/Doc/lib/libarray.tex +++ /dev/null @@ -1,241 +0,0 @@ -\section{\module{array} --- - Efficient arrays of numeric values} - -\declaremodule{builtin}{array} -\modulesynopsis{Efficient arrays of uniformly typed numeric values.} - - -This module defines an object type which can efficiently represent -an array of basic values: characters, integers, floating point -numbers. Arrays\index{arrays} are sequence types and behave very much -like lists, except that the type of objects stored in them is -constrained. The type is specified at object creation time by using a -\dfn{type code}, which is a single character. The following type -codes are defined: - -\begin{tableiv}{c|l|l|c}{code}{Type code}{C Type}{Python Type}{Minimum size in bytes} - \lineiv{'c'}{char} {character} {1} - \lineiv{'b'}{signed char} {int} {1} - \lineiv{'B'}{unsigned char} {int} {1} - \lineiv{'u'}{Py_UNICODE} {Unicode character}{2} - \lineiv{'h'}{signed short} {int} {2} - \lineiv{'H'}{unsigned short}{int} {2} - \lineiv{'i'}{signed int} {int} {2} - \lineiv{'I'}{unsigned int} {long} {2} - \lineiv{'l'}{signed long} {int} {4} - \lineiv{'L'}{unsigned long} {long} {4} - \lineiv{'f'}{float} {float} {4} - \lineiv{'d'}{double} {float} {8} -\end{tableiv} - -The actual representation of values is determined by the machine -architecture (strictly speaking, by the C implementation). The actual -size can be accessed through the \member{itemsize} attribute. The values -stored for \code{'L'} and \code{'I'} items will be represented as -Python long integers when retrieved, because Python's plain integer -type cannot represent the full range of C's unsigned (long) integers. - - -The module defines the following type: - -\begin{funcdesc}{array}{typecode\optional{, initializer}} -Return a new array whose items are restricted by \var{typecode}, -and initialized from the optional \var{initializer} value, which -must be a list, string, or iterable over elements of the -appropriate type. -\versionchanged[Formerly, only lists or strings were accepted]{2.4} -If given a list or string, the initializer is passed to the -new array's \method{fromlist()}, \method{fromstring()}, or -\method{fromunicode()} method (see below) to add initial items to -the array. Otherwise, the iterable initializer is passed to the -\method{extend()} method. -\end{funcdesc} - -\begin{datadesc}{ArrayType} -Obsolete alias for \function{array}. -\end{datadesc} - - -Array objects support the ordinary sequence operations of -indexing, slicing, concatenation, and multiplication. When using -slice assignment, the assigned value must be an array object with the -same type code; in all other cases, \exception{TypeError} is raised. -Array objects also implement the buffer interface, and may be used -wherever buffer objects are supported. - -The following data items and methods are also supported: - -\begin{memberdesc}[array]{typecode} -The typecode character used to create the array. -\end{memberdesc} - -\begin{memberdesc}[array]{itemsize} -The length in bytes of one array item in the internal representation. -\end{memberdesc} - - -\begin{methoddesc}[array]{append}{x} -Append a new item with value \var{x} to the end of the array. -\end{methoddesc} - -\begin{methoddesc}[array]{buffer_info}{} -Return a tuple \code{(\var{address}, \var{length})} giving the current -memory address and the length in elements of the buffer used to hold -array's contents. The size of the memory buffer in bytes can be -computed as \code{\var{array}.buffer_info()[1] * -\var{array}.itemsize}. This is occasionally useful when working with -low-level (and inherently unsafe) I/O interfaces that require memory -addresses, such as certain \cfunction{ioctl()} operations. The -returned numbers are valid as long as the array exists and no -length-changing operations are applied to it. - -\note{When using array objects from code written in C or -\Cpp{} (the only way to effectively make use of this information), it -makes more sense to use the buffer interface supported by array -objects. This method is maintained for backward compatibility and -should be avoided in new code. The buffer interface is documented in -the \citetitle[../api/newTypes.html]{Python/C API Reference Manual}.} -\end{methoddesc} - -\begin{methoddesc}[array]{byteswap}{} -``Byteswap'' all items of the array. This is only supported for -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]{count}{x} -Return the number of occurrences of \var{x} in the array. -\end{methoddesc} - -\begin{methoddesc}[array]{extend}{iterable} -Append items from \var{iterable} to the end of the array. If -\var{iterable} is another array, it must have \emph{exactly} the same -type code; if not, \exception{TypeError} will be raised. If -\var{iterable} is not an array, it must be iterable and its -elements must be the right type to be appended to the array. -\versionchanged[Formerly, the argument could only be another array]{2.4} -\end{methoddesc} - -\begin{methoddesc}[array]{fromfile}{f, n} -Read \var{n} items (as machine values) from the file object \var{f} -and append them to the end of the array. If less than \var{n} items -are available, \exception{EOFError} is raised, but the items that were -available are still inserted into the array. \var{f} must be a real -built-in file object; something else with a \method{read()} method won't -do. -\end{methoddesc} - -\begin{methoddesc}[array]{fromlist}{list} -Append items from the list. This is equivalent to -\samp{for x in \var{list}:\ a.append(x)} -except that if there is a type error, the array is unchanged. -\end{methoddesc} - -\begin{methoddesc}[array]{fromstring}{s} -Appends items from the string, interpreting the string as an -array of machine values (as if it had been read from a -file using the \method{fromfile()} method). -\end{methoddesc} - -\begin{methoddesc}[array]{fromunicode}{s} -Extends this array with data from the given unicode string. The array -must be a type \code{'u'} array; otherwise a \exception{ValueError} -is raised. Use \samp{array.fromstring(ustr.decode(enc))} to -append Unicode data to an array of some other type. -\end{methoddesc} - -\begin{methoddesc}[array]{index}{x} -Return the smallest \var{i} such that \var{i} is the index of -the first occurrence of \var{x} in the array. -\end{methoddesc} - -\begin{methoddesc}[array]{insert}{i, x} -Insert a new item with value \var{x} in the array before position -\var{i}. Negative values are treated as being relative to the end -of the array. -\end{methoddesc} - -\begin{methoddesc}[array]{pop}{\optional{i}} -Removes the item with the index \var{i} from the array and returns -it. The optional argument defaults to \code{-1}, so that by default -the last item is removed and returned. -\end{methoddesc} - -\begin{methoddesc}[array]{read}{f, n} -\deprecated {1.5.1} - {Use the \method{fromfile()} method.} -Read \var{n} items (as machine values) from the file object \var{f} -and append them to the end of the array. If less than \var{n} items -are available, \exception{EOFError} is raised, but the items that were -available are still inserted into the array. \var{f} must be a real -built-in file object; something else with a \method{read()} method won't -do. -\end{methoddesc} - -\begin{methoddesc}[array]{remove}{x} -Remove the first occurrence of \var{x} from the array. -\end{methoddesc} - -\begin{methoddesc}[array]{reverse}{} -Reverse the order of the items in the array. -\end{methoddesc} - -\begin{methoddesc}[array]{tofile}{f} -Write all items (as machine values) to the file object \var{f}. -\end{methoddesc} - -\begin{methoddesc}[array]{tolist}{} -Convert the array to an ordinary list with the same items. -\end{methoddesc} - -\begin{methoddesc}[array]{tostring}{} -Convert the array to an array of machine values and return the -string representation (the same sequence of bytes that would -be written to a file by the \method{tofile()} method.) -\end{methoddesc} - -\begin{methoddesc}[array]{tounicode}{} -Convert the array to a unicode string. The array must be -a type \code{'u'} array; otherwise a \exception{ValueError} is raised. -Use \samp{array.tostring().decode(enc)} to obtain a unicode string -from an array of some other type. -\end{methoddesc} - -\begin{methoddesc}[array]{write}{f} -\deprecated {1.5.1} - {Use the \method{tofile()} method.} -Write all items (as machine values) to the file object \var{f}. -\end{methoddesc} - -When an array object is printed or converted to a string, it is -represented as \code{array(\var{typecode}, \var{initializer})}. The -\var{initializer} is omitted if the array is empty, otherwise it is a -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{``}), so long as the \function{array()} function has been -imported using \code{from array import array}. Examples: - -\begin{verbatim} -array('l') -array('c', 'hello world') -array('u', u'hello \textbackslash u2641') -array('l', [1, 2, 3, 4, 5]) -array('d', [1.0, 2.0, 3.14]) -\end{verbatim} - - -\begin{seealso} - \seemodule{struct}{Packing and unpacking of heterogeneous binary data.} - \seemodule{xdrlib}{Packing and unpacking of External Data - Representation (XDR) data as used in some remote - procedure call systems.} - \seetitle[http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm]{The - Numerical Python Manual}{The Numeric Python extension - (NumPy) defines another array type; see - \url{http://numpy.sourceforge.net/} for further information - about Numerical Python. (A PDF version of the NumPy manual - is available at - \url{http://numpy.sourceforge.net/numdoc/numdoc.pdf}).} -\end{seealso} diff --git a/Doc/lib/libascii.tex b/Doc/lib/libascii.tex deleted file mode 100644 index 003bd95..0000000 --- a/Doc/lib/libascii.tex +++ /dev/null @@ -1,175 +0,0 @@ -\section{\module{curses.ascii} --- - Utilities for ASCII characters} - -\declaremodule{standard}{curses.ascii} -\modulesynopsis{Constants and set-membership functions for - \ASCII\ characters.} -\moduleauthor{Eric S. Raymond}{esr@thyrsus.com} -\sectionauthor{Eric S. Raymond}{esr@thyrsus.com} - -\versionadded{1.6} - -The \module{curses.ascii} module supplies name constants for -\ASCII{} characters and functions to test membership in various -\ASCII{} character classes. The constants supplied are names for -control characters as follows: - -\begin{tableii}{l|l}{constant}{Name}{Meaning} - \lineii{NUL}{} - \lineii{SOH}{Start of heading, console interrupt} - \lineii{STX}{Start of text} - \lineii{ETX}{End of text} - \lineii{EOT}{End of transmission} - \lineii{ENQ}{Enquiry, goes with \constant{ACK} flow control} - \lineii{ACK}{Acknowledgement} - \lineii{BEL}{Bell} - \lineii{BS}{Backspace} - \lineii{TAB}{Tab} - \lineii{HT}{Alias for \constant{TAB}: ``Horizontal tab''} - \lineii{LF}{Line feed} - \lineii{NL}{Alias for \constant{LF}: ``New line''} - \lineii{VT}{Vertical tab} - \lineii{FF}{Form feed} - \lineii{CR}{Carriage return} - \lineii{SO}{Shift-out, begin alternate character set} - \lineii{SI}{Shift-in, resume default character set} - \lineii{DLE}{Data-link escape} - \lineii{DC1}{XON, for flow control} - \lineii{DC2}{Device control 2, block-mode flow control} - \lineii{DC3}{XOFF, for flow control} - \lineii{DC4}{Device control 4} - \lineii{NAK}{Negative acknowledgement} - \lineii{SYN}{Synchronous idle} - \lineii{ETB}{End transmission block} - \lineii{CAN}{Cancel} - \lineii{EM}{End of medium} - \lineii{SUB}{Substitute} - \lineii{ESC}{Escape} - \lineii{FS}{File separator} - \lineii{GS}{Group separator} - \lineii{RS}{Record separator, block-mode terminator} - \lineii{US}{Unit separator} - \lineii{SP}{Space} - \lineii{DEL}{Delete} -\end{tableii} - -Note that many of these have little practical significance in modern -usage. The mnemonics derive from teleprinter conventions that predate -digital computers. - -The module supplies the following functions, patterned on those in the -standard C library: - - -\begin{funcdesc}{isalnum}{c} -Checks for an \ASCII{} alphanumeric character; it is equivalent to -\samp{isalpha(\var{c}) or isdigit(\var{c})}. -\end{funcdesc} - -\begin{funcdesc}{isalpha}{c} -Checks for an \ASCII{} alphabetic character; it is equivalent to -\samp{isupper(\var{c}) or islower(\var{c})}. -\end{funcdesc} - -\begin{funcdesc}{isascii}{c} -Checks for a character value that fits in the 7-bit \ASCII{} set. -\end{funcdesc} - -\begin{funcdesc}{isblank}{c} -Checks for an \ASCII{} whitespace character. -\end{funcdesc} - -\begin{funcdesc}{iscntrl}{c} -Checks for an \ASCII{} control character (in the range 0x00 to 0x1f). -\end{funcdesc} - -\begin{funcdesc}{isdigit}{c} -Checks for an \ASCII{} decimal digit, \character{0} through -\character{9}. This is equivalent to \samp{\var{c} in string.digits}. -\end{funcdesc} - -\begin{funcdesc}{isgraph}{c} -Checks for \ASCII{} any printable character except space. -\end{funcdesc} - -\begin{funcdesc}{islower}{c} -Checks for an \ASCII{} lower-case character. -\end{funcdesc} - -\begin{funcdesc}{isprint}{c} -Checks for any \ASCII{} printable character including space. -\end{funcdesc} - -\begin{funcdesc}{ispunct}{c} -Checks for any printable \ASCII{} character which is not a space or an -alphanumeric character. -\end{funcdesc} - -\begin{funcdesc}{isspace}{c} -Checks for \ASCII{} white-space characters; space, line feed, -carriage return, form feed, horizontal tab, vertical tab. -\end{funcdesc} - -\begin{funcdesc}{isupper}{c} -Checks for an \ASCII{} uppercase letter. -\end{funcdesc} - -\begin{funcdesc}{isxdigit}{c} -Checks for an \ASCII{} hexadecimal digit. This is equivalent to -\samp{\var{c} in string.hexdigits}. -\end{funcdesc} - -\begin{funcdesc}{isctrl}{c} -Checks for an \ASCII{} control character (ordinal values 0 to 31). -\end{funcdesc} - -\begin{funcdesc}{ismeta}{c} -Checks for a non-\ASCII{} character (ordinal values 0x80 and above). -\end{funcdesc} - -These functions accept either integers or strings; when the argument -is a string, it is first converted using the built-in function -\function{ord()}. - -Note that all these functions check ordinal bit values derived from the -first character of the string you pass in; they do not actually know -anything about the host machine's character encoding. For functions -that know about the character encoding (and handle -internationalization properly) see the \refmodule{string} module. - -The following two functions take either a single-character string or -integer byte value; they return a value of the same type. - -\begin{funcdesc}{ascii}{c} -Return the ASCII value corresponding to the low 7 bits of \var{c}. -\end{funcdesc} - -\begin{funcdesc}{ctrl}{c} -Return the control character corresponding to the given character -(the character bit value is bitwise-anded with 0x1f). -\end{funcdesc} - -\begin{funcdesc}{alt}{c} -Return the 8-bit character corresponding to the given ASCII character -(the character bit value is bitwise-ored with 0x80). -\end{funcdesc} - -The following function takes either a single-character string or -integer value; it returns a string. - -\begin{funcdesc}{unctrl}{c} -Return a string representation of the \ASCII{} character \var{c}. If -\var{c} is printable, this string is the character itself. If the -character is a control character (0x00-0x1f) the string consists of a -caret (\character{\^}) followed by the corresponding uppercase letter. -If the character is an \ASCII{} delete (0x7f) the string is -\code{'\^{}?'}. If the character has its meta bit (0x80) set, the meta -bit is stripped, the preceding rules applied, and -\character{!} prepended to the result. -\end{funcdesc} - -\begin{datadesc}{controlnames} -A 33-element string array that contains the \ASCII{} mnemonics for the -thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f (US), in -order, plus the mnemonic \samp{SP} for the space character. -\end{datadesc} diff --git a/Doc/lib/libast.tex b/Doc/lib/libast.tex deleted file mode 100644 index b2956ae..0000000 --- a/Doc/lib/libast.tex +++ /dev/null @@ -1,57 +0,0 @@ -% XXX Label can't be _ast? -% XXX Where should this section/chapter go? -\chapter{Abstract Syntax Trees\label{ast}} - -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} - -\versionadded{2.5} - -The \code{_ast} module helps Python applications to process -trees of the Python abstract syntax grammar. The Python compiler -currently provides read-only access to such trees, meaning that -applications can only create a tree for a given piece of Python -source code; generating byte code from a (potentially modified) -tree is not supported. The abstract syntax itself might change with -each Python release; this module helps to find out programmatically -what the current grammar looks like. - -An abstract syntax tree can be generated by passing \code{_ast.PyCF_ONLY_AST} -as a flag to the \function{compile} builtin function. The result will be a tree -of objects whose classes all inherit from \code{_ast.AST}. - -The actual classes are derived from the \code{Parser/Python.asdl} file, -which is reproduced below. There is one class defined for each left-hand -side symbol in the abstract grammar (for example, \code{_ast.stmt} or \code{_ast.expr}). -In addition, there is one class defined for each constructor on the -right-hand side; these classes inherit from the classes for the left-hand -side trees. For example, \code{_ast.BinOp} inherits from \code{_ast.expr}. -For production rules with alternatives (aka "sums"), the left-hand side -class is abstract: only instances of specific constructor nodes are ever -created. - -Each concrete class has an attribute \code{_fields} which gives the -names of all child nodes. - -Each instance of a concrete class has one attribute for each child node, -of the type as defined in the grammar. For example, \code{_ast.BinOp} -instances have an attribute \code{left} of type \code{_ast.expr}. -Instances of \code{_ast.expr} and \code{_ast.stmt} subclasses also -have lineno and col_offset attributes. The lineno is the line number -of source text (1 indexed so the first line is line 1) and the -col_offset is the utf8 byte offset of the first token that generated -the node. The utf8 offset is recorded because the parser uses utf8 -internally. - -If these attributes are marked as optional in the grammar (using a -question mark), the value might be \code{None}. If the attributes -can have zero-or-more values (marked with an asterisk), the -values are represented as Python lists. - -\section{Abstract Grammar} - -The module defines a string constant \code{__version__} which -is the decimal subversion revision number of the file shown below. - -The abstract grammar is currently defined as follows: - -\verbatiminput{../../Parser/Python.asdl} diff --git a/Doc/lib/libasynchat.tex b/Doc/lib/libasynchat.tex deleted file mode 100644 index 223bfed7..0000000 --- a/Doc/lib/libasynchat.tex +++ /dev/null @@ -1,254 +0,0 @@ -\section{\module{asynchat} --- - Asynchronous socket command/response handler} - -\declaremodule{standard}{asynchat} -\modulesynopsis{Support for asynchronous command/response protocols.} -\moduleauthor{Sam Rushing}{rushing@nightmare.com} -\sectionauthor{Steve Holden}{sholden@holdenweb.com} - -This module builds on the \refmodule{asyncore} infrastructure, -simplifying asynchronous clients and servers and making it easier to -handle protocols whose elements are terminated by arbitrary strings, or -are of variable length. \refmodule{asynchat} defines the abstract class -\class{async_chat} that you subclass, providing implementations of the -\method{collect_incoming_data()} and \method{found_terminator()} -methods. It uses the same asynchronous loop as \refmodule{asyncore}, and -the two types of channel, \class{asyncore.dispatcher} and -\class{asynchat.async_chat}, can freely be mixed in the channel map. -Typically an \class{asyncore.dispatcher} server channel generates new -\class{asynchat.async_chat} channel objects as it receives incoming -connection requests. - -\begin{classdesc}{async_chat}{} - This class is an abstract subclass of \class{asyncore.dispatcher}. To make - practical use of the code you must subclass \class{async_chat}, providing - meaningful \method{collect_incoming_data()} and \method{found_terminator()} - methods. The \class{asyncore.dispatcher} methods can be - used, although not all make sense in a message/response context. - - Like \class{asyncore.dispatcher}, \class{async_chat} defines a set of events - that are generated by an analysis of socket conditions after a - \cfunction{select()} call. Once the polling loop has been started the - \class{async_chat} object's methods are called by the event-processing - framework with no action on the part of the programmer. - - Unlike \class{asyncore.dispatcher}, \class{async_chat} allows you to define - a first-in-first-out queue (fifo) of \emph{producers}. A producer need have - only one method, \method{more()}, which should return data to be transmitted - on the channel. The producer indicates exhaustion (\emph{i.e.} that it contains - no more data) by having its \method{more()} method return the empty string. At - this point the \class{async_chat} object removes the producer from the fifo - and starts using the next producer, if any. When the producer fifo is empty - the \method{handle_write()} method does nothing. You use the channel object's - \method{set_terminator()} method to describe how to recognize the end - of, or an important breakpoint in, an incoming transmission from the - remote endpoint. - - To build a functioning \class{async_chat} subclass your - input methods \method{collect_incoming_data()} and - \method{found_terminator()} must handle the data that the channel receives - asynchronously. The methods are described below. -\end{classdesc} - -\begin{methoddesc}{close_when_done}{} - Pushes a \code{None} on to the producer fifo. When this producer is - popped off the fifo it causes the channel to be closed. -\end{methoddesc} - -\begin{methoddesc}{collect_incoming_data}{data} - Called with \var{data} holding an arbitrary amount of received data. - The default method, which must be overridden, raises a \exception{NotImplementedError} exception. -\end{methoddesc} - -\begin{methoddesc}{discard_buffers}{} - In emergencies this method will discard any data held in the input and/or - output buffers and the producer fifo. -\end{methoddesc} - -\begin{methoddesc}{found_terminator}{} - Called when the incoming data stream matches the termination condition - set by \method{set_terminator}. The default method, which must be overridden, - raises a \exception{NotImplementedError} exception. The buffered input data should - be available via an instance attribute. -\end{methoddesc} - -\begin{methoddesc}{get_terminator}{} - Returns the current terminator for the channel. -\end{methoddesc} - -\begin{methoddesc}{handle_close}{} - Called when the channel is closed. The default method silently closes - the channel's socket. -\end{methoddesc} - -\begin{methoddesc}{handle_read}{} - Called when a read event fires on the channel's socket in the - asynchronous loop. The default method checks for the termination - condition established by \method{set_terminator()}, which can be either - the appearance of a particular string in the input stream or the receipt - of a particular number of characters. When the terminator is found, - \method{handle_read} calls the \method{found_terminator()} method after - calling \method{collect_incoming_data()} with any data preceding the - terminating condition. -\end{methoddesc} - -\begin{methoddesc}{handle_write}{} - Called when the application may write data to the channel. - The default method calls the \method{initiate_send()} method, which in turn - will call \method{refill_buffer()} to collect data from the producer - fifo associated with the channel. -\end{methoddesc} - -\begin{methoddesc}{push}{data} - Creates a \class{simple_producer} object (\emph{see below}) containing the data and - pushes it on to the channel's \code{producer_fifo} to ensure its - transmission. This is all you need to do to have the channel write - the data out to the network, although it is possible to use your - own producers in more complex schemes to implement encryption and - chunking, for example. -\end{methoddesc} - -\begin{methoddesc}{push_with_producer}{producer} - Takes a producer object and adds it to the producer fifo associated with - the channel. When all currently-pushed producers have been exhausted - the channel will consume this producer's data by calling its - \method{more()} method and send the data to the remote endpoint. -\end{methoddesc} - -\begin{methoddesc}{readable}{} - Should return \code{True} for the channel to be included in the set of - channels tested by the \cfunction{select()} loop for readability. -\end{methoddesc} - -\begin{methoddesc}{refill_buffer}{} - Refills the output buffer by calling the \method{more()} method of the - producer at the head of the fifo. If it is exhausted then the - producer is popped off the fifo and the next producer is activated. - If the current producer is, or becomes, \code{None} then the channel - is closed. -\end{methoddesc} - -\begin{methoddesc}{set_terminator}{term} - Sets the terminating condition to be recognised on the channel. \code{term} - may be any of three types of value, corresponding to three different ways - to handle incoming protocol data. - - \begin{tableii}{l|l}{}{term}{Description} - \lineii{\emph{string}}{Will call \method{found_terminator()} when the - string is found in the input stream} - \lineii{\emph{integer}}{Will call \method{found_terminator()} when the - indicated number of characters have been received} - \lineii{\code{None}}{The channel continues to collect data forever} - \end{tableii} - - Note that any data following the terminator will be available for reading by - the channel after \method{found_terminator()} is called. -\end{methoddesc} - -\begin{methoddesc}{writable}{} - Should return \code{True} as long as items remain on the producer fifo, - or the channel is connected and the channel's output buffer is non-empty. -\end{methoddesc} - -\subsection{asynchat - Auxiliary Classes and Functions} - -\begin{classdesc}{simple_producer}{data\optional{, buffer_size=512}} - A \class{simple_producer} takes a chunk of data and an optional buffer size. - Repeated calls to its \method{more()} method yield successive chunks of the - data no larger than \var{buffer_size}. -\end{classdesc} - -\begin{methoddesc}{more}{} - Produces the next chunk of information from the producer, or returns the empty string. -\end{methoddesc} - -\begin{classdesc}{fifo}{\optional{list=None}} - Each channel maintains a \class{fifo} holding data which has been pushed by the - application but not yet popped for writing to the channel. - A \class{fifo} is a list used to hold data and/or producers until they are required. - If the \var{list} argument is provided then it should contain producers or - data items to be written to the channel. -\end{classdesc} - -\begin{methoddesc}{is_empty}{} - Returns \code{True} iff the fifo is empty. -\end{methoddesc} - -\begin{methoddesc}{first}{} - Returns the least-recently \method{push()}ed item from the fifo. -\end{methoddesc} - -\begin{methoddesc}{push}{data} - Adds the given data (which may be a string or a producer object) to the - producer fifo. -\end{methoddesc} - -\begin{methoddesc}{pop}{} - If the fifo is not empty, returns \code{True, first()}, deleting the popped - item. Returns \code{False, None} for an empty fifo. -\end{methoddesc} - -The \module{asynchat} module also defines one utility function, which may be -of use in network and textual analysis operations. - -\begin{funcdesc}{find_prefix_at_end}{haystack, needle} - Returns \code{True} if string \var{haystack} ends with any non-empty - prefix of string \var{needle}. -\end{funcdesc} - -\subsection{asynchat Example \label{asynchat-example}} - -The following partial example shows how HTTP requests can be read with -\class{async_chat}. A web server might create an \class{http_request_handler} object for -each incoming client connection. Notice that initially the -channel terminator is set to match the blank line at the end of the HTTP -headers, and a flag indicates that the headers are being read. - -Once the headers have been read, if the request is of type POST -(indicating that further data are present in the input stream) then the -\code{Content-Length:} header is used to set a numeric terminator to -read the right amount of data from the channel. - -The \method{handle_request()} method is called once all relevant input -has been marshalled, after setting the channel terminator to \code{None} -to ensure that any extraneous data sent by the web client are ignored. - -\begin{verbatim} -class http_request_handler(asynchat.async_chat): - - def __init__(self, conn, addr, sessions, log): - asynchat.async_chat.__init__(self, conn=conn) - self.addr = addr - self.sessions = sessions - self.ibuffer = [] - self.obuffer = "" - self.set_terminator("\r\n\r\n") - self.reading_headers = True - self.handling = False - self.cgi_data = None - self.log = log - - def collect_incoming_data(self, data): - """Buffer the data""" - self.ibuffer.append(data) - - def found_terminator(self): - if self.reading_headers: - self.reading_headers = False - self.parse_headers("".join(self.ibuffer)) - self.ibuffer = [] - if self.op.upper() == "POST": - clen = self.headers.getheader("content-length") - self.set_terminator(int(clen)) - else: - self.handling = True - self.set_terminator(None) - self.handle_request() - elif not self.handling: - self.set_terminator(None) # browsers sometimes over-send - self.cgi_data = parse(self.headers, "".join(self.ibuffer)) - self.handling = True - self.ibuffer = [] - self.handle_request() -\end{verbatim} - diff --git a/Doc/lib/libasyncore.tex b/Doc/lib/libasyncore.tex deleted file mode 100644 index 0552896..0000000 --- a/Doc/lib/libasyncore.tex +++ /dev/null @@ -1,260 +0,0 @@ -\section{\module{asyncore} --- - Asynchronous socket handler} - -\declaremodule{builtin}{asyncore} -\modulesynopsis{A base class for developing asynchronous socket - handling services.} -\moduleauthor{Sam Rushing}{rushing@nightmare.com} -\sectionauthor{Christopher Petrilli}{petrilli@amber.org} -\sectionauthor{Steve Holden}{sholden@holdenweb.com} -% Heavily adapted from original documentation by Sam Rushing. - -This module provides the basic infrastructure for writing asynchronous -socket service clients and servers. - -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 -different technique, that lets you have nearly all the advantages of -multi-threading, without actually using multiple threads. It's really -only practical if your program is largely I/O bound. If your program -is processor bound, then pre-emptive scheduled threads are probably what -you really need. Network servers are rarely processor bound, however. - -If your operating system supports the \cfunction{select()} system call -in its I/O library (and nearly all do), then you can use it to juggle -multiple communication channels at once; doing other work while your -I/O is taking place in the ``background.'' Although this strategy can -seem strange and complex, especially at first, it is in many ways -easier to understand and control than multi-threaded programming. -The \module{asyncore} module solves many of the difficult problems for -you, making the task of building sophisticated high-performance -network servers and clients a snap. For ``conversational'' applications -and protocols the companion \refmodule{asynchat} module is invaluable. - -The basic idea behind both modules is to create one or more network -\emph{channels}, instances of class \class{asyncore.dispatcher} and -\class{asynchat.async_chat}. Creating the channels adds them to a global -map, used by the \function{loop()} function if you do not provide it -with your own \var{map}. - -Once the initial channel(s) is(are) created, calling the \function{loop()} -function activates channel service, which continues until the last -channel (including any that have been added to the map during asynchronous -service) is closed. - -\begin{funcdesc}{loop}{\optional{timeout\optional{, use_poll\optional{, - map\optional{,count}}}}} - Enter a polling loop that terminates after count passes or all open - channels have been closed. All arguments are optional. The \var{count} - parameter defaults to None, resulting in the loop terminating only - when all channels have been closed. The \var{timeout} argument sets the - timeout parameter for the appropriate \function{select()} or - \function{poll()} call, measured in seconds; the default is 30 seconds. - The \var{use_poll} parameter, if true, indicates that \function{poll()} - should be used in preference to \function{select()} (the default is - \code{False}). - - The \var{map} parameter is a dictionary whose items are - the channels to watch. As channels are closed they are deleted from their - map. If \var{map} is omitted, a global map is used. - Channels (instances of \class{asyncore.dispatcher}, \class{asynchat.async_chat} - and subclasses thereof) can freely be mixed in the map. -\end{funcdesc} - -\begin{classdesc}{dispatcher}{} - The \class{dispatcher} class is a thin wrapper around a low-level socket object. - To make it more useful, it has a few methods for event-handling which are called - from the asynchronous loop. - Otherwise, it can be treated as a normal non-blocking socket object. - - Two class attributes can be modified, to improve performance, - or possibly even to conserve memory. - - \begin{datadesc}{ac_in_buffer_size} - The asynchronous input buffer size (default \code{4096}). - \end{datadesc} - - \begin{datadesc}{ac_out_buffer_size} - The asynchronous output buffer size (default \code{4096}). - \end{datadesc} - - The firing of low-level events at certain times or in certain connection - states tells the asynchronous loop that certain higher-level events have - taken place. For example, if we have asked for a socket to connect to - another host, we know that the connection has been made when the socket - becomes writable for the first time (at this point you know that you may - write to it with the expectation of success). The implied higher-level - events are: - - \begin{tableii}{l|l}{code}{Event}{Description} - \lineii{handle_connect()}{Implied by the first write event} - \lineii{handle_close()}{Implied by a read event with no data available} - \lineii{handle_accept()}{Implied by a read event on a listening socket} - \end{tableii} - - During asynchronous processing, each mapped channel's \method{readable()} - and \method{writable()} methods are used to determine whether the channel's - socket should be added to the list of channels \cfunction{select()}ed or - \cfunction{poll()}ed for read and write events. - -\end{classdesc} - -Thus, the set of channel events is larger than the basic socket events. -The full set of methods that can be overridden in your subclass follows: - -\begin{methoddesc}{handle_read}{} - Called when the asynchronous loop detects that a \method{read()} - call on the channel's socket will succeed. -\end{methoddesc} - -\begin{methoddesc}{handle_write}{} - Called when the asynchronous loop detects that a writable socket - can be written. - Often this method will implement the necessary buffering for - performance. For example: - -\begin{verbatim} -def handle_write(self): - sent = self.send(self.buffer) - self.buffer = self.buffer[sent:] -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{handle_expt}{} - Called when there is out of band (OOB) data for a socket - connection. This will almost never happen, as OOB is - tenuously supported and rarely used. -\end{methoddesc} - -\begin{methoddesc}{handle_connect}{} - Called when the active opener's socket actually makes a connection. - Might send a ``welcome'' banner, or initiate a protocol - negotiation with the remote endpoint, for example. -\end{methoddesc} - -\begin{methoddesc}{handle_close}{} - Called when the socket is closed. -\end{methoddesc} - -\begin{methoddesc}{handle_error}{} - Called when an exception is raised and not otherwise handled. The default - version prints a condensed traceback. -\end{methoddesc} - -\begin{methoddesc}{handle_accept}{} - Called on listening channels (passive openers) when a - connection can be established with a new remote endpoint that - has issued a \method{connect()} call for the local endpoint. -\end{methoddesc} - -\begin{methoddesc}{readable}{} - Called each time around the asynchronous loop to determine whether a - channel's socket should be added to the list on which read events can - occur. The default method simply returns \code{True}, - indicating that by default, all channels will be interested in - read events. -\end{methoddesc} - -\begin{methoddesc}{writable}{} - Called each time around the asynchronous loop to determine whether a - channel's socket should be added to the list on which write events can - occur. The default method simply returns \code{True}, - indicating that by default, all channels will be interested in - write events. -\end{methoddesc} - -In addition, each channel delegates or extends many of the socket methods. -Most of these are nearly identical to their socket partners. - -\begin{methoddesc}{create_socket}{family, type} - This is identical to the creation of a normal socket, and - will use the same options for creation. Refer to the - \refmodule{socket} documentation for information on creating - sockets. -\end{methoddesc} - -\begin{methoddesc}{connect}{address} - As with the normal socket object, \var{address} is a - tuple with the first element the host to connect to, and the - second the port number. -\end{methoddesc} - -\begin{methoddesc}{send}{data} - Send \var{data} to the remote end-point of the socket. -\end{methoddesc} - -\begin{methoddesc}{recv}{buffer_size} - Read at most \var{buffer_size} bytes from the socket's remote end-point. - An empty string implies that the channel has been closed from the other - end. -\end{methoddesc} - -\begin{methoddesc}{listen}{backlog} - Listen for connections made to the socket. The \var{backlog} - argument specifies the maximum number of queued connections - and should be at least 1; the maximum value is - system-dependent (usually 5). -\end{methoddesc} - -\begin{methoddesc}{bind}{address} - Bind the socket to \var{address}. The socket must not already be - bound. (The format of \var{address} depends on the address family - --- see above.) To mark the socket as re-usable (setting the - \constant{SO_REUSEADDR} option), call the \class{dispatcher} - object's \method{set_reuse_addr()} method. -\end{methoddesc} - -\begin{methoddesc}{accept}{} - Accept a connection. The socket must be bound to an address - and listening for connections. The return value is a pair - \code{(\var{conn}, \var{address})} where \var{conn} is a - \emph{new} socket object usable to send and receive data on - the connection, and \var{address} is the address bound to the - socket on the other end of the connection. -\end{methoddesc} - -\begin{methoddesc}{close}{} - Close the socket. All future operations on the socket object - will fail. The remote end-point will receive no more data (after - queued data is flushed). Sockets are automatically closed - when they are garbage-collected. -\end{methoddesc} - - -\subsection{asyncore Example basic HTTP client \label{asyncore-example}} - -Here is a very basic HTTP client that uses the \class{dispatcher} -class to implement its socket handling: - -\begin{verbatim} -import asyncore, socket - -class http_client(asyncore.dispatcher): - - def __init__(self, host, path): - asyncore.dispatcher.__init__(self) - self.create_socket(socket.AF_INET, socket.SOCK_STREAM) - self.connect( (host, 80) ) - self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path - - def handle_connect(self): - pass - - def handle_close(self): - self.close() - - def handle_read(self): - print self.recv(8192) - - def writable(self): - return (len(self.buffer) > 0) - - def handle_write(self): - sent = self.send(self.buffer) - self.buffer = self.buffer[sent:] - -c = http_client('www.python.org', '/') - -asyncore.loop() -\end{verbatim} diff --git a/Doc/lib/libatexit.tex b/Doc/lib/libatexit.tex deleted file mode 100644 index 04f1d49..0000000 --- a/Doc/lib/libatexit.tex +++ /dev/null @@ -1,108 +0,0 @@ -\section{\module{atexit} --- - Exit handlers} - -\declaremodule{builtin}{atexit} -\moduleauthor{Skip Montanaro}{skip@mojam.com} -\sectionauthor{Skip Montanaro}{skip@mojam.com} -\modulesynopsis{Register and execute cleanup functions.} - -\versionadded{2.0} - - -The \module{atexit} module defines functions to register and -unregister cleanup functions. Functions thus registered are -automatically executed upon normal interpreter termination. - -Note: the functions registered via this module are not called when -the program is killed by a signal, when a Python fatal internal -error is detected, or when \function{os._exit()} is called. - -\begin{funcdesc}{register}{func\optional{, *args\optional{, **kargs}}} -Register \var{func} as a function to be executed at termination. Any -optional arguments that are to be passed to \var{func} must be passed -as arguments to \function{register()}. - -At normal program termination (for instance, if -\function{sys.exit()} is called or the main module's execution -completes), all functions registered are called in last in, first out -order. The assumption is that lower level modules will normally be -imported before higher level modules and thus must be cleaned up -later. - -If an exception is raised during execution of the exit handlers, a -traceback is printed (unless \exception{SystemExit} is raised) and the -exception information is saved. After all exit handlers have had a -chance to run the last exception to be raised is re-raised. - -\versionchanged[This function now returns \var{func} which makes it - possible to use it as a decorator without binding the - original name to \code{None}]{2.6} -\end{funcdesc} - -\begin{funcdesc}{unregister}{func} -Remove a function \var{func} from the list of functions to be run at -interpreter-shutdown. After calling \function{unregister()}, -\var{func} is guaranteed not to be called when the interpreter -shuts down. - -\versionadded{3.0} -\end{funcdesc} - - -\begin{seealso} - \seemodule{readline}{Useful example of \module{atexit} to read and - write \refmodule{readline} history files.} -\end{seealso} - - -\subsection{\module{atexit} Example \label{atexit-example}} - -The following simple example demonstrates how a module can initialize -a counter from a file when it is imported and save the counter's -updated value automatically when the program terminates without -relying on the application making an explicit call into this module at -termination. - -\begin{verbatim} -try: - _count = int(open("/tmp/counter").read()) -except IOError: - _count = 0 - -def incrcounter(n): - global _count - _count = _count + n - -def savecounter(): - open("/tmp/counter", "w").write("%d" % _count) - -import atexit -atexit.register(savecounter) -\end{verbatim} - -Positional and keyword arguments may also be passed to -\function{register()} to be passed along to the registered function -when it is called: - -\begin{verbatim} -def goodbye(name, adjective): - print 'Goodbye, %s, it was %s to meet you.' % (name, adjective) - -import atexit -atexit.register(goodbye, 'Donny', 'nice') - -# or: -atexit.register(goodbye, adjective='nice', name='Donny') -\end{verbatim} - -Usage as a decorator: - -\begin{verbatim} -import atexit - -@atexit.register -def goodbye(): - print "You are now leaving the Python sector." -\end{verbatim} - -This obviously only works with functions that don't take arguments. diff --git a/Doc/lib/libaudioop.tex b/Doc/lib/libaudioop.tex deleted file mode 100644 index e827e76..0000000 --- a/Doc/lib/libaudioop.tex +++ /dev/null @@ -1,258 +0,0 @@ -\section{\module{audioop} --- - Manipulate raw audio data} - -\declaremodule{builtin}{audioop} -\modulesynopsis{Manipulate raw audio data.} - - -The \module{audioop} module contains some useful operations on sound -fragments. It operates on sound fragments consisting of signed -integer samples 8, 16 or 32 bits wide, stored in Python strings. -All scalar items are integers, unless specified otherwise. - -% This para is mostly here to provide an excuse for the index entries... -This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings. -\index{Intel/DVI ADPCM} -\index{ADPCM, Intel/DVI} -\index{a-LAW} -\index{u-LAW} - -A few of the more complicated operations only take 16-bit samples, -otherwise the sample size (in bytes) is always a parameter of the -operation. - -The module defines the following variables and functions: - -\begin{excdesc}{error} -This exception is raised on all errors, such as unknown number of bytes -per sample, etc. -\end{excdesc} - -\begin{funcdesc}{add}{fragment1, fragment2, width} -Return a fragment which is the addition of the two samples passed as -parameters. \var{width} is the sample width in bytes, either -\code{1}, \code{2} or \code{4}. Both fragments should have the same -length. -\end{funcdesc} - -\begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state} -Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See -the description of \function{lin2adpcm()} for details on ADPCM coding. -Return a tuple \code{(\var{sample}, \var{newstate})} where the sample -has the width specified in \var{width}. -\end{funcdesc} - -\begin{funcdesc}{alaw2lin}{fragment, width} -Convert sound fragments in a-LAW encoding to linearly encoded sound -fragments. a-LAW encoding always uses 8 bits samples, so \var{width} -refers only to the sample width of the output fragment here. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{avg}{fragment, width} -Return the average over all samples in the fragment. -\end{funcdesc} - -\begin{funcdesc}{avgpp}{fragment, width} -Return the average peak-peak value over all samples in the fragment. -No filtering is done, so the usefulness of this routine is -questionable. -\end{funcdesc} - -\begin{funcdesc}{bias}{fragment, width, bias} -Return a fragment that is the original fragment with a bias added to -each sample. -\end{funcdesc} - -\begin{funcdesc}{cross}{fragment, width} -Return the number of zero crossings in the fragment passed as an -argument. -\end{funcdesc} - -\begin{funcdesc}{findfactor}{fragment, reference} -Return a factor \var{F} such that -\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is -minimal, i.e., return the factor with which you should multiply -\var{reference} to make it match as well as possible to -\var{fragment}. The fragments should both contain 2-byte samples. - -The time taken by this routine is proportional to -\code{len(\var{fragment})}. -\end{funcdesc} - -\begin{funcdesc}{findfit}{fragment, reference} -Try to match \var{reference} as well as possible to a portion of -\var{fragment} (which should be the longer fragment). This is -(conceptually) done by taking slices out of \var{fragment}, using -\function{findfactor()} to compute the best match, and minimizing the -result. The fragments should both contain 2-byte samples. Return a -tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the -(integer) offset into \var{fragment} where the optimal match started -and \var{factor} is the (floating-point) factor as per -\function{findfactor()}. -\end{funcdesc} - -\begin{funcdesc}{findmax}{fragment, length} -Search \var{fragment} for a slice of length \var{length} samples (not -bytes!)\ with maximum energy, i.e., return \var{i} for which -\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments -should both contain 2-byte samples. - -The routine takes time proportional to \code{len(\var{fragment})}. -\end{funcdesc} - -\begin{funcdesc}{getsample}{fragment, width, index} -Return the value of sample \var{index} from the fragment. -\end{funcdesc} - -\begin{funcdesc}{lin2adpcm}{fragment, width, state} -Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an -adaptive coding scheme, whereby each 4 bit number is the difference -between one sample and the next, divided by a (varying) step. The -Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it -may well become a standard. - -\var{state} is a tuple containing the state of the coder. The coder -returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the -\var{newstate} should be passed to the next call of -\function{lin2adpcm()}. In the initial call, \code{None} can be -passed as the state. \var{adpcmfrag} is the ADPCM coded fragment -packed 2 4-bit values per byte. -\end{funcdesc} - -\begin{funcdesc}{lin2alaw}{fragment, width} -Convert samples in the audio fragment to a-LAW encoding and return -this as a Python string. a-LAW is an audio encoding format whereby -you get a dynamic range of about 13 bits using only 8 bit samples. It -is used by the Sun audio hardware, among others. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{lin2lin}{fragment, width, newwidth} -Convert samples between 1-, 2- and 4-byte formats. -\end{funcdesc} - -\begin{funcdesc}{lin2ulaw}{fragment, width} -Convert samples in the audio fragment to u-LAW encoding and return -this as a Python string. u-LAW is an audio encoding format whereby -you get a dynamic range of about 14 bits using only 8 bit samples. It -is used by the Sun audio hardware, among others. -\end{funcdesc} - -\begin{funcdesc}{minmax}{fragment, width} -Return a tuple consisting of the minimum and maximum values of all -samples in the sound fragment. -\end{funcdesc} - -\begin{funcdesc}{max}{fragment, width} -Return the maximum of the \emph{absolute value} of all samples in a -fragment. -\end{funcdesc} - -\begin{funcdesc}{maxpp}{fragment, width} -Return the maximum peak-peak value in the sound fragment. -\end{funcdesc} - -\begin{funcdesc}{mul}{fragment, width, factor} -Return a fragment that has all samples in the original fragment -multiplied by the floating-point value \var{factor}. Overflow is -silently ignored. -\end{funcdesc} - -\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate, - state\optional{, weightA\optional{, weightB}}} -Convert the frame rate of the input fragment. - -\var{state} is a tuple containing the state of the converter. The -converter returns a tuple \code{(\var{newfragment}, \var{newstate})}, -and \var{newstate} should be passed to the next call of -\function{ratecv()}. The initial call should pass \code{None} -as the state. - -The \var{weightA} and \var{weightB} arguments are parameters for a -simple digital filter and default to \code{1} and \code{0} respectively. -\end{funcdesc} - -\begin{funcdesc}{reverse}{fragment, width} -Reverse the samples in a fragment and returns the modified fragment. -\end{funcdesc} - -\begin{funcdesc}{rms}{fragment, width} -Return the root-mean-square of the fragment, i.e. -\begin{displaymath} -\catcode`_=8 -\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}} -\end{displaymath} -This is a measure of the power in an audio signal. -\end{funcdesc} - -\begin{funcdesc}{tomono}{fragment, width, lfactor, rfactor} -Convert a stereo fragment to a mono fragment. The left channel is -multiplied by \var{lfactor} and the right channel by \var{rfactor} -before adding the two channels to give a mono signal. -\end{funcdesc} - -\begin{funcdesc}{tostereo}{fragment, width, lfactor, rfactor} -Generate a stereo fragment from a mono fragment. Each pair of samples -in the stereo fragment are computed from the mono sample, whereby left -channel samples are multiplied by \var{lfactor} and right channel -samples by \var{rfactor}. -\end{funcdesc} - -\begin{funcdesc}{ulaw2lin}{fragment, width} -Convert sound fragments in u-LAW encoding to linearly encoded sound -fragments. u-LAW encoding always uses 8 bits samples, so \var{width} -refers only to the sample width of the output fragment here. -\end{funcdesc} - -Note that operations such as \function{mul()} or \function{max()} make -no distinction between mono and stereo fragments, i.e.\ all samples -are treated equal. If this is a problem the stereo fragment should be -split into two mono fragments first and recombined later. Here is an -example of how to do that: - -\begin{verbatim} -def mul_stereo(sample, width, lfactor, rfactor): - lsample = audioop.tomono(sample, width, 1, 0) - rsample = audioop.tomono(sample, width, 0, 1) - lsample = audioop.mul(sample, width, lfactor) - rsample = audioop.mul(sample, width, rfactor) - lsample = audioop.tostereo(lsample, width, 1, 0) - rsample = audioop.tostereo(rsample, width, 0, 1) - return audioop.add(lsample, rsample, width) -\end{verbatim} - -If you use the ADPCM coder to build network packets and you want your -protocol to be stateless (i.e.\ to be able to tolerate packet loss) -you should not only transmit the data but also the state. Note that -you should send the \var{initial} state (the one you passed to -\function{lin2adpcm()}) along to the decoder, not the final state (as -returned by the coder). If you want to use \function{struct.struct()} -to store the state in binary you can code the first element (the -predicted value) in 16 bits and the second (the delta index) in 8. - -The ADPCM coders have never been tried against other ADPCM coders, -only against themselves. It could well be that I misinterpreted the -standards in which case they will not be interoperable with the -respective standards. - -The \function{find*()} routines might look a bit funny at first sight. -They are primarily meant to do echo cancellation. A reasonably -fast way to do this is to pick the most energetic piece of the output -sample, locate that in the input sample and subtract the whole output -sample from the input sample: - -\begin{verbatim} -def echocancel(outputdata, inputdata): - pos = audioop.findmax(outputdata, 800) # one tenth second - out_test = outputdata[pos*2:] - in_test = inputdata[pos*2:] - ipos, factor = audioop.findfit(in_test, out_test) - # Optional (for better cancellation): - # factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)], - # out_test) - prefill = '\0'*(pos+ipos)*2 - postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata)) - outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill - return audioop.add(inputdata, outputdata, 2) -\end{verbatim} diff --git a/Doc/lib/libbase64.tex b/Doc/lib/libbase64.tex deleted file mode 100644 index 23b74f0..0000000 --- a/Doc/lib/libbase64.tex +++ /dev/null @@ -1,169 +0,0 @@ -\section{\module{base64} --- - RFC 3548: Base16, Base32, Base64 Data Encodings} - -\declaremodule{standard}{base64} -\modulesynopsis{RFC 3548: Base16, Base32, Base64 Data Encodings} - - -\indexii{base64}{encoding} -\index{MIME!base64 encoding} - -This module provides data encoding and decoding as specified in -\rfc{3548}. This standard defines the Base16, Base32, and Base64 -algorithms for encoding and decoding arbitrary binary strings into -text strings that can be safely sent by email, used as parts of URLs, -or included as part of an HTTP POST request. The encoding algorithm is -not the same as the \program{uuencode} program. - -There are two interfaces provided by this module. The modern -interface supports encoding and decoding string objects using all -three alphabets. The legacy interface provides for encoding and -decoding to and from file-like objects as well as strings, but only -using the Base64 standard alphabet. - -The modern interface, which was introduced in Python 2.4, provides: - -\begin{funcdesc}{b64encode}{s\optional{, altchars}} -Encode a string use Base64. - -\var{s} is the string to encode. Optional \var{altchars} must be a -string of at least length 2 (additional characters are ignored) which -specifies an alternative alphabet for the \code{+} and \code{/} -characters. This allows an application to e.g. generate URL or -filesystem safe Base64 strings. The default is \code{None}, for which -the standard Base64 alphabet is used. - -The encoded string is returned. -\end{funcdesc} - -\begin{funcdesc}{b64decode}{s\optional{, altchars}} -Decode a Base64 encoded string. - -\var{s} is the string to decode. Optional \var{altchars} must be a -string of at least length 2 (additional characters are ignored) which -specifies the alternative alphabet used instead of the \code{+} and -\code{/} characters. - -The decoded string is returned. A \exception{TypeError} is raised if -\var{s} were incorrectly padded or if there are non-alphabet -characters present in the string. -\end{funcdesc} - -\begin{funcdesc}{standard_b64encode}{s} -Encode string \var{s} using the standard Base64 alphabet. -\end{funcdesc} - -\begin{funcdesc}{standard_b64decode}{s} -Decode string \var{s} using the standard Base64 alphabet. -\end{funcdesc} - -\begin{funcdesc}{urlsafe_b64encode}{s} -Encode string \var{s} using a URL-safe alphabet, which substitutes -\code{-} instead of \code{+} and \code{_} instead of \code{/} in the -standard Base64 alphabet. -\end{funcdesc} - -\begin{funcdesc}{urlsafe_b64decode}{s} -Decode string \var{s} using a URL-safe alphabet, which substitutes -\code{-} instead of \code{+} and \code{_} instead of \code{/} in the -standard Base64 alphabet. -\end{funcdesc} - -\begin{funcdesc}{b32encode}{s} -Encode a string using Base32. \var{s} is the string to encode. The -encoded string is returned. -\end{funcdesc} - -\begin{funcdesc}{b32decode}{s\optional{, casefold\optional{, map01}}} -Decode a Base32 encoded string. - -\var{s} is the string to decode. Optional \var{casefold} is a flag -specifying whether a lowercase alphabet is acceptable as input. For -security purposes, the default is \code{False}. - -\rfc{3548} allows for optional mapping of the digit 0 (zero) to the -letter O (oh), and for optional mapping of the digit 1 (one) to either -the letter I (eye) or letter L (el). The optional argument -\var{map01} when not \code{None}, specifies which letter the digit 1 should -be mapped to (when \var{map01} is not \code{None}, the digit 0 is always -mapped to the letter O). For security purposes the default is -\code{None}, so that 0 and 1 are not allowed in the input. - -The decoded string is returned. A \exception{TypeError} is raised if -\var{s} were incorrectly padded or if there are non-alphabet characters -present in the string. -\end{funcdesc} - -\begin{funcdesc}{b16encode}{s} -Encode a string using Base16. - -\var{s} is the string to encode. The encoded string is returned. -\end{funcdesc} - -\begin{funcdesc}{b16decode}{s\optional{, casefold}} -Decode a Base16 encoded string. - -\var{s} is the string to decode. Optional \var{casefold} is a flag -specifying whether a lowercase alphabet is acceptable as input. For -security purposes, the default is \code{False}. - -The decoded string is returned. A \exception{TypeError} is raised if -\var{s} were incorrectly padded or if there are non-alphabet -characters present in the string. -\end{funcdesc} - -The legacy interface: - -\begin{funcdesc}{decode}{input, output} -Decode the contents of the \var{input} file and write the resulting -binary data to the \var{output} file. -\var{input} and \var{output} must either be file objects or objects that -mimic the file object interface. \var{input} will be read until -\code{\var{input}.read()} returns an empty string. -\end{funcdesc} - -\begin{funcdesc}{decodestring}{s} -Decode the string \var{s}, which must contain one or more lines of -base64 encoded data, and return a string containing the resulting -binary data. -\end{funcdesc} - -\begin{funcdesc}{encode}{input, output} -Encode the contents of the \var{input} file and write the resulting -base64 encoded data to the \var{output} file. -\var{input} and \var{output} must either be file objects or objects that -mimic the file object interface. \var{input} will be read until -\code{\var{input}.read()} returns an empty string. \function{encode()} -returns the encoded data plus a trailing newline character -(\code{'\e n'}). -\end{funcdesc} - -\begin{funcdesc}{encodestring}{s} -Encode the string \var{s}, which can contain arbitrary binary data, -and return a string containing one or more lines of -base64-encoded data. \function{encodestring()} returns a -string containing one or more lines of base64-encoded data -always including an extra trailing newline (\code{'\e n'}). -\end{funcdesc} - -An example usage of the module: - -\begin{verbatim} ->>> import base64 ->>> encoded = base64.b64encode('data to be encoded') ->>> encoded -'ZGF0YSB0byBiZSBlbmNvZGVk' ->>> data = base64.b64decode(encoded) ->>> data -'data to be encoded' -\end{verbatim} - -\begin{seealso} - \seemodule{binascii}{Support module containing \ASCII-to-binary - and binary-to-\ASCII{} conversions.} - \seerfc{1521}{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/libbasehttp.tex b/Doc/lib/libbasehttp.tex deleted file mode 100644 index 64c069f..0000000 --- a/Doc/lib/libbasehttp.tex +++ /dev/null @@ -1,245 +0,0 @@ -\section{\module{BaseHTTPServer} --- - Basic HTTP server} - -\declaremodule{standard}{BaseHTTPServer} -\modulesynopsis{Basic HTTP server (base class for - \class{SimpleHTTPServer} and \class{CGIHTTPServer}).} - - -\indexii{WWW}{server} -\indexii{HTTP}{protocol} -\index{URL} -\index{httpd} - -This module defines two classes for implementing HTTP servers -(Web servers). Usually, this module isn't used directly, but is used -as a basis for building functioning Web servers. See the -\refmodule{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and -\refmodule{CGIHTTPServer}\refstmodindex{CGIHTTPServer} modules. - -The first class, \class{HTTPServer}, is a -\class{SocketServer.TCPServer} subclass. It creates and listens at the -HTTP socket, dispatching the requests to a handler. Code to create and -run the server looks like this: - -\begin{verbatim} -def run(server_class=BaseHTTPServer.HTTPServer, - handler_class=BaseHTTPServer.BaseHTTPRequestHandler): - server_address = ('', 8000) - httpd = server_class(server_address, handler_class) - httpd.serve_forever() -\end{verbatim} - -\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass} -This class builds on the \class{TCPServer} class by -storing the server address as instance -variables named \member{server_name} and \member{server_port}. The -server is accessible by the handler, typically through the handler's -\member{server} instance variable. -\end{classdesc} - -\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server} -This class is used -to handle the HTTP requests that arrive at the server. By itself, -it cannot respond to any actual HTTP requests; it must be subclassed -to handle each request method (e.g. GET or POST). -\class{BaseHTTPRequestHandler} provides a number of class and instance -variables, and methods for use by subclasses. - -The handler will parse the request and the headers, then call a -method specific to the request type. The method name is constructed -from the request. For example, for the request method \samp{SPAM}, the -\method{do_SPAM()} method will be called with no arguments. All of -the relevant information is stored in instance variables of the -handler. Subclasses should not need to override or extend the -\method{__init__()} method. -\end{classdesc} - - -\class{BaseHTTPRequestHandler} has the following instance variables: - -\begin{memberdesc}{client_address} -Contains a tuple of the form \code{(\var{host}, \var{port})} referring -to the client's address. -\end{memberdesc} - -\begin{memberdesc}{command} -Contains the command (request type). For example, \code{'GET'}. -\end{memberdesc} - -\begin{memberdesc}{path} -Contains the request path. -\end{memberdesc} - -\begin{memberdesc}{request_version} -Contains the version string from the request. For example, -\code{'HTTP/1.0'}. -\end{memberdesc} - -\begin{memberdesc}{headers} -Holds an instance of the class specified by the \member{MessageClass} -class variable. This instance parses and manages the headers in -the HTTP request. -\end{memberdesc} - -\begin{memberdesc}{rfile} -Contains an input stream, positioned at the start of the optional -input data. -\end{memberdesc} - -\begin{memberdesc}{wfile} -Contains the output stream for writing a response back to the client. -Proper adherence to the HTTP protocol must be used when writing -to this stream. -\end{memberdesc} - - -\class{BaseHTTPRequestHandler} has the following class variables: - -\begin{memberdesc}{server_version} -Specifies the server software version. You may want to override -this. -The format is multiple whitespace-separated strings, -where each string is of the form name[/version]. -For example, \code{'BaseHTTP/0.2'}. -\end{memberdesc} - -\begin{memberdesc}{sys_version} -Contains the Python system version, in a form usable by the -\member{version_string} method and the \member{server_version} class -variable. For example, \code{'Python/1.4'}. -\end{memberdesc} - -\begin{memberdesc}{error_message_format} -Specifies a format string for building an error response to the -client. It uses parenthesized, keyed format specifiers, so the -format operand must be a dictionary. The \var{code} key should -be an integer, specifying the numeric HTTP error code value. -\var{message} should be a string containing a (detailed) error -message of what occurred, and \var{explain} should be an -explanation of the error code number. Default \var{message} -and \var{explain} values can found in the \var{responses} -class variable. -\end{memberdesc} - -\begin{memberdesc}{protocol_version} -This specifies the HTTP protocol version used in responses. If set -to \code{'HTTP/1.1'}, the server will permit HTTP persistent -connections; however, your server \emph{must} then include an -accurate \code{Content-Length} header (using \method{send_header()}) -in all of its responses to clients. For backwards compatibility, -the setting defaults to \code{'HTTP/1.0'}. -\end{memberdesc} - -\begin{memberdesc}{MessageClass} -Specifies a \class{rfc822.Message}-like class to parse HTTP -headers. Typically, this is not overridden, and it defaults to -\class{mimetools.Message}. -\withsubitem{(in module mimetools)}{\ttindex{Message}} -\end{memberdesc} - -\begin{memberdesc}{responses} -This variable contains a mapping of error code integers to two-element -tuples containing a short and long message. For example, -\code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The -\var{shortmessage} is usually used as the \var{message} key in an -error response, and \var{longmessage} as the \var{explain} key -(see the \member{error_message_format} class variable). -\end{memberdesc} - - -A \class{BaseHTTPRequestHandler} instance has the following methods: - -\begin{methoddesc}{handle}{} -Calls \method{handle_one_request()} once (or, if persistent connections -are enabled, multiple times) to handle incoming HTTP requests. -You should never need to override it; instead, implement appropriate -\method{do_*()} methods. -\end{methoddesc} - -\begin{methoddesc}{handle_one_request}{} -This method will parse and dispatch -the request to the appropriate \method{do_*()} method. You should -never need to override it. -\end{methoddesc} - -\begin{methoddesc}{send_error}{code\optional{, message}} -Sends and logs a complete error reply to the client. The numeric -\var{code} specifies the HTTP error code, with \var{message} as -optional, more specific text. A complete set of headers is sent, -followed by text composed using the \member{error_message_format} -class variable. -\end{methoddesc} - -\begin{methoddesc}{send_response}{code\optional{, message}} -Sends a response header and logs the accepted request. The HTTP -response line is sent, followed by \emph{Server} and \emph{Date} -headers. The values for these two headers are picked up from the -\method{version_string()} and \method{date_time_string()} methods, -respectively. -\end{methoddesc} - -\begin{methoddesc}{send_header}{keyword, value} -Writes a specific HTTP header to the output stream. \var{keyword} -should specify the header keyword, with \var{value} specifying -its value. -\end{methoddesc} - -\begin{methoddesc}{end_headers}{} -Sends a blank line, indicating the end of the HTTP headers in -the response. -\end{methoddesc} - -\begin{methoddesc}{log_request}{\optional{code\optional{, size}}} -Logs an accepted (successful) request. \var{code} should specify -the numeric HTTP code associated with the response. If a size of -the response is available, then it should be passed as the -\var{size} parameter. -\end{methoddesc} - -\begin{methoddesc}{log_error}{...} -Logs an error when a request cannot be fulfilled. By default, -it passes the message to \method{log_message()}, so it takes the -same arguments (\var{format} and additional values). -\end{methoddesc} - -\begin{methoddesc}{log_message}{format, ...} -Logs an arbitrary message to \code{sys.stderr}. This is typically -overridden to create custom error logging mechanisms. The -\var{format} argument is a standard printf-style format string, -where the additional arguments to \method{log_message()} are applied -as inputs to the formatting. The client address and current date -and time are prefixed to every message logged. -\end{methoddesc} - -\begin{methoddesc}{version_string}{} -Returns the server software's version string. This is a combination -of the \member{server_version} and \member{sys_version} class variables. -\end{methoddesc} - -\begin{methoddesc}{date_time_string}{\optional{timestamp}} -Returns the date and time given by \var{timestamp} (which must be in the -format returned by \function{time.time()}), formatted for a message header. -If \var{timestamp} is omitted, it uses the current date and time. - -The result looks like \code{'Sun, 06 Nov 1994 08:49:37 GMT'}. -\versionadded[The \var{timestamp} parameter]{2.5} -\end{methoddesc} - -\begin{methoddesc}{log_date_time_string}{} -Returns the current date and time, formatted for logging. -\end{methoddesc} - -\begin{methoddesc}{address_string}{} -Returns the client address, formatted for logging. A name lookup -is performed on the client's IP address. -\end{methoddesc} - - -\begin{seealso} - \seemodule{CGIHTTPServer}{Extended request handler that supports CGI - scripts.} - - \seemodule{SimpleHTTPServer}{Basic request handler that limits response - to files actually under the document root.} -\end{seealso} diff --git a/Doc/lib/libbinascii.tex b/Doc/lib/libbinascii.tex deleted file mode 100644 index 84d29c6..0000000 --- a/Doc/lib/libbinascii.tex +++ /dev/null @@ -1,147 +0,0 @@ -\section{\module{binascii} --- - Convert between binary and \ASCII} - -\declaremodule{builtin}{binascii} -\modulesynopsis{Tools for converting between binary and various - \ASCII-encoded binary representations.} - - -The \module{binascii} module contains a number of methods to convert -between binary and various \ASCII-encoded binary -representations. Normally, you will not use these functions directly -but use wrapper modules like \refmodule{uu}\refstmodindex{uu}, -\refmodule{base64}\refstmodindex{base64}, or -\refmodule{binhex}\refstmodindex{binhex} instead. The \module{binascii} module -contains low-level functions written in C for greater speed -that are used by the higher-level modules. - -The \module{binascii} module defines the following functions: - -\begin{funcdesc}{a2b_uu}{string} -Convert a single line of uuencoded data back to binary and return the -binary data. Lines normally contain 45 (binary) bytes, except for the -last line. Line data may be followed by whitespace. -\end{funcdesc} - -\begin{funcdesc}{b2a_uu}{data} -Convert binary data to a line of \ASCII{} characters, the return value -is the converted line, including a newline char. The length of -\var{data} should be at most 45. -\end{funcdesc} - -\begin{funcdesc}{a2b_base64}{string} -Convert a block of base64 data back to binary and return the -binary data. More than one line may be passed at a time. -\end{funcdesc} - -\begin{funcdesc}{b2a_base64}{data} -Convert binary data to a line of \ASCII{} characters in base64 coding. -The return value is the converted line, including a newline char. -The length of \var{data} should be at most 57 to adhere to the base64 -standard. -\end{funcdesc} - -\begin{funcdesc}{a2b_qp}{string\optional{, header}} -Convert a block of quoted-printable data back to binary and return the -binary data. More than one line may be passed at a time. -If the optional argument \var{header} is present and true, underscores -will be decoded as spaces. -\end{funcdesc} - -\begin{funcdesc}{b2a_qp}{data\optional{, quotetabs, istext, header}} -Convert binary data to a line(s) of \ASCII{} characters in -quoted-printable encoding. The return value is the converted line(s). -If the optional argument \var{quotetabs} is present and true, all tabs -and spaces will be encoded. -If the optional argument \var{istext} is present and true, -newlines are not encoded but trailing whitespace will be encoded. -If the optional argument \var{header} is -present and true, spaces will be encoded as underscores per RFC1522. -If the optional argument \var{header} is present and false, newline -characters will be encoded as well; otherwise linefeed conversion might -corrupt the binary data stream. -\end{funcdesc} - -\begin{funcdesc}{a2b_hqx}{string} -Convert binhex4 formatted \ASCII{} data to binary, without doing -RLE-decompression. The string should contain a complete number of -binary bytes, or (in case of the last portion of the binhex4 data) -have the remaining bits zero. -\end{funcdesc} - -\begin{funcdesc}{rledecode_hqx}{data} -Perform RLE-decompression on the data, as per the binhex4 -standard. The algorithm uses \code{0x90} after a byte as a repeat -indicator, followed by a count. A count of \code{0} specifies a byte -value of \code{0x90}. The routine returns the decompressed data, -unless data input data ends in an orphaned repeat indicator, in which -case the \exception{Incomplete} exception is raised. -\end{funcdesc} - -\begin{funcdesc}{rlecode_hqx}{data} -Perform binhex4 style RLE-compression on \var{data} and return the -result. -\end{funcdesc} - -\begin{funcdesc}{b2a_hqx}{data} -Perform hexbin4 binary-to-\ASCII{} translation and return the -resulting string. The argument should already be RLE-coded, and have a -length divisible by 3 (except possibly the last fragment). -\end{funcdesc} - -\begin{funcdesc}{crc_hqx}{data, crc} -Compute the binhex4 crc value of \var{data}, starting with an initial -\var{crc} and returning the result. -\end{funcdesc} - -\begin{funcdesc}{crc32}{data\optional{, crc}} -Compute CRC-32, the 32-bit checksum of data, starting with an initial -crc. This is consistent with the ZIP file checksum. Since the -algorithm is designed for use as a checksum algorithm, it is not -suitable for use as a general hash algorithm. Use as follows: -\begin{verbatim} - print binascii.crc32("hello world") - # Or, in two pieces: - crc = binascii.crc32("hello") - crc = binascii.crc32(" world", crc) - print crc -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{b2a_hex}{data} -\funcline{hexlify}{data} -Return the hexadecimal representation of the binary \var{data}. Every -byte of \var{data} is converted into the corresponding 2-digit hex -representation. The resulting string is therefore twice as long as -the length of \var{data}. -\end{funcdesc} - -\begin{funcdesc}{a2b_hex}{hexstr} -\funcline{unhexlify}{hexstr} -Return the binary data represented by the hexadecimal string -\var{hexstr}. This function is the inverse of \function{b2a_hex()}. -\var{hexstr} must contain an even number of hexadecimal digits (which -can be upper or lower case), otherwise a \exception{TypeError} is -raised. -\end{funcdesc} - -\begin{excdesc}{Error} -Exception raised on errors. These are usually programming errors. -\end{excdesc} - -\begin{excdesc}{Incomplete} -Exception raised on incomplete data. These are usually not programming -errors, but may be handled by reading a little more data and trying -again. -\end{excdesc} - - -\begin{seealso} - \seemodule{base64}{Support for base64 encoding used in MIME email messages.} - - \seemodule{binhex}{Support for the binhex format used on the Macintosh.} - - \seemodule{uu}{Support for UU encoding used on \UNIX.} - - \seemodule{quopri}{Support for quoted-printable encoding used in MIME email messages. } -\end{seealso} diff --git a/Doc/lib/libbinhex.tex b/Doc/lib/libbinhex.tex deleted file mode 100644 index d30f2b4..0000000 --- a/Doc/lib/libbinhex.tex +++ /dev/null @@ -1,55 +0,0 @@ -\section{\module{binhex} --- - Encode and decode binhex4 files} - -\declaremodule{standard}{binhex} -\modulesynopsis{Encode and decode files in binhex4 format.} - - -This module encodes and decodes files in binhex4 format, a format -allowing representation of Macintosh files in \ASCII. On the Macintosh, -both forks of a file and the finder information are encoded (or -decoded), on other platforms only the data fork is handled. - -The \module{binhex} module defines the following functions: - -\begin{funcdesc}{binhex}{input, output} -Convert a binary file with filename \var{input} to binhex file -\var{output}. The \var{output} parameter can either be a filename or a -file-like object (any object supporting a \method{write()} and -\method{close()} method). -\end{funcdesc} - -\begin{funcdesc}{hexbin}{input\optional{, output}} -Decode a binhex file \var{input}. \var{input} may be a filename or a -file-like object supporting \method{read()} and \method{close()} methods. -The resulting file is written to a file named \var{output}, unless the -argument is omitted in which case the output filename is read from the -binhex file. -\end{funcdesc} - -The following exception is also defined: - -\begin{excdesc}{Error} -Exception raised when something can't be encoded using the binhex -format (for example, a filename is too long to fit in the filename -field), or when input is not properly encoded binhex data. -\end{excdesc} - - -\begin{seealso} - \seemodule{binascii}{Support module containing \ASCII-to-binary - and binary-to-\ASCII{} conversions.} -\end{seealso} - - -\subsection{Notes \label{binhex-notes}} - -There is an alternative, more powerful interface to the coder and -decoder, see the source for details. - -If you code or decode textfiles on non-Macintosh platforms they will -still use the Macintosh newline convention (carriage-return as end of -line). - -As of this writing, \function{hexbin()} appears to not work in all -cases. diff --git a/Doc/lib/libbisect.tex b/Doc/lib/libbisect.tex deleted file mode 100644 index 516e5cf..0000000 --- a/Doc/lib/libbisect.tex +++ /dev/null @@ -1,84 +0,0 @@ -\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 -without having to sort the list after each insertion. For long lists -of items with expensive comparison operations, this can be an -improvement over the more common approach. The module is called -\module{bisect} because it uses a basic bisection algorithm to do its -work. The source code may be most useful as a working example of the -algorithm (the boundary conditions are already right!). - -The following functions are provided: - -\begin{funcdesc}{bisect_left}{list, item\optional{, lo\optional{, hi}}} - Locate the proper insertion point for \var{item} in \var{list} to - maintain sorted order. The parameters \var{lo} and \var{hi} may be - used to specify a subset of the list which should be considered; by - default the entire list is used. If \var{item} is already present - in \var{list}, the insertion point will be before (to the left of) - any existing entries. The return value is suitable for use as the - first parameter to \code{\var{list}.insert()}. This assumes that - \var{list} is already sorted. -\versionadded{2.1} -\end{funcdesc} - -\begin{funcdesc}{bisect_right}{list, item\optional{, lo\optional{, hi}}} - Similar to \function{bisect_left()}, but returns an insertion point - which comes after (to the right of) any existing entries of - \var{item} in \var{list}. -\versionadded{2.1} -\end{funcdesc} - -\begin{funcdesc}{bisect}{\unspecified} - Alias for \function{bisect_right()}. -\end{funcdesc} - -\begin{funcdesc}{insort_left}{list, item\optional{, lo\optional{, hi}}} - Insert \var{item} in \var{list} in sorted order. This is equivalent - to \code{\var{list}.insert(bisect.bisect_left(\var{list}, \var{item}, - \var{lo}, \var{hi}), \var{item})}. This assumes that \var{list} is - already sorted. -\versionadded{2.1} -\end{funcdesc} - -\begin{funcdesc}{insort_right}{list, item\optional{, lo\optional{, hi}}} - Similar to \function{insort_left()}, but inserting \var{item} in - \var{list} after any existing entries of \var{item}. -\versionadded{2.1} -\end{funcdesc} - -\begin{funcdesc}{insort}{\unspecified} - Alias for \function{insort_right()}. -\end{funcdesc} - - -\subsection{Examples} -\nodename{bisect-example} - -The \function{bisect()} function is generally useful for categorizing -numeric data. This example uses \function{bisect()} to look up a -letter grade for an exam total (say) based on a set of ordered numeric -breakpoints: 85 and up is an `A', 75..84 is a `B', etc. - -\begin{verbatim} ->>> grades = "FEDCBA" ->>> breakpoints = [30, 44, 66, 75, 85] ->>> from bisect import bisect ->>> def grade(total): -... return grades[bisect(breakpoints, total)] -... ->>> grade(66) -'C' ->>> map(grade, [33, 99, 77, 44, 12, 88]) -['E', 'A', 'B', 'D', 'F', 'A'] - -\end{verbatim} diff --git a/Doc/lib/libbltin.tex b/Doc/lib/libbltin.tex deleted file mode 100644 index f6abe25..0000000 --- a/Doc/lib/libbltin.tex +++ /dev/null @@ -1,44 +0,0 @@ -\section{\module{__builtin__} --- - Built-in objects} - -\declaremodule[builtin]{builtin}{__builtin__} -\modulesynopsis{The module that provides the built-in namespace.} - - -This module provides direct access to all `built-in' identifiers of -Python; for example, \code{__builtin__.open} is the full name for the -built-in function \function{open()}. See chapter~\ref{builtin}, -``Built-in Objects.'' - -This module is not normally accessed explicitly by most applications, -but can be useful in modules that provide objects with the same name -as a built-in value, but in which the built-in of that name is also -needed. For example, in a module that wants to implement an -\function{open()} function that wraps the built-in \function{open()}, -this module can be used directly: - -\begin{verbatim} -import __builtin__ - -def open(path): - f = __builtin__.open(path, 'r') - return UpperCaser(f) - -class UpperCaser: - '''Wrapper around a file that converts output to upper-case.''' - - def __init__(self, f): - self._f = f - - def read(self, count=-1): - return self._f.read(count).upper() - - # ... -\end{verbatim} - -As an implementation detail, most modules have the name -\code{__builtins__} (note the \character{s}) made available as part of -their globals. The value of \code{__builtins__} is normally either -this module or the value of this modules's \member{__dict__} -attribute. Since this is an implementation detail, it may not be used -by alternate implementations of Python. diff --git a/Doc/lib/libbsddb.tex b/Doc/lib/libbsddb.tex deleted file mode 100644 index 8f23324..0000000 --- a/Doc/lib/libbsddb.tex +++ /dev/null @@ -1,211 +0,0 @@ -\section{\module{bsddb} --- - Interface to Berkeley DB library} - -\declaremodule{extension}{bsddb} -\modulesynopsis{Interface to Berkeley DB database library} -\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 \function{marshal.dumps()} or -\function{pickle.dumps()}. - -The \module{bsddb} module requires a Berkeley DB library version from -3.3 thru 4.5. - -\begin{seealso} - \seeurl{http://pybsddb.sourceforge.net/} - {The website with documentation for the \module{bsddb.db} - Python Berkeley DB interface that closely mirrors the object - oriented interface provided in Berkeley DB 3 and 4.} - - \seeurl{http://www.oracle.com/database/berkeley-db/} - {The Berkeley DB library.} -\end{seealso} - -A more modern DB, DBEnv and DBSequence object interface is available in the -\module{bsddb.db} module which closely matches the Berkeley DB C API -documented at the above URLs. Additional features provided by the -\module{bsddb.db} API include fine tuning, transactions, logging, and -multiprocess concurrent database access. - -The following is a description of the legacy \module{bsddb} interface -compatible with the old Python bsddb module. Starting in Python 2.5 this -interface should be safe for multithreaded access. The \module{bsddb.db} -API is recommended for threading users as it provides better control. - -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. - -\begin{funcdesc}{hashopen}{filename\optional{, flag\optional{, - mode\optional{, pgsize\optional{, - ffactor\optional{, nelem\optional{, - cachesize\optional{, lorder\optional{, - hflags}}}}}}}}} -Open the hash format file named \var{filename}. Files never intended -to be preserved on disk may be created by passing \code{None} as the -\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; the default) 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{, pgsize\optional{, lorder}}}}}}}}} - -Open the btree format file named \var{filename}. Files never intended -to be preserved on disk may be created by passing \code{None} as the -\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; the default) 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{, pgsize\optional{, lorder\optional{, -rlen\optional{, delim\optional{, source\optional{, pad}}}}}}}}}}} - -Open a DB record format file named \var{filename}. Files never intended -to be preserved on disk may be created by passing \code{None} as the -\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; the default) 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{classdesc}{StringKeys}{db} - Wrapper class around a DB object that supports string keys - (rather than bytes). All keys are encoded as UTF-8, then passed - to the underlying object. \versionadded{3.0} -\end{classdesc} - -\begin{classdesc}{StringValues}{db} - Wrapper class around a DB object that supports string values - (rather than bytes). All values are encoded as UTF-8, then passed - to the underlying object. \versionadded{3.0} -\end{classdesc} - -\begin{seealso} - \seemodule{dbhash}{DBM-style interface to the \module{bsddb}} -\end{seealso} - -\subsection{Hash, BTree and Record Objects \label{bsddb-objects}} - -Once instantiated, hash, btree and record objects support -the same methods as dictionaries. In addition, they support -the methods listed below. -\versionchanged[Added dictionary methods]{2.3.1} - -\begin{methoddesc}[bsddbobject]{close}{} -Close the underlying file. The object can no longer be accessed. Since -there is no open \method{open} method for these objects, to open the file -again a new \module{bsddb} module open function must be called. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{keys}{} -Return the list of keys contained in the DB file. The order of the list is -unspecified and should not be relied on. In particular, the order of the -list returned is different for different file formats. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{has_key}{key} -Return \code{1} if the DB file contains the argument as a key. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{set_location}{key} -Set the cursor to the item indicated by \var{key} and return a tuple -containing the key and its value. For binary tree databases (opened -using \function{btopen()}), if \var{key} does not actually exist in -the database, the cursor will point to the next item in sorted order -and return that key and value. For other databases, -\exception{KeyError} will be raised if \var{key} is not found in the -database. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{first}{} -Set the cursor to the first item in the DB file and return it. The order of -keys in the file is unspecified, except in the case of B-Tree databases. -This method raises \exception{bsddb.error} if the database is empty. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{next}{} -Set the cursor to the next item in the DB file and return it. The order of -keys in the file is unspecified, except in the case of B-Tree databases. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{previous}{} -Set the cursor to the previous item in the DB file and return it. The -order of keys in the file is unspecified, except in the case of B-Tree -databases. This is not supported on hashtable databases (those opened -with \function{hashopen()}). -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{last}{} -Set the cursor to the last item in the DB file and return it. The -order of keys in the file is unspecified. This is not supported on -hashtable databases (those opened with \function{hashopen()}). -This method raises \exception{bsddb.error} if the database is empty. -\end{methoddesc} - -\begin{methoddesc}[bsddbobject]{sync}{} -Synchronize the database on disk. -\end{methoddesc} - -Example: - -\begin{verbatim} ->>> import bsddb ->>> db = bsddb.btopen('/tmp/spam.db', 'c') ->>> for i in range(10): db['%d'%i] = '%d'% (i*i) -... ->>> db['3'] -'9' ->>> db.keys() -['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] ->>> db.first() -('0', '0') ->>> db.next() -('1', '1') ->>> db.last() -('9', '81') ->>> db.set_location('2') -('2', '4') ->>> db.previous() -('1', '1') ->>> for k, v in db.iteritems(): -... print k, v -0 0 -1 1 -2 4 -3 9 -4 16 -5 25 -6 36 -7 49 -8 64 -9 81 ->>> '8' in db -True ->>> db.sync() -0 -\end{verbatim} diff --git a/Doc/lib/libbz2.tex b/Doc/lib/libbz2.tex deleted file mode 100644 index 36bc0d2..0000000 --- a/Doc/lib/libbz2.tex +++ /dev/null @@ -1,165 +0,0 @@ -\section{\module{bz2} --- - Compression compatible with \program{bzip2}} - -\declaremodule{builtin}{bz2} -\modulesynopsis{Interface to compression and decompression - routines compatible with \program{bzip2}.} -\moduleauthor{Gustavo Niemeyer}{niemeyer@conectiva.com} -\sectionauthor{Gustavo Niemeyer}{niemeyer@conectiva.com} - -\versionadded{2.3} - -This module provides a comprehensive interface for the bz2 compression library. -It implements a complete file interface, one-shot (de)compression functions, -and types for sequential (de)compression. - -Here is a resume of the features offered by the bz2 module: - -\begin{itemize} -\item \class{BZ2File} class implements a complete file interface, including - \method{readline()}, \method{readlines()}, - \method{writelines()}, \method{seek()}, etc; -\item \class{BZ2File} class implements emulated \method{seek()} support; -\item \class{BZ2File} class implements universal newline support; -\item \class{BZ2File} class offers an optimized line iteration using - the readahead algorithm borrowed from file objects; -\item Sequential (de)compression supported by \class{BZ2Compressor} and - \class{BZ2Decompressor} classes; -\item One-shot (de)compression supported by \function{compress()} and - \function{decompress()} functions; -\item Thread safety uses individual locking mechanism; -\item Complete inline documentation; -\end{itemize} - - -\subsection{(De)compression of files} - -Handling of compressed files is offered by the \class{BZ2File} class. - -\begin{classdesc}{BZ2File}{filename\optional{, mode\optional{, - buffering\optional{, compresslevel}}}} -Open a bz2 file. Mode can be either \code{'r'} or \code{'w'}, for reading -(default) or writing. When opened for writing, the file will be created if -it doesn't exist, and truncated otherwise. If \var{buffering} is given, -\code{0} means unbuffered, and larger numbers specify the buffer size; -the default is \code{0}. If -\var{compresslevel} is given, it must be a number between \code{1} and -\code{9}; the default is \code{9}. -Add a \character{U} to mode to open the file for input with universal newline -support. Any line ending in the input file will be seen as a -\character{\e n} in Python. Also, a file so opened gains the -attribute \member{newlines}; the value for this attribute is one of -\code{None} (no newline read yet), \code{'\e r'}, \code{'\e n'}, -\code{'\e r\e n'} or a tuple containing all the newline types -seen. Universal newlines are available only when reading. -Instances support iteration in the same way as normal \class{file} -instances. -\end{classdesc} - -\begin{methoddesc}[BZ2File]{close}{} -Close the file. Sets data attribute \member{closed} to true. A closed file -cannot be used for further I/O operations. \method{close()} may be called -more than once without error. -\end{methoddesc} - -\begin{methoddesc}[BZ2File]{read}{\optional{size}} -Read at most \var{size} uncompressed bytes, returned as a string. If the -\var{size} argument is negative or omitted, read until EOF is reached. -\end{methoddesc} - -\begin{methoddesc}[BZ2File]{readline}{\optional{size}} -Return the next line from the file, as a string, retaining newline. -A non-negative \var{size} argument limits the maximum number of bytes to -return (an incomplete line may be returned then). Return an empty -string at EOF. -\end{methoddesc} - -\begin{methoddesc}[BZ2File]{readlines}{\optional{size}} -Return a list of lines read. The optional \var{size} argument, if given, -is an approximate bound on the total number of bytes in the lines returned. -\end{methoddesc} - -\begin{methoddesc}[BZ2File]{seek}{offset\optional{, whence}} -Move to new file position. Argument \var{offset} is a byte count. Optional -argument \var{whence} defaults to \code{os.SEEK_SET} or \code{0} (offset from start of file; -offset should be \code{>= 0}); other values are \code{os.SEEK_CUR} or \code{1} (move relative to -current position; offset can be positive or negative), and \code{os.SEEK_END} or \code{2} (move relative to end -of file; offset is usually negative, although many platforms allow seeking beyond -the end of a file). - -Note that seeking of bz2 files is emulated, and depending on the parameters -the operation may be extremely slow. -\end{methoddesc} - -\begin{methoddesc}[BZ2File]{tell}{} -Return the current file position, an integer (may be a long integer). -\end{methoddesc} - -\begin{methoddesc}[BZ2File]{write}{data} -Write string \var{data} to file. Note that due to buffering, \method{close()} -may be needed before the file on disk reflects the data written. -\end{methoddesc} - -\begin{methoddesc}[BZ2File]{writelines}{sequence_of_strings} -Write the sequence of strings to the file. Note that newlines are not added. -The sequence can be any iterable object producing strings. This is equivalent -to calling write() for each string. -\end{methoddesc} - - -\subsection{Sequential (de)compression} - -Sequential compression and decompression is done using the classes -\class{BZ2Compressor} and \class{BZ2Decompressor}. - -\begin{classdesc}{BZ2Compressor}{\optional{compresslevel}} -Create a new compressor object. This object may be used to compress -data sequentially. If you want to compress data in one shot, use the -\function{compress()} function instead. The \var{compresslevel} parameter, -if given, must be a number between \code{1} and \code{9}; the default -is \code{9}. -\end{classdesc} - -\begin{methoddesc}[BZ2Compressor]{compress}{data} -Provide more data to the compressor object. It will return chunks of compressed -data whenever possible. When you've finished providing data to compress, call -the \method{flush()} method to finish the compression process, and return what -is left in internal buffers. -\end{methoddesc} - -\begin{methoddesc}[BZ2Compressor]{flush}{} -Finish the compression process and return what is left in internal buffers. You -must not use the compressor object after calling this method. -\end{methoddesc} - -\begin{classdesc}{BZ2Decompressor}{} -Create a new decompressor object. This object may be used to decompress -data sequentially. If you want to decompress data in one shot, use the -\function{decompress()} function instead. -\end{classdesc} - -\begin{methoddesc}[BZ2Decompressor]{decompress}{data} -Provide more data to the decompressor object. It will return chunks of -decompressed data whenever possible. If you try to decompress data after the -end of stream is found, \exception{EOFError} will be raised. If any data was -found after the end of stream, it'll be ignored and saved in -\member{unused\_data} attribute. -\end{methoddesc} - - -\subsection{One-shot (de)compression} - -One-shot compression and decompression is provided through the -\function{compress()} and \function{decompress()} functions. - -\begin{funcdesc}{compress}{data\optional{, compresslevel}} -Compress \var{data} in one shot. If you want to compress data sequentially, -use an instance of \class{BZ2Compressor} instead. The \var{compresslevel} -parameter, if given, must be a number between \code{1} and \code{9}; -the default is \code{9}. -\end{funcdesc} - -\begin{funcdesc}{decompress}{data} -Decompress \var{data} in one shot. If you want to decompress data -sequentially, use an instance of \class{BZ2Decompressor} instead. -\end{funcdesc} diff --git a/Doc/lib/libcalendar.tex b/Doc/lib/libcalendar.tex deleted file mode 100644 index acfd2da..0000000 --- a/Doc/lib/libcalendar.tex +++ /dev/null @@ -1,304 +0,0 @@ -\section{\module{calendar} --- - General calendar-related functions} - -\declaremodule{standard}{calendar} -\modulesynopsis{Functions for working with calendars, - 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{} -\program{cal} program, and provides additional useful functions -related to the calendar. By default, these calendars have Monday as -the first day of the week, and Sunday as the last (the European -convention). Use \function{setfirstweekday()} to set the first day of the -week to Sunday (6) or to any other weekday. Parameters that specify -dates are given as integers. - -Most of these functions and classses rely on the \module{datetime} -module which uses an idealized calendar, the current Gregorian -calendar indefinitely extended in both directions. This matches -the definition of the "proleptic Gregorian" calendar in Dershowitz -and Reingold's book "Calendrical Calculations", where it's the -base calendar for all computations. - -\begin{classdesc}{Calendar}{\optional{firstweekday}} -Creates a \class{Calendar} object. \var{firstweekday} is an integer -specifying the first day of the week. \code{0} is Monday (the default), -\code{6} is Sunday. - -A \class{Calendar} object provides several methods that can -be used for preparing the calendar data for formatting. This -class doesn't do any formatting itself. This is the job of -subclasses. -\versionadded{2.5} -\end{classdesc} - -\class{Calendar} instances have the following methods: - -\begin{methoddesc}{iterweekdays}{weekday} -Return an iterator for the week day numbers that will be used -for one week. The first number from the iterator will be the -same as the number returned by \method{firstweekday()}. -\end{methoddesc} - -\begin{methoddesc}{itermonthdates}{year, month} -Return an iterator for the month \var{month} (1-12) in the -year \var{year}. This iterator will return all days (as -\class{datetime.date} objects) for the month and all days -before the start of the month or after the end of the month -that are required to get a complete week. -\end{methoddesc} - -\begin{methoddesc}{itermonthdays2}{year, month} -Return an iterator for the month \var{month} in the year -\var{year} similar to \method{itermonthdates()}. Days returned -will be tuples consisting of a day number and a week day -number. -\end{methoddesc} - -\begin{methoddesc}{itermonthdays}{year, month} -Return an iterator for the month \var{month} in the year -\var{year} similar to \method{itermonthdates()}. Days returned -will simply be day numbers. -\end{methoddesc} - -\begin{methoddesc}{monthdatescalendar}{year, month} -Return a list of the weeks in the month \var{month} of -the \var{year} as full weeks. Weeks are lists of seven -\class{datetime.date} objects. -\end{methoddesc} - -\begin{methoddesc}{monthdays2calendar}{year, month} -Return a list of the weeks in the month \var{month} of -the \var{year} as full weeks. Weeks are lists of seven -tuples of day numbers and weekday numbers. -\end{methoddesc} - -\begin{methoddesc}{monthdayscalendar}{year, month} -Return a list of the weeks in the month \var{month} of -the \var{year} as full weeks. Weeks are lists of seven -day numbers. -\end{methoddesc} - -\begin{methoddesc}{yeardatescalendar}{year, month\optional{, width}} -Return the data for the specified year ready for formatting. The return -value is a list of month rows. Each month row contains up to \var{width} -months (defaulting to 3). Each month contains between 4 and 6 weeks and -each week contains 1--7 days. Days are \class{datetime.date} objects. -\end{methoddesc} - -\begin{methoddesc}{yeardays2calendar}{year, month\optional{, width}} -Return the data for the specified year ready for formatting (similar to -\method{yeardatescalendar()}). Entries in the week lists are tuples of -day numbers and weekday numbers. Day numbers outside this month are zero. -\end{methoddesc} - -\begin{methoddesc}{yeardayscalendar}{year, month\optional{, width}} -Return the data for the specified year ready for formatting (similar to -\method{yeardatescalendar()}). Entries in the week lists are day numbers. -Day numbers outside this month are zero. -\end{methoddesc} - - -\begin{classdesc}{TextCalendar}{\optional{firstweekday}} -This class can be used to generate plain text calendars. - -\versionadded{2.5} -\end{classdesc} - -\class{TextCalendar} instances have the following methods: - -\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, w\optional{, l}}} -Return a month's calendar in a multi-line string. If \var{w} is -provided, it specifies the width of the date columns, which are -centered. If \var{l} is given, it specifies the number of lines that -each week will use. Depends on the first weekday as set by -\function{setfirstweekday()}. -\end{methoddesc} - -\begin{methoddesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}} -Print a month's calendar as returned by \method{formatmonth()}. -\end{methoddesc} - -\begin{methoddesc}{formatyear}{theyear, themonth\optional{, w\optional{, - l\optional{, c\optional{, m}}}}} -Return a \var{m}-column calendar for an entire year as a multi-line string. -Optional parameters \var{w}, \var{l}, and \var{c} are for date column -width, lines per week, and number of spaces between month columns, -respectively. Depends on the first weekday as set by -\method{setfirstweekday()}. The earliest year for which a calendar can -be generated is platform-dependent. -\end{methoddesc} - -\begin{methoddesc}{pryear}{theyear\optional{, w\optional{, l\optional{, - c\optional{, m}}}}} -Print the calendar for an entire year as returned by \method{formatyear()}. -\end{methoddesc} - - -\begin{classdesc}{HTMLCalendar}{\optional{firstweekday}} -This class can be used to generate HTML calendars. - -\versionadded{2.5} -\end{classdesc} - -\class{HTMLCalendar} instances have the following methods: - -\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, withyear}} -Return a month's calendar as an HTML table. If \var{withyear} is -true the year will be included in the header, otherwise just the -month name will be used. -\end{methoddesc} - -\begin{methoddesc}{formatyear}{theyear, themonth\optional{, width}} -Return a year's calendar as an HTML table. \var{width} (defaulting to 3) -specifies the number of months per row. -\end{methoddesc} - -\begin{methoddesc}{formatyearpage}{theyear, themonth\optional{, - width\optional{, css\optional{, encoding}}}} -Return a year's calendar as a complete HTML page. \var{width} -(defaulting to 3) specifies the number of months per row. \var{css} -is the name for the cascading style sheet to be used. \constant{None} -can be passed if no style sheet should be used. \var{encoding} -specifies the encoding to be used for the output (defaulting -to the system default encoding). -\end{methoddesc} - - -\begin{classdesc}{LocaleTextCalendar}{\optional{firstweekday\optional{, locale}}} -This subclass of \class{TextCalendar} can be passed a locale name in the -constructor and will return month and weekday names in the specified locale. -If this locale includes an encoding all strings containing month and weekday -names will be returned as unicode. -\versionadded{2.5} -\end{classdesc} - - -\begin{classdesc}{LocaleHTMLCalendar}{\optional{firstweekday\optional{, locale}}} -This subclass of \class{HTMLCalendar} can be passed a locale name in the -constructor and will return month and weekday names in the specified locale. -If this locale includes an encoding all strings containing month and weekday -names will be returned as unicode. -\versionadded{2.5} -\end{classdesc} - - -For simple text calendars this module provides the following functions. - -\begin{funcdesc}{setfirstweekday}{weekday} -Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start -each week. The values \constant{MONDAY}, \constant{TUESDAY}, -\constant{WEDNESDAY}, \constant{THURSDAY}, \constant{FRIDAY}, -\constant{SATURDAY}, and \constant{SUNDAY} are provided for -convenience. For example, to set the first weekday to Sunday: - -\begin{verbatim} -import calendar -calendar.setfirstweekday(calendar.SUNDAY) -\end{verbatim} -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{firstweekday}{} -Returns the current setting for the weekday to start each week. -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{isleap}{year} -Returns \constant{True} if \var{year} is a leap year, otherwise -\constant{False}. -\end{funcdesc} - -\begin{funcdesc}{leapdays}{y1, y2} -Returns the number of leap years in the range -[\var{y1}\ldots\var{y2}), where \var{y1} and \var{y2} are years. -\versionchanged[This function didn't work for ranges spanning - a century change in Python 1.5.2]{2.0} -\end{funcdesc} - -\begin{funcdesc}{weekday}{year, month, day} -Returns the day of the week (\code{0} is Monday) for \var{year} -(\code{1970}--\ldots), \var{month} (\code{1}--\code{12}), \var{day} -(\code{1}--\code{31}). -\end{funcdesc} - -\begin{funcdesc}{weekheader}{n} -Return a header containing abbreviated weekday names. \var{n} specifies -the width in characters for one weekday. -\end{funcdesc} - -\begin{funcdesc}{monthrange}{year, month} -Returns weekday of first day of the month and number of days in month, -for the specified \var{year} and \var{month}. -\end{funcdesc} - -\begin{funcdesc}{monthcalendar}{year, month} -Returns a matrix representing a month's calendar. Each row represents -a week; days outside of the month a represented by zeros. -Each week begins with Monday unless set by \function{setfirstweekday()}. -\end{funcdesc} - -\begin{funcdesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}} -Prints a month's calendar as returned by \function{month()}. -\end{funcdesc} - -\begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}} -Returns a month's calendar in a multi-line string using the -\method{formatmonth} of the \class{TextCalendar} class. -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{prcal}{year\optional{, w\optional{, l\optional{c}}}} -Prints the calendar for an entire year as returned by -\function{calendar()}. -\end{funcdesc} - -\begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}} -Returns a 3-column calendar for an entire year as a multi-line string -using the \method{formatyear} of the \class{TextCalendar} class. -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{timegm}{tuple} -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{time.gmtime()} and \function{timegm()} are each others' inverse. -\versionadded{2.0} -\end{funcdesc} - -The \module{calendar} module exports the following data attributes: - -\begin{datadesc}{day_name} -An array that represents the days of the week in the -current locale. -\end{datadesc} - -\begin{datadesc}{day_abbr} -An array that represents the abbreviated days of the week -in the current locale. -\end{datadesc} - -\begin{datadesc}{month_name} -An array that represents the months of the year in the -current locale. This follows normal convention -of January being month number 1, so it has a length of 13 and -\code{month_name[0]} is the empty string. -\end{datadesc} - -\begin{datadesc}{month_abbr} -An array that represents the abbreviated months of the year -in the current locale. This follows normal convention -of January being month number 1, so it has a length of 13 and -\code{month_abbr[0]} is the empty string. -\end{datadesc} - -\begin{seealso} - \seemodule{datetime}{Object-oriented interface to dates and times - with similar functionality to the - \refmodule{time} module.} - \seemodule{time}{Low-level time related functions.} -\end{seealso} diff --git a/Doc/lib/libcfgparser.tex b/Doc/lib/libcfgparser.tex deleted file mode 100644 index a41aee1..0000000 --- a/Doc/lib/libcfgparser.tex +++ /dev/null @@ -1,322 +0,0 @@ -\section{\module{ConfigParser} --- - Configuration file parser} - -\declaremodule{standard}{ConfigParser} -\modulesynopsis{Configuration file parser.} -\moduleauthor{Ken Manheimer}{klm@zope.com} -\moduleauthor{Barry Warsaw}{bwarsaw@python.org} -\moduleauthor{Eric S. Raymond}{esr@thyrsus.com} -\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org} - -This module defines the class \class{ConfigParser}. -\indexii{.ini}{file}\indexii{configuration}{file}\index{ini file} -\index{Windows ini file} -The \class{ConfigParser} class implements a basic configuration file -parser language which provides a structure similar to what you would -find on Microsoft Windows INI files. You can use this to write Python -programs which can be customized by end users easily. - -\begin{notice}[warning] - This library does \emph{not} interpret or write the value-type - prefixes used in the Windows Registry extended version of INI syntax. -\end{notice} - -The configuration file consists of sections, led 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. 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 on -initialization and retrieval. Lines beginning with \character{\#} or -\character{;} are ignored and may be used to provide comments. - -For example: - -\begin{verbatim} -[My Section] -foodir: %(dir)s/whatever -dir=frob -\end{verbatim} - -would resolve the \samp{\%(dir)s} to the value of -\samp{dir} (\samp{frob} in this case). All reference expansions are -done on demand. - -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. - -Sections are normally stored in a builtin dictionary. An alternative -dictionary type can be passed to the \class{ConfigParser} constructor. -For example, if a dictionary type is passed that sorts its keys, -the sections will be sorted on write-back, as will be the keys within -each section. - -\begin{classdesc}{RawConfigParser}{\optional{defaults\optional{, dict_type}}} -The basic configuration object. When \var{defaults} is given, it is -initialized into the dictionary of intrinsic defaults. When \var{dict_type} -is given, it will be used to create the dictionary objects for the list -of sections, for the options within a section, and for the default values. -This class does not support the magical interpolation behavior. -\versionadded{2.3} -\versionchanged[\var{dict_type} was added]{2.6} -\end{classdesc} - -\begin{classdesc}{ConfigParser}{\optional{defaults}} -Derived class of \class{RawConfigParser} that implements the magical -interpolation feature and adds optional arguments to the \method{get()} -and \method{items()} methods. The values in \var{defaults} must be -appropriate for the \samp{\%()s} string interpolation. Note that -\var{__name__} is an intrinsic default; its value is the section name, -and will override any value provided in \var{defaults}. - -All option names used in interpolation will be passed through the -\method{optionxform()} method just like any other option name -reference. For example, using the default implementation of -\method{optionxform()} (which converts option names to lower case), -the values \samp{foo \%(bar)s} and \samp{foo \%(BAR)s} are -equivalent. -\end{classdesc} - -\begin{classdesc}{SafeConfigParser}{\optional{defaults}} -Derived class of \class{ConfigParser} that implements a more-sane -variant of the magical interpolation feature. This implementation is -more predictable as well. -% XXX Need to explain what's safer/more predictable about it. -New applications should prefer this version if they don't need to be -compatible with older versions of Python. -\versionadded{2.3} -\end{classdesc} - -\begin{excdesc}{NoSectionError} -Exception raised when a specified section is not found. -\end{excdesc} - -\begin{excdesc}{DuplicateSectionError} -Exception raised if \method{add_section()} is called with the name of -a section that is already present. -\end{excdesc} - -\begin{excdesc}{NoOptionError} -Exception raised when a specified option is not found in the specified -section. -\end{excdesc} - -\begin{excdesc}{InterpolationError} -Base class for exceptions raised when problems occur performing string -interpolation. -\end{excdesc} - -\begin{excdesc}{InterpolationDepthError} -Exception raised when string interpolation cannot be completed because -the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}. -Subclass of \exception{InterpolationError}. -\end{excdesc} - -\begin{excdesc}{InterpolationMissingOptionError} -Exception raised when an option referenced from a value does not exist. -Subclass of \exception{InterpolationError}. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{InterpolationSyntaxError} -Exception raised when the source text into which substitutions are -made does not conform to the required syntax. -Subclass of \exception{InterpolationError}. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{MissingSectionHeaderError} -Exception raised when attempting to parse a file which has no section -headers. -\end{excdesc} - -\begin{excdesc}{ParsingError} -Exception raised when errors occur attempting to parse a file. -\end{excdesc} - -\begin{datadesc}{MAX_INTERPOLATION_DEPTH} -The maximum depth for recursive interpolation for \method{get()} when -the \var{raw} parameter is false. This is relevant only for the -\class{ConfigParser} class. -\end{datadesc} - - -\begin{seealso} - \seemodule{shlex}{Support for a creating \UNIX{} shell-like - mini-languages which can be used as an alternate - format for application configuration files.} -\end{seealso} - - -\subsection{RawConfigParser Objects \label{RawConfigParser-objects}} - -\class{RawConfigParser} instances have the following methods: - -\begin{methoddesc}[RawConfigParser]{defaults}{} -Return a dictionary containing the instance-wide defaults. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{sections}{} -Return a list of the sections available; \code{DEFAULT} is not -included in the list. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{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}[RawConfigParser]{has_section}{section} -Indicates whether the named section is present in the -configuration. The \code{DEFAULT} section is not acknowledged. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{options}{section} -Returns a list of options available in the specified \var{section}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{has_option}{section, option} -If the given section exists, and contains the given option, -return \constant{True}; otherwise return \constant{False}. -\versionadded{1.6} -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{read}{filenames} -Attempt to read and parse a list of filenames, returning a list of filenames -which were successfully parsed. If \var{filenames} is a string or -Unicode string, it is treated as a single filename. -If a file named in \var{filenames} cannot be opened, that file will be -ignored. This is designed so that you can specify a list of potential -configuration file locations (for example, the current directory, the -user's home directory, and some system-wide directory), and all -existing configuration files in the list will be read. If none of the -named files exist, the \class{ConfigParser} instance will contain an -empty dataset. An application which requires initial values to be -loaded from a file should load the required file or files using -\method{readfp()} before calling \method{read()} for any optional -files: - -\begin{verbatim} -import ConfigParser, os - -config = ConfigParser.ConfigParser() -config.readfp(open('defaults.cfg')) -config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')]) -\end{verbatim} -\versionchanged[Returns list of successfully parsed filenames]{2.4} -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{readfp}{fp\optional{, filename}} -Read and parse configuration data from the file or file-like object in -\var{fp} (only the \method{readline()} method is used). If -\var{filename} is omitted and \var{fp} has a \member{name} attribute, -that is used for \var{filename}; the default is \samp{<???>}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{get}{section, option} -Get an \var{option} value for the named \var{section}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{getint}{section, option} -A convenience method which coerces the \var{option} in the specified -\var{section} to an integer. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{getfloat}{section, option} -A convenience method which coerces the \var{option} in the specified -\var{section} to a floating point number. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{getboolean}{section, option} -A convenience method which coerces the \var{option} in the specified -\var{section} to a Boolean value. Note that the accepted values -for the option are \code{"1"}, \code{"yes"}, \code{"true"}, and \code{"on"}, -which cause this method to return \code{True}, and \code{"0"}, \code{"no"}, -\code{"false"}, and \code{"off"}, which cause it to return \code{False}. These -string values are checked in a case-insensitive manner. Any other value will -cause it to raise \exception{ValueError}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{items}{section} -Return a list of \code{(\var{name}, \var{value})} pairs for each -option in the given \var{section}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{set}{section, option, value} -If the given section exists, set the given option to the specified -value; otherwise raise \exception{NoSectionError}. While it is -possible to use \class{RawConfigParser} (or \class{ConfigParser} with -\var{raw} parameters set to true) for \emph{internal} storage of -non-string values, full functionality (including interpolation and -output to files) can only be achieved using string values. -\versionadded{1.6} -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{write}{fileobject} -Write a representation of the configuration to the specified file -object. This representation can be parsed by a future \method{read()} -call. -\versionadded{1.6} -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{remove_option}{section, option} -Remove the specified \var{option} from the specified \var{section}. -If the section does not exist, raise \exception{NoSectionError}. -If the option existed to be removed, return \constant{True}; -otherwise return \constant{False}. -\versionadded{1.6} -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{remove_section}{section} -Remove the specified \var{section} from the configuration. -If the section in fact existed, return \code{True}. -Otherwise return \code{False}. -\end{methoddesc} - -\begin{methoddesc}[RawConfigParser]{optionxform}{option} -Transforms the option name \var{option} as found in an input file or -as passed in by client code to the form that should be used in the -internal structures. The default implementation returns a lower-case -version of \var{option}; subclasses may override this or client code -can set an attribute of this name on instances to affect this -behavior. Setting this to \function{str()}, for example, would make -option names case sensitive. -\end{methoddesc} - - -\subsection{ConfigParser Objects \label{ConfigParser-objects}} - -The \class{ConfigParser} class extends some methods of the -\class{RawConfigParser} interface, adding some optional arguments. - -\begin{methoddesc}[ConfigParser]{get}{section, option\optional{, raw\optional{, vars}}} -Get an \var{option} value for the named \var{section}. All the -\character{\%} interpolations are expanded in the return values, based -on the defaults passed into the constructor, as well as the options -\var{vars} provided, unless the \var{raw} argument is true. -\end{methoddesc} - -\begin{methoddesc}[ConfigParser]{items}{section\optional{, raw\optional{, vars}}} -Return a list of \code{(\var{name}, \var{value})} pairs for each -option in the given \var{section}. Optional arguments have the -same meaning as for the \method{get()} method. -\versionadded{2.3} -\end{methoddesc} - - -\subsection{SafeConfigParser Objects \label{SafeConfigParser-objects}} - -The \class{SafeConfigParser} class implements the same extended -interface as \class{ConfigParser}, with the following addition: - -\begin{methoddesc}[SafeConfigParser]{set}{section, option, value} -If the given section exists, set the given option to the specified -value; otherwise raise \exception{NoSectionError}. \var{value} must -be a string (\class{str} or \class{unicode}); if not, -\exception{TypeError} is raised. -\versionadded{2.4} -\end{methoddesc} diff --git a/Doc/lib/libcgi.tex b/Doc/lib/libcgi.tex deleted file mode 100644 index 1dd7e03..0000000 --- a/Doc/lib/libcgi.tex +++ /dev/null @@ -1,602 +0,0 @@ -\section{\module{cgi} --- - Common Gateway Interface support.} -\declaremodule{standard}{cgi} - -\modulesynopsis{Common Gateway Interface support, used to interpret -forms in server-side scripts.} - -\indexii{WWW}{server} -\indexii{CGI}{protocol} -\indexii{HTTP}{protocol} -\indexii{MIME}{headers} -\index{URL} - - -Support module for Common Gateway Interface (CGI) scripts.% -\index{Common Gateway Interface} - -This module defines a number of utilities for use by CGI scripts -written in Python. - -\subsection{Introduction} -\nodename{cgi-intro} - -A CGI script is invoked by an HTTP server, usually to process user -input submitted through an HTML \code{<FORM>} or \code{<ISINDEX>} element. - -Most often, CGI scripts live in the server's special \file{cgi-bin} -directory. The HTTP server places all sorts of information about the -request (such as the client's hostname, the requested URL, the query -string, and lots of other goodies) in the script's shell environment, -executes the script, and sends the script's output back to the client. - -The script's input is connected to the client too, and sometimes the -form data is read this way; at other times the form data is passed via -the ``query string'' part of the URL. This module is intended -to take care of the different cases and provide a simpler interface to -the Python script. It also provides a number of utilities that help -in debugging scripts, and the latest addition is support for file -uploads from a form (if your browser supports it). - -The output of a CGI script should consist of two sections, separated -by a blank line. The first section contains a number of headers, -telling the client what kind of data is following. Python code to -generate a minimal header section looks like this: - -\begin{verbatim} -print "Content-Type: text/html" # HTML is following -print # blank line, end of headers -\end{verbatim} - -The second section is usually HTML, which allows the client software -to display nicely formatted text with header, in-line images, etc. -Here's Python code that prints a simple piece of HTML: - -\begin{verbatim} -print "<TITLE>CGI script output</TITLE>" -print "<H1>This is my first CGI script</H1>" -print "Hello, world!" -\end{verbatim} - -\subsection{Using the cgi module} -\nodename{Using the cgi module} - -Begin by writing \samp{import cgi}. Do not use \samp{from cgi import -*} --- the module defines all sorts of names for its own use or for -backward compatibility that you don't want in your namespace. - -When you write a new script, consider adding the line: - -\begin{verbatim} -import cgitb; cgitb.enable() -\end{verbatim} - -This activates a special exception handler that will display detailed -reports in the Web browser if any errors occur. If you'd rather not -show the guts of your program to users of your script, you can have -the reports saved to files instead, with a line like this: - -\begin{verbatim} -import cgitb; cgitb.enable(display=0, logdir="/tmp") -\end{verbatim} - -It's very helpful to use this feature during script development. -The reports produced by \refmodule{cgitb} provide information that -can save you a lot of time in tracking down bugs. You can always -remove the \code{cgitb} line later when you have tested your script -and are confident that it works correctly. - -To get at submitted form data, -it's best to use the \class{FieldStorage} class. The other classes -defined in this module are provided mostly for backward compatibility. -Instantiate it exactly once, without arguments. This reads the form -contents from standard input or the environment (depending on the -value of various environment variables set according to the CGI -standard). Since it may consume standard input, it should be -instantiated only once. - -The \class{FieldStorage} instance can be indexed like a Python -dictionary, and also supports the standard dictionary methods -\method{has_key()} and \method{keys()}. The built-in \function{len()} -is also supported. Form fields containing empty strings are ignored -and do not appear in the dictionary; to keep such values, provide -a true value for the optional \var{keep_blank_values} keyword -parameter when creating the \class{FieldStorage} instance. - -For instance, the following code (which assumes that the -\mailheader{Content-Type} header and blank line have already been -printed) checks that the fields \code{name} and \code{addr} are both -set to a non-empty string: - -\begin{verbatim} -form = cgi.FieldStorage() -if not (form.has_key("name") and form.has_key("addr")): - print "<H1>Error</H1>" - print "Please fill in the name and addr fields." - return -print "<p>name:", form["name"].value -print "<p>addr:", form["addr"].value -...further form processing here... -\end{verbatim} - -Here the fields, accessed through \samp{form[\var{key}]}, are -themselves instances of \class{FieldStorage} (or -\class{MiniFieldStorage}, depending on the form encoding). -The \member{value} attribute of the instance yields the string value -of the field. The \method{getvalue()} method returns this string value -directly; it also accepts an optional second argument as a default to -return if the requested key is not present. - -If the submitted form data contains more than one field with the same -name, the object retrieved by \samp{form[\var{key}]} is not a -\class{FieldStorage} or \class{MiniFieldStorage} -instance but a list of such instances. Similarly, in this situation, -\samp{form.getvalue(\var{key})} would return a list of strings. -If you expect this possibility -(when your HTML form contains multiple fields with the same name), use -the \function{getlist()} function, which always returns a list of values (so that you -do not need to special-case the single item case). For example, this -code concatenates any number of username fields, separated by -commas: - -\begin{verbatim} -value = form.getlist("username") -usernames = ",".join(value) -\end{verbatim} - -If a field represents an uploaded file, accessing the value via the -\member{value} attribute or the \function{getvalue()} method reads the -entire file in memory as a string. This may not be what you want. -You can test for an uploaded file by testing either the \member{filename} -attribute or the \member{file} attribute. You can then read the data at -leisure from the \member{file} attribute: - -\begin{verbatim} -fileitem = form["userfile"] -if fileitem.file: - # It's an uploaded file; count lines - linecount = 0 - while 1: - line = fileitem.file.readline() - if not line: break - linecount = linecount + 1 -\end{verbatim} - -The file upload draft standard entertains the possibility of uploading -multiple files from one field (using a recursive -\mimetype{multipart/*} encoding). When this occurs, the item will be -a dictionary-like \class{FieldStorage} item. This can be determined -by testing its \member{type} attribute, which should be -\mimetype{multipart/form-data} (or perhaps another MIME type matching -\mimetype{multipart/*}). In this case, it can be iterated over -recursively just like the top-level form object. - -When a form is submitted in the ``old'' format (as the query string or -as a single data part of type -\mimetype{application/x-www-form-urlencoded}), the items will actually -be instances of the class \class{MiniFieldStorage}. In this case, the -\member{list}, \member{file}, and \member{filename} attributes are -always \code{None}. - - -\subsection{Higher Level Interface} - -\versionadded{2.2} % XXX: Is this true ? - -The previous section explains how to read CGI form data using the -\class{FieldStorage} class. This section describes a higher level -interface which was added to this class to allow one to do it in a -more readable and intuitive way. The interface doesn't make the -techniques described in previous sections obsolete --- they are still -useful to process file uploads efficiently, for example. - -The interface consists of two simple methods. Using the methods -you can process form data in a generic way, without the need to worry -whether only one or more values were posted under one name. - -In the previous section, you learned to write following code anytime -you expected a user to post more than one value under one name: - -\begin{verbatim} -item = form.getvalue("item") -if isinstance(item, list): - # The user is requesting more than one item. -else: - # The user is requesting only one item. -\end{verbatim} - -This situation is common for example when a form contains a group of -multiple checkboxes with the same name: - -\begin{verbatim} -<input type="checkbox" name="item" value="1" /> -<input type="checkbox" name="item" value="2" /> -\end{verbatim} - -In most situations, however, there's only one form control with a -particular name in a form and then you expect and need only one value -associated with this name. So you write a script containing for -example this code: - -\begin{verbatim} -user = form.getvalue("user").upper() -\end{verbatim} - -The problem with the code is that you should never expect that a -client will provide valid input to your scripts. For example, if a -curious user appends another \samp{user=foo} pair to the query string, -then the script would crash, because in this situation the -\code{getvalue("user")} method call returns a list instead of a -string. Calling the \method{toupper()} method on a list is not valid -(since lists do not have a method of this name) and results in an -\exception{AttributeError} exception. - -Therefore, the appropriate way to read form data values was to always -use the code which checks whether the obtained value is a single value -or a list of values. That's annoying and leads to less readable -scripts. - -A more convenient approach is to use the methods \method{getfirst()} -and \method{getlist()} provided by this higher level interface. - -\begin{methoddesc}[FieldStorage]{getfirst}{name\optional{, default}} - This method always returns only one value associated with form field - \var{name}. The method returns only the first value in case that - more values were posted under such name. Please note that the order - in which the values are received may vary from browser to browser - and should not be counted on.\footnote{Note that some recent - versions of the HTML specification do state what order the - field values should be supplied in, but knowing whether a - request was received from a conforming browser, or even from a - browser at all, is tedious and error-prone.} If no such form - field or value exists then the method returns the value specified by - the optional parameter \var{default}. This parameter defaults to - \code{None} if not specified. -\end{methoddesc} - -\begin{methoddesc}[FieldStorage]{getlist}{name} - This method always returns a list of values associated with form - field \var{name}. The method returns an empty list if no such form - field or value exists for \var{name}. It returns a list consisting - of one item if only one such value exists. -\end{methoddesc} - -Using these methods you can write nice compact code: - -\begin{verbatim} -import cgi -form = cgi.FieldStorage() -user = form.getfirst("user", "").upper() # This way it's safe. -for item in form.getlist("item"): - do_something(item) -\end{verbatim} - - -\subsection{Old classes} - -These classes, present in earlier versions of the \module{cgi} module, -are still supported for backward compatibility. New applications -should use the \class{FieldStorage} class. - -\class{SvFormContentDict} stores single value form content as -dictionary; it assumes each field name occurs in the form only once. - -\class{FormContentDict} stores multiple value form content as a -dictionary (the form items are lists of values). Useful if your form -contains multiple fields with the same name. - -Other classes (\class{FormContent}, \class{InterpFormContentDict}) are -present for backwards compatibility with really old applications only. -If you still use these and would be inconvenienced when they -disappeared from a next version of this module, drop me a note. - - -\subsection{Functions} -\nodename{Functions in cgi module} - -These are useful if you want more control, or if you want to employ -some of the algorithms implemented in this module in other -circumstances. - -\begin{funcdesc}{parse}{fp\optional{, keep_blank_values\optional{, - strict_parsing}}} - Parse a query in the environment or from a file (the file defaults - to \code{sys.stdin}). The \var{keep_blank_values} and - \var{strict_parsing} parameters are passed to \function{parse_qs()} - unchanged. -\end{funcdesc} - -\begin{funcdesc}{parse_qs}{qs\optional{, keep_blank_values\optional{, - strict_parsing}}} -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 values for each name. - -The optional argument \var{keep_blank_values} is -a flag indicating whether blank values in -URL encoded queries should be treated as blank strings. -A true value indicates that blanks should be retained as -blank strings. The default false value indicates that -blank values are to be ignored and treated as if they were -not included. - -The optional argument \var{strict_parsing} is a flag indicating what -to do with parsing errors. If false (the default), errors -are silently ignored. If true, errors raise a \exception{ValueError} -exception. - -Use the \function{\refmodule{urllib}.urlencode()} function to convert -such dictionaries into query strings. - -\end{funcdesc} - -\begin{funcdesc}{parse_qsl}{qs\optional{, keep_blank_values\optional{, - strict_parsing}}} -Parse a query string given as a string argument (data of type -\mimetype{application/x-www-form-urlencoded}). Data are -returned as a list of name, value pairs. - -The optional argument \var{keep_blank_values} is -a flag indicating whether blank values in -URL encoded queries should be treated as blank strings. -A true value indicates that blanks should be retained as -blank strings. The default false value indicates that -blank values are to be ignored and treated as if they were -not included. - -The optional argument \var{strict_parsing} is a flag indicating what -to do with parsing errors. If false (the default), errors -are silently ignored. If true, errors raise a \exception{ValueError} -exception. - -Use the \function{\refmodule{urllib}.urlencode()} function to convert -such lists of pairs into query strings. -\end{funcdesc} - -\begin{funcdesc}{parse_multipart}{fp, pdict} -Parse input of type \mimetype{multipart/form-data} (for -file uploads). Arguments are \var{fp} for the input file and -\var{pdict} for a dictionary containing other parameters in -the \mailheader{Content-Type} header. - -Returns a dictionary just like \function{parse_qs()} keys are the -field names, each value is a list of values for that field. This is -easy to use but not much good if you are expecting megabytes to be -uploaded --- in that case, use the \class{FieldStorage} class instead -which is much more flexible. - -Note that this does not parse nested multipart parts --- use -\class{FieldStorage} for that. -\end{funcdesc} - -\begin{funcdesc}{parse_header}{string} -Parse a MIME header (such as \mailheader{Content-Type}) into a main -value and a dictionary of parameters. -\end{funcdesc} - -\begin{funcdesc}{test}{} -Robust test CGI script, usable as main program. -Writes minimal HTTP headers and formats all information provided to -the script in HTML form. -\end{funcdesc} - -\begin{funcdesc}{print_environ}{} -Format the shell environment in HTML. -\end{funcdesc} - -\begin{funcdesc}{print_form}{form} -Format a form in HTML. -\end{funcdesc} - -\begin{funcdesc}{print_directory}{} -Format the current directory in HTML. -\end{funcdesc} - -\begin{funcdesc}{print_environ_usage}{} -Print a list of useful (used by CGI) environment variables in -HTML. -\end{funcdesc} - -\begin{funcdesc}{escape}{s\optional{, quote}} -Convert the characters -\character{\&}, \character{<} and \character{>} in string \var{s} to -HTML-safe sequences. Use this if you need to display text that might -contain such characters in HTML. If the optional flag \var{quote} is -true, the quotation mark character (\character{"}) is also translated; -this helps for inclusion in an HTML attribute value, as in \code{<A -HREF="...">}. If the value to be quoted might include single- or -double-quote characters, or both, consider using the -\function{quoteattr()} function in the \refmodule{xml.sax.saxutils} -module instead. -\end{funcdesc} - - -\subsection{Caring about security \label{cgi-security}} - -\indexii{CGI}{security} - -There's one important rule: if you invoke an external program (via the -\function{os.system()} or \function{os.popen()} functions. or others -with similar functionality), make very sure you don't pass arbitrary -strings received from the client to the shell. This is a well-known -security hole whereby clever hackers anywhere on the Web can exploit a -gullible CGI script to invoke arbitrary shell commands. Even parts of -the URL or field names cannot be trusted, since the request doesn't -have to come from your form! - -To be on the safe side, if you must pass a string gotten from a form -to a shell command, you should make sure the string contains only -alphanumeric characters, dashes, underscores, and periods. - - -\subsection{Installing your CGI script on a \UNIX\ system} - -Read the documentation for your HTTP server and check with your local -system administrator to find the directory where CGI scripts should be -installed; usually this is in a directory \file{cgi-bin} in the server tree. - -Make sure that your script is readable and executable by ``others''; the -\UNIX{} file mode should be \code{0755} octal (use \samp{chmod 0755 -\var{filename}}). Make sure that the first line of the script contains -\code{\#!} starting in column 1 followed by the pathname of the Python -interpreter, for instance: - -\begin{verbatim} -#!/usr/local/bin/python -\end{verbatim} - -Make sure the Python interpreter exists and is executable by ``others''. - -Make sure that any files your script needs to read or write are -readable or writable, respectively, by ``others'' --- their mode -should be \code{0644} for readable and \code{0666} for writable. This -is because, for security reasons, the HTTP server executes your script -as user ``nobody'', without any special privileges. It can only read -(write, execute) files that everybody can read (write, execute). The -current directory at execution time is also different (it is usually -the server's cgi-bin directory) and the set of environment variables -is also different from what you get when you log in. In particular, don't -count on the shell's search path for executables (\envvar{PATH}) or -the Python module search path (\envvar{PYTHONPATH}) to be set to -anything interesting. - -If you need to load modules from a directory which is not on Python's -default module search path, you can change the path in your script, -before importing other modules. For example: - -\begin{verbatim} -import sys -sys.path.insert(0, "/usr/home/joe/lib/python") -sys.path.insert(0, "/usr/local/lib/python") -\end{verbatim} - -(This way, the directory inserted last will be searched first!) - -Instructions for non-\UNIX{} systems will vary; check your HTTP server's -documentation (it will usually have a section on CGI scripts). - - -\subsection{Testing your CGI script} - -Unfortunately, a CGI script will generally not run when you try it -from the command line, and a script that works perfectly from the -command line may fail mysteriously when run from the server. There's -one reason why you should still test your script from the command -line: if it contains a syntax error, the Python interpreter won't -execute it at all, and the HTTP server will most likely send a cryptic -error to the client. - -Assuming your script has no syntax errors, yet it does not work, you -have no choice but to read the next section. - - -\subsection{Debugging CGI scripts} \indexii{CGI}{debugging} - -First of all, check for trivial installation errors --- reading the -section above on installing your CGI script carefully can save you a -lot of time. If you wonder whether you have understood the -installation procedure correctly, try installing a copy of this module -file (\file{cgi.py}) as a CGI script. When invoked as a script, the file -will dump its environment and the contents of the form in HTML form. -Give it the right mode etc, and send it a request. If it's installed -in the standard \file{cgi-bin} directory, it should be possible to send it a -request by entering a URL into your browser of the form: - -\begin{verbatim} -http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home -\end{verbatim} - -If this gives an error of type 404, the server cannot find the script --- perhaps you need to install it in a different directory. If it -gives another error, there's an installation problem that -you should fix before trying to go any further. If you get a nicely -formatted listing of the environment and form content (in this -example, the fields should be listed as ``addr'' with value ``At Home'' -and ``name'' with value ``Joe Blow''), the \file{cgi.py} script has been -installed correctly. If you follow the same procedure for your own -script, you should now be able to debug it. - -The next step could be to call the \module{cgi} module's -\function{test()} function from your script: replace its main code -with the single statement - -\begin{verbatim} -cgi.test() -\end{verbatim} - -This should produce the same results as those gotten from installing -the \file{cgi.py} file itself. - -When an ordinary Python script raises an unhandled exception (for -whatever reason: of a typo in a module name, a file that can't be -opened, etc.), the Python interpreter prints a nice traceback and -exits. While the Python interpreter will still do this when your CGI -script raises an exception, most likely the traceback will end up in -one of the HTTP server's log files, or be discarded altogether. - -Fortunately, once you have managed to get your script to execute -\emph{some} code, you can easily send tracebacks to the Web browser -using the \refmodule{cgitb} module. If you haven't done so already, -just add the line: - -\begin{verbatim} -import cgitb; cgitb.enable() -\end{verbatim} - -to the top of your script. Then try running it again; when a -problem occurs, you should see a detailed report that will -likely make apparent the cause of the crash. - -If you suspect that there may be a problem in importing the -\refmodule{cgitb} module, you can use an even more robust approach -(which only uses built-in modules): - -\begin{verbatim} -import sys -sys.stderr = sys.stdout -print "Content-Type: text/plain" -print -...your code here... -\end{verbatim} - -This relies on the Python interpreter to print the traceback. The -content type of the output is set to plain text, which disables all -HTML processing. If your script works, the raw HTML will be displayed -by your client. If it raises an exception, most likely after the -first two lines have been printed, a traceback will be displayed. -Because no HTML interpretation is going on, the traceback will be -readable. - - -\subsection{Common problems and solutions} - -\begin{itemize} -\item Most HTTP servers buffer the output from CGI scripts until the -script is completed. This means that it is not possible to display a -progress report on the client's display while the script is running. - -\item Check the installation instructions above. - -\item Check the HTTP server's log files. (\samp{tail -f logfile} in a -separate window may be useful!) - -\item Always check a script for syntax errors first, by doing something -like \samp{python script.py}. - -\item If your script does not have any syntax errors, try adding -\samp{import cgitb; cgitb.enable()} to the top of the script. - -\item When invoking external programs, make sure they can be found. -Usually, this means using absolute path names --- \envvar{PATH} is -usually not set to a very useful value in a CGI script. - -\item When reading or writing external files, make sure they can be read -or written by the userid under which your CGI script will be running: -this is typically the userid under which the web server is running, or some -explicitly specified userid for a web server's \samp{suexec} feature. - -\item Don't try to give a CGI script a set-uid mode. This doesn't work on -most systems, and is a security liability as well. -\end{itemize} - diff --git a/Doc/lib/libcgihttp.tex b/Doc/lib/libcgihttp.tex deleted file mode 100644 index df0728e..0000000 --- a/Doc/lib/libcgihttp.tex +++ /dev/null @@ -1,70 +0,0 @@ -\section{\module{CGIHTTPServer} --- - CGI-capable HTTP request handler} - - -\declaremodule{standard}{CGIHTTPServer} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{This module provides a request handler for HTTP servers - which can run CGI scripts.} - - -The \module{CGIHTTPServer} module defines a request-handler class, -interface compatible with -\class{BaseHTTPServer.BaseHTTPRequestHandler} and inherits behavior -from \class{SimpleHTTPServer.SimpleHTTPRequestHandler} but can also -run CGI scripts. - -\note{This module can run CGI scripts on \UNIX{} and Windows systems; -on Mac OS it will only be able to run Python scripts within the same -process as itself.} - -\note{CGI scripts run by the \class{CGIHTTPRequestHandler} class cannot execute -redirects (HTTP code 302), because code 200 (script output follows) -is sent prior to execution of the CGI script. This pre-empts the status -code.} - -The \module{CGIHTTPServer} module defines the following class: - -\begin{classdesc}{CGIHTTPRequestHandler}{request, client_address, server} -This class is used to serve either files or output of CGI scripts from -the current directory and below. Note that mapping HTTP hierarchic -structure to local directory structure is exactly as in -\class{SimpleHTTPServer.SimpleHTTPRequestHandler}. - -The class will however, run the CGI script, instead of serving it as a -file, if it guesses it to be a CGI script. Only directory-based CGI -are used --- the other common server configuration is to treat special -extensions as denoting CGI scripts. - -The \function{do_GET()} and \function{do_HEAD()} functions are -modified to run CGI scripts and serve the output, instead of serving -files, if the request leads to somewhere below the -\code{cgi_directories} path. -\end{classdesc} - -The \class{CGIHTTPRequestHandler} defines the following data member: - -\begin{memberdesc}{cgi_directories} -This defaults to \code{['/cgi-bin', '/htbin']} and describes -directories to treat as containing CGI scripts. -\end{memberdesc} - -The \class{CGIHTTPRequestHandler} defines the following methods: - -\begin{methoddesc}{do_POST}{} -This method serves the \code{'POST'} request type, only allowed for -CGI scripts. Error 501, "Can only POST to CGI scripts", is output -when trying to POST to a non-CGI url. -\end{methoddesc} - -Note that CGI scripts will be run with UID of user nobody, for security -reasons. Problems with the CGI script will be translated to error 403. - -For example usage, see the implementation of the \function{test()} -function. - - -\begin{seealso} - \seemodule{BaseHTTPServer}{Base class implementation for Web server - and request handler.} -\end{seealso} diff --git a/Doc/lib/libcgitb.tex b/Doc/lib/libcgitb.tex deleted file mode 100644 index ca9959f..0000000 --- a/Doc/lib/libcgitb.tex +++ /dev/null @@ -1,67 +0,0 @@ -\section{\module{cgitb} --- - Traceback manager for CGI scripts} - -\declaremodule{standard}{cgitb} -\modulesynopsis{Configurable traceback handler for CGI scripts.} -\moduleauthor{Ka-Ping Yee}{ping@lfw.org} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -\versionadded{2.2} -\index{CGI!exceptions} -\index{CGI!tracebacks} -\index{exceptions!in CGI scripts} -\index{tracebacks!in CGI scripts} - -The \module{cgitb} module provides a special exception handler for Python -scripts. (Its name is a bit misleading. It was originally designed to -display extensive traceback information in HTML for CGI scripts. It was -later generalized to also display this information in plain text.) After -this module is activated, if an uncaught exception occurs, a detailed, -formatted report will be displayed. The report -includes a traceback showing excerpts of the source code for each level, -as well as the values of the arguments and local variables to currently -running functions, to help you debug the problem. Optionally, you can -save this information to a file instead of sending it to the browser. - -To enable this feature, simply add one line to the top of your CGI script: - -\begin{verbatim} -import cgitb; cgitb.enable() -\end{verbatim} - -The options to the \function{enable()} function control whether the -report is displayed in the browser and whether the report is logged -to a file for later analysis. - - -\begin{funcdesc}{enable}{\optional{display\optional{, logdir\optional{, - context\optional{, format}}}}} - This function causes the \module{cgitb} module to take over the - interpreter's default handling for exceptions by setting the - value of \member{\refmodule{sys}.excepthook}. - \withsubitem{(in module sys)}{\ttindex{excepthook()}} - - The optional argument \var{display} defaults to \code{1} and can be set - to \code{0} to suppress sending the traceback to the browser. - If the argument \var{logdir} is present, the traceback reports are - written to files. The value of \var{logdir} should be a directory - where these files will be placed. - The optional argument \var{context} is the number of lines of - context to display around the current line of source code in the - traceback; this defaults to \code{5}. - If the optional argument \var{format} is \code{"html"}, the output is - formatted as HTML. Any other value forces plain text output. The default - value is \code{"html"}. -\end{funcdesc} - -\begin{funcdesc}{handler}{\optional{info}} - This function handles an exception using the default settings - (that is, show a report in the browser, but don't log to a file). - This can be used when you've caught an exception and want to - report it using \module{cgitb}. The optional \var{info} argument - should be a 3-tuple containing an exception type, exception - value, and traceback object, exactly like the tuple returned by - \function{\refmodule{sys}.exc_info()}. If the \var{info} argument - is not supplied, the current exception is obtained from - \function{\refmodule{sys}.exc_info()}. -\end{funcdesc} diff --git a/Doc/lib/libchunk.tex b/Doc/lib/libchunk.tex deleted file mode 100644 index 8e2a494..0000000 --- a/Doc/lib/libchunk.tex +++ /dev/null @@ -1,111 +0,0 @@ -\section{\module{chunk} --- - Read IFF chunked data} - -\declaremodule{standard}{chunk} -\modulesynopsis{Module to read IFF chunks.} -\moduleauthor{Sjoerd Mullender}{sjoerd@acm.org} -\sectionauthor{Sjoerd Mullender}{sjoerd@acm.org} - - - -This module provides an interface for reading files that use EA IFF 85 -chunks.\footnote{``EA IFF 85'' Standard for Interchange Format Files, -Jerry Morrison, Electronic Arts, January 1985.} This format is used -in at least the Audio\index{Audio Interchange File -Format}\index{AIFF}\index{AIFF-C} Interchange File Format -(AIFF/AIFF-C) and the Real\index{Real Media File Format} Media File -Format\index{RMFF} (RMFF). The WAVE audio file format is closely -related and can also be read using this module. - -A chunk has the following structure: - -\begin{tableiii}{c|c|l}{textrm}{Offset}{Length}{Contents} - \lineiii{0}{4}{Chunk ID} - \lineiii{4}{4}{Size of chunk in big-endian byte order, not including the - header} - \lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in - the preceding field} - \lineiii{8 + \var{n}}{0 or 1}{Pad byte needed if \var{n} is odd and - chunk alignment is used} -\end{tableiii} - -The ID is a 4-byte string which identifies the type of chunk. - -The size field (a 32-bit value, encoded using big-endian byte order) -gives the size of the chunk data, not including the 8-byte header. - -Usually an IFF-type file consists of one or more chunks. The proposed -usage of the \class{Chunk} class defined here is to instantiate an -instance at the start of each chunk and read from the instance until -it reaches the end, after which a new instance can be instantiated. -At the end of the file, creating a new instance will fail with a -\exception{EOFError} exception. - -\begin{classdesc}{Chunk}{file\optional{, align, bigendian, inclheader}} -Class which represents a chunk. The \var{file} argument is expected -to be a file-like object. An instance of this class is specifically -allowed. The only method that is needed is \method{read()}. If the -methods \method{seek()} and \method{tell()} are present and don't -raise an exception, they are also used. If these methods are present -and raise an exception, they are expected to not have altered the -object. If the optional argument \var{align} is true, chunks are -assumed to be aligned on 2-byte boundaries. If \var{align} is -false, no alignment is assumed. The default value is true. If the -optional argument \var{bigendian} is false, the chunk size is assumed -to be in little-endian order. This is needed for WAVE audio files. -The default value is true. If the optional argument \var{inclheader} -is true, the size given in the chunk header includes the size of the -header. The default value is false. -\end{classdesc} - -A \class{Chunk} object supports the following methods: - -\begin{methoddesc}{getname}{} -Returns the name (ID) of the chunk. This is the first 4 bytes of the -chunk. -\end{methoddesc} - -\begin{methoddesc}{getsize}{} -Returns the size of the chunk. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Close and skip to the end of the chunk. This does not close the -underlying file. -\end{methoddesc} - -The remaining methods will raise \exception{IOError} if called after -the \method{close()} method has been called. - -\begin{methoddesc}{isatty}{} -Returns \code{False}. -\end{methoddesc} - -\begin{methoddesc}{seek}{pos\optional{, whence}} -Set the chunk's current position. The \var{whence} argument is -optional and defaults to \code{0} (absolute file positioning); other -values are \code{1} (seek relative to the current position) and -\code{2} (seek relative to the file's end). There is no return value. -If the underlying file does not allow seek, only forward seeks are -allowed. -\end{methoddesc} - -\begin{methoddesc}{tell}{} -Return the current position into the chunk. -\end{methoddesc} - -\begin{methoddesc}{read}{\optional{size}} -Read at most \var{size} bytes from the chunk (less if the read hits -the end of the chunk before obtaining \var{size} bytes). If the -\var{size} argument is negative or omitted, read all data until the -end of the chunk. The bytes are returned as a string object. An -empty string is returned when the end of the chunk is encountered -immediately. -\end{methoddesc} - -\begin{methoddesc}{skip}{} -Skip to the end of the chunk. All further calls to \method{read()} -for the chunk will return \code{''}. If you are not interested in the -contents of the chunk, this method should be called so that the file -points to the start of the next chunk. -\end{methoddesc} diff --git a/Doc/lib/libcmath.tex b/Doc/lib/libcmath.tex deleted file mode 100644 index f8aa45b..0000000 --- a/Doc/lib/libcmath.tex +++ /dev/null @@ -1,149 +0,0 @@ -\section{\module{cmath} --- - Mathematical functions for complex numbers} - -\declaremodule{builtin}{cmath} -\modulesynopsis{Mathematical functions for complex numbers.} - -This module is always available. It provides access to mathematical -functions for complex numbers. The functions in this module accept -integers, floating-point numbers or complex numbers as arguments. -They will also accept any Python object that has either a -\method{__complex__} or a \method{__float__} method: these methods are -used to convert the object to a complex or floating-point number, respectively, and -the function is then applied to the result of the conversion. - -The functions are: - -\begin{funcdesc}{acos}{x} -Return the arc cosine of \var{x}. -There are two branch cuts: -One extends right from 1 along the real axis to \infinity, continuous -from below. -The other extends left from -1 along the real axis to -\infinity, -continuous from above. -\end{funcdesc} - -\begin{funcdesc}{acosh}{x} -Return the hyperbolic arc cosine of \var{x}. -There is one branch cut, extending left from 1 along the real axis -to -\infinity, continuous from above. -\end{funcdesc} - -\begin{funcdesc}{asin}{x} -Return the arc sine of \var{x}. -This has the same branch cuts as \function{acos()}. -\end{funcdesc} - -\begin{funcdesc}{asinh}{x} -Return the hyperbolic arc sine of \var{x}. -There are two branch cuts, extending left from \plusminus\code{1j} to -\plusminus-\infinity\code{j}, both continuous from above. -These branch cuts should be considered a bug to be corrected in a -future release. -The correct branch cuts should extend along the imaginary axis, -one from \code{1j} up to \infinity\code{j} and continuous from the -right, and one from -\code{1j} down to -\infinity\code{j} and -continuous from the left. -\end{funcdesc} - -\begin{funcdesc}{atan}{x} -Return the arc tangent of \var{x}. -There are two branch cuts: -One extends from \code{1j} along the imaginary axis to -\infinity\code{j}, continuous from the left. -The other extends from -\code{1j} along the imaginary axis to --\infinity\code{j}, continuous from the left. -(This should probably be changed so the upper cut becomes continuous -from the other side.) -\end{funcdesc} - -\begin{funcdesc}{atanh}{x} -Return the hyperbolic arc tangent of \var{x}. -There are two branch cuts: -One extends from 1 along the real axis to \infinity, continuous -from above. -The other extends from -1 along the real axis to -\infinity, -continuous from above. -(This should probably be changed so the right cut becomes continuous from -the other side.) -\end{funcdesc} - -\begin{funcdesc}{cos}{x} -Return the cosine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{cosh}{x} -Return the hyperbolic cosine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{exp}{x} -Return the exponential value \code{e**\var{x}}. -\end{funcdesc} - -\begin{funcdesc}{log}{x\optional{, base}} -Returns the logarithm of \var{x} to the given \var{base}. -If the \var{base} is not specified, returns the natural logarithm of \var{x}. -There is one branch cut, from 0 along the negative real axis to --\infinity, continuous from above. -\versionchanged[\var{base} argument added]{2.4} -\end{funcdesc} - -\begin{funcdesc}{log10}{x} -Return the base-10 logarithm of \var{x}. -This has the same branch cut as \function{log()}. -\end{funcdesc} - -\begin{funcdesc}{sin}{x} -Return the sine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{sinh}{x} -Return the hyperbolic sine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{sqrt}{x} -Return the square root of \var{x}. -This has the same branch cut as \function{log()}. -\end{funcdesc} - -\begin{funcdesc}{tan}{x} -Return the tangent of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{tanh}{x} -Return the hyperbolic tangent of \var{x}. -\end{funcdesc} - -The module also defines two mathematical constants: - -\begin{datadesc}{pi} -The mathematical constant \emph{pi}, as a real. -\end{datadesc} - -\begin{datadesc}{e} -The mathematical constant \emph{e}, as a real. -\end{datadesc} - -Note that the selection of functions is similar, but not identical, to -that in module \refmodule{math}\refbimodindex{math}. The reason for having -two modules is that some users aren't interested in complex numbers, -and perhaps don't even know what they are. They would rather have -\code{math.sqrt(-1)} raise an exception than return a complex number. -Also note that the functions defined in \module{cmath} always return a -complex number, even if the answer can be expressed as a real number -(in which case the complex number has an imaginary part of zero). - -A note on branch cuts: They are curves along which the given function -fails to be continuous. They are a necessary feature of many complex -functions. It is assumed that if you need to compute with complex -functions, you will understand about branch cuts. Consult almost any -(not too elementary) book on complex variables for enlightenment. For -information of the proper choice of branch cuts for numerical -purposes, a good reference should be the following: - -\begin{seealso} - \seetext{Kahan, W: Branch cuts for complex elementary functions; - or, Much ado about nothing's sign bit. In Iserles, A., - and Powell, M. (eds.), \citetitle{The state of the art in - numerical analysis}. Clarendon Press (1987) pp165-211.} -\end{seealso} diff --git a/Doc/lib/libcmd.tex b/Doc/lib/libcmd.tex deleted file mode 100644 index 810f19c..0000000 --- a/Doc/lib/libcmd.tex +++ /dev/null @@ -1,198 +0,0 @@ -\section{\module{cmd} --- - Support for line-oriented command interpreters} - -\declaremodule{standard}{cmd} -\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} -\modulesynopsis{Build line-oriented command interpreters.} - - -The \class{Cmd} class provides a simple framework for writing -line-oriented command interpreters. These are often useful for -test harnesses, administrative tools, and prototypes that will -later be wrapped in a more sophisticated interface. - -\begin{classdesc}{Cmd}{\optional{completekey\optional{, - stdin\optional{, stdout}}}} -A \class{Cmd} instance or subclass instance is a line-oriented -interpreter framework. There is no good reason to instantiate -\class{Cmd} itself; rather, it's useful as a superclass of an -interpreter class you define yourself in order to inherit -\class{Cmd}'s methods and encapsulate action methods. - -The optional argument \var{completekey} is the \refmodule{readline} name -of a completion key; it defaults to \kbd{Tab}. If \var{completekey} is -not \constant{None} and \refmodule{readline} is available, command completion -is done automatically. - -The optional arguments \var{stdin} and \var{stdout} specify the -input and output file objects that the Cmd instance or subclass -instance will use for input and output. If not specified, they -will default to \var{sys.stdin} and \var{sys.stdout}. - -\versionchanged[The \var{stdin} and \var{stdout} parameters were added]{2.3} -\end{classdesc} - -\subsection{Cmd Objects} -\label{Cmd-objects} - -A \class{Cmd} instance has the following methods: - -\begin{methoddesc}[Cmd]{cmdloop}{\optional{intro}} -Repeatedly issue a prompt, accept input, parse an initial prefix off -the received input, and dispatch to action methods, passing them the -remainder of the line as argument. - -The optional argument is a banner or intro string to be issued before the -first prompt (this overrides the \member{intro} class member). - -If the \refmodule{readline} module is loaded, input will automatically -inherit \program{bash}-like history-list editing (e.g. \kbd{Control-P} -scrolls back to the last command, \kbd{Control-N} forward to the next -one, \kbd{Control-F} moves the cursor to the right non-destructively, -\kbd{Control-B} moves the cursor to the left non-destructively, etc.). - -An end-of-file on input is passed back as the string \code{'EOF'}. - -An interpreter instance will recognize a command name \samp{foo} if -and only if it has a method \method{do_foo()}. As a special case, -a line beginning with the character \character{?} is dispatched to -the method \method{do_help()}. As another special case, a line -beginning with the character \character{!} is dispatched to the -method \method{do_shell()} (if such a method is defined). - -This method will return when the \method{postcmd()} method returns a -true value. The \var{stop} argument to \method{postcmd()} is the -return value from the command's corresponding \method{do_*()} method. - -If completion is enabled, completing commands will be done -automatically, and completing of commands args is done by calling -\method{complete_foo()} with arguments \var{text}, \var{line}, -\var{begidx}, and \var{endidx}. \var{text} is the string prefix we -are attempting to match: all returned matches must begin with it. -\var{line} is the current input line with leading whitespace removed, -\var{begidx} and \var{endidx} are the beginning and ending indexes -of the prefix text, which could be used to provide different -completion depending upon which position the argument is in. - -All subclasses of \class{Cmd} inherit a predefined \method{do_help()}. -This method, called with an argument \code{'bar'}, invokes the -corresponding method \method{help_bar()}. With no argument, -\method{do_help()} lists all available help topics (that is, all -commands with corresponding \method{help_*()} methods), and also lists -any undocumented commands. -\end{methoddesc} - -\begin{methoddesc}[Cmd]{onecmd}{str} -Interpret the argument as though it had been typed in response to the -prompt. This may be overridden, but should not normally need to be; -see the \method{precmd()} and \method{postcmd()} methods for useful -execution hooks. The return value is a flag indicating whether -interpretation of commands by the interpreter should stop. If there -is a \method{do_*()} method for the command \var{str}, the return -value of that method is returned, otherwise the return value from the -\method{default()} method is returned. -\end{methoddesc} - -\begin{methoddesc}[Cmd]{emptyline}{} -Method called when an empty line is entered in response to the prompt. -If this method is not overridden, it repeats the last nonempty command -entered. -\end{methoddesc} - -\begin{methoddesc}[Cmd]{default}{line} -Method called on an input line when the command prefix is not -recognized. If this method is not overridden, it prints an -error message and returns. -\end{methoddesc} - -\begin{methoddesc}[Cmd]{completedefault}{text, line, begidx, endidx} -Method called to complete an input line when no command-specific -\method{complete_*()} method is available. By default, it returns an -empty list. -\end{methoddesc} - -\begin{methoddesc}[Cmd]{precmd}{line} -Hook method executed just before the command line \var{line} is -interpreted, but after the input prompt is generated and issued. This -method is a stub in \class{Cmd}; it exists to be overridden by -subclasses. The return value is used as the command which will be -executed by the \method{onecmd()} method; the \method{precmd()} -implementation may re-write the command or simply return \var{line} -unchanged. -\end{methoddesc} - -\begin{methoddesc}[Cmd]{postcmd}{stop, line} -Hook method executed just after a command dispatch is finished. This -method is a stub in \class{Cmd}; it exists to be overridden by -subclasses. \var{line} is the command line which was executed, and -\var{stop} is a flag which indicates whether execution will be -terminated after the call to \method{postcmd()}; this will be the -return value of the \method{onecmd()} method. The return value of -this method will be used as the new value for the internal flag which -corresponds to \var{stop}; returning false will cause interpretation -to continue. -\end{methoddesc} - -\begin{methoddesc}[Cmd]{preloop}{} -Hook method executed once when \method{cmdloop()} is called. This -method is a stub in \class{Cmd}; it exists to be overridden by -subclasses. -\end{methoddesc} - -\begin{methoddesc}[Cmd]{postloop}{} -Hook method executed once when \method{cmdloop()} is about to return. -This method is a stub in \class{Cmd}; it exists to be overridden by -subclasses. -\end{methoddesc} - -Instances of \class{Cmd} subclasses have some public instance variables: - -\begin{memberdesc}[Cmd]{prompt} -The prompt issued to solicit input. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{identchars} -The string of characters accepted for the command prefix. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{lastcmd} -The last nonempty command prefix seen. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{intro} -A string to issue as an intro or banner. May be overridden by giving -the \method{cmdloop()} method an argument. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{doc_header} -The header to issue if the help output has a section for documented -commands. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{misc_header} -The header to issue if the help output has a section for miscellaneous -help topics (that is, there are \method{help_*()} methods without -corresponding \method{do_*()} methods). -\end{memberdesc} - -\begin{memberdesc}[Cmd]{undoc_header} -The header to issue if the help output has a section for undocumented -commands (that is, there are \method{do_*()} methods without -corresponding \method{help_*()} methods). -\end{memberdesc} - -\begin{memberdesc}[Cmd]{ruler} -The character used to draw separator lines under the help-message -headers. If empty, no ruler line is drawn. It defaults to -\character{=}. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{use_rawinput} -A flag, defaulting to true. If true, \method{cmdloop()} uses -\function{input()} to display a prompt and read the next command; -if false, \method{sys.stdout.write()} and -\method{sys.stdin.readline()} are used. (This means that by -importing \refmodule{readline}, on systems that support it, the -interpreter will automatically support \program{Emacs}-like line editing -and command-history keystrokes.) -\end{memberdesc} diff --git a/Doc/lib/libcmp.tex b/Doc/lib/libcmp.tex deleted file mode 100644 index 489efee..0000000 --- a/Doc/lib/libcmp.tex +++ /dev/null @@ -1,36 +0,0 @@ -\section{\module{cmp} --- - File comparisons} - -\declaremodule{standard}{cmp} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Compare files very efficiently.} - -\deprecated{1.6}{Use the \refmodule{filecmp} module instead.} - -The \module{cmp} module defines a function to compare files, taking all -sort of short-cuts to make it a highly efficient operation. - -The \module{cmp} module defines the following function: - -\begin{funcdesc}{cmp}{f1, f2} -Compare two files given as names. The following tricks are used to -optimize the comparisons: - -\begin{itemize} - \item Files with identical type, size and mtime are assumed equal. - \item Files with different type or size are never equal. - \item The module only compares files it already compared if their - signature (type, size and mtime) changed. - \item No external programs are called. -\end{itemize} -\end{funcdesc} - -Example: - -\begin{verbatim} ->>> import cmp ->>> cmp.cmp('libundoc.tex', 'libundoc.tex') -1 ->>> cmp.cmp('libundoc.tex', 'lib.tex') -0 -\end{verbatim} diff --git a/Doc/lib/libcmpcache.tex b/Doc/lib/libcmpcache.tex deleted file mode 100644 index 8991477..0000000 --- a/Doc/lib/libcmpcache.tex +++ /dev/null @@ -1,21 +0,0 @@ -\section{\module{cmpcache} --- - Efficient file comparisons} - -\declaremodule{standard}{cmpcache} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Compare files very efficiently.} - -\deprecated{1.6}{Use the \refmodule{filecmp} module instead.} - -The \module{cmpcache} module provides an identical interface and similar -functionality as the \refmodule{cmp} module, but can be a bit more efficient -as it uses \function{statcache.stat()} instead of \function{os.stat()} -(see the \refmodule{statcache} module for information on the -difference). - -\note{Using the \refmodule{statcache} module to provide -\function{stat()} information results in trashing the cache -invalidation mechanism: results are not as reliable. To ensure -``current'' results, use \function{cmp.cmp()} instead of the version -defined in this module, or use \function{statcache.forget()} to -invalidate the appropriate entries.} diff --git a/Doc/lib/libcode.tex b/Doc/lib/libcode.tex deleted file mode 100644 index 8e14b02..0000000 --- a/Doc/lib/libcode.tex +++ /dev/null @@ -1,173 +0,0 @@ -\section{\module{code} --- - Interpreter base classes} -\declaremodule{standard}{code} - -\modulesynopsis{Base classes for interactive Python interpreters.} - - -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{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. - -\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} or -\exception{ValueError} if the command contains an invalid literal. -\end{funcdesc} - - -\subsection{Interactive Interpreter Objects - \label{interpreter-objects}} - -\begin{methoddesc}[InteractiveInterpreter]{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{False}. - -\item -The input is incomplete, and more input is required; -\function{compile_command()} returned \code{None}. -\method{runsource()} returns \code{True}. - -\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{False}. -\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}[InteractiveInterpreter]{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 propagate. - -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}[InteractiveInterpreter]{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}[InteractiveInterpreter]{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}[InteractiveInterpreter]{write}{data} -Write a string to the standard error stream (\code{sys.stderr}). -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}[InteractiveConsole]{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}[InteractiveConsole]{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{True} if more input is required, -\code{False} if the line was dealt with in some way (this is the same as -\method{runsource()}). -\end{methoddesc} - -\begin{methoddesc}[InteractiveConsole]{resetbuffer}{} -Remove any unhandled source text from the input buffer. -\end{methoddesc} - -\begin{methoddesc}[InteractiveConsole]{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 reads from -\code{sys.stdin}; a subclass may replace this -with a different implementation. -\end{methoddesc} diff --git a/Doc/lib/libcodecs.tex b/Doc/lib/libcodecs.tex deleted file mode 100644 index ee141d9..0000000 --- a/Doc/lib/libcodecs.tex +++ /dev/null @@ -1,1341 +0,0 @@ -\section{\module{codecs} --- - Codec registry and base classes} - -\declaremodule{standard}{codecs} -\modulesynopsis{Encode and decode data and streams.} -\moduleauthor{Marc-Andre Lemburg}{mal@lemburg.com} -\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} - -\index{Unicode} -\index{Codecs} -\indexii{Codecs}{encode} -\indexii{Codecs}{decode} -\index{streams} -\indexii{stackable}{streams} - - -This module defines base classes for standard Python codecs (encoders -and decoders) and provides access to the internal Python codec -registry which manages the codec and error handling lookup process. - -It defines the following functions: - -\begin{funcdesc}{register}{search_function} -Register a codec search function. Search functions are expected to -take one argument, the encoding name in all lower case letters, and -return a \class{CodecInfo} object having the following attributes: - -\begin{itemize} - \item \code{name} The name of the encoding; - \item \code{encoder} The stateless encoding function; - \item \code{decoder} The stateless decoding function; - \item \code{incrementalencoder} An incremental encoder class or factory function; - \item \code{incrementaldecoder} An incremental decoder class or factory function; - \item \code{streamwriter} A stream writer class or factory function; - \item \code{streamreader} A stream reader class or factory function. -\end{itemize} - -The various functions or classes take the following arguments: - - \var{encoder} and \var{decoder}: These must be functions or methods - which have the same interface as the - \method{encode()}/\method{decode()} methods of Codec instances (see - Codec Interface). The functions/methods are expected to work in a - stateless mode. - - \var{incrementalencoder} and \var{incrementalencoder}: These have to be - factory functions providing the following interface: - - \code{factory(\var{errors}='strict')} - - The factory functions must return objects providing the interfaces - defined by the base classes \class{IncrementalEncoder} and - \class{IncrementalEncoder}, respectively. Incremental codecs can maintain - state. - - \var{streamreader} and \var{streamwriter}: These have to be - factory functions providing the following interface: - - \code{factory(\var{stream}, \var{errors}='strict')} - - The factory functions must return objects providing the interfaces - defined by the base classes \class{StreamWriter} and - \class{StreamReader}, respectively. Stream codecs can maintain - state. - - Possible values for errors are \code{'strict'} (raise an exception - in case of an encoding error), \code{'replace'} (replace malformed - data with a suitable replacement marker, such as \character{?}), - \code{'ignore'} (ignore malformed data and continue without further - notice), \code{'xmlcharrefreplace'} (replace with the appropriate XML - character reference (for encoding only)) and \code{'backslashreplace'} - (replace with backslashed escape sequences (for encoding only)) as - well as any other error handling name defined via - \function{register_error()}. - -In case a search function cannot find a given encoding, it should -return \code{None}. -\end{funcdesc} - -\begin{funcdesc}{lookup}{encoding} -Looks up the codec info in the Python codec registry and returns a -\class{CodecInfo} object as defined above. - -Encodings are first looked up in the registry's cache. If not found, -the list of registered search functions is scanned. If no \class{CodecInfo} -object is found, a \exception{LookupError} is raised. Otherwise, the -\class{CodecInfo} object is stored in the cache and returned to the caller. -\end{funcdesc} - -To simplify access to the various codecs, the module provides these -additional functions which use \function{lookup()} for the codec -lookup: - -\begin{funcdesc}{getencoder}{encoding} -Look up the codec for the given encoding and return its encoder -function. - -Raises a \exception{LookupError} in case the encoding cannot be found. -\end{funcdesc} - -\begin{funcdesc}{getdecoder}{encoding} -Look up the codec for the given encoding and return its decoder -function. - -Raises a \exception{LookupError} in case the encoding cannot be found. -\end{funcdesc} - -\begin{funcdesc}{getincrementalencoder}{encoding} -Look up the codec for the given encoding and return its incremental encoder -class or factory function. - -Raises a \exception{LookupError} in case the encoding cannot be found or the -codec doesn't support an incremental encoder. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{getincrementaldecoder}{encoding} -Look up the codec for the given encoding and return its incremental decoder -class or factory function. - -Raises a \exception{LookupError} in case the encoding cannot be found or the -codec doesn't support an incremental decoder. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{getreader}{encoding} -Look up the codec for the given encoding and return its StreamReader -class or factory function. - -Raises a \exception{LookupError} in case the encoding cannot be found. -\end{funcdesc} - -\begin{funcdesc}{getwriter}{encoding} -Look up the codec for the given encoding and return its StreamWriter -class or factory function. - -Raises a \exception{LookupError} in case the encoding cannot be found. -\end{funcdesc} - -\begin{funcdesc}{register_error}{name, error_handler} -Register the error handling function \var{error_handler} under the -name \var{name}. \var{error_handler} will be called during encoding -and decoding in case of an error, when \var{name} is specified as the -errors parameter. - -For encoding \var{error_handler} will be called with a -\exception{UnicodeEncodeError} instance, which contains information about -the location of the error. The error handler must either raise this or -a different exception or return a tuple with a replacement for the -unencodable part of the input and a position where encoding should -continue. The encoder will encode the replacement and continue encoding -the original input at the specified position. Negative position values -will be treated as being relative to the end of the input string. If the -resulting position is out of bound an \exception{IndexError} will be raised. - -Decoding and translating works similar, except \exception{UnicodeDecodeError} -or \exception{UnicodeTranslateError} will be passed to the handler and -that the replacement from the error handler will be put into the output -directly. -\end{funcdesc} - -\begin{funcdesc}{lookup_error}{name} -Return the error handler previously registered under the name \var{name}. - -Raises a \exception{LookupError} in case the handler cannot be found. -\end{funcdesc} - -\begin{funcdesc}{strict_errors}{exception} -Implements the \code{strict} error handling. -\end{funcdesc} - -\begin{funcdesc}{replace_errors}{exception} -Implements the \code{replace} error handling. -\end{funcdesc} - -\begin{funcdesc}{ignore_errors}{exception} -Implements the \code{ignore} error handling. -\end{funcdesc} - -\begin{funcdesc}{xmlcharrefreplace_errors_errors}{exception} -Implements the \code{xmlcharrefreplace} error handling. -\end{funcdesc} - -\begin{funcdesc}{backslashreplace_errors_errors}{exception} -Implements the \code{backslashreplace} error handling. -\end{funcdesc} - -To simplify working with encoded files or stream, the module -also defines these utility functions: - -\begin{funcdesc}{open}{filename, mode\optional{, encoding\optional{, - errors\optional{, buffering}}}} -Open an encoded file using the given \var{mode} and return -a wrapped version providing transparent encoding/decoding. - -\note{The wrapped version will only accept the object format -defined by the codecs, i.e.\ Unicode objects for most built-in -codecs. Output is also codec-dependent and will usually be Unicode as -well.} - -\var{encoding} specifies the encoding which is to be used for the -file. - -\var{errors} may be given to define the error handling. It defaults -to \code{'strict'} which causes a \exception{ValueError} to be raised -in case an encoding error occurs. - -\var{buffering} has the same meaning as for the built-in -\function{open()} function. It defaults to line buffered. -\end{funcdesc} - -\begin{funcdesc}{EncodedFile}{file, input\optional{, - output\optional{, errors}}} -Return a wrapped version of file which provides transparent -encoding translation. - -Strings written to the wrapped file are interpreted according to the -given \var{input} encoding and then written to the original file as -strings using the \var{output} encoding. The intermediate encoding will -usually be Unicode but depends on the specified codecs. - -If \var{output} is not given, it defaults to \var{input}. - -\var{errors} may be given to define the error handling. It defaults to -\code{'strict'}, which causes \exception{ValueError} to be raised in case -an encoding error occurs. -\end{funcdesc} - -\begin{funcdesc}{iterencode}{iterable, encoding\optional{, errors}} -Uses an incremental encoder to iteratively encode the input provided by -\var{iterable}. This function is a generator. \var{errors} (as well as -any other keyword argument) is passed through to the incremental encoder. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{iterdecode}{iterable, encoding\optional{, errors}} -Uses an incremental decoder to iteratively decode the input provided by -\var{iterable}. This function is a generator. \var{errors} (as well as -any other keyword argument) is passed through to the incremental decoder. -\versionadded{2.5} -\end{funcdesc} - -The module also provides the following constants which are useful -for reading and writing to platform dependent files: - -\begin{datadesc}{BOM} -\dataline{BOM_BE} -\dataline{BOM_LE} -\dataline{BOM_UTF8} -\dataline{BOM_UTF16} -\dataline{BOM_UTF16_BE} -\dataline{BOM_UTF16_LE} -\dataline{BOM_UTF32} -\dataline{BOM_UTF32_BE} -\dataline{BOM_UTF32_LE} -These constants define various encodings of the Unicode byte order mark -(BOM) used in UTF-16 and UTF-32 data streams to indicate the byte order -used in the stream or file and in UTF-8 as a Unicode signature. -\constant{BOM_UTF16} is either \constant{BOM_UTF16_BE} or -\constant{BOM_UTF16_LE} depending on the platform's native byte order, -\constant{BOM} is an alias for \constant{BOM_UTF16}, \constant{BOM_LE} -for \constant{BOM_UTF16_LE} and \constant{BOM_BE} for \constant{BOM_UTF16_BE}. -The others represent the BOM in UTF-8 and UTF-32 encodings. -\end{datadesc} - - -\subsection{Codec Base Classes \label{codec-base-classes}} - -The \module{codecs} module defines a set of base classes which define the -interface and can also be used to easily write you own codecs for use -in Python. - -Each codec has to define four interfaces to make it usable as codec in -Python: stateless encoder, stateless decoder, stream reader and stream -writer. The stream reader and writers typically reuse the stateless -encoder/decoder to implement the file protocols. - -The \class{Codec} class defines the interface for stateless -encoders/decoders. - -To simplify and standardize error handling, the \method{encode()} and -\method{decode()} methods may implement different error handling -schemes by providing the \var{errors} string argument. The following -string values are defined and implemented by all standard Python -codecs: - -\begin{tableii}{l|l}{code}{Value}{Meaning} - \lineii{'strict'}{Raise \exception{UnicodeError} (or a subclass); - this is the default.} - \lineii{'ignore'}{Ignore the character and continue with the next.} - \lineii{'replace'}{Replace with a suitable replacement character; - Python will use the official U+FFFD REPLACEMENT - CHARACTER for the built-in Unicode codecs on - decoding and '?' on encoding.} - \lineii{'xmlcharrefreplace'}{Replace with the appropriate XML - character reference (only for encoding).} - \lineii{'backslashreplace'}{Replace with backslashed escape sequences - (only for encoding).} -\end{tableii} - -The set of allowed values can be extended via \method{register_error}. - - -\subsubsection{Codec Objects \label{codec-objects}} - -The \class{Codec} class defines these methods which also define the -function interfaces of the stateless encoder and decoder: - -\begin{methoddesc}[Codec]{encode}{input\optional{, errors}} - Encodes the object \var{input} and returns a tuple (output object, - length consumed). While codecs are not restricted to use with Unicode, in - a Unicode context, encoding converts a Unicode object to a plain string - using a particular character set encoding (e.g., \code{cp1252} or - \code{iso-8859-1}). - - \var{errors} defines the error handling to apply. It defaults to - \code{'strict'} handling. - - The method may not store state in the \class{Codec} instance. Use - \class{StreamCodec} for codecs which have to keep state in order to - make encoding/decoding efficient. - - The encoder must be able to handle zero length input and return an - empty object of the output object type in this situation. -\end{methoddesc} - -\begin{methoddesc}[Codec]{decode}{input\optional{, errors}} - Decodes the object \var{input} and returns a tuple (output object, - length consumed). In a Unicode context, decoding converts a plain string - encoded using a particular character set encoding to a Unicode object. - - \var{input} must be an object which provides the \code{bf_getreadbuf} - buffer slot. Python strings, buffer objects and memory mapped files - are examples of objects providing this slot. - - \var{errors} defines the error handling to apply. It defaults to - \code{'strict'} handling. - - The method may not store state in the \class{Codec} instance. Use - \class{StreamCodec} for codecs which have to keep state in order to - make encoding/decoding efficient. - - The decoder must be able to handle zero length input and return an - empty object of the output object type in this situation. -\end{methoddesc} - -The \class{IncrementalEncoder} and \class{IncrementalDecoder} classes provide -the basic interface for incremental encoding and decoding. Encoding/decoding the -input isn't done with one call to the stateless encoder/decoder function, -but with multiple calls to the \method{encode}/\method{decode} method of the -incremental encoder/decoder. The incremental encoder/decoder keeps track of -the encoding/decoding process during method calls. - -The joined output of calls to the \method{encode}/\method{decode} method is the -same as if all the single inputs were joined into one, and this input was -encoded/decoded with the stateless encoder/decoder. - - -\subsubsection{IncrementalEncoder Objects \label{incremental-encoder-objects}} - -\versionadded{2.5} - -The \class{IncrementalEncoder} class is used for encoding an input in multiple -steps. It defines the following methods which every incremental encoder must -define in order to be compatible with the Python codec registry. - -\begin{classdesc}{IncrementalEncoder}{\optional{errors}} - Constructor for an \class{IncrementalEncoder} instance. - - All incremental encoders must provide this constructor interface. They are - free to add additional keyword arguments, but only the ones defined - here are used by the Python codec registry. - - The \class{IncrementalEncoder} may implement different error handling - schemes by providing the \var{errors} keyword argument. These - parameters are predefined: - - \begin{itemize} - \item \code{'strict'} Raise \exception{ValueError} (or a subclass); - this is the default. - \item \code{'ignore'} Ignore the character and continue with the next. - \item \code{'replace'} Replace with a suitable replacement character - \item \code{'xmlcharrefreplace'} Replace with the appropriate XML - character reference - \item \code{'backslashreplace'} Replace with backslashed escape sequences. - \end{itemize} - - The \var{errors} argument will be assigned to an attribute of the - same name. Assigning to this attribute makes it possible to switch - between different error handling strategies during the lifetime - of the \class{IncrementalEncoder} object. - - The set of allowed values for the \var{errors} argument can - be extended with \function{register_error()}. -\end{classdesc} - -\begin{methoddesc}{encode}{object\optional{, final}} - Encodes \var{object} (taking the current state of the encoder into account) - and returns the resulting encoded object. If this is the last call to - \method{encode} \var{final} must be true (the default is false). -\end{methoddesc} - -\begin{methoddesc}{reset}{} - Reset the encoder to the initial state. -\end{methoddesc} - -\begin{methoddesc}{getstate}{} - Return the current state of the encoder which must be an integer. - The implementation should make sure that \code{0} is the most common state. - (States that are more complicated than integers can be converted into an - integer by marshaling/pickling the state and encoding the bytes of the - resulting string into an integer). - \versionadded{3.0} -\end{methoddesc} - -\begin{methoddesc}{setstate}{state} - Set the state of the encoder to \var{state}. \var{state} must be an - encoder state returned by \method{getstate}. - \versionadded{3.0} -\end{methoddesc} - - -\subsubsection{IncrementalDecoder Objects \label{incremental-decoder-objects}} - -The \class{IncrementalDecoder} class is used for decoding an input in multiple -steps. It defines the following methods which every incremental decoder must -define in order to be compatible with the Python codec registry. - -\begin{classdesc}{IncrementalDecoder}{\optional{errors}} - Constructor for an \class{IncrementalDecoder} instance. - - All incremental decoders must provide this constructor interface. They are - free to add additional keyword arguments, but only the ones defined - here are used by the Python codec registry. - - The \class{IncrementalDecoder} may implement different error handling - schemes by providing the \var{errors} keyword argument. These - parameters are predefined: - - \begin{itemize} - \item \code{'strict'} Raise \exception{ValueError} (or a subclass); - this is the default. - \item \code{'ignore'} Ignore the character and continue with the next. - \item \code{'replace'} Replace with a suitable replacement character. - \end{itemize} - - The \var{errors} argument will be assigned to an attribute of the - same name. Assigning to this attribute makes it possible to switch - between different error handling strategies during the lifetime - of the \class{IncrementalEncoder} object. - - The set of allowed values for the \var{errors} argument can - be extended with \function{register_error()}. -\end{classdesc} - -\begin{methoddesc}{decode}{object\optional{, final}} - Decodes \var{object} (taking the current state of the decoder into account) - and returns the resulting decoded object. If this is the last call to - \method{decode} \var{final} must be true (the default is false). - If \var{final} is true the decoder must decode the input completely and must - flush all buffers. If this isn't possible (e.g. because of incomplete byte - sequences at the end of the input) it must initiate error handling just like - in the stateless case (which might raise an exception). -\end{methoddesc} - -\begin{methoddesc}{reset}{} - Reset the decoder to the initial state. -\end{methoddesc} - -\begin{methoddesc}{getstate}{} - Return the current state of the decoder. This must be a tuple with two - items, the first must be the buffer containing the still undecoded input. - The second must be an integer and can be additional state info. - (The implementation should make sure that \code{0} is the most common - additional state info.) If this additional state info is \code{0} it must - be possible to set the decoder to the state which has no input buffered - and \code{0} as the additional state info, so that feeding the previously - buffered input to the decoder returns it to the previous state without - producing any output. (Additional state info that is more complicated - than integers can be converted into an integer by marshaling/pickling - the info and encoding the bytes of the resulting string into an integer.) - \versionadded{3.0} -\end{methoddesc} - -\begin{methoddesc}{setstate}{state} - Set the state of the encoder to \var{state}. \var{state} must be a - decoder state returned by \method{getstate}. - \versionadded{3.0} -\end{methoddesc} - - -The \class{StreamWriter} and \class{StreamReader} classes provide -generic working interfaces which can be used to implement new -encoding submodules very easily. See \module{encodings.utf_8} for an -example of how this is done. - - -\subsubsection{StreamWriter Objects \label{stream-writer-objects}} - -The \class{StreamWriter} class is a subclass of \class{Codec} and -defines the following methods which every stream writer must define in -order to be compatible with the Python codec registry. - -\begin{classdesc}{StreamWriter}{stream\optional{, errors}} - Constructor for a \class{StreamWriter} instance. - - All stream writers must provide this constructor interface. They are - free to add additional keyword arguments, but only the ones defined - here are used by the Python codec registry. - - \var{stream} must be a file-like object open for writing binary - data. - - The \class{StreamWriter} may implement different error handling - schemes by providing the \var{errors} keyword argument. These - parameters are predefined: - - \begin{itemize} - \item \code{'strict'} Raise \exception{ValueError} (or a subclass); - this is the default. - \item \code{'ignore'} Ignore the character and continue with the next. - \item \code{'replace'} Replace with a suitable replacement character - \item \code{'xmlcharrefreplace'} Replace with the appropriate XML - character reference - \item \code{'backslashreplace'} Replace with backslashed escape sequences. - \end{itemize} - - The \var{errors} argument will be assigned to an attribute of the - same name. Assigning to this attribute makes it possible to switch - between different error handling strategies during the lifetime - of the \class{StreamWriter} object. - - The set of allowed values for the \var{errors} argument can - be extended with \function{register_error()}. -\end{classdesc} - -\begin{methoddesc}{write}{object} - Writes the object's contents encoded to the stream. -\end{methoddesc} - -\begin{methoddesc}{writelines}{list} - Writes the concatenated list of strings to the stream (possibly by - reusing the \method{write()} method). -\end{methoddesc} - -\begin{methoddesc}{reset}{} - Flushes and resets the codec buffers used for keeping state. - - Calling this method should ensure that the data on the output is put - into a clean state that allows appending of new fresh data without - having to rescan the whole stream to recover state. -\end{methoddesc} - -In addition to the above methods, the \class{StreamWriter} must also -inherit all other methods and attributes from the underlying stream. - - -\subsubsection{StreamReader Objects \label{stream-reader-objects}} - -The \class{StreamReader} class is a subclass of \class{Codec} and -defines the following methods which every stream reader must define in -order to be compatible with the Python codec registry. - -\begin{classdesc}{StreamReader}{stream\optional{, errors}} - Constructor for a \class{StreamReader} instance. - - All stream readers must provide this constructor interface. They are - free to add additional keyword arguments, but only the ones defined - here are used by the Python codec registry. - - \var{stream} must be a file-like object open for reading (binary) - data. - - The \class{StreamReader} may implement different error handling - schemes by providing the \var{errors} keyword argument. These - parameters are defined: - - \begin{itemize} - \item \code{'strict'} Raise \exception{ValueError} (or a subclass); - this is the default. - \item \code{'ignore'} Ignore the character and continue with the next. - \item \code{'replace'} Replace with a suitable replacement character. - \end{itemize} - - The \var{errors} argument will be assigned to an attribute of the - same name. Assigning to this attribute makes it possible to switch - between different error handling strategies during the lifetime - of the \class{StreamReader} object. - - The set of allowed values for the \var{errors} argument can - be extended with \function{register_error()}. -\end{classdesc} - -\begin{methoddesc}{read}{\optional{size\optional{, chars, \optional{firstline}}}} - Decodes data from the stream and returns the resulting object. - - \var{chars} indicates the number of characters to read from the - stream. \function{read()} will never return more than \var{chars} - characters, but it might return less, if there are not enough - characters available. - - \var{size} indicates the approximate maximum number of bytes to read - from the stream for decoding purposes. The decoder can modify this - setting as appropriate. The default value -1 indicates to read and - decode as much as possible. \var{size} is intended to prevent having - to decode huge files in one step. - - \var{firstline} indicates that it would be sufficient to only return - the first line, if there are decoding errors on later lines. - - The method should use a greedy read strategy meaning that it should - read as much data as is allowed within the definition of the encoding - and the given size, e.g. if optional encoding endings or state - markers are available on the stream, these should be read too. - - \versionchanged[\var{chars} argument added]{2.4} - \versionchanged[\var{firstline} argument added]{2.4.2} -\end{methoddesc} - -\begin{methoddesc}{readline}{\optional{size\optional{, keepends}}} - Read one line from the input stream and return the - decoded data. - - \var{size}, if given, is passed as size argument to the stream's - \method{readline()} method. - - If \var{keepends} is false line-endings will be stripped from the - lines returned. - - \versionchanged[\var{keepends} argument added]{2.4} -\end{methoddesc} - -\begin{methoddesc}{readlines}{\optional{sizehint\optional{, keepends}}} - Read all lines available on the input stream and return them as a list - of lines. - - Line-endings are implemented using the codec's decoder method and are - included in the list entries if \var{keepends} is true. - - \var{sizehint}, if given, is passed as the \var{size} argument to the - stream's \method{read()} method. -\end{methoddesc} - -\begin{methoddesc}{reset}{} - Resets the codec buffers used for keeping state. - - Note that no stream repositioning should take place. This method is - primarily intended to be able to recover from decoding errors. -\end{methoddesc} - -In addition to the above methods, the \class{StreamReader} must also -inherit all other methods and attributes from the underlying stream. - -The next two base classes are included for convenience. They are not -needed by the codec registry, but may provide useful in practice. - - -\subsubsection{StreamReaderWriter Objects \label{stream-reader-writer}} - -The \class{StreamReaderWriter} allows wrapping streams which work in -both read and write modes. - -The design is such that one can use the factory functions returned by -the \function{lookup()} function to construct the instance. - -\begin{classdesc}{StreamReaderWriter}{stream, Reader, Writer, errors} - Creates a \class{StreamReaderWriter} instance. - \var{stream} must be a file-like object. - \var{Reader} and \var{Writer} must be factory functions or classes - providing the \class{StreamReader} and \class{StreamWriter} interface - resp. - Error handling is done in the same way as defined for the - stream readers and writers. -\end{classdesc} - -\class{StreamReaderWriter} instances define the combined interfaces of -\class{StreamReader} and \class{StreamWriter} classes. They inherit -all other methods and attributes from the underlying stream. - - -\subsubsection{StreamRecoder Objects \label{stream-recoder-objects}} - -The \class{StreamRecoder} provide a frontend - backend view of -encoding data which is sometimes useful when dealing with different -encoding environments. - -The design is such that one can use the factory functions returned by -the \function{lookup()} function to construct the instance. - -\begin{classdesc}{StreamRecoder}{stream, encode, decode, - Reader, Writer, errors} - Creates a \class{StreamRecoder} instance which implements a two-way - conversion: \var{encode} and \var{decode} work on the frontend (the - input to \method{read()} and output of \method{write()}) while - \var{Reader} and \var{Writer} work on the backend (reading and - writing to the stream). - - You can use these objects to do transparent direct recodings from - e.g.\ Latin-1 to UTF-8 and back. - - \var{stream} must be a file-like object. - - \var{encode}, \var{decode} must adhere to the \class{Codec} - interface. \var{Reader}, \var{Writer} must be factory functions or - classes providing objects of the \class{StreamReader} and - \class{StreamWriter} interface respectively. - - \var{encode} and \var{decode} are needed for the frontend - translation, \var{Reader} and \var{Writer} for the backend - translation. The intermediate format used is determined by the two - sets of codecs, e.g. the Unicode codecs will use Unicode as the - intermediate encoding. - - Error handling is done in the same way as defined for the - stream readers and writers. -\end{classdesc} - -\class{StreamRecoder} instances define the combined interfaces of -\class{StreamReader} and \class{StreamWriter} classes. They inherit -all other methods and attributes from the underlying stream. - -\subsection{Encodings and Unicode\label{encodings-overview}} - -Unicode strings are stored internally as sequences of codepoints (to -be precise as \ctype{Py_UNICODE} arrays). Depending on the way Python is -compiled (either via \longprogramopt{enable-unicode=ucs2} or -\longprogramopt{enable-unicode=ucs4}, with the former being the default) -\ctype{Py_UNICODE} is either a 16-bit or -32-bit data type. Once a Unicode object is used outside of CPU and -memory, CPU endianness and how these arrays are stored as bytes become -an issue. Transforming a unicode object into a sequence of bytes is -called encoding and recreating the unicode object from the sequence of -bytes is known as decoding. There are many different methods for how this -transformation can be done (these methods are also called encodings). -The simplest method is to map the codepoints 0-255 to the bytes -\code{0x0}-\code{0xff}. This means that a unicode object that contains -codepoints above \code{U+00FF} can't be encoded with this method (which -is called \code{'latin-1'} or \code{'iso-8859-1'}). -\function{unicode.encode()} will raise a \exception{UnicodeEncodeError} -that looks like this: \samp{UnicodeEncodeError: 'latin-1' codec can't -encode character u'\e u1234' in position 3: ordinal not in range(256)}. - -There's another group of encodings (the so called charmap encodings) -that choose a different subset of all unicode code points and how -these codepoints are mapped to the bytes \code{0x0}-\code{0xff.} -To see how this is done simply open e.g. \file{encodings/cp1252.py} -(which is an encoding that is used primarily on Windows). -There's a string constant with 256 characters that shows you which -character is mapped to which byte value. - -All of these encodings can only encode 256 of the 65536 (or 1114111) -codepoints defined in unicode. A simple and straightforward way that -can store each Unicode code point, is to store each codepoint as two -consecutive bytes. There are two possibilities: Store the bytes in big -endian or in little endian order. These two encodings are called -UTF-16-BE and UTF-16-LE respectively. Their disadvantage is that if -e.g. you use UTF-16-BE on a little endian machine you will always have -to swap bytes on encoding and decoding. UTF-16 avoids this problem: -Bytes will always be in natural endianness. When these bytes are read -by a CPU with a different endianness, then bytes have to be swapped -though. To be able to detect the endianness of a UTF-16 byte sequence, -there's the so called BOM (the "Byte Order Mark"). This is the Unicode -character \code{U+FEFF}. This character will be prepended to every UTF-16 -byte sequence. The byte swapped version of this character (\code{0xFFFE}) is -an illegal character that may not appear in a Unicode text. So when -the first character in an UTF-16 byte sequence appears to be a \code{U+FFFE} -the bytes have to be swapped on decoding. Unfortunately upto Unicode -4.0 the character \code{U+FEFF} had a second purpose as a \samp{ZERO WIDTH -NO-BREAK SPACE}: A character that has no width and doesn't allow a -word to be split. It can e.g. be used to give hints to a ligature -algorithm. With Unicode 4.0 using \code{U+FEFF} as a \samp{ZERO WIDTH NO-BREAK -SPACE} has been deprecated (with \code{U+2060} (\samp{WORD JOINER}) assuming -this role). Nevertheless Unicode software still must be able to handle -\code{U+FEFF} in both roles: As a BOM it's a device to determine the storage -layout of the encoded bytes, and vanishes once the byte sequence has -been decoded into a Unicode string; as a \samp{ZERO WIDTH NO-BREAK SPACE} -it's a normal character that will be decoded like any other. - -There's another encoding that is able to encoding the full range of -Unicode characters: UTF-8. UTF-8 is an 8-bit encoding, which means -there are no issues with byte order in UTF-8. Each byte in a UTF-8 -byte sequence consists of two parts: Marker bits (the most significant -bits) and payload bits. The marker bits are a sequence of zero to six -1 bits followed by a 0 bit. Unicode characters are encoded like this -(with x being payload bits, which when concatenated give the Unicode -character): - -\begin{tableii}{l|l}{textrm}{Range}{Encoding} -\lineii{\code{U-00000000} ... \code{U-0000007F}}{0xxxxxxx} -\lineii{\code{U-00000080} ... \code{U-000007FF}}{110xxxxx 10xxxxxx} -\lineii{\code{U-00000800} ... \code{U-0000FFFF}}{1110xxxx 10xxxxxx 10xxxxxx} -\lineii{\code{U-00010000} ... \code{U-001FFFFF}}{11110xxx 10xxxxxx 10xxxxxx 10xxxxxx} -\lineii{\code{U-00200000} ... \code{U-03FFFFFF}}{111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx} -\lineii{\code{U-04000000} ... \code{U-7FFFFFFF}}{1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx} -\end{tableii} - -The least significant bit of the Unicode character is the rightmost x -bit. - -As UTF-8 is an 8-bit encoding no BOM is required and any \code{U+FEFF} -character in the decoded Unicode string (even if it's the first -character) is treated as a \samp{ZERO WIDTH NO-BREAK SPACE}. - -Without external information it's impossible to reliably determine -which encoding was used for encoding a Unicode string. Each charmap -encoding can decode any random byte sequence. However that's not -possible with UTF-8, as UTF-8 byte sequences have a structure that -doesn't allow arbitrary byte sequence. To increase the reliability -with which a UTF-8 encoding can be detected, Microsoft invented a -variant of UTF-8 (that Python 2.5 calls \code{"utf-8-sig"}) for its Notepad -program: Before any of the Unicode characters is written to the file, -a UTF-8 encoded BOM (which looks like this as a byte sequence: \code{0xef}, -\code{0xbb}, \code{0xbf}) is written. As it's rather improbable that any -charmap encoded file starts with these byte values (which would e.g. map to - - LATIN SMALL LETTER I WITH DIAERESIS \\ - RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK \\ - INVERTED QUESTION MARK - -in iso-8859-1), this increases the probability that a utf-8-sig -encoding can be correctly guessed from the byte sequence. So here the -BOM is not used to be able to determine the byte order used for -generating the byte sequence, but as a signature that helps in -guessing the encoding. On encoding the utf-8-sig codec will write -\code{0xef}, \code{0xbb}, \code{0xbf} as the first three bytes to the file. -On decoding utf-8-sig will skip those three bytes if they appear as the -first three bytes in the file. - - -\subsection{Standard Encodings\label{standard-encodings}} - -Python comes with a number of codecs built-in, either implemented as C -functions or with dictionaries as mapping tables. The following table -lists the codecs by name, together with a few common aliases, and the -languages for which the encoding is likely used. Neither the list of -aliases nor the list of languages is meant to be exhaustive. Notice -that spelling alternatives that only differ in case or use a hyphen -instead of an underscore are also valid aliases. - -Many of the character sets support the same languages. They vary in -individual characters (e.g. whether the EURO SIGN is supported or -not), and in the assignment of characters to code positions. For the -European languages in particular, the following variants typically -exist: - -\begin{itemize} -\item an ISO 8859 codeset -\item a Microsoft Windows code page, which is typically derived from - a 8859 codeset, but replaces control characters with additional - graphic characters -\item an IBM EBCDIC code page -\item an IBM PC code page, which is \ASCII{} compatible -\end{itemize} - -\begin{longtableiii}{l|l|l}{textrm}{Codec}{Aliases}{Languages} - -\lineiii{ascii} - {646, us-ascii} - {English} - -\lineiii{big5} - {big5-tw, csbig5} - {Traditional Chinese} - -\lineiii{big5hkscs} - {big5-hkscs, hkscs} - {Traditional Chinese} - -\lineiii{cp037} - {IBM037, IBM039} - {English} - -\lineiii{cp424} - {EBCDIC-CP-HE, IBM424} - {Hebrew} - -\lineiii{cp437} - {437, IBM437} - {English} - -\lineiii{cp500} - {EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500} - {Western Europe} - -\lineiii{cp737} - {} - {Greek} - -\lineiii{cp775} - {IBM775} - {Baltic languages} - -\lineiii{cp850} - {850, IBM850} - {Western Europe} - -\lineiii{cp852} - {852, IBM852} - {Central and Eastern Europe} - -\lineiii{cp855} - {855, IBM855} - {Bulgarian, Byelorussian, Macedonian, Russian, Serbian} - -\lineiii{cp856} - {} - {Hebrew} - -\lineiii{cp857} - {857, IBM857} - {Turkish} - -\lineiii{cp860} - {860, IBM860} - {Portuguese} - -\lineiii{cp861} - {861, CP-IS, IBM861} - {Icelandic} - -\lineiii{cp862} - {862, IBM862} - {Hebrew} - -\lineiii{cp863} - {863, IBM863} - {Canadian} - -\lineiii{cp864} - {IBM864} - {Arabic} - -\lineiii{cp865} - {865, IBM865} - {Danish, Norwegian} - -\lineiii{cp866} - {866, IBM866} - {Russian} - -\lineiii{cp869} - {869, CP-GR, IBM869} - {Greek} - -\lineiii{cp874} - {} - {Thai} - -\lineiii{cp875} - {} - {Greek} - -\lineiii{cp932} - {932, ms932, mskanji, ms-kanji} - {Japanese} - -\lineiii{cp949} - {949, ms949, uhc} - {Korean} - -\lineiii{cp950} - {950, ms950} - {Traditional Chinese} - -\lineiii{cp1006} - {} - {Urdu} - -\lineiii{cp1026} - {ibm1026} - {Turkish} - -\lineiii{cp1140} - {ibm1140} - {Western Europe} - -\lineiii{cp1250} - {windows-1250} - {Central and Eastern Europe} - -\lineiii{cp1251} - {windows-1251} - {Bulgarian, Byelorussian, Macedonian, Russian, Serbian} - -\lineiii{cp1252} - {windows-1252} - {Western Europe} - -\lineiii{cp1253} - {windows-1253} - {Greek} - -\lineiii{cp1254} - {windows-1254} - {Turkish} - -\lineiii{cp1255} - {windows-1255} - {Hebrew} - -\lineiii{cp1256} - {windows1256} - {Arabic} - -\lineiii{cp1257} - {windows-1257} - {Baltic languages} - -\lineiii{cp1258} - {windows-1258} - {Vietnamese} - -\lineiii{euc_jp} - {eucjp, ujis, u-jis} - {Japanese} - -\lineiii{euc_jis_2004} - {jisx0213, eucjis2004} - {Japanese} - -\lineiii{euc_jisx0213} - {eucjisx0213} - {Japanese} - -\lineiii{euc_kr} - {euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001} - {Korean} - -\lineiii{gb2312} - {chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, - gb2312-80, iso-ir-58} - {Simplified Chinese} - -\lineiii{gbk} - {936, cp936, ms936} - {Unified Chinese} - -\lineiii{gb18030} - {gb18030-2000} - {Unified Chinese} - -\lineiii{hz} - {hzgb, hz-gb, hz-gb-2312} - {Simplified Chinese} - -\lineiii{iso2022_jp} - {csiso2022jp, iso2022jp, iso-2022-jp} - {Japanese} - -\lineiii{iso2022_jp_1} - {iso2022jp-1, iso-2022-jp-1} - {Japanese} - -\lineiii{iso2022_jp_2} - {iso2022jp-2, iso-2022-jp-2} - {Japanese, Korean, Simplified Chinese, Western Europe, Greek} - -\lineiii{iso2022_jp_2004} - {iso2022jp-2004, iso-2022-jp-2004} - {Japanese} - -\lineiii{iso2022_jp_3} - {iso2022jp-3, iso-2022-jp-3} - {Japanese} - -\lineiii{iso2022_jp_ext} - {iso2022jp-ext, iso-2022-jp-ext} - {Japanese} - -\lineiii{iso2022_kr} - {csiso2022kr, iso2022kr, iso-2022-kr} - {Korean} - -\lineiii{latin_1} - {iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1} - {West Europe} - -\lineiii{iso8859_2} - {iso-8859-2, latin2, L2} - {Central and Eastern Europe} - -\lineiii{iso8859_3} - {iso-8859-3, latin3, L3} - {Esperanto, Maltese} - -\lineiii{iso8859_4} - {iso-8859-4, latin4, L4} - {Baltic languagues} - -\lineiii{iso8859_5} - {iso-8859-5, cyrillic} - {Bulgarian, Byelorussian, Macedonian, Russian, Serbian} - -\lineiii{iso8859_6} - {iso-8859-6, arabic} - {Arabic} - -\lineiii{iso8859_7} - {iso-8859-7, greek, greek8} - {Greek} - -\lineiii{iso8859_8} - {iso-8859-8, hebrew} - {Hebrew} - -\lineiii{iso8859_9} - {iso-8859-9, latin5, L5} - {Turkish} - -\lineiii{iso8859_10} - {iso-8859-10, latin6, L6} - {Nordic languages} - -\lineiii{iso8859_13} - {iso-8859-13} - {Baltic languages} - -\lineiii{iso8859_14} - {iso-8859-14, latin8, L8} - {Celtic languages} - -\lineiii{iso8859_15} - {iso-8859-15} - {Western Europe} - -\lineiii{johab} - {cp1361, ms1361} - {Korean} - -\lineiii{koi8_r} - {} - {Russian} - -\lineiii{koi8_u} - {} - {Ukrainian} - -\lineiii{mac_cyrillic} - {maccyrillic} - {Bulgarian, Byelorussian, Macedonian, Russian, Serbian} - -\lineiii{mac_greek} - {macgreek} - {Greek} - -\lineiii{mac_iceland} - {maciceland} - {Icelandic} - -\lineiii{mac_latin2} - {maclatin2, maccentraleurope} - {Central and Eastern Europe} - -\lineiii{mac_roman} - {macroman} - {Western Europe} - -\lineiii{mac_turkish} - {macturkish} - {Turkish} - -\lineiii{ptcp154} - {csptcp154, pt154, cp154, cyrillic-asian} - {Kazakh} - -\lineiii{shift_jis} - {csshiftjis, shiftjis, sjis, s_jis} - {Japanese} - -\lineiii{shift_jis_2004} - {shiftjis2004, sjis_2004, sjis2004} - {Japanese} - -\lineiii{shift_jisx0213} - {shiftjisx0213, sjisx0213, s_jisx0213} - {Japanese} - -\lineiii{utf_16} - {U16, utf16} - {all languages} - -\lineiii{utf_16_be} - {UTF-16BE} - {all languages (BMP only)} - -\lineiii{utf_16_le} - {UTF-16LE} - {all languages (BMP only)} - -\lineiii{utf_7} - {U7, unicode-1-1-utf-7} - {all languages} - -\lineiii{utf_8} - {U8, UTF, utf8} - {all languages} - -\lineiii{utf_8_sig} - {} - {all languages} - -\end{longtableiii} - -A number of codecs are specific to Python, so their codec names have -no meaning outside Python. Some of them don't convert from Unicode -strings to byte strings, but instead use the property of the Python -codecs machinery that any bijective function with one argument can be -considered as an encoding. - -For the codecs listed below, the result in the ``encoding'' direction -is always a byte string. The result of the ``decoding'' direction is -listed as operand type in the table. - -\begin{tableiv}{l|l|l|l}{textrm}{Codec}{Aliases}{Operand type}{Purpose} - -\lineiv{idna} - {} - {Unicode string} - {Implements \rfc{3490}, - see also \refmodule{encodings.idna}} - -\lineiv{mbcs} - {dbcs} - {Unicode string} - {Windows only: Encode operand according to the ANSI codepage (CP_ACP)} - -\lineiv{palmos} - {} - {Unicode string} - {Encoding of PalmOS 3.5} - -\lineiv{punycode} - {} - {Unicode string} - {Implements \rfc{3492}} - -\lineiv{raw_unicode_escape} - {} - {Unicode string} - {Produce a string that is suitable as raw Unicode literal in - Python source code} - -\lineiv{undefined} - {} - {any} - {Raise an exception for all conversions. Can be used as the - system encoding if no automatic coercion between byte and - Unicode strings is desired.} - -\lineiv{unicode_escape} - {} - {Unicode string} - {Produce a string that is suitable as Unicode literal in - Python source code} - -\lineiv{unicode_internal} - {} - {Unicode string} - {Return the internal representation of the operand} -\end{tableiv} - -\versionadded[The \code{idna} and \code{punycode} encodings]{2.3} - -\subsection{\module{encodings.idna} --- - Internationalized Domain Names in Applications} - -\declaremodule{standard}{encodings.idna} -\modulesynopsis{Internationalized Domain Names implementation} -% XXX The next line triggers a formatting bug, so it's commented out -% until that can be fixed. -%\moduleauthor{Martin v. L\"owis} - -\versionadded{2.3} - -This module implements \rfc{3490} (Internationalized Domain Names in -Applications) and \rfc{3492} (Nameprep: A Stringprep Profile for -Internationalized Domain Names (IDN)). It builds upon the -\code{punycode} encoding and \refmodule{stringprep}. - -These RFCs together define a protocol to support non-\ASCII{} characters -in domain names. A domain name containing non-\ASCII{} characters (such -as ``www.Alliancefran\c caise.nu'') is converted into an -\ASCII-compatible encoding (ACE, such as -``www.xn--alliancefranaise-npb.nu''). The ACE form of the domain name -is then used in all places where arbitrary characters are not allowed -by the protocol, such as DNS queries, HTTP \mailheader{Host} fields, and so -on. This conversion is carried out in the application; if possible -invisible to the user: The application should transparently convert -Unicode domain labels to IDNA on the wire, and convert back ACE labels -to Unicode before presenting them to the user. - -Python supports this conversion in several ways: The \code{idna} codec -allows to convert between Unicode and the ACE. Furthermore, the -\refmodule{socket} module transparently converts Unicode host names to -ACE, so that applications need not be concerned about converting host -names themselves when they pass them to the socket module. On top of -that, modules that have host names as function parameters, such as -\refmodule{httplib} and \refmodule{ftplib}, accept Unicode host names -(\refmodule{httplib} then also transparently sends an IDNA hostname in -the \mailheader{Host} field if it sends that field at all). - -When receiving host names from the wire (such as in reverse name -lookup), no automatic conversion to Unicode is performed: Applications -wishing to present such host names to the user should decode them to -Unicode. - -The module \module{encodings.idna} also implements the nameprep -procedure, which performs certain normalizations on host names, to -achieve case-insensitivity of international domain names, and to unify -similar characters. The nameprep functions can be used directly if -desired. - -\begin{funcdesc}{nameprep}{label} -Return the nameprepped version of \var{label}. The implementation -currently assumes query strings, so \code{AllowUnassigned} is -true. -\end{funcdesc} - -\begin{funcdesc}{ToASCII}{label} -Convert a label to \ASCII, as specified in \rfc{3490}. -\code{UseSTD3ASCIIRules} is assumed to be false. -\end{funcdesc} - -\begin{funcdesc}{ToUnicode}{label} -Convert a label to Unicode, as specified in \rfc{3490}. -\end{funcdesc} - - \subsection{\module{encodings.utf_8_sig} --- - UTF-8 codec with BOM signature} -\declaremodule{standard}{encodings.utf-8-sig} % XXX utf_8_sig gives TeX errors -\modulesynopsis{UTF-8 codec with BOM signature} -\moduleauthor{Walter D\"orwald}{} - -\versionadded{2.5} - -This module implements a variant of the UTF-8 codec: On encoding a -UTF-8 encoded BOM will be prepended to the UTF-8 encoded bytes. For -the stateful encoder this is only done once (on the first write to the -byte stream). For decoding an optional UTF-8 encoded BOM at the start -of the data will be skipped. diff --git a/Doc/lib/libcodeop.tex b/Doc/lib/libcodeop.tex deleted file mode 100644 index 6972b6f..0000000 --- a/Doc/lib/libcodeop.tex +++ /dev/null @@ -1,103 +0,0 @@ -\section{\module{codeop} --- - Compile Python code} - -% LaTeXed from excellent doc-string. - -\declaremodule{standard}{codeop} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\sectionauthor{Michael Hudson}{mwh@python.net} -\modulesynopsis{Compile (possibly incomplete) Python code.} - -The \module{codeop} module provides utilities upon which the Python -read-eval-print loop can be emulated, as is done in the -\refmodule{code} module. As a result, you probably don't want to use -the module directly; if you want to include such a loop in your -program you probably want to use the \refmodule{code} module instead. - -There are two parts to this job: - -\begin{enumerate} - \item Being able to tell if a line of input completes a Python - statement: in short, telling whether to print - `\code{>>>~}' or `\code{...~}' next. - \item Remembering which future statements the user has entered, so - subsequent input can be compiled with these in effect. -\end{enumerate} - -The \module{codeop} module provides a way of doing each of these -things, and a way of doing them both. - -To do just the former: - -\begin{funcdesc}{compile_command} - {source\optional{, filename\optional{, symbol}}} -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>'}. -Returns \code{None} if \var{source} is \emph{not} valid Python -code, but is a prefix of valid Python code. - -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} or \exception{ValueError} if there is an -invalid literal. - -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 -with a successful outcome before reaching the end of the source; -in this case, trailing symbols may be ignored instead of causing an -error. For example, a backslash followed by two newlines may be -followed by arbitrary garbage. This will be fixed once the API -for the parser is better. -\end{funcdesc} - -\begin{classdesc}{Compile}{} -Instances of this class have \method{__call__()} methods identical in -signature to the built-in function \function{compile()}, but with the -difference that if the instance compiles program text containing a -\module{__future__} statement, the instance 'remembers' and compiles -all subsequent program texts with the statement in force. -\end{classdesc} - -\begin{classdesc}{CommandCompiler}{} -Instances of this class have \method{__call__()} methods identical in -signature to \function{compile_command()}; the difference is that if -the instance compiles program text containing a \code{__future__} -statement, the instance 'remembers' and compiles all subsequent -program texts with the statement in force. -\end{classdesc} - -A note on version compatibility: the \class{Compile} and -\class{CommandCompiler} are new in Python 2.2. If you want to enable -the future-tracking features of 2.2 but also retain compatibility with -2.1 and earlier versions of Python you can either write - -\begin{verbatim} -try: - from codeop import CommandCompiler - compile_command = CommandCompiler() - del CommandCompiler -except ImportError: - from codeop import compile_command -\end{verbatim} - -which is a low-impact change, but introduces possibly unwanted global -state into your program, or you can write: - -\begin{verbatim} -try: - from codeop import CommandCompiler -except ImportError: - def CommandCompiler(): - from codeop import compile_command - return compile_command -\end{verbatim} - -and then call \code{CommandCompiler} every time you need a fresh -compiler object. diff --git a/Doc/lib/libcollections.tex b/Doc/lib/libcollections.tex deleted file mode 100644 index fc44e01..0000000 --- a/Doc/lib/libcollections.tex +++ /dev/null @@ -1,402 +0,0 @@ -\section{\module{collections} --- - High-performance container datatypes} - -\declaremodule{standard}{collections} -\modulesynopsis{High-performance datatypes} -\moduleauthor{Raymond Hettinger}{python@rcn.com} -\sectionauthor{Raymond Hettinger}{python@rcn.com} -\versionadded{2.4} - - -This module implements high-performance container datatypes. Currently, -there are two datatypes, deque and defaultdict, and one datatype factory -function, \function{NamedTuple}. -Future additions may include balanced trees and ordered dictionaries. -\versionchanged[Added defaultdict]{2.5} -\versionchanged[Added NamedTuple]{2.6} - -\subsection{\class{deque} objects \label{deque-objects}} - -\begin{classdesc}{deque}{\optional{iterable}} - Returns a new deque object initialized left-to-right (using - \method{append()}) with data from \var{iterable}. If \var{iterable} - is not specified, the new deque is empty. - - Deques are a generalization of stacks and queues (the name is pronounced - ``deck'' and is short for ``double-ended queue''). Deques support - thread-safe, memory efficient appends and pops from either side of the deque - with approximately the same \code{O(1)} performance in either direction. - - Though \class{list} objects support similar operations, they are optimized - for fast fixed-length operations and incur \code{O(n)} memory movement costs - for \samp{pop(0)} and \samp{insert(0, v)} operations which change both the - size and position of the underlying data representation. - \versionadded{2.4} -\end{classdesc} - -Deque objects support the following methods: - -\begin{methoddesc}{append}{x} - Add \var{x} to the right side of the deque. -\end{methoddesc} - -\begin{methoddesc}{appendleft}{x} - Add \var{x} to the left side of the deque. -\end{methoddesc} - -\begin{methoddesc}{clear}{} - Remove all elements from the deque leaving it with length 0. -\end{methoddesc} - -\begin{methoddesc}{extend}{iterable} - Extend the right side of the deque by appending elements from - the iterable argument. -\end{methoddesc} - -\begin{methoddesc}{extendleft}{iterable} - Extend the left side of the deque by appending elements from - \var{iterable}. Note, the series of left appends results in - reversing the order of elements in the iterable argument. -\end{methoddesc} - -\begin{methoddesc}{pop}{} - Remove and return an element from the right side of the deque. - If no elements are present, raises an \exception{IndexError}. -\end{methoddesc} - -\begin{methoddesc}{popleft}{} - Remove and return an element from the left side of the deque. - If no elements are present, raises an \exception{IndexError}. -\end{methoddesc} - -\begin{methoddesc}{remove}{value} - Removed the first occurrence of \var{value}. If not found, - raises a \exception{ValueError}. - \versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}{rotate}{n} - Rotate the deque \var{n} steps to the right. If \var{n} is - negative, rotate to the left. Rotating one step to the right - is equivalent to: \samp{d.appendleft(d.pop())}. -\end{methoddesc} - -In addition to the above, deques support iteration, pickling, \samp{len(d)}, -\samp{reversed(d)}, \samp{copy.copy(d)}, \samp{copy.deepcopy(d)}, -membership testing with the \keyword{in} operator, and subscript references -such as \samp{d[-1]}. - -Example: - -\begin{verbatim} ->>> from collections import deque ->>> d = deque('ghi') # make a new deque with three items ->>> for elem in d: # iterate over the deque's elements -... print elem.upper() -G -H -I - ->>> d.append('j') # add a new entry to the right side ->>> d.appendleft('f') # add a new entry to the left side ->>> d # show the representation of the deque -deque(['f', 'g', 'h', 'i', 'j']) - ->>> d.pop() # return and remove the rightmost item -'j' ->>> d.popleft() # return and remove the leftmost item -'f' ->>> list(d) # list the contents of the deque -['g', 'h', 'i'] ->>> d[0] # peek at leftmost item -'g' ->>> d[-1] # peek at rightmost item -'i' - ->>> list(reversed(d)) # list the contents of a deque in reverse -['i', 'h', 'g'] ->>> 'h' in d # search the deque -True ->>> d.extend('jkl') # add multiple elements at once ->>> d -deque(['g', 'h', 'i', 'j', 'k', 'l']) ->>> d.rotate(1) # right rotation ->>> d -deque(['l', 'g', 'h', 'i', 'j', 'k']) ->>> d.rotate(-1) # left rotation ->>> d -deque(['g', 'h', 'i', 'j', 'k', 'l']) - ->>> deque(reversed(d)) # make a new deque in reverse order -deque(['l', 'k', 'j', 'i', 'h', 'g']) ->>> d.clear() # empty the deque ->>> d.pop() # cannot pop from an empty deque -Traceback (most recent call last): - File "<pyshell#6>", line 1, in -toplevel- - d.pop() -IndexError: pop from an empty deque - ->>> d.extendleft('abc') # extendleft() reverses the input order ->>> d -deque(['c', 'b', 'a']) -\end{verbatim} - -\subsubsection{Recipes \label{deque-recipes}} - -This section shows various approaches to working with deques. - -The \method{rotate()} method provides a way to implement \class{deque} -slicing and deletion. For example, a pure python implementation of -\code{del d[n]} relies on the \method{rotate()} method to position -elements to be popped: - -\begin{verbatim} -def delete_nth(d, n): - d.rotate(-n) - d.popleft() - d.rotate(n) -\end{verbatim} - -To implement \class{deque} slicing, use a similar approach applying -\method{rotate()} to bring a target element to the left side of the deque. -Remove old entries with \method{popleft()}, add new entries with -\method{extend()}, and then reverse the rotation. - -With minor variations on that approach, it is easy to implement Forth style -stack manipulations such as \code{dup}, \code{drop}, \code{swap}, \code{over}, -\code{pick}, \code{rot}, and \code{roll}. - -A roundrobin task server can be built from a \class{deque} using -\method{popleft()} to select the current task and \method{append()} -to add it back to the tasklist if the input stream is not exhausted: - -\begin{verbatim} -def roundrobin(*iterables): - pending = deque(iter(i) for i in iterables) - while pending: - task = pending.popleft() - try: - yield next(task) - except StopIteration: - continue - pending.append(task) - ->>> for value in roundrobin('abc', 'd', 'efgh'): -... print value - -a -d -e -b -f -c -g -h - -\end{verbatim} - - -Multi-pass data reduction algorithms can be succinctly expressed and -efficiently coded by extracting elements with multiple calls to -\method{popleft()}, applying the reduction function, and calling -\method{append()} to add the result back to the queue. - -For example, building a balanced binary tree of nested lists entails -reducing two adjacent nodes into one by grouping them in a list: - -\begin{verbatim} -def maketree(iterable): - d = deque(iterable) - while len(d) > 1: - pair = [d.popleft(), d.popleft()] - d.append(pair) - return list(d) - ->>> print maketree('abcdefgh') -[[[['a', 'b'], ['c', 'd']], [['e', 'f'], ['g', 'h']]]] - -\end{verbatim} - - - -\subsection{\class{defaultdict} objects \label{defaultdict-objects}} - -\begin{classdesc}{defaultdict}{\optional{default_factory\optional{, ...}}} - Returns a new dictionary-like object. \class{defaultdict} is a subclass - of the builtin \class{dict} class. It overrides one method and adds one - writable instance variable. The remaining functionality is the same as - for the \class{dict} class and is not documented here. - - The first argument provides the initial value for the - \member{default_factory} attribute; it defaults to \code{None}. - All remaining arguments are treated the same as if they were - passed to the \class{dict} constructor, including keyword arguments. - - \versionadded{2.5} -\end{classdesc} - -\class{defaultdict} objects support the following method in addition to -the standard \class{dict} operations: - -\begin{methoddesc}{__missing__}{key} - If the \member{default_factory} attribute is \code{None}, this raises - an \exception{KeyError} exception with the \var{key} as argument. - - If \member{default_factory} is not \code{None}, it is called without - arguments to provide a default value for the given \var{key}, this - value is inserted in the dictionary for the \var{key}, and returned. - - If calling \member{default_factory} raises an exception this exception - is propagated unchanged. - - This method is called by the \method{__getitem__} method of the - \class{dict} class when the requested key is not found; whatever it - returns or raises is then returned or raised by \method{__getitem__}. -\end{methoddesc} - -\class{defaultdict} objects support the following instance variable: - -\begin{memberdesc}{default_factory} - This attribute is used by the \method{__missing__} method; it is initialized - from the first argument to the constructor, if present, or to \code{None}, - if absent. -\end{memberdesc} - - -\subsubsection{\class{defaultdict} Examples \label{defaultdict-examples}} - -Using \class{list} as the \member{default_factory}, it is easy to group -a sequence of key-value pairs into a dictionary of lists: - -\begin{verbatim} ->>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)] ->>> d = defaultdict(list) ->>> for k, v in s: - d[k].append(v) - ->>> d.items() -[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])] -\end{verbatim} - -When each key is encountered for the first time, it is not already in the -mapping; so an entry is automatically created using the -\member{default_factory} function which returns an empty \class{list}. The -\method{list.append()} operation then attaches the value to the new list. When -keys are encountered again, the look-up proceeds normally (returning the list -for that key) and the \method{list.append()} operation adds another value to -the list. This technique is simpler and faster than an equivalent technique -using \method{dict.setdefault()}: - -\begin{verbatim} ->>> d = {} ->>> for k, v in s: - d.setdefault(k, []).append(v) - ->>> d.items() -[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])] -\end{verbatim} - -Setting the \member{default_factory} to \class{int} makes the -\class{defaultdict} useful for counting (like a bag or multiset in other -languages): - -\begin{verbatim} ->>> s = 'mississippi' ->>> d = defaultdict(int) ->>> for k in s: - d[k] += 1 - ->>> d.items() -[('i', 4), ('p', 2), ('s', 4), ('m', 1)] -\end{verbatim} - -When a letter is first encountered, it is missing from the mapping, so the -\member{default_factory} function calls \function{int()} to supply a default -count of zero. The increment operation then builds up the count for each -letter. - -The function \function{int()} which always returns zero is just a special -case of constant functions. A faster and more flexible way to create -constant functions is to use a lambda function which can supply -any constant value (not just zero): - -\begin{verbatim} ->>> def constant_factory(value): -... return lambda: value ->>> d = defaultdict(constant_factory('<missing>')) ->>> d.update(name='John', action='ran') ->>> '%(name)s %(action)s to %(object)s' % d -'John ran to <missing>' -\end{verbatim} - -Setting the \member{default_factory} to \class{set} makes the -\class{defaultdict} useful for building a dictionary of sets: - -\begin{verbatim} ->>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)] ->>> d = defaultdict(set) ->>> for k, v in s: - d[k].add(v) - ->>> d.items() -[('blue', set([2, 4])), ('red', set([1, 3]))] -\end{verbatim} - - - -\subsection{\function{NamedTuple} datatype factory function \label{named-tuple-factory}} - -\begin{funcdesc}{NamedTuple}{typename, fieldnames} - Returns a new tuple subclass named \var{typename}. The new subclass is used - to create tuple-like objects that have fields accessable by attribute - lookup as well as being indexable and iterable. Instances of the subclass - also have a helpful docstring (with typename and fieldnames) and a helpful - \method{__repr__()} method which lists the tuple contents in a \code{name=value} - format. - \versionadded{2.6} - - The \var{fieldnames} are specified in a single string and are separated by spaces. - Any valid Python identifier may be used for a field name. - - Example: - \begin{verbatim} ->>> Point = NamedTuple('Point', 'x y') ->>> Point.__doc__ # docstring for the new datatype -'Point(x, y)' ->>> p = Point(11, y=22) # instantiate with positional or keyword arguments ->>> p[0] + p[1] # works just like the tuple (11, 22) -33 ->>> x, y = p # unpacks just like a tuple ->>> x, y -(11, 22) ->>> p.x + p.y # fields also accessable by name -33 ->>> p # readable __repr__ with name=value style -Point(x=11, y=22) -\end{verbatim} - - The use cases are the same as those for tuples. The named factories - assign meaning to each tuple position and allow for more readable, - self-documenting code. Named tuples can also be used to assign field names - to tuples returned by the \module{csv} or \module{sqlite3} modules. - For example: - - \begin{verbatim} -from itertools import starmap -import csv -EmployeeRecord = NamedTuple('EmployeeRecord', 'name age title department paygrade') -for record in starmap(EmployeeRecord, csv.reader(open("employees.csv", "rb"))): - print record -\end{verbatim} - - To cast an individual record stored as \class{list}, \class{tuple}, or some other - iterable type, use the star-operator to unpack the values: - - \begin{verbatim} ->>> Color = NamedTuple('Color', 'name code') ->>> m = dict(red=1, green=2, blue=3) ->>> print Color(*m.popitem()) -Color(name='blue', code=3) -\end{verbatim} - -\end{funcdesc} diff --git a/Doc/lib/libcolorsys.tex b/Doc/lib/libcolorsys.tex deleted file mode 100644 index 2748377..0000000 --- a/Doc/lib/libcolorsys.tex +++ /dev/null @@ -1,54 +0,0 @@ -\section{\module{colorsys} --- - Conversions between color systems} - -\declaremodule{standard}{colorsys} -\modulesynopsis{Conversion functions between RGB and other color systems.} -\sectionauthor{David Ascher}{da@python.net} - -The \module{colorsys} module defines bidirectional conversions of -color values between colors expressed in the RGB (Red Green Blue) -color space used in computer monitors and three other coordinate -systems: YIQ, HLS (Hue Lightness Saturation) and HSV (Hue Saturation -Value). Coordinates in all of these color spaces are floating point -values. In the YIQ space, the Y coordinate is between 0 and 1, but -the I and Q coordinates can be positive or negative. In all other -spaces, the coordinates are all between 0 and 1. - -More information about color spaces can be found at -\url{http://www.poynton.com/ColorFAQ.html}. - -The \module{colorsys} module defines the following functions: - -\begin{funcdesc}{rgb_to_yiq}{r, g, b} -Convert the color from RGB coordinates to YIQ coordinates. -\end{funcdesc} - -\begin{funcdesc}{yiq_to_rgb}{y, i, q} -Convert the color from YIQ coordinates to RGB coordinates. -\end{funcdesc} - -\begin{funcdesc}{rgb_to_hls}{r, g, b} -Convert the color from RGB coordinates to HLS coordinates. -\end{funcdesc} - -\begin{funcdesc}{hls_to_rgb}{h, l, s} -Convert the color from HLS coordinates to RGB coordinates. -\end{funcdesc} - -\begin{funcdesc}{rgb_to_hsv}{r, g, b} -Convert the color from RGB coordinates to HSV coordinates. -\end{funcdesc} - -\begin{funcdesc}{hsv_to_rgb}{h, s, v} -Convert the color from HSV coordinates to RGB coordinates. -\end{funcdesc} - -Example: - -\begin{verbatim} ->>> import colorsys ->>> colorsys.rgb_to_hsv(.3, .4, .2) -(0.25, 0.5, 0.4) ->>> colorsys.hsv_to_rgb(0.25, 0.5, 0.4) -(0.3, 0.4, 0.2) -\end{verbatim} diff --git a/Doc/lib/libcommands.tex b/Doc/lib/libcommands.tex deleted file mode 100644 index 4a5fa55..0000000 --- a/Doc/lib/libcommands.tex +++ /dev/null @@ -1,54 +0,0 @@ -\section{\module{commands} --- - Utilities for running commands} - -\declaremodule{standard}{commands} - \platform{Unix} -\modulesynopsis{Utility functions for running external commands.} -\sectionauthor{Sue Williams}{sbw@provis.com} - - -The \module{commands} module contains wrapper functions for -\function{os.popen()} which take a system command as a string and -return any output generated by the command and, optionally, the exit -status. - -The \module{subprocess} module provides more powerful facilities for -spawning new processes and retrieving their results. Using the -\module{subprocess} module is preferable to using the \module{commands} -module. - -The \module{commands} module defines the following functions: - - -\begin{funcdesc}{getstatusoutput}{cmd} -Execute the string \var{cmd} in a shell with \function{os.popen()} and -return a 2-tuple \code{(\var{status}, \var{output})}. \var{cmd} is -actually run as \code{\{ \var{cmd} ; \} 2>\&1}, so that the returned -output will contain output or error messages. A trailing newline is -stripped from the output. The exit status for the command can be -interpreted according to the rules for the C function -\cfunction{wait()}. -\end{funcdesc} - -\begin{funcdesc}{getoutput}{cmd} -Like \function{getstatusoutput()}, except the exit status is ignored -and the return value is a string containing the command's output. -\end{funcdesc} - -Example: - -\begin{verbatim} ->>> import commands ->>> commands.getstatusoutput('ls /bin/ls') -(0, '/bin/ls') ->>> commands.getstatusoutput('cat /bin/junk') -(256, 'cat: /bin/junk: No such file or directory') ->>> commands.getstatusoutput('/bin/junk') -(256, 'sh: /bin/junk: not found') ->>> commands.getoutput('ls /bin/ls') -'/bin/ls' -\end{verbatim} - -\begin{seealso} - \seemodule{subprocess}{Module for spawning and managing subprocesses.} -\end{seealso} diff --git a/Doc/lib/libcompileall.tex b/Doc/lib/libcompileall.tex deleted file mode 100644 index 3e9667d..0000000 --- a/Doc/lib/libcompileall.tex +++ /dev/null @@ -1,63 +0,0 @@ -\section{\module{compileall} --- - Byte-compile Python libraries} - -\declaremodule{standard}{compileall} -\modulesynopsis{Tools for byte-compiling all Python source files in a - directory tree.} - - -This module provides some utility functions to support installing -Python libraries. These functions compile Python source files in a -directory tree, allowing users without permission to write to the -libraries to take advantage of cached byte-code files. - -The source file for this module may also be used as a script to -compile Python sources in directories named on the command line or in -\code{sys.path}. - - -\begin{funcdesc}{compile_dir}{dir\optional{, maxlevels\optional{, - ddir\optional{, force\optional{, - rx\optional{, quiet}}}}}} - 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. If - \var{force} is true, modules are re-compiled even if the timestamps - are up to date. - - If \var{rx} is given, it specifies a regular expression of file - names to exclude from the search; that expression is searched for in - the full path. - - If \var{quiet} is true, nothing is printed to the standard output - in normal operation. -\end{funcdesc} - -\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} and - \var{force} parameters default to \code{0} and are passed to the - \function{compile_dir()} function. -\end{funcdesc} - -To force a recompile of all the \file{.py} files in the \file{Lib/} -subdirectory and all its subdirectories: - -\begin{verbatim} -import compileall - -compileall.compile_dir('Lib/', force=True) - -# Perform same compilation, excluding files in .svn directories. -import re -compileall.compile_dir('Lib/', rx=re.compile('/[.]svn'), force=True) -\end{verbatim} - - -\begin{seealso} - \seemodule[pycompile]{py_compile}{Byte-compile a single source file.} -\end{seealso} diff --git a/Doc/lib/libconsts.tex b/Doc/lib/libconsts.tex deleted file mode 100644 index bf36281..0000000 --- a/Doc/lib/libconsts.tex +++ /dev/null @@ -1,33 +0,0 @@ -\section{Built-in Constants} - -A small number of constants live in the built-in namespace. They are: - -\begin{datadesc}{False} - The false value of the \class{bool} type. - \versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{True} - The true value of the \class{bool} type. - \versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{None} - The sole value of \member{\refmodule{types}.NoneType}. \code{None} is - frequently used to represent the absence of a value, as when default - arguments are not passed to a function. -\end{datadesc} - -\begin{datadesc}{NotImplemented} - Special value which can be returned by the ``rich comparison'' - special methods (\method{__eq__()}, \method{__lt__()}, and friends), - to indicate that the comparison is not implemented with respect to - the other type. -\end{datadesc} - -\begin{datadesc}{Ellipsis} - The same as \code{...}. - Special value used mostly in conjunction with extended slicing syntax - for user-defined container data types. - % XXX Someone who understands extended slicing should fill in here. -\end{datadesc} diff --git a/Doc/lib/libcontextlib.tex b/Doc/lib/libcontextlib.tex deleted file mode 100644 index 0ac5442..0000000 --- a/Doc/lib/libcontextlib.tex +++ /dev/null @@ -1,130 +0,0 @@ -\section{\module{contextlib} --- - Utilities for \keyword{with}-statement contexts.} - -\declaremodule{standard}{contextlib} -\modulesynopsis{Utilities for \keyword{with}-statement contexts.} - -\versionadded{2.5} - -This module provides utilities for common tasks involving the -\keyword{with} statement. - -Functions provided: - -\begin{funcdesc}{contextmanager}{func} -This function is a decorator that can be used to define a factory -function for \keyword{with} statement context managers, without -needing to create a class or separate \method{__enter__()} and -\method{__exit__()} methods. - -A simple example (this is not recommended as a real way of -generating HTML!): - -\begin{verbatim} -from __future__ import with_statement -from contextlib import contextmanager - -@contextmanager -def tag(name): - print "<%s>" % name - yield - print "</%s>" % name - ->>> with tag("h1"): -... print "foo" -... -<h1> -foo -</h1> -\end{verbatim} - -The function being decorated must return a generator-iterator when -called. This iterator must yield exactly one value, which will be -bound to the targets in the \keyword{with} statement's \keyword{as} -clause, if any. - -At the point where the generator yields, the block nested in the -\keyword{with} statement is executed. The generator is then resumed -after the block is exited. If an unhandled exception occurs in the -block, it is reraised inside the generator at the point where the yield -occurred. Thus, you can use a -\keyword{try}...\keyword{except}...\keyword{finally} statement to trap -the error (if any), or ensure that some cleanup takes place. If an -exception is trapped merely in order to log it or to perform some -action (rather than to suppress it entirely), the generator must -reraise that exception. Otherwise the generator context manager will -indicate to the \keyword{with} statement that the exception has been -handled, and execution will resume with the statement immediately -following the \keyword{with} statement. -\end{funcdesc} - -\begin{funcdesc}{nested}{mgr1\optional{, mgr2\optional{, ...}}} -Combine multiple context managers into a single nested context manager. - -Code like this: - -\begin{verbatim} -from contextlib import nested - -with nested(A, B, C) as (X, Y, Z): - do_something() -\end{verbatim} - -is equivalent to this: - -\begin{verbatim} -with A as X: - with B as Y: - with C as Z: - do_something() -\end{verbatim} - -Note that if the \method{__exit__()} method of one of the nested -context managers indicates an exception should be suppressed, no -exception information will be passed to any remaining outer context -managers. Similarly, if the \method{__exit__()} method of one of the -nested managers raises an exception, any previous exception state will -be lost; the new exception will be passed to the -\method{__exit__()} methods of any remaining outer context managers. -In general, \method{__exit__()} methods should avoid raising -exceptions, and in particular they should not re-raise a -passed-in exception. -\end{funcdesc} - -\label{context-closing} -\begin{funcdesc}{closing}{thing} -Return a context manager that closes \var{thing} upon completion of -the block. This is basically equivalent to: - -\begin{verbatim} -from contextlib import contextmanager - -@contextmanager -def closing(thing): - try: - yield thing - finally: - thing.close() -\end{verbatim} - -And lets you write code like this: -\begin{verbatim} -from __future__ import with_statement -from contextlib import closing -import urllib - -with closing(urllib.urlopen('http://www.python.org')) as page: - for line in page: - print line -\end{verbatim} - -without needing to explicitly close \code{page}. Even if an error -occurs, \code{page.close()} will be called when the \keyword{with} -block is exited. -\end{funcdesc} - -\begin{seealso} - \seepep{0343}{The "with" statement} - {The specification, background, and examples for the - Python \keyword{with} statement.} -\end{seealso} diff --git a/Doc/lib/libcookie.tex b/Doc/lib/libcookie.tex deleted file mode 100644 index e5d2038..0000000 --- a/Doc/lib/libcookie.tex +++ /dev/null @@ -1,260 +0,0 @@ -\section{\module{Cookie} --- - HTTP state management} - -\declaremodule{standard}{Cookie} -\modulesynopsis{Support for HTTP state management (cookies).} -\moduleauthor{Timothy O'Malley}{timo@alum.mit.edu} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} - - -The \module{Cookie} module defines classes for abstracting the concept of -cookies, an HTTP state management mechanism. It supports both simple -string-only cookies, and provides an abstraction for having any serializable -data-type as cookie value. - -The module formerly strictly applied the parsing rules described in -the \rfc{2109} and \rfc{2068} specifications. It has since been discovered -that MSIE 3.0x doesn't follow the character rules outlined in those -specs. As a result, the parsing rules used are a bit less strict. - -\begin{excdesc}{CookieError} -Exception failing because of \rfc{2109} invalidity: incorrect -attributes, incorrect \mailheader{Set-Cookie} header, etc. -\end{excdesc} - -\begin{classdesc}{BaseCookie}{\optional{input}} -This class is a dictionary-like object whose keys are strings and -whose values are \class{Morsel} instances. Note that upon setting a key to -a value, the value is first converted to a \class{Morsel} containing -the key and the value. - -If \var{input} is given, it is passed to the \method{load()} method. -\end{classdesc} - -\begin{classdesc}{SimpleCookie}{\optional{input}} -This class derives from \class{BaseCookie} and overrides -\method{value_decode()} and \method{value_encode()} to be the identity -and \function{str()} respectively. -\end{classdesc} - -\begin{classdesc}{SerialCookie}{\optional{input}} -This class derives from \class{BaseCookie} and overrides -\method{value_decode()} and \method{value_encode()} to be the -\function{pickle.loads()} and \function{pickle.dumps()}. - -\deprecated{2.3}{Reading pickled values from untrusted -cookie data is a huge security hole, as pickle strings can be crafted -to cause arbitrary code to execute on your server. It is supported -for backwards compatibility only, and may eventually go away.} -\end{classdesc} - -\begin{classdesc}{SmartCookie}{\optional{input}} -This class derives from \class{BaseCookie}. It overrides -\method{value_decode()} to be \function{pickle.loads()} if it is a -valid pickle, and otherwise the value itself. It overrides -\method{value_encode()} to be \function{pickle.dumps()} unless it is a -string, in which case it returns the value itself. - -\deprecated{2.3}{The same security warning from \class{SerialCookie} -applies here.} -\end{classdesc} - -A further security note is warranted. For backwards compatibility, -the \module{Cookie} module exports a class named \class{Cookie} which -is just an alias for \class{SmartCookie}. This is probably a mistake -and will likely be removed in a future version. You should not use -the \class{Cookie} class in your applications, for the same reason why -you should not use the \class{SerialCookie} class. - - -\begin{seealso} - \seemodule{cookielib}{HTTP cookie handling for web - \emph{clients}. The \module{cookielib} and \module{Cookie} - modules do not depend on each other.} - - \seerfc{2109}{HTTP State Management Mechanism}{This is the state - management specification implemented by this module.} -\end{seealso} - - -\subsection{Cookie Objects \label{cookie-objects}} - -\begin{methoddesc}[BaseCookie]{value_decode}{val} -Return a decoded value from a string representation. Return value can -be any type. This method does nothing in \class{BaseCookie} --- it exists -so it can be overridden. -\end{methoddesc} - -\begin{methoddesc}[BaseCookie]{value_encode}{val} -Return an encoded value. \var{val} can be any type, but return value -must be a string. This method does nothing in \class{BaseCookie} --- it exists -so it can be overridden - -In general, it should be the case that \method{value_encode()} and -\method{value_decode()} are inverses on the range of \var{value_decode}. -\end{methoddesc} - -\begin{methoddesc}[BaseCookie]{output}{\optional{attrs\optional{, header\optional{, sep}}}} -Return a string representation suitable to be sent as HTTP headers. -\var{attrs} and \var{header} are sent to each \class{Morsel}'s -\method{output()} method. \var{sep} is used to join the headers -together, and is by default the combination \code{'\e r\e n'} (CRLF). -\versionchanged[The default separator has been changed from \code{'\e n'} -to match the cookie specification]{2.5} -\end{methoddesc} - -\begin{methoddesc}[BaseCookie]{js_output}{\optional{attrs}} -Return an embeddable JavaScript snippet, which, if run on a browser which -supports JavaScript, will act the same as if the HTTP headers was sent. - -The meaning for \var{attrs} is the same as in \method{output()}. -\end{methoddesc} - -\begin{methoddesc}[BaseCookie]{load}{rawdata} -If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add -the values found there as \class{Morsel}s. If it is a dictionary, it -is equivalent to: - -\begin{verbatim} -for k, v in rawdata.items(): - cookie[k] = v -\end{verbatim} -\end{methoddesc} - - -\subsection{Morsel Objects \label{morsel-objects}} - -\begin{classdesc}{Morsel}{} -Abstract a key/value pair, which has some \rfc{2109} attributes. - -Morsels are dictionary-like objects, whose set of keys is constant --- -the valid \rfc{2109} attributes, which are - -\begin{itemize} -\item \code{expires} -\item \code{path} -\item \code{comment} -\item \code{domain} -\item \code{max-age} -\item \code{secure} -\item \code{version} -\end{itemize} - -The keys are case-insensitive. -\end{classdesc} - -\begin{memberdesc}[Morsel]{value} -The value of the cookie. -\end{memberdesc} - -\begin{memberdesc}[Morsel]{coded_value} -The encoded value of the cookie --- this is what should be sent. -\end{memberdesc} - -\begin{memberdesc}[Morsel]{key} -The name of the cookie. -\end{memberdesc} - -\begin{methoddesc}[Morsel]{set}{key, value, coded_value} -Set the \var{key}, \var{value} and \var{coded_value} members. -\end{methoddesc} - -\begin{methoddesc}[Morsel]{isReservedKey}{K} -Whether \var{K} is a member of the set of keys of a \class{Morsel}. -\end{methoddesc} - -\begin{methoddesc}[Morsel]{output}{\optional{attrs\optional{, header}}} -Return a string representation of the Morsel, suitable -to be sent as an HTTP header. By default, all the attributes are included, -unless \var{attrs} is given, in which case it should be a list of attributes -to use. \var{header} is by default \code{"Set-Cookie:"}. -\end{methoddesc} - -\begin{methoddesc}[Morsel]{js_output}{\optional{attrs}} -Return an embeddable JavaScript snippet, which, if run on a browser which -supports JavaScript, will act the same as if the HTTP header was sent. - -The meaning for \var{attrs} is the same as in \method{output()}. -\end{methoddesc} - -\begin{methoddesc}[Morsel]{OutputString}{\optional{attrs}} -Return a string representing the Morsel, without any surrounding HTTP -or JavaScript. - -The meaning for \var{attrs} is the same as in \method{output()}. -\end{methoddesc} - - -\subsection{Example \label{cookie-example}} - -The following example demonstrates how to use the \module{Cookie} module. - -\begin{verbatim} ->>> import Cookie ->>> C = Cookie.SimpleCookie() ->>> C = Cookie.SerialCookie() ->>> C = Cookie.SmartCookie() ->>> C["fig"] = "newton" ->>> C["sugar"] = "wafer" ->>> print C # generate HTTP headers -Set-Cookie: sugar=wafer -Set-Cookie: fig=newton ->>> print C.output() # same thing -Set-Cookie: sugar=wafer -Set-Cookie: fig=newton ->>> C = Cookie.SmartCookie() ->>> C["rocky"] = "road" ->>> C["rocky"]["path"] = "/cookie" ->>> print C.output(header="Cookie:") -Cookie: rocky=road; Path=/cookie ->>> print C.output(attrs=[], header="Cookie:") -Cookie: rocky=road ->>> C = Cookie.SmartCookie() ->>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header) ->>> print C -Set-Cookie: vienna=finger -Set-Cookie: chips=ahoy ->>> C = Cookie.SmartCookie() ->>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";') ->>> print C -Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;" ->>> C = Cookie.SmartCookie() ->>> C["oreo"] = "doublestuff" ->>> C["oreo"]["path"] = "/" ->>> print C -Set-Cookie: oreo=doublestuff; Path=/ ->>> C = Cookie.SmartCookie() ->>> C["twix"] = "none for you" ->>> C["twix"].value -'none for you' ->>> C = Cookie.SimpleCookie() ->>> C["number"] = 7 # equivalent to C["number"] = str(7) ->>> C["string"] = "seven" ->>> C["number"].value -'7' ->>> C["string"].value -'seven' ->>> print C -Set-Cookie: number=7 -Set-Cookie: string=seven ->>> C = Cookie.SerialCookie() ->>> C["number"] = 7 ->>> C["string"] = "seven" ->>> C["number"].value -7 ->>> C["string"].value -'seven' ->>> print C -Set-Cookie: number="I7\012." -Set-Cookie: string="S'seven'\012p1\012." ->>> C = Cookie.SmartCookie() ->>> C["number"] = 7 ->>> C["string"] = "seven" ->>> C["number"].value -7 ->>> C["string"].value -'seven' ->>> print C -Set-Cookie: number="I7\012." -Set-Cookie: string=seven -\end{verbatim} diff --git a/Doc/lib/libcookielib.tex b/Doc/lib/libcookielib.tex deleted file mode 100644 index 2ea3554..0000000 --- a/Doc/lib/libcookielib.tex +++ /dev/null @@ -1,720 +0,0 @@ -\section{\module{cookielib} --- - Cookie handling for HTTP clients} - -\declaremodule{standard}{cookielib} -\moduleauthor{John J. Lee}{jjl@pobox.com} -\sectionauthor{John J. Lee}{jjl@pobox.com} - -\versionadded{2.4} - -\modulesynopsis{Cookie handling for HTTP clients} - -The \module{cookielib} module defines classes for automatic handling -of HTTP cookies. It is useful for accessing web sites that require -small pieces of data -- \dfn{cookies} -- to be set on the client -machine by an HTTP response from a web server, and then returned to -the server in later HTTP requests. - -Both the regular Netscape cookie protocol and the protocol defined by -\rfc{2965} are handled. RFC 2965 handling is switched off by default. -\rfc{2109} cookies are parsed as Netscape cookies and subsequently -treated either as Netscape or RFC 2965 cookies according to the -'policy' in effect. Note that the great majority of cookies on the -Internet are Netscape cookies. \module{cookielib} attempts to follow -the de-facto Netscape cookie protocol (which differs substantially -from that set out in the original Netscape specification), including -taking note of the \code{max-age} and \code{port} cookie-attributes -introduced with RFC 2965. \note{The various named parameters found in -\mailheader{Set-Cookie} and \mailheader{Set-Cookie2} headers -(eg. \code{domain} and \code{expires}) are conventionally referred to -as \dfn{attributes}. To distinguish them from Python attributes, the -documentation for this module uses the term \dfn{cookie-attribute} -instead}. - - -The module defines the following exception: - -\begin{excdesc}{LoadError} -Instances of \class{FileCookieJar} raise this exception on failure to -load cookies from a file. \note{For backwards-compatibility -with Python 2.4 (which raised an \exception{IOError}), -\exception{LoadError} is a subclass of \exception{IOError}}. -\end{excdesc} - - -The following classes are provided: - -\begin{classdesc}{CookieJar}{policy=\constant{None}} -\var{policy} is an object implementing the \class{CookiePolicy} -interface. - -The \class{CookieJar} class stores HTTP cookies. It extracts cookies -from HTTP requests, and returns them in HTTP responses. -\class{CookieJar} instances automatically expire contained cookies -when necessary. Subclasses are also responsible for storing and -retrieving cookies from a file or database. -\end{classdesc} - -\begin{classdesc}{FileCookieJar}{filename, delayload=\constant{None}, - policy=\constant{None}} -\var{policy} is an object implementing the \class{CookiePolicy} -interface. For the other arguments, see the documentation for the -corresponding attributes. - -A \class{CookieJar} which can load cookies from, and perhaps save -cookies to, a file on disk. Cookies are \strong{NOT} loaded from the -named file until either the \method{load()} or \method{revert()} -method is called. Subclasses of this class are documented in section -\ref{file-cookie-jar-classes}. -\end{classdesc} - -\begin{classdesc}{CookiePolicy}{} -This class is responsible for deciding whether each cookie should be -accepted from / returned to the server. -\end{classdesc} - -\begin{classdesc}{DefaultCookiePolicy}{ - blocked_domains=\constant{None}, - allowed_domains=\constant{None}, - netscape=\constant{True}, rfc2965=\constant{False}, - rfc2109_as_netscape=\constant{None}, - hide_cookie2=\constant{False}, - strict_domain=\constant{False}, - strict_rfc2965_unverifiable=\constant{True}, - strict_ns_unverifiable=\constant{False}, - strict_ns_domain=\constant{DefaultCookiePolicy.DomainLiberal}, - strict_ns_set_initial_dollar=\constant{False}, - strict_ns_set_path=\constant{False} - } - -Constructor arguments should be passed as keyword arguments only. -\var{blocked_domains} is a sequence of domain names that we never -accept cookies from, nor return cookies to. \var{allowed_domains} if -not \constant{None}, this is a sequence of the only domains for which -we accept and return cookies. For all other arguments, see the -documentation for \class{CookiePolicy} and \class{DefaultCookiePolicy} -objects. - -\class{DefaultCookiePolicy} implements the standard accept / reject -rules for Netscape and RFC 2965 cookies. By default, RFC 2109 cookies -(ie. cookies received in a \mailheader{Set-Cookie} header with a -version cookie-attribute of 1) are treated according to the RFC 2965 -rules. However, if RFC 2965 handling is turned off or -\member{rfc2109_as_netscape} is True, RFC 2109 cookies are -'downgraded' by the \class{CookieJar} instance to Netscape cookies, by -setting the \member{version} attribute of the \class{Cookie} instance -to 0. \class{DefaultCookiePolicy} also provides some parameters to -allow some fine-tuning of policy. -\end{classdesc} - -\begin{classdesc}{Cookie}{} -This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is -not expected that users of \module{cookielib} construct their own -\class{Cookie} instances. Instead, if necessary, call -\method{make_cookies()} on a \class{CookieJar} instance. -\end{classdesc} - -\begin{seealso} - -\seemodule{urllib2}{URL opening with automatic cookie handling.} - -\seemodule{Cookie}{HTTP cookie classes, principally useful for -server-side code. The \module{cookielib} and \module{Cookie} modules -do not depend on each other.} - -\seeurl{http://wwwsearch.sf.net/ClientCookie/}{Extensions to this -module, including a class for reading Microsoft Internet Explorer -cookies on Windows.} - -\seeurl{http://www.netscape.com/newsref/std/cookie_spec.html}{The -specification of the original Netscape cookie protocol. Though this -is still the dominant protocol, the 'Netscape cookie protocol' -implemented by all the major browsers (and \module{cookielib}) only -bears a passing resemblance to the one sketched out in -\code{cookie_spec.html}.} - -\seerfc{2109}{HTTP State Management Mechanism}{Obsoleted by RFC 2965. -Uses \mailheader{Set-Cookie} with version=1.} - -\seerfc{2965}{HTTP State Management Mechanism}{The Netscape protocol -with the bugs fixed. Uses \mailheader{Set-Cookie2} in place of -\mailheader{Set-Cookie}. Not widely used.} - -\seeurl{http://kristol.org/cookie/errata.html}{Unfinished errata to -RFC 2965.} - -\seerfc{2964}{Use of HTTP State Management}{} - -\end{seealso} - - -\subsection{CookieJar and FileCookieJar Objects \label{cookie-jar-objects}} - -\class{CookieJar} objects support the iterator protocol for iterating -over contained \class{Cookie} objects. - -\class{CookieJar} has the following methods: - -\begin{methoddesc}[CookieJar]{add_cookie_header}{request} -Add correct \mailheader{Cookie} header to \var{request}. - -If policy allows (ie. the \member{rfc2965} and \member{hide_cookie2} -attributes of the \class{CookieJar}'s \class{CookiePolicy} instance -are true and false respectively), the \mailheader{Cookie2} header is -also added when appropriate. - -The \var{request} object (usually a \class{urllib2.Request} instance) -must support the methods \method{get_full_url()}, \method{get_host()}, -\method{get_type()}, \method{unverifiable()}, -\method{get_origin_req_host()}, \method{has_header()}, -\method{get_header()}, \method{header_items()}, and -\method{add_unredirected_header()},as documented by \module{urllib2}. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{extract_cookies}{response, request} -Extract cookies from HTTP \var{response} and store them in the -\class{CookieJar}, where allowed by policy. - -The \class{CookieJar} will look for allowable \mailheader{Set-Cookie} -and \mailheader{Set-Cookie2} headers in the \var{response} argument, -and store cookies as appropriate (subject to the -\method{CookiePolicy.set_ok()} method's approval). - -The \var{response} object (usually the result of a call to -\method{urllib2.urlopen()}, or similar) should support an -\method{info()} method, which returns an object with a -\method{getallmatchingheaders()} method (usually a -\class{mimetools.Message} instance). - -The \var{request} object (usually a \class{urllib2.Request} instance) -must support the methods \method{get_full_url()}, \method{get_host()}, -\method{unverifiable()}, and \method{get_origin_req_host()}, as -documented by \module{urllib2}. The request is used to set default -values for cookie-attributes as well as for checking that the cookie -is allowed to be set. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{set_policy}{policy} -Set the \class{CookiePolicy} instance to be used. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{make_cookies}{response, request} -Return sequence of \class{Cookie} objects extracted from -\var{response} object. - -See the documentation for \method{extract_cookies} for the interfaces -required of the \var{response} and \var{request} arguments. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{set_cookie_if_ok}{cookie, request} -Set a \class{Cookie} if policy says it's OK to do so. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{set_cookie}{cookie} -Set a \class{Cookie}, without checking with policy to see whether or -not it should be set. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{clear}{\optional{domain\optional{, - path\optional{, name}}}} -Clear some cookies. - -If invoked without arguments, clear all cookies. If given a single -argument, only cookies belonging to that \var{domain} will be removed. -If given two arguments, cookies belonging to the specified -\var{domain} and URL \var{path} are removed. If given three -arguments, then the cookie with the specified \var{domain}, \var{path} -and \var{name} is removed. - -Raises \exception{KeyError} if no matching cookie exists. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{clear_session_cookies}{} -Discard all session cookies. - -Discards all contained cookies that have a true \member{discard} -attribute (usually because they had either no \code{max-age} or -\code{expires} cookie-attribute, or an explicit \code{discard} -cookie-attribute). For interactive browsers, the end of a session -usually corresponds to closing the browser window. - -Note that the \method{save()} method won't save session cookies -anyway, unless you ask otherwise by passing a true -\var{ignore_discard} argument. -\end{methoddesc} - -\class{FileCookieJar} implements the following additional methods: - -\begin{methoddesc}[FileCookieJar]{save}{filename=\constant{None}, - ignore_discard=\constant{False}, ignore_expires=\constant{False}} -Save cookies to a file. - -This base class raises \exception{NotImplementedError}. Subclasses may -leave this method unimplemented. - -\var{filename} is the name of file in which to save cookies. If -\var{filename} is not specified, \member{self.filename} is used (whose -default is the value passed to the constructor, if any); if -\member{self.filename} is \constant{None}, \exception{ValueError} is -raised. - -\var{ignore_discard}: save even cookies set to be discarded. -\var{ignore_expires}: save even cookies that have expired - -The file is overwritten if it already exists, thus wiping all the -cookies it contains. Saved cookies can be restored later using the -\method{load()} or \method{revert()} methods. -\end{methoddesc} - -\begin{methoddesc}[FileCookieJar]{load}{filename=\constant{None}, - ignore_discard=\constant{False}, ignore_expires=\constant{False}} -Load cookies from a file. - -Old cookies are kept unless overwritten by newly loaded ones. - -Arguments are as for \method{save()}. - -The named file must be in the format understood by the class, or -\exception{LoadError} will be raised. Also, \exception{IOError} may -be raised, for example if the file does not exist. \note{For -backwards-compatibility with Python 2.4 (which raised -an \exception{IOError}), \exception{LoadError} is a subclass -of \exception{IOError}.} -\end{methoddesc} - -\begin{methoddesc}[FileCookieJar]{revert}{filename=\constant{None}, - ignore_discard=\constant{False}, ignore_expires=\constant{False}} -Clear all cookies and reload cookies from a saved file. - -\method{revert()} can raise the same exceptions as \method{load()}. -If there is a failure, the object's state will not be altered. -\end{methoddesc} - -\class{FileCookieJar} instances have the following public attributes: - -\begin{memberdesc}[FileCookieJar]{filename} -Filename of default file in which to keep cookies. This attribute may -be assigned to. -\end{memberdesc} - -\begin{memberdesc}[FileCookieJar]{delayload} -If true, load cookies lazily from disk. This attribute should not be -assigned to. This is only a hint, since this only affects -performance, not behaviour (unless the cookies on disk are changing). -A \class{CookieJar} object may ignore it. None of the -\class{FileCookieJar} classes included in the standard library lazily -loads cookies. -\end{memberdesc} - - -\subsection{FileCookieJar subclasses and co-operation with web browsers - \label{file-cookie-jar-classes}} - -The following \class{CookieJar} subclasses are provided for reading -and writing . Further \class{CookieJar} subclasses, including one -that reads Microsoft Internet Explorer cookies, are available at -\url{http://wwwsearch.sf.net/ClientCookie/}. - -\begin{classdesc}{MozillaCookieJar}{filename, delayload=\constant{None}, - policy=\constant{None}} -A \class{FileCookieJar} that can load from and save cookies to disk in -the Mozilla \code{cookies.txt} file format (which is also used by the -Lynx and Netscape browsers). \note{This loses information about RFC -2965 cookies, and also about newer or non-standard cookie-attributes -such as \code{port}.} - -\warning{Back up your cookies before saving if you have cookies whose -loss / corruption would be inconvenient (there are some subtleties -which may lead to slight changes in the file over a load / save -round-trip).} - -Also note that cookies saved while Mozilla is running will get -clobbered by Mozilla. -\end{classdesc} - -\begin{classdesc}{LWPCookieJar}{filename, delayload=\constant{None}, - policy=\constant{None}} -A \class{FileCookieJar} that can load from and save cookies to disk in -format compatible with the libwww-perl library's \code{Set-Cookie3} -file format. This is convenient if you want to store cookies in a -human-readable file. -\end{classdesc} - - -\subsection{CookiePolicy Objects \label{cookie-policy-objects}} - -Objects implementing the \class{CookiePolicy} interface have the -following methods: - -\begin{methoddesc}[CookiePolicy]{set_ok}{cookie, request} -Return boolean value indicating whether cookie should be accepted from server. - -\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is -an object implementing the interface defined by the documentation for -\method{CookieJar.extract_cookies()}. -\end{methoddesc} - -\begin{methoddesc}[CookiePolicy]{return_ok}{cookie, request} -Return boolean value indicating whether cookie should be returned to server. - -\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is -an object implementing the interface defined by the documentation for -\method{CookieJar.add_cookie_header()}. -\end{methoddesc} - -\begin{methoddesc}[CookiePolicy]{domain_return_ok}{domain, request} -Return false if cookies should not be returned, given cookie domain. - -This method is an optimization. It removes the need for checking -every cookie with a particular domain (which might involve reading -many files). Returning true from \method{domain_return_ok()} and -\method{path_return_ok()} leaves all the work to \method{return_ok()}. - -If \method{domain_return_ok()} returns true for the cookie domain, -\method{path_return_ok()} is called for the cookie path. Otherwise, -\method{path_return_ok()} and \method{return_ok()} are never called -for that cookie domain. If \method{path_return_ok()} returns true, -\method{return_ok()} is called with the \class{Cookie} object itself -for a full check. Otherwise, \method{return_ok()} is never called for -that cookie path. - -Note that \method{domain_return_ok()} is called for every -\emph{cookie} domain, not just for the \emph{request} domain. For -example, the function might be called with both \code{".example.com"} -and \code{"www.example.com"} if the request domain is -\code{"www.example.com"}. The same goes for -\method{path_return_ok()}. - -The \var{request} argument is as documented for \method{return_ok()}. -\end{methoddesc} - -\begin{methoddesc}[CookiePolicy]{path_return_ok}{path, request} -Return false if cookies should not be returned, given cookie path. - -See the documentation for \method{domain_return_ok()}. -\end{methoddesc} - - -In addition to implementing the methods above, implementations of the -\class{CookiePolicy} interface must also supply the following -attributes, indicating which protocols should be used, and how. All -of these attributes may be assigned to. - -\begin{memberdesc}[CookiePolicy]{netscape} -Implement Netscape protocol. -\end{memberdesc} -\begin{memberdesc}[CookiePolicy]{rfc2965} -Implement RFC 2965 protocol. -\end{memberdesc} -\begin{memberdesc}[CookiePolicy]{hide_cookie2} -Don't add \mailheader{Cookie2} header to requests (the presence of -this header indicates to the server that we understand RFC 2965 -cookies). -\end{memberdesc} - -The most useful way to define a \class{CookiePolicy} class is by -subclassing from \class{DefaultCookiePolicy} and overriding some or -all of the methods above. \class{CookiePolicy} itself may be used as -a 'null policy' to allow setting and receiving any and all cookies -(this is unlikely to be useful). - - -\subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-objects}} - -Implements the standard rules for accepting and returning cookies. - -Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is -switched off by default. - -The easiest way to provide your own policy is to override this class -and call its methods in your overridden implementations before adding -your own additional checks: - -\begin{verbatim} -import cookielib -class MyCookiePolicy(cookielib.DefaultCookiePolicy): - def set_ok(self, cookie, request): - if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request): - return False - if i_dont_want_to_store_this_cookie(cookie): - return False - return True -\end{verbatim} - -In addition to the features required to implement the -\class{CookiePolicy} interface, this class allows you to block and -allow domains from setting and receiving cookies. There are also some -strictness switches that allow you to tighten up the rather loose -Netscape protocol rules a little bit (at the cost of blocking some -benign cookies). - -A domain blacklist and whitelist is provided (both off by default). -Only domains not in the blacklist and present in the whitelist (if the -whitelist is active) participate in cookie setting and returning. Use -the \var{blocked_domains} constructor argument, and -\method{blocked_domains()} and \method{set_blocked_domains()} methods -(and the corresponding argument and methods for -\var{allowed_domains}). If you set a whitelist, you can turn it off -again by setting it to \constant{None}. - -Domains in block or allow lists that do not start with a dot must -equal the cookie domain to be matched. For example, -\code{"example.com"} matches a blacklist entry of -\code{"example.com"}, but \code{"www.example.com"} does not. Domains -that do start with a dot are matched by more specific domains too. -For example, both \code{"www.example.com"} and -\code{"www.coyote.example.com"} match \code{".example.com"} (but -\code{"example.com"} itself does not). IP addresses are an exception, -and must match exactly. For example, if blocked_domains contains -\code{"192.168.1.2"} and \code{".168.1.2"}, 192.168.1.2 is blocked, -but 193.168.1.2 is not. - -\class{DefaultCookiePolicy} implements the following additional -methods: - -\begin{methoddesc}[DefaultCookiePolicy]{blocked_domains}{} -Return the sequence of blocked domains (as a tuple). -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{set_blocked_domains} - {blocked_domains} -Set the sequence of blocked domains. -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{is_blocked}{domain} -Return whether \var{domain} is on the blacklist for setting or -receiving cookies. -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{allowed_domains}{} -Return \constant{None}, or the sequence of allowed domains (as a tuple). -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{set_allowed_domains} - {allowed_domains} -Set the sequence of allowed domains, or \constant{None}. -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{is_not_allowed}{domain} -Return whether \var{domain} is not on the whitelist for setting or -receiving cookies. -\end{methoddesc} - -\class{DefaultCookiePolicy} instances have the following attributes, -which are all initialised from the constructor arguments of the same -name, and which may all be assigned to. - -\begin{memberdesc}[DefaultCookiePolicy]{rfc2109_as_netscape} -If true, request that the \class{CookieJar} instance downgrade RFC -2109 cookies (ie. cookies received in a \mailheader{Set-Cookie} header -with a version cookie-attribute of 1) to Netscape cookies by setting -the version attribute of the \class{Cookie} instance to 0. The -default value is \constant{None}, in which case RFC 2109 cookies are -downgraded if and only if RFC 2965 handling is turned off. Therefore, -RFC 2109 cookies are downgraded by default. -\versionadded{2.5} -\end{memberdesc} - -General strictness switches: - -\begin{memberdesc}[DefaultCookiePolicy]{strict_domain} -Don't allow sites to set two-component domains with country-code -top-level domains like \code{.co.uk}, \code{.gov.uk}, -\code{.co.nz}.etc. This is far from perfect and isn't guaranteed to -work! -\end{memberdesc} - -RFC 2965 protocol strictness switches: - -\begin{memberdesc}[DefaultCookiePolicy]{strict_rfc2965_unverifiable} -Follow RFC 2965 rules on unverifiable transactions (usually, an -unverifiable transaction is one resulting from a redirect or a request -for an image hosted on another site). If this is false, cookies are -\emph{never} blocked on the basis of verifiability -\end{memberdesc} - -Netscape protocol strictness switches: - -\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_unverifiable} -apply RFC 2965 rules on unverifiable transactions even to Netscape -cookies -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_domain} -Flags indicating how strict to be with domain-matching rules for -Netscape cookies. See below for acceptable values. -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_set_initial_dollar} -Ignore cookies in Set-Cookie: headers that have names starting with -\code{'\$'}. -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_set_path} -Don't allow setting cookies whose path doesn't path-match request URI. -\end{memberdesc} - -\member{strict_ns_domain} is a collection of flags. Its value is -constructed by or-ing together (for example, -\code{DomainStrictNoDots|DomainStrictNonDomain} means both flags are -set). - -\begin{memberdesc}[DefaultCookiePolicy]{DomainStrictNoDots} -When setting cookies, the 'host prefix' must not contain a dot -(eg. \code{www.foo.bar.com} can't set a cookie for \code{.bar.com}, -because \code{www.foo} contains a dot). -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{DomainStrictNonDomain} -Cookies that did not explicitly specify a \code{domain} -cookie-attribute can only be returned to a domain equal to the domain -that set the cookie (eg. \code{spam.example.com} won't be returned -cookies from \code{example.com} that had no \code{domain} -cookie-attribute). -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{DomainRFC2965Match} -When setting cookies, require a full RFC 2965 domain-match. -\end{memberdesc} - -The following attributes are provided for convenience, and are the -most useful combinations of the above flags: - -\begin{memberdesc}[DefaultCookiePolicy]{DomainLiberal} -Equivalent to 0 (ie. all of the above Netscape domain strictness flags -switched off). -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{DomainStrict} -Equivalent to \code{DomainStrictNoDots|DomainStrictNonDomain}. -\end{memberdesc} - - -\subsection{Cookie Objects \label{cookie-objects}} - -\class{Cookie} instances have Python attributes roughly corresponding -to the standard cookie-attributes specified in the various cookie -standards. The correspondence is not one-to-one, because there are -complicated rules for assigning default values, because the -\code{max-age} and \code{expires} cookie-attributes contain equivalent -information, and because RFC 2109 cookies may be 'downgraded' by -\module{cookielib} from version 1 to version 0 (Netscape) cookies. - -Assignment to these attributes should not be necessary other than in -rare circumstances in a \class{CookiePolicy} method. The class does -not enforce internal consistency, so you should know what you're -doing if you do that. - -\begin{memberdesc}[Cookie]{version} -Integer or \constant{None}. Netscape cookies have \member{version} 0. -RFC 2965 and RFC 2109 cookies have a \code{version} cookie-attribute -of 1. However, note that \module{cookielib} may 'downgrade' RFC 2109 -cookies to Netscape cookies, in which case \member{version} is 0. -\end{memberdesc} -\begin{memberdesc}[Cookie]{name} -Cookie name (a string). -\end{memberdesc} -\begin{memberdesc}[Cookie]{value} -Cookie value (a string), or \constant{None}. -\end{memberdesc} -\begin{memberdesc}[Cookie]{port} -String representing a port or a set of ports (eg. '80', or '80,8080'), -or \constant{None}. -\end{memberdesc} -\begin{memberdesc}[Cookie]{path} -Cookie path (a string, eg. \code{'/acme/rocket_launchers'}). -\end{memberdesc} -\begin{memberdesc}[Cookie]{secure} -True if cookie should only be returned over a secure connection. -\end{memberdesc} -\begin{memberdesc}[Cookie]{expires} -Integer expiry date in seconds since epoch, or \constant{None}. See -also the \method{is_expired()} method. -\end{memberdesc} -\begin{memberdesc}[Cookie]{discard} -True if this is a session cookie. -\end{memberdesc} -\begin{memberdesc}[Cookie]{comment} -String comment from the server explaining the function of this cookie, -or \constant{None}. -\end{memberdesc} -\begin{memberdesc}[Cookie]{comment_url} -URL linking to a comment from the server explaining the function of -this cookie, or \constant{None}. -\end{memberdesc} -\begin{memberdesc}[Cookie]{rfc2109} -True if this cookie was received as an RFC 2109 cookie (ie. the cookie -arrived in a \mailheader{Set-Cookie} header, and the value of the -Version cookie-attribute in that header was 1). This attribute is -provided because \module{cookielib} may 'downgrade' RFC 2109 cookies -to Netscape cookies, in which case \member{version} is 0. -\versionadded{2.5} -\end{memberdesc} - -\begin{memberdesc}[Cookie]{port_specified} -True if a port or set of ports was explicitly specified by the server -(in the \mailheader{Set-Cookie} / \mailheader{Set-Cookie2} header). -\end{memberdesc} -\begin{memberdesc}[Cookie]{domain_specified} -True if a domain was explicitly specified by the server. -\end{memberdesc} -\begin{memberdesc}[Cookie]{domain_initial_dot} -True if the domain explicitly specified by the server began with a -dot (\code{'.'}). -\end{memberdesc} - -Cookies may have additional non-standard cookie-attributes. These may -be accessed using the following methods: - -\begin{methoddesc}[Cookie]{has_nonstandard_attr}{name} -Return true if cookie has the named cookie-attribute. -\end{methoddesc} -\begin{methoddesc}[Cookie]{get_nonstandard_attr}{name, default=\constant{None}} -If cookie has the named cookie-attribute, return its value. -Otherwise, return \var{default}. -\end{methoddesc} -\begin{methoddesc}[Cookie]{set_nonstandard_attr}{name, value} -Set the value of the named cookie-attribute. -\end{methoddesc} - -The \class{Cookie} class also defines the following method: - -\begin{methoddesc}[Cookie]{is_expired}{\optional{now=\constant{None}}} -True if cookie has passed the time at which the server requested it -should expire. If \var{now} is given (in seconds since the epoch), -return whether the cookie has expired at the specified time. -\end{methoddesc} - - -\subsection{Examples \label{cookielib-examples}} - -The first example shows the most common usage of \module{cookielib}: - -\begin{verbatim} -import cookielib, urllib2 -cj = cookielib.CookieJar() -opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj)) -r = opener.open("http://example.com/") -\end{verbatim} - -This example illustrates how to open a URL using your Netscape, -Mozilla, or Lynx cookies (assumes \UNIX{}/Netscape convention for -location of the cookies file): - -\begin{verbatim} -import os, cookielib, urllib2 -cj = cookielib.MozillaCookieJar() -cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt")) -opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj)) -r = opener.open("http://example.com/") -\end{verbatim} - -The next example illustrates the use of \class{DefaultCookiePolicy}. -Turn on RFC 2965 cookies, be more strict about domains when setting -and returning Netscape cookies, and block some domains from setting -cookies or having them returned: - -\begin{verbatim} -import urllib2 -from cookielib import CookieJar, DefaultCookiePolicy -policy = DefaultCookiePolicy( - rfc2965=True, strict_ns_domain=Policy.DomainStrict, - blocked_domains=["ads.net", ".ads.net"]) -cj = CookieJar(policy) -opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj)) -r = opener.open("http://example.com/") -\end{verbatim} diff --git a/Doc/lib/libcopy.tex b/Doc/lib/libcopy.tex deleted file mode 100644 index 5964187..0000000 --- a/Doc/lib/libcopy.tex +++ /dev/null @@ -1,97 +0,0 @@ -\section{\module{copy} --- - Shallow and deep copy operations} - -\declaremodule{standard}{copy} -\modulesynopsis{Shallow and deep copy operations.} - - -This module provides generic (shallow and deep) copying operations. -\withsubitem{(in copy)}{\ttindex{copy()}\ttindex{deepcopy()}} - -Interface summary: - -\begin{verbatim} -import copy - -x = copy.copy(y) # make a shallow copy of y -x = copy.deepcopy(y) # make a deep copy of y -\end{verbatim} -% -For module specific errors, \exception{copy.error} is raised. - -The difference between shallow and deep copying is only relevant for -compound objects (objects that contain other objects, like lists or -class instances): - -\begin{itemize} - -\item -A \emph{shallow copy} constructs a new compound object and then (to the -extent possible) inserts \emph{references} into it to the objects found -in the original. - -\item -A \emph{deep copy} constructs a new compound object and then, -recursively, inserts \emph{copies} into it of the objects found in the -original. - -\end{itemize} - -Two problems often exist with deep copy operations that don't exist -with shallow copy operations: - -\begin{itemize} - -\item -Recursive objects (compound objects that, directly or indirectly, -contain a reference to themselves) may cause a recursive loop. - -\item -Because deep copy copies \emph{everything} it may copy too much, -e.g., administrative data structures that should be shared even -between copies. - -\end{itemize} - -The \function{deepcopy()} function avoids these problems by: - -\begin{itemize} - -\item -keeping a ``memo'' dictionary of objects already copied during the current -copying pass; and - -\item -letting user-defined classes override the copying operation or the -set of components copied. - -\end{itemize} - -This module does not copy types like module, method, -stack trace, stack frame, file, socket, window, array, or any similar -types. It does ``copy'' functions and classes (shallow and deeply), -by returning the original object unchanged; this is compatible with -the way these are treated by the \module{pickle} module. -\versionchanged[Added copying functions]{2.5} - -Classes can use the same interfaces to control copying that they use -to control pickling. See the description of module -\refmodule{pickle}\refstmodindex{pickle} for information on these -methods. The \module{copy} module does not use the -\refmodule[copyreg]{copy_reg} registration module. - -In order for a class to define its own copy implementation, it can -define special methods \method{__copy__()} and -\method{__deepcopy__()}. The former is called to implement the -shallow copy operation; no additional arguments are passed. The -latter is called to implement the deep copy operation; it is passed -one argument, the memo dictionary. If the \method{__deepcopy__()} -implementation needs to make a deep copy of a component, it should -call the \function{deepcopy()} function with the component as first -argument and the memo dictionary as second argument. -\withsubitem{(copy protocol)}{\ttindex{__copy__()}\ttindex{__deepcopy__()}} - -\begin{seealso} -\seemodule{pickle}{Discussion of the special methods used to -support object state retrieval and restoration.} -\end{seealso} diff --git a/Doc/lib/libcopyreg.tex b/Doc/lib/libcopyreg.tex deleted file mode 100644 index 594978c..0000000 --- a/Doc/lib/libcopyreg.tex +++ /dev/null @@ -1,40 +0,0 @@ -\section{\module{copy_reg} --- - Register \module{pickle} support functions} - -\declaremodule[copyreg]{standard}{copy_reg} -\modulesynopsis{Register \module{pickle} support functions.} - - -The \module{copy_reg} module provides support for the -\refmodule{pickle}\refstmodindex{pickle}\ and -\refmodule{cPickle}\refbimodindex{cPickle}\ modules. The -\refmodule{copy}\refstmodindex{copy}\ module is likely to use this in the -future as well. It provides configuration information about object -constructors which are not classes. Such constructors may be factory -functions or class instances. - - -\begin{funcdesc}{constructor}{object} - Declares \var{object} to be a valid constructor. If \var{object} is - not callable (and hence not valid as a constructor), raises - \exception{TypeError}. -\end{funcdesc} - -\begin{funcdesc}{pickle}{type, function\optional{, constructor}} - Declares that \var{function} should be used as a ``reduction'' - function for objects of type \var{type}; \var{type} must not be a - ``classic'' class object. (Classic classes are handled differently; - see the documentation for the \refmodule{pickle} module for - details.) \var{function} should return either a string or a tuple - containing two or three elements. - - The optional \var{constructor} parameter, if provided, is a - callable object which can be used to reconstruct the object when - called with the tuple of arguments returned by \var{function} at - pickling time. \exception{TypeError} will be raised if - \var{object} is a class or \var{constructor} is not callable. - - See the \refmodule{pickle} module for more - details on the interface expected of \var{function} and - \var{constructor}. -\end{funcdesc} diff --git a/Doc/lib/libcrypt.tex b/Doc/lib/libcrypt.tex deleted file mode 100644 index 55e7163..0000000 --- a/Doc/lib/libcrypt.tex +++ /dev/null @@ -1,60 +0,0 @@ -\section{\module{crypt} --- - Function to check \UNIX{} passwords} - -\declaremodule{builtin}{crypt} - \platform{Unix} -\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}\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. - -Notice that the behavior of this module depends on the actual implementation -of the \manpage{crypt}{3}\index{crypt(3)} routine in the running system. -Therefore, any extensions available on the current implementation will also -be available on this module. -\begin{funcdesc}{crypt}{word, 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). - - Since a few \manpage{crypt}{3}\index{crypt(3)} extensions allow different - values, with different sizes in the \var{salt}, it is recommended to use - the full crypted password as salt when checking for a password. -\end{funcdesc} - - -A simple example illustrating typical use: - -\begin{verbatim} -import crypt, getpass, pwd - -def raw_input(prompt): - import sys - sys.stdout.write(prompt) - sys.stdout.flush() - return sys.stdin.readline() - -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) == cryptedpasswd - else: - return 1 -\end{verbatim} diff --git a/Doc/lib/libcrypto.tex b/Doc/lib/libcrypto.tex deleted file mode 100644 index 75987bf..0000000 --- a/Doc/lib/libcrypto.tex +++ /dev/null @@ -1,19 +0,0 @@ -\chapter{Cryptographic Services} -\label{crypto} -\index{cryptography} - -The modules described in this chapter implement various algorithms of -a cryptographic nature. They are available at the discretion of the -installation. Here's an overview: - -\localmoduletable - -Hardcore cypherpunks will probably find the cryptographic modules -written by A.M. Kuchling of further interest; the package contains -modules for various encryption algorithms, most notably AES. These modules -are not distributed with Python but available separately. See the URL -\url{http://www.amk.ca/python/code/crypto.html} -for more information. -\indexii{AES}{algorithm} -\index{cryptography} -\index{Kuchling, Andrew} diff --git a/Doc/lib/libcsv.tex b/Doc/lib/libcsv.tex deleted file mode 100644 index 54fc8db..0000000 --- a/Doc/lib/libcsv.tex +++ /dev/null @@ -1,538 +0,0 @@ -\section{\module{csv} --- CSV File Reading and Writing} - -\declaremodule{standard}{csv} -\modulesynopsis{Write and read tabular data to and from delimited files.} -\sectionauthor{Skip Montanaro}{skip@pobox.com} - -\versionadded{2.3} -\index{csv} -\indexii{data}{tabular} - -The so-called CSV (Comma Separated Values) format is the most common import -and export format for spreadsheets and databases. There is no ``CSV -standard'', so the format is operationally defined by the many applications -which read and write it. The lack of a standard means that subtle -differences often exist in the data produced and consumed by different -applications. These differences can make it annoying to process CSV files -from multiple sources. Still, while the delimiters and quoting characters -vary, the overall format is similar enough that it is possible to write a -single module which can efficiently manipulate such data, hiding the details -of reading and writing the data from the programmer. - -The \module{csv} module implements classes to read and write tabular data in -CSV format. It allows programmers to say, ``write this data in the format -preferred by Excel,'' or ``read data from this file which was generated by -Excel,'' without knowing the precise details of the CSV format used by -Excel. Programmers can also describe the CSV formats understood by other -applications or define their own special-purpose CSV formats. - -The \module{csv} module's \class{reader} and \class{writer} objects read and -write sequences. Programmers can also read and write data in dictionary -form using the \class{DictReader} and \class{DictWriter} classes. - -\begin{notice} - This version of the \module{csv} module doesn't support Unicode - input. Also, there are currently some issues regarding \ASCII{} NUL - characters. Accordingly, all input should be UTF-8 or printable - \ASCII{} to be safe; see the examples in section~\ref{csv-examples}. - These restrictions will be removed in the future. -\end{notice} - -\begin{seealso} -% \seemodule{array}{Arrays of uniformly types numeric values.} - \seepep{305}{CSV File API} - {The Python Enhancement Proposal which proposed this addition - to Python.} -\end{seealso} - - -\subsection{Module Contents \label{csv-contents}} - -The \module{csv} module defines the following functions: - -\begin{funcdesc}{reader}{csvfile\optional{, - dialect=\code{'excel'}}\optional{, fmtparam}} -Return a reader object which will iterate over lines in the given -{}\var{csvfile}. \var{csvfile} can be any object which supports the -iterator protocol and returns a string each time its \method{next} -method is called --- file objects and list objects are both suitable. -If \var{csvfile} is a file object, it must be opened with -the 'b' flag on platforms where that makes a difference. An optional -{}\var{dialect} parameter can be given -which is used to define a set of parameters specific to a particular CSV -dialect. It may be an instance of a subclass of the \class{Dialect} -class or one of the strings returned by the \function{list_dialects} -function. The other optional {}\var{fmtparam} keyword arguments can be -given to override individual formatting parameters in the current -dialect. For full details about the dialect and formatting -parameters, see section~\ref{csv-fmt-params}, ``Dialects and Formatting -Parameters''. - -All data read are returned as strings. No automatic data type -conversion is performed. - -\versionchanged[ -The parser is now stricter with respect to multi-line quoted -fields. Previously, if a line ended within a quoted field without a -terminating newline character, a newline would be inserted into the -returned field. This behavior caused problems when reading files -which contained carriage return characters within fields. The -behavior was changed to return the field without inserting newlines. As -a consequence, if newlines embedded within fields are important, the -input should be split into lines in a manner which preserves the newline -characters]{2.5} - -\end{funcdesc} - -\begin{funcdesc}{writer}{csvfile\optional{, - dialect=\code{'excel'}}\optional{, fmtparam}} -Return a writer object responsible for converting the user's data into -delimited strings on the given file-like object. \var{csvfile} can be any -object with a \function{write} method. If \var{csvfile} is a file object, -it must be opened with the 'b' flag on platforms where that makes a -difference. An optional -{}\var{dialect} parameter can be given which is used to define a set of -parameters specific to a particular CSV dialect. It may be an instance -of a subclass of the \class{Dialect} class or one of the strings -returned by the \function{list_dialects} function. The other optional -{}\var{fmtparam} keyword arguments can be given to override individual -formatting parameters in the current dialect. For full details -about the dialect and formatting parameters, see -section~\ref{csv-fmt-params}, ``Dialects and Formatting Parameters''. -To make it as easy as possible to -interface with modules which implement the DB API, the value -\constant{None} is written as the empty string. While this isn't a -reversible transformation, it makes it easier to dump SQL NULL data values -to CSV files without preprocessing the data returned from a -\code{cursor.fetch*()} call. All other non-string data are stringified -with \function{str()} before being written. -\end{funcdesc} - -\begin{funcdesc}{register_dialect}{name\optional{, dialect}\optional{, fmtparam}} -Associate \var{dialect} with \var{name}. \var{name} must be a string -or Unicode object. The dialect can be specified either by passing a -sub-class of \class{Dialect}, or by \var{fmtparam} keyword arguments, -or both, with keyword arguments overriding parameters of the dialect. -For full details about the dialect and formatting parameters, see -section~\ref{csv-fmt-params}, ``Dialects and Formatting Parameters''. -\end{funcdesc} - -\begin{funcdesc}{unregister_dialect}{name} -Delete the dialect associated with \var{name} from the dialect registry. An -\exception{Error} is raised if \var{name} is not a registered dialect -name. -\end{funcdesc} - -\begin{funcdesc}{get_dialect}{name} -Return the dialect associated with \var{name}. An \exception{Error} is -raised if \var{name} is not a registered dialect name. -\end{funcdesc} - -\begin{funcdesc}{list_dialects}{} -Return the names of all registered dialects. -\end{funcdesc} - -\begin{funcdesc}{field_size_limit}{\optional{new_limit}} - Returns the current maximum field size allowed by the parser. If - \var{new_limit} is given, this becomes the new limit. - \versionadded{2.5} -\end{funcdesc} - - -The \module{csv} module defines the following classes: - -\begin{classdesc}{DictReader}{csvfile\optional{, - fieldnames=\constant{None},\optional{, - restkey=\constant{None}\optional{, - restval=\constant{None}\optional{, - dialect=\code{'excel'}\optional{, - *args, **kwds}}}}}} -Create an object which operates like a regular reader but maps the -information read into a dict whose keys are given by the optional -{} \var{fieldnames} -parameter. If the \var{fieldnames} parameter is omitted, the values in -the first row of the \var{csvfile} will be used as the fieldnames. -If the row read has fewer fields than the fieldnames sequence, -the value of \var{restval} will be used as the default value. If the row -read has more fields than the fieldnames sequence, the remaining data is -added as a sequence keyed by the value of \var{restkey}. If the row read -has fewer fields than the fieldnames sequence, the remaining keys take the -value of the optional \var{restval} parameter. Any other optional or -keyword arguments are passed to the underlying \class{reader} instance. -\end{classdesc} - - -\begin{classdesc}{DictWriter}{csvfile, fieldnames\optional{, - restval=""\optional{, - extrasaction=\code{'raise'}\optional{, - dialect=\code{'excel'}\optional{, - *args, **kwds}}}}} -Create an object which operates like a regular writer but maps dictionaries -onto output rows. The \var{fieldnames} parameter identifies the order in -which values in the dictionary passed to the \method{writerow()} method are -written to the \var{csvfile}. The optional \var{restval} parameter -specifies the value to be written if the dictionary is missing a key in -\var{fieldnames}. If the dictionary passed to the \method{writerow()} -method contains a key not found in \var{fieldnames}, the optional -\var{extrasaction} parameter indicates what action to take. If it is set -to \code{'raise'} a \exception{ValueError} is raised. If it is set to -\code{'ignore'}, extra values in the dictionary are ignored. Any other -optional or keyword arguments are passed to the underlying \class{writer} -instance. - -Note that unlike the \class{DictReader} class, the \var{fieldnames} -parameter of the \class{DictWriter} is not optional. Since Python's -\class{dict} objects are not ordered, there is not enough information -available to deduce the order in which the row should be written to the -\var{csvfile}. - -\end{classdesc} - -\begin{classdesc*}{Dialect}{} -The \class{Dialect} class is a container class relied on primarily for its -attributes, which are used to define the parameters for a specific -\class{reader} or \class{writer} instance. -\end{classdesc*} - -\begin{classdesc}{excel}{} -The \class{excel} class defines the usual properties of an Excel-generated -CSV file. It is registered with the dialect name \code{'excel'}. -\end{classdesc} - -\begin{classdesc}{excel_tab}{} -The \class{excel_tab} class defines the usual properties of an -Excel-generated TAB-delimited file. It is registered with the dialect name -\code{'excel-tab'}. -\end{classdesc} - -\begin{classdesc}{Sniffer}{} -The \class{Sniffer} class is used to deduce the format of a CSV file. -\end{classdesc} - -The \class{Sniffer} class provides two methods: - -\begin{methoddesc}{sniff}{sample\optional{,delimiters=None}} -Analyze the given \var{sample} and return a \class{Dialect} subclass -reflecting the parameters found. If the optional \var{delimiters} parameter -is given, it is interpreted as a string containing possible valid delimiter -characters. -\end{methoddesc} - -\begin{methoddesc}{has_header}{sample} -Analyze the sample text (presumed to be in CSV format) and return -\constant{True} if the first row appears to be a series of column -headers. -\end{methoddesc} - - -The \module{csv} module defines the following constants: - -\begin{datadesc}{QUOTE_ALL} -Instructs \class{writer} objects to quote all fields. -\end{datadesc} - -\begin{datadesc}{QUOTE_MINIMAL} -Instructs \class{writer} objects to only quote those fields which contain -special characters such as \var{delimiter}, \var{quotechar} or any of the -characters in \var{lineterminator}. -\end{datadesc} - -\begin{datadesc}{QUOTE_NONNUMERIC} -Instructs \class{writer} objects to quote all non-numeric -fields. - -Instructs the reader to convert all non-quoted fields to type \var{float}. -\end{datadesc} - -\begin{datadesc}{QUOTE_NONE} -Instructs \class{writer} objects to never quote fields. When the current -\var{delimiter} occurs in output data it is preceded by the current -\var{escapechar} character. If \var{escapechar} is not set, the writer -will raise \exception{Error} if any characters that require escaping -are encountered. - -Instructs \class{reader} to perform no special processing of quote characters. -\end{datadesc} - - -The \module{csv} module defines the following exception: - -\begin{excdesc}{Error} -Raised by any of the functions when an error is detected. -\end{excdesc} - - -\subsection{Dialects and Formatting Parameters\label{csv-fmt-params}} - -To make it easier to specify the format of input and output records, -specific formatting parameters are grouped together into dialects. A -dialect is a subclass of the \class{Dialect} class having a set of specific -methods and a single \method{validate()} method. When creating \class{reader} -or \class{writer} objects, the programmer can specify a string or a subclass -of the \class{Dialect} class as the dialect parameter. In addition to, or -instead of, the \var{dialect} parameter, the programmer can also specify -individual formatting parameters, which have the same names as the -attributes defined below for the \class{Dialect} class. - -Dialects support the following attributes: - -\begin{memberdesc}[Dialect]{delimiter} -A one-character string used to separate fields. It defaults to \code{','}. -\end{memberdesc} - -\begin{memberdesc}[Dialect]{doublequote} -Controls how instances of \var{quotechar} appearing inside a field should -be themselves be quoted. When \constant{True}, the character is doubled. -When \constant{False}, the \var{escapechar} is used as a prefix to the -\var{quotechar}. It defaults to \constant{True}. - -On output, if \var{doublequote} is \constant{False} and no -\var{escapechar} is set, \exception{Error} is raised if a \var{quotechar} -is found in a field. -\end{memberdesc} - -\begin{memberdesc}[Dialect]{escapechar} -A one-character string used by the writer to escape the \var{delimiter} if -\var{quoting} is set to \constant{QUOTE_NONE} and the \var{quotechar} -if \var{doublequote} is \constant{False}. On reading, the \var{escapechar} -removes any special meaning from the following character. It defaults -to \constant{None}, which disables escaping. -\end{memberdesc} - -\begin{memberdesc}[Dialect]{lineterminator} -The string used to terminate lines produced by the \class{writer}. -It defaults to \code{'\e r\e n'}. - -\note{The \class{reader} is hard-coded to recognise either \code{'\e r'} -or \code{'\e n'} as end-of-line, and ignores \var{lineterminator}. This -behavior may change in the future.} -\end{memberdesc} - -\begin{memberdesc}[Dialect]{quotechar} -A one-character string used to quote fields containing special characters, -such as the \var{delimiter} or \var{quotechar}, or which contain new-line -characters. It defaults to \code{'"'}. -\end{memberdesc} - -\begin{memberdesc}[Dialect]{quoting} -Controls when quotes should be generated by the writer and recognised -by the reader. It can take on any of the \constant{QUOTE_*} constants -(see section~\ref{csv-contents}) and defaults to \constant{QUOTE_MINIMAL}. -\end{memberdesc} - -\begin{memberdesc}[Dialect]{skipinitialspace} -When \constant{True}, whitespace immediately following the \var{delimiter} -is ignored. The default is \constant{False}. -\end{memberdesc} - - -\subsection{Reader Objects} - -Reader objects (\class{DictReader} instances and objects returned by -the \function{reader()} function) have the following public methods: - -\begin{methoddesc}[csv reader]{next}{} -Return the next row of the reader's iterable object as a list, parsed -according to the current dialect. -\end{methoddesc} - -Reader objects have the following public attributes: - -\begin{memberdesc}[csv reader]{dialect} -A read-only description of the dialect in use by the parser. -\end{memberdesc} - -\begin{memberdesc}[csv reader]{line_num} - The number of lines read from the source iterator. This is not the same - as the number of records returned, as records can span multiple lines. - \versionadded{2.5} -\end{memberdesc} - - -\subsection{Writer Objects} - -\class{Writer} objects (\class{DictWriter} instances and objects returned by -the \function{writer()} function) have the following public methods. A -{}\var{row} must be a sequence of strings or numbers for \class{Writer} -objects and a dictionary mapping fieldnames to strings or numbers (by -passing them through \function{str()} first) for {}\class{DictWriter} -objects. Note that complex numbers are written out surrounded by parens. -This may cause some problems for other programs which read CSV files -(assuming they support complex numbers at all). - -\begin{methoddesc}[csv writer]{writerow}{row} -Write the \var{row} parameter to the writer's file object, formatted -according to the current dialect. -\end{methoddesc} - -\begin{methoddesc}[csv writer]{writerows}{rows} -Write all the \var{rows} parameters (a list of \var{row} objects as -described above) to the writer's file object, formatted -according to the current dialect. -\end{methoddesc} - -Writer objects have the following public attribute: - -\begin{memberdesc}[csv writer]{dialect} -A read-only description of the dialect in use by the writer. -\end{memberdesc} - - - -\subsection{Examples\label{csv-examples}} - -The simplest example of reading a CSV file: - -\begin{verbatim} -import csv -reader = csv.reader(open("some.csv", "rb")) -for row in reader: - print row -\end{verbatim} - -Reading a file with an alternate format: - -\begin{verbatim} -import csv -reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE) -for row in reader: - print row -\end{verbatim} - -The corresponding simplest possible writing example is: - -\begin{verbatim} -import csv -writer = csv.writer(open("some.csv", "wb")) -writer.writerows(someiterable) -\end{verbatim} - -Registering a new dialect: - -\begin{verbatim} -import csv - -csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE) - -reader = csv.reader(open("passwd", "rb"), 'unixpwd') -\end{verbatim} - -A slightly more advanced use of the reader --- catching and reporting errors: - -\begin{verbatim} -import csv, sys -filename = "some.csv" -reader = csv.reader(open(filename, "rb")) -try: - for row in reader: - print row -except csv.Error as e: - sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e)) -\end{verbatim} - -And while the module doesn't directly support parsing strings, it can -easily be done: - -\begin{verbatim} -import csv -for row in csv.reader(['one,two,three']): - print row -\end{verbatim} - -The \module{csv} module doesn't directly support reading and writing -Unicode, but it is 8-bit-clean save for some problems with \ASCII{} NUL -characters. So you can write functions or classes that handle the -encoding and decoding for you as long as you avoid encodings like -UTF-16 that use NULs. UTF-8 is recommended. - -\function{unicode_csv_reader} below is a generator that wraps -\class{csv.reader} to handle Unicode CSV data (a list of Unicode -strings). \function{utf_8_encoder} is a generator that encodes the -Unicode strings as UTF-8, one string (or row) at a time. The encoded -strings are parsed by the CSV reader, and -\function{unicode_csv_reader} decodes the UTF-8-encoded cells back -into Unicode: - -\begin{verbatim} -import csv - -def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs): - # csv.py doesn't do Unicode; encode temporarily as UTF-8: - csv_reader = csv.reader(utf_8_encoder(unicode_csv_data), - dialect=dialect, **kwargs) - for row in csv_reader: - # decode UTF-8 back to Unicode, cell by cell: - yield [unicode(cell, 'utf-8') for cell in row] - -def utf_8_encoder(unicode_csv_data): - for line in unicode_csv_data: - yield line.encode('utf-8') -\end{verbatim} - -For all other encodings the following \class{UnicodeReader} and -\class{UnicodeWriter} classes can be used. They take an additional -\var{encoding} parameter in their constructor and make sure that the data -passes the real reader or writer encoded as UTF-8: - -\begin{verbatim} -import csv, codecs, cStringIO - -class UTF8Recoder: - """ - Iterator that reads an encoded stream and reencodes the input to UTF-8 - """ - def __init__(self, f, encoding): - self.reader = codecs.getreader(encoding)(f) - - def __iter__(self): - return self - - def __next__(self): - return next(self.reader).encode("utf-8") - -class UnicodeReader: - """ - A CSV reader which will iterate over lines in the CSV file "f", - which is encoded in the given encoding. - """ - - def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds): - f = UTF8Recoder(f, encoding) - self.reader = csv.reader(f, dialect=dialect, **kwds) - - def __next__(self): - row = next(self.reader) - return [unicode(s, "utf-8") for s in row] - - def __iter__(self): - return self - -class UnicodeWriter: - """ - A CSV writer which will write rows to CSV file "f", - which is encoded in the given encoding. - """ - - def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds): - # Redirect output to a queue - self.queue = cStringIO.StringIO() - self.writer = csv.writer(self.queue, dialect=dialect, **kwds) - self.stream = f - self.encoder = codecs.getincrementalencoder(encoding)() - - def writerow(self, row): - self.writer.writerow([s.encode("utf-8") for s in row]) - # Fetch UTF-8 output from the queue ... - data = self.queue.getvalue() - data = data.decode("utf-8") - # ... and reencode it into the target encoding - data = self.encoder.encode(data) - # write to the target stream - self.stream.write(data) - # empty queue - self.queue.truncate(0) - - def writerows(self, rows): - for row in rows: - self.writerow(row) -\end{verbatim} diff --git a/Doc/lib/libctypes.tex b/Doc/lib/libctypes.tex deleted file mode 100755 index 346863d..0000000 --- a/Doc/lib/libctypes.tex +++ /dev/null @@ -1,2450 +0,0 @@ -\ifx\locallinewidth\undefined\newlength{\locallinewidth}\fi -\setlength{\locallinewidth}{\linewidth} -\section{\module{ctypes} --- A foreign function library for Python.} -\declaremodule{standard}{ctypes} -\moduleauthor{Thomas Heller}{theller@python.net} -\modulesynopsis{A foreign function library for Python.} -\versionadded{2.5} - -\code{ctypes} is a foreign function library for Python. It provides C -compatible data types, and allows calling functions in dlls/shared -libraries. It can be used to wrap these libraries in pure Python. - - -\subsection{ctypes tutorial\label{ctypes-ctypes-tutorial}} - -Note: The code samples in this tutorial use \code{doctest} to make sure -that they actually work. Since some code samples behave differently -under Linux, Windows, or Mac OS X, they contain doctest directives in -comments. - -Note: Some code sample references the ctypes \class{c{\_}int} type. -This type is an alias to the \class{c{\_}long} type on 32-bit systems. So, -you should not be confused if \class{c{\_}long} is printed if you would -expect \class{c{\_}int} --- they are actually the same type. - - -\subsubsection{Loading dynamic link libraries\label{ctypes-loading-dynamic-link-libraries}} - -\code{ctypes} exports the \var{cdll}, and on Windows also \var{windll} and -\var{oledll} objects to load dynamic link libraries. - -You load libraries by accessing them as attributes of these objects. -\var{cdll} loads libraries which export functions using the standard -\code{cdecl} calling convention, while \var{windll} libraries call -functions using the \code{stdcall} calling convention. \var{oledll} also -uses the \code{stdcall} calling convention, and assumes the functions -return a Windows \class{HRESULT} error code. The error code is used to -automatically raise \class{WindowsError} Python exceptions when the -function call fails. - -Here are some examples for Windows. Note that \code{msvcrt} is the MS -standard C library containing most standard C functions, and uses the -cdecl calling convention: -\begin{verbatim} ->>> from ctypes import * ->>> print windll.kernel32 # doctest: +WINDOWS -<WinDLL 'kernel32', handle ... at ...> ->>> print cdll.msvcrt # doctest: +WINDOWS -<CDLL 'msvcrt', handle ... at ...> ->>> libc = cdll.msvcrt # doctest: +WINDOWS ->>> -\end{verbatim} - -Windows appends the usual '.dll' file suffix automatically. - -On Linux, it is required to specify the filename \emph{including} the -extension to load a library, so attribute access does not work. -Either the \method{LoadLibrary} method of the dll loaders should be used, -or you should load the library by creating an instance of CDLL by -calling the constructor: -\begin{verbatim} ->>> cdll.LoadLibrary("libc.so.6") # doctest: +LINUX -<CDLL 'libc.so.6', handle ... at ...> ->>> libc = CDLL("libc.so.6") # doctest: +LINUX ->>> libc # doctest: +LINUX -<CDLL 'libc.so.6', handle ... at ...> ->>> -\end{verbatim} -% XXX Add section for Mac OS X. - - -\subsubsection{Accessing functions from loaded dlls\label{ctypes-accessing-functions-from-loaded-dlls}} - -Functions are accessed as attributes of dll objects: -\begin{verbatim} ->>> from ctypes import * ->>> libc.printf -<_FuncPtr object at 0x...> ->>> print windll.kernel32.GetModuleHandleA # doctest: +WINDOWS -<_FuncPtr object at 0x...> ->>> print windll.kernel32.MyOwnFunction # doctest: +WINDOWS -Traceback (most recent call last): - File "<stdin>", line 1, in ? - File "ctypes.py", line 239, in __getattr__ - func = _StdcallFuncPtr(name, self) -AttributeError: function 'MyOwnFunction' not found ->>> -\end{verbatim} - -Note that win32 system dlls like \code{kernel32} and \code{user32} often -export ANSI as well as UNICODE versions of a function. The UNICODE -version is exported with an \code{W} appended to the name, while the ANSI -version is exported with an \code{A} appended to the name. The win32 -\code{GetModuleHandle} function, which returns a \emph{module handle} for a -given module name, has the following C prototype, and a macro is used -to expose one of them as \code{GetModuleHandle} depending on whether -UNICODE is defined or not: -\begin{verbatim} -/* ANSI version */ -HMODULE GetModuleHandleA(LPCSTR lpModuleName); -/* UNICODE version */ -HMODULE GetModuleHandleW(LPCWSTR lpModuleName); -\end{verbatim} - -\var{windll} does not try to select one of them by magic, you must -access the version you need by specifying \code{GetModuleHandleA} or -\code{GetModuleHandleW} explicitely, and then call it with normal strings -or unicode strings respectively. - -Sometimes, dlls export functions with names which aren't valid Python -identifiers, like \code{"??2@YAPAXI@Z"}. In this case you have to use -\code{getattr} to retrieve the function: -\begin{verbatim} ->>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS -<_FuncPtr object at 0x...> ->>> -\end{verbatim} - -On Windows, some dlls export functions not by name but by ordinal. -These functions can be accessed by indexing the dll object with the -ordinal number: -\begin{verbatim} ->>> cdll.kernel32[1] # doctest: +WINDOWS -<_FuncPtr object at 0x...> ->>> cdll.kernel32[0] # doctest: +WINDOWS -Traceback (most recent call last): - File "<stdin>", line 1, in ? - File "ctypes.py", line 310, in __getitem__ - func = _StdcallFuncPtr(name, self) -AttributeError: function ordinal 0 not found ->>> -\end{verbatim} - - -\subsubsection{Calling functions\label{ctypes-calling-functions}} - -You can call these functions like any other Python callable. This -example uses the \code{time()} function, which returns system time in -seconds since the \UNIX{} epoch, and the \code{GetModuleHandleA()} function, -which returns a win32 module handle. - -This example calls both functions with a NULL pointer (\code{None} should -be used as the NULL pointer): -\begin{verbatim} ->>> print libc.time(None) # doctest: +SKIP -1150640792 ->>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS -0x1d000000 ->>> -\end{verbatim} - -\code{ctypes} tries to protect you from calling functions with the wrong -number of arguments or the wrong calling convention. Unfortunately -this only works on Windows. It does this by examining the stack after -the function returns, so although an error is raised the function -\emph{has} been called: -\begin{verbatim} ->>> windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ValueError: Procedure probably called with not enough arguments (4 bytes missing) ->>> windll.kernel32.GetModuleHandleA(0, 0) # doctest: +WINDOWS -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ValueError: Procedure probably called with too many arguments (4 bytes in excess) ->>> -\end{verbatim} - -The same exception is raised when you call an \code{stdcall} function -with the \code{cdecl} calling convention, or vice versa: -\begin{verbatim} ->>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ValueError: Procedure probably called with not enough arguments (4 bytes missing) ->>> - ->>> windll.msvcrt.printf("spam") # doctest: +WINDOWS -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ValueError: Procedure probably called with too many arguments (4 bytes in excess) ->>> -\end{verbatim} - -To find out the correct calling convention you have to look into the C -header file or the documentation for the function you want to call. - -On Windows, \code{ctypes} uses win32 structured exception handling to -prevent crashes from general protection faults when functions are -called with invalid argument values: -\begin{verbatim} ->>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS -Traceback (most recent call last): - File "<stdin>", line 1, in ? -WindowsError: exception: access violation reading 0x00000020 ->>> -\end{verbatim} - -There are, however, enough ways to crash Python with \code{ctypes}, so -you should be careful anyway. - -\code{None}, integers, longs, byte strings and unicode strings are the -only native Python objects that can directly be used as parameters in -these function calls. \code{None} is passed as a C \code{NULL} pointer, -byte strings and unicode strings are passed as pointer to the memory -block that contains their data (\code{char *} or \code{wchar{\_}t *}). Python -integers and Python longs are passed as the platforms default C -\code{int} type, their value is masked to fit into the C type. - -Before we move on calling functions with other parameter types, we -have to learn more about \code{ctypes} data types. - - -\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}} - -\code{ctypes} defines a number of primitive C compatible data types : -\begin{quote} -\begin{tableiii}{l|l|l}{textrm} -{ -ctypes type -} -{ -C type -} -{ -Python type -} -\lineiii{ -\class{c{\_}char} -} -{ -\code{char} -} -{ -1-character -string -} -\lineiii{ -\class{c{\_}wchar} -} -{ -\code{wchar{\_}t} -} -{ -1-character -unicode string -} -\lineiii{ -\class{c{\_}byte} -} -{ -\code{char} -} -{ -int/long -} -\lineiii{ -\class{c{\_}ubyte} -} -{ -\code{unsigned char} -} -{ -int/long -} -\lineiii{ -\class{c{\_}short} -} -{ -\code{short} -} -{ -int/long -} -\lineiii{ -\class{c{\_}ushort} -} -{ -\code{unsigned short} -} -{ -int/long -} -\lineiii{ -\class{c{\_}int} -} -{ -\code{int} -} -{ -int/long -} -\lineiii{ -\class{c{\_}uint} -} -{ -\code{unsigned int} -} -{ -int/long -} -\lineiii{ -\class{c{\_}long} -} -{ -\code{long} -} -{ -int/long -} -\lineiii{ -\class{c{\_}ulong} -} -{ -\code{unsigned long} -} -{ -int/long -} -\lineiii{ -\class{c{\_}longlong} -} -{ -\code{{\_}{\_}int64} or -\code{long long} -} -{ -int/long -} -\lineiii{ -\class{c{\_}ulonglong} -} -{ -\code{unsigned {\_}{\_}int64} or -\code{unsigned long long} -} -{ -int/long -} -\lineiii{ -\class{c{\_}float} -} -{ -\code{float} -} -{ -float -} -\lineiii{ -\class{c{\_}double} -} -{ -\code{double} -} -{ -float -} -\lineiii{ -\class{c{\_}char{\_}p} -} -{ -\code{char *} -(NUL terminated) -} -{ -string or -\code{None} -} -\lineiii{ -\class{c{\_}wchar{\_}p} -} -{ -\code{wchar{\_}t *} -(NUL terminated) -} -{ -unicode or -\code{None} -} -\lineiii{ -\class{c{\_}void{\_}p} -} -{ -\code{void *} -} -{ -int/long -or \code{None} -} -\end{tableiii} -\end{quote} - -All these types can be created by calling them with an optional -initializer of the correct type and value: -\begin{verbatim} ->>> c_int() -c_long(0) ->>> c_char_p("Hello, World") -c_char_p('Hello, World') ->>> c_ushort(-3) -c_ushort(65533) ->>> -\end{verbatim} - -Since these types are mutable, their value can also be changed -afterwards: -\begin{verbatim} ->>> i = c_int(42) ->>> print i -c_long(42) ->>> print i.value -42 ->>> i.value = -99 ->>> print i.value --99 ->>> -\end{verbatim} - -Assigning a new value to instances of the pointer types \class{c{\_}char{\_}p}, -\class{c{\_}wchar{\_}p}, and \class{c{\_}void{\_}p} changes the \emph{memory location} they -point to, \emph{not the contents} of the memory block (of course not, -because Python strings are immutable): -\begin{verbatim} ->>> s = "Hello, World" ->>> c_s = c_char_p(s) ->>> print c_s -c_char_p('Hello, World') ->>> c_s.value = "Hi, there" ->>> print c_s -c_char_p('Hi, there') ->>> print s # first string is unchanged -Hello, World ->>> -\end{verbatim} - -You should be careful, however, not to pass them to functions -expecting pointers to mutable memory. If you need mutable memory -blocks, ctypes has a \code{create{\_}string{\_}buffer} function which creates -these in various ways. The current memory block contents can be -accessed (or changed) with the \code{raw} property; if you want to access -it as NUL terminated string, use the \code{value} property: -\begin{verbatim} ->>> from ctypes import * ->>> p = create_string_buffer(3) # create a 3 byte buffer, initialized to NUL bytes ->>> print sizeof(p), repr(p.raw) -3 '\x00\x00\x00' ->>> p = create_string_buffer("Hello") # create a buffer containing a NUL terminated string ->>> print sizeof(p), repr(p.raw) -6 'Hello\x00' ->>> print repr(p.value) -'Hello' ->>> p = create_string_buffer("Hello", 10) # create a 10 byte buffer ->>> print sizeof(p), repr(p.raw) -10 'Hello\x00\x00\x00\x00\x00' ->>> p.value = "Hi" ->>> print sizeof(p), repr(p.raw) -10 'Hi\x00lo\x00\x00\x00\x00\x00' ->>> -\end{verbatim} - -The \code{create{\_}string{\_}buffer} function replaces the \code{c{\_}buffer} -function (which is still available as an alias), as well as the -\code{c{\_}string} function from earlier ctypes releases. To create a -mutable memory block containing unicode characters of the C type -\code{wchar{\_}t} use the \code{create{\_}unicode{\_}buffer} function. - - -\subsubsection{Calling functions, continued\label{ctypes-calling-functions-continued}} - -Note that printf prints to the real standard output channel, \emph{not} to -\code{sys.stdout}, so these examples will only work at the console -prompt, not from within \emph{IDLE} or \emph{PythonWin}: -\begin{verbatim} ->>> printf = libc.printf ->>> printf("Hello, %s\n", "World!") -Hello, World! -14 ->>> printf("Hello, %S", u"World!") -Hello, World! -13 ->>> printf("%d bottles of beer\n", 42) -42 bottles of beer -19 ->>> printf("%f bottles of beer\n", 42.5) -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2 ->>> -\end{verbatim} - -As has been mentioned before, all Python types except integers, -strings, and unicode strings have to be wrapped in their corresponding -\code{ctypes} type, so that they can be converted to the required C data -type: -\begin{verbatim} ->>> printf("An int %d, a double %f\n", 1234, c_double(3.14)) -Integer 1234, double 3.1400001049 -31 ->>> -\end{verbatim} - - -\subsubsection{Calling functions with your own custom data types\label{ctypes-calling-functions-with-own-custom-data-types}} - -You can also customize \code{ctypes} argument conversion to allow -instances of your own classes be used as function arguments. -\code{ctypes} looks for an \member{{\_}as{\_}parameter{\_}} attribute and uses this as -the function argument. Of course, it must be one of integer, string, -or unicode: -\begin{verbatim} ->>> class Bottles(object): -... def __init__(self, number): -... self._as_parameter_ = number -... ->>> bottles = Bottles(42) ->>> printf("%d bottles of beer\n", bottles) -42 bottles of beer -19 ->>> -\end{verbatim} - -If you don't want to store the instance's data in the -\member{{\_}as{\_}parameter{\_}} instance variable, you could define a \code{property} -which makes the data avaiblable. - - -\subsubsection{Specifying the required argument types (function prototypes)\label{ctypes-specifying-required-argument-types}} - -It is possible to specify the required argument types of functions -exported from DLLs by setting the \member{argtypes} attribute. - -\member{argtypes} must be a sequence of C data types (the \code{printf} -function is probably not a good example here, because it takes a -variable number and different types of parameters depending on the -format string, on the other hand this is quite handy to experiment -with this feature): -\begin{verbatim} ->>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double] ->>> printf("String '%s', Int %d, Double %f\n", "Hi", 10, 2.2) -String 'Hi', Int 10, Double 2.200000 -37 ->>> -\end{verbatim} - -Specifying a format protects against incompatible argument types (just -as a prototype for a C function), and tries to convert the arguments -to valid types: -\begin{verbatim} ->>> printf("%d %d %d", 1, 2, 3) -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ArgumentError: argument 2: exceptions.TypeError: wrong type ->>> printf("%s %d %f", "X", 2, 3) -X 2 3.00000012 -12 ->>> -\end{verbatim} - -If you have defined your own classes which you pass to function calls, -you have to implement a \method{from{\_}param} class method for them to be -able to use them in the \member{argtypes} sequence. The \method{from{\_}param} -class method receives the Python object passed to the function call, -it should do a typecheck or whatever is needed to make sure this -object is acceptable, and then return the object itself, it's -\member{{\_}as{\_}parameter{\_}} attribute, or whatever you want to pass as the C -function argument in this case. Again, the result should be an -integer, string, unicode, a \code{ctypes} instance, or something having -the \member{{\_}as{\_}parameter{\_}} attribute. - - -\subsubsection{Return types\label{ctypes-return-types}} - -By default functions are assumed to return the C \code{int} type. Other -return types can be specified by setting the \member{restype} attribute of -the function object. - -Here is a more advanced example, it uses the \code{strchr} function, which -expects a string pointer and a char, and returns a pointer to a -string: -\begin{verbatim} ->>> strchr = libc.strchr ->>> strchr("abcdef", ord("d")) # doctest: +SKIP -8059983 ->>> strchr.restype = c_char_p # c_char_p is a pointer to a string ->>> strchr("abcdef", ord("d")) -'def' ->>> print strchr("abcdef", ord("x")) -None ->>> -\end{verbatim} - -If you want to avoid the \code{ord("x")} calls above, you can set the -\member{argtypes} attribute, and the second argument will be converted from -a single character Python string into a C char: -\begin{verbatim} ->>> strchr.restype = c_char_p ->>> strchr.argtypes = [c_char_p, c_char] ->>> strchr("abcdef", "d") -'def' ->>> strchr("abcdef", "def") -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ArgumentError: argument 2: exceptions.TypeError: one character string expected ->>> print strchr("abcdef", "x") -None ->>> strchr("abcdef", "d") -'def' ->>> -\end{verbatim} - -You can also use a callable Python object (a function or a class for -example) as the \member{restype} attribute, if the foreign function returns -an integer. The callable will be called with the \code{integer} the C -function returns, and the result of this call will be used as the -result of your function call. This is useful to check for error return -values and automatically raise an exception: -\begin{verbatim} ->>> GetModuleHandle = windll.kernel32.GetModuleHandleA # doctest: +WINDOWS ->>> def ValidHandle(value): -... if value == 0: -... raise WinError() -... return value -... ->>> ->>> GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS ->>> GetModuleHandle(None) # doctest: +WINDOWS -486539264 ->>> GetModuleHandle("something silly") # doctest: +WINDOWS -Traceback (most recent call last): - File "<stdin>", line 1, in ? - File "<stdin>", line 3, in ValidHandle -WindowsError: [Errno 126] The specified module could not be found. ->>> -\end{verbatim} - -\code{WinError} is a function which will call Windows \code{FormatMessage()} -api to get the string representation of an error code, and \emph{returns} -an exception. \code{WinError} takes an optional error code parameter, if -no one is used, it calls \function{GetLastError()} to retrieve it. - -Please note that a much more powerful error checking mechanism is -available through the \member{errcheck} attribute; see the reference manual -for details. - - -\subsubsection{Passing pointers (or: passing parameters by reference)\label{ctypes-passing-pointers}} - -Sometimes a C api function expects a \emph{pointer} to a data type as -parameter, probably to write into the corresponding location, or if -the data is too large to be passed by value. This is also known as -\emph{passing parameters by reference}. - -\code{ctypes} exports the \function{byref} function which is used to pass -parameters by reference. The same effect can be achieved with the -\code{pointer} function, although \code{pointer} does a lot more work since -it constructs a real pointer object, so it is faster to use \function{byref} -if you don't need the pointer object in Python itself: -\begin{verbatim} ->>> i = c_int() ->>> f = c_float() ->>> s = create_string_buffer('\000' * 32) ->>> print i.value, f.value, repr(s.value) -0 0.0 '' ->>> libc.sscanf("1 3.14 Hello", "%d %f %s", -... byref(i), byref(f), s) -3 ->>> print i.value, f.value, repr(s.value) -1 3.1400001049 'Hello' ->>> -\end{verbatim} - - -\subsubsection{Structures and unions\label{ctypes-structures-unions}} - -Structures and unions must derive from the \class{Structure} and \class{Union} -base classes which are defined in the \code{ctypes} module. Each subclass -must define a \member{{\_}fields{\_}} attribute. \member{{\_}fields{\_}} must be a list of -\emph{2-tuples}, containing a \emph{field name} and a \emph{field type}. - -The field type must be a \code{ctypes} type like \class{c{\_}int}, or any other -derived \code{ctypes} type: structure, union, array, pointer. - -Here is a simple example of a POINT structure, which contains two -integers named \code{x} and \code{y}, and also shows how to initialize a -structure in the constructor: -\begin{verbatim} ->>> from ctypes import * ->>> class POINT(Structure): -... _fields_ = [("x", c_int), -... ("y", c_int)] -... ->>> point = POINT(10, 20) ->>> print point.x, point.y -10 20 ->>> point = POINT(y=5) ->>> print point.x, point.y -0 5 ->>> POINT(1, 2, 3) -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ValueError: too many initializers ->>> -\end{verbatim} - -You can, however, build much more complicated structures. Structures -can itself contain other structures by using a structure as a field -type. - -Here is a RECT structure which contains two POINTs named \code{upperleft} -and \code{lowerright} -\begin{verbatim} ->>> class RECT(Structure): -... _fields_ = [("upperleft", POINT), -... ("lowerright", POINT)] -... ->>> rc = RECT(point) ->>> print rc.upperleft.x, rc.upperleft.y -0 5 ->>> print rc.lowerright.x, rc.lowerright.y -0 0 ->>> -\end{verbatim} - -Nested structures can also be initialized in the constructor in -several ways: -\begin{verbatim} ->>> r = RECT(POINT(1, 2), POINT(3, 4)) ->>> r = RECT((1, 2), (3, 4)) -\end{verbatim} - -Fields descriptors can be retrieved from the \emph{class}, they are useful -for debugging because they can provide useful information: -\begin{verbatim} ->>> print POINT.x -<Field type=c_long, ofs=0, size=4> ->>> print POINT.y -<Field type=c_long, ofs=4, size=4> ->>> -\end{verbatim} - - -\subsubsection{Structure/union alignment and byte order\label{ctypes-structureunion-alignment-byte-order}} - -By default, Structure and Union fields are aligned in the same way the -C compiler does it. It is possible to override this behaviour be -specifying a \member{{\_}pack{\_}} class attribute in the subclass -definition. This must be set to a positive integer and specifies the -maximum alignment for the fields. This is what \code{{\#}pragma pack(n)} -also does in MSVC. - -\code{ctypes} uses the native byte order for Structures and Unions. To -build structures with non-native byte order, you can use one of the -BigEndianStructure, LittleEndianStructure, BigEndianUnion, and -LittleEndianUnion base classes. These classes cannot contain pointer -fields. - - -\subsubsection{Bit fields in structures and unions\label{ctypes-bit-fields-in-structures-unions}} - -It is possible to create structures and unions containing bit fields. -Bit fields are only possible for integer fields, the bit width is -specified as the third item in the \member{{\_}fields{\_}} tuples: -\begin{verbatim} ->>> class Int(Structure): -... _fields_ = [("first_16", c_int, 16), -... ("second_16", c_int, 16)] -... ->>> print Int.first_16 -<Field type=c_long, ofs=0:0, bits=16> ->>> print Int.second_16 -<Field type=c_long, ofs=0:16, bits=16> ->>> -\end{verbatim} - - -\subsubsection{Arrays\label{ctypes-arrays}} - -Arrays are sequences, containing a fixed number of instances of the -same type. - -The recommended way to create array types is by multiplying a data -type with a positive integer: -\begin{verbatim} -TenPointsArrayType = POINT * 10 -\end{verbatim} - -Here is an example of an somewhat artifical data type, a structure -containing 4 POINTs among other stuff: -\begin{verbatim} ->>> from ctypes import * ->>> class POINT(Structure): -... _fields_ = ("x", c_int), ("y", c_int) -... ->>> class MyStruct(Structure): -... _fields_ = [("a", c_int), -... ("b", c_float), -... ("point_array", POINT * 4)] ->>> ->>> print len(MyStruct().point_array) -4 ->>> -\end{verbatim} - -Instances are created in the usual way, by calling the class: -\begin{verbatim} -arr = TenPointsArrayType() -for pt in arr: - print pt.x, pt.y -\end{verbatim} - -The above code print a series of \code{0 0} lines, because the array -contents is initialized to zeros. - -Initializers of the correct type can also be specified: -\begin{verbatim} ->>> from ctypes import * ->>> TenIntegers = c_int * 10 ->>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) ->>> print ii -<c_long_Array_10 object at 0x...> ->>> for i in ii: print i, -... -1 2 3 4 5 6 7 8 9 10 ->>> -\end{verbatim} - - -\subsubsection{Pointers\label{ctypes-pointers}} - -Pointer instances are created by calling the \code{pointer} function on a -\code{ctypes} type: -\begin{verbatim} ->>> from ctypes import * ->>> i = c_int(42) ->>> pi = pointer(i) ->>> -\end{verbatim} - -Pointer instances have a \code{contents} attribute which returns the -object to which the pointer points, the \code{i} object above: -\begin{verbatim} ->>> pi.contents -c_long(42) ->>> -\end{verbatim} - -Note that \code{ctypes} does not have OOR (original object return), it -constructs a new, equivalent object each time you retrieve an -attribute: -\begin{verbatim} ->>> pi.contents is i -False ->>> pi.contents is pi.contents -False ->>> -\end{verbatim} - -Assigning another \class{c{\_}int} instance to the pointer's contents -attribute would cause the pointer to point to the memory location -where this is stored: -\begin{verbatim} ->>> i = c_int(99) ->>> pi.contents = i ->>> pi.contents -c_long(99) ->>> -\end{verbatim} - -Pointer instances can also be indexed with integers: -\begin{verbatim} ->>> pi[0] -99 ->>> -\end{verbatim} - -Assigning to an integer index changes the pointed to value: -\begin{verbatim} ->>> print i -c_long(99) ->>> pi[0] = 22 ->>> print i -c_long(22) ->>> -\end{verbatim} - -It is also possible to use indexes different from 0, but you must know -what you're doing, just as in C: You can access or change arbitrary -memory locations. Generally you only use this feature if you receive a -pointer from a C function, and you \emph{know} that the pointer actually -points to an array instead of a single item. - -Behind the scenes, the \code{pointer} function does more than simply -create pointer instances, it has to create pointer \emph{types} first. -This is done with the \code{POINTER} function, which accepts any -\code{ctypes} type, and returns a new type: -\begin{verbatim} ->>> PI = POINTER(c_int) ->>> PI -<class 'ctypes.LP_c_long'> ->>> PI(42) -Traceback (most recent call last): - File "<stdin>", line 1, in ? -TypeError: expected c_long instead of int ->>> PI(c_int(42)) -<ctypes.LP_c_long object at 0x...> ->>> -\end{verbatim} - -Calling the pointer type without an argument creates a \code{NULL} -pointer. \code{NULL} pointers have a \code{False} boolean value: -\begin{verbatim} ->>> null_ptr = POINTER(c_int)() ->>> print bool(null_ptr) -False ->>> -\end{verbatim} - -\code{ctypes} checks for \code{NULL} when dereferencing pointers (but -dereferencing non-\code{NULL} pointers would crash Python): -\begin{verbatim} ->>> null_ptr[0] -Traceback (most recent call last): - .... -ValueError: NULL pointer access ->>> - ->>> null_ptr[0] = 1234 -Traceback (most recent call last): - .... -ValueError: NULL pointer access ->>> -\end{verbatim} - - -\subsubsection{Type conversions\label{ctypes-type-conversions}} - -Usually, ctypes does strict type checking. This means, if you have -\code{POINTER(c{\_}int)} in the \member{argtypes} list of a function or as the -type of a member field in a structure definition, only instances of -exactly the same type are accepted. There are some exceptions to this -rule, where ctypes accepts other objects. For example, you can pass -compatible array instances instead of pointer types. So, for -\code{POINTER(c{\_}int)}, ctypes accepts an array of c{\_}int: -\begin{verbatim} ->>> class Bar(Structure): -... _fields_ = [("count", c_int), ("values", POINTER(c_int))] -... ->>> bar = Bar() ->>> bar.values = (c_int * 3)(1, 2, 3) ->>> bar.count = 3 ->>> for i in range(bar.count): -... print bar.values[i] -... -1 -2 -3 ->>> -\end{verbatim} - -To set a POINTER type field to \code{NULL}, you can assign \code{None}: -\begin{verbatim} ->>> bar.values = None ->>> -\end{verbatim} - -XXX list other conversions... - -Sometimes you have instances of incompatible types. In \code{C}, you can -cast one type into another type. \code{ctypes} provides a \code{cast} -function which can be used in the same way. The \code{Bar} structure -defined above accepts \code{POINTER(c{\_}int)} pointers or \class{c{\_}int} arrays -for its \code{values} field, but not instances of other types: -\begin{verbatim} ->>> bar.values = (c_byte * 4)() -Traceback (most recent call last): - File "<stdin>", line 1, in ? -TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance ->>> -\end{verbatim} - -For these cases, the \code{cast} function is handy. - -The \code{cast} function can be used to cast a ctypes instance into a -pointer to a different ctypes data type. \code{cast} takes two -parameters, a ctypes object that is or can be converted to a pointer -of some kind, and a ctypes pointer type. It returns an instance of -the second argument, which references the same memory block as the -first argument: -\begin{verbatim} ->>> a = (c_byte * 4)() ->>> cast(a, POINTER(c_int)) -<ctypes.LP_c_long object at ...> ->>> -\end{verbatim} - -So, \code{cast} can be used to assign to the \code{values} field of \code{Bar} -the structure: -\begin{verbatim} ->>> bar = Bar() ->>> bar.values = cast((c_byte * 4)(), POINTER(c_int)) ->>> print bar.values[0] -0 ->>> -\end{verbatim} - - -\subsubsection{Incomplete Types\label{ctypes-incomplete-types}} - -\emph{Incomplete Types} are structures, unions or arrays whose members are -not yet specified. In C, they are specified by forward declarations, which -are defined later: -\begin{verbatim} -struct cell; /* forward declaration */ - -struct { - char *name; - struct cell *next; -} cell; -\end{verbatim} - -The straightforward translation into ctypes code would be this, but it -does not work: -\begin{verbatim} ->>> class cell(Structure): -... _fields_ = [("name", c_char_p), -... ("next", POINTER(cell))] -... -Traceback (most recent call last): - File "<stdin>", line 1, in ? - File "<stdin>", line 2, in cell -NameError: name 'cell' is not defined ->>> -\end{verbatim} - -because the new \code{class cell} is not available in the class statement -itself. In \code{ctypes}, we can define the \code{cell} class and set the -\member{{\_}fields{\_}} attribute later, after the class statement: -\begin{verbatim} ->>> from ctypes import * ->>> class cell(Structure): -... pass -... ->>> cell._fields_ = [("name", c_char_p), -... ("next", POINTER(cell))] ->>> -\end{verbatim} - -Lets try it. We create two instances of \code{cell}, and let them point -to each other, and finally follow the pointer chain a few times: -\begin{verbatim} ->>> c1 = cell() ->>> c1.name = "foo" ->>> c2 = cell() ->>> c2.name = "bar" ->>> c1.next = pointer(c2) ->>> c2.next = pointer(c1) ->>> p = c1 ->>> for i in range(8): -... print p.name, -... p = p.next[0] -... -foo bar foo bar foo bar foo bar ->>> -\end{verbatim} - - -\subsubsection{Callback functions\label{ctypes-callback-functions}} - -\code{ctypes} allows to create C callable function pointers from Python -callables. These are sometimes called \emph{callback functions}. - -First, you must create a class for the callback function, the class -knows the calling convention, the return type, and the number and -types of arguments this function will receive. - -The CFUNCTYPE factory function creates types for callback functions -using the normal cdecl calling convention, and, on Windows, the -WINFUNCTYPE factory function creates types for callback functions -using the stdcall calling convention. - -Both of these factory functions are called with the result type as -first argument, and the callback functions expected argument types as -the remaining arguments. - -I will present an example here which uses the standard C library's -\function{qsort} function, this is used to sort items with the help of a -callback function. \function{qsort} will be used to sort an array of -integers: -\begin{verbatim} ->>> IntArray5 = c_int * 5 ->>> ia = IntArray5(5, 1, 7, 33, 99) ->>> qsort = libc.qsort ->>> qsort.restype = None ->>> -\end{verbatim} - -\function{qsort} must be called with a pointer to the data to sort, the -number of items in the data array, the size of one item, and a pointer -to the comparison function, the callback. The callback will then be -called with two pointers to items, and it must return a negative -integer if the first item is smaller than the second, a zero if they -are equal, and a positive integer else. - -So our callback function receives pointers to integers, and must -return an integer. First we create the \code{type} for the callback -function: -\begin{verbatim} ->>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int)) ->>> -\end{verbatim} - -For the first implementation of the callback function, we simply print -the arguments we get, and return 0 (incremental development ;-): -\begin{verbatim} ->>> def py_cmp_func(a, b): -... print "py_cmp_func", a, b -... return 0 -... ->>> -\end{verbatim} - -Create the C callable callback: -\begin{verbatim} ->>> cmp_func = CMPFUNC(py_cmp_func) ->>> -\end{verbatim} - -And we're ready to go: -\begin{verbatim} ->>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> -py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...> ->>> -\end{verbatim} - -We know how to access the contents of a pointer, so lets redefine our callback: -\begin{verbatim} ->>> def py_cmp_func(a, b): -... print "py_cmp_func", a[0], b[0] -... return 0 -... ->>> cmp_func = CMPFUNC(py_cmp_func) ->>> -\end{verbatim} - -Here is what we get on Windows: -\begin{verbatim} ->>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS -py_cmp_func 7 1 -py_cmp_func 33 1 -py_cmp_func 99 1 -py_cmp_func 5 1 -py_cmp_func 7 5 -py_cmp_func 33 5 -py_cmp_func 99 5 -py_cmp_func 7 99 -py_cmp_func 33 99 -py_cmp_func 7 33 ->>> -\end{verbatim} - -It is funny to see that on linux the sort function seems to work much -more efficient, it is doing less comparisons: -\begin{verbatim} ->>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +LINUX -py_cmp_func 5 1 -py_cmp_func 33 99 -py_cmp_func 7 33 -py_cmp_func 5 7 -py_cmp_func 1 7 ->>> -\end{verbatim} - -Ah, we're nearly done! The last step is to actually compare the two -items and return a useful result: -\begin{verbatim} ->>> def py_cmp_func(a, b): -... print "py_cmp_func", a[0], b[0] -... return a[0] - b[0] -... ->>> -\end{verbatim} - -Final run on Windows: -\begin{verbatim} ->>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +WINDOWS -py_cmp_func 33 7 -py_cmp_func 99 33 -py_cmp_func 5 99 -py_cmp_func 1 99 -py_cmp_func 33 7 -py_cmp_func 1 33 -py_cmp_func 5 33 -py_cmp_func 5 7 -py_cmp_func 1 7 -py_cmp_func 5 1 ->>> -\end{verbatim} - -and on Linux: -\begin{verbatim} ->>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +LINUX -py_cmp_func 5 1 -py_cmp_func 33 99 -py_cmp_func 7 33 -py_cmp_func 1 7 -py_cmp_func 5 7 ->>> -\end{verbatim} - -It is quite interesting to see that the Windows \function{qsort} function -needs more comparisons than the linux version! - -As we can easily check, our array is sorted now: -\begin{verbatim} ->>> for i in ia: print i, -... -1 5 7 33 99 ->>> -\end{verbatim} - -\textbf{Important note for callback functions:} - -Make sure you keep references to CFUNCTYPE objects as long as they are -used from C code. \code{ctypes} doesn't, and if you don't, they may be -garbage collected, crashing your program when a callback is made. - - -\subsubsection{Accessing values exported from dlls\label{ctypes-accessing-values-exported-from-dlls}} - -Sometimes, a dll not only exports functions, it also exports -variables. An example in the Python library itself is the -\code{Py{\_}OptimizeFlag}, an integer set to 0, 1, or 2, depending on the -\programopt{-O} or \programopt{-OO} flag given on startup. - -\code{ctypes} can access values like this with the \method{in{\_}dll} class -methods of the type. \var{pythonapi} is a predefined symbol giving -access to the Python C api: -\begin{verbatim} ->>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag") ->>> print opt_flag -c_long(0) ->>> -\end{verbatim} - -If the interpreter would have been started with \programopt{-O}, the sample -would have printed \code{c{\_}long(1)}, or \code{c{\_}long(2)} if \programopt{-OO} would have -been specified. - -An extended example which also demonstrates the use of pointers -accesses the \code{PyImport{\_}FrozenModules} pointer exported by Python. - -Quoting the Python docs: \emph{This pointer is initialized to point to an -array of ``struct {\_}frozen`` records, terminated by one whose members -are all NULL or zero. When a frozen module is imported, it is searched -in this table. Third-party code could play tricks with this to provide -a dynamically created collection of frozen modules.} - -So manipulating this pointer could even prove useful. To restrict the -example size, we show only how this table can be read with -\code{ctypes}: -\begin{verbatim} ->>> from ctypes import * ->>> ->>> class struct_frozen(Structure): -... _fields_ = [("name", c_char_p), -... ("code", POINTER(c_ubyte)), -... ("size", c_int)] -... ->>> -\end{verbatim} - -We have defined the \code{struct {\_}frozen} data type, so we can get the -pointer to the table: -\begin{verbatim} ->>> FrozenTable = POINTER(struct_frozen) ->>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules") ->>> -\end{verbatim} - -Since \code{table} is a \code{pointer} to the array of \code{struct{\_}frozen} -records, we can iterate over it, but we just have to make sure that -our loop terminates, because pointers have no size. Sooner or later it -would probably crash with an access violation or whatever, so it's -better to break out of the loop when we hit the NULL entry: -\begin{verbatim} ->>> for item in table: -... print item.name, item.size -... if item.name is None: -... break -... -__hello__ 104 -__phello__ -104 -__phello__.spam 104 -None 0 ->>> -\end{verbatim} - -The fact that standard Python has a frozen module and a frozen package -(indicated by the negative size member) is not wellknown, it is only -used for testing. Try it out with \code{import {\_}{\_}hello{\_}{\_}} for example. - - -\subsubsection{Surprises\label{ctypes-surprises}} - -There are some edges in \code{ctypes} where you may be expect something -else than what actually happens. - -Consider the following example: -\begin{verbatim} ->>> from ctypes import * ->>> class POINT(Structure): -... _fields_ = ("x", c_int), ("y", c_int) -... ->>> class RECT(Structure): -... _fields_ = ("a", POINT), ("b", POINT) -... ->>> p1 = POINT(1, 2) ->>> p2 = POINT(3, 4) ->>> rc = RECT(p1, p2) ->>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y -1 2 3 4 ->>> # now swap the two points ->>> rc.a, rc.b = rc.b, rc.a ->>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y -3 4 3 4 ->>> -\end{verbatim} - -Hm. We certainly expected the last statement to print \code{3 4 1 2}. -What happended? Here are the steps of the \code{rc.a, rc.b = rc.b, rc.a} -line above: -\begin{verbatim} ->>> temp0, temp1 = rc.b, rc.a ->>> rc.a = temp0 ->>> rc.b = temp1 ->>> -\end{verbatim} - -Note that \code{temp0} and \code{temp1} are objects still using the internal -buffer of the \code{rc} object above. So executing \code{rc.a = temp0} -copies the buffer contents of \code{temp0} into \code{rc} 's buffer. This, -in turn, changes the contents of \code{temp1}. So, the last assignment -\code{rc.b = temp1}, doesn't have the expected effect. - -Keep in mind that retrieving subobjects from Structure, Unions, and -Arrays doesn't \emph{copy} the subobject, instead it retrieves a wrapper -object accessing the root-object's underlying buffer. - -Another example that may behave different from what one would expect is this: -\begin{verbatim} ->>> s = c_char_p() ->>> s.value = "abc def ghi" ->>> s.value -'abc def ghi' ->>> s.value is s.value -False ->>> -\end{verbatim} - -Why is it printing \code{False}? ctypes instances are objects containing -a memory block plus some descriptors accessing the contents of the -memory. Storing a Python object in the memory block does not store -the object itself, instead the \code{contents} of the object is stored. -Accessing the contents again constructs a new Python each time! - - -\subsubsection{Variable-sized data types\label{ctypes-variable-sized-data-types}} - -\code{ctypes} provides some support for variable-sized arrays and -structures (this was added in version 0.9.9.7). - -The \code{resize} function can be used to resize the memory buffer of an -existing ctypes object. The function takes the object as first -argument, and the requested size in bytes as the second argument. The -memory block cannot be made smaller than the natural memory block -specified by the objects type, a \code{ValueError} is raised if this is -tried: -\begin{verbatim} ->>> short_array = (c_short * 4)() ->>> print sizeof(short_array) -8 ->>> resize(short_array, 4) -Traceback (most recent call last): - ... -ValueError: minimum size is 8 ->>> resize(short_array, 32) ->>> sizeof(short_array) -32 ->>> sizeof(type(short_array)) -8 ->>> -\end{verbatim} - -This is nice and fine, but how would one access the additional -elements contained in this array? Since the type still only knows -about 4 elements, we get errors accessing other elements: -\begin{verbatim} ->>> short_array[:] -[0, 0, 0, 0] ->>> short_array[7] -Traceback (most recent call last): - ... -IndexError: invalid index ->>> -\end{verbatim} - -Another way to use variable-sized data types with \code{ctypes} is to use -the dynamic nature of Python, and (re-)define the data type after the -required size is already known, on a case by case basis. - - -\subsubsection{Bugs, ToDo and non-implemented things\label{ctypes-bugs-todo-non-implemented-things}} - -Enumeration types are not implemented. You can do it easily yourself, -using \class{c{\_}int} as the base class. - -\code{long double} is not implemented. -% Local Variables: -% compile-command: "make.bat" -% End: - - -\subsection{ctypes reference\label{ctypes-ctypes-reference}} - - -\subsubsection{Finding shared libraries\label{ctypes-finding-shared-libraries}} - -When programming in a compiled language, shared libraries are accessed -when compiling/linking a program, and when the program is run. - -The purpose of the \code{find{\_}library} function is to locate a library in -a way similar to what the compiler does (on platforms with several -versions of a shared library the most recent should be loaded), while -the ctypes library loaders act like when a program is run, and call -the runtime loader directly. - -The \code{ctypes.util} module provides a function which can help to -determine the library to load. - -\begin{datadescni}{find_library(name)} -Try to find a library and return a pathname. \var{name} is the -library name without any prefix like \var{lib}, suffix like \code{.so}, -\code{.dylib} or version number (this is the form used for the posix -linker option \programopt{-l}). If no library can be found, returns -\code{None}. -\end{datadescni} - -The exact functionality is system dependend. - -On Linux, \code{find{\_}library} tries to run external programs -(/sbin/ldconfig, gcc, and objdump) to find the library file. It -returns the filename of the library file. Here are sone examples: -\begin{verbatim} ->>> from ctypes.util import find_library ->>> find_library("m") -'libm.so.6' ->>> find_library("c") -'libc.so.6' ->>> find_library("bz2") -'libbz2.so.1.0' ->>> -\end{verbatim} - -On OS X, \code{find{\_}library} tries several predefined naming schemes and -paths to locate the library, and returns a full pathname if successfull: -\begin{verbatim} ->>> from ctypes.util import find_library ->>> find_library("c") -'/usr/lib/libc.dylib' ->>> find_library("m") -'/usr/lib/libm.dylib' ->>> find_library("bz2") -'/usr/lib/libbz2.dylib' ->>> find_library("AGL") -'/System/Library/Frameworks/AGL.framework/AGL' ->>> -\end{verbatim} - -On Windows, \code{find{\_}library} searches along the system search path, -and returns the full pathname, but since there is no predefined naming -scheme a call like \code{find{\_}library("c")} will fail and return -\code{None}. - -If wrapping a shared library with \code{ctypes}, it \emph{may} be better to -determine the shared library name at development type, and hardcode -that into the wrapper module instead of using \code{find{\_}library} to -locate the library at runtime. - - -\subsubsection{Loading shared libraries\label{ctypes-loading-shared-libraries}} - -There are several ways to loaded shared libraries into the Python -process. One way is to instantiate one of the following classes: - -\begin{classdesc}{CDLL}{name, mode=DEFAULT_MODE, handle=None} -Instances of this class represent loaded shared libraries. -Functions in these libraries use the standard C calling -convention, and are assumed to return \code{int}. -\end{classdesc} - -\begin{classdesc}{OleDLL}{name, mode=DEFAULT_MODE, handle=None} -Windows only: Instances of this class represent loaded shared -libraries, functions in these libraries use the \code{stdcall} -calling convention, and are assumed to return the windows specific -\class{HRESULT} code. \class{HRESULT} values contain information -specifying whether the function call failed or succeeded, together -with additional error code. If the return value signals a -failure, an \class{WindowsError} is automatically raised. -\end{classdesc} - -\begin{classdesc}{WinDLL}{name, mode=DEFAULT_MODE, handle=None} -Windows only: Instances of this class represent loaded shared -libraries, functions in these libraries use the \code{stdcall} -calling convention, and are assumed to return \code{int} by default. - -On Windows CE only the standard calling convention is used, for -convenience the \class{WinDLL} and \class{OleDLL} use the standard calling -convention on this platform. -\end{classdesc} - -The Python GIL is released before calling any function exported by -these libraries, and reaquired afterwards. - -\begin{classdesc}{PyDLL}{name, mode=DEFAULT_MODE, handle=None} -Instances of this class behave like \class{CDLL} instances, except -that the Python GIL is \emph{not} released during the function call, -and after the function execution the Python error flag is checked. -If the error flag is set, a Python exception is raised. - -Thus, this is only useful to call Python C api functions directly. -\end{classdesc} - -All these classes can be instantiated by calling them with at least -one argument, the pathname of the shared library. If you have an -existing handle to an already loaded shard library, it can be passed -as the \code{handle} named parameter, otherwise the underlying platforms -\code{dlopen} or \method{LoadLibrary} function is used to load the library -into the process, and to get a handle to it. - -The \var{mode} parameter can be used to specify how the library is -loaded. For details, consult the \code{dlopen(3)} manpage, on Windows, -\var{mode} is ignored. - -\begin{datadescni}{RTLD_GLOBAL} -Flag to use as \var{mode} parameter. On platforms where this flag -is not available, it is defined as the integer zero. -\end{datadescni} - -\begin{datadescni}{RTLD_LOCAL} -Flag to use as \var{mode} parameter. On platforms where this is not -available, it is the same as \var{RTLD{\_}GLOBAL}. -\end{datadescni} - -\begin{datadescni}{DEFAULT_MODE} -The default mode which is used to load shared libraries. On OSX -10.3, this is \var{RTLD{\_}GLOBAL}, otherwise it is the same as -\var{RTLD{\_}LOCAL}. -\end{datadescni} - -Instances of these classes have no public methods, however -\method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} have special behaviour: functions -exported by the shared library can be accessed as attributes of by -index. Please note that both \method{{\_}{\_}getattr{\_}{\_}} and \method{{\_}{\_}getitem{\_}{\_}} -cache their result, so calling them repeatedly returns the same object -each time. - -The following public attributes are available, their name starts with -an underscore to not clash with exported function names: - -\begin{memberdesc}{_handle} -The system handle used to access the library. -\end{memberdesc} - -\begin{memberdesc}{_name} -The name of the library passed in the contructor. -\end{memberdesc} - -Shared libraries can also be loaded by using one of the prefabricated -objects, which are instances of the \class{LibraryLoader} class, either by -calling the \method{LoadLibrary} method, or by retrieving the library as -attribute of the loader instance. - -\begin{classdesc}{LibraryLoader}{dlltype} -Class which loads shared libraries. \code{dlltype} should be one -of the \class{CDLL}, \class{PyDLL}, \class{WinDLL}, or \class{OleDLL} types. - -\method{{\_}{\_}getattr{\_}{\_}} has special behaviour: It allows to load a shared -library by accessing it as attribute of a library loader -instance. The result is cached, so repeated attribute accesses -return the same library each time. -\end{classdesc} - -\begin{methoddesc}{LoadLibrary}{name} -Load a shared library into the process and return it. This method -always returns a new instance of the library. -\end{methoddesc} - -These prefabricated library loaders are available: - -\begin{datadescni}{cdll} -Creates \class{CDLL} instances. -\end{datadescni} - -\begin{datadescni}{windll} -Windows only: Creates \class{WinDLL} instances. -\end{datadescni} - -\begin{datadescni}{oledll} -Windows only: Creates \class{OleDLL} instances. -\end{datadescni} - -\begin{datadescni}{pydll} -Creates \class{PyDLL} instances. -\end{datadescni} - -For accessing the C Python api directly, a ready-to-use Python shared -library object is available: - -\begin{datadescni}{pythonapi} -An instance of \class{PyDLL} that exposes Python C api functions as -attributes. Note that all these functions are assumed to return C -\code{int}, which is of course not always the truth, so you have to -assign the correct \member{restype} attribute to use these functions. -\end{datadescni} - - -\subsubsection{Foreign functions\label{ctypes-foreign-functions}} - -As explained in the previous section, foreign functions can be -accessed as attributes of loaded shared libraries. The function -objects created in this way by default accept any number of arguments, -accept any ctypes data instances as arguments, and return the default -result type specified by the library loader. They are instances of a -private class: - -\begin{classdesc*}{_FuncPtr} -Base class for C callable foreign functions. -\end{classdesc*} - -Instances of foreign functions are also C compatible data types; they -represent C function pointers. - -This behaviour can be customized by assigning to special attributes of -the foreign function object. - -\begin{memberdesc}{restype} -Assign a ctypes type to specify the result type of the foreign -function. Use \code{None} for \code{void} a function not returning -anything. - -It is possible to assign a callable Python object that is not a -ctypes type, in this case the function is assumed to return a -C \code{int}, and the callable will be called with this integer, -allowing to do further processing or error checking. Using this -is deprecated, for more flexible postprocessing or error checking -use a ctypes data type as \member{restype} and assign a callable to the -\member{errcheck} attribute. -\end{memberdesc} - -\begin{memberdesc}{argtypes} -Assign a tuple of ctypes types to specify the argument types that -the function accepts. Functions using the \code{stdcall} calling -convention can only be called with the same number of arguments as -the length of this tuple; functions using the C calling convention -accept additional, unspecified arguments as well. - -When a foreign function is called, each actual argument is passed -to the \method{from{\_}param} class method of the items in the -\member{argtypes} tuple, this method allows to adapt the actual -argument to an object that the foreign function accepts. For -example, a \class{c{\_}char{\_}p} item in the \member{argtypes} tuple will -convert a unicode string passed as argument into an byte string -using ctypes conversion rules. - -New: It is now possible to put items in argtypes which are not -ctypes types, but each item must have a \method{from{\_}param} method -which returns a value usable as argument (integer, string, ctypes -instance). This allows to define adapters that can adapt custom -objects as function parameters. -\end{memberdesc} - -\begin{memberdesc}{errcheck} -Assign a Python function or another callable to this attribute. -The callable will be called with three or more arguments: -\end{memberdesc} - -\begin{funcdescni}{callable}{result, func, arguments} -\code{result} is what the foreign function returns, as specified by the -\member{restype} attribute. - -\code{func} is the foreign function object itself, this allows to -reuse the same callable object to check or postprocess the results -of several functions. - -\code{arguments} is a tuple containing the parameters originally -passed to the function call, this allows to specialize the -behaviour on the arguments used. - -The object that this function returns will be returned from the -foreign function call, but it can also check the result value and -raise an exception if the foreign function call failed. -\end{funcdescni} - -\begin{excdesc}{ArgumentError()} -This exception is raised when a foreign function call cannot -convert one of the passed arguments. -\end{excdesc} - - -\subsubsection{Function prototypes\label{ctypes-function-prototypes}} - -Foreign functions can also be created by instantiating function -prototypes. Function prototypes are similar to function prototypes in -C; they describe a function (return type, argument types, calling -convention) without defining an implementation. The factory -functions must be called with the desired result type and the argument -types of the function. - -\begin{funcdesc}{CFUNCTYPE}{restype, *argtypes} -The returned function prototype creates functions that use the -standard C calling convention. The function will release the GIL -during the call. -\end{funcdesc} - -\begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes} -Windows only: The returned function prototype creates functions -that use the \code{stdcall} calling convention, except on Windows CE -where \function{WINFUNCTYPE} is the same as \function{CFUNCTYPE}. The function -will release the GIL during the call. -\end{funcdesc} - -\begin{funcdesc}{PYFUNCTYPE}{restype, *argtypes} -The returned function prototype creates functions that use the -Python calling convention. The function will \emph{not} release the -GIL during the call. -\end{funcdesc} - -Function prototypes created by the factory functions can be -instantiated in different ways, depending on the type and number of -the parameters in the call. - -\begin{funcdescni}{prototype}{address} -Returns a foreign function at the specified address. -\end{funcdescni} - -\begin{funcdescni}{prototype}{callable} -Create a C callable function (a callback function) from a Python -\code{callable}. -\end{funcdescni} - -\begin{funcdescni}{prototype}{func_spec\optional{, paramflags}} -Returns a foreign function exported by a shared library. -\code{func{\_}spec} must be a 2-tuple \code{(name{\_}or{\_}ordinal, library)}. -The first item is the name of the exported function as string, or -the ordinal of the exported function as small integer. The second -item is the shared library instance. -\end{funcdescni} - -\begin{funcdescni}{prototype}{vtbl_index, name\optional{, paramflags\optional{, iid}}} -Returns a foreign function that will call a COM method. -\code{vtbl{\_}index} is the index into the virtual function table, a -small nonnegative integer. \var{name} is name of the COM method. -\var{iid} is an optional pointer to the interface identifier which -is used in extended error reporting. - -COM methods use a special calling convention: They require a -pointer to the COM interface as first argument, in addition to -those parameters that are specified in the \member{argtypes} tuple. -\end{funcdescni} - -The optional \var{paramflags} parameter creates foreign function -wrappers with much more functionality than the features described -above. - -\var{paramflags} must be a tuple of the same length as \member{argtypes}. - -Each item in this tuple contains further information about a -parameter, it must be a tuple containing 1, 2, or 3 items. - -The first item is an integer containing flags for the parameter: - -\begin{datadescni}{1} -Specifies an input parameter to the function. -\end{datadescni} - -\begin{datadescni}{2} -Output parameter. The foreign function fills in a value. -\end{datadescni} - -\begin{datadescni}{4} -Input parameter which defaults to the integer zero. -\end{datadescni} - -The optional second item is the parameter name as string. If this is -specified, the foreign function can be called with named parameters. - -The optional third item is the default value for this parameter. - -This example demonstrates how to wrap the Windows \code{MessageBoxA} -function so that it supports default parameters and named arguments. -The C declaration from the windows header file is this: -\begin{verbatim} -WINUSERAPI int WINAPI -MessageBoxA( - HWND hWnd , - LPCSTR lpText, - LPCSTR lpCaption, - UINT uType); -\end{verbatim} - -Here is the wrapping with \code{ctypes}: -\begin{quote} -\begin{verbatim}>>> from ctypes import c_int, WINFUNCTYPE, windll ->>> from ctypes.wintypes import HWND, LPCSTR, UINT ->>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT) ->>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0) ->>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags) ->>>\end{verbatim} -\end{quote} - -The MessageBox foreign function can now be called in these ways: -\begin{verbatim} ->>> MessageBox() ->>> MessageBox(text="Spam, spam, spam") ->>> MessageBox(flags=2, text="foo bar") ->>> -\end{verbatim} - -A second example demonstrates output parameters. The win32 -\code{GetWindowRect} function retrieves the dimensions of a specified -window by copying them into \code{RECT} structure that the caller has to -supply. Here is the C declaration: -\begin{verbatim} -WINUSERAPI BOOL WINAPI -GetWindowRect( - HWND hWnd, - LPRECT lpRect); -\end{verbatim} - -Here is the wrapping with \code{ctypes}: -\begin{quote} -\begin{verbatim}>>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError ->>> from ctypes.wintypes import BOOL, HWND, RECT ->>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT)) ->>> paramflags = (1, "hwnd"), (2, "lprect") ->>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags) ->>>\end{verbatim} -\end{quote} - -Functions with output parameters will automatically return the output -parameter value if there is a single one, or a tuple containing the -output parameter values when there are more than one, so the -GetWindowRect function now returns a RECT instance, when called. - -Output parameters can be combined with the \member{errcheck} protocol to do -further output processing and error checking. The win32 -\code{GetWindowRect} api function returns a \code{BOOL} to signal success or -failure, so this function could do the error checking, and raises an -exception when the api call failed: -\begin{verbatim} ->>> def errcheck(result, func, args): -... if not result: -... raise WinError() -... return args ->>> GetWindowRect.errcheck = errcheck ->>> -\end{verbatim} - -If the \member{errcheck} function returns the argument tuple it receives -unchanged, \code{ctypes} continues the normal processing it does on the -output parameters. If you want to return a tuple of window -coordinates instead of a \code{RECT} instance, you can retrieve the -fields in the function and return them instead, the normal processing -will no longer take place: -\begin{verbatim} ->>> def errcheck(result, func, args): -... if not result: -... raise WinError() -... rc = args[1] -... return rc.left, rc.top, rc.bottom, rc.right ->>> ->>> GetWindowRect.errcheck = errcheck ->>> -\end{verbatim} - - -\subsubsection{Utility functions\label{ctypes-utility-functions}} - -\begin{funcdesc}{addressof}{obj} -Returns the address of the memory buffer as integer. \code{obj} must -be an instance of a ctypes type. -\end{funcdesc} - -\begin{funcdesc}{alignment}{obj_or_type} -Returns the alignment requirements of a ctypes type. -\code{obj{\_}or{\_}type} must be a ctypes type or instance. -\end{funcdesc} - -\begin{funcdesc}{byref}{obj} -Returns a light-weight pointer to \code{obj}, which must be an -instance of a ctypes type. The returned object can only be used as -a foreign function call parameter. It behaves similar to -\code{pointer(obj)}, but the construction is a lot faster. -\end{funcdesc} - -\begin{funcdesc}{cast}{obj, type} -This function is similar to the cast operator in C. It returns a -new instance of \code{type} which points to the same memory block as -\code{obj}. \code{type} must be a pointer type, and \code{obj} must be an -object that can be interpreted as a pointer. -\end{funcdesc} - -\begin{funcdesc}{create_string_buffer}{init_or_size\optional{, size}} -This function creates a mutable character buffer. The returned -object is a ctypes array of \class{c{\_}char}. - -\code{init{\_}or{\_}size} must be an integer which specifies the size of -the array, or a string which will be used to initialize the array -items. - -If a string is specified as first argument, the buffer is made one -item larger than the length of the string so that the last element -in the array is a NUL termination character. An integer can be -passed as second argument which allows to specify the size of the -array if the length of the string should not be used. - -If the first parameter is a unicode string, it is converted into -an 8-bit string according to ctypes conversion rules. -\end{funcdesc} - -\begin{funcdesc}{create_unicode_buffer}{init_or_size\optional{, size}} -This function creates a mutable unicode character buffer. The -returned object is a ctypes array of \class{c{\_}wchar}. - -\code{init{\_}or{\_}size} must be an integer which specifies the size of -the array, or a unicode string which will be used to initialize -the array items. - -If a unicode string is specified as first argument, the buffer is -made one item larger than the length of the string so that the -last element in the array is a NUL termination character. An -integer can be passed as second argument which allows to specify -the size of the array if the length of the string should not be -used. - -If the first parameter is a 8-bit string, it is converted into an -unicode string according to ctypes conversion rules. -\end{funcdesc} - -\begin{funcdesc}{DllCanUnloadNow}{} -Windows only: This function is a hook which allows to implement -inprocess COM servers with ctypes. It is called from the -DllCanUnloadNow function that the {\_}ctypes extension dll exports. -\end{funcdesc} - -\begin{funcdesc}{DllGetClassObject}{} -Windows only: This function is a hook which allows to implement -inprocess COM servers with ctypes. It is called from the -DllGetClassObject function that the \code{{\_}ctypes} extension dll exports. -\end{funcdesc} - -\begin{funcdesc}{FormatError}{\optional{code}} -Windows only: Returns a textual description of the error code. If -no error code is specified, the last error code is used by calling -the Windows api function GetLastError. -\end{funcdesc} - -\begin{funcdesc}{GetLastError}{} -Windows only: Returns the last error code set by Windows in the -calling thread. -\end{funcdesc} - -\begin{funcdesc}{memmove}{dst, src, count} -Same as the standard C memmove library function: copies \var{count} -bytes from \code{src} to \var{dst}. \var{dst} and \code{src} must be -integers or ctypes instances that can be converted to pointers. -\end{funcdesc} - -\begin{funcdesc}{memset}{dst, c, count} -Same as the standard C memset library function: fills the memory -block at address \var{dst} with \var{count} bytes of value -\var{c}. \var{dst} must be an integer specifying an address, or a -ctypes instance. -\end{funcdesc} - -\begin{funcdesc}{POINTER}{type} -This factory function creates and returns a new ctypes pointer -type. Pointer types are cached an reused internally, so calling -this function repeatedly is cheap. type must be a ctypes type. -\end{funcdesc} - -\begin{funcdesc}{pointer}{obj} -This function creates a new pointer instance, pointing to -\code{obj}. The returned object is of the type POINTER(type(obj)). - -Note: If you just want to pass a pointer to an object to a foreign -function call, you should use \code{byref(obj)} which is much faster. -\end{funcdesc} - -\begin{funcdesc}{resize}{obj, size} -This function resizes the internal memory buffer of obj, which -must be an instance of a ctypes type. It is not possible to make -the buffer smaller than the native size of the objects type, as -given by sizeof(type(obj)), but it is possible to enlarge the -buffer. -\end{funcdesc} - -\begin{funcdesc}{set_conversion_mode}{encoding, errors} -This function sets the rules that ctypes objects use when -converting between 8-bit strings and unicode strings. encoding -must be a string specifying an encoding, like \code{'utf-8'} or -\code{'mbcs'}, errors must be a string specifying the error handling -on encoding/decoding errors. Examples of possible values are -\code{"strict"}, \code{"replace"}, or \code{"ignore"}. - -\code{set{\_}conversion{\_}mode} returns a 2-tuple containing the previous -conversion rules. On windows, the initial conversion rules are -\code{('mbcs', 'ignore')}, on other systems \code{('ascii', 'strict')}. -\end{funcdesc} - -\begin{funcdesc}{sizeof}{obj_or_type} -Returns the size in bytes of a ctypes type or instance memory -buffer. Does the same as the C \code{sizeof()} function. -\end{funcdesc} - -\begin{funcdesc}{string_at}{address\optional{, size}} -This function returns the string starting at memory address -address. If size is specified, it is used as size, otherwise the -string is assumed to be zero-terminated. -\end{funcdesc} - -\begin{funcdesc}{WinError}{code=None, descr=None} -Windows only: this function is probably the worst-named thing in -ctypes. It creates an instance of WindowsError. If \var{code} is not -specified, \code{GetLastError} is called to determine the error -code. If \code{descr} is not spcified, \function{FormatError} is called to -get a textual description of the error. -\end{funcdesc} - -\begin{funcdesc}{wstring_at}{address} -This function returns the wide character string starting at memory -address \code{address} as unicode string. If \code{size} is specified, -it is used as the number of characters of the string, otherwise -the string is assumed to be zero-terminated. -\end{funcdesc} - - -\subsubsection{Data types\label{ctypes-data-types}} - -\begin{classdesc*}{_CData} -This non-public class is the common base class of all ctypes data -types. Among other things, all ctypes type instances contain a -memory block that hold C compatible data; the address of the -memory block is returned by the \code{addressof()} helper function. -Another instance variable is exposed as \member{{\_}objects}; this -contains other Python objects that need to be kept alive in case -the memory block contains pointers. -\end{classdesc*} - -Common methods of ctypes data types, these are all class methods (to -be exact, they are methods of the metaclass): - -\begin{methoddesc}{from_address}{address} -This method returns a ctypes type instance using the memory -specified by address which must be an integer. -\end{methoddesc} - -\begin{methoddesc}{from_param}{obj} -This method adapts obj to a ctypes type. It is called with the -actual object used in a foreign function call, when the type is -present in the foreign functions \member{argtypes} tuple; it must -return an object that can be used as function call parameter. - -All ctypes data types have a default implementation of this -classmethod, normally it returns \code{obj} if that is an instance of -the type. Some types accept other objects as well. -\end{methoddesc} - -\begin{methoddesc}{in_dll}{library, name} -This method returns a ctypes type instance exported by a shared -library. \var{name} is the name of the symbol that exports the data, -\var{library} is the loaded shared library. -\end{methoddesc} - -Common instance variables of ctypes data types: - -\begin{memberdesc}{_b_base_} -Sometimes ctypes data instances do not own the memory block they -contain, instead they share part of the memory block of a base -object. The \member{{\_}b{\_}base{\_}} readonly member is the root ctypes -object that owns the memory block. -\end{memberdesc} - -\begin{memberdesc}{_b_needsfree_} -This readonly variable is true when the ctypes data instance has -allocated the memory block itself, false otherwise. -\end{memberdesc} - -\begin{memberdesc}{_objects} -This member is either \code{None} or a dictionary containing Python -objects that need to be kept alive so that the memory block -contents is kept valid. This object is only exposed for -debugging; never modify the contents of this dictionary. -\end{memberdesc} - - -\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types-2}} - -\begin{classdesc*}{_SimpleCData} -This non-public class is the base class of all fundamental ctypes -data types. It is mentioned here because it contains the common -attributes of the fundamental ctypes data types. \code{{\_}SimpleCData} -is a subclass of \code{{\_}CData}, so it inherits their methods and -attributes. -\end{classdesc*} - -Instances have a single attribute: - -\begin{memberdesc}{value} -This attribute contains the actual value of the instance. For -integer and pointer types, it is an integer, for character types, -it is a single character string, for character pointer types it -is a Python string or unicode string. - -When the \code{value} attribute is retrieved from a ctypes instance, -usually a new object is returned each time. \code{ctypes} does \emph{not} -implement original object return, always a new object is -constructed. The same is true for all other ctypes object -instances. -\end{memberdesc} - -Fundamental data types, when returned as foreign function call -results, or, for example, by retrieving structure field members or -array items, are transparently converted to native Python types. In -other words, if a foreign function has a \member{restype} of \class{c{\_}char{\_}p}, -you will always receive a Python string, \emph{not} a \class{c{\_}char{\_}p} -instance. - -Subclasses of fundamental data types do \emph{not} inherit this behaviour. -So, if a foreign functions \member{restype} is a subclass of \class{c{\_}void{\_}p}, -you will receive an instance of this subclass from the function call. -Of course, you can get the value of the pointer by accessing the -\code{value} attribute. - -These are the fundamental ctypes data types: - -\begin{classdesc*}{c_byte} -Represents the C signed char datatype, and interprets the value as -small integer. The constructor accepts an optional integer -initializer; no overflow checking is done. -\end{classdesc*} - -\begin{classdesc*}{c_char} -Represents the C char datatype, and interprets the value as a single -character. The constructor accepts an optional string initializer, -the length of the string must be exactly one character. -\end{classdesc*} - -\begin{classdesc*}{c_char_p} -Represents the C char * datatype, which must be a pointer to a -zero-terminated string. The constructor accepts an integer -address, or a string. -\end{classdesc*} - -\begin{classdesc*}{c_double} -Represents the C double datatype. The constructor accepts an -optional float initializer. -\end{classdesc*} - -\begin{classdesc*}{c_float} -Represents the C double datatype. The constructor accepts an -optional float initializer. -\end{classdesc*} - -\begin{classdesc*}{c_int} -Represents the C signed int datatype. The constructor accepts an -optional integer initializer; no overflow checking is done. On -platforms where \code{sizeof(int) == sizeof(long)} it is an alias to -\class{c{\_}long}. -\end{classdesc*} - -\begin{classdesc*}{c_int8} -Represents the C 8-bit \code{signed int} datatype. Usually an alias for -\class{c{\_}byte}. -\end{classdesc*} - -\begin{classdesc*}{c_int16} -Represents the C 16-bit signed int datatype. Usually an alias for -\class{c{\_}short}. -\end{classdesc*} - -\begin{classdesc*}{c_int32} -Represents the C 32-bit signed int datatype. Usually an alias for -\class{c{\_}int}. -\end{classdesc*} - -\begin{classdesc*}{c_int64} -Represents the C 64-bit \code{signed int} datatype. Usually an alias -for \class{c{\_}longlong}. -\end{classdesc*} - -\begin{classdesc*}{c_long} -Represents the C \code{signed long} datatype. The constructor accepts an -optional integer initializer; no overflow checking is done. -\end{classdesc*} - -\begin{classdesc*}{c_longlong} -Represents the C \code{signed long long} datatype. The constructor accepts -an optional integer initializer; no overflow checking is done. -\end{classdesc*} - -\begin{classdesc*}{c_short} -Represents the C \code{signed short} datatype. The constructor accepts an -optional integer initializer; no overflow checking is done. -\end{classdesc*} - -\begin{classdesc*}{c_size_t} -Represents the C \code{size{\_}t} datatype. -\end{classdesc*} - -\begin{classdesc*}{c_ubyte} -Represents the C \code{unsigned char} datatype, it interprets the -value as small integer. The constructor accepts an optional -integer initializer; no overflow checking is done. -\end{classdesc*} - -\begin{classdesc*}{c_uint} -Represents the C \code{unsigned int} datatype. The constructor accepts an -optional integer initializer; no overflow checking is done. On -platforms where \code{sizeof(int) == sizeof(long)} it is an alias for -\class{c{\_}ulong}. -\end{classdesc*} - -\begin{classdesc*}{c_uint8} -Represents the C 8-bit unsigned int datatype. Usually an alias for -\class{c{\_}ubyte}. -\end{classdesc*} - -\begin{classdesc*}{c_uint16} -Represents the C 16-bit unsigned int datatype. Usually an alias for -\class{c{\_}ushort}. -\end{classdesc*} - -\begin{classdesc*}{c_uint32} -Represents the C 32-bit unsigned int datatype. Usually an alias for -\class{c{\_}uint}. -\end{classdesc*} - -\begin{classdesc*}{c_uint64} -Represents the C 64-bit unsigned int datatype. Usually an alias for -\class{c{\_}ulonglong}. -\end{classdesc*} - -\begin{classdesc*}{c_ulong} -Represents the C \code{unsigned long} datatype. The constructor accepts an -optional integer initializer; no overflow checking is done. -\end{classdesc*} - -\begin{classdesc*}{c_ulonglong} -Represents the C \code{unsigned long long} datatype. The constructor -accepts an optional integer initializer; no overflow checking is -done. -\end{classdesc*} - -\begin{classdesc*}{c_ushort} -Represents the C \code{unsigned short} datatype. The constructor accepts an -optional integer initializer; no overflow checking is done. -\end{classdesc*} - -\begin{classdesc*}{c_void_p} -Represents the C \code{void *} type. The value is represented as -integer. The constructor accepts an optional integer initializer. -\end{classdesc*} - -\begin{classdesc*}{c_wchar} -Represents the C \code{wchar{\_}t} datatype, and interprets the value as a -single character unicode string. The constructor accepts an -optional string initializer, the length of the string must be -exactly one character. -\end{classdesc*} - -\begin{classdesc*}{c_wchar_p} -Represents the C \code{wchar{\_}t *} datatype, which must be a pointer to -a zero-terminated wide character string. The constructor accepts -an integer address, or a string. -\end{classdesc*} - -\begin{classdesc*}{c_bool} -Represent the C \code{bool} datatype (more accurately, _Bool from C99). -Its value can be True or False, and the constructor accepts any object that -has a truth value. -\versionadded{2.6} -\end{classdesc*} - -\begin{classdesc*}{HRESULT} -Windows only: Represents a \class{HRESULT} value, which contains success -or error information for a function or method call. -\end{classdesc*} - -\begin{classdesc*}{py_object} -Represents the C \code{PyObject *} datatype. Calling this without an -argument creates a \code{NULL} \code{PyObject *} pointer. -\end{classdesc*} - -The \code{ctypes.wintypes} module provides quite some other Windows -specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}. -Some useful structures like \code{MSG} or \code{RECT} are also defined. - - -\subsubsection{Structured data types\label{ctypes-structured-data-types}} - -\begin{classdesc}{Union}{*args, **kw} -Abstract base class for unions in native byte order. -\end{classdesc} - -\begin{classdesc}{BigEndianStructure}{*args, **kw} -Abstract base class for structures in \emph{big endian} byte order. -\end{classdesc} - -\begin{classdesc}{LittleEndianStructure}{*args, **kw} -Abstract base class for structures in \emph{little endian} byte order. -\end{classdesc} - -Structures with non-native byte order cannot contain pointer type -fields, or any other data types containing pointer type fields. - -\begin{classdesc}{Structure}{*args, **kw} -Abstract base class for structures in \emph{native} byte order. -\end{classdesc} - -Concrete structure and union types must be created by subclassing one -of these types, and at least define a \member{{\_}fields{\_}} class variable. -\code{ctypes} will create descriptors which allow reading and writing the -fields by direct attribute accesses. These are the - -\begin{memberdesc}{_fields_} -A sequence defining the structure fields. The items must be -2-tuples or 3-tuples. The first item is the name of the field, -the second item specifies the type of the field; it can be any -ctypes data type. - -For integer type fields like \class{c{\_}int}, a third optional item can -be given. It must be a small positive integer defining the bit -width of the field. - -Field names must be unique within one structure or union. This is -not checked, only one field can be accessed when names are -repeated. - -It is possible to define the \member{{\_}fields{\_}} class variable \emph{after} -the class statement that defines the Structure subclass, this -allows to create data types that directly or indirectly reference -themselves: -\begin{verbatim} -class List(Structure): - pass -List._fields_ = [("pnext", POINTER(List)), - ... - ] -\end{verbatim} - -The \member{{\_}fields{\_}} class variable must, however, be defined before -the type is first used (an instance is created, \code{sizeof()} is -called on it, and so on). Later assignments to the \member{{\_}fields{\_}} -class variable will raise an AttributeError. - -Structure and union subclass constructors accept both positional -and named arguments. Positional arguments are used to initialize -the fields in the same order as they appear in the \member{{\_}fields{\_}} -definition, named arguments are used to initialize the fields with -the corresponding name. - -It is possible to defined sub-subclasses of structure types, they -inherit the fields of the base class plus the \member{{\_}fields{\_}} defined -in the sub-subclass, if any. -\end{memberdesc} - -\begin{memberdesc}{_pack_} -An optional small integer that allows to override the alignment of -structure fields in the instance. \member{{\_}pack{\_}} must already be -defined when \member{{\_}fields{\_}} is assigned, otherwise it will have no -effect. -\end{memberdesc} - -\begin{memberdesc}{_anonymous_} -An optional sequence that lists the names of unnamed (anonymous) -fields. \code{{\_}anonymous{\_}} must be already defined when \member{{\_}fields{\_}} -is assigned, otherwise it will have no effect. - -The fields listed in this variable must be structure or union type -fields. \code{ctypes} will create descriptors in the structure type -that allows to access the nested fields directly, without the need -to create the structure or union field. - -Here is an example type (Windows): -\begin{verbatim} -class _U(Union): - _fields_ = [("lptdesc", POINTER(TYPEDESC)), - ("lpadesc", POINTER(ARRAYDESC)), - ("hreftype", HREFTYPE)] - -class TYPEDESC(Structure): - _fields_ = [("u", _U), - ("vt", VARTYPE)] - - _anonymous_ = ("u",) -\end{verbatim} - -The \code{TYPEDESC} structure describes a COM data type, the \code{vt} -field specifies which one of the union fields is valid. Since the -\code{u} field is defined as anonymous field, it is now possible to -access the members directly off the TYPEDESC instance. -\code{td.lptdesc} and \code{td.u.lptdesc} are equivalent, but the former -is faster since it does not need to create a temporary union -instance: -\begin{verbatim} -td = TYPEDESC() -td.vt = VT_PTR -td.lptdesc = POINTER(some_type) -td.u.lptdesc = POINTER(some_type) -\end{verbatim} -\end{memberdesc} - -It is possible to defined sub-subclasses of structures, they inherit -the fields of the base class. If the subclass definition has a -separate \member{{\_}fields{\_}} variable, the fields specified in this are -appended to the fields of the base class. - -Structure and union constructors accept both positional and -keyword arguments. Positional arguments are used to initialize member -fields in the same order as they are appear in \member{{\_}fields{\_}}. Keyword -arguments in the constructor are interpreted as attribute assignments, -so they will initialize \member{{\_}fields{\_}} with the same name, or create new -attributes for names not present in \member{{\_}fields{\_}}. - - -\subsubsection{Arrays and pointers\label{ctypes-arrays-pointers}} - -Not yet written - please see section~\ref{ctypes-pointers}, pointers and -section~\ref{ctypes-arrays}, arrays in the tutorial. - diff --git a/Doc/lib/libcurses.tex b/Doc/lib/libcurses.tex deleted file mode 100644 index 33dea5a..0000000 --- a/Doc/lib/libcurses.tex +++ /dev/null @@ -1,1405 +0,0 @@ -\section{\module{curses} --- - Terminal handling for character-cell displays} - -\declaremodule{standard}{curses} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\sectionauthor{Eric Raymond}{esr@thyrsus.com} -\modulesynopsis{An interface to the curses library, providing portable - terminal handling.} - -\versionchanged[Added support for the \code{ncurses} library and - converted to a package]{1.6} - -The \module{curses} module provides an interface to the curses -library, the de-facto standard for portable advanced terminal -handling. - -While curses is most widely used in the \UNIX{} environment, versions -are available for DOS, OS/2, and possibly other systems as well. This -extension module is designed to match the API of ncurses, an -open-source curses library hosted on Linux and the BSD variants of -\UNIX. - -\begin{seealso} - \seemodule{curses.ascii}{Utilities for working with \ASCII{} - characters, regardless of your locale - settings.} - \seemodule{curses.panel}{A panel stack extension that adds depth to - curses windows.} - \seemodule{curses.textpad}{Editable text widget for curses supporting - \program{Emacs}-like bindings.} - \seemodule{curses.wrapper}{Convenience function to ensure proper - terminal setup and resetting on - application entry and exit.} - \seetitle[http://www.python.org/doc/howto/curses/curses.html]{Curses - Programming with Python}{Tutorial material on using curses - with Python, by Andrew Kuchling and Eric Raymond, is - available on the Python Web site.} - \seetext{The \file{Demo/curses/} directory in the Python source - distribution contains some example programs using the - curses bindings provided by this module.} -\end{seealso} - - -\subsection{Functions \label{curses-functions}} - -The module \module{curses} defines the following exception: - -\begin{excdesc}{error} -Exception raised when a curses library function returns an error. -\end{excdesc} - -\note{Whenever \var{x} or \var{y} arguments to a function -or a method are optional, they default to the current cursor location. -Whenever \var{attr} is optional, it defaults to \constant{A_NORMAL}.} - -The module \module{curses} defines the following functions: - -\begin{funcdesc}{baudrate}{} -Returns the output speed of the terminal in bits per second. On -software terminal emulators it will have a fixed high value. -Included for historical reasons; in former times, it was used to -write output loops for time delays and occasionally to change -interfaces depending on the line speed. -\end{funcdesc} - -\begin{funcdesc}{beep}{} -Emit a short attention sound. -\end{funcdesc} - -\begin{funcdesc}{can_change_color}{} -Returns true or false, depending on whether the programmer can change -the colors displayed by the terminal. -\end{funcdesc} - -\begin{funcdesc}{cbreak}{} -Enter cbreak mode. In cbreak mode (sometimes called ``rare'' mode) -normal tty line buffering is turned off and characters are available -to be read one by one. However, unlike raw mode, special characters -(interrupt, quit, suspend, and flow control) retain their effects on -the tty driver and calling program. Calling first \function{raw()} -then \function{cbreak()} leaves the terminal in cbreak mode. -\end{funcdesc} - -\begin{funcdesc}{color_content}{color_number} -Returns the intensity of the red, green, and blue (RGB) components in -the color \var{color_number}, which must be between \code{0} and -\constant{COLORS}. A 3-tuple is returned, containing the R,G,B values -for the given color, which will be between \code{0} (no component) and -\code{1000} (maximum amount of component). -\end{funcdesc} - -\begin{funcdesc}{color_pair}{color_number} -Returns the attribute value for displaying text in the specified -color. This attribute value can be combined with -\constant{A_STANDOUT}, \constant{A_REVERSE}, and the other -\constant{A_*} attributes. \function{pair_number()} is the -counterpart to this function. -\end{funcdesc} - -\begin{funcdesc}{curs_set}{visibility} -Sets the cursor state. \var{visibility} can be set to 0, 1, or 2, for -invisible, normal, or very visible. If the terminal supports the -visibility requested, the previous cursor state is returned; -otherwise, an exception is raised. On many terminals, the ``visible'' -mode is an underline cursor and the ``very visible'' mode is a block cursor. -\end{funcdesc} - -\begin{funcdesc}{def_prog_mode}{} -Saves the current terminal mode as the ``program'' mode, the mode when -the running program is using curses. (Its counterpart is the -``shell'' mode, for when the program is not in curses.) Subsequent calls -to \function{reset_prog_mode()} will restore this mode. -\end{funcdesc} - -\begin{funcdesc}{def_shell_mode}{} -Saves the current terminal mode as the ``shell'' mode, the mode when -the running program is not using curses. (Its counterpart is the -``program'' mode, when the program is using curses capabilities.) -Subsequent calls -to \function{reset_shell_mode()} will restore this mode. -\end{funcdesc} - -\begin{funcdesc}{delay_output}{ms} -Inserts an \var{ms} millisecond pause in output. -\end{funcdesc} - -\begin{funcdesc}{doupdate}{} -Update the physical screen. The curses library keeps two data -structures, one representing the current physical screen contents -and a virtual screen representing the desired next state. The -\function{doupdate()} ground updates the physical screen to match the -virtual screen. - -The virtual screen may be updated by a \method{noutrefresh()} call -after write operations such as \method{addstr()} have been performed -on a window. The normal \method{refresh()} call is simply -\method{noutrefresh()} followed by \function{doupdate()}; if you have -to update multiple windows, you can speed performance and perhaps -reduce screen flicker by issuing \method{noutrefresh()} calls on -all windows, followed by a single \function{doupdate()}. -\end{funcdesc} - -\begin{funcdesc}{echo}{} -Enter echo mode. In echo mode, each character input is echoed to the -screen as it is entered. -\end{funcdesc} - -\begin{funcdesc}{endwin}{} -De-initialize the library, and return terminal to normal status. -\end{funcdesc} - -\begin{funcdesc}{erasechar}{} -Returns the user's current erase character. Under \UNIX{} operating -systems this is a property of the controlling tty of the curses -program, and is not set by the curses library itself. -\end{funcdesc} - -\begin{funcdesc}{filter}{} -The \function{filter()} routine, if used, must be called before -\function{initscr()} is called. The effect is that, during those -calls, LINES is set to 1; the capabilities clear, cup, cud, cud1, -cuu1, cuu, vpa are disabled; and the home string is set to the value of cr. -The effect is that the cursor is confined to the current line, and so -are screen updates. This may be used for enabling character-at-a-time -line editing without touching the rest of the screen. -\end{funcdesc} - -\begin{funcdesc}{flash}{} -Flash the screen. That is, change it to reverse-video and then change -it back in a short interval. Some people prefer such as `visible bell' -to the audible attention signal produced by \function{beep()}. -\end{funcdesc} - -\begin{funcdesc}{flushinp}{} -Flush all input buffers. This throws away any typeahead that has -been typed by the user and has not yet been processed by the program. -\end{funcdesc} - -\begin{funcdesc}{getmouse}{} -After \method{getch()} returns \constant{KEY_MOUSE} to signal a mouse -event, this method should be call to retrieve the queued mouse event, -represented as a 5-tuple -\code{(\var{id}, \var{x}, \var{y}, \var{z}, \var{bstate})}. -\var{id} is an ID value used to distinguish multiple devices, -and \var{x}, \var{y}, \var{z} are the event's coordinates. (\var{z} -is currently unused.). \var{bstate} is an integer value whose bits -will be set to indicate the type of event, and will be the bitwise OR -of one or more of the following constants, where \var{n} is the button -number from 1 to 4: -\constant{BUTTON\var{n}_PRESSED}, -\constant{BUTTON\var{n}_RELEASED}, -\constant{BUTTON\var{n}_CLICKED}, -\constant{BUTTON\var{n}_DOUBLE_CLICKED}, -\constant{BUTTON\var{n}_TRIPLE_CLICKED}, -\constant{BUTTON_SHIFT}, -\constant{BUTTON_CTRL}, -\constant{BUTTON_ALT}. -\end{funcdesc} - -\begin{funcdesc}{getsyx}{} -Returns the current coordinates of the virtual screen cursor in y and -x. If leaveok is currently true, then -1,-1 is returned. -\end{funcdesc} - -\begin{funcdesc}{getwin}{file} -Reads window related data stored in the file by an earlier -\function{putwin()} call. The routine then creates and initializes a -new window using that data, returning the new window object. -\end{funcdesc} - -\begin{funcdesc}{has_colors}{} -Returns true if the terminal can display colors; otherwise, it -returns false. -\end{funcdesc} - -\begin{funcdesc}{has_ic}{} -Returns true if the terminal has insert- and delete- character -capabilities. This function is included for historical reasons only, -as all modern software terminal emulators have such capabilities. -\end{funcdesc} - -\begin{funcdesc}{has_il}{} -Returns true if the terminal has insert- and -delete-line capabilities, or can simulate them using -scrolling regions. This function is included for historical reasons only, -as all modern software terminal emulators have such capabilities. -\end{funcdesc} - -\begin{funcdesc}{has_key}{ch} -Takes a key value \var{ch}, and returns true if the current terminal -type recognizes a key with that value. -\end{funcdesc} - -\begin{funcdesc}{halfdelay}{tenths} -Used for half-delay mode, which is similar to cbreak mode in that -characters typed by the user are immediately available to the program. -However, after blocking for \var{tenths} tenths of seconds, an -exception is raised if nothing has been typed. The value of -\var{tenths} must be a number between 1 and 255. Use -\function{nocbreak()} to leave half-delay mode. -\end{funcdesc} - -\begin{funcdesc}{init_color}{color_number, r, g, b} -Changes the definition of a color, taking the number of the color to -be changed followed by three RGB values (for the amounts of red, -green, and blue components). The value of \var{color_number} must be -between \code{0} and \constant{COLORS}. Each of \var{r}, \var{g}, -\var{b}, must be a value between \code{0} and \code{1000}. When -\function{init_color()} is used, all occurrences of that color on the -screen immediately change to the new definition. This function is a -no-op on most terminals; it is active only if -\function{can_change_color()} returns \code{1}. -\end{funcdesc} - -\begin{funcdesc}{init_pair}{pair_number, fg, bg} -Changes the definition of a color-pair. It takes three arguments: the -number of the color-pair to be changed, the foreground color number, -and the background color number. The value of \var{pair_number} must -be between \code{1} and \code{COLOR_PAIRS - 1} (the \code{0} color -pair is wired to white on black and cannot be changed). The value of -\var{fg} and \var{bg} arguments must be between \code{0} and -\constant{COLORS}. If the color-pair was previously initialized, the -screen is refreshed and all occurrences of that color-pair are changed -to the new definition. -\end{funcdesc} - -\begin{funcdesc}{initscr}{} -Initialize the library. Returns a \class{WindowObject} which represents -the whole screen. \note{If there is an error opening the terminal, -the underlying curses library may cause the interpreter to exit.} -\end{funcdesc} - -\begin{funcdesc}{isendwin}{} -Returns true if \function{endwin()} has been called (that is, the -curses library has been deinitialized). -\end{funcdesc} - -\begin{funcdesc}{keyname}{k} -Return the name of the key numbered \var{k}. The name of a key -generating printable ASCII character is the key's character. The name -of a control-key combination is a two-character string consisting of a -caret followed by the corresponding printable ASCII character. The -name of an alt-key combination (128-255) is a string consisting of the -prefix `M-' followed by the name of the corresponding ASCII character. -\end{funcdesc} - -\begin{funcdesc}{killchar}{} -Returns the user's current line kill character. Under \UNIX{} operating -systems this is a property of the controlling tty of the curses -program, and is not set by the curses library itself. -\end{funcdesc} - -\begin{funcdesc}{longname}{} -Returns a string containing the terminfo long name field describing the current -terminal. The maximum length of a verbose description is 128 -characters. It is defined only after the call to -\function{initscr()}. -\end{funcdesc} - -\begin{funcdesc}{meta}{yes} -If \var{yes} is 1, allow 8-bit characters to be input. If \var{yes} is 0, -allow only 7-bit chars. -\end{funcdesc} - -\begin{funcdesc}{mouseinterval}{interval} -Sets the maximum time in milliseconds that can elapse between press and -release events in order for them to be recognized as a click, and -returns the previous interval value. The default value is 200 msec, -or one fifth of a second. -\end{funcdesc} - -\begin{funcdesc}{mousemask}{mousemask} -Sets the mouse events to be reported, and returns a tuple -\code{(\var{availmask}, \var{oldmask})}. -\var{availmask} indicates which of the -specified mouse events can be reported; on complete failure it returns -0. \var{oldmask} is the previous value of the given window's mouse -event mask. If this function is never called, no mouse events are -ever reported. -\end{funcdesc} - -\begin{funcdesc}{napms}{ms} -Sleep for \var{ms} milliseconds. -\end{funcdesc} - -\begin{funcdesc}{newpad}{nlines, ncols} -Creates and returns a pointer to a new pad data structure with the -given number of lines and columns. A pad is returned as a -window object. - -A pad is like a window, except that it is not restricted by the screen -size, and is not necessarily associated with a particular part of the -screen. Pads can be used when a large window is needed, and only a -part of the window will be on the screen at one time. Automatic -refreshes of pads (such as from scrolling or echoing of input) do not -occur. The \method{refresh()} and \method{noutrefresh()} methods of a -pad require 6 arguments to specify the part of the pad to be -displayed and the location on the screen to be used for the display. -The arguments are pminrow, pmincol, sminrow, smincol, smaxrow, -smaxcol; the p arguments refer to the upper left corner of the pad -region to be displayed and the s arguments define a clipping box on -the screen within which the pad region is to be displayed. -\end{funcdesc} - -\begin{funcdesc}{newwin}{\optional{nlines, ncols,} begin_y, begin_x} -Return a new window, whose left-upper corner is at -\code{(\var{begin_y}, \var{begin_x})}, and whose height/width is -\var{nlines}/\var{ncols}. - -By default, the window will extend from the -specified position to the lower right corner of the screen. -\end{funcdesc} - -\begin{funcdesc}{nl}{} -Enter newline mode. This mode translates the return key into newline -on input, and translates newline into return and line-feed on output. -Newline mode is initially on. -\end{funcdesc} - -\begin{funcdesc}{nocbreak}{} -Leave cbreak mode. Return to normal ``cooked'' mode with line buffering. -\end{funcdesc} - -\begin{funcdesc}{noecho}{} -Leave echo mode. Echoing of input characters is turned off. -\end{funcdesc} - -\begin{funcdesc}{nonl}{} -Leave newline mode. Disable translation of return into newline on -input, and disable low-level translation of newline into -newline/return on output (but this does not change the behavior of -\code{addch('\e n')}, which always does the equivalent of return and -line feed on the virtual screen). With translation off, curses can -sometimes speed up vertical motion a little; also, it will be able to -detect the return key on input. -\end{funcdesc} - -\begin{funcdesc}{noqiflush}{} -When the noqiflush routine is used, normal flush of input and -output queues associated with the INTR, QUIT and SUSP -characters will not be done. You may want to call -\function{noqiflush()} in a signal handler if you want output -to continue as though the interrupt had not occurred, after the -handler exits. -\end{funcdesc} - -\begin{funcdesc}{noraw}{} -Leave raw mode. Return to normal ``cooked'' mode with line buffering. -\end{funcdesc} - -\begin{funcdesc}{pair_content}{pair_number} -Returns a tuple \code{(\var{fg}, \var{bg})} containing the colors for -the requested color pair. The value of \var{pair_number} must be -between \code{1} and \code{\constant{COLOR_PAIRS} - 1}. -\end{funcdesc} - -\begin{funcdesc}{pair_number}{attr} -Returns the number of the color-pair set by the attribute value -\var{attr}. \function{color_pair()} is the counterpart to this -function. -\end{funcdesc} - -\begin{funcdesc}{putp}{string} -Equivalent to \code{tputs(str, 1, putchar)}; emits the value of a -specified terminfo capability for the current terminal. Note that the -output of putp always goes to standard output. -\end{funcdesc} - -\begin{funcdesc}{qiflush}{ \optional{flag} } -If \var{flag} is false, the effect is the same as calling -\function{noqiflush()}. If \var{flag} is true, or no argument is -provided, the queues will be flushed when these control characters are -read. -\end{funcdesc} - -\begin{funcdesc}{raw}{} -Enter raw mode. In raw mode, normal line buffering and -processing of interrupt, quit, suspend, and flow control keys are -turned off; characters are presented to curses input functions one -by one. -\end{funcdesc} - -\begin{funcdesc}{reset_prog_mode}{} -Restores the terminal to ``program'' mode, as previously saved -by \function{def_prog_mode()}. -\end{funcdesc} - -\begin{funcdesc}{reset_shell_mode}{} -Restores the terminal to ``shell'' mode, as previously saved -by \function{def_shell_mode()}. -\end{funcdesc} - -\begin{funcdesc}{setsyx}{y, x} -Sets the virtual screen cursor to \var{y}, \var{x}. -If \var{y} and \var{x} are both -1, then leaveok is set. -\end{funcdesc} - -\begin{funcdesc}{setupterm}{\optional{termstr, fd}} -Initializes the terminal. \var{termstr} is a string giving the -terminal name; if omitted, the value of the TERM environment variable -will be used. \var{fd} is the file descriptor to which any -initialization sequences will be sent; if not supplied, the file -descriptor for \code{sys.stdout} will be used. -\end{funcdesc} - -\begin{funcdesc}{start_color}{} -Must be called if the programmer wants to use colors, and before any -other color manipulation routine is called. It is good -practice to call this routine right after \function{initscr()}. - -\function{start_color()} initializes eight basic colors (black, red, -green, yellow, blue, magenta, cyan, and white), and two global -variables in the \module{curses} module, \constant{COLORS} and -\constant{COLOR_PAIRS}, containing the maximum number of colors and -color-pairs the terminal can support. It also restores the colors on -the terminal to the values they had when the terminal was just turned -on. -\end{funcdesc} - -\begin{funcdesc}{termattrs}{} -Returns a logical OR of all video attributes supported by the -terminal. This information is useful when a curses program needs -complete control over the appearance of the screen. -\end{funcdesc} - -\begin{funcdesc}{termname}{} -Returns the value of the environment variable TERM, truncated to 14 -characters. -\end{funcdesc} - -\begin{funcdesc}{tigetflag}{capname} -Returns the value of the Boolean capability corresponding to the -terminfo capability name \var{capname}. The value \code{-1} is -returned if \var{capname} is not a Boolean capability, or \code{0} if -it is canceled or absent from the terminal description. -\end{funcdesc} - -\begin{funcdesc}{tigetnum}{capname} -Returns the value of the numeric capability corresponding to the -terminfo capability name \var{capname}. The value \code{-2} is -returned if \var{capname} is not a numeric capability, or \code{-1} if -it is canceled or absent from the terminal description. -\end{funcdesc} - -\begin{funcdesc}{tigetstr}{capname} -Returns the value of the string capability corresponding to the -terminfo capability name \var{capname}. \code{None} is returned if -\var{capname} is not a string capability, or is canceled or absent -from the terminal description. -\end{funcdesc} - -\begin{funcdesc}{tparm}{str\optional{,...}} -Instantiates the string \var{str} with the supplied parameters, where -\var{str} should be a parameterized string obtained from the terminfo -database. E.g. \code{tparm(tigetstr("cup"), 5, 3)} could result in -\code{'\e{}033[6;4H'}, the exact result depending on terminal type. -\end{funcdesc} - -\begin{funcdesc}{typeahead}{fd} -Specifies that the file descriptor \var{fd} be used for typeahead -checking. If \var{fd} is \code{-1}, then no typeahead checking is -done. - -The curses library does ``line-breakout optimization'' by looking for -typeahead periodically while updating the screen. If input is found, -and it is coming from a tty, the current update is postponed until -refresh or doupdate is called again, allowing faster response to -commands typed in advance. This function allows specifying a different -file descriptor for typeahead checking. -\end{funcdesc} - -\begin{funcdesc}{unctrl}{ch} -Returns a string which is a printable representation of the character -\var{ch}. Control characters are displayed as a caret followed by the -character, for example as \code{\textasciicircum C}. Printing -characters are left as they are. -\end{funcdesc} - -\begin{funcdesc}{ungetch}{ch} -Push \var{ch} so the next \method{getch()} will return it. -\note{Only one \var{ch} can be pushed before \method{getch()} -is called.} -\end{funcdesc} - -\begin{funcdesc}{ungetmouse}{id, x, y, z, bstate} -Push a \constant{KEY_MOUSE} event onto the input queue, associating -the given state data with it. -\end{funcdesc} - -\begin{funcdesc}{use_env}{flag} -If used, this function should be called before \function{initscr()} or -newterm are called. When \var{flag} is false, the values of -lines and columns specified in the terminfo database will be -used, even if environment variables \envvar{LINES} and -\envvar{COLUMNS} (used by default) are set, or if curses is running in -a window (in which case default behavior would be to use the window -size if \envvar{LINES} and \envvar{COLUMNS} are not set). -\end{funcdesc} - -\begin{funcdesc}{use_default_colors}{} -Allow use of default values for colors on terminals supporting this -feature. Use this to support transparency in your -application. The default color is assigned to the color number -1. -After calling this function, -\code{init_pair(x, curses.COLOR_RED, -1)} initializes, for instance, -color pair \var{x} to a red foreground color on the default background. -\end{funcdesc} - -\subsection{Window Objects \label{curses-window-objects}} - -Window objects, as returned by \function{initscr()} and -\function{newwin()} above, have the -following methods: - -\begin{methoddesc}[window]{addch}{\optional{y, x,} ch\optional{, attr}} -\note{A \emph{character} means a C character (an -\ASCII{} code), rather then a Python character (a string of length 1). -(This note is true whenever the documentation mentions a character.) -The builtin \function{ord()} is handy for conveying strings to codes.} - -Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes -\var{attr}, overwriting any character previously painter at that -location. By default, the character position and attributes are the -current settings for the window object. -\end{methoddesc} - -\begin{methoddesc}[window]{addnstr}{\optional{y, x,} str, n\optional{, attr}} -Paint at most \var{n} characters of the -string \var{str} at \code{(\var{y}, \var{x})} with attributes -\var{attr}, overwriting anything previously on the display. -\end{methoddesc} - -\begin{methoddesc}[window]{addstr}{\optional{y, x,} str\optional{, attr}} -Paint the string \var{str} at \code{(\var{y}, \var{x})} with attributes -\var{attr}, overwriting anything previously on the display. -\end{methoddesc} - -\begin{methoddesc}[window]{attroff}{attr} -Remove attribute \var{attr} from the ``background'' set applied to all -writes to the current window. -\end{methoddesc} - -\begin{methoddesc}[window]{attron}{attr} -Add attribute \var{attr} from the ``background'' set applied to all -writes to the current window. -\end{methoddesc} - -\begin{methoddesc}[window]{attrset}{attr} -Set the ``background'' set of attributes to \var{attr}. This set is -initially 0 (no attributes). -\end{methoddesc} - -\begin{methoddesc}[window]{bkgd}{ch\optional{, attr}} -Sets the background property of the window to the character \var{ch}, -with attributes \var{attr}. The change is then applied to every -character position in that window: -\begin{itemize} -\item -The attribute of every character in the window is -changed to the new background attribute. -\item -Wherever the former background character appears, -it is changed to the new background character. -\end{itemize} - -\end{methoddesc} - -\begin{methoddesc}[window]{bkgdset}{ch\optional{, attr}} -Sets the window's background. A window's background consists of a -character and any combination of attributes. The attribute part of -the background is combined (OR'ed) with all non-blank characters that -are written into the window. Both the character and attribute parts -of the background are combined with the blank characters. The -background becomes a property of the character and moves with the -character through any scrolling and insert/delete line/character -operations. -\end{methoddesc} - -\begin{methoddesc}[window]{border}{\optional{ls\optional{, rs\optional{, - ts\optional{, bs\optional{, tl\optional{, - tr\optional{, bl\optional{, br}}}}}}}}} -Draw a border around the edges of the window. Each parameter specifies -the character to use for a specific part of the border; see the table -below for more details. The characters can be specified as integers -or as one-character strings. - -\note{A \code{0} value for any parameter will cause the -default character to be used for that parameter. Keyword parameters -can \emph{not} be used. The defaults are listed in this table:} - -\begin{tableiii}{l|l|l}{var}{Parameter}{Description}{Default value} - \lineiii{ls}{Left side}{\constant{ACS_VLINE}} - \lineiii{rs}{Right side}{\constant{ACS_VLINE}} - \lineiii{ts}{Top}{\constant{ACS_HLINE}} - \lineiii{bs}{Bottom}{\constant{ACS_HLINE}} - \lineiii{tl}{Upper-left corner}{\constant{ACS_ULCORNER}} - \lineiii{tr}{Upper-right corner}{\constant{ACS_URCORNER}} - \lineiii{bl}{Bottom-left corner}{\constant{ACS_LLCORNER}} - \lineiii{br}{Bottom-right corner}{\constant{ACS_LRCORNER}} -\end{tableiii} -\end{methoddesc} - -\begin{methoddesc}[window]{box}{\optional{vertch, horch}} -Similar to \method{border()}, but both \var{ls} and \var{rs} are -\var{vertch} and both \var{ts} and {bs} are \var{horch}. The default -corner characters are always used by this function. -\end{methoddesc} - -\begin{methoddesc}[window]{chgat}{\optional{y, x, } \optional{num,} attr} -Sets the attributes of \var{num} characters at the current cursor -position, or at position \code{(\var{y}, \var{x})} if supplied. If no -value of \var{num} is given or \var{num} = -1, the attribute will -be set on all the characters to the end of the line. -This function does not move the cursor. The changed line -will be touched using the \method{touchline} method so that the -contents will be redisplayed by the next window refresh. -\end{methoddesc} - -\begin{methoddesc}[window]{clear}{} -Like \method{erase()}, but also causes the whole window to be repainted -upon next call to \method{refresh()}. -\end{methoddesc} - -\begin{methoddesc}[window]{clearok}{yes} -If \var{yes} is 1, the next call to \method{refresh()} -will clear the window completely. -\end{methoddesc} - -\begin{methoddesc}[window]{clrtobot}{} -Erase from cursor to the end of the window: all lines below the cursor -are deleted, and then the equivalent of \method{clrtoeol()} is performed. -\end{methoddesc} - -\begin{methoddesc}[window]{clrtoeol}{} -Erase from cursor to the end of the line. -\end{methoddesc} - -\begin{methoddesc}[window]{cursyncup}{} -Updates the current cursor position of all the ancestors of the window -to reflect the current cursor position of the window. -\end{methoddesc} - -\begin{methoddesc}[window]{delch}{\optional{y, x}} -Delete any character at \code{(\var{y}, \var{x})}. -\end{methoddesc} - -\begin{methoddesc}[window]{deleteln}{} -Delete the line under the cursor. All following lines are moved up -by 1 line. -\end{methoddesc} - -\begin{methoddesc}[window]{derwin}{\optional{nlines, ncols,} begin_y, begin_x} -An abbreviation for ``derive window'', \method{derwin()} is the same -as calling \method{subwin()}, except that \var{begin_y} and -\var{begin_x} are relative to the origin of the window, rather than -relative to the entire screen. Returns a window object for the -derived window. -\end{methoddesc} - -\begin{methoddesc}[window]{echochar}{ch\optional{, attr}} -Add character \var{ch} with attribute \var{attr}, and immediately -call \method{refresh()} on the window. -\end{methoddesc} - -\begin{methoddesc}[window]{enclose}{y, x} -Tests whether the given pair of screen-relative character-cell -coordinates are enclosed by the given window, returning true or -false. It is useful for determining what subset of the screen -windows enclose the location of a mouse event. -\end{methoddesc} - -\begin{methoddesc}[window]{erase}{} -Clear the window. -\end{methoddesc} - -\begin{methoddesc}[window]{getbegyx}{} -Return a tuple \code{(\var{y}, \var{x})} of co-ordinates of upper-left -corner. -\end{methoddesc} - -\begin{methoddesc}[window]{getch}{\optional{y, x}} -Get a character. Note that the integer returned does \emph{not} have to -be in \ASCII{} range: function keys, keypad keys and so on return numbers -higher than 256. In no-delay mode, -1 is returned if there is -no input. -\end{methoddesc} - -\begin{methoddesc}[window]{getkey}{\optional{y, x}} -Get a character, returning a string instead of an integer, as -\method{getch()} does. Function keys, keypad keys and so on return a -multibyte string containing the key name. In no-delay mode, an -exception is raised if there is no input. -\end{methoddesc} - -\begin{methoddesc}[window]{getmaxyx}{} -Return a tuple \code{(\var{y}, \var{x})} of the height and width of -the window. -\end{methoddesc} - -\begin{methoddesc}[window]{getparyx}{} -Returns the beginning coordinates of this window relative to its -parent window into two integer variables y and x. Returns -\code{-1,-1} if this window has no parent. -\end{methoddesc} - -\begin{methoddesc}[window]{getstr}{\optional{y, x}} -Read a string from the user, with primitive line editing capacity. -\end{methoddesc} - -\begin{methoddesc}[window]{getyx}{} -Return a tuple \code{(\var{y}, \var{x})} of current cursor position -relative to the window's upper-left corner. -\end{methoddesc} - -\begin{methoddesc}[window]{hline}{\optional{y, x,} ch, n} -Display a horizontal line starting at \code{(\var{y}, \var{x})} with -length \var{n} consisting of the character \var{ch}. -\end{methoddesc} - -\begin{methoddesc}[window]{idcok}{flag} -If \var{flag} is false, curses no longer considers using the hardware -insert/delete character feature of the terminal; if \var{flag} is -true, use of character insertion and deletion is enabled. When curses -is first initialized, use of character insert/delete is enabled by -default. -\end{methoddesc} - -\begin{methoddesc}[window]{idlok}{yes} -If called with \var{yes} equal to 1, \module{curses} will try and use -hardware line editing facilities. Otherwise, line insertion/deletion -are disabled. -\end{methoddesc} - -\begin{methoddesc}[window]{immedok}{flag} -If \var{flag} is true, any change in the window image -automatically causes the window to be refreshed; you no longer -have to call \method{refresh()} yourself. However, it may -degrade performance considerably, due to repeated calls to -wrefresh. This option is disabled by default. -\end{methoddesc} - -\begin{methoddesc}[window]{inch}{\optional{y, x}} -Return the character at the given position in the window. The bottom -8 bits are the character proper, and upper bits are the attributes. -\end{methoddesc} - -\begin{methoddesc}[window]{insch}{\optional{y, x,} ch\optional{, attr}} -Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes -\var{attr}, moving the line from position \var{x} right by one -character. -\end{methoddesc} - -\begin{methoddesc}[window]{insdelln}{nlines} -Inserts \var{nlines} lines into the specified window above the current -line. The \var{nlines} bottom lines are lost. For negative -\var{nlines}, delete \var{nlines} lines starting with the one under -the cursor, and move the remaining lines up. The bottom \var{nlines} -lines are cleared. The current cursor position remains the same. -\end{methoddesc} - -\begin{methoddesc}[window]{insertln}{} -Insert a blank line under the cursor. All following lines are moved -down by 1 line. -\end{methoddesc} - -\begin{methoddesc}[window]{insnstr}{\optional{y, x,} str, n \optional{, attr}} -Insert a character string (as many characters as will fit on the line) -before the character under the cursor, up to \var{n} characters. -If \var{n} is zero or negative, -the entire string is inserted. -All characters to the right of -the cursor are shifted right, with the rightmost characters on the -line being lost. The cursor position does not change (after moving to -\var{y}, \var{x}, if specified). -\end{methoddesc} - -\begin{methoddesc}[window]{insstr}{\optional{y, x, } str \optional{, attr}} -Insert a character string (as many characters as will fit on the line) -before the character under the cursor. All characters to the right of -the cursor are shifted right, with the rightmost characters on the -line being lost. The cursor position does not change (after moving to -\var{y}, \var{x}, if specified). -\end{methoddesc} - -\begin{methoddesc}[window]{instr}{\optional{y, x} \optional{, n}} -Returns a string of characters, extracted from the window starting at -the current cursor position, or at \var{y}, \var{x} if specified. -Attributes are stripped from the characters. If \var{n} is specified, -\method{instr()} returns return a string at most \var{n} characters -long (exclusive of the trailing NUL). -\end{methoddesc} - -\begin{methoddesc}[window]{is_linetouched}{\var{line}} -Returns true if the specified line was modified since the last call to -\method{refresh()}; otherwise returns false. Raises a -\exception{curses.error} exception if \var{line} is not valid -for the given window. -\end{methoddesc} - -\begin{methoddesc}[window]{is_wintouched}{} -Returns true if the specified window was modified since the last call to -\method{refresh()}; otherwise returns false. -\end{methoddesc} - -\begin{methoddesc}[window]{keypad}{yes} -If \var{yes} is 1, escape sequences generated by some keys (keypad, -function keys) will be interpreted by \module{curses}. -If \var{yes} is 0, escape sequences will be left as is in the input -stream. -\end{methoddesc} - -\begin{methoddesc}[window]{leaveok}{yes} -If \var{yes} is 1, cursor is left where it is on update, instead of -being at ``cursor position.'' This reduces cursor movement where -possible. If possible the cursor will be made invisible. - -If \var{yes} is 0, cursor will always be at ``cursor position'' after -an update. -\end{methoddesc} - -\begin{methoddesc}[window]{move}{new_y, new_x} -Move cursor to \code{(\var{new_y}, \var{new_x})}. -\end{methoddesc} - -\begin{methoddesc}[window]{mvderwin}{y, x} -Moves the window inside its parent window. The screen-relative -parameters of the window are not changed. This routine is used to -display different parts of the parent window at the same physical -position on the screen. -\end{methoddesc} - -\begin{methoddesc}[window]{mvwin}{new_y, new_x} -Move the window so its upper-left corner is at -\code{(\var{new_y}, \var{new_x})}. -\end{methoddesc} - -\begin{methoddesc}[window]{nodelay}{yes} -If \var{yes} is \code{1}, \method{getch()} will be non-blocking. -\end{methoddesc} - -\begin{methoddesc}[window]{notimeout}{yes} -If \var{yes} is \code{1}, escape sequences will not be timed out. - -If \var{yes} is \code{0}, after a few milliseconds, an escape sequence -will not be interpreted, and will be left in the input stream as is. -\end{methoddesc} - -\begin{methoddesc}[window]{noutrefresh}{} -Mark for refresh but wait. This function updates the data structure -representing the desired state of the window, but does not force -an update of the physical screen. To accomplish that, call -\function{doupdate()}. -\end{methoddesc} - -\begin{methoddesc}[window]{overlay}{destwin\optional{, sminrow, smincol, - dminrow, dmincol, dmaxrow, dmaxcol}} -Overlay the window on top of \var{destwin}. The windows need not be -the same size, only the overlapping region is copied. This copy is -non-destructive, which means that the current background character -does not overwrite the old contents of \var{destwin}. - -To get fine-grained control over the copied region, the second form -of \method{overlay()} can be used. \var{sminrow} and \var{smincol} are -the upper-left coordinates of the source window, and the other variables -mark a rectangle in the destination window. -\end{methoddesc} - -\begin{methoddesc}[window]{overwrite}{destwin\optional{, sminrow, smincol, - dminrow, dmincol, dmaxrow, dmaxcol}} -Overwrite the window on top of \var{destwin}. The windows need not be -the same size, in which case only the overlapping region is -copied. This copy is destructive, which means that the current -background character overwrites the old contents of \var{destwin}. - -To get fine-grained control over the copied region, the second form -of \method{overwrite()} can be used. \var{sminrow} and \var{smincol} are -the upper-left coordinates of the source window, the other variables -mark a rectangle in the destination window. -\end{methoddesc} - -\begin{methoddesc}[window]{putwin}{file} -Writes all data associated with the window into the provided file -object. This information can be later retrieved using the -\function{getwin()} function. -\end{methoddesc} - -\begin{methoddesc}[window]{redrawln}{beg, num} -Indicates that the \var{num} screen lines, starting at line \var{beg}, -are corrupted and should be completely redrawn on the next -\method{refresh()} call. -\end{methoddesc} - -\begin{methoddesc}[window]{redrawwin}{} -Touches the entire window, causing it to be completely redrawn on the -next \method{refresh()} call. -\end{methoddesc} - -\begin{methoddesc}[window]{refresh}{\optional{pminrow, pmincol, sminrow, - smincol, smaxrow, smaxcol}} -Update the display immediately (sync actual screen with previous -drawing/deleting methods). - -The 6 optional arguments can only be specified when the window is a -pad created with \function{newpad()}. The additional parameters are -needed to indicate what part of the pad and screen are involved. -\var{pminrow} and \var{pmincol} specify the upper left-hand corner of the -rectangle to be displayed in the pad. \var{sminrow}, \var{smincol}, -\var{smaxrow}, and \var{smaxcol} specify the edges of the rectangle to -be displayed on the screen. The lower right-hand corner of the -rectangle to be displayed in the pad is calculated from the screen -coordinates, since the rectangles must be the same size. Both -rectangles must be entirely contained within their respective -structures. Negative values of \var{pminrow}, \var{pmincol}, -\var{sminrow}, or \var{smincol} are treated as if they were zero. -\end{methoddesc} - -\begin{methoddesc}[window]{scroll}{\optional{lines\code{ = 1}}} -Scroll the screen or scrolling region upward by \var{lines} lines. -\end{methoddesc} - -\begin{methoddesc}[window]{scrollok}{flag} -Controls what happens when the cursor of a window is moved off the -edge of the window or scrolling region, either as a result of a -newline action on the bottom line, or typing the last character -of the last line. If \var{flag} is false, the cursor is left -on the bottom line. If \var{flag} is true, the window is -scrolled up one line. Note that in order to get the physical -scrolling effect on the terminal, it is also necessary to call -\method{idlok()}. -\end{methoddesc} - -\begin{methoddesc}[window]{setscrreg}{top, bottom} -Set the scrolling region from line \var{top} to line \var{bottom}. All -scrolling actions will take place in this region. -\end{methoddesc} - -\begin{methoddesc}[window]{standend}{} -Turn off the standout attribute. On some terminals this has the -side effect of turning off all attributes. -\end{methoddesc} - -\begin{methoddesc}[window]{standout}{} -Turn on attribute \var{A_STANDOUT}. -\end{methoddesc} - -\begin{methoddesc}[window]{subpad}{\optional{nlines, ncols,} begin_y, begin_x} -Return a sub-window, whose upper-left corner is at -\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is -\var{ncols}/\var{nlines}. -\end{methoddesc} - -\begin{methoddesc}[window]{subwin}{\optional{nlines, ncols,} begin_y, begin_x} -Return a sub-window, whose upper-left corner is at -\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is -\var{ncols}/\var{nlines}. - -By default, the sub-window will extend from the -specified position to the lower right corner of the window. -\end{methoddesc} - -\begin{methoddesc}[window]{syncdown}{} -Touches each location in the window that has been touched in any of -its ancestor windows. This routine is called by \method{refresh()}, -so it should almost never be necessary to call it manually. -\end{methoddesc} - -\begin{methoddesc}[window]{syncok}{flag} -If called with \var{flag} set to true, then \method{syncup()} is -called automatically whenever there is a change in the window. -\end{methoddesc} - -\begin{methoddesc}[window]{syncup}{} -Touches all locations in ancestors of the window that have been changed in -the window. -\end{methoddesc} - -\begin{methoddesc}[window]{timeout}{delay} -Sets blocking or non-blocking read behavior for the window. If -\var{delay} is negative, blocking read is used (which will wait -indefinitely for input). If \var{delay} is zero, then non-blocking -read is used, and -1 will be returned by \method{getch()} if no input -is waiting. If \var{delay} is positive, then \method{getch()} will -block for \var{delay} milliseconds, and return -1 if there is still no -input at the end of that time. -\end{methoddesc} - -\begin{methoddesc}[window]{touchline}{start, count\optional{, changed}} -Pretend \var{count} lines have been changed, starting with line -\var{start}. If \var{changed} is supplied, it specifies -whether the affected lines are marked as -having been changed (\var{changed}=1) or unchanged (\var{changed}=0). -\end{methoddesc} - -\begin{methoddesc}[window]{touchwin}{} -Pretend the whole window has been changed, for purposes of drawing -optimizations. -\end{methoddesc} - -\begin{methoddesc}[window]{untouchwin}{} -Marks all lines in the window as unchanged since the last call to -\method{refresh()}. -\end{methoddesc} - -\begin{methoddesc}[window]{vline}{\optional{y, x,} ch, n} -Display a vertical line starting at \code{(\var{y}, \var{x})} with -length \var{n} consisting of the character \var{ch}. -\end{methoddesc} - -\subsection{Constants} - -The \module{curses} module defines the following data members: - -\begin{datadesc}{ERR} -Some curses routines that return an integer, such as -\function{getch()}, return \constant{ERR} upon failure. -\end{datadesc} - -\begin{datadesc}{OK} -Some curses routines that return an integer, such as -\function{napms()}, return \constant{OK} upon success. -\end{datadesc} - -\begin{datadesc}{version} -A string representing the current version of the module. -Also available as \constant{__version__}. -\end{datadesc} - -Several constants are available to specify character cell attributes: - -\begin{tableii}{l|l}{code}{Attribute}{Meaning} - \lineii{A_ALTCHARSET}{Alternate character set mode.} - \lineii{A_BLINK}{Blink mode.} - \lineii{A_BOLD}{Bold mode.} - \lineii{A_DIM}{Dim mode.} - \lineii{A_NORMAL}{Normal attribute.} - \lineii{A_STANDOUT}{Standout mode.} - \lineii{A_UNDERLINE}{Underline mode.} -\end{tableii} - -Keys are referred to by integer constants with names starting with -\samp{KEY_}. The exact keycaps available are system dependent. - -% XXX this table is far too large! -% XXX should this table be alphabetized? - -\begin{longtableii}{l|l}{code}{Key constant}{Key} - \lineii{KEY_MIN}{Minimum key value} - \lineii{KEY_BREAK}{ Break key (unreliable) } - \lineii{KEY_DOWN}{ Down-arrow } - \lineii{KEY_UP}{ Up-arrow } - \lineii{KEY_LEFT}{ Left-arrow } - \lineii{KEY_RIGHT}{ Right-arrow } - \lineii{KEY_HOME}{ Home key (upward+left arrow) } - \lineii{KEY_BACKSPACE}{ Backspace (unreliable) } - \lineii{KEY_F0}{ Function keys. Up to 64 function keys are supported. } - \lineii{KEY_F\var{n}}{ Value of function key \var{n} } - \lineii{KEY_DL}{ Delete line } - \lineii{KEY_IL}{ Insert line } - \lineii{KEY_DC}{ Delete character } - \lineii{KEY_IC}{ Insert char or enter insert mode } - \lineii{KEY_EIC}{ Exit insert char mode } - \lineii{KEY_CLEAR}{ Clear screen } - \lineii{KEY_EOS}{ Clear to end of screen } - \lineii{KEY_EOL}{ Clear to end of line } - \lineii{KEY_SF}{ Scroll 1 line forward } - \lineii{KEY_SR}{ Scroll 1 line backward (reverse) } - \lineii{KEY_NPAGE}{ Next page } - \lineii{KEY_PPAGE}{ Previous page } - \lineii{KEY_STAB}{ Set tab } - \lineii{KEY_CTAB}{ Clear tab } - \lineii{KEY_CATAB}{ Clear all tabs } - \lineii{KEY_ENTER}{ Enter or send (unreliable) } - \lineii{KEY_SRESET}{ Soft (partial) reset (unreliable) } - \lineii{KEY_RESET}{ Reset or hard reset (unreliable) } - \lineii{KEY_PRINT}{ Print } - \lineii{KEY_LL}{ Home down or bottom (lower left) } - \lineii{KEY_A1}{ Upper left of keypad } - \lineii{KEY_A3}{ Upper right of keypad } - \lineii{KEY_B2}{ Center of keypad } - \lineii{KEY_C1}{ Lower left of keypad } - \lineii{KEY_C3}{ Lower right of keypad } - \lineii{KEY_BTAB}{ Back tab } - \lineii{KEY_BEG}{ Beg (beginning) } - \lineii{KEY_CANCEL}{ Cancel } - \lineii{KEY_CLOSE}{ Close } - \lineii{KEY_COMMAND}{ Cmd (command) } - \lineii{KEY_COPY}{ Copy } - \lineii{KEY_CREATE}{ Create } - \lineii{KEY_END}{ End } - \lineii{KEY_EXIT}{ Exit } - \lineii{KEY_FIND}{ Find } - \lineii{KEY_HELP}{ Help } - \lineii{KEY_MARK}{ Mark } - \lineii{KEY_MESSAGE}{ Message } - \lineii{KEY_MOVE}{ Move } - \lineii{KEY_NEXT}{ Next } - \lineii{KEY_OPEN}{ Open } - \lineii{KEY_OPTIONS}{ Options } - \lineii{KEY_PREVIOUS}{ Prev (previous) } - \lineii{KEY_REDO}{ Redo } - \lineii{KEY_REFERENCE}{ Ref (reference) } - \lineii{KEY_REFRESH}{ Refresh } - \lineii{KEY_REPLACE}{ Replace } - \lineii{KEY_RESTART}{ Restart } - \lineii{KEY_RESUME}{ Resume } - \lineii{KEY_SAVE}{ Save } - \lineii{KEY_SBEG}{ Shifted Beg (beginning) } - \lineii{KEY_SCANCEL}{ Shifted Cancel } - \lineii{KEY_SCOMMAND}{ Shifted Command } - \lineii{KEY_SCOPY}{ Shifted Copy } - \lineii{KEY_SCREATE}{ Shifted Create } - \lineii{KEY_SDC}{ Shifted Delete char } - \lineii{KEY_SDL}{ Shifted Delete line } - \lineii{KEY_SELECT}{ Select } - \lineii{KEY_SEND}{ Shifted End } - \lineii{KEY_SEOL}{ Shifted Clear line } - \lineii{KEY_SEXIT}{ Shifted Dxit } - \lineii{KEY_SFIND}{ Shifted Find } - \lineii{KEY_SHELP}{ Shifted Help } - \lineii{KEY_SHOME}{ Shifted Home } - \lineii{KEY_SIC}{ Shifted Input } - \lineii{KEY_SLEFT}{ Shifted Left arrow } - \lineii{KEY_SMESSAGE}{ Shifted Message } - \lineii{KEY_SMOVE}{ Shifted Move } - \lineii{KEY_SNEXT}{ Shifted Next } - \lineii{KEY_SOPTIONS}{ Shifted Options } - \lineii{KEY_SPREVIOUS}{ Shifted Prev } - \lineii{KEY_SPRINT}{ Shifted Print } - \lineii{KEY_SREDO}{ Shifted Redo } - \lineii{KEY_SREPLACE}{ Shifted Replace } - \lineii{KEY_SRIGHT}{ Shifted Right arrow } - \lineii{KEY_SRSUME}{ Shifted Resume } - \lineii{KEY_SSAVE}{ Shifted Save } - \lineii{KEY_SSUSPEND}{ Shifted Suspend } - \lineii{KEY_SUNDO}{ Shifted Undo } - \lineii{KEY_SUSPEND}{ Suspend } - \lineii{KEY_UNDO}{ Undo } - \lineii{KEY_MOUSE}{ Mouse event has occurred } - \lineii{KEY_RESIZE}{ Terminal resize event } - \lineii{KEY_MAX}{Maximum key value} -\end{longtableii} - -On VT100s and their software emulations, such as X terminal emulators, -there are normally at least four function keys (\constant{KEY_F1}, -\constant{KEY_F2}, \constant{KEY_F3}, \constant{KEY_F4}) available, -and the arrow keys mapped to \constant{KEY_UP}, \constant{KEY_DOWN}, -\constant{KEY_LEFT} and \constant{KEY_RIGHT} in the obvious way. If -your machine has a PC keyboard, it is safe to expect arrow keys and -twelve function keys (older PC keyboards may have only ten function -keys); also, the following keypad mappings are standard: - -\begin{tableii}{l|l}{kbd}{Keycap}{Constant} - \lineii{Insert}{KEY_IC} - \lineii{Delete}{KEY_DC} - \lineii{Home}{KEY_HOME} - \lineii{End}{KEY_END} - \lineii{Page Up}{KEY_NPAGE} - \lineii{Page Down}{KEY_PPAGE} -\end{tableii} - -The following table lists characters from the alternate character set. -These are inherited from the VT100 terminal, and will generally be -available on software emulations such as X terminals. When there -is no graphic available, curses falls back on a crude printable ASCII -approximation. -\note{These are available only after \function{initscr()} has -been called.} - -\begin{longtableii}{l|l}{code}{ACS code}{Meaning} - \lineii{ACS_BBSS}{alternate name for upper right corner} - \lineii{ACS_BLOCK}{solid square block} - \lineii{ACS_BOARD}{board of squares} - \lineii{ACS_BSBS}{alternate name for horizontal line} - \lineii{ACS_BSSB}{alternate name for upper left corner} - \lineii{ACS_BSSS}{alternate name for top tee} - \lineii{ACS_BTEE}{bottom tee} - \lineii{ACS_BULLET}{bullet} - \lineii{ACS_CKBOARD}{checker board (stipple)} - \lineii{ACS_DARROW}{arrow pointing down} - \lineii{ACS_DEGREE}{degree symbol} - \lineii{ACS_DIAMOND}{diamond} - \lineii{ACS_GEQUAL}{greater-than-or-equal-to} - \lineii{ACS_HLINE}{horizontal line} - \lineii{ACS_LANTERN}{lantern symbol} - \lineii{ACS_LARROW}{left arrow} - \lineii{ACS_LEQUAL}{less-than-or-equal-to} - \lineii{ACS_LLCORNER}{lower left-hand corner} - \lineii{ACS_LRCORNER}{lower right-hand corner} - \lineii{ACS_LTEE}{left tee} - \lineii{ACS_NEQUAL}{not-equal sign} - \lineii{ACS_PI}{letter pi} - \lineii{ACS_PLMINUS}{plus-or-minus sign} - \lineii{ACS_PLUS}{big plus sign} - \lineii{ACS_RARROW}{right arrow} - \lineii{ACS_RTEE}{right tee} - \lineii{ACS_S1}{scan line 1} - \lineii{ACS_S3}{scan line 3} - \lineii{ACS_S7}{scan line 7} - \lineii{ACS_S9}{scan line 9} - \lineii{ACS_SBBS}{alternate name for lower right corner} - \lineii{ACS_SBSB}{alternate name for vertical line} - \lineii{ACS_SBSS}{alternate name for right tee} - \lineii{ACS_SSBB}{alternate name for lower left corner} - \lineii{ACS_SSBS}{alternate name for bottom tee} - \lineii{ACS_SSSB}{alternate name for left tee} - \lineii{ACS_SSSS}{alternate name for crossover or big plus} - \lineii{ACS_STERLING}{pound sterling} - \lineii{ACS_TTEE}{top tee} - \lineii{ACS_UARROW}{up arrow} - \lineii{ACS_ULCORNER}{upper left corner} - \lineii{ACS_URCORNER}{upper right corner} - \lineii{ACS_VLINE}{vertical line} -\end{longtableii} - -The following table lists the predefined colors: - -\begin{tableii}{l|l}{code}{Constant}{Color} - \lineii{COLOR_BLACK}{Black} - \lineii{COLOR_BLUE}{Blue} - \lineii{COLOR_CYAN}{Cyan (light greenish blue)} - \lineii{COLOR_GREEN}{Green} - \lineii{COLOR_MAGENTA}{Magenta (purplish red)} - \lineii{COLOR_RED}{Red} - \lineii{COLOR_WHITE}{White} - \lineii{COLOR_YELLOW}{Yellow} -\end{tableii} - -\section{\module{curses.textpad} --- - Text input widget for curses programs} - -\declaremodule{standard}{curses.textpad} -\sectionauthor{Eric Raymond}{esr@thyrsus.com} -\moduleauthor{Eric Raymond}{esr@thyrsus.com} -\modulesynopsis{Emacs-like input editing in a curses window.} -\versionadded{1.6} - -The \module{curses.textpad} module provides a \class{Textbox} class -that handles elementary text editing in a curses window, supporting a -set of keybindings resembling those of Emacs (thus, also of Netscape -Navigator, BBedit 6.x, FrameMaker, and many other programs). The -module also provides a rectangle-drawing function useful for framing -text boxes or for other purposes. - -The module \module{curses.textpad} defines the following function: - -\begin{funcdesc}{rectangle}{win, uly, ulx, lry, lrx} -Draw a rectangle. The first argument must be a window object; the -remaining arguments are coordinates relative to that window. The -second and third arguments are the y and x coordinates of the upper -left hand corner of the rectangle to be drawn; the fourth and fifth -arguments are the y and x coordinates of the lower right hand corner. -The rectangle will be drawn using VT100/IBM PC forms characters on -terminals that make this possible (including xterm and most other -software terminal emulators). Otherwise it will be drawn with ASCII -dashes, vertical bars, and plus signs. -\end{funcdesc} - - -\subsection{Textbox objects \label{curses-textpad-objects}} - -You can instantiate a \class{Textbox} object as follows: - -\begin{classdesc}{Textbox}{win} -Return a textbox widget object. The \var{win} argument should be a -curses \class{WindowObject} in which the textbox is to be contained. -The edit cursor of the textbox is initially located at the upper left -hand corner of the containing window, with coordinates \code{(0, 0)}. -The instance's \member{stripspaces} flag is initially on. -\end{classdesc} - -\class{Textbox} objects have the following methods: - -\begin{methoddesc}{edit}{\optional{validator}} -This is the entry point you will normally use. It accepts editing -keystrokes until one of the termination keystrokes is entered. If -\var{validator} is supplied, it must be a function. It will be called -for each keystroke entered with the keystroke as a parameter; command -dispatch is done on the result. This method returns the window -contents as a string; whether blanks in the window are included is -affected by the \member{stripspaces} member. -\end{methoddesc} - -\begin{methoddesc}{do_command}{ch} -Process a single command keystroke. Here are the supported special -keystrokes: - -\begin{tableii}{l|l}{kbd}{Keystroke}{Action} - \lineii{Control-A}{Go to left edge of window.} - \lineii{Control-B}{Cursor left, wrapping to previous line if appropriate.} - \lineii{Control-D}{Delete character under cursor.} - \lineii{Control-E}{Go to right edge (stripspaces off) or end of line - (stripspaces on).} - \lineii{Control-F}{Cursor right, wrapping to next line when appropriate.} - \lineii{Control-G}{Terminate, returning the window contents.} - \lineii{Control-H}{Delete character backward.} - \lineii{Control-J}{Terminate if the window is 1 line, otherwise - insert newline.} - \lineii{Control-K}{If line is blank, delete it, otherwise clear to - end of line.} - \lineii{Control-L}{Refresh screen.} - \lineii{Control-N}{Cursor down; move down one line.} - \lineii{Control-O}{Insert a blank line at cursor location.} - \lineii{Control-P}{Cursor up; move up one line.} -\end{tableii} - -Move operations do nothing if the cursor is at an edge where the -movement is not possible. The following synonyms are supported where -possible: - -\begin{tableii}{l|l}{constant}{Constant}{Keystroke} - \lineii{KEY_LEFT}{\kbd{Control-B}} - \lineii{KEY_RIGHT}{\kbd{Control-F}} - \lineii{KEY_UP}{\kbd{Control-P}} - \lineii{KEY_DOWN}{\kbd{Control-N}} - \lineii{KEY_BACKSPACE}{\kbd{Control-h}} -\end{tableii} - -All other keystrokes are treated as a command to insert the given -character and move right (with line wrapping). -\end{methoddesc} - -\begin{methoddesc}{gather}{} -This method returns the window contents as a string; whether blanks in -the window are included is affected by the \member{stripspaces} -member. -\end{methoddesc} - -\begin{memberdesc}{stripspaces} -This data member is a flag which controls the interpretation of blanks in -the window. When it is on, trailing blanks on each line are ignored; -any cursor motion that would land the cursor on a trailing blank goes -to the end of that line instead, and trailing blanks are stripped when -the window contents are gathered. -\end{memberdesc} - - -\section{\module{curses.wrapper} --- - Terminal handler for curses programs} - -\declaremodule{standard}{curses.wrapper} -\sectionauthor{Eric Raymond}{esr@thyrsus.com} -\moduleauthor{Eric Raymond}{esr@thyrsus.com} -\modulesynopsis{Terminal configuration wrapper for curses programs.} -\versionadded{1.6} - -This module supplies one function, \function{wrapper()}, which runs -another function which should be the rest of your curses-using -application. If the application raises an exception, -\function{wrapper()} will restore the terminal to a sane state before -re-raising the exception and generating a traceback. - -\begin{funcdesc}{wrapper}{func, \moreargs} -Wrapper function that initializes curses and calls another function, -\var{func}, restoring normal keyboard/screen behavior on error. -The callable object \var{func} is then passed the main window 'stdscr' -as its first argument, followed by any other arguments passed to -\function{wrapper()}. -\end{funcdesc} - -Before calling the hook function, \function{wrapper()} turns on cbreak -mode, turns off echo, enables the terminal keypad, and initializes -colors if the terminal has color support. On exit (whether normally -or by exception) it restores cooked mode, turns on echo, and disables -the terminal keypad. - diff --git a/Doc/lib/libcursespanel.tex b/Doc/lib/libcursespanel.tex deleted file mode 100644 index 14d83e3..0000000 --- a/Doc/lib/libcursespanel.tex +++ /dev/null @@ -1,96 +0,0 @@ -\section{\module{curses.panel} --- - A panel stack extension for curses.} - -\declaremodule{standard}{curses.panel} -\sectionauthor{A.M. Kuchling}{amk@amk.ca} -\modulesynopsis{A panel stack extension that adds depth to - curses windows.} - -Panels are windows with the added feature of depth, so they can be -stacked on top of each other, and only the visible portions of -each window will be displayed. Panels can be added, moved up -or down in the stack, and removed. - -\subsection{Functions \label{cursespanel-functions}} - -The module \module{curses.panel} defines the following functions: - - -\begin{funcdesc}{bottom_panel}{} -Returns the bottom panel in the panel stack. -\end{funcdesc} - -\begin{funcdesc}{new_panel}{win} -Returns a panel object, associating it with the given window \var{win}. -Be aware that you need to keep the returned panel object referenced -explicitly. If you don't, the panel object is garbage collected and -removed from the panel stack. -\end{funcdesc} - -\begin{funcdesc}{top_panel}{} -Returns the top panel in the panel stack. -\end{funcdesc} - -\begin{funcdesc}{update_panels}{} -Updates the virtual screen after changes in the panel stack. This does -not call \function{curses.doupdate()}, so you'll have to do this yourself. -\end{funcdesc} - -\subsection{Panel Objects \label{curses-panel-objects}} - -Panel objects, as returned by \function{new_panel()} above, are windows -with a stacking order. There's always a window associated with a -panel which determines the content, while the panel methods are -responsible for the window's depth in the panel stack. - -Panel objects have the following methods: - -\begin{methoddesc}[Panel]{above}{} -Returns the panel above the current panel. -\end{methoddesc} - -\begin{methoddesc}[Panel]{below}{} -Returns the panel below the current panel. -\end{methoddesc} - -\begin{methoddesc}[Panel]{bottom}{} -Push the panel to the bottom of the stack. -\end{methoddesc} - -\begin{methoddesc}[Panel]{hidden}{} -Returns true if the panel is hidden (not visible), false otherwise. -\end{methoddesc} - -\begin{methoddesc}[Panel]{hide}{} -Hide the panel. This does not delete the object, it just makes the -window on screen invisible. -\end{methoddesc} - -\begin{methoddesc}[Panel]{move}{y, x} -Move the panel to the screen coordinates \code{(\var{y}, \var{x})}. -\end{methoddesc} - -\begin{methoddesc}[Panel]{replace}{win} -Change the window associated with the panel to the window \var{win}. -\end{methoddesc} - -\begin{methoddesc}[Panel]{set_userptr}{obj} -Set the panel's user pointer to \var{obj}. This is used to associate an -arbitrary piece of data with the panel, and can be any Python object. -\end{methoddesc} - -\begin{methoddesc}[Panel]{show}{} -Display the panel (which might have been hidden). -\end{methoddesc} - -\begin{methoddesc}[Panel]{top}{} -Push panel to the top of the stack. -\end{methoddesc} - -\begin{methoddesc}[Panel]{userptr}{} -Returns the user pointer for the panel. This might be any Python object. -\end{methoddesc} - -\begin{methoddesc}[Panel]{window}{} -Returns the window object associated with the panel. -\end{methoddesc} diff --git a/Doc/lib/libdatetime.tex b/Doc/lib/libdatetime.tex deleted file mode 100644 index fb13ea7..0000000 --- a/Doc/lib/libdatetime.tex +++ /dev/null @@ -1,1441 +0,0 @@ -% XXX what order should the types be discussed in? - -\section{\module{datetime} --- - Basic date and time types} - -\declaremodule{builtin}{datetime} -\modulesynopsis{Basic date and time types.} -\moduleauthor{Tim Peters}{tim@zope.com} -\sectionauthor{Tim Peters}{tim@zope.com} -\sectionauthor{A.M. Kuchling}{amk@amk.ca} - -\versionadded{2.3} - - -The \module{datetime} module supplies classes for manipulating dates -and times in both simple and complex ways. While date and time -arithmetic is supported, the focus of the implementation is on -efficient member extraction for output formatting and manipulation. - -There are two kinds of date and time objects: ``naive'' and ``aware''. -This distinction refers to whether the object has any notion of time -zone, daylight saving time, or other kind of algorithmic or political -time adjustment. Whether a naive \class{datetime} object represents -Coordinated Universal Time (UTC), local time, or time in some other -timezone is purely up to the program, just like it's up to the program -whether a particular number represents metres, miles, or mass. Naive -\class{datetime} objects are easy to understand and to work with, at -the cost of ignoring some aspects of reality. - -For applications requiring more, \class{datetime} and \class{time} -objects have an optional time zone information member, -\member{tzinfo}, that can contain an instance of a subclass of -the abstract \class{tzinfo} class. These \class{tzinfo} objects -capture information about the offset from UTC time, the time zone -name, and whether Daylight Saving Time is in effect. Note that no -concrete \class{tzinfo} classes are supplied by the \module{datetime} -module. Supporting timezones at whatever level of detail is required -is up to the application. The rules for time adjustment across the -world are more political than rational, and there is no standard -suitable for every application. - -The \module{datetime} module exports the following constants: - -\begin{datadesc}{MINYEAR} - The smallest year number allowed in a \class{date} or - \class{datetime} object. \constant{MINYEAR} - is \code{1}. -\end{datadesc} - -\begin{datadesc}{MAXYEAR} - The largest year number allowed in a \class{date} or \class{datetime} - object. \constant{MAXYEAR} is \code{9999}. -\end{datadesc} - -\begin{seealso} - \seemodule{calendar}{General calendar related functions.} - \seemodule{time}{Time access and conversions.} -\end{seealso} - -\subsection{Available Types} - -\begin{classdesc*}{date} - An idealized naive date, assuming the current Gregorian calendar - always was, and always will be, in effect. - Attributes: \member{year}, \member{month}, and \member{day}. -\end{classdesc*} - -\begin{classdesc*}{time} - An idealized time, independent of any particular day, assuming - that every day has exactly 24*60*60 seconds (there is no notion - of "leap seconds" here). - Attributes: \member{hour}, \member{minute}, \member{second}, - \member{microsecond}, and \member{tzinfo}. -\end{classdesc*} - -\begin{classdesc*}{datetime} - A combination of a date and a time. - Attributes: \member{year}, \member{month}, \member{day}, - \member{hour}, \member{minute}, \member{second}, - \member{microsecond}, and \member{tzinfo}. -\end{classdesc*} - -\begin{classdesc*}{timedelta} - A duration expressing the difference between two \class{date}, - \class{time}, or \class{datetime} instances to microsecond - resolution. -\end{classdesc*} - -\begin{classdesc*}{tzinfo} - An abstract base class for time zone information objects. These - are used by the \class{datetime} and \class{time} classes to - provide a customizable notion of time adjustment (for example, to - account for time zone and/or daylight saving time). -\end{classdesc*} - -Objects of these types are immutable. - -Objects of the \class{date} type are always naive. - -An object \var{d} of type \class{time} or \class{datetime} may be -naive or aware. \var{d} is aware if \code{\var{d}.tzinfo} is not -\code{None} and \code{\var{d}.tzinfo.utcoffset(\var{d})} does not return -\code{None}. If \code{\var{d}.tzinfo} is \code{None}, or if -\code{\var{d}.tzinfo} is not \code{None} but -\code{\var{d}.tzinfo.utcoffset(\var{d})} returns \code{None}, \var{d} -is naive. - -The distinction between naive and aware doesn't apply to -\class{timedelta} objects. - -Subclass relationships: - -\begin{verbatim} -object - timedelta - tzinfo - time - date - datetime -\end{verbatim} - -\subsection{\class{timedelta} Objects \label{datetime-timedelta}} - -A \class{timedelta} object represents a duration, the difference -between two dates or times. - -\begin{classdesc}{timedelta}{\optional{days\optional{, seconds\optional{, - microseconds\optional{, milliseconds\optional{, - minutes\optional{, hours\optional{, weeks}}}}}}}} - All arguments are optional and default to \code{0}. Arguments may - be ints, longs, or floats, and may be positive or negative. - - Only \var{days}, \var{seconds} and \var{microseconds} are stored - internally. Arguments are converted to those units: - -\begin{itemize} - \item A millisecond is converted to 1000 microseconds. - \item A minute is converted to 60 seconds. - \item An hour is converted to 3600 seconds. - \item A week is converted to 7 days. -\end{itemize} - - and days, seconds and microseconds are then normalized so that the - representation is unique, with - -\begin{itemize} - \item \code{0 <= \var{microseconds} < 1000000} - \item \code{0 <= \var{seconds} < 3600*24} (the number of seconds in one day) - \item \code{-999999999 <= \var{days} <= 999999999} -\end{itemize} - - If any argument is a float and there are fractional microseconds, - the fractional microseconds left over from all arguments are combined - and their sum is rounded to the nearest microsecond. If no - argument is a float, the conversion and normalization processes - are exact (no information is lost). - - If the normalized value of days lies outside the indicated range, - \exception{OverflowError} is raised. - - Note that normalization of negative values may be surprising at first. - For example, - -\begin{verbatim} ->>> d = timedelta(microseconds=-1) ->>> (d.days, d.seconds, d.microseconds) -(-1, 86399, 999999) -\end{verbatim} -\end{classdesc} - -Class attributes are: - -\begin{memberdesc}{min} - The most negative \class{timedelta} object, - \code{timedelta(-999999999)}. -\end{memberdesc} - -\begin{memberdesc}{max} - The most positive \class{timedelta} object, - \code{timedelta(days=999999999, hours=23, minutes=59, seconds=59, - microseconds=999999)}. -\end{memberdesc} - -\begin{memberdesc}{resolution} - The smallest possible difference between non-equal - \class{timedelta} objects, \code{timedelta(microseconds=1)}. -\end{memberdesc} - -Note that, because of normalization, \code{timedelta.max} \textgreater -\code{-timedelta.min}. \code{-timedelta.max} is not representable as -a \class{timedelta} object. - -Instance attributes (read-only): - -\begin{tableii}{c|l}{code}{Attribute}{Value} - \lineii{days}{Between -999999999 and 999999999 inclusive} - \lineii{seconds}{Between 0 and 86399 inclusive} - \lineii{microseconds}{Between 0 and 999999 inclusive} -\end{tableii} - -Supported operations: - -% XXX this table is too wide! -\begin{tableii}{c|l}{code}{Operation}{Result} - \lineii{\var{t1} = \var{t2} + \var{t3}} - {Sum of \var{t2} and \var{t3}. - Afterwards \var{t1}-\var{t2} == \var{t3} and \var{t1}-\var{t3} - == \var{t2} are true. - (1)} - \lineii{\var{t1} = \var{t2} - \var{t3}} - {Difference of \var{t2} and \var{t3}. - Afterwards \var{t1} == \var{t2} - \var{t3} and - \var{t2} == \var{t1} + \var{t3} are true. - (1)} - \lineii{\var{t1} = \var{t2} * \var{i} or \var{t1} = \var{i} * \var{t2}} - {Delta multiplied by an integer or long. - Afterwards \var{t1} // i == \var{t2} is true, - provided \code{i != 0}.} - \lineii{}{In general, \var{t1} * i == \var{t1} * (i-1) + \var{t1} is true. - (1)} - \lineii{\var{t1} = \var{t2} // \var{i}} - {The floor is computed and the remainder (if any) is thrown away. - (3)} - \lineii{+\var{t1}} - {Returns a \class{timedelta} object with the same value. - (2)} - \lineii{-\var{t1}} - {equivalent to \class{timedelta}(-\var{t1.days}, -\var{t1.seconds}, - -\var{t1.microseconds}), and to \var{t1}* -1. - (1)(4)} - \lineii{abs(\var{t})} - {equivalent to +\var{t} when \code{t.days >= 0}, and to - -\var{t} when \code{t.days < 0}. - (2)} -\end{tableii} -\noindent -Notes: - -\begin{description} -\item[(1)] - This is exact, but may overflow. - -\item[(2)] - This is exact, and cannot overflow. - -\item[(3)] - Division by 0 raises \exception{ZeroDivisionError}. - -\item[(4)] - -\var{timedelta.max} is not representable as a \class{timedelta} object. -\end{description} - -In addition to the operations listed above \class{timedelta} objects -support certain additions and subtractions with \class{date} and -\class{datetime} objects (see below). - -Comparisons of \class{timedelta} objects are supported with the -\class{timedelta} object representing the smaller duration considered -to be the smaller timedelta. -In order to stop mixed-type comparisons from falling back to the -default comparison by object address, when a \class{timedelta} object is -compared to an object of a different type, \exception{TypeError} is -raised unless the comparison is \code{==} or \code{!=}. The latter -cases return \constant{False} or \constant{True}, respectively. - -\class{timedelta} objects are hashable (usable as dictionary keys), -support efficient pickling, and in Boolean contexts, a \class{timedelta} -object is considered to be true if and only if it isn't equal to -\code{timedelta(0)}. - - -\subsection{\class{date} Objects \label{datetime-date}} - -A \class{date} object represents a date (year, month and day) in an idealized -calendar, the current Gregorian calendar indefinitely extended in both -directions. January 1 of year 1 is called day number 1, January 2 of year -1 is called day number 2, and so on. This matches the definition of the -"proleptic Gregorian" calendar in Dershowitz and Reingold's book -\citetitle{Calendrical Calculations}, where it's the base calendar for all -computations. See the book for algorithms for converting between -proleptic Gregorian ordinals and many other calendar systems. - -\begin{classdesc}{date}{year, month, day} - All arguments are required. Arguments may be ints or longs, in the - following ranges: - - \begin{itemize} - \item \code{MINYEAR <= \var{year} <= MAXYEAR} - \item \code{1 <= \var{month} <= 12} - \item \code{1 <= \var{day} <= number of days in the given month and year} - \end{itemize} - - If an argument outside those ranges is given, \exception{ValueError} - is raised. -\end{classdesc} - -Other constructors, all class methods: - -\begin{methoddesc}{today}{} - Return the current local date. This is equivalent to - \code{date.fromtimestamp(time.time())}. -\end{methoddesc} - -\begin{methoddesc}{fromtimestamp}{timestamp} - Return the local date corresponding to the POSIX timestamp, such - as is returned by \function{time.time()}. This may raise - \exception{ValueError}, if the timestamp is out of the range of - values supported by the platform C \cfunction{localtime()} - function. It's common for this to be restricted to years from 1970 - through 2038. Note that on non-POSIX systems that include leap - seconds in their notion of a timestamp, leap seconds are ignored by - \method{fromtimestamp()}. -\end{methoddesc} - -\begin{methoddesc}{fromordinal}{ordinal} - Return the date corresponding to the proleptic Gregorian ordinal, - where January 1 of year 1 has ordinal 1. \exception{ValueError} is - raised unless \code{1 <= \var{ordinal} <= date.max.toordinal()}. - For any date \var{d}, \code{date.fromordinal(\var{d}.toordinal()) == - \var{d}}. -\end{methoddesc} - -Class attributes: - -\begin{memberdesc}{min} - The earliest representable date, \code{date(MINYEAR, 1, 1)}. -\end{memberdesc} - -\begin{memberdesc}{max} - The latest representable date, \code{date(MAXYEAR, 12, 31)}. -\end{memberdesc} - -\begin{memberdesc}{resolution} - The smallest possible difference between non-equal date - objects, \code{timedelta(days=1)}. -\end{memberdesc} - -Instance attributes (read-only): - -\begin{memberdesc}{year} - Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive. -\end{memberdesc} - -\begin{memberdesc}{month} - Between 1 and 12 inclusive. -\end{memberdesc} - -\begin{memberdesc}{day} - Between 1 and the number of days in the given month of the given - year. -\end{memberdesc} - -Supported operations: - -\begin{tableii}{c|l}{code}{Operation}{Result} - \lineii{\var{date2} = \var{date1} + \var{timedelta}} - {\var{date2} is \code{\var{timedelta}.days} days removed from - \var{date1}. (1)} - - - \lineii{\var{date2} = \var{date1} - \var{timedelta}} - {Computes \var{date2} such that \code{\var{date2} + \var{timedelta} - == \var{date1}}. (2)} - - \lineii{\var{timedelta} = \var{date1} - \var{date2}} - {(3)} - - \lineii{\var{date1} < \var{date2}} - {\var{date1} is considered less than \var{date2} when \var{date1} - precedes \var{date2} in time. (4)} - -\end{tableii} - -Notes: -\begin{description} - -\item[(1)] - \var{date2} is moved forward in time if \code{\var{timedelta}.days - > 0}, or backward if \code{\var{timedelta}.days < 0}. Afterward - \code{\var{date2} - \var{date1} == \var{timedelta}.days}. - \code{\var{timedelta}.seconds} and - \code{\var{timedelta}.microseconds} are ignored. - \exception{OverflowError} is raised if \code{\var{date2}.year} - would be smaller than \constant{MINYEAR} or larger than - \constant{MAXYEAR}. - -\item[(2)] - This isn't quite equivalent to date1 + - (-timedelta), because -timedelta in isolation can overflow in cases - where date1 - timedelta does not. \code{\var{timedelta}.seconds} - and \code{\var{timedelta}.microseconds} are ignored. - -\item[(3)] -This is exact, and cannot overflow. timedelta.seconds and - timedelta.microseconds are 0, and date2 + timedelta == date1 - after. - -\item[(4)] -In other words, \code{date1 < date2} - if and only if \code{\var{date1}.toordinal() < - \var{date2}.toordinal()}. -In order to stop comparison from falling back to the default -scheme of comparing object addresses, date comparison -normally raises \exception{TypeError} if the other comparand -isn't also a \class{date} object. However, \code{NotImplemented} -is returned instead if the other comparand has a -\method{timetuple} attribute. This hook gives other kinds of -date objects a chance at implementing mixed-type comparison. -If not, when a \class{date} object is -compared to an object of a different type, \exception{TypeError} is -raised unless the comparison is \code{==} or \code{!=}. The latter -cases return \constant{False} or \constant{True}, respectively. - -\end{description} - - -Dates can be used as dictionary keys. In Boolean contexts, all -\class{date} objects are considered to be true. - -Instance methods: - -\begin{methoddesc}{replace}{year, month, day} - Return a date with the same value, except for those members given - new values by whichever keyword arguments are specified. For - example, if \code{d == date(2002, 12, 31)}, then - \code{d.replace(day=26) == date(2002, 12, 26)}. -\end{methoddesc} - -\begin{methoddesc}{timetuple}{} - Return a \class{time.struct_time} such as returned by - \function{time.localtime()}. The hours, minutes and seconds are - 0, and the DST flag is -1. - \code{\var{d}.timetuple()} is equivalent to - \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day, - 0, 0, 0, - \var{d}.weekday(), - \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1, - -1))} -\end{methoddesc} - -\begin{methoddesc}{toordinal}{} - Return the proleptic Gregorian ordinal of the date, where January 1 - of year 1 has ordinal 1. For any \class{date} object \var{d}, - \code{date.fromordinal(\var{d}.toordinal()) == \var{d}}. -\end{methoddesc} - -\begin{methoddesc}{weekday}{} - Return the day of the week as an integer, where Monday is 0 and - Sunday is 6. For example, \code{date(2002, 12, 4).weekday() == 2}, a - Wednesday. - See also \method{isoweekday()}. -\end{methoddesc} - -\begin{methoddesc}{isoweekday}{} - Return the day of the week as an integer, where Monday is 1 and - Sunday is 7. For example, \code{date(2002, 12, 4).isoweekday() == 3}, a - Wednesday. - See also \method{weekday()}, \method{isocalendar()}. -\end{methoddesc} - -\begin{methoddesc}{isocalendar}{} - Return a 3-tuple, (ISO year, ISO week number, ISO weekday). - - The ISO calendar is a widely used variant of the Gregorian calendar. - See \url{http://www.phys.uu.nl/~vgent/calendar/isocalendar.htm} - for a good explanation. - - The ISO year consists of 52 or 53 full weeks, and where a week starts - on a Monday and ends on a Sunday. The first week of an ISO year is - the first (Gregorian) calendar week of a year containing a Thursday. - This is called week number 1, and the ISO year of that Thursday is - the same as its Gregorian year. - - For example, 2004 begins on a Thursday, so the first week of ISO - year 2004 begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan - 2004, so that - \code{date(2003, 12, 29).isocalendar() == (2004, 1, 1)} - and - \code{date(2004, 1, 4).isocalendar() == (2004, 1, 7)}. -\end{methoddesc} - -\begin{methoddesc}{isoformat}{} - Return a string representing the date in ISO 8601 format, - 'YYYY-MM-DD'. For example, - \code{date(2002, 12, 4).isoformat() == '2002-12-04'}. -\end{methoddesc} - -\begin{methoddesc}{__str__}{} - For a date \var{d}, \code{str(\var{d})} is equivalent to - \code{\var{d}.isoformat()}. -\end{methoddesc} - -\begin{methoddesc}{ctime}{} - Return a string representing the date, for example - date(2002, 12, 4).ctime() == 'Wed Dec 4 00:00:00 2002'. - \code{\var{d}.ctime()} is equivalent to - \code{time.ctime(time.mktime(\var{d}.timetuple()))} - on platforms where the native C \cfunction{ctime()} function - (which \function{time.ctime()} invokes, but which - \method{date.ctime()} does not invoke) conforms to the C standard. -\end{methoddesc} - -\begin{methoddesc}{strftime}{format} - Return a string representing the date, controlled by an explicit - format string. Format codes referring to hours, minutes or seconds - will see 0 values. - See section~\ref{strftime-behavior} -- \method{strftime()} behavior. -\end{methoddesc} - - -\subsection{\class{datetime} Objects \label{datetime-datetime}} - -A \class{datetime} object is a single object containing all the -information from a \class{date} object and a \class{time} object. Like a -\class{date} object, \class{datetime} assumes the current Gregorian -calendar extended in both directions; like a time object, -\class{datetime} assumes there are exactly 3600*24 seconds in every -day. - -Constructor: - -\begin{classdesc}{datetime}{year, month, day\optional{, - hour\optional{, minute\optional{, - second\optional{, microsecond\optional{, - tzinfo}}}}}} - The year, month and day arguments are required. \var{tzinfo} may - be \code{None}, or an instance of a \class{tzinfo} subclass. The - remaining arguments may be ints or longs, in the following ranges: - - \begin{itemize} - \item \code{MINYEAR <= \var{year} <= MAXYEAR} - \item \code{1 <= \var{month} <= 12} - \item \code{1 <= \var{day} <= number of days in the given month and year} - \item \code{0 <= \var{hour} < 24} - \item \code{0 <= \var{minute} < 60} - \item \code{0 <= \var{second} < 60} - \item \code{0 <= \var{microsecond} < 1000000} - \end{itemize} - - If an argument outside those ranges is given, - \exception{ValueError} is raised. -\end{classdesc} - -Other constructors, all class methods: - -\begin{methoddesc}{today}{} - Return the current local datetime, with \member{tzinfo} \code{None}. - This is equivalent to - \code{datetime.fromtimestamp(time.time())}. - See also \method{now()}, \method{fromtimestamp()}. -\end{methoddesc} - -\begin{methoddesc}{now}{\optional{tz}} - Return the current local date and time. If optional argument - \var{tz} is \code{None} or not specified, this is like - \method{today()}, but, if possible, supplies more precision than can - be gotten from going through a \function{time.time()} timestamp (for - example, this may be possible on platforms supplying the C - \cfunction{gettimeofday()} function). - - Else \var{tz} must be an instance of a class \class{tzinfo} subclass, - and the current date and time are converted to \var{tz}'s time - zone. In this case the result is equivalent to - \code{\var{tz}.fromutc(datetime.utcnow().replace(tzinfo=\var{tz}))}. - See also \method{today()}, \method{utcnow()}. -\end{methoddesc} - -\begin{methoddesc}{utcnow}{} - Return the current UTC date and time, with \member{tzinfo} \code{None}. - This is like \method{now()}, but returns the current UTC date and time, - as a naive \class{datetime} object. - See also \method{now()}. -\end{methoddesc} - -\begin{methoddesc}{fromtimestamp}{timestamp\optional{, tz}} - Return the local date and time corresponding to the \POSIX{} - timestamp, such as is returned by \function{time.time()}. - If optional argument \var{tz} is \code{None} or not specified, the - timestamp is converted to the platform's local date and time, and - the returned \class{datetime} object is naive. - - Else \var{tz} must be an instance of a class \class{tzinfo} subclass, - and the timestamp is converted to \var{tz}'s time zone. In this case - the result is equivalent to - \code{\var{tz}.fromutc(datetime.utcfromtimestamp(\var{timestamp}).replace(tzinfo=\var{tz}))}. - - \method{fromtimestamp()} may raise \exception{ValueError}, if the - timestamp is out of the range of values supported by the platform C - \cfunction{localtime()} or \cfunction{gmtime()} functions. It's common - for this to be restricted to years in 1970 through 2038. - Note that on non-POSIX systems that include leap seconds in their - notion of a timestamp, leap seconds are ignored by - \method{fromtimestamp()}, and then it's possible to have two timestamps - differing by a second that yield identical \class{datetime} objects. - See also \method{utcfromtimestamp()}. -\end{methoddesc} - -\begin{methoddesc}{utcfromtimestamp}{timestamp} - Return the UTC \class{datetime} corresponding to the \POSIX{} - timestamp, with \member{tzinfo} \code{None}. - This may raise \exception{ValueError}, if the - timestamp is out of the range of values supported by the platform - C \cfunction{gmtime()} function. It's common for this to be - restricted to years in 1970 through 2038. - See also \method{fromtimestamp()}. -\end{methoddesc} - -\begin{methoddesc}{fromordinal}{ordinal} - Return the \class{datetime} corresponding to the proleptic - Gregorian ordinal, where January 1 of year 1 has ordinal 1. - \exception{ValueError} is raised unless \code{1 <= ordinal <= - datetime.max.toordinal()}. The hour, minute, second and - microsecond of the result are all 0, - and \member{tzinfo} is \code{None}. -\end{methoddesc} - -\begin{methoddesc}{combine}{date, time} - Return a new \class{datetime} object whose date members are - equal to the given \class{date} object's, and whose time - and \member{tzinfo} members are equal to the given \class{time} object's. - For any \class{datetime} object \var{d}, \code{\var{d} == - datetime.combine(\var{d}.date(), \var{d}.timetz())}. If date is a - \class{datetime} object, its time and \member{tzinfo} members are - ignored. - \end{methoddesc} - -\begin{methoddesc}{strptime}{date_string, format} - Return a \class{datetime} corresponding to \var{date_string}, parsed - according to \var{format}. This is equivalent to - \code{datetime(*(time.strptime(date_string, - format)[0:6]))}. \exception{ValueError} is raised if the date_string and - format can't be parsed by \function{time.strptime()} or if it returns a - value which isn't a time tuple. - - \versionadded{2.5} -\end{methoddesc} - -Class attributes: - -\begin{memberdesc}{min} - The earliest representable \class{datetime}, - \code{datetime(MINYEAR, 1, 1, tzinfo=None)}. -\end{memberdesc} - -\begin{memberdesc}{max} - The latest representable \class{datetime}, - \code{datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None)}. -\end{memberdesc} - -\begin{memberdesc}{resolution} - The smallest possible difference between non-equal \class{datetime} - objects, \code{timedelta(microseconds=1)}. -\end{memberdesc} - -Instance attributes (read-only): - -\begin{memberdesc}{year} - Between \constant{MINYEAR} and \constant{MAXYEAR} inclusive. -\end{memberdesc} - -\begin{memberdesc}{month} - Between 1 and 12 inclusive. -\end{memberdesc} - -\begin{memberdesc}{day} - Between 1 and the number of days in the given month of the given - year. -\end{memberdesc} - -\begin{memberdesc}{hour} - In \code{range(24)}. -\end{memberdesc} - -\begin{memberdesc}{minute} - In \code{range(60)}. -\end{memberdesc} - -\begin{memberdesc}{second} - In \code{range(60)}. -\end{memberdesc} - -\begin{memberdesc}{microsecond} - In \code{range(1000000)}. -\end{memberdesc} - -\begin{memberdesc}{tzinfo} - The object passed as the \var{tzinfo} argument to the - \class{datetime} constructor, or \code{None} if none was passed. -\end{memberdesc} - -Supported operations: - -\begin{tableii}{c|l}{code}{Operation}{Result} - \lineii{\var{datetime2} = \var{datetime1} + \var{timedelta}}{(1)} - - \lineii{\var{datetime2} = \var{datetime1} - \var{timedelta}}{(2)} - - \lineii{\var{timedelta} = \var{datetime1} - \var{datetime2}}{(3)} - - \lineii{\var{datetime1} < \var{datetime2}} - {Compares \class{datetime} to \class{datetime}. - (4)} - -\end{tableii} - -\begin{description} - -\item[(1)] - - datetime2 is a duration of timedelta removed from datetime1, moving - forward in time if \code{\var{timedelta}.days} > 0, or backward if - \code{\var{timedelta}.days} < 0. The result has the same \member{tzinfo} member - as the input datetime, and datetime2 - datetime1 == timedelta after. - \exception{OverflowError} is raised if datetime2.year would be - smaller than \constant{MINYEAR} or larger than \constant{MAXYEAR}. - Note that no time zone adjustments are done even if the input is an - aware object. - -\item[(2)] - Computes the datetime2 such that datetime2 + timedelta == datetime1. - As for addition, the result has the same \member{tzinfo} member - as the input datetime, and no time zone adjustments are done even - if the input is aware. - This isn't quite equivalent to datetime1 + (-timedelta), because - -timedelta in isolation can overflow in cases where - datetime1 - timedelta does not. - -\item[(3)] - Subtraction of a \class{datetime} from a - \class{datetime} is defined only if both - operands are naive, or if both are aware. If one is aware and the - other is naive, \exception{TypeError} is raised. - - If both are naive, or both are aware and have the same \member{tzinfo} - member, the \member{tzinfo} members are ignored, and the result is - a \class{timedelta} object \var{t} such that - \code{\var{datetime2} + \var{t} == \var{datetime1}}. No time zone - adjustments are done in this case. - - If both are aware and have different \member{tzinfo} members, - \code{a-b} acts as if \var{a} and \var{b} were first converted to - naive UTC datetimes first. The result is - \code{(\var{a}.replace(tzinfo=None) - \var{a}.utcoffset()) - - (\var{b}.replace(tzinfo=None) - \var{b}.utcoffset())} - except that the implementation never overflows. - -\item[(4)] - -\var{datetime1} is considered less than \var{datetime2} -when \var{datetime1} precedes \var{datetime2} in time. - -If one comparand is naive and -the other is aware, \exception{TypeError} is raised. If both - comparands are aware, and have the same \member{tzinfo} member, - the common \member{tzinfo} member is ignored and the base datetimes - are compared. If both comparands are aware and have different - \member{tzinfo} members, the comparands are first adjusted by - subtracting their UTC offsets (obtained from \code{self.utcoffset()}). - \note{In order to stop comparison from falling back to the default - scheme of comparing object addresses, datetime comparison - normally raises \exception{TypeError} if the other comparand - isn't also a \class{datetime} object. However, - \code{NotImplemented} is returned instead if the other comparand - has a \method{timetuple} attribute. This hook gives other - kinds of date objects a chance at implementing mixed-type - comparison. If not, when a \class{datetime} object is - compared to an object of a different type, \exception{TypeError} - is raised unless the comparison is \code{==} or \code{!=}. The - latter cases return \constant{False} or \constant{True}, - respectively.} - -\end{description} - -\class{datetime} objects can be used as dictionary keys. In Boolean -contexts, all \class{datetime} objects are considered to be true. - - -Instance methods: - -\begin{methoddesc}{date}{} - Return \class{date} object with same year, month and day. -\end{methoddesc} - -\begin{methoddesc}{time}{} - Return \class{time} object with same hour, minute, second and microsecond. - \member{tzinfo} is \code{None}. See also method \method{timetz()}. -\end{methoddesc} - -\begin{methoddesc}{timetz}{} - Return \class{time} object with same hour, minute, second, microsecond, - and tzinfo members. See also method \method{time()}. -\end{methoddesc} - -\begin{methoddesc}{replace}{\optional{year\optional{, month\optional{, - day\optional{, hour\optional{, minute\optional{, - second\optional{, microsecond\optional{, - tzinfo}}}}}}}}} - Return a datetime with the same members, except for those members given - new values by whichever keyword arguments are specified. Note that - \code{tzinfo=None} can be specified to create a naive datetime from - an aware datetime with no conversion of date and time members. -\end{methoddesc} - -\begin{methoddesc}{astimezone}{tz} - Return a \class{datetime} object with new \member{tzinfo} member - \var{tz}, adjusting the date and time members so the result is the - same UTC time as \var{self}, but in \var{tz}'s local time. - - \var{tz} must be an instance of a \class{tzinfo} subclass, and its - \method{utcoffset()} and \method{dst()} methods must not return - \code{None}. \var{self} must be aware (\code{\var{self}.tzinfo} must - not be \code{None}, and \code{\var{self}.utcoffset()} must not return - \code{None}). - - If \code{\var{self}.tzinfo} is \var{tz}, - \code{\var{self}.astimezone(\var{tz})} is equal to \var{self}: no - adjustment of date or time members is performed. - Else the result is local time in time zone \var{tz}, representing the - same UTC time as \var{self}: after \code{\var{astz} = - \var{dt}.astimezone(\var{tz})}, - \code{\var{astz} - \var{astz}.utcoffset()} will usually have the same - date and time members as \code{\var{dt} - \var{dt}.utcoffset()}. - The discussion of class \class{tzinfo} explains the cases at Daylight - Saving Time transition boundaries where this cannot be achieved (an issue - only if \var{tz} models both standard and daylight time). - - If you merely want to attach a time zone object \var{tz} to a - datetime \var{dt} without adjustment of date and time members, - use \code{\var{dt}.replace(tzinfo=\var{tz})}. If - you merely want to remove the time zone object from an aware datetime - \var{dt} without conversion of date and time members, use - \code{\var{dt}.replace(tzinfo=None)}. - - Note that the default \method{tzinfo.fromutc()} method can be overridden - in a \class{tzinfo} subclass to affect the result returned by - \method{astimezone()}. Ignoring error cases, \method{astimezone()} - acts like: - - \begin{verbatim} - def astimezone(self, tz): - if self.tzinfo is tz: - return self - # Convert self to UTC, and attach the new time zone object. - utc = (self - self.utcoffset()).replace(tzinfo=tz) - # Convert from UTC to tz's local time. - return tz.fromutc(utc) - \end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{utcoffset}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - returns \code{\var{self}.tzinfo.utcoffset(\var{self})}, and - raises an exception if the latter doesn't return \code{None}, or - a \class{timedelta} object representing a whole number of minutes - with magnitude less than one day. -\end{methoddesc} - -\begin{methoddesc}{dst}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - returns \code{\var{self}.tzinfo.dst(\var{self})}, and - raises an exception if the latter doesn't return \code{None}, or - a \class{timedelta} object representing a whole number of minutes - with magnitude less than one day. -\end{methoddesc} - -\begin{methoddesc}{tzname}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - returns \code{\var{self}.tzinfo.tzname(\var{self})}, - raises an exception if the latter doesn't return \code{None} or - a string object, -\end{methoddesc} - -\begin{methoddesc}{timetuple}{} - Return a \class{time.struct_time} such as returned by - \function{time.localtime()}. - \code{\var{d}.timetuple()} is equivalent to - \code{time.struct_time((\var{d}.year, \var{d}.month, \var{d}.day, - \var{d}.hour, \var{d}.minute, \var{d}.second, - \var{d}.weekday(), - \var{d}.toordinal() - date(\var{d}.year, 1, 1).toordinal() + 1, - dst))} - The \member{tm_isdst} flag of the result is set according to - the \method{dst()} method: \member{tzinfo} is \code{None} or - \method{dst()} returns \code{None}, - \member{tm_isdst} is set to \code{-1}; else if \method{dst()} returns - a non-zero value, \member{tm_isdst} is set to \code{1}; - else \code{tm_isdst} is set to \code{0}. -\end{methoddesc} - -\begin{methoddesc}{utctimetuple}{} - If \class{datetime} instance \var{d} is naive, this is the same as - \code{\var{d}.timetuple()} except that \member{tm_isdst} is forced to 0 - regardless of what \code{d.dst()} returns. DST is never in effect - for a UTC time. - - If \var{d} is aware, \var{d} is normalized to UTC time, by subtracting - \code{\var{d}.utcoffset()}, and a \class{time.struct_time} for the - normalized time is returned. \member{tm_isdst} is forced to 0. - Note that the result's \member{tm_year} member may be - \constant{MINYEAR}-1 or \constant{MAXYEAR}+1, if \var{d}.year was - \code{MINYEAR} or \code{MAXYEAR} and UTC adjustment spills over a - year boundary. -\end{methoddesc} - -\begin{methoddesc}{toordinal}{} - Return the proleptic Gregorian ordinal of the date. The same as - \code{self.date().toordinal()}. -\end{methoddesc} - -\begin{methoddesc}{weekday}{} - Return the day of the week as an integer, where Monday is 0 and - Sunday is 6. The same as \code{self.date().weekday()}. - See also \method{isoweekday()}. -\end{methoddesc} - -\begin{methoddesc}{isoweekday}{} - Return the day of the week as an integer, where Monday is 1 and - Sunday is 7. The same as \code{self.date().isoweekday()}. - See also \method{weekday()}, \method{isocalendar()}. -\end{methoddesc} - -\begin{methoddesc}{isocalendar}{} - Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The - same as \code{self.date().isocalendar()}. -\end{methoddesc} - -\begin{methoddesc}{isoformat}{\optional{sep}} - Return a string representing the date and time in ISO 8601 format, - YYYY-MM-DDTHH:MM:SS.mmmmmm - or, if \member{microsecond} is 0, - YYYY-MM-DDTHH:MM:SS - - If \method{utcoffset()} does not return \code{None}, a 6-character - string is appended, giving the UTC offset in (signed) hours and - minutes: - YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM - or, if \member{microsecond} is 0 - YYYY-MM-DDTHH:MM:SS+HH:MM - - The optional argument \var{sep} (default \code{'T'}) is a - one-character separator, placed between the date and time portions - of the result. For example, - -\begin{verbatim} ->>> from datetime import tzinfo, timedelta, datetime ->>> class TZ(tzinfo): -... def utcoffset(self, dt): return timedelta(minutes=-399) -... ->>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ') -'2002-12-25 00:00:00-06:39' -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{__str__}{} - For a \class{datetime} instance \var{d}, \code{str(\var{d})} is - equivalent to \code{\var{d}.isoformat(' ')}. -\end{methoddesc} - -\begin{methoddesc}{ctime}{} - Return a string representing the date and time, for example - \code{datetime(2002, 12, 4, 20, 30, 40).ctime() == - 'Wed Dec 4 20:30:40 2002'}. - \code{d.ctime()} is equivalent to - \code{time.ctime(time.mktime(d.timetuple()))} on platforms where - the native C \cfunction{ctime()} function (which - \function{time.ctime()} invokes, but which - \method{datetime.ctime()} does not invoke) conforms to the C - standard. -\end{methoddesc} - -\begin{methoddesc}{strftime}{format} - Return a string representing the date and time, controlled by an - explicit format string. See section~\ref{strftime-behavior} -- - \method{strftime()} behavior. -\end{methoddesc} - - -\subsection{\class{time} Objects \label{datetime-time}} - -A time object represents a (local) time of day, independent of any -particular day, and subject to adjustment via a \class{tzinfo} object. - -\begin{classdesc}{time}{hour\optional{, minute\optional{, second\optional{, - microsecond\optional{, tzinfo}}}}} - All arguments are optional. \var{tzinfo} may be \code{None}, or - an instance of a \class{tzinfo} subclass. The remaining arguments - may be ints or longs, in the following ranges: - - \begin{itemize} - \item \code{0 <= \var{hour} < 24} - \item \code{0 <= \var{minute} < 60} - \item \code{0 <= \var{second} < 60} - \item \code{0 <= \var{microsecond} < 1000000}. - \end{itemize} - - If an argument outside those ranges is given, - \exception{ValueError} is raised. All default to \code{0} except - \var{tzinfo}, which defaults to \constant{None}. -\end{classdesc} - -Class attributes: - -\begin{memberdesc}{min} - The earliest representable \class{time}, \code{time(0, 0, 0, 0)}. -\end{memberdesc} - -\begin{memberdesc}{max} - The latest representable \class{time}, \code{time(23, 59, 59, 999999)}. -\end{memberdesc} - -\begin{memberdesc}{resolution} - The smallest possible difference between non-equal \class{time} - objects, \code{timedelta(microseconds=1)}, although note that - arithmetic on \class{time} objects is not supported. -\end{memberdesc} - -Instance attributes (read-only): - -\begin{memberdesc}{hour} - In \code{range(24)}. -\end{memberdesc} - -\begin{memberdesc}{minute} - In \code{range(60)}. -\end{memberdesc} - -\begin{memberdesc}{second} - In \code{range(60)}. -\end{memberdesc} - -\begin{memberdesc}{microsecond} - In \code{range(1000000)}. -\end{memberdesc} - -\begin{memberdesc}{tzinfo} - The object passed as the tzinfo argument to the \class{time} - constructor, or \code{None} if none was passed. -\end{memberdesc} - -Supported operations: - -\begin{itemize} - \item - comparison of \class{time} to \class{time}, - where \var{a} is considered less than \var{b} when \var{a} precedes - \var{b} in time. If one comparand is naive and the other is aware, - \exception{TypeError} is raised. If both comparands are aware, and - have the same \member{tzinfo} member, the common \member{tzinfo} - member is ignored and the base times are compared. If both - comparands are aware and have different \member{tzinfo} members, - the comparands are first adjusted by subtracting their UTC offsets - (obtained from \code{self.utcoffset()}). - In order to stop mixed-type comparisons from falling back to the - default comparison by object address, when a \class{time} object is - compared to an object of a different type, \exception{TypeError} is - raised unless the comparison is \code{==} or \code{!=}. The latter - cases return \constant{False} or \constant{True}, respectively. - - \item - hash, use as dict key - - \item - efficient pickling - - \item - in Boolean contexts, a \class{time} object is considered to be - true if and only if, after converting it to minutes and - subtracting \method{utcoffset()} (or \code{0} if that's - \code{None}), the result is non-zero. -\end{itemize} - -Instance methods: - -\begin{methoddesc}{replace}{\optional{hour\optional{, minute\optional{, - second\optional{, microsecond\optional{, - tzinfo}}}}}} - Return a \class{time} with the same value, except for those members given - new values by whichever keyword arguments are specified. Note that - \code{tzinfo=None} can be specified to create a naive \class{time} from - an aware \class{time}, without conversion of the time members. -\end{methoddesc} - -\begin{methoddesc}{isoformat}{} - Return a string representing the time in ISO 8601 format, - HH:MM:SS.mmmmmm - or, if self.microsecond is 0, - HH:MM:SS - If \method{utcoffset()} does not return \code{None}, a 6-character - string is appended, giving the UTC offset in (signed) hours and - minutes: - HH:MM:SS.mmmmmm+HH:MM - or, if self.microsecond is 0, - HH:MM:SS+HH:MM -\end{methoddesc} - -\begin{methoddesc}{__str__}{} - For a time \var{t}, \code{str(\var{t})} is equivalent to - \code{\var{t}.isoformat()}. -\end{methoddesc} - -\begin{methoddesc}{strftime}{format} - Return a string representing the time, controlled by an explicit - format string. See section~\ref{strftime-behavior} -- - \method{strftime()} behavior. -\end{methoddesc} - -\begin{methoddesc}{utcoffset}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - returns \code{\var{self}.tzinfo.utcoffset(None)}, and - raises an exception if the latter doesn't return \code{None} or - a \class{timedelta} object representing a whole number of minutes - with magnitude less than one day. -\end{methoddesc} - -\begin{methoddesc}{dst}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - returns \code{\var{self}.tzinfo.dst(None)}, and - raises an exception if the latter doesn't return \code{None}, or - a \class{timedelta} object representing a whole number of minutes - with magnitude less than one day. -\end{methoddesc} - -\begin{methoddesc}{tzname}{} - If \member{tzinfo} is \code{None}, returns \code{None}, else - returns \code{\var{self}.tzinfo.tzname(None)}, or - raises an exception if the latter doesn't return \code{None} or - a string object. -\end{methoddesc} - - -\subsection{\class{tzinfo} Objects \label{datetime-tzinfo}} - -\class{tzinfo} is an abstract base clase, meaning that this class -should not be instantiated directly. You need to derive a concrete -subclass, and (at least) supply implementations of the standard -\class{tzinfo} methods needed by the \class{datetime} methods you -use. The \module{datetime} module does not supply any concrete -subclasses of \class{tzinfo}. - -An instance of (a concrete subclass of) \class{tzinfo} can be passed -to the constructors for \class{datetime} and \class{time} objects. -The latter objects view their members as being in local time, and the -\class{tzinfo} object supports methods revealing offset of local time -from UTC, the name of the time zone, and DST offset, all relative to a -date or time object passed to them. - -Special requirement for pickling: A \class{tzinfo} subclass must have an -\method{__init__} method that can be called with no arguments, else it -can be pickled but possibly not unpickled again. This is a technical -requirement that may be relaxed in the future. - -A concrete subclass of \class{tzinfo} may need to implement the -following methods. Exactly which methods are needed depends on the -uses made of aware \module{datetime} objects. If in doubt, simply -implement all of them. - -\begin{methoddesc}[tzinfo]{utcoffset}{self, dt} - Return offset of local time from UTC, in minutes east of UTC. If - local time is west of UTC, this should be negative. Note that this - is intended to be the total offset from UTC; for example, if a - \class{tzinfo} object represents both time zone and DST adjustments, - \method{utcoffset()} should return their sum. If the UTC offset - isn't known, return \code{None}. Else the value returned must be - a \class{timedelta} object specifying a whole number of minutes in the - range -1439 to 1439 inclusive (1440 = 24*60; the magnitude of the offset - must be less than one day). Most implementations of - \method{utcoffset()} will probably look like one of these two: - -\begin{verbatim} - return CONSTANT # fixed-offset class - return CONSTANT + self.dst(dt) # daylight-aware class -\end{verbatim} - - If \method{utcoffset()} does not return \code{None}, - \method{dst()} should not return \code{None} either. - - The default implementation of \method{utcoffset()} raises - \exception{NotImplementedError}. -\end{methoddesc} - -\begin{methoddesc}[tzinfo]{dst}{self, dt} - Return the daylight saving time (DST) adjustment, in minutes east of - UTC, or \code{None} if DST information isn't known. Return - \code{timedelta(0)} if DST is not in effect. - If DST is in effect, return the offset as a - \class{timedelta} object (see \method{utcoffset()} for details). - Note that DST offset, if applicable, has - already been added to the UTC offset returned by - \method{utcoffset()}, so there's no need to consult \method{dst()} - unless you're interested in obtaining DST info separately. For - example, \method{datetime.timetuple()} calls its \member{tzinfo} - member's \method{dst()} method to determine how the - \member{tm_isdst} flag should be set, and - \method{tzinfo.fromutc()} calls \method{dst()} to account for - DST changes when crossing time zones. - - An instance \var{tz} of a \class{tzinfo} subclass that models both - standard and daylight times must be consistent in this sense: - - \code{\var{tz}.utcoffset(\var{dt}) - \var{tz}.dst(\var{dt})} - - must return the same result for every \class{datetime} \var{dt} - with \code{\var{dt}.tzinfo == \var{tz}} For sane \class{tzinfo} - subclasses, this expression yields the time zone's "standard offset", - which should not depend on the date or the time, but only on geographic - location. The implementation of \method{datetime.astimezone()} relies - on this, but cannot detect violations; it's the programmer's - responsibility to ensure it. If a \class{tzinfo} subclass cannot - guarantee this, it may be able to override the default implementation - of \method{tzinfo.fromutc()} to work correctly with \method{astimezone()} - regardless. - - Most implementations of \method{dst()} will probably look like one - of these two: - -\begin{verbatim} - def dst(self): - # a fixed-offset class: doesn't account for DST - return timedelta(0) -\end{verbatim} - - or - -\begin{verbatim} - def dst(self): - # Code to set dston and dstoff to the time zone's DST - # transition times based on the input dt.year, and expressed - # in standard local time. Then - - if dston <= dt.replace(tzinfo=None) < dstoff: - return timedelta(hours=1) - else: - return timedelta(0) -\end{verbatim} - - The default implementation of \method{dst()} raises - \exception{NotImplementedError}. -\end{methoddesc} - -\begin{methoddesc}[tzinfo]{tzname}{self, dt} - Return the time zone name corresponding to the \class{datetime} - object \var{dt}, as a string. - Nothing about string names is defined by the - \module{datetime} module, and there's no requirement that it mean - anything in particular. For example, "GMT", "UTC", "-500", "-5:00", - "EDT", "US/Eastern", "America/New York" are all valid replies. Return - \code{None} if a string name isn't known. Note that this is a method - rather than a fixed string primarily because some \class{tzinfo} - subclasses will wish to return different names depending on the specific - value of \var{dt} passed, especially if the \class{tzinfo} class is - accounting for daylight time. - - The default implementation of \method{tzname()} raises - \exception{NotImplementedError}. -\end{methoddesc} - -These methods are called by a \class{datetime} or \class{time} object, -in response to their methods of the same names. A \class{datetime} -object passes itself as the argument, and a \class{time} object passes -\code{None} as the argument. A \class{tzinfo} subclass's methods should -therefore be prepared to accept a \var{dt} argument of \code{None}, or of -class \class{datetime}. - -When \code{None} is passed, it's up to the class designer to decide the -best response. For example, returning \code{None} is appropriate if the -class wishes to say that time objects don't participate in the -\class{tzinfo} protocols. It may be more useful for \code{utcoffset(None)} -to return the standard UTC offset, as there is no other convention for -discovering the standard offset. - -When a \class{datetime} object is passed in response to a -\class{datetime} method, \code{dt.tzinfo} is the same object as -\var{self}. \class{tzinfo} methods can rely on this, unless -user code calls \class{tzinfo} methods directly. The intent is that -the \class{tzinfo} methods interpret \var{dt} as being in local time, -and not need worry about objects in other timezones. - -There is one more \class{tzinfo} method that a subclass may wish to -override: - -\begin{methoddesc}[tzinfo]{fromutc}{self, dt} - This is called from the default \class{datetime.astimezone()} - implementation. When called from that, \code{\var{dt}.tzinfo} is - \var{self}, and \var{dt}'s date and time members are to be viewed as - expressing a UTC time. The purpose of \method{fromutc()} is to - adjust the date and time members, returning an equivalent datetime in - \var{self}'s local time. - - Most \class{tzinfo} subclasses should be able to inherit the default - \method{fromutc()} implementation without problems. It's strong enough - to handle fixed-offset time zones, and time zones accounting for both - standard and daylight time, and the latter even if the DST transition - times differ in different years. An example of a time zone the default - \method{fromutc()} implementation may not handle correctly in all cases - is one where the standard offset (from UTC) depends on the specific date - and time passed, which can happen for political reasons. - The default implementations of \method{astimezone()} and - \method{fromutc()} may not produce the result you want if the result is - one of the hours straddling the moment the standard offset changes. - - Skipping code for error cases, the default \method{fromutc()} - implementation acts like: - - \begin{verbatim} - def fromutc(self, dt): - # raise ValueError error if dt.tzinfo is not self - dtoff = dt.utcoffset() - dtdst = dt.dst() - # raise ValueError if dtoff is None or dtdst is None - delta = dtoff - dtdst # this is self's standard offset - if delta: - dt += delta # convert to standard local time - dtdst = dt.dst() - # raise ValueError if dtdst is None - if dtdst: - return dt + dtdst - else: - return dt - \end{verbatim} -\end{methoddesc} - -Example \class{tzinfo} classes: - -\verbatiminput{tzinfo-examples.py} - -Note that there are unavoidable subtleties twice per year in a -\class{tzinfo} -subclass accounting for both standard and daylight time, at the DST -transition points. For concreteness, consider US Eastern (UTC -0500), -where EDT begins the minute after 1:59 (EST) on the first Sunday in -April, and ends the minute after 1:59 (EDT) on the last Sunday in October: - -\begin{verbatim} - UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM - EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM - EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM - - start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM - - end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM -\end{verbatim} - -When DST starts (the "start" line), the local wall clock leaps from 1:59 -to 3:00. A wall time of the form 2:MM doesn't really make sense on that -day, so \code{astimezone(Eastern)} won't deliver a result with -\code{hour == 2} on the -day DST begins. In order for \method{astimezone()} to make this -guarantee, the \method{rzinfo.dst()} method must consider times -in the "missing hour" (2:MM for Eastern) to be in daylight time. - -When DST ends (the "end" line), there's a potentially worse problem: -there's an hour that can't be spelled unambiguously in local wall time: -the last hour of daylight time. In Eastern, that's times of -the form 5:MM UTC on the day daylight time ends. The local wall clock -leaps from 1:59 (daylight time) back to 1:00 (standard time) again. -Local times of the form 1:MM are ambiguous. \method{astimezone()} mimics -the local clock's behavior by mapping two adjacent UTC hours into the -same local hour then. In the Eastern example, UTC times of the form -5:MM and 6:MM both map to 1:MM when converted to Eastern. In order for -\method{astimezone()} to make this guarantee, the \method{tzinfo.dst()} -method must consider times in the "repeated hour" to be in -standard time. This is easily arranged, as in the example, by expressing -DST switch times in the time zone's standard local time. - -Applications that can't bear such ambiguities should avoid using hybrid -\class{tzinfo} subclasses; there are no ambiguities when using UTC, or -any other fixed-offset \class{tzinfo} subclass (such as a class -representing only EST (fixed offset -5 hours), or only EDT (fixed offset --4 hours)). - - -\subsection{\method{strftime()} Behavior\label{strftime-behavior}} - -\class{date}, \class{datetime}, and \class{time} -objects all support a \code{strftime(\var{format})} -method, to create a string representing the time under the control of -an explicit format string. Broadly speaking, -\code{d.strftime(fmt)} -acts like the \refmodule{time} module's -\code{time.strftime(fmt, d.timetuple())} -although not all objects support a \method{timetuple()} method. - -For \class{time} objects, the format codes for -year, month, and day should not be used, as time objects have no such -values. If they're used anyway, \code{1900} is substituted for the -year, and \code{0} for the month and day. - -For \class{date} objects, the format codes for hours, minutes, and -seconds should not be used, as \class{date} objects have no such -values. If they're used anyway, \code{0} is substituted for them. - -For a naive object, the \code{\%z} and \code{\%Z} format codes are -replaced by empty strings. - -For an aware object: - -\begin{itemize} - \item[\code{\%z}] - \method{utcoffset()} is transformed into a 5-character string of - the form +HHMM or -HHMM, where HH is a 2-digit string giving the - number of UTC offset hours, and MM is a 2-digit string giving the - number of UTC offset minutes. For example, if - \method{utcoffset()} returns \code{timedelta(hours=-3, minutes=-30)}, - \code{\%z} is replaced with the string \code{'-0330'}. - - \item[\code{\%Z}] - If \method{tzname()} returns \code{None}, \code{\%Z} is replaced - by an empty string. Otherwise \code{\%Z} is replaced by the returned - value, which must be a string. -\end{itemize} - -The full set of format codes supported varies across platforms, -because Python calls the platform C library's \function{strftime()} -function, and platform variations are common. The documentation for -Python's \refmodule{time} module lists the format codes that the C -standard (1989 version) requires, and those work on all platforms -with a standard C implementation. Note that the 1999 version of the -C standard added additional format codes. - -The exact range of years for which \method{strftime()} works also -varies across platforms. Regardless of platform, years before 1900 -cannot be used. - -%%% This example is obsolete, since strptime is now supported by datetime. -% -% \subsection{Examples} -% -% \subsubsection{Creating Datetime Objects from Formatted Strings} -% -% The \class{datetime} class does not directly support parsing formatted time -% strings. You can use \function{time.strptime} to do the parsing and create -% a \class{datetime} object from the tuple it returns: -% -% \begin{verbatim} -% >>> s = "2005-12-06T12:13:14" -% >>> from datetime import datetime -% >>> from time import strptime -% >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6]) -% datetime.datetime(2005, 12, 6, 12, 13, 14) -% \end{verbatim} -% diff --git a/Doc/lib/libdbhash.tex b/Doc/lib/libdbhash.tex deleted file mode 100644 index 5852b73..0000000 --- a/Doc/lib/libdbhash.tex +++ /dev/null @@ -1,88 +0,0 @@ -\section{\module{dbhash} --- - DBM-style interface to the BSD database library} - -\declaremodule{standard}{dbhash} -\modulesynopsis{DBM-style interface to the BSD database library.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -The \module{dbhash} module provides a function to open databases using -the BSD \code{db} library. This module mirrors the interface of the -other Python database modules that provide access to DBM-style -databases. The \refmodule{bsddb}\refbimodindex{bsddb} module is required -to use \module{dbhash}. - -This module provides an exception and a function: - - -\begin{excdesc}{error} - Exception raised on database errors other than - \exception{KeyError}. It is a synonym for \exception{bsddb.error}. -\end{excdesc} - -\begin{funcdesc}{open}{path\optional{, flag\optional{, mode}}} - Open a \code{db} database and return the database object. The - \var{path} argument is the name of the database file. - - The \var{flag} argument can be - \code{'r'} (the default), \code{'w'}, - \code{'c'} (which creates the database if it doesn't exist), or - \code{'n'} (which always creates a new empty database). - For platforms on which the BSD \code{db} library supports locking, - an \character{l} can be appended to indicate that locking should be - used. - - The optional \var{mode} parameter is used to indicate the \UNIX{} - permission bits that should be set if a new database must be - created; this will be masked by the current umask value for the - process. -\end{funcdesc} - - -\begin{seealso} - \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.} - \seemodule{bsddb}{Lower-level interface to the BSD \code{db} library.} - \seemodule{whichdb}{Utility module used to determine the type of an - existing database.} -\end{seealso} - - -\subsection{Database Objects \label{dbhash-objects}} - -The database objects returned by \function{open()} provide the methods -common to all the DBM-style databases and mapping objects. The following -methods are available in addition to the standard methods. - -\begin{methoddesc}[dbhash]{first}{} - It's possible to loop over every key/value pair in the database using - this method and the \method{next()} method. The traversal is ordered by - the databases internal hash values, and won't be sorted by the key - values. This method returns the starting key. -\end{methoddesc} - -\begin{methoddesc}[dbhash]{last}{} - Return the last key/value pair in a database traversal. This may be used to - begin a reverse-order traversal; see \method{previous()}. -\end{methoddesc} - -\begin{methoddesc}[dbhash]{next}{} - Returns the key next key/value pair in a database traversal. The - following code prints every key in the database \code{db}, without - having to create a list in memory that contains them all: - -\begin{verbatim} -print db.first() -for i in range(1, len(db)): - print db.next() -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[dbhash]{previous}{} - Returns the previous key/value pair in a forward-traversal of the database. - In conjunction with \method{last()}, this may be used to implement - a reverse-order traversal. -\end{methoddesc} - -\begin{methoddesc}[dbhash]{sync}{} - This method forces any unwritten data to be written to the disk. -\end{methoddesc} diff --git a/Doc/lib/libdbm.tex b/Doc/lib/libdbm.tex deleted file mode 100644 index e08af99..0000000 --- a/Doc/lib/libdbm.tex +++ /dev/null @@ -1,61 +0,0 @@ -\section{\module{dbm} --- - Simple ``database'' interface} - -\declaremodule{builtin}{dbm} - \platform{Unix} -\modulesynopsis{The standard ``database'' interface, based on ndbm.} - - -The \module{dbm} module provides an interface to the \UNIX{} -(\code{n})\code{dbm} library. Dbm objects behave like mappings -(dictionaries), except that keys and values are always strings. -Printing a dbm object doesn't print the keys and values, and the -\method{items()} and \method{values()} methods are not supported. - -This module can be used with the ``classic'' ndbm interface, the BSD -DB compatibility interface, or the GNU GDBM compatibility interface. -On \UNIX, the \program{configure} script will attempt to locate the -appropriate header file to simplify building this module. - -The module defines the following: - -\begin{excdesc}{error} -Raised on dbm-specific errors, such as I/O errors. -\exception{KeyError} is raised for general mapping errors like -specifying an incorrect key. -\end{excdesc} - -\begin{datadesc}{library} -Name of the \code{ndbm} implementation library used. -\end{datadesc} - -\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}} -Open a dbm database and return a dbm object. The \var{filename} -argument is the name of the database file (without the \file{.dir} or -\file{.pag} extensions; note that the BSD DB implementation of the -interface will append the extension \file{.db} and only create one -file). - -The optional \var{flag} argument must be one of these values: - -\begin{tableii}{c|l}{code}{Value}{Meaning} - \lineii{'r'}{Open existing database for reading only (default)} - \lineii{'w'}{Open existing database for reading and writing} - \lineii{'c'}{Open database for reading and writing, creating it if - it doesn't exist} - \lineii{'n'}{Always create a new, empty database, open for reading - and writing} -\end{tableii} - -The optional \var{mode} argument is the \UNIX{} mode of the file, used -only when the database has to be created. It defaults to octal -\code{0666}. -\end{funcdesc} - - -\begin{seealso} - \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.} - \seemodule{gdbm}{Similar interface to the GNU GDBM library.} - \seemodule{whichdb}{Utility module used to determine the type of an - existing database.} -\end{seealso} diff --git a/Doc/lib/libdecimal.tex b/Doc/lib/libdecimal.tex deleted file mode 100644 index 8c665da..0000000 --- a/Doc/lib/libdecimal.tex +++ /dev/null @@ -1,1313 +0,0 @@ -\section{\module{decimal} --- - Decimal floating point arithmetic} - -\declaremodule{standard}{decimal} -\modulesynopsis{Implementation of the General Decimal Arithmetic -Specification.} - -\moduleauthor{Eric Price}{eprice at tjhsst.edu} -\moduleauthor{Facundo Batista}{facundo at taniquetil.com.ar} -\moduleauthor{Raymond Hettinger}{python at rcn.com} -\moduleauthor{Aahz}{aahz at pobox.com} -\moduleauthor{Tim Peters}{tim.one at comcast.net} - -\sectionauthor{Raymond D. Hettinger}{python at rcn.com} - -\versionadded{2.4} - -The \module{decimal} module provides support for decimal floating point -arithmetic. It offers several advantages over the \class{float()} datatype: - -\begin{itemize} - -\item Decimal numbers can be represented exactly. In contrast, numbers like -\constant{1.1} do not have an exact representation in binary floating point. -End users typically would not expect \constant{1.1} to display as -\constant{1.1000000000000001} as it does with binary floating point. - -\item The exactness carries over into arithmetic. In decimal floating point, -\samp{0.1 + 0.1 + 0.1 - 0.3} is exactly equal to zero. In binary floating -point, result is \constant{5.5511151231257827e-017}. While near to zero, the -differences prevent reliable equality testing and differences can accumulate. -For this reason, decimal would be preferred in accounting applications which -have strict equality invariants. - -\item The decimal module incorporates a notion of significant places so that -\samp{1.30 + 1.20} is \constant{2.50}. The trailing zero is kept to indicate -significance. This is the customary presentation for monetary applications. For -multiplication, the ``schoolbook'' approach uses all the figures in the -multiplicands. For instance, \samp{1.3 * 1.2} gives \constant{1.56} while -\samp{1.30 * 1.20} gives \constant{1.5600}. - -\item Unlike hardware based binary floating point, the decimal module has a user -settable precision (defaulting to 28 places) which can be as large as needed for -a given problem: - -\begin{verbatim} ->>> getcontext().prec = 6 ->>> Decimal(1) / Decimal(7) -Decimal("0.142857") ->>> getcontext().prec = 28 ->>> Decimal(1) / Decimal(7) -Decimal("0.1428571428571428571428571429") -\end{verbatim} - -\item Both binary and decimal floating point are implemented in terms of published -standards. While the built-in float type exposes only a modest portion of its -capabilities, the decimal module exposes all required parts of the standard. -When needed, the programmer has full control over rounding and signal handling. - -\end{itemize} - - -The module design is centered around three concepts: the decimal number, the -context for arithmetic, and signals. - -A decimal number is immutable. It has a sign, coefficient digits, and an -exponent. To preserve significance, the coefficient digits do not truncate -trailing zeroes. Decimals also include special values such as -\constant{Infinity}, \constant{-Infinity}, and \constant{NaN}. The standard -also differentiates \constant{-0} from \constant{+0}. - -The context for arithmetic is an environment specifying precision, rounding -rules, limits on exponents, flags indicating the results of operations, -and trap enablers which determine whether signals are treated as -exceptions. Rounding options include \constant{ROUND_CEILING}, -\constant{ROUND_DOWN}, \constant{ROUND_FLOOR}, \constant{ROUND_HALF_DOWN}, -\constant{ROUND_HALF_EVEN}, \constant{ROUND_HALF_UP}, and \constant{ROUND_UP}. - -Signals are groups of exceptional conditions arising during the course of -computation. Depending on the needs of the application, signals may be -ignored, considered as informational, or treated as exceptions. The signals in -the decimal module are: \constant{Clamped}, \constant{InvalidOperation}, -\constant{DivisionByZero}, \constant{Inexact}, \constant{Rounded}, -\constant{Subnormal}, \constant{Overflow}, and \constant{Underflow}. - -For each signal there is a flag and a trap enabler. When a signal is -encountered, its flag is incremented from zero and, then, if the trap enabler -is set to one, an exception is raised. Flags are sticky, so the user -needs to reset them before monitoring a calculation. - - -\begin{seealso} - \seetext{IBM's General Decimal Arithmetic Specification, - \citetitle[http://www2.hursley.ibm.com/decimal/decarith.html] - {The General Decimal Arithmetic Specification}.} - - \seetext{IEEE standard 854-1987, - \citetitle[http://www.cs.berkeley.edu/\textasciitilde ejr/projects/754/private/drafts/854-1987/dir.html] - {Unofficial IEEE 854 Text}.} -\end{seealso} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Quick-start Tutorial \label{decimal-tutorial}} - -The usual start to using decimals is importing the module, viewing the current -context with \function{getcontext()} and, if necessary, setting new values -for precision, rounding, or enabled traps: - -\begin{verbatim} ->>> from decimal import * ->>> getcontext() -Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, - capitals=1, flags=[], traps=[Overflow, InvalidOperation, - DivisionByZero]) - ->>> getcontext().prec = 7 # Set a new precision -\end{verbatim} - - -Decimal instances can be constructed from integers, strings, or tuples. To -create a Decimal from a \class{float}, first convert it to a string. This -serves as an explicit reminder of the details of the conversion (including -representation error). Decimal numbers include special values such as -\constant{NaN} which stands for ``Not a number'', positive and negative -\constant{Infinity}, and \constant{-0}. - -\begin{verbatim} ->>> Decimal(10) -Decimal("10") ->>> Decimal("3.14") -Decimal("3.14") ->>> Decimal((0, (3, 1, 4), -2)) -Decimal("3.14") ->>> Decimal(str(2.0 ** 0.5)) -Decimal("1.41421356237") ->>> Decimal("NaN") -Decimal("NaN") ->>> Decimal("-Infinity") -Decimal("-Infinity") -\end{verbatim} - - -The significance of a new Decimal is determined solely by the number -of digits input. Context precision and rounding only come into play during -arithmetic operations. - -\begin{verbatim} ->>> getcontext().prec = 6 ->>> Decimal('3.0') -Decimal("3.0") ->>> Decimal('3.1415926535') -Decimal("3.1415926535") ->>> Decimal('3.1415926535') + Decimal('2.7182818285') -Decimal("5.85987") ->>> getcontext().rounding = ROUND_UP ->>> Decimal('3.1415926535') + Decimal('2.7182818285') -Decimal("5.85988") -\end{verbatim} - - -Decimals interact well with much of the rest of Python. Here is a small -decimal floating point flying circus: - -\begin{verbatim} ->>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split()) ->>> max(data) -Decimal("9.25") ->>> min(data) -Decimal("0.03") ->>> sorted(data) -[Decimal("0.03"), Decimal("1.00"), Decimal("1.34"), Decimal("1.87"), - Decimal("2.35"), Decimal("3.45"), Decimal("9.25")] ->>> sum(data) -Decimal("19.29") ->>> a,b,c = data[:3] ->>> str(a) -'1.34' ->>> float(a) -1.3400000000000001 ->>> round(a, 1) # round() first converts to binary floating point -1.3 ->>> int(a) -1 ->>> a * 5 -Decimal("6.70") ->>> a * b -Decimal("2.5058") ->>> c % a -Decimal("0.77") -\end{verbatim} - -The \method{quantize()} method rounds a number to a fixed exponent. This -method is useful for monetary applications that often round results to a fixed -number of places: - -\begin{verbatim} ->>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN) -Decimal("7.32") ->>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP) -Decimal("8") -\end{verbatim} - -As shown above, the \function{getcontext()} function accesses the current -context and allows the settings to be changed. This approach meets the -needs of most applications. - -For more advanced work, it may be useful to create alternate contexts using -the Context() constructor. To make an alternate active, use the -\function{setcontext()} function. - -In accordance with the standard, the \module{Decimal} module provides two -ready to use standard contexts, \constant{BasicContext} and -\constant{ExtendedContext}. The former is especially useful for debugging -because many of the traps are enabled: - -\begin{verbatim} ->>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN) ->>> setcontext(myothercontext) ->>> Decimal(1) / Decimal(7) -Decimal("0.142857142857142857142857142857142857142857142857142857142857") - ->>> ExtendedContext -Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, - capitals=1, flags=[], traps=[]) ->>> setcontext(ExtendedContext) ->>> Decimal(1) / Decimal(7) -Decimal("0.142857143") ->>> Decimal(42) / Decimal(0) -Decimal("Infinity") - ->>> setcontext(BasicContext) ->>> Decimal(42) / Decimal(0) -Traceback (most recent call last): - File "<pyshell#143>", line 1, in -toplevel- - Decimal(42) / Decimal(0) -DivisionByZero: x / 0 -\end{verbatim} - - -Contexts also have signal flags for monitoring exceptional conditions -encountered during computations. The flags remain set until explicitly -cleared, so it is best to clear the flags before each set of monitored -computations by using the \method{clear_flags()} method. - -\begin{verbatim} ->>> setcontext(ExtendedContext) ->>> getcontext().clear_flags() ->>> Decimal(355) / Decimal(113) -Decimal("3.14159292") ->>> getcontext() -Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999, - capitals=1, flags=[Inexact, Rounded], traps=[]) -\end{verbatim} - -The \var{flags} entry shows that the rational approximation to \constant{Pi} -was rounded (digits beyond the context precision were thrown away) and that -the result is inexact (some of the discarded digits were non-zero). - -Individual traps are set using the dictionary in the \member{traps} -field of a context: - -\begin{verbatim} ->>> Decimal(1) / Decimal(0) -Decimal("Infinity") ->>> getcontext().traps[DivisionByZero] = 1 ->>> Decimal(1) / Decimal(0) -Traceback (most recent call last): - File "<pyshell#112>", line 1, in -toplevel- - Decimal(1) / Decimal(0) -DivisionByZero: x / 0 -\end{verbatim} - -Most programs adjust the current context only once, at the beginning of the -program. And, in many applications, data is converted to \class{Decimal} with -a single cast inside a loop. With context set and decimals created, the bulk -of the program manipulates the data no differently than with other Python -numeric types. - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Decimal objects \label{decimal-decimal}} - -\begin{classdesc}{Decimal}{\optional{value \optional{, context}}} - Constructs a new \class{Decimal} object based from \var{value}. - - \var{value} can be an integer, string, tuple, or another \class{Decimal} - object. If no \var{value} is given, returns \code{Decimal("0")}. If - \var{value} is a string, it should conform to the decimal numeric string - syntax: - - \begin{verbatim} - sign ::= '+' | '-' - digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' - indicator ::= 'e' | 'E' - digits ::= digit [digit]... - decimal-part ::= digits '.' [digits] | ['.'] digits - exponent-part ::= indicator [sign] digits - infinity ::= 'Infinity' | 'Inf' - nan ::= 'NaN' [digits] | 'sNaN' [digits] - numeric-value ::= decimal-part [exponent-part] | infinity - numeric-string ::= [sign] numeric-value | [sign] nan - \end{verbatim} - - If \var{value} is a \class{tuple}, it should have three components, - a sign (\constant{0} for positive or \constant{1} for negative), - a \class{tuple} of digits, and an integer exponent. For example, - \samp{Decimal((0, (1, 4, 1, 4), -3))} returns \code{Decimal("1.414")}. - - The \var{context} precision does not affect how many digits are stored. - That is determined exclusively by the number of digits in \var{value}. For - example, \samp{Decimal("3.00000")} records all five zeroes even if the - context precision is only three. - - The purpose of the \var{context} argument is determining what to do if - \var{value} is a malformed string. If the context traps - \constant{InvalidOperation}, an exception is raised; otherwise, the - constructor returns a new Decimal with the value of \constant{NaN}. - - Once constructed, \class{Decimal} objects are immutable. -\end{classdesc} - -Decimal floating point objects share many properties with the other builtin -numeric types such as \class{float} and \class{int}. All of the usual -math operations and special methods apply. Likewise, decimal objects can -be copied, pickled, printed, used as dictionary keys, used as set elements, -compared, sorted, and coerced to another type (such as \class{float} -or \class{long}). - -In addition to the standard numeric properties, decimal floating point objects -also have a number of specialized methods: - -\begin{methoddesc}{adjusted}{} - Return the adjusted exponent after shifting out the coefficient's rightmost - digits until only the lead digit remains: \code{Decimal("321e+5").adjusted()} - returns seven. Used for determining the position of the most significant - digit with respect to the decimal point. -\end{methoddesc} - -\begin{methoddesc}{as_tuple}{} - Returns a tuple representation of the number: - \samp{(sign, digittuple, exponent)}. -\end{methoddesc} - -\begin{methoddesc}{compare}{other\optional{, context}} - Compares like \method{__cmp__()} but returns a decimal instance: - \begin{verbatim} - a or b is a NaN ==> Decimal("NaN") - a < b ==> Decimal("-1") - a == b ==> Decimal("0") - a > b ==> Decimal("1") - \end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{max}{other\optional{, context}} - Like \samp{max(self, other)} except that the context rounding rule - is applied before returning and that \constant{NaN} values are - either signalled or ignored (depending on the context and whether - they are signaling or quiet). -\end{methoddesc} - -\begin{methoddesc}{min}{other\optional{, context}} - Like \samp{min(self, other)} except that the context rounding rule - is applied before returning and that \constant{NaN} values are - either signalled or ignored (depending on the context and whether - they are signaling or quiet). -\end{methoddesc} - -\begin{methoddesc}{normalize}{\optional{context}} - Normalize the number by stripping the rightmost trailing zeroes and - converting any result equal to \constant{Decimal("0")} to - \constant{Decimal("0e0")}. Used for producing canonical values for members - of an equivalence class. For example, \code{Decimal("32.100")} and - \code{Decimal("0.321000e+2")} both normalize to the equivalent value - \code{Decimal("32.1")}. -\end{methoddesc} - -\begin{methoddesc}{quantize} - {exp \optional{, rounding\optional{, context\optional{, watchexp}}}} - Quantize makes the exponent the same as \var{exp}. Searches for a - rounding method in \var{rounding}, then in \var{context}, and then - in the current context. - - If \var{watchexp} is set (default), then an error is returned whenever - the resulting exponent is greater than \member{Emax} or less than - \member{Etiny}. -\end{methoddesc} - -\begin{methoddesc}{remainder_near}{other\optional{, context}} - Computes the modulo as either a positive or negative value depending - on which is closest to zero. For instance, - \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")} - which is closer to zero than \code{Decimal("4")}. - - If both are equally close, the one chosen will have the same sign - as \var{self}. -\end{methoddesc} - -\begin{methoddesc}{same_quantum}{other\optional{, context}} - Test whether self and other have the same exponent or whether both - are \constant{NaN}. -\end{methoddesc} - -\begin{methoddesc}{sqrt}{\optional{context}} - Return the square root to full precision. -\end{methoddesc} - -\begin{methoddesc}{to_eng_string}{\optional{context}} - Convert to an engineering-type string. - - Engineering notation has an exponent which is a multiple of 3, so there - are up to 3 digits left of the decimal place. For example, converts - \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")} -\end{methoddesc} - -\begin{methoddesc}{to_integral}{\optional{rounding\optional{, context}}} - Rounds to the nearest integer without signaling \constant{Inexact} - or \constant{Rounded}. If given, applies \var{rounding}; otherwise, - uses the rounding method in either the supplied \var{context} or the - current context. -\end{methoddesc} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Context objects \label{decimal-context}} - -Contexts are environments for arithmetic operations. They govern precision, -set rules for rounding, determine which signals are treated as exceptions, and -limit the range for exponents. - -Each thread has its own current context which is accessed or changed using -the \function{getcontext()} and \function{setcontext()} functions: - -\begin{funcdesc}{getcontext}{} - Return the current context for the active thread. -\end{funcdesc} - -\begin{funcdesc}{setcontext}{c} - Set the current context for the active thread to \var{c}. -\end{funcdesc} - -Beginning with Python 2.5, you can also use the \keyword{with} statement -and the \function{localcontext()} function to temporarily change the -active context. - -\begin{funcdesc}{localcontext}{\optional{c}} - Return a context manager that will set the current context for - the active thread to a copy of \var{c} on entry to the with-statement - and restore the previous context when exiting the with-statement. If - no context is specified, a copy of the current context is used. - \versionadded{2.5} - - For example, the following code sets the current decimal precision - to 42 places, performs a calculation, and then automatically restores - the previous context: -\begin{verbatim} - from __future__ import with_statement - from decimal import localcontext - - with localcontext() as ctx: - ctx.prec = 42 # Perform a high precision calculation - s = calculate_something() - s = +s # Round the final result back to the default precision -\end{verbatim} -\end{funcdesc} - -New contexts can also be created using the \class{Context} constructor -described below. In addition, the module provides three pre-made -contexts: - -\begin{classdesc*}{BasicContext} - This is a standard context defined by the General Decimal Arithmetic - Specification. Precision is set to nine. Rounding is set to - \constant{ROUND_HALF_UP}. All flags are cleared. All traps are enabled - (treated as exceptions) except \constant{Inexact}, \constant{Rounded}, and - \constant{Subnormal}. - - Because many of the traps are enabled, this context is useful for debugging. -\end{classdesc*} - -\begin{classdesc*}{ExtendedContext} - This is a standard context defined by the General Decimal Arithmetic - Specification. Precision is set to nine. Rounding is set to - \constant{ROUND_HALF_EVEN}. All flags are cleared. No traps are enabled - (so that exceptions are not raised during computations). - - Because the trapped are disabled, this context is useful for applications - that prefer to have result value of \constant{NaN} or \constant{Infinity} - instead of raising exceptions. This allows an application to complete a - run in the presence of conditions that would otherwise halt the program. -\end{classdesc*} - -\begin{classdesc*}{DefaultContext} - This context is used by the \class{Context} constructor as a prototype for - new contexts. Changing a field (such a precision) has the effect of - changing the default for new contexts creating by the \class{Context} - constructor. - - This context is most useful in multi-threaded environments. Changing one of - the fields before threads are started has the effect of setting system-wide - defaults. Changing the fields after threads have started is not recommended - as it would require thread synchronization to prevent race conditions. - - In single threaded environments, it is preferable to not use this context - at all. Instead, simply create contexts explicitly as described below. - - The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled - traps for Overflow, InvalidOperation, and DivisionByZero. -\end{classdesc*} - - -In addition to the three supplied contexts, new contexts can be created -with the \class{Context} constructor. - -\begin{classdesc}{Context}{prec=None, rounding=None, traps=None, - flags=None, Emin=None, Emax=None, capitals=1} - Creates a new context. If a field is not specified or is \constant{None}, - the default values are copied from the \constant{DefaultContext}. If the - \var{flags} field is not specified or is \constant{None}, all flags are - cleared. - - The \var{prec} field is a positive integer that sets the precision for - arithmetic operations in the context. - - The \var{rounding} option is one of: - \begin{itemize} - \item \constant{ROUND_CEILING} (towards \constant{Infinity}), - \item \constant{ROUND_DOWN} (towards zero), - \item \constant{ROUND_FLOOR} (towards \constant{-Infinity}), - \item \constant{ROUND_HALF_DOWN} (to nearest with ties going towards zero), - \item \constant{ROUND_HALF_EVEN} (to nearest with ties going to nearest even integer), - \item \constant{ROUND_HALF_UP} (to nearest with ties going away from zero), or - \item \constant{ROUND_UP} (away from zero). - \end{itemize} - - The \var{traps} and \var{flags} fields list any signals to be set. - Generally, new contexts should only set traps and leave the flags clear. - - The \var{Emin} and \var{Emax} fields are integers specifying the outer - limits allowable for exponents. - - The \var{capitals} field is either \constant{0} or \constant{1} (the - default). If set to \constant{1}, exponents are printed with a capital - \constant{E}; otherwise, a lowercase \constant{e} is used: - \constant{Decimal('6.02e+23')}. -\end{classdesc} - -The \class{Context} class defines several general purpose methods as well as a -large number of methods for doing arithmetic directly in a given context. - -\begin{methoddesc}{clear_flags}{} - Resets all of the flags to \constant{0}. -\end{methoddesc} - -\begin{methoddesc}{copy}{} - Return a duplicate of the context. -\end{methoddesc} - -\begin{methoddesc}{create_decimal}{num} - Creates a new Decimal instance from \var{num} but using \var{self} as - context. Unlike the \class{Decimal} constructor, the context precision, - rounding method, flags, and traps are applied to the conversion. - - This is useful because constants are often given to a greater precision than - is needed by the application. Another benefit is that rounding immediately - eliminates unintended effects from digits beyond the current precision. - In the following example, using unrounded inputs means that adding zero - to a sum can change the result: - - \begin{verbatim} - >>> getcontext().prec = 3 - >>> Decimal("3.4445") + Decimal("1.0023") - Decimal("4.45") - >>> Decimal("3.4445") + Decimal(0) + Decimal("1.0023") - Decimal("4.44") - \end{verbatim} - -\end{methoddesc} - -\begin{methoddesc}{Etiny}{} - Returns a value equal to \samp{Emin - prec + 1} which is the minimum - exponent value for subnormal results. When underflow occurs, the - exponent is set to \constant{Etiny}. -\end{methoddesc} - -\begin{methoddesc}{Etop}{} - Returns a value equal to \samp{Emax - prec + 1}. -\end{methoddesc} - - -The usual approach to working with decimals is to create \class{Decimal} -instances and then apply arithmetic operations which take place within the -current context for the active thread. An alternate approach is to use -context methods for calculating within a specific context. The methods are -similar to those for the \class{Decimal} class and are only briefly recounted -here. - -\begin{methoddesc}{abs}{x} - Returns the absolute value of \var{x}. -\end{methoddesc} - -\begin{methoddesc}{add}{x, y} - Return the sum of \var{x} and \var{y}. -\end{methoddesc} - -\begin{methoddesc}{compare}{x, y} - Compares values numerically. - - Like \method{__cmp__()} but returns a decimal instance: - \begin{verbatim} - a or b is a NaN ==> Decimal("NaN") - a < b ==> Decimal("-1") - a == b ==> Decimal("0") - a > b ==> Decimal("1") - \end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{divide}{x, y} - Return \var{x} divided by \var{y}. -\end{methoddesc} - -\begin{methoddesc}{divmod}{x, y} - Divides two numbers and returns the integer part of the result. -\end{methoddesc} - -\begin{methoddesc}{max}{x, y} - Compare two values numerically and return the maximum. - - If they are numerically equal then the left-hand operand is chosen as the - result. -\end{methoddesc} - -\begin{methoddesc}{min}{x, y} - Compare two values numerically and return the minimum. - - If they are numerically equal then the left-hand operand is chosen as the - result. -\end{methoddesc} - -\begin{methoddesc}{minus}{x} - Minus corresponds to the unary prefix minus operator in Python. -\end{methoddesc} - -\begin{methoddesc}{multiply}{x, y} - Return the product of \var{x} and \var{y}. -\end{methoddesc} - -\begin{methoddesc}{normalize}{x} - Normalize reduces an operand to its simplest form. - - Essentially a \method{plus} operation with all trailing zeros removed from - the result. -\end{methoddesc} - -\begin{methoddesc}{plus}{x} - Plus corresponds to the unary prefix plus operator in Python. This - operation applies the context precision and rounding, so it is - \emph{not} an identity operation. -\end{methoddesc} - -\begin{methoddesc}{power}{x, y\optional{, modulo}} - Return \samp{x ** y} to the \var{modulo} if given. - - The right-hand operand must be a whole number whose integer part (after any - exponent has been applied) has no more than 9 digits and whose fractional - part (if any) is all zeros before any rounding. The operand may be positive, - negative, or zero; if negative, the absolute value of the power is used, and - the left-hand operand is inverted (divided into 1) before use. - - If the increased precision needed for the intermediate calculations exceeds - the capabilities of the implementation then an \constant{InvalidOperation} - condition is signaled. - - If, when raising to a negative power, an underflow occurs during the - division into 1, the operation is not halted at that point but continues. -\end{methoddesc} - -\begin{methoddesc}{quantize}{x, y} - Returns a value equal to \var{x} after rounding and having the exponent of - \var{y}. - - Unlike other operations, if the length of the coefficient after the quantize - operation would be greater than precision, then an - \constant{InvalidOperation} is signaled. This guarantees that, unless there - is an error condition, the quantized exponent is always equal to that of the - right-hand operand. - - Also unlike other operations, quantize never signals Underflow, even - if the result is subnormal and inexact. -\end{methoddesc} - -\begin{methoddesc}{remainder}{x, y} - Returns the remainder from integer division. - - The sign of the result, if non-zero, is the same as that of the original - dividend. -\end{methoddesc} - -\begin{methoddesc}{remainder_near}{x, y} - Computed the modulo as either a positive or negative value depending - on which is closest to zero. For instance, - \samp{Decimal(10).remainder_near(6)} returns \code{Decimal("-2")} - which is closer to zero than \code{Decimal("4")}. - - If both are equally close, the one chosen will have the same sign - as \var{self}. -\end{methoddesc} - -\begin{methoddesc}{same_quantum}{x, y} - Test whether \var{x} and \var{y} have the same exponent or whether both are - \constant{NaN}. -\end{methoddesc} - -\begin{methoddesc}{sqrt}{x} - Return the square root of \var{x} to full precision. -\end{methoddesc} - -\begin{methoddesc}{subtract}{x, y} - Return the difference between \var{x} and \var{y}. -\end{methoddesc} - -\begin{methoddesc}{to_eng_string}{} - Convert to engineering-type string. - - Engineering notation has an exponent which is a multiple of 3, so there - are up to 3 digits left of the decimal place. For example, converts - \code{Decimal('123E+1')} to \code{Decimal("1.23E+3")} -\end{methoddesc} - -\begin{methoddesc}{to_integral}{x} - Rounds to the nearest integer without signaling \constant{Inexact} - or \constant{Rounded}. -\end{methoddesc} - -\begin{methoddesc}{to_sci_string}{x} - Converts a number to a string using scientific notation. -\end{methoddesc} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Signals \label{decimal-signals}} - -Signals represent conditions that arise during computation. -Each corresponds to one context flag and one context trap enabler. - -The context flag is incremented whenever the condition is encountered. -After the computation, flags may be checked for informational -purposes (for instance, to determine whether a computation was exact). -After checking the flags, be sure to clear all flags before starting -the next computation. - -If the context's trap enabler is set for the signal, then the condition -causes a Python exception to be raised. For example, if the -\class{DivisionByZero} trap is set, then a \exception{DivisionByZero} -exception is raised upon encountering the condition. - - -\begin{classdesc*}{Clamped} - Altered an exponent to fit representation constraints. - - Typically, clamping occurs when an exponent falls outside the context's - \member{Emin} and \member{Emax} limits. If possible, the exponent is - reduced to fit by adding zeroes to the coefficient. -\end{classdesc*} - -\begin{classdesc*}{DecimalException} - Base class for other signals and a subclass of - \exception{ArithmeticError}. -\end{classdesc*} - -\begin{classdesc*}{DivisionByZero} - Signals the division of a non-infinite number by zero. - - Can occur with division, modulo division, or when raising a number to a - negative power. If this signal is not trapped, returns - \constant{Infinity} or \constant{-Infinity} with the sign determined by - the inputs to the calculation. -\end{classdesc*} - -\begin{classdesc*}{Inexact} - Indicates that rounding occurred and the result is not exact. - - Signals when non-zero digits were discarded during rounding. The rounded - result is returned. The signal flag or trap is used to detect when - results are inexact. -\end{classdesc*} - -\begin{classdesc*}{InvalidOperation} - An invalid operation was performed. - - Indicates that an operation was requested that does not make sense. - If not trapped, returns \constant{NaN}. Possible causes include: - - \begin{verbatim} - Infinity - Infinity - 0 * Infinity - Infinity / Infinity - x % 0 - Infinity % x - x._rescale( non-integer ) - sqrt(-x) and x > 0 - 0 ** 0 - x ** (non-integer) - x ** Infinity - \end{verbatim} -\end{classdesc*} - -\begin{classdesc*}{Overflow} - Numerical overflow. - - Indicates the exponent is larger than \member{Emax} after rounding has - occurred. If not trapped, the result depends on the rounding mode, either - pulling inward to the largest representable finite number or rounding - outward to \constant{Infinity}. In either case, \class{Inexact} and - \class{Rounded} are also signaled. -\end{classdesc*} - -\begin{classdesc*}{Rounded} - Rounding occurred though possibly no information was lost. - - Signaled whenever rounding discards digits; even if those digits are - zero (such as rounding \constant{5.00} to \constant{5.0}). If not - trapped, returns the result unchanged. This signal is used to detect - loss of significant digits. -\end{classdesc*} - -\begin{classdesc*}{Subnormal} - Exponent was lower than \member{Emin} prior to rounding. - - Occurs when an operation result is subnormal (the exponent is too small). - If not trapped, returns the result unchanged. -\end{classdesc*} - -\begin{classdesc*}{Underflow} - Numerical underflow with result rounded to zero. - - Occurs when a subnormal result is pushed to zero by rounding. - \class{Inexact} and \class{Subnormal} are also signaled. -\end{classdesc*} - -The following table summarizes the hierarchy of signals: - -\begin{verbatim} - exceptions.ArithmeticError(exceptions.Exception) - DecimalException - Clamped - DivisionByZero(DecimalException, exceptions.ZeroDivisionError) - Inexact - Overflow(Inexact, Rounded) - Underflow(Inexact, Rounded, Subnormal) - InvalidOperation - Rounded - Subnormal -\end{verbatim} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Floating Point Notes \label{decimal-notes}} - -\subsubsection{Mitigating round-off error with increased precision} - -The use of decimal floating point eliminates decimal representation error -(making it possible to represent \constant{0.1} exactly); however, some -operations can still incur round-off error when non-zero digits exceed the -fixed precision. - -The effects of round-off error can be amplified by the addition or subtraction -of nearly offsetting quantities resulting in loss of significance. Knuth -provides two instructive examples where rounded floating point arithmetic with -insufficient precision causes the breakdown of the associative and -distributive properties of addition: - -\begin{verbatim} -# Examples from Seminumerical Algorithms, Section 4.2.2. ->>> from decimal import Decimal, getcontext ->>> getcontext().prec = 8 - ->>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111') ->>> (u + v) + w -Decimal("9.5111111") ->>> u + (v + w) -Decimal("10") - ->>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003') ->>> (u*v) + (u*w) -Decimal("0.01") ->>> u * (v+w) -Decimal("0.0060000") -\end{verbatim} - -The \module{decimal} module makes it possible to restore the identities -by expanding the precision sufficiently to avoid loss of significance: - -\begin{verbatim} ->>> getcontext().prec = 20 ->>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111') ->>> (u + v) + w -Decimal("9.51111111") ->>> u + (v + w) -Decimal("9.51111111") ->>> ->>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003') ->>> (u*v) + (u*w) -Decimal("0.0060000") ->>> u * (v+w) -Decimal("0.0060000") -\end{verbatim} - -\subsubsection{Special values} - -The number system for the \module{decimal} module provides special -values including \constant{NaN}, \constant{sNaN}, \constant{-Infinity}, -\constant{Infinity}, and two zeroes, \constant{+0} and \constant{-0}. - -Infinities can be constructed directly with: \code{Decimal('Infinity')}. Also, -they can arise from dividing by zero when the \exception{DivisionByZero} -signal is not trapped. Likewise, when the \exception{Overflow} signal is not -trapped, infinity can result from rounding beyond the limits of the largest -representable number. - -The infinities are signed (affine) and can be used in arithmetic operations -where they get treated as very large, indeterminate numbers. For instance, -adding a constant to infinity gives another infinite result. - -Some operations are indeterminate and return \constant{NaN}, or if the -\exception{InvalidOperation} signal is trapped, raise an exception. For -example, \code{0/0} returns \constant{NaN} which means ``not a number''. This -variety of \constant{NaN} is quiet and, once created, will flow through other -computations always resulting in another \constant{NaN}. This behavior can be -useful for a series of computations that occasionally have missing inputs --- -it allows the calculation to proceed while flagging specific results as -invalid. - -A variant is \constant{sNaN} which signals rather than remaining quiet -after every operation. This is a useful return value when an invalid -result needs to interrupt a calculation for special handling. - -The signed zeros can result from calculations that underflow. -They keep the sign that would have resulted if the calculation had -been carried out to greater precision. Since their magnitude is -zero, both positive and negative zeros are treated as equal and their -sign is informational. - -In addition to the two signed zeros which are distinct yet equal, -there are various representations of zero with differing precisions -yet equivalent in value. This takes a bit of getting used to. For -an eye accustomed to normalized floating point representations, it -is not immediately obvious that the following calculation returns -a value equal to zero: - -\begin{verbatim} ->>> 1 / Decimal('Infinity') -Decimal("0E-1000000026") -\end{verbatim} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Working with threads \label{decimal-threads}} - -The \function{getcontext()} function accesses a different \class{Context} -object for each thread. Having separate thread contexts means that threads -may make changes (such as \code{getcontext.prec=10}) without interfering with -other threads. - -Likewise, the \function{setcontext()} function automatically assigns its target -to the current thread. - -If \function{setcontext()} has not been called before \function{getcontext()}, -then \function{getcontext()} will automatically create a new context for use -in the current thread. - -The new context is copied from a prototype context called -\var{DefaultContext}. To control the defaults so that each thread will use the -same values throughout the application, directly modify the -\var{DefaultContext} object. This should be done \emph{before} any threads are -started so that there won't be a race condition between threads calling -\function{getcontext()}. For example: - -\begin{verbatim} -# Set applicationwide defaults for all threads about to be launched -DefaultContext.prec = 12 -DefaultContext.rounding = ROUND_DOWN -DefaultContext.traps = ExtendedContext.traps.copy() -DefaultContext.traps[InvalidOperation] = 1 -setcontext(DefaultContext) - -# Afterwards, the threads can be started -t1.start() -t2.start() -t3.start() - . . . -\end{verbatim} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Recipes \label{decimal-recipes}} - -Here are a few recipes that serve as utility functions and that demonstrate -ways to work with the \class{Decimal} class: - -\begin{verbatim} -def moneyfmt(value, places=2, curr='', sep=',', dp='.', - pos='', neg='-', trailneg=''): - """Convert Decimal to a money formatted string. - - places: required number of places after the decimal point - curr: optional currency symbol before the sign (may be blank) - sep: optional grouping separator (comma, period, space, or blank) - dp: decimal point indicator (comma or period) - only specify as blank when places is zero - pos: optional sign for positive numbers: '+', space or blank - neg: optional sign for negative numbers: '-', '(', space or blank - trailneg:optional trailing minus indicator: '-', ')', space or blank - - >>> d = Decimal('-1234567.8901') - >>> moneyfmt(d, curr='$') - '-$1,234,567.89' - >>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-') - '1.234.568-' - >>> moneyfmt(d, curr='$', neg='(', trailneg=')') - '($1,234,567.89)' - >>> moneyfmt(Decimal(123456789), sep=' ') - '123 456 789.00' - >>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>') - '<.02>' - - """ - q = Decimal((0, (1,), -places)) # 2 places --> '0.01' - sign, digits, exp = value.quantize(q).as_tuple() - assert exp == -places - result = [] - digits = map(str, digits) - build, next = result.append, digits.pop - if sign: - build(trailneg) - for i in range(places): - if digits: - build(next()) - else: - build('0') - build(dp) - i = 0 - while digits: - build(next()) - i += 1 - if i == 3 and digits: - i = 0 - build(sep) - build(curr) - if sign: - build(neg) - else: - build(pos) - result.reverse() - return ''.join(result) - -def pi(): - """Compute Pi to the current precision. - - >>> print pi() - 3.141592653589793238462643383 - - """ - getcontext().prec += 2 # extra digits for intermediate steps - three = Decimal(3) # substitute "three=3.0" for regular floats - lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24 - while s != lasts: - lasts = s - n, na = n+na, na+8 - d, da = d+da, da+32 - t = (t * n) / d - s += t - getcontext().prec -= 2 - return +s # unary plus applies the new precision - -def exp(x): - """Return e raised to the power of x. Result type matches input type. - - >>> print exp(Decimal(1)) - 2.718281828459045235360287471 - >>> print exp(Decimal(2)) - 7.389056098930650227230427461 - >>> print exp(2.0) - 7.38905609893 - >>> print exp(2+0j) - (7.38905609893+0j) - - """ - getcontext().prec += 2 - i, lasts, s, fact, num = 0, 0, 1, 1, 1 - while s != lasts: - lasts = s - i += 1 - fact *= i - num *= x - s += num / fact - getcontext().prec -= 2 - return +s - -def cos(x): - """Return the cosine of x as measured in radians. - - >>> print cos(Decimal('0.5')) - 0.8775825618903727161162815826 - >>> print cos(0.5) - 0.87758256189 - >>> print cos(0.5+0j) - (0.87758256189+0j) - - """ - getcontext().prec += 2 - i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1 - while s != lasts: - lasts = s - i += 2 - fact *= i * (i-1) - num *= x * x - sign *= -1 - s += num / fact * sign - getcontext().prec -= 2 - return +s - -def sin(x): - """Return the sine of x as measured in radians. - - >>> print sin(Decimal('0.5')) - 0.4794255386042030002732879352 - >>> print sin(0.5) - 0.479425538604 - >>> print sin(0.5+0j) - (0.479425538604+0j) - - """ - getcontext().prec += 2 - i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1 - while s != lasts: - lasts = s - i += 2 - fact *= i * (i-1) - num *= x * x - sign *= -1 - s += num / fact * sign - getcontext().prec -= 2 - return +s - -\end{verbatim} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Decimal FAQ \label{decimal-faq}} - -Q. It is cumbersome to type \code{decimal.Decimal('1234.5')}. Is there a way -to minimize typing when using the interactive interpreter? - -A. Some users abbreviate the constructor to just a single letter: - -\begin{verbatim} ->>> D = decimal.Decimal ->>> D('1.23') + D('3.45') -Decimal("4.68") -\end{verbatim} - - -Q. In a fixed-point application with two decimal places, some inputs -have many places and need to be rounded. Others are not supposed to have -excess digits and need to be validated. What methods should be used? - -A. The \method{quantize()} method rounds to a fixed number of decimal places. -If the \constant{Inexact} trap is set, it is also useful for validation: - -\begin{verbatim} ->>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01') - ->>> # Round to two places ->>> Decimal("3.214").quantize(TWOPLACES) -Decimal("3.21") - ->>> # Validate that a number does not exceed two places ->>> Decimal("3.21").quantize(TWOPLACES, context=Context(traps=[Inexact])) -Decimal("3.21") - ->>> Decimal("3.214").quantize(TWOPLACES, context=Context(traps=[Inexact])) -Traceback (most recent call last): - ... -Inexact: Changed in rounding -\end{verbatim} - - -Q. Once I have valid two place inputs, how do I maintain that invariant -throughout an application? - -A. Some operations like addition and subtraction automatically preserve fixed -point. Others, like multiplication and division, change the number of decimal -places and need to be followed-up with a \method{quantize()} step. - - -Q. There are many ways to express the same value. The numbers -\constant{200}, \constant{200.000}, \constant{2E2}, and \constant{.02E+4} all -have the same value at various precisions. Is there a way to transform them to -a single recognizable canonical value? - -A. The \method{normalize()} method maps all equivalent values to a single -representative: - -\begin{verbatim} ->>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split()) ->>> [v.normalize() for v in values] -[Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2"), Decimal("2E+2")] -\end{verbatim} - - -Q. Some decimal values always print with exponential notation. Is there -a way to get a non-exponential representation? - -A. For some values, exponential notation is the only way to express -the number of significant places in the coefficient. For example, -expressing \constant{5.0E+3} as \constant{5000} keeps the value -constant but cannot show the original's two-place significance. - - -Q. Is there a way to convert a regular float to a \class{Decimal}? - -A. Yes, all binary floating point numbers can be exactly expressed as a -Decimal. An exact conversion may take more precision than intuition would -suggest, so trapping \constant{Inexact} will signal a need for more precision: - -\begin{verbatim} -def floatToDecimal(f): - "Convert a floating point number to a Decimal with no loss of information" - # Transform (exactly) a float to a mantissa (0.5 <= abs(m) < 1.0) and an - # exponent. Double the mantissa until it is an integer. Use the integer - # mantissa and exponent to compute an equivalent Decimal. If this cannot - # be done exactly, then retry with more precision. - - mantissa, exponent = math.frexp(f) - while mantissa != int(mantissa): - mantissa *= 2.0 - exponent -= 1 - mantissa = int(mantissa) - - oldcontext = getcontext() - setcontext(Context(traps=[Inexact])) - try: - while True: - try: - return mantissa * Decimal(2) ** exponent - except Inexact: - getcontext().prec += 1 - finally: - setcontext(oldcontext) -\end{verbatim} - - -Q. Why isn't the \function{floatToDecimal()} routine included in the module? - -A. There is some question about whether it is advisable to mix binary and -decimal floating point. Also, its use requires some care to avoid the -representation issues associated with binary floating point: - -\begin{verbatim} ->>> floatToDecimal(1.1) -Decimal("1.100000000000000088817841970012523233890533447265625") -\end{verbatim} - - -Q. Within a complex calculation, how can I make sure that I haven't gotten a -spurious result because of insufficient precision or rounding anomalies. - -A. The decimal module makes it easy to test results. A best practice is to -re-run calculations using greater precision and with various rounding modes. -Widely differing results indicate insufficient precision, rounding mode -issues, ill-conditioned inputs, or a numerically unstable algorithm. - - -Q. I noticed that context precision is applied to the results of operations -but not to the inputs. Is there anything to watch out for when mixing -values of different precisions? - -A. Yes. The principle is that all values are considered to be exact and so -is the arithmetic on those values. Only the results are rounded. The -advantage for inputs is that ``what you type is what you get''. A -disadvantage is that the results can look odd if you forget that the inputs -haven't been rounded: - -\begin{verbatim} ->>> getcontext().prec = 3 ->>> Decimal('3.104') + D('2.104') -Decimal("5.21") ->>> Decimal('3.104') + D('0.000') + D('2.104') -Decimal("5.20") -\end{verbatim} - -The solution is either to increase precision or to force rounding of inputs -using the unary plus operation: - -\begin{verbatim} ->>> getcontext().prec = 3 ->>> +Decimal('1.23456789') # unary plus triggers rounding -Decimal("1.23") -\end{verbatim} - -Alternatively, inputs can be rounded upon creation using the -\method{Context.create_decimal()} method: - -\begin{verbatim} ->>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678') -Decimal("1.2345") -\end{verbatim} diff --git a/Doc/lib/libdifflib.tex b/Doc/lib/libdifflib.tex deleted file mode 100644 index 7fb8e92..0000000 --- a/Doc/lib/libdifflib.tex +++ /dev/null @@ -1,704 +0,0 @@ -\section{\module{difflib} --- - Helpers for computing deltas} - -\declaremodule{standard}{difflib} -\modulesynopsis{Helpers for computing differences between objects.} -\moduleauthor{Tim Peters}{tim_one@users.sourceforge.net} -\sectionauthor{Tim Peters}{tim_one@users.sourceforge.net} -% LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>. - -\versionadded{2.1} - - -\begin{classdesc*}{SequenceMatcher} - This is a flexible class for comparing pairs of sequences of any - type, so long as the sequence elements are hashable. The basic - algorithm predates, and is a little fancier than, an algorithm - published in the late 1980's by Ratcliff and Obershelp under the - hyperbolic name ``gestalt pattern matching.'' The idea is to find - the longest contiguous matching subsequence that contains no - ``junk'' elements (the Ratcliff and Obershelp algorithm doesn't - address junk). The same idea is then applied recursively to the - pieces of the sequences to the left and to the right of the matching - subsequence. This does not yield minimal edit sequences, but does - tend to yield matches that ``look right'' to people. - - \strong{Timing:} The basic Ratcliff-Obershelp algorithm is cubic - time in the worst case and quadratic time in the expected case. - \class{SequenceMatcher} is quadratic time for the worst case and has - expected-case behavior dependent in a complicated way on how many - elements the sequences have in common; best case time is linear. -\end{classdesc*} - -\begin{classdesc*}{Differ} - This is a class for comparing sequences of lines of text, and - producing human-readable differences or deltas. Differ uses - \class{SequenceMatcher} both to compare sequences of lines, and to - compare sequences of characters within similar (near-matching) - lines. - - Each line of a \class{Differ} delta begins with a two-letter code: - -\begin{tableii}{l|l}{code}{Code}{Meaning} - \lineii{'- '}{line unique to sequence 1} - \lineii{'+ '}{line unique to sequence 2} - \lineii{' '}{line common to both sequences} - \lineii{'? '}{line not present in either input sequence} -\end{tableii} - - Lines beginning with `\code{?~}' attempt to guide the eye to - intraline differences, and were not present in either input - sequence. These lines can be confusing if the sequences contain tab - characters. -\end{classdesc*} - -\begin{classdesc*}{HtmlDiff} - - This class can be used to create an HTML table (or a complete HTML file - containing the table) showing a side by side, line by line comparison - of text with inter-line and intra-line change highlights. The table can - be generated in either full or contextual difference mode. - - The constructor for this class is: - - \begin{funcdesc}{__init__}{\optional{tabsize}\optional{, - wrapcolumn}\optional{, linejunk}\optional{, charjunk}} - - Initializes instance of \class{HtmlDiff}. - - \var{tabsize} is an optional keyword argument to specify tab stop spacing - and defaults to \code{8}. - - \var{wrapcolumn} is an optional keyword to specify column number where - lines are broken and wrapped, defaults to \code{None} where lines are not - wrapped. - - \var{linejunk} and \var{charjunk} are optional keyword arguments passed - into \code{ndiff()} (used by \class{HtmlDiff} to generate the - side by side HTML differences). See \code{ndiff()} documentation for - argument default values and descriptions. - - \end{funcdesc} - - The following methods are public: - - \begin{funcdesc}{make_file}{fromlines, tolines - \optional{, fromdesc}\optional{, todesc}\optional{, context}\optional{, - numlines}} - Compares \var{fromlines} and \var{tolines} (lists of strings) and returns - a string which is a complete HTML file containing a table showing line by - line differences with inter-line and intra-line changes highlighted. - - \var{fromdesc} and \var{todesc} are optional keyword arguments to specify - from/to file column header strings (both default to an empty string). - - \var{context} and \var{numlines} are both optional keyword arguments. - Set \var{context} to \code{True} when contextual differences are to be - shown, else the default is \code{False} to show the full files. - \var{numlines} defaults to \code{5}. When \var{context} is \code{True} - \var{numlines} controls the number of context lines which surround the - difference highlights. When \var{context} is \code{False} \var{numlines} - controls the number of lines which are shown before a difference - highlight when using the "next" hyperlinks (setting to zero would cause - the "next" hyperlinks to place the next difference highlight at the top of - the browser without any leading context). - \end{funcdesc} - - \begin{funcdesc}{make_table}{fromlines, tolines - \optional{, fromdesc}\optional{, todesc}\optional{, context}\optional{, - numlines}} - Compares \var{fromlines} and \var{tolines} (lists of strings) and returns - a string which is a complete HTML table showing line by line differences - with inter-line and intra-line changes highlighted. - - The arguments for this method are the same as those for the - \method{make_file()} method. - \end{funcdesc} - - \file{Tools/scripts/diff.py} is a command-line front-end to this class - and contains a good example of its use. - - \versionadded{2.4} -\end{classdesc*} - -\begin{funcdesc}{context_diff}{a, b\optional{, fromfile}\optional{, - tofile}\optional{, fromfiledate}\optional{, tofiledate}\optional{, - n}\optional{, lineterm}} - Compare \var{a} and \var{b} (lists of strings); return a - delta (a generator generating the delta lines) in context diff - format. - - Context diffs are a compact way of showing just the lines that have - changed plus a few lines of context. The changes are shown in a - before/after style. The number of context lines is set by \var{n} - which defaults to three. - - By default, the diff control lines (those with \code{***} or \code{---}) - are created with a trailing newline. This is helpful so that inputs created - from \function{file.readlines()} result in diffs that are suitable for use - with \function{file.writelines()} since both the inputs and outputs have - trailing newlines. - - For inputs that do not have trailing newlines, set the \var{lineterm} - argument to \code{""} so that the output will be uniformly newline free. - - The context diff format normally has a header for filenames and - modification times. Any or all of these may be specified using strings for - \var{fromfile}, \var{tofile}, \var{fromfiledate}, and \var{tofiledate}. - The modification times are normally expressed in the format returned by - \function{time.ctime()}. If not specified, the strings default to blanks. - - \file{Tools/scripts/diff.py} is a command-line front-end for this - function. - - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{get_close_matches}{word, possibilities\optional{, - n}\optional{, cutoff}} - Return a list of the best ``good enough'' matches. \var{word} is a - sequence for which close matches are desired (typically a string), - and \var{possibilities} is a list of sequences against which to - match \var{word} (typically a list of strings). - - Optional argument \var{n} (default \code{3}) is the maximum number - of close matches to return; \var{n} must be greater than \code{0}. - - Optional argument \var{cutoff} (default \code{0.6}) is a float in - the range [0, 1]. Possibilities that don't score at least that - similar to \var{word} are ignored. - - The best (no more than \var{n}) matches among the possibilities are - returned in a list, sorted by similarity score, most similar first. - -\begin{verbatim} ->>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy']) -['apple', 'ape'] ->>> import keyword ->>> get_close_matches('wheel', keyword.kwlist) -['while'] ->>> get_close_matches('apple', keyword.kwlist) -[] ->>> get_close_matches('accept', keyword.kwlist) -['except'] -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{ndiff}{a, b\optional{, linejunk}\optional{, charjunk}} - Compare \var{a} and \var{b} (lists of strings); return a - \class{Differ}-style delta (a generator generating the delta lines). - - Optional keyword parameters \var{linejunk} and \var{charjunk} are - for filter functions (or \code{None}): - - \var{linejunk}: A function that accepts a single string - argument, and returns true if the string is junk, or false if not. - The default is (\code{None}), starting with Python 2.3. Before then, - the default was the module-level function - \function{IS_LINE_JUNK()}, which filters out lines without visible - characters, except for at most one pound character (\character{\#}). - As of Python 2.3, the underlying \class{SequenceMatcher} class - does a dynamic analysis of which lines are so frequent as to - constitute noise, and this usually works better than the pre-2.3 - default. - - \var{charjunk}: A function that accepts a character (a string of - length 1), and returns if the character is junk, or false if not. - The default is module-level function \function{IS_CHARACTER_JUNK()}, - which filters out whitespace characters (a blank or tab; note: bad - idea to include newline in this!). - - \file{Tools/scripts/ndiff.py} is a command-line front-end to this - function. - -\begin{verbatim} ->>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1), -... 'ore\ntree\nemu\n'.splitlines(1)) ->>> print ''.join(diff), -- one -? ^ -+ ore -? ^ -- two -- three -? - -+ tree -+ emu -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{restore}{sequence, which} - Return one of the two sequences that generated a delta. - - Given a \var{sequence} produced by \method{Differ.compare()} or - \function{ndiff()}, extract lines originating from file 1 or 2 - (parameter \var{which}), stripping off line prefixes. - - Example: - -\begin{verbatim} ->>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1), -... 'ore\ntree\nemu\n'.splitlines(1)) ->>> diff = list(diff) # materialize the generated delta into a list ->>> print ''.join(restore(diff, 1)), -one -two -three ->>> print ''.join(restore(diff, 2)), -ore -tree -emu -\end{verbatim} - -\end{funcdesc} - -\begin{funcdesc}{unified_diff}{a, b\optional{, fromfile}\optional{, - tofile}\optional{, fromfiledate}\optional{, tofiledate}\optional{, - n}\optional{, lineterm}} - Compare \var{a} and \var{b} (lists of strings); return a - delta (a generator generating the delta lines) in unified diff - format. - - Unified diffs are a compact way of showing just the lines that have - changed plus a few lines of context. The changes are shown in a - inline style (instead of separate before/after blocks). The number - of context lines is set by \var{n} which defaults to three. - - By default, the diff control lines (those with \code{---}, \code{+++}, - or \code{@@}) are created with a trailing newline. This is helpful so - that inputs created from \function{file.readlines()} result in diffs - that are suitable for use with \function{file.writelines()} since both - the inputs and outputs have trailing newlines. - - For inputs that do not have trailing newlines, set the \var{lineterm} - argument to \code{""} so that the output will be uniformly newline free. - - The context diff format normally has a header for filenames and - modification times. Any or all of these may be specified using strings for - \var{fromfile}, \var{tofile}, \var{fromfiledate}, and \var{tofiledate}. - The modification times are normally expressed in the format returned by - \function{time.ctime()}. If not specified, the strings default to blanks. - - \file{Tools/scripts/diff.py} is a command-line front-end for this - function. - - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{IS_LINE_JUNK}{line} - Return true for ignorable lines. The line \var{line} is ignorable - if \var{line} is blank or contains a single \character{\#}, - otherwise it is not ignorable. Used as a default for parameter - \var{linejunk} in \function{ndiff()} before Python 2.3. -\end{funcdesc} - - -\begin{funcdesc}{IS_CHARACTER_JUNK}{ch} - Return true for ignorable characters. The character \var{ch} is - ignorable if \var{ch} is a space or tab, otherwise it is not - ignorable. Used as a default for parameter \var{charjunk} in - \function{ndiff()}. -\end{funcdesc} - - -\begin{seealso} - \seetitle[http://www.ddj.com/184407970?pgno=5] - {Pattern Matching: The Gestalt Approach}{Discussion of a - similar algorithm by John W. Ratcliff and D. E. Metzener. - This was published in - \citetitle[http://www.ddj.com/]{Dr. Dobb's Journal} in - July, 1988.} -\end{seealso} - - -\subsection{SequenceMatcher Objects \label{sequence-matcher}} - -The \class{SequenceMatcher} class has this constructor: - -\begin{classdesc}{SequenceMatcher}{\optional{isjunk\optional{, - a\optional{, b}}}} - Optional argument \var{isjunk} must be \code{None} (the default) or - a one-argument function that takes a sequence element and returns - true if and only if the element is ``junk'' and should be ignored. - Passing \code{None} for \var{isjunk} is equivalent to passing - \code{lambda x: 0}; in other words, no elements are ignored. For - example, pass: - -\begin{verbatim} -lambda x: x in " \t" -\end{verbatim} - - if you're comparing lines as sequences of characters, and don't want - to synch up on blanks or hard tabs. - - The optional arguments \var{a} and \var{b} are sequences to be - compared; both default to empty strings. The elements of both - sequences must be hashable. -\end{classdesc} - - -\class{SequenceMatcher} objects have the following methods: - -\begin{methoddesc}{set_seqs}{a, b} - Set the two sequences to be compared. -\end{methoddesc} - -\class{SequenceMatcher} computes and caches detailed information about -the second sequence, so if you want to compare one sequence against -many sequences, use \method{set_seq2()} to set the commonly used -sequence once and call \method{set_seq1()} repeatedly, once for each -of the other sequences. - -\begin{methoddesc}{set_seq1}{a} - Set the first sequence to be compared. The second sequence to be - compared is not changed. -\end{methoddesc} - -\begin{methoddesc}{set_seq2}{b} - Set the second sequence to be compared. The first sequence to be - compared is not changed. -\end{methoddesc} - -\begin{methoddesc}{find_longest_match}{alo, ahi, blo, bhi} - Find longest matching block in \code{\var{a}[\var{alo}:\var{ahi}]} - and \code{\var{b}[\var{blo}:\var{bhi}]}. - - If \var{isjunk} was omitted or \code{None}, - \method{get_longest_match()} returns \code{(\var{i}, \var{j}, - \var{k})} such that \code{\var{a}[\var{i}:\var{i}+\var{k}]} is equal - to \code{\var{b}[\var{j}:\var{j}+\var{k}]}, where - \code{\var{alo} <= \var{i} <= \var{i}+\var{k} <= \var{ahi}} and - \code{\var{blo} <= \var{j} <= \var{j}+\var{k} <= \var{bhi}}. - For all \code{(\var{i'}, \var{j'}, \var{k'})} meeting those - conditions, the additional conditions - \code{\var{k} >= \var{k'}}, - \code{\var{i} <= \var{i'}}, - and if \code{\var{i} == \var{i'}}, \code{\var{j} <= \var{j'}} - are also met. - In other words, of all maximal matching blocks, return one that - starts earliest in \var{a}, and of all those maximal matching blocks - that start earliest in \var{a}, return the one that starts earliest - in \var{b}. - -\begin{verbatim} ->>> s = SequenceMatcher(None, " abcd", "abcd abcd") ->>> s.find_longest_match(0, 5, 0, 9) -(0, 4, 5) -\end{verbatim} - - If \var{isjunk} was provided, first the longest matching block is - determined as above, but with the additional restriction that no - junk element appears in the block. Then that block is extended as - far as possible by matching (only) junk elements on both sides. - So the resulting block never matches on junk except as identical - junk happens to be adjacent to an interesting match. - - Here's the same example as before, but considering blanks to be junk. - That prevents \code{' abcd'} from matching the \code{' abcd'} at the - tail end of the second sequence directly. Instead only the - \code{'abcd'} can match, and matches the leftmost \code{'abcd'} in - the second sequence: - -\begin{verbatim} ->>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd") ->>> s.find_longest_match(0, 5, 0, 9) -(1, 0, 4) -\end{verbatim} - - If no blocks match, this returns \code{(\var{alo}, \var{blo}, 0)}. -\end{methoddesc} - -\begin{methoddesc}{get_matching_blocks}{} - Return list of triples describing matching subsequences. - Each triple is of the form \code{(\var{i}, \var{j}, \var{n})}, and - means that \code{\var{a}[\var{i}:\var{i}+\var{n}] == - \var{b}[\var{j}:\var{j}+\var{n}]}. The triples are monotonically - increasing in \var{i} and \var{j}. - - The last triple is a dummy, and has the value \code{(len(\var{a}), - len(\var{b}), 0)}. It is the only triple with \code{\var{n} == 0}. - % Explain why a dummy is used! - - If - \code{(\var{i}, \var{j}, \var{n})} and - \code{(\var{i'}, \var{j'}, \var{n'})} are adjacent triples in the list, - and the second is not the last triple in the list, then - \code{\var{i}+\var{n} != \var{i'}} or - \code{\var{j}+\var{n} != \var{j'}}; in other words, adjacent triples - always describe non-adjacent equal blocks. - \versionchanged[The guarantee that adjacent triples always describe - non-adjacent blocks was implemented]{2.5} - -\begin{verbatim} ->>> s = SequenceMatcher(None, "abxcd", "abcd") ->>> s.get_matching_blocks() -[(0, 0, 2), (3, 2, 2), (5, 4, 0)] -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{get_opcodes}{} - Return list of 5-tuples describing how to turn \var{a} into \var{b}. - Each tuple is of the form \code{(\var{tag}, \var{i1}, \var{i2}, - \var{j1}, \var{j2})}. The first tuple has \code{\var{i1} == - \var{j1} == 0}, and remaining tuples have \var{i1} equal to the - \var{i2} from the preceding tuple, and, likewise, \var{j1} equal to - the previous \var{j2}. - - The \var{tag} values are strings, with these meanings: - -\begin{tableii}{l|l}{code}{Value}{Meaning} - \lineii{'replace'}{\code{\var{a}[\var{i1}:\var{i2}]} should be - replaced by \code{\var{b}[\var{j1}:\var{j2}]}.} - \lineii{'delete'}{\code{\var{a}[\var{i1}:\var{i2}]} should be - deleted. Note that \code{\var{j1} == \var{j2}} in - this case.} - \lineii{'insert'}{\code{\var{b}[\var{j1}:\var{j2}]} should be - inserted at \code{\var{a}[\var{i1}:\var{i1}]}. - Note that \code{\var{i1} == \var{i2}} in this - case.} - \lineii{'equal'}{\code{\var{a}[\var{i1}:\var{i2}] == - \var{b}[\var{j1}:\var{j2}]} (the sub-sequences are - equal).} -\end{tableii} - -For example: - -\begin{verbatim} ->>> a = "qabxcd" ->>> b = "abycdf" ->>> s = SequenceMatcher(None, a, b) ->>> for tag, i1, i2, j1, j2 in s.get_opcodes(): -... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" % -... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2])) - delete a[0:1] (q) b[0:0] () - equal a[1:3] (ab) b[0:2] (ab) -replace a[3:4] (x) b[2:3] (y) - equal a[4:6] (cd) b[3:5] (cd) - insert a[6:6] () b[5:6] (f) -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}{get_grouped_opcodes}{\optional{n}} - Return a generator of groups with up to \var{n} lines of context. - - Starting with the groups returned by \method{get_opcodes()}, - this method splits out smaller change clusters and eliminates - intervening ranges which have no changes. - - The groups are returned in the same format as \method{get_opcodes()}. - \versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}{ratio}{} - Return a measure of the sequences' similarity as a float in the - range [0, 1]. - - Where T is the total number of elements in both sequences, and M is - the number of matches, this is 2.0*M / T. Note that this is - \code{1.0} if the sequences are identical, and \code{0.0} if they - have nothing in common. - - This is expensive to compute if \method{get_matching_blocks()} or - \method{get_opcodes()} hasn't already been called, in which case you - may want to try \method{quick_ratio()} or - \method{real_quick_ratio()} first to get an upper bound. -\end{methoddesc} - -\begin{methoddesc}{quick_ratio}{} - Return an upper bound on \method{ratio()} relatively quickly. - - This isn't defined beyond that it is an upper bound on - \method{ratio()}, and is faster to compute. -\end{methoddesc} - -\begin{methoddesc}{real_quick_ratio}{} - Return an upper bound on \method{ratio()} very quickly. - - This isn't defined beyond that it is an upper bound on - \method{ratio()}, and is faster to compute than either - \method{ratio()} or \method{quick_ratio()}. -\end{methoddesc} - -The three methods that return the ratio of matching to total characters -can give different results due to differing levels of approximation, -although \method{quick_ratio()} and \method{real_quick_ratio()} are always -at least as large as \method{ratio()}: - -\begin{verbatim} ->>> s = SequenceMatcher(None, "abcd", "bcde") ->>> s.ratio() -0.75 ->>> s.quick_ratio() -0.75 ->>> s.real_quick_ratio() -1.0 -\end{verbatim} - - -\subsection{SequenceMatcher Examples \label{sequencematcher-examples}} - - -This example compares two strings, considering blanks to be ``junk:'' - -\begin{verbatim} ->>> s = SequenceMatcher(lambda x: x == " ", -... "private Thread currentThread;", -... "private volatile Thread currentThread;") -\end{verbatim} - -\method{ratio()} returns a float in [0, 1], measuring the similarity -of the sequences. As a rule of thumb, a \method{ratio()} value over -0.6 means the sequences are close matches: - -\begin{verbatim} ->>> print round(s.ratio(), 3) -0.866 -\end{verbatim} - -If you're only interested in where the sequences match, -\method{get_matching_blocks()} is handy: - -\begin{verbatim} ->>> for block in s.get_matching_blocks(): -... print "a[%d] and b[%d] match for %d elements" % block -a[0] and b[0] match for 8 elements -a[8] and b[17] match for 6 elements -a[14] and b[23] match for 15 elements -a[29] and b[38] match for 0 elements -\end{verbatim} - -Note that the last tuple returned by \method{get_matching_blocks()} is -always a dummy, \code{(len(\var{a}), len(\var{b}), 0)}, and this is -the only case in which the last tuple element (number of elements -matched) is \code{0}. - -If you want to know how to change the first sequence into the second, -use \method{get_opcodes()}: - -\begin{verbatim} ->>> for opcode in s.get_opcodes(): -... print "%6s a[%d:%d] b[%d:%d]" % opcode - equal a[0:8] b[0:8] -insert a[8:8] b[8:17] - equal a[8:14] b[17:23] - equal a[14:29] b[23:38] -\end{verbatim} - -See also the function \function{get_close_matches()} in this module, -which shows how simple code building on \class{SequenceMatcher} can be -used to do useful work. - - -\subsection{Differ Objects \label{differ-objects}} - -Note that \class{Differ}-generated deltas make no claim to be -\strong{minimal} diffs. To the contrary, minimal diffs are often -counter-intuitive, because they synch up anywhere possible, sometimes -accidental matches 100 pages apart. Restricting synch points to -contiguous matches preserves some notion of locality, at the -occasional cost of producing a longer diff. - -The \class{Differ} class has this constructor: - -\begin{classdesc}{Differ}{\optional{linejunk\optional{, charjunk}}} - Optional keyword parameters \var{linejunk} and \var{charjunk} are - for filter functions (or \code{None}): - - \var{linejunk}: A function that accepts a single string - argument, and returns true if the string is junk. The default is - \code{None}, meaning that no line is considered junk. - - \var{charjunk}: A function that accepts a single character argument - (a string of length 1), and returns true if the character is junk. - The default is \code{None}, meaning that no character is - considered junk. -\end{classdesc} - -\class{Differ} objects are used (deltas generated) via a single -method: - -\begin{methoddesc}{compare}{a, b} - Compare two sequences of lines, and generate the delta (a sequence - of lines). - - Each sequence must contain individual single-line strings ending - with newlines. Such sequences can be obtained from the - \method{readlines()} method of file-like objects. The delta generated - also consists of newline-terminated strings, ready to be printed as-is - via the \method{writelines()} method of a file-like object. -\end{methoddesc} - - -\subsection{Differ Example \label{differ-examples}} - -This example compares two texts. First we set up the texts, sequences -of individual single-line strings ending with newlines (such sequences -can also be obtained from the \method{readlines()} method of file-like -objects): - -\begin{verbatim} ->>> text1 = ''' 1. Beautiful is better than ugly. -... 2. Explicit is better than implicit. -... 3. Simple is better than complex. -... 4. Complex is better than complicated. -... '''.splitlines(1) ->>> len(text1) -4 ->>> text1[0][-1] -'\n' ->>> text2 = ''' 1. Beautiful is better than ugly. -... 3. Simple is better than complex. -... 4. Complicated is better than complex. -... 5. Flat is better than nested. -... '''.splitlines(1) -\end{verbatim} - -Next we instantiate a Differ object: - -\begin{verbatim} ->>> d = Differ() -\end{verbatim} - -Note that when instantiating a \class{Differ} object we may pass -functions to filter out line and character ``junk.'' See the -\method{Differ()} constructor for details. - -Finally, we compare the two: - -\begin{verbatim} ->>> result = list(d.compare(text1, text2)) -\end{verbatim} - -\code{result} is a list of strings, so let's pretty-print it: - -\begin{verbatim} ->>> from pprint import pprint ->>> pprint(result) -[' 1. Beautiful is better than ugly.\n', - '- 2. Explicit is better than implicit.\n', - '- 3. Simple is better than complex.\n', - '+ 3. Simple is better than complex.\n', - '? ++ \n', - '- 4. Complex is better than complicated.\n', - '? ^ ---- ^ \n', - '+ 4. Complicated is better than complex.\n', - '? ++++ ^ ^ \n', - '+ 5. Flat is better than nested.\n'] -\end{verbatim} - -As a single multi-line string it looks like this: - -\begin{verbatim} ->>> import sys ->>> sys.stdout.writelines(result) - 1. Beautiful is better than ugly. -- 2. Explicit is better than implicit. -- 3. Simple is better than complex. -+ 3. Simple is better than complex. -? ++ -- 4. Complex is better than complicated. -? ^ ---- ^ -+ 4. Complicated is better than complex. -? ++++ ^ ^ -+ 5. Flat is better than nested. -\end{verbatim} diff --git a/Doc/lib/libdircache.tex b/Doc/lib/libdircache.tex deleted file mode 100644 index 5884549..0000000 --- a/Doc/lib/libdircache.tex +++ /dev/null @@ -1,49 +0,0 @@ -\section{\module{dircache} --- - Cached directory listings} - -\declaremodule{standard}{dircache} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Return directory listing, with cache mechanism.} - -The \module{dircache} module defines a function for reading directory listing -using a cache, and cache invalidation using the \var{mtime} of the directory. -Additionally, it defines a function to annotate directories by appending -a slash. - -The \module{dircache} module defines the following functions: - -\begin{funcdesc}{reset}{} -Resets the directory cache. -\end{funcdesc} - -\begin{funcdesc}{listdir}{path} -Return a directory listing of \var{path}, as gotten from -\function{os.listdir()}. Note that unless \var{path} changes, further call -to \function{listdir()} will not re-read the directory structure. - -Note that the list returned should be regarded as read-only. (Perhaps -a future version should change it to return a tuple?) -\end{funcdesc} - -\begin{funcdesc}{opendir}{path} -Same as \function{listdir()}. Defined for backwards compatibility. -\end{funcdesc} - -\begin{funcdesc}{annotate}{head, list} -Assume \var{list} is a list of paths relative to \var{head}, and append, -in place, a \character{/} to each path which points to a directory. -\end{funcdesc} - -\begin{verbatim} ->>> import dircache ->>> a = dircache.listdir('/') ->>> a = a[:] # Copy the return value so we can change 'a' ->>> a -['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+ -found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz'] ->>> dircache.annotate('/', a) ->>> a -['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/ -', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm -linuz'] -\end{verbatim} diff --git a/Doc/lib/libdis.tex b/Doc/lib/libdis.tex deleted file mode 100644 index 2d78d9a..0000000 --- a/Doc/lib/libdis.tex +++ /dev/null @@ -1,674 +0,0 @@ -\section{\module{dis} --- - Disassembler for Python byte code} - -\declaremodule{standard}{dis} -\modulesynopsis{Disassembler for Python byte code.} - - -The \module{dis} module supports the analysis of Python byte code by -disassembling it. Since there is no Python assembler, this module -defines the Python assembly language. The Python byte code which -this module takes as an input is defined in the file -\file{Include/opcode.h} and used by the compiler and the interpreter. - -Example: Given the function \function{myfunc}: - -\begin{verbatim} -def myfunc(alist): - return len(alist) -\end{verbatim} - -the following command can be used to get the disassembly of -\function{myfunc()}: - -\begin{verbatim} ->>> dis.dis(myfunc) - 2 0 LOAD_GLOBAL 0 (len) - 3 LOAD_FAST 0 (alist) - 6 CALL_FUNCTION 1 - 9 RETURN_VALUE -\end{verbatim} - -(The ``2'' is a line number). - -The \module{dis} module defines the following functions and constants: - -\begin{funcdesc}{dis}{\optional{bytesource}} -Disassemble the \var{bytesource} object. \var{bytesource} can denote -either a module, a class, a method, a function, or a code object. -For a module, it disassembles all functions. For a class, -it disassembles all methods. For a single code sequence, it prints -one line per byte code instruction. If no object is provided, it -disassembles the last traceback. -\end{funcdesc} - -\begin{funcdesc}{distb}{\optional{tb}} -Disassembles the top-of-stack function of a traceback, using the last -traceback if none was passed. The instruction causing the exception -is indicated. -\end{funcdesc} - -\begin{funcdesc}{disassemble}{code\optional{, lasti}} -Disassembles a code object, indicating the last instruction if \var{lasti} -was provided. The output is divided in the following columns: - -\begin{enumerate} -\item the line number, for the first instruction of each line -\item the current instruction, indicated as \samp{-->}, -\item a labelled instruction, indicated with \samp{>>}, -\item the address of the instruction, -\item the operation code name, -\item operation parameters, and -\item interpretation of the parameters in parentheses. -\end{enumerate} - -The parameter interpretation recognizes local and global -variable names, constant values, branch targets, and compare -operators. -\end{funcdesc} - -\begin{funcdesc}{disco}{code\optional{, lasti}} -A synonym for disassemble. It is more convenient to type, and kept -for compatibility with earlier Python releases. -\end{funcdesc} - -\begin{datadesc}{opname} -Sequence of operation names, indexable using the byte code. -\end{datadesc} - -\begin{datadesc}{opmap} -Dictionary mapping byte codes to operation names. -\end{datadesc} - -\begin{datadesc}{cmp_op} -Sequence of all compare operation names. -\end{datadesc} - -\begin{datadesc}{hasconst} -Sequence of byte codes that have a constant parameter. -\end{datadesc} - -\begin{datadesc}{hasfree} -Sequence of byte codes that access a free variable. -\end{datadesc} - -\begin{datadesc}{hasname} -Sequence of byte codes that access an attribute by name. -\end{datadesc} - -\begin{datadesc}{hasjrel} -Sequence of byte codes that have a relative jump target. -\end{datadesc} - -\begin{datadesc}{hasjabs} -Sequence of byte codes that have an absolute jump target. -\end{datadesc} - -\begin{datadesc}{haslocal} -Sequence of byte codes that access a local variable. -\end{datadesc} - -\begin{datadesc}{hascompare} -Sequence of byte codes of Boolean operations. -\end{datadesc} - -\subsection{Python Byte Code Instructions} -\label{bytecodes} - -The Python compiler currently generates the following byte code -instructions. - -\setindexsubitem{(byte code insns)} - -\begin{opcodedesc}{STOP_CODE}{} -Indicates end-of-code to the compiler, not used by the interpreter. -\end{opcodedesc} - -\begin{opcodedesc}{NOP}{} -Do nothing code. Used as a placeholder by the bytecode optimizer. -\end{opcodedesc} - -\begin{opcodedesc}{POP_TOP}{} -Removes the top-of-stack (TOS) item. -\end{opcodedesc} - -\begin{opcodedesc}{ROT_TWO}{} -Swaps the two top-most stack items. -\end{opcodedesc} - -\begin{opcodedesc}{ROT_THREE}{} -Lifts second and third stack item one position up, moves top down -to position three. -\end{opcodedesc} - -\begin{opcodedesc}{ROT_FOUR}{} -Lifts second, third and forth stack item one position up, moves top down to -position four. -\end{opcodedesc} - -\begin{opcodedesc}{DUP_TOP}{} -Duplicates the reference on top of the stack. -\end{opcodedesc} - -Unary Operations take the top of the stack, apply the operation, and -push the result back on the stack. - -\begin{opcodedesc}{UNARY_POSITIVE}{} -Implements \code{TOS = +TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{UNARY_NEGATIVE}{} -Implements \code{TOS = -TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{UNARY_NOT}{} -Implements \code{TOS = not TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{UNARY_INVERT}{} -Implements \code{TOS = \~{}TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{GET_ITER}{} -Implements \code{TOS = iter(TOS)}. -\end{opcodedesc} - -Binary operations remove the top of the stack (TOS) and the second top-most -stack item (TOS1) from the stack. They perform the operation, and put the -result back on the stack. - -\begin{opcodedesc}{BINARY_POWER}{} -Implements \code{TOS = TOS1 ** TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_MULTIPLY}{} -Implements \code{TOS = TOS1 * TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_FLOOR_DIVIDE}{} -Implements \code{TOS = TOS1 // TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_TRUE_DIVIDE}{} -Implements \code{TOS = TOS1 / TOS} when -\code{from __future__ import division} is in effect. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_MODULO}{} -Implements \code{TOS = TOS1 \%{} TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_ADD}{} -Implements \code{TOS = TOS1 + TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_SUBTRACT}{} -Implements \code{TOS = TOS1 - TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_SUBSCR}{} -Implements \code{TOS = TOS1[TOS]}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_LSHIFT}{} -Implements \code{TOS = TOS1 <\code{}< TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_RSHIFT}{} -Implements \code{TOS = TOS1 >\code{}> TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_AND}{} -Implements \code{TOS = TOS1 \&\ TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_XOR}{} -Implements \code{TOS = TOS1 \^\ TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{BINARY_OR}{} -Implements \code{TOS = TOS1 | TOS}. -\end{opcodedesc} - -In-place operations are like binary operations, in that they remove TOS and -TOS1, and push the result back on the stack, but the operation is done -in-place when TOS1 supports it, and the resulting TOS may be (but does not -have to be) the original TOS1. - -\begin{opcodedesc}{INPLACE_POWER}{} -Implements in-place \code{TOS = TOS1 ** TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_MULTIPLY}{} -Implements in-place \code{TOS = TOS1 * TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_FLOOR_DIVIDE}{} -Implements in-place \code{TOS = TOS1 // TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_TRUE_DIVIDE}{} -Implements in-place \code{TOS = TOS1 / TOS} when -\code{from __future__ import division} is in effect. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_MODULO}{} -Implements in-place \code{TOS = TOS1 \%{} TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_ADD}{} -Implements in-place \code{TOS = TOS1 + TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_SUBTRACT}{} -Implements in-place \code{TOS = TOS1 - TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_LSHIFT}{} -Implements in-place \code{TOS = TOS1 <\code{}< TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_RSHIFT}{} -Implements in-place \code{TOS = TOS1 >\code{}> TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_AND}{} -Implements in-place \code{TOS = TOS1 \&\ TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_XOR}{} -Implements in-place \code{TOS = TOS1 \^\ TOS}. -\end{opcodedesc} - -\begin{opcodedesc}{INPLACE_OR}{} -Implements in-place \code{TOS = TOS1 | TOS}. -\end{opcodedesc} - -The slice opcodes take up to three parameters. - -\begin{opcodedesc}{SLICE+0}{} -Implements \code{TOS = TOS[:]}. -\end{opcodedesc} - -\begin{opcodedesc}{SLICE+1}{} -Implements \code{TOS = TOS1[TOS:]}. -\end{opcodedesc} - -\begin{opcodedesc}{SLICE+2}{} -Implements \code{TOS = TOS1[:TOS]}. -\end{opcodedesc} - -\begin{opcodedesc}{SLICE+3}{} -Implements \code{TOS = TOS2[TOS1:TOS]}. -\end{opcodedesc} - -Slice assignment needs even an additional parameter. As any statement, -they put nothing on the stack. - -\begin{opcodedesc}{STORE_SLICE+0}{} -Implements \code{TOS[:] = TOS1}. -\end{opcodedesc} - -\begin{opcodedesc}{STORE_SLICE+1}{} -Implements \code{TOS1[TOS:] = TOS2}. -\end{opcodedesc} - -\begin{opcodedesc}{STORE_SLICE+2}{} -Implements \code{TOS1[:TOS] = TOS2}. -\end{opcodedesc} - -\begin{opcodedesc}{STORE_SLICE+3}{} -Implements \code{TOS2[TOS1:TOS] = TOS3}. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_SLICE+0}{} -Implements \code{del TOS[:]}. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_SLICE+1}{} -Implements \code{del TOS1[TOS:]}. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_SLICE+2}{} -Implements \code{del TOS1[:TOS]}. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_SLICE+3}{} -Implements \code{del TOS2[TOS1:TOS]}. -\end{opcodedesc} - -\begin{opcodedesc}{STORE_SUBSCR}{} -Implements \code{TOS1[TOS] = TOS2}. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_SUBSCR}{} -Implements \code{del TOS1[TOS]}. -\end{opcodedesc} - -Miscellaneous opcodes. - -\begin{opcodedesc}{PRINT_EXPR}{} -Implements the expression statement for the interactive mode. TOS is -removed from the stack and printed. In non-interactive mode, an -expression statement is terminated with \code{POP_STACK}. -\end{opcodedesc} - -\begin{opcodedesc}{BREAK_LOOP}{} -Terminates a loop due to a \keyword{break} statement. -\end{opcodedesc} - -\begin{opcodedesc}{CONTINUE_LOOP}{target} -Continues a loop due to a \keyword{continue} statement. \var{target} -is the address to jump to (which should be a \code{FOR_ITER} -instruction). -\end{opcodedesc} - -\begin{opcodedesc}{SET_ADD}{} -Calls \code{set.add(TOS1, TOS)}. Used to implement set comprehensions. -\end{opcodedesc} - -\begin{opcodedesc}{LIST_APPEND}{} -Calls \code{list.append(TOS1, TOS)}. Used to implement list comprehensions. -\end{opcodedesc} - -\begin{opcodedesc}{LOAD_LOCALS}{} -Pushes a reference to the locals of the current scope on the stack. -This is used in the code for a class definition: After the class body -is evaluated, the locals are passed to the class definition. -\end{opcodedesc} - -\begin{opcodedesc}{RETURN_VALUE}{} -Returns with TOS to the caller of the function. -\end{opcodedesc} - -\begin{opcodedesc}{YIELD_VALUE}{} -Pops \code{TOS} and yields it from a generator. -\end{opcodedesc} - -\begin{opcodedesc}{IMPORT_STAR}{} -Loads all symbols not starting with \character{_} directly from the module TOS -to the local namespace. The module is popped after loading all names. -This opcode implements \code{from module import *}. -\end{opcodedesc} - -\begin{opcodedesc}{POP_BLOCK}{} -Removes one block from the block stack. Per frame, there is a -stack of blocks, denoting nested loops, try statements, and such. -\end{opcodedesc} - -\begin{opcodedesc}{END_FINALLY}{} -Terminates a \keyword{finally} clause. The interpreter recalls -whether the exception has to be re-raised, or whether the function -returns, and continues with the outer-next block. -\end{opcodedesc} - -\begin{opcodedesc}{BUILD_CLASS}{} -Creates a new class object. TOS is the methods dictionary, TOS1 -the tuple of the names of the base classes, and TOS2 the class name. -\end{opcodedesc} - -All of the following opcodes expect arguments. An argument is two -bytes, with the more significant byte last. - -\begin{opcodedesc}{STORE_NAME}{namei} -Implements \code{name = TOS}. \var{namei} is the index of \var{name} -in the attribute \member{co_names} of the code object. -The compiler tries to use \code{STORE_LOCAL} or \code{STORE_GLOBAL} -if possible. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_NAME}{namei} -Implements \code{del name}, where \var{namei} is the index into -\member{co_names} attribute of the code object. -\end{opcodedesc} - -\begin{opcodedesc}{UNPACK_SEQUENCE}{count} -Unpacks TOS into \var{count} individual values, which are put onto -the stack right-to-left. -\end{opcodedesc} - -%\begin{opcodedesc}{UNPACK_LIST}{count} -%This opcode is obsolete. -%\end{opcodedesc} - -%\begin{opcodedesc}{UNPACK_ARG}{count} -%This opcode is obsolete. -%\end{opcodedesc} - -\begin{opcodedesc}{DUP_TOPX}{count} -Duplicate \var{count} items, keeping them in the same order. Due to -implementation limits, \var{count} should be between 1 and 5 inclusive. -\end{opcodedesc} - -\begin{opcodedesc}{STORE_ATTR}{namei} -Implements \code{TOS.name = TOS1}, where \var{namei} is the index -of name in \member{co_names}. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_ATTR}{namei} -Implements \code{del TOS.name}, using \var{namei} as index into -\member{co_names}. -\end{opcodedesc} - -\begin{opcodedesc}{STORE_GLOBAL}{namei} -Works as \code{STORE_NAME}, but stores the name as a global. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_GLOBAL}{namei} -Works as \code{DELETE_NAME}, but deletes a global name. -\end{opcodedesc} - -%\begin{opcodedesc}{UNPACK_VARARG}{argc} -%This opcode is obsolete. -%\end{opcodedesc} - -\begin{opcodedesc}{LOAD_CONST}{consti} -Pushes \samp{co_consts[\var{consti}]} onto the stack. -\end{opcodedesc} - -\begin{opcodedesc}{LOAD_NAME}{namei} -Pushes the value associated with \samp{co_names[\var{namei}]} onto the stack. -\end{opcodedesc} - -\begin{opcodedesc}{BUILD_TUPLE}{count} -Creates a tuple consuming \var{count} items from the stack, and pushes -the resulting tuple onto the stack. -\end{opcodedesc} - -\begin{opcodedesc}{BUILD_LIST}{count} -Works as \code{BUILD_TUPLE}, but creates a list. -\end{opcodedesc} - -\begin{opcodedesc}{BUILD_SET}{count} -Works as \code{BUILD_TUPLE}, but creates a set. -\end{opcodedesc} - -\begin{opcodedesc}{BUILD_MAP}{zero} -Pushes a new empty dictionary object onto the stack. The argument is -ignored and set to zero by the compiler. -\end{opcodedesc} - -\begin{opcodedesc}{LOAD_ATTR}{namei} -Replaces TOS with \code{getattr(TOS, co_names[\var{namei}])}. -\end{opcodedesc} - -\begin{opcodedesc}{COMPARE_OP}{opname} -Performs a Boolean operation. The operation name can be found -in \code{cmp_op[\var{opname}]}. -\end{opcodedesc} - -\begin{opcodedesc}{IMPORT_NAME}{namei} -Imports the module \code{co_names[\var{namei}]}. The module object is -pushed onto the stack. The current namespace is not affected: for a -proper import statement, a subsequent \code{STORE_FAST} instruction -modifies the namespace. -\end{opcodedesc} - -\begin{opcodedesc}{IMPORT_FROM}{namei} -Loads the attribute \code{co_names[\var{namei}]} from the module found in -TOS. The resulting object is pushed onto the stack, to be subsequently -stored by a \code{STORE_FAST} instruction. -\end{opcodedesc} - -\begin{opcodedesc}{JUMP_FORWARD}{delta} -Increments byte code counter by \var{delta}. -\end{opcodedesc} - -\begin{opcodedesc}{JUMP_IF_TRUE}{delta} -If TOS is true, increment the byte code counter by \var{delta}. TOS is -left on the stack. -\end{opcodedesc} - -\begin{opcodedesc}{JUMP_IF_FALSE}{delta} -If TOS is false, increment the byte code counter by \var{delta}. TOS -is not changed. -\end{opcodedesc} - -\begin{opcodedesc}{JUMP_ABSOLUTE}{target} -Set byte code counter to \var{target}. -\end{opcodedesc} - -\begin{opcodedesc}{FOR_ITER}{delta} - \code{TOS} is an iterator. Call its \method{__next__()} method. If this - yields a new value, push it on the stack (leaving the iterator below it). If - the iterator indicates it is exhausted \code{TOS} is popped, and the byte code - counter is incremented by \var{delta}. -\end{opcodedesc} - -%\begin{opcodedesc}{FOR_LOOP}{delta} -%This opcode is obsolete. -%\end{opcodedesc} - -%\begin{opcodedesc}{LOAD_LOCAL}{namei} -%This opcode is obsolete. -%\end{opcodedesc} - -\begin{opcodedesc}{LOAD_GLOBAL}{namei} -Loads the global named \code{co_names[\var{namei}]} onto the stack. -\end{opcodedesc} - -%\begin{opcodedesc}{SET_FUNC_ARGS}{argc} -%This opcode is obsolete. -%\end{opcodedesc} - -\begin{opcodedesc}{SETUP_LOOP}{delta} -Pushes a block for a loop onto the block stack. The block spans -from the current instruction with a size of \var{delta} bytes. -\end{opcodedesc} - -\begin{opcodedesc}{SETUP_EXCEPT}{delta} -Pushes a try block from a try-except clause onto the block stack. -\var{delta} points to the first except block. -\end{opcodedesc} - -\begin{opcodedesc}{SETUP_FINALLY}{delta} -Pushes a try block from a try-except clause onto the block stack. -\var{delta} points to the finally block. -\end{opcodedesc} - -\begin{opcodedesc}{LOAD_FAST}{var_num} -Pushes a reference to the local \code{co_varnames[\var{var_num}]} onto -the stack. -\end{opcodedesc} - -\begin{opcodedesc}{STORE_FAST}{var_num} -Stores TOS into the local \code{co_varnames[\var{var_num}]}. -\end{opcodedesc} - -\begin{opcodedesc}{DELETE_FAST}{var_num} -Deletes local \code{co_varnames[\var{var_num}]}. -\end{opcodedesc} - -\begin{opcodedesc}{LOAD_CLOSURE}{i} -Pushes a reference to the cell contained in slot \var{i} of the -cell and free variable storage. The name of the variable is -\code{co_cellvars[\var{i}]} if \var{i} is less than the length of -\var{co_cellvars}. Otherwise it is -\code{co_freevars[\var{i} - len(co_cellvars)]}. -\end{opcodedesc} - -\begin{opcodedesc}{LOAD_DEREF}{i} -Loads the cell contained in slot \var{i} of the cell and free variable -storage. Pushes a reference to the object the cell contains on the -stack. -\end{opcodedesc} - -\begin{opcodedesc}{STORE_DEREF}{i} -Stores TOS into the cell contained in slot \var{i} of the cell and -free variable storage. -\end{opcodedesc} - -\begin{opcodedesc}{SET_LINENO}{lineno} -This opcode is obsolete. -\end{opcodedesc} - -\begin{opcodedesc}{RAISE_VARARGS}{argc} -Raises an exception. \var{argc} indicates the number of parameters -to the raise statement, ranging from 0 to 3. The handler will find -the traceback as TOS2, the parameter as TOS1, and the exception -as TOS. -\end{opcodedesc} - -\begin{opcodedesc}{CALL_FUNCTION}{argc} -Calls a function. The low byte of \var{argc} indicates the number of -positional parameters, the high byte the number of keyword parameters. -On the stack, the opcode finds the keyword parameters first. For each -keyword argument, the value is on top of the key. Below the keyword -parameters, the positional parameters are on the stack, with the -right-most parameter on top. Below the parameters, the function object -to call is on the stack. -\end{opcodedesc} - -\begin{opcodedesc}{MAKE_FUNCTION}{argc} -Pushes a new function object on the stack. TOS is the code associated -with the function. The function object is defined to have \var{argc} -default parameters, which are found below TOS. -\end{opcodedesc} - -\begin{opcodedesc}{MAKE_CLOSURE}{argc} -Creates a new function object, sets its \var{__closure__} slot, and -pushes it on the stack. TOS is the code associated with the function. -If the code object has N free variables, the next N items on the stack -are the cells for these variables. The function also has \var{argc} -default parameters, where are found before the cells. -\end{opcodedesc} - -\begin{opcodedesc}{BUILD_SLICE}{argc} -Pushes a slice object on the stack. \var{argc} must be 2 or 3. If it -is 2, \code{slice(TOS1, TOS)} is pushed; if it is 3, -\code{slice(TOS2, TOS1, TOS)} is pushed. -See the \code{slice()}\bifuncindex{slice} built-in function for more -information. -\end{opcodedesc} - -\begin{opcodedesc}{EXTENDED_ARG}{ext} -Prefixes any opcode which has an argument too big to fit into the -default two bytes. \var{ext} holds two additional bytes which, taken -together with the subsequent opcode's argument, comprise a four-byte -argument, \var{ext} being the two most-significant bytes. -\end{opcodedesc} - -\begin{opcodedesc}{CALL_FUNCTION_VAR}{argc} -Calls a function. \var{argc} is interpreted as in \code{CALL_FUNCTION}. -The top element on the stack contains the variable argument list, followed -by keyword and positional arguments. -\end{opcodedesc} - -\begin{opcodedesc}{CALL_FUNCTION_KW}{argc} -Calls a function. \var{argc} is interpreted as in \code{CALL_FUNCTION}. -The top element on the stack contains the keyword arguments dictionary, -followed by explicit keyword and positional arguments. -\end{opcodedesc} - -\begin{opcodedesc}{CALL_FUNCTION_VAR_KW}{argc} -Calls a function. \var{argc} is interpreted as in -\code{CALL_FUNCTION}. The top element on the stack contains the -keyword arguments dictionary, followed by the variable-arguments -tuple, followed by explicit keyword and positional arguments. -\end{opcodedesc} - -\begin{opcodedesc}{HAVE_ARGUMENT}{} -This is not really an opcode. It identifies the dividing line between -opcodes which don't take arguments \code{< HAVE_ARGUMENT} and those which do -\code{>= HAVE_ARGUMENT}. -\end{opcodedesc} diff --git a/Doc/lib/libdl.tex b/Doc/lib/libdl.tex deleted file mode 100644 index d4a799e..0000000 --- a/Doc/lib/libdl.tex +++ /dev/null @@ -1,101 +0,0 @@ -\section{\module{dl} --- - Call C functions in shared objects} -\declaremodule{extension}{dl} - \platform{Unix} %?????????? Anyone???????????? -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Call C functions in shared objects.} - -The \module{dl} module defines an interface to the -\cfunction{dlopen()} function, which is the most common interface on -\UNIX{} platforms for handling dynamically linked libraries. It allows -the program to call arbitrary functions in such a library. - -\warning{The \module{dl} module bypasses the Python type system and -error handling. If used incorrectly it may cause segmentation faults, -crashes or other incorrect behaviour.} - -\note{This module will not work unless -\code{sizeof(int) == sizeof(long) == sizeof(char *)} -If this is not the case, \exception{SystemError} will be raised on -import.} - -The \module{dl} module defines the following function: - -\begin{funcdesc}{open}{name\optional{, mode\code{ = RTLD_LAZY}}} -Open a shared object file, and return a handle. Mode -signifies late binding (\constant{RTLD_LAZY}) or immediate binding -(\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that some -systems do not support \constant{RTLD_NOW}. - -Return value is a \class{dlobject}. -\end{funcdesc} - -The \module{dl} module defines the following constants: - -\begin{datadesc}{RTLD_LAZY} -Useful as an argument to \function{open()}. -\end{datadesc} - -\begin{datadesc}{RTLD_NOW} -Useful as an argument to \function{open()}. Note that on systems -which do not support immediate binding, this constant will not appear -in the module. For maximum portability, use \function{hasattr()} to -determine if the system supports immediate binding. -\end{datadesc} - -The \module{dl} module defines the following exception: - -\begin{excdesc}{error} -Exception raised when an error has occurred inside the dynamic loading -and linking routines. -\end{excdesc} - -Example: - -\begin{verbatim} ->>> import dl, time ->>> a=dl.open('/lib/libc.so.6') ->>> a.call('time'), time.time() -(929723914, 929723914.498) -\end{verbatim} - -This example was tried on a Debian GNU/Linux system, and is a good -example of the fact that using this module is usually a bad alternative. - -\subsection{Dl Objects \label{dl-objects}} - -Dl objects, as returned by \function{open()} above, have the -following methods: - -\begin{methoddesc}[dl]{close}{} -Free all resources, except the memory. -\end{methoddesc} - -\begin{methoddesc}[dl]{sym}{name} -Return the pointer for the function named \var{name}, as a number, if -it exists in the referenced shared object, otherwise \code{None}. This -is useful in code like: - -\begin{verbatim} ->>> if a.sym('time'): -... a.call('time') -... else: -... time.time() -\end{verbatim} - -(Note that this function will return a non-zero number, as zero is the -\NULL{} pointer) -\end{methoddesc} - -\begin{methoddesc}[dl]{call}{name\optional{, arg1\optional{, arg2\ldots}}} -Call the function named \var{name} in the referenced shared object. -The arguments must be either Python integers, which will be -passed as is, Python strings, to which a pointer will be passed, -or \code{None}, which will be passed as \NULL. Note that -strings should only be passed to functions as \ctype{const char*}, as -Python will not like its string mutated. - -There must be at most 10 arguments, and arguments not given will be -treated as \code{None}. The function's return value must be a C -\ctype{long}, which is a Python integer. -\end{methoddesc} diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex deleted file mode 100644 index 9143b84..0000000 --- a/Doc/lib/libdoctest.tex +++ /dev/null @@ -1,1974 +0,0 @@ -\section{\module{doctest} --- - Test interactive Python examples} - -\declaremodule{standard}{doctest} -\moduleauthor{Tim Peters}{tim@python.org} -\sectionauthor{Tim Peters}{tim@python.org} -\sectionauthor{Moshe Zadka}{moshez@debian.org} -\sectionauthor{Edward Loper}{edloper@users.sourceforge.net} - -\modulesynopsis{A framework for verifying interactive Python examples.} - -The \refmodule{doctest} module searches for pieces of text that look like -interactive Python sessions, and then executes those sessions to -verify that they work exactly as shown. There are several common ways to -use doctest: - -\begin{itemize} -\item To check that a module's docstrings are up-to-date by verifying - that all interactive examples still work as documented. -\item To perform regression testing by verifying that interactive - examples from a test file or a test object work as expected. -\item To write tutorial documentation for a package, liberally - illustrated with input-output examples. Depending on whether - the examples or the expository text are emphasized, this has - the flavor of "literate testing" or "executable documentation". -\end{itemize} - -Here's a complete but small example module: - -\begin{verbatim} -""" -This is the "example" module. - -The example module supplies one function, factorial(). For example, - ->>> factorial(5) -120 -""" - -def factorial(n): - """Return the factorial of n, an exact integer >= 0. - - If the result is small enough to fit in an int, return an int. - Else return a long. - - >>> [factorial(n) for n in range(6)] - [1, 1, 2, 6, 24, 120] - >>> [factorial(long(n)) for n in range(6)] - [1, 1, 2, 6, 24, 120] - >>> factorial(30) - 265252859812191058636308480000000L - >>> factorial(30L) - 265252859812191058636308480000000L - >>> factorial(-1) - Traceback (most recent call last): - ... - ValueError: n must be >= 0 - - Factorials of floats are OK, but the float must be an exact integer: - >>> factorial(30.1) - Traceback (most recent call last): - ... - ValueError: n must be exact integer - >>> factorial(30.0) - 265252859812191058636308480000000L - - It must also not be ridiculously large: - >>> factorial(1e100) - Traceback (most recent call last): - ... - OverflowError: n too large - """ - -\end{verbatim} -% allow LaTeX to break here. -\begin{verbatim} - - import math - if not n >= 0: - raise ValueError("n must be >= 0") - if math.floor(n) != n: - raise ValueError("n must be exact integer") - if n+1 == n: # catch a value like 1e300 - raise OverflowError("n too large") - result = 1 - factor = 2 - while factor <= n: - result *= factor - factor += 1 - return result - -def _test(): - import doctest - doctest.testmod() - -if __name__ == "__main__": - _test() -\end{verbatim} - -If you run \file{example.py} directly from the command line, -\refmodule{doctest} works its magic: - -\begin{verbatim} -$ python example.py -$ -\end{verbatim} - -There's no output! That's normal, and it means all the examples -worked. Pass \programopt{-v} to the script, and \refmodule{doctest} -prints a detailed log of what it's trying, and prints a summary at the -end: - -\begin{verbatim} -$ python example.py -v -Trying: - factorial(5) -Expecting: - 120 -ok -Trying: - [factorial(n) for n in range(6)] -Expecting: - [1, 1, 2, 6, 24, 120] -ok -Trying: - [factorial(long(n)) for n in range(6)] -Expecting: - [1, 1, 2, 6, 24, 120] -ok -\end{verbatim} - -And so on, eventually ending with: - -\begin{verbatim} -Trying: - factorial(1e100) -Expecting: - Traceback (most recent call last): - ... - OverflowError: n too large -ok -1 items had no tests: - __main__._test -2 items passed all tests: - 1 tests in __main__ - 8 tests in __main__.factorial -9 tests in 3 items. -9 passed and 0 failed. -Test passed. -$ -\end{verbatim} - -That's all you need to know to start making productive use of -\refmodule{doctest}! Jump in. The following sections provide full -details. Note that there are many examples of doctests in -the standard Python test suite and libraries. Especially useful examples -can be found in the standard test file \file{Lib/test/test_doctest.py}. - -\subsection{Simple Usage: Checking Examples in - Docstrings\label{doctest-simple-testmod}} - -The simplest way to start using doctest (but not necessarily the way -you'll continue to do it) is to end each module \module{M} with: - -\begin{verbatim} -def _test(): - import doctest - doctest.testmod() - -if __name__ == "__main__": - _test() -\end{verbatim} - -\refmodule{doctest} then examines docstrings in module \module{M}. - -Running the module as a script causes the examples in the docstrings -to get executed and verified: - -\begin{verbatim} -python M.py -\end{verbatim} - -This won't display anything unless an example fails, in which case the -failing example(s) and the cause(s) of the failure(s) are printed to stdout, -and the final line of output is -\samp{***Test Failed*** \var{N} failures.}, where \var{N} is the -number of examples that failed. - -Run it with the \programopt{-v} switch instead: - -\begin{verbatim} -python M.py -v -\end{verbatim} - -and a detailed report of all examples tried is printed to standard -output, along with assorted summaries at the end. - -You can force verbose mode by passing \code{verbose=True} to -\function{testmod()}, or -prohibit it by passing \code{verbose=False}. In either of those cases, -\code{sys.argv} is not examined by \function{testmod()} (so passing -\programopt{-v} or not has no effect). - -Since Python 2.6, there is also a command line shortcut for running -\function{testmod()}. You can instruct the Python interpreter to run -the doctest module directly from the standard library and pass the module -name(s) on the command line: - -\begin{verbatim} -python -m doctest -v example.py -\end{verbatim} - -This will import \file{example.py} as a standalone module and run -\function{testmod()} on it. Note that this may not work correctly if the -file is part of a package and imports other submodules from that package. - -For more information on \function{testmod()}, see -section~\ref{doctest-basic-api}. - -\subsection{Simple Usage: Checking Examples in a Text - File\label{doctest-simple-testfile}} - -Another simple application of doctest is testing interactive examples -in a text file. This can be done with the \function{testfile()} -function: - -\begin{verbatim} -import doctest -doctest.testfile("example.txt") -\end{verbatim} - -That short script executes and verifies any interactive Python -examples contained in the file \file{example.txt}. The file content -is treated as if it were a single giant docstring; the file doesn't -need to contain a Python program! For example, perhaps \file{example.txt} -contains this: - -\begin{verbatim} -The ``example`` module -====================== - -Using ``factorial`` -------------------- - -This is an example text file in reStructuredText format. First import -``factorial`` from the ``example`` module: - - >>> from example import factorial - -Now use it: - - >>> factorial(6) - 120 -\end{verbatim} - -Running \code{doctest.testfile("example.txt")} then finds the error -in this documentation: - -\begin{verbatim} -File "./example.txt", line 14, in example.txt -Failed example: - factorial(6) -Expected: - 120 -Got: - 720 -\end{verbatim} - -As with \function{testmod()}, \function{testfile()} won't display anything -unless an example fails. If an example does fail, then the failing -example(s) and the cause(s) of the failure(s) are printed to stdout, using -the same format as \function{testmod()}. - -By default, \function{testfile()} looks for files in the calling -module's directory. See section~\ref{doctest-basic-api} for a -description of the optional arguments that can be used to tell it to -look for files in other locations. - -Like \function{testmod()}, \function{testfile()}'s verbosity can be -set with the \programopt{-v} command-line switch or with the optional -keyword argument \var{verbose}. - -Since Python 2.6, there is also a command line shortcut for running -\function{testfile()}. You can instruct the Python interpreter to run -the doctest module directly from the standard library and pass the file -name(s) on the command line: - -\begin{verbatim} -python -m doctest -v example.txt -\end{verbatim} - -Because the file name does not end with \file{.py}, \module{doctest} infers -that it must be run with \function{testfile()}, not \function{testmod()}. - -For more information on \function{testfile()}, see -section~\ref{doctest-basic-api}. - -\subsection{How It Works\label{doctest-how-it-works}} - -This section examines in detail how doctest works: which docstrings it -looks at, how it finds interactive examples, what execution context it -uses, how it handles exceptions, and how option flags can be used to -control its behavior. This is the information that you need to know -to write doctest examples; for information about actually running -doctest on these examples, see the following sections. - -\subsubsection{Which Docstrings Are Examined?\label{doctest-which-docstrings}} - -The module docstring, and all function, class and method docstrings are -searched. Objects imported into the module are not searched. - -In addition, if \code{M.__test__} exists and "is true", it must be a -dict, and each entry maps a (string) name to a function object, class -object, or string. Function and class object docstrings found from -\code{M.__test__} are searched, and strings are treated as if they -were docstrings. In output, a key \code{K} in \code{M.__test__} appears -with name - -\begin{verbatim} -<name of M>.__test__.K -\end{verbatim} - -Any classes found are recursively searched similarly, to test docstrings in -their contained methods and nested classes. - -\versionchanged[A "private name" concept is deprecated and no longer - documented]{2.4} - -\subsubsection{How are Docstring Examples - Recognized?\label{doctest-finding-examples}} - -In most cases a copy-and-paste of an interactive console session works -fine, but doctest isn't trying to do an exact emulation of any specific -Python shell. All hard tab characters are expanded to spaces, using -8-column tab stops. If you don't believe tabs should mean that, too -bad: don't use hard tabs, or write your own \class{DocTestParser} -class. - -\versionchanged[Expanding tabs to spaces is new; previous versions - tried to preserve hard tabs, with confusing results]{2.4} - -\begin{verbatim} ->>> # comments are ignored ->>> x = 12 ->>> x -12 ->>> if x == 13: -... print "yes" -... else: -... print "no" -... print "NO" -... print "NO!!!" -... -no -NO -NO!!! ->>> -\end{verbatim} - -Any expected output must immediately follow the final -\code{'>>>~'} or \code{'...~'} line containing the code, and -the expected output (if any) extends to the next \code{'>>>~'} -or all-whitespace line. - -The fine print: - -\begin{itemize} - -\item Expected output cannot contain an all-whitespace line, since such a - line is taken to signal the end of expected output. If expected - output does contain a blank line, put \code{<BLANKLINE>} in your - doctest example each place a blank line is expected. - \versionchanged[\code{<BLANKLINE>} was added; there was no way to - use expected output containing empty lines in - previous versions]{2.4} - -\item Output to stdout is captured, but not output to stderr (exception - tracebacks are captured via a different means). - -\item If you continue a line via backslashing in an interactive session, - or for any other reason use a backslash, you should use a raw - docstring, which will preserve your backslashes exactly as you type - them: - -\begin{verbatim} ->>> def f(x): -... r'''Backslashes in a raw docstring: m\n''' ->>> print f.__doc__ -Backslashes in a raw docstring: m\n -\end{verbatim} - - Otherwise, the backslash will be interpreted as part of the string. - For example, the "{\textbackslash}" above would be interpreted as a - newline character. Alternatively, you can double each backslash in the - doctest version (and not use a raw string): - -\begin{verbatim} ->>> def f(x): -... '''Backslashes in a raw docstring: m\\n''' ->>> print f.__doc__ -Backslashes in a raw docstring: m\n -\end{verbatim} - -\item The starting column doesn't matter: - -\begin{verbatim} - >>> assert "Easy!" - >>> import math - >>> math.floor(1.9) - 1.0 -\end{verbatim} - -and as many leading whitespace characters are stripped from the -expected output as appeared in the initial \code{'>>>~'} line -that started the example. -\end{itemize} - -\subsubsection{What's the Execution Context?\label{doctest-execution-context}} - -By default, each time \refmodule{doctest} finds a docstring to test, it -uses a \emph{shallow copy} of \module{M}'s globals, so that running tests -doesn't change the module's real globals, and so that one test in -\module{M} can't leave behind crumbs that accidentally allow another test -to work. This means examples can freely use any names defined at top-level -in \module{M}, and names defined earlier in the docstring being run. -Examples cannot see names defined in other docstrings. - -You can force use of your own dict as the execution context by passing -\code{globs=your_dict} to \function{testmod()} or -\function{testfile()} instead. - -\subsubsection{What About Exceptions?\label{doctest-exceptions}} - -No problem, provided that the traceback is the only output produced by -the example: just paste in the traceback.\footnote{Examples containing - both expected output and an exception are not supported. Trying - to guess where one ends and the other begins is too error-prone, - and that also makes for a confusing test.} -Since tracebacks contain details that are likely to change rapidly (for -example, exact file paths and line numbers), this is one case where doctest -works hard to be flexible in what it accepts. - -Simple example: - -\begin{verbatim} ->>> [1, 2, 3].remove(42) -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ValueError: list.remove(x): x not in list -\end{verbatim} - -That doctest succeeds if \exception{ValueError} is raised, with the -\samp{list.remove(x): x not in list} detail as shown. - -The expected output for an exception must start with a traceback -header, which may be either of the following two lines, indented the -same as the first line of the example: - -\begin{verbatim} -Traceback (most recent call last): -Traceback (innermost last): -\end{verbatim} - -The traceback header is followed by an optional traceback stack, whose -contents are ignored by doctest. The traceback stack is typically -omitted, or copied verbatim from an interactive session. - -The traceback stack is followed by the most interesting part: the -line(s) containing the exception type and detail. This is usually the -last line of a traceback, but can extend across multiple lines if the -exception has a multi-line detail: - -\begin{verbatim} ->>> raise ValueError('multi\n line\ndetail') -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ValueError: multi - line -detail -\end{verbatim} - -The last three lines (starting with \exception{ValueError}) are -compared against the exception's type and detail, and the rest are -ignored. - -Best practice is to omit the traceback stack, unless it adds -significant documentation value to the example. So the last example -is probably better as: - -\begin{verbatim} ->>> raise ValueError('multi\n line\ndetail') -Traceback (most recent call last): - ... -ValueError: multi - line -detail -\end{verbatim} - -Note that tracebacks are treated very specially. In particular, in the -rewritten example, the use of \samp{...} is independent of doctest's -\constant{ELLIPSIS} option. The ellipsis in that example could be left -out, or could just as well be three (or three hundred) commas or digits, -or an indented transcript of a Monty Python skit. - -Some details you should read once, but won't need to remember: - -\begin{itemize} - -\item Doctest can't guess whether your expected output came from an - exception traceback or from ordinary printing. So, e.g., an example - that expects \samp{ValueError: 42 is prime} will pass whether - \exception{ValueError} is actually raised or if the example merely - prints that traceback text. In practice, ordinary output rarely begins - with a traceback header line, so this doesn't create real problems. - -\item Each line of the traceback stack (if present) must be indented - further than the first line of the example, \emph{or} start with a - non-alphanumeric character. The first line following the traceback - header indented the same and starting with an alphanumeric is taken - to be the start of the exception detail. Of course this does the - right thing for genuine tracebacks. - -\item When the \constant{IGNORE_EXCEPTION_DETAIL} doctest option is - is specified, everything following the leftmost colon is ignored. - -\item The interactive shell omits the traceback header line for some - \exception{SyntaxError}s. But doctest uses the traceback header - line to distinguish exceptions from non-exceptions. So in the rare - case where you need to test a \exception{SyntaxError} that omits the - traceback header, you will need to manually add the traceback header - line to your test example. - -\item For some \exception{SyntaxError}s, Python displays the character - position of the syntax error, using a \code{\^} marker: - -\begin{verbatim} ->>> 1 1 - File "<stdin>", line 1 - 1 1 - ^ -SyntaxError: invalid syntax -\end{verbatim} - - Since the lines showing the position of the error come before the - exception type and detail, they are not checked by doctest. For - example, the following test would pass, even though it puts the - \code{\^} marker in the wrong location: - -\begin{verbatim} ->>> 1 1 -Traceback (most recent call last): - File "<stdin>", line 1 - 1 1 - ^ -SyntaxError: invalid syntax -\end{verbatim} - -\end{itemize} - -\versionchanged[The ability to handle a multi-line exception detail, - and the \constant{IGNORE_EXCEPTION_DETAIL} doctest option, - were added]{2.4} - -\subsubsection{Option Flags and Directives\label{doctest-options}} - -A number of option flags control various aspects of doctest's -behavior. Symbolic names for the flags are supplied as module constants, -which can be or'ed together and passed to various functions. The names -can also be used in doctest directives (see below). - -The first group of options define test semantics, controlling -aspects of how doctest decides whether actual output matches an -example's expected output: - -\begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1} - By default, if an expected output block contains just \code{1}, - an actual output block containing just \code{1} or just - \code{True} is considered to be a match, and similarly for \code{0} - versus \code{False}. When \constant{DONT_ACCEPT_TRUE_FOR_1} is - specified, neither substitution is allowed. The default behavior - caters to that Python changed the return type of many functions - from integer to boolean; doctests expecting "little integer" - output still work in these cases. This option will probably go - away, but not for several years. -\end{datadesc} - -\begin{datadesc}{DONT_ACCEPT_BLANKLINE} - By default, if an expected output block contains a line - containing only the string \code{<BLANKLINE>}, then that line - will match a blank line in the actual output. Because a - genuinely blank line delimits the expected output, this is - the only way to communicate that a blank line is expected. When - \constant{DONT_ACCEPT_BLANKLINE} is specified, this substitution - is not allowed. -\end{datadesc} - -\begin{datadesc}{NORMALIZE_WHITESPACE} - When specified, all sequences of whitespace (blanks and newlines) are - treated as equal. Any sequence of whitespace within the expected - output will match any sequence of whitespace within the actual output. - By default, whitespace must match exactly. - \constant{NORMALIZE_WHITESPACE} is especially useful when a line - of expected output is very long, and you want to wrap it across - multiple lines in your source. -\end{datadesc} - -\begin{datadesc}{ELLIPSIS} - When specified, an ellipsis marker (\code{...}) in the expected output - can match any substring in the actual output. This includes - substrings that span line boundaries, and empty substrings, so it's - best to keep usage of this simple. Complicated uses can lead to the - same kinds of "oops, it matched too much!" surprises that \regexp{.*} - is prone to in regular expressions. -\end{datadesc} - -\begin{datadesc}{IGNORE_EXCEPTION_DETAIL} - When specified, an example that expects an exception passes if - an exception of the expected type is raised, even if the exception - detail does not match. For example, an example expecting - \samp{ValueError: 42} will pass if the actual exception raised is - \samp{ValueError: 3*14}, but will fail, e.g., if - \exception{TypeError} is raised. - - Note that a similar effect can be obtained using \constant{ELLIPSIS}, - and \constant{IGNORE_EXCEPTION_DETAIL} may go away when Python releases - prior to 2.4 become uninteresting. Until then, - \constant{IGNORE_EXCEPTION_DETAIL} is the only clear way to write a - doctest that doesn't care about the exception detail yet continues - to pass under Python releases prior to 2.4 (doctest directives - appear to be comments to them). For example, - -\begin{verbatim} ->>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL -Traceback (most recent call last): - File "<stdin>", line 1, in ? -TypeError: object doesn't support item assignment -\end{verbatim} - - passes under Python 2.4 and Python 2.3. The detail changed in 2.4, - to say "does not" instead of "doesn't". - -\end{datadesc} - -\begin{datadesc}{SKIP} - - When specified, do not run the example at all. This can be useful - in contexts where doctest examples serve as both documentation and - test cases, and an example should be included for documentation - purposes, but should not be checked. E.g., the example's output - might be random; or the example might depend on resources which - would be unavailable to the test driver. - - The SKIP flag can also be used for temporarily "commenting out" - examples. - -\end{datadesc} - -\begin{datadesc}{COMPARISON_FLAGS} - A bitmask or'ing together all the comparison flags above. -\end{datadesc} - -The second group of options controls how test failures are reported: - -\begin{datadesc}{REPORT_UDIFF} - When specified, failures that involve multi-line expected and - actual outputs are displayed using a unified diff. -\end{datadesc} - -\begin{datadesc}{REPORT_CDIFF} - When specified, failures that involve multi-line expected and - actual outputs will be displayed using a context diff. -\end{datadesc} - -\begin{datadesc}{REPORT_NDIFF} - When specified, differences are computed by \code{difflib.Differ}, - using the same algorithm as the popular \file{ndiff.py} utility. - This is the only method that marks differences within lines as - well as across lines. For example, if a line of expected output - contains digit \code{1} where actual output contains letter \code{l}, - a line is inserted with a caret marking the mismatching column - positions. -\end{datadesc} - -\begin{datadesc}{REPORT_ONLY_FIRST_FAILURE} - When specified, display the first failing example in each doctest, - but suppress output for all remaining examples. This will prevent - doctest from reporting correct examples that break because of - earlier failures; but it might also hide incorrect examples that - fail independently of the first failure. When - \constant{REPORT_ONLY_FIRST_FAILURE} is specified, the remaining - examples are still run, and still count towards the total number of - failures reported; only the output is suppressed. -\end{datadesc} - -\begin{datadesc}{REPORTING_FLAGS} - A bitmask or'ing together all the reporting flags above. -\end{datadesc} - -"Doctest directives" may be used to modify the option flags for -individual examples. Doctest directives are expressed as a special -Python comment following an example's source code: - -\begin{productionlist}[doctest] - \production{directive} - {"\#" "doctest:" \token{directive_options}} - \production{directive_options} - {\token{directive_option} ("," \token{directive_option})*} - \production{directive_option} - {\token{on_or_off} \token{directive_option_name}} - \production{on_or_off} - {"+" | "-"} - \production{directive_option_name} - {"DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...} -\end{productionlist} - -Whitespace is not allowed between the \code{+} or \code{-} and the -directive option name. The directive option name can be any of the -option flag names explained above. - -An example's doctest directives modify doctest's behavior for that -single example. Use \code{+} to enable the named behavior, or -\code{-} to disable it. - -For example, this test passes: - -\begin{verbatim} ->>> print range(20) #doctest: +NORMALIZE_WHITESPACE -[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, -10, 11, 12, 13, 14, 15, 16, 17, 18, 19] -\end{verbatim} - -Without the directive it would fail, both because the actual output -doesn't have two blanks before the single-digit list elements, and -because the actual output is on a single line. This test also passes, -and also requires a directive to do so: - -\begin{verbatim} ->>> print range(20) # doctest:+ELLIPSIS -[0, 1, ..., 18, 19] -\end{verbatim} - -Multiple directives can be used on a single physical line, separated -by commas: - -\begin{verbatim} ->>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE -[0, 1, ..., 18, 19] -\end{verbatim} - -If multiple directive comments are used for a single example, then -they are combined: - -\begin{verbatim} ->>> print range(20) # doctest: +ELLIPSIS -... # doctest: +NORMALIZE_WHITESPACE -[0, 1, ..., 18, 19] -\end{verbatim} - -As the previous example shows, you can add \samp{...} lines to your -example containing only directives. This can be useful when an -example is too long for a directive to comfortably fit on the same -line: - -\begin{verbatim} ->>> print range(5) + range(10,20) + range(30,40) + range(50,60) -... # doctest: +ELLIPSIS -[0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59] -\end{verbatim} - -Note that since all options are disabled by default, and directives apply -only to the example they appear in, enabling options (via \code{+} in a -directive) is usually the only meaningful choice. However, option flags -can also be passed to functions that run doctests, establishing different -defaults. In such cases, disabling an option via \code{-} in a directive -can be useful. - -\versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE}, - \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS}, - \constant{IGNORE_EXCEPTION_DETAIL}, - \constant{REPORT_UDIFF}, \constant{REPORT_CDIFF}, - \constant{REPORT_NDIFF}, \constant{REPORT_ONLY_FIRST_FAILURE}, - \constant{COMPARISON_FLAGS} and \constant{REPORTING_FLAGS} - were added; by default \code{<BLANKLINE>} in expected output - matches an empty line in actual output; and doctest directives - were added]{2.4} -\versionchanged[Constant \constant{SKIP} was added]{2.5} - -There's also a way to register new option flag names, although this -isn't useful unless you intend to extend \refmodule{doctest} internals -via subclassing: - -\begin{funcdesc}{register_optionflag}{name} - Create a new option flag with a given name, and return the new - flag's integer value. \function{register_optionflag()} can be - used when subclassing \class{OutputChecker} or - \class{DocTestRunner} to create new options that are supported by - your subclasses. \function{register_optionflag} should always be - called using the following idiom: - -\begin{verbatim} - MY_FLAG = register_optionflag('MY_FLAG') -\end{verbatim} - - \versionadded{2.4} -\end{funcdesc} - -\subsubsection{Warnings\label{doctest-warnings}} - -\refmodule{doctest} is serious about requiring exact matches in expected -output. If even a single character doesn't match, the test fails. This -will probably surprise you a few times, as you learn exactly what Python -does and doesn't guarantee about output. For example, when printing a -dict, Python doesn't guarantee that the key-value pairs will be printed -in any particular order, so a test like - -% Hey! What happened to Monty Python examples? -% Tim: ask Guido -- it's his example! -\begin{verbatim} ->>> foo() -{"Hermione": "hippogryph", "Harry": "broomstick"} -\end{verbatim} - -is vulnerable! One workaround is to do - -\begin{verbatim} ->>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"} -True -\end{verbatim} - -instead. Another is to do - -\begin{verbatim} ->>> d = foo().items() ->>> d.sort() ->>> d -[('Harry', 'broomstick'), ('Hermione', 'hippogryph')] -\end{verbatim} - -There are others, but you get the idea. - -Another bad idea is to print things that embed an object address, like - -\begin{verbatim} ->>> id(1.0) # certain to fail some of the time -7948648 ->>> class C: pass ->>> C() # the default repr() for instances embeds an address -<__main__.C instance at 0x00AC18F0> -\end{verbatim} - -The \constant{ELLIPSIS} directive gives a nice approach for the last -example: - -\begin{verbatim} ->>> C() #doctest: +ELLIPSIS -<__main__.C instance at 0x...> -\end{verbatim} - -Floating-point numbers are also subject to small output variations across -platforms, because Python defers to the platform C library for float -formatting, and C libraries vary widely in quality here. - -\begin{verbatim} ->>> 1./7 # risky -0.14285714285714285 ->>> print 1./7 # safer -0.142857142857 ->>> print round(1./7, 6) # much safer -0.142857 -\end{verbatim} - -Numbers of the form \code{I/2.**J} are safe across all platforms, and I -often contrive doctest examples to produce numbers of that form: - -\begin{verbatim} ->>> 3./4 # utterly safe -0.75 -\end{verbatim} - -Simple fractions are also easier for people to understand, and that makes -for better documentation. - -\subsection{Basic API\label{doctest-basic-api}} - -The functions \function{testmod()} and \function{testfile()} provide a -simple interface to doctest that should be sufficient for most basic -uses. For a less formal introduction to these two functions, see -sections \ref{doctest-simple-testmod} and -\ref{doctest-simple-testfile}. - -\begin{funcdesc}{testfile}{filename\optional{, module_relative}\optional{, - name}\optional{, package}\optional{, - globs}\optional{, verbose}\optional{, - report}\optional{, optionflags}\optional{, - extraglobs}\optional{, raise_on_error}\optional{, - parser}\optional{, encoding}} - - All arguments except \var{filename} are optional, and should be - specified in keyword form. - - Test examples in the file named \var{filename}. Return - \samp{(\var{failure_count}, \var{test_count})}. - - Optional argument \var{module_relative} specifies how the filename - should be interpreted: - - \begin{itemize} - \item If \var{module_relative} is \code{True} (the default), then - \var{filename} specifies an OS-independent module-relative - path. By default, this path is relative to the calling - module's directory; but if the \var{package} argument is - specified, then it is relative to that package. To ensure - OS-independence, \var{filename} should use \code{/} characters - to separate path segments, and may not be an absolute path - (i.e., it may not begin with \code{/}). - \item If \var{module_relative} is \code{False}, then \var{filename} - specifies an OS-specific path. The path may be absolute or - relative; relative paths are resolved with respect to the - current working directory. - \end{itemize} - - Optional argument \var{name} gives the name of the test; by default, - or if \code{None}, \code{os.path.basename(\var{filename})} is used. - - Optional argument \var{package} is a Python package or the name of a - Python package whose directory should be used as the base directory - for a module-relative filename. If no package is specified, then - the calling module's directory is used as the base directory for - module-relative filenames. It is an error to specify \var{package} - if \var{module_relative} is \code{False}. - - Optional argument \var{globs} gives a dict to be used as the globals - when executing examples. A new shallow copy of this dict is - created for the doctest, so its examples start with a clean slate. - By default, or if \code{None}, a new empty dict is used. - - Optional argument \var{extraglobs} gives a dict merged into the - globals used to execute examples. This works like - \method{dict.update()}: if \var{globs} and \var{extraglobs} have a - common key, the associated value in \var{extraglobs} appears in the - combined dict. By default, or if \code{None}, no extra globals are - used. This is an advanced feature that allows parameterization of - doctests. For example, a doctest can be written for a base class, using - a generic name for the class, then reused to test any number of - subclasses by passing an \var{extraglobs} dict mapping the generic - name to the subclass to be tested. - - Optional argument \var{verbose} prints lots of stuff if true, and prints - only failures if false; by default, or if \code{None}, it's true - if and only if \code{'-v'} is in \code{sys.argv}. - - Optional argument \var{report} prints a summary at the end when true, - else prints nothing at the end. In verbose mode, the summary is - detailed, else the summary is very brief (in fact, empty if all tests - passed). - - Optional argument \var{optionflags} or's together option flags. See - section~\ref{doctest-options}. - - Optional argument \var{raise_on_error} defaults to false. If true, - an exception is raised upon the first failure or unexpected exception - in an example. This allows failures to be post-mortem debugged. - Default behavior is to continue running examples. - - Optional argument \var{parser} specifies a \class{DocTestParser} (or - subclass) that should be used to extract tests from the files. It - defaults to a normal parser (i.e., \code{\class{DocTestParser}()}). - - Optional argument \var{encoding} specifies an encoding that should - be used to convert the file to unicode. - - \versionadded{2.4} - - \versionchanged[The parameter \var{encoding} was added]{2.5} - -\end{funcdesc} - -\begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{, - globs}\optional{, verbose}\optional{, - report}\optional{, - optionflags}\optional{, extraglobs}\optional{, - raise_on_error}\optional{, exclude_empty}} - - All arguments are optional, and all except for \var{m} should be - specified in keyword form. - - Test examples in docstrings in functions and classes reachable - from module \var{m} (or module \module{__main__} if \var{m} is not - supplied or is \code{None}), starting with \code{\var{m}.__doc__}. - - Also test examples reachable from dict \code{\var{m}.__test__}, if it - exists and is not \code{None}. \code{\var{m}.__test__} maps - names (strings) to functions, classes and strings; function and class - docstrings are searched for examples; strings are searched directly, - as if they were docstrings. - - Only docstrings attached to objects belonging to module \var{m} are - searched. - - Return \samp{(\var{failure_count}, \var{test_count})}. - - Optional argument \var{name} gives the name of the module; by default, - or if \code{None}, \code{\var{m}.__name__} is used. - - Optional argument \var{exclude_empty} defaults to false. If true, - objects for which no doctests are found are excluded from consideration. - The default is a backward compatibility hack, so that code still - using \method{doctest.master.summarize()} in conjunction with - \function{testmod()} continues to get output for objects with no tests. - The \var{exclude_empty} argument to the newer \class{DocTestFinder} - constructor defaults to true. - - Optional arguments \var{extraglobs}, \var{verbose}, \var{report}, - \var{optionflags}, \var{raise_on_error}, and \var{globs} are the same as - for function \function{testfile()} above, except that \var{globs} - defaults to \code{\var{m}.__dict__}. - - \versionchanged[The parameter \var{optionflags} was added]{2.3} - - \versionchanged[The parameters \var{extraglobs}, \var{raise_on_error} - and \var{exclude_empty} were added]{2.4} - - \versionchanged[The optional argument \var{isprivate}, deprecated - in 2.4, was removed]{2.5} - -\end{funcdesc} - -There's also a function to run the doctests associated with a single object. -This function is provided for backward compatibility. There are no plans -to deprecate it, but it's rarely useful: - -\begin{funcdesc}{run_docstring_examples}{f, globs\optional{, - verbose}\optional{, name}\optional{, - compileflags}\optional{, optionflags}} - - Test examples associated with object \var{f}; for example, \var{f} may - be a module, function, or class object. - - A shallow copy of dictionary argument \var{globs} is used for the - execution context. - - Optional argument \var{name} is used in failure messages, and defaults - to \code{"NoName"}. - - If optional argument \var{verbose} is true, output is generated even - if there are no failures. By default, output is generated only in case - of an example failure. - - Optional argument \var{compileflags} gives the set of flags that should - be used by the Python compiler when running the examples. By default, or - if \code{None}, flags are deduced corresponding to the set of future - features found in \var{globs}. - - Optional argument \var{optionflags} works as for function - \function{testfile()} above. -\end{funcdesc} - -\subsection{Unittest API\label{doctest-unittest-api}} - -As your collection of doctest'ed modules grows, you'll want a way to run -all their doctests systematically. Prior to Python 2.4, \refmodule{doctest} -had a barely documented \class{Tester} class that supplied a rudimentary -way to combine doctests from multiple modules. \class{Tester} was feeble, -and in practice most serious Python testing frameworks build on the -\refmodule{unittest} module, which supplies many flexible ways to combine -tests from multiple sources. So, in Python 2.4, \refmodule{doctest}'s -\class{Tester} class is deprecated, and \refmodule{doctest} provides two -functions that can be used to create \refmodule{unittest} test suites from -modules and text files containing doctests. These test suites can then be -run using \refmodule{unittest} test runners: - -\begin{verbatim} -import unittest -import doctest -import my_module_with_doctests, and_another - -suite = unittest.TestSuite() -for mod in my_module_with_doctests, and_another: - suite.addTest(doctest.DocTestSuite(mod)) -runner = unittest.TextTestRunner() -runner.run(suite) -\end{verbatim} - -There are two main functions for creating \class{\refmodule{unittest}.TestSuite} -instances from text files and modules with doctests: - -\begin{funcdesc}{DocFileSuite}{\optional{module_relative}\optional{, - package}\optional{, setUp}\optional{, - tearDown}\optional{, globs}\optional{, - optionflags}\optional{, parser}\optional{, - encoding}} - - Convert doctest tests from one or more text files to a - \class{\refmodule{unittest}.TestSuite}. - - The returned \class{\refmodule{unittest}.TestSuite} is to be run by the - unittest framework and runs the interactive examples in each file. If an - example in any file fails, then the synthesized unit test fails, and a - \exception{failureException} exception is raised showing the name of the - file containing the test and a (sometimes approximate) line number. - - Pass one or more paths (as strings) to text files to be examined. - - Options may be provided as keyword arguments: - - Optional argument \var{module_relative} specifies how - the filenames in \var{paths} should be interpreted: - - \begin{itemize} - \item If \var{module_relative} is \code{True} (the default), then - each filename specifies an OS-independent module-relative - path. By default, this path is relative to the calling - module's directory; but if the \var{package} argument is - specified, then it is relative to that package. To ensure - OS-independence, each filename should use \code{/} characters - to separate path segments, and may not be an absolute path - (i.e., it may not begin with \code{/}). - \item If \var{module_relative} is \code{False}, then each filename - specifies an OS-specific path. The path may be absolute or - relative; relative paths are resolved with respect to the - current working directory. - \end{itemize} - - Optional argument \var{package} is a Python package or the name - of a Python package whose directory should be used as the base - directory for module-relative filenames. If no package is - specified, then the calling module's directory is used as the base - directory for module-relative filenames. It is an error to specify - \var{package} if \var{module_relative} is \code{False}. - - Optional argument \var{setUp} specifies a set-up function for - the test suite. This is called before running the tests in each - file. The \var{setUp} function will be passed a \class{DocTest} - object. The setUp function can access the test globals as the - \var{globs} attribute of the test passed. - - Optional argument \var{tearDown} specifies a tear-down function - for the test suite. This is called after running the tests in each - file. The \var{tearDown} function will be passed a \class{DocTest} - object. The setUp function can access the test globals as the - \var{globs} attribute of the test passed. - - Optional argument \var{globs} is a dictionary containing the - initial global variables for the tests. A new copy of this - dictionary is created for each test. By default, \var{globs} is - a new empty dictionary. - - Optional argument \var{optionflags} specifies the default - doctest options for the tests, created by or-ing together - individual option flags. See section~\ref{doctest-options}. - See function \function{set_unittest_reportflags()} below for - a better way to set reporting options. - - Optional argument \var{parser} specifies a \class{DocTestParser} (or - subclass) that should be used to extract tests from the files. It - defaults to a normal parser (i.e., \code{\class{DocTestParser}()}). - - Optional argument \var{encoding} specifies an encoding that should - be used to convert the file to unicode. - - \versionadded{2.4} - - \versionchanged[The global \code{__file__} was added to the - globals provided to doctests loaded from a text file using - \function{DocFileSuite()}]{2.5} - - \versionchanged[The parameter \var{encoding} was added]{2.5} - -\end{funcdesc} - -\begin{funcdesc}{DocTestSuite}{\optional{module}\optional{, - globs}\optional{, extraglobs}\optional{, - test_finder}\optional{, setUp}\optional{, - tearDown}\optional{, checker}} - Convert doctest tests for a module to a - \class{\refmodule{unittest}.TestSuite}. - - The returned \class{\refmodule{unittest}.TestSuite} is to be run by the - unittest framework and runs each doctest in the module. If any of the - doctests fail, then the synthesized unit test fails, and a - \exception{failureException} exception is raised showing the name of the - file containing the test and a (sometimes approximate) line number. - - Optional argument \var{module} provides the module to be tested. It - can be a module object or a (possibly dotted) module name. If not - specified, the module calling this function is used. - - Optional argument \var{globs} is a dictionary containing the - initial global variables for the tests. A new copy of this - dictionary is created for each test. By default, \var{globs} is - a new empty dictionary. - - Optional argument \var{extraglobs} specifies an extra set of - global variables, which is merged into \var{globs}. By default, no - extra globals are used. - - Optional argument \var{test_finder} is the \class{DocTestFinder} - object (or a drop-in replacement) that is used to extract doctests - from the module. - - Optional arguments \var{setUp}, \var{tearDown}, and \var{optionflags} - are the same as for function \function{DocFileSuite()} above. - - \versionadded{2.3} - - \versionchanged[The parameters \var{globs}, \var{extraglobs}, - \var{test_finder}, \var{setUp}, \var{tearDown}, and - \var{optionflags} were added; this function now uses the same search - technique as \function{testmod()}]{2.4} -\end{funcdesc} - -Under the covers, \function{DocTestSuite()} creates a -\class{\refmodule{unittest}.TestSuite} out of \class{doctest.DocTestCase} -instances, and \class{DocTestCase} is a subclass of -\class{\refmodule{unittest}.TestCase}. \class{DocTestCase} isn't documented -here (it's an internal detail), but studying its code can answer questions -about the exact details of \refmodule{unittest} integration. - -Similarly, \function{DocFileSuite()} creates a -\class{\refmodule{unittest}.TestSuite} out of \class{doctest.DocFileCase} -instances, and \class{DocFileCase} is a subclass of \class{DocTestCase}. - -So both ways of creating a \class{\refmodule{unittest}.TestSuite} run -instances of \class{DocTestCase}. This is important for a subtle reason: -when you run \refmodule{doctest} functions yourself, you can control the -\refmodule{doctest} options in use directly, by passing option flags to -\refmodule{doctest} functions. However, if you're writing a -\refmodule{unittest} framework, \refmodule{unittest} ultimately controls -when and how tests get run. The framework author typically wants to -control \refmodule{doctest} reporting options (perhaps, e.g., specified by -command line options), but there's no way to pass options through -\refmodule{unittest} to \refmodule{doctest} test runners. - -For this reason, \refmodule{doctest} also supports a notion of -\refmodule{doctest} reporting flags specific to \refmodule{unittest} -support, via this function: - -\begin{funcdesc}{set_unittest_reportflags}{flags} - Set the \refmodule{doctest} reporting flags to use. - - Argument \var{flags} or's together option flags. See - section~\ref{doctest-options}. Only "reporting flags" can be used. - - This is a module-global setting, and affects all future doctests run by - module \refmodule{unittest}: the \method{runTest()} method of - \class{DocTestCase} looks at the option flags specified for the test case - when the \class{DocTestCase} instance was constructed. If no reporting - flags were specified (which is the typical and expected case), - \refmodule{doctest}'s \refmodule{unittest} reporting flags are or'ed into - the option flags, and the option flags so augmented are passed to the - \class{DocTestRunner} instance created to run the doctest. If any - reporting flags were specified when the \class{DocTestCase} instance was - constructed, \refmodule{doctest}'s \refmodule{unittest} reporting flags - are ignored. - - The value of the \refmodule{unittest} reporting flags in effect before the - function was called is returned by the function. - - \versionadded{2.4} -\end{funcdesc} - - -\subsection{Advanced API\label{doctest-advanced-api}} - -The basic API is a simple wrapper that's intended to make doctest easy -to use. It is fairly flexible, and should meet most users' needs; -however, if you require more fine-grained control over testing, or -wish to extend doctest's capabilities, then you should use the -advanced API. - -The advanced API revolves around two container classes, which are used -to store the interactive examples extracted from doctest cases: - -\begin{itemize} -\item \class{Example}: A single python statement, paired with its - expected output. -\item \class{DocTest}: A collection of \class{Example}s, typically - extracted from a single docstring or text file. -\end{itemize} - -Additional processing classes are defined to find, parse, and run, and -check doctest examples: - -\begin{itemize} -\item \class{DocTestFinder}: Finds all docstrings in a given module, - and uses a \class{DocTestParser} to create a \class{DocTest} - from every docstring that contains interactive examples. -\item \class{DocTestParser}: Creates a \class{DocTest} object from - a string (such as an object's docstring). -\item \class{DocTestRunner}: Executes the examples in a - \class{DocTest}, and uses an \class{OutputChecker} to verify - their output. -\item \class{OutputChecker}: Compares the actual output from a - doctest example with the expected output, and decides whether - they match. -\end{itemize} - -The relationships among these processing classes are summarized in the -following diagram: - -\begin{verbatim} - list of: -+------+ +---------+ -|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results -+------+ | ^ +---------+ | ^ (printed) - | | | Example | | | - v | | ... | v | - DocTestParser | Example | OutputChecker - +---------+ -\end{verbatim} - -\subsubsection{DocTest Objects\label{doctest-DocTest}} -\begin{classdesc}{DocTest}{examples, globs, name, filename, lineno, - docstring} - A collection of doctest examples that should be run in a single - namespace. The constructor arguments are used to initialize the - member variables of the same names. - \versionadded{2.4} -\end{classdesc} - -\class{DocTest} defines the following member variables. They are -initialized by the constructor, and should not be modified directly. - -\begin{memberdesc}{examples} - A list of \class{Example} objects encoding the individual - interactive Python examples that should be run by this test. -\end{memberdesc} - -\begin{memberdesc}{globs} - The namespace (aka globals) that the examples should be run in. - This is a dictionary mapping names to values. Any changes to the - namespace made by the examples (such as binding new variables) - will be reflected in \member{globs} after the test is run. -\end{memberdesc} - -\begin{memberdesc}{name} - A string name identifying the \class{DocTest}. Typically, this is - the name of the object or file that the test was extracted from. -\end{memberdesc} - -\begin{memberdesc}{filename} - The name of the file that this \class{DocTest} was extracted from; - or \code{None} if the filename is unknown, or if the - \class{DocTest} was not extracted from a file. -\end{memberdesc} - -\begin{memberdesc}{lineno} - The line number within \member{filename} where this - \class{DocTest} begins, or \code{None} if the line number is - unavailable. This line number is zero-based with respect to the - beginning of the file. -\end{memberdesc} - -\begin{memberdesc}{docstring} - The string that the test was extracted from, or `None` if the - string is unavailable, or if the test was not extracted from a - string. -\end{memberdesc} - -\subsubsection{Example Objects\label{doctest-Example}} -\begin{classdesc}{Example}{source, want\optional{, - exc_msg}\optional{, lineno}\optional{, - indent}\optional{, options}} - A single interactive example, consisting of a Python statement and - its expected output. The constructor arguments are used to - initialize the member variables of the same names. - \versionadded{2.4} -\end{classdesc} - -\class{Example} defines the following member variables. They are -initialized by the constructor, and should not be modified directly. - -\begin{memberdesc}{source} - A string containing the example's source code. This source code - consists of a single Python statement, and always ends with a - newline; the constructor adds a newline when necessary. -\end{memberdesc} - -\begin{memberdesc}{want} - The expected output from running the example's source code (either - from stdout, or a traceback in case of exception). \member{want} - ends with a newline unless no output is expected, in which case - it's an empty string. The constructor adds a newline when - necessary. -\end{memberdesc} - -\begin{memberdesc}{exc_msg} - The exception message generated by the example, if the example is - expected to generate an exception; or \code{None} if it is not - expected to generate an exception. This exception message is - compared against the return value of - \function{traceback.format_exception_only()}. \member{exc_msg} - ends with a newline unless it's \code{None}. The constructor adds - a newline if needed. -\end{memberdesc} - -\begin{memberdesc}{lineno} - The line number within the string containing this example where - the example begins. This line number is zero-based with respect - to the beginning of the containing string. -\end{memberdesc} - -\begin{memberdesc}{indent} - The example's indentation in the containing string, i.e., the - number of space characters that precede the example's first - prompt. -\end{memberdesc} - -\begin{memberdesc}{options} - A dictionary mapping from option flags to \code{True} or - \code{False}, which is used to override default options for this - example. Any option flags not contained in this dictionary are - left at their default value (as specified by the - \class{DocTestRunner}'s \member{optionflags}). - By default, no options are set. -\end{memberdesc} - -\subsubsection{DocTestFinder objects\label{doctest-DocTestFinder}} -\begin{classdesc}{DocTestFinder}{\optional{verbose}\optional{, - parser}\optional{, recurse}\optional{, - exclude_empty}} - A processing class used to extract the \class{DocTest}s that are - relevant to a given object, from its docstring and the docstrings - of its contained objects. \class{DocTest}s can currently be - extracted from the following object types: modules, functions, - classes, methods, staticmethods, classmethods, and properties. - - The optional argument \var{verbose} can be used to display the - objects searched by the finder. It defaults to \code{False} (no - output). - - The optional argument \var{parser} specifies the - \class{DocTestParser} object (or a drop-in replacement) that is - used to extract doctests from docstrings. - - If the optional argument \var{recurse} is false, then - \method{DocTestFinder.find()} will only examine the given object, - and not any contained objects. - - If the optional argument \var{exclude_empty} is false, then - \method{DocTestFinder.find()} will include tests for objects with - empty docstrings. - - \versionadded{2.4} -\end{classdesc} - -\class{DocTestFinder} defines the following method: - -\begin{methoddesc}{find}{obj\optional{, name}\optional{, - module}\optional{, globs}\optional{, extraglobs}} - Return a list of the \class{DocTest}s that are defined by - \var{obj}'s docstring, or by any of its contained objects' - docstrings. - - The optional argument \var{name} specifies the object's name; this - name will be used to construct names for the returned - \class{DocTest}s. If \var{name} is not specified, then - \code{\var{obj}.__name__} is used. - - The optional parameter \var{module} is the module that contains - the given object. If the module is not specified or is None, then - the test finder will attempt to automatically determine the - correct module. The object's module is used: - - \begin{itemize} - \item As a default namespace, if \var{globs} is not specified. - \item To prevent the DocTestFinder from extracting DocTests - from objects that are imported from other modules. (Contained - objects with modules other than \var{module} are ignored.) - \item To find the name of the file containing the object. - \item To help find the line number of the object within its file. - \end{itemize} - - If \var{module} is \code{False}, no attempt to find the module - will be made. This is obscure, of use mostly in testing doctest - itself: if \var{module} is \code{False}, or is \code{None} but - cannot be found automatically, then all objects are considered to - belong to the (non-existent) module, so all contained objects will - (recursively) be searched for doctests. - - The globals for each \class{DocTest} is formed by combining - \var{globs} and \var{extraglobs} (bindings in \var{extraglobs} - override bindings in \var{globs}). A new shallow copy of the globals - dictionary is created for each \class{DocTest}. If \var{globs} is - not specified, then it defaults to the module's \var{__dict__}, if - specified, or \code{\{\}} otherwise. If \var{extraglobs} is not - specified, then it defaults to \code{\{\}}. -\end{methoddesc} - -\subsubsection{DocTestParser objects\label{doctest-DocTestParser}} -\begin{classdesc}{DocTestParser}{} - A processing class used to extract interactive examples from a - string, and use them to create a \class{DocTest} object. - \versionadded{2.4} -\end{classdesc} - -\class{DocTestParser} defines the following methods: - -\begin{methoddesc}{get_doctest}{string, globs, name, filename, lineno} - Extract all doctest examples from the given string, and collect - them into a \class{DocTest} object. - - \var{globs}, \var{name}, \var{filename}, and \var{lineno} are - attributes for the new \class{DocTest} object. See the - documentation for \class{DocTest} for more information. -\end{methoddesc} - -\begin{methoddesc}{get_examples}{string\optional{, name}} - Extract all doctest examples from the given string, and return - them as a list of \class{Example} objects. Line numbers are - 0-based. The optional argument \var{name} is a name identifying - this string, and is only used for error messages. -\end{methoddesc} - -\begin{methoddesc}{parse}{string\optional{, name}} - Divide the given string into examples and intervening text, and - return them as a list of alternating \class{Example}s and strings. - Line numbers for the \class{Example}s are 0-based. The optional - argument \var{name} is a name identifying this string, and is only - used for error messages. -\end{methoddesc} - -\subsubsection{DocTestRunner objects\label{doctest-DocTestRunner}} -\begin{classdesc}{DocTestRunner}{\optional{checker}\optional{, - verbose}\optional{, optionflags}} - A processing class used to execute and verify the interactive - examples in a \class{DocTest}. - - The comparison between expected outputs and actual outputs is done - by an \class{OutputChecker}. This comparison may be customized - with a number of option flags; see section~\ref{doctest-options} - for more information. If the option flags are insufficient, then - the comparison may also be customized by passing a subclass of - \class{OutputChecker} to the constructor. - - The test runner's display output can be controlled in two ways. - First, an output function can be passed to - \method{TestRunner.run()}; this function will be called with - strings that should be displayed. It defaults to - \code{sys.stdout.write}. If capturing the output is not - sufficient, then the display output can be also customized by - subclassing DocTestRunner, and overriding the methods - \method{report_start}, \method{report_success}, - \method{report_unexpected_exception}, and \method{report_failure}. - - The optional keyword argument \var{checker} specifies the - \class{OutputChecker} object (or drop-in replacement) that should - be used to compare the expected outputs to the actual outputs of - doctest examples. - - The optional keyword argument \var{verbose} controls the - \class{DocTestRunner}'s verbosity. If \var{verbose} is - \code{True}, then information is printed about each example, as it - is run. If \var{verbose} is \code{False}, then only failures are - printed. If \var{verbose} is unspecified, or \code{None}, then - verbose output is used iff the command-line switch \programopt{-v} - is used. - - The optional keyword argument \var{optionflags} can be used to - control how the test runner compares expected output to actual - output, and how it displays failures. For more information, see - section~\ref{doctest-options}. - - \versionadded{2.4} -\end{classdesc} - -\class{DocTestParser} defines the following methods: - -\begin{methoddesc}{report_start}{out, test, example} - Report that the test runner is about to process the given example. - This method is provided to allow subclasses of - \class{DocTestRunner} to customize their output; it should not be - called directly. - - \var{example} is the example about to be processed. \var{test} is - the test containing \var{example}. \var{out} is the output - function that was passed to \method{DocTestRunner.run()}. -\end{methoddesc} - -\begin{methoddesc}{report_success}{out, test, example, got} - Report that the given example ran successfully. This method is - provided to allow subclasses of \class{DocTestRunner} to customize - their output; it should not be called directly. - - \var{example} is the example about to be processed. \var{got} is - the actual output from the example. \var{test} is the test - containing \var{example}. \var{out} is the output function that - was passed to \method{DocTestRunner.run()}. -\end{methoddesc} - -\begin{methoddesc}{report_failure}{out, test, example, got} - Report that the given example failed. This method is provided to - allow subclasses of \class{DocTestRunner} to customize their - output; it should not be called directly. - - \var{example} is the example about to be processed. \var{got} is - the actual output from the example. \var{test} is the test - containing \var{example}. \var{out} is the output function that - was passed to \method{DocTestRunner.run()}. -\end{methoddesc} - -\begin{methoddesc}{report_unexpected_exception}{out, test, example, exc_info} - Report that the given example raised an unexpected exception. - This method is provided to allow subclasses of - \class{DocTestRunner} to customize their output; it should not be - called directly. - - \var{example} is the example about to be processed. - \var{exc_info} is a tuple containing information about the - unexpected exception (as returned by \function{sys.exc_info()}). - \var{test} is the test containing \var{example}. \var{out} is the - output function that was passed to \method{DocTestRunner.run()}. -\end{methoddesc} - -\begin{methoddesc}{run}{test\optional{, compileflags}\optional{, - out}\optional{, clear_globs}} - Run the examples in \var{test} (a \class{DocTest} object), and - display the results using the writer function \var{out}. - - The examples are run in the namespace \code{test.globs}. If - \var{clear_globs} is true (the default), then this namespace will - be cleared after the test runs, to help with garbage collection. - If you would like to examine the namespace after the test - completes, then use \var{clear_globs=False}. - - \var{compileflags} gives the set of flags that should be used by - the Python compiler when running the examples. If not specified, - then it will default to the set of future-import flags that apply - to \var{globs}. - - The output of each example is checked using the - \class{DocTestRunner}'s output checker, and the results are - formatted by the \method{DocTestRunner.report_*} methods. -\end{methoddesc} - -\begin{methoddesc}{summarize}{\optional{verbose}} - Print a summary of all the test cases that have been run by this - DocTestRunner, and return a tuple \samp{(\var{failure_count}, - \var{test_count})}. - - The optional \var{verbose} argument controls how detailed the - summary is. If the verbosity is not specified, then the - \class{DocTestRunner}'s verbosity is used. -\end{methoddesc} - -\subsubsection{OutputChecker objects\label{doctest-OutputChecker}} - -\begin{classdesc}{OutputChecker}{} - A class used to check the whether the actual output from a doctest - example matches the expected output. \class{OutputChecker} - defines two methods: \method{check_output}, which compares a given - pair of outputs, and returns true if they match; and - \method{output_difference}, which returns a string describing the - differences between two outputs. - \versionadded{2.4} -\end{classdesc} - -\class{OutputChecker} defines the following methods: - -\begin{methoddesc}{check_output}{want, got, optionflags} - Return \code{True} iff the actual output from an example - (\var{got}) matches the expected output (\var{want}). These - strings are always considered to match if they are identical; but - depending on what option flags the test runner is using, several - non-exact match types are also possible. See - section~\ref{doctest-options} for more information about option - flags. -\end{methoddesc} - -\begin{methoddesc}{output_difference}{example, got, optionflags} - Return a string describing the differences between the expected - output for a given example (\var{example}) and the actual output - (\var{got}). \var{optionflags} is the set of option flags used to - compare \var{want} and \var{got}. -\end{methoddesc} - -\subsection{Debugging\label{doctest-debugging}} - -Doctest provides several mechanisms for debugging doctest examples: - -\begin{itemize} -\item Several functions convert doctests to executable Python - programs, which can be run under the Python debugger, \refmodule{pdb}. -\item The \class{DebugRunner} class is a subclass of - \class{DocTestRunner} that raises an exception for the first - failing example, containing information about that example. - This information can be used to perform post-mortem debugging on - the example. -\item The \refmodule{unittest} cases generated by \function{DocTestSuite()} - support the \method{debug()} method defined by - \class{\refmodule{unittest}.TestCase}. -\item You can add a call to \function{\refmodule{pdb}.set_trace()} in a - doctest example, and you'll drop into the Python debugger when that - line is executed. Then you can inspect current values of variables, - and so on. For example, suppose \file{a.py} contains just this - module docstring: - -\begin{verbatim} -""" ->>> def f(x): -... g(x*2) ->>> def g(x): -... print x+3 -... import pdb; pdb.set_trace() ->>> f(3) -9 -""" -\end{verbatim} - - Then an interactive Python session may look like this: - -\begin{verbatim} ->>> import a, doctest ->>> doctest.testmod(a) ---Return-- -> <doctest a[1]>(3)g()->None --> import pdb; pdb.set_trace() -(Pdb) list - 1 def g(x): - 2 print x+3 - 3 -> import pdb; pdb.set_trace() -[EOF] -(Pdb) print x -6 -(Pdb) step ---Return-- -> <doctest a[0]>(2)f()->None --> g(x*2) -(Pdb) list - 1 def f(x): - 2 -> g(x*2) -[EOF] -(Pdb) print x -3 -(Pdb) step ---Return-- -> <doctest a[2]>(1)?()->None --> f(3) -(Pdb) cont -(0, 3) ->>> -\end{verbatim} - - \versionchanged[The ability to use \function{\refmodule{pdb}.set_trace()} - usefully inside doctests was added]{2.4} -\end{itemize} - -Functions that convert doctests to Python code, and possibly run -the synthesized code under the debugger: - -\begin{funcdesc}{script_from_examples}{s} - Convert text with examples to a script. - - Argument \var{s} is a string containing doctest examples. The string - is converted to a Python script, where doctest examples in \var{s} - are converted to regular code, and everything else is converted to - Python comments. The generated script is returned as a string. - For example, - - \begin{verbatim} - import doctest - print doctest.script_from_examples(r""" - Set x and y to 1 and 2. - >>> x, y = 1, 2 - - Print their sum: - >>> print x+y - 3 - """) - \end{verbatim} - - displays: - - \begin{verbatim} - # Set x and y to 1 and 2. - x, y = 1, 2 - # - # Print their sum: - print x+y - # Expected: - ## 3 - \end{verbatim} - - This function is used internally by other functions (see below), but - can also be useful when you want to transform an interactive Python - session into a Python script. - - \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{testsource}{module, name} - Convert the doctest for an object to a script. - - Argument \var{module} is a module object, or dotted name of a module, - containing the object whose doctests are of interest. Argument - \var{name} is the name (within the module) of the object with the - doctests of interest. The result is a string, containing the - object's docstring converted to a Python script, as described for - \function{script_from_examples()} above. For example, if module - \file{a.py} contains a top-level function \function{f()}, then - -\begin{verbatim} -import a, doctest -print doctest.testsource(a, "a.f") -\end{verbatim} - - prints a script version of function \function{f()}'s docstring, - with doctests converted to code, and the rest placed in comments. - - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{debug}{module, name\optional{, pm}} - Debug the doctests for an object. - - The \var{module} and \var{name} arguments are the same as for function - \function{testsource()} above. The synthesized Python script for the - named object's docstring is written to a temporary file, and then that - file is run under the control of the Python debugger, \refmodule{pdb}. - - A shallow copy of \code{\var{module}.__dict__} is used for both local - and global execution context. - - Optional argument \var{pm} controls whether post-mortem debugging is - used. If \var{pm} has a true value, the script file is run directly, and - the debugger gets involved only if the script terminates via raising an - unhandled exception. If it does, then post-mortem debugging is invoked, - via \function{\refmodule{pdb}.post_mortem()}, passing the traceback object - from the unhandled exception. If \var{pm} is not specified, or is false, - the script is run under the debugger from the start, via passing an - appropriate \function{exec()} call to \function{\refmodule{pdb}.run()}. - - \versionadded{2.3} - - \versionchanged[The \var{pm} argument was added]{2.4} -\end{funcdesc} - -\begin{funcdesc}{debug_src}{src\optional{, pm}\optional{, globs}} - Debug the doctests in a string. - - This is like function \function{debug()} above, except that - a string containing doctest examples is specified directly, via - the \var{src} argument. - - Optional argument \var{pm} has the same meaning as in function - \function{debug()} above. - - Optional argument \var{globs} gives a dictionary to use as both - local and global execution context. If not specified, or \code{None}, - an empty dictionary is used. If specified, a shallow copy of the - dictionary is used. - - \versionadded{2.4} -\end{funcdesc} - -The \class{DebugRunner} class, and the special exceptions it may raise, -are of most interest to testing framework authors, and will only be -sketched here. See the source code, and especially \class{DebugRunner}'s -docstring (which is a doctest!) for more details: - -\begin{classdesc}{DebugRunner}{\optional{checker}\optional{, - verbose}\optional{, optionflags}} - - A subclass of \class{DocTestRunner} that raises an exception as - soon as a failure is encountered. If an unexpected exception - occurs, an \exception{UnexpectedException} exception is raised, - containing the test, the example, and the original exception. If - the output doesn't match, then a \exception{DocTestFailure} - exception is raised, containing the test, the example, and the - actual output. - - For information about the constructor parameters and methods, see - the documentation for \class{DocTestRunner} in - section~\ref{doctest-advanced-api}. -\end{classdesc} - -There are two exceptions that may be raised by \class{DebugRunner} -instances: - -\begin{excclassdesc}{DocTestFailure}{test, example, got} - An exception thrown by \class{DocTestRunner} to signal that a - doctest example's actual output did not match its expected output. - The constructor arguments are used to initialize the member - variables of the same names. -\end{excclassdesc} -\exception{DocTestFailure} defines the following member variables: -\begin{memberdesc}{test} - The \class{DocTest} object that was being run when the example failed. -\end{memberdesc} -\begin{memberdesc}{example} - The \class{Example} that failed. -\end{memberdesc} -\begin{memberdesc}{got} - The example's actual output. -\end{memberdesc} - -\begin{excclassdesc}{UnexpectedException}{test, example, exc_info} - An exception thrown by \class{DocTestRunner} to signal that a - doctest example raised an unexpected exception. The constructor - arguments are used to initialize the member variables of the same - names. -\end{excclassdesc} -\exception{UnexpectedException} defines the following member variables: -\begin{memberdesc}{test} - The \class{DocTest} object that was being run when the example failed. -\end{memberdesc} -\begin{memberdesc}{example} - The \class{Example} that failed. -\end{memberdesc} -\begin{memberdesc}{exc_info} - A tuple containing information about the unexpected exception, as - returned by \function{sys.exc_info()}. -\end{memberdesc} - -\subsection{Soapbox\label{doctest-soapbox}} - -As mentioned in the introduction, \refmodule{doctest} has grown to have -three primary uses: - -\begin{enumerate} -\item Checking examples in docstrings. -\item Regression testing. -\item Executable documentation / literate testing. -\end{enumerate} - -These uses have different requirements, and it is important to -distinguish them. In particular, filling your docstrings with obscure -test cases makes for bad documentation. - -When writing a docstring, choose docstring examples with care. -There's an art to this that needs to be learned---it may not be -natural at first. Examples should add genuine value to the -documentation. A good example can often be worth many words. -If done with care, the examples will be invaluable for your users, and -will pay back the time it takes to collect them many times over as the -years go by and things change. I'm still amazed at how often one of -my \refmodule{doctest} examples stops working after a "harmless" -change. - -Doctest also makes an excellent tool for regression testing, especially if -you don't skimp on explanatory text. By interleaving prose and examples, -it becomes much easier to keep track of what's actually being tested, and -why. When a test fails, good prose can make it much easier to figure out -what the problem is, and how it should be fixed. It's true that you could -write extensive comments in code-based testing, but few programmers do. -Many have found that using doctest approaches instead leads to much clearer -tests. Perhaps this is simply because doctest makes writing prose a little -easier than writing code, while writing comments in code is a little -harder. I think it goes deeper than just that: the natural attitude -when writing a doctest-based test is that you want to explain the fine -points of your software, and illustrate them with examples. This in -turn naturally leads to test files that start with the simplest features, -and logically progress to complications and edge cases. A coherent -narrative is the result, instead of a collection of isolated functions -that test isolated bits of functionality seemingly at random. It's -a different attitude, and produces different results, blurring the -distinction between testing and explaining. - -Regression testing is best confined to dedicated objects or files. There -are several options for organizing tests: - -\begin{itemize} -\item Write text files containing test cases as interactive examples, - and test the files using \function{testfile()} or - \function{DocFileSuite()}. This is recommended, although is - easiest to do for new projects, designed from the start to use - doctest. -\item Define functions named \code{_regrtest_\textit{topic}} that - consist of single docstrings, containing test cases for the - named topics. These functions can be included in the same file - as the module, or separated out into a separate test file. -\item Define a \code{__test__} dictionary mapping from regression test - topics to docstrings containing test cases. -\end{itemize} diff --git a/Doc/lib/libdocxmlrpc.tex b/Doc/lib/libdocxmlrpc.tex deleted file mode 100644 index f93b3b2..0000000 --- a/Doc/lib/libdocxmlrpc.tex +++ /dev/null @@ -1,109 +0,0 @@ -\section{\module{DocXMLRPCServer} --- - Self-documenting XML-RPC server} - -\declaremodule{standard}{DocXMLRPCServer} -\modulesynopsis{Self-documenting XML-RPC server implementation.} -\moduleauthor{Brian Quinlan}{brianq@activestate.com} -\sectionauthor{Brian Quinlan}{brianq@activestate.com} - -\versionadded{2.3} - -The \module{DocXMLRPCServer} module extends the classes found in -\module{SimpleXMLRPCServer} to serve HTML documentation in response to -HTTP GET requests. Servers can either be free standing, using -\class{DocXMLRPCServer}, or embedded in a CGI environment, using -\class{DocCGIXMLRPCRequestHandler}. - -\begin{classdesc}{DocXMLRPCServer}{addr\optional{, - requestHandler\optional{, - logRequests\optional{, - allow_none\optional{, - encoding\optional{, - bind_and_activate}}}}}} - -Create a new server instance. All parameters have the same meaning as -for \class{SimpleXMLRPCServer.SimpleXMLRPCServer}; -\var{requestHandler} defaults to \class{DocXMLRPCRequestHandler}. - -\end{classdesc} - -\begin{classdesc}{DocCGIXMLRPCRequestHandler}{} - -Create a new instance to handle XML-RPC requests in a CGI environment. - -\end{classdesc} - -\begin{classdesc}{DocXMLRPCRequestHandler}{} - -Create a new request handler instance. This request handler supports -XML-RPC POST requests, documentation GET requests, and modifies -logging so that the \var{logRequests} parameter to the -\class{DocXMLRPCServer} constructor parameter is honored. - -\end{classdesc} - -\subsection{DocXMLRPCServer Objects \label{doc-xmlrpc-servers}} - -The \class{DocXMLRPCServer} class is derived from -\class{SimpleXMLRPCServer.SimpleXMLRPCServer} and provides a means of -creating self-documenting, stand alone XML-RPC servers. HTTP POST -requests are handled as XML-RPC method calls. HTTP GET requests are -handled by generating pydoc-style HTML documentation. This allows a -server to provide its own web-based documentation. - -\begin{methoddesc}[DocXMLRPCServer]{set_server_title}{server_title} - -Set the title used in the generated HTML documentation. This title -will be used inside the HTML "title" element. - -\end{methoddesc} - -\begin{methoddesc}[DocXMLRPCServer]{set_server_name}{server_name} - -Set the name used in the generated HTML documentation. This name will -appear at the top of the generated documentation inside a "h1" -element. - -\end{methoddesc} - - -\begin{methoddesc}[DocXMLRPCServer]{set_server_documentation}{server_documentation} - -Set the description used in the generated HTML documentation. This -description will appear as a paragraph, below the server name, in the -documentation. - -\end{methoddesc} - -\subsection{DocCGIXMLRPCRequestHandler} - -The \class{DocCGIXMLRPCRequestHandler} class is derived from -\class{SimpleXMLRPCServer.CGIXMLRPCRequestHandler} and provides a means -of creating self-documenting, XML-RPC CGI scripts. HTTP POST requests -are handled as XML-RPC method calls. HTTP GET requests are handled by -generating pydoc-style HTML documentation. This allows a server to -provide its own web-based documentation. - -\begin{methoddesc}[DocCGIXMLRPCRequestHandler]{set_server_title}{server_title} - -Set the title used in the generated HTML documentation. This title -will be used inside the HTML "title" element. - -\end{methoddesc} - -\begin{methoddesc}[DocCGIXMLRPCRequestHandler]{set_server_name}{server_name} - -Set the name used in the generated HTML documentation. This name will -appear at the top of the generated documentation inside a "h1" -element. - -\end{methoddesc} - - -\begin{methoddesc}[DocCGIXMLRPCRequestHandler]{set_server_documentation}{server_documentation} - -Set the description used in the generated HTML documentation. This -description will appear as a paragraph, below the server name, in the -documentation. - -\end{methoddesc} diff --git a/Doc/lib/libdumbdbm.tex b/Doc/lib/libdumbdbm.tex deleted file mode 100644 index d0917be..0000000 --- a/Doc/lib/libdumbdbm.tex +++ /dev/null @@ -1,63 +0,0 @@ -\section{\module{dumbdbm} --- - Portable DBM implementation} - -\declaremodule{standard}{dumbdbm} -\modulesynopsis{Portable implementation of the simple DBM interface.} - -\index{databases} - -\begin{notice} -The \module{dumbdbm} module is intended as a last resort fallback for -the \refmodule{anydbm} module when no more robust module is available. -The \module{dumbdbm} module is not written for speed and is not nearly as -heavily used as the other database modules. -\end{notice} - -The \module{dumbdbm} module provides a persistent dictionary-like interface -which is written entirely in Python. Unlike other modules such as -\refmodule{gdbm} and \refmodule{bsddb}, no external library is required. As -with other persistent mappings, the keys and values must always be strings. - -The module defines the following: - -\begin{excdesc}{error} -Raised on dumbdbm-specific errors, such as I/O errors. \exception{KeyError} -is raised for general mapping errors like specifying an incorrect key. -\end{excdesc} - -\begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}} -Open a dumbdbm database and return a dumbdbm object. The \var{filename} -argument is the basename of the database file (without any specific -extensions). When a dumbdbm database is created, files with \file{.dat} and -\file{.dir} extensions are created. - -The optional \var{flag} argument is currently ignored; the database is -always opened for update, and will be created if it does not exist. - -The optional \var{mode} argument is the \UNIX{} mode of the file, used -only when the database has to be created. It defaults to octal -\code{0666} (and will be modified by the prevailing umask). -\versionchanged[The \var{mode} argument was ignored in earlier - versions]{2.2} -\end{funcdesc} - - -\begin{seealso} - \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.} - \seemodule{dbm}{Similar interface to the DBM/NDBM library.} - \seemodule{gdbm}{Similar interface to the GNU GDBM library.} - \seemodule{shelve}{Persistence module which stores non-string data.} - \seemodule{whichdb}{Utility module used to determine the type of an - existing database.} -\end{seealso} - - -\subsection{Dumbdbm Objects \label{dumbdbm-objects}} - -In addition to the methods provided by the \class{UserDict.DictMixin} class, -\class{dumbdbm} objects provide the following methods. - -\begin{methoddesc}[dumbdbm]{sync}{} -Synchronize the on-disk directory and data files. This method is called by -the \method{sync} method of \class{Shelve} objects. -\end{methoddesc} diff --git a/Doc/lib/libdummythread.tex b/Doc/lib/libdummythread.tex deleted file mode 100644 index f6b4c56..0000000 --- a/Doc/lib/libdummythread.tex +++ /dev/null @@ -1,22 +0,0 @@ -\section{\module{dummy_thread} --- - Drop-in replacement for the \module{thread} module} - -\declaremodule[dummythread]{standard}{dummy_thread} -\modulesynopsis{Drop-in replacement for the \refmodule{thread} module.} - -This module provides a duplicate interface to the \refmodule{thread} -module. It is meant to be imported when the \refmodule{thread} module -is not provided on a platform. - -Suggested usage is: - -\begin{verbatim} -try: - import thread as _thread -except ImportError: - import dummy_thread as _thread -\end{verbatim} - -Be careful to not use this module where deadlock might occur from a thread -being created that blocks waiting for another thread to be created. This -often occurs with blocking I/O. diff --git a/Doc/lib/libdummythreading.tex b/Doc/lib/libdummythreading.tex deleted file mode 100644 index 874f596..0000000 --- a/Doc/lib/libdummythreading.tex +++ /dev/null @@ -1,22 +0,0 @@ -\section{\module{dummy_threading} --- - Drop-in replacement for the \module{threading} module} - -\declaremodule[dummythreading]{standard}{dummy_threading} -\modulesynopsis{Drop-in replacement for the \refmodule{threading} module.} - -This module provides a duplicate interface to the -\refmodule{threading} module. It is meant to be imported when the -\refmodule{thread} module is not provided on a platform. - -Suggested usage is: - -\begin{verbatim} -try: - import threading as _threading -except ImportError: - import dummy_threading as _threading -\end{verbatim} - -Be careful to not use this module where deadlock might occur from a thread -being created that blocks waiting for another thread to be created. This -often occurs with blocking I/O. diff --git a/Doc/lib/liberrno.tex b/Doc/lib/liberrno.tex deleted file mode 100644 index c0ce6e8..0000000 --- a/Doc/lib/liberrno.tex +++ /dev/null @@ -1,149 +0,0 @@ -\section{\module{errno} --- - Standard errno system symbols} - -\declaremodule{standard}{errno} -\modulesynopsis{Standard errno system symbols.} - - -This module makes available standard \code{errno} system symbols. -The value of each symbol is the corresponding integer value. -The names and descriptions are borrowed from \file{linux/include/errno.h}, -which should be pretty all-inclusive. - -\begin{datadesc}{errorcode} - Dictionary providing a mapping from the errno value to the string - name in the underlying system. For instance, - \code{errno.errorcode[errno.EPERM]} maps to \code{'EPERM'}. -\end{datadesc} - -To translate a numeric error code to an error message, use -\function{os.strerror()}. - -Of the following list, symbols that are not used on the current -platform are not defined by the module. The specific list of defined -symbols is available as \code{errno.errorcode.keys()}. Symbols -available can include: - -\begin{datadesc}{EPERM} Operation not permitted \end{datadesc} -\begin{datadesc}{ENOENT} No such file or directory \end{datadesc} -\begin{datadesc}{ESRCH} No such process \end{datadesc} -\begin{datadesc}{EINTR} Interrupted system call \end{datadesc} -\begin{datadesc}{EIO} I/O error \end{datadesc} -\begin{datadesc}{ENXIO} No such device or address \end{datadesc} -\begin{datadesc}{E2BIG} Arg list too long \end{datadesc} -\begin{datadesc}{ENOEXEC} Exec format error \end{datadesc} -\begin{datadesc}{EBADF} Bad file number \end{datadesc} -\begin{datadesc}{ECHILD} No child processes \end{datadesc} -\begin{datadesc}{EAGAIN} Try again \end{datadesc} -\begin{datadesc}{ENOMEM} Out of memory \end{datadesc} -\begin{datadesc}{EACCES} Permission denied \end{datadesc} -\begin{datadesc}{EFAULT} Bad address \end{datadesc} -\begin{datadesc}{ENOTBLK} Block device required \end{datadesc} -\begin{datadesc}{EBUSY} Device or resource busy \end{datadesc} -\begin{datadesc}{EEXIST} File exists \end{datadesc} -\begin{datadesc}{EXDEV} Cross-device link \end{datadesc} -\begin{datadesc}{ENODEV} No such device \end{datadesc} -\begin{datadesc}{ENOTDIR} Not a directory \end{datadesc} -\begin{datadesc}{EISDIR} Is a directory \end{datadesc} -\begin{datadesc}{EINVAL} Invalid argument \end{datadesc} -\begin{datadesc}{ENFILE} File table overflow \end{datadesc} -\begin{datadesc}{EMFILE} Too many open files \end{datadesc} -\begin{datadesc}{ENOTTY} Not a typewriter \end{datadesc} -\begin{datadesc}{ETXTBSY} Text file busy \end{datadesc} -\begin{datadesc}{EFBIG} File too large \end{datadesc} -\begin{datadesc}{ENOSPC} No space left on device \end{datadesc} -\begin{datadesc}{ESPIPE} Illegal seek \end{datadesc} -\begin{datadesc}{EROFS} Read-only file system \end{datadesc} -\begin{datadesc}{EMLINK} Too many links \end{datadesc} -\begin{datadesc}{EPIPE} Broken pipe \end{datadesc} -\begin{datadesc}{EDOM} Math argument out of domain of func \end{datadesc} -\begin{datadesc}{ERANGE} Math result not representable \end{datadesc} -\begin{datadesc}{EDEADLK} Resource deadlock would occur \end{datadesc} -\begin{datadesc}{ENAMETOOLONG} File name too long \end{datadesc} -\begin{datadesc}{ENOLCK} No record locks available \end{datadesc} -\begin{datadesc}{ENOSYS} Function not implemented \end{datadesc} -\begin{datadesc}{ENOTEMPTY} Directory not empty \end{datadesc} -\begin{datadesc}{ELOOP} Too many symbolic links encountered \end{datadesc} -\begin{datadesc}{EWOULDBLOCK} Operation would block \end{datadesc} -\begin{datadesc}{ENOMSG} No message of desired type \end{datadesc} -\begin{datadesc}{EIDRM} Identifier removed \end{datadesc} -\begin{datadesc}{ECHRNG} Channel number out of range \end{datadesc} -\begin{datadesc}{EL2NSYNC} Level 2 not synchronized \end{datadesc} -\begin{datadesc}{EL3HLT} Level 3 halted \end{datadesc} -\begin{datadesc}{EL3RST} Level 3 reset \end{datadesc} -\begin{datadesc}{ELNRNG} Link number out of range \end{datadesc} -\begin{datadesc}{EUNATCH} Protocol driver not attached \end{datadesc} -\begin{datadesc}{ENOCSI} No CSI structure available \end{datadesc} -\begin{datadesc}{EL2HLT} Level 2 halted \end{datadesc} -\begin{datadesc}{EBADE} Invalid exchange \end{datadesc} -\begin{datadesc}{EBADR} Invalid request descriptor \end{datadesc} -\begin{datadesc}{EXFULL} Exchange full \end{datadesc} -\begin{datadesc}{ENOANO} No anode \end{datadesc} -\begin{datadesc}{EBADRQC} Invalid request code \end{datadesc} -\begin{datadesc}{EBADSLT} Invalid slot \end{datadesc} -\begin{datadesc}{EDEADLOCK} File locking deadlock error \end{datadesc} -\begin{datadesc}{EBFONT} Bad font file format \end{datadesc} -\begin{datadesc}{ENOSTR} Device not a stream \end{datadesc} -\begin{datadesc}{ENODATA} No data available \end{datadesc} -\begin{datadesc}{ETIME} Timer expired \end{datadesc} -\begin{datadesc}{ENOSR} Out of streams resources \end{datadesc} -\begin{datadesc}{ENONET} Machine is not on the network \end{datadesc} -\begin{datadesc}{ENOPKG} Package not installed \end{datadesc} -\begin{datadesc}{EREMOTE} Object is remote \end{datadesc} -\begin{datadesc}{ENOLINK} Link has been severed \end{datadesc} -\begin{datadesc}{EADV} Advertise error \end{datadesc} -\begin{datadesc}{ESRMNT} Srmount error \end{datadesc} -\begin{datadesc}{ECOMM} Communication error on send \end{datadesc} -\begin{datadesc}{EPROTO} Protocol error \end{datadesc} -\begin{datadesc}{EMULTIHOP} Multihop attempted \end{datadesc} -\begin{datadesc}{EDOTDOT} RFS specific error \end{datadesc} -\begin{datadesc}{EBADMSG} Not a data message \end{datadesc} -\begin{datadesc}{EOVERFLOW} Value too large for defined data type \end{datadesc} -\begin{datadesc}{ENOTUNIQ} Name not unique on network \end{datadesc} -\begin{datadesc}{EBADFD} File descriptor in bad state \end{datadesc} -\begin{datadesc}{EREMCHG} Remote address changed \end{datadesc} -\begin{datadesc}{ELIBACC} Can not access a needed shared library \end{datadesc} -\begin{datadesc}{ELIBBAD} Accessing a corrupted shared library \end{datadesc} -\begin{datadesc}{ELIBSCN} .lib section in a.out corrupted \end{datadesc} -\begin{datadesc}{ELIBMAX} Attempting to link in too many shared libraries \end{datadesc} -\begin{datadesc}{ELIBEXEC} Cannot exec a shared library directly \end{datadesc} -\begin{datadesc}{EILSEQ} Illegal byte sequence \end{datadesc} -\begin{datadesc}{ERESTART} Interrupted system call should be restarted \end{datadesc} -\begin{datadesc}{ESTRPIPE} Streams pipe error \end{datadesc} -\begin{datadesc}{EUSERS} Too many users \end{datadesc} -\begin{datadesc}{ENOTSOCK} Socket operation on non-socket \end{datadesc} -\begin{datadesc}{EDESTADDRREQ} Destination address required \end{datadesc} -\begin{datadesc}{EMSGSIZE} Message too long \end{datadesc} -\begin{datadesc}{EPROTOTYPE} Protocol wrong type for socket \end{datadesc} -\begin{datadesc}{ENOPROTOOPT} Protocol not available \end{datadesc} -\begin{datadesc}{EPROTONOSUPPORT} Protocol not supported \end{datadesc} -\begin{datadesc}{ESOCKTNOSUPPORT} Socket type not supported \end{datadesc} -\begin{datadesc}{EOPNOTSUPP} Operation not supported on transport endpoint \end{datadesc} -\begin{datadesc}{EPFNOSUPPORT} Protocol family not supported \end{datadesc} -\begin{datadesc}{EAFNOSUPPORT} Address family not supported by protocol \end{datadesc} -\begin{datadesc}{EADDRINUSE} Address already in use \end{datadesc} -\begin{datadesc}{EADDRNOTAVAIL} Cannot assign requested address \end{datadesc} -\begin{datadesc}{ENETDOWN} Network is down \end{datadesc} -\begin{datadesc}{ENETUNREACH} Network is unreachable \end{datadesc} -\begin{datadesc}{ENETRESET} Network dropped connection because of reset \end{datadesc} -\begin{datadesc}{ECONNABORTED} Software caused connection abort \end{datadesc} -\begin{datadesc}{ECONNRESET} Connection reset by peer \end{datadesc} -\begin{datadesc}{ENOBUFS} No buffer space available \end{datadesc} -\begin{datadesc}{EISCONN} Transport endpoint is already connected \end{datadesc} -\begin{datadesc}{ENOTCONN} Transport endpoint is not connected \end{datadesc} -\begin{datadesc}{ESHUTDOWN} Cannot send after transport endpoint shutdown \end{datadesc} -\begin{datadesc}{ETOOMANYREFS} Too many references: cannot splice \end{datadesc} -\begin{datadesc}{ETIMEDOUT} Connection timed out \end{datadesc} -\begin{datadesc}{ECONNREFUSED} Connection refused \end{datadesc} -\begin{datadesc}{EHOSTDOWN} Host is down \end{datadesc} -\begin{datadesc}{EHOSTUNREACH} No route to host \end{datadesc} -\begin{datadesc}{EALREADY} Operation already in progress \end{datadesc} -\begin{datadesc}{EINPROGRESS} Operation now in progress \end{datadesc} -\begin{datadesc}{ESTALE} Stale NFS file handle \end{datadesc} -\begin{datadesc}{EUCLEAN} Structure needs cleaning \end{datadesc} -\begin{datadesc}{ENOTNAM} Not a XENIX named type file \end{datadesc} -\begin{datadesc}{ENAVAIL} No XENIX semaphores available \end{datadesc} -\begin{datadesc}{EISNAM} Is a named type file \end{datadesc} -\begin{datadesc}{EREMOTEIO} Remote I/O error \end{datadesc} -\begin{datadesc}{EDQUOT} Quota exceeded \end{datadesc} - diff --git a/Doc/lib/libetree.tex b/Doc/lib/libetree.tex deleted file mode 100644 index 6f20ee3..0000000 --- a/Doc/lib/libetree.tex +++ /dev/null @@ -1,426 +0,0 @@ -\section{\module{xml.etree.ElementTree} --- The ElementTree XML API} -\declaremodule{standard}{xml.etree.ElementTree} -\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com} -\modulesynopsis{Implementation of the ElementTree API.} - -\versionadded{2.5} - -The Element type is a flexible container object, designed to store -hierarchical data structures in memory. The type can be described as a -cross between a list and a dictionary. - -Each element has a number of properties associated with it: - -\begin{itemize} - \item a tag which is a string identifying what kind of data - this element represents (the element type, in other words). - \item a number of attributes, stored in a Python dictionary. - \item a text string. - \item an optional tail string. - \item a number of child elements, stored in a Python sequence -\end{itemize} - -To create an element instance, use the Element or SubElement factory -functions. - -The \class{ElementTree} class can be used to wrap an element -structure, and convert it from and to XML. - -A C implementation of this API is available as -\module{xml.etree.cElementTree}. - - -\subsection{Functions\label{elementtree-functions}} - -\begin{funcdesc}{Comment}{\optional{text}} -Comment element factory. This factory function creates a special -element that will be serialized as an XML comment. -The comment string can be either an 8-bit ASCII string or a Unicode -string. -\var{text} is a string containing the comment string. -Returns an element instance representing a comment. -\end{funcdesc} - -\begin{funcdesc}{dump}{elem} -Writes an element tree or element structure to sys.stdout. This -function should be used for debugging only. - -The exact output format is implementation dependent. In this -version, it's written as an ordinary XML file. - -\var{elem} is an element tree or an individual element. -\end{funcdesc} - -\begin{funcdesc}{Element}{tag\optional{, attrib}\optional{, **extra}} -Element factory. This function returns an object implementing the -standard Element interface. The exact class or type of that object -is implementation dependent, but it will always be compatible with -the {\_}ElementInterface class in this module. - -The element name, attribute names, and attribute values can be -either 8-bit ASCII strings or Unicode strings. -\var{tag} is the element name. -\var{attrib} is an optional dictionary, containing element attributes. -\var{extra} contains additional attributes, given as keyword arguments. -Returns an element instance. -\end{funcdesc} - -\begin{funcdesc}{fromstring}{text} -Parses an XML section from a string constant. Same as XML. -\var{text} is a string containing XML data. -Returns an Element instance. -\end{funcdesc} - -\begin{funcdesc}{iselement}{element} -Checks if an object appears to be a valid element object. -\var{element} is an element instance. -Returns a true value if this is an element object. -\end{funcdesc} - -\begin{funcdesc}{iterparse}{source\optional{, events}} -Parses an XML section into an element tree incrementally, and reports -what's going on to the user. -\var{source} is a filename or file object containing XML data. -\var{events} is a list of events to report back. If omitted, only ``end'' -events are reported. -Returns an iterator providing \code{(\var{event}, \var{elem})} pairs. -\end{funcdesc} - -\begin{funcdesc}{parse}{source\optional{, parser}} -Parses an XML section into an element tree. -\var{source} is a filename or file object containing XML data. -\var{parser} is an optional parser instance. If not given, the -standard XMLTreeBuilder parser is used. -Returns an ElementTree instance. -\end{funcdesc} - -\begin{funcdesc}{ProcessingInstruction}{target\optional{, text}} -PI element factory. This factory function creates a special element -that will be serialized as an XML processing instruction. -\var{target} is a string containing the PI target. -\var{text} is a string containing the PI contents, if given. -Returns an element instance, representing a processing instruction. -\end{funcdesc} - -\begin{funcdesc}{SubElement}{parent, tag\optional{, - attrib\optional{, **extra}}} -Subelement factory. This function creates an element instance, and -appends it to an existing element. - -The element name, attribute names, and attribute values can be -either 8-bit ASCII strings or Unicode strings. -\var{parent} is the parent element. -\var{tag} is the subelement name. -\var{attrib} is an optional dictionary, containing element attributes. -\var{extra} contains additional attributes, given as keyword arguments. -Returns an element instance. -\end{funcdesc} - -\begin{funcdesc}{tostring}{element\optional{, encoding}} -Generates a string representation of an XML element, including all -subelements. -\var{element} is an Element instance. -\var{encoding} is the output encoding (default is US-ASCII). -Returns an encoded string containing the XML data. -\end{funcdesc} - -\begin{funcdesc}{XML}{text} -Parses an XML section from a string constant. This function can -be used to embed ``XML literals'' in Python code. -\var{text} is a string containing XML data. -Returns an Element instance. -\end{funcdesc} - -\begin{funcdesc}{XMLID}{text} -Parses an XML section from a string constant, and also returns -a dictionary which maps from element id:s to elements. -\var{text} is a string containing XML data. -Returns a tuple containing an Element instance and a dictionary. -\end{funcdesc} - - -\subsection{The Element Interface\label{elementtree-element-interface}} - -Element objects returned by Element or SubElement have the -following methods and attributes. - -\begin{memberdesc}[Element]{tag} -A string identifying what kind of data this element represents -(the element type, in other words). -\end{memberdesc} - -\begin{memberdesc}[Element]{text} -The \var{text} attribute can be used to hold additional data -associated with the element. -As the name implies this attribute is usually a string but may be any -application-specific object. -If the element is created from an XML file the attribute will contain -any text found between the element tags. -\end{memberdesc} - -\begin{memberdesc}[Element]{tail} -The \var{tail} attribute can be used to hold additional data -associated with the element. -This attribute is usually a string but may be any application-specific object. -If the element is created from an XML file the attribute will contain -any text found after the element's end tag and before the next tag. -\end{memberdesc} - -\begin{memberdesc}[Element]{attrib} -A dictionary containing the element's attributes. -Note that while the \var{attrib} value is always a real mutable Python -dictionary, an ElementTree implementation may choose to use another -internal representation, and create the dictionary only if someone -asks for it. To take advantage of such implementations, use the -dictionary methods below whenever possible. -\end{memberdesc} - -The following dictionary-like methods work on the element attributes. - -\begin{methoddesc}[Element]{clear}{} -Resets an element. This function removes all subelements, clears -all attributes, and sets the text and tail attributes to None. -\end{methoddesc} - -\begin{methoddesc}[Element]{get}{key\optional{, default=None}} -Gets the element attribute named \var{key}. - -Returns the attribute value, or \var{default} if the -attribute was not found. -\end{methoddesc} - -\begin{methoddesc}[Element]{items}{} -Returns the element attributes as a sequence of (name, value) pairs. -The attributes are returned in an arbitrary order. -\end{methoddesc} - -\begin{methoddesc}[Element]{keys}{} -Returns the elements attribute names as a list. -The names are returned in an arbitrary order. -\end{methoddesc} - -\begin{methoddesc}[Element]{set}{key, value} -Set the attribute \var{key} on the element to \var{value}. -\end{methoddesc} - -The following methods work on the element's children (subelements). - -\begin{methoddesc}[Element]{append}{subelement} -Adds the element \var{subelement} to the end of this elements internal list -of subelements. -\end{methoddesc} - -\begin{methoddesc}[Element]{find}{match} -Finds the first subelement matching \var{match}. -\var{match} may be a tag name or path. -Returns an element instance or \code{None}. -\end{methoddesc} - -\begin{methoddesc}[Element]{findall}{match} -Finds all subelements matching \var{match}. -\var{match} may be a tag name or path. -Returns an iterable yielding all matching elements in document order. -\end{methoddesc} - -\begin{methoddesc}[Element]{findtext}{condition\optional{, default=None}} -Finds text for the first subelement matching \var{condition}. -\var{condition} may be a tag name or path. -Returns the text content of the first matching element, or -\var{default} if no element was found. Note that if the -matching element has no text content an empty string is returned. -\end{methoddesc} - -\begin{methoddesc}[Element]{getchildren}{} -Returns all subelements. The elements are returned in document order. -\end{methoddesc} - -\begin{methoddesc}[Element]{getiterator}{\optional{tag=None}} -Creates a tree iterator with the current element as the root. -The iterator iterates over this element and all elements below it -that match the given tag. If tag -is \code{None} or \code{'*'} then all elements are iterated over. -Returns an iterable that provides element objects in document (depth first) -order. -\end{methoddesc} - -\begin{methoddesc}[Element]{insert}{index, element} -Inserts a subelement at the given position in this element. -\end{methoddesc} - -\begin{methoddesc}[Element]{makeelement}{tag, attrib} -Creates a new element object of the same type as this element. -Do not call this method, use the SubElement factory function instead. -\end{methoddesc} - -\begin{methoddesc}[Element]{remove}{subelement} -Removes \var{subelement} from the element. -Unlike the findXXX methods this method compares elements based on -the instance identity, not on tag value or contents. -\end{methoddesc} - -Element objects also support the following sequence type methods for -working with subelements: \method{__delitem__()}, -\method{__getitem__()}, \method{__setitem__()}, \method{__len__()}. - -Caution: Because Element objects do not define a -\method{__nonzero__()} method, elements with no subelements will test -as \code{False}. - -\begin{verbatim} -element = root.find('foo') - -if not element: # careful! - print "element not found, or element has no subelements" - -if element is None: - print "element not found" -\end{verbatim} - - -\subsection{ElementTree Objects\label{elementtree-elementtree-objects}} - -\begin{classdesc}{ElementTree}{\optional{element,} \optional{file}} -ElementTree wrapper class. This class represents an entire element -hierarchy, and adds some extra support for serialization to and from -standard XML. - -\var{element} is the root element. -The tree is initialized with the contents of the XML \var{file} if given. -\end{classdesc} - -\begin{methoddesc}{_setroot}{element} -Replaces the root element for this tree. This discards the -current contents of the tree, and replaces it with the given -element. Use with care. -\var{element} is an element instance. -\end{methoddesc} - -\begin{methoddesc}{find}{path} -Finds the first toplevel element with given tag. -Same as getroot().find(path). -\var{path} is the element to look for. -Returns the first matching element, or \code{None} if no element was found. -\end{methoddesc} - -\begin{methoddesc}{findall}{path} -Finds all toplevel elements with the given tag. -Same as getroot().findall(path). -\var{path} is the element to look for. -Returns a list or iterator containing all matching elements, -in document order. -\end{methoddesc} - -\begin{methoddesc}{findtext}{path\optional{, default}} -Finds the element text for the first toplevel element with given -tag. Same as getroot().findtext(path). -\var{path} is the toplevel element to look for. -\var{default} is the value to return if the element was not found. -Returns the text content of the first matching element, or the -default value no element was found. Note that if the element -has is found, but has no text content, this method returns an -empty string. -\end{methoddesc} - -\begin{methoddesc}{getiterator}{\optional{tag}} -Creates and returns a tree iterator for the root element. The iterator loops -over all elements in this tree, in section order. -\var{tag} is the tag to look for (default is to return all elements) -\end{methoddesc} - -\begin{methoddesc}{getroot}{} -Returns the root element for this tree. -\end{methoddesc} - -\begin{methoddesc}{parse}{source\optional{, parser}} -Loads an external XML section into this element tree. -\var{source} is a file name or file object. -\var{parser} is an optional parser instance. If not given, the -standard XMLTreeBuilder parser is used. -Returns the section root element. -\end{methoddesc} - -\begin{methoddesc}{write}{file\optional{, encoding}} -Writes the element tree to a file, as XML. -\var{file} is a file name, or a file object opened for writing. -\var{encoding} is the output encoding (default is US-ASCII). -\end{methoddesc} - - -\subsection{QName Objects\label{elementtree-qname-objects}} - -\begin{classdesc}{QName}{text_or_uri\optional{, tag}} -QName wrapper. This can be used to wrap a QName attribute value, in -order to get proper namespace handling on output. -\var{text_or_uri} is a string containing the QName value, -in the form {\{}uri{\}}local, or, if the tag argument is given, -the URI part of a QName. -If \var{tag} is given, the first argument is interpreted as -an URI, and this argument is interpreted as a local name. -\class{QName} instances are opaque. -\end{classdesc} - - -\subsection{TreeBuilder Objects\label{elementtree-treebuilder-objects}} - -\begin{classdesc}{TreeBuilder}{\optional{element_factory}} -Generic element structure builder. This builder converts a sequence -of start, data, and end method calls to a well-formed element structure. -You can use this class to build an element structure using a custom XML -parser, or a parser for some other XML-like format. -The \var{element_factory} is called to create new Element instances when -given. -\end{classdesc} - -\begin{methoddesc}{close}{} -Flushes the parser buffers, and returns the toplevel documen -element. -Returns an Element instance. -\end{methoddesc} - -\begin{methoddesc}{data}{data} -Adds text to the current element. -\var{data} is a string. This should be either an 8-bit string -containing ASCII text, or a Unicode string. -\end{methoddesc} - -\begin{methoddesc}{end}{tag} -Closes the current element. -\var{tag} is the element name. -Returns the closed element. -\end{methoddesc} - -\begin{methoddesc}{start}{tag, attrs} -Opens a new element. -\var{tag} is the element name. -\var{attrs} is a dictionary containing element attributes. -Returns the opened element. -\end{methoddesc} - - -\subsection{XMLTreeBuilder Objects\label{elementtree-xmltreebuilder-objects}} - -\begin{classdesc}{XMLTreeBuilder}{\optional{html,} \optional{target}} -Element structure builder for XML source data, based on the -expat parser. -\var{html} are predefined HTML entities. This flag is not supported -by the current implementation. -\var{target} is the target object. If omitted, the builder uses an -instance of the standard TreeBuilder class. -\end{classdesc} - -\begin{methoddesc}{close}{} -Finishes feeding data to the parser. -Returns an element structure. -\end{methoddesc} - -\begin{methoddesc}{doctype}{name, pubid, system} -Handles a doctype declaration. -\var{name} is the doctype name. -\var{pubid} is the public identifier. -\var{system} is the system identifier. -\end{methoddesc} - -\begin{methoddesc}{feed}{data} -Feeds data to the parser. -\var{data} is encoded data. -\end{methoddesc} diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex deleted file mode 100644 index 74531d3..0000000 --- a/Doc/lib/libexcs.tex +++ /dev/null @@ -1,427 +0,0 @@ -\section{Built-in Exceptions} - -\declaremodule{standard}{exceptions} -\modulesynopsis{Standard exception classes.} - - -Exceptions should be class objects. -The exceptions are defined in the module \module{exceptions}. This -module never needs to be imported explicitly: the exceptions are -provided in the built-in namespace as well as the \module{exceptions} -module. - -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}\stindex{raise} statement. If the exception class is -derived from the standard root class \exception{BaseException}, the -associated value is present as the exception instance's \member{args} -attribute. - -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 -situation in which the interpreter raises the same exception; but -beware that there is nothing to prevent user code from raising an -inappropriate error. - -The built-in exception classes can be sub-classed to define new -exceptions; programmers are encouraged to at least derive new -exceptions from the \exception{Exception} class and not -\exception{BaseException}. More -information on defining exceptions is available in the -\citetitle[../tut/tut.html]{Python Tutorial} under the heading -``User-defined Exceptions.'' - -\setindexsubitem{(built-in exception base class)} - -The following exceptions are only used as base classes for other -exceptions. - -\begin{excdesc}{BaseException} -The base class for all built-in exceptions. It is not meant to be directly -inherited by user-defined classes (for that use \exception{Exception}). If -\function{str()} or \function{unicode()} is called on an instance of this -class, the representation of the argument(s) to the instance are returned or -the emptry string when there were no arguments. All arguments are -stored in \member{args} as a tuple. -\versionadded{2.5} -\end{excdesc} - -\begin{excdesc}{Exception} -All built-in, non-system-exiting exceptions are derived -from this class. All user-defined exceptions should also be derived -from this class. -\versionchanged[Changed to inherit from \exception{BaseException}]{2.5} -\end{excdesc} - -\begin{excdesc}{ArithmeticError} -The base class for those built-in exceptions that are raised for -various arithmetic errors: \exception{OverflowError}, -\exception{ZeroDivisionError}, \exception{FloatingPointError}. -\end{excdesc} - -\begin{excdesc}{LookupError} -The base class for the exceptions that are raised when a key or -index used on a mapping or sequence is invalid: \exception{IndexError}, -\exception{KeyError}. This can be raised directly by -\function{sys.setdefaultencoding()}. -\end{excdesc} - -\begin{excdesc}{EnvironmentError} -The base class for exceptions that -can occur outside the Python system: \exception{IOError}, -\exception{OSError}. When exceptions of this type are created with a -2-tuple, the first item is available on the instance's \member{errno} -attribute (it is assumed to be an error number), and the second item -is available on the \member{strerror} attribute (it is usually the -associated error message). The tuple itself is also available on the -\member{args} attribute. -\versionadded{1.5.2} - -When an \exception{EnvironmentError} exception is instantiated with a -3-tuple, the first two items are available as above, while the third -item is available on the \member{filename} attribute. However, for -backwards compatibility, the \member{args} attribute contains only a -2-tuple of the first two constructor arguments. - -The \member{filename} attribute is \code{None} when this exception is -created with other than 3 arguments. The \member{errno} and -\member{strerror} attributes are also \code{None} when the instance was -created with other than 2 or 3 arguments. In this last case, -\member{args} contains the verbatim constructor arguments as a tuple. -\end{excdesc} - - -\setindexsubitem{(built-in exception)} - -The following exceptions are the exceptions that are actually raised. - -\begin{excdesc}{AssertionError} -\stindex{assert} -Raised when an \keyword{assert} statement fails. -\end{excdesc} - -\begin{excdesc}{AttributeError} -% xref to attribute reference? - Raised when an attribute reference or assignment fails. (When an - object does not support attribute references or attribute assignments - at all, \exception{TypeError} is raised.) -\end{excdesc} - -\begin{excdesc}{EOFError} -% XXXJH xrefs here - Raised when attempting to read beyond the end of a file. -% XXXJH xrefs here - (N.B.: the \method{read()} and \method{readline()} methods of file - objects return an empty string when they hit \EOF.) -\end{excdesc} - -\begin{excdesc}{FloatingPointError} - Raised when a floating point operation fails. This exception is - always defined, but can only be raised when Python is configured - with the \longprogramopt{with-fpectl} option, or the - \constant{WANT_SIGFPE_HANDLER} symbol is defined in the - \file{pyconfig.h} file. -\end{excdesc} - -\begin{excdesc}{GeneratorExit} - Raise when a generator's \method{close()} method is called. - \versionadded{2.5} - \versionchanged[Changed to inherit from Exception instead of - StandardError]{3.0} -\end{excdesc} - -\begin{excdesc}{IOError} -% XXXJH xrefs here - Raised when an I/O operation (such as a \keyword{print} statement, - the built-in \function{open()} function or a method of a file - object) fails for an I/O-related reason, e.g., ``file not found'' or - ``disk full''. - - This class is derived from \exception{EnvironmentError}. See the - discussion above for more information on exception instance - attributes. -\end{excdesc} - -\begin{excdesc}{ImportError} -% XXXJH xref to import statement? - Raised when an \keyword{import} statement fails to find the module - definition or when a \code{from \textrm{\ldots} import} fails to find a - name that is to be imported. -\end{excdesc} - -\begin{excdesc}{IndexError} -% XXXJH xref to sequences - Raised when a sequence subscript is out of range. (Slice indices are - silently truncated to fall in the allowed range; if an index is not a - plain integer, \exception{TypeError} is raised.) -\end{excdesc} - -\begin{excdesc}{KeyError} -% XXXJH xref to mapping objects? - Raised when a mapping (dictionary) key is not found in the set of - existing keys. -\end{excdesc} - -\begin{excdesc}{KeyboardInterrupt} - Raised when the user hits the interrupt key (normally - \kbd{Control-C} or \kbd{Delete}). During execution, a check for - interrupts is made regularly. -% XXX(hylton) xrefs here - The exception inherits from \exception{BaseException} so as to not be - accidentally caught by code that catches \exception{Exception} and thus - prevent the interpreter from exiting. - \versionchanged[Changed to inherit from \exception{BaseException}]{2.5} -\end{excdesc} - -\begin{excdesc}{MemoryError} - Raised when an operation runs out of memory but the situation may - still be rescued (by deleting some objects). The associated value is - a string indicating what kind of (internal) operation ran out of memory. - Note that because of the underlying memory management architecture - (C's \cfunction{malloc()} function), the interpreter may not - always be able to completely recover from this situation; it - nevertheless raises an exception so that a stack traceback can be - printed, in case a run-away program was the cause. -\end{excdesc} - -\begin{excdesc}{NameError} - Raised when a local or global name is not found. This applies only - to unqualified names. The associated value is an error message that - includes the name that could not be found. -\end{excdesc} - -\begin{excdesc}{NotImplementedError} - This exception is derived from \exception{RuntimeError}. In user - defined base classes, abstract methods should raise this exception - when they require derived classes to override the method. - \versionadded{1.5.2} -\end{excdesc} - -\begin{excdesc}{OSError} - %xref for os module - This class is derived from \exception{EnvironmentError} and is used - primarily as the \refmodule{os} module's \code{os.error} exception. - See \exception{EnvironmentError} above for a description of the - possible associated values. - \versionadded{1.5.2} -\end{excdesc} - -\begin{excdesc}{OverflowError} -% XXXJH reference to long's and/or int's? - Raised when the result of an arithmetic operation is too large to be - represented. This cannot occur for long integers (which would rather - raise \exception{MemoryError} than give up). Because of the lack of - standardization of floating point exception handling in C, most - floating point operations also aren't checked. For plain integers, - all operations that can overflow are checked except left shift, where - typical applications prefer to drop bits than raise an exception. -\end{excdesc} - -\begin{excdesc}{ReferenceError} - This exception is raised when a weak reference proxy, created by the - \function{\refmodule{weakref}.proxy()} function, is used to access - an attribute of the referent after it has been garbage collected. - For more information on weak references, see the \refmodule{weakref} - module. - \versionadded[Previously known as the - \exception{\refmodule{weakref}.ReferenceError} - exception]{2.2} -\end{excdesc} - -\begin{excdesc}{RuntimeError} - Raised when an error is detected that doesn't fall in any of the - other categories. The associated value is a string indicating what - precisely went wrong. (This exception is mostly a relic from a - previous version of the interpreter; it is not used very much any - more.) -\end{excdesc} - -\begin{excdesc}{StopIteration} - Raised by builtin \function{next()} and an iterator's \method{__next__()} - method to signal that there are no further values. - \versionadded{2.2} - \versionchanged[Changed to inherit from Exception instead of - StandardError]{3.0} -\end{excdesc} - - -\begin{excdesc}{SyntaxError} -% XXXJH xref to these functions? - Raised when the parser encounters a syntax error. This may occur in - an \keyword{import} statement, in a call to the built-in functions - \function{exec()}, \function{eval()} or - \function{input()}, or when reading the initial script or standard - input (also interactively). - - Instances of this class have attributes \member{filename}, - \member{lineno}, \member{offset} and \member{text} for easier access - to the details. \function{str()} of the exception instance returns - only the message. -\end{excdesc} - -\begin{excdesc}{SystemError} - Raised when the interpreter finds an internal error, but the - situation does not look so serious to cause it to abandon all hope. - The associated value is a string indicating what went wrong (in - low-level terms). - - You should report this to the author or maintainer of your Python - interpreter. Be sure to report the version of the Python - interpreter (\code{sys.version}; it is also printed at the start of an - interactive Python session), the exact error message (the exception's - associated value) and if possible the source of the program that - triggered the error. -\end{excdesc} - -\begin{excdesc}{SystemExit} -% XXX(hylton) xref to module sys? - This exception is raised by the \function{sys.exit()} function. When it - is not handled, the Python interpreter exits; no stack traceback is - printed. If the associated value is a plain integer, it specifies the - system exit status (passed to C's \cfunction{exit()} function); if it is - \code{None}, the exit status is zero; if it has another type (such as - a string), the object's value is printed and the exit status is one. - - Instances have an attribute \member{code} which is set to the - proposed exit status or error message (defaulting to \code{None}). - Also, this exception derives directly from \exception{BaseException} and - not \exception{Exception}, since it is not technically an error. - - A call to \function{sys.exit()} is translated into an exception so that - clean-up handlers (\keyword{finally} clauses of \keyword{try} statements) - can be executed, and so that a debugger can execute a script without - running the risk of losing control. The \function{os._exit()} function - can be used if it is absolutely positively necessary to exit - immediately (for example, in the child process after a call to - \function{fork()}). - - The exception inherits from \exception{BaseException} instead of - \exception{Exception} so that it is not - accidentally caught by code that catches \exception{Exception}. This allows - the exception to properly propagate up and cause the interpreter to exit. - \versionchanged[Changed to inherit from \exception{BaseException}]{2.5} -\end{excdesc} - -\begin{excdesc}{TypeError} - Raised when an operation or function is applied to an object - of inappropriate type. The associated value is a string giving - details about the type mismatch. -\end{excdesc} - -\begin{excdesc}{UnboundLocalError} - Raised when a reference is made to a local variable in a function or - method, but no value has been bound to that variable. This is a - subclass of \exception{NameError}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{UnicodeError} - Raised when a Unicode-related encoding or decoding error occurs. It - is a subclass of \exception{ValueError}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{UnicodeEncodeError} - Raised when a Unicode-related error occurs during encoding. It - is a subclass of \exception{UnicodeError}. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{UnicodeDecodeError} - Raised when a Unicode-related error occurs during decoding. It - is a subclass of \exception{UnicodeError}. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{UnicodeTranslateError} - Raised when a Unicode-related error occurs during translating. It - is a subclass of \exception{UnicodeError}. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{ValueError} - Raised when a built-in operation or function receives an argument - that has the right type but an inappropriate value, and the - situation is not described by a more precise exception such as - \exception{IndexError}. -\end{excdesc} - -\begin{excdesc}{WindowsError} - Raised when a Windows-specific error occurs or when the error number - does not correspond to an \cdata{errno} value. The - \member{winerror} and \member{strerror} values are created from the - return values of the \cfunction{GetLastError()} and - \cfunction{FormatMessage()} functions from the Windows Platform API. - The \member{errno} value maps the \member{winerror} value to - corresponding \code{errno.h} values. - This is a subclass of \exception{OSError}. -\versionadded{2.0} -\versionchanged[Previous versions put the \cfunction{GetLastError()} -codes into \member{errno}]{2.5} -\end{excdesc} - -\begin{excdesc}{ZeroDivisionError} - Raised when the second argument of a division or modulo operation is - zero. The associated value is a string indicating the type of the - operands and the operation. -\end{excdesc} - - -\setindexsubitem{(built-in warning)} - -The following exceptions are used as warning categories; see the -\refmodule{warnings} module for more information. - -\begin{excdesc}{Warning} -Base class for warning categories. -\end{excdesc} - -\begin{excdesc}{UserWarning} -Base class for warnings generated by user code. -\end{excdesc} - -\begin{excdesc}{DeprecationWarning} -Base class for warnings about deprecated features. -\end{excdesc} - -\begin{excdesc}{PendingDeprecationWarning} -Base class for warnings about features which will be deprecated in the future. -\end{excdesc} - -\begin{excdesc}{SyntaxWarning} -Base class for warnings about dubious syntax -\end{excdesc} - -\begin{excdesc}{RuntimeWarning} -Base class for warnings about dubious runtime behavior. -\end{excdesc} - -\begin{excdesc}{FutureWarning} -Base class for warnings about constructs that will change semantically -in the future. -\end{excdesc} - -\begin{excdesc}{ImportWarning} -Base class for warnings about probable mistakes in module imports. -\versionadded{2.5} -\end{excdesc} - -\begin{excdesc}{UnicodeWarning} -Base class for warnings related to Unicode. -\versionadded{2.5} -\end{excdesc} - -The class hierarchy for built-in exceptions is: - -\verbatiminput{../../Lib/test/exception_hierarchy.txt} diff --git a/Doc/lib/libfcntl.tex b/Doc/lib/libfcntl.tex deleted file mode 100644 index dc76da3..0000000 --- a/Doc/lib/libfcntl.tex +++ /dev/null @@ -1,174 +0,0 @@ -\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} - -This module performs file control and I/O control on file descriptors. -It is an interface to the \cfunction{fcntl()} and \cfunction{ioctl()} -\UNIX{} routines. - -All functions in this module take a file descriptor \var{fd} as their -first argument. This can be an integer file descriptor, such as -returned by \code{sys.stdin.fileno()}, or a file object, such as -\code{sys.stdin} itself, which provides a \method{fileno()} which -returns a genuine file descriptor. - -The module defines the following functions: - - -\begin{funcdesc}{fcntl}{fd, op\optional{, arg}} - Perform the requested operation on file descriptor \var{fd} (file - objects providing a \method{fileno()} method are accepted as well). - The operation is defined by \var{op} and is operating system - dependent. These codes are also found in the \module{fcntl} - module. The argument \var{arg} is optional, and defaults to the - integer value \code{0}. When present, it can either be an integer - value, or a string. With the argument missing or an integer value, - the return value of this function is the integer return value of the - C \cfunction{fcntl()} call. When the argument is a string it - represents a binary structure, e.g.\ created by - \function{\refmodule{struct}.pack()}. The binary data is copied to a buffer - whose address is passed to the C \cfunction{fcntl()} call. The - return value after a successful call is the contents of the buffer, - converted to a string object. The length of the returned string - will be the same as the length of the \var{arg} argument. This is - limited to 1024 bytes. If the information returned in the buffer by - the operating system is larger than 1024 bytes, this is most likely - to result in a segmentation violation or a more subtle data - corruption. - - If the \cfunction{fcntl()} fails, an \exception{IOError} is - raised. -\end{funcdesc} - -\begin{funcdesc}{ioctl}{fd, op\optional{, arg\optional{, mutate_flag}}} - This function is identical to the \function{fcntl()} function, - except that the operations are typically defined in the library - module \refmodule{termios} and the argument handling is even more - complicated. - - The parameter \var{arg} can be one of an integer, absent (treated - identically to the integer \code{0}), an object supporting the - read-only buffer interface (most likely a plain Python string) or an - object supporting the read-write buffer interface. - - In all but the last case, behaviour is as for the \function{fcntl()} - function. - - If a mutable buffer is passed, then the behaviour is determined by - the value of the \var{mutate_flag} parameter. - - If it is false, the buffer's mutability is ignored and behaviour is - as for a read-only buffer, except that the 1024 byte limit mentioned - above is avoided -- so long as the buffer you pass is as least as - long as what the operating system wants to put there, things should - work. - - If \var{mutate_flag} is true, then the buffer is (in effect) passed - to the underlying \function{ioctl()} system call, the latter's - return code is passed back to the calling Python, and the buffer's - new contents reflect the action of the \function{ioctl()}. This is a - slight simplification, because if the supplied buffer is less than - 1024 bytes long it is first copied into a static buffer 1024 bytes - long which is then passed to \function{ioctl()} and copied back into - the supplied buffer. - - If \var{mutate_flag} is not supplied, then from Python 2.5 it - defaults to true, which is a change from versions 2.3 and 2.4. - Supply the argument explicitly if version portability is a priority. - - An example: - -\begin{verbatim} ->>> import array, fcntl, struct, termios, os ->>> os.getpgrp() -13341 ->>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0] -13341 ->>> buf = array.array('h', [0]) ->>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1) -0 ->>> buf -array('h', [13341]) -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{flock}{fd, op} -Perform the lock operation \var{op} on file descriptor \var{fd} (file - objects providing a \method{fileno()} method are accepted as well). -See the \UNIX{} manual \manpage{flock}{3} for details. (On some -systems, this function is emulated using \cfunction{fcntl()}.) -\end{funcdesc} - -\begin{funcdesc}{lockf}{fd, operation, - \optional{length, \optional{start, \optional{whence}}}} -This is essentially a wrapper around the \function{fcntl()} locking -calls. \var{fd} is the file descriptor of the file to lock or unlock, -and \var{operation} is one of the following values: - -\begin{itemize} -\item \constant{LOCK_UN} -- unlock -\item \constant{LOCK_SH} -- acquire a shared lock -\item \constant{LOCK_EX} -- acquire an exclusive lock -\end{itemize} - -When \var{operation} is \constant{LOCK_SH} or \constant{LOCK_EX}, it -can also be bit-wise OR'd with \constant{LOCK_NB} to avoid blocking on -lock acquisition. If \constant{LOCK_NB} is used and the lock cannot -be acquired, an \exception{IOError} will be raised and the exception -will have an \var{errno} attribute set to \constant{EACCES} or -\constant{EAGAIN} (depending on the operating system; for portability, -check for both values). On at least some systems, \constant{LOCK_EX} -can only be used if the file descriptor refers to a file opened for -writing. - -\var{length} is the number of bytes to lock, \var{start} is the byte -offset at which the lock starts, relative to \var{whence}, and -\var{whence} is as with \function{fileobj.seek()}, specifically: - -\begin{itemize} -\item \constant{0} -- relative to the start of the file - (\constant{SEEK_SET}) -\item \constant{1} -- relative to the current buffer position - (\constant{SEEK_CUR}) -\item \constant{2} -- relative to the end of the file - (\constant{SEEK_END}) -\end{itemize} - -The default for \var{start} is 0, which means to start at the -beginning of the file. The default for \var{length} is 0 which means -to lock to the end of the file. The default for \var{whence} is also -0. -\end{funcdesc} - -Examples (all on a SVR4 compliant system): - -\begin{verbatim} -import struct, fcntl, os - -f = open(...) -rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY) - -lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0) -rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata) -\end{verbatim} - -Note that in the first example the return value variable \var{rv} will -hold an integer value; in the second example it will hold a string -value. The structure lay-out for the \var{lockdata} variable is -system dependent --- therefore using the \function{flock()} call may be -better. - -\begin{seealso} - \seemodule{os}{If the locking flags \constant{O_SHLOCK} and - \constant{O_EXLOCK} are present in the \module{os} module, - the \function{os.open()} function provides a more - platform-independent alternative to the \function{lockf()} - and \function{flock()} functions.} -\end{seealso} diff --git a/Doc/lib/libfilecmp.tex b/Doc/lib/libfilecmp.tex deleted file mode 100644 index 42b4b8c..0000000 --- a/Doc/lib/libfilecmp.tex +++ /dev/null @@ -1,142 +0,0 @@ -\section{\module{filecmp} --- - File and Directory Comparisons} - -\declaremodule{standard}{filecmp} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Compare files efficiently.} - - -The \module{filecmp} module defines functions to compare files and -directories, with various optional time/correctness trade-offs. - -The \module{filecmp} module defines the following functions: - -\begin{funcdesc}{cmp}{f1, f2\optional{, shallow}} -Compare the files named \var{f1} and \var{f2}, returning \code{True} if -they seem equal, \code{False} otherwise. - -Unless \var{shallow} is given and is false, files with identical -\function{os.stat()} signatures are taken to be equal. - -Files that were compared using this function will not be compared again -unless their \function{os.stat()} signature changes. - -Note that no external programs are called from this function, giving it -portability and efficiency. -\end{funcdesc} - -\begin{funcdesc}{cmpfiles}{dir1, dir2, common\optional{, - shallow}} -Returns three lists of file names: \var{match}, \var{mismatch}, -\var{errors}. \var{match} contains the list of files match in both -directories, \var{mismatch} includes the names of those that don't, -and \var{errros} lists the names of files which could not be -compared. Files may be listed in \var{errors} because the user may -lack permission to read them or many other reasons, but always that -the comparison could not be done for some reason. - -The \var{common} parameter is a list of file names found in both directories. -The \var{shallow} parameter has the same -meaning and default value as for \function{filecmp.cmp()}. -\end{funcdesc} - -Example: - -\begin{verbatim} ->>> import filecmp ->>> filecmp.cmp('libundoc.tex', 'libundoc.tex') -True ->>> filecmp.cmp('libundoc.tex', 'lib.tex') -False -\end{verbatim} - - -\subsection{The \protect\class{dircmp} class \label{dircmp-objects}} - -\class{dircmp} instances are built using this constructor: - -\begin{classdesc}{dircmp}{a, b\optional{, ignore\optional{, hide}}} -Construct a new directory comparison object, to compare the -directories \var{a} and \var{b}. \var{ignore} is a list of names to -ignore, and defaults to \code{['RCS', 'CVS', 'tags']}. \var{hide} is a -list of names to hide, and defaults to \code{[os.curdir, os.pardir]}. -\end{classdesc} - -The \class{dircmp} class provides the following methods: - -\begin{methoddesc}[dircmp]{report}{} -Print (to \code{sys.stdout}) a comparison between \var{a} and \var{b}. -\end{methoddesc} - -\begin{methoddesc}[dircmp]{report_partial_closure}{} -Print a comparison between \var{a} and \var{b} and common immediate -subdirectories. -\end{methoddesc} - -\begin{methoddesc}[dircmp]{report_full_closure}{} -Print a comparison between \var{a} and \var{b} and common -subdirectories (recursively). -\end{methoddesc} - - -The \class{dircmp} offers a number of interesting attributes that may -be used to get various bits of information about the directory trees -being compared. - -Note that via \method{__getattr__()} hooks, all attributes are -computed lazily, so there is no speed penalty if only those -attributes which are lightweight to compute are used. - -\begin{memberdesc}[dircmp]{left_list} -Files and subdirectories in \var{a}, filtered by \var{hide} and -\var{ignore}. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{right_list} -Files and subdirectories in \var{b}, filtered by \var{hide} and -\var{ignore}. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{common} -Files and subdirectories in both \var{a} and \var{b}. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{left_only} -Files and subdirectories only in \var{a}. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{right_only} -Files and subdirectories only in \var{b}. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{common_dirs} -Subdirectories in both \var{a} and \var{b}. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{common_files} -Files in both \var{a} and \var{b} -\end{memberdesc} - -\begin{memberdesc}[dircmp]{common_funny} -Names in both \var{a} and \var{b}, such that the type differs between -the directories, or names for which \function{os.stat()} reports an -error. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{same_files} -Files which are identical in both \var{a} and \var{b}. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{diff_files} -Files which are in both \var{a} and \var{b}, whose contents differ. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{funny_files} -Files which are in both \var{a} and \var{b}, but could not be -compared. -\end{memberdesc} - -\begin{memberdesc}[dircmp]{subdirs} -A dictionary mapping names in \member{common_dirs} to -\class{dircmp} objects. -\end{memberdesc} diff --git a/Doc/lib/libfileinput.tex b/Doc/lib/libfileinput.tex deleted file mode 100644 index 3cfb7bc..0000000 --- a/Doc/lib/libfileinput.tex +++ /dev/null @@ -1,192 +0,0 @@ -\section{\module{fileinput} --- - Iterate over lines from multiple input streams} -\declaremodule{standard}{fileinput} -\moduleauthor{Guido van Rossum}{guido@python.org} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -\modulesynopsis{Perl-like iteration over lines from multiple input -streams, with ``save in place'' capability.} - - -This module implements a helper class and functions to quickly write a -loop over standard input or a list of files. - -The typical use is: - -\begin{verbatim} -import fileinput -for line in fileinput.input(): - process(line) -\end{verbatim} - -This iterates over the lines of all files listed in -\code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is -empty. If a filename is \code{'-'}, it is also replaced by -\code{sys.stdin}. To specify an alternative list of filenames, pass -it as the first argument to \function{input()}. A single file name is -also allowed. - -All files are opened in text mode by default, but you can override this by -specifying the \var{mode} parameter in the call to \function{input()} -or \class{FileInput()}. If an I/O error occurs during opening or reading -a file, \exception{IOError} is raised. - -If \code{sys.stdin} is used more than once, the second and further use -will return no lines, except perhaps for interactive use, or if it has -been explicitly reset (e.g. using \code{sys.stdin.seek(0)}). - -Empty files are opened and immediately closed; the only time their -presence in the list of filenames is noticeable at all is when the -last file opened is empty. - -It is possible that the last line of a file does not end in a newline -character; lines are returned including the trailing newline when it -is present. - -You can control how files are opened by providing an opening hook via the -\var{openhook} parameter to \function{input()} or \class{FileInput()}. -The hook must be a function that takes two arguments, \var{filename} -and \var{mode}, and returns an accordingly opened file-like object. -Two useful hooks are already provided by this module. - -The following function is the primary interface of this module: - -\begin{funcdesc}{input}{\optional{files\optional{, inplace\optional{, - backup\optional{, mode\optional{, openhook}}}}}} - Create an instance of the \class{FileInput} class. The instance - will be used as global state for the functions of this module, and - is also returned to use during iteration. The parameters to this - function will be passed along to the constructor of the - \class{FileInput} class. - - \versionchanged[Added the \var{mode} and \var{openhook} parameters]{2.5} -\end{funcdesc} - - -The following functions use the global state created by -\function{input()}; if there is no active state, -\exception{RuntimeError} is raised. - -\begin{funcdesc}{filename}{} - Return the name of the file currently being read. Before the first - line has been read, returns \code{None}. -\end{funcdesc} - -\begin{funcdesc}{fileno}{} - Return the integer ``file descriptor'' for the current file. When no - file is opened (before the first line and between files), returns - \code{-1}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{lineno}{} - Return the cumulative line number of the line that has just been - read. Before the first line has been read, returns \code{0}. After - the last line of the last file has been read, returns the line - number of that line. -\end{funcdesc} - -\begin{funcdesc}{filelineno}{} - Return the line number in the current file. Before the first line - has been read, returns \code{0}. After the last line of the last - file has been read, returns the line number of that line within the - file. -\end{funcdesc} - -\begin{funcdesc}{isfirstline}{} - Returns true if the line just read is the first line of its file, - otherwise returns false. -\end{funcdesc} - -\begin{funcdesc}{isstdin}{} - Returns true if the last line was read from \code{sys.stdin}, - otherwise returns false. -\end{funcdesc} - -\begin{funcdesc}{nextfile}{} - Close the current file so that the next iteration will read the - first line from the next file (if any); lines not read from the file - will not count towards the cumulative line count. The filename is - not changed until after the first line of the next file has been - read. Before the first line has been read, this function has no - effect; it cannot be used to skip the first file. After the last - line of the last file has been read, this function has no effect. -\end{funcdesc} - -\begin{funcdesc}{close}{} - Close the sequence. -\end{funcdesc} - - -The class which implements the sequence behavior provided by the -module is available for subclassing as well: - -\begin{classdesc}{FileInput}{\optional{files\optional{, - inplace\optional{, backup\optional{, - mode\optional{, openhook}}}}}} - Class \class{FileInput} is the implementation; its methods - \method{filename()}, \method{fileno()}, \method{lineno()}, - \method{fileline()}, \method{isfirstline()}, \method{isstdin()}, - \method{nextfile()} and \method{close()} correspond to the functions - of the same name in the module. - In addition it has a \method{readline()} method which - returns the next input line, and a \method{__getitem__()} method - which implements the sequence behavior. The sequence must be - accessed in strictly sequential order; random access and - \method{readline()} cannot be mixed. - - With \var{mode} you can specify which file mode will be passed to - \function{open()}. It must be one of \code{'r'}, \code{'rU'}, - \code{'U'} and \code{'rb'}. - - The \var{openhook}, when given, must be a function that takes two arguments, - \var{filename} and \var{mode}, and returns an accordingly opened - file-like object. - You cannot use \var{inplace} and \var{openhook} together. - - \versionchanged[Added the \var{mode} and \var{openhook} parameters]{2.5} -\end{classdesc} - -\strong{Optional in-place filtering:} if the keyword argument -\code{\var{inplace}=1} is passed to \function{input()} or to the -\class{FileInput} constructor, the file is moved to a backup file and -standard output is directed to the input file (if a file of the same -name as the backup file already exists, it will be replaced silently). -This makes it possible to write a filter that rewrites its input file -in place. If the keyword argument \code{\var{backup}='.<some -extension>'} is also given, it specifies the extension for the backup -file, and the backup file remains around; by default, the extension is -\code{'.bak'} and it is deleted when the output file is closed. In-place -filtering is disabled when standard input is read. - -\strong{Caveat:} The current implementation does not work for MS-DOS -8+3 filesystems. - - -The two following opening hooks are provided by this module: - -\begin{funcdesc}{hook_compressed}{filename, mode} - Transparently opens files compressed with gzip and bzip2 (recognized - by the extensions \code{'.gz'} and \code{'.bz2'}) using the \module{gzip} - and \module{bz2} modules. If the filename extension is not \code{'.gz'} - or \code{'.bz2'}, the file is opened normally (ie, - using \function{open()} without any decompression). - - Usage example: - \samp{fi = fileinput.FileInput(openhook=fileinput.hook_compressed)} - - \versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{hook_encoded}{encoding} - Returns a hook which opens each file with \function{codecs.open()}, - using the given \var{encoding} to read the file. - - Usage example: - \samp{fi = fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))} - - \note{With this hook, \class{FileInput} might return Unicode strings - depending on the specified \var{encoding}.} - \versionadded{2.5} -\end{funcdesc} - diff --git a/Doc/lib/libfnmatch.tex b/Doc/lib/libfnmatch.tex deleted file mode 100644 index 1ac46bd..0000000 --- a/Doc/lib/libfnmatch.tex +++ /dev/null @@ -1,86 +0,0 @@ -\section{\module{fnmatch} --- - \UNIX{} filename pattern matching} - -\declaremodule{standard}{fnmatch} -\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: - -\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 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 comparison is performed. If you -require a case-sensitive comparison regardless of whether that's -standard for your operating system, use \function{fnmatchcase()} -instead. - -This example will print all file names in the current directory with the -extension \code{.txt}: - -\begin{verbatim} -import fnmatch -import os - -for file in os.listdir('.'): - if fnmatch.fnmatch(file, '*.txt'): - print file -\end{verbatim} - -\end{funcdesc} - -\begin{funcdesc}{fnmatchcase}{filename, pattern} -Test whether \var{filename} matches \var{pattern}, returning true or -false; the comparison is case-sensitive. -\end{funcdesc} - -\begin{funcdesc}{filter}{names, pattern} -Return the subset of the list of \var{names} that match \var{pattern}. -It is the same as \code{[n for n in names if fnmatch(n, pattern)]}, but -implemented more efficiently. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{translate}{pattern} -Return the shell-style \var{pattern} converted to a regular -expression. - -Example: - -\begin{verbatim} ->>> import fnmatch, re ->>> ->>> regex = fnmatch.translate('*.txt') ->>> regex -'.*\\.txt$' ->>> reobj = re.compile(regex) ->>> print reobj.match('foobar.txt') -<_sre.SRE_Match object at 0x...> -\end{verbatim} -\end{funcdesc} - -\begin{seealso} - \seemodule{glob}{\UNIX{} shell-style path expansion.} -\end{seealso} diff --git a/Doc/lib/libformatter.tex b/Doc/lib/libformatter.tex deleted file mode 100644 index d7c5a6b..0000000 --- a/Doc/lib/libformatter.tex +++ /dev/null @@ -1,329 +0,0 @@ -\section{\module{formatter} --- - Generic output formatting} - -\declaremodule{standard}{formatter} -\modulesynopsis{Generic output formatter and device interface.} - - - -This module supports two interface definitions, each with multiple -implementations. The \emph{formatter} interface is used by the -\class{HTMLParser} class of the \refmodule{htmllib} module, and the -\emph{writer} interface is required by the formatter interface. -\withsubitem{(class in htmllib)}{\ttindex{HTMLParser}} - -Formatter objects transform an abstract flow of formatting events into -specific output events on writer objects. Formatters manage several -stack structures to allow various properties of a writer object to be -changed and restored; writers need not be able to handle relative -changes nor any sort of ``change back'' operation. Specific writer -properties which may be controlled via formatter objects are -horizontal alignment, font, and left margin indentations. A mechanism -is provided which supports providing arbitrary, non-exclusive style -settings to a writer as well. Additional interfaces facilitate -formatting events which are not reversible, such as paragraph -separation. - -Writer objects encapsulate device interfaces. Abstract devices, such -as file formats, are supported as well as physical devices. The -provided implementations all work with abstract devices. The -interface makes available mechanisms for setting the properties which -formatter objects manage and inserting data into the output. - - -\subsection{The Formatter Interface \label{formatter-interface}} - -Interfaces to create formatters are dependent on the specific -formatter class being instantiated. The interfaces described below -are the required interfaces which all formatters must support once -initialized. - -One data element is defined at the module level: - - -\begin{datadesc}{AS_IS} -Value which can be used in the font specification passed to the -\code{push_font()} method described below, or as the new value to any -other \code{push_\var{property}()} method. Pushing the \code{AS_IS} -value allows the corresponding \code{pop_\var{property}()} method to -be called without having to track whether the property was changed. -\end{datadesc} - -The following attributes are defined for formatter instance objects: - - -\begin{memberdesc}[formatter]{writer} -The writer instance with which the formatter interacts. -\end{memberdesc} - - -\begin{methoddesc}[formatter]{end_paragraph}{blanklines} -Close any open paragraphs and insert at least \var{blanklines} -before the next paragraph. -\end{methoddesc} - -\begin{methoddesc}[formatter]{add_line_break}{} -Add a hard line break if one does not already exist. This does not -break the logical paragraph. -\end{methoddesc} - -\begin{methoddesc}[formatter]{add_hor_rule}{*args, **kw} -Insert a horizontal rule in the output. A hard break is inserted if -there is data in the current paragraph, but the logical paragraph is -not broken. The arguments and keywords are passed on to the writer's -\method{send_line_break()} method. -\end{methoddesc} - -\begin{methoddesc}[formatter]{add_flowing_data}{data} -Provide data which should be formatted with collapsed whitespace. -Whitespace from preceding and successive calls to -\method{add_flowing_data()} is considered as well when the whitespace -collapse is performed. The data which is passed to this method is -expected to be word-wrapped by the output device. Note that any -word-wrapping still must be performed by the writer object due to the -need to rely on device and font information. -\end{methoddesc} - -\begin{methoddesc}[formatter]{add_literal_data}{data} -Provide data which should be passed to the writer unchanged. -Whitespace, including newline and tab characters, are considered legal -in the value of \var{data}. -\end{methoddesc} - -\begin{methoddesc}[formatter]{add_label_data}{format, counter} -Insert a label which should be placed to the left of the current left -margin. This should be used for constructing bulleted or numbered -lists. If the \var{format} value is a string, it is interpreted as a -format specification for \var{counter}, which should be an integer. -The result of this formatting becomes the value of the label; if -\var{format} is not a string it is used as the label value directly. -The label value is passed as the only argument to the writer's -\method{send_label_data()} method. Interpretation of non-string label -values is dependent on the associated writer. - -Format specifications are strings which, in combination with a counter -value, are used to compute label values. Each character in the format -string is copied to the label value, with some characters recognized -to indicate a transform on the counter value. Specifically, the -character \character{1} represents the counter value formatter as an -Arabic number, the characters \character{A} and \character{a} -represent alphabetic representations of the counter value in upper and -lower case, respectively, and \character{I} and \character{i} -represent the counter value in Roman numerals, in upper and lower -case. Note that the alphabetic and roman transforms require that the -counter value be greater than zero. -\end{methoddesc} - -\begin{methoddesc}[formatter]{flush_softspace}{} -Send any pending whitespace buffered from a previous call to -\method{add_flowing_data()} to the associated writer object. This -should be called before any direct manipulation of the writer object. -\end{methoddesc} - -\begin{methoddesc}[formatter]{push_alignment}{align} -Push a new alignment setting onto the alignment stack. This may be -\constant{AS_IS} if no change is desired. If the alignment value is -changed from the previous setting, the writer's \method{new_alignment()} -method is called with the \var{align} value. -\end{methoddesc} - -\begin{methoddesc}[formatter]{pop_alignment}{} -Restore the previous alignment. -\end{methoddesc} - -\begin{methoddesc}[formatter]{push_font}{\code{(}size, italic, bold, teletype\code{)}} -Change some or all font properties of the writer object. Properties -which are not set to \constant{AS_IS} are set to the values passed in -while others are maintained at their current settings. The writer's -\method{new_font()} method is called with the fully resolved font -specification. -\end{methoddesc} - -\begin{methoddesc}[formatter]{pop_font}{} -Restore the previous font. -\end{methoddesc} - -\begin{methoddesc}[formatter]{push_margin}{margin} -Increase the number of left margin indentations by one, associating -the logical tag \var{margin} with the new indentation. The initial -margin level is \code{0}. Changed values of the logical tag must be -true values; false values other than \constant{AS_IS} are not -sufficient to change the margin. -\end{methoddesc} - -\begin{methoddesc}[formatter]{pop_margin}{} -Restore the previous margin. -\end{methoddesc} - -\begin{methoddesc}[formatter]{push_style}{*styles} -Push any number of arbitrary style specifications. All styles are -pushed onto the styles stack in order. A tuple representing the -entire stack, including \constant{AS_IS} values, is passed to the -writer's \method{new_styles()} method. -\end{methoddesc} - -\begin{methoddesc}[formatter]{pop_style}{\optional{n\code{ = 1}}} -Pop the last \var{n} style specifications passed to -\method{push_style()}. A tuple representing the revised stack, -including \constant{AS_IS} values, is passed to the writer's -\method{new_styles()} method. -\end{methoddesc} - -\begin{methoddesc}[formatter]{set_spacing}{spacing} -Set the spacing style for the writer. -\end{methoddesc} - -\begin{methoddesc}[formatter]{assert_line_data}{\optional{flag\code{ = 1}}} -Inform the formatter that data has been added to the current paragraph -out-of-band. This should be used when the writer has been manipulated -directly. The optional \var{flag} argument can be set to false if -the writer manipulations produced a hard line break at the end of the -output. -\end{methoddesc} - - -\subsection{Formatter Implementations \label{formatter-impls}} - -Two implementations of formatter objects are provided by this module. -Most applications may use one of these classes without modification or -subclassing. - -\begin{classdesc}{NullFormatter}{\optional{writer}} -A formatter which does nothing. If \var{writer} is omitted, a -\class{NullWriter} instance is created. No methods of the writer are -called by \class{NullFormatter} instances. Implementations should -inherit from this class if implementing a writer interface but don't -need to inherit any implementation. -\end{classdesc} - -\begin{classdesc}{AbstractFormatter}{writer} -The standard formatter. This implementation has demonstrated wide -applicability to many writers, and may be used directly in most -circumstances. It has been used to implement a full-featured -World Wide Web browser. -\end{classdesc} - - - -\subsection{The Writer Interface \label{writer-interface}} - -Interfaces to create writers are dependent on the specific writer -class being instantiated. The interfaces described below are the -required interfaces which all writers must support once initialized. -Note that while most applications can use the -\class{AbstractFormatter} class as a formatter, the writer must -typically be provided by the application. - - -\begin{methoddesc}[writer]{flush}{} -Flush any buffered output or device control events. -\end{methoddesc} - -\begin{methoddesc}[writer]{new_alignment}{align} -Set the alignment style. The \var{align} value can be any object, -but by convention is a string or \code{None}, where \code{None} -indicates that the writer's ``preferred'' alignment should be used. -Conventional \var{align} values are \code{'left'}, \code{'center'}, -\code{'right'}, and \code{'justify'}. -\end{methoddesc} - -\begin{methoddesc}[writer]{new_font}{font} -Set the font style. The value of \var{font} will be \code{None}, -indicating that the device's default font should be used, or a tuple -of the form \code{(}\var{size}, \var{italic}, \var{bold}, -\var{teletype}\code{)}. Size will be a string indicating the size of -font that should be used; specific strings and their interpretation -must be defined by the application. The \var{italic}, \var{bold}, and -\var{teletype} values are Boolean values specifying which of those -font attributes should be used. -\end{methoddesc} - -\begin{methoddesc}[writer]{new_margin}{margin, level} -Set the margin level to the integer \var{level} and the logical tag -to \var{margin}. Interpretation of the logical tag is at the -writer's discretion; the only restriction on the value of the logical -tag is that it not be a false value for non-zero values of -\var{level}. -\end{methoddesc} - -\begin{methoddesc}[writer]{new_spacing}{spacing} -Set the spacing style to \var{spacing}. -\end{methoddesc} - -\begin{methoddesc}[writer]{new_styles}{styles} -Set additional styles. The \var{styles} value is a tuple of -arbitrary values; the value \constant{AS_IS} should be ignored. The -\var{styles} tuple may be interpreted either as a set or as a stack -depending on the requirements of the application and writer -implementation. -\end{methoddesc} - -\begin{methoddesc}[writer]{send_line_break}{} -Break the current line. -\end{methoddesc} - -\begin{methoddesc}[writer]{send_paragraph}{blankline} -Produce a paragraph separation of at least \var{blankline} blank -lines, or the equivalent. The \var{blankline} value will be an -integer. Note that the implementation will receive a call to -\method{send_line_break()} before this call if a line break is needed; -this method should not include ending the last line of the paragraph. -It is only responsible for vertical spacing between paragraphs. -\end{methoddesc} - -\begin{methoddesc}[writer]{send_hor_rule}{*args, **kw} -Display a horizontal rule on the output device. The arguments to this -method are entirely application- and writer-specific, and should be -interpreted with care. The method implementation may assume that a -line break has already been issued via \method{send_line_break()}. -\end{methoddesc} - -\begin{methoddesc}[writer]{send_flowing_data}{data} -Output character data which may be word-wrapped and re-flowed as -needed. Within any sequence of calls to this method, the writer may -assume that spans of multiple whitespace characters have been -collapsed to single space characters. -\end{methoddesc} - -\begin{methoddesc}[writer]{send_literal_data}{data} -Output character data which has already been formatted -for display. Generally, this should be interpreted to mean that line -breaks indicated by newline characters should be preserved and no new -line breaks should be introduced. The data may contain embedded -newline and tab characters, unlike data provided to the -\method{send_formatted_data()} interface. -\end{methoddesc} - -\begin{methoddesc}[writer]{send_label_data}{data} -Set \var{data} to the left of the current left margin, if possible. -The value of \var{data} is not restricted; treatment of non-string -values is entirely application- and writer-dependent. This method -will only be called at the beginning of a line. -\end{methoddesc} - - -\subsection{Writer Implementations \label{writer-impls}} - -Three implementations of the writer object interface are provided as -examples by this module. Most applications will need to derive new -writer classes from the \class{NullWriter} class. - -\begin{classdesc}{NullWriter}{} -A writer which only provides the interface definition; no actions are -taken on any methods. This should be the base class for all writers -which do not need to inherit any implementation methods. -\end{classdesc} - -\begin{classdesc}{AbstractWriter}{} -A writer which can be used in debugging formatters, but not much -else. Each method simply announces itself by printing its name and -arguments on standard output. -\end{classdesc} - -\begin{classdesc}{DumbWriter}{\optional{file\optional{, maxcol\code{ = 72}}}} -Simple writer class which writes output on the file object passed in -as \var{file} or, if \var{file} is omitted, on standard output. The -output is simply word-wrapped to the number of columns specified by -\var{maxcol}. This class is suitable for reflowing a sequence of -paragraphs. -\end{classdesc} diff --git a/Doc/lib/libfpectl.tex b/Doc/lib/libfpectl.tex deleted file mode 100644 index cca2314..0000000 --- a/Doc/lib/libfpectl.tex +++ /dev/null @@ -1,127 +0,0 @@ -\section{\module{fpectl} --- - Floating point exception control} - -\declaremodule{extension}{fpectl} - \platform{Unix} -\moduleauthor{Lee Busby}{busby1@llnl.gov} -\sectionauthor{Lee Busby}{busby1@llnl.gov} -\modulesynopsis{Provide control for floating point exception handling.} - -\note{The \module{fpectl} module is not built by default, and its usage - is discouraged and may be dangerous except in the hands of - experts. See also the section \ref{fpectl-limitations} on - limitations for more details.} - -Most computers carry out floating point operations\index{IEEE-754} -in conformance with the so-called IEEE-754 standard. -On any real computer, -some floating point operations produce results that cannot -be expressed as a normal floating point value. -For example, try - -\begin{verbatim} ->>> import math ->>> math.exp(1000) -inf ->>> math.exp(1000) / math.exp(1000) -nan -\end{verbatim} - -(The example above will work on many platforms. -DEC Alpha may be one exception.) -"Inf" is a special, non-numeric value in IEEE-754 that -stands for "infinity", and "nan" means "not a number." -Note that, -other than the non-numeric results, -nothing special happened when you asked Python -to carry out those calculations. -That is in fact the default behaviour prescribed in the IEEE-754 standard, -and if it works for you, -stop reading now. - -In some circumstances, -it would be better to raise an exception and stop processing -at the point where the faulty operation was attempted. -The \module{fpectl} module -is for use in that situation. -It provides control over floating point -units from several hardware manufacturers, -allowing the user to turn on the generation -of \constant{SIGFPE} whenever any of the -IEEE-754 exceptions Division by Zero, Overflow, or -Invalid Operation occurs. -In tandem with a pair of wrapper macros that are inserted -into the C code comprising your python system, -\constant{SIGFPE} is trapped and converted into the Python -\exception{FloatingPointError} exception. - -The \module{fpectl} module defines the following functions and -may raise the given exception: - -\begin{funcdesc}{turnon_sigfpe}{} -Turn on the generation of \constant{SIGFPE}, -and set up an appropriate signal handler. -\end{funcdesc} - -\begin{funcdesc}{turnoff_sigfpe}{} -Reset default handling of floating point exceptions. -\end{funcdesc} - -\begin{excdesc}{FloatingPointError} -After \function{turnon_sigfpe()} has been executed, -a floating point operation that raises one of the -IEEE-754 exceptions -Division by Zero, Overflow, or Invalid operation -will in turn raise this standard Python exception. -\end{excdesc} - - -\subsection{Example \label{fpectl-example}} - -The following example demonstrates how to start up and test operation of -the \module{fpectl} module. - -\begin{verbatim} ->>> import fpectl ->>> import fpetest ->>> fpectl.turnon_sigfpe() ->>> fpetest.test() -overflow PASS -FloatingPointError: Overflow - -div by 0 PASS -FloatingPointError: Division by zero - [ more output from test elided ] ->>> import math ->>> math.exp(1000) -Traceback (most recent call last): - File "<stdin>", line 1, in ? -FloatingPointError: in math_1 -\end{verbatim} - - -\subsection{Limitations and other considerations \label{fpectl-limitations}} - -Setting up a given processor to trap IEEE-754 floating point -errors currently requires custom code on a per-architecture basis. -You may have to modify \module{fpectl} to control your particular hardware. - -Conversion of an IEEE-754 exception to a Python exception requires -that the wrapper macros \code{PyFPE_START_PROTECT} and -\code{PyFPE_END_PROTECT} be inserted into your code in an appropriate -fashion. Python itself has been modified to support the -\module{fpectl} module, but many other codes of interest to numerical -analysts have not. - -The \module{fpectl} module is not thread-safe. - -\begin{seealso} - \seetext{Some files in the source distribution may be interesting in - learning more about how this module operates. - The include file \file{Include/pyfpe.h} discusses the - implementation of this module at some length. - \file{Modules/fpetestmodule.c} gives several examples of - use. - Many additional examples can be found in - \file{Objects/floatobject.c}.} -\end{seealso} diff --git a/Doc/lib/libfpformat.tex b/Doc/lib/libfpformat.tex deleted file mode 100644 index a3a6282..0000000 --- a/Doc/lib/libfpformat.tex +++ /dev/null @@ -1,54 +0,0 @@ -\section{\module{fpformat} --- - Floating point conversions} - -\declaremodule{standard}{fpformat} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{General floating point formatting functions.} - - -The \module{fpformat} module defines functions for dealing with -floating point numbers representations in 100\% pure -Python. \note{This module is unneeded: everything here could -be done via the \code{\%} string interpolation operator.} - -The \module{fpformat} module defines the following functions and an -exception: - - -\begin{funcdesc}{fix}{x, digs} -Format \var{x} as \code{[-]ddd.ddd} with \var{digs} digits after the -point and at least one digit before. -If \code{\var{digs} <= 0}, the decimal point is suppressed. - -\var{x} can be either a number or a string that looks like -one. \var{digs} is an integer. - -Return value is a string. -\end{funcdesc} - -\begin{funcdesc}{sci}{x, digs} -Format \var{x} as \code{[-]d.dddE[+-]ddd} with \var{digs} digits after the -point and exactly one digit before. -If \code{\var{digs} <= 0}, one digit is kept and the point is suppressed. - -\var{x} can be either a real number, or a string that looks like -one. \var{digs} is an integer. - -Return value is a string. -\end{funcdesc} - -\begin{excdesc}{NotANumber} -Exception raised when a string passed to \function{fix()} or -\function{sci()} as the \var{x} parameter does not look like a number. -This is a subclass of \exception{ValueError} when the standard -exceptions are strings. The exception value is the improperly -formatted string that caused the exception to be raised. -\end{excdesc} - -Example: - -\begin{verbatim} ->>> import fpformat ->>> fpformat.fix(1.23, 1) -'1.2' -\end{verbatim} diff --git a/Doc/lib/libftplib.tex b/Doc/lib/libftplib.tex deleted file mode 100644 index 1ce5f9b..0000000 --- a/Doc/lib/libftplib.tex +++ /dev/null @@ -1,300 +0,0 @@ -\section{\module{ftplib} --- - FTP protocol client} - -\declaremodule{standard}{ftplib} -\modulesynopsis{FTP protocol client (requires sockets).} - -\indexii{FTP}{protocol} -\index{FTP!\module{ftplib} (standard module)} - -This module defines the class \class{FTP} and a few related items. -The \class{FTP} class implements the client side of the FTP -protocol. You can use this to write Python -programs that perform a variety of automated FTP jobs, such as -mirroring other ftp servers. It is also used by the module -\refmodule{urllib} to handle URLs that use FTP. For more information -on FTP (File Transfer Protocol), see Internet \rfc{959}. - -Here's a sample session using the \module{ftplib} module: - -\begin{verbatim} ->>> from ftplib import FTP ->>> ftp = FTP('ftp.cwi.nl') # connect to host, default port ->>> ftp.login() # user anonymous, passwd anonymous@ ->>> ftp.retrlines('LIST') # list directory contents -total 24418 -drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 . -dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. --rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX - . - . - . ->>> ftp.retrbinary('RETR README', open('README', 'wb').write) -'226 Transfer complete.' ->>> ftp.quit() -\end{verbatim} - -The module defines the following items: - -\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, - passwd\optional{, acct\optional{, timeout}}}}}} -Return a new instance of the \class{FTP} class. When -\var{host} is given, the method call \code{connect(\var{host})} is -made. When \var{user} is given, additionally the method call -\code{login(\var{user}, \var{passwd}, \var{acct})} is made (where -\var{passwd} and \var{acct} default to the empty string when not given). -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if is not specified, or passed as None, the global -default timeout setting will be used). -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - -\begin{datadesc}{all_errors} -The set of all exceptions (as a tuple) that methods of \class{FTP} -instances may raise as a result of problems with the FTP connection -(as opposed to programming errors made by the caller). This set -includes the four exceptions listed below as well as -\exception{socket.error} and \exception{IOError}. -\end{datadesc} - -\begin{excdesc}{error_reply} -Exception raised when an unexpected reply is received from the server. -\end{excdesc} - -\begin{excdesc}{error_temp} -Exception raised when an error code in the range 400--499 is received. -\end{excdesc} - -\begin{excdesc}{error_perm} -Exception raised when an error code in the range 500--599 is received. -\end{excdesc} - -\begin{excdesc}{error_proto} -Exception raised when a reply is received from the server that does -not begin with a digit in the range 1--5. -\end{excdesc} - - -\begin{seealso} - \seemodule{netrc}{Parser for the \file{.netrc} file format. The file - \file{.netrc} is typically used by FTP clients to - load user authentication information before prompting - the user.} - \seetext{The file \file{Tools/scripts/ftpmirror.py}\index{ftpmirror.py} - in the Python source distribution is a script that can mirror - FTP sites, or portions thereof, using the \module{ftplib} module. - It can be used as an extended example that applies this module.} -\end{seealso} - - -\subsection{FTP Objects \label{ftp-objects}} - -Several methods are available in two flavors: one for handling text -files and another for binary files. These are named for the command -which is used followed by \samp{lines} for the text version or -\samp{binary} for the binary version. - -\class{FTP} instances have the following methods: - -\begin{methoddesc}[FTP]{set_debuglevel}{level} -Set the instance's debugging level. This controls the amount of -debugging output printed. The default, \code{0}, produces no -debugging output. A value of \code{1} produces a moderate amount of -debugging output, generally a single line per request. A value of -\code{2} or higher produces the maximum amount of debugging output, -logging each line sent and received on the control connection. -\end{methoddesc} - -\begin{methoddesc}[FTP]{connect}{host\optional{, port\optional{, timeout}}} -Connect to the given host and port. The default port number is \code{21}, as -specified by the FTP protocol specification. It is rarely needed to -specify a different port number. This function should be called only -once for each instance; it should not be called at all if a host was -given when the instance was created. All other methods can only be -used after a connection has been made. - -The optional \var{timeout} parameter specifies a timeout in seconds for -the connection attempt. If is not specified, or passed as None, the -object timeout is used (the timeout that you passed when instantiating the -class); if the object timeout is also None, the global default timeout -setting will be used. - -\versionchanged[\var{timeout} was added]{2.6} -\end{methoddesc} - -\begin{methoddesc}[FTP]{getwelcome}{} -Return the welcome message sent by the server in reply to the initial -connection. (This message sometimes contains disclaimers or help -information that may be relevant to the user.) -\end{methoddesc} - -\begin{methoddesc}[FTP]{login}{\optional{user\optional{, passwd\optional{, acct}}}} -Log in as the given \var{user}. The \var{passwd} and \var{acct} -parameters are optional and default to the empty string. If no -\var{user} is specified, it defaults to \code{'anonymous'}. If -\var{user} is \code{'anonymous'}, the default \var{passwd} is -\code{'anonymous@'}. This function should be called only -once for each instance, after a connection has been established; it -should not be called at all if a host and user were given when the -instance was created. Most FTP commands are only allowed after the -client has logged in. -\end{methoddesc} - -\begin{methoddesc}[FTP]{abort}{} -Abort a file transfer that is in progress. Using this does not always -work, but it's worth a try. -\end{methoddesc} - -\begin{methoddesc}[FTP]{sendcmd}{command} -Send a simple command string to the server and return the response -string. -\end{methoddesc} - -\begin{methoddesc}[FTP]{voidcmd}{command} -Send a simple command string to the server and handle the response. -Return nothing if a response code in the range 200--299 is received. -Raise an exception otherwise. -\end{methoddesc} - -\begin{methoddesc}[FTP]{retrbinary}{command, - callback\optional{, maxblocksize\optional{, rest}}} -Retrieve a file in binary transfer mode. \var{command} should be an -appropriate \samp{RETR} command: \code{'RETR \var{filename}'}. -The \var{callback} function is called for each block of data received, -with a single string argument giving the data block. -The optional \var{maxblocksize} argument specifies the maximum chunk size to -read on the low-level socket object created to do the actual transfer -(which will also be the largest size of the data blocks passed to -\var{callback}). A reasonable default is chosen. \var{rest} means the -same thing as in the \method{transfercmd()} method. -\end{methoddesc} - -\begin{methoddesc}[FTP]{retrlines}{command\optional{, callback}} -Retrieve a file or directory listing in \ASCII{} transfer mode. -\var{command} should be an appropriate \samp{RETR} command (see -\method{retrbinary()}) or a \samp{LIST} command (usually just the string -\code{'LIST'}). The \var{callback} function is called for each line, -with the trailing CRLF stripped. The default \var{callback} prints -the line to \code{sys.stdout}. -\end{methoddesc} - -\begin{methoddesc}[FTP]{set_pasv}{boolean} -Enable ``passive'' mode if \var{boolean} is true, other disable -passive mode. (In Python 2.0 and before, passive mode was off by -default; in Python 2.1 and later, it is on by default.) -\end{methoddesc} - -\begin{methoddesc}[FTP]{storbinary}{command, file\optional{, blocksize}} -Store a file in binary transfer mode. \var{command} should be an -appropriate \samp{STOR} command: \code{"STOR \var{filename}"}. -\var{file} is an open file object which is read until \EOF{} using its -\method{read()} method in blocks of size \var{blocksize} to provide the -data to be stored. The \var{blocksize} argument defaults to 8192. -\versionchanged[default for \var{blocksize} added]{2.1} -\end{methoddesc} - -\begin{methoddesc}[FTP]{storlines}{command, file} -Store a file in \ASCII{} transfer mode. \var{command} should be an -appropriate \samp{STOR} command (see \method{storbinary()}). Lines are -read until \EOF{} from the open file object \var{file} using its -\method{readline()} method to provide the data to be stored. -\end{methoddesc} - -\begin{methoddesc}[FTP]{transfercmd}{cmd\optional{, rest}} -Initiate a transfer over the data connection. If the transfer is -active, send a \samp{EPRT} or \samp{PORT} command and the transfer command specified -by \var{cmd}, and accept the connection. If the server is passive, -send a \samp{EPSV} or \samp{PASV} command, connect to it, and start the transfer -command. Either way, return the socket for the connection. - -If optional \var{rest} is given, a \samp{REST} command is -sent to the server, passing \var{rest} as an argument. \var{rest} is -usually a byte offset into the requested file, telling the server to -restart sending the file's bytes at the requested offset, skipping -over the initial bytes. Note however that RFC -959 requires only that \var{rest} be a string containing characters -in the printable range from ASCII code 33 to ASCII code 126. The -\method{transfercmd()} method, therefore, converts -\var{rest} to a string, but no check is -performed on the string's contents. If the server does -not recognize the \samp{REST} command, an -\exception{error_reply} exception will be raised. If this happens, -simply call \method{transfercmd()} without a \var{rest} argument. -\end{methoddesc} - -\begin{methoddesc}[FTP]{ntransfercmd}{cmd\optional{, rest}} -Like \method{transfercmd()}, but returns a tuple of the data -connection and the expected size of the data. If the expected size -could not be computed, \code{None} will be returned as the expected -size. \var{cmd} and \var{rest} means the same thing as in -\method{transfercmd()}. -\end{methoddesc} - -\begin{methoddesc}[FTP]{nlst}{argument\optional{, \ldots}} -Return a list of files as returned by the \samp{NLST} command. The -optional \var{argument} is a directory to list (default is the current -server directory). Multiple arguments can be used to pass -non-standard options to the \samp{NLST} command. -\end{methoddesc} - -\begin{methoddesc}[FTP]{dir}{argument\optional{, \ldots}} -Produce a directory listing as returned by the \samp{LIST} command, -printing it to standard output. The optional \var{argument} is a -directory to list (default is the current server directory). Multiple -arguments can be used to pass non-standard options to the \samp{LIST} -command. If the last argument is a function, it is used as a -\var{callback} function as for \method{retrlines()}; the default -prints to \code{sys.stdout}. This method returns \code{None}. -\end{methoddesc} - -\begin{methoddesc}[FTP]{rename}{fromname, toname} -Rename file \var{fromname} on the server to \var{toname}. -\end{methoddesc} - -\begin{methoddesc}[FTP]{delete}{filename} -Remove the file named \var{filename} from the server. If successful, -returns the text of the response, otherwise raises -\exception{error_perm} on permission errors or -\exception{error_reply} on other errors. -\end{methoddesc} - -\begin{methoddesc}[FTP]{cwd}{pathname} -Set the current directory on the server. -\end{methoddesc} - -\begin{methoddesc}[FTP]{mkd}{pathname} -Create a new directory on the server. -\end{methoddesc} - -\begin{methoddesc}[FTP]{pwd}{} -Return the pathname of the current directory on the server. -\end{methoddesc} - -\begin{methoddesc}[FTP]{rmd}{dirname} -Remove the directory named \var{dirname} on the server. -\end{methoddesc} - -\begin{methoddesc}[FTP]{size}{filename} -Request the size of the file named \var{filename} on the server. On -success, the size of the file is returned as an integer, otherwise -\code{None} is returned. Note that the \samp{SIZE} command is not -standardized, but is supported by many common server implementations. -\end{methoddesc} - -\begin{methoddesc}[FTP]{quit}{} -Send a \samp{QUIT} command to the server and close the connection. -This is the ``polite'' way to close a connection, but it may raise an -exception of the server reponds with an error to the -\samp{QUIT} command. This implies a call to the \method{close()} -method which renders the \class{FTP} instance useless for subsequent -calls (see below). -\end{methoddesc} - -\begin{methoddesc}[FTP]{close}{} -Close the connection unilaterally. This should not be applied to an -already closed connection such as after a successful call to -\method{quit()}. After this call the \class{FTP} instance should not -be used any more (after a call to \method{close()} or -\method{quit()} you cannot reopen the connection by issuing another -\method{login()} method). -\end{methoddesc} diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex deleted file mode 100644 index 0fcc4f4..0000000 --- a/Doc/lib/libfuncs.tex +++ /dev/null @@ -1,1125 +0,0 @@ -\section{Built-in Functions \label{built-in-funcs}} - -The Python interpreter has a number of functions built into it that -are always available. They are listed here in alphabetical order. - - -\setindexsubitem{(built-in function)} - -\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist\optional{, level}}}}} - This function is invoked by the \keyword{import}\stindex{import} - statement. It mainly exists so that you can replace it with another - function that has a compatible interface, in order to change the - semantics of the \keyword{import} statement. For examples of why - and how you would do this, see the standard library modules - \module{ihooks}\refstmodindex{ihooks} and - \refmodule{rexec}\refstmodindex{rexec}. See also the built-in - module \refmodule{imp}\refbimodindex{imp}, which defines some useful - operations out of which you can build your own - \function{__import__()} function. - - For example, the statement \samp{import spam} results in the - following call: \code{__import__('spam',} \code{globals(),} - \code{locals(), [], -1)}; the statement \samp{from spam.ham import eggs} - results in \samp{__import__('spam.ham', globals(), locals(), - ['eggs'], -1)}. Note that even though \code{locals()} and - \code{['eggs']} are passed in as arguments, the - \function{__import__()} function does not set the local variable - named \code{eggs}; this is done by subsequent code that is generated - for the import statement. (In fact, the standard implementation - does not use its \var{locals} argument at all, and uses its - \var{globals} only to determine the package context of the - \keyword{import} statement.) - - When the \var{name} variable is of the form \code{package.module}, - normally, the top-level package (the name up till the first dot) is - returned, \emph{not} the module named by \var{name}. However, when - a non-empty \var{fromlist} argument is given, the module named by - \var{name} is returned. This is done for compatibility with the - bytecode generated for the different kinds of import statement; when - using \samp{import spam.ham.eggs}, the top-level package \module{spam} - must be placed in the importing namespace, but when using \samp{from - spam.ham import eggs}, the \code{spam.ham} subpackage must be used - to find the \code{eggs} variable. As a workaround for this - behavior, use \function{getattr()} to extract the desired - components. For example, you could define the following helper: - -\begin{verbatim} -def my_import(name): - mod = __import__(name) - components = name.split('.') - for comp in components[1:]: - mod = getattr(mod, comp) - return mod -\end{verbatim} - - \var{level} specifies whether to use absolute or relative imports. - The default is \code{-1} which indicates both absolute and relative - imports will be attempted. \code{0} means only perform absolute imports. - Positive values for \var{level} indicate the number of parent directories - to search relative to the directory of the module calling - \function{__import__}. -\versionchanged[The level parameter was added]{2.5} -\versionchanged[Keyword support for parameters was added]{2.5} -\end{funcdesc} - -\begin{funcdesc}{abs}{x} - Return the absolute value of a number. The argument may be a plain - or long integer or a floating point number. If the argument is a - complex number, its magnitude is returned. -\end{funcdesc} - -\begin{funcdesc}{all}{iterable} - Return True if all elements of the \var{iterable} are true. - Equivalent to: - \begin{verbatim} - def all(iterable): - for element in iterable: - if not element: - return False - return True - \end{verbatim} - \versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{any}{iterable} - Return True if any element of the \var{iterable} is true. - Equivalent to: - \begin{verbatim} - def any(iterable): - for element in iterable: - if element: - return True - return False - \end{verbatim} - \versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{basestring}{} - This abstract type is the superclass for \class{str}. - It cannot be called or instantiated, but it can be used to test whether - an object is an instance of \class{str}. - \code{isinstance(obj, basestring)} is equivalent to - \code{isinstance(obj, str)}. - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{bin}{x} - Convert an integer number to a binary string. - The result is a valid Python expression. If \var{x} is not a Python - \class{int} object, it has to define an \method{__index__} method - that returns an integer. - \versionadded{3.0} -\end{funcdesc} - -\begin{funcdesc}{bool}{\optional{x}} - Convert a value to a Boolean, using the standard truth testing - procedure. If \var{x} is false or omitted, this returns - \constant{False}; otherwise it returns \constant{True}. - \class{bool} is also a class, which is a subclass of \class{int}. - Class \class{bool} cannot be subclassed further. Its only instances - are \constant{False} and \constant{True}. - - \indexii{Boolean}{type} - \versionadded{2.2.1} - \versionchanged[If no argument is given, this function returns - \constant{False}]{2.3} -\end{funcdesc} - -\begin{funcdesc}{chr}{i} - Return the Unicode string of one character whose Unicode code is the - integer \var{i}. For example, \code{unichr(97)} returns the string - \code{u'a'}. This is the inverse of \function{ord()} for Unicode - strings. The valid range for the argument depends how Python was - configured -- it may be either UCS2 [0..0xFFFF] or UCS4 [0..0x10FFFF]. - \exception{ValueError} is raised otherwise. -\end{funcdesc} - -\begin{funcdesc}{classmethod}{function} - Return a class method for \var{function}. - - A class method receives the class as implicit first argument, - just like an instance method receives the instance. - To declare a class method, use this idiom: - -\begin{verbatim} -class C: - @classmethod - def f(cls, arg1, arg2, ...): ... -\end{verbatim} - - The \code{@classmethod} form is a function decorator -- see the description - of function definitions in chapter 7 of the - \citetitle[../ref/ref.html]{Python Reference Manual} for details. - - It can be called either on the class (such as \code{C.f()}) or on an - instance (such as \code{C().f()}). The instance is ignored except for - its class. - If a class method is called for a derived class, the derived class - object is passed as the implied first argument. - - Class methods are different than \Cpp{} or Java static methods. - If you want those, see \function{staticmethod()} in this section. - - For more information on class methods, consult the documentation on the - standard type hierarchy in chapter 3 of the - \citetitle[../ref/types.html]{Python Reference Manual} (at the bottom). - \versionadded{2.2} - \versionchanged[Function decorator syntax added]{2.4} -\end{funcdesc} - -\begin{funcdesc}{cmp}{x, y} - Compare the two objects \var{x} and \var{y} and return an integer - according to the outcome. The return value is negative if \code{\var{x} - < \var{y}}, zero if \code{\var{x} == \var{y}} and strictly positive if - \code{\var{x} > \var{y}}. -\end{funcdesc} - -\begin{funcdesc}{compile}{source, filename, mode\optional{, - flags\optional{, dont_inherit}}} - Compile the \var{source} into a code object. Code objects can be - executed by a call to \function{exec()} or evaluated by a call to - \function{eval()}. The \var{filename} argument should - give the file from which the code was read; pass some recognizable value - if it wasn't read from a file (\code{'<string>'} is commonly used). - The \var{mode} argument specifies what kind of code must be - compiled; it can be \code{'exec'} if \var{source} consists of a - sequence of statements, \code{'eval'} if it consists of a single - expression, or \code{'single'} if it consists of a single - interactive statement (in the latter case, expression statements - that evaluate to something else than \code{None} will be printed). - - When compiling multi-line statements, two caveats apply: line - endings must be represented by a single newline character - (\code{'\e n'}), and the input must be terminated by at least one - newline character. If line endings are represented by - \code{'\e r\e n'}, use the string \method{replace()} method to - change them into \code{'\e n'}. - - The optional arguments \var{flags} and \var{dont_inherit} - (which are new in Python 2.2) control which future statements (see - \pep{236}) affect the compilation of \var{source}. If neither is - present (or both are zero) the code is compiled with those future - statements that are in effect in the code that is calling compile. - If the \var{flags} argument is given and \var{dont_inherit} is not - (or is zero) then the future statements specified by the \var{flags} - argument are used in addition to those that would be used anyway. - If \var{dont_inherit} is a non-zero integer then the \var{flags} - argument is it -- the future statements in effect around the call to - compile are ignored. - - Future statements are specified by bits which can be bitwise or-ed - together to specify multiple statements. The bitfield required to - specify a given feature can be found as the \member{compiler_flag} - attribute on the \class{_Feature} instance in the - \module{__future__} module. -\end{funcdesc} - -\begin{funcdesc}{complex}{\optional{real\optional{, imag}}} - Create a complex number with the value \var{real} + \var{imag}*j or - convert a string or number to a complex number. If the first - parameter is a string, it will be interpreted as a complex number - and the function must be called without a second parameter. The - second parameter can never be a string. - Each argument may be any numeric type (including complex). - If \var{imag} is omitted, it defaults to zero and the function - serves as a numeric conversion function like \function{int()}, - \function{long()} and \function{float()}. If both arguments - are omitted, returns \code{0j}. -\end{funcdesc} - -\begin{funcdesc}{delattr}{object, name} - This is a relative of \function{setattr()}. The arguments are an - object and a string. The string must be the name - of one of the object's attributes. The function deletes - the named attribute, provided the object allows it. For example, - \code{delattr(\var{x}, '\var{foobar}')} is equivalent to - \code{del \var{x}.\var{foobar}}. -\end{funcdesc} - -\begin{funcdesc}{dict}{\optional{arg}} - Return a new dictionary initialized from an optional positional - argument or from a set of keyword arguments. - If no arguments are given, return a new empty dictionary. - If the positional argument \var{arg} is a mapping object, return a dictionary - mapping the same keys to the same values as does the mapping object. - Otherwise the positional argument must be a sequence, a container that - supports iteration, or an iterator object. The elements of the argument - must each also be of one of those kinds, and each must in turn contain - exactly two objects. The first is used as a key in the new dictionary, - and the second as the key's value. If a given key is seen more than - once, the last value associated with it is retained in the new - dictionary. - - If keyword arguments are given, the keywords themselves with their - associated values are added as items to the dictionary. If a key - is specified both in the positional argument and as a keyword argument, - the value associated with the keyword is retained in the dictionary. - For example, these all return a dictionary equal to - \code{\{"one": 2, "two": 3\}}: - - \begin{itemize} - \item \code{dict(\{'one': 2, 'two': 3\})} - \item \code{dict(\{'one': 2, 'two': 3\}.items())} - \item \code{dict(\{'one': 2, 'two': 3\}.iteritems())} - \item \code{dict(zip(('one', 'two'), (2, 3)))} - \item \code{dict([['two', 3], ['one', 2]])} - \item \code{dict(one=2, two=3)} - \item \code{dict([(['one', 'two'][i-2], i) for i in (2, 3)])} - \end{itemize} - - \versionadded{2.2} - \versionchanged[Support for building a dictionary from keyword - arguments added]{2.3} -\end{funcdesc} - -\begin{funcdesc}{dir}{\optional{object}} - Without arguments, return the list of names in the current local scope. With - an argument, attempt to return a list of valid attributes for that object. - - If the object has a method named \method{__dir__()}, this method will be - called and must return the list of attributes. This allows objects that - implement a custom \function{__getattr__()} or \function{__getattribute__()} - function to customize the way \function{dir()} reports their attributes. - - If the object does not provide \method{__dir__()}, the function tries its best - to gather information from the object's \member{__dict__} attribute, if - defined, and from its type object. The resulting list is not necessarily - complete, and may be inaccurate when the object has a custom - \function{__getattr__()}. - - The default \function{dir()} mechanism behaves differently with different - types of objects, as it attempts to produce the most relevant, rather than - complete, information: - \begin{itemize} - \item If the object is a module object, the list contains the names of the - module's attributes. - \item If the object is a type or class object, the list contains the names of - its attributes, and recursively of the attributes of its bases. - \item Otherwise, the list contains the object's attributes' names, the names - of its class's attributes, and recursively of the attributes of its class's - base classes. - \end{itemize} - - The resulting list is sorted alphabetically. For example: - -\begin{verbatim} ->>> import struct ->>> dir() -['__builtins__', '__doc__', '__name__', 'struct'] ->>> dir(struct) -['__doc__', '__name__', 'calcsize', 'error', 'pack', 'unpack'] ->>> class Foo(object): -... def __dir__(self): -... return ["kan", "ga", "roo"] -... ->>> f = Foo() ->>> dir(f) -['ga', 'kan', 'roo'] -\end{verbatim} - - \note{Because \function{dir()} is supplied primarily as a convenience for use - at an interactive prompt, it tries to supply an interesting set of names - more than it tries to supply a rigorously or consistently defined set of - names, and its detailed behavior may change across releases.} -\end{funcdesc} - -\begin{funcdesc}{divmod}{a, b} - Take two (non complex) numbers as arguments and return a pair of numbers - consisting of their quotient and remainder when using long division. With - mixed operand types, the rules for binary arithmetic operators apply. For - plain and long integers, the result is the same as - \code{(\var{a} // \var{b}, \var{a} \%{} \var{b})}. - For floating point numbers the result is \code{(\var{q}, \var{a} \%{} - \var{b})}, where \var{q} is usually \code{math.floor(\var{a} / - \var{b})} but may be 1 less than that. In any case \code{\var{q} * - \var{b} + \var{a} \%{} \var{b}} is very close to \var{a}, if - \code{\var{a} \%{} \var{b}} is non-zero it has the same sign as - \var{b}, and \code{0 <= abs(\var{a} \%{} \var{b}) < abs(\var{b})}. - - \versionchanged[Using \function{divmod()} with complex numbers is - deprecated]{2.3} -\end{funcdesc} - -\begin{funcdesc}{enumerate}{iterable} - Return an enumerate object. \var{iterable} must be a sequence, an iterator, or - some other object which supports iteration. The \method{__next__()} method of - the iterator returned by \function{enumerate()} returns a tuple containing a - count (from zero) and the corresponding value obtained from iterating over - \var{iterable}. \function{enumerate()} is useful for obtaining an indexed - series: \code{(0, seq[0])}, \code{(1, seq[1])}, \code{(2, seq[2])}, \ldots. - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{eval}{expression\optional{, globals\optional{, locals}}} - The arguments are a string and optional globals and locals. If provided, - \var{globals} must be a dictionary. If provided, \var{locals} can be - any mapping object. \versionchanged[formerly \var{locals} was required - to be a dictionary]{2.4} - - The \var{expression} argument is parsed and evaluated as a Python - expression (technically speaking, a condition list) using the - \var{globals} and \var{locals} dictionaries as global and local name - space. If the \var{globals} dictionary is present and lacks - '__builtins__', the current globals are copied into \var{globals} before - \var{expression} is parsed. This means that \var{expression} - normally has full access to the standard - \refmodule[builtin]{__builtin__} module and restricted environments - are propagated. If the \var{locals} dictionary is omitted it defaults to - the \var{globals} dictionary. If both dictionaries are omitted, the - expression is executed in the environment where \keyword{eval} is - called. The return value is the result of the evaluated expression. - Syntax errors are reported as exceptions. Example: - -\begin{verbatim} ->>> x = 1 ->>> print eval('x+1') -2 -\end{verbatim} - - This function can also be used to execute arbitrary code objects - (such as those created by \function{compile()}). In this case pass - a code object instead of a string. The code object must have been - compiled passing \code{'eval'} as the \var{kind} argument. - - Hints: dynamic execution of statements is supported by the - \function{exec()} function. The - \function{globals()} and \function{locals()} functions returns the - current global and local dictionary, respectively, which may be - useful to pass around for use by \function{eval()} or - \function{exec()}. -\end{funcdesc} - -\begin{funcdesc}{exec}{object\optional{, globals\optional{, locals}}} - This function supports dynamic execution of Python code. - \var{object} must be either a string, an open file object, or - a code object. If it is a string, the string is parsed as a suite of - Python statements which is then executed (unless a syntax error - occurs). If it is an open file, the file is parsed until \EOF{} and - executed. If it is a code object, it is simply executed. In all - cases, the code that's executed is expected to be valid as file - input (see the section ``File input'' in the Reference Manual). - Be aware that the \keyword{return} and \keyword{yield} statements may - not be used outside of function definitions even within the context of - code passed to the \function{exec()} function. - The return value is \code{None}. - - In all cases, if the optional parts are omitted, the code is executed - in the current scope. If only \var{globals} is provided, it must be - a dictionary, which will be used for both the global and the local - variables. If \var{globals} and \var{locals} are given, they are used - for the global and local variables, respectively. If provided, - \var{locals} can be any mapping object. - - If the \var{globals} dictionary does not contain a value for the - key \code{__builtins__}, a reference to the dictionary of the built-in - module \module{__builtin__} is inserted under that key. That way you - can control what builtins are available to the executed code by - inserting your own \code{__builtins__} dictionary into \var{globals} - before passing it to \function{exec()}. - - \note{The built-in functions \function{globals()} and \function{locals()} - return the current global and local dictionary, respectively, which - may be useful to pass around for use as the second and third - argument to \function{exec()}.} -\end{funcdesc} - -\begin{funcdesc}{filter}{function, iterable} - Construct a list from those elements of \var{iterable} for which - \var{function} returns true. \var{iterable} may be either a sequence, a - container which supports iteration, or an iterator, If \var{iterable} - is a string or a tuple, the result - also has that type; otherwise it is always a list. If \var{function} is - \code{None}, the identity function is assumed, that is, all elements of - \var{iterable} that are false are removed. - - Note that \code{filter(function, \var{iterable})} is equivalent to - \code{[item for item in \var{iterable} if function(item)]} if function is - not \code{None} and \code{[item for item in \var{iterable} if item]} if - function is \code{None}. -\end{funcdesc} - -\begin{funcdesc}{float}{\optional{x}} - Convert a string or a number to floating point. If the argument is a - string, it must contain a possibly signed decimal or floating point - number, possibly embedded in whitespace. Otherwise, the argument may be a plain - or long integer or a floating point number, and a floating point - number with the same value (within Python's floating point - precision) is returned. If no argument is given, returns \code{0.0}. - - \note{When passing in a string, values for NaN\index{NaN} - and Infinity\index{Infinity} may be returned, depending on the - underlying C library. The specific set of strings accepted which - cause these values to be returned depends entirely on the C library - and is known to vary.} -\end{funcdesc} - -\begin{funcdesc}{frozenset}{\optional{iterable}} - Return a frozenset object whose elements are taken from \var{iterable}. - Frozensets are sets that have no update methods but can be hashed and - used as members of other sets or as dictionary keys. The elements of - a frozenset must be immutable themselves. To represent sets of sets, - the inner sets should also be \class{frozenset} objects. If - \var{iterable} is not specified, returns a new empty set, - \code{frozenset([])}. - \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{getattr}{object, name\optional{, default}} - Return the value of the named attributed of \var{object}. \var{name} - must be a string. If the string is the name of one of the object's - attributes, the result is the value of that attribute. For example, - \code{getattr(x, 'foobar')} is equivalent to \code{x.foobar}. If the - named attribute does not exist, \var{default} is returned if provided, - otherwise \exception{AttributeError} is raised. -\end{funcdesc} - -\begin{funcdesc}{globals}{} - Return a dictionary representing the current global symbol table. - This is always the dictionary of the current module (inside a - function or method, this is the module where it is defined, not the - module from which it is called). -\end{funcdesc} - -\begin{funcdesc}{hasattr}{object, name} - The arguments are an object and a string. The result is \code{True} if the - string is the name of one of the object's attributes, \code{False} if not. - (This is implemented by calling \code{getattr(\var{object}, - \var{name})} and seeing whether it raises an exception or not.) -\end{funcdesc} - -\begin{funcdesc}{hash}{object} - Return the hash value of the object (if it has one). Hash values - are integers. They are used to quickly compare dictionary - keys during a dictionary lookup. Numeric values that compare equal - have the same hash value (even if they are of different types, as is - the case for 1 and 1.0). -\end{funcdesc} - -\begin{funcdesc}{help}{\optional{object}} - Invoke the built-in help system. (This function is intended for - interactive use.) If no argument is given, the interactive help - system starts on the interpreter console. If the argument is a - string, then the string is looked up as the name of a module, - function, class, method, keyword, or documentation topic, and a - help page is printed on the console. If the argument is any other - kind of object, a help page on the object is generated. - \versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{hex}{x} - Convert an integer number to a hexadecimal string. - The result is a valid Python expression. If \var{x} is not a Python - \class{int} object, it has to define an \method{__index__} method - that returns an integer. - \versionchanged[Formerly only returned an unsigned literal]{2.4} -\end{funcdesc} - -\begin{funcdesc}{id}{object} - Return the ``identity'' of an object. This is an integer (or long - integer) which is guaranteed to be unique and constant for this - object during its lifetime. Two objects with non-overlapping lifetimes - may have the same \function{id()} value. (Implementation - note: this is the address of the object.) -\end{funcdesc} - -\begin{funcdesc}{int}{\optional{x\optional{, radix}}} - Convert a string or number to a long integer. If the argument is a - string, it must contain a possibly signed number of - arbitrary size, possibly embedded in whitespace. The - \var{radix} argument is interpreted in the same way as for - \function{int()}, and may only be given when \var{x} is a string. - Otherwise, the argument may be another - integer or a floating point number, and an integer with - the same value is returned. Conversion of floating - point numbers to integers truncates (towards zero). If no arguments - are given, returns \code{0}. -\end{funcdesc} - -\begin{funcdesc}{isinstance}{object, classinfo} - Return true if the \var{object} argument is an instance of the - \var{classinfo} argument, or of a (direct or indirect) subclass - thereof. Also return true if \var{classinfo} is a type object - (new-style class) and \var{object} is an object of that type or of a - (direct or indirect) subclass thereof. If \var{object} is not a - class instance or an object of the given type, the function always - returns false. If \var{classinfo} is neither a class object nor a - type object, it may be a tuple of class or type objects, or may - recursively contain other such tuples (other sequence types are not - accepted). If \var{classinfo} is not a class, type, or tuple of - classes, types, and such tuples, a \exception{TypeError} exception - is raised. - \versionchanged[Support for a tuple of type information was added]{2.2} -\end{funcdesc} - -\begin{funcdesc}{issubclass}{class, classinfo} - Return true if \var{class} is a subclass (direct or indirect) of - \var{classinfo}. A class is considered a subclass of itself. - \var{classinfo} may be a tuple of class objects, in which case every - entry in \var{classinfo} will be checked. In any other case, a - \exception{TypeError} exception is raised. - \versionchanged[Support for a tuple of type information was added]{2.3} -\end{funcdesc} - -\begin{funcdesc}{iter}{o\optional{, sentinel}} - Return an iterator object. The first argument is interpreted very - differently depending on the presence of the second argument. - Without a second argument, \var{o} must be a collection object which - supports the iteration protocol (the \method{__iter__()} method), or - it must support the sequence protocol (the \method{__getitem__()} - method with integer arguments starting at \code{0}). If it does not - support either of those protocols, \exception{TypeError} is raised. - If the second argument, \var{sentinel}, is given, then \var{o} must - be a callable object. The iterator created in this case will call - \var{o} with no arguments for each call to its \method{__next__()} - method; if the value returned is equal to \var{sentinel}, - \exception{StopIteration} will be raised, otherwise the value will - be returned. - \versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{len}{s} - Return the length (the number of items) of an object. The argument - may be a sequence (string, tuple or list) or a mapping (dictionary). -\end{funcdesc} - -\begin{funcdesc}{list}{\optional{iterable}} - Return a list whose items are the same and in the same order as - \var{iterable}'s items. \var{iterable} may be either a sequence, a - container that supports iteration, or an iterator object. If - \var{iterable} is already a list, a copy is made and returned, - similar to \code{\var{iterable}[:]}. For instance, - \code{list('abc')} returns \code{['a', 'b', 'c']} and \code{list( - (1, 2, 3) )} returns \code{[1, 2, 3]}. If no argument is given, - returns a new empty list, \code{[]}. -\end{funcdesc} - -\begin{funcdesc}{locals}{} - Update and return a dictionary representing the current local symbol table. - \warning{The contents of this dictionary should not be modified; - changes may not affect the values of local variables used by the - interpreter.} - - Free variables are returned by \var{locals} when it is called in - a function block. Modifications of free variables may not affect - the values used by the interpreter. Free variables are not - returned in class blocks. -\end{funcdesc} - -\begin{funcdesc}{map}{function, iterable, ...} - Apply \var{function} to every item of \var{iterable} and return a list - of the results. If additional \var{iterable} arguments are passed, - \var{function} must take that many arguments and is applied to the - items from all iterables in parallel. If one iterable is shorter than another it - is assumed to be extended with \code{None} items. If \var{function} - is \code{None}, the identity function is assumed; if there are - multiple arguments, \function{map()} returns a list consisting - of tuples containing the corresponding items from all iterables (a kind - of transpose operation). The \var{iterable} arguments may be a sequence - or any iterable object; the result is always a list. -\end{funcdesc} - -\begin{funcdesc}{max}{iterable\optional{, args...}\optional{key}} - With a single argument \var{iterable}, return the largest item of a - non-empty iterable (such as a string, tuple or list). With more - than one argument, return the largest of the arguments. - - The optional \var{key} argument specifies a one-argument ordering - function like that used for \method{list.sort()}. The \var{key} - argument, if supplied, must be in keyword form (for example, - \samp{max(a,b,c,key=func)}). - \versionchanged[Added support for the optional \var{key} argument]{2.5} -\end{funcdesc} - -\begin{funcdesc}{min}{iterable\optional{, args...}\optional{key}} - With a single argument \var{iterable}, return the smallest item of a - non-empty iterable (such as a string, tuple or list). With more - than one argument, return the smallest of the arguments. - - The optional \var{key} argument specifies a one-argument ordering - function like that used for \method{list.sort()}. The \var{key} - argument, if supplied, must be in keyword form (for example, - \samp{min(a,b,c,key=func)}). - \versionchanged[Added support for the optional \var{key} argument]{2.5} -\end{funcdesc} - -\begin{funcdesc}{next}{iterator\optional{, default}} - Retrieve the next item from the \var{iterable} by calling its - \method{__next__()} method. If \var{default} is given, it is returned if the - iterator is exhausted, otherwise \exception{StopIteration} is raised. -\end{funcdesc} - -\begin{funcdesc}{object}{} - Return a new featureless object. \class{object} is a base - for all new style classes. It has the methods that are common - to all instances of new style classes. - \versionadded{2.2} - - \versionchanged[This function does not accept any arguments. - Formerly, it accepted arguments but ignored them]{2.3} -\end{funcdesc} - -\begin{funcdesc}{oct}{x} - Convert an integer number to an octal string. The - result is a valid Python expression. If \var{x} is not a Python - \class{int} object, it has to define an \method{__index__} method - that returns an integer. - \versionchanged[Formerly only returned an unsigned literal]{2.4} -\end{funcdesc} - -\begin{funcdesc}{open}{filename\optional{, mode\optional{, bufsize}}} - Open a file, returning an object of the \class{file} type described - in section~\ref{bltin-file-objects}, ``\ulink{File - Objects}{bltin-file-objects.html}''. If the file cannot be opened, - \exception{IOError} is raised. When opening a file, it's - preferable to use \function{open()} instead of invoking the - \class{file} constructor directly. - - The first two arguments are the same as for \code{stdio}'s - \cfunction{fopen()}: \var{filename} is the file name to be opened, - and \var{mode} is a string indicating how the file is to be opened. - - The most commonly-used values of \var{mode} are \code{'r'} for - reading, \code{'w'} for writing (truncating the file if it already - exists), and \code{'a'} for appending (which on \emph{some} \UNIX{} - systems means that \emph{all} writes append to the end of the file - regardless of the current seek position). If \var{mode} is omitted, - it defaults to \code{'r'}. When opening a binary file, you should - append \code{'b'} to the \var{mode} value to open the file in binary - mode, which will improve portability. (Appending \code{'b'} is - useful even on systems that don't treat binary and text files - differently, where it serves as documentation.) See below for more - possible values of \var{mode}. - - \index{line-buffered I/O}\index{unbuffered I/O}\index{buffer size, I/O} - \index{I/O control!buffering} - The optional \var{bufsize} argument specifies the - file's desired buffer size: 0 means unbuffered, 1 means line - buffered, any other positive value means use a buffer of - (approximately) that size. A negative \var{bufsize} means to use - the system default, which is usually line buffered for tty - devices and fully buffered for other files. If omitted, the system - default is used.\footnote{ - Specifying a buffer size currently has no effect on systems that - don't have \cfunction{setvbuf()}. The interface to specify the - buffer size is not done using a method that calls - \cfunction{setvbuf()}, because that may dump core when called - after any I/O has been performed, and there's no reliable way to - determine whether this is the case.} - - Modes \code{'r+'}, \code{'w+'} and \code{'a+'} open the file for - updating (note that \code{'w+'} truncates the file). Append - \code{'b'} to the mode to open the file in binary mode, on systems - that differentiate between binary and text files; on systems - that don't have this distinction, adding the \code{'b'} has no effect. - - In addition to the standard \cfunction{fopen()} values \var{mode} - may be \code{'U'} or \code{'rU'}. Python is usually built with universal - newline support; supplying \code{'U'} opens the file as a text file, but - lines may be terminated by any of the following: the \UNIX{} end-of-line - convention \code{'\e n'}, - the Macintosh convention \code{'\e r'}, or the Windows - convention \code{'\e r\e n'}. All of these external representations are seen as - \code{'\e n'} - by the Python program. If Python is built without universal newline support - a \var{mode} with \code{'U'} is the same as normal text mode. Note that - file objects so opened also have an attribute called - \member{newlines} which has a value of \code{None} (if no newlines - have yet been seen), \code{'\e n'}, \code{'\e r'}, \code{'\e r\e n'}, - or a tuple containing all the newline types seen. - - Python enforces that the mode, after stripping \code{'U'}, begins with - \code{'r'}, \code{'w'} or \code{'a'}. - - \versionchanged[Restriction on first letter of mode string - introduced]{2.5} -\end{funcdesc} - -\begin{funcdesc}{ord}{c} - Given a string of length one, return an integer representing the - Unicode code point of the character when the argument is a unicode object, - or the value of the byte when the argument is an 8-bit string. - For example, \code{ord('a')} returns the integer \code{97}, - \code{ord(u'\e u2020')} returns \code{8224}. This is the inverse of - \function{chr()} for strings. - If Python was built with - UCS2 Unicode, then the character's code point must be in the range - [0..65535] inclusive; otherwise the string length is two, and a - \exception{TypeError} will be raised. -\end{funcdesc} - -\begin{funcdesc}{pow}{x, y\optional{, z}} - Return \var{x} to the power \var{y}; if \var{z} is present, return - \var{x} to the power \var{y}, modulo \var{z} (computed more - efficiently than \code{pow(\var{x}, \var{y}) \%\ \var{z}}). - The two-argument form \code{pow(\var{x}, \var{y})} is equivalent to using - the power operator: \code{\var{x}**\var{y}}. - - The arguments must have numeric types. With mixed operand types, the - coercion rules for binary arithmetic operators apply. For int and - long int operands, the result has the same type as the operands - (after coercion) unless the second argument is negative; in that - case, all arguments are converted to float and a float result is - delivered. For example, \code{10**2} returns \code{100}, but - \code{10**-2} returns \code{0.01}. (This last feature was added in - Python 2.2. In Python 2.1 and before, if both arguments were of integer - types and the second argument was negative, an exception was raised.) - If the second argument is negative, the third argument must be omitted. - If \var{z} is present, \var{x} and \var{y} must be of integer types, - and \var{y} must be non-negative. (This restriction was added in - Python 2.2. In Python 2.1 and before, floating 3-argument \code{pow()} - returned platform-dependent results depending on floating-point - rounding accidents.) -\end{funcdesc} - -\begin{funcdesc}{property}{\optional{fget\optional{, fset\optional{, - fdel\optional{, doc}}}}} - Return a property attribute for new-style classes (classes that - derive from \class{object}). - - \var{fget} is a function for getting an attribute value, likewise - \var{fset} is a function for setting, and \var{fdel} a function - for del'ing, an attribute. Typical use is to define a managed attribute x: - -\begin{verbatim} -class C(object): - def __init__(self): self._x = None - def getx(self): return self._x - def setx(self, value): self._x = value - def delx(self): del self._x - x = property(getx, setx, delx, "I'm the 'x' property.") -\end{verbatim} - - If given, \var{doc} will be the docstring of the property attribute. - Otherwise, the property will copy \var{fget}'s docstring (if it - exists). This makes it possible to create read-only properties - easily using \function{property()} as a decorator: - -\begin{verbatim} -class Parrot(object): - def __init__(self): - self._voltage = 100000 - - @property - def voltage(self): - """Get the current voltage.""" - return self._voltage -\end{verbatim} - - turns the \method{voltage()} method into a ``getter'' for a read-only - attribute with the same name. - - \versionadded{2.2} - \versionchanged[Use \var{fget}'s docstring if no \var{doc} given]{2.5} -\end{funcdesc} - -\begin{funcdesc}{range}{\optional{start,} stop\optional{, step}} - This is a versatile function to create sequences containing arithmetic - progressions. It is most often used in \keyword{for} loops. The - arguments must be plain integers. If the \var{step} argument is - omitted, it defaults to \code{1}. If the \var{start} argument is - omitted, it defaults to \code{0}. The full form returns a list of - plain integers \code{[\var{start}, \var{start} + \var{step}, - \var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive, - the last element is the largest \code{\var{start} + \var{i} * - \var{step}} less than \var{stop}; if \var{step} is negative, the last - element is the smallest \code{\var{start} + \var{i} * \var{step}} - greater than \var{stop}. \var{step} must not be zero (or else - \exception{ValueError} is raised). Example: - -\begin{verbatim} ->>> list(range(10)) -[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] ->>> list(range(1, 11)) -[1, 2, 3, 4, 5, 6, 7, 8, 9, 10] ->>> list(range(0, 30, 5)) -[0, 5, 10, 15, 20, 25] ->>> list(range(0, 10, 3)) -[0, 3, 6, 9] ->>> list(range(0, -10, -1)) -[0, -1, -2, -3, -4, -5, -6, -7, -8, -9] ->>> list(range(0)) -[] ->>> list(range(1, 0)) -[] -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{repr}{object} - Return a string containing a printable representation of an object. - This is the same value yielded by conversions (reverse quotes). - It is sometimes useful to be able to access this operation as an - ordinary function. For many types, this function makes an attempt - to return a string that would yield an object with the same value - when passed to \function{eval()}. -\end{funcdesc} - -\begin{funcdesc}{reversed}{seq} - Return a reverse iterator. \var{seq} must be an object which - supports the sequence protocol (the \method{__len__()} method and the - \method{__getitem__()} method with integer arguments starting at - \code{0}). - \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{round}{x\optional{, n}} - Return the floating point value \var{x} rounded to \var{n} digits - after the decimal point. If \var{n} is omitted, it defaults to zero. - The result is a floating point number. Values are rounded to the - closest multiple of 10 to the power minus \var{n}; if two multiples - are equally close, rounding is done away from 0 (so. for example, - \code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}). -\end{funcdesc} - -\begin{funcdesc}{set}{\optional{iterable}} - Return a set whose elements are taken from \var{iterable}. The elements - must be immutable. To represent sets of sets, the inner sets should - be \class{frozenset} objects. If \var{iterable} is not specified, - returns a new empty set, \code{set([])}. - \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{setattr}{object, name, value} - This is the counterpart of \function{getattr()}. The arguments are an - object, a string and an arbitrary value. The string may name an - existing attribute or a new attribute. The function assigns the - value to the attribute, provided the object allows it. For example, - \code{setattr(\var{x}, '\var{foobar}', 123)} is equivalent to - \code{\var{x}.\var{foobar} = 123}. -\end{funcdesc} - -\begin{funcdesc}{slice}{\optional{start,} stop\optional{, step}} - Return a slice object representing the set of indices specified by - \code{range(\var{start}, \var{stop}, \var{step})}. The \var{start} - and \var{step} arguments default to \code{None}. Slice objects have - read-only data attributes \member{start}, \member{stop} and - \member{step} which merely return the argument values (or their - default). They have no other explicit functionality; however they - are used by Numerical Python\index{Numerical Python} and other third - party extensions. Slice objects are also generated when extended - indexing syntax is used. For example: \samp{a[start:stop:step]} or - \samp{a[start:stop, i]}. -\end{funcdesc} - -\begin{funcdesc}{sorted}{iterable\optional{, cmp\optional{, - key\optional{, reverse}}}} - Return a new sorted list from the items in \var{iterable}. - - The optional arguments \var{cmp}, \var{key}, and \var{reverse} have - the same meaning as those for the \method{list.sort()} method - (described in section~\ref{typesseq-mutable}). - - \var{cmp} specifies a custom comparison function of two arguments - (iterable elements) which should return a negative, zero or positive - number depending on whether the first argument is considered smaller - than, equal to, or larger than the second argument: - \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}: - \function{cmp}(x.lower(), y.lower())} - - \var{key} specifies a function of one argument that is used to - extract a comparison key from each list element: - \samp{\var{key}=\function{str.lower}} - - \var{reverse} is a boolean value. If set to \code{True}, then the - list elements are sorted as if each comparison were reversed. - - In general, the \var{key} and \var{reverse} conversion processes are - much faster than specifying an equivalent \var{cmp} function. This is - because \var{cmp} is called multiple times for each list element while - \var{key} and \var{reverse} touch each element only once. - - \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{staticmethod}{function} - Return a static method for \var{function}. - - A static method does not receive an implicit first argument. - To declare a static method, use this idiom: - -\begin{verbatim} -class C: - @staticmethod - def f(arg1, arg2, ...): ... -\end{verbatim} - - The \code{@staticmethod} form is a function decorator -- see the description - of function definitions in chapter 7 of the - \citetitle[../ref/function.html]{Python Reference Manual} for details. - - It can be called either on the class (such as \code{C.f()}) or on an - instance (such as \code{C().f()}). The instance is ignored except - for its class. - - Static methods in Python are similar to those found in Java or \Cpp. - For a more advanced concept, see \function{classmethod()} in this - section. - - For more information on static methods, consult the documentation on the - standard type hierarchy in chapter 3 of the - \citetitle[../ref/types.html]{Python Reference Manual} (at the bottom). - \versionadded{2.2} - \versionchanged[Function decorator syntax added]{2.4} -\end{funcdesc} - -\begin{funcdesc}{str}{\optional{object\optional{, encoding - \optional{, errors}}}} - Return the Unicode string version of \var{object} using one of the - following modes: - - If \var{encoding} and/or \var{errors} are given, \code{unicode()} - will decode the object which can either be an 8-bit string or a - character buffer using the codec for \var{encoding}. The - \var{encoding} parameter is a string giving the name of an encoding; - if the encoding is not known, \exception{LookupError} is raised. - Error handling is done according to \var{errors}; this specifies the - treatment of characters which are invalid in the input encoding. If - \var{errors} is \code{'strict'} (the default), a - \exception{ValueError} is raised on errors, while a value of - \code{'ignore'} causes errors to be silently ignored, and a value of - \code{'replace'} causes the official Unicode replacement character, - \code{U+FFFD}, to be used to replace input characters which cannot - be decoded. See also the \refmodule{codecs} module. - - If no optional parameters are given, \code{unicode()} will mimic the - behaviour of \code{str()} except that it returns Unicode strings - instead of 8-bit strings. More precisely, if \var{object} is a - Unicode string or subclass it will return that Unicode string without - any additional decoding applied. - - For objects which provide a \method{__unicode__()} method, it will - call this method without arguments to create a Unicode string. For - all other objects, the 8-bit string version or representation is - requested and then converted to a Unicode string using the codec for - the default encoding in \code{'strict'} mode. - - \versionadded{2.0} - \versionchanged[Support for \method{__unicode__()} added]{2.2} -\end{funcdesc} - -\begin{funcdesc}{sum}{iterable\optional{, start}} - Sums \var{start} and the items of an \var{iterable} from left to - right and returns the total. \var{start} defaults to \code{0}. - The \var{iterable}'s items are normally numbers, and are not allowed - to be strings. The fast, correct way to concatenate a sequence of - strings is by calling \code{''.join(\var{sequence})}. - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{super}{type\optional{, object-or-type}} - Return the superclass of \var{type}. If the second argument is omitted - the super object returned is unbound. If the second argument is an - object, \code{isinstance(\var{obj}, \var{type})} must be true. If - the second argument is a type, \code{issubclass(\var{type2}, - \var{type})} must be true. - \function{super()} only works for new-style classes. - - A typical use for calling a cooperative superclass method is: -\begin{verbatim} -class C(B): - def meth(self, arg): - super(C, self).meth(arg) -\end{verbatim} - - Note that \function{super} is implemented as part of the binding process for - explicit dotted attribute lookups such as - \samp{super(C, self).__getitem__(name)}. Accordingly, \function{super} is - undefined for implicit lookups using statements or operators such as - \samp{super(C, self)[name]}. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{tuple}{\optional{iterable}} - Return a tuple whose items are the same and in the same order as - \var{iterable}'s items. \var{iterable} may be a sequence, a - container that supports iteration, or an iterator object. - If \var{iterable} is already a tuple, it - is returned unchanged. For instance, \code{tuple('abc')} returns - \code{('a', 'b', 'c')} and \code{tuple([1, 2, 3])} returns - \code{(1, 2, 3)}. If no argument is given, returns a new empty - tuple, \code{()}. -\end{funcdesc} - -\begin{funcdesc}{type}{object} - Return the type of an \var{object}. The return value is a - type\obindex{type} object. The \function{isinstance()} built-in - function is recommended for testing the type of an object. - - With three arguments, \function{type} functions as a constructor - as detailed below. -\end{funcdesc} - -\begin{funcdescni}{type}{name, bases, dict} - Return a new type object. This is essentially a dynamic form of the - \keyword{class} statement. The \var{name} string is the class name - and becomes the \member{__name__} attribute; the \var{bases} tuple - itemizes the base classes and becomes the \member{__bases__} - attribute; and the \var{dict} dictionary is the namespace containing - definitions for class body and becomes the \member{__dict__} - attribute. For example, the following two statements create - identical \class{type} objects: - -\begin{verbatim} - >>> class X(object): - ... a = 1 - ... - >>> X = type('X', (object,), dict(a=1)) -\end{verbatim} -\versionadded{2.2} -\end{funcdescni} - -\begin{funcdesc}{vars}{\optional{object}} - Without arguments, return a dictionary corresponding to the current - local symbol table. With a module, class or class instance object - as argument (or anything else that has a \member{__dict__} - attribute), returns a dictionary corresponding to the object's - symbol table. The returned dictionary should not be modified: the - effects on the corresponding symbol table are undefined.\footnote{ - In the current implementation, local variable bindings cannot - normally be affected this way, but variables retrieved from - other scopes (such as modules) can be. This may change.} -\end{funcdesc} - -\begin{funcdesc}{zip}{\optional{iterable, \moreargs}} - This function returns a list of tuples, where the \var{i}-th tuple contains - the \var{i}-th element from each of the argument sequences or iterables. - The returned list is truncated in length to the length of - the shortest argument sequence. When there are multiple arguments - which are all of the same length, \function{zip()} is - similar to \function{map()} with an initial argument of \code{None}. - With a single sequence argument, it returns a list of 1-tuples. - With no arguments, it returns an empty list. - \versionadded{2.0} - - \versionchanged[Formerly, \function{zip()} required at least one argument - and \code{zip()} raised a \exception{TypeError} instead of returning - an empty list]{2.4} -\end{funcdesc} - - -% --------------------------------------------------------------------------- - - -\section{Non-essential Built-in Functions \label{non-essential-built-in-funcs}} - -There are several built-in functions that are no longer essential to learn, -know or use in modern Python programming. They have been kept here to -maintain backwards compatibility with programs written for older versions -of Python. - -Python programmers, trainers, students and bookwriters should feel free to -bypass these functions without concerns about missing something important. - - -\setindexsubitem{(non-essential built-in functions)} - -\begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}} - The \var{object} argument must be an object that supports the buffer - call interface (such as strings, arrays, and buffers). A new buffer - object will be created which references the \var{object} argument. - The buffer object will be a slice from the beginning of \var{object} - (or from the specified \var{offset}). The slice will extend to the - end of \var{object} (or will have a length given by the \var{size} - argument). -\end{funcdesc} - diff --git a/Doc/lib/libfunctools.tex b/Doc/lib/libfunctools.tex deleted file mode 100644 index 654a5b1..0000000 --- a/Doc/lib/libfunctools.tex +++ /dev/null @@ -1,145 +0,0 @@ -\section{\module{functools} --- - Higher order functions and operations on callable objects.} - -\declaremodule{standard}{functools} % standard library, in Python - -\moduleauthor{Peter Harris}{scav@blueyonder.co.uk} -\moduleauthor{Raymond Hettinger}{python@rcn.com} -\moduleauthor{Nick Coghlan}{ncoghlan@gmail.com} -\sectionauthor{Peter Harris}{scav@blueyonder.co.uk} - -\modulesynopsis{Higher-order functions and operations on callable objects.} - -\versionadded{2.5} - -The \module{functools} module is for higher-order functions: functions -that act on or return other functions. In general, any callable object can -be treated as a function for the purposes of this module. - - -The \module{functools} module defines the following function: - -\begin{funcdesc}{partial}{func\optional{,*args}\optional{, **keywords}} -Return a new \class{partial} object which when called will behave like -\var{func} called with the positional arguments \var{args} and keyword -arguments \var{keywords}. If more arguments are supplied to the call, they -are appended to \var{args}. If additional keyword arguments are supplied, -they extend and override \var{keywords}. Roughly equivalent to: - \begin{verbatim} - def partial(func, *args, **keywords): - def newfunc(*fargs, **fkeywords): - newkeywords = keywords.copy() - newkeywords.update(fkeywords) - return func(*(args + fargs), **newkeywords) - newfunc.func = func - newfunc.args = args - newfunc.keywords = keywords - return newfunc - \end{verbatim} - -The \function{partial} is used for partial function application which -``freezes'' some portion of a function's arguments and/or keywords -resulting in a new object with a simplified signature. For example, -\function{partial} can be used to create a callable that behaves like -the \function{int} function where the \var{base} argument defaults to -two: - \begin{verbatim} - >>> basetwo = partial(int, base=2) - >>> basetwo.__doc__ = 'Convert base 2 string to an int.' - >>> basetwo('10010') - 18 - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{reduce}{function, sequence\optional{, initializer}} - Apply \var{function} of two arguments cumulatively to the items of - \var{sequence}, from left to right, so as to reduce the sequence to - a single value. For example, \code{reduce(lambda x, y: x+y, [1, 2, - 3, 4, 5])} calculates \code{((((1+2)+3)+4)+5)}. The left argument, - \var{x}, is the accumulated value and the right argument, \var{y}, - is the update value from the \var{sequence}. If the optional - \var{initializer} is present, it is placed before the items of the - sequence in the calculation, and serves as a default when the - sequence is empty. If \var{initializer} is not given and - \var{sequence} contains only one item, the first item is returned. -\end{funcdesc} - -\begin{funcdesc}{update_wrapper} -{wrapper, wrapped\optional{, assigned}\optional{, updated}} -Update a \var{wrapper} function to look like the \var{wrapped} function. -The optional arguments are tuples to specify which attributes of the original -function are assigned directly to the matching attributes on the wrapper -function and which attributes of the wrapper function are updated with -the corresponding attributes from the original function. The default -values for these arguments are the module level constants -\var{WRAPPER_ASSIGNMENTS} (which assigns to the wrapper function's -\var{__name__}, \var{__module__} and \var{__doc__}, the documentation string) -and \var{WRAPPER_UPDATES} (which updates the wrapper function's \var{__dict__}, -i.e. the instance dictionary). - -The main intended use for this function is in decorator functions -which wrap the decorated function and return the wrapper. If the -wrapper function is not updated, the metadata of the returned function -will reflect the wrapper definition rather than the original function -definition, which is typically less than helpful. -\end{funcdesc} - -\begin{funcdesc}{wraps} -{wrapped\optional{, assigned}\optional{, updated}} -This is a convenience function for invoking -\code{partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)} -as a function decorator when defining a wrapper function. For example: - \begin{verbatim} - >>> def my_decorator(f): - ... @wraps(f) - ... def wrapper(*args, **kwds): - ... print 'Calling decorated function' - ... return f(*args, **kwds) - ... return wrapper - ... - >>> @my_decorator - ... def example(): - ... """Docstring""" - ... print 'Called example function' - ... - >>> example() - Calling decorated function - Called example function - >>> example.__name__ - 'example' - >>> example.__doc__ - 'Docstring' - \end{verbatim} -Without the use of this decorator factory, the name of the example -function would have been \code{'wrapper'}, and the docstring of the -original \function{example()} would have been lost. -\end{funcdesc} - - -\subsection{\class{partial} Objects \label{partial-objects}} - - -\class{partial} objects are callable objects created by \function{partial()}. -They have three read-only attributes: - -\begin{memberdesc}[callable]{func}{} -A callable object or function. Calls to the \class{partial} object will -be forwarded to \member{func} with new arguments and keywords. -\end{memberdesc} - -\begin{memberdesc}[tuple]{args}{} -The leftmost positional arguments that will be prepended to the -positional arguments provided to a \class{partial} object call. -\end{memberdesc} - -\begin{memberdesc}[dict]{keywords}{} -The keyword arguments that will be supplied when the \class{partial} object -is called. -\end{memberdesc} - -\class{partial} objects are like \class{function} objects in that they are -callable, weak referencable, and can have attributes. There are some -important differences. For instance, the \member{__name__} and -\member{__doc__} attributes are not created automatically. Also, -\class{partial} objects defined in classes behave like static methods and -do not transform into bound methods during instance attribute look-up. diff --git a/Doc/lib/libfuture.tex b/Doc/lib/libfuture.tex deleted file mode 100644 index f1ba064..0000000 --- a/Doc/lib/libfuture.tex +++ /dev/null @@ -1,69 +0,0 @@ -\section{\module{__future__} --- - Future statement definitions} - -\declaremodule[future]{standard}{__future__} -\modulesynopsis{Future statement definitions} - -\module{__future__} is a real module, and serves three purposes: - -\begin{itemize} - -\item To avoid confusing existing tools that analyze import statements - and expect to find the modules they're importing. - -\item To ensure that future_statements run under releases prior to 2.1 - at least yield runtime exceptions (the import of - \module{__future__} will fail, because there was no module of - that name prior to 2.1). - -\item To document when incompatible changes were introduced, and when they - will be --- or were --- made mandatory. This is a form of executable - documentation, and can be inspected programatically via importing - \module{__future__} and examining its contents. - -\end{itemize} - -Each statement in \file{__future__.py} is of the form: - -\begin{alltt} -FeatureName = "_Feature(" \var{OptionalRelease} "," \var{MandatoryRelease} "," - \var{CompilerFlag} ")" -\end{alltt} - -where, normally, \var{OptionalRelease} is less than -\var{MandatoryRelease}, and both are 5-tuples of the same form as -\code{sys.version_info}: - -\begin{verbatim} - (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int - PY_MINOR_VERSION, # the 1; an int - PY_MICRO_VERSION, # the 0; an int - PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string - PY_RELEASE_SERIAL # the 3; an int - ) -\end{verbatim} - -\var{OptionalRelease} records the first release in which the feature -was accepted. - -In the case of a \var{MandatoryRelease} that has not yet occurred, -\var{MandatoryRelease} predicts the release in which the feature will -become part of the language. - -Else \var{MandatoryRelease} records when the feature became part of -the language; in releases at or after that, modules no longer need a -future statement to use the feature in question, but may continue to -use such imports. - -\var{MandatoryRelease} may also be \code{None}, meaning that a planned -feature got dropped. - -Instances of class \class{_Feature} have two corresponding methods, -\method{getOptionalRelease()} and \method{getMandatoryRelease()}. - -\var{CompilerFlag} is the (bitfield) flag that should be passed in the -fourth argument to the builtin function \function{compile()} to enable -the feature in dynamically compiled code. This flag is stored in the -\member{compiler_flag} attribute on \class{_Feature} instances. - -No feature description will ever be deleted from \module{__future__}. diff --git a/Doc/lib/libgc.tex b/Doc/lib/libgc.tex deleted file mode 100644 index 0d3408b..0000000 --- a/Doc/lib/libgc.tex +++ /dev/null @@ -1,196 +0,0 @@ -\section{\module{gc} --- - Garbage Collector interface} - -\declaremodule{extension}{gc} -\modulesynopsis{Interface to the cycle-detecting garbage collector.} -\moduleauthor{Neil Schemenauer}{nas@arctrix.com} -\sectionauthor{Neil Schemenauer}{nas@arctrix.com} - -This module provides an interface to the optional garbage collector. It -provides the ability to disable the collector, tune the collection -frequency, and set debugging options. It also provides access to -unreachable objects that the collector found but cannot free. Since the -collector supplements the reference counting already used in Python, you -can disable the collector if you are sure your program does not create -reference cycles. Automatic collection can be disabled by calling -\code{gc.disable()}. To debug a leaking program call -\code{gc.set_debug(gc.DEBUG_LEAK)}. Notice that this includes -\code{gc.DEBUG_SAVEALL}, causing garbage-collected objects to be -saved in gc.garbage for inspection. - -The \module{gc} module provides the following functions: - -\begin{funcdesc}{enable}{} -Enable automatic garbage collection. -\end{funcdesc} - -\begin{funcdesc}{disable}{} -Disable automatic garbage collection. -\end{funcdesc} - -\begin{funcdesc}{isenabled}{} -Returns true if automatic collection is enabled. -\end{funcdesc} - -\begin{funcdesc}{collect}{\optional{generation}} -With no arguments, run a full collection. The optional argument -\var{generation} may be an integer specifying which generation to collect -(from 0 to 2). A \exception{ValueError} is raised if the generation number -is invalid. -The number of unreachable objects found is returned. - -\versionchanged[The optional \var{generation} argument was added]{2.5} -\end{funcdesc} - -\begin{funcdesc}{set_debug}{flags} -Set the garbage collection debugging flags. -Debugging information will be written to \code{sys.stderr}. See below -for a list of debugging flags which can be combined using bit -operations to control debugging. -\end{funcdesc} - -\begin{funcdesc}{get_debug}{} -Return the debugging flags currently set. -\end{funcdesc} - -\begin{funcdesc}{get_objects}{} -Returns a list of all objects tracked by the collector, excluding the -list returned. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{set_threshold}{threshold0\optional{, - threshold1\optional{, threshold2}}} -Set the garbage collection thresholds (the collection frequency). -Setting \var{threshold0} to zero disables collection. - -The GC classifies objects into three generations depending on how many -collection sweeps they have survived. New objects are placed in the -youngest generation (generation \code{0}). If an object survives a -collection it is moved into the next older generation. Since -generation \code{2} is the oldest generation, objects in that -generation remain there after a collection. In order to decide when -to run, the collector keeps track of the number object allocations and -deallocations since the last collection. When the number of -allocations minus the number of deallocations exceeds -\var{threshold0}, collection starts. Initially only generation -\code{0} is examined. If generation \code{0} has been examined more -than \var{threshold1} times since generation \code{1} has been -examined, then generation \code{1} is examined as well. Similarly, -\var{threshold2} controls the number of collections of generation -\code{1} before collecting generation \code{2}. -\end{funcdesc} - -\begin{funcdesc}{get_count}{} -Return the current collection counts as a tuple of -\code{(\var{count0}, \var{count1}, \var{count2})}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{get_threshold}{} -Return the current collection thresholds as a tuple of -\code{(\var{threshold0}, \var{threshold1}, \var{threshold2})}. -\end{funcdesc} - -\begin{funcdesc}{get_referrers}{*objs} -Return the list of objects that directly refer to any of objs. This -function will only locate those containers which support garbage -collection; extension types which do refer to other objects but do not -support garbage collection will not be found. - -Note that objects which have already been dereferenced, but which live -in cycles and have not yet been collected by the garbage collector can -be listed among the resulting referrers. To get only currently live -objects, call \function{collect()} before calling -\function{get_referrers()}. - -Care must be taken when using objects returned by -\function{get_referrers()} because some of them could still be under -construction and hence in a temporarily invalid state. Avoid using -\function{get_referrers()} for any purpose other than debugging. - -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{get_referents}{*objs} -Return a list of objects directly referred to by any of the arguments. -The referents returned are those objects visited by the arguments' -C-level \member{tp_traverse} methods (if any), and may not be all -objects actually directly reachable. \member{tp_traverse} methods -are supported only by objects that support garbage collection, and are -only required to visit objects that may be involved in a cycle. So, -for example, if an integer is directly reachable from an argument, that -integer object may or may not appear in the result list. - -\versionadded{2.3} -\end{funcdesc} - -The following variable is provided for read-only access (you can -mutate its value but should not rebind it): - -\begin{datadesc}{garbage} -A list of objects which the collector found to be unreachable -but could not be freed (uncollectable objects). By default, this list -contains only objects with \method{__del__()} methods.\footnote{Prior to - Python 2.2, the list contained all instance objects in unreachable - cycles, not only those with \method{__del__()} methods.} -Objects that have -\method{__del__()} methods and are part of a reference cycle cause -the entire reference cycle to be uncollectable, including objects -not necessarily in the cycle but reachable only from it. Python doesn't -collect such cycles automatically because, in general, it isn't possible -for Python to guess a safe order in which to run the \method{__del__()} -methods. If you know a safe order, you can force the issue by examining -the \var{garbage} list, and explicitly breaking cycles due to your -objects within the list. Note that these objects are kept alive even -so by virtue of being in the \var{garbage} list, so they should be -removed from \var{garbage} too. For example, after breaking cycles, do -\code{del gc.garbage[:]} to empty the list. It's generally better -to avoid the issue by not creating cycles containing objects with -\method{__del__()} methods, and \var{garbage} can be examined in that -case to verify that no such cycles are being created. - -If \constant{DEBUG_SAVEALL} is set, then all unreachable objects will -be added to this list rather than freed. -\end{datadesc} - - -The following constants are provided for use with -\function{set_debug()}: - -\begin{datadesc}{DEBUG_STATS} -Print statistics during collection. This information can -be useful when tuning the collection frequency. -\end{datadesc} - -\begin{datadesc}{DEBUG_COLLECTABLE} -Print information on collectable objects found. -\end{datadesc} - -\begin{datadesc}{DEBUG_UNCOLLECTABLE} -Print information of uncollectable objects found (objects which are -not reachable but cannot be freed by the collector). These objects -will be added to the \code{garbage} list. -\end{datadesc} - -\begin{datadesc}{DEBUG_INSTANCES} -When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is -set, print information about instance objects found. -\end{datadesc} - -\begin{datadesc}{DEBUG_OBJECTS} -When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is -set, print information about objects other than instance objects found. -\end{datadesc} - -\begin{datadesc}{DEBUG_SAVEALL} -When set, all unreachable objects found will be appended to -\var{garbage} rather than being freed. This can be useful for debugging -a leaking program. -\end{datadesc} - -\begin{datadesc}{DEBUG_LEAK} -The debugging flags necessary for the collector to print -information about a leaking program (equal to \code{DEBUG_COLLECTABLE | -DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL}). -\end{datadesc} diff --git a/Doc/lib/libgdbm.tex b/Doc/lib/libgdbm.tex deleted file mode 100644 index 0c36677..0000000 --- a/Doc/lib/libgdbm.tex +++ /dev/null @@ -1,100 +0,0 @@ -\section{\module{gdbm} --- - GNU's reinterpretation of dbm} - -\declaremodule{builtin}{gdbm} - \platform{Unix} -\modulesynopsis{GNU's reinterpretation of dbm.} - - -This module is quite similar to the \refmodule{dbm}\refbimodindex{dbm} -module, but uses \code{gdbm} instead to provide some additional -functionality. Please note that the file formats created by -\code{gdbm} and \code{dbm} are incompatible. - -The \module{gdbm} module provides an interface to the GNU DBM -library. \code{gdbm} objects behave like mappings -(dictionaries), except that keys and values are always strings. -Printing a \code{gdbm} object doesn't print the keys and values, and -the \method{items()} and \method{values()} methods are not supported. - -The module defines the following constant and functions: - -\begin{excdesc}{error} -Raised on \code{gdbm}-specific errors, such as I/O errors. -\exception{KeyError} is raised for general mapping errors like -specifying an incorrect key. -\end{excdesc} - -\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}} -Open a \code{gdbm} database and return a \code{gdbm} object. The -\var{filename} argument is the name of the database file. - -The optional \var{flag} argument can be -\code{'r'} (to open an existing database for reading only --- default), -\code{'w'} (to open an existing database for reading and writing), -\code{'c'} (which creates the database if it doesn't exist), or -\code{'n'} (which always creates a new empty database). - -The following additional characters may be appended to the flag to -control how the database is opened: - -\begin{itemize} -\item \code{'f'} --- Open the database in fast mode. Writes to the database - will not be synchronized. -\item \code{'s'} --- Synchronized mode. This will cause changes to the database - will be immediately written to the file. -\item \code{'u'} --- Do not lock database. -\end{itemize} - -Not all flags are valid for all versions of \code{gdbm}. The -module constant \code{open_flags} is a string of supported flag -characters. The exception \exception{error} is raised if an invalid -flag is specified. - -The optional \var{mode} argument is the \UNIX{} mode of the file, used -only when the database has to be created. It defaults to octal -\code{0666}. -\end{funcdesc} - -In addition to the dictionary-like methods, \code{gdbm} objects have the -following methods: - -\begin{funcdesc}{firstkey}{} -It's possible to loop over every key in the database using this method -and the \method{nextkey()} method. The traversal is ordered by -\code{gdbm}'s internal hash values, and won't be sorted by the key -values. This method returns the starting key. -\end{funcdesc} - -\begin{funcdesc}{nextkey}{key} -Returns the key that follows \var{key} in the traversal. The -following code prints every key in the database \code{db}, without -having to create a list in memory that contains them all: - -\begin{verbatim} -k = db.firstkey() -while k != None: - print k - k = db.nextkey(k) -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{reorganize}{} -If you have carried out a lot of deletions and would like to shrink -the space used by the \code{gdbm} file, this routine will reorganize -the database. \code{gdbm} will not shorten the length of a database -file except by using this reorganization; otherwise, deleted file -space will be kept and reused as new (key, value) pairs are added. -\end{funcdesc} - -\begin{funcdesc}{sync}{} -When the database has been opened in fast mode, this method forces any -unwritten data to be written to the disk. -\end{funcdesc} - - -\begin{seealso} - \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.} - \seemodule{whichdb}{Utility module used to determine the type of an - existing database.} -\end{seealso} diff --git a/Doc/lib/libgetopt.tex b/Doc/lib/libgetopt.tex deleted file mode 100644 index 7930acd..0000000 --- a/Doc/lib/libgetopt.tex +++ /dev/null @@ -1,154 +0,0 @@ -\section{\module{getopt} --- - Parser for command line options} - -\declaremodule{standard}{getopt} -\modulesynopsis{Portable parser for command line options; support both - short and long option names.} - - -This module helps scripts to parse the command line arguments in -\code{sys.argv}. -It supports the same conventions as the \UNIX{} \cfunction{getopt()} -function (including the special meanings of arguments of the form -`\code{-}' and `\code{-}\code{-}'). -% That's to fool latex2html into leaving the two hyphens alone! -Long options similar to those supported by -GNU software may be used as well via an optional third argument. -This module provides a single function and an exception: - -\begin{funcdesc}{getopt}{args, options\optional{, long_options}} -Parses command line options and parameter list. \var{args} is the -argument list to be parsed, without the leading reference to the -running program. Typically, this means \samp{sys.argv[1:]}. -\var{options} is the string of option letters that the script wants to -recognize, with options that require an argument followed by a colon -(\character{:}; i.e., the same format that \UNIX{} -\cfunction{getopt()} uses). - -\note{Unlike GNU \cfunction{getopt()}, after a non-option -argument, all further arguments are considered also non-options. -This is similar to the way non-GNU \UNIX{} systems work.} - -\var{long_options}, if specified, must be a list of strings with the -names of the long options which should be supported. The leading -\code{'-}\code{-'} characters should not be included in the option -name. Long options which require an argument should be followed by an -equal sign (\character{=}). To accept only long options, -\var{options} should be an empty string. Long options on the command -line can be recognized so long as they provide a prefix of the option -name that matches exactly one of the accepted options. For example, -if \var{long_options} is \code{['foo', 'frob']}, the option -\longprogramopt{fo} will match as \longprogramopt{foo}, but -\longprogramopt{f} will not match uniquely, so \exception{GetoptError} -will be raised. - -The return value consists of two elements: the first is a list of -\code{(\var{option}, \var{value})} pairs; the second is the list of -program arguments left after the option list was stripped (this is a -trailing slice of \var{args}). Each option-and-value pair returned -has the option as its first 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. -\end{funcdesc} - -\begin{funcdesc}{gnu_getopt}{args, options\optional{, long_options}} -This function works like \function{getopt()}, except that GNU style -scanning mode is used by default. This means that option and -non-option arguments may be intermixed. The \function{getopt()} -function stops processing options as soon as a non-option argument is -encountered. - -If the first character of the option string is `+', or if the -environment variable POSIXLY_CORRECT is set, then option processing -stops as soon as a non-option argument is encountered. - -\versionadded{2.3} -\end{funcdesc} - -\begin{excdesc}{GetoptError} -This is raised when an unrecognized option is found in the argument -list or when an option requiring an argument is given none. -The argument to the exception is a string indicating the cause of the -error. For long options, an argument given to an option which does -not require one will also cause this exception to be raised. The -attributes \member{msg} and \member{opt} give the error message and -related option; if there is no specific option to which the exception -relates, \member{opt} is an empty string. - -\versionchanged[Introduced \exception{GetoptError} as a synonym for - \exception{error}]{1.6} -\end{excdesc} - -\begin{excdesc}{error} -Alias for \exception{GetoptError}; for backward compatibility. -\end{excdesc} - - -An example using only \UNIX{} style options: - -\begin{verbatim} ->>> import getopt ->>> args = '-a -b -cfoo -d bar a1 a2'.split() ->>> args -['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2'] ->>> optlist, args = getopt.getopt(args, 'abc:d:') ->>> optlist -[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')] ->>> args -['a1', 'a2'] -\end{verbatim} - -Using long option names is equally easy: - -\begin{verbatim} ->>> s = '--condition=foo --testing --output-file abc.def -x a1 a2' ->>> args = s.split() ->>> args -['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2'] ->>> optlist, args = getopt.getopt(args, 'x', [ -... 'condition=', 'output-file=', 'testing']) ->>> optlist -[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', - '')] ->>> args -['a1', 'a2'] -\end{verbatim} - -In a script, typical usage is something like this: - -\begin{verbatim} -import getopt, sys - -def main(): - try: - opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="]) - except getopt.GetoptError as err: - # print help information and exit: - print str(err) # will print something like "option -a not recognized" - usage() - sys.exit(2) - output = None - verbose = False - for o, a in opts: - if o == "-v": - verbose = True - elif o in ("-h", "--help"): - usage() - sys.exit() - elif o in ("-o", "--output"): - output = a - else: - assert False, "unhandled option" - # ... - -if __name__ == "__main__": - main() -\end{verbatim} - -\begin{seealso} - \seemodule{optparse}{More object-oriented command line option parsing.} -\end{seealso} diff --git a/Doc/lib/libgetpass.tex b/Doc/lib/libgetpass.tex deleted file mode 100644 index a742439..0000000 --- a/Doc/lib/libgetpass.tex +++ /dev/null @@ -1,36 +0,0 @@ -\section{\module{getpass} - --- Portable password input} - -\declaremodule{standard}{getpass} -\modulesynopsis{Portable reading of passwords and retrieval of the userid.} -\moduleauthor{Piers Lauder}{piers@cs.su.oz.au} -% Windows (& Mac?) support by Guido van Rossum. -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -The \module{getpass} module provides two functions: - - -\begin{funcdesc}{getpass}{\optional{prompt\optional{, stream}}} - Prompt the user for a password without echoing. The user is - prompted using the string \var{prompt}, which defaults to - \code{'Password: '}. On \UNIX, the prompt is written to the - file-like object \var{stream}, which defaults to - \code{sys.stdout} (this argument is ignored on Windows). - - Availability: Macintosh, \UNIX, Windows. - \versionchanged[The \var{stream} parameter was added]{2.5} -\end{funcdesc} - - -\begin{funcdesc}{getuser}{} - Return the ``login name'' of the user. - Availability: \UNIX, Windows. - - This function checks the environment variables \envvar{LOGNAME}, - \envvar{USER}, \envvar{LNAME} and \envvar{USERNAME}, in order, and - returns the value of the first one which is set to a non-empty - string. If none are set, the login name from the password database - is returned on systems which support the \refmodule{pwd} module, - otherwise, an exception is raised. -\end{funcdesc} diff --git a/Doc/lib/libgettext.tex b/Doc/lib/libgettext.tex deleted file mode 100644 index 6aee255..0000000 --- a/Doc/lib/libgettext.tex +++ /dev/null @@ -1,773 +0,0 @@ -\section{\module{gettext} --- - Multilingual internationalization services} - -\declaremodule{standard}{gettext} -\modulesynopsis{Multilingual internationalization services.} -\moduleauthor{Barry A. Warsaw}{barry@zope.com} -\sectionauthor{Barry A. Warsaw}{barry@zope.com} - - -The \module{gettext} module provides internationalization (I18N) and -localization (L10N) services for your Python modules and applications. -It supports both the GNU \code{gettext} message catalog API and a -higher level, class-based API that may be more appropriate for Python -files. The interface described below allows you to write your -module and application messages in one natural language, and provide a -catalog of translated messages for running under different natural -languages. - -Some hints on localizing your Python modules and applications are also -given. - -\subsection{GNU \program{gettext} API} - -The \module{gettext} module defines the following API, which is very -similar to the GNU \program{gettext} API. If you use this API you -will affect the translation of your entire application globally. Often -this is what you want if your application is monolingual, with the choice -of language dependent on the locale of your user. If you are -localizing a Python module, or if your application needs to switch -languages on the fly, you probably want to use the class-based API -instead. - -\begin{funcdesc}{bindtextdomain}{domain\optional{, localedir}} -Bind the \var{domain} to the locale directory -\var{localedir}. More concretely, \module{gettext} will look for -binary \file{.mo} files for the given domain using the path (on \UNIX): -\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo}, -where \var{languages} is searched for in the environment variables -\envvar{LANGUAGE}, \envvar{LC_ALL}, \envvar{LC_MESSAGES}, and -\envvar{LANG} respectively. - -If \var{localedir} is omitted or \code{None}, then the current binding -for \var{domain} is returned.\footnote{ - The default locale directory is system dependent; for example, - on RedHat Linux it is \file{/usr/share/locale}, but on Solaris - it is \file{/usr/lib/locale}. The \module{gettext} module - does not try to support these system dependent defaults; - instead its default is \file{\code{sys.prefix}/share/locale}. - For this reason, it is always best to call - \function{bindtextdomain()} with an explicit absolute path at - the start of your application.} -\end{funcdesc} - -\begin{funcdesc}{bind_textdomain_codeset}{domain\optional{, codeset}} -Bind the \var{domain} to \var{codeset}, changing the encoding of -strings returned by the \function{gettext()} family of functions. -If \var{codeset} is omitted, then the current binding is returned. - -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{textdomain}{\optional{domain}} -Change or query the current global domain. If \var{domain} is -\code{None}, then the current global domain is returned, otherwise the -global domain is set to \var{domain}, which is returned. -\end{funcdesc} - -\begin{funcdesc}{gettext}{message} -Return the localized translation of \var{message}, based on the -current global domain, language, and locale directory. This function -is usually aliased as \function{_} in the local namespace (see -examples below). -\end{funcdesc} - -\begin{funcdesc}{lgettext}{message} -Equivalent to \function{gettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \function{bind_textdomain_codeset()}. - -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{dgettext}{domain, message} -Like \function{gettext()}, but look the message up in the specified -\var{domain}. -\end{funcdesc} - -\begin{funcdesc}{ldgettext}{domain, message} -Equivalent to \function{dgettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \function{bind_textdomain_codeset()}. - -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{ngettext}{singular, plural, n} - -Like \function{gettext()}, but consider plural forms. If a translation -is found, apply the plural formula to \var{n}, and return the -resulting message (some languages have more than two plural forms). -If no translation is found, return \var{singular} if \var{n} is 1; -return \var{plural} otherwise. - -The Plural formula is taken from the catalog header. It is a C or -Python expression that has a free variable \var{n}; the expression evaluates -to the index of the plural in the catalog. See the GNU gettext -documentation for the precise syntax to be used in \file{.po} files and the -formulas for a variety of languages. - -\versionadded{2.3} - -\end{funcdesc} - -\begin{funcdesc}{lngettext}{singular, plural, n} -Equivalent to \function{ngettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \function{bind_textdomain_codeset()}. - -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{dngettext}{domain, singular, plural, n} -Like \function{ngettext()}, but look the message up in the specified -\var{domain}. - -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{ldngettext}{domain, singular, plural, n} -Equivalent to \function{dngettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \function{bind_textdomain_codeset()}. - -\versionadded{2.4} -\end{funcdesc} - - - -Note that GNU \program{gettext} also defines a \function{dcgettext()} -method, but this was deemed not useful and so it is currently -unimplemented. - -Here's an example of typical usage for this API: - -\begin{verbatim} -import gettext -gettext.bindtextdomain('myapplication', '/path/to/my/language/directory') -gettext.textdomain('myapplication') -_ = gettext.gettext -# ... -print _('This is a translatable string.') -\end{verbatim} - -\subsection{Class-based API} - -The class-based API of the \module{gettext} module gives you more -flexibility and greater convenience than the GNU \program{gettext} -API. It is the recommended way of localizing your Python applications and -modules. \module{gettext} defines a ``translations'' class which -implements the parsing of GNU \file{.mo} format files, and has methods -for returning either standard 8-bit strings or Unicode strings. -Instances of this ``translations'' class can also install themselves -in the built-in namespace as the function \function{_()}. - -\begin{funcdesc}{find}{domain\optional{, localedir\optional{, - languages\optional{, all}}}} -This function implements the standard \file{.mo} file search -algorithm. It takes a \var{domain}, identical to what -\function{textdomain()} takes. Optional \var{localedir} is as in -\function{bindtextdomain()} Optional \var{languages} is a list of -strings, where each string is a language code. - -If \var{localedir} is not given, then the default system locale -directory is used.\footnote{See the footnote for -\function{bindtextdomain()} above.} If \var{languages} is not given, -then the following environment variables are searched: \envvar{LANGUAGE}, -\envvar{LC_ALL}, \envvar{LC_MESSAGES}, and \envvar{LANG}. The first one -returning a non-empty value is used for the \var{languages} variable. -The environment variables should contain a colon separated list of -languages, which will be split on the colon to produce the expected -list of language code strings. - -\function{find()} then expands and normalizes the languages, and then -iterates through them, searching for an existing file built of these -components: - -\file{\var{localedir}/\var{language}/LC_MESSAGES/\var{domain}.mo} - -The first such file name that exists is returned by \function{find()}. -If no such file is found, then \code{None} is returned. If \var{all} -is given, it returns a list of all file names, in the order in which -they appear in the languages list or the environment variables. -\end{funcdesc} - -\begin{funcdesc}{translation}{domain\optional{, localedir\optional{, - languages\optional{, class_\optional{, - fallback\optional{, codeset}}}}}} -Return a \class{Translations} instance based on the \var{domain}, -\var{localedir}, and \var{languages}, which are first passed to -\function{find()} to get a list of the -associated \file{.mo} file paths. Instances with -identical \file{.mo} file names are cached. The actual class instantiated -is either \var{class_} if provided, otherwise -\class{GNUTranslations}. The class's constructor must take a single -file object argument. If provided, \var{codeset} will change the -charset used to encode translated strings. - -If multiple files are found, later files are used as fallbacks for -earlier ones. To allow setting the fallback, \function{copy.copy} -is used to clone each translation object from the cache; the actual -instance data is still shared with the cache. - -If no \file{.mo} file is found, this function raises -\exception{IOError} if \var{fallback} is false (which is the default), -and returns a \class{NullTranslations} instance if \var{fallback} is -true. - -\versionchanged[Added the \var{codeset} parameter]{2.4} -\end{funcdesc} - -\begin{funcdesc}{install}{domain\optional{, localedir\optional{, unicode - \optional{, codeset\optional{, names}}}}} -This installs the function \function{_} in Python's builtin namespace, -based on \var{domain}, \var{localedir}, and \var{codeset} which are -passed to the function \function{translation()}. The \var{unicode} -flag is passed to the resulting translation object's \method{install} -method. - -For the \var{names} parameter, please see the description of the -translation object's \method{install} method. - -As seen below, you usually mark the strings in your application that are -candidates for translation, by wrapping them in a call to the -\function{_()} function, like this: - -\begin{verbatim} -print _('This string will be translated.') -\end{verbatim} - -For convenience, you want the \function{_()} function to be installed in -Python's builtin namespace, so it is easily accessible in all modules -of your application. - -\versionchanged[Added the \var{codeset} parameter]{2.4} -\versionchanged[Added the \var{names} parameter]{2.5} -\end{funcdesc} - -\subsubsection{The \class{NullTranslations} class} -Translation classes are what actually implement the translation of -original source file message strings to translated message strings. -The base class used by all translation classes is -\class{NullTranslations}; this provides the basic interface you can use -to write your own specialized translation classes. Here are the -methods of \class{NullTranslations}: - -\begin{methoddesc}[NullTranslations]{__init__}{\optional{fp}} -Takes an optional file object \var{fp}, which is ignored by the base -class. Initializes ``protected'' instance variables \var{_info} and -\var{_charset} which are set by derived classes, as well as \var{_fallback}, -which is set through \method{add_fallback}. It then calls -\code{self._parse(fp)} if \var{fp} is not \code{None}. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{_parse}{fp} -No-op'd in the base class, this method takes file object \var{fp}, and -reads the data from the file, initializing its message catalog. If -you have an unsupported message catalog file format, you should -override this method to parse your format. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{add_fallback}{fallback} -Add \var{fallback} as the fallback object for the current translation -object. A translation object should consult the fallback if it cannot -provide a translation for a given message. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{gettext}{message} -If a fallback has been set, forward \method{gettext()} to the fallback. -Otherwise, return the translated message. Overridden in derived classes. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{lgettext}{message} -If a fallback has been set, forward \method{lgettext()} to the fallback. -Otherwise, return the translated message. Overridden in derived classes. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{ugettext}{message} -If a fallback has been set, forward \method{ugettext()} to the fallback. -Otherwise, return the translated message as a Unicode string. -Overridden in derived classes. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{ngettext}{singular, plural, n} -If a fallback has been set, forward \method{ngettext()} to the fallback. -Otherwise, return the translated message. Overridden in derived classes. - -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{lngettext}{singular, plural, n} -If a fallback has been set, forward \method{ngettext()} to the fallback. -Otherwise, return the translated message. Overridden in derived classes. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{ungettext}{singular, plural, n} -If a fallback has been set, forward \method{ungettext()} to the fallback. -Otherwise, return the translated message as a Unicode string. -Overridden in derived classes. - -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{info}{} -Return the ``protected'' \member{_info} variable. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{charset}{} -Return the ``protected'' \member{_charset} variable. -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{output_charset}{} -Return the ``protected'' \member{_output_charset} variable, which -defines the encoding used to return translated messages. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{set_output_charset}{charset} -Change the ``protected'' \member{_output_charset} variable, which -defines the encoding used to return translated messages. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NullTranslations]{install}{\optional{unicode - \optional{, names}}} -If the \var{unicode} flag is false, this method installs -\method{self.gettext()} into the built-in namespace, binding it to -\samp{_}. If \var{unicode} is true, it binds \method{self.ugettext()} -instead. By default, \var{unicode} is false. - -If the \var{names} parameter is given, it must be a sequence containing -the names of functions you want to install in the builtin namespace in -addition to \function{_()}. Supported names are \code{'gettext'} (bound -to \method{self.gettext()} or \method{self.ugettext()} according to the -\var{unicode} flag), \code{'ngettext'} (bound to \method{self.ngettext()} -or \method{self.ungettext()} according to the \var{unicode} flag), -\code{'lgettext'} and \code{'lngettext'}. - -Note that this is only one way, albeit the most convenient way, to -make the \function{_} function available to your application. Because it -affects the entire application globally, and specifically the built-in -namespace, localized modules should never install \function{_}. -Instead, they should use this code to make \function{_} available to -their module: - -\begin{verbatim} -import gettext -t = gettext.translation('mymodule', ...) -_ = t.gettext -\end{verbatim} - -This puts \function{_} only in the module's global namespace and so -only affects calls within this module. - -\versionchanged[Added the \var{names} parameter]{2.5} -\end{methoddesc} - -\subsubsection{The \class{GNUTranslations} class} - -The \module{gettext} module provides one additional class derived from -\class{NullTranslations}: \class{GNUTranslations}. This class -overrides \method{_parse()} to enable reading GNU \program{gettext} -format \file{.mo} files in both big-endian and little-endian format. -It also coerces both message ids and message strings to Unicode. - -\class{GNUTranslations} parses optional meta-data out of the -translation catalog. It is convention with GNU \program{gettext} to -include meta-data as the translation for the empty string. This -meta-data is in \rfc{822}-style \code{key: value} pairs, and should -contain the \code{Project-Id-Version} key. If the key -\code{Content-Type} is found, then the \code{charset} property is used -to initialize the ``protected'' \member{_charset} instance variable, -defaulting to \code{None} if not found. If the charset encoding is -specified, then all message ids and message strings read from the -catalog are converted to Unicode using this encoding. The -\method{ugettext()} method always returns a Unicode, while the -\method{gettext()} returns an encoded 8-bit string. For the message -id arguments of both methods, either Unicode strings or 8-bit strings -containing only US-ASCII characters are acceptable. Note that the -Unicode version of the methods (i.e. \method{ugettext()} and -\method{ungettext()}) are the recommended interface to use for -internationalized Python programs. - -The entire set of key/value pairs are placed into a dictionary and set -as the ``protected'' \member{_info} instance variable. - -If the \file{.mo} file's magic number is invalid, or if other problems -occur while reading the file, instantiating a \class{GNUTranslations} class -can raise \exception{IOError}. - -The following methods are overridden from the base class implementation: - -\begin{methoddesc}[GNUTranslations]{gettext}{message} -Look up the \var{message} id in the catalog and return the -corresponding message string, as an 8-bit string encoded with the -catalog's charset encoding, if known. If there is no entry in the -catalog for the \var{message} id, and a fallback has been set, the -look up is forwarded to the fallback's \method{gettext()} method. -Otherwise, the \var{message} id is returned. -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{lgettext}{message} -Equivalent to \method{gettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \method{set_output_charset()}. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{ugettext}{message} -Look up the \var{message} id in the catalog and return the -corresponding message string, as a Unicode string. If there is no -entry in the catalog for the \var{message} id, and a fallback has been -set, the look up is forwarded to the fallback's \method{ugettext()} -method. Otherwise, the \var{message} id is returned. -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{ngettext}{singular, plural, n} -Do a plural-forms lookup of a message id. \var{singular} is used as -the message id for purposes of lookup in the catalog, while \var{n} is -used to determine which plural form to use. The returned message -string is an 8-bit string encoded with the catalog's charset encoding, -if known. - -If the message id is not found in the catalog, and a fallback is -specified, the request is forwarded to the fallback's -\method{ngettext()} method. Otherwise, when \var{n} is 1 \var{singular} is -returned, and \var{plural} is returned in all other cases. - -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{lngettext}{singular, plural, n} -Equivalent to \method{gettext()}, but the translation is returned -in the preferred system encoding, if no other encoding was explicitly -set with \method{set_output_charset()}. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[GNUTranslations]{ungettext}{singular, plural, n} -Do a plural-forms lookup of a message id. \var{singular} is used as -the message id for purposes of lookup in the catalog, while \var{n} is -used to determine which plural form to use. The returned message -string is a Unicode string. - -If the message id is not found in the catalog, and a fallback is -specified, the request is forwarded to the fallback's -\method{ungettext()} method. Otherwise, when \var{n} is 1 \var{singular} is -returned, and \var{plural} is returned in all other cases. - -Here is an example: - -\begin{verbatim} -n = len(os.listdir('.')) -cat = GNUTranslations(somefile) -message = cat.ungettext( - 'There is %(num)d file in this directory', - 'There are %(num)d files in this directory', - n) % {'num': n} -\end{verbatim} - -\versionadded{2.3} -\end{methoddesc} - -\subsubsection{Solaris message catalog support} - -The Solaris operating system defines its own binary -\file{.mo} file format, but since no documentation can be found on -this format, it is not supported at this time. - -\subsubsection{The Catalog constructor} - -GNOME\index{GNOME} uses a version of the \module{gettext} module by -James Henstridge, but this version has a slightly different API. Its -documented usage was: - -\begin{verbatim} -import gettext -cat = gettext.Catalog(domain, localedir) -_ = cat.gettext -print _('hello world') -\end{verbatim} - -For compatibility with this older module, the function -\function{Catalog()} is an alias for the \function{translation()} -function described above. - -One difference between this module and Henstridge's: his catalog -objects supported access through a mapping API, but this appears to be -unused and so is not currently supported. - -\subsection{Internationalizing your programs and modules} -Internationalization (I18N) refers to the operation by which a program -is made aware of multiple languages. Localization (L10N) refers to -the adaptation of your program, once internationalized, to the local -language and cultural habits. In order to provide multilingual -messages for your Python programs, you need to take the following -steps: - -\begin{enumerate} - \item prepare your program or module by specially marking - translatable strings - \item run a suite of tools over your marked files to generate raw - messages catalogs - \item create language specific translations of the message catalogs - \item use the \module{gettext} module so that message strings are - properly translated -\end{enumerate} - -In order to prepare your code for I18N, you need to look at all the -strings in your files. Any string that needs to be translated -should be marked by wrapping it in \code{_('...')} --- that is, a call -to the function \function{_()}. For example: - -\begin{verbatim} -filename = 'mylog.txt' -message = _('writing a log message') -fp = open(filename, 'w') -fp.write(message) -fp.close() -\end{verbatim} - -In this example, the string \code{'writing a log message'} is marked as -a candidate for translation, while the strings \code{'mylog.txt'} and -\code{'w'} are not. - -The Python distribution comes with two tools which help you generate -the message catalogs once you've prepared your source code. These may -or may not be available from a binary distribution, but they can be -found in a source distribution, in the \file{Tools/i18n} directory. - -The \program{pygettext}\footnote{Fran\c cois Pinard has -written a program called -\program{xpot} which does a similar job. It is available as part of -his \program{po-utils} package at -\url{http://po-utils.progiciels-bpi.ca/}.} program -scans all your Python source code looking for the strings you -previously marked as translatable. It is similar to the GNU -\program{gettext} program except that it understands all the -intricacies of Python source code, but knows nothing about C or \Cpp -source code. You don't need GNU \code{gettext} unless you're also -going to be translating C code (such as C extension modules). - -\program{pygettext} generates textual Uniforum-style human readable -message catalog \file{.pot} files, essentially structured human -readable files which contain every marked string in the source code, -along with a placeholder for the translation strings. -\program{pygettext} is a command line script that supports a similar -command line interface as \program{xgettext}; for details on its use, -run: - -\begin{verbatim} -pygettext.py --help -\end{verbatim} - -Copies of these \file{.pot} files are then handed over to the -individual human translators who write language-specific versions for -every supported natural language. They send you back the filled in -language-specific versions as a \file{.po} file. Using the -\program{msgfmt.py}\footnote{\program{msgfmt.py} is binary -compatible with GNU \program{msgfmt} except that it provides a -simpler, all-Python implementation. With this and -\program{pygettext.py}, you generally won't need to install the GNU -\program{gettext} package to internationalize your Python -applications.} program (in the \file{Tools/i18n} directory), you take the -\file{.po} files from your translators and generate the -machine-readable \file{.mo} binary catalog files. The \file{.mo} -files are what the \module{gettext} module uses for the actual -translation processing during run-time. - -How you use the \module{gettext} module in your code depends on -whether you are internationalizing a single module or your entire application. -The next two sections will discuss each case. - -\subsubsection{Localizing your module} - -If you are localizing your module, you must take care not to make -global changes, e.g. to the built-in namespace. You should not use -the GNU \code{gettext} API but instead the class-based API. - -Let's say your module is called ``spam'' and the module's various -natural language translation \file{.mo} files reside in -\file{/usr/share/locale} in GNU \program{gettext} format. Here's what -you would put at the top of your module: - -\begin{verbatim} -import gettext -t = gettext.translation('spam', '/usr/share/locale') -_ = t.lgettext -\end{verbatim} - -If your translators were providing you with Unicode strings in their -\file{.po} files, you'd instead do: - -\begin{verbatim} -import gettext -t = gettext.translation('spam', '/usr/share/locale') -_ = t.ugettext -\end{verbatim} - -\subsubsection{Localizing your application} - -If you are localizing your application, you can install the \function{_()} -function globally into the built-in namespace, usually in the main driver file -of your application. This will let all your application-specific -files just use \code{_('...')} without having to explicitly install it in -each file. - -In the simple case then, you need only add the following bit of code -to the main driver file of your application: - -\begin{verbatim} -import gettext -gettext.install('myapplication') -\end{verbatim} - -If you need to set the locale directory or the \var{unicode} flag, -you can pass these into the \function{install()} function: - -\begin{verbatim} -import gettext -gettext.install('myapplication', '/usr/share/locale', unicode=1) -\end{verbatim} - -\subsubsection{Changing languages on the fly} - -If your program needs to support many languages at the same time, you -may want to create multiple translation instances and then switch -between them explicitly, like so: - -\begin{verbatim} -import gettext - -lang1 = gettext.translation('myapplication', languages=['en']) -lang2 = gettext.translation('myapplication', languages=['fr']) -lang3 = gettext.translation('myapplication', languages=['de']) - -# start by using language1 -lang1.install() - -# ... time goes by, user selects language 2 -lang2.install() - -# ... more time goes by, user selects language 3 -lang3.install() -\end{verbatim} - -\subsubsection{Deferred translations} - -In most coding situations, strings are translated where they are coded. -Occasionally however, you need to mark strings for translation, but -defer actual translation until later. A classic example is: - -\begin{verbatim} -animals = ['mollusk', - 'albatross', - 'rat', - 'penguin', - 'python', - ] -# ... -for a in animals: - print a -\end{verbatim} - -Here, you want to mark the strings in the \code{animals} list as being -translatable, but you don't actually want to translate them until they -are printed. - -Here is one way you can handle this situation: - -\begin{verbatim} -def _(message): return message - -animals = [_('mollusk'), - _('albatross'), - _('rat'), - _('penguin'), - _('python'), - ] - -del _ - -# ... -for a in animals: - print _(a) -\end{verbatim} - -This works because the dummy definition of \function{_()} simply returns -the string unchanged. And this dummy definition will temporarily -override any definition of \function{_()} in the built-in namespace -(until the \keyword{del} command). -Take care, though if you have a previous definition of \function{_} in -the local namespace. - -Note that the second use of \function{_()} will not identify ``a'' as -being translatable to the \program{pygettext} program, since it is not -a string. - -Another way to handle this is with the following example: - -\begin{verbatim} -def N_(message): return message - -animals = [N_('mollusk'), - N_('albatross'), - N_('rat'), - N_('penguin'), - N_('python'), - ] - -# ... -for a in animals: - print _(a) -\end{verbatim} - -In this case, you are marking translatable strings with the function -\function{N_()},\footnote{The choice of \function{N_()} here is totally -arbitrary; it could have just as easily been -\function{MarkThisStringForTranslation()}. -} which won't conflict with any definition of -\function{_()}. However, you will need to teach your message extraction -program to look for translatable strings marked with \function{N_()}. -\program{pygettext} and \program{xpot} both support this through the -use of command line switches. - -\subsubsection{\function{gettext()} vs. \function{lgettext()}} -In Python 2.4 the \function{lgettext()} family of functions were -introduced. The intention of these functions is to provide an -alternative which is more compliant with the current -implementation of GNU gettext. Unlike \function{gettext()}, which -returns strings encoded with the same codeset used in the -translation file, \function{lgettext()} will return strings -encoded with the preferred system encoding, as returned by -\function{locale.getpreferredencoding()}. Also notice that -Python 2.4 introduces new functions to explicitly choose -the codeset used in translated strings. If a codeset is explicitly -set, even \function{lgettext()} will return translated strings in -the requested codeset, as would be expected in the GNU gettext -implementation. - -\subsection{Acknowledgements} - -The following people contributed code, feedback, design suggestions, -previous implementations, and valuable experience to the creation of -this module: - -\begin{itemize} - \item Peter Funk - \item James Henstridge - \item Juan David Ib\'a\~nez Palomar - \item Marc-Andr\'e Lemburg - \item Martin von L\"owis - \item Fran\c cois Pinard - \item Barry Warsaw - \item Gustavo Niemeyer -\end{itemize} diff --git a/Doc/lib/libglob.tex b/Doc/lib/libglob.tex deleted file mode 100644 index f3f4fb7..0000000 --- a/Doc/lib/libglob.tex +++ /dev/null @@ -1,51 +0,0 @@ -\section{\module{glob} --- - \UNIX{} style pathname pattern expansion} - -\declaremodule{standard}{glob} -\modulesynopsis{\UNIX\ shell style pathname pattern expansion.} - - -The \module{glob} module finds all the pathnames matching a specified -pattern according to the rules used by the \UNIX{} shell. No tilde -expansion is done, but \code{*}, \code{?}, and character ranges -expressed with \code{[]} will be correctly matched. This is done by -using the \function{os.listdir()} and \function{fnmatch.fnmatch()} -functions in concert, and not by actually invoking a subshell. (For -tilde and shell variable expansion, use \function{os.path.expanduser()} -and \function{os.path.expandvars()}.) -\index{filenames!pathname expansion} - -\begin{funcdesc}{glob}{pathname} -Return a possibly-empty list of path names that match \var{pathname}, -which must be a string containing a path specification. -\var{pathname} can be either absolute (like -\file{/usr/src/Python-1.5/Makefile}) or relative (like -\file{../../Tools/*/*.gif}), and can contain shell-style wildcards. -Broken symlinks are included in the results (as in the shell). -\end{funcdesc} - -\begin{funcdesc}{iglob}{pathname} -Return an iterator which yields the same values as \function{glob()} -without actually storing them all simultaneously. -\versionadded{2.5} -\end{funcdesc} - -For example, consider a directory containing only the following files: -\file{1.gif}, \file{2.txt}, and \file{card.gif}. \function{glob()} -will produce the following results. Notice how any leading components -of the path are preserved. - -\begin{verbatim} ->>> import glob ->>> glob.glob('./[0-9].*') -['./1.gif', './2.txt'] ->>> glob.glob('*.gif') -['1.gif', 'card.gif'] ->>> glob.glob('?.gif') -['1.gif'] -\end{verbatim} - - -\begin{seealso} - \seemodule{fnmatch}{Shell-style filename (not path) expansion} -\end{seealso} diff --git a/Doc/lib/libgrp.tex b/Doc/lib/libgrp.tex deleted file mode 100644 index 3eed7d0..0000000 --- a/Doc/lib/libgrp.tex +++ /dev/null @@ -1,49 +0,0 @@ -\section{\module{grp} --- - The group database} - -\declaremodule{builtin}{grp} - \platform{Unix} -\modulesynopsis{The group database (\function{getgrnam()} and friends).} - - -This module provides access to the \UNIX{} group database. -It is available on all \UNIX{} versions. - -Group database entries are reported as a tuple-like object, whose -attributes correspond to the members of the \code{group} structure -(Attribute field below, see \code{<pwd.h>}): - -\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{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 -group they are in according to the password database. Check both -databases to get complete membership information.) - -It defines the following items: - -\begin{funcdesc}{getgrgid}{gid} -Return the group database entry for the given numeric group ID. -\exception{KeyError} is raised if the entry asked for cannot be found. -\end{funcdesc} - -\begin{funcdesc}{getgrnam}{name} -Return the group database entry for the given group name. -\exception{KeyError} is raised if the entry asked for cannot be found. -\end{funcdesc} - -\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.} - \seemodule{spwd}{An interface to the shadow password database, similar to this.} -\end{seealso} diff --git a/Doc/lib/libgzip.tex b/Doc/lib/libgzip.tex deleted file mode 100644 index b4cc659..0000000 --- a/Doc/lib/libgzip.tex +++ /dev/null @@ -1,70 +0,0 @@ -\section{\module{gzip} --- - Support for \program{gzip} files} - -\declaremodule{standard}{gzip} -\modulesynopsis{Interfaces for \program{gzip} compression and -decompression using file objects.} - - -The data compression provided by the \code{zlib} module is compatible -with that used by the GNU compression program \program{gzip}. -Accordingly, the \module{gzip} module provides the \class{GzipFile} -class to read and write \program{gzip}-format files, automatically -compressing or decompressing the data so it looks like an ordinary -file object. Note that additional file formats which can be -decompressed by the \program{gzip} and \program{gunzip} programs, such -as those produced by \program{compress} and \program{pack}, are not -supported by this module. - -The module defines the following items: - -\begin{classdesc}{GzipFile}{\optional{filename\optional{, mode\optional{, - compresslevel\optional{, fileobj}}}}} -Constructor for the \class{GzipFile} class, which simulates most of -the methods of a file object, with the exception of the \method{readinto()} -and \method{truncate()} methods. At least one of -\var{fileobj} and \var{filename} must be given a non-trivial value. - -The new class instance is based on \var{fileobj}, which can be a -regular file, a \class{StringIO} object, or any other object which -simulates a file. It defaults to \code{None}, in which case -\var{filename} is opened to provide a file object. - -When \var{fileobj} is not \code{None}, the \var{filename} argument is -only used to be included in the \program{gzip} file header, which may -includes the original filename of the uncompressed file. It defaults -to the filename of \var{fileobj}, if discernible; otherwise, it -defaults to the empty string, and in this case the original filename -is not included in the header. - -The \var{mode} argument can be any of \code{'r'}, \code{'rb'}, -\code{'a'}, \code{'ab'}, \code{'w'}, or \code{'wb'}, depending on -whether the file will be read or written. The default is the mode of -\var{fileobj} if discernible; otherwise, the default is \code{'rb'}. -If not given, the 'b' flag will be added to the mode to ensure the -file is opened in binary mode for cross-platform portability. - -The \var{compresslevel} argument is an integer from \code{1} to -\code{9} controlling the level of compression; \code{1} is fastest and -produces the least compression, and \code{9} is slowest and produces -the most compression. The default is \code{9}. - -Calling a \class{GzipFile} object's \method{close()} method does not -close \var{fileobj}, since you might wish to append more material -after the compressed data. This also allows you to pass a -\class{StringIO} object opened for writing as \var{fileobj}, and -retrieve the resulting memory buffer using the \class{StringIO} -object's \method{getvalue()} method. -\end{classdesc} - -\begin{funcdesc}{open}{filename\optional{, mode\optional{, compresslevel}}} -This is a shorthand for \code{GzipFile(\var{filename},} -\code{\var{mode},} \code{\var{compresslevel})}. The \var{filename} -argument is required; \var{mode} defaults to \code{'rb'} and -\var{compresslevel} defaults to \code{9}. -\end{funcdesc} - -\begin{seealso} - \seemodule{zlib}{The basic data compression module needed to support - the \program{gzip} file format.} -\end{seealso} diff --git a/Doc/lib/libhashlib.tex b/Doc/lib/libhashlib.tex deleted file mode 100644 index 17f5179..0000000 --- a/Doc/lib/libhashlib.tex +++ /dev/null @@ -1,114 +0,0 @@ -\section{\module{hashlib} --- - Secure hashes and message digests} - -\declaremodule{builtin}{hashlib} -\modulesynopsis{Secure hash and message digest algorithms.} -\moduleauthor{Gregory P. Smith}{greg@users.sourceforge.net} -\sectionauthor{Gregory P. Smith}{greg@users.sourceforge.net} - -\versionadded{2.5} - -\index{message digest, MD5} -\index{secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512} - -This module implements a common interface to many different secure hash and -message digest algorithms. Included are the FIPS secure hash algorithms SHA1, -SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5 -algorithm (defined in Internet \rfc{1321}). -The terms secure hash and message digest are interchangeable. Older -algorithms were called message digests. The modern term is secure hash. - -\warning{Some algorithms have known hash collision weaknesses, see the FAQ at the end.} - -There is one constructor method named for each type of \dfn{hash}. All return -a hash object with the same simple interface. -For example: use \function{sha1()} to create a SHA1 hash object. -You can now feed this object with arbitrary strings using the \method{update()} -method. At any point you can ask it for the \dfn{digest} of the concatenation -of the strings fed to it so far using the \method{digest()} or -\method{hexdigest()} methods. - -Constructors for hash algorithms that are always present in this module are -\function{md5()}, \function{sha1()}, \function{sha224()}, \function{sha256()}, -\function{sha384()}, and \function{sha512()}. Additional algorithms may also -be available depending upon the OpenSSL library that Python uses on your platform. -\index{OpenSSL} - -For example, to obtain the digest of the string \code{'Nobody inspects -the spammish repetition'}: - -\begin{verbatim} ->>> import hashlib ->>> m = hashlib.md5() ->>> m.update("Nobody inspects") ->>> m.update(" the spammish repetition") ->>> m.digest() -'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9' -\end{verbatim} - -More condensed: - -\begin{verbatim} ->>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest() -'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2' -\end{verbatim} - -A generic \function{new()} constructor that takes the string name of the -desired algorithm as its first parameter also exists to allow access to the -above listed hashes as well as any other algorithms that your OpenSSL library -may offer. The named constructors are much faster than \function{new()} and -should be preferred. - -Using \function{new()} with an algorithm provided by OpenSSL: - -\begin{verbatim} ->>> h = hashlib.new('ripemd160') ->>> h.update("Nobody inspects the spammish repetition") ->>> h.hexdigest() -'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc' -\end{verbatim} - -The following values are provided as constant attributes of the hash objects -returned by the constructors: - -\begin{datadesc}{digest_size} - The size of the resulting digest in bytes. -\end{datadesc} - -A hash object has the following methods: - -\begin{methoddesc}[hash]{update}{arg} -Update the hash object with the string \var{arg}. Repeated calls are -equivalent to a single call with the concatenation of all the -arguments: \code{m.update(a); m.update(b)} is equivalent to -\code{m.update(a+b)}. -\end{methoddesc} - -\begin{methoddesc}[hash]{digest}{} -Return the digest of the strings passed to the \method{update()} -method so far. This is a string of \member{digest_size} bytes which may -contain non-\ASCII{} characters, including null bytes. -\end{methoddesc} - -\begin{methoddesc}[hash]{hexdigest}{} -Like \method{digest()} except the digest is returned as a string of -double length, containing only hexadecimal digits. This may -be used to exchange the value safely in email or other non-binary -environments. -\end{methoddesc} - -\begin{methoddesc}[hash]{copy}{} -Return a copy (``clone'') of the hash object. This can be used to -efficiently compute the digests of strings that share a common initial -substring. -\end{methoddesc} - -\begin{seealso} - \seemodule{hmac}{A module to generate message authentication codes using hashes.} - \seemodule{base64}{Another way to encode binary hashes for non-binary environments.} - \seeurl{http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf} - {The FIPS 180-2 publication on Secure Hash Algorithms.} - \seeurl{http://www.cryptography.com/cnews/hash.html} - {Hash Collision FAQ with information on which algorithms have known issues and - what that means regarding their use.} -\end{seealso} diff --git a/Doc/lib/libheapq.tex b/Doc/lib/libheapq.tex deleted file mode 100644 index e403a3a..0000000 --- a/Doc/lib/libheapq.tex +++ /dev/null @@ -1,225 +0,0 @@ -\section{\module{heapq} --- - Heap queue algorithm} - -\declaremodule{standard}{heapq} -\modulesynopsis{Heap queue algorithm (a.k.a. priority queue).} -\moduleauthor{Kevin O'Connor}{} -\sectionauthor{Guido van Rossum}{guido@python.org} -% Theoretical explanation: -\sectionauthor{Fran\c cois Pinard}{} -\versionadded{2.3} - - -This module provides an implementation of the heap queue algorithm, -also known as the priority queue algorithm. - -Heaps are arrays for which -\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+1]} and -\code{\var{heap}[\var{k}] <= \var{heap}[2*\var{k}+2]} -for all \var{k}, counting elements from zero. For the sake of -comparison, non-existing elements are considered to be infinite. The -interesting property of a heap is that \code{\var{heap}[0]} is always -its smallest element. - -The API below differs from textbook heap algorithms in two aspects: -(a) We use zero-based indexing. This makes the relationship between the -index for a node and the indexes for its children slightly less -obvious, but is more suitable since Python uses zero-based indexing. -(b) Our pop method returns the smallest item, not the largest (called a -"min heap" in textbooks; a "max heap" is more common in texts because -of its suitability for in-place sorting). - -These two make it possible to view the heap as a regular Python list -without surprises: \code{\var{heap}[0]} is the smallest item, and -\code{\var{heap}.sort()} maintains the heap invariant! - -To create a heap, use a list initialized to \code{[]}, or you can -transform a populated list into a heap via function \function{heapify()}. - -The following functions are provided: - -\begin{funcdesc}{heappush}{heap, item} -Push the value \var{item} onto the \var{heap}, maintaining the -heap invariant. -\end{funcdesc} - -\begin{funcdesc}{heappop}{heap} -Pop and return the smallest item from the \var{heap}, maintaining the -heap invariant. If the heap is empty, \exception{IndexError} is raised. -\end{funcdesc} - -\begin{funcdesc}{heapify}{x} -Transform list \var{x} into a heap, in-place, in linear time. -\end{funcdesc} - -\begin{funcdesc}{heapreplace}{heap, item} -Pop and return the smallest item from the \var{heap}, and also push -the new \var{item}. The heap size doesn't change. -If the heap is empty, \exception{IndexError} is raised. -This is more efficient than \function{heappop()} followed -by \function{heappush()}, and can be more appropriate when using -a fixed-size heap. Note that the value returned may be larger -than \var{item}! That constrains reasonable uses of this routine -unless written as part of a conditional replacement: -\begin{verbatim} - if item > heap[0]: - item = heapreplace(heap, item) -\end{verbatim} -\end{funcdesc} - -Example of use: - -\begin{verbatim} ->>> from heapq import heappush, heappop ->>> heap = [] ->>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0] ->>> for item in data: -... heappush(heap, item) -... ->>> ordered = [] ->>> while heap: -... ordered.append(heappop(heap)) -... ->>> print ordered -[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] ->>> data.sort() ->>> print data == ordered -True ->>> -\end{verbatim} - -The module also offers three general purpose functions based on heaps. - -\begin{funcdesc}{merge}{*iterables} -Merge multiple sorted inputs into a single sorted output (for example, merge -timestamped entries from multiple log files). Returns an iterator over -over the sorted values. - -Similar to \code{sorted(itertools.chain(*iterables))} but returns an iterable, -does not pull the data into memory all at once, and assumes that each of the -input streams is already sorted (smallest to largest). -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{nlargest}{n, iterable\optional{, key}} -Return a list with the \var{n} largest elements from the dataset defined -by \var{iterable}. \var{key}, if provided, specifies a function of one -argument that is used to extract a comparison key from each element -in the iterable: \samp{\var{key}=\function{str.lower}} -Equivalent to: \samp{sorted(iterable, key=key, reverse=True)[:n]} -\versionadded{2.4} -\versionchanged[Added the optional \var{key} argument]{2.5} -\end{funcdesc} - -\begin{funcdesc}{nsmallest}{n, iterable\optional{, key}} -Return a list with the \var{n} smallest elements from the dataset defined -by \var{iterable}. \var{key}, if provided, specifies a function of one -argument that is used to extract a comparison key from each element -in the iterable: \samp{\var{key}=\function{str.lower}} -Equivalent to: \samp{sorted(iterable, key=key)[:n]} -\versionadded{2.4} -\versionchanged[Added the optional \var{key} argument]{2.5} -\end{funcdesc} - -The latter two functions perform best for smaller values of \var{n}. For larger -values, it is more efficient to use the \function{sorted()} function. Also, -when \code{n==1}, it is more efficient to use the builtin \function{min()} -and \function{max()} functions. - - -\subsection{Theory} - -(This explanation is due to François Pinard. The Python -code for this module was contributed by Kevin O'Connor.) - -Heaps are arrays for which \code{a[\var{k}] <= a[2*\var{k}+1]} and -\code{a[\var{k}] <= a[2*\var{k}+2]} -for all \var{k}, counting elements from 0. For the sake of comparison, -non-existing elements are considered to be infinite. The interesting -property of a heap is that \code{a[0]} is always its smallest element. - -The strange invariant above is meant to be an efficient memory -representation for a tournament. The numbers below are \var{k}, not -\code{a[\var{k}]}: - -\begin{verbatim} - 0 - - 1 2 - - 3 4 5 6 - - 7 8 9 10 11 12 13 14 - - 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 -\end{verbatim} - -In the tree above, each cell \var{k} is topping \code{2*\var{k}+1} and -\code{2*\var{k}+2}. -In an usual binary tournament we see in sports, each cell is the winner -over the two cells it tops, and we can trace the winner down the tree -to see all opponents s/he had. However, in many computer applications -of such tournaments, we do not need to trace the history of a winner. -To be more memory efficient, when a winner is promoted, we try to -replace it by something else at a lower level, and the rule becomes -that a cell and the two cells it tops contain three different items, -but the top cell "wins" over the two topped cells. - -If this heap invariant is protected at all time, index 0 is clearly -the overall winner. The simplest algorithmic way to remove it and -find the "next" winner is to move some loser (let's say cell 30 in the -diagram above) into the 0 position, and then percolate this new 0 down -the tree, exchanging values, until the invariant is re-established. -This is clearly logarithmic on the total number of items in the tree. -By iterating over all items, you get an O(n log n) sort. - -A nice feature of this sort is that you can efficiently insert new -items while the sort is going on, provided that the inserted items are -not "better" than the last 0'th element you extracted. This is -especially useful in simulation contexts, where the tree holds all -incoming events, and the "win" condition means the smallest scheduled -time. When an event schedule other events for execution, they are -scheduled into the future, so they can easily go into the heap. So, a -heap is a good structure for implementing schedulers (this is what I -used for my MIDI sequencer :-). - -Various structures for implementing schedulers have been extensively -studied, and heaps are good for this, as they are reasonably speedy, -the speed is almost constant, and the worst case is not much different -than the average case. However, there are other representations which -are more efficient overall, yet the worst cases might be terrible. - -Heaps are also very useful in big disk sorts. You most probably all -know that a big sort implies producing "runs" (which are pre-sorted -sequences, which size is usually related to the amount of CPU memory), -followed by a merging passes for these runs, which merging is often -very cleverly organised\footnote{The disk balancing algorithms which -are current, nowadays, are -more annoying than clever, and this is a consequence of the seeking -capabilities of the disks. On devices which cannot seek, like big -tape drives, the story was quite different, and one had to be very -clever to ensure (far in advance) that each tape movement will be the -most effective possible (that is, will best participate at -"progressing" the merge). Some tapes were even able to read -backwards, and this was also used to avoid the rewinding time. -Believe me, real good tape sorts were quite spectacular to watch! -From all times, sorting has always been a Great Art! :-)}. -It is very important that the initial -sort produces the longest runs possible. Tournaments are a good way -to that. If, using all the memory available to hold a tournament, you -replace and percolate items that happen to fit the current run, you'll -produce runs which are twice the size of the memory for random input, -and much better for input fuzzily ordered. - -Moreover, if you output the 0'th item on disk and get an input which -may not fit in the current tournament (because the value "wins" over -the last output value), it cannot fit in the heap, so the size of the -heap decreases. The freed memory could be cleverly reused immediately -for progressively building a second heap, which grows at exactly the -same rate the first heap is melting. When the first heap completely -vanishes, you switch heaps and start a new run. Clever and quite -effective! - -In a word, heaps are useful memory structures to know. I use them in -a few applications, and I think it is good to keep a `heap' module -around. :-) diff --git a/Doc/lib/libhmac.tex b/Doc/lib/libhmac.tex deleted file mode 100644 index 5329cb5..0000000 --- a/Doc/lib/libhmac.tex +++ /dev/null @@ -1,54 +0,0 @@ -\section{\module{hmac} --- - Keyed-Hashing for Message Authentication} - -\declaremodule{standard}{hmac} -\modulesynopsis{Keyed-Hashing for Message Authentication (HMAC) - implementation for Python.} -\moduleauthor{Gerhard H{\"a}ring}{ghaering@users.sourceforge.net} -\sectionauthor{Gerhard H{\"a}ring}{ghaering@users.sourceforge.net} - -\versionadded{2.2} - -This module implements the HMAC algorithm as described by \rfc{2104}. - -\begin{funcdesc}{new}{key\optional{, msg\optional{, digestmod}}} - Return a new hmac object. If \var{msg} is present, the method call - \code{update(\var{msg})} is made. \var{digestmod} is the digest - constructor or module for the HMAC object to use. It defaults to - the \function{\refmodule{hashlib}.md5} constructor. \note{The md5 hash - has known weaknesses but remains the default for backwards compatibility. - Choose a better one for your application.} -\end{funcdesc} - -An HMAC object has the following methods: - -\begin{methoddesc}[hmac]{update}{msg} - Update the hmac object with the string \var{msg}. Repeated calls - are equivalent to a single call with the concatenation of all the - arguments: \code{m.update(a); m.update(b)} is equivalent to - \code{m.update(a + b)}. -\end{methoddesc} - -\begin{methoddesc}[hmac]{digest}{} - Return the digest of the strings passed to the \method{update()} - method so far. This string will be the same length as the - \var{digest_size} of the digest given to the constructor. It - may contain non-\ASCII{} characters, including NUL bytes. -\end{methoddesc} - -\begin{methoddesc}[hmac]{hexdigest}{} - Like \method{digest()} except the digest is returned as a string - twice the length containing - only hexadecimal digits. This may be used to exchange the value - safely in email or other non-binary environments. -\end{methoddesc} - -\begin{methoddesc}[hmac]{copy}{} - Return a copy (``clone'') of the hmac object. This can be used to - efficiently compute the digests of strings that share a common - initial substring. -\end{methoddesc} - -\begin{seealso} - \seemodule{hashlib}{The python module providing secure hash functions.} -\end{seealso} diff --git a/Doc/lib/libhotshot.tex b/Doc/lib/libhotshot.tex deleted file mode 100644 index 0004e37..0000000 --- a/Doc/lib/libhotshot.tex +++ /dev/null @@ -1,137 +0,0 @@ -\section{\module{hotshot} --- - High performance logging profiler} - -\declaremodule{standard}{hotshot} -\modulesynopsis{High performance logging profiler, mostly written in C.} -\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\sectionauthor{Anthony Baxter}{anthony@interlink.com.au} - -\versionadded{2.2} - - -This module provides a nicer interface to the \module{_hotshot} C module. -Hotshot is a replacement for the existing \refmodule{profile} module. As it's -written mostly in C, it should result in a much smaller performance impact -than the existing \refmodule{profile} module. - -\begin{notice}[note] - The \module{hotshot} module focuses on minimizing the overhead - while profiling, at the expense of long data post-processing times. - For common usages it is recommended to use \module{cProfile} instead. - \module{hotshot} is not maintained and might be removed from the - standard library in the future. -\end{notice} - -\versionchanged[the results should be more meaningful than in the -past: the timing core contained a critical bug]{2.5} - -\begin{notice}[warning] - The \module{hotshot} profiler does not yet work well with threads. - It is useful to use an unthreaded script to run the profiler over - the code you're interested in measuring if at all possible. -\end{notice} - - -\begin{classdesc}{Profile}{logfile\optional{, lineevents\optional{, - linetimings}}} -The profiler object. The argument \var{logfile} is the name of a log -file to use for logged profile data. The argument \var{lineevents} -specifies whether to generate events for every source line, or just on -function call/return. It defaults to \code{0} (only log function -call/return). The argument \var{linetimings} specifies whether to -record timing information. It defaults to \code{1} (store timing -information). -\end{classdesc} - - -\subsection{Profile Objects \label{hotshot-objects}} - -Profile objects have the following methods: - -\begin{methoddesc}[Profile]{addinfo}{key, value} -Add an arbitrary labelled value to the profile output. -\end{methoddesc} - -\begin{methoddesc}[Profile]{close}{} -Close the logfile and terminate the profiler. -\end{methoddesc} - -\begin{methoddesc}[Profile]{fileno}{} -Return the file descriptor of the profiler's log file. -\end{methoddesc} - -\begin{methoddesc}[Profile]{run}{cmd} -Profile an \function{exec()}-compatible string in the script environment. -The globals from the \refmodule[main]{__main__} module are used as -both the globals and locals for the script. -\end{methoddesc} - -\begin{methoddesc}[Profile]{runcall}{func, *args, **keywords} -Profile a single call of a callable. -Additional positional and keyword arguments may be passed -along; the result of the call is returned, and exceptions are -allowed to propagate cleanly, while ensuring that profiling is -disabled on the way out. -\end{methoddesc} - - -\begin{methoddesc}[Profile]{runctx}{cmd, globals, locals} -Profile an \function{exec()}-compatible string in a specific environment. -The string is compiled before profiling begins. -\end{methoddesc} - -\begin{methoddesc}[Profile]{start}{} -Start the profiler. -\end{methoddesc} - -\begin{methoddesc}[Profile]{stop}{} -Stop the profiler. -\end{methoddesc} - - -\subsection{Using hotshot data} - -\declaremodule{standard}{hotshot.stats} -\modulesynopsis{Statistical analysis for Hotshot} - -\versionadded{2.2} - -This module loads hotshot profiling data into the standard \module{pstats} -Stats objects. - -\begin{funcdesc}{load}{filename} -Load hotshot data from \var{filename}. Returns an instance -of the \class{pstats.Stats} class. -\end{funcdesc} - -\begin{seealso} - \seemodule{profile}{The \module{profile} module's \class{Stats} class} -\end{seealso} - - -\subsection{Example Usage \label{hotshot-example}} - -Note that this example runs the python ``benchmark'' pystones. It can -take some time to run, and will produce large output files. - -\begin{verbatim} ->>> import hotshot, hotshot.stats, test.pystone ->>> prof = hotshot.Profile("stones.prof") ->>> benchtime, stones = prof.runcall(test.pystone.pystones) ->>> prof.close() ->>> stats = hotshot.stats.load("stones.prof") ->>> stats.strip_dirs() ->>> stats.sort_stats('time', 'calls') ->>> stats.print_stats(20) - 850004 function calls in 10.090 CPU seconds - - Ordered by: internal time, call count - - ncalls tottime percall cumtime percall filename:lineno(function) - 1 3.295 3.295 10.090 10.090 pystone.py:79(Proc0) - 150000 1.315 0.000 1.315 0.000 pystone.py:203(Proc7) - 50000 1.313 0.000 1.463 0.000 pystone.py:229(Func2) - . - . - . -\end{verbatim} diff --git a/Doc/lib/libhtmllib.tex b/Doc/lib/libhtmllib.tex deleted file mode 100644 index e51dfcb..0000000 --- a/Doc/lib/libhtmllib.tex +++ /dev/null @@ -1,181 +0,0 @@ -\section{\module{htmllib} --- - A parser for HTML documents} - -\declaremodule{standard}{htmllib} -\modulesynopsis{A parser for HTML documents.} - -\index{HTML} -\index{hypertext} - - -This module defines a class which can serve as a base for parsing text -files formatted in the HyperText Mark-up Language (HTML). The class -is not directly concerned with I/O --- it must be provided with input -in string form via a method, and makes calls to methods of a -``formatter'' object in order to produce output. The -\class{HTMLParser} class is designed to be used as a base class for -other classes in order to add functionality, and allows most of its -methods to be extended or overridden. In turn, this class is derived -from and extends the \class{SGMLParser} class defined in module -\refmodule{sgmllib}\refstmodindex{sgmllib}. The \class{HTMLParser} -implementation supports the HTML 2.0 language as described in -\rfc{1866}. Two implementations of formatter objects are provided in -the \refmodule{formatter}\refstmodindex{formatter}\ module; refer to the -documentation for that module for information on the formatter -interface. -\withsubitem{(in module sgmllib)}{\ttindex{SGMLParser}} - -The following is a summary of the interface defined by -\class{sgmllib.SGMLParser}: - -\begin{itemize} - -\item -The interface to feed data to an instance is through the \method{feed()} -method, which takes a string argument. This can be called with as -little or as much text at a time as desired; \samp{p.feed(a); -p.feed(b)} has the same effect as \samp{p.feed(a+b)}. When the data -contains complete HTML markup constructs, these are processed immediately; -incomplete constructs are saved in a buffer. To force processing of all -unprocessed data, call the \method{close()} method. - -For example, to parse the entire contents of a file, use: -\begin{verbatim} -parser.feed(open('myfile.html').read()) -parser.close() -\end{verbatim} - -\item -The interface to define semantics for HTML tags is very simple: derive -a class and define methods called \method{start_\var{tag}()}, -\method{end_\var{tag}()}, or \method{do_\var{tag}()}. The parser will -call these at appropriate moments: \method{start_\var{tag}} or -\method{do_\var{tag}()} is called when an opening tag of the form -\code{<\var{tag} ...>} is encountered; \method{end_\var{tag}()} is called -when a closing tag of the form \code{<\var{tag}>} is encountered. If -an opening tag requires a corresponding closing tag, like \code{<H1>} -... \code{</H1>}, the class should define the \method{start_\var{tag}()} -method; if a tag requires no closing tag, like \code{<P>}, the class -should define the \method{do_\var{tag}()} method. - -\end{itemize} - -The module defines a parser class and an exception: - -\begin{classdesc}{HTMLParser}{formatter} -This is the basic HTML parser class. It supports all entity names -required by the XHTML 1.0 Recommendation (\url{http://www.w3.org/TR/xhtml1}). -It also defines handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements. -\end{classdesc} - -\begin{excdesc}{HTMLParseError} -Exception raised by the \class{HTMLParser} class when it encounters an -error while parsing. -\versionadded{2.4} -\end{excdesc} - - -\begin{seealso} - \seemodule{formatter}{Interface definition for transforming an - abstract flow of formatting events into - specific output events on writer objects.} - \seemodule{HTMLParser}{Alternate HTML parser that offers a slightly - lower-level view of the input, but is - designed to work with XHTML, and does not - implement some of the SGML syntax not used in - ``HTML as deployed'' and which isn't legal - for XHTML.} - \seemodule{htmlentitydefs}{Definition of replacement text for XHTML 1.0 - entities.} - \seemodule{sgmllib}{Base class for \class{HTMLParser}.} -\end{seealso} - - -\subsection{HTMLParser Objects \label{html-parser-objects}} - -In addition to tag methods, the \class{HTMLParser} class provides some -additional methods and instance variables for use within tag methods. - -\begin{memberdesc}[HTMLParser]{formatter} -This is the formatter instance associated with the parser. -\end{memberdesc} - -\begin{memberdesc}[HTMLParser]{nofill} -Boolean flag which should be true when whitespace should not be -collapsed, or false when it should be. In general, this should only -be true when character data is to be treated as ``preformatted'' text, -as within a \code{<PRE>} element. The default value is false. This -affects the operation of \method{handle_data()} and \method{save_end()}. -\end{memberdesc} - - -\begin{methoddesc}[HTMLParser]{anchor_bgn}{href, name, type} -This method is called at the start of an anchor region. The arguments -correspond to the attributes of the \code{<A>} tag with the same -names. The default implementation maintains a list of hyperlinks -(defined by the \code{HREF} attribute for \code{<A>} tags) within the -document. The list of hyperlinks is available as the data attribute -\member{anchorlist}. -\end{methoddesc} - -\begin{methoddesc}[HTMLParser]{anchor_end}{} -This method is called at the end of an anchor region. The default -implementation adds a textual footnote marker using an index into the -list of hyperlinks created by \method{anchor_bgn()}. -\end{methoddesc} - -\begin{methoddesc}[HTMLParser]{handle_image}{source, alt\optional{, ismap\optional{, - align\optional{, width\optional{, height}}}}} -This method is called to handle images. The default implementation -simply passes the \var{alt} value to the \method{handle_data()} -method. -\end{methoddesc} - -\begin{methoddesc}[HTMLParser]{save_bgn}{} -Begins saving character data in a buffer instead of sending it to the -formatter object. Retrieve the stored data via \method{save_end()}. -Use of the \method{save_bgn()} / \method{save_end()} pair may not be -nested. -\end{methoddesc} - -\begin{methoddesc}[HTMLParser]{save_end}{} -Ends buffering character data and returns all data saved since the -preceding call to \method{save_bgn()}. If the \member{nofill} flag is -false, whitespace is collapsed to single spaces. A call to this -method without a preceding call to \method{save_bgn()} will raise a -\exception{TypeError} exception. -\end{methoddesc} - - - -\section{\module{htmlentitydefs} --- - Definitions of HTML general entities} - -\declaremodule{standard}{htmlentitydefs} -\modulesynopsis{Definitions of HTML general entities.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -This module defines three dictionaries, \code{name2codepoint}, -\code{codepoint2name}, and \code{entitydefs}. \code{entitydefs} is -used by the \refmodule{htmllib} module to provide the -\member{entitydefs} member of the \class{HTMLParser} class. The -definition provided here contains all the entities defined by XHTML 1.0 -that can be handled using simple textual substitution in the Latin-1 -character set (ISO-8859-1). - - -\begin{datadesc}{entitydefs} - A dictionary mapping XHTML 1.0 entity definitions to their - replacement text in ISO Latin-1. - -\end{datadesc} - -\begin{datadesc}{name2codepoint} - A dictionary that maps HTML entity names to the Unicode codepoints. - \versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{codepoint2name} - A dictionary that maps Unicode codepoints to HTML entity names. - \versionadded{2.3} -\end{datadesc} diff --git a/Doc/lib/libhtmlparser.tex b/Doc/lib/libhtmlparser.tex deleted file mode 100644 index 5e99f27..0000000 --- a/Doc/lib/libhtmlparser.tex +++ /dev/null @@ -1,173 +0,0 @@ -\section{\module{HTMLParser} --- - Simple HTML and XHTML parser} - -\declaremodule{standard}{HTMLParser} -\modulesynopsis{A simple parser that can handle HTML and XHTML.} - -\versionadded{2.2} - -This module defines a class \class{HTMLParser} which serves as the -basis for parsing text files formatted in HTML\index{HTML} (HyperText -Mark-up Language) and XHTML.\index{XHTML} Unlike the parser in -\refmodule{htmllib}, this parser is not based on the SGML parser in -\refmodule{sgmllib}. - - -\begin{classdesc}{HTMLParser}{} -The \class{HTMLParser} class is instantiated without arguments. - -An HTMLParser instance is fed HTML data and calls handler functions -when tags begin and end. The \class{HTMLParser} class is meant to be -overridden by the user to provide a desired behavior. - -Unlike the parser in \refmodule{htmllib}, this parser does not check -that end tags match start tags or call the end-tag handler for -elements which are closed implicitly by closing an outer element. -\end{classdesc} - -An exception is defined as well: - -\begin{excdesc}{HTMLParseError} -Exception raised by the \class{HTMLParser} class when it encounters an -error while parsing. This exception provides three attributes: -\member{msg} is a brief message explaining the error, \member{lineno} -is the number of the line on which the broken construct was detected, -and \member{offset} is the number of characters into the line at which -the construct starts. -\end{excdesc} - - -\class{HTMLParser} instances have the following methods: - -\begin{methoddesc}{reset}{} -Reset the instance. Loses all unprocessed data. This is called -implicitly at instantiation time. -\end{methoddesc} - -\begin{methoddesc}{feed}{data} -Feed some text to the parser. It is processed insofar as it consists -of complete elements; incomplete data is buffered until more data is -fed or \method{close()} is called. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Force processing of all buffered data as if it were followed by an -end-of-file mark. This method may be redefined by a derived class to -define additional processing at the end of the input, but the -redefined version should always call the \class{HTMLParser} base class -method \method{close()}. -\end{methoddesc} - -\begin{methoddesc}{getpos}{} -Return current line number and offset. -\end{methoddesc} - -\begin{methoddesc}{get_starttag_text}{} -Return the text of the most recently opened start tag. This should -not normally be needed for structured processing, but may be useful in -dealing with HTML ``as deployed'' or for re-generating input with -minimal changes (whitespace between attributes can be preserved, -etc.). -\end{methoddesc} - -\begin{methoddesc}{handle_starttag}{tag, attrs} -This method is called to handle the start of a tag. It is intended to -be overridden by a derived class; the base class implementation does -nothing. - -The \var{tag} argument is the name of the tag converted to lower case. -The \var{attrs} argument is a list of \code{(\var{name}, \var{value})} -pairs containing the attributes found inside the tag's \code{<>} -brackets. The \var{name} will be translated to lower case, and quotes -in the \var{value} have been removed, and character and entity -references have been replaced. For instance, for the tag \code{<A - HREF="http://www.cwi.nl/">}, this method would be called as -\samp{handle_starttag('a', [('href', 'http://www.cwi.nl/')])}. - -\versionchanged[All entity references from htmlentitydefs are now -replaced in the attribute values]{2.6} - -\end{methoddesc} - -\begin{methoddesc}{handle_startendtag}{tag, attrs} -Similar to \method{handle_starttag()}, but called when the parser -encounters an XHTML-style empty tag (\code{<a .../>}). This method -may be overridden by subclasses which require this particular lexical -information; the default implementation simple calls -\method{handle_starttag()} and \method{handle_endtag()}. -\end{methoddesc} - -\begin{methoddesc}{handle_endtag}{tag} -This method is called to handle the end tag of an element. It is -intended to be overridden by a derived class; the base class -implementation does nothing. The \var{tag} argument is the name of -the tag converted to lower case. -\end{methoddesc} - -\begin{methoddesc}{handle_data}{data} -This method is called to process arbitrary data. It is intended to be -overridden by a derived class; the base class implementation does -nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_charref}{name} This method is called to -process a character reference of the form \samp{\&\#\var{ref};}. It -is intended to be overridden by a derived class; the base class -implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_entityref}{name} -This method is called to process a general entity reference of the -form \samp{\&\var{name};} where \var{name} is an general entity -reference. It is intended to be overridden by a derived class; the -base class implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_comment}{data} -This method is called when a comment is encountered. The -\var{comment} argument is a string containing the text between the -\samp{--} and \samp{--} delimiters, but not the delimiters -themselves. For example, the comment \samp{<!--text-->} will -cause this method to be called with the argument \code{'text'}. It is -intended to be overridden by a derived class; the base class -implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_decl}{decl} -Method called when an SGML declaration is read by the parser. The -\var{decl} parameter will be the entire contents of the declaration -inside the \code{<!}...\code{>} markup. It is intended to be overridden -by a derived class; the base class implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_pi}{data} -Method called when a processing instruction is encountered. The -\var{data} parameter will contain the entire processing instruction. -For example, for the processing instruction \code{<?proc color='red'>}, -this method would be called as \code{handle_pi("proc color='red'")}. It -is intended to be overridden by a derived class; the base class -implementation does nothing. - -\note{The \class{HTMLParser} class uses the SGML syntactic rules for -processing instructions. An XHTML processing instruction using the -trailing \character{?} will cause the \character{?} to be included in -\var{data}.} -\end{methoddesc} - - -\subsection{Example HTML Parser Application \label{htmlparser-example}} - -As a basic example, below is a very basic HTML parser that uses the -\class{HTMLParser} class to print out tags as they are encountered: - -\begin{verbatim} -from HTMLParser import HTMLParser - -class MyHTMLParser(HTMLParser): - - def handle_starttag(self, tag, attrs): - print "Encountered the beginning of a %s tag" % tag - - def handle_endtag(self, tag): - print "Encountered the end of a %s tag" % tag -\end{verbatim} diff --git a/Doc/lib/libhttplib.tex b/Doc/lib/libhttplib.tex deleted file mode 100644 index 37a442d..0000000 --- a/Doc/lib/libhttplib.tex +++ /dev/null @@ -1,452 +0,0 @@ -\section{\module{httplib} --- - HTTP protocol client} - -\declaremodule{standard}{httplib} -\modulesynopsis{HTTP and HTTPS protocol client (requires sockets).} - -\indexii{HTTP}{protocol} -\index{HTTP!\module{httplib} (standard module)} - -This module defines classes which implement the client side of the -HTTP and HTTPS protocols. It is normally not used directly --- the -module \refmodule{urllib}\refstmodindex{urllib} uses it to handle URLs -that use HTTP and HTTPS. - -\begin{notice} - HTTPS support is only available if the \refmodule{socket} module was - compiled with SSL support. -\end{notice} - -\begin{notice} - The public interface for this module changed substantially in Python - 2.0. The \class{HTTP} class is retained only for backward - compatibility with 1.5.2. It should not be used in new code. Refer - to the online docstrings for usage. -\end{notice} - -The module provides the following classes: - -\begin{classdesc}{HTTPConnection}{host\optional{, port\optional{, - strict\optional{, timeout}}}} -An \class{HTTPConnection} instance represents one transaction with an HTTP -server. It should be instantiated passing it a host and optional port number. -If no port number is passed, the port is extracted from the host string if it -has the form \code{\var{host}:\var{port}}, else the default HTTP port (80) is -used. When True, the optional parameter \var{strict} -causes \code{BadStatusLine} to be raised if the status line can't be parsed -as a valid HTTP/1.0 or 1.1 status line. If the optional \var{timeout} -parameter is given, connection attempts will timeout after that many -seconds (if it is not given or \code{None}, the global default -timeout setting is used). - -For example, the following calls all create instances that connect to -the server at the same host and port: - -\begin{verbatim} ->>> h1 = httplib.HTTPConnection('www.cwi.nl') ->>> h2 = httplib.HTTPConnection('www.cwi.nl:80') ->>> h3 = httplib.HTTPConnection('www.cwi.nl', 80) ->>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10) -\end{verbatim} -\versionadded{2.0} -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - -\begin{classdesc}{HTTPSConnection}{host\optional{, port\optional{, - key_file\optional{, cert_file\optional{, - strict\optional{, timeout}}}}}} -A subclass of \class{HTTPConnection} that uses SSL for communication with -secure servers. Default port is \code{443}. -\var{key_file} is -the name of a PEM formatted file that contains your private -key. \var{cert_file} is a PEM formatted certificate chain file. - -\warning{This does not do any certificate verification!} - -\versionadded{2.0} -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - -\begin{classdesc}{HTTPResponse}{sock\optional{, debuglevel=0}\optional{, strict=0}} -Class whose instances are returned upon successful connection. Not -instantiated directly by user. -\versionadded{2.0} -\end{classdesc} - -The following exceptions are raised as appropriate: - -\begin{excdesc}{HTTPException} -The base class of the other exceptions in this module. It is a -subclass of \exception{Exception}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{NotConnected} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{InvalidURL} -A subclass of \exception{HTTPException}, raised if a port is given and is -either non-numeric or empty. -\versionadded{2.3} -\end{excdesc} - -\begin{excdesc}{UnknownProtocol} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{UnknownTransferEncoding} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{UnimplementedFileMode} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{IncompleteRead} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{ImproperConnectionState} -A subclass of \exception{HTTPException}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{CannotSendRequest} -A subclass of \exception{ImproperConnectionState}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{CannotSendHeader} -A subclass of \exception{ImproperConnectionState}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{ResponseNotReady} -A subclass of \exception{ImproperConnectionState}. -\versionadded{2.0} -\end{excdesc} - -\begin{excdesc}{BadStatusLine} -A subclass of \exception{HTTPException}. Raised if a server responds with a -HTTP status code that we don't understand. -\versionadded{2.0} -\end{excdesc} - -The constants defined in this module are: - -\begin{datadesc}{HTTP_PORT} - The default port for the HTTP protocol (always \code{80}). -\end{datadesc} - -\begin{datadesc}{HTTPS_PORT} - The default port for the HTTPS protocol (always \code{443}). -\end{datadesc} - -and also the following constants for integer status codes: - -\begin{tableiii}{l|c|l}{constant}{Constant}{Value}{Definition} - \lineiii{CONTINUE}{\code{100}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.1.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1}} - \lineiii{SWITCHING_PROTOCOLS}{\code{101}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.1.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2}} - \lineiii{PROCESSING}{\code{102}} - {WEBDAV, \ulink{RFC 2518, Section 10.1} - {http://www.webdav.org/specs/rfc2518.html#STATUS_102}} - - \lineiii{OK}{\code{200}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1}} - \lineiii{CREATED}{\code{201}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2}} - \lineiii{ACCEPTED}{\code{202}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.3} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3}} - \lineiii{NON_AUTHORITATIVE_INFORMATION}{\code{203}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.4} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4}} - \lineiii{NO_CONTENT}{\code{204}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.5} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5}} - \lineiii{RESET_CONTENT}{\code{205}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.6} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6}} - \lineiii{PARTIAL_CONTENT}{\code{206}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.2.7} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7}} - \lineiii{MULTI_STATUS}{\code{207}} - {WEBDAV \ulink{RFC 2518, Section 10.2} - {http://www.webdav.org/specs/rfc2518.html#STATUS_207}} - \lineiii{IM_USED}{\code{226}} - {Delta encoding in HTTP, \rfc{3229}, Section 10.4.1} - - \lineiii{MULTIPLE_CHOICES}{\code{300}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1}} - \lineiii{MOVED_PERMANENTLY}{\code{301}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2}} - \lineiii{FOUND}{\code{302}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.3} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3}} - \lineiii{SEE_OTHER}{\code{303}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.4} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4}} - \lineiii{NOT_MODIFIED}{\code{304}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.5} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5}} - \lineiii{USE_PROXY}{\code{305}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.6} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6}} - \lineiii{TEMPORARY_REDIRECT}{\code{307}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.3.8} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8}} - - \lineiii{BAD_REQUEST}{\code{400}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1}} - \lineiii{UNAUTHORIZED}{\code{401}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2}} - \lineiii{PAYMENT_REQUIRED}{\code{402}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.3} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3}} - \lineiii{FORBIDDEN}{\code{403}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.4} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4}} - \lineiii{NOT_FOUND}{\code{404}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.5} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5}} - \lineiii{METHOD_NOT_ALLOWED}{\code{405}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.6} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6}} - \lineiii{NOT_ACCEPTABLE}{\code{406}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.7} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7}} - \lineiii{PROXY_AUTHENTICATION_REQUIRED} - {\code{407}}{HTTP/1.1, \ulink{RFC 2616, Section 10.4.8} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8}} - \lineiii{REQUEST_TIMEOUT}{\code{408}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.9} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9}} - \lineiii{CONFLICT}{\code{409}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.10} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10}} - \lineiii{GONE}{\code{410}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.11} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11}} - \lineiii{LENGTH_REQUIRED}{\code{411}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.12} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12}} - \lineiii{PRECONDITION_FAILED}{\code{412}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.13} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13}} - \lineiii{REQUEST_ENTITY_TOO_LARGE} - {\code{413}}{HTTP/1.1, \ulink{RFC 2616, Section 10.4.14} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14}} - \lineiii{REQUEST_URI_TOO_LONG}{\code{414}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.15} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15}} - \lineiii{UNSUPPORTED_MEDIA_TYPE}{\code{415}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.16} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16}} - \lineiii{REQUESTED_RANGE_NOT_SATISFIABLE}{\code{416}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.17} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17}} - \lineiii{EXPECTATION_FAILED}{\code{417}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.4.18} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18}} - \lineiii{UNPROCESSABLE_ENTITY}{\code{422}} - {WEBDAV, \ulink{RFC 2518, Section 10.3} - {http://www.webdav.org/specs/rfc2518.html#STATUS_422}} - \lineiii{LOCKED}{\code{423}} - {WEBDAV \ulink{RFC 2518, Section 10.4} - {http://www.webdav.org/specs/rfc2518.html#STATUS_423}} - \lineiii{FAILED_DEPENDENCY}{\code{424}} - {WEBDAV, \ulink{RFC 2518, Section 10.5} - {http://www.webdav.org/specs/rfc2518.html#STATUS_424}} - \lineiii{UPGRADE_REQUIRED}{\code{426}} - {HTTP Upgrade to TLS, \rfc{2817}, Section 6} - - \lineiii{INTERNAL_SERVER_ERROR}{\code{500}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.5.1} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1}} - \lineiii{NOT_IMPLEMENTED}{\code{501}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.5.2} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2}} - \lineiii{BAD_GATEWAY}{\code{502}} - {HTTP/1.1 \ulink{RFC 2616, Section 10.5.3} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3}} - \lineiii{SERVICE_UNAVAILABLE}{\code{503}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.5.4} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4}} - \lineiii{GATEWAY_TIMEOUT}{\code{504}} - {HTTP/1.1 \ulink{RFC 2616, Section 10.5.5} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5}} - \lineiii{HTTP_VERSION_NOT_SUPPORTED}{\code{505}} - {HTTP/1.1, \ulink{RFC 2616, Section 10.5.6} - {http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6}} - \lineiii{INSUFFICIENT_STORAGE}{\code{507}} - {WEBDAV, \ulink{RFC 2518, Section 10.6} - {http://www.webdav.org/specs/rfc2518.html#STATUS_507}} - \lineiii{NOT_EXTENDED}{\code{510}} - {An HTTP Extension Framework, \rfc{2774}, Section 7} -\end{tableiii} - -\begin{datadesc}{responses} -This dictionary maps the HTTP 1.1 status codes to the W3C names. - -Example: \code{httplib.responses[httplib.NOT_FOUND]} is \code{'Not Found'}. -\versionadded{2.5} -\end{datadesc} - - -\subsection{HTTPConnection Objects \label{httpconnection-objects}} - -\class{HTTPConnection} instances have the following methods: - -\begin{methoddesc}[HTTPConnection]{request}{method, url\optional{, body\optional{, headers}}} -This will send a request to the server using the HTTP request method -\var{method} and the selector \var{url}. If the \var{body} argument is -present, it should be a string of data to send after the headers are finished. -Alternatively, it may be an open file object, in which case the -contents of the file is sent; this file object should support -\code{fileno()} and \code{read()} methods. -The header Content-Length is automatically set to the correct value. -The \var{headers} argument should be a mapping of extra HTTP headers to send -with the request. - -\versionchanged[\var{body} can be a file object]{2.6} -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{getresponse}{} -Should be called after a request is sent to get the response from the server. -Returns an \class{HTTPResponse} instance. -\note{Note that you must have read the whole response before you can send a new -request to the server.} -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{set_debuglevel}{level} -Set the debugging level (the amount of debugging output printed). -The default debug level is \code{0}, meaning no debugging output is -printed. -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{connect}{} -Connect to the server specified when the object was created. -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{close}{} -Close the connection to the server. -\end{methoddesc} - -As an alternative to using the \method{request()} method described above, -you can also send your request step by step, by using the four functions -below. - -\begin{methoddesc}[HTTPConnection]{putrequest}{request, selector\optional{, -skip\_host\optional{, skip_accept_encoding}}} -This should be the first call after the connection to the server has -been made. It sends a line to the server consisting of the -\var{request} string, the \var{selector} string, and the HTTP version -(\code{HTTP/1.1}). To disable automatic sending of \code{Host:} or -\code{Accept-Encoding:} headers (for example to accept additional -content encodings), specify \var{skip_host} or \var{skip_accept_encoding} -with non-False values. -\versionchanged[\var{skip_accept_encoding} argument added]{2.4} -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{putheader}{header, argument\optional{, ...}} -Send an \rfc{822}-style header to the server. It sends a line to the -server consisting of the header, a colon and a space, and the first -argument. If more arguments are given, continuation lines are sent, -each consisting of a tab and an argument. -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{endheaders}{} -Send a blank line to the server, signalling the end of the headers. -\end{methoddesc} - -\begin{methoddesc}[HTTPConnection]{send}{data} -Send data to the server. This should be used directly only after the -\method{endheaders()} method has been called and before -\method{getresponse()} is called. -\end{methoddesc} - -\subsection{HTTPResponse Objects \label{httpresponse-objects}} - -\class{HTTPResponse} instances have the following methods and attributes: - -\begin{methoddesc}[HTTPResponse]{read}{\optional{amt}} -Reads and returns the response body, or up to the next \var{amt} bytes. -\end{methoddesc} - -\begin{methoddesc}[HTTPResponse]{getheader}{name\optional{, default}} -Get the contents of the header \var{name}, or \var{default} if there is no -matching header. -\end{methoddesc} - -\begin{methoddesc}[HTTPResponse]{getheaders}{} -Return a list of (header, value) tuples. \versionadded{2.4} -\end{methoddesc} - -\begin{memberdesc}[HTTPResponse]{msg} - A \class{mimetools.Message} instance containing the response headers. -\end{memberdesc} - -\begin{memberdesc}[HTTPResponse]{version} - HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1. -\end{memberdesc} - -\begin{memberdesc}[HTTPResponse]{status} - Status code returned by server. -\end{memberdesc} - -\begin{memberdesc}[HTTPResponse]{reason} - Reason phrase returned by server. -\end{memberdesc} - - -\subsection{Examples \label{httplib-examples}} - -Here is an example session that uses the \samp{GET} method: - -\begin{verbatim} ->>> import httplib ->>> conn = httplib.HTTPConnection("www.python.org") ->>> conn.request("GET", "/index.html") ->>> r1 = conn.getresponse() ->>> print r1.status, r1.reason -200 OK ->>> data1 = r1.read() ->>> conn.request("GET", "/parrot.spam") ->>> r2 = conn.getresponse() ->>> print r2.status, r2.reason -404 Not Found ->>> data2 = r2.read() ->>> conn.close() -\end{verbatim} - -Here is an example session that shows how to \samp{POST} requests: - -\begin{verbatim} ->>> import httplib, urllib ->>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0}) ->>> headers = {"Content-type": "application/x-www-form-urlencoded", -... "Accept": "text/plain"} ->>> conn = httplib.HTTPConnection("musi-cal.mojam.com:80") ->>> conn.request("POST", "/cgi-bin/query", params, headers) ->>> response = conn.getresponse() ->>> print response.status, response.reason -200 OK ->>> data = response.read() ->>> conn.close() -\end{verbatim} diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex deleted file mode 100644 index e34caaa..0000000 --- a/Doc/lib/libimaplib.tex +++ /dev/null @@ -1,507 +0,0 @@ -\section{\module{imaplib} --- - IMAP4 protocol client} - -\declaremodule{standard}{imaplib} -\modulesynopsis{IMAP4 protocol client (requires sockets).} -\moduleauthor{Piers Lauder}{piers@communitysolutions.com.au} -\sectionauthor{Piers Lauder}{piers@communitysolutions.com.au} - -% Based on HTML documentation by Piers Lauder -% <piers@communitysolutions.com.au>; -% converted by Fred L. Drake, Jr. <fdrake@acm.org>. -% Revised by ESR, January 2000. -% Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002 -% Changes for IMAP4_stream by Piers Lauder -% <piers@communitysolutions.com.au>, November 2002 - -\indexii{IMAP4}{protocol} -\indexii{IMAP4_SSL}{protocol} -\indexii{IMAP4_stream}{protocol} - -This module defines three classes, \class{IMAP4}, \class{IMAP4_SSL} -and \class{IMAP4_stream}, which encapsulate a -connection to an IMAP4 server and implement a large subset of the -IMAP4rev1 client protocol as defined in \rfc{2060}. It is backward -compatible with IMAP4 (\rfc{1730}) servers, but note that the -\samp{STATUS} command is not supported in IMAP4. - -Three classes are provided by the \module{imaplib} module, -\class{IMAP4} is the base class: - -\begin{classdesc}{IMAP4}{\optional{host\optional{, port}}} -This class implements the actual IMAP4 protocol. The connection is -created and protocol version (IMAP4 or IMAP4rev1) is determined when -the instance is initialized. -If \var{host} is not specified, \code{''} (the local host) is used. -If \var{port} is omitted, the standard IMAP4 port (143) is used. -\end{classdesc} - -Three exceptions are defined as attributes of the \class{IMAP4} class: - -\begin{excdesc}{IMAP4.error} -Exception raised on any errors. The reason for the exception is -passed to the constructor as a string. -\end{excdesc} - -\begin{excdesc}{IMAP4.abort} -IMAP4 server errors cause this exception to be raised. This is a -sub-class of \exception{IMAP4.error}. Note that closing the instance -and instantiating a new one will usually allow recovery from this -exception. -\end{excdesc} - -\begin{excdesc}{IMAP4.readonly} -This exception is raised when a writable mailbox has its status -changed by the server. This is a sub-class of -\exception{IMAP4.error}. Some other client now has write permission, -and the mailbox will need to be re-opened to re-obtain write -permission. -\end{excdesc} - -There's also a subclass for secure connections: - -\begin{classdesc}{IMAP4_SSL}{\optional{host\optional{, port\optional{, - keyfile\optional{, certfile}}}}} -This is a subclass derived from \class{IMAP4} that connects over an -SSL encrypted socket (to use this class you need a socket module that -was compiled with SSL support). If \var{host} is not specified, -\code{''} (the local host) is used. If \var{port} is omitted, the -standard IMAP4-over-SSL port (993) is used. \var{keyfile} and -\var{certfile} are also optional - they can contain a PEM formatted -private key and certificate chain file for the SSL connection. -\end{classdesc} - -The second subclass allows for connections created by a child process: - -\begin{classdesc}{IMAP4_stream}{command} -This is a subclass derived from \class{IMAP4} that connects -to the \code{stdin/stdout} file descriptors created by passing -\var{command} to \code{os.popen2()}. -\versionadded{2.3} -\end{classdesc} - -The following utility functions are defined: - -\begin{funcdesc}{Internaldate2tuple}{datestr} - Converts an IMAP4 INTERNALDATE string to Coordinated Universal - Time. Returns a \refmodule{time} module tuple. -\end{funcdesc} - -\begin{funcdesc}{Int2AP}{num} - Converts an integer into a string representation using characters - from the set [\code{A} .. \code{P}]. -\end{funcdesc} - -\begin{funcdesc}{ParseFlags}{flagstr} - Converts an IMAP4 \samp{FLAGS} response to a tuple of individual - flags. -\end{funcdesc} - -\begin{funcdesc}{Time2Internaldate}{date_time} - Converts a \refmodule{time} module tuple to an IMAP4 - \samp{INTERNALDATE} representation. Returns a string in the form: - \code{"DD-Mmm-YYYY HH:MM:SS +HHMM"} (including double-quotes). -\end{funcdesc} - - -Note that IMAP4 message numbers change as the mailbox changes; in -particular, after an \samp{EXPUNGE} command performs deletions the -remaining messages are renumbered. So it is highly advisable to use -UIDs instead, with the UID command. - -At the end of the module, there is a test section that contains a more -extensive example of usage. - -\begin{seealso} - \seetext{Documents describing the protocol, and sources and binaries - for servers implementing it, can all be found at the - University of Washington's \emph{IMAP Information Center} - (\url{http://www.cac.washington.edu/imap/}).} -\end{seealso} - - -\subsection{IMAP4 Objects \label{imap4-objects}} - -All IMAP4rev1 commands are represented by methods of the same name, -either upper-case or lower-case. - -All arguments to commands are converted to strings, except for -\samp{AUTHENTICATE}, and the last argument to \samp{APPEND} which is -passed as an IMAP4 literal. If necessary (the string contains IMAP4 -protocol-sensitive characters and isn't enclosed with either -parentheses or double quotes) each string is quoted. However, the -\var{password} argument to the \samp{LOGIN} command is always quoted. -If you want to avoid having an argument string quoted -(eg: the \var{flags} argument to \samp{STORE}) then enclose the string in -parentheses (eg: \code{r'(\e Deleted)'}). - -Each command returns a tuple: \code{(\var{type}, [\var{data}, -...])} where \var{type} is usually \code{'OK'} or \code{'NO'}, -and \var{data} is either the text from the command response, or -mandated results from the command. Each \var{data} -is either a string, or a tuple. If a tuple, then the first part -is the header of the response, and the second part contains -the data (ie: 'literal' value). - -The \var{message_set} options to commands below is a string specifying one -or more messages to be acted upon. It may be a simple message number -(\code{'1'}), a range of message numbers (\code{'2:4'}), or a group of -non-contiguous ranges separated by commas (\code{'1:3,6:9'}). A range -can contain an asterisk to indicate an infinite upper bound -(\code{'3:*'}). - -An \class{IMAP4} instance has the following methods: - - -\begin{methoddesc}[IMAP4]{append}{mailbox, flags, date_time, message} - Append \var{message} to named mailbox. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{authenticate}{mechanism, authobject} - Authenticate command --- requires response processing. - - \var{mechanism} specifies which authentication mechanism is to be - used - it should appear in the instance variable \code{capabilities} - in the form \code{AUTH=mechanism}. - - \var{authobject} must be a callable object: - -\begin{verbatim} -data = authobject(response) -\end{verbatim} - - It will be called to process server continuation responses. - It should return \code{data} that will be encoded and sent to server. - It should return \code{None} if the client abort response \samp{*} should - be sent instead. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{check}{} - Checkpoint mailbox on server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{close}{} - Close currently selected mailbox. Deleted messages are removed from - writable mailbox. This is the recommended command before - \samp{LOGOUT}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{copy}{message_set, new_mailbox} - Copy \var{message_set} messages onto end of \var{new_mailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{create}{mailbox} - Create new mailbox named \var{mailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{delete}{mailbox} - Delete old mailbox named \var{mailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{deleteacl}{mailbox, who} - Delete the ACLs (remove any rights) set for who on mailbox. -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{expunge}{} - Permanently remove deleted items from selected mailbox. Generates an - \samp{EXPUNGE} response for each deleted message. Returned data - contains a list of \samp{EXPUNGE} message numbers in order - received. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{fetch}{message_set, message_parts} - Fetch (parts of) messages. \var{message_parts} should be - a string of message part names enclosed within parentheses, - eg: \samp{"(UID BODY[TEXT])"}. Returned data are tuples - of message part envelope and data. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{getacl}{mailbox} - Get the \samp{ACL}s for \var{mailbox}. - The method is non-standard, but is supported by the \samp{Cyrus} server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{getannotation}{mailbox, entry, attribute} - Retrieve the specified \samp{ANNOTATION}s for \var{mailbox}. - The method is non-standard, but is supported by the \samp{Cyrus} server. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{getquota}{root} - Get the \samp{quota} \var{root}'s resource usage and limits. - This method is part of the IMAP4 QUOTA extension defined in rfc2087. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{getquotaroot}{mailbox} - Get the list of \samp{quota} \samp{roots} for the named \var{mailbox}. - This method is part of the IMAP4 QUOTA extension defined in rfc2087. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{list}{\optional{directory\optional{, pattern}}} - List mailbox names in \var{directory} matching - \var{pattern}. \var{directory} defaults to the top-level mail - folder, and \var{pattern} defaults to match anything. Returned data - contains a list of \samp{LIST} responses. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{login}{user, password} - Identify the client using a plaintext password. - The \var{password} will be quoted. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{login_cram_md5}{user, password} - Force use of \samp{CRAM-MD5} authentication when identifying the - client to protect the password. Will only work if the server - \samp{CAPABILITY} response includes the phrase \samp{AUTH=CRAM-MD5}. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{logout}{} - Shutdown connection to server. Returns server \samp{BYE} response. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{lsub}{\optional{directory\optional{, pattern}}} - List subscribed mailbox names in directory matching pattern. - \var{directory} defaults to the top level directory and - \var{pattern} defaults to match any mailbox. - Returned data are tuples of message part envelope and data. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{myrights}{mailbox} - Show my ACLs for a mailbox (i.e. the rights that I have on mailbox). -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{namespace}{} - Returns IMAP namespaces as defined in RFC2342. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{noop}{} - Send \samp{NOOP} to server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{open}{host, port} - Opens socket to \var{port} at \var{host}. - The connection objects established by this method - will be used in the \code{read}, \code{readline}, \code{send}, and - \code{shutdown} methods. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{partial}{message_num, message_part, start, length} - Fetch truncated part of a message. - Returned data is a tuple of message part envelope and data. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{proxyauth}{user} - Assume authentication as \var{user}. - Allows an authorised administrator to proxy into any user's mailbox. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{read}{size} - Reads \var{size} bytes from the remote server. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{readline}{} - Reads one line from the remote server. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{recent}{} - Prompt server for an update. Returned data is \code{None} if no new - messages, else value of \samp{RECENT} response. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{rename}{oldmailbox, newmailbox} - Rename mailbox named \var{oldmailbox} to \var{newmailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{response}{code} - Return data for response \var{code} if received, or - \code{None}. Returns the given code, instead of the usual type. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{search}{charset, criterion\optional{, ...}} - Search mailbox for matching messages. \var{charset} may be - \code{None}, in which case no \samp{CHARSET} will be specified in the - request to the server. The IMAP protocol requires that at least one - criterion be specified; an exception will be raised when the server - returns an error. - - Example: - -\begin{verbatim} -# M is a connected IMAP4 instance... -typ, msgnums = M.search(None, 'FROM', '"LDJ"') - -# or: -typ, msgnums = M.search(None, '(FROM "LDJ")') -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{select}{\optional{mailbox\optional{, readonly}}} - Select a mailbox. Returned data is the count of messages in - \var{mailbox} (\samp{EXISTS} response). The default \var{mailbox} - is \code{'INBOX'}. If the \var{readonly} flag is set, modifications - to the mailbox are not allowed. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{send}{data} - Sends \code{data} to the remote server. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{setacl}{mailbox, who, what} - Set an \samp{ACL} for \var{mailbox}. - The method is non-standard, but is supported by the \samp{Cyrus} server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{setannotation}{mailbox, entry, attribute\optional{, ...}} - Set \samp{ANNOTATION}s for \var{mailbox}. - The method is non-standard, but is supported by the \samp{Cyrus} server. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{setquota}{root, limits} - Set the \samp{quota} \var{root}'s resource \var{limits}. - This method is part of the IMAP4 QUOTA extension defined in rfc2087. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{shutdown}{} - Close connection established in \code{open}. - You may override this method. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{socket}{} - Returns socket instance used to connect to server. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{sort}{sort_criteria, charset, search_criterion\optional{, ...}} - The \code{sort} command is a variant of \code{search} with sorting - semantics for the results. Returned data contains a space separated - list of matching message numbers. - - Sort has two arguments before the \var{search_criterion} - argument(s); a parenthesized list of \var{sort_criteria}, and the - searching \var{charset}. Note that unlike \code{search}, the - searching \var{charset} argument is mandatory. There is also a - \code{uid sort} command which corresponds to \code{sort} the way - that \code{uid search} corresponds to \code{search}. The - \code{sort} command first searches the mailbox for messages that - match the given searching criteria using the charset argument for - the interpretation of strings in the searching criteria. It then - returns the numbers of matching messages. - - This is an \samp{IMAP4rev1} extension command. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{status}{mailbox, names} - Request named status conditions for \var{mailbox}. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{store}{message_set, command, flag_list} - Alters flag dispositions for messages in mailbox. \var{command} is - specified by section 6.4.6 of \rfc{2060} as being one of "FLAGS", "+FLAGS", - or "-FLAGS", optionally with a suffix of ".SILENT". - - For example, to set the delete flag on all messages: - -\begin{verbatim} -typ, data = M.search(None, 'ALL') -for num in data[0].split(): - M.store(num, '+FLAGS', '\\Deleted') -M.expunge() -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{subscribe}{mailbox} - Subscribe to new mailbox. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{thread}{threading_algorithm, charset, - search_criterion\optional{, ...}} - The \code{thread} command is a variant of \code{search} with - threading semantics for the results. Returned data contains a space - separated list of thread members. - - Thread members consist of zero or more messages numbers, delimited - by spaces, indicating successive parent and child. - - Thread has two arguments before the \var{search_criterion} - argument(s); a \var{threading_algorithm}, and the searching - \var{charset}. Note that unlike \code{search}, the searching - \var{charset} argument is mandatory. There is also a \code{uid - thread} command which corresponds to \code{thread} the way that - \code{uid search} corresponds to \code{search}. The \code{thread} - command first searches the mailbox for messages that match the given - searching criteria using the charset argument for the interpretation - of strings in the searching criteria. It then returns the matching - messages threaded according to the specified threading algorithm. - - This is an \samp{IMAP4rev1} extension command. \versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{uid}{command, arg\optional{, ...}} - Execute command args with messages identified by UID, rather than - message number. Returns response appropriate to command. At least - one argument must be supplied; if none are provided, the server will - return an error and an exception will be raised. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{unsubscribe}{mailbox} - Unsubscribe from old mailbox. -\end{methoddesc} - -\begin{methoddesc}[IMAP4]{xatom}{name\optional{, arg\optional{, ...}}} - Allow simple extension commands notified by server in - \samp{CAPABILITY} response. -\end{methoddesc} - - -Instances of \class{IMAP4_SSL} have just one additional method: - -\begin{methoddesc}[IMAP4_SSL]{ssl}{} - Returns SSLObject instance used for the secure connection with the server. -\end{methoddesc} - - -The following attributes are defined on instances of \class{IMAP4}: - - -\begin{memberdesc}[IMAP4]{PROTOCOL_VERSION} -The most recent supported protocol in the -\samp{CAPABILITY} response from the server. -\end{memberdesc} - -\begin{memberdesc}[IMAP4]{debug} -Integer value to control debugging output. The initialize value is -taken from the module variable \code{Debug}. Values greater than -three trace each command. -\end{memberdesc} - - -\subsection{IMAP4 Example \label{imap4-example}} - -Here is a minimal example (without error checking) that opens a -mailbox and retrieves and prints all messages: - -\begin{verbatim} -import getpass, imaplib - -M = imaplib.IMAP4() -M.login(getpass.getuser(), getpass.getpass()) -M.select() -typ, data = M.search(None, 'ALL') -for num in data[0].split(): - typ, data = M.fetch(num, '(RFC822)') - print 'Message %s\n%s\n' % (num, data[0][1]) -M.close() -M.logout() -\end{verbatim} diff --git a/Doc/lib/libimghdr.tex b/Doc/lib/libimghdr.tex deleted file mode 100644 index 4a4f368..0000000 --- a/Doc/lib/libimghdr.tex +++ /dev/null @@ -1,60 +0,0 @@ -\section{\module{imghdr} --- - Determine the type of an image} - -\declaremodule{standard}{imghdr} -\modulesynopsis{Determine the type of image contained in a file or - byte stream.} - - -The \module{imghdr} module determines the type of image contained in a -file or byte stream. - -The \module{imghdr} module defines the following function: - - -\begin{funcdesc}{what}{filename\optional{, h}} -Tests the image data contained in the file named by \var{filename}, -and returns a string describing the image type. If optional \var{h} -is provided, the \var{filename} is ignored and \var{h} is assumed to -contain the byte stream to test. -\end{funcdesc} - -The following image types are recognized, as listed below with the -return value from \function{what()}: - -\begin{tableii}{l|l}{code}{Value}{Image format} - \lineii{'rgb'}{SGI ImgLib Files} - \lineii{'gif'}{GIF 87a and 89a Files} - \lineii{'pbm'}{Portable Bitmap Files} - \lineii{'pgm'}{Portable Graymap Files} - \lineii{'ppm'}{Portable Pixmap Files} - \lineii{'tiff'}{TIFF Files} - \lineii{'rast'}{Sun Raster Files} - \lineii{'xbm'}{X Bitmap Files} - \lineii{'jpeg'}{JPEG data in JFIF or Exif formats} - \lineii{'bmp'}{BMP files} - \lineii{'png'}{Portable Network Graphics} -\end{tableii} - -\versionadded[Exif detection]{2.5} - -You can extend the list of file types \module{imghdr} can recognize by -appending to this variable: - -\begin{datadesc}{tests} -A list of functions performing the individual tests. Each function -takes two arguments: the byte-stream and an open file-like object. -When \function{what()} is called with a byte-stream, the file-like -object will be \code{None}. - -The test function should return a string describing the image type if -the test succeeded, or \code{None} if it failed. -\end{datadesc} - -Example: - -\begin{verbatim} ->>> import imghdr ->>> imghdr.what('/tmp/bass.gif') -'gif' -\end{verbatim} diff --git a/Doc/lib/libimp.tex b/Doc/lib/libimp.tex deleted file mode 100644 index 6396605..0000000 --- a/Doc/lib/libimp.tex +++ /dev/null @@ -1,291 +0,0 @@ -\section{\module{imp} --- - Access the \keyword{import} internals} - -\declaremodule{builtin}{imp} -\modulesynopsis{Access the implementation of the \keyword{import} statement.} - - -This\stindex{import} module provides an interface to the mechanisms -used to implement the \keyword{import} statement. It defines the -following constants and functions: - - -\begin{funcdesc}{get_magic}{} -\indexii{file}{byte-code} -Return the magic string value used to recognize byte-compiled code -files (\file{.pyc} files). (This value may be different for each -Python version.) -\end{funcdesc} - -\begin{funcdesc}{get_suffixes}{} -Return a list of triples, each describing a particular type of module. -Each triple has the form \code{(\var{suffix}, \var{mode}, -\var{type})}, where \var{suffix} is a string to be appended to the -module name to form the filename to search for, \var{mode} is the mode -string to pass to the built-in \function{open()} function to open the -file (this can be \code{'r'} for text files or \code{'rb'} for binary -files), and \var{type} is the file type, which has one of the values -\constant{PY_SOURCE}, \constant{PY_COMPILED}, or -\constant{C_EXTENSION}, described below. -\end{funcdesc} - -\begin{funcdesc}{find_module}{name\optional{, path}} -Try to find the module \var{name} on the search path \var{path}. If -\var{path} is a list of directory names, each directory is searched -for files with any of the suffixes returned by \function{get_suffixes()} -above. Invalid names in the list are silently ignored (but all list -items must be strings). If \var{path} is omitted or \code{None}, the -list of directory names given by \code{sys.path} is searched, but -first it searches a few special places: it tries to find a built-in -module with the given name (\constant{C_BUILTIN}), then a frozen module -(\constant{PY_FROZEN}), and on some systems some other places are looked -in as well (on the Mac, it looks for a resource (\constant{PY_RESOURCE}); -on Windows, it looks in the registry which may point to a specific -file). - -If search is successful, the return value is a triple -\code{(\var{file}, \var{pathname}, \var{description})} where -\var{file} is an open file object positioned at the beginning, -\var{pathname} is the pathname of the -file found, and \var{description} is a triple as contained in the list -returned by \function{get_suffixes()} describing the kind of module found. -If the module does not live in a file, the returned \var{file} is -\code{None}, \var{filename} is the empty string, and the -\var{description} tuple contains empty strings for its suffix and -mode; the module type is as indicate in parentheses above. If the -search is unsuccessful, \exception{ImportError} is raised. Other -exceptions indicate problems with the arguments or environment. - -This function does not handle hierarchical module names (names -containing dots). In order to find \var{P}.\var{M}, that is, submodule -\var{M} of package \var{P}, use \function{find_module()} and -\function{load_module()} to find and load package \var{P}, and then use -\function{find_module()} with the \var{path} argument set to -\code{\var{P}.__path__}. When \var{P} itself has a dotted name, apply -this recipe recursively. -\end{funcdesc} - -\begin{funcdesc}{load_module}{name, file, filename, description} -Load a module that was previously found by \function{find_module()} (or by -an otherwise conducted search yielding compatible results). This -function does more than importing the module: if the module was -already imported, it will reload the module! The \var{name} argument -indicates the full module name (including the package name, if this is -a submodule of a package). The \var{file} argument is an open file, -and \var{filename} is the corresponding file name; these can be -\code{None} and \code{''}, respectively, when the module is not being -loaded from a file. The \var{description} argument is a tuple, as -would be returned by \function{get_suffixes()}, describing what kind -of module must be loaded. - -If the load is successful, the return value is the module object; -otherwise, an exception (usually \exception{ImportError}) is raised. - -\strong{Important:} the caller is responsible for closing the -\var{file} argument, if it was not \code{None}, even when an exception -is raised. This is best done using a \keyword{try} -... \keyword{finally} statement. -\end{funcdesc} - -\begin{funcdesc}{new_module}{name} -Return a new empty module object called \var{name}. This object is -\emph{not} inserted in \code{sys.modules}. -\end{funcdesc} - -\begin{funcdesc}{lock_held}{} -Return \code{True} if the import lock is currently held, else \code{False}. -On platforms without threads, always return \code{False}. - -On platforms with threads, a thread executing an import holds an internal -lock until the import is complete. -This lock blocks other threads from doing an import until the original -import completes, which in turn prevents other threads from seeing -incomplete module objects constructed by the original thread while in -the process of completing its import (and the imports, if any, -triggered by that). -\end{funcdesc} - -\begin{funcdesc}{acquire_lock}{} -Acquires the interpreter's import lock for the current thread. This lock -should be used by import hooks to ensure thread-safety when importing modules. -On platforms without threads, this function does nothing. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{release_lock}{} -Release the interpreter's import lock. -On platforms without threads, this function does nothing. -\versionadded{2.3} -\end{funcdesc} - -The following constants with integer values, defined in this module, -are used to indicate the search result of \function{find_module()}. - -\begin{datadesc}{PY_SOURCE} -The module was found as a source file. -\end{datadesc} - -\begin{datadesc}{PY_COMPILED} -The module was found as a compiled code object file. -\end{datadesc} - -\begin{datadesc}{C_EXTENSION} -The module was found as dynamically loadable shared library. -\end{datadesc} - -\begin{datadesc}{PY_RESOURCE} -The module was found as a Mac OS 9 resource. This value can only be -returned on a Mac OS 9 or earlier Macintosh. -\end{datadesc} - -\begin{datadesc}{PKG_DIRECTORY} -The module was found as a package directory. -\end{datadesc} - -\begin{datadesc}{C_BUILTIN} -The module was found as a built-in module. -\end{datadesc} - -\begin{datadesc}{PY_FROZEN} -The module was found as a frozen module (see \function{init_frozen()}). -\end{datadesc} - -The following constant and functions are obsolete; their functionality -is available through \function{find_module()} or \function{load_module()}. -They are kept around for backward compatibility: - -\begin{datadesc}{SEARCH_ERROR} -Unused. -\end{datadesc} - -\begin{funcdesc}{init_builtin}{name} -Initialize the built-in module called \var{name} and return its module -object along with storing it in \code{sys.modules}. If the module was already -initialized, it will be initialized \emph{again}. Re-initialization involves -the copying of the built-in module's \code{__dict__} from the cached -module over the module's entry in \code{sys.modules}. If there is no -built-in module called \var{name}, \code{None} is returned. -\end{funcdesc} - -\begin{funcdesc}{init_frozen}{name} -Initialize the frozen module called \var{name} and return its module -object. If the module was already initialized, it will be initialized -\emph{again}. If there is no frozen module called \var{name}, -\code{None} is returned. (Frozen modules are modules written in -Python whose compiled byte-code object is incorporated into a -custom-built Python interpreter by Python's \program{freeze} utility. -See \file{Tools/freeze/} for now.) -\end{funcdesc} - -\begin{funcdesc}{is_builtin}{name} -Return \code{1} if there is a built-in module called \var{name} which -can be initialized again. Return \code{-1} if there is a built-in -module called \var{name} which cannot be initialized again (see -\function{init_builtin()}). Return \code{0} if there is no built-in -module called \var{name}. -\end{funcdesc} - -\begin{funcdesc}{is_frozen}{name} -Return \code{True} if there is a frozen module (see -\function{init_frozen()}) called \var{name}, or \code{False} if there is -no such module. -\end{funcdesc} - -\begin{funcdesc}{load_compiled}{name, pathname, \optional{file}} -\indexii{file}{byte-code} -Load and initialize a module implemented as a byte-compiled code file -and return its module object. If the module was already initialized, -it will be initialized \emph{again}. The \var{name} argument is used -to create or access a module object. The \var{pathname} argument -points to the byte-compiled code file. The \var{file} -argument is the byte-compiled code file, open for reading in binary -mode, from the beginning. -It must currently be a real file object, not a -user-defined class emulating a file. -\end{funcdesc} - -\begin{funcdesc}{load_dynamic}{name, pathname\optional{, file}} -Load and initialize a module implemented as a dynamically loadable -shared library and return its module object. If the module was -already initialized, it will be initialized \emph{again}. -Re-initialization involves copying the \code{__dict__} attribute of the cached -instance of the module over the value used in the module cached in -\code{sys.modules}. The \var{pathname} argument must point to the shared -library. The \var{name} argument is used to construct the name of the -initialization function: an external C function called -\samp{init\var{name}()} in the shared library is called. The optional -\var{file} argument is ignored. (Note: using shared libraries is highly -system dependent, and not all systems support it.) -\end{funcdesc} - -\begin{funcdesc}{load_source}{name, pathname\optional{, file}} -Load and initialize a module implemented as a Python source file and -return its module object. If the module was already initialized, it -will be initialized \emph{again}. The \var{name} argument is used to -create or access a module object. The \var{pathname} argument points -to the source file. The \var{file} argument is the source -file, open for reading as text, from the beginning. -It must currently be a real file -object, not a user-defined class emulating a file. Note that if a -properly matching byte-compiled file (with suffix \file{.pyc} or -\file{.pyo}) exists, it will be used instead of parsing the given -source file. -\end{funcdesc} - -\begin{classdesc}{NullImporter}{path_string} -The \class{NullImporter} type is a \pep{302} import hook that handles -non-directory path strings by failing to find any modules. Calling this -type with an existing directory or empty string raises -\exception{ImportError}. Otherwise, a \class{NullImporter} instance is -returned. - -Python adds instances of this type to \code{sys.path_importer_cache} for -any path entries that are not directories and are not handled by any other -path hooks on \code{sys.path_hooks}. Instances have only one method: - -\begin{methoddesc}{find_module}{fullname \optional{, path}} -This method always returns \code{None}, indicating that the requested -module could not be found. -\end{methoddesc} - -\versionadded{2.5} -\end{classdesc} - -\subsection{Examples} -\label{examples-imp} - -The following function emulates what was the standard import statement -up to Python 1.4 (no hierarchical module names). (This -\emph{implementation} wouldn't work in that version, since -\function{find_module()} has been extended and -\function{load_module()} has been added in 1.4.) - -\begin{verbatim} -import imp -import sys - -def __import__(name, globals=None, locals=None, fromlist=None): - # Fast path: see if the module has already been imported. - try: - return sys.modules[name] - except KeyError: - pass - - # If any of the following calls raises an exception, - # there's a problem we can't handle -- let the caller handle it. - - fp, pathname, description = imp.find_module(name) - - try: - return imp.load_module(name, fp, pathname, description) - finally: - # Since we may exit via an exception, close fp explicitly. - if fp: - fp.close() -\end{verbatim} - -A more complete example that implements hierarchical module names and -includes a \function{reload()} function can be -found in the module \module{knee}\refmodindex{knee}. The -\module{knee} module can be found in \file{Demo/imputil/} in the -Python source distribution. diff --git a/Doc/lib/libinspect.tex b/Doc/lib/libinspect.tex deleted file mode 100644 index c9a63fc..0000000 --- a/Doc/lib/libinspect.tex +++ /dev/null @@ -1,391 +0,0 @@ -\section{\module{inspect} --- - Inspect live objects} - -\declaremodule{standard}{inspect} -\modulesynopsis{Extract information and source code from live objects.} -\moduleauthor{Ka-Ping Yee}{ping@lfw.org} -\sectionauthor{Ka-Ping Yee}{ping@lfw.org} - -\versionadded{2.1} - -The \module{inspect} module provides several useful functions -to help get information about live objects such as modules, -classes, methods, functions, tracebacks, frame objects, and -code objects. For example, it can help you examine the -contents of a class, retrieve the source code of a method, -extract and format the argument list for a function, or -get all the information you need to display a detailed traceback. - -There are four main kinds of services provided by this module: -type checking, getting source code, inspecting classes -and functions, and examining the interpreter stack. - -\subsection{Types and members - \label{inspect-types}} - -The \function{getmembers()} function retrieves the members -of an object such as a class or module. -The eleven functions whose names begin with ``is'' are mainly -provided as convenient choices for the second argument to -\function{getmembers()}. They also help you determine when -you can expect to find the following special attributes: - -\begin{tableiv}{c|l|l|c}{}{Type}{Attribute}{Description}{Notes} - \lineiv{module}{__doc__}{documentation string}{} - \lineiv{}{__file__}{filename (missing for built-in modules)}{} - \hline - \lineiv{class}{__doc__}{documentation string}{} - \lineiv{}{__module__}{name of module in which this class was defined}{} - \hline - \lineiv{method}{__doc__}{documentation string}{} - \lineiv{}{__name__}{name with which this method was defined}{} - \lineiv{}{im_class}{class object that asked for this method}{(1)} - \lineiv{}{im_func}{function object containing implementation of method}{} - \lineiv{}{im_self}{instance to which this method is bound, or \code{None}}{} - \hline - \lineiv{function}{__doc__}{documentation string}{} - \lineiv{}{__name__}{name with which this function was defined}{} - \lineiv{}{__code__}{code object containing compiled function bytecode}{} - \lineiv{}{__defaults__}{tuple of any default values for arguments}{} - \lineiv{}{__globals__}{global namespace in which this function was defined}{} - \hline - \lineiv{traceback}{tb_frame}{frame object at this level}{} - \lineiv{}{tb_lasti}{index of last attempted instruction in bytecode}{} - \lineiv{}{tb_lineno}{current line number in Python source code}{} - \lineiv{}{tb_next}{next inner traceback object (called by this level)}{} - \hline - \lineiv{frame}{f_back}{next outer frame object (this frame's caller)}{} - \lineiv{}{f_builtins}{built-in namespace seen by this frame}{} - \lineiv{}{f_code}{code object being executed in this frame}{} - \lineiv{}{f_exc_traceback}{traceback if raised in this frame, or \code{None}}{} - \lineiv{}{f_exc_type}{exception type if raised in this frame, or \code{None}}{} - \lineiv{}{f_exc_value}{exception value if raised in this frame, or \code{None}}{} - \lineiv{}{f_globals}{global namespace seen by this frame}{} - \lineiv{}{f_lasti}{index of last attempted instruction in bytecode}{} - \lineiv{}{f_lineno}{current line number in Python source code}{} - \lineiv{}{f_locals}{local namespace seen by this frame}{} - \lineiv{}{f_restricted}{0 or 1 if frame is in restricted execution mode}{} - \lineiv{}{f_trace}{tracing function for this frame, or \code{None}}{} - \hline - \lineiv{code}{co_argcount}{number of arguments (not including * or ** args)}{} - \lineiv{}{co_code}{string of raw compiled bytecode}{} - \lineiv{}{co_consts}{tuple of constants used in the bytecode}{} - \lineiv{}{co_filename}{name of file in which this code object was created}{} - \lineiv{}{co_firstlineno}{number of first line in Python source code}{} - \lineiv{}{co_flags}{bitmap: 1=optimized \code{|} 2=newlocals \code{|} 4=*arg \code{|} 8=**arg}{} - \lineiv{}{co_lnotab}{encoded mapping of line numbers to bytecode indices}{} - \lineiv{}{co_name}{name with which this code object was defined}{} - \lineiv{}{co_names}{tuple of names of local variables}{} - \lineiv{}{co_nlocals}{number of local variables}{} - \lineiv{}{co_stacksize}{virtual machine stack space required}{} - \lineiv{}{co_varnames}{tuple of names of arguments and local variables}{} - \hline - \lineiv{builtin}{__doc__}{documentation string}{} - \lineiv{}{__name__}{original name of this function or method}{} - \lineiv{}{__self__}{instance to which a method is bound, or \code{None}}{} -\end{tableiv} - -\noindent -Note: -\begin{description} -\item[(1)] -\versionchanged[\member{im_class} used to refer to the class that - defined the method]{2.2} -\end{description} - - -\begin{funcdesc}{getmembers}{object\optional{, predicate}} - Return all the members of an object in a list of (name, value) pairs - sorted by name. If the optional \var{predicate} argument is supplied, - only members for which the predicate returns a true value are included. -\end{funcdesc} - -\begin{funcdesc}{getmoduleinfo}{path} - Return a tuple of values that describe how Python will interpret the - file identified by \var{path} if it is a module, or \code{None} if - it would not be identified as a module. The return tuple is - \code{(\var{name}, \var{suffix}, \var{mode}, \var{mtype})}, where - \var{name} is the name of the module without the name of any - enclosing package, \var{suffix} is the trailing part of the file - name (which may not be a dot-delimited extension), \var{mode} is the - \function{open()} mode that would be used (\code{'r'} or - \code{'rb'}), and \var{mtype} is an integer giving the type of the - module. \var{mtype} will have a value which can be compared to the - constants defined in the \refmodule{imp} module; see the - documentation for that module for more information on module types. -\end{funcdesc} - -\begin{funcdesc}{getmodulename}{path} - Return the name of the module named by the file \var{path}, without - including the names of enclosing packages. This uses the same - algorithm as the interpreter uses when searching for modules. If - the name cannot be matched according to the interpreter's rules, - \code{None} is returned. -\end{funcdesc} - -\begin{funcdesc}{ismodule}{object} - Return true if the object is a module. -\end{funcdesc} - -\begin{funcdesc}{isclass}{object} - Return true if the object is a class. -\end{funcdesc} - -\begin{funcdesc}{ismethod}{object} - Return true if the object is a method. -\end{funcdesc} - -\begin{funcdesc}{isfunction}{object} - Return true if the object is a Python function or unnamed (lambda) function. -\end{funcdesc} - -\begin{funcdesc}{istraceback}{object} - Return true if the object is a traceback. -\end{funcdesc} - -\begin{funcdesc}{isframe}{object} - Return true if the object is a frame. -\end{funcdesc} - -\begin{funcdesc}{iscode}{object} - Return true if the object is a code. -\end{funcdesc} - -\begin{funcdesc}{isbuiltin}{object} - Return true if the object is a built-in function. -\end{funcdesc} - -\begin{funcdesc}{isroutine}{object} - Return true if the object is a user-defined or built-in function or method. -\end{funcdesc} - -\begin{funcdesc}{ismethoddescriptor}{object} - Return true if the object is a method descriptor, but not if ismethod() or - isclass() or isfunction() are true. - - This is new as of Python 2.2, and, for example, is true of int.__add__. - An object passing this test has a __get__ attribute but not a __set__ - attribute, but beyond that the set of attributes varies. __name__ is - usually sensible, and __doc__ often is. - - Methods implemented via descriptors that also pass one of the other - tests return false from the ismethoddescriptor() test, simply because - the other tests promise more -- you can, e.g., count on having the - im_func attribute (etc) when an object passes ismethod(). -\end{funcdesc} - -\begin{funcdesc}{isdatadescriptor}{object} - Return true if the object is a data descriptor. - - Data descriptors have both a __get__ and a __set__ attribute. Examples are - properties (defined in Python), getsets, and members. The latter two are - defined in C and there are more specific tests available for those types, - which is robust across Python implementations. Typically, data descriptors - will also have __name__ and __doc__ attributes (properties, getsets, and - members have both of these attributes), but this is not guaranteed. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{isgetsetdescriptor}{object} - Return true if the object is a getset descriptor. - - getsets are attributes defined in extension modules via \code{PyGetSetDef} - structures. For Python implementations without such types, this method will - always return \code{False}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{ismemberdescriptor}{object} - Return true if the object is a member descriptor. - - Member descriptors are attributes defined in extension modules via - \code{PyMemberDef} structures. For Python implementations without such - types, this method will always return \code{False}. -\versionadded{2.5} -\end{funcdesc} - -\subsection{Retrieving source code - \label{inspect-source}} - -\begin{funcdesc}{getdoc}{object} - Get the documentation string for an object. - All tabs are expanded to spaces. To clean up docstrings that are - indented to line up with blocks of code, any whitespace than can be - uniformly removed from the second line onwards is removed. -\end{funcdesc} - -\begin{funcdesc}{getcomments}{object} - Return in a single string any lines of comments immediately preceding - the object's source code (for a class, function, or method), or at the - top of the Python source file (if the object is a module). -\end{funcdesc} - -\begin{funcdesc}{getfile}{object} - Return the name of the (text or binary) file in which an object was - defined. This will fail with a \exception{TypeError} if the object - is a built-in module, class, or function. -\end{funcdesc} - -\begin{funcdesc}{getmodule}{object} - Try to guess which module an object was defined in. -\end{funcdesc} - -\begin{funcdesc}{getsourcefile}{object} - Return the name of the Python source file in which an object was - defined. This will fail with a \exception{TypeError} if the object - is a built-in module, class, or function. -\end{funcdesc} - -\begin{funcdesc}{getsourcelines}{object} - Return a list of source lines and starting line number for an object. - The argument may be a module, class, method, function, traceback, frame, - or code object. The source code is returned as a list of the lines - corresponding to the object and the line number indicates where in the - original source file the first line of code was found. An - \exception{IOError} is raised if the source code cannot be retrieved. -\end{funcdesc} - -\begin{funcdesc}{getsource}{object} - Return the text of the source code for an object. - The argument may be a module, class, method, function, traceback, frame, - or code object. The source code is returned as a single string. An - \exception{IOError} is raised if the source code cannot be retrieved. -\end{funcdesc} - -\subsection{Classes and functions - \label{inspect-classes-functions}} - -\begin{funcdesc}{getclasstree}{classes\optional{, unique}} - Arrange the given list of classes into a hierarchy of nested lists. - Where a nested list appears, it contains classes derived from the class - whose entry immediately precedes the list. Each entry is a 2-tuple - containing a class and a tuple of its base classes. If the \var{unique} - argument is true, exactly one entry appears in the returned structure - for each class in the given list. Otherwise, classes using multiple - inheritance and their descendants will appear multiple times. -\end{funcdesc} - -\begin{funcdesc}{getargspec}{func} - Get the names and default values of a function's arguments. - A tuple of four things is returned: \code{(\var{args}, - \var{varargs}, \var{varkw}, \var{defaults})}. - \var{args} is a list of the argument names (it may contain nested lists). - \var{varargs} and \var{varkw} are the names of the \code{*} and - \code{**} arguments or \code{None}. - \var{defaults} is a tuple of default argument values or None if there are no - default arguments; if this tuple has \var{n} elements, they correspond to - the last \var{n} elements listed in \var{args}. -\end{funcdesc} - -\begin{funcdesc}{getargvalues}{frame} - Get information about arguments passed into a particular frame. - A tuple of four things is returned: \code{(\var{args}, - \var{varargs}, \var{varkw}, \var{locals})}. - \var{args} is a list of the argument names (it may contain nested - lists). - \var{varargs} and \var{varkw} are the names of the \code{*} and - \code{**} arguments or \code{None}. - \var{locals} is the locals dictionary of the given frame. -\end{funcdesc} - -\begin{funcdesc}{formatargspec}{args\optional{, varargs, varkw, defaults, - formatarg, formatvarargs, formatvarkw, formatvalue, join}} - - Format a pretty argument spec from the four values returned by - \function{getargspec()}. The format* arguments are the - corresponding optional formatting functions that are called to turn - names and values into strings. -\end{funcdesc} - -\begin{funcdesc}{formatargvalues}{args\optional{, varargs, varkw, locals, - formatarg, formatvarargs, formatvarkw, formatvalue, join}} - Format a pretty argument spec from the four values returned by - \function{getargvalues()}. The format* arguments are the - corresponding optional formatting functions that are called to turn - names and values into strings. -\end{funcdesc} - -\begin{funcdesc}{getmro}{cls} - Return a tuple of class cls's base classes, including cls, in - method resolution order. No class appears more than once in this tuple. - Note that the method resolution order depends on cls's type. Unless a - very peculiar user-defined metatype is in use, cls will be the first - element of the tuple. -\end{funcdesc} - -\subsection{The interpreter stack - \label{inspect-stack}} - -When the following functions return ``frame records,'' each record -is a tuple of six items: the frame object, the filename, -the line number of the current line, the function name, a list of -lines of context from the source code, and the index of the current -line within that list. - -\begin{notice}[warning] -Keeping references to frame objects, as found in -the first element of the frame records these functions return, can -cause your program to create reference cycles. Once a reference cycle -has been created, the lifespan of all objects which can be accessed -from the objects which form the cycle can become much longer even if -Python's optional cycle detector is enabled. If such cycles must be -created, it is important to ensure they are explicitly broken to avoid -the delayed destruction of objects and increased memory consumption -which occurs. - -Though the cycle detector will catch these, destruction of the frames -(and local variables) can be made deterministic by removing the cycle -in a \keyword{finally} clause. This is also important if the cycle -detector was disabled when Python was compiled or using -\function{\refmodule{gc}.disable()}. For example: - -\begin{verbatim} -def handle_stackframe_without_leak(): - frame = inspect.currentframe() - try: - # do something with the frame - finally: - del frame -\end{verbatim} -\end{notice} - -The optional \var{context} argument supported by most of these -functions specifies the number of lines of context to return, which -are centered around the current line. - -\begin{funcdesc}{getframeinfo}{frame\optional{, context}} - Get information about a frame or traceback object. A 5-tuple - is returned, the last five elements of the frame's frame record. -\end{funcdesc} - -\begin{funcdesc}{getouterframes}{frame\optional{, context}} - Get a list of frame records for a frame and all outer frames. These - frames represent the calls that lead to the creation of \var{frame}. - The first entry in the returned list represents \var{frame}; the - last entry represents the outermost call on \var{frame}'s stack. -\end{funcdesc} - -\begin{funcdesc}{getinnerframes}{traceback\optional{, context}} - Get a list of frame records for a traceback's frame and all inner - frames. These frames represent calls made as a consequence of - \var{frame}. The first entry in the list represents - \var{traceback}; the last entry represents where the exception was - raised. -\end{funcdesc} - -\begin{funcdesc}{currentframe}{} - Return the frame object for the caller's stack frame. -\end{funcdesc} - -\begin{funcdesc}{stack}{\optional{context}} - Return a list of frame records for the caller's stack. The first - entry in the returned list represents the caller; the last entry - represents the outermost call on the stack. -\end{funcdesc} - -\begin{funcdesc}{trace}{\optional{context}} - Return a list of frame records for the stack between the current - frame and the frame in which an exception currently being handled - was raised in. The first entry in the list represents the caller; - the last entry represents where the exception was raised. -\end{funcdesc} diff --git a/Doc/lib/libintro.tex b/Doc/lib/libintro.tex deleted file mode 100644 index 62434cd..0000000 --- a/Doc/lib/libintro.tex +++ /dev/null @@ -1,53 +0,0 @@ -\chapter{Introduction} -\label{intro} - -The ``Python library'' contains several different kinds of components. - -It contains data types that would normally be considered part of the -``core'' of a language, such as numbers and lists. For these types, -the Python language core defines the form of literals and places some -constraints on their semantics, but does not fully define the -semantics. (On the other hand, the language core does define -syntactic properties like the spelling and priorities of operators.) - -The library also contains built-in functions and exceptions --- -objects that can be used by all Python code without the need of an -\keyword{import} statement. Some of these are defined by the core -language, but many are not essential for the core semantics and are -only described here. - -The bulk of the library, however, consists of a collection of modules. -There are many ways to dissect this collection. Some modules are -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, 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 available 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 -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 -each chapter is roughly from most relevant to least important. - -This means that if you start reading this manual from the start, and -skip to the next chapter when you get bored, you will get a reasonable -overview of the available modules and application areas that are -supported by the Python library. Of course, you don't \emph{have} to -read it like a novel --- you can also browse the table of contents (in -front of the manual), or look for a specific function, module or term -in the index (in the back). And finally, if you enjoy learning about -random subjects, you choose a random page number (see module -\refmodule{random}) and read a section or two. Regardless of the -order in which you read the sections of this manual, it helps to start -with chapter \ref{builtin}, ``Built-in Types, Exceptions and -Functions,'' as the remainder of the manual assumes familiarity with -this material. - -Let the show begin! diff --git a/Doc/lib/libitertools.tex b/Doc/lib/libitertools.tex deleted file mode 100644 index b4784a8..0000000 --- a/Doc/lib/libitertools.tex +++ /dev/null @@ -1,575 +0,0 @@ -\section{\module{itertools} --- - Functions creating iterators for efficient looping} - -\declaremodule{standard}{itertools} -\modulesynopsis{Functions creating iterators for efficient looping.} -\moduleauthor{Raymond Hettinger}{python@rcn.com} -\sectionauthor{Raymond Hettinger}{python@rcn.com} -\versionadded{2.3} - - -This module implements a number of iterator building blocks inspired -by constructs from the Haskell and SML programming languages. Each -has been recast in a form suitable for Python. - -The module standardizes a core set of fast, memory efficient tools -that are useful by themselves or in combination. Standardization helps -avoid the readability and reliability problems which arise when many -different individuals create their own slightly varying implementations, -each with their own quirks and naming conventions. - -The tools are designed to combine readily with one another. This makes -it easy to construct more specialized tools succinctly and efficiently -in pure Python. - -For instance, SML provides a tabulation tool: \code{tabulate(f)} -which produces a sequence \code{f(0), f(1), ...}. This toolbox -provides \function{imap()} and \function{count()} which can be combined -to form \code{imap(f, count())} and produce an equivalent result. - -Likewise, the functional tools are designed to work well with the -high-speed functions provided by the \refmodule{operator} module. - -The module author welcomes suggestions for other basic building blocks -to be added to future versions of the module. - -Whether cast in pure python form or compiled code, tools that use iterators -are more memory efficient (and faster) than their list based counterparts. -Adopting the principles of just-in-time manufacturing, they create -data when and where needed instead of consuming memory with the -computer equivalent of ``inventory''. - -The performance advantage of iterators becomes more acute as the number -of elements increases -- at some point, lists grow large enough to -severely impact memory cache performance and start running slowly. - -\begin{seealso} - \seetext{The Standard ML Basis Library, - \citetitle[http://www.standardml.org/Basis/] - {The Standard ML Basis Library}.} - - \seetext{Haskell, A Purely Functional Language, - \citetitle[http://www.haskell.org/definition/] - {Definition of Haskell and the Standard Libraries}.} -\end{seealso} - - -\subsection{Itertool functions \label{itertools-functions}} - -The following module functions all construct and return iterators. -Some provide streams of infinite length, so they should only be accessed -by functions or loops that truncate the stream. - -\begin{funcdesc}{chain}{*iterables} - Make an iterator that returns elements from the first iterable until - it is exhausted, then proceeds to the next iterable, until all of the - iterables are exhausted. Used for treating consecutive sequences as - a single sequence. Equivalent to: - - \begin{verbatim} - def chain(*iterables): - for it in iterables: - for element in it: - yield element - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{count}{\optional{n}} - Make an iterator that returns consecutive integers starting with \var{n}. - If not specified \var{n} defaults to zero. - Does not currently support python long integers. Often used as an - argument to \function{imap()} to generate consecutive data points. - Also, used with \function{izip()} to add sequence numbers. Equivalent to: - - \begin{verbatim} - def count(n=0): - while True: - yield n - n += 1 - \end{verbatim} - - Note, \function{count()} does not check for overflow and will return - negative numbers after exceeding \code{sys.maxint}. This behavior - may change in the future. -\end{funcdesc} - -\begin{funcdesc}{cycle}{iterable} - Make an iterator returning elements from the iterable and saving a - copy of each. When the iterable is exhausted, return elements from - the saved copy. Repeats indefinitely. Equivalent to: - - \begin{verbatim} - def cycle(iterable): - saved = [] - for element in iterable: - yield element - saved.append(element) - while saved: - for element in saved: - yield element - \end{verbatim} - - Note, this member of the toolkit may require significant - auxiliary storage (depending on the length of the iterable). -\end{funcdesc} - -\begin{funcdesc}{dropwhile}{predicate, iterable} - Make an iterator that drops elements from the iterable as long as - the predicate is true; afterwards, returns every element. Note, - the iterator does not produce \emph{any} output until the predicate - first becomes false, so it may have a lengthy start-up time. Equivalent to: - - \begin{verbatim} - def dropwhile(predicate, iterable): - iterable = iter(iterable) - for x in iterable: - if not predicate(x): - yield x - break - for x in iterable: - yield x - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{groupby}{iterable\optional{, key}} - Make an iterator that returns consecutive keys and groups from the - \var{iterable}. The \var{key} is a function computing a key value for each - element. If not specified or is \code{None}, \var{key} defaults to an - identity function and returns the element unchanged. Generally, the - iterable needs to already be sorted on the same key function. - - The operation of \function{groupby()} is similar to the \code{uniq} filter - in \UNIX{}. It generates a break or new group every time the value - of the key function changes (which is why it is usually necessary - to have sorted the data using the same key function). That behavior - differs from SQL's GROUP BY which aggregates common elements regardless - of their input order. - - The returned group is itself an iterator that shares the underlying - iterable with \function{groupby()}. Because the source is shared, when - the \function{groupby} object is advanced, the previous group is no - longer visible. So, if that data is needed later, it should be stored - as a list: - - \begin{verbatim} - groups = [] - uniquekeys = [] - data = sorted(data, key=keyfunc) - for k, g in groupby(data, keyfunc): - groups.append(list(g)) # Store group iterator as a list - uniquekeys.append(k) - \end{verbatim} - - \function{groupby()} is equivalent to: - - \begin{verbatim} - class groupby(object): - def __init__(self, iterable, key=None): - if key is None: - key = lambda x: x - self.keyfunc = key - self.it = iter(iterable) - self.tgtkey = self.currkey = self.currvalue = [] - def __iter__(self): - return self - def __next__(self): - while self.currkey == self.tgtkey: - self.currvalue = next(self.it) # Exit on StopIteration - self.currkey = self.keyfunc(self.currvalue) - self.tgtkey = self.currkey - return (self.currkey, self._grouper(self.tgtkey)) - def _grouper(self, tgtkey): - while self.currkey == tgtkey: - yield self.currvalue - self.currvalue = next(self.it) # Exit on StopIteration - self.currkey = self.keyfunc(self.currvalue) - \end{verbatim} - \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{ifilter}{predicate, iterable} - Make an iterator that filters elements from iterable returning only - those for which the predicate is \code{True}. - If \var{predicate} is \code{None}, return the items that are true. - Equivalent to: - - \begin{verbatim} - def ifilter(predicate, iterable): - if predicate is None: - predicate = bool - for x in iterable: - if predicate(x): - yield x - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{ifilterfalse}{predicate, iterable} - Make an iterator that filters elements from iterable returning only - those for which the predicate is \code{False}. - If \var{predicate} is \code{None}, return the items that are false. - Equivalent to: - - \begin{verbatim} - def ifilterfalse(predicate, iterable): - if predicate is None: - predicate = bool - for x in iterable: - if not predicate(x): - yield x - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{imap}{function, *iterables} - Make an iterator that computes the function using arguments from - each of the iterables. If \var{function} is set to \code{None}, then - \function{imap()} returns the arguments as a tuple. Like - \function{map()} but stops when the shortest iterable is exhausted - instead of filling in \code{None} for shorter iterables. The reason - for the difference is that infinite iterator arguments are typically - an error for \function{map()} (because the output is fully evaluated) - but represent a common and useful way of supplying arguments to - \function{imap()}. - Equivalent to: - - \begin{verbatim} - def imap(function, *iterables): - iterables = map(iter, iterables) - while True: - args = [next(i) for i in iterables] - if function is None: - yield tuple(args) - else: - yield function(*args) - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{islice}{iterable, \optional{start,} stop \optional{, step}} - Make an iterator that returns selected elements from the iterable. - If \var{start} is non-zero, then elements from the iterable are skipped - until start is reached. Afterward, elements are returned consecutively - unless \var{step} is set higher than one which results in items being - skipped. If \var{stop} is \code{None}, then iteration continues until - the iterator is exhausted, if at all; otherwise, it stops at the specified - position. Unlike regular slicing, - \function{islice()} does not support negative values for \var{start}, - \var{stop}, or \var{step}. Can be used to extract related fields - from data where the internal structure has been flattened (for - example, a multi-line report may list a name field on every - third line). Equivalent to: - - \begin{verbatim} - def islice(iterable, *args): - s = slice(*args) - it = iter(range(s.start or 0, s.stop or sys.maxint, s.step or 1)) - nexti = next(it) - for i, element in enumerate(iterable): - if i == nexti: - yield element - nexti = next(it) - \end{verbatim} - - If \var{start} is \code{None}, then iteration starts at zero. - If \var{step} is \code{None}, then the step defaults to one. - \versionchanged[accept \code{None} values for default \var{start} and - \var{step}]{2.5} -\end{funcdesc} - -\begin{funcdesc}{izip}{*iterables} - Make an iterator that aggregates elements from each of the iterables. - Like \function{zip()} except that it returns an iterator instead of - a list. Used for lock-step iteration over several iterables at a - time. Equivalent to: - - \begin{verbatim} - def izip(*iterables): - iterables = map(iter, iterables) - while iterables: - result = [next(it) for it in iterables] - yield tuple(result) - \end{verbatim} - - \versionchanged[When no iterables are specified, returns a zero length - iterator instead of raising a \exception{TypeError} - exception]{2.4} - - Note, the left-to-right evaluation order of the iterables is guaranteed. - This makes possible an idiom for clustering a data series into n-length - groups using \samp{izip(*[iter(s)]*n)}. For data that doesn't fit - n-length groups exactly, the last tuple can be pre-padded with fill - values using \samp{izip(*[chain(s, [None]*(n-1))]*n)}. - - Note, when \function{izip()} is used with unequal length inputs, subsequent - iteration over the longer iterables cannot reliably be continued after - \function{izip()} terminates. Potentially, up to one entry will be missing - from each of the left-over iterables. This occurs because a value is fetched - from each iterator in-turn, but the process ends when one of the iterators - terminates. This leaves the last fetched values in limbo (they cannot be - returned in a final, incomplete tuple and they are cannot be pushed back - into the iterator for retrieval with \code{next(it)}). In general, - \function{izip()} should only be used with unequal length inputs when you - don't care about trailing, unmatched values from the longer iterables. -\end{funcdesc} - -\begin{funcdesc}{izip_longest}{*iterables\optional{, fillvalue}} - Make an iterator that aggregates elements from each of the iterables. - If the iterables are of uneven length, missing values are filled-in - with \var{fillvalue}. Iteration continues until the longest iterable - is exhausted. Equivalent to: - - \begin{verbatim} - def izip_longest(*args, **kwds): - fillvalue = kwds.get('fillvalue') - def sentinel(counter = ([fillvalue]*(len(args)-1)).pop): - yield counter() # yields the fillvalue, or raises IndexError - fillers = repeat(fillvalue) - iters = [chain(it, sentinel(), fillers) for it in args] - try: - for tup in izip(*iters): - yield tup - except IndexError: - pass - \end{verbatim} - - If one of the iterables is potentially infinite, then the - \function{izip_longest()} function should be wrapped with something - that limits the number of calls (for example \function{islice()} or - \function{take()}). - \versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{repeat}{object\optional{, times}} - Make an iterator that returns \var{object} over and over again. - Runs indefinitely unless the \var{times} argument is specified. - Used as argument to \function{imap()} for invariant parameters - to the called function. Also used with \function{izip()} to create - an invariant part of a tuple record. Equivalent to: - - \begin{verbatim} - def repeat(object, times=None): - if times is None: - while True: - yield object - else: - for i in range(times): - yield object - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{starmap}{function, iterable} - Make an iterator that computes the function using arguments tuples - obtained from the iterable. Used instead of \function{imap()} when - argument parameters are already grouped in tuples from a single iterable - (the data has been ``pre-zipped''). The difference between - \function{imap()} and \function{starmap()} parallels the distinction - between \code{function(a,b)} and \code{function(*c)}. - Equivalent to: - - \begin{verbatim} - def starmap(function, iterable): - iterable = iter(iterable) - while True: - yield function(*next(iterable)) - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{takewhile}{predicate, iterable} - Make an iterator that returns elements from the iterable as long as - the predicate is true. Equivalent to: - - \begin{verbatim} - def takewhile(predicate, iterable): - for x in iterable: - if predicate(x): - yield x - else: - break - \end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{tee}{iterable\optional{, n=2}} - Return \var{n} independent iterators from a single iterable. - The case where \code{n==2} is equivalent to: - - \begin{verbatim} - def tee(iterable): - def gen(next, data={}, cnt=[0]): - for i in count(): - if i == cnt[0]: - item = data[i] = next() - cnt[0] += 1 - else: - item = data.pop(i) - yield item - it = iter(iterable) - return (gen(it.__next__), gen(it.__next__)) - \end{verbatim} - - Note, once \function{tee()} has made a split, the original \var{iterable} - should not be used anywhere else; otherwise, the \var{iterable} could get - advanced without the tee objects being informed. - - Note, this member of the toolkit may require significant auxiliary - storage (depending on how much temporary data needs to be stored). - In general, if one iterator is going to use most or all of the data before - the other iterator, it is faster to use \function{list()} instead of - \function{tee()}. - \versionadded{2.4} -\end{funcdesc} - - -\subsection{Examples \label{itertools-example}} - -The following examples show common uses for each tool and -demonstrate ways they can be combined. - -\begin{verbatim} - ->>> amounts = [120.15, 764.05, 823.14] ->>> for checknum, amount in izip(count(1200), amounts): -... print 'Check %d is for $%.2f' % (checknum, amount) -... -Check 1200 is for $120.15 -Check 1201 is for $764.05 -Check 1202 is for $823.14 - ->>> import operator ->>> for cube in imap(operator.pow, range(1,5), repeat(3)): -... print cube -... -1 -8 -27 -64 - ->>> reportlines = ['EuroPython', 'Roster', '', 'alex', '', 'laura', - '', 'martin', '', 'walter', '', 'mark'] ->>> for name in islice(reportlines, 3, None, 2): -... print name.title() -... -Alex -Laura -Martin -Walter -Mark - -# Show a dictionary sorted and grouped by value ->>> from operator import itemgetter ->>> d = dict(a=1, b=2, c=1, d=2, e=1, f=2, g=3) ->>> di = sorted(d.iteritems(), key=itemgetter(1)) ->>> for k, g in groupby(di, key=itemgetter(1)): -... print k, map(itemgetter(0), g) -... -1 ['a', 'c', 'e'] -2 ['b', 'd', 'f'] -3 ['g'] - -# Find runs of consecutive numbers using groupby. The key to the solution -# is differencing with a range so that consecutive numbers all appear in -# same group. ->>> data = [ 1, 4,5,6, 10, 15,16,17,18, 22, 25,26,27,28] ->>> for k, g in groupby(enumerate(data), lambda t:t[0]-t[1]): -... print map(operator.itemgetter(1), g) -... -[1] -[4, 5, 6] -[10] -[15, 16, 17, 18] -[22] -[25, 26, 27, 28] - -\end{verbatim} - - -\subsection{Recipes \label{itertools-recipes}} - -This section shows recipes for creating an extended toolset using the -existing itertools as building blocks. - -The extended tools offer the same high performance as the underlying -toolset. The superior memory performance is kept by processing elements one -at a time rather than bringing the whole iterable into memory all at once. -Code volume is kept small by linking the tools together in a functional style -which helps eliminate temporary variables. High speed is retained by -preferring ``vectorized'' building blocks over the use of for-loops and -generators which incur interpreter overhead. - - -\begin{verbatim} -def take(n, seq): - return list(islice(seq, n)) - -def enumerate(iterable): - return izip(count(), iterable) - -def tabulate(function): - "Return function(0), function(1), ..." - return imap(function, count()) - -def iteritems(mapping): - return izip(mapping.iterkeys(), mapping.itervalues()) - -def nth(iterable, n): - "Returns the nth item or raise StopIteration" - return islice(iterable, n, None).next() - -def all(seq, pred=None): - "Returns True if pred(x) is true for every element in the iterable" - for elem in ifilterfalse(pred, seq): - return False - return True - -def any(seq, pred=None): - "Returns True if pred(x) is true for at least one element in the iterable" - for elem in ifilter(pred, seq): - return True - return False - -def no(seq, pred=None): - "Returns True if pred(x) is false for every element in the iterable" - for elem in ifilter(pred, seq): - return False - return True - -def quantify(seq, pred=None): - "Count how many times the predicate is true in the sequence" - return sum(imap(pred, seq)) - -def padnone(seq): - """Returns the sequence elements and then returns None indefinitely. - - Useful for emulating the behavior of the built-in map() function. - """ - return chain(seq, repeat(None)) - -def ncycles(seq, n): - "Returns the sequence elements n times" - return chain(*repeat(seq, n)) - -def dotproduct(vec1, vec2): - return sum(imap(operator.mul, vec1, vec2)) - -def flatten(listOfLists): - return list(chain(*listOfLists)) - -def repeatfunc(func, times=None, *args): - """Repeat calls to func with specified arguments. - - Example: repeatfunc(random.random) - """ - if times is None: - return starmap(func, repeat(args)) - else: - return starmap(func, repeat(args, times)) - -def pairwise(iterable): - "s -> (s0,s1), (s1,s2), (s2, s3), ..." - a, b = tee(iterable) - next(b, None) - return izip(a, b) - -def grouper(n, iterable, padvalue=None): - "grouper(3, 'abcdefg', 'x') --> ('a','b','c'), ('d','e','f'), ('g','x','x')" - return izip(*[chain(iterable, repeat(padvalue, n-1))]*n) - - -\end{verbatim} diff --git a/Doc/lib/libkeyword.tex b/Doc/lib/libkeyword.tex deleted file mode 100644 index 0c07cec..0000000 --- a/Doc/lib/libkeyword.tex +++ /dev/null @@ -1,20 +0,0 @@ -\section{\module{keyword} --- - Testing for Python keywords} - -\declaremodule{standard}{keyword} -\modulesynopsis{Test whether a string is a keyword in Python.} - - -This module allows a Python program to determine if a string is a -keyword. - -\begin{funcdesc}{iskeyword}{s} -Return true if \var{s} is a Python keyword. -\end{funcdesc} - -\begin{datadesc}{kwlist} -Sequence containing all the keywords defined for the interpreter. If -any keywords are defined to only be active when particular -\module{__future__} statements are in effect, these will be included -as well. -\end{datadesc} diff --git a/Doc/lib/liblinecache.tex b/Doc/lib/liblinecache.tex deleted file mode 100644 index 72c7743..0000000 --- a/Doc/lib/liblinecache.tex +++ /dev/null @@ -1,50 +0,0 @@ -\section{\module{linecache} --- - Random access to text lines} - -\declaremodule{standard}{linecache} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{This module provides random access to individual lines - from text files.} - - -The \module{linecache} module allows one to get any line from any file, -while attempting to optimize internally, using a cache, the common case -where many lines are read from a single file. This is used by the -\refmodule{traceback} module to retrieve source lines for inclusion in -the formatted traceback. - -The \module{linecache} module defines the following functions: - -\begin{funcdesc}{getline}{filename, lineno\optional{, module_globals}} -Get line \var{lineno} from file named \var{filename}. This function -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, -\code{sys.path}, after first checking for a \pep{302} \code{__loader__} -in \var{module_globals}, in case the module was imported from a zipfile -or other non-filesystem import source. - -\versionadded[The \var{module_globals} parameter was added]{2.5} -\end{funcdesc} - -\begin{funcdesc}{clearcache}{} -Clear the cache. Use this function if you no longer need lines from -files previously read using \function{getline()}. -\end{funcdesc} - -\begin{funcdesc}{checkcache}{\optional{filename}} -Check the cache for validity. Use this function if files in the cache -may have changed on disk, and you require the updated version. If -\var{filename} is omitted, it will check all the entries in the cache. -\end{funcdesc} - -Example: - -\begin{verbatim} ->>> import linecache ->>> linecache.getline('/etc/passwd', 4) -'sys:x:3:3:sys:/dev:/bin/sh\n' -\end{verbatim} diff --git a/Doc/lib/liblocale.tex b/Doc/lib/liblocale.tex deleted file mode 100644 index 319d893..0000000 --- a/Doc/lib/liblocale.tex +++ /dev/null @@ -1,527 +0,0 @@ -\section{\module{locale} --- - Internationalization services} - -\declaremodule{standard}{locale} -\modulesynopsis{Internationalization services.} -\moduleauthor{Martin von L\"owis}{martin@v.loewis.de} -\sectionauthor{Martin von L\"owis}{martin@v.loewis.de} - - -The \module{locale} module opens access to the \POSIX{} locale -database and functionality. The \POSIX{} locale mechanism allows -programmers to deal with certain cultural issues in an application, -without requiring the programmer to know all the specifics of each -country where the software is executed. - -The \module{locale} module is implemented on top of the -\module{_locale}\refbimodindex{_locale} module, which in turn uses an -ANSI C locale implementation if available. - -The \module{locale} module defines the following exception and -functions: - - -\begin{excdesc}{Error} - Exception raised when \function{setlocale()} fails. -\end{excdesc} - -\begin{funcdesc}{setlocale}{category\optional{, locale}} - If \var{locale} is specified, it may be a string, a tuple of the - form \code{(\var{language code}, \var{encoding})}, or \code{None}. - If it is a tuple, it is converted to a string using the locale - aliasing engine. If \var{locale} is given and not \code{None}, - \function{setlocale()} modifies the locale setting for the - \var{category}. The available categories are listed in the data - description below. The value is the name of a locale. An empty - string specifies the user's default settings. If the modification of - the locale fails, the exception \exception{Error} is raised. If - successful, the new locale setting is returned. - - If \var{locale} is omitted or \code{None}, the current setting for - \var{category} is returned. - - \function{setlocale()} is not thread safe on most systems. - Applications typically start with a call of - -\begin{verbatim} -import locale -locale.setlocale(locale.LC_ALL, '') -\end{verbatim} - - This sets the locale for all categories to the user's default - setting (typically specified in the \envvar{LANG} environment - variable). If the locale is not changed thereafter, using - multithreading should not cause problems. - - \versionchanged[Added support for tuple values of the \var{locale} - parameter]{2.0} -\end{funcdesc} - -\begin{funcdesc}{localeconv}{} - Returns the database of the local conventions as a dictionary. - This dictionary has the following strings as keys: - - \begin{tableiii}{l|l|p{3in}}{constant}{Category}{Key}{Meaning} - \lineiii{LC_NUMERIC}{\code{'decimal_point'}} - {Decimal point character.} - \lineiii{}{\code{'grouping'}} - {Sequence of numbers specifying which relative positions - the \code{'thousands_sep'} is expected. If the sequence is - terminated with \constant{CHAR_MAX}, no further grouping - is performed. If the sequence terminates with a \code{0}, - the last group size is repeatedly used.} - \lineiii{}{\code{'thousands_sep'}} - {Character used between groups.}\hline - \lineiii{LC_MONETARY}{\code{'int_curr_symbol'}} - {International currency symbol.} - \lineiii{}{\code{'currency_symbol'}} - {Local currency symbol.} - \lineiii{}{\code{'p_cs_precedes/n_cs_precedes'}} - {Whether the currency symbol precedes the value (for positive resp. - negative values).} - \lineiii{}{\code{'p_sep_by_space/n_sep_by_space'}} - {Whether the currency symbol is separated from the value - by a space (for positive resp. negative values).} - \lineiii{}{\code{'mon_decimal_point'}} - {Decimal point used for monetary values.} - \lineiii{}{\code{'frac_digits'}} - {Number of fractional digits used in local formatting - of monetary values.} - \lineiii{}{\code{'int_frac_digits'}} - {Number of fractional digits used in international - formatting of monetary values.} - \lineiii{}{\code{'mon_thousands_sep'}} - {Group separator used for monetary values.} - \lineiii{}{\code{'mon_grouping'}} - {Equivalent to \code{'grouping'}, used for monetary - values.} - \lineiii{}{\code{'positive_sign'}} - {Symbol used to annotate a positive monetary value.} - \lineiii{}{\code{'negative_sign'}} - {Symbol used to annotate a negative monetary value.} - \lineiii{}{\code{'p_sign_posn/n_sign_posn'}} - {The position of the sign (for positive resp. negative values), see below.} - \end{tableiii} - - All numeric values can be set to \constant{CHAR_MAX} to indicate that - there is no value specified in this locale. - - The possible values for \code{'p_sign_posn'} and - \code{'n_sign_posn'} are given below. - - \begin{tableii}{c|l}{code}{Value}{Explanation} - \lineii{0}{Currency and value are surrounded by parentheses.} - \lineii{1}{The sign should precede the value and currency symbol.} - \lineii{2}{The sign should follow the value and currency symbol.} - \lineii{3}{The sign should immediately precede the value.} - \lineii{4}{The sign should immediately follow the value.} - \lineii{\constant{CHAR_MAX}}{Nothing is specified in this locale.} - \end{tableii} -\end{funcdesc} - -\begin{funcdesc}{nl_langinfo}{option} - -Return some locale-specific information as a string. This function is -not available on all systems, and the set of possible options might -also vary across platforms. The possible argument values are numbers, -for which symbolic constants are available in the locale module. - -\end{funcdesc} - -\begin{funcdesc}{getdefaultlocale}{\optional{envvars}} - Tries to determine the default locale settings and returns - them as a tuple of the form \code{(\var{language code}, - \var{encoding})}. - - According to \POSIX, a program which has not called - \code{setlocale(LC_ALL, '')} runs using the portable \code{'C'} - locale. Calling \code{setlocale(LC_ALL, '')} lets it use the - default locale as defined by the \envvar{LANG} variable. Since we - do not want to interfere with the current locale setting we thus - emulate the behavior in the way described above. - - To maintain compatibility with other platforms, not only the - \envvar{LANG} variable is tested, but a list of variables given as - envvars parameter. The first found to be defined will be - used. \var{envvars} defaults to the search path used in GNU gettext; - it must always contain the variable name \samp{LANG}. The GNU - gettext search path contains \code{'LANGUAGE'}, \code{'LC_ALL'}, - \code{'LC_CTYPE'}, and \code{'LANG'}, in that order. - - Except for the code \code{'C'}, the language code corresponds to - \rfc{1766}. \var{language code} and \var{encoding} may be - \code{None} if their values cannot be determined. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{getlocale}{\optional{category}} - Returns the current setting for the given locale category as - sequence containing \var{language code}, \var{encoding}. - \var{category} may be one of the \constant{LC_*} values except - \constant{LC_ALL}. It defaults to \constant{LC_CTYPE}. - - Except for the code \code{'C'}, the language code corresponds to - \rfc{1766}. \var{language code} and \var{encoding} may be - \code{None} if their values cannot be determined. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{getpreferredencoding}{\optional{do_setlocale}} - Return the encoding used for text data, according to user - preferences. User preferences are expressed differently on - different systems, and might not be available programmatically on - some systems, so this function only returns a guess. - - On some systems, it is necessary to invoke \function{setlocale} - to obtain the user preferences, so this function is not thread-safe. - If invoking setlocale is not necessary or desired, \var{do_setlocale} - should be set to \code{False}. - - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{normalize}{localename} - Returns a normalized locale code for the given locale name. The - returned locale code is formatted for use with - \function{setlocale()}. If normalization fails, the original name - is returned unchanged. - - If the given encoding is not known, the function defaults to - the default encoding for the locale code just like - \function{setlocale()}. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{resetlocale}{\optional{category}} - Sets the locale for \var{category} to the default setting. - - The default setting is determined by calling - \function{getdefaultlocale()}. \var{category} defaults to - \constant{LC_ALL}. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{strcoll}{string1, string2} - Compares two strings according to the current - \constant{LC_COLLATE} setting. As any other compare function, - returns a negative, or a positive value, or \code{0}, depending on - whether \var{string1} collates before or after \var{string2} or is - equal to it. -\end{funcdesc} - -\begin{funcdesc}{strxfrm}{string} - Transforms a string to one that can be used for the built-in - function \function{cmp()}\bifuncindex{cmp}, and still returns - locale-aware results. This function can be used when the same - string is compared repeatedly, e.g. when collating a sequence of - strings. -\end{funcdesc} - -\begin{funcdesc}{format}{format, val\optional{, grouping\optional{, monetary}}} - Formats a number \var{val} according to the current - \constant{LC_NUMERIC} setting. The format follows the conventions - of the \code{\%} operator. For floating point values, the decimal - point is modified if appropriate. If \var{grouping} is true, also - takes the grouping into account. - - If \var{monetary} is true, the conversion uses monetary thousands - separator and grouping strings. - - Please note that this function will only work for exactly one \%char - specifier. For whole format strings, use \function{format_string()}. - - \versionchanged[Added the \var{monetary} parameter]{2.5} -\end{funcdesc} - -\begin{funcdesc}{format_string}{format, val\optional{, grouping}} - Processes formatting specifiers as in \code{format \% val}, - but takes the current locale settings into account. - - \versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{currency}{val\optional{, symbol\optional{, grouping\optional{, international}}}} - Formats a number \var{val} according to the current \constant{LC_MONETARY} - settings. - - The returned string includes the currency symbol if \var{symbol} is true, - which is the default. - If \var{grouping} is true (which is not the default), grouping is done with - the value. - If \var{international} is true (which is not the default), the international - currency symbol is used. - - Note that this function will not work with the `C' locale, so you have to set - a locale via \function{setlocale()} first. - - \versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{str}{float} - Formats a floating point number using the same format as the - built-in function \code{str(\var{float})}, but takes the decimal - point into account. -\end{funcdesc} - -\begin{funcdesc}{atof}{string} - Converts a string to a floating point number, following the - \constant{LC_NUMERIC} settings. -\end{funcdesc} - -\begin{funcdesc}{atoi}{string} - Converts a string to an integer, following the - \constant{LC_NUMERIC} conventions. -\end{funcdesc} - -\begin{datadesc}{LC_CTYPE} -\refstmodindex{string} - Locale category for the character type functions. Depending on the - settings of this category, the functions of module - \refmodule{string} dealing with case change their behaviour. -\end{datadesc} - -\begin{datadesc}{LC_COLLATE} - Locale category for sorting strings. The functions - \function{strcoll()} and \function{strxfrm()} of the - \module{locale} module are affected. -\end{datadesc} - -\begin{datadesc}{LC_TIME} - Locale category for the formatting of time. The function - \function{time.strftime()} follows these conventions. -\end{datadesc} - -\begin{datadesc}{LC_MONETARY} - Locale category for formatting of monetary values. The available - options are available from the \function{localeconv()} function. -\end{datadesc} - -\begin{datadesc}{LC_MESSAGES} - Locale category for message display. Python currently does not - support application specific locale-aware messages. Messages - displayed by the operating system, like those returned by - \function{os.strerror()} might be affected by this category. -\end{datadesc} - -\begin{datadesc}{LC_NUMERIC} - Locale category for formatting numbers. The functions - \function{format()}, \function{atoi()}, \function{atof()} and - \function{str()} of the \module{locale} module are affected by that - category. All other numeric formatting operations are not - affected. -\end{datadesc} - -\begin{datadesc}{LC_ALL} - Combination of all locale settings. If this flag is used when the - locale is changed, setting the locale for all categories is - attempted. If that fails for any category, no category is changed at - all. When the locale is retrieved using this flag, a string - indicating the setting for all categories is returned. This string - can be later used to restore the settings. -\end{datadesc} - -\begin{datadesc}{CHAR_MAX} - This is a symbolic constant used for different values returned by - \function{localeconv()}. -\end{datadesc} - -The \function{nl_langinfo} function accepts one of the following keys. -Most descriptions are taken from the corresponding description in the -GNU C library. - -\begin{datadesc}{CODESET} -Return a string with the name of the character encoding used in the -selected locale. -\end{datadesc} - -\begin{datadesc}{D_T_FMT} -Return a string that can be used as a format string for strftime(3) to -represent time and date in a locale-specific way. -\end{datadesc} - -\begin{datadesc}{D_FMT} -Return a string that can be used as a format string for strftime(3) to -represent a date in a locale-specific way. -\end{datadesc} - -\begin{datadesc}{T_FMT} -Return a string that can be used as a format string for strftime(3) to -represent a time in a locale-specific way. -\end{datadesc} - -\begin{datadesc}{T_FMT_AMPM} -The return value can be used as a format string for `strftime' to -represent time in the am/pm format. -\end{datadesc} - -\begin{datadesc}{DAY_1 ... DAY_7} -Return name of the n-th day of the week. \warning{This -follows the US convention of \constant{DAY_1} being Sunday, not the -international convention (ISO 8601) that Monday is the first day of -the week.} -\end{datadesc} - -\begin{datadesc}{ABDAY_1 ... ABDAY_7} -Return abbreviated name of the n-th day of the week. -\end{datadesc} - -\begin{datadesc}{MON_1 ... MON_12} -Return name of the n-th month. -\end{datadesc} - -\begin{datadesc}{ABMON_1 ... ABMON_12} -Return abbreviated name of the n-th month. -\end{datadesc} - -\begin{datadesc}{RADIXCHAR} -Return radix character (decimal dot, decimal comma, etc.) -\end{datadesc} - -\begin{datadesc}{THOUSEP} -Return separator character for thousands (groups of three digits). -\end{datadesc} - -\begin{datadesc}{YESEXPR} -Return a regular expression that can be used with the regex -function to recognize a positive response to a yes/no question. -\warning{The expression is in the syntax suitable for the -\cfunction{regex()} function from the C library, which might differ -from the syntax used in \refmodule{re}.} -\end{datadesc} - -\begin{datadesc}{NOEXPR} -Return a regular expression that can be used with the regex(3) -function to recognize a negative response to a yes/no question. -\end{datadesc} - -\begin{datadesc}{CRNCYSTR} -Return the currency symbol, preceded by "-" if the symbol should -appear before the value, "+" if the symbol should appear after the -value, or "." if the symbol should replace the radix character. -\end{datadesc} - -\begin{datadesc}{ERA} -The return value represents the era used in the current locale. - -Most locales do not define this value. An example of a locale which -does define this value is the Japanese one. In Japan, the traditional -representation of dates includes the name of the era corresponding to -the then-emperor's reign. - -Normally it should not be necessary to use this value directly. -Specifying the \code{E} modifier in their format strings causes the -\function{strftime} function to use this information. The format of the -returned string is not specified, and therefore you should not assume -knowledge of it on different systems. -\end{datadesc} - -\begin{datadesc}{ERA_YEAR} -The return value gives the year in the relevant era of the locale. -\end{datadesc} - -\begin{datadesc}{ERA_D_T_FMT} -This return value can be used as a format string for -\function{strftime} to represent dates and times in a locale-specific -era-based way. -\end{datadesc} - -\begin{datadesc}{ERA_D_FMT} -This return value can be used as a format string for -\function{strftime} to represent time in a locale-specific era-based -way. -\end{datadesc} - -\begin{datadesc}{ALT_DIGITS} -The return value is a representation of up to 100 values used to -represent the values 0 to 99. -\end{datadesc} - -Example: - -\begin{verbatim} ->>> import locale ->>> loc = locale.getlocale(locale.LC_ALL) # get current locale ->>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform ->>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut ->>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale ->>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale ->>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale -\end{verbatim} - - -\subsection{Background, details, hints, tips and caveats} - -The C standard defines the locale as a program-wide property that may -be relatively expensive to change. On top of that, some -implementation are broken in such a way that frequent locale changes -may cause core dumps. This makes the locale somewhat painful to use -correctly. - -Initially, when a program is started, the locale is the \samp{C} locale, no -matter what the user's preferred locale is. The program must -explicitly say that it wants the user's preferred locale settings by -calling \code{setlocale(LC_ALL, '')}. - -It is generally a bad idea to call \function{setlocale()} in some library -routine, since as a side effect it affects the entire program. Saving -and restoring it is almost as bad: it is expensive and affects other -threads that happen to run before the settings have been restored. - -If, when coding a module for general use, you need a locale -independent version of an operation that is affected by the locale -(such as \function{string.lower()}, or certain formats used with -\function{time.strftime()}), you will have to find a way to do it -without using the standard library routine. Even better is convincing -yourself that using locale settings is okay. Only as a last resort -should you document that your module is not compatible with -non-\samp{C} locale settings. - -The case conversion functions in the -\refmodule{string}\refstmodindex{string} module are affected by the -locale settings. When a call to the \function{setlocale()} function -changes the \constant{LC_CTYPE} settings, the variables -\code{string.lowercase}, \code{string.uppercase} and -\code{string.letters} are recalculated. Note that code that uses -these variable through `\keyword{from} ... \keyword{import} ...', -e.g.\ \code{from string import letters}, is not affected by subsequent -\function{setlocale()} calls. - -The only way to perform numeric operations according to the locale -is to use the special functions defined by this module: -\function{atof()}, \function{atoi()}, \function{format()}, -\function{str()}. - -\subsection{For extension writers and programs that embed Python - \label{embedding-locale}} - -Extension modules should never call \function{setlocale()}, except to -find out what the current locale is. But since the return value can -only be used portably to restore it, that is not very useful (except -perhaps to find out whether or not the locale is \samp{C}). - -When Python code uses the \module{locale} module to change the locale, -this also affects the embedding application. If the embedding -application doesn't want this to happen, it should remove the -\module{_locale} extension module (which does all the work) from the -table of built-in modules in the \file{config.c} file, and make sure -that the \module{_locale} module is not accessible as a shared library. - - -\subsection{Access to message catalogs \label{locale-gettext}} - -The locale module exposes the C library's gettext interface on systems -that provide this interface. It consists of the functions -\function{gettext()}, \function{dgettext()}, \function{dcgettext()}, -\function{textdomain()}, \function{bindtextdomain()}, and -\function{bind_textdomain_codeset()}. These are similar to the same -functions in the \refmodule{gettext} module, but use the C library's -binary format for message catalogs, and the C library's search -algorithms for locating message catalogs. - -Python applications should normally find no need to invoke these -functions, and should use \refmodule{gettext} instead. A known -exception to this rule are applications that link use additional C -libraries which internally invoke \cfunction{gettext()} or -\function{dcgettext()}. For these applications, it may be necessary to -bind the text domain, so that the libraries can properly locate their -message catalogs. diff --git a/Doc/lib/liblogging.tex b/Doc/lib/liblogging.tex deleted file mode 100644 index c5c3e4e..0000000 --- a/Doc/lib/liblogging.tex +++ /dev/null @@ -1,1768 +0,0 @@ -\section{\module{logging} --- - Logging facility for Python} - -\declaremodule{standard}{logging} - -% These apply to all modules, and may be given more than once: - -\moduleauthor{Vinay Sajip}{vinay_sajip@red-dove.com} -\sectionauthor{Vinay Sajip}{vinay_sajip@red-dove.com} - -\modulesynopsis{Logging module for Python based on \pep{282}.} - -\indexii{Errors}{logging} - -\versionadded{2.3} -This module defines functions and classes which implement a flexible -error logging system for applications. - -Logging is performed by calling methods on instances of the -\class{Logger} class (hereafter called \dfn{loggers}). Each instance has a -name, and they are conceptually arranged in a name space hierarchy -using dots (periods) as separators. For example, a logger named -"scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf". -Logger names can be anything you want, and indicate the area of an -application in which a logged message originates. - -Logged messages also have levels of importance associated with them. -The default levels provided are \constant{DEBUG}, \constant{INFO}, -\constant{WARNING}, \constant{ERROR} and \constant{CRITICAL}. As a -convenience, you indicate the importance of a logged message by calling -an appropriate method of \class{Logger}. The methods are -\method{debug()}, \method{info()}, \method{warning()}, \method{error()} and -\method{critical()}, which mirror the default levels. You are not -constrained to use these levels: you can specify your own and use a -more general \class{Logger} method, \method{log()}, which takes an -explicit level argument. - -The numeric values of logging levels are given in the following table. These -are primarily of interest if you want to define your own levels, and need -them to have specific values relative to the predefined levels. If you -define a level with the same numeric value, it overwrites the predefined -value; the predefined name is lost. - -\begin{tableii}{l|l}{code}{Level}{Numeric value} - \lineii{CRITICAL}{50} - \lineii{ERROR}{40} - \lineii{WARNING}{30} - \lineii{INFO}{20} - \lineii{DEBUG}{10} - \lineii{NOTSET}{0} -\end{tableii} - -Levels can also be associated with loggers, being set either by the -developer or through loading a saved logging configuration. When a -logging method is called on a logger, the logger compares its own -level with the level associated with the method call. If the logger's -level is higher than the method call's, no logging message is actually -generated. This is the basic mechanism controlling the verbosity of -logging output. - -Logging messages are encoded as instances of the \class{LogRecord} class. -When a logger decides to actually log an event, a \class{LogRecord} -instance is created from the logging message. - -Logging messages are subjected to a dispatch mechanism through the -use of \dfn{handlers}, which are instances of subclasses of the -\class{Handler} class. Handlers are responsible for ensuring that a logged -message (in the form of a \class{LogRecord}) ends up in a particular -location (or set of locations) which is useful for the target audience for -that message (such as end users, support desk staff, system administrators, -developers). Handlers are passed \class{LogRecord} instances intended for -particular destinations. Each logger can have zero, one or more handlers -associated with it (via the \method{addHandler()} method of \class{Logger}). -In addition to any handlers directly associated with a logger, -\emph{all handlers associated with all ancestors of the logger} are -called to dispatch the message. - -Just as for loggers, handlers can have levels associated with them. -A handler's level acts as a filter in the same way as a logger's level does. -If a handler decides to actually dispatch an event, the \method{emit()} method -is used to send the message to its destination. Most user-defined subclasses -of \class{Handler} will need to override this \method{emit()}. - -In addition to the base \class{Handler} class, many useful subclasses -are provided: - -\begin{enumerate} - -\item \class{StreamHandler} instances send error messages to -streams (file-like objects). - -\item \class{FileHandler} instances send error messages to disk -files. - -\item \class{BaseRotatingHandler} is the base class for handlers that -rotate log files at a certain point. It is not meant to be instantiated -directly. Instead, use \class{RotatingFileHandler} or -\class{TimedRotatingFileHandler}. - -\item \class{RotatingFileHandler} instances send error messages to disk -files, with support for maximum log file sizes and log file rotation. - -\item \class{TimedRotatingFileHandler} instances send error messages to -disk files rotating the log file at certain timed intervals. - -\item \class{SocketHandler} instances send error messages to -TCP/IP sockets. - -\item \class{DatagramHandler} instances send error messages to UDP -sockets. - -\item \class{SMTPHandler} instances send error messages to a -designated email address. - -\item \class{SysLogHandler} instances send error messages to a -\UNIX{} syslog daemon, possibly on a remote machine. - -\item \class{NTEventLogHandler} instances send error messages to a -Windows NT/2000/XP event log. - -\item \class{MemoryHandler} instances send error messages to a -buffer in memory, which is flushed whenever specific criteria are -met. - -\item \class{HTTPHandler} instances send error messages to an -HTTP server using either \samp{GET} or \samp{POST} semantics. - -\end{enumerate} - -The \class{StreamHandler} and \class{FileHandler} classes are defined -in the core logging package. The other handlers are defined in a sub- -module, \module{logging.handlers}. (There is also another sub-module, -\module{logging.config}, for configuration functionality.) - -Logged messages are formatted for presentation through instances of the -\class{Formatter} class. They are initialized with a format string -suitable for use with the \% operator and a dictionary. - -For formatting multiple messages in a batch, instances of -\class{BufferingFormatter} can be used. In addition to the format string -(which is applied to each message in the batch), there is provision for -header and trailer format strings. - -When filtering based on logger level and/or handler level is not enough, -instances of \class{Filter} can be added to both \class{Logger} and -\class{Handler} instances (through their \method{addFilter()} method). -Before deciding to process a message further, both loggers and handlers -consult all their filters for permission. If any filter returns a false -value, the message is not processed further. - -The basic \class{Filter} functionality allows filtering by specific logger -name. If this feature is used, messages sent to the named logger and its -children are allowed through the filter, and all others dropped. - -In addition to the classes described above, there are a number of module- -level functions. - -\begin{funcdesc}{getLogger}{\optional{name}} -Return a logger with the specified name or, if no name is specified, return -a logger which is the root logger of the hierarchy. If specified, the name -is typically a dot-separated hierarchical name like \var{"a"}, \var{"a.b"} -or \var{"a.b.c.d"}. Choice of these names is entirely up to the developer -who is using logging. - -All calls to this function with a given name return the same logger instance. -This means that logger instances never need to be passed between different -parts of an application. -\end{funcdesc} - -\begin{funcdesc}{getLoggerClass}{} -Return either the standard \class{Logger} class, or the last class passed to -\function{setLoggerClass()}. This function may be called from within a new -class definition, to ensure that installing a customised \class{Logger} class -will not undo customisations already applied by other code. For example: - -\begin{verbatim} - class MyLogger(logging.getLoggerClass()): - # ... override behaviour here -\end{verbatim} - -\end{funcdesc} - -\begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{DEBUG} on the root logger. -The \var{msg} is the message format string, and the \var{args} are the -arguments which are merged into \var{msg} using the string formatting -operator. (Note that this means that you can use keywords in the -format string, together with a single dictionary argument.) - -There are two keyword arguments in \var{kwargs} which are inspected: -\var{exc_info} which, if it does not evaluate as false, causes exception -information to be added to the logging message. If an exception tuple (in the -format returned by \function{sys.exc_info()}) is provided, it is used; -otherwise, \function{sys.exc_info()} is called to get the exception -information. - -The other optional keyword argument is \var{extra} which can be used to pass -a dictionary which is used to populate the __dict__ of the LogRecord created -for the logging event with user-defined attributes. These custom attributes -can then be used as you like. For example, they could be incorporated into -logged messages. For example: - -\begin{verbatim} - FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" - logging.basicConfig(format=FORMAT) - d = {'clientip': '192.168.0.1', 'user': 'fbloggs'} - logging.warning("Protocol problem: %s", "connection reset", extra=d) -\end{verbatim} - -would print something like -\begin{verbatim} -2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset -\end{verbatim} - -The keys in the dictionary passed in \var{extra} should not clash with the keys -used by the logging system. (See the \class{Formatter} documentation for more -information on which keys are used by the logging system.) - -If you choose to use these attributes in logged messages, you need to exercise -some care. In the above example, for instance, the \class{Formatter} has been -set up with a format string which expects 'clientip' and 'user' in the -attribute dictionary of the LogRecord. If these are missing, the message will -not be logged because a string formatting exception will occur. So in this -case, you always need to pass the \var{extra} dictionary with these keys. - -While this might be annoying, this feature is intended for use in specialized -circumstances, such as multi-threaded servers where the same code executes -in many contexts, and interesting conditions which arise are dependent on this -context (such as remote client IP address and authenticated user name, in the -above example). In such circumstances, it is likely that specialized -\class{Formatter}s would be used with particular \class{Handler}s. - -\versionchanged[\var{extra} was added]{2.5} - -\end{funcdesc} - -\begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{INFO} on the root logger. -The arguments are interpreted as for \function{debug()}. -\end{funcdesc} - -\begin{funcdesc}{warning}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{WARNING} on the root logger. -The arguments are interpreted as for \function{debug()}. -\end{funcdesc} - -\begin{funcdesc}{error}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{ERROR} on the root logger. -The arguments are interpreted as for \function{debug()}. -\end{funcdesc} - -\begin{funcdesc}{critical}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{CRITICAL} on the root logger. -The arguments are interpreted as for \function{debug()}. -\end{funcdesc} - -\begin{funcdesc}{exception}{msg\optional{, *args}} -Logs a message with level \constant{ERROR} on the root logger. -The arguments are interpreted as for \function{debug()}. Exception info -is added to the logging message. This function should only be called -from an exception handler. -\end{funcdesc} - -\begin{funcdesc}{log}{level, msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \var{level} on the root logger. -The other arguments are interpreted as for \function{debug()}. -\end{funcdesc} - -\begin{funcdesc}{disable}{lvl} -Provides an overriding level \var{lvl} for all loggers which takes -precedence over the logger's own level. When the need arises to -temporarily throttle logging output down across the whole application, -this function can be useful. -\end{funcdesc} - -\begin{funcdesc}{addLevelName}{lvl, levelName} -Associates level \var{lvl} with text \var{levelName} in an internal -dictionary, which is used to map numeric levels to a textual -representation, for example when a \class{Formatter} formats a message. -This function can also be used to define your own levels. The only -constraints are that all levels used must be registered using this -function, levels should be positive integers and they should increase -in increasing order of severity. -\end{funcdesc} - -\begin{funcdesc}{getLevelName}{lvl} -Returns the textual representation of logging level \var{lvl}. If the -level is one of the predefined levels \constant{CRITICAL}, -\constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG} -then you get the corresponding string. If you have associated levels -with names using \function{addLevelName()} then the name you have associated -with \var{lvl} is returned. If a numeric value corresponding to one of the -defined levels is passed in, the corresponding string representation is -returned. Otherwise, the string "Level \%s" \% lvl is returned. -\end{funcdesc} - -\begin{funcdesc}{makeLogRecord}{attrdict} -Creates and returns a new \class{LogRecord} instance whose attributes are -defined by \var{attrdict}. This function is useful for taking a pickled -\class{LogRecord} attribute dictionary, sent over a socket, and reconstituting -it as a \class{LogRecord} instance at the receiving end. -\end{funcdesc} - -\begin{funcdesc}{basicConfig}{\optional{**kwargs}} -Does basic configuration for the logging system by creating a -\class{StreamHandler} with a default \class{Formatter} and adding it to -the root logger. The functions \function{debug()}, \function{info()}, -\function{warning()}, \function{error()} and \function{critical()} will call -\function{basicConfig()} automatically if no handlers are defined for the -root logger. - -\versionchanged[Formerly, \function{basicConfig} did not take any keyword -arguments]{2.4} - -The following keyword arguments are supported. - -\begin{tableii}{l|l}{code}{Format}{Description} -\lineii{filename}{Specifies that a FileHandler be created, using the -specified filename, rather than a StreamHandler.} -\lineii{filemode}{Specifies the mode to open the file, if filename is -specified (if filemode is unspecified, it defaults to 'a').} -\lineii{format}{Use the specified format string for the handler.} -\lineii{datefmt}{Use the specified date/time format.} -\lineii{level}{Set the root logger level to the specified level.} -\lineii{stream}{Use the specified stream to initialize the StreamHandler. -Note that this argument is incompatible with 'filename' - if both -are present, 'stream' is ignored.} -\end{tableii} - -\end{funcdesc} - -\begin{funcdesc}{shutdown}{} -Informs the logging system to perform an orderly shutdown by flushing and -closing all handlers. -\end{funcdesc} - -\begin{funcdesc}{setLoggerClass}{klass} -Tells the logging system to use the class \var{klass} when instantiating a -logger. The class should define \method{__init__()} such that only a name -argument is required, and the \method{__init__()} should call -\method{Logger.__init__()}. This function is typically called before any -loggers are instantiated by applications which need to use custom logger -behavior. -\end{funcdesc} - - -\begin{seealso} - \seepep{282}{A Logging System} - {The proposal which described this feature for inclusion in - the Python standard library.} - \seelink{http://www.red-dove.com/python_logging.html} - {Original Python \module{logging} package} - {This is the original source for the \module{logging} - package. The version of the package available from this - site is suitable for use with Python 1.5.2, 2.1.x and 2.2.x, - which do not include the \module{logging} package in the standard - library.} -\end{seealso} - - -\subsection{Logger Objects} - -Loggers have the following attributes and methods. Note that Loggers are -never instantiated directly, but always through the module-level function -\function{logging.getLogger(name)}. - -\begin{memberdesc}[Logger]{propagate} -If this evaluates to false, logging messages are not passed by this -logger or by child loggers to higher level (ancestor) loggers. The -constructor sets this attribute to 1. -\end{memberdesc} - -\begin{methoddesc}[Logger]{setLevel}{lvl} -Sets the threshold for this logger to \var{lvl}. Logging messages -which are less severe than \var{lvl} will be ignored. When a logger is -created, the level is set to \constant{NOTSET} (which causes all messages -to be processed when the logger is the root logger, or delegation to the -parent when the logger is a non-root logger). Note that the root logger -is created with level \constant{WARNING}. - -The term "delegation to the parent" means that if a logger has a level -of NOTSET, its chain of ancestor loggers is traversed until either an -ancestor with a level other than NOTSET is found, or the root is -reached. - -If an ancestor is found with a level other than NOTSET, then that -ancestor's level is treated as the effective level of the logger where -the ancestor search began, and is used to determine how a logging -event is handled. - -If the root is reached, and it has a level of NOTSET, then all -messages will be processed. Otherwise, the root's level will be used -as the effective level. -\end{methoddesc} - -\begin{methoddesc}[Logger]{isEnabledFor}{lvl} -Indicates if a message of severity \var{lvl} would be processed by -this logger. This method checks first the module-level level set by -\function{logging.disable(lvl)} and then the logger's effective level as -determined by \method{getEffectiveLevel()}. -\end{methoddesc} - -\begin{methoddesc}[Logger]{getEffectiveLevel}{} -Indicates the effective level for this logger. If a value other than -\constant{NOTSET} has been set using \method{setLevel()}, it is returned. -Otherwise, the hierarchy is traversed towards the root until a value -other than \constant{NOTSET} is found, and that value is returned. -\end{methoddesc} - -\begin{methoddesc}[Logger]{debug}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{DEBUG} on this logger. -The \var{msg} is the message format string, and the \var{args} are the -arguments which are merged into \var{msg} using the string formatting -operator. (Note that this means that you can use keywords in the -format string, together with a single dictionary argument.) - -There are two keyword arguments in \var{kwargs} which are inspected: -\var{exc_info} which, if it does not evaluate as false, causes exception -information to be added to the logging message. If an exception tuple (in the -format returned by \function{sys.exc_info()}) is provided, it is used; -otherwise, \function{sys.exc_info()} is called to get the exception -information. - -The other optional keyword argument is \var{extra} which can be used to pass -a dictionary which is used to populate the __dict__ of the LogRecord created -for the logging event with user-defined attributes. These custom attributes -can then be used as you like. For example, they could be incorporated into -logged messages. For example: - -\begin{verbatim} - FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s" - logging.basicConfig(format=FORMAT) - dict = { 'clientip' : '192.168.0.1', 'user' : 'fbloggs' } - logger = logging.getLogger("tcpserver") - logger.warning("Protocol problem: %s", "connection reset", extra=d) -\end{verbatim} - -would print something like -\begin{verbatim} -2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset -\end{verbatim} - -The keys in the dictionary passed in \var{extra} should not clash with the keys -used by the logging system. (See the \class{Formatter} documentation for more -information on which keys are used by the logging system.) - -If you choose to use these attributes in logged messages, you need to exercise -some care. In the above example, for instance, the \class{Formatter} has been -set up with a format string which expects 'clientip' and 'user' in the -attribute dictionary of the LogRecord. If these are missing, the message will -not be logged because a string formatting exception will occur. So in this -case, you always need to pass the \var{extra} dictionary with these keys. - -While this might be annoying, this feature is intended for use in specialized -circumstances, such as multi-threaded servers where the same code executes -in many contexts, and interesting conditions which arise are dependent on this -context (such as remote client IP address and authenticated user name, in the -above example). In such circumstances, it is likely that specialized -\class{Formatter}s would be used with particular \class{Handler}s. - -\versionchanged[\var{extra} was added]{2.5} - -\end{methoddesc} - -\begin{methoddesc}[Logger]{info}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{INFO} on this logger. -The arguments are interpreted as for \method{debug()}. -\end{methoddesc} - -\begin{methoddesc}[Logger]{warning}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{WARNING} on this logger. -The arguments are interpreted as for \method{debug()}. -\end{methoddesc} - -\begin{methoddesc}[Logger]{error}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{ERROR} on this logger. -The arguments are interpreted as for \method{debug()}. -\end{methoddesc} - -\begin{methoddesc}[Logger]{critical}{msg\optional{, *args\optional{, **kwargs}}} -Logs a message with level \constant{CRITICAL} on this logger. -The arguments are interpreted as for \method{debug()}. -\end{methoddesc} - -\begin{methoddesc}[Logger]{log}{lvl, msg\optional{, *args\optional{, **kwargs}}} -Logs a message with integer level \var{lvl} on this logger. -The other arguments are interpreted as for \method{debug()}. -\end{methoddesc} - -\begin{methoddesc}[Logger]{exception}{msg\optional{, *args}} -Logs a message with level \constant{ERROR} on this logger. -The arguments are interpreted as for \method{debug()}. Exception info -is added to the logging message. This method should only be called -from an exception handler. -\end{methoddesc} - -\begin{methoddesc}[Logger]{addFilter}{filt} -Adds the specified filter \var{filt} to this logger. -\end{methoddesc} - -\begin{methoddesc}[Logger]{removeFilter}{filt} -Removes the specified filter \var{filt} from this logger. -\end{methoddesc} - -\begin{methoddesc}[Logger]{filter}{record} -Applies this logger's filters to the record and returns a true value if -the record is to be processed. -\end{methoddesc} - -\begin{methoddesc}[Logger]{addHandler}{hdlr} -Adds the specified handler \var{hdlr} to this logger. -\end{methoddesc} - -\begin{methoddesc}[Logger]{removeHandler}{hdlr} -Removes the specified handler \var{hdlr} from this logger. -\end{methoddesc} - -\begin{methoddesc}[Logger]{findCaller}{} -Finds the caller's source filename and line number. Returns the filename, -line number and function name as a 3-element tuple. -\versionchanged[The function name was added. In earlier versions, the -filename and line number were returned as a 2-element tuple.]{2.5} -\end{methoddesc} - -\begin{methoddesc}[Logger]{handle}{record} -Handles a record by passing it to all handlers associated with this logger -and its ancestors (until a false value of \var{propagate} is found). -This method is used for unpickled records received from a socket, as well -as those created locally. Logger-level filtering is applied using -\method{filter()}. -\end{methoddesc} - -\begin{methoddesc}[Logger]{makeRecord}{name, lvl, fn, lno, msg, args, exc_info - \optional{, func, extra}} -This is a factory method which can be overridden in subclasses to create -specialized \class{LogRecord} instances. -\versionchanged[\var{func} and \var{extra} were added]{2.5} -\end{methoddesc} - -\subsection{Basic example \label{minimal-example}} - -\versionchanged[formerly \function{basicConfig} did not take any keyword -arguments]{2.4} - -The \module{logging} package provides a lot of flexibility, and its -configuration can appear daunting. This section demonstrates that simple -use of the logging package is possible. - -The simplest example shows logging to the console: - -\begin{verbatim} -import logging - -logging.debug('A debug message') -logging.info('Some information') -logging.warning('A shot across the bows') -\end{verbatim} - -If you run the above script, you'll see this: -\begin{verbatim} -WARNING:root:A shot across the bows -\end{verbatim} - -Because no particular logger was specified, the system used the root logger. -The debug and info messages didn't appear because by default, the root -logger is configured to only handle messages with a severity of WARNING -or above. The message format is also a configuration default, as is the output -destination of the messages - \code{sys.stderr}. The severity level, -the message format and destination can be easily changed, as shown in -the example below: - -\begin{verbatim} -import logging - -logging.basicConfig(level=logging.DEBUG, - format='%(asctime)s %(levelname)s %(message)s', - filename='/tmp/myapp.log', - filemode='w') -logging.debug('A debug message') -logging.info('Some information') -logging.warning('A shot across the bows') -\end{verbatim} - -The \method{basicConfig()} method is used to change the configuration -defaults, which results in output (written to \code{/tmp/myapp.log}) -which should look something like the following: - -\begin{verbatim} -2004-07-02 13:00:08,743 DEBUG A debug message -2004-07-02 13:00:08,743 INFO Some information -2004-07-02 13:00:08,743 WARNING A shot across the bows -\end{verbatim} - -This time, all messages with a severity of DEBUG or above were handled, -and the format of the messages was also changed, and output went to the -specified file rather than the console. - -Formatting uses standard Python string formatting - see section -\ref{typesseq-strings}. The format string takes the following -common specifiers. For a complete list of specifiers, consult the -\class{Formatter} documentation. - -\begin{tableii}{l|l}{code}{Format}{Description} -\lineii{\%(name)s} {Name of the logger (logging channel).} -\lineii{\%(levelname)s}{Text logging level for the message - (\code{'DEBUG'}, \code{'INFO'}, - \code{'WARNING'}, \code{'ERROR'}, - \code{'CRITICAL'}).} -\lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord} - was created. By default this is of the form - ``2003-07-08 16:49:45,896'' (the numbers after the - comma are millisecond portion of the time).} -\lineii{\%(message)s} {The logged message.} -\end{tableii} - -To change the date/time format, you can pass an additional keyword parameter, -\var{datefmt}, as in the following: - -\begin{verbatim} -import logging - -logging.basicConfig(level=logging.DEBUG, - format='%(asctime)s %(levelname)-8s %(message)s', - datefmt='%a, %d %b %Y %H:%M:%S', - filename='/temp/myapp.log', - filemode='w') -logging.debug('A debug message') -logging.info('Some information') -logging.warning('A shot across the bows') -\end{verbatim} - -which would result in output like - -\begin{verbatim} -Fri, 02 Jul 2004 13:06:18 DEBUG A debug message -Fri, 02 Jul 2004 13:06:18 INFO Some information -Fri, 02 Jul 2004 13:06:18 WARNING A shot across the bows -\end{verbatim} - -The date format string follows the requirements of \function{strftime()} - -see the documentation for the \refmodule{time} module. - -If, instead of sending logging output to the console or a file, you'd rather -use a file-like object which you have created separately, you can pass it -to \function{basicConfig()} using the \var{stream} keyword argument. Note -that if both \var{stream} and \var{filename} keyword arguments are passed, -the \var{stream} argument is ignored. - -Of course, you can put variable information in your output. To do this, -simply have the message be a format string and pass in additional arguments -containing the variable information, as in the following example: - -\begin{verbatim} -import logging - -logging.basicConfig(level=logging.DEBUG, - format='%(asctime)s %(levelname)-8s %(message)s', - datefmt='%a, %d %b %Y %H:%M:%S', - filename='/temp/myapp.log', - filemode='w') -logging.error('Pack my box with %d dozen %s', 5, 'liquor jugs') -\end{verbatim} - -which would result in - -\begin{verbatim} -Wed, 21 Jul 2004 15:35:16 ERROR Pack my box with 5 dozen liquor jugs -\end{verbatim} - -\subsection{Logging to multiple destinations \label{multiple-destinations}} - -Let's say you want to log to console and file with different message formats -and in differing circumstances. Say you want to log messages with levels -of DEBUG and higher to file, and those messages at level INFO and higher to -the console. Let's also assume that the file should contain timestamps, but -the console messages should not. Here's how you can achieve this: - -\begin{verbatim} -import logging - -# set up logging to file - see previous section for more details -logging.basicConfig(level=logging.DEBUG, - format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s', - datefmt='%m-%d %H:%M', - filename='/temp/myapp.log', - filemode='w') -# define a Handler which writes INFO messages or higher to the sys.stderr -console = logging.StreamHandler() -console.setLevel(logging.INFO) -# set a format which is simpler for console use -formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s') -# tell the handler to use this format -console.setFormatter(formatter) -# add the handler to the root logger -logging.getLogger('').addHandler(console) - -# Now, we can log to the root logger, or any other logger. First the root... -logging.info('Jackdaws love my big sphinx of quartz.') - -# Now, define a couple of other loggers which might represent areas in your -# application: - -logger1 = logging.getLogger('myapp.area1') -logger2 = logging.getLogger('myapp.area2') - -logger1.debug('Quick zephyrs blow, vexing daft Jim.') -logger1.info('How quickly daft jumping zebras vex.') -logger2.warning('Jail zesty vixen who grabbed pay from quack.') -logger2.error('The five boxing wizards jump quickly.') -\end{verbatim} - -When you run this, on the console you will see - -\begin{verbatim} -root : INFO Jackdaws love my big sphinx of quartz. -myapp.area1 : INFO How quickly daft jumping zebras vex. -myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack. -myapp.area2 : ERROR The five boxing wizards jump quickly. -\end{verbatim} - -and in the file you will see something like - -\begin{verbatim} -10-22 22:19 root INFO Jackdaws love my big sphinx of quartz. -10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim. -10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex. -10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack. -10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly. -\end{verbatim} - -As you can see, the DEBUG message only shows up in the file. The other -messages are sent to both destinations. - -This example uses console and file handlers, but you can use any number and -combination of handlers you choose. - -\subsection{Sending and receiving logging events across a network -\label{network-logging}} - -Let's say you want to send logging events across a network, and handle them -at the receiving end. A simple way of doing this is attaching a -\class{SocketHandler} instance to the root logger at the sending end: - -\begin{verbatim} -import logging, logging.handlers - -rootLogger = logging.getLogger('') -rootLogger.setLevel(logging.DEBUG) -socketHandler = logging.handlers.SocketHandler('localhost', - logging.handlers.DEFAULT_TCP_LOGGING_PORT) -# don't bother with a formatter, since a socket handler sends the event as -# an unformatted pickle -rootLogger.addHandler(socketHandler) - -# Now, we can log to the root logger, or any other logger. First the root... -logging.info('Jackdaws love my big sphinx of quartz.') - -# Now, define a couple of other loggers which might represent areas in your -# application: - -logger1 = logging.getLogger('myapp.area1') -logger2 = logging.getLogger('myapp.area2') - -logger1.debug('Quick zephyrs blow, vexing daft Jim.') -logger1.info('How quickly daft jumping zebras vex.') -logger2.warning('Jail zesty vixen who grabbed pay from quack.') -logger2.error('The five boxing wizards jump quickly.') -\end{verbatim} - -At the receiving end, you can set up a receiver using the -\module{SocketServer} module. Here is a basic working example: - -\begin{verbatim} -import cPickle -import logging -import logging.handlers -import SocketServer -import struct - - -class LogRecordStreamHandler(SocketServer.StreamRequestHandler): - """Handler for a streaming logging request. - - This basically logs the record using whatever logging policy is - configured locally. - """ - - def handle(self): - """ - Handle multiple requests - each expected to be a 4-byte length, - followed by the LogRecord in pickle format. Logs the record - according to whatever policy is configured locally. - """ - while 1: - chunk = self.connection.recv(4) - if len(chunk) < 4: - break - slen = struct.unpack(">L", chunk)[0] - chunk = self.connection.recv(slen) - while len(chunk) < slen: - chunk = chunk + self.connection.recv(slen - len(chunk)) - obj = self.unPickle(chunk) - record = logging.makeLogRecord(obj) - self.handleLogRecord(record) - - def unPickle(self, data): - return cPickle.loads(data) - - def handleLogRecord(self, record): - # if a name is specified, we use the named logger rather than the one - # implied by the record. - if self.server.logname is not None: - name = self.server.logname - else: - name = record.name - logger = logging.getLogger(name) - # N.B. EVERY record gets logged. This is because Logger.handle - # is normally called AFTER logger-level filtering. If you want - # to do filtering, do it at the client end to save wasting - # cycles and network bandwidth! - logger.handle(record) - -class LogRecordSocketReceiver(SocketServer.ThreadingTCPServer): - """simple TCP socket-based logging receiver suitable for testing. - """ - - allow_reuse_address = 1 - - def __init__(self, host='localhost', - port=logging.handlers.DEFAULT_TCP_LOGGING_PORT, - handler=LogRecordStreamHandler): - SocketServer.ThreadingTCPServer.__init__(self, (host, port), handler) - self.abort = 0 - self.timeout = 1 - self.logname = None - - def serve_until_stopped(self): - import select - abort = 0 - while not abort: - rd, wr, ex = select.select([self.socket.fileno()], - [], [], - self.timeout) - if rd: - self.handle_request() - abort = self.abort - -def main(): - logging.basicConfig( - format="%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s") - tcpserver = LogRecordSocketReceiver() - print "About to start TCP server..." - tcpserver.serve_until_stopped() - -if __name__ == "__main__": - main() -\end{verbatim} - -First run the server, and then the client. On the client side, nothing is -printed on the console; on the server side, you should see something like: - -\begin{verbatim} -About to start TCP server... - 59 root INFO Jackdaws love my big sphinx of quartz. - 59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim. - 69 myapp.area1 INFO How quickly daft jumping zebras vex. - 69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack. - 69 myapp.area2 ERROR The five boxing wizards jump quickly. -\end{verbatim} - -\subsection{Handler Objects} - -Handlers have the following attributes and methods. Note that -\class{Handler} is never instantiated directly; this class acts as a -base for more useful subclasses. However, the \method{__init__()} -method in subclasses needs to call \method{Handler.__init__()}. - -\begin{methoddesc}[Handler]{__init__}{level=\constant{NOTSET}} -Initializes the \class{Handler} instance by setting its level, setting -the list of filters to the empty list and creating a lock (using -\method{createLock()}) for serializing access to an I/O mechanism. -\end{methoddesc} - -\begin{methoddesc}[Handler]{createLock}{} -Initializes a thread lock which can be used to serialize access to -underlying I/O functionality which may not be threadsafe. -\end{methoddesc} - -\begin{methoddesc}[Handler]{acquire}{} -Acquires the thread lock created with \method{createLock()}. -\end{methoddesc} - -\begin{methoddesc}[Handler]{release}{} -Releases the thread lock acquired with \method{acquire()}. -\end{methoddesc} - -\begin{methoddesc}[Handler]{setLevel}{lvl} -Sets the threshold for this handler to \var{lvl}. Logging messages which are -less severe than \var{lvl} will be ignored. When a handler is created, the -level is set to \constant{NOTSET} (which causes all messages to be processed). -\end{methoddesc} - -\begin{methoddesc}[Handler]{setFormatter}{form} -Sets the \class{Formatter} for this handler to \var{form}. -\end{methoddesc} - -\begin{methoddesc}[Handler]{addFilter}{filt} -Adds the specified filter \var{filt} to this handler. -\end{methoddesc} - -\begin{methoddesc}[Handler]{removeFilter}{filt} -Removes the specified filter \var{filt} from this handler. -\end{methoddesc} - -\begin{methoddesc}[Handler]{filter}{record} -Applies this handler's filters to the record and returns a true value if -the record is to be processed. -\end{methoddesc} - -\begin{methoddesc}[Handler]{flush}{} -Ensure all logging output has been flushed. This version does -nothing and is intended to be implemented by subclasses. -\end{methoddesc} - -\begin{methoddesc}[Handler]{close}{} -Tidy up any resources used by the handler. This version does -nothing and is intended to be implemented by subclasses. -\end{methoddesc} - -\begin{methoddesc}[Handler]{handle}{record} -Conditionally emits the specified logging record, depending on -filters which may have been added to the handler. Wraps the actual -emission of the record with acquisition/release of the I/O thread -lock. -\end{methoddesc} - -\begin{methoddesc}[Handler]{handleError}{record} -This method should be called from handlers when an exception is -encountered during an \method{emit()} call. By default it does nothing, -which means that exceptions get silently ignored. This is what is -mostly wanted for a logging system - most users will not care -about errors in the logging system, they are more interested in -application errors. You could, however, replace this with a custom -handler if you wish. The specified record is the one which was being -processed when the exception occurred. -\end{methoddesc} - -\begin{methoddesc}[Handler]{format}{record} -Do formatting for a record - if a formatter is set, use it. -Otherwise, use the default formatter for the module. -\end{methoddesc} - -\begin{methoddesc}[Handler]{emit}{record} -Do whatever it takes to actually log the specified logging record. -This version is intended to be implemented by subclasses and so -raises a \exception{NotImplementedError}. -\end{methoddesc} - -\subsubsection{StreamHandler} - -The \class{StreamHandler} class, located in the core \module{logging} -package, sends logging output to streams such as \var{sys.stdout}, -\var{sys.stderr} or any file-like object (or, more precisely, any -object which supports \method{write()} and \method{flush()} methods). - -\begin{classdesc}{StreamHandler}{\optional{strm}} -Returns a new instance of the \class{StreamHandler} class. If \var{strm} is -specified, the instance will use it for logging output; otherwise, -\var{sys.stderr} will be used. -\end{classdesc} - -\begin{methoddesc}{emit}{record} -If a formatter is specified, it is used to format the record. -The record is then written to the stream with a trailing newline. -If exception information is present, it is formatted using -\function{traceback.print_exception()} and appended to the stream. -\end{methoddesc} - -\begin{methoddesc}{flush}{} -Flushes the stream by calling its \method{flush()} method. Note that -the \method{close()} method is inherited from \class{Handler} and -so does nothing, so an explicit \method{flush()} call may be needed -at times. -\end{methoddesc} - -\subsubsection{FileHandler} - -The \class{FileHandler} class, located in the core \module{logging} -package, sends logging output to a disk file. It inherits the output -functionality from \class{StreamHandler}. - -\begin{classdesc}{FileHandler}{filename\optional{, mode\optional{, encoding}}} -Returns a new instance of the \class{FileHandler} class. The specified -file is opened and used as the stream for logging. If \var{mode} is -not specified, \constant{'a'} is used. If \var{encoding} is not \var{None}, -it is used to open the file with that encoding. By default, the file grows -indefinitely. -\end{classdesc} - -\begin{methoddesc}{close}{} -Closes the file. -\end{methoddesc} - -\begin{methoddesc}{emit}{record} -Outputs the record to the file. -\end{methoddesc} - -\subsubsection{WatchedFileHandler} - -\versionadded{2.6} -The \class{WatchedFileHandler} class, located in the \module{logging.handlers} -module, is a \class{FileHandler} which watches the file it is logging to. -If the file changes, it is closed and reopened using the file name. - -A file change can happen because of usage of programs such as \var{newsyslog} -and \var{logrotate} which perform log file rotation. This handler, intended -for use under Unix/Linux, watches the file to see if it has changed since the -last emit. (A file is deemed to have changed if its device or inode have -changed.) If the file has changed, the old file stream is closed, and the file -opened to get a new stream. - -This handler is not appropriate for use under Windows, because under Windows -open log files cannot be moved or renamed - logging opens the files with -exclusive locks - and so there is no need for such a handler. Furthermore, -\var{ST_INO} is not supported under Windows; \function{stat()} always returns -zero for this value. - -\begin{classdesc}{WatchedFileHandler}{filename\optional{,mode\optional{, - encoding}}} -Returns a new instance of the \class{WatchedFileHandler} class. The specified -file is opened and used as the stream for logging. If \var{mode} is -not specified, \constant{'a'} is used. If \var{encoding} is not \var{None}, -it is used to open the file with that encoding. By default, the file grows -indefinitely. -\end{classdesc} - -\begin{methoddesc}{emit}{record} -Outputs the record to the file, but first checks to see if the file has -changed. If it has, the existing stream is flushed and closed and the file -opened again, before outputting the record to the file. -\end{methoddesc} - -\subsubsection{RotatingFileHandler} - -The \class{RotatingFileHandler} class, located in the \module{logging.handlers} -module, supports rotation of disk log files. - -\begin{classdesc}{RotatingFileHandler}{filename\optional{, mode\optional{, - maxBytes\optional{, backupCount}}}} -Returns a new instance of the \class{RotatingFileHandler} class. The -specified file is opened and used as the stream for logging. If -\var{mode} is not specified, \code{'a'} is used. By default, the -file grows indefinitely. - -You can use the \var{maxBytes} and -\var{backupCount} values to allow the file to \dfn{rollover} at a -predetermined size. When the size is about to be exceeded, the file is -closed and a new file is silently opened for output. Rollover occurs -whenever the current log file is nearly \var{maxBytes} in length; if -\var{maxBytes} is zero, rollover never occurs. If \var{backupCount} -is non-zero, the system will save old log files by appending the -extensions ".1", ".2" etc., to the filename. For example, with -a \var{backupCount} of 5 and a base file name of -\file{app.log}, you would get \file{app.log}, -\file{app.log.1}, \file{app.log.2}, up to \file{app.log.5}. The file being -written to is always \file{app.log}. When this file is filled, it is -closed and renamed to \file{app.log.1}, and if files \file{app.log.1}, -\file{app.log.2}, etc. exist, then they are renamed to \file{app.log.2}, -\file{app.log.3} etc. respectively. -\end{classdesc} - -\begin{methoddesc}{doRollover}{} -Does a rollover, as described above. -\end{methoddesc} - -\begin{methoddesc}{emit}{record} -Outputs the record to the file, catering for rollover as described previously. -\end{methoddesc} - -\subsubsection{TimedRotatingFileHandler} - -The \class{TimedRotatingFileHandler} class, located in the -\module{logging.handlers} module, supports rotation of disk log files -at certain timed intervals. - -\begin{classdesc}{TimedRotatingFileHandler}{filename - \optional{,when - \optional{,interval - \optional{,backupCount}}}} - -Returns a new instance of the \class{TimedRotatingFileHandler} class. The -specified file is opened and used as the stream for logging. On rotating -it also sets the filename suffix. Rotating happens based on the product -of \var{when} and \var{interval}. - -You can use the \var{when} to specify the type of \var{interval}. The -list of possible values is, note that they are not case sensitive: - -\begin{tableii}{l|l}{}{Value}{Type of interval} - \lineii{S}{Seconds} - \lineii{M}{Minutes} - \lineii{H}{Hours} - \lineii{D}{Days} - \lineii{W}{Week day (0=Monday)} - \lineii{midnight}{Roll over at midnight} -\end{tableii} - -If \var{backupCount} is non-zero, the system will save old log files by -appending extensions to the filename. The extensions are date-and-time -based, using the strftime format \code{\%Y-\%m-\%d_\%H-\%M-\%S} or a leading -portion thereof, depending on the rollover interval. At most \var{backupCount} -files will be kept, and if more would be created when rollover occurs, the -oldest one is deleted. -\end{classdesc} - -\begin{methoddesc}{doRollover}{} -Does a rollover, as described above. -\end{methoddesc} - -\begin{methoddesc}{emit}{record} -Outputs the record to the file, catering for rollover as described -above. -\end{methoddesc} - -\subsubsection{SocketHandler} - -The \class{SocketHandler} class, located in the -\module{logging.handlers} module, sends logging output to a network -socket. The base class uses a TCP socket. - -\begin{classdesc}{SocketHandler}{host, port} -Returns a new instance of the \class{SocketHandler} class intended to -communicate with a remote machine whose address is given by \var{host} -and \var{port}. -\end{classdesc} - -\begin{methoddesc}{close}{} -Closes the socket. -\end{methoddesc} - -\begin{methoddesc}{emit}{} -Pickles the record's attribute dictionary and writes it to the socket in -binary format. If there is an error with the socket, silently drops the -packet. If the connection was previously lost, re-establishes the connection. -To unpickle the record at the receiving end into a \class{LogRecord}, use the -\function{makeLogRecord()} function. -\end{methoddesc} - -\begin{methoddesc}{handleError}{} -Handles an error which has occurred during \method{emit()}. The -most likely cause is a lost connection. Closes the socket so that -we can retry on the next event. -\end{methoddesc} - -\begin{methoddesc}{makeSocket}{} -This is a factory method which allows subclasses to define the precise -type of socket they want. The default implementation creates a TCP -socket (\constant{socket.SOCK_STREAM}). -\end{methoddesc} - -\begin{methoddesc}{makePickle}{record} -Pickles the record's attribute dictionary in binary format with a length -prefix, and returns it ready for transmission across the socket. -\end{methoddesc} - -\begin{methoddesc}{send}{packet} -Send a pickled string \var{packet} to the socket. This function allows -for partial sends which can happen when the network is busy. -\end{methoddesc} - -\subsubsection{DatagramHandler} - -The \class{DatagramHandler} class, located in the -\module{logging.handlers} module, inherits from \class{SocketHandler} -to support sending logging messages over UDP sockets. - -\begin{classdesc}{DatagramHandler}{host, port} -Returns a new instance of the \class{DatagramHandler} class intended to -communicate with a remote machine whose address is given by \var{host} -and \var{port}. -\end{classdesc} - -\begin{methoddesc}{emit}{} -Pickles the record's attribute dictionary and writes it to the socket in -binary format. If there is an error with the socket, silently drops the -packet. -To unpickle the record at the receiving end into a \class{LogRecord}, use the -\function{makeLogRecord()} function. -\end{methoddesc} - -\begin{methoddesc}{makeSocket}{} -The factory method of \class{SocketHandler} is here overridden to create -a UDP socket (\constant{socket.SOCK_DGRAM}). -\end{methoddesc} - -\begin{methoddesc}{send}{s} -Send a pickled string to a socket. -\end{methoddesc} - -\subsubsection{SysLogHandler} - -The \class{SysLogHandler} class, located in the -\module{logging.handlers} module, supports sending logging messages to -a remote or local \UNIX{} syslog. - -\begin{classdesc}{SysLogHandler}{\optional{address\optional{, facility}}} -Returns a new instance of the \class{SysLogHandler} class intended to -communicate with a remote \UNIX{} machine whose address is given by -\var{address} in the form of a \code{(\var{host}, \var{port})} -tuple. If \var{address} is not specified, \code{('localhost', 514)} is -used. The address is used to open a UDP socket. An alternative to providing -a \code{(\var{host}, \var{port})} tuple is providing an address as a string, -for example "/dev/log". In this case, a Unix domain socket is used to send -the message to the syslog. If \var{facility} is not specified, -\constant{LOG_USER} is used. -\end{classdesc} - -\begin{methoddesc}{close}{} -Closes the socket to the remote host. -\end{methoddesc} - -\begin{methoddesc}{emit}{record} -The record is formatted, and then sent to the syslog server. If -exception information is present, it is \emph{not} sent to the server. -\end{methoddesc} - -\begin{methoddesc}{encodePriority}{facility, priority} -Encodes the facility and priority into an integer. You can pass in strings -or integers - if strings are passed, internal mapping dictionaries are used -to convert them to integers. -\end{methoddesc} - -\subsubsection{NTEventLogHandler} - -The \class{NTEventLogHandler} class, located in the -\module{logging.handlers} module, supports sending logging messages to -a local Windows NT, Windows 2000 or Windows XP event log. Before you -can use it, you need Mark Hammond's Win32 extensions for Python -installed. - -\begin{classdesc}{NTEventLogHandler}{appname\optional{, - dllname\optional{, logtype}}} -Returns a new instance of the \class{NTEventLogHandler} class. The -\var{appname} is used to define the application name as it appears in the -event log. An appropriate registry entry is created using this name. -The \var{dllname} should give the fully qualified pathname of a .dll or .exe -which contains message definitions to hold in the log (if not specified, -\code{'win32service.pyd'} is used - this is installed with the Win32 -extensions and contains some basic placeholder message definitions. -Note that use of these placeholders will make your event logs big, as the -entire message source is held in the log. If you want slimmer logs, you have -to pass in the name of your own .dll or .exe which contains the message -definitions you want to use in the event log). The \var{logtype} is one of -\code{'Application'}, \code{'System'} or \code{'Security'}, and -defaults to \code{'Application'}. -\end{classdesc} - -\begin{methoddesc}{close}{} -At this point, you can remove the application name from the registry as a -source of event log entries. However, if you do this, you will not be able -to see the events as you intended in the Event Log Viewer - it needs to be -able to access the registry to get the .dll name. The current version does -not do this (in fact it doesn't do anything). -\end{methoddesc} - -\begin{methoddesc}{emit}{record} -Determines the message ID, event category and event type, and then logs the -message in the NT event log. -\end{methoddesc} - -\begin{methoddesc}{getEventCategory}{record} -Returns the event category for the record. Override this if you -want to specify your own categories. This version returns 0. -\end{methoddesc} - -\begin{methoddesc}{getEventType}{record} -Returns the event type for the record. Override this if you want -to specify your own types. This version does a mapping using the -handler's typemap attribute, which is set up in \method{__init__()} -to a dictionary which contains mappings for \constant{DEBUG}, -\constant{INFO}, \constant{WARNING}, \constant{ERROR} and -\constant{CRITICAL}. If you are using your own levels, you will either need -to override this method or place a suitable dictionary in the -handler's \var{typemap} attribute. -\end{methoddesc} - -\begin{methoddesc}{getMessageID}{record} -Returns the message ID for the record. If you are using your -own messages, you could do this by having the \var{msg} passed to the -logger being an ID rather than a format string. Then, in here, -you could use a dictionary lookup to get the message ID. This -version returns 1, which is the base message ID in -\file{win32service.pyd}. -\end{methoddesc} - -\subsubsection{SMTPHandler} - -The \class{SMTPHandler} class, located in the -\module{logging.handlers} module, supports sending logging messages to -an email address via SMTP. - -\begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject\optional{, - credentials}} -Returns a new instance of the \class{SMTPHandler} class. The -instance is initialized with the from and to addresses and subject -line of the email. The \var{toaddrs} should be a list of strings. To specify a -non-standard SMTP port, use the (host, port) tuple format for the -\var{mailhost} argument. If you use a string, the standard SMTP port -is used. If your SMTP server requires authentication, you can specify a -(username, password) tuple for the \var{credentials} argument. -\versionchanged[\var{credentials} was added]{2.6} -\end{classdesc} - -\begin{methoddesc}{emit}{record} -Formats the record and sends it to the specified addressees. -\end{methoddesc} - -\begin{methoddesc}{getSubject}{record} -If you want to specify a subject line which is record-dependent, -override this method. -\end{methoddesc} - -\subsubsection{MemoryHandler} - -The \class{MemoryHandler} class, located in the -\module{logging.handlers} module, supports buffering of logging -records in memory, periodically flushing them to a \dfn{target} -handler. Flushing occurs whenever the buffer is full, or when an event -of a certain severity or greater is seen. - -\class{MemoryHandler} is a subclass of the more general -\class{BufferingHandler}, which is an abstract class. This buffers logging -records in memory. Whenever each record is added to the buffer, a -check is made by calling \method{shouldFlush()} to see if the buffer -should be flushed. If it should, then \method{flush()} is expected to -do the needful. - -\begin{classdesc}{BufferingHandler}{capacity} -Initializes the handler with a buffer of the specified capacity. -\end{classdesc} - -\begin{methoddesc}{emit}{record} -Appends the record to the buffer. If \method{shouldFlush()} returns true, -calls \method{flush()} to process the buffer. -\end{methoddesc} - -\begin{methoddesc}{flush}{} -You can override this to implement custom flushing behavior. This version -just zaps the buffer to empty. -\end{methoddesc} - -\begin{methoddesc}{shouldFlush}{record} -Returns true if the buffer is up to capacity. This method can be -overridden to implement custom flushing strategies. -\end{methoddesc} - -\begin{classdesc}{MemoryHandler}{capacity\optional{, flushLevel -\optional{, target}}} -Returns a new instance of the \class{MemoryHandler} class. The -instance is initialized with a buffer size of \var{capacity}. If -\var{flushLevel} is not specified, \constant{ERROR} is used. If no -\var{target} is specified, the target will need to be set using -\method{setTarget()} before this handler does anything useful. -\end{classdesc} - -\begin{methoddesc}{close}{} -Calls \method{flush()}, sets the target to \constant{None} and -clears the buffer. -\end{methoddesc} - -\begin{methoddesc}{flush}{} -For a \class{MemoryHandler}, flushing means just sending the buffered -records to the target, if there is one. Override if you want -different behavior. -\end{methoddesc} - -\begin{methoddesc}{setTarget}{target} -Sets the target handler for this handler. -\end{methoddesc} - -\begin{methoddesc}{shouldFlush}{record} -Checks for buffer full or a record at the \var{flushLevel} or higher. -\end{methoddesc} - -\subsubsection{HTTPHandler} - -The \class{HTTPHandler} class, located in the -\module{logging.handlers} module, supports sending logging messages to -a Web server, using either \samp{GET} or \samp{POST} semantics. - -\begin{classdesc}{HTTPHandler}{host, url\optional{, method}} -Returns a new instance of the \class{HTTPHandler} class. The -instance is initialized with a host address, url and HTTP method. -The \var{host} can be of the form \code{host:port}, should you need to -use a specific port number. If no \var{method} is specified, \samp{GET} -is used. -\end{classdesc} - -\begin{methoddesc}{emit}{record} -Sends the record to the Web server as an URL-encoded dictionary. -\end{methoddesc} - -\subsection{Formatter Objects} - -\class{Formatter}s have the following attributes and methods. They are -responsible for converting a \class{LogRecord} to (usually) a string -which can be interpreted by either a human or an external system. The -base -\class{Formatter} allows a formatting string to be specified. If none is -supplied, the default value of \code{'\%(message)s'} is used. - -A Formatter can be initialized with a format string which makes use of -knowledge of the \class{LogRecord} attributes - such as the default value -mentioned above making use of the fact that the user's message and -arguments are pre-formatted into a \class{LogRecord}'s \var{message} -attribute. This format string contains standard python \%-style -mapping keys. See section \ref{typesseq-strings}, ``String Formatting -Operations,'' for more information on string formatting. - -Currently, the useful mapping keys in a \class{LogRecord} are: - -\begin{tableii}{l|l}{code}{Format}{Description} -\lineii{\%(name)s} {Name of the logger (logging channel).} -\lineii{\%(levelno)s} {Numeric logging level for the message - (\constant{DEBUG}, \constant{INFO}, - \constant{WARNING}, \constant{ERROR}, - \constant{CRITICAL}).} -\lineii{\%(levelname)s}{Text logging level for the message - (\code{'DEBUG'}, \code{'INFO'}, - \code{'WARNING'}, \code{'ERROR'}, - \code{'CRITICAL'}).} -\lineii{\%(pathname)s} {Full pathname of the source file where the logging - call was issued (if available).} -\lineii{\%(filename)s} {Filename portion of pathname.} -\lineii{\%(module)s} {Module (name portion of filename).} -\lineii{\%(funcName)s} {Name of function containing the logging call.} -\lineii{\%(lineno)d} {Source line number where the logging call was issued - (if available).} -\lineii{\%(created)f} {Time when the \class{LogRecord} was created (as - returned by \function{time.time()}).} -\lineii{\%(relativeCreated)d} {Time in milliseconds when the LogRecord was - created, relative to the time the logging module was - loaded.} -\lineii{\%(asctime)s} {Human-readable time when the \class{LogRecord} - was created. By default this is of the form - ``2003-07-08 16:49:45,896'' (the numbers after the - comma are millisecond portion of the time).} -\lineii{\%(msecs)d} {Millisecond portion of the time when the - \class{LogRecord} was created.} -\lineii{\%(thread)d} {Thread ID (if available).} -\lineii{\%(threadName)s} {Thread name (if available).} -\lineii{\%(process)d} {Process ID (if available).} -\lineii{\%(message)s} {The logged message, computed as \code{msg \% args}.} -\end{tableii} - -\versionchanged[\var{funcName} was added]{2.5} - -\begin{classdesc}{Formatter}{\optional{fmt\optional{, datefmt}}} -Returns a new instance of the \class{Formatter} class. The -instance is initialized with a format string for the message as a whole, -as well as a format string for the date/time portion of a message. If -no \var{fmt} is specified, \code{'\%(message)s'} is used. If no \var{datefmt} -is specified, the ISO8601 date format is used. -\end{classdesc} - -\begin{methoddesc}{format}{record} -The record's attribute dictionary is used as the operand to a -string formatting operation. Returns the resulting string. -Before formatting the dictionary, a couple of preparatory steps -are carried out. The \var{message} attribute of the record is computed -using \var{msg} \% \var{args}. If the formatting string contains -\code{'(asctime)'}, \method{formatTime()} is called to format the -event time. If there is exception information, it is formatted using -\method{formatException()} and appended to the message. -\end{methoddesc} - -\begin{methoddesc}{formatTime}{record\optional{, datefmt}} -This method should be called from \method{format()} by a formatter which -wants to make use of a formatted time. This method can be overridden -in formatters to provide for any specific requirement, but the -basic behavior is as follows: if \var{datefmt} (a string) is specified, -it is used with \function{time.strftime()} to format the creation time of the -record. Otherwise, the ISO8601 format is used. The resulting -string is returned. -\end{methoddesc} - -\begin{methoddesc}{formatException}{exc_info} -Formats the specified exception information (a standard exception tuple -as returned by \function{sys.exc_info()}) as a string. This default -implementation just uses \function{traceback.print_exception()}. -The resulting string is returned. -\end{methoddesc} - -\subsection{Filter Objects} - -\class{Filter}s can be used by \class{Handler}s and \class{Logger}s for -more sophisticated filtering than is provided by levels. The base filter -class only allows events which are below a certain point in the logger -hierarchy. For example, a filter initialized with "A.B" will allow events -logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB", -"B.A.B" etc. If initialized with the empty string, all events are passed. - -\begin{classdesc}{Filter}{\optional{name}} -Returns an instance of the \class{Filter} class. If \var{name} is specified, -it names a logger which, together with its children, will have its events -allowed through the filter. If no name is specified, allows every event. -\end{classdesc} - -\begin{methoddesc}{filter}{record} -Is the specified record to be logged? Returns zero for no, nonzero for -yes. If deemed appropriate, the record may be modified in-place by this -method. -\end{methoddesc} - -\subsection{LogRecord Objects} - -\class{LogRecord} instances are created every time something is logged. They -contain all the information pertinent to the event being logged. The -main information passed in is in msg and args, which are combined -using msg \% args to create the message field of the record. The record -also includes information such as when the record was created, the -source line where the logging call was made, and any exception -information to be logged. - -\begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args, - exc_info \optional{, func}} -Returns an instance of \class{LogRecord} initialized with interesting -information. The \var{name} is the logger name; \var{lvl} is the -numeric level; \var{pathname} is the absolute pathname of the source -file in which the logging call was made; \var{lineno} is the line -number in that file where the logging call is found; \var{msg} is the -user-supplied message (a format string); \var{args} is the tuple -which, together with \var{msg}, makes up the user message; and -\var{exc_info} is the exception tuple obtained by calling -\function{sys.exc_info() }(or \constant{None}, if no exception information -is available). The \var{func} is the name of the function from which the -logging call was made. If not specified, it defaults to \code{None}. -\versionchanged[\var{func} was added]{2.5} -\end{classdesc} - -\begin{methoddesc}{getMessage}{} -Returns the message for this \class{LogRecord} instance after merging any -user-supplied arguments with the message. -\end{methoddesc} - -\subsection{Thread Safety} - -The logging module is intended to be thread-safe without any special work -needing to be done by its clients. It achieves this though using threading -locks; there is one lock to serialize access to the module's shared data, -and each handler also creates a lock to serialize access to its underlying -I/O. - -\subsection{Configuration} - - -\subsubsection{Configuration functions% - \label{logging-config-api}} - -The following functions configure the logging module. They are located in the -\module{logging.config} module. Their use is optional --- you can configure -the logging module using these functions or by making calls to the -main API (defined in \module{logging} itself) and defining handlers -which are declared either in \module{logging} or -\module{logging.handlers}. - -\begin{funcdesc}{fileConfig}{fname\optional{, defaults}} -Reads the logging configuration from a ConfigParser-format file named -\var{fname}. This function can be called several times from an application, -allowing an end user the ability to select from various pre-canned -configurations (if the developer provides a mechanism to present the -choices and load the chosen configuration). Defaults to be passed to -ConfigParser can be specified in the \var{defaults} argument. -\end{funcdesc} - -\begin{funcdesc}{listen}{\optional{port}} -Starts up a socket server on the specified port, and listens for new -configurations. If no port is specified, the module's default -\constant{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations -will be sent as a file suitable for processing by \function{fileConfig()}. -Returns a \class{Thread} instance on which you can call \method{start()} -to start the server, and which you can \method{join()} when appropriate. -To stop the server, call \function{stopListening()}. To send a configuration -to the socket, read in the configuration file and send it to the socket -as a string of bytes preceded by a four-byte length packed in binary using -struct.\code{pack('>L', n)}. -\end{funcdesc} - -\begin{funcdesc}{stopListening}{} -Stops the listening server which was created with a call to -\function{listen()}. This is typically called before calling \method{join()} -on the return value from \function{listen()}. -\end{funcdesc} - -\subsubsection{Configuration file format% - \label{logging-config-fileformat}} - -The configuration file format understood by \function{fileConfig()} is -based on ConfigParser functionality. The file must contain sections -called \code{[loggers]}, \code{[handlers]} and \code{[formatters]} -which identify by name the entities of each type which are defined in -the file. For each such entity, there is a separate section which -identified how that entity is configured. Thus, for a logger named -\code{log01} in the \code{[loggers]} section, the relevant -configuration details are held in a section -\code{[logger_log01]}. Similarly, a handler called \code{hand01} in -the \code{[handlers]} section will have its configuration held in a -section called \code{[handler_hand01]}, while a formatter called -\code{form01} in the \code{[formatters]} section will have its -configuration specified in a section called -\code{[formatter_form01]}. The root logger configuration must be -specified in a section called \code{[logger_root]}. - -Examples of these sections in the file are given below. - -\begin{verbatim} -[loggers] -keys=root,log02,log03,log04,log05,log06,log07 - -[handlers] -keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09 - -[formatters] -keys=form01,form02,form03,form04,form05,form06,form07,form08,form09 -\end{verbatim} - -The root logger must specify a level and a list of handlers. An -example of a root logger section is given below. - -\begin{verbatim} -[logger_root] -level=NOTSET -handlers=hand01 -\end{verbatim} - -The \code{level} entry can be one of \code{DEBUG, INFO, WARNING, -ERROR, CRITICAL} or \code{NOTSET}. For the root logger only, -\code{NOTSET} means that all messages will be logged. Level values are -\function{eval()}uated in the context of the \code{logging} package's -namespace. - -The \code{handlers} entry is a comma-separated list of handler names, -which must appear in the \code{[handlers]} section. These names must -appear in the \code{[handlers]} section and have corresponding -sections in the configuration file. - -For loggers other than the root logger, some additional information is -required. This is illustrated by the following example. - -\begin{verbatim} -[logger_parser] -level=DEBUG -handlers=hand01 -propagate=1 -qualname=compiler.parser -\end{verbatim} - -The \code{level} and \code{handlers} entries are interpreted as for -the root logger, except that if a non-root logger's level is specified -as \code{NOTSET}, the system consults loggers higher up the hierarchy -to determine the effective level of the logger. The \code{propagate} -entry is set to 1 to indicate that messages must propagate to handlers -higher up the logger hierarchy from this logger, or 0 to indicate that -messages are \strong{not} propagated to handlers up the hierarchy. The -\code{qualname} entry is the hierarchical channel name of the logger, -that is to say the name used by the application to get the logger. - -Sections which specify handler configuration are exemplified by the -following. - -\begin{verbatim} -[handler_hand01] -class=StreamHandler -level=NOTSET -formatter=form01 -args=(sys.stdout,) -\end{verbatim} - -The \code{class} entry indicates the handler's class (as determined by -\function{eval()} in the \code{logging} package's namespace). The -\code{level} is interpreted as for loggers, and \code{NOTSET} is taken -to mean "log everything". - -The \code{formatter} entry indicates the key name of the formatter for -this handler. If blank, a default formatter -(\code{logging._defaultFormatter}) is used. If a name is specified, it -must appear in the \code{[formatters]} section and have a -corresponding section in the configuration file. - -The \code{args} entry, when \function{eval()}uated in the context of -the \code{logging} package's namespace, is the list of arguments to -the constructor for the handler class. Refer to the constructors for -the relevant handlers, or to the examples below, to see how typical -entries are constructed. - -\begin{verbatim} -[handler_hand02] -class=FileHandler -level=DEBUG -formatter=form02 -args=('python.log', 'w') - -[handler_hand03] -class=handlers.SocketHandler -level=INFO -formatter=form03 -args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT) - -[handler_hand04] -class=handlers.DatagramHandler -level=WARN -formatter=form04 -args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT) - -[handler_hand05] -class=handlers.SysLogHandler -level=ERROR -formatter=form05 -args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER) - -[handler_hand06] -class=handlers.NTEventLogHandler -level=CRITICAL -formatter=form06 -args=('Python Application', '', 'Application') - -[handler_hand07] -class=handlers.SMTPHandler -level=WARN -formatter=form07 -args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject') - -[handler_hand08] -class=handlers.MemoryHandler -level=NOTSET -formatter=form08 -target= -args=(10, ERROR) - -[handler_hand09] -class=handlers.HTTPHandler -level=NOTSET -formatter=form09 -args=('localhost:9022', '/log', 'GET') -\end{verbatim} - -Sections which specify formatter configuration are typified by the following. - -\begin{verbatim} -[formatter_form01] -format=F1 %(asctime)s %(levelname)s %(message)s -datefmt= -class=logging.Formatter -\end{verbatim} - -The \code{format} entry is the overall format string, and the -\code{datefmt} entry is the \function{strftime()}-compatible date/time format -string. If empty, the package substitutes ISO8601 format date/times, which -is almost equivalent to specifying the date format string "%Y-%m-%d %H:%M:%S". -The ISO8601 format also specifies milliseconds, which are appended to the -result of using the above format string, with a comma separator. An example -time in ISO8601 format is \code{2003-01-23 00:29:50,411}. - -The \code{class} entry is optional. It indicates the name of the -formatter's class (as a dotted module and class name.) This option is -useful for instantiating a \class{Formatter} subclass. Subclasses of -\class{Formatter} can present exception tracebacks in an expanded or -condensed format. diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex deleted file mode 100644 index c3e7ffd..0000000 --- a/Doc/lib/libmailbox.tex +++ /dev/null @@ -1,1443 +0,0 @@ -\section{\module{mailbox} --- - Manipulate mailboxes in various formats} - -\declaremodule{}{mailbox} -\moduleauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com} -\sectionauthor{Gregory K.~Johnson}{gkj@gregorykjohnson.com} -\modulesynopsis{Manipulate mailboxes in various formats} - - -This module defines two classes, \class{Mailbox} and \class{Message}, for -accessing and manipulating on-disk mailboxes and the messages they contain. -\class{Mailbox} offers a dictionary-like mapping from keys to messages. -\class{Message} extends the \module{email.Message} module's \class{Message} -class with format-specific state and behavior. Supported mailbox formats are -Maildir, mbox, MH, Babyl, and MMDF. - -\begin{seealso} - \seemodule{email}{Represent and manipulate messages.} -\end{seealso} - -\subsection{\class{Mailbox} objects} -\label{mailbox-objects} - -\begin{classdesc*}{Mailbox} -A mailbox, which may be inspected and modified. -\end{classdesc*} - -The \class{Mailbox} class defines an interface and -is not intended to be instantiated. Instead, format-specific -subclasses should inherit from \class{Mailbox} and your code -should instantiate a particular subclass. - -The \class{Mailbox} interface is dictionary-like, with small keys -corresponding to messages. Keys are issued by the \class{Mailbox} -instance with which they will be used and are only meaningful to that -\class{Mailbox} instance. A key continues to identify a message even -if the corresponding message is modified, such as by replacing it with -another message. - -Messages may be added to a \class{Mailbox} instance using the set-like -method \method{add()} and removed using a \code{del} statement or the -set-like methods \method{remove()} and \method{discard()}. - -\class{Mailbox} interface semantics differ from dictionary semantics in some -noteworthy ways. Each time a message is requested, a new -representation (typically a \class{Message} instance) is generated -based upon the current state of the mailbox. Similarly, when a message -is added to a \class{Mailbox} instance, the provided message -representation's contents are copied. In neither case is a reference -to the message representation kept by the \class{Mailbox} instance. - -The default \class{Mailbox} iterator iterates over message representations, not -keys as the default dictionary iterator does. Moreover, modification of a -mailbox during iteration is safe and well-defined. Messages added to the -mailbox after an iterator is created will not be seen by the iterator. Messages -removed from the mailbox before the iterator yields them will be silently -skipped, though using a key from an iterator may result in a -\exception{KeyError} exception if the corresponding message is subsequently -removed. - -\begin{notice}[warning] -Be very cautious when modifying mailboxes that might be -simultaneously changed by some other process. The safest mailbox -format to use for such tasks is Maildir; try to avoid using -single-file formats such as mbox for concurrent writing. If you're -modifying a mailbox, you -\emph{must} lock it by calling the \method{lock()} and -\method{unlock()} methods \emph{before} reading any messages in the file -or making any changes by adding or deleting a message. Failing to -lock the mailbox runs the risk of losing messages or corrupting the entire -mailbox. -\end{notice} - -\class{Mailbox} instances have the following methods: - -\begin{methoddesc}{add}{message} -Add \var{message} to the mailbox and return the key that has been assigned to -it. - -Parameter \var{message} may be a \class{Message} instance, an -\class{email.Message.Message} instance, a string, or a file-like object (which -should be open in text mode). If \var{message} is an instance of the -appropriate format-specific \class{Message} subclass (e.g., if it's an -\class{mboxMessage} instance and this is an \class{mbox} instance), its -format-specific information is used. Otherwise, reasonable defaults for -format-specific information are used. -\end{methoddesc} - -\begin{methoddesc}{remove}{key} -\methodline{__delitem__}{key} -\methodline{discard}{key} -Delete the message corresponding to \var{key} from the mailbox. - -If no such message exists, a \exception{KeyError} exception is raised if the -method was called as \method{remove()} or \method{__delitem__()} but no -exception is raised if the method was called as \method{discard()}. The -behavior of \method{discard()} may be preferred if the underlying mailbox -format supports concurrent modification by other processes. -\end{methoddesc} - -\begin{methoddesc}{__setitem__}{key, message} -Replace the message corresponding to \var{key} with \var{message}. Raise a -\exception{KeyError} exception if no message already corresponds to \var{key}. - -As with \method{add()}, parameter \var{message} may be a \class{Message} -instance, an \class{email.Message.Message} instance, a string, or a file-like -object (which should be open in text mode). If \var{message} is an instance of -the appropriate format-specific \class{Message} subclass (e.g., if it's an -\class{mboxMessage} instance and this is an \class{mbox} instance), its -format-specific information is used. Otherwise, the format-specific information -of the message that currently corresponds to \var{key} is left unchanged. -\end{methoddesc} - -\begin{methoddesc}{iterkeys}{} -\methodline{keys}{} -Return an iterator over all keys if called as \method{iterkeys()} or return a -list of keys if called as \method{keys()}. -\end{methoddesc} - -\begin{methoddesc}{itervalues}{} -\methodline{__iter__}{} -\methodline{values}{} -Return an iterator over representations of all messages if called as -\method{itervalues()} or \method{__iter__()} or return a list of such -representations if called as \method{values()}. The messages are represented as -instances of the appropriate format-specific \class{Message} subclass unless a -custom message factory was specified when the \class{Mailbox} instance was -initialized. \note{The behavior of \method{__iter__()} is unlike that of -dictionaries, which iterate over keys.} -\end{methoddesc} - -\begin{methoddesc}{iteritems}{} -\methodline{items}{} -Return an iterator over (\var{key}, \var{message}) pairs, where \var{key} is a -key and \var{message} is a message representation, if called as -\method{iteritems()} or return a list of such pairs if called as -\method{items()}. The messages are represented as instances of the appropriate -format-specific \class{Message} subclass unless a custom message factory was -specified when the \class{Mailbox} instance was initialized. -\end{methoddesc} - -\begin{methoddesc}{get}{key\optional{, default=None}} -\methodline{__getitem__}{key} -Return a representation of the message corresponding to \var{key}. If no such -message exists, \var{default} is returned if the method was called as -\method{get()} and a \exception{KeyError} exception is raised if the method was -called as \method{__getitem__()}. The message is represented as an instance of -the appropriate format-specific \class{Message} subclass unless a custom -message factory was specified when the \class{Mailbox} instance was -initialized. -\end{methoddesc} - -\begin{methoddesc}{get_message}{key} -Return a representation of the message corresponding to \var{key} as an -instance of the appropriate format-specific \class{Message} subclass, or raise -a \exception{KeyError} exception if no such message exists. -\end{methoddesc} - -\begin{methoddesc}{get_string}{key} -Return a string representation of the message corresponding to \var{key}, or -raise a \exception{KeyError} exception if no such message exists. -\end{methoddesc} - -\begin{methoddesc}{get_file}{key} -Return a file-like representation of the message corresponding to \var{key}, -or raise a \exception{KeyError} exception if no such message exists. The -file-like object behaves as if open in binary mode. This file should be closed -once it is no longer needed. - -\note{Unlike other representations of messages, file-like representations are -not necessarily independent of the \class{Mailbox} instance that created them -or of the underlying mailbox. More specific documentation is provided by each -subclass.} -\end{methoddesc} - -\begin{methoddesc}{has_key}{key} -\methodline{__contains__}{key} -Return \code{True} if \var{key} corresponds to a message, \code{False} -otherwise. -\end{methoddesc} - -\begin{methoddesc}{__len__}{} -Return a count of messages in the mailbox. -\end{methoddesc} - -\begin{methoddesc}{clear}{} -Delete all messages from the mailbox. -\end{methoddesc} - -\begin{methoddesc}{pop}{key\optional{, default}} -Return a representation of the message corresponding to \var{key} and delete -the message. If no such message exists, return \var{default} if it was supplied -or else raise a \exception{KeyError} exception. The message is represented as -an instance of the appropriate format-specific \class{Message} subclass unless -a custom message factory was specified when the \class{Mailbox} instance was -initialized. -\end{methoddesc} - -\begin{methoddesc}{popitem}{} -Return an arbitrary (\var{key}, \var{message}) pair, where \var{key} is a key -and \var{message} is a message representation, and delete the corresponding -message. If the mailbox is empty, raise a \exception{KeyError} exception. The -message is represented as an instance of the appropriate format-specific -\class{Message} subclass unless a custom message factory was specified when the -\class{Mailbox} instance was initialized. -\end{methoddesc} - -\begin{methoddesc}{update}{arg} -Parameter \var{arg} should be a \var{key}-to-\var{message} mapping or an -iterable of (\var{key}, \var{message}) pairs. Updates the mailbox so that, for -each given \var{key} and \var{message}, the message corresponding to \var{key} -is set to \var{message} as if by using \method{__setitem__()}. As with -\method{__setitem__()}, each \var{key} must already correspond to a message in -the mailbox or else a \exception{KeyError} exception will be raised, so in -general it is incorrect for \var{arg} to be a \class{Mailbox} instance. -\note{Unlike with dictionaries, keyword arguments are not supported.} -\end{methoddesc} - -\begin{methoddesc}{flush}{} -Write any pending changes to the filesystem. For some \class{Mailbox} -subclasses, changes are always written immediately and \method{flush()} does -nothing, but you should still make a habit of calling this method. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -Acquire an exclusive advisory lock on the mailbox so that other processes know -not to modify it. An \exception{ExternalClashError} is raised if the lock is -not available. The particular locking mechanisms used depend upon the mailbox -format. You should \emph{always} lock the mailbox before making any -modifications to its contents. -\end{methoddesc} - -\begin{methoddesc}{unlock}{} -Release the lock on the mailbox, if any. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Flush the mailbox, unlock it if necessary, and close any open files. For some -\class{Mailbox} subclasses, this method does nothing. -\end{methoddesc} - - -\subsubsection{\class{Maildir}} -\label{mailbox-maildir} - -\begin{classdesc}{Maildir}{dirname\optional{, factory=rfc822.Message\optional{, -create=True}}} -A subclass of \class{Mailbox} for mailboxes in Maildir format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{MaildirMessage} is used -as the default message representation. If \var{create} is \code{True}, the -mailbox is created if it does not exist. - -It is for historical reasons that \var{factory} defaults to -\class{rfc822.Message} and that \var{dirname} is named as such rather than -\var{path}. For a \class{Maildir} instance that behaves like instances of other -\class{Mailbox} subclasses, set \var{factory} to \code{None}. -\end{classdesc} - -Maildir is a directory-based mailbox format invented for the qmail mail -transfer agent and now widely supported by other programs. Messages in a -Maildir mailbox are stored in separate files within a common directory -structure. This design allows Maildir mailboxes to be accessed and modified by -multiple unrelated programs without data corruption, so file locking is -unnecessary. - -Maildir mailboxes contain three subdirectories, namely: \file{tmp}, \file{new}, -and \file{cur}. Messages are created momentarily in the \file{tmp} subdirectory -and then moved to the \file{new} subdirectory to finalize delivery. A mail user -agent may subsequently move the message to the \file{cur} subdirectory and -store information about the state of the message in a special "info" section -appended to its file name. - -Folders of the style introduced by the Courier mail transfer agent are also -supported. Any subdirectory of the main mailbox is considered a folder if -\character{.} is the first character in its name. Folder names are represented -by \class{Maildir} without the leading \character{.}. Each folder is itself a -Maildir mailbox but should not contain other folders. Instead, a logical -nesting is indicated using \character{.} to delimit levels, e.g., -"Archived.2005.07". - -\begin{notice} -The Maildir specification requires the use of a colon (\character{:}) in -certain message file names. However, some operating systems do not permit this -character in file names, If you wish to use a Maildir-like format on such an -operating system, you should specify another character to use instead. The -exclamation point (\character{!}) is a popular choice. For example: -\begin{verbatim} -import mailbox -mailbox.Maildir.colon = '!' -\end{verbatim} -The \member{colon} attribute may also be set on a per-instance basis. -\end{notice} - -\class{Maildir} instances have all of the methods of \class{Mailbox} in -addition to the following: - -\begin{methoddesc}{list_folders}{} -Return a list of the names of all folders. -\end{methoddesc} - -\begin{methoddesc}{get_folder}{folder} -Return a \class{Maildir} instance representing the folder whose name is -\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the -folder does not exist. -\end{methoddesc} - -\begin{methoddesc}{add_folder}{folder} -Create a folder whose name is \var{folder} and return a \class{Maildir} -instance representing it. -\end{methoddesc} - -\begin{methoddesc}{remove_folder}{folder} -Delete the folder whose name is \var{folder}. If the folder contains any -messages, a \exception{NotEmptyError} exception will be raised and the folder -will not be deleted. -\end{methoddesc} - -\begin{methoddesc}{clean}{} -Delete temporary files from the mailbox that have not been accessed in the -last 36 hours. The Maildir specification says that mail-reading programs -should do this occasionally. -\end{methoddesc} - -Some \class{Mailbox} methods implemented by \class{Maildir} deserve special -remarks: - -\begin{methoddesc}{add}{message} -\methodline[Maildir]{__setitem__}{key, message} -\methodline[Maildir]{update}{arg} -\warning{These methods generate unique file names based upon the current -process ID. When using multiple threads, undetected name clashes may occur and -cause corruption of the mailbox unless threads are coordinated to avoid using -these methods to manipulate the same mailbox simultaneously.} -\end{methoddesc} - -\begin{methoddesc}{flush}{} -All changes to Maildir mailboxes are immediately applied, so this method does -nothing. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Maildir mailboxes do not support (or require) locking, so these methods do -nothing. -\end{methoddesc} - -\begin{methoddesc}{close}{} -\class{Maildir} instances do not keep any open files and the underlying -mailboxes do not support locking, so this method does nothing. -\end{methoddesc} - -\begin{methoddesc}{get_file}{key} -Depending upon the host platform, it may not be possible to modify or remove -the underlying message while the returned file remains open. -\end{methoddesc} - -\begin{seealso} - \seelink{http://www.qmail.org/man/man5/maildir.html}{maildir man page from - qmail}{The original specification of the format.} - \seelink{http://cr.yp.to/proto/maildir.html}{Using maildir format}{Notes - on Maildir by its inventor. Includes an updated name-creation scheme and - details on "info" semantics.} - \seelink{http://www.courier-mta.org/?maildir.html}{maildir man page from - Courier}{Another specification of the format. Describes a common extension - for supporting folders.} -\end{seealso} - -\subsubsection{\class{mbox}} -\label{mailbox-mbox} - -\begin{classdesc}{mbox}{path\optional{, factory=None\optional{, create=True}}} -A subclass of \class{Mailbox} for mailboxes in mbox format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{mboxMessage} is used as -the default message representation. If \var{create} is \code{True}, the mailbox -is created if it does not exist. -\end{classdesc} - -The mbox format is the classic format for storing mail on \UNIX{} systems. All -messages in an mbox mailbox are stored in a single file with the beginning of -each message indicated by a line whose first five characters are "From~". - -Several variations of the mbox format exist to address perceived shortcomings -in the original. In the interest of compatibility, \class{mbox} implements the -original format, which is sometimes referred to as \dfn{mboxo}. This means that -the \mailheader{Content-Length} header, if present, is ignored and that any -occurrences of "From~" at the beginning of a line in a message body are -transformed to ">From~" when storing the message, although occurences of -">From~" are not transformed to "From~" when reading the message. - -Some \class{Mailbox} methods implemented by \class{mbox} deserve special -remarks: - -\begin{methoddesc}{get_file}{key} -Using the file after calling \method{flush()} or \method{close()} on the -\class{mbox} instance may yield unpredictable results or raise an exception. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Three locking mechanisms are used---dot locking and, if available, the -\cfunction{flock()} and \cfunction{lockf()} system calls. -\end{methoddesc} - -\begin{seealso} - \seelink{http://www.qmail.org/man/man5/mbox.html}{mbox man page from - qmail}{A specification of the format and its variations.} - \seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mbox}{mbox man - page from tin}{Another specification of the format, with details on - locking.} - \seelink{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html} - {Configuring Netscape Mail on \UNIX{}: Why The Content-Length Format is - Bad}{An argument for using the original mbox format rather than a - variation.} - \seelink{http://homepages.tesco.net./\tilde{}J.deBoynePollard/FGA/mail-mbox-formats.html} - {"mbox" is a family of several mutually incompatible mailbox formats}{A - history of mbox variations.} -\end{seealso} - -\subsubsection{\class{MH}} -\label{mailbox-mh} - -\begin{classdesc}{MH}{path\optional{, factory=None\optional{, create=True}}} -A subclass of \class{Mailbox} for mailboxes in MH format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{MHMessage} is used as -the default message representation. If \var{create} is \code{True}, the mailbox -is created if it does not exist. -\end{classdesc} - -MH is a directory-based mailbox format invented for the MH Message Handling -System, a mail user agent. Each message in an MH mailbox resides in its own -file. An MH mailbox may contain other MH mailboxes (called \dfn{folders}) in -addition to messages. Folders may be nested indefinitely. MH mailboxes also -support \dfn{sequences}, which are named lists used to logically group messages -without moving them to sub-folders. Sequences are defined in a file called -\file{.mh_sequences} in each folder. - -The \class{MH} class manipulates MH mailboxes, but it does not attempt to -emulate all of \program{mh}'s behaviors. In particular, it does not modify and -is not affected by the \file{context} or \file{.mh_profile} files that are used -by \program{mh} to store its state and configuration. - -\class{MH} instances have all of the methods of \class{Mailbox} in addition to -the following: - -\begin{methoddesc}{list_folders}{} -Return a list of the names of all folders. -\end{methoddesc} - -\begin{methoddesc}{get_folder}{folder} -Return an \class{MH} instance representing the folder whose name is -\var{folder}. A \exception{NoSuchMailboxError} exception is raised if the -folder does not exist. -\end{methoddesc} - -\begin{methoddesc}{add_folder}{folder} -Create a folder whose name is \var{folder} and return an \class{MH} instance -representing it. -\end{methoddesc} - -\begin{methoddesc}{remove_folder}{folder} -Delete the folder whose name is \var{folder}. If the folder contains any -messages, a \exception{NotEmptyError} exception will be raised and the folder -will not be deleted. -\end{methoddesc} - -\begin{methoddesc}{get_sequences}{} -Return a dictionary of sequence names mapped to key lists. If there are no -sequences, the empty dictionary is returned. -\end{methoddesc} - -\begin{methoddesc}{set_sequences}{sequences} -Re-define the sequences that exist in the mailbox based upon \var{sequences}, a -dictionary of names mapped to key lists, like returned by -\method{get_sequences()}. -\end{methoddesc} - -\begin{methoddesc}{pack}{} -Rename messages in the mailbox as necessary to eliminate gaps in numbering. -Entries in the sequences list are updated correspondingly. \note{Already-issued -keys are invalidated by this operation and should not be subsequently used.} -\end{methoddesc} - -Some \class{Mailbox} methods implemented by \class{MH} deserve special remarks: - -\begin{methoddesc}{remove}{key} -\methodline{__delitem__}{key} -\methodline{discard}{key} -These methods immediately delete the message. The MH convention of marking a -message for deletion by prepending a comma to its name is not used. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Three locking mechanisms are used---dot locking and, if available, the -\cfunction{flock()} and \cfunction{lockf()} system calls. For MH mailboxes, -locking the mailbox means locking the \file{.mh_sequences} file and, only for -the duration of any operations that affect them, locking individual message -files. -\end{methoddesc} - -\begin{methoddesc}{get_file}{key} -Depending upon the host platform, it may not be possible to remove the -underlying message while the returned file remains open. -\end{methoddesc} - -\begin{methoddesc}{flush}{} -All changes to MH mailboxes are immediately applied, so this method does -nothing. -\end{methoddesc} - -\begin{methoddesc}{close}{} -\class{MH} instances do not keep any open files, so this method is equivelant -to \method{unlock()}. -\end{methoddesc} - -\begin{seealso} -\seelink{http://www.nongnu.org/nmh/}{nmh - Message Handling System}{Home page -of \program{nmh}, an updated version of the original \program{mh}.} -\seelink{http://www.ics.uci.edu/\tilde{}mh/book/}{MH \& nmh: Email for Users \& -Programmers}{A GPL-licensed book on \program{mh} and \program{nmh}, with some -information on the mailbox format.} -\end{seealso} - -\subsubsection{\class{Babyl}} -\label{mailbox-babyl} - -\begin{classdesc}{Babyl}{path\optional{, factory=None\optional{, create=True}}} -A subclass of \class{Mailbox} for mailboxes in Babyl format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{BabylMessage} is used -as the default message representation. If \var{create} is \code{True}, the -mailbox is created if it does not exist. -\end{classdesc} - -Babyl is a single-file mailbox format used by the Rmail mail user agent -included with Emacs. The beginning of a message is indicated by a line -containing the two characters Control-Underscore -(\character{\textbackslash037}) and Control-L (\character{\textbackslash014}). -The end of a message is indicated by the start of the next message or, in the -case of the last message, a line containing a Control-Underscore -(\character{\textbackslash037}) character. - -Messages in a Babyl mailbox have two sets of headers, original headers and -so-called visible headers. Visible headers are typically a subset of the -original headers that have been reformatted or abridged to be more attractive. -Each message in a Babyl mailbox also has an accompanying list of \dfn{labels}, -or short strings that record extra information about the message, and a list of -all user-defined labels found in the mailbox is kept in the Babyl options -section. - -\class{Babyl} instances have all of the methods of \class{Mailbox} in addition -to the following: - -\begin{methoddesc}{get_labels}{} -Return a list of the names of all user-defined labels used in the mailbox. -\note{The actual messages are inspected to determine which labels exist in the -mailbox rather than consulting the list of labels in the Babyl options section, -but the Babyl section is updated whenever the mailbox is modified.} -\end{methoddesc} - -Some \class{Mailbox} methods implemented by \class{Babyl} deserve special -remarks: - -\begin{methoddesc}{get_file}{key} -In Babyl mailboxes, the headers of a message are not stored contiguously with -the body of the message. To generate a file-like representation, the headers -and body are copied together into a \class{StringIO} instance (from the -\module{StringIO} module), which has an API identical to that of a file. As a -result, the file-like object is truly independent of the underlying mailbox but -does not save memory compared to a string representation. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Three locking mechanisms are used---dot locking and, if available, the -\cfunction{flock()} and \cfunction{lockf()} system calls. -\end{methoddesc} - -\begin{seealso} -\seelink{http://quimby.gnus.org/notes/BABYL}{Format of Version 5 Babyl Files}{A -specification of the Babyl format.} -\seelink{http://www.gnu.org/software/emacs/manual/html_node/Rmail.html}{Reading -Mail with Rmail}{The Rmail manual, with some information on Babyl semantics.} -\end{seealso} - -\subsubsection{\class{MMDF}} -\label{mailbox-mmdf} - -\begin{classdesc}{MMDF}{path\optional{, factory=None\optional{, create=True}}} -A subclass of \class{Mailbox} for mailboxes in MMDF format. Parameter -\var{factory} is a callable object that accepts a file-like message -representation (which behaves as if opened in binary mode) and returns a custom -representation. If \var{factory} is \code{None}, \class{MMDFMessage} is used as -the default message representation. If \var{create} is \code{True}, the mailbox -is created if it does not exist. -\end{classdesc} - -MMDF is a single-file mailbox format invented for the Multichannel Memorandum -Distribution Facility, a mail transfer agent. Each message is in the same form -as an mbox message but is bracketed before and after by lines containing four -Control-A (\character{\textbackslash001}) characters. As with the mbox format, -the beginning of each message is indicated by a line whose first five -characters are "From~", but additional occurrences of "From~" are not -transformed to ">From~" when storing messages because the extra message -separator lines prevent mistaking such occurrences for the starts of subsequent -messages. - -Some \class{Mailbox} methods implemented by \class{MMDF} deserve special -remarks: - -\begin{methoddesc}{get_file}{key} -Using the file after calling \method{flush()} or \method{close()} on the -\class{MMDF} instance may yield unpredictable results or raise an exception. -\end{methoddesc} - -\begin{methoddesc}{lock}{} -\methodline{unlock}{} -Three locking mechanisms are used---dot locking and, if available, the -\cfunction{flock()} and \cfunction{lockf()} system calls. -\end{methoddesc} - -\begin{seealso} -\seelink{http://www.tin.org/bin/man.cgi?section=5\&topic=mmdf}{mmdf man page -from tin}{A specification of MMDF format from the documentation of tin, a -newsreader.} -\seelink{http://en.wikipedia.org/wiki/MMDF}{MMDF}{A Wikipedia article -describing the Multichannel Memorandum Distribution Facility.} -\end{seealso} - -\subsection{\class{Message} objects} -\label{mailbox-message-objects} - -\begin{classdesc}{Message}{\optional{message}} -A subclass of the \module{email.Message} module's \class{Message}. Subclasses -of \class{mailbox.Message} add mailbox-format-specific state and behavior. - -If \var{message} is omitted, the new instance is created in a default, empty -state. If \var{message} is an \class{email.Message.Message} instance, its -contents are copied; furthermore, any format-specific information is converted -insofar as possible if \var{message} is a \class{Message} instance. If -\var{message} is a string or a file, it should contain an \rfc{2822}-compliant -message, which is read and parsed. -\end{classdesc} - -The format-specific state and behaviors offered by subclasses vary, but in -general it is only the properties that are not specific to a particular mailbox -that are supported (although presumably the properties are specific to a -particular mailbox format). For example, file offsets for single-file mailbox -formats and file names for directory-based mailbox formats are not retained, -because they are only applicable to the original mailbox. But state such as -whether a message has been read by the user or marked as important is retained, -because it applies to the message itself. - -There is no requirement that \class{Message} instances be used to represent -messages retrieved using \class{Mailbox} instances. In some situations, the -time and memory required to generate \class{Message} representations might not -not acceptable. For such situations, \class{Mailbox} instances also offer -string and file-like representations, and a custom message factory may be -specified when a \class{Mailbox} instance is initialized. - -\subsubsection{\class{MaildirMessage}} -\label{mailbox-maildirmessage} - -\begin{classdesc}{MaildirMessage}{\optional{message}} -A message with Maildir-specific behaviors. Parameter \var{message} -has the same meaning as with the \class{Message} constructor. -\end{classdesc} - -Typically, a mail user agent application moves all of the messages in the -\file{new} subdirectory to the \file{cur} subdirectory after the first time the -user opens and closes the mailbox, recording that the messages are old whether -or not they've actually been read. Each message in \file{cur} has an "info" -section added to its file name to store information about its state. (Some mail -readers may also add an "info" section to messages in \file{new}.) The "info" -section may take one of two forms: it may contain "2," followed by a list of -standardized flags (e.g., "2,FR") or it may contain "1," followed by so-called -experimental information. Standard flags for Maildir messages are as follows: - -\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation} -\lineiii{D}{Draft}{Under composition} -\lineiii{F}{Flagged}{Marked as important} -\lineiii{P}{Passed}{Forwarded, resent, or bounced} -\lineiii{R}{Replied}{Replied to} -\lineiii{S}{Seen}{Read} -\lineiii{T}{Trashed}{Marked for subsequent deletion} -\end{tableiii} - -\class{MaildirMessage} instances offer the following methods: - -\begin{methoddesc}{get_subdir}{} -Return either "new" (if the message should be stored in the \file{new} -subdirectory) or "cur" (if the message should be stored in the \file{cur} -subdirectory). \note{A message is typically moved from \file{new} to \file{cur} -after its mailbox has been accessed, whether or not the message is has been -read. A message \code{msg} has been read if \code{"S" not in msg.get_flags()} -is \code{True}.} -\end{methoddesc} - -\begin{methoddesc}{set_subdir}{subdir} -Set the subdirectory the message should be stored in. Parameter \var{subdir} -must be either "new" or "cur". -\end{methoddesc} - -\begin{methoddesc}{get_flags}{} -Return a string specifying the flags that are currently set. If the message -complies with the standard Maildir format, the result is the concatenation in -alphabetical order of zero or one occurrence of each of \character{D}, -\character{F}, \character{P}, \character{R}, \character{S}, and \character{T}. -The empty string is returned if no flags are set or if "info" contains -experimental semantics. -\end{methoddesc} - -\begin{methoddesc}{set_flags}{flags} -Set the flags specified by \var{flags} and unset all others. -\end{methoddesc} - -\begin{methoddesc}{add_flag}{flag} -Set the flag(s) specified by \var{flag} without changing other flags. To add -more than one flag at a time, \var{flag} may be a string of more than one -character. The current "info" is overwritten whether or not it contains -experimental information rather than -flags. -\end{methoddesc} - -\begin{methoddesc}{remove_flag}{flag} -Unset the flag(s) specified by \var{flag} without changing other flags. To -remove more than one flag at a time, \var{flag} maybe a string of more than one -character. If "info" contains experimental information rather than flags, the -current "info" is not modified. -\end{methoddesc} - -\begin{methoddesc}{get_date}{} -Return the delivery date of the message as a floating-point number representing -seconds since the epoch. -\end{methoddesc} - -\begin{methoddesc}{set_date}{date} -Set the delivery date of the message to \var{date}, a floating-point number -representing seconds since the epoch. -\end{methoddesc} - -\begin{methoddesc}{get_info}{} -Return a string containing the "info" for a message. This is useful for -accessing and modifying "info" that is experimental (i.e., not a list of -flags). -\end{methoddesc} - -\begin{methoddesc}{set_info}{info} -Set "info" to \var{info}, which should be a string. -\end{methoddesc} - -When a \class{MaildirMessage} instance is created based upon an -\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status} -and \mailheader{X-Status} headers are omitted and the following conversions -take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state} -\lineii{"cur" subdirectory}{O flag} -\lineii{F flag}{F flag} -\lineii{R flag}{A flag} -\lineii{S flag}{R flag} -\lineii{T flag}{D flag} -\end{tableii} - -When a \class{MaildirMessage} instance is created based upon an -\class{MHMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MHMessage} state} -\lineii{"cur" subdirectory}{"unseen" sequence} -\lineii{"cur" subdirectory and S flag}{no "unseen" sequence} -\lineii{F flag}{"flagged" sequence} -\lineii{R flag}{"replied" sequence} -\end{tableii} - -When a \class{MaildirMessage} instance is created based upon a -\class{BabylMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{BabylMessage} state} -\lineii{"cur" subdirectory}{"unseen" label} -\lineii{"cur" subdirectory and S flag}{no "unseen" label} -\lineii{P flag}{"forwarded" or "resent" label} -\lineii{R flag}{"answered" label} -\lineii{T flag}{"deleted" label} -\end{tableii} - -\subsubsection{\class{mboxMessage}} -\label{mailbox-mboxmessage} - -\begin{classdesc}{mboxMessage}{\optional{message}} -A message with mbox-specific behaviors. Parameter \var{message} has the same -meaning as with the \class{Message} constructor. -\end{classdesc} - -Messages in an mbox mailbox are stored together in a single file. The sender's -envelope address and the time of delivery are typically stored in a line -beginning with "From~" that is used to indicate the start of a message, though -there is considerable variation in the exact format of this data among mbox -implementations. Flags that indicate the state of the message, such as whether -it has been read or marked as important, are typically stored in -\mailheader{Status} and \mailheader{X-Status} headers. - -Conventional flags for mbox messages are as follows: - -\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation} -\lineiii{R}{Read}{Read} -\lineiii{O}{Old}{Previously detected by MUA} -\lineiii{D}{Deleted}{Marked for subsequent deletion} -\lineiii{F}{Flagged}{Marked as important} -\lineiii{A}{Answered}{Replied to} -\end{tableiii} - -The "R" and "O" flags are stored in the \mailheader{Status} header, and the -"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The -flags and headers typically appear in the order mentioned. - -\class{mboxMessage} instances offer the following methods: - -\begin{methoddesc}{get_from}{} -Return a string representing the "From~" line that marks the start of the -message in an mbox mailbox. The leading "From~" and the trailing newline are -excluded. -\end{methoddesc} - -\begin{methoddesc}{set_from}{from_\optional{, time_=None}} -Set the "From~" line to \var{from_}, which should be specified without a -leading "From~" or trailing newline. For convenience, \var{time_} may be -specified and will be formatted appropriately and appended to \var{from_}. If -\var{time_} is specified, it should be a \class{struct_time} instance, a tuple -suitable for passing to \method{time.strftime()}, or \code{True} (to use -\method{time.gmtime()}). -\end{methoddesc} - -\begin{methoddesc}{get_flags}{} -Return a string specifying the flags that are currently set. If the message -complies with the conventional format, the result is the concatenation in the -following order of zero or one occurrence of each of \character{R}, -\character{O}, \character{D}, \character{F}, and \character{A}. -\end{methoddesc} - -\begin{methoddesc}{set_flags}{flags} -Set the flags specified by \var{flags} and unset all others. Parameter -\var{flags} should be the concatenation in any order of zero or more -occurrences of each of \character{R}, \character{O}, \character{D}, -\character{F}, and \character{A}. -\end{methoddesc} - -\begin{methoddesc}{add_flag}{flag} -Set the flag(s) specified by \var{flag} without changing other flags. To add -more than one flag at a time, \var{flag} may be a string of more than one -character. -\end{methoddesc} - -\begin{methoddesc}{remove_flag}{flag} -Unset the flag(s) specified by \var{flag} without changing other flags. To -remove more than one flag at a time, \var{flag} maybe a string of more than one -character. -\end{methoddesc} - -When an \class{mboxMessage} instance is created based upon a -\class{MaildirMessage} instance, a "From~" line is generated based upon the -\class{MaildirMessage} instance's delivery date, and the following conversions -take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MaildirMessage} state} -\lineii{R flag}{S flag} -\lineii{O flag}{"cur" subdirectory} -\lineii{D flag}{T flag} -\lineii{F flag}{F flag} -\lineii{A flag}{R flag} -\end{tableii} - -When an \class{mboxMessage} instance is created based upon an \class{MHMessage} -instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MHMessage} state} -\lineii{R flag and O flag}{no "unseen" sequence} -\lineii{O flag}{"unseen" sequence} -\lineii{F flag}{"flagged" sequence} -\lineii{A flag}{"replied" sequence} -\end{tableii} - -When an \class{mboxMessage} instance is created based upon a -\class{BabylMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{BabylMessage} state} -\lineii{R flag and O flag}{no "unseen" label} -\lineii{O flag}{"unseen" label} -\lineii{D flag}{"deleted" label} -\lineii{A flag}{"answered" label} -\end{tableii} - -When a \class{Message} instance is created based upon an \class{MMDFMessage} -instance, the "From~" line is copied and all flags directly correspond: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MMDFMessage} state} -\lineii{R flag}{R flag} -\lineii{O flag}{O flag} -\lineii{D flag}{D flag} -\lineii{F flag}{F flag} -\lineii{A flag}{A flag} -\end{tableii} - -\subsubsection{\class{MHMessage}} -\label{mailbox-mhmessage} - -\begin{classdesc}{MHMessage}{\optional{message}} -A message with MH-specific behaviors. Parameter \var{message} has the same -meaning as with the \class{Message} constructor. -\end{classdesc} - -MH messages do not support marks or flags in the traditional sense, but they do -support sequences, which are logical groupings of arbitrary messages. Some mail -reading programs (although not the standard \program{mh} and \program{nmh}) use -sequences in much the same way flags are used with other formats, as follows: - -\begin{tableii}{l|l}{textrm}{Sequence}{Explanation} -\lineii{unseen}{Not read, but previously detected by MUA} -\lineii{replied}{Replied to} -\lineii{flagged}{Marked as important} -\end{tableii} - -\class{MHMessage} instances offer the following methods: - -\begin{methoddesc}{get_sequences}{} -Return a list of the names of sequences that include this message. -\end{methoddesc} - -\begin{methoddesc}{set_sequences}{sequences} -Set the list of sequences that include this message. -\end{methoddesc} - -\begin{methoddesc}{add_sequence}{sequence} -Add \var{sequence} to the list of sequences that include this message. -\end{methoddesc} - -\begin{methoddesc}{remove_sequence}{sequence} -Remove \var{sequence} from the list of sequences that include this message. -\end{methoddesc} - -When an \class{MHMessage} instance is created based upon a -\class{MaildirMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MaildirMessage} state} -\lineii{"unseen" sequence}{no S flag} -\lineii{"replied" sequence}{R flag} -\lineii{"flagged" sequence}{F flag} -\end{tableii} - -When an \class{MHMessage} instance is created based upon an \class{mboxMessage} -or \class{MMDFMessage} instance, the \mailheader{Status} and -\mailheader{X-Status} headers are omitted and the following conversions take -place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state} -\lineii{"unseen" sequence}{no R flag} -\lineii{"replied" sequence}{A flag} -\lineii{"flagged" sequence}{F flag} -\end{tableii} - -When an \class{MHMessage} instance is created based upon a \class{BabylMessage} -instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{BabylMessage} state} -\lineii{"unseen" sequence}{"unseen" label} -\lineii{"replied" sequence}{"answered" label} -\end{tableii} - -\subsubsection{\class{BabylMessage}} -\label{mailbox-babylmessage} - -\begin{classdesc}{BabylMessage}{\optional{message}} -A message with Babyl-specific behaviors. Parameter \var{message} has the same -meaning as with the \class{Message} constructor. -\end{classdesc} - -Certain message labels, called \dfn{attributes}, are defined by convention to -have special meanings. The attributes are as follows: - -\begin{tableii}{l|l}{textrm}{Label}{Explanation} -\lineii{unseen}{Not read, but previously detected by MUA} -\lineii{deleted}{Marked for subsequent deletion} -\lineii{filed}{Copied to another file or mailbox} -\lineii{answered}{Replied to} -\lineii{forwarded}{Forwarded} -\lineii{edited}{Modified by the user} -\lineii{resent}{Resent} -\end{tableii} - -By default, Rmail displays only -visible headers. The \class{BabylMessage} class, though, uses the original -headers because they are more complete. Visible headers may be accessed -explicitly if desired. - -\class{BabylMessage} instances offer the following methods: - -\begin{methoddesc}{get_labels}{} -Return a list of labels on the message. -\end{methoddesc} - -\begin{methoddesc}{set_labels}{labels} -Set the list of labels on the message to \var{labels}. -\end{methoddesc} - -\begin{methoddesc}{add_label}{label} -Add \var{label} to the list of labels on the message. -\end{methoddesc} - -\begin{methoddesc}{remove_label}{label} -Remove \var{label} from the list of labels on the message. -\end{methoddesc} - -\begin{methoddesc}{get_visible}{} -Return an \class{Message} instance whose headers are the message's visible -headers and whose body is empty. -\end{methoddesc} - -\begin{methoddesc}{set_visible}{visible} -Set the message's visible headers to be the same as the headers in -\var{message}. Parameter \var{visible} should be a \class{Message} instance, an -\class{email.Message.Message} instance, a string, or a file-like object (which -should be open in text mode). -\end{methoddesc} - -\begin{methoddesc}{update_visible}{} -When a \class{BabylMessage} instance's original headers are modified, the -visible headers are not automatically modified to correspond. This method -updates the visible headers as follows: each visible header with a -corresponding original header is set to the value of the original header, each -visible header without a corresponding original header is removed, and any of -\mailheader{Date}, \mailheader{From}, \mailheader{Reply-To}, \mailheader{To}, -\mailheader{CC}, and \mailheader{Subject} that are present in the original -headers but not the visible headers are added to the visible headers. -\end{methoddesc} - -When a \class{BabylMessage} instance is created based upon a -\class{MaildirMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MaildirMessage} state} -\lineii{"unseen" label}{no S flag} -\lineii{"deleted" label}{T flag} -\lineii{"answered" label}{R flag} -\lineii{"forwarded" label}{P flag} -\end{tableii} - -When a \class{BabylMessage} instance is created based upon an -\class{mboxMessage} or \class{MMDFMessage} instance, the \mailheader{Status} -and \mailheader{X-Status} headers are omitted and the following conversions -take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{mboxMessage} or \class{MMDFMessage} state} -\lineii{"unseen" label}{no R flag} -\lineii{"deleted" label}{D flag} -\lineii{"answered" label}{A flag} -\end{tableii} - -When a \class{BabylMessage} instance is created based upon an \class{MHMessage} -instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MHMessage} state} -\lineii{"unseen" label}{"unseen" sequence} -\lineii{"answered" label}{"replied" sequence} -\end{tableii} - -\subsubsection{\class{MMDFMessage}} -\label{mailbox-mmdfmessage} - -\begin{classdesc}{MMDFMessage}{\optional{message}} -A message with MMDF-specific behaviors. Parameter \var{message} has the same -meaning as with the \class{Message} constructor. -\end{classdesc} - -As with message in an mbox mailbox, MMDF messages are stored with the sender's -address and the delivery date in an initial line beginning with "From ". -Likewise, flags that indicate the state of the message are typically stored in -\mailheader{Status} and \mailheader{X-Status} headers. - -Conventional flags for MMDF messages are identical to those of mbox message and -are as follows: - -\begin{tableiii}{l|l|l}{textrm}{Flag}{Meaning}{Explanation} -\lineiii{R}{Read}{Read} -\lineiii{O}{Old}{Previously detected by MUA} -\lineiii{D}{Deleted}{Marked for subsequent deletion} -\lineiii{F}{Flagged}{Marked as important} -\lineiii{A}{Answered}{Replied to} -\end{tableiii} - -The "R" and "O" flags are stored in the \mailheader{Status} header, and the -"D", "F", and "A" flags are stored in the \mailheader{X-Status} header. The -flags and headers typically appear in the order mentioned. - -\class{MMDFMessage} instances offer the following methods, which are identical -to those offered by \class{mboxMessage}: - -\begin{methoddesc}{get_from}{} -Return a string representing the "From~" line that marks the start of the -message in an mbox mailbox. The leading "From~" and the trailing newline are -excluded. -\end{methoddesc} - -\begin{methoddesc}{set_from}{from_\optional{, time_=None}} -Set the "From~" line to \var{from_}, which should be specified without a -leading "From~" or trailing newline. For convenience, \var{time_} may be -specified and will be formatted appropriately and appended to \var{from_}. If -\var{time_} is specified, it should be a \class{struct_time} instance, a tuple -suitable for passing to \method{time.strftime()}, or \code{True} (to use -\method{time.gmtime()}). -\end{methoddesc} - -\begin{methoddesc}{get_flags}{} -Return a string specifying the flags that are currently set. If the message -complies with the conventional format, the result is the concatenation in the -following order of zero or one occurrence of each of \character{R}, -\character{O}, \character{D}, \character{F}, and \character{A}. -\end{methoddesc} - -\begin{methoddesc}{set_flags}{flags} -Set the flags specified by \var{flags} and unset all others. Parameter -\var{flags} should be the concatenation in any order of zero or more -occurrences of each of \character{R}, \character{O}, \character{D}, -\character{F}, and \character{A}. -\end{methoddesc} - -\begin{methoddesc}{add_flag}{flag} -Set the flag(s) specified by \var{flag} without changing other flags. To add -more than one flag at a time, \var{flag} may be a string of more than one -character. -\end{methoddesc} - -\begin{methoddesc}{remove_flag}{flag} -Unset the flag(s) specified by \var{flag} without changing other flags. To -remove more than one flag at a time, \var{flag} maybe a string of more than one -character. -\end{methoddesc} - -When an \class{MMDFMessage} instance is created based upon a -\class{MaildirMessage} instance, a "From~" line is generated based upon the -\class{MaildirMessage} instance's delivery date, and the following conversions -take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MaildirMessage} state} -\lineii{R flag}{S flag} -\lineii{O flag}{"cur" subdirectory} -\lineii{D flag}{T flag} -\lineii{F flag}{F flag} -\lineii{A flag}{R flag} -\end{tableii} - -When an \class{MMDFMessage} instance is created based upon an \class{MHMessage} -instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{MHMessage} state} -\lineii{R flag and O flag}{no "unseen" sequence} -\lineii{O flag}{"unseen" sequence} -\lineii{F flag}{"flagged" sequence} -\lineii{A flag}{"replied" sequence} -\end{tableii} - -When an \class{MMDFMessage} instance is created based upon a -\class{BabylMessage} instance, the following conversions take place: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{BabylMessage} state} -\lineii{R flag and O flag}{no "unseen" label} -\lineii{O flag}{"unseen" label} -\lineii{D flag}{"deleted" label} -\lineii{A flag}{"answered" label} -\end{tableii} - -When an \class{MMDFMessage} instance is created based upon an -\class{mboxMessage} instance, the "From~" line is copied and all flags directly -correspond: - -\begin{tableii}{l|l}{textrm} - {Resulting state}{\class{mboxMessage} state} -\lineii{R flag}{R flag} -\lineii{O flag}{O flag} -\lineii{D flag}{D flag} -\lineii{F flag}{F flag} -\lineii{A flag}{A flag} -\end{tableii} - -\subsection{Exceptions} - -The following exception classes are defined in the \module{mailbox} module: - -\begin{classdesc}{Error}{} -The based class for all other module-specific exceptions. -\end{classdesc} - -\begin{classdesc}{NoSuchMailboxError}{} -Raised when a mailbox is expected but is not found, such as when instantiating -a \class{Mailbox} subclass with a path that does not exist (and with the -\var{create} parameter set to \code{False}), or when opening a folder that does -not exist. -\end{classdesc} - -\begin{classdesc}{NotEmptyErrorError}{} -Raised when a mailbox is not empty but is expected to be, such as when deleting -a folder that contains messages. -\end{classdesc} - -\begin{classdesc}{ExternalClashError}{} -Raised when some mailbox-related condition beyond the control of the program -causes it to be unable to proceed, such as when failing to acquire a lock that -another program already holds a lock, or when a uniquely-generated file name -already exists. -\end{classdesc} - -\begin{classdesc}{FormatError}{} -Raised when the data in a file cannot be parsed, such as when an \class{MH} -instance attempts to read a corrupted \file{.mh_sequences} file. -\end{classdesc} - -\subsection{Deprecated classes and methods} -\label{mailbox-deprecated} - -Older versions of the \module{mailbox} module do not support modification of -mailboxes, such as adding or removing message, and do not provide classes to -represent format-specific message properties. For backward compatibility, the -older mailbox classes are still available, but the newer classes should be used -in preference to them. - -Older mailbox objects support only iteration and provide a single public -method: - -\begin{methoddesc}[oldmailbox]{next}{} -Return the next message in the mailbox, created with the optional \var{factory} -argument passed into the mailbox object's constructor. By default this is an -\class{rfc822.Message} object (see the \refmodule{rfc822} module). Depending -on the mailbox implementation the \var{fp} attribute of this object may be a -true file object or a class instance simulating a file object, taking care of -things like message boundaries if multiple mail messages are contained in a -single file, etc. If no more messages are available, this method returns -\code{None}. -\end{methoddesc} - -Most of the older mailbox classes have names that differ from the current -mailbox class names, except for \class{Maildir}. For this reason, the new -\class{Maildir} class defines a \method{next()} method and its constructor -differs slightly from those of the other new mailbox classes. - -The older mailbox classes whose names are not the same as their newer -counterparts are as follows: - -\begin{classdesc}{UnixMailbox}{fp\optional{, factory}} -Access to a classic \UNIX-style mailbox, where all messages are -contained in a single file and separated by \samp{From } -(a.k.a.\ \samp{From_}) lines. The file object \var{fp} points to the -mailbox file. The optional \var{factory} parameter is a callable that -should create new message objects. \var{factory} is called with one -argument, \var{fp} by the \method{next()} method of the mailbox -object. The default is the \class{rfc822.Message} class (see the -\refmodule{rfc822} module -- and the note below). - -\begin{notice} - For reasons of this module's internal implementation, you will - probably want to open the \var{fp} object in binary mode. This is - especially important on Windows. -\end{notice} - -For maximum portability, messages in a \UNIX-style mailbox are -separated by any line that begins exactly with the string \code{'From -'} (note the trailing space) if preceded by exactly two newlines. -Because of the wide-range of variations in practice, nothing else on -the \samp{From_} line should be considered. However, the current -implementation doesn't check for the leading two newlines. This is -usually fine for most applications. - -The \class{UnixMailbox} class implements a more strict version of -\samp{From_} line checking, using a regular expression that usually correctly -matched \samp{From_} delimiters. It considers delimiter line to be separated -by \samp{From \var{name} \var{time}} lines. For maximum portability, -use the \class{PortableUnixMailbox} class instead. This class is -identical to \class{UnixMailbox} except that individual messages are -separated by only \samp{From } lines. - -For more information, see -\citetitle[http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html]{Configuring -Netscape Mail on \UNIX: Why the Content-Length Format is Bad}. -\end{classdesc} - -\begin{classdesc}{PortableUnixMailbox}{fp\optional{, factory}} -A less-strict version of \class{UnixMailbox}, which considers only the -\samp{From } at the beginning of the line separating messages. The -``\var{name} \var{time}'' portion of the From line is ignored, to -protect against some variations that are observed in practice. This -works since lines in the message which begin with \code{'From '} are -quoted by mail handling software at delivery-time. -\end{classdesc} - -\begin{classdesc}{MmdfMailbox}{fp\optional{, factory}} -Access an MMDF-style mailbox, where all messages are contained -in a single file and separated by lines consisting of 4 control-A -characters. The file object \var{fp} points to the mailbox file. -Optional \var{factory} is as with the \class{UnixMailbox} class. -\end{classdesc} - -\begin{classdesc}{MHMailbox}{dirname\optional{, factory}} -Access an MH mailbox, a directory with each message in a separate -file with a numeric name. -The name of the mailbox directory is passed in \var{dirname}. -\var{factory} is as with the \class{UnixMailbox} class. -\end{classdesc} - -\begin{classdesc}{BabylMailbox}{fp\optional{, factory}} -Access a Babyl mailbox, which is similar to an MMDF mailbox. In -Babyl format, each message has two sets of headers, the -\emph{original} headers and the \emph{visible} headers. The original -headers appear before a line containing only \code{'*** EOOH ***'} -(End-Of-Original-Headers) and the visible headers appear after the -\code{EOOH} line. Babyl-compliant mail readers will show you only the -visible headers, and \class{BabylMailbox} objects will return messages -containing only the visible headers. You'll have to do your own -parsing of the mailbox file to get at the original headers. Mail -messages start with the EOOH line and end with a line containing only -\code{'\e{}037\e{}014'}. \var{factory} is as with the -\class{UnixMailbox} class. -\end{classdesc} - -If you wish to use the older mailbox classes with the \module{email} module -rather than the deprecated \module{rfc822} module, you can do so as follows: - -\begin{verbatim} -import email -import email.Errors -import mailbox - -def msgfactory(fp): - try: - return email.message_from_file(fp) - except email.Errors.MessageParseError: - # Don't return None since that will - # stop the mailbox iterator - return '' - -mbox = mailbox.UnixMailbox(fp, msgfactory) -\end{verbatim} - -Alternatively, if you know your mailbox contains only well-formed MIME -messages, you can simplify this to: - -\begin{verbatim} -import email -import mailbox - -mbox = mailbox.UnixMailbox(fp, email.message_from_file) -\end{verbatim} - -\subsection{Examples} -\label{mailbox-examples} - -A simple example of printing the subjects of all messages in a mailbox that -seem interesting: - -\begin{verbatim} -import mailbox -for message in mailbox.mbox('~/mbox'): - subject = message['subject'] # Could possibly be None. - if subject and 'python' in subject.lower(): - print subject -\end{verbatim} - -To copy all mail from a Babyl mailbox to an MH mailbox, converting all -of the format-specific information that can be converted: - -\begin{verbatim} -import mailbox -destination = mailbox.MH('~/Mail') -destination.lock() -for message in mailbox.Babyl('~/RMAIL'): - destination.add(MHMessage(message)) -destination.flush() -destination.unlock() -\end{verbatim} - -This example sorts mail from several mailing lists into different -mailboxes, being careful to avoid mail corruption due to concurrent -modification by other programs, mail loss due to interruption of the -program, or premature termination due to malformed messages in the -mailbox: - -\begin{verbatim} -import mailbox -import email.Errors - -list_names = ('python-list', 'python-dev', 'python-bugs') - -boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names) -inbox = mailbox.Maildir('~/Maildir', factory=None) - -for key in inbox.iterkeys(): - try: - message = inbox[key] - except email.Errors.MessageParseError: - continue # The message is malformed. Just leave it. - - for name in list_names: - list_id = message['list-id'] - if list_id and name in list_id: - # Get mailbox to use - box = boxes[name] - - # Write copy to disk before removing original. - # If there's a crash, you might duplicate a message, but - # that's better than losing a message completely. - box.lock() - box.add(message) - box.flush() - box.unlock() - - # Remove original message - inbox.lock() - inbox.discard(key) - inbox.flush() - inbox.unlock() - break # Found destination, so stop looking. - -for box in boxes.itervalues(): - box.close() -\end{verbatim} diff --git a/Doc/lib/libmailcap.tex b/Doc/lib/libmailcap.tex deleted file mode 100644 index b221bb3..0000000 --- a/Doc/lib/libmailcap.tex +++ /dev/null @@ -1,82 +0,0 @@ -\section{\module{mailcap} --- - Mailcap file handling.} -\declaremodule{standard}{mailcap} - -\modulesynopsis{Mailcap file handling.} - - -Mailcap files are used to configure how MIME-aware applications such -as mail readers and Web browsers react to files with different MIME -types. (The name ``mailcap'' is derived from the phrase ``mail -capability''.) For example, a mailcap file might contain a line like -\samp{video/mpeg; xmpeg \%s}. Then, if the user encounters an email -message or Web document with the MIME type \mimetype{video/mpeg}, -\samp{\%s} will be replaced by a filename (usually one belonging to a -temporary file) and the \program{xmpeg} program can be automatically -started to view the file. - -The mailcap format is documented in \rfc{1524}, ``A User Agent -Configuration Mechanism For Multimedia Mail Format Information,'' but -is not an Internet standard. However, mailcap files are supported on -most \UNIX{} systems. - -\begin{funcdesc}{findmatch}{caps, MIMEtype% - \optional{, key\optional{, - filename\optional{, plist}}}} -Return a 2-tuple; the first element is a string containing the command -line to be executed -(which can be passed to \function{os.system()}), and the second element is -the mailcap entry for a given MIME type. If no matching MIME -type can be found, \code{(None, None)} is returned. - -\var{key} is the name of the field desired, which represents the type -of activity to be performed; the default value is 'view', since in the -most common case you simply want to view the body of the MIME-typed -data. Other possible values might be 'compose' and 'edit', if you -wanted to create a new body of the given MIME type or alter the -existing body data. See \rfc{1524} for a complete list of these -fields. - -\var{filename} is the filename to be substituted for \samp{\%s} in the -command line; the default value is -\code{'/dev/null'} which is almost certainly not what you want, so -usually you'll override it by specifying a filename. - -\var{plist} can be a list containing named parameters; the default -value is simply an empty list. Each entry in the list must be a -string containing the parameter name, an equals sign (\character{=}), -and the parameter's value. Mailcap entries can contain -named parameters like \code{\%\{foo\}}, which will be replaced by the -value of the parameter named 'foo'. For example, if the command line -\samp{showpartial \%\{id\}\ \%\{number\}\ \%\{total\}} -was in a mailcap file, and \var{plist} was set to \code{['id=1', -'number=2', 'total=3']}, the resulting command line would be -\code{'showpartial 1 2 3'}. - -In a mailcap file, the ``test'' field can optionally be specified to -test some external condition (such as the machine architecture, or the -window system in use) to determine whether or not the mailcap line -applies. \function{findmatch()} will automatically check such -conditions and skip the entry if the check fails. -\end{funcdesc} - -\begin{funcdesc}{getcaps}{} -Returns a dictionary mapping MIME types to a list of mailcap file -entries. This dictionary must be passed to the \function{findmatch()} -function. An entry is stored as a list of dictionaries, but it -shouldn't be necessary to know the details of this representation. - -The information is derived from all of the mailcap files found on the -system. Settings in the user's mailcap file \file{\$HOME/.mailcap} -will override settings in the system mailcap files -\file{/etc/mailcap}, \file{/usr/etc/mailcap}, and -\file{/usr/local/etc/mailcap}. -\end{funcdesc} - -An example usage: -\begin{verbatim} ->>> import mailcap ->>> d=mailcap.getcaps() ->>> mailcap.findmatch(d, 'video/mpeg', filename='/tmp/tmp1223') -('xmpeg /tmp/tmp1223', {'view': 'xmpeg %s'}) -\end{verbatim} diff --git a/Doc/lib/libmain.tex b/Doc/lib/libmain.tex deleted file mode 100644 index 00c7426..0000000 --- a/Doc/lib/libmain.tex +++ /dev/null @@ -1,16 +0,0 @@ -\section{\module{__main__} --- - Top-level script environment} - -\declaremodule[main]{builtin}{__main__} -\modulesynopsis{The environment where the top-level script is run.} - -This module represents the (otherwise anonymous) scope in which the -interpreter's main program executes --- commands read either from -standard input, from a script file, or from an interactive prompt. It -is this environment in which the idiomatic ``conditional script'' -stanza causes a script to run: - -\begin{verbatim} -if __name__ == "__main__": - main() -\end{verbatim} diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex deleted file mode 100644 index 63ff392..0000000 --- a/Doc/lib/libmarshal.tex +++ /dev/null @@ -1,117 +0,0 @@ -\section{\module{marshal} --- - Internal Python object serialization} - -\declaremodule{builtin}{marshal} -\modulesynopsis{Convert Python objects to streams of bytes and back - (with different constraints).} - - -This module contains functions that can read and write Python -values in a binary format. The format is specific to Python, but -independent of machine architecture issues (e.g., you can write a -Python value to a file on a PC, transport the file to a Sun, and read -it back there). Details of the format are undocumented on purpose; -it may change between Python versions (although it rarely -does).\footnote{The name of this module stems from a bit of - terminology used by the designers of Modula-3 (amongst others), who - use the term ``marshalling'' for shipping of data around in a - self-contained form. Strictly speaking, ``to marshal'' means to - convert some data from internal to external form (in an RPC buffer for - instance) and ``unmarshalling'' for the reverse process.} - -This is not a general ``persistence'' module. For general persistence -and transfer of Python objects through RPC calls, see the modules -\refmodule{pickle} and \refmodule{shelve}. The \module{marshal} module exists -mainly to support reading and writing the ``pseudo-compiled'' code for -Python modules of \file{.pyc} files. Therefore, the Python -maintainers reserve the right to modify the marshal format in backward -incompatible ways should the need arise. If you're serializing and -de-serializing Python objects, use the \module{pickle} module instead. -\refstmodindex{pickle} -\refstmodindex{shelve} -\obindex{code} - -\begin{notice}[warning] -The \module{marshal} module is not intended to be secure against -erroneous or maliciously constructed data. Never unmarshal data -received from an untrusted or unauthenticated source. -\end{notice} - -Not all Python object types are supported; in general, only objects -whose value is independent from a particular invocation of Python can -be written and read by this module. The following types are supported: -\code{None}, integers, long integers, floating point numbers, -strings, Unicode objects, tuples, lists, dictionaries, and code -objects, where it should be understood that tuples, lists and -dictionaries are only supported as long as the values contained -therein are themselves supported; and recursive lists and dictionaries -should not be written (they will cause infinite loops). - -\strong{Caveat:} On machines where C's \code{long int} type has more than -32 bits (such as the DEC Alpha), it is possible to create plain Python -integers that are longer than 32 bits. -If such an integer is marshaled and read back in on a machine where -C's \code{long int} type has only 32 bits, a Python long integer object -is returned instead. While of a different type, the numeric value is -the same. (This behavior is new in Python 2.2. In earlier versions, -all but the least-significant 32 bits of the value were lost, and a -warning message was printed.) - -There are functions that read/write files as well as functions -operating on strings. - -The module defines these functions: - -\begin{funcdesc}{dump}{value, file\optional{, version}} - 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()}. 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 - will also be written to the file. The object will not be properly - read back by \function{load()}. - - \versionadded[The \var{version} argument indicates the data - format that \code{dump} should use (see below)]{2.4} -\end{funcdesc} - -\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 opened - in binary mode (\code{'rb'} or \code{'r+b'}). - - \warning{If an object containing an unsupported type was - marshalled with \function{dump()}, \function{load()} will substitute - \code{None} for the unmarshallable type.} -\end{funcdesc} - -\begin{funcdesc}{dumps}{value\optional{, version}} - Return the string that would be written to a file by - \code{dump(\var{value}, \var{file})}. The value must be a supported - type. Raise a \exception{ValueError} exception if value has (or - contains an object that has) an unsupported type. - - \versionadded[The \var{version} argument indicates the data - format that \code{dumps} should use (see below)]{2.4} -\end{funcdesc} - -\begin{funcdesc}{loads}{string} - Convert the string to a value. If no valid value is found, raise - \exception{EOFError}, \exception{ValueError} or - \exception{TypeError}. Extra characters in the string are ignored. -\end{funcdesc} - -In addition, the following constants are defined: - -\begin{datadesc}{version} - Indicates the format that the module uses. Version 0 is the - historical format, version 1 (added in Python 2.4) shares interned - strings and version 2 (added in Python 2.5) uses a binary format for - floating point numbers. The current version is 2. - - \versionadded{2.4} -\end{datadesc} diff --git a/Doc/lib/libmath.tex b/Doc/lib/libmath.tex deleted file mode 100644 index e52f8f9..0000000 --- a/Doc/lib/libmath.tex +++ /dev/null @@ -1,209 +0,0 @@ -\section{\module{math} --- - Mathematical functions} - -\declaremodule{builtin}{math} -\modulesynopsis{Mathematical functions (\function{sin()} etc.).} - -This module is always available. It provides access to the -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 are provided by this module. Except -when explicitly noted otherwise, all return values are floats. - -Number-theoretic and representation functions: - -\begin{funcdesc}{ceil}{x} -Return the ceiling of \var{x} as a float, the smallest integer value -greater than or equal to \var{x}. -\end{funcdesc} - -\begin{funcdesc}{fabs}{x} -Return the absolute value of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{floor}{x} -Return the floor of \var{x} as a float, the largest integer value -less than or equal to \var{x}. -\end{funcdesc} - -\begin{funcdesc}{fmod}{x, y} -Return \code{fmod(\var{x}, \var{y})}, as defined by the platform C library. -Note that the Python expression \code{\var{x} \%\ \var{y}} may not return -the same result. The intent of the C standard is that -\code{fmod(\var{x}, \var{y})} be exactly (mathematically; to infinite -precision) equal to \code{\var{x} - \var{n}*\var{y}} for some integer -\var{n} such that the result has the same sign as \var{x} and -magnitude less than \code{abs(\var{y})}. Python's -\code{\var{x} \%\ \var{y}} returns a result with the sign of -\var{y} instead, and may not be exactly computable for float arguments. -For example, \code{fmod(-1e-100, 1e100)} is \code{-1e-100}, but the -result of Python's \code{-1e-100 \%\ 1e100} is \code{1e100-1e-100}, which -cannot be represented exactly as a float, and rounds to the surprising -\code{1e100}. For this reason, function \function{fmod()} is generally -preferred when working with floats, while Python's -\code{\var{x} \%\ \var{y}} is preferred when working with integers. -\end{funcdesc} - -\begin{funcdesc}{frexp}{x} -Return the mantissa and exponent of \var{x} as the pair -\code{(\var{m}, \var{e})}. \var{m} is a float and \var{e} is an -integer such that \code{\var{x} == \var{m} * 2**\var{e}} exactly. -If \var{x} is zero, returns \code{(0.0, 0)}, otherwise -\code{0.5 <= abs(\var{m}) < 1}. This is used to "pick apart" the -internal representation of a float in a portable way. -\end{funcdesc} - -\begin{funcdesc}{ldexp}{x, i} -Return \code{\var{x} * (2**\var{i})}. This is essentially the inverse of -function \function{frexp()}. -\end{funcdesc} - -\begin{funcdesc}{modf}{x} -Return the fractional and integer parts of \var{x}. Both results -carry the sign of \var{x}, and both are floats. -\end{funcdesc} - -Note that \function{frexp()} and \function{modf()} have a different -call/return pattern than their C equivalents: they take a single -argument and return a pair of values, rather than returning their -second return value through an `output parameter' (there is no such -thing in Python). - -For the \function{ceil()}, \function{floor()}, and \function{modf()} -functions, note that \emph{all} floating-point numbers of sufficiently -large magnitude are exact integers. Python floats typically carry no more -than 53 bits of precision (the same as the platform C double type), in -which case any float \var{x} with \code{abs(\var{x}) >= 2**52} -necessarily has no fractional bits. - - -Power and logarithmic functions: - -\begin{funcdesc}{exp}{x} -Return \code{e**\var{x}}. -\end{funcdesc} - -\begin{funcdesc}{log}{x\optional{, base}} -Return the logarithm of \var{x} to the given \var{base}. -If the \var{base} is not specified, return the natural logarithm of \var{x} -(that is, the logarithm to base \emph{e}). -\versionchanged[\var{base} argument added]{2.3} -\end{funcdesc} - -\begin{funcdesc}{log10}{x} -Return the base-10 logarithm of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{pow}{x, y} -Return \code{\var{x}**\var{y}}. -\end{funcdesc} - -\begin{funcdesc}{sqrt}{x} -Return the square root of \var{x}. -\end{funcdesc} - -Trigonometric functions: - -\begin{funcdesc}{acos}{x} -Return the arc cosine of \var{x}, in radians. -\end{funcdesc} - -\begin{funcdesc}{asin}{x} -Return the arc sine of \var{x}, in radians. -\end{funcdesc} - -\begin{funcdesc}{atan}{x} -Return the arc tangent of \var{x}, in radians. -\end{funcdesc} - -\begin{funcdesc}{atan2}{y, x} -Return \code{atan(\var{y} / \var{x})}, in radians. -The result is between \code{-pi} and \code{pi}. -The vector in the plane from the origin to point \code{(\var{x}, \var{y})} -makes this angle with the positive X axis. -The point of \function{atan2()} is that the signs of both inputs are -known to it, so it can compute the correct quadrant for the angle. -For example, \code{atan(1}) and \code{atan2(1, 1)} are both \code{pi/4}, -but \code{atan2(-1, -1)} is \code{-3*pi/4}. -\end{funcdesc} - -\begin{funcdesc}{cos}{x} -Return the cosine of \var{x} radians. -\end{funcdesc} - -\begin{funcdesc}{hypot}{x, y} -Return the Euclidean norm, \code{sqrt(\var{x}*\var{x} + \var{y}*\var{y})}. -This is the length of the vector from the origin to point -\code{(\var{x}, \var{y})}. -\end{funcdesc} - -\begin{funcdesc}{sin}{x} -Return the sine of \var{x} radians. -\end{funcdesc} - -\begin{funcdesc}{tan}{x} -Return the tangent of \var{x} radians. -\end{funcdesc} - -Angular conversion: - -\begin{funcdesc}{degrees}{x} -Converts angle \var{x} from radians to degrees. -\end{funcdesc} - -\begin{funcdesc}{radians}{x} -Converts angle \var{x} from degrees to radians. -\end{funcdesc} - -Hyperbolic functions: - -\begin{funcdesc}{cosh}{x} -Return the hyperbolic cosine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{sinh}{x} -Return the hyperbolic sine of \var{x}. -\end{funcdesc} - -\begin{funcdesc}{tanh}{x} -Return the hyperbolic tangent of \var{x}. -\end{funcdesc} - -The module also defines two mathematical constants: - -\begin{datadesc}{pi} -The mathematical constant \emph{pi}. -\end{datadesc} - -\begin{datadesc}{e} -The mathematical constant \emph{e}. -\end{datadesc} - -\begin{notice} - The \module{math} module consists mostly of thin wrappers around - the platform C math library functions. Behavior in exceptional cases is - loosely specified by the C standards, and Python inherits much of its - math-function error-reporting behavior from the platform C - implementation. As a result, - the specific exceptions raised in error cases (and even whether some - arguments are considered to be exceptional at all) are not defined in any - useful cross-platform or cross-release way. For example, whether - \code{math.log(0)} returns \code{-Inf} or raises \exception{ValueError} or - \exception{OverflowError} isn't defined, and in - cases where \code{math.log(0)} raises \exception{OverflowError}, - \code{math.log(0L)} may raise \exception{ValueError} instead. -\end{notice} - -\begin{seealso} - \seemodule{cmath}{Complex number versions of many of these functions.} -\end{seealso} diff --git a/Doc/lib/libmhlib.tex b/Doc/lib/libmhlib.tex deleted file mode 100644 index 3e70663..0000000 --- a/Doc/lib/libmhlib.tex +++ /dev/null @@ -1,168 +0,0 @@ -\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.} - - -The \module{mhlib} module provides a Python interface to MH folders and -their contents. - -The module contains three basic classes, \class{MH}, which represents a -particular collection of folders, \class{Folder}, which represents a single -folder, and \class{Message}, which represents a single message. - - -\begin{classdesc}{MH}{\optional{path\optional{, profile}}} -\class{MH} represents a collection of MH folders. -\end{classdesc} - -\begin{classdesc}{Folder}{mh, name} -The \class{Folder} class represents a single folder and its messages. -\end{classdesc} - -\begin{classdesc}{Message}{folder, number\optional{, name}} -\class{Message} objects represent individual messages in a folder. The -Message class is derived from \class{mimetools.Message}. -\end{classdesc} - - -\subsection{MH Objects \label{mh-objects}} - -\class{MH} instances have the following methods: - - -\begin{methoddesc}[MH]{error}{format\optional{, ...}} -Print an error message -- can be overridden. -\end{methoddesc} - -\begin{methoddesc}[MH]{getprofile}{key} -Return a profile entry (\code{None} if not set). -\end{methoddesc} - -\begin{methoddesc}[MH]{getpath}{} -Return the mailbox pathname. -\end{methoddesc} - -\begin{methoddesc}[MH]{getcontext}{} -Return the current folder name. -\end{methoddesc} - -\begin{methoddesc}[MH]{setcontext}{name} -Set the current folder name. -\end{methoddesc} - -\begin{methoddesc}[MH]{listfolders}{} -Return a list of top-level folders. -\end{methoddesc} - -\begin{methoddesc}[MH]{listallfolders}{} -Return a list of all folders. -\end{methoddesc} - -\begin{methoddesc}[MH]{listsubfolders}{name} -Return a list of direct subfolders of the given folder. -\end{methoddesc} - -\begin{methoddesc}[MH]{listallsubfolders}{name} -Return a list of all subfolders of the given folder. -\end{methoddesc} - -\begin{methoddesc}[MH]{makefolder}{name} -Create a new folder. -\end{methoddesc} - -\begin{methoddesc}[MH]{deletefolder}{name} -Delete a folder -- must have no subfolders. -\end{methoddesc} - -\begin{methoddesc}[MH]{openfolder}{name} -Return a new open folder object. -\end{methoddesc} - - - -\subsection{Folder Objects \label{mh-folder-objects}} - -\class{Folder} instances represent open folders and have the following -methods: - - -\begin{methoddesc}[Folder]{error}{format\optional{, ...}} -Print an error message -- can be overridden. -\end{methoddesc} - -\begin{methoddesc}[Folder]{getfullname}{} -Return the folder's full pathname. -\end{methoddesc} - -\begin{methoddesc}[Folder]{getsequencesfilename}{} -Return the full pathname of the folder's sequences file. -\end{methoddesc} - -\begin{methoddesc}[Folder]{getmessagefilename}{n} -Return the full pathname of message \var{n} of the folder. -\end{methoddesc} - -\begin{methoddesc}[Folder]{listmessages}{} -Return a list of messages in the folder (as numbers). -\end{methoddesc} - -\begin{methoddesc}[Folder]{getcurrent}{} -Return the current message number. -\end{methoddesc} - -\begin{methoddesc}[Folder]{setcurrent}{n} -Set the current message number to \var{n}. -\end{methoddesc} - -\begin{methoddesc}[Folder]{parsesequence}{seq} -Parse msgs syntax into list of messages. -\end{methoddesc} - -\begin{methoddesc}[Folder]{getlast}{} -Get last message, or \code{0} if no messages are in the folder. -\end{methoddesc} - -\begin{methoddesc}[Folder]{setlast}{n} -Set last message (internal use only). -\end{methoddesc} - -\begin{methoddesc}[Folder]{getsequences}{} -Return dictionary of sequences in folder. The sequence names are used -as keys, and the values are the lists of message numbers in the -sequences. -\end{methoddesc} - -\begin{methoddesc}[Folder]{putsequences}{dict} -Return dictionary of sequences in folder {name: list}. -\end{methoddesc} - -\begin{methoddesc}[Folder]{removemessages}{list} -Remove messages in list from folder. -\end{methoddesc} - -\begin{methoddesc}[Folder]{refilemessages}{list, tofolder} -Move messages in list to other folder. -\end{methoddesc} - -\begin{methoddesc}[Folder]{movemessage}{n, tofolder, ton} -Move one message to a given destination in another folder. -\end{methoddesc} - -\begin{methoddesc}[Folder]{copymessage}{n, tofolder, ton} -Copy one message to a given destination in another folder. -\end{methoddesc} - - -\subsection{Message Objects \label{mh-message-objects}} - -The \class{Message} class adds one method to those of -\class{mimetools.Message}: - -\begin{methoddesc}[Message]{openmessage}{n} -Return a new open message object (costs a file descriptor). -\end{methoddesc} diff --git a/Doc/lib/libmimetools.tex b/Doc/lib/libmimetools.tex deleted file mode 100644 index 3e4bd4b..0000000 --- a/Doc/lib/libmimetools.tex +++ /dev/null @@ -1,120 +0,0 @@ -\section{\module{mimetools} --- - Tools for parsing MIME messages} - -\declaremodule{standard}{mimetools} -\modulesynopsis{Tools for parsing MIME-style message bodies.} - -\deprecated{2.3}{The \refmodule{email} package should be used in - preference to the \module{mimetools} module. This - module is present only to maintain backward - compatibility.} - -This module defines a subclass of the -\refmodule{rfc822}\refstmodindex{rfc822} module's -\class{Message} class and a number of utility functions that are -useful for the manipulation for MIME multipart or encoded message. - -It defines the following items: - -\begin{classdesc}{Message}{fp\optional{, seekable}} -Return a new instance of the \class{Message} class. This is a -subclass of the \class{rfc822.Message} class, with some additional -methods (see below). The \var{seekable} argument has the same meaning -as for \class{rfc822.Message}. -\end{classdesc} - -\begin{funcdesc}{choose_boundary}{} -Return a unique string that has a high likelihood of being usable as a -part boundary. The string has the form -\code{'\var{hostipaddr}.\var{uid}.\var{pid}.\var{timestamp}.\var{random}'}. -\end{funcdesc} - -\begin{funcdesc}{decode}{input, output, encoding} -Read data encoded using the allowed MIME \var{encoding} from open file -object \var{input} and write the decoded data to open file object -\var{output}. Valid values for \var{encoding} include -\code{'base64'}, \code{'quoted-printable'}, \code{'uuencode'}, -\code{'x-uuencode'}, \code{'uue'}, \code{'x-uue'}, \code{'7bit'}, and -\code{'8bit'}. Decoding messages encoded in \code{'7bit'} or \code{'8bit'} -has no effect. The input is simply copied to the output. -\end{funcdesc} - -\begin{funcdesc}{encode}{input, output, encoding} -Read data from open file object \var{input} and write it encoded using -the allowed MIME \var{encoding} to open file object \var{output}. -Valid values for \var{encoding} are the same as for \method{decode()}. -\end{funcdesc} - -\begin{funcdesc}{copyliteral}{input, output} -Read lines from open file \var{input} until \EOF{} and write them to -open file \var{output}. -\end{funcdesc} - -\begin{funcdesc}{copybinary}{input, output} -Read blocks until \EOF{} from open file \var{input} and write them to -open file \var{output}. The block size is currently fixed at 8192. -\end{funcdesc} - - -\begin{seealso} - \seemodule{email}{Comprehensive email handling package; supersedes - the \module{mimetools} module.} - \seemodule{rfc822}{Provides the base class for - \class{mimetools.Message}.} - \seemodule{multifile}{Support for reading files which contain - distinct parts, such as MIME data.} - \seeurl{http://www.cs.uu.nl/wais/html/na-dir/mail/mime-faq/.html}{ - The MIME Frequently Asked Questions document. For an - overview of MIME, see the answer to question 1.1 in Part 1 - of this document.} -\end{seealso} - - -\subsection{Additional Methods of Message Objects - \label{mimetools-message-objects}} - -The \class{Message} class defines the following methods in -addition to the \class{rfc822.Message} methods: - -\begin{methoddesc}[Message]{getplist}{} -Return the parameter list of the \mailheader{Content-Type} header. -This is a list of strings. For parameters of the form -\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but -\var{value} is not. For example, if the message contains the header -\samp{Content-type: text/html; spam=1; Spam=2; Spam} then -\method{getplist()} will return the Python list \code{['spam=1', -'spam=2', 'Spam']}. -\end{methoddesc} - -\begin{methoddesc}[Message]{getparam}{name} -Return the \var{value} of the first parameter (as returned by -\method{getplist()}) of the form \samp{\var{name}=\var{value}} for the -given \var{name}. If \var{value} is surrounded by quotes of the form -`\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed. -\end{methoddesc} - -\begin{methoddesc}[Message]{getencoding}{} -Return the encoding specified in the -\mailheader{Content-Transfer-Encoding} message header. If no such -header exists, return \code{'7bit'}. The encoding is converted to -lower case. -\end{methoddesc} - -\begin{methoddesc}[Message]{gettype}{} -Return the message type (of the form \samp{\var{type}/\var{subtype}}) -as specified in the \mailheader{Content-Type} header. If no such -header exists, return \code{'text/plain'}. The type is converted to -lower case. -\end{methoddesc} - -\begin{methoddesc}[Message]{getmaintype}{} -Return the main type as specified in the \mailheader{Content-Type} -header. If no such header exists, return \code{'text'}. The main -type is converted to lower case. -\end{methoddesc} - -\begin{methoddesc}[Message]{getsubtype}{} -Return the subtype as specified in the \mailheader{Content-Type} -header. If no such header exists, return \code{'plain'}. The subtype -is converted to lower case. -\end{methoddesc} diff --git a/Doc/lib/libmimetypes.tex b/Doc/lib/libmimetypes.tex deleted file mode 100644 index af99f08..0000000 --- a/Doc/lib/libmimetypes.tex +++ /dev/null @@ -1,226 +0,0 @@ -\section{\module{mimetypes} --- - Map filenames to MIME types} - -\declaremodule{standard}{mimetypes} -\modulesynopsis{Mapping of filename extensions to MIME types.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -\indexii{MIME}{content type} - -The \module{mimetypes} module converts between a filename or URL and -the MIME type associated with the filename extension. Conversions are -provided from filename to MIME type and from MIME type to filename -extension; encodings are not supported for the latter conversion. - -The module provides one class and a number of convenience functions. -The functions are the normal interface to this module, but some -applications may be interested in the class as well. - -The functions described below provide the primary interface for this -module. If the module has not been initialized, they will call -\function{init()} if they rely on the information \function{init()} -sets up. - - -\begin{funcdesc}{guess_type}{filename\optional{, strict}} -Guess the type of a file based on its filename or URL, given by -\var{filename}. The return value is a tuple \code{(\var{type}, -\var{encoding})} where \var{type} is \code{None} if the type can't be -guessed (missing or unknown suffix) or a string of the form -\code{'\var{type}/\var{subtype}'}, usable for a MIME -\mailheader{content-type} header\indexii{MIME}{headers}. - -\var{encoding} is \code{None} for no encoding or the name of the -program used to encode (e.g. \program{compress} or \program{gzip}). -The encoding is suitable for use as a \mailheader{Content-Encoding} -header, \emph{not} as a \mailheader{Content-Transfer-Encoding} header. -The mappings are table driven. Encoding suffixes are case sensitive; -type suffixes are first tried case sensitively, then case -insensitively. - -Optional \var{strict} is a flag specifying whether the list of known -MIME types is limited to only the official types \ulink{registered -with IANA}{http://www.isi.edu/in-notes/iana/assignments/media-types} -are recognized. When \var{strict} is true (the default), only the -IANA types are supported; when \var{strict} is false, some additional -non-standard but commonly used MIME types are also recognized. -\end{funcdesc} - -\begin{funcdesc}{guess_all_extensions}{type\optional{, strict}} -Guess the extensions for a file based on its MIME type, given by -\var{type}. -The return value is a list of strings giving all possible filename extensions, -including the leading dot (\character{.}). The extensions are not guaranteed -to have been associated with any particular data stream, but would be mapped -to the MIME type \var{type} by \function{guess_type()}. - -Optional \var{strict} has the same meaning as with the -\function{guess_type()} function. -\end{funcdesc} - - -\begin{funcdesc}{guess_extension}{type\optional{, strict}} -Guess the extension for a file based on its MIME type, given by -\var{type}. -The return value is a string giving a filename extension, including the -leading dot (\character{.}). The extension is not guaranteed to have been -associated with any particular data stream, but would be mapped to the -MIME type \var{type} by \function{guess_type()}. If no extension can -be guessed for \var{type}, \code{None} is returned. - -Optional \var{strict} has the same meaning as with the -\function{guess_type()} function. -\end{funcdesc} - - -Some additional functions and data items are available for controlling -the behavior of the module. - - -\begin{funcdesc}{init}{\optional{files}} -Initialize the internal data structures. If given, \var{files} must -be a sequence of file names which should be used to augment the -default type map. If omitted, the file names to use are taken from -\constant{knownfiles}. Each file named in \var{files} or -\constant{knownfiles} takes precedence over those named before it. -Calling \function{init()} repeatedly is allowed. -\end{funcdesc} - -\begin{funcdesc}{read_mime_types}{filename} -Load the type map given in the file \var{filename}, if it exists. The -type map is returned as a dictionary mapping filename extensions, -including the leading dot (\character{.}), to strings of the form -\code{'\var{type}/\var{subtype}'}. If the file \var{filename} does -not exist or cannot be read, \code{None} is returned. -\end{funcdesc} - - -\begin{funcdesc}{add_type}{type, ext\optional{, strict}} -Add a mapping from the mimetype \var{type} to the extension \var{ext}. -When the extension is already known, the new type will replace the old -one. When the type is already known the extension will be added -to the list of known extensions. - -When \var{strict} is the mapping will added to the official -MIME types, otherwise to the non-standard ones. -\end{funcdesc} - - -\begin{datadesc}{inited} -Flag indicating whether or not the global data structures have been -initialized. This is set to true by \function{init()}. -\end{datadesc} - -\begin{datadesc}{knownfiles} -List of type map file names commonly installed. These files are -typically named \file{mime.types} and are installed in different -locations by different packages.\index{file!mime.types} -\end{datadesc} - -\begin{datadesc}{suffix_map} -Dictionary mapping suffixes to suffixes. This is used to allow -recognition of encoded files for which the encoding and the type are -indicated by the same extension. For example, the \file{.tgz} -extension is mapped to \file{.tar.gz} to allow the encoding and type -to be recognized separately. -\end{datadesc} - -\begin{datadesc}{encodings_map} -Dictionary mapping filename extensions to encoding types. -\end{datadesc} - -\begin{datadesc}{types_map} -Dictionary mapping filename extensions to MIME types. -\end{datadesc} - -\begin{datadesc}{common_types} -Dictionary mapping filename extensions to non-standard, but commonly -found MIME types. -\end{datadesc} - - -The \class{MimeTypes} class may be useful for applications which may -want more than one MIME-type database: - -\begin{classdesc}{MimeTypes}{\optional{filenames}} - This class represents a MIME-types database. By default, it - provides access to the same database as the rest of this module. - The initial database is a copy of that provided by the module, and - may be extended by loading additional \file{mime.types}-style files - into the database using the \method{read()} or \method{readfp()} - methods. The mapping dictionaries may also be cleared before - loading additional data if the default data is not desired. - - The optional \var{filenames} parameter can be used to cause - additional files to be loaded ``on top'' of the default database. - - \versionadded{2.2} -\end{classdesc} - -An example usage of the module: - -\begin{verbatim} ->>> import mimetypes ->>> mimetypes.init() ->>> mimetypes.knownfiles -['/etc/mime.types', '/etc/httpd/mime.types', ... ] ->>> mimetypes.suffix_map['.tgz'] -'.tar.gz' ->>> mimetypes.encodings_map['.gz'] -'gzip' ->>> mimetypes.types_map['.tgz'] -'application/x-tar-gz' -\end{verbatim} - -\subsection{MimeTypes Objects \label{mimetypes-objects}} - -\class{MimeTypes} instances provide an interface which is very like -that of the \refmodule{mimetypes} module. - -\begin{memberdesc}[MimeTypes]{suffix_map} - Dictionary mapping suffixes to suffixes. This is used to allow - recognition of encoded files for which the encoding and the type are - indicated by the same extension. For example, the \file{.tgz} - extension is mapped to \file{.tar.gz} to allow the encoding and type - to be recognized separately. This is initially a copy of the global - \code{suffix_map} defined in the module. -\end{memberdesc} - -\begin{memberdesc}[MimeTypes]{encodings_map} - Dictionary mapping filename extensions to encoding types. This is - initially a copy of the global \code{encodings_map} defined in the - module. -\end{memberdesc} - -\begin{memberdesc}[MimeTypes]{types_map} - Dictionary mapping filename extensions to MIME types. This is - initially a copy of the global \code{types_map} defined in the - module. -\end{memberdesc} - -\begin{memberdesc}[MimeTypes]{common_types} - Dictionary mapping filename extensions to non-standard, but commonly - found MIME types. This is initially a copy of the global - \code{common_types} defined in the module. -\end{memberdesc} - -\begin{methoddesc}[MimeTypes]{guess_extension}{type\optional{, strict}} - Similar to the \function{guess_extension()} function, using the - tables stored as part of the object. -\end{methoddesc} - -\begin{methoddesc}[MimeTypes]{guess_type}{url\optional{, strict}} - Similar to the \function{guess_type()} function, using the tables - stored as part of the object. -\end{methoddesc} - -\begin{methoddesc}[MimeTypes]{read}{path} - Load MIME information from a file named \var{path}. This uses - \method{readfp()} to parse the file. -\end{methoddesc} - -\begin{methoddesc}[MimeTypes]{readfp}{file} - Load MIME type information from an open file. The file must have - the format of the standard \file{mime.types} files. -\end{methoddesc} diff --git a/Doc/lib/libmisc.tex b/Doc/lib/libmisc.tex deleted file mode 100644 index 6f79eda..0000000 --- a/Doc/lib/libmisc.tex +++ /dev/null @@ -1,7 +0,0 @@ -\chapter{Miscellaneous Services} -\label{misc} - -The modules described in this chapter provide miscellaneous services -that are available in all Python versions. Here's an overview: - -\localmoduletable diff --git a/Doc/lib/libmm.tex b/Doc/lib/libmm.tex deleted file mode 100644 index 22c14b4..0000000 --- a/Doc/lib/libmm.tex +++ /dev/null @@ -1,8 +0,0 @@ -\chapter{Multimedia Services} -\label{mmedia} - -The modules described in this chapter implement various algorithms or -interfaces that are mainly useful for multimedia applications. They -are available at the discretion of the installation. Here's an overview: - -\localmoduletable diff --git a/Doc/lib/libmmap.tex b/Doc/lib/libmmap.tex deleted file mode 100644 index 345aeea..0000000 --- a/Doc/lib/libmmap.tex +++ /dev/null @@ -1,171 +0,0 @@ -\section{\module{mmap} --- -Memory-mapped file support} - -\declaremodule{builtin}{mmap} -\modulesynopsis{Interface to memory-mapped files for \UNIX\ and Windows.} - -Memory-mapped file objects behave like both strings and like -file objects. Unlike normal string objects, however, these are -mutable. You can use mmap objects in most places where strings -are expected; for example, you can use the \module{re} module to -search through a memory-mapped file. Since they're mutable, you can -change a single character by doing \code{obj[\var{index}] = 'a'}, or -change a substring by assigning to a slice: -\code{obj[\var{i1}:\var{i2}] = '...'}. You can also read and write -data starting at the current file position, and \method{seek()} -through the file to different positions. - -A memory-mapped file is created by the \function{mmap()} function, -which is different on \UNIX{} and on Windows. In either case you must -provide a file descriptor for a file opened for update. -If you wish to map an existing Python file object, use its -\method{fileno()} method to obtain the correct value for the -\var{fileno} parameter. Otherwise, you can open the file using the -\function{os.open()} function, which returns a file descriptor -directly (the file still needs to be closed when done). - -For both the \UNIX{} and Windows versions of the function, -\var{access} may be specified as an optional keyword parameter. -\var{access} accepts one of three values: \constant{ACCESS_READ}, -\constant{ACCESS_WRITE}, or \constant{ACCESS_COPY} to specify -readonly, write-through or copy-on-write memory respectively. -\var{access} can be used on both \UNIX{} and Windows. If -\var{access} is not specified, Windows mmap returns a write-through -mapping. The initial memory values for all three access types are -taken from the specified file. Assignment to an -\constant{ACCESS_READ} memory map raises a \exception{TypeError} -exception. Assignment to an \constant{ACCESS_WRITE} memory map -affects both memory and the underlying file. Assignment to an -\constant{ACCESS_COPY} memory map affects memory but does not update -the underlying file. \versionchanged[To map anonymous memory, --1 should be passed as the fileno along with the length]{2.5} - -\begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}} - \strong{(Windows version)} Maps \var{length} bytes from the file - specified by the file handle \var{fileno}, and returns a mmap - object. If \var{length} is larger than the current size of the file, - the file is extended to contain \var{length} bytes. If \var{length} - is \code{0}, the maximum length of the map is the current size - of the file, except that if the file is empty Windows raises an - exception (you cannot create an empty mapping on Windows). - - \var{tagname}, if specified and not \code{None}, is a string giving - a tag name for the mapping. Windows allows you to have many - different mappings against the same file. If you specify the name - of an existing tag, that tag is opened, otherwise a new tag of this - name is created. If this parameter is omitted or \code{None}, the - mapping is created without a name. Avoiding the use of the tag - parameter will assist in keeping your code portable between \UNIX{} - and Windows. -\end{funcdesc} - -\begin{funcdescni}{mmap}{fileno, length\optional{, flags\optional{, - prot\optional{, access}}}} - \strong{(\UNIX{} version)} Maps \var{length} bytes from the file - specified by the file descriptor \var{fileno}, and returns a mmap - object. If \var{length} is \code{0}, the maximum length of the map - will be the current size of the file when \function{mmap()} is - called. - - \var{flags} specifies the nature of the mapping. - \constant{MAP_PRIVATE} creates a private copy-on-write mapping, so - changes to the contents of the mmap object will be private to this - process, and \constant{MAP_SHARED} creates a mapping that's shared - with all other processes mapping the same areas of the file. The - default value is \constant{MAP_SHARED}. - - \var{prot}, if specified, gives the desired memory protection; the - two most useful values are \constant{PROT_READ} and - \constant{PROT_WRITE}, to specify that the pages may be read or - written. \var{prot} defaults to \constant{PROT_READ | PROT_WRITE}. - - \var{access} may be specified in lieu of \var{flags} and \var{prot} - as an optional keyword parameter. It is an error to specify both - \var{flags}, \var{prot} and \var{access}. See the description of - \var{access} above for information on how to use this parameter. -\end{funcdescni} - - -Memory-mapped file objects support the following methods: - - -\begin{methoddesc}[mmap]{close}{} - Close the file. Subsequent calls to other methods of the object - will result in an exception being raised. -\end{methoddesc} - -\begin{methoddesc}[mmap]{find}{string\optional{, start}} - Returns the lowest index in the object where the substring - \var{string} is found. Returns \code{-1} on failure. \var{start} - is the index at which the search begins, and defaults to zero. -\end{methoddesc} - -\begin{methoddesc}[mmap]{flush}{\optional{offset, size}} - Flushes changes made to the in-memory copy of a file back to disk. - Without use of this call there is no guarantee that changes are - written back before the object is destroyed. If \var{offset} and - \var{size} are specified, only changes to the given range of bytes - will be flushed to disk; otherwise, the whole extent of the mapping - is flushed. -\end{methoddesc} - -\begin{methoddesc}[mmap]{move}{\var{dest}, \var{src}, \var{count}} - Copy the \var{count} bytes starting at offset \var{src} to the - destination index \var{dest}. If the mmap was created with - \constant{ACCESS_READ}, then calls to move will throw a - \exception{TypeError} exception. -\end{methoddesc} - -\begin{methoddesc}[mmap]{read}{\var{num}} - Return a string containing up to \var{num} bytes starting from the - current file position; the file position is updated to point after the - bytes that were returned. -\end{methoddesc} - -\begin{methoddesc}[mmap]{read_byte}{} - Returns a string of length 1 containing the character at the current - file position, and advances the file position by 1. -\end{methoddesc} - -\begin{methoddesc}[mmap]{readline}{} - Returns a single line, starting at the current file position and up to - the next newline. -\end{methoddesc} - -\begin{methoddesc}[mmap]{resize}{\var{newsize}} - Resizes the map and the underlying file, if any. - If the mmap was created with \constant{ACCESS_READ} or - \constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception. -\end{methoddesc} - -\begin{methoddesc}[mmap]{seek}{pos\optional{, whence}} - Set the file's current position. \var{whence} argument is optional - and defaults to \code{os.SEEK_SET} or \code{0} (absolute file - positioning); other values are \code{os.SEEK_CUR} or \code{1} (seek - relative to the current position) and \code{os.SEEK_END} or \code{2} - (seek relative to the file's end). -\end{methoddesc} - -\begin{methoddesc}[mmap]{size}{} - Return the length of the file, which can be larger than the size of - the memory-mapped area. -\end{methoddesc} - -\begin{methoddesc}[mmap]{tell}{} - Returns the current position of the file pointer. -\end{methoddesc} - -\begin{methoddesc}[mmap]{write}{\var{string}} - Write the bytes in \var{string} into memory at the current position - of the file pointer; the file position is updated to point after the - bytes that were written. If the mmap was created with - \constant{ACCESS_READ}, then writing to it will throw a - \exception{TypeError} exception. -\end{methoddesc} - -\begin{methoddesc}[mmap]{write_byte}{\var{byte}} - Write the single-character string \var{byte} into memory at the - current position of the file pointer; the file position is advanced - by \code{1}. If the mmap was created with \constant{ACCESS_READ}, - then writing to it will throw a \exception{TypeError} exception. -\end{methoddesc} diff --git a/Doc/lib/libmodulefinder.tex b/Doc/lib/libmodulefinder.tex deleted file mode 100644 index 5fb9e8e..0000000 --- a/Doc/lib/libmodulefinder.tex +++ /dev/null @@ -1,51 +0,0 @@ -\section{\module{modulefinder} --- - Find modules used by a script} -\sectionauthor{A.M. Kuchling}{amk@amk.ca} - -\declaremodule{standard}{modulefinder} -\modulesynopsis{Find modules used by a script.} - -\versionadded{2.3} - -This module provides a \class{ModuleFinder} class that can be used to -determine the set of modules imported by a script. -\code{modulefinder.py} can also be run as a script, giving the -filename of a Python script as its argument, after which a report of -the imported modules will be printed. - -\begin{funcdesc}{AddPackagePath}{pkg_name, path} -Record that the package named \var{pkg_name} can be found in the specified \var{path}. -\end{funcdesc} - -\begin{funcdesc}{ReplacePackage}{oldname, newname} -Allows specifying that the module named \var{oldname} is in fact -the package named \var{newname}. The most common usage would be -to handle how the \module{_xmlplus} package replaces the \module{xml} -package. -\end{funcdesc} - -\begin{classdesc}{ModuleFinder}{\optional{path=None, debug=0, excludes=[], replace_paths=[]}} - -This class provides \method{run_script()} and \method{report()} -methods to determine the set of modules imported by a script. -\var{path} can be a list of directories to search for modules; if not -specified, \code{sys.path} is used. -\var{debug} sets the debugging level; higher values make the class print -debugging messages about what it's doing. -\var{excludes} is a list of module names to exclude from the analysis. -\var{replace_paths} is a list of \code{(\var{oldpath}, \var{newpath})} -tuples that will be replaced in module paths. -\end{classdesc} - -\begin{methoddesc}[ModuleFinder]{report}{} -Print a report to standard output that lists the modules imported by the script -and their -paths, as well as modules that are missing or seem to be missing. -\end{methoddesc} - -\begin{methoddesc}[ModuleFinder]{run_script}{pathname} -Analyze the contents of the \var{pathname} file, which must contain -Python code. -\end{methoddesc} - - diff --git a/Doc/lib/libmsilib.tex b/Doc/lib/libmsilib.tex deleted file mode 100644 index 075103a..0000000 --- a/Doc/lib/libmsilib.tex +++ /dev/null @@ -1,485 +0,0 @@ -\section{\module{msilib} --- - Read and write Microsoft Installer files} - -\declaremodule{standard}{msilib} - \platform{Windows} -\modulesynopsis{Creation of Microsoft Installer files, and CAB files.} -\moduleauthor{Martin v. L\"owis}{martin@v.loewis.de} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} - -\index{msi} - -\versionadded{2.5} - -The \module{msilib} supports the creation of Microsoft Installer -(\code{.msi}) files. Because these files often contain an embedded -``cabinet'' file (\code{.cab}), it also exposes an API to create -CAB files. Support for reading \code{.cab} files is currently not -implemented; read support for the \code{.msi} database is possible. - -This package aims to provide complete access to all tables in an -\code{.msi} file, therefore, it is a fairly low-level API. Two -primary applications of this package are the \module{distutils} -command \code{bdist_msi}, and the creation of Python installer -package itself (although that currently uses a different version -of \code{msilib}). - -The package contents can be roughly split into four parts: -low-level CAB routines, low-level MSI routines, higher-level -MSI routines, and standard table structures. - -\begin{funcdesc}{FCICreate}{cabname, files} - Create a new CAB file named \var{cabname}. \var{files} must - be a list of tuples, each containing the name of the file on - disk, and the name of the file inside the CAB file. - - The files are added to the CAB file in the order they appear - in the list. All files are added into a single CAB file, - using the MSZIP compression algorithm. - - Callbacks to Python for the various steps of MSI creation - are currently not exposed. -\end{funcdesc} - -\begin{funcdesc}{UUIDCreate}{} - Return the string representation of a new unique identifier. - This wraps the Windows API functions \cfunction{UuidCreate} and - \cfunction{UuidToString}. -\end{funcdesc} - -\begin{funcdesc}{OpenDatabase}{path, persist} - Return a new database object by calling MsiOpenDatabase. - \var{path} is the file name of the - MSI file; \var{persist} can be one of the constants - \code{MSIDBOPEN_CREATEDIRECT}, \code{MSIDBOPEN_CREATE}, - \code{MSIDBOPEN_DIRECT}, \code{MSIDBOPEN_READONLY}, or - \code{MSIDBOPEN_TRANSACT}, and may include the flag - \code{MSIDBOPEN_PATCHFILE}. See the Microsoft documentation for - the meaning of these flags; depending on the flags, - an existing database is opened, or a new one created. -\end{funcdesc} - -\begin{funcdesc}{CreateRecord}{count} - Return a new record object by calling \cfunction{MSICreateRecord}. - \var{count} is the number of fields of the record. -\end{funcdesc} - -\begin{funcdesc}{init_database}{name, schema, ProductName, ProductCode, ProductVersion, Manufacturer} - Create and return a new database \var{name}, initialize it - with \var{schema}, and set the properties \var{ProductName}, - \var{ProductCode}, \var{ProductVersion}, and \var{Manufacturer}. - - \var{schema} must be a module object containing \code{tables} and - \code{_Validation_records} attributes; typically, - \module{msilib.schema} should be used. - - The database will contain just the schema and the validation - records when this function returns. -\end{funcdesc} - -\begin{funcdesc}{add_data}{database, records} - Add all \var{records} to \var{database}. \var{records} should - be a list of tuples, each one containing all fields of a record - according to the schema of the table. For optional fields, - \code{None} can be passed. - - Field values can be int or long numbers, strings, or instances - of the Binary class. -\end{funcdesc} - -\begin{classdesc}{Binary}{filename} - Represents entries in the Binary table; inserting such - an object using \function{add_data} reads the file named - \var{filename} into the table. -\end{classdesc} - -\begin{funcdesc}{add_tables}{database, module} - Add all table content from \var{module} to \var{database}. - \var{module} must contain an attribute \var{tables} - listing all tables for which content should be added, - and one attribute per table that has the actual content. - - This is typically used to install the sequence tables. -\end{funcdesc} - -\begin{funcdesc}{add_stream}{database, name, path} - Add the file \var{path} into the \code{_Stream} table - of \var{database}, with the stream name \var{name}. -\end{funcdesc} - -\begin{funcdesc}{gen_uuid}{} - Return a new UUID, in the format that MSI typically - requires (i.e. in curly braces, and with all hexdigits - in upper-case). -\end{funcdesc} - -\begin{seealso} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/devnotes/winprog/fcicreate.asp]{FCICreateFile}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidcreate.asp]{UuidCreate}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidtostring.asp]{UuidToString}{} -\end{seealso} - -\subsection{Database Objects\label{database-objects}} - -\begin{methoddesc}[Database]{OpenView}{sql} - Return a view object, by calling \cfunction{MSIDatabaseOpenView}. - \var{sql} is the SQL statement to execute. -\end{methoddesc} - -\begin{methoddesc}[Database]{Commit}{} - Commit the changes pending in the current transaction, - by calling \cfunction{MSIDatabaseCommit}. -\end{methoddesc} - -\begin{methoddesc}[Database]{GetSummaryInformation}{count} - Return a new summary information object, by calling - \cfunction{MsiGetSummaryInformation}. \var{count} is the maximum number of - updated values. -\end{methoddesc} - -\begin{seealso} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiopenview.asp]{MSIOpenView}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabasecommit.asp]{MSIDatabaseCommit}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msigetsummaryinformation.asp]{MSIGetSummaryInformation}{} -\end{seealso} - -\subsection{View Objects\label{view-objects}} - -\begin{methoddesc}[View]{Execute}{\optional{params=None}} - Execute the SQL query of the view, through \cfunction{MSIViewExecute}. - \var{params} is an optional record describing actual values - of the parameter tokens in the query. -\end{methoddesc} - -\begin{methoddesc}[View]{GetColumnInfo}{kind} - Return a record describing the columns of the view, through - calling \cfunction{MsiViewGetColumnInfo}. \var{kind} can be either - \code{MSICOLINFO_NAMES} or \code{MSICOLINFO_TYPES}. -\end{methoddesc} - -\begin{methoddesc}[View]{Fetch}{} - Return a result record of the query, through calling - \cfunction{MsiViewFetch}. -\end{methoddesc} - -\begin{methoddesc}[View]{Modify}{kind, data} - Modify the view, by calling \cfunction{MsiViewModify}. \var{kind} - can be one of \code{MSIMODIFY_SEEK}, \code{MSIMODIFY_REFRESH}, - \code{MSIMODIFY_INSERT}, \code{MSIMODIFY_UPDATE}, \code{MSIMODIFY_ASSIGN}, - \code{MSIMODIFY_REPLACE}, \code{MSIMODIFY_MERGE}, \code{MSIMODIFY_DELETE}, - \code{MSIMODIFY_INSERT_TEMPORARY}, \code{MSIMODIFY_VALIDATE}, - \code{MSIMODIFY_VALIDATE_NEW}, \code{MSIMODIFY_VALIDATE_FIELD}, or - \code{MSIMODIFY_VALIDATE_DELETE}. - - \var{data} must be a record describing the new data. -\end{methoddesc} - -\begin{methoddesc}[View]{Close}{} - Close the view, through \cfunction{MsiViewClose}. -\end{methoddesc} - -\begin{seealso} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewexecute.asp]{MsiViewExecute}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp]{MSIViewGetColumnInfo}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewfetch.asp]{MsiViewFetch}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewmodify.asp]{MsiViewModify}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewclose.asp]{MsiViewClose}{} -\end{seealso} - -\subsection{Summary Information Objects\label{summary-objects}} - -\begin{methoddesc}[SummaryInformation]{GetProperty}{field} - Return a property of the summary, through \cfunction{MsiSummaryInfoGetProperty}. - \var{field} is the name of the property, and can be one of the - constants - \code{PID_CODEPAGE}, \code{PID_TITLE}, \code{PID_SUBJECT}, - \code{PID_AUTHOR}, \code{PID_KEYWORDS}, \code{PID_COMMENTS}, - \code{PID_TEMPLATE}, \code{PID_LASTAUTHOR}, \code{PID_REVNUMBER}, - \code{PID_LASTPRINTED}, \code{PID_CREATE_DTM}, \code{PID_LASTSAVE_DTM}, - \code{PID_PAGECOUNT}, \code{PID_WORDCOUNT}, \code{PID_CHARCOUNT}, - \code{PID_APPNAME}, or \code{PID_SECURITY}. -\end{methoddesc} - -\begin{methoddesc}[SummaryInformation]{GetPropertyCount}{} - Return the number of summary properties, through - \cfunction{MsiSummaryInfoGetPropertyCount}. -\end{methoddesc} - -\begin{methoddesc}[SummaryInformation]{SetProperty}{field, value} - Set a property through \cfunction{MsiSummaryInfoSetProperty}. \var{field} - can have the same values as in \method{GetProperty}, \var{value} - is the new value of the property. Possible value types are integer - and string. -\end{methoddesc} - -\begin{methoddesc}[SummaryInformation]{Persist}{} - Write the modified properties to the summary information stream, - using \cfunction{MsiSummaryInfoPersist}. -\end{methoddesc} - -\begin{seealso} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp]{MsiSummaryInfoGetProperty}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp]{MsiSummaryInfoGetPropertyCount}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp]{MsiSummaryInfoSetProperty}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfopersist.asp]{MsiSummaryInfoPersist}{} -\end{seealso} - -\subsection{Record Objects\label{record-objects}} - -\begin{methoddesc}[Record]{GetFieldCount}{} - Return the number of fields of the record, through \cfunction{MsiRecordGetFieldCount}. -\end{methoddesc} - -\begin{methoddesc}[Record]{SetString}{field, value} - Set \var{field} to \var{value} through \cfunction{MsiRecordSetString}. - \var{field} must be an integer; \var{value} a string. -\end{methoddesc} - -\begin{methoddesc}[Record]{SetStream}{field, value} - Set \var{field} to the contents of the file named \var{value}, - through \cfunction{MsiRecordSetStream}. - \var{field} must be an integer; \var{value} a string. -\end{methoddesc} - -\begin{methoddesc}[Record]{SetInteger}{field, value} - Set \var{field} to \var{value} through \cfunction{MsiRecordSetInteger}. - Both \var{field} and \var{value} must be an integer. -\end{methoddesc} - -\begin{methoddesc}[Record]{ClearData}{} - Set all fields of the record to 0, through \cfunction{MsiRecordClearData}. -\end{methoddesc} - -\begin{seealso} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp]{MsiRecordGetFieldCount}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstring.asp]{MsiRecordSetString}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstream.asp]{MsiRecordSetStream}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetinteger.asp]{MsiRecordSetInteger}{} - \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordclear.asp]{MsiRecordClear}{} -\end{seealso} - -\subsection{Errors\label{msi-errors}} - -All wrappers around MSI functions raise \exception{MsiError}; -the string inside the exception will contain more detail. - -\subsection{CAB Objects\label{cab}} - -\begin{classdesc}{CAB}{name} - The class \class{CAB} represents a CAB file. During MSI construction, - files will be added simultaneously to the \code{Files} table, and - to a CAB file. Then, when all files have been added, the CAB file - can be written, then added to the MSI file. - - \var{name} is the name of the CAB file in the MSI file. -\end{classdesc} - -\begin{methoddesc}[CAB]{append}{full, file, logical} - Add the file with the pathname \var{full} to the CAB file, - under the name \var{logical}. If there is already a file - named \var{logical}, a new file name is created. - - Return the index of the file in the CAB file, and the - new name of the file inside the CAB file. -\end{methoddesc} - -\begin{methoddesc}[CAB]{commit}{database} - Generate a CAB file, add it as a stream to the MSI file, - put it into the \code{Media} table, and remove the generated - file from the disk. -\end{methoddesc} - -\subsection{Directory Objects\label{msi-directory}} - -\begin{classdesc}{Directory}{database, cab, basedir, physical, - logical, default, component, \optional{componentflags}} - Create a new directory in the Directory table. There is a current - component at each point in time for the directory, which is either - explicitly created through \method{start_component}, or implicitly when files - are added for the first time. Files are added into the current - component, and into the cab file. To create a directory, a base - directory object needs to be specified (can be \code{None}), the path to - the physical directory, and a logical directory name. \var{default} - specifies the DefaultDir slot in the directory table. \var{componentflags} - specifies the default flags that new components get. -\end{classdesc} - -\begin{methoddesc}[Directory]{start_component}{\optional{component\optional{, - feature\optional{, flags\optional{, keyfile\optional{, uuid}}}}}} - Add an entry to the Component table, and make this component the - current component for this directory. If no component name is given, the - directory name is used. If no \var{feature} is given, the current feature - is used. If no \var{flags} are given, the directory's default flags are - used. If no \var{keyfile} is given, the KeyPath is left null in the - Component table. -\end{methoddesc} - -\begin{methoddesc}[Directory]{add_file}{file\optional{, src\optional{, - version\optional{, language}}}} - Add a file to the current component of the directory, starting a new - one if there is no current component. By default, the file name - in the source and the file table will be identical. If the \var{src} file - is specified, it is interpreted relative to the current - directory. Optionally, a \var{version} and a \var{language} can be specified for - the entry in the File table. -\end{methoddesc} - -\begin{methoddesc}[Directory]{glob}{pattern\optional{, exclude}} - Add a list of files to the current component as specified in the glob - pattern. Individual files can be excluded in the \var{exclude} list. -\end{methoddesc} - -\begin{methoddesc}[Directory]{remove_pyc}{} - Remove \code{.pyc}/\code{.pyo} files on uninstall. -\end{methoddesc} - -\begin{seealso} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp]{Directory Table}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp]{File Table}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp]{Component Table}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp]{FeatureComponents Table}{} -\end{seealso} - - -\subsection{Features\label{features}} - -\begin{classdesc}{Feature}{database, id, title, desc, display\optional{, - level=1\optional{, parent\optional{, directory\optional{, - attributes=0}}}}} - - Add a new record to the \code{Feature} table, using the values - \var{id}, \var{parent.id}, \var{title}, \var{desc}, \var{display}, - \var{level}, \var{directory}, and \var{attributes}. The resulting - feature object can be passed to the \method{start_component} method - of \class{Directory}. -\end{classdesc} - -\begin{methoddesc}[Feature]{set_current}{} - Make this feature the current feature of \module{msilib}. - New components are automatically added to the default feature, - unless a feature is explicitly specified. -\end{methoddesc} - -\begin{seealso} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp]{Feature Table}{} -\end{seealso} - -\subsection{GUI classes\label{msi-gui}} - -\module{msilib} provides several classes that wrap the GUI tables in -an MSI database. However, no standard user interface is provided; use -\module{bdist_msi} to create MSI files with a user-interface for -installing Python packages. - -\begin{classdesc}{Control}{dlg, name} - Base class of the dialog controls. \var{dlg} is the dialog object - the control belongs to, and \var{name} is the control's name. -\end{classdesc} - -\begin{methoddesc}[Control]{event}{event, argument\optional{, - condition = ``1''\optional{, ordering}}} - - Make an entry into the \code{ControlEvent} table for this control. -\end{methoddesc} - -\begin{methoddesc}[Control]{mapping}{event, attribute} - Make an entry into the \code{EventMapping} table for this control. -\end{methoddesc} - -\begin{methoddesc}[Control]{condition}{action, condition} - Make an entry into the \code{ControlCondition} table for this control. -\end{methoddesc} - - -\begin{classdesc}{RadioButtonGroup}{dlg, name, property} - Create a radio button control named \var{name}. \var{property} - is the installer property that gets set when a radio button - is selected. -\end{classdesc} - -\begin{methoddesc}[RadioButtonGroup]{add}{name, x, y, width, height, text - \optional{, value}} - Add a radio button named \var{name} to the group, at the - coordinates \var{x}, \var{y}, \var{width}, \var{height}, and - with the label \var{text}. If \var{value} is omitted, it - defaults to \var{name}. -\end{methoddesc} - -\begin{classdesc}{Dialog}{db, name, x, y, w, h, attr, title, first, - default, cancel} - Return a new \class{Dialog} object. An entry in the \code{Dialog} table - is made, with the specified coordinates, dialog attributes, title, - name of the first, default, and cancel controls. -\end{classdesc} - -\begin{methoddesc}[Dialog]{control}{name, type, x, y, width, height, - attributes, property, text, control_next, help} - Return a new \class{Control} object. An entry in the \code{Control} table - is made with the specified parameters. - - This is a generic method; for specific types, specialized methods - are provided. -\end{methoddesc} - - -\begin{methoddesc}[Dialog]{text}{name, x, y, width, height, attributes, text} - Add and return a \code{Text} control. -\end{methoddesc} - -\begin{methoddesc}[Dialog]{bitmap}{name, x, y, width, height, text} - Add and return a \code{Bitmap} control. -\end{methoddesc} - -\begin{methoddesc}[Dialog]{line}{name, x, y, width, height} - Add and return a \code{Line} control. -\end{methoddesc} - -\begin{methoddesc}[Dialog]{pushbutton}{name, x, y, width, height, attributes, - text, next_control} - Add and return a \code{PushButton} control. -\end{methoddesc} - -\begin{methoddesc}[Dialog]{radiogroup}{name, x, y, width, height, - attributes, property, text, next_control} - Add and return a \code{RadioButtonGroup} control. -\end{methoddesc} - -\begin{methoddesc}[Dialog]{checkbox}{name, x, y, width, height, - attributes, property, text, next_control} - Add and return a \code{CheckBox} control. -\end{methoddesc} - -\begin{seealso} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp]{Dialog Table}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp]{Control Table}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp]{Control Types}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp]{ControlCondition Table}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp]{ControlEvent Table}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp]{EventMapping Table}{} - \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp]{RadioButton Table}{} -\end{seealso} - -\subsection{Precomputed tables\label{msi-tables}} - -\module{msilib} provides a few subpackages that contain -only schema and table definitions. Currently, these definitions -are based on MSI version 2.0. - -\begin{datadesc}{schema} - This is the standard MSI schema for MSI 2.0, with the - \var{tables} variable providing a list of table definitions, - and \var{_Validation_records} providing the data for - MSI validation. -\end{datadesc} - -\begin{datadesc}{sequence} - This module contains table contents for the standard sequence - tables: \var{AdminExecuteSequence}, \var{AdminUISequence}, - \var{AdvtExecuteSequence}, \var{InstallExecuteSequence}, and - \var{InstallUISequence}. -\end{datadesc} - -\begin{datadesc}{text} - This module contains definitions for the UIText and ActionText - tables, for the standard installer actions. -\end{datadesc} diff --git a/Doc/lib/libmsvcrt.tex b/Doc/lib/libmsvcrt.tex deleted file mode 100644 index 3e4ce5a..0000000 --- a/Doc/lib/libmsvcrt.tex +++ /dev/null @@ -1,109 +0,0 @@ -\section{\module{msvcrt} -- - Useful routines from the MS V\Cpp\ runtime} - -\declaremodule{builtin}{msvcrt} - \platform{Windows} -\modulesynopsis{Miscellaneous useful routines from the MS V\Cpp\ runtime.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -These functions provide access to some useful capabilities on Windows -platforms. Some higher-level modules use these functions to build the -Windows implementations of their services. For example, the -\refmodule{getpass} module uses this in the implementation of the -\function{getpass()} function. - -Further documentation on these functions can be found in the Platform -API documentation. - - -\subsection{File Operations \label{msvcrt-files}} - -\begin{funcdesc}{locking}{fd, mode, nbytes} - Lock part of a file based on file descriptor \var{fd} from the C - runtime. Raises \exception{IOError} on failure. The locked region - of the file extends from the current file position for \var{nbytes} - bytes, and may continue beyond the end of the file. \var{mode} must - be one of the \constant{LK_\var{*}} constants listed below. - Multiple regions in a file may be locked at the same time, but may - not overlap. Adjacent regions are not merged; they must be unlocked - individually. -\end{funcdesc} - -\begin{datadesc}{LK_LOCK} -\dataline{LK_RLCK} - Locks the specified bytes. If the bytes cannot be locked, the - program immediately tries again after 1 second. If, after 10 - attempts, the bytes cannot be locked, \exception{IOError} is - raised. -\end{datadesc} - -\begin{datadesc}{LK_NBLCK} -\dataline{LK_NBRLCK} - Locks the specified bytes. If the bytes cannot be locked, - \exception{IOError} is raised. -\end{datadesc} - -\begin{datadesc}{LK_UNLCK} - Unlocks the specified bytes, which must have been previously locked. -\end{datadesc} - -\begin{funcdesc}{setmode}{fd, flags} - Set the line-end translation mode for the file descriptor \var{fd}. - To set it to text mode, \var{flags} should be \constant{os.O_TEXT}; - for binary, it should be \constant{os.O_BINARY}. -\end{funcdesc} - -\begin{funcdesc}{open_osfhandle}{handle, flags} - Create a C runtime file descriptor from the file handle - \var{handle}. The \var{flags} parameter should be a bit-wise OR of - \constant{os.O_APPEND}, \constant{os.O_RDONLY}, and - \constant{os.O_TEXT}. The returned file descriptor may be used as a - parameter to \function{os.fdopen()} to create a file object. -\end{funcdesc} - -\begin{funcdesc}{get_osfhandle}{fd} - Return the file handle for the file descriptor \var{fd}. Raises - \exception{IOError} if \var{fd} is not recognized. -\end{funcdesc} - - -\subsection{Console I/O \label{msvcrt-console}} - -\begin{funcdesc}{kbhit}{} - Return true if a keypress is waiting to be read. -\end{funcdesc} - -\begin{funcdesc}{getch}{} - Read a keypress and return the resulting character. Nothing is - echoed to the console. This call will block if a keypress is not - already available, but will not wait for \kbd{Enter} to be pressed. - If the pressed key was a special function key, this will return - \code{'\e000'} or \code{'\e xe0'}; the next call will return the - keycode. The \kbd{Control-C} keypress cannot be read with this - function. -\end{funcdesc} - -\begin{funcdesc}{getche}{} - Similar to \function{getch()}, but the keypress will be echoed if it - represents a printable character. -\end{funcdesc} - -\begin{funcdesc}{putch}{char} - Print the character \var{char} to the console without buffering. -\end{funcdesc} - -\begin{funcdesc}{ungetch}{char} - Cause the character \var{char} to be ``pushed back'' into the - console buffer; it will be the next character read by - \function{getch()} or \function{getche()}. -\end{funcdesc} - - -\subsection{Other Functions \label{msvcrt-other}} - -\begin{funcdesc}{heapmin}{} - Force the \cfunction{malloc()} heap to clean itself up and return - unused blocks to the operating system. This only works on Windows - NT. On failure, this raises \exception{IOError}. -\end{funcdesc} diff --git a/Doc/lib/libmultifile.tex b/Doc/lib/libmultifile.tex deleted file mode 100644 index f3f0af7..0000000 --- a/Doc/lib/libmultifile.tex +++ /dev/null @@ -1,175 +0,0 @@ -\section{\module{multifile} --- - Support for files containing distinct parts} - -\declaremodule{standard}{multifile} -\modulesynopsis{Support for reading files which contain distinct - parts, such as some MIME data.} -\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} - -\deprecated{2.5}{The \refmodule{email} package should be used in - preference to the \module{multifile} module. - This module is present only to maintain backward - compatibility.} - -The \class{MultiFile} object enables you to treat sections of a text -file as file-like input objects, with \code{''} being returned by -\method{readline()} when a given delimiter pattern is encountered. The -defaults of this class are designed to make it useful for parsing -MIME multipart messages, but by subclassing it and overriding methods -it can be easily adapted for more general use. - -\begin{classdesc}{MultiFile}{fp\optional{, seekable}} -Create a multi-file. You must instantiate this class with an input -object argument for the \class{MultiFile} instance to get lines from, -such as a file object returned by \function{open()}. - -\class{MultiFile} only ever looks at the input object's -\method{readline()}, \method{seek()} and \method{tell()} methods, and -the latter two are only needed if you want random access to the -individual MIME parts. To use \class{MultiFile} on a non-seekable -stream object, set the optional \var{seekable} argument to false; this -will prevent using the input object's \method{seek()} and -\method{tell()} methods. -\end{classdesc} - -It will be useful to know that in \class{MultiFile}'s view of the world, text -is composed of three kinds of lines: data, section-dividers, and -end-markers. MultiFile is designed to support parsing of -messages that may have multiple nested message parts, each with its -own pattern for section-divider and end-marker lines. - -\begin{seealso} - \seemodule{email}{Comprehensive email handling package; supersedes - the \module{multifile} module.} -\end{seealso} - - -\subsection{MultiFile Objects \label{MultiFile-objects}} - -A \class{MultiFile} instance has the following methods: - -\begin{methoddesc}[MultiFile]{readline}{str} -Read a line. If the line is data (not a section-divider or end-marker -or real EOF) return it. If the line matches the most-recently-stacked -boundary, return \code{''} and set \code{self.last} to 1 or 0 according as -the match is or is not an end-marker. If the line matches any other -stacked boundary, raise an error. On encountering end-of-file on the -underlying stream object, the method raises \exception{Error} unless -all boundaries have been popped. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{readlines}{str} -Return all lines remaining in this part as a list of strings. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{read}{} -Read all lines, up to the next section. Return them as a single -(multiline) string. Note that this doesn't take a size argument! -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{seek}{pos\optional{, whence}} -Seek. Seek indices are relative to the start of the current section. -The \var{pos} and \var{whence} arguments are interpreted as for a file -seek. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{tell}{} -Return the file position relative to the start of the current section. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{next}{} -Skip lines to the next section (that is, read lines until a -section-divider or end-marker has been consumed). Return true if -there is such a section, false if an end-marker is seen. Re-enable -the most-recently-pushed boundary. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{is_data}{str} -Return true if \var{str} is data and false if it might be a section -boundary. As written, it tests for a prefix other than \code{'-}\code{-'} at -start of line (which all MIME boundaries have) but it is declared so -it can be overridden in derived classes. - -Note that this test is used intended as a fast guard for the real -boundary tests; if it always returns false it will merely slow -processing, not cause it to fail. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{push}{str} -Push a boundary string. When a decorated version of this boundary -is found as an input line, it will be interpreted as a section-divider -or end-marker (depending on the decoration, see \rfc{2045}). All subsequent -reads will return the empty string to indicate end-of-file, until a -call to \method{pop()} removes the boundary a or \method{next()} call -reenables it. - -It is possible to push more than one boundary. Encountering the -most-recently-pushed boundary will return EOF; encountering any other -boundary will raise an error. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{pop}{} -Pop a section boundary. This boundary will no longer be interpreted -as EOF. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{section_divider}{str} -Turn a boundary into a section-divider line. By default, this -method prepends \code{'-}\code{-'} (which MIME section boundaries have) but -it is declared so it can be overridden in derived classes. This -method need not append LF or CR-LF, as comparison with the result -ignores trailing whitespace. -\end{methoddesc} - -\begin{methoddesc}[MultiFile]{end_marker}{str} -Turn a boundary string into an end-marker line. By default, this -method prepends \code{'-}\code{-'} and appends \code{'-}\code{-'} (like a -MIME-multipart end-of-message marker) but it is declared so it can be -overridden in derived classes. This method need not append LF or -CR-LF, as comparison with the result ignores trailing whitespace. -\end{methoddesc} - -Finally, \class{MultiFile} instances have two public instance variables: - -\begin{memberdesc}[MultiFile]{level} -Nesting depth of the current part. -\end{memberdesc} - -\begin{memberdesc}[MultiFile]{last} -True if the last end-of-file was for an end-of-message marker. -\end{memberdesc} - - -\subsection{\class{MultiFile} Example \label{multifile-example}} -\sectionauthor{Skip Montanaro}{skip@mojam.com} - -\begin{verbatim} -import mimetools -import multifile -import StringIO - -def extract_mime_part_matching(stream, mimetype): - """Return the first element in a multipart MIME message on stream - matching mimetype.""" - - msg = mimetools.Message(stream) - msgtype = msg.gettype() - params = msg.getplist() - - data = StringIO.StringIO() - if msgtype[:10] == "multipart/": - - file = multifile.MultiFile(stream) - file.push(msg.getparam("boundary")) - while file.next(): - submsg = mimetools.Message(file) - try: - data = StringIO.StringIO() - mimetools.decode(file, data, submsg.getencoding()) - except ValueError: - continue - if submsg.gettype() == mimetype: - break - file.pop() - return data.getvalue() -\end{verbatim} diff --git a/Doc/lib/libmutex.tex b/Doc/lib/libmutex.tex deleted file mode 100644 index 8c35c96..0000000 --- a/Doc/lib/libmutex.tex +++ /dev/null @@ -1,57 +0,0 @@ -\section{\module{mutex} --- - Mutual exclusion support} - -\declaremodule{standard}{mutex} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Lock and queue for mutual exclusion.} - -The \module{mutex} module defines a class that allows mutual-exclusion -via acquiring and releasing locks. It does not require (or imply) -threading or multi-tasking, though it could be useful for -those purposes. - -The \module{mutex} module defines the following class: - -\begin{classdesc}{mutex}{} -Create a new (unlocked) mutex. - -A mutex has two pieces of state --- a ``locked'' bit and a queue. -When the mutex is not locked, the queue is empty. -Otherwise, the queue contains zero or more -\code{(\var{function}, \var{argument})} pairs -representing functions (or methods) waiting to acquire the lock. -When the mutex is unlocked while the queue is not empty, -the first queue entry is removed and its -\code{\var{function}(\var{argument})} pair called, -implying it now has the lock. - -Of course, no multi-threading is implied -- hence the funny interface -for \method{lock()}, where a function is called once the lock is -acquired. -\end{classdesc} - - -\subsection{Mutex Objects \label{mutex-objects}} - -\class{mutex} objects have following methods: - -\begin{methoddesc}[mutex]{test}{} -Check whether the mutex is locked. -\end{methoddesc} - -\begin{methoddesc}[mutex]{testandset}{} -``Atomic'' test-and-set, grab the lock if it is not set, -and return \code{True}, otherwise, return \code{False}. -\end{methoddesc} - -\begin{methoddesc}[mutex]{lock}{function, argument} -Execute \code{\var{function}(\var{argument})}, unless the mutex is locked. -In the case it is locked, place the function and argument on the queue. -See \method{unlock} for explanation of when -\code{\var{function}(\var{argument})} is executed in that case. -\end{methoddesc} - -\begin{methoddesc}[mutex]{unlock}{} -Unlock the mutex if queue is empty, otherwise execute the first element -in the queue. -\end{methoddesc} diff --git a/Doc/lib/libnetrc.tex b/Doc/lib/libnetrc.tex deleted file mode 100644 index f867b34..0000000 --- a/Doc/lib/libnetrc.tex +++ /dev/null @@ -1,68 +0,0 @@ -\section{\module{netrc} --- - netrc file processing} - -\declaremodule{standard}{netrc} -% Note the \protect needed for \file... ;-( -\modulesynopsis{Loading of \protect\file{.netrc} files.} -\moduleauthor{Eric S. Raymond}{esr@snark.thyrsus.com} -\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} - - -\versionadded{1.5.2} - -The \class{netrc} class parses and encapsulates the netrc file format -used by the \UNIX{} \program{ftp} program and other FTP clients. - -\begin{classdesc}{netrc}{\optional{file}} -A \class{netrc} instance or subclass instance encapsulates data from -a netrc file. The initialization argument, if present, specifies the -file to parse. If no argument is given, the file \file{.netrc} in the -user's home directory will be read. Parse errors will raise -\exception{NetrcParseError} with diagnostic information including the -file name, line number, and terminating token. -\end{classdesc} - -\begin{excdesc}{NetrcParseError} -Exception raised by the \class{netrc} class when syntactical errors -are encountered in source text. Instances of this exception provide -three interesting attributes: \member{msg} is a textual explanation -of the error, \member{filename} is the name of the source file, and -\member{lineno} gives the line number on which the error was found. -\end{excdesc} - - -\subsection{netrc Objects \label{netrc-objects}} - -A \class{netrc} instance has the following methods: - -\begin{methoddesc}[netrc]{authenticators}{host} -Return a 3-tuple \code{(\var{login}, \var{account}, \var{password})} -of authenticators for \var{host}. If the netrc file did not -contain an entry for the given host, return the tuple associated with -the `default' entry. If neither matching host nor default entry is -available, return \code{None}. -\end{methoddesc} - -\begin{methoddesc}[netrc]{__repr__}{} -Dump the class data as a string in the format of a netrc file. -(This discards comments and may reorder the entries.) -\end{methoddesc} - -Instances of \class{netrc} have public instance variables: - -\begin{memberdesc}[netrc]{hosts} -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} - -\begin{memberdesc}[netrc]{macros} -Dictionary mapping macro names to string lists. -\end{memberdesc} - -\note{Passwords are limited to a subset of the ASCII character set. -Versions of this module prior to 2.3 were extremely limited. Starting with -2.3, all ASCII punctuation is allowed in passwords. However, note that -whitespace and non-printable characters are not allowed in passwords. This -is a limitation of the way the .netrc file is parsed and may be removed in -the future.} diff --git a/Doc/lib/libnew.tex b/Doc/lib/libnew.tex deleted file mode 100644 index 18162dc..0000000 --- a/Doc/lib/libnew.tex +++ /dev/null @@ -1,55 +0,0 @@ -\section{\module{new} --- - Creation of runtime internal objects} - -\declaremodule{builtin}{new} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Interface to the creation of runtime implementation objects.} - - -The \module{new} module allows an interface to the interpreter object -creation functions. This is for use primarily in marshal-type functions, -when a new object needs to be created ``magically'' and not by using the -regular creation functions. This module provides a low-level interface -to the interpreter, so care must be exercised when using this module. -It is possible to supply non-sensical arguments which crash the -interpreter when the object is used. - -The \module{new} module defines the following functions: - -\begin{funcdesc}{instancemethod}{function, instance, class} -This function will return a method object, bound to \var{instance}, or -unbound if \var{instance} is \code{None}. \var{function} must be -callable. -\end{funcdesc} - -\begin{funcdesc}{function}{code, globals\optional{, name\optional{, - argdefs\optional{, closure}}}} -Returns a (Python) function with the given code and globals. If -\var{name} is given, it must be a string or \code{None}. If it is a -string, the function will have the given name, otherwise the function -name will be taken from \code{\var{code}.co_name}. If -\var{argdefs} is given, it must be a tuple and will be used to -determine the default values of parameters. If \var{closure} is given, -it must be \code{None} or a tuple of cell objects containing objects -to bind to the names in \code{\var{code}.co_freevars}. -\end{funcdesc} - -\begin{funcdesc}{code}{argcount, nlocals, stacksize, flags, codestring, - constants, names, varnames, filename, name, firstlineno, - lnotab} -This function is an interface to the \cfunction{PyCode_New()} C -function. -%XXX This is still undocumented!!!!!!!!!!! -\end{funcdesc} - -\begin{funcdesc}{module}{name[, doc]} -This function returns a new module object with name \var{name}. -\var{name} must be a string. -The optional \var{doc} argument can have any type. -\end{funcdesc} - -\begin{funcdesc}{classobj}{name, baseclasses, dict} -This function returns a new class object, with name \var{name}, derived -from \var{baseclasses} (which should be a tuple of classes) and with -namespace \var{dict}. -\end{funcdesc} diff --git a/Doc/lib/libni.tex b/Doc/lib/libni.tex deleted file mode 100644 index fa2b3ee..0000000 --- a/Doc/lib/libni.tex +++ /dev/null @@ -1,63 +0,0 @@ -\section{\module{ni} --- - None} -\declaremodule{standard}{ni} - -\modulesynopsis{None} - - -\strong{Warning: This module is obsolete.} As of Python 1.5a4, -package support (with different semantics for \code{__init__} and no -support for \code{__domain__} or \code{__}) is built in the -interpreter. The ni module is retained only for backward -compatibility. As of Python 1.5b2, it has been renamed to \code{ni1}; -if you really need it, you can use \code{import ni1}, but the -recommended approach is to rely on the built-in package support, -converting existing packages if needed. Note that mixing \code{ni} -and the built-in package support doesn't work: once you import -\code{ni}, all packages use it. - -The \code{ni} module defines a new importing scheme, which supports -packages containing several Python modules. To enable package -support, execute \code{import ni} before importing any packages. Importing -this module automatically installs the relevant import hooks. There -are no publicly-usable functions or variables in the \code{ni} module. - -To create a package named \code{spam} containing sub-modules \code{ham}, \code{bacon} and -\code{eggs}, create a directory \file{spam} somewhere on Python's module search -path, as given in \code{sys.path}. Then, create files called \file{ham.py}, \file{bacon.py} and -\file{eggs.py} inside \file{spam}. - -To import module \code{ham} from package \code{spam} and use function -\code{hamneggs()} from that module, you can use any of the following -possibilities: - -\begin{verbatim} -import spam.ham # *not* "import spam" !!! -spam.ham.hamneggs() -\end{verbatim} -% -\begin{verbatim} -from spam import ham -ham.hamneggs() -\end{verbatim} -% -\begin{verbatim} -from spam.ham import hamneggs -hamneggs() -\end{verbatim} -% -\code{import spam} creates an -empty package named \code{spam} if one does not already exist, but it does -\emph{not} automatically import \code{spam}'s submodules. -The only submodule that is guaranteed to be imported is -\code{spam.__init__}, if it exists; it would be in a file named -\file{__init__.py} in the \file{spam} directory. Note that -\code{spam.__init__} is a submodule of package spam. It can refer to -spam's namespace as \code{__} (two underscores): - -\begin{verbatim} -__.spam_inited = 1 # Set a package-level variable -\end{verbatim} -% -Additional initialization code (setting up variables, importing other -submodules) can be performed in \file{spam/__init__.py}. diff --git a/Doc/lib/libnis.tex b/Doc/lib/libnis.tex deleted file mode 100644 index fe4acb5..0000000 --- a/Doc/lib/libnis.tex +++ /dev/null @@ -1,63 +0,0 @@ -\section{\module{nis} --- - Interface to Sun's NIS (Yellow Pages)} - -\declaremodule{extension}{nis} - \platform{Unix} -\moduleauthor{Fred Gansevles}{Fred.Gansevles@cs.utwente.nl} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Interface to Sun's NIS (Yellow Pages) library.} - -The \module{nis} module gives a thin wrapper around the NIS library, useful -for central administration of several hosts. - -Because NIS exists only on \UNIX{} systems, this module is -only available for \UNIX. - -The \module{nis} module defines the following functions: - -\begin{funcdesc}{match}{key, mapname[, domain=default_domain]} -Return the match for \var{key} in map \var{mapname}, or raise an -error (\exception{nis.error}) if there is none. -Both should be strings, \var{key} is 8-bit clean. -Return value is an arbitrary array of bytes (may contain \code{NULL} -and other joys). - -Note that \var{mapname} is first checked if it is an alias to another -name. - -\versionchanged[The \var{domain} argument allows to override -the NIS domain used for the lookup. If unspecified, lookup is in the -default NIS domain]{2.5} -\end{funcdesc} - -\begin{funcdesc}{cat}{mapname[, domain=default_domain]} -Return a dictionary mapping \var{key} to \var{value} such that -\code{match(\var{key}, \var{mapname})==\var{value}}. -Note that both keys and values of the dictionary are arbitrary -arrays of bytes. - -Note that \var{mapname} is first checked if it is an alias to another -name. - -\versionchanged[The \var{domain} argument allows to override -the NIS domain used for the lookup. If unspecified, lookup is in the -default NIS domain]{2.5} -\end{funcdesc} - - \begin{funcdesc}{maps}{[domain=default_domain]} -Return a list of all valid maps. - -\versionchanged[The \var{domain} argument allows to override -the NIS domain used for the lookup. If unspecified, lookup is in the -default NIS domain]{2.5} -\end{funcdesc} - - \begin{funcdesc}{get_default_domain}{} -Return the system default NIS domain. \versionadded{2.5} -\end{funcdesc} - -The \module{nis} module defines the following exception: - -\begin{excdesc}{error} -An error raised when a NIS function returns an error code. -\end{excdesc} diff --git a/Doc/lib/libnntplib.tex b/Doc/lib/libnntplib.tex deleted file mode 100644 index 22236f4..0000000 --- a/Doc/lib/libnntplib.tex +++ /dev/null @@ -1,355 +0,0 @@ -\section{\module{nntplib} --- - NNTP protocol client} - -\declaremodule{standard}{nntplib} -\modulesynopsis{NNTP protocol client (requires sockets).} - -\indexii{NNTP}{protocol} -\index{Network News Transfer Protocol} - -This module defines the class \class{NNTP} which implements the client -side of the NNTP protocol. It can be used to implement a news reader -or poster, or automated news processors. For more information on NNTP -(Network News Transfer Protocol), see Internet \rfc{977}. - -Here are two small examples of how it can be used. To list some -statistics about a newsgroup and print the subjects of the last 10 -articles: - -\begin{verbatim} ->>> s = NNTP('news.cwi.nl') ->>> resp, count, first, last, name = s.group('comp.lang.python') ->>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last -Group comp.lang.python has 59 articles, range 3742 to 3803 ->>> resp, subs = s.xhdr('subject', first + '-' + last) ->>> for id, sub in subs[-10:]: print id, sub -... -3792 Re: Removing elements from a list while iterating... -3793 Re: Who likes Info files? -3794 Emacs and doc strings -3795 a few questions about the Mac implementation -3796 Re: executable python scripts -3797 Re: executable python scripts -3798 Re: a few questions about the Mac implementation -3799 Re: PROPOSAL: A Generic Python Object Interface for Python C Modules -3802 Re: executable python scripts -3803 Re: \POSIX{} wait and SIGCHLD ->>> s.quit() -'205 news.cwi.nl closing connection. Goodbye.' -\end{verbatim} - -To post an article from a file (this assumes that the article has -valid headers): - -\begin{verbatim} ->>> s = NNTP('news.cwi.nl') ->>> f = open('/tmp/article') ->>> s.post(f) -'240 Article posted successfully.' ->>> s.quit() -'205 news.cwi.nl closing connection. Goodbye.' -\end{verbatim} - -The module itself defines the following items: - -\begin{classdesc}{NNTP}{host\optional{, port - \optional{, user\optional{, password - \optional{, readermode} - \optional{, usenetrc}}}}} -Return a new instance of the \class{NNTP} class, representing a -connection to the NNTP server running on host \var{host}, listening at -port \var{port}. The default \var{port} is 119. If the optional -\var{user} and \var{password} are provided, -or if suitable credentials are present in \file{~/.netrc} and the -optional flag \var{usenetrc} is true (the default), -the \samp{AUTHINFO USER} and \samp{AUTHINFO PASS} commands are used to -identify and authenticate the user to the server. If the optional -flag \var{readermode} is true, then a \samp{mode reader} command is -sent before authentication is performed. Reader mode is sometimes -necessary if you are connecting to an NNTP server on the local machine -and intend to call reader-specific commands, such as \samp{group}. If -you get unexpected \exception{NNTPPermanentError}s, you might need to set -\var{readermode}. \var{readermode} defaults to \code{None}. -\var{usenetrc} defaults to \code{True}. - -\versionchanged[\var{usenetrc} argument added]{2.4} -\end{classdesc} - -\begin{excdesc}{NNTPError} -Derived from the standard exception \exception{Exception}, this is the -base class for all exceptions raised by the \module{nntplib} module. -\end{excdesc} - -\begin{excdesc}{NNTPReplyError} -Exception raised when an unexpected reply is received from the -server. For backwards compatibility, the exception \code{error_reply} -is equivalent to this class. -\end{excdesc} - -\begin{excdesc}{NNTPTemporaryError} -Exception raised when an error code in the range 400--499 is -received. For backwards compatibility, the exception -\code{error_temp} is equivalent to this class. -\end{excdesc} - -\begin{excdesc}{NNTPPermanentError} -Exception raised when an error code in the range 500--599 is -received. For backwards compatibility, the exception -\code{error_perm} is equivalent to this class. -\end{excdesc} - -\begin{excdesc}{NNTPProtocolError} -Exception raised when a reply is received from the server that does -not begin with a digit in the range 1--5. For backwards -compatibility, the exception \code{error_proto} is equivalent to this -class. -\end{excdesc} - -\begin{excdesc}{NNTPDataError} -Exception raised when there is some error in the response data. For -backwards compatibility, the exception \code{error_data} is -equivalent to this class. -\end{excdesc} - - -\subsection{NNTP Objects \label{nntp-objects}} - -NNTP instances have the following methods. The \var{response} that is -returned as the first item in the return tuple of almost all methods -is the server's response: a string beginning with a three-digit code. -If the server's response indicates an error, the method raises one of -the above exceptions. - - -\begin{methoddesc}[NNTP]{getwelcome}{} -Return the welcome message sent by the server in reply to the initial -connection. (This message sometimes contains disclaimers or help -information that may be relevant to the user.) -\end{methoddesc} - -\begin{methoddesc}[NNTP]{set_debuglevel}{level} -Set the instance's debugging level. This controls the amount of -debugging output printed. The default, \code{0}, produces no debugging -output. A value of \code{1} produces a moderate amount of debugging -output, generally a single line per request or response. A value of -\code{2} or higher produces the maximum amount of debugging output, -logging each line sent and received on the connection (including -message text). -\end{methoddesc} - -\begin{methoddesc}[NNTP]{newgroups}{date, time, \optional{file}} -Send a \samp{NEWGROUPS} command. The \var{date} argument should be a -string of the form \code{'\var{yy}\var{mm}\var{dd}'} indicating the -date, and \var{time} should be a string of the form -\code{'\var{hh}\var{mm}\var{ss}'} indicating the time. Return a pair -\code{(\var{response}, \var{groups})} where \var{groups} is a list of -group names that are new since the given date and time. -If the \var{file} parameter is supplied, then the output of the -\samp{NEWGROUPS} command is stored in a file. If \var{file} is a string, -then the method will open a file object with that name, write to it -then close it. If \var{file} is a file object, then it will start -calling \method{write()} on it to store the lines of the command output. -If \var{file} is supplied, then the returned \var{list} is an empty list. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{newnews}{group, date, time, \optional{file}} -Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or -\code{'*'}, and \var{date} and \var{time} have the same meaning as for -\method{newgroups()}. Return a pair \code{(\var{response}, -\var{articles})} where \var{articles} is a list of message ids. -If the \var{file} parameter is supplied, then the output of the -\samp{NEWNEWS} command is stored in a file. If \var{file} is a string, -then the method will open a file object with that name, write to it -then close it. If \var{file} is a file object, then it will start -calling \method{write()} on it to store the lines of the command output. -If \var{file} is supplied, then the returned \var{list} is an empty list. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{list}{\optional{file}} -Send a \samp{LIST} command. Return a pair \code{(\var{response}, -\var{list})} where \var{list} is a list of tuples. Each tuple has the -form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where -\var{group} is a group name, \var{last} and \var{first} are the last -and first article numbers (as strings), and \var{flag} is -\code{'y'} if posting is allowed, \code{'n'} if not, and \code{'m'} if -the newsgroup is moderated. (Note the ordering: \var{last}, -\var{first}.) -If the \var{file} parameter is supplied, then the output of the -\samp{LIST} command is stored in a file. If \var{file} is a string, -then the method will open a file object with that name, write to it -then close it. If \var{file} is a file object, then it will start -calling \method{write()} on it to store the lines of the command output. -If \var{file} is supplied, then the returned \var{list} is an empty list. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{descriptions}{grouppattern} -Send a \samp{LIST NEWSGROUPS} command, where \var{grouppattern} is a wildmat -string as specified in RFC2980 (it's essentially the same as DOS or UNIX -shell wildcard strings). Return a pair \code{(\var{response}, -\var{list})}, where \var{list} is a list of tuples containing -\code{(\var{name}, \var{title})}. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NNTP]{description}{group} -Get a description for a single group \var{group}. If more than one group -matches (if 'group' is a real wildmat string), return the first match. -If no group matches, return an empty string. - -This elides the response code from the server. If the response code is -needed, use \method{descriptions()}. - -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[NNTP]{group}{name} -Send a \samp{GROUP} command, where \var{name} is the group name. -Return a tuple \code{(\var{response}, \var{count}, \var{first}, -\var{last}, \var{name})} where \var{count} is the (estimated) number -of articles in the group, \var{first} is the first article number in -the group, \var{last} is the last article number in the group, and -\var{name} is the group name. The numbers are returned as strings. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{help}{\optional{file}} -Send a \samp{HELP} command. Return a pair \code{(\var{response}, -\var{list})} where \var{list} is a list of help strings. -If the \var{file} parameter is supplied, then the output of the -\samp{HELP} command is stored in a file. If \var{file} is a string, -then the method will open a file object with that name, write to it -then close it. If \var{file} is a file object, then it will start -calling \method{write()} on it to store the lines of the command output. -If \var{file} is supplied, then the returned \var{list} is an empty list. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{stat}{id} -Send a \samp{STAT} command, where \var{id} is the message id (enclosed -in \character{<} and \character{>}) or an article number (as a string). -Return a triple \code{(\var{response}, \var{number}, \var{id})} where -\var{number} is the article number (as a string) and \var{id} is the -message id (enclosed in \character{<} and \character{>}). -\end{methoddesc} - -\begin{methoddesc}[NNTP]{next}{} -Send a \samp{NEXT} command. Return as for \method{stat()}. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{last}{} -Send a \samp{LAST} command. Return as for \method{stat()}. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{head}{id} -Send a \samp{HEAD} command, where \var{id} has the same meaning as for -\method{stat()}. Return a tuple -\code{(\var{response}, \var{number}, \var{id}, \var{list})} -where the first three are the same as for \method{stat()}, -and \var{list} is a list of the article's headers (an uninterpreted -list of lines, without trailing newlines). -\end{methoddesc} - -\begin{methoddesc}[NNTP]{body}{id,\optional{file}} -Send a \samp{BODY} command, where \var{id} has the same meaning as for -\method{stat()}. If the \var{file} parameter is supplied, then -the body is stored in a file. If \var{file} is a string, then -the method will open a file object with that name, write to it then close it. -If \var{file} is a file object, then it will start calling -\method{write()} on it to store the lines of the body. -Return as for \method{head()}. If \var{file} is supplied, then -the returned \var{list} is an empty list. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{article}{id} -Send an \samp{ARTICLE} command, where \var{id} has the same meaning as -for \method{stat()}. Return as for \method{head()}. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{slave}{} -Send a \samp{SLAVE} command. Return the server's \var{response}. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{xhdr}{header, string, \optional{file}} -Send an \samp{XHDR} command. This command is not defined in the RFC -but is a common extension. The \var{header} argument is a header -keyword, e.g. \code{'subject'}. The \var{string} argument should have -the form \code{'\var{first}-\var{last}'} where \var{first} and -\var{last} are the first and last article numbers to search. Return a -pair \code{(\var{response}, \var{list})}, where \var{list} is a list of -pairs \code{(\var{id}, \var{text})}, where \var{id} is an article number -(as a string) and \var{text} is the text of the requested header for -that article. -If the \var{file} parameter is supplied, then the output of the -\samp{XHDR} command is stored in a file. If \var{file} is a string, -then the method will open a file object with that name, write to it -then close it. If \var{file} is a file object, then it will start -calling \method{write()} on it to store the lines of the command output. -If \var{file} is supplied, then the returned \var{list} is an empty list. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{post}{file} -Post an article using the \samp{POST} command. The \var{file} -argument is an open file object which is read until EOF using its -\method{readline()} method. It should be a well-formed news article, -including the required headers. The \method{post()} method -automatically escapes lines beginning with \samp{.}. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{ihave}{id, file} -Send an \samp{IHAVE} command. \var{id} is a message id (enclosed in -\character{<} and \character{>}). -If the response is not an error, treat -\var{file} exactly as for the \method{post()} method. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{date}{} -Return a triple \code{(\var{response}, \var{date}, \var{time})}, -containing the current date and time in a form suitable for the -\method{newnews()} and \method{newgroups()} methods. -This is an optional NNTP extension, and may not be supported by all -servers. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{xgtitle}{name, \optional{file}} -Process an \samp{XGTITLE} command, returning a pair \code{(\var{response}, -\var{list})}, where \var{list} is a list of tuples containing -\code{(\var{name}, \var{title})}. -% XXX huh? Should that be name, description? -If the \var{file} parameter is supplied, then the output of the -\samp{XGTITLE} command is stored in a file. If \var{file} is a string, -then the method will open a file object with that name, write to it -then close it. If \var{file} is a file object, then it will start -calling \method{write()} on it to store the lines of the command output. -If \var{file} is supplied, then the returned \var{list} is an empty list. -This is an optional NNTP extension, and may not be supported by all -servers. - -RFC2980 says ``It is suggested that this extension be deprecated''. Use -\method{descriptions()} or \method{description()} instead. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{xover}{start, end, \optional{file}} -Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list -of tuples, one for each article in the range delimited by the \var{start} -and \var{end} article numbers. Each tuple is of the form -\code{(\var{article number}, \var{subject}, \var{poster}, \var{date}, -\var{id}, \var{references}, \var{size}, \var{lines})}. -If the \var{file} parameter is supplied, then the output of the -\samp{XOVER} command is stored in a file. If \var{file} is a string, -then the method will open a file object with that name, write to it -then close it. If \var{file} is a file object, then it will start -calling \method{write()} on it to store the lines of the command output. -If \var{file} is supplied, then the returned \var{list} is an empty list. -This is an optional NNTP extension, and may not be supported by all -servers. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{xpath}{id} -Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the -directory path to the article with message ID \var{id}. This is an -optional NNTP extension, and may not be supported by all servers. -\end{methoddesc} - -\begin{methoddesc}[NNTP]{quit}{} -Send a \samp{QUIT} command and close the connection. Once this method -has been called, no other methods of the NNTP object should be called. -\end{methoddesc} diff --git a/Doc/lib/libobjs.tex b/Doc/lib/libobjs.tex deleted file mode 100644 index 3c7d798..0000000 --- a/Doc/lib/libobjs.tex +++ /dev/null @@ -1,24 +0,0 @@ -\chapter{Built-in Objects \label{builtin}} - -Names for built-in exceptions and functions and a number of constants are -found in a separate -symbol table. This table is searched last when the interpreter looks -up the meaning of a name, so local and global -user-defined names can override built-in names. Built-in types are -described together here for easy reference.\footnote{ - Most descriptions sorely lack explanations of the exceptions - that may be raised --- this will be fixed in a future version of - this manual.} -\indexii{built-in}{types} -\indexii{built-in}{exceptions} -\indexii{built-in}{functions} -\indexii{built-in}{constants} -\index{symbol table} - -The tables in this chapter document the priorities of operators by -listing them in order of ascending priority (within a table) and -grouping operators that have the same priority in the same box. -Binary operators of the same priority group from left to right. -(Unary operators group from right to left, but there you have no real -choice.) See chapter 5 of the \citetitle[../ref/ref.html]{Python -Reference Manual} for the complete picture on operator priorities. diff --git a/Doc/lib/liboperator.tex b/Doc/lib/liboperator.tex deleted file mode 100644 index 867c2ab..0000000 --- a/Doc/lib/liboperator.tex +++ /dev/null @@ -1,530 +0,0 @@ -\section{\module{operator} --- - Standard operators as functions.} -\declaremodule{builtin}{operator} -\sectionauthor{Skip Montanaro}{skip@automatrix.com} - -\modulesynopsis{All Python's standard operators as built-in functions.} - - -The \module{operator} module exports a set of functions implemented in C -corresponding to the intrinsic operators of Python. For example, -\code{operator.add(x, y)} is equivalent to the expression \code{x+y}. The -function names are those used for special class methods; variants without -leading and trailing \samp{__} are also provided for convenience. - -The functions fall into categories that perform object comparisons, -logical operations, mathematical operations, sequence operations, and -abstract type tests. - -The object comparison functions are useful for all objects, and are -named after the rich comparison operators they support: - -\begin{funcdesc}{lt}{a, b} -\funcline{le}{a, b} -\funcline{eq}{a, b} -\funcline{ne}{a, b} -\funcline{ge}{a, b} -\funcline{gt}{a, b} -\funcline{__lt__}{a, b} -\funcline{__le__}{a, b} -\funcline{__eq__}{a, b} -\funcline{__ne__}{a, b} -\funcline{__ge__}{a, b} -\funcline{__gt__}{a, b} -Perform ``rich comparisons'' between \var{a} and \var{b}. Specifically, -\code{lt(\var{a}, \var{b})} is equivalent to \code{\var{a} < \var{b}}, -\code{le(\var{a}, \var{b})} is equivalent to \code{\var{a} <= \var{b}}, -\code{eq(\var{a}, \var{b})} is equivalent to \code{\var{a} == \var{b}}, -\code{ne(\var{a}, \var{b})} is equivalent to \code{\var{a} != \var{b}}, -\code{gt(\var{a}, \var{b})} is equivalent to \code{\var{a} > \var{b}} -and -\code{ge(\var{a}, \var{b})} is equivalent to \code{\var{a} >= \var{b}}. -Note that unlike the built-in \function{cmp()}, these functions can -return any value, which may or may not be interpretable as a Boolean -value. See the \citetitle[../ref/ref.html]{Python Reference Manual} -for more information about rich comparisons. -\versionadded{2.2} -\end{funcdesc} - - -The logical operations are also generally applicable to all objects, -and support truth tests, identity tests, and boolean operations: - -\begin{funcdesc}{not_}{o} -\funcline{__not__}{o} -Return the outcome of \keyword{not} \var{o}. (Note that there is no -\method{__not__()} method for object instances; only the interpreter -core defines this operation. The result is affected by the -\method{__bool__()} and \method{__len__()} methods.) -\end{funcdesc} - -\begin{funcdesc}{truth}{o} -Return \constant{True} if \var{o} is true, and \constant{False} -otherwise. This is equivalent to using the \class{bool} -constructor. -\end{funcdesc} - -\begin{funcdesc}{is_}{a, b} -Return \code{\var{a} is \var{b}}. Tests object identity. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{is_not}{a, b} -Return \code{\var{a} is not \var{b}}. Tests object identity. -\versionadded{2.3} -\end{funcdesc} - - -The mathematical and bitwise operations are the most numerous: - -\begin{funcdesc}{abs}{o} -\funcline{__abs__}{o} -Return the absolute value of \var{o}. -\end{funcdesc} - -\begin{funcdesc}{add}{a, b} -\funcline{__add__}{a, b} -Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers. -\end{funcdesc} - -\begin{funcdesc}{and_}{a, b} -\funcline{__and__}{a, b} -Return the bitwise and of \var{a} and \var{b}. -\end{funcdesc} - -\begin{funcdesc}{div}{a, b} -\funcline{__div__}{a, b} -Return \var{a} \code{/} \var{b} when \code{__future__.division} is not -in effect. This is also known as ``classic'' division. -\end{funcdesc} - -\begin{funcdesc}{floordiv}{a, b} -\funcline{__floordiv__}{a, b} -Return \var{a} \code{//} \var{b}. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{inv}{o} -\funcline{invert}{o} -\funcline{__inv__}{o} -\funcline{__invert__}{o} -Return the bitwise inverse of the number \var{o}. This is equivalent -to \code{\textasciitilde}\var{o}. The names \function{invert()} and -\function{__invert__()} were added in Python 2.0. -\end{funcdesc} - -\begin{funcdesc}{lshift}{a, b} -\funcline{__lshift__}{a, b} -Return \var{a} shifted left by \var{b}. -\end{funcdesc} - -\begin{funcdesc}{mod}{a, b} -\funcline{__mod__}{a, b} -Return \var{a} \code{\%} \var{b}. -\end{funcdesc} - -\begin{funcdesc}{mul}{a, b} -\funcline{__mul__}{a, b} -Return \var{a} \code{*} \var{b}, for \var{a} and \var{b} numbers. -\end{funcdesc} - -\begin{funcdesc}{neg}{o} -\funcline{__neg__}{o} -Return \var{o} negated. -\end{funcdesc} - -\begin{funcdesc}{or_}{a, b} -\funcline{__or__}{a, b} -Return the bitwise or of \var{a} and \var{b}. -\end{funcdesc} - -\begin{funcdesc}{pos}{o} -\funcline{__pos__}{o} -Return \var{o} positive. -\end{funcdesc} - -\begin{funcdesc}{pow}{a, b} -\funcline{__pow__}{a, b} -Return \var{a} \code{**} \var{b}, for \var{a} and \var{b} numbers. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{rshift}{a, b} -\funcline{__rshift__}{a, b} -Return \var{a} shifted right by \var{b}. -\end{funcdesc} - -\begin{funcdesc}{sub}{a, b} -\funcline{__sub__}{a, b} -Return \var{a} \code{-} \var{b}. -\end{funcdesc} - -\begin{funcdesc}{truediv}{a, b} -\funcline{__truediv__}{a, b} -Return \var{a} \code{/} \var{b} when \code{__future__.division} is in -effect. This is also known as ``true'' division. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{xor}{a, b} -\funcline{__xor__}{a, b} -Return the bitwise exclusive or of \var{a} and \var{b}. -\end{funcdesc} - -\begin{funcdesc}{index}{a} -\funcline{__index__}{a} -Return \var{a} converted to an integer. Equivalent to \var{a}\code{.__index__()}. -\versionadded{2.5} -\end{funcdesc} - -Operations which work with sequences include: - -\begin{funcdesc}{concat}{a, b} -\funcline{__concat__}{a, b} -Return \var{a} \code{+} \var{b} for \var{a} and \var{b} sequences. -\end{funcdesc} - -\begin{funcdesc}{contains}{a, b} -\funcline{__contains__}{a, b} -Return the outcome of the test \var{b} \code{in} \var{a}. -Note the reversed operands. The name \function{__contains__()} was -added in Python 2.0. -\end{funcdesc} - -\begin{funcdesc}{countOf}{a, b} -Return the number of occurrences of \var{b} in \var{a}. -\end{funcdesc} - -\begin{funcdesc}{delitem}{a, b} -\funcline{__delitem__}{a, b} -Remove the value of \var{a} at index \var{b}. -\end{funcdesc} - -\begin{funcdesc}{delslice}{a, b, c} -\funcline{__delslice__}{a, b, c} -Delete the slice of \var{a} from index \var{b} to index \var{c}\code{-1}. -\end{funcdesc} - -\begin{funcdesc}{getitem}{a, b} -\funcline{__getitem__}{a, b} -Return the value of \var{a} at index \var{b}. -\end{funcdesc} - -\begin{funcdesc}{getslice}{a, b, c} -\funcline{__getslice__}{a, b, c} -Return the slice of \var{a} from index \var{b} to index \var{c}\code{-1}. -\end{funcdesc} - -\begin{funcdesc}{indexOf}{a, b} -Return the index of the first of occurrence of \var{b} in \var{a}. -\end{funcdesc} - -\begin{funcdesc}{repeat}{a, b} -\funcline{__repeat__}{a, b} -Return \var{a} \code{*} \var{b} where \var{a} is a sequence and -\var{b} is an integer. -\end{funcdesc} - -\begin{funcdesc}{sequenceIncludes}{\unspecified} -\deprecated{2.0}{Use \function{contains()} instead.} -Alias for \function{contains()}. -\end{funcdesc} - -\begin{funcdesc}{setitem}{a, b, c} -\funcline{__setitem__}{a, b, c} -Set the value of \var{a} at index \var{b} to \var{c}. -\end{funcdesc} - -\begin{funcdesc}{setslice}{a, b, c, v} -\funcline{__setslice__}{a, b, c, v} -Set the slice of \var{a} from index \var{b} to index \var{c}\code{-1} to the -sequence \var{v}. -\end{funcdesc} - - -Many operations have an ``in-place'' version. The following functions -provide a more primitive access to in-place operators than the usual -syntax does; for example, the statement \code{x += y} is equivalent to -\code{x = operator.iadd(x, y)}. Another way to put it is to say that -\code{z = operator.iadd(x, y)} is equivalent to the compound statement -\code{z = x; z += y}. - -\begin{funcdesc}{iadd}{a, b} -\funcline{__iadd__}{a, b} -\code{a = iadd(a, b)} is equivalent to \code{a += b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{iand}{a, b} -\funcline{__iand__}{a, b} -\code{a = iand(a, b)} is equivalent to \code{a \&= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{iconcat}{a, b} -\funcline{__iconcat__}{a, b} -\code{a = iconcat(a, b)} is equivalent to \code{a += b} for \var{a} -and \var{b} sequences. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{idiv}{a, b} -\funcline{__idiv__}{a, b} -\code{a = idiv(a, b)} is equivalent to \code{a /= b} when -\code{__future__.division} is not in effect. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{ifloordiv}{a, b} -\funcline{__ifloordiv__}{a, b} -\code{a = ifloordiv(a, b)} is equivalent to \code{a //= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{ilshift}{a, b} -\funcline{__ilshift__}{a, b} -\code{a = ilshift(a, b)} is equivalent to \code{a <}\code{<= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{imod}{a, b} -\funcline{__imod__}{a, b} -\code{a = imod(a, b)} is equivalent to \code{a \%= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{imul}{a, b} -\funcline{__imul__}{a, b} -\code{a = imul(a, b)} is equivalent to \code{a *= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{ior}{a, b} -\funcline{__ior__}{a, b} -\code{a = ior(a, b)} is equivalent to \code{a |= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{ipow}{a, b} -\funcline{__ipow__}{a, b} -\code{a = ipow(a, b)} is equivalent to \code{a **= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{irepeat}{a, b} -\funcline{__irepeat__}{a, b} -\code{a = irepeat(a, b)} is equivalent to \code{a *= b} where -\var{a} is a sequence and \var{b} is an integer. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{irshift}{a, b} -\funcline{__irshift__}{a, b} -\code{a = irshift(a, b)} is equivalent to \code{a >>= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{isub}{a, b} -\funcline{__isub__}{a, b} -\code{a = isub(a, b)} is equivalent to \code{a -= b}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{itruediv}{a, b} -\funcline{__itruediv__}{a, b} -\code{a = itruediv(a, b)} is equivalent to \code{a /= b} when -\code{__future__.division} is in effect. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{ixor}{a, b} -\funcline{__ixor__}{a, b} -\code{a = ixor(a, b)} is equivalent to \code{a \textasciicircum= b}. -\versionadded{2.5} -\end{funcdesc} - - -The \module{operator} module also defines a few predicates to test the -type of objects. \note{Be careful not to misinterpret the -results of these functions; only \function{isCallable()} has any -measure of reliability with instance objects. For example:} - -\begin{verbatim} ->>> class C: -... pass -... ->>> import operator ->>> o = C() ->>> operator.isMappingType(o) -True -\end{verbatim} - -\begin{funcdesc}{isCallable}{o} -\deprecated{2.0}{Use the \function{callable()} built-in function instead.} -Returns true if the object \var{o} can be called like a function, -otherwise it returns false. True is returned for functions, bound and -unbound methods, class objects, and instance objects which support the -\method{__call__()} method. -\end{funcdesc} - -\begin{funcdesc}{isMappingType}{o} -Returns true if the object \var{o} supports the mapping interface. -This is true for dictionaries and all instance objects defining -\method{__getitem__}. -\warning{There is no reliable way to test if an instance -supports the complete mapping protocol since the interface itself is -ill-defined. This makes this test less useful than it otherwise might -be.} -\end{funcdesc} - -\begin{funcdesc}{isNumberType}{o} -Returns true if the object \var{o} represents a number. This is true -for all numeric types implemented in C. -\warning{There is no reliable way to test if an instance -supports the complete numeric interface since the interface itself is -ill-defined. This makes this test less useful than it otherwise might -be.} -\end{funcdesc} - -\begin{funcdesc}{isSequenceType}{o} -Returns true if the object \var{o} supports the sequence protocol. -This returns true for all objects which define sequence methods in C, -and for all instance objects defining \method{__getitem__}. -\warning{There is no reliable -way to test if an instance supports the complete sequence interface -since the interface itself is ill-defined. This makes this test less -useful than it otherwise might be.} -\end{funcdesc} - - -Example: Build a dictionary that maps the ordinals from \code{0} to -\code{255} to their character equivalents. - -\begin{verbatim} ->>> import operator ->>> d = {} ->>> keys = range(256) ->>> vals = map(chr, keys) ->>> map(operator.setitem, [d]*len(keys), keys, vals) -\end{verbatim} - - -The \module{operator} module also defines tools for generalized attribute -and item lookups. These are useful for making fast field extractors -as arguments for \function{map()}, \function{sorted()}, -\method{itertools.groupby()}, or other functions that expect a -function argument. - -\begin{funcdesc}{attrgetter}{attr\optional{, args...}} -Return a callable object that fetches \var{attr} from its operand. -If more than one attribute is requested, returns a tuple of attributes. -After, \samp{f=attrgetter('name')}, the call \samp{f(b)} returns -\samp{b.name}. After, \samp{f=attrgetter('name', 'date')}, the call -\samp{f(b)} returns \samp{(b.name, b.date)}. -\versionadded{2.4} -\versionchanged[Added support for multiple attributes]{2.5} -\end{funcdesc} - -\begin{funcdesc}{itemgetter}{item\optional{, args...}} -Return a callable object that fetches \var{item} from its operand. -If more than one item is requested, returns a tuple of items. -After, \samp{f=itemgetter(2)}, the call \samp{f(b)} returns -\samp{b[2]}. -After, \samp{f=itemgetter(2,5,3)}, the call \samp{f(b)} returns -\samp{(b[2], b[5], b[3])}. -\versionadded{2.4} -\versionchanged[Added support for multiple item extraction]{2.5} -\end{funcdesc} - -Examples: - -\begin{verbatim} ->>> from operator import itemgetter ->>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)] ->>> getcount = itemgetter(1) ->>> map(getcount, inventory) -[3, 2, 5, 1] ->>> sorted(inventory, key=getcount) -[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)] -\end{verbatim} - - -\subsection{Mapping Operators to Functions \label{operator-map}} - -This table shows how abstract operations correspond to operator -symbols in the Python syntax and the functions in the -\refmodule{operator} module. - - -\begin{tableiii}{l|c|l}{textrm}{Operation}{Syntax}{Function} - \lineiii{Addition}{\code{\var{a} + \var{b}}} - {\code{add(\var{a}, \var{b})}} - \lineiii{Concatenation}{\code{\var{seq1} + \var{seq2}}} - {\code{concat(\var{seq1}, \var{seq2})}} - \lineiii{Containment Test}{\code{\var{o} in \var{seq}}} - {\code{contains(\var{seq}, \var{o})}} - \lineiii{Division}{\code{\var{a} / \var{b}}} - {\code{div(\var{a}, \var{b}) \#} without \code{__future__.division}} - \lineiii{Division}{\code{\var{a} / \var{b}}} - {\code{truediv(\var{a}, \var{b}) \#} with \code{__future__.division}} - \lineiii{Division}{\code{\var{a} // \var{b}}} - {\code{floordiv(\var{a}, \var{b})}} - \lineiii{Bitwise And}{\code{\var{a} \&\ \var{b}}} - {\code{and_(\var{a}, \var{b})}} - \lineiii{Bitwise Exclusive Or}{\code{\var{a} \^\ \var{b}}} - {\code{xor(\var{a}, \var{b})}} - \lineiii{Bitwise Inversion}{\code{\~{} \var{a}}} - {\code{invert(\var{a})}} - \lineiii{Bitwise Or}{\code{\var{a} | \var{b}}} - {\code{or_(\var{a}, \var{b})}} - \lineiii{Exponentiation}{\code{\var{a} ** \var{b}}} - {\code{pow(\var{a}, \var{b})}} - \lineiii{Identity}{\code{\var{a} is \var{b}}} - {\code{is_(\var{a}, \var{b})}} - \lineiii{Identity}{\code{\var{a} is not \var{b}}} - {\code{is_not(\var{a}, \var{b})}} - \lineiii{Indexed Assignment}{\code{\var{o}[\var{k}] = \var{v}}} - {\code{setitem(\var{o}, \var{k}, \var{v})}} - \lineiii{Indexed Deletion}{\code{del \var{o}[\var{k}]}} - {\code{delitem(\var{o}, \var{k})}} - \lineiii{Indexing}{\code{\var{o}[\var{k}]}} - {\code{getitem(\var{o}, \var{k})}} - \lineiii{Left Shift}{\code{\var{a} <\code{<} \var{b}}} - {\code{lshift(\var{a}, \var{b})}} - \lineiii{Modulo}{\code{\var{a} \%\ \var{b}}} - {\code{mod(\var{a}, \var{b})}} - \lineiii{Multiplication}{\code{\var{a} * \var{b}}} - {\code{mul(\var{a}, \var{b})}} - \lineiii{Negation (Arithmetic)}{\code{- \var{a}}} - {\code{neg(\var{a})}} - \lineiii{Negation (Logical)}{\code{not \var{a}}} - {\code{not_(\var{a})}} - \lineiii{Right Shift}{\code{\var{a} >> \var{b}}} - {\code{rshift(\var{a}, \var{b})}} - \lineiii{Sequence Repitition}{\code{\var{seq} * \var{i}}} - {\code{repeat(\var{seq}, \var{i})}} - \lineiii{Slice Assignment}{\code{\var{seq}[\var{i}:\var{j}]} = \var{values}} - {\code{setslice(\var{seq}, \var{i}, \var{j}, \var{values})}} - \lineiii{Slice Deletion}{\code{del \var{seq}[\var{i}:\var{j}]}} - {\code{delslice(\var{seq}, \var{i}, \var{j})}} - \lineiii{Slicing}{\code{\var{seq}[\var{i}:\var{j}]}} - {\code{getslice(\var{seq}, \var{i}, \var{j})}} - \lineiii{String Formatting}{\code{\var{s} \%\ \var{o}}} - {\code{mod(\var{s}, \var{o})}} - \lineiii{Subtraction}{\code{\var{a} - \var{b}}} - {\code{sub(\var{a}, \var{b})}} - \lineiii{Truth Test}{\code{\var{o}}} - {\code{truth(\var{o})}} - \lineiii{Ordering}{\code{\var{a} < \var{b}}} - {\code{lt(\var{a}, \var{b})}} - \lineiii{Ordering}{\code{\var{a} <= \var{b}}} - {\code{le(\var{a}, \var{b})}} - \lineiii{Equality}{\code{\var{a} == \var{b}}} - {\code{eq(\var{a}, \var{b})}} - \lineiii{Difference}{\code{\var{a} != \var{b}}} - {\code{ne(\var{a}, \var{b})}} - \lineiii{Ordering}{\code{\var{a} >= \var{b}}} - {\code{ge(\var{a}, \var{b})}} - \lineiii{Ordering}{\code{\var{a} > \var{b}}} - {\code{gt(\var{a}, \var{b})}} -\end{tableiii} diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex deleted file mode 100644 index eb4919b..0000000 --- a/Doc/lib/liboptparse.tex +++ /dev/null @@ -1,1888 +0,0 @@ -% THIS FILE IS AUTO-GENERATED! DO NOT EDIT! -% (Your changes will be lost the next time it is generated.) -\section{\module{optparse} --- More powerful command line option parser} -\declaremodule{standard}{optparse} -\moduleauthor{Greg Ward}{gward@python.net} -\modulesynopsis{More convenient, flexible, and powerful command-line parsing library.} -\versionadded{2.3} -\sectionauthor{Greg Ward}{gward@python.net} -% An intro blurb used only when generating LaTeX docs for the Python -% manual (based on README.txt). - -\code{optparse} is a more convenient, flexible, and powerful library for -parsing command-line options than \code{getopt}. \code{optparse} uses a more -declarative style of command-line parsing: you create an instance of -\class{OptionParser}, populate it with options, and parse the command line. -\code{optparse} allows users to specify options in the conventional GNU/POSIX -syntax, and additionally generates usage and help messages for you. - -Here's an example of using \code{optparse} in a simple script: -\begin{verbatim} -from optparse import OptionParser -[...] -parser = OptionParser() -parser.add_option("-f", "--file", dest="filename", - help="write report to FILE", metavar="FILE") -parser.add_option("-q", "--quiet", - action="store_false", dest="verbose", default=True, - help="don't print status messages to stdout") - -(options, args) = parser.parse_args() -\end{verbatim} - -With these few lines of code, users of your script can now do the -``usual thing'' on the command-line, for example: -\begin{verbatim} -<yourscript> --file=outfile -q -\end{verbatim} - -As it parses the command line, \code{optparse} sets attributes of the -\code{options} object returned by \method{parse{\_}args()} based on user-supplied -command-line values. When \method{parse{\_}args()} returns from parsing this -command line, \code{options.filename} will be \code{"outfile"} and -\code{options.verbose} will be \code{False}. \code{optparse} supports both long -and short options, allows short options to be merged together, and -allows options to be associated with their arguments in a variety of -ways. Thus, the following command lines are all equivalent to the above -example: -\begin{verbatim} -<yourscript> -f outfile --quiet -<yourscript> --quiet --file outfile -<yourscript> -q -foutfile -<yourscript> -qfoutfile -\end{verbatim} - -Additionally, users can run one of -\begin{verbatim} -<yourscript> -h -<yourscript> --help -\end{verbatim} - -and \code{optparse} will print out a brief summary of your script's -options: -\begin{verbatim} -usage: <yourscript> [options] - -options: - -h, --help show this help message and exit - -f FILE, --file=FILE write report to FILE - -q, --quiet don't print status messages to stdout -\end{verbatim} - -where the value of \emph{yourscript} is determined at runtime (normally -from \code{sys.argv{[}0]}). -% $Id: intro.txt 413 2004-09-28 00:59:13Z greg $ - - -\subsection{Background\label{optparse-background}} - -\module{optparse} was explicitly designed to encourage the creation of programs with -straightforward, conventional command-line interfaces. To that end, it -supports only the most common command-line syntax and semantics -conventionally used under \UNIX{}. If you are unfamiliar with these -conventions, read this section to acquaint yourself with them. - - -\subsubsection{Terminology\label{optparse-terminology}} -\begin{description} -\item[argument] -a string entered on the command-line, and passed by the shell to -\code{execl()} or \code{execv()}. In Python, arguments are elements of -\code{sys.argv{[}1:]} (\code{sys.argv{[}0]} is the name of the program being -executed). \UNIX{} shells also use the term ``word''. - -It is occasionally desirable to substitute an argument list other -than \code{sys.argv{[}1:]}, so you should read ``argument'' as ``an element of -\code{sys.argv{[}1:]}, or of some other list provided as a substitute for -\code{sys.argv{[}1:]}''. -\item[option ] -an argument used to supply extra information to guide or customize the -execution of a program. There are many different syntaxes for -options; the traditional \UNIX{} syntax is a hyphen (``-'') followed by a -single letter, e.g. \code{"-x"} or \code{"-F"}. Also, traditional \UNIX{} -syntax allows multiple options to be merged into a single argument, -e.g. \code{"-x -F"} is equivalent to \code{"-xF"}. The GNU project -introduced \code{"-{}-"} followed by a series of hyphen-separated words, -e.g. \code{"-{}-file"} or \code{"-{}-dry-run"}. These are the only two option -syntaxes provided by \module{optparse}. - -Some other option syntaxes that the world has seen include: -\begin{itemize} -\item {} -a hyphen followed by a few letters, e.g. \code{"-pf"} (this is -\emph{not} the same as multiple options merged into a single argument) - -\item {} -a hyphen followed by a whole word, e.g. \code{"-file"} (this is -technically equivalent to the previous syntax, but they aren't -usually seen in the same program) - -\item {} -a plus sign followed by a single letter, or a few letters, -or a word, e.g. \code{"+f"}, \code{"+rgb"} - -\item {} -a slash followed by a letter, or a few letters, or a word, e.g. -\code{"/f"}, \code{"/file"} - -\end{itemize} - -These option syntaxes are not supported by \module{optparse}, and they never will -be. This is deliberate: the first three are non-standard on any -environment, and the last only makes sense if you're exclusively -targeting VMS, MS-DOS, and/or Windows. -\item[option argument] -an argument that follows an option, is closely associated with that -option, and is consumed from the argument list when that option is. -With \module{optparse}, option arguments may either be in a separate argument -from their option: -\begin{verbatim} --f foo ---file foo -\end{verbatim} - -or included in the same argument: -\begin{verbatim} --ffoo ---file=foo -\end{verbatim} - -Typically, a given option either takes an argument or it doesn't. -Lots of people want an ``optional option arguments'' feature, meaning -that some options will take an argument if they see it, and won't if -they don't. This is somewhat controversial, because it makes parsing -ambiguous: if \code{"-a"} takes an optional argument and \code{"-b"} is -another option entirely, how do we interpret \code{"-ab"}? Because of -this ambiguity, \module{optparse} does not support this feature. -\item[positional argument] -something leftover in the argument list after options have been -parsed, i.e. after options and their arguments have been parsed and -removed from the argument list. -\item[required option] -an option that must be supplied on the command-line; note that the -phrase ``required option'' is self-contradictory in English. \module{optparse} -doesn't prevent you from implementing required options, but doesn't -give you much help at it either. See \code{examples/required{\_}1.py} and -\code{examples/required{\_}2.py} in the \module{optparse} source distribution for two -ways to implement required options with \module{optparse}. -\end{description} - -For example, consider this hypothetical command-line: -\begin{verbatim} -prog -v --report /tmp/report.txt foo bar -\end{verbatim} - -\code{"-v"} and \code{"-{}-report"} are both options. Assuming that -\longprogramopt{report} takes one argument, \code{"/tmp/report.txt"} is an option -argument. \code{"foo"} and \code{"bar"} are positional arguments. - - -\subsubsection{What are options for?\label{optparse-what-options-for}} - -Options are used to provide extra information to tune or customize the -execution of a program. In case it wasn't clear, options are usually -\emph{optional}. A program should be able to run just fine with no options -whatsoever. (Pick a random program from the \UNIX{} or GNU toolsets. Can -it run without any options at all and still make sense? The main -exceptions are \code{find}, \code{tar}, and \code{dd}{---}all of which are mutant -oddballs that have been rightly criticized for their non-standard syntax -and confusing interfaces.) - -Lots of people want their programs to have ``required options''. Think -about it. If it's required, then it's \emph{not optional}! If there is a -piece of information that your program absolutely requires in order to -run successfully, that's what positional arguments are for. - -As an example of good command-line interface design, consider the humble -\code{cp} utility, for copying files. It doesn't make much sense to try to -copy files without supplying a destination and at least one source. -Hence, \code{cp} fails if you run it with no arguments. However, it has a -flexible, useful syntax that does not require any options at all: -\begin{verbatim} -cp SOURCE DEST -cp SOURCE ... DEST-DIR -\end{verbatim} - -You can get pretty far with just that. Most \code{cp} implementations -provide a bunch of options to tweak exactly how the files are copied: -you can preserve mode and modification time, avoid following symlinks, -ask before clobbering existing files, etc. But none of this distracts -from the core mission of \code{cp}, which is to copy either one file to -another, or several files to another directory. - - -\subsubsection{What are positional arguments for?\label{optparse-what-positional-arguments-for}} - -Positional arguments are for those pieces of information that your -program absolutely, positively requires to run. - -A good user interface should have as few absolute requirements as -possible. If your program requires 17 distinct pieces of information in -order to run successfully, it doesn't much matter \emph{how} you get that -information from the user{---}most people will give up and walk away -before they successfully run the program. This applies whether the user -interface is a command-line, a configuration file, or a GUI: if you make -that many demands on your users, most of them will simply give up. - -In short, try to minimize the amount of information that users are -absolutely required to supply{---}use sensible defaults whenever -possible. Of course, you also want to make your programs reasonably -flexible. That's what options are for. Again, it doesn't matter if -they are entries in a config file, widgets in the ``Preferences'' dialog -of a GUI, or command-line options{---}the more options you implement, the -more flexible your program is, and the more complicated its -implementation becomes. Too much flexibility has drawbacks as well, of -course; too many options can overwhelm users and make your code much -harder to maintain. -% $Id: tao.txt 413 2004-09-28 00:59:13Z greg $ - - -\subsection{Tutorial\label{optparse-tutorial}} - -While \module{optparse} is quite flexible and powerful, it's also straightforward to -use in most cases. This section covers the code patterns that are -common to any \module{optparse}-based program. - -First, you need to import the OptionParser class; then, early in the -main program, create an OptionParser instance: -\begin{verbatim} -from optparse import OptionParser -[...] -parser = OptionParser() -\end{verbatim} - -Then you can start defining options. The basic syntax is: -\begin{verbatim} -parser.add_option(opt_str, ..., - attr=value, ...) -\end{verbatim} - -Each option has one or more option strings, such as \code{"-f"} or -\code{"-{}-file"}, and several option attributes that tell \module{optparse} what to -expect and what to do when it encounters that option on the command -line. - -Typically, each option will have one short option string and one long -option string, e.g.: -\begin{verbatim} -parser.add_option("-f", "--file", ...) -\end{verbatim} - -You're free to define as many short option strings and as many long -option strings as you like (including zero), as long as there is at -least one option string overall. - -The option strings passed to \method{add{\_}option()} are effectively labels for -the option defined by that call. For brevity, we will frequently refer -to \emph{encountering an option} on the command line; in reality, \module{optparse} -encounters \emph{option strings} and looks up options from them. - -Once all of your options are defined, instruct \module{optparse} to parse your -program's command line: -\begin{verbatim} -(options, args) = parser.parse_args() -\end{verbatim} - -(If you like, you can pass a custom argument list to \method{parse{\_}args()}, -but that's rarely necessary: by default it uses \code{sys.argv{[}1:]}.) - -\method{parse{\_}args()} returns two values: -\begin{itemize} -\item {} -\code{options}, an object containing values for all of your options{---}e.g. if \code{"-{}-file"} takes a single string argument, then -\code{options.file} will be the filename supplied by the user, or -\code{None} if the user did not supply that option - -\item {} -\code{args}, the list of positional arguments leftover after parsing -options - -\end{itemize} - -This tutorial section only covers the four most important option -attributes: \member{action}, \member{type}, \member{dest} (destination), and \member{help}. -Of these, \member{action} is the most fundamental. - - -\subsubsection{Understanding option actions\label{optparse-understanding-option-actions}} - -Actions tell \module{optparse} what to do when it encounters an option on the -command line. There is a fixed set of actions hard-coded into \module{optparse}; -adding new actions is an advanced topic covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}. -Most actions tell \module{optparse} to store a value in some variable{---}for -example, take a string from the command line and store it in an -attribute of \code{options}. - -If you don't specify an option action, \module{optparse} defaults to \code{store}. - - -\subsubsection{The store action\label{optparse-store-action}} - -The most common option action is \code{store}, which tells \module{optparse} to take -the next argument (or the remainder of the current argument), ensure -that it is of the correct type, and store it to your chosen destination. - -For example: -\begin{verbatim} -parser.add_option("-f", "--file", - action="store", type="string", dest="filename") -\end{verbatim} - -Now let's make up a fake command line and ask \module{optparse} to parse it: -\begin{verbatim} -args = ["-f", "foo.txt"] -(options, args) = parser.parse_args(args) -\end{verbatim} - -When \module{optparse} sees the option string \code{"-f"}, it consumes the next -argument, \code{"foo.txt"}, and stores it in \code{options.filename}. So, -after this call to \method{parse{\_}args()}, \code{options.filename} is -\code{"foo.txt"}. - -Some other option types supported by \module{optparse} are \code{int} and \code{float}. -Here's an option that expects an integer argument: -\begin{verbatim} -parser.add_option("-n", type="int", dest="num") -\end{verbatim} - -Note that this option has no long option string, which is perfectly -acceptable. Also, there's no explicit action, since the default is -\code{store}. - -Let's parse another fake command-line. This time, we'll jam the option -argument right up against the option: since \code{"-n42"} (one argument) is -equivalent to \code{"-n 42"} (two arguments), the code -\begin{verbatim} -(options, args) = parser.parse_args(["-n42"]) -print options.num -\end{verbatim} - -will print \code{"42"}. - -If you don't specify a type, \module{optparse} assumes \code{string}. Combined with the -fact that the default action is \code{store}, that means our first example -can be a lot shorter: -\begin{verbatim} -parser.add_option("-f", "--file", dest="filename") -\end{verbatim} - -If you don't supply a destination, \module{optparse} figures out a sensible default -from the option strings: if the first long option string is -\code{"-{}-foo-bar"}, then the default destination is \code{foo{\_}bar}. If there -are no long option strings, \module{optparse} looks at the first short option -string: the default destination for \code{"-f"} is \code{f}. - -\module{optparse} also includes built-in \code{long} and \code{complex} types. Adding -types is covered in section~\ref{optparse-extending-optparse}, Extending \module{optparse}. - - -\subsubsection{Handling boolean (flag) options\label{optparse-handling-boolean-options}} - -Flag options{---}set a variable to true or false when a particular option -is seen{---}are quite common. \module{optparse} supports them with two separate -actions, \code{store{\_}true} and \code{store{\_}false}. For example, you might have a -\code{verbose} flag that is turned on with \code{"-v"} and off with \code{"-q"}: -\begin{verbatim} -parser.add_option("-v", action="store_true", dest="verbose") -parser.add_option("-q", action="store_false", dest="verbose") -\end{verbatim} - -Here we have two different options with the same destination, which is -perfectly OK. (It just means you have to be a bit careful when setting -default values{---}see below.) - -When \module{optparse} encounters \code{"-v"} on the command line, it sets -\code{options.verbose} to \code{True}; when it encounters \code{"-q"}, -\code{options.verbose} is set to \code{False}. - - -\subsubsection{Other actions\label{optparse-other-actions}} - -Some other actions supported by \module{optparse} are: -\begin{description} -\item[\code{store{\_}const}] -store a constant value -\item[\code{append}] -append this option's argument to a list -\item[\code{count}] -increment a counter by one -\item[\code{callback}] -call a specified function -\end{description} - -These are covered in section~\ref{optparse-reference-guide}, Reference Guide and section~\ref{optparse-option-callbacks}, Option Callbacks. - - -\subsubsection{Default values\label{optparse-default-values}} - -All of the above examples involve setting some variable (the -``destination'') when certain command-line options are seen. What happens -if those options are never seen? Since we didn't supply any defaults, -they are all set to \code{None}. This is usually fine, but sometimes you -want more control. \module{optparse} lets you supply a default value for each -destination, which is assigned before the command line is parsed. - -First, consider the verbose/quiet example. If we want \module{optparse} to set -\code{verbose} to \code{True} unless \code{"-q"} is seen, then we can do this: -\begin{verbatim} -parser.add_option("-v", action="store_true", dest="verbose", default=True) -parser.add_option("-q", action="store_false", dest="verbose") -\end{verbatim} - -Since default values apply to the \emph{destination} rather than to any -particular option, and these two options happen to have the same -destination, this is exactly equivalent: -\begin{verbatim} -parser.add_option("-v", action="store_true", dest="verbose") -parser.add_option("-q", action="store_false", dest="verbose", default=True) -\end{verbatim} - -Consider this: -\begin{verbatim} -parser.add_option("-v", action="store_true", dest="verbose", default=False) -parser.add_option("-q", action="store_false", dest="verbose", default=True) -\end{verbatim} - -Again, the default value for \code{verbose} will be \code{True}: the last -default value supplied for any particular destination is the one that -counts. - -A clearer way to specify default values is the \method{set{\_}defaults()} -method of OptionParser, which you can call at any time before calling -\method{parse{\_}args()}: -\begin{verbatim} -parser.set_defaults(verbose=True) -parser.add_option(...) -(options, args) = parser.parse_args() -\end{verbatim} - -As before, the last value specified for a given option destination is -the one that counts. For clarity, try to use one method or the other of -setting default values, not both. - - -\subsubsection{Generating help\label{optparse-generating-help}} - -\module{optparse}'s ability to generate help and usage text automatically is useful -for creating user-friendly command-line interfaces. All you have to do -is supply a \member{help} value for each option, and optionally a short usage -message for your whole program. Here's an OptionParser populated with -user-friendly (documented) options: -\begin{verbatim} -usage = "usage: %prog [options] arg1 arg2" -parser = OptionParser(usage=usage) -parser.add_option("-v", "--verbose", - action="store_true", dest="verbose", default=True, - help="make lots of noise [default]") -parser.add_option("-q", "--quiet", - action="store_false", dest="verbose", - help="be vewwy quiet (I'm hunting wabbits)") -parser.add_option("-f", "--filename", - metavar="FILE", help="write output to FILE"), -parser.add_option("-m", "--mode", - default="intermediate", - help="interaction mode: novice, intermediate, " - "or expert [default: %default]") -\end{verbatim} - -If \module{optparse} encounters either \code{"-h"} or \code{"-{}-help"} on the command-line, -or if you just call \method{parser.print{\_}help()}, it prints the following to -standard output: -\begin{verbatim} -usage: <yourscript> [options] arg1 arg2 - -options: - -h, --help show this help message and exit - -v, --verbose make lots of noise [default] - -q, --quiet be vewwy quiet (I'm hunting wabbits) - -f FILE, --filename=FILE - write output to FILE - -m MODE, --mode=MODE interaction mode: novice, intermediate, or - expert [default: intermediate] -\end{verbatim} - -(If the help output is triggered by a help option, \module{optparse} exits after -printing the help text.) - -There's a lot going on here to help \module{optparse} generate the best possible -help message: -\begin{itemize} -\item {} -the script defines its own usage message: -\begin{verbatim} -usage = "usage: %prog [options] arg1 arg2" -\end{verbatim} - -\module{optparse} expands \code{"{\%}prog"} in the usage string to the name of the current -program, i.e. \code{os.path.basename(sys.argv{[}0])}. The expanded string -is then printed before the detailed option help. - -If you don't supply a usage string, \module{optparse} uses a bland but sensible -default: \code{"usage: {\%}prog {[}options]"}, which is fine if your script -doesn't take any positional arguments. - -\item {} -every option defines a help string, and doesn't worry about line- -wrapping{---}\module{optparse} takes care of wrapping lines and making the -help output look good. - -\item {} -options that take a value indicate this fact in their -automatically-generated help message, e.g. for the ``mode'' option: -\begin{verbatim} --m MODE, --mode=MODE -\end{verbatim} - -Here, ``MODE'' is called the meta-variable: it stands for the argument -that the user is expected to supply to \programopt{-m}/\longprogramopt{mode}. By default, -\module{optparse} converts the destination variable name to uppercase and uses -that for the meta-variable. Sometimes, that's not what you want{---}for example, the \longprogramopt{filename} option explicitly sets -\code{metavar="FILE"}, resulting in this automatically-generated option -description: -\begin{verbatim} --f FILE, --filename=FILE -\end{verbatim} - -This is important for more than just saving space, though: the -manually written help text uses the meta-variable ``FILE'' to clue the -user in that there's a connection between the semi-formal syntax ``-f -FILE'' and the informal semantic description ``write output to FILE''. -This is a simple but effective way to make your help text a lot -clearer and more useful for end users. - -\item {} -options that have a default value can include \code{{\%}default} in -the help string{---}\module{optparse} will replace it with \function{str()} of the -option's default value. If an option has no default value (or the -default value is \code{None}), \code{{\%}default} expands to \code{none}. - -\end{itemize} - - -\subsubsection{Printing a version string\label{optparse-printing-version-string}} - -Similar to the brief usage string, \module{optparse} can also print a version string -for your program. You have to supply the string as the \code{version} -argument to OptionParser: -\begin{verbatim} -parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0") -\end{verbatim} - -\code{"{\%}prog"} is expanded just like it is in \code{usage}. Apart -from that, \code{version} can contain anything you like. When you supply -it, \module{optparse} automatically adds a \code{"-{}-version"} option to your parser. -If it encounters this option on the command line, it expands your -\code{version} string (by replacing \code{"{\%}prog"}), prints it to stdout, and -exits. - -For example, if your script is called \code{/usr/bin/foo}: -\begin{verbatim} -$ /usr/bin/foo --version -foo 1.0 -\end{verbatim} - - -\subsubsection{How \module{optparse} handles errors\label{optparse-how-optparse-handles-errors}} - -There are two broad classes of errors that \module{optparse} has to worry about: -programmer errors and user errors. Programmer errors are usually -erroneous calls to \code{parser.add{\_}option()}, e.g. invalid option strings, -unknown option attributes, missing option attributes, etc. These are -dealt with in the usual way: raise an exception (either -\code{optparse.OptionError} or \code{TypeError}) and let the program crash. - -Handling user errors is much more important, since they are guaranteed -to happen no matter how stable your code is. \module{optparse} can automatically -detect some user errors, such as bad option arguments (passing \code{"-n -4x"} where \programopt{-n} takes an integer argument), missing arguments -(\code{"-n"} at the end of the command line, where \programopt{-n} takes an argument -of any type). Also, you can call \code{parser.error()} to signal an -application-defined error condition: -\begin{verbatim} -(options, args) = parser.parse_args() -[...] -if options.a and options.b: - parser.error("options -a and -b are mutually exclusive") -\end{verbatim} - -In either case, \module{optparse} handles the error the same way: it prints the -program's usage message and an error message to standard error and -exits with error status 2. - -Consider the first example above, where the user passes \code{"4x"} to an -option that takes an integer: -\begin{verbatim} -$ /usr/bin/foo -n 4x -usage: foo [options] - -foo: error: option -n: invalid integer value: '4x' -\end{verbatim} - -Or, where the user fails to pass a value at all: -\begin{verbatim} -$ /usr/bin/foo -n -usage: foo [options] - -foo: error: -n option requires an argument -\end{verbatim} - -\module{optparse}-generated error messages take care always to mention the option -involved in the error; be sure to do the same when calling -\code{parser.error()} from your application code. - -If \module{optparse}'s default error-handling behaviour does not suite your needs, -you'll need to subclass OptionParser and override \code{exit()} and/or -\method{error()}. - - -\subsubsection{Putting it all together\label{optparse-putting-it-all-together}} - -Here's what \module{optparse}-based scripts usually look like: -\begin{verbatim} -from optparse import OptionParser -[...] -def main(): - usage = "usage: %prog [options] arg" - parser = OptionParser(usage) - parser.add_option("-f", "--file", dest="filename", - help="read data from FILENAME") - parser.add_option("-v", "--verbose", - action="store_true", dest="verbose") - parser.add_option("-q", "--quiet", - action="store_false", dest="verbose") - [...] - (options, args) = parser.parse_args() - if len(args) != 1: - parser.error("incorrect number of arguments") - if options.verbose: - print "reading %s..." % options.filename - [...] - -if __name__ == "__main__": - main() -\end{verbatim} -% $Id: tutorial.txt 515 2006-06-10 15:37:45Z gward $ - - -\subsection{Reference Guide\label{optparse-reference-guide}} - - -\subsubsection{Creating the parser\label{optparse-creating-parser}} - -The first step in using \module{optparse} is to create an OptionParser instance: -\begin{verbatim} -parser = OptionParser(...) -\end{verbatim} - -The OptionParser constructor has no required arguments, but a number of -optional keyword arguments. You should always pass them as keyword -arguments, i.e. do not rely on the order in which the arguments are -declared. -\begin{quote} -\begin{description} -\item[\code{usage} (default: \code{"{\%}prog {[}options]"})] -The usage summary to print when your program is run incorrectly or -with a help option. When \module{optparse} prints the usage string, it expands -\code{{\%}prog} to \code{os.path.basename(sys.argv{[}0])} (or to \code{prog} if -you passed that keyword argument). To suppress a usage message, -pass the special value \code{optparse.SUPPRESS{\_}USAGE}. -\item[\code{option{\_}list} (default: \code{{[}]})] -A list of Option objects to populate the parser with. The options -in \code{option{\_}list} are added after any options in -\code{standard{\_}option{\_}list} (a class attribute that may be set by -OptionParser subclasses), but before any version or help options. -Deprecated; use \method{add{\_}option()} after creating the parser instead. -\item[\code{option{\_}class} (default: optparse.Option)] -Class to use when adding options to the parser in \method{add{\_}option()}. -\item[\code{version} (default: \code{None})] -A version string to print when the user supplies a version option. -If you supply a true value for \code{version}, \module{optparse} automatically adds -a version option with the single option string \code{"-{}-version"}. The -substring \code{"{\%}prog"} is expanded the same as for \code{usage}. -\item[\code{conflict{\_}handler} (default: \code{"error"})] -Specifies what to do when options with conflicting option strings -are added to the parser; see section~\ref{optparse-conflicts-between-options}, Conflicts between options. -\item[\code{description} (default: \code{None})] -A paragraph of text giving a brief overview of your program. \module{optparse} -reformats this paragraph to fit the current terminal width and -prints it when the user requests help (after \code{usage}, but before -the list of options). -\item[\code{formatter} (default: a new IndentedHelpFormatter)] -An instance of optparse.HelpFormatter that will be used for -printing help text. \module{optparse} provides two concrete classes for this -purpose: IndentedHelpFormatter and TitledHelpFormatter. -\item[\code{add{\_}help{\_}option} (default: \code{True})] -If true, \module{optparse} will add a help option (with option strings \code{"-h"} -and \code{"-{}-help"}) to the parser. -\item[\code{prog}] -The string to use when expanding \code{"{\%}prog"} in \code{usage} and -\code{version} instead of \code{os.path.basename(sys.argv{[}0])}. -\end{description} -\end{quote} - - -\subsubsection{Populating the parser\label{optparse-populating-parser}} - -There are several ways to populate the parser with options. The -preferred way is by using \code{OptionParser.add{\_}option()}, as shown in -section~\ref{optparse-tutorial}, the tutorial. \method{add{\_}option()} can be called in one of two -ways: -\begin{itemize} -\item {} -pass it an Option instance (as returned by \function{make{\_}option()}) - -\item {} -pass it any combination of positional and keyword arguments that are -acceptable to \function{make{\_}option()} (i.e., to the Option constructor), -and it will create the Option instance for you - -\end{itemize} - -The other alternative is to pass a list of pre-constructed Option -instances to the OptionParser constructor, as in: -\begin{verbatim} -option_list = [ - make_option("-f", "--filename", - action="store", type="string", dest="filename"), - make_option("-q", "--quiet", - action="store_false", dest="verbose"), - ] -parser = OptionParser(option_list=option_list) -\end{verbatim} - -(\function{make{\_}option()} is a factory function for creating Option instances; -currently it is an alias for the Option constructor. A future version -of \module{optparse} may split Option into several classes, and \function{make{\_}option()} -will pick the right class to instantiate. Do not instantiate Option -directly.) - - -\subsubsection{Defining options\label{optparse-defining-options}} - -Each Option instance represents a set of synonymous command-line option -strings, e.g. \programopt{-f} and \longprogramopt{file}. You can -specify any number of short or long option strings, but you must specify -at least one overall option string. - -The canonical way to create an Option instance is with the -\method{add{\_}option()} method of \class{OptionParser}: -\begin{verbatim} -parser.add_option(opt_str[, ...], attr=value, ...) -\end{verbatim} - -To define an option with only a short option string: -\begin{verbatim} -parser.add_option("-f", attr=value, ...) -\end{verbatim} - -And to define an option with only a long option string: -\begin{verbatim} -parser.add_option("--foo", attr=value, ...) -\end{verbatim} - -The keyword arguments define attributes of the new Option object. The -most important option attribute is \member{action}, and it largely determines -which other attributes are relevant or required. If you pass irrelevant -option attributes, or fail to pass required ones, \module{optparse} raises an -OptionError exception explaining your mistake. - -An options's \emph{action} determines what \module{optparse} does when it encounters this -option on the command-line. The standard option actions hard-coded into -\module{optparse} are: -\begin{description} -\item[\code{store}] -store this option's argument (default) -\item[\code{store{\_}const}] -store a constant value -\item[\code{store{\_}true}] -store a true value -\item[\code{store{\_}false}] -store a false value -\item[\code{append}] -append this option's argument to a list -\item[\code{append{\_}const}] -append a constant value to a list -\item[\code{count}] -increment a counter by one -\item[\code{callback}] -call a specified function -\item[\member{help}] -print a usage message including all options and the -documentation for them -\end{description} - -(If you don't supply an action, the default is \code{store}. For this -action, you may also supply \member{type} and \member{dest} option attributes; see -below.) - -As you can see, most actions involve storing or updating a value -somewhere. \module{optparse} always creates a special object for this, -conventionally called \code{options} (it happens to be an instance of -\code{optparse.Values}). Option arguments (and various other values) are -stored as attributes of this object, according to the \member{dest} -(destination) option attribute. - -For example, when you call -\begin{verbatim} -parser.parse_args() -\end{verbatim} - -one of the first things \module{optparse} does is create the \code{options} object: -\begin{verbatim} -options = Values() -\end{verbatim} - -If one of the options in this parser is defined with -\begin{verbatim} -parser.add_option("-f", "--file", action="store", type="string", dest="filename") -\end{verbatim} - -and the command-line being parsed includes any of the following: -\begin{verbatim} --ffoo --f foo ---file=foo ---file foo -\end{verbatim} - -then \module{optparse}, on seeing this option, will do the equivalent of -\begin{verbatim} -options.filename = "foo" -\end{verbatim} - -The \member{type} and \member{dest} option attributes are almost as important as -\member{action}, but \member{action} is the only one that makes sense for \emph{all} -options. - - -\subsubsection{Standard option actions\label{optparse-standard-option-actions}} - -The various option actions all have slightly different requirements and -effects. Most actions have several relevant option attributes which you -may specify to guide \module{optparse}'s behaviour; a few have required attributes, -which you must specify for any option using that action. -\begin{itemize} -\item {} -\code{store} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}] - -The option must be followed by an argument, which is -converted to a value according to \member{type} and stored in -\member{dest}. If \code{nargs} {\textgreater} 1, multiple arguments will be consumed -from the command line; all will be converted according to -\member{type} and stored to \member{dest} as a tuple. See the ``Option -types'' section below. - -If \code{choices} is supplied (a list or tuple of strings), the type -defaults to \code{choice}. - -If \member{type} is not supplied, it defaults to \code{string}. - -If \member{dest} is not supplied, \module{optparse} derives a destination from the -first long option string (e.g., \code{"-{}-foo-bar"} implies \code{foo{\_}bar}). -If there are no long option strings, \module{optparse} derives a destination from -the first short option string (e.g., \code{"-f"} implies \code{f}). - -Example: -\begin{verbatim} -parser.add_option("-f") -parser.add_option("-p", type="float", nargs=3, dest="point") -\end{verbatim} - -As it parses the command line -\begin{verbatim} --f foo.txt -p 1 -3.5 4 -fbar.txt -\end{verbatim} - -\module{optparse} will set -\begin{verbatim} -options.f = "foo.txt" -options.point = (1.0, -3.5, 4.0) -options.f = "bar.txt" -\end{verbatim} - -\item {} -\code{store{\_}const} {[}required: \code{const}; relevant: \member{dest}] - -The value \code{const} is stored in \member{dest}. - -Example: -\begin{verbatim} -parser.add_option("-q", "--quiet", - action="store_const", const=0, dest="verbose") -parser.add_option("-v", "--verbose", - action="store_const", const=1, dest="verbose") -parser.add_option("--noisy", - action="store_const", const=2, dest="verbose") -\end{verbatim} - -If \code{"-{}-noisy"} is seen, \module{optparse} will set -\begin{verbatim} -options.verbose = 2 -\end{verbatim} - -\item {} -\code{store{\_}true} {[}relevant: \member{dest}] - -A special case of \code{store{\_}const} that stores a true value -to \member{dest}. - -\item {} -\code{store{\_}false} {[}relevant: \member{dest}] - -Like \code{store{\_}true}, but stores a false value. - -Example: -\begin{verbatim} -parser.add_option("--clobber", action="store_true", dest="clobber") -parser.add_option("--no-clobber", action="store_false", dest="clobber") -\end{verbatim} - -\item {} -\code{append} {[}relevant: \member{type}, \member{dest}, \code{nargs}, \code{choices}] - -The option must be followed by an argument, which is appended to the -list in \member{dest}. If no default value for \member{dest} is supplied, an -empty list is automatically created when \module{optparse} first encounters this -option on the command-line. If \code{nargs} {\textgreater} 1, multiple arguments are -consumed, and a tuple of length \code{nargs} is appended to \member{dest}. - -The defaults for \member{type} and \member{dest} are the same as for the -\code{store} action. - -Example: -\begin{verbatim} -parser.add_option("-t", "--tracks", action="append", type="int") -\end{verbatim} - -If \code{"-t3"} is seen on the command-line, \module{optparse} does the equivalent of: -\begin{verbatim} -options.tracks = [] -options.tracks.append(int("3")) -\end{verbatim} - -If, a little later on, \code{"-{}-tracks=4"} is seen, it does: -\begin{verbatim} -options.tracks.append(int("4")) -\end{verbatim} - -\item {} -\code{append{\_}const} {[}required: \code{const}; relevant: \member{dest}] - -Like \code{store{\_}const}, but the value \code{const} is appended to \member{dest}; -as with \code{append}, \member{dest} defaults to \code{None}, and an an empty list is -automatically created the first time the option is encountered. - -\item {} -\code{count} {[}relevant: \member{dest}] - -Increment the integer stored at \member{dest}. If no default value is -supplied, \member{dest} is set to zero before being incremented the first -time. - -Example: -\begin{verbatim} -parser.add_option("-v", action="count", dest="verbosity") -\end{verbatim} - -The first time \code{"-v"} is seen on the command line, \module{optparse} does the -equivalent of: -\begin{verbatim} -options.verbosity = 0 -options.verbosity += 1 -\end{verbatim} - -Every subsequent occurrence of \code{"-v"} results in -\begin{verbatim} -options.verbosity += 1 -\end{verbatim} - -\item {} -\code{callback} {[}required: \code{callback}; -relevant: \member{type}, \code{nargs}, \code{callback{\_}args}, \code{callback{\_}kwargs}] - -Call the function specified by \code{callback}, which is called as -\begin{verbatim} -func(option, opt_str, value, parser, *args, **kwargs) -\end{verbatim} - -See section~\ref{optparse-option-callbacks}, Option Callbacks for more detail. - -\item {} -\member{help} - -Prints a complete help message for all the options in the -current option parser. The help message is constructed from -the \code{usage} string passed to OptionParser's constructor and -the \member{help} string passed to every option. - -If no \member{help} string is supplied for an option, it will still be -listed in the help message. To omit an option entirely, use -the special value \code{optparse.SUPPRESS{\_}HELP}. - -\module{optparse} automatically adds a \member{help} option to all OptionParsers, so -you do not normally need to create one. - -Example: -\begin{verbatim} -from optparse import OptionParser, SUPPRESS_HELP - -parser = OptionParser() -parser.add_option("-h", "--help", action="help"), -parser.add_option("-v", action="store_true", dest="verbose", - help="Be moderately verbose") -parser.add_option("--file", dest="filename", - help="Input file to read data from"), -parser.add_option("--secret", help=SUPPRESS_HELP) -\end{verbatim} - -If \module{optparse} sees either \code{"-h"} or \code{"-{}-help"} on the command line, it -will print something like the following help message to stdout -(assuming \code{sys.argv{[}0]} is \code{"foo.py"}): -\begin{verbatim} -usage: foo.py [options] - -options: - -h, --help Show this help message and exit - -v Be moderately verbose - --file=FILENAME Input file to read data from -\end{verbatim} - -After printing the help message, \module{optparse} terminates your process -with \code{sys.exit(0)}. - -\item {} -\code{version} - -Prints the version number supplied to the OptionParser to stdout and -exits. The version number is actually formatted and printed by the -\code{print{\_}version()} method of OptionParser. Generally only relevant -if the \code{version} argument is supplied to the OptionParser -constructor. As with \member{help} options, you will rarely create -\code{version} options, since \module{optparse} automatically adds them when needed. - -\end{itemize} - - -\subsubsection{Option attributes\label{optparse-option-attributes}} - -The following option attributes may be passed as keyword arguments -to \code{parser.add{\_}option()}. If you pass an option attribute -that is not relevant to a particular option, or fail to pass a required -option attribute, \module{optparse} raises OptionError. -\begin{itemize} -\item {} -\member{action} (default: \code{"store"}) - -Determines \module{optparse}'s behaviour when this option is seen on the command -line; the available options are documented above. - -\item {} -\member{type} (default: \code{"string"}) - -The argument type expected by this option (e.g., \code{"string"} or -\code{"int"}); the available option types are documented below. - -\item {} -\member{dest} (default: derived from option strings) - -If the option's action implies writing or modifying a value somewhere, -this tells \module{optparse} where to write it: \member{dest} names an attribute of the -\code{options} object that \module{optparse} builds as it parses the command line. - -\item {} -\code{default} (deprecated) - -The value to use for this option's destination if the option is not -seen on the command line. Deprecated; use \code{parser.set{\_}defaults()} -instead. - -\item {} -\code{nargs} (default: 1) - -How many arguments of type \member{type} should be consumed when this -option is seen. If {\textgreater} 1, \module{optparse} will store a tuple of values to -\member{dest}. - -\item {} -\code{const} - -For actions that store a constant value, the constant value to store. - -\item {} -\code{choices} - -For options of type \code{"choice"}, the list of strings the user -may choose from. - -\item {} -\code{callback} - -For options with action \code{"callback"}, the callable to call when this -option is seen. See section~\ref{optparse-option-callbacks}, Option Callbacks for detail on the arguments -passed to \code{callable}. - -\item {} -\code{callback{\_}args}, \code{callback{\_}kwargs} - -Additional positional and keyword arguments to pass to \code{callback} -after the four standard callback arguments. - -\item {} -\member{help} - -Help text to print for this option when listing all available options -after the user supplies a \member{help} option (such as \code{"-{}-help"}). -If no help text is supplied, the option will be listed without help -text. To hide this option, use the special value \code{SUPPRESS{\_}HELP}. - -\item {} -\code{metavar} (default: derived from option strings) - -Stand-in for the option argument(s) to use when printing help text. -See section~\ref{optparse-tutorial}, the tutorial for an example. - -\end{itemize} - - -\subsubsection{Standard option types\label{optparse-standard-option-types}} - -\module{optparse} has six built-in option types: \code{string}, \code{int}, \code{long}, -\code{choice}, \code{float} and \code{complex}. If you need to add new option -types, see section~\ref{optparse-extending-optparse}, Extending \module{optparse}. - -Arguments to string options are not checked or converted in any way: the -text on the command line is stored in the destination (or passed to the -callback) as-is. - -Integer arguments (type \code{int} or \code{long}) are parsed as follows: -\begin{quote} -\begin{itemize} -\item {} -if the number starts with \code{0x}, it is parsed as a hexadecimal number - -\item {} -if the number starts with \code{0}, it is parsed as an octal number - -\item {} -if the number starts with \code{0b}, is is parsed as a binary number - -\item {} -otherwise, the number is parsed as a decimal number - -\end{itemize} -\end{quote} - -The conversion is done by calling either \code{int()} or \code{long()} with -the appropriate base (2, 8, 10, or 16). If this fails, so will \module{optparse}, -although with a more useful error message. - -\code{float} and \code{complex} option arguments are converted directly with -\code{float()} and \code{complex()}, with similar error-handling. - -\code{choice} options are a subtype of \code{string} options. The \code{choices} -option attribute (a sequence of strings) defines the set of allowed -option arguments. \code{optparse.check{\_}choice()} compares -user-supplied option arguments against this master list and raises -OptionValueError if an invalid string is given. - - -\subsubsection{Parsing arguments\label{optparse-parsing-arguments}} - -The whole point of creating and populating an OptionParser is to call -its \method{parse{\_}args()} method: -\begin{verbatim} -(options, args) = parser.parse_args(args=None, values=None) -\end{verbatim} - -where the input parameters are -\begin{description} -\item[\code{args}] -the list of arguments to process (default: \code{sys.argv{[}1:]}) -\item[\code{values}] -object to store option arguments in (default: a new instance of -optparse.Values) -\end{description} - -and the return values are -\begin{description} -\item[\code{options}] -the same object that was passed in as \code{options}, or the -optparse.Values instance created by \module{optparse} -\item[\code{args}] -the leftover positional arguments after all options have been -processed -\end{description} - -The most common usage is to supply neither keyword argument. If you -supply \code{options}, it will be modified with repeated \code{setattr()} -calls (roughly one for every option argument stored to an option -destination) and returned by \method{parse{\_}args()}. - -If \method{parse{\_}args()} encounters any errors in the argument list, it calls -the OptionParser's \method{error()} method with an appropriate end-user error -message. This ultimately terminates your process with an exit status of -2 (the traditional \UNIX{} exit status for command-line errors). - - -\subsubsection{Querying and manipulating your option parser\label{optparse-querying-manipulating-option-parser}} - -Sometimes, it's useful to poke around your option parser and see what's -there. OptionParser provides a couple of methods to help you out: -\begin{description} -\item[\code{has{\_}option(opt{\_}str)}] -Return true if the OptionParser has an option with -option string \code{opt{\_}str} (e.g., \code{"-q"} or \code{"-{}-verbose"}). -\item[\code{get{\_}option(opt{\_}str)}] -Returns the Option instance with the option string \code{opt{\_}str}, or -\code{None} if no options have that option string. -\item[\code{remove{\_}option(opt{\_}str)}] -If the OptionParser has an option corresponding to \code{opt{\_}str}, -that option is removed. If that option provided any other -option strings, all of those option strings become invalid. -If \code{opt{\_}str} does not occur in any option belonging to this -OptionParser, raises ValueError. -\end{description} - - -\subsubsection{Conflicts between options\label{optparse-conflicts-between-options}} - -If you're not careful, it's easy to define options with conflicting -option strings: -\begin{verbatim} -parser.add_option("-n", "--dry-run", ...) -[...] -parser.add_option("-n", "--noisy", ...) -\end{verbatim} - -(This is particularly true if you've defined your own OptionParser -subclass with some standard options.) - -Every time you add an option, \module{optparse} checks for conflicts with existing -options. If it finds any, it invokes the current conflict-handling -mechanism. You can set the conflict-handling mechanism either in the -constructor: -\begin{verbatim} -parser = OptionParser(..., conflict_handler=handler) -\end{verbatim} - -or with a separate call: -\begin{verbatim} -parser.set_conflict_handler(handler) -\end{verbatim} - -The available conflict handlers are: -\begin{quote} -\begin{description} -\item[\code{error} (default)] -assume option conflicts are a programming error and raise -OptionConflictError -\item[\code{resolve}] -resolve option conflicts intelligently (see below) -\end{description} -\end{quote} - -As an example, let's define an OptionParser that resolves conflicts -intelligently and add conflicting options to it: -\begin{verbatim} -parser = OptionParser(conflict_handler="resolve") -parser.add_option("-n", "--dry-run", ..., help="do no harm") -parser.add_option("-n", "--noisy", ..., help="be noisy") -\end{verbatim} - -At this point, \module{optparse} detects that a previously-added option is already -using the \code{"-n"} option string. Since \code{conflict{\_}handler} is -\code{"resolve"}, it resolves the situation by removing \code{"-n"} from the -earlier option's list of option strings. Now \code{"-{}-dry-run"} is the -only way for the user to activate that option. If the user asks for -help, the help message will reflect that: -\begin{verbatim} -options: - --dry-run do no harm - [...] - -n, --noisy be noisy -\end{verbatim} - -It's possible to whittle away the option strings for a previously-added -option until there are none left, and the user has no way of invoking -that option from the command-line. In that case, \module{optparse} removes that -option completely, so it doesn't show up in help text or anywhere else. -Carrying on with our existing OptionParser: -\begin{verbatim} -parser.add_option("--dry-run", ..., help="new dry-run option") -\end{verbatim} - -At this point, the original \programopt{-n/-{}-dry-run} option is no longer -accessible, so \module{optparse} removes it, leaving this help text: -\begin{verbatim} -options: - [...] - -n, --noisy be noisy - --dry-run new dry-run option -\end{verbatim} - - -\subsubsection{Cleanup\label{optparse-cleanup}} - -OptionParser instances have several cyclic references. This should not -be a problem for Python's garbage collector, but you may wish to break -the cyclic references explicitly by calling \code{destroy()} on your -OptionParser once you are done with it. This is particularly useful in -long-running applications where large object graphs are reachable from -your OptionParser. - - -\subsubsection{Other methods\label{optparse-other-methods}} - -OptionParser supports several other public methods: -\begin{itemize} -\item {} -\code{set{\_}usage(usage)} - -Set the usage string according to the rules described above for the -\code{usage} constructor keyword argument. Passing \code{None} sets the -default usage string; use \code{SUPPRESS{\_}USAGE} to suppress a usage -message. - -\item {} -\code{enable{\_}interspersed{\_}args()}, \code{disable{\_}interspersed{\_}args()} - -Enable/disable positional arguments interspersed with options, similar -to GNU getopt (enabled by default). For example, if \code{"-a"} and -\code{"-b"} are both simple options that take no arguments, \module{optparse} -normally accepts this syntax: -\begin{verbatim} -prog -a arg1 -b arg2 -\end{verbatim} - -and treats it as equivalent to -\begin{verbatim} -prog -a -b arg1 arg2 -\end{verbatim} - -To disable this feature, call \code{disable{\_}interspersed{\_}args()}. This -restores traditional \UNIX{} syntax, where option parsing stops with the -first non-option argument. - -\item {} -\code{set{\_}defaults(dest=value, ...)} - -Set default values for several option destinations at once. Using -\method{set{\_}defaults()} is the preferred way to set default values for -options, since multiple options can share the same destination. For -example, if several ``mode'' options all set the same destination, any -one of them can set the default, and the last one wins: -\begin{verbatim} -parser.add_option("--advanced", action="store_const", - dest="mode", const="advanced", - default="novice") # overridden below -parser.add_option("--novice", action="store_const", - dest="mode", const="novice", - default="advanced") # overrides above setting -\end{verbatim} - -To avoid this confusion, use \method{set{\_}defaults()}: -\begin{verbatim} -parser.set_defaults(mode="advanced") -parser.add_option("--advanced", action="store_const", - dest="mode", const="advanced") -parser.add_option("--novice", action="store_const", - dest="mode", const="novice") -\end{verbatim} - -\end{itemize} -% $Id: reference.txt 519 2006-06-11 14:39:11Z gward $ - - -\subsection{Option Callbacks\label{optparse-option-callbacks}} - -When \module{optparse}'s built-in actions and types aren't quite enough for your -needs, you have two choices: extend \module{optparse} or define a callback option. -Extending \module{optparse} is more general, but overkill for a lot of simple -cases. Quite often a simple callback is all you need. - -There are two steps to defining a callback option: -\begin{itemize} -\item {} -define the option itself using the \code{callback} action - -\item {} -write the callback; this is a function (or method) that -takes at least four arguments, as described below - -\end{itemize} - - -\subsubsection{Defining a callback option\label{optparse-defining-callback-option}} - -As always, the easiest way to define a callback option is by using the -\code{parser.add{\_}option()} method. Apart from \member{action}, the only option -attribute you must specify is \code{callback}, the function to call: -\begin{verbatim} -parser.add_option("-c", action="callback", callback=my_callback) -\end{verbatim} - -\code{callback} is a function (or other callable object), so you must have -already defined \code{my{\_}callback()} when you create this callback option. -In this simple case, \module{optparse} doesn't even know if \programopt{-c} takes any -arguments, which usually means that the option takes no arguments{---}the -mere presence of \programopt{-c} on the command-line is all it needs to know. In -some circumstances, though, you might want your callback to consume an -arbitrary number of command-line arguments. This is where writing -callbacks gets tricky; it's covered later in this section. - -\module{optparse} always passes four particular arguments to your callback, and it -will only pass additional arguments if you specify them via -\code{callback{\_}args} and \code{callback{\_}kwargs}. Thus, the minimal callback -function signature is: -\begin{verbatim} -def my_callback(option, opt, value, parser): -\end{verbatim} - -The four arguments to a callback are described below. - -There are several other option attributes that you can supply when you -define a callback option: -\begin{description} -\item[\member{type}] -has its usual meaning: as with the \code{store} or \code{append} actions, -it instructs \module{optparse} to consume one argument and convert it to -\member{type}. Rather than storing the converted value(s) anywhere, -though, \module{optparse} passes it to your callback function. -\item[\code{nargs}] -also has its usual meaning: if it is supplied and {\textgreater} 1, \module{optparse} will -consume \code{nargs} arguments, each of which must be convertible to -\member{type}. It then passes a tuple of converted values to your -callback. -\item[\code{callback{\_}args}] -a tuple of extra positional arguments to pass to the callback -\item[\code{callback{\_}kwargs}] -a dictionary of extra keyword arguments to pass to the callback -\end{description} - - -\subsubsection{How callbacks are called\label{optparse-how-callbacks-called}} - -All callbacks are called as follows: -\begin{verbatim} -func(option, opt_str, value, parser, *args, **kwargs) -\end{verbatim} - -where -\begin{description} -\item[\code{option}] -is the Option instance that's calling the callback -\item[\code{opt{\_}str}] -is the option string seen on the command-line that's triggering the -callback. (If an abbreviated long option was used, \code{opt{\_}str} will -be the full, canonical option string{---}e.g. if the user puts -\code{"-{}-foo"} on the command-line as an abbreviation for -\code{"-{}-foobar"}, then \code{opt{\_}str} will be \code{"-{}-foobar"}.) -\item[\code{value}] -is the argument to this option seen on the command-line. \module{optparse} will -only expect an argument if \member{type} is set; the type of \code{value} -will be the type implied by the option's type. If \member{type} for this -option is \code{None} (no argument expected), then \code{value} will be -\code{None}. If \code{nargs} {\textgreater} 1, \code{value} will be a tuple of values of -the appropriate type. -\item[\code{parser}] -is the OptionParser instance driving the whole thing, mainly -useful because you can access some other interesting data through -its instance attributes: -\begin{description} -\item[\code{parser.largs}] -the current list of leftover arguments, ie. arguments that have -been consumed but are neither options nor option arguments. -Feel free to modify \code{parser.largs}, e.g. by adding more -arguments to it. (This list will become \code{args}, the second -return value of \method{parse{\_}args()}.) -\item[\code{parser.rargs}] -the current list of remaining arguments, ie. with \code{opt{\_}str} and -\code{value} (if applicable) removed, and only the arguments -following them still there. Feel free to modify -\code{parser.rargs}, e.g. by consuming more arguments. -\item[\code{parser.values}] -the object where option values are by default stored (an -instance of optparse.OptionValues). This lets callbacks use the -same mechanism as the rest of \module{optparse} for storing option values; -you don't need to mess around with globals or closures. You can -also access or modify the value(s) of any options already -encountered on the command-line. -\end{description} -\item[\code{args}] -is a tuple of arbitrary positional arguments supplied via the -\code{callback{\_}args} option attribute. -\item[\code{kwargs}] -is a dictionary of arbitrary keyword arguments supplied via -\code{callback{\_}kwargs}. -\end{description} - - -\subsubsection{Raising errors in a callback\label{optparse-raising-errors-in-callback}} - -The callback function should raise OptionValueError if there are any -problems with the option or its argument(s). \module{optparse} catches this and -terminates the program, printing the error message you supply to -stderr. Your message should be clear, concise, accurate, and mention -the option at fault. Otherwise, the user will have a hard time -figuring out what he did wrong. - - -\subsubsection{Callback example 1: trivial callback\label{optparse-callback-example-1}} - -Here's an example of a callback option that takes no arguments, and -simply records that the option was seen: -\begin{verbatim} -def record_foo_seen(option, opt_str, value, parser): - parser.saw_foo = True - -parser.add_option("--foo", action="callback", callback=record_foo_seen) -\end{verbatim} - -Of course, you could do that with the \code{store{\_}true} action. - - -\subsubsection{Callback example 2: check option order\label{optparse-callback-example-2}} - -Here's a slightly more interesting example: record the fact that -\code{"-a"} is seen, but blow up if it comes after \code{"-b"} in the -command-line. -\begin{verbatim} -def check_order(option, opt_str, value, parser): - if parser.values.b: - raise OptionValueError("can't use -a after -b") - parser.values.a = 1 -[...] -parser.add_option("-a", action="callback", callback=check_order) -parser.add_option("-b", action="store_true", dest="b") -\end{verbatim} - - -\subsubsection{Callback example 3: check option order (generalized)\label{optparse-callback-example-3}} - -If you want to re-use this callback for several similar options (set a -flag, but blow up if \code{"-b"} has already been seen), it needs a bit of -work: the error message and the flag that it sets must be -generalized. -\begin{verbatim} -def check_order(option, opt_str, value, parser): - if parser.values.b: - raise OptionValueError("can't use %s after -b" % opt_str) - setattr(parser.values, option.dest, 1) -[...] -parser.add_option("-a", action="callback", callback=check_order, dest='a') -parser.add_option("-b", action="store_true", dest="b") -parser.add_option("-c", action="callback", callback=check_order, dest='c') -\end{verbatim} - - -\subsubsection{Callback example 4: check arbitrary condition\label{optparse-callback-example-4}} - -Of course, you could put any condition in there{---}you're not limited -to checking the values of already-defined options. For example, if -you have options that should not be called when the moon is full, all -you have to do is this: -\begin{verbatim} -def check_moon(option, opt_str, value, parser): - if is_moon_full(): - raise OptionValueError("%s option invalid when moon is full" - % opt_str) - setattr(parser.values, option.dest, 1) -[...] -parser.add_option("--foo", - action="callback", callback=check_moon, dest="foo") -\end{verbatim} - -(The definition of \code{is{\_}moon{\_}full()} is left as an exercise for the -reader.) - - -\subsubsection{Callback example 5: fixed arguments\label{optparse-callback-example-5}} - -Things get slightly more interesting when you define callback options -that take a fixed number of arguments. Specifying that a callback -option takes arguments is similar to defining a \code{store} or \code{append} -option: if you define \member{type}, then the option takes one argument that -must be convertible to that type; if you further define \code{nargs}, then -the option takes \code{nargs} arguments. - -Here's an example that just emulates the standard \code{store} action: -\begin{verbatim} -def store_value(option, opt_str, value, parser): - setattr(parser.values, option.dest, value) -[...] -parser.add_option("--foo", - action="callback", callback=store_value, - type="int", nargs=3, dest="foo") -\end{verbatim} - -Note that \module{optparse} takes care of consuming 3 arguments and converting them -to integers for you; all you have to do is store them. (Or whatever; -obviously you don't need a callback for this example.) - - -\subsubsection{Callback example 6: variable arguments\label{optparse-callback-example-6}} - -Things get hairy when you want an option to take a variable number of -arguments. For this case, you must write a callback, as \module{optparse} doesn't -provide any built-in capabilities for it. And you have to deal with -certain intricacies of conventional \UNIX{} command-line parsing that \module{optparse} -normally handles for you. In particular, callbacks should implement -the conventional rules for bare \code{"-{}-"} and \code{"-"} arguments: -\begin{itemize} -\item {} -either \code{"-{}-"} or \code{"-"} can be option arguments - -\item {} -bare \code{"-{}-"} (if not the argument to some option): halt command-line -processing and discard the \code{"-{}-"} - -\item {} -bare \code{"-"} (if not the argument to some option): halt command-line -processing but keep the \code{"-"} (append it to \code{parser.largs}) - -\end{itemize} - -If you want an option that takes a variable number of arguments, there -are several subtle, tricky issues to worry about. The exact -implementation you choose will be based on which trade-offs you're -willing to make for your application (which is why \module{optparse} doesn't support -this sort of thing directly). - -Nevertheless, here's a stab at a callback for an option with variable -arguments: -\begin{verbatim} -def vararg_callback(option, opt_str, value, parser): - assert value is None - done = 0 - value = [] - rargs = parser.rargs - while rargs: - arg = rargs[0] - - # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f", - # etc. Note that this also stops on "-3" or "-3.0", so if - # your option takes numeric values, you will need to handle - # this. - if ((arg[:2] == "--" and len(arg) > 2) or - (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")): - break - else: - value.append(arg) - del rargs[0] - - setattr(parser.values, option.dest, value) - -[...] -parser.add_option("-c", "--callback", - action="callback", callback=varargs) -\end{verbatim} - -The main weakness with this particular implementation is that negative -numbers in the arguments following \code{"-c"} will be interpreted as -further options (probably causing an error), rather than as arguments to -\code{"-c"}. Fixing this is left as an exercise for the reader. -% $Id: callbacks.txt 415 2004-09-30 02:26:17Z greg $ - - -\subsection{Extending \module{optparse}\label{optparse-extending-optparse}} - -Since the two major controlling factors in how \module{optparse} interprets -command-line options are the action and type of each option, the most -likely direction of extension is to add new actions and new types. - - -\subsubsection{Adding new types\label{optparse-adding-new-types}} - -To add new types, you need to define your own subclass of \module{optparse}'s Option -class. This class has a couple of attributes that define \module{optparse}'s types: -\member{TYPES} and \member{TYPE{\_}CHECKER}. - -\member{TYPES} is a tuple of type names; in your subclass, simply define a new -tuple \member{TYPES} that builds on the standard one. - -\member{TYPE{\_}CHECKER} is a dictionary mapping type names to type-checking -functions. A type-checking function has the following signature: -\begin{verbatim} -def check_mytype(option, opt, value) -\end{verbatim} - -where \code{option} is an \class{Option} instance, \code{opt} is an option string -(e.g., \code{"-f"}), and \code{value} is the string from the command line that -must be checked and converted to your desired type. \code{check{\_}mytype()} -should return an object of the hypothetical type \code{mytype}. The value -returned by a type-checking function will wind up in the OptionValues -instance returned by \method{OptionParser.parse{\_}args()}, or be passed to a -callback as the \code{value} parameter. - -Your type-checking function should raise OptionValueError if it -encounters any problems. OptionValueError takes a single string -argument, which is passed as-is to OptionParser's \method{error()} method, -which in turn prepends the program name and the string \code{"error:"} and -prints everything to stderr before terminating the process. - -Here's a silly example that demonstrates adding a \code{complex} option -type to parse Python-style complex numbers on the command line. (This -is even sillier than it used to be, because \module{optparse} 1.3 added built-in -support for complex numbers, but never mind.) - -First, the necessary imports: -\begin{verbatim} -from copy import copy -from optparse import Option, OptionValueError -\end{verbatim} - -You need to define your type-checker first, since it's referred to later -(in the \member{TYPE{\_}CHECKER} class attribute of your Option subclass): -\begin{verbatim} -def check_complex(option, opt, value): - try: - return complex(value) - except ValueError: - raise OptionValueError( - "option %s: invalid complex value: %r" % (opt, value)) -\end{verbatim} - -Finally, the Option subclass: -\begin{verbatim} -class MyOption (Option): - TYPES = Option.TYPES + ("complex",) - TYPE_CHECKER = copy(Option.TYPE_CHECKER) - TYPE_CHECKER["complex"] = check_complex -\end{verbatim} - -(If we didn't make a \function{copy()} of \member{Option.TYPE{\_}CHECKER}, we would end -up modifying the \member{TYPE{\_}CHECKER} attribute of \module{optparse}'s Option class. -This being Python, nothing stops you from doing that except good manners -and common sense.) - -That's it! Now you can write a script that uses the new option type -just like any other \module{optparse}-based script, except you have to instruct your -OptionParser to use MyOption instead of Option: -\begin{verbatim} -parser = OptionParser(option_class=MyOption) -parser.add_option("-c", type="complex") -\end{verbatim} - -Alternately, you can build your own option list and pass it to -OptionParser; if you don't use \method{add{\_}option()} in the above way, you -don't need to tell OptionParser which option class to use: -\begin{verbatim} -option_list = [MyOption("-c", action="store", type="complex", dest="c")] -parser = OptionParser(option_list=option_list) -\end{verbatim} - - -\subsubsection{Adding new actions\label{optparse-adding-new-actions}} - -Adding new actions is a bit trickier, because you have to understand -that \module{optparse} has a couple of classifications for actions: -\begin{description} -\item[``store'' actions] -actions that result in \module{optparse} storing a value to an attribute of the -current OptionValues instance; these options require a \member{dest} -attribute to be supplied to the Option constructor -\item[``typed'' actions] -actions that take a value from the command line and expect it to be -of a certain type; or rather, a string that can be converted to a -certain type. These options require a \member{type} attribute to the -Option constructor. -\end{description} - -These are overlapping sets: some default ``store'' actions are \code{store}, -\code{store{\_}const}, \code{append}, and \code{count}, while the default ``typed'' -actions are \code{store}, \code{append}, and \code{callback}. - -When you add an action, you need to categorize it by listing it in at -least one of the following class attributes of Option (all are lists of -strings): -\begin{description} -\item[\member{ACTIONS}] -all actions must be listed in ACTIONS -\item[\member{STORE{\_}ACTIONS}] -``store'' actions are additionally listed here -\item[\member{TYPED{\_}ACTIONS}] -``typed'' actions are additionally listed here -\item[\code{ALWAYS{\_}TYPED{\_}ACTIONS}] -actions that always take a type (i.e. whose options always take a -value) are additionally listed here. The only effect of this is -that \module{optparse} assigns the default type, \code{string}, to options with no -explicit type whose action is listed in \code{ALWAYS{\_}TYPED{\_}ACTIONS}. -\end{description} - -In order to actually implement your new action, you must override -Option's \method{take{\_}action()} method and add a case that recognizes your -action. - -For example, let's add an \code{extend} action. This is similar to the -standard \code{append} action, but instead of taking a single value from -the command-line and appending it to an existing list, \code{extend} will -take multiple values in a single comma-delimited string, and extend an -existing list with them. That is, if \code{"-{}-names"} is an \code{extend} -option of type \code{string}, the command line -\begin{verbatim} ---names=foo,bar --names blah --names ding,dong -\end{verbatim} - -would result in a list -\begin{verbatim} -["foo", "bar", "blah", "ding", "dong"] -\end{verbatim} - -Again we define a subclass of Option: -\begin{verbatim} -class MyOption (Option): - - ACTIONS = Option.ACTIONS + ("extend",) - STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",) - TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",) - ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",) - - def take_action(self, action, dest, opt, value, values, parser): - if action == "extend": - lvalue = value.split(",") - values.ensure_value(dest, []).extend(lvalue) - else: - Option.take_action( - self, action, dest, opt, value, values, parser) -\end{verbatim} - -Features of note: -\begin{itemize} -\item {} -\code{extend} both expects a value on the command-line and stores that -value somewhere, so it goes in both \member{STORE{\_}ACTIONS} and -\member{TYPED{\_}ACTIONS} - -\item {} -to ensure that \module{optparse} assigns the default type of \code{string} to -\code{extend} actions, we put the \code{extend} action in -\code{ALWAYS{\_}TYPED{\_}ACTIONS} as well - -\item {} -\method{MyOption.take{\_}action()} implements just this one new action, and -passes control back to \method{Option.take{\_}action()} for the standard -\module{optparse} actions - -\item {} -\code{values} is an instance of the optparse{\_}parser.Values class, -which provides the very useful \method{ensure{\_}value()} method. -\method{ensure{\_}value()} is essentially \function{getattr()} with a safety valve; -it is called as -\begin{verbatim} -values.ensure_value(attr, value) -\end{verbatim} - -If the \code{attr} attribute of \code{values} doesn't exist or is None, then -ensure{\_}value() first sets it to \code{value}, and then returns 'value. -This is very handy for actions like \code{extend}, \code{append}, and -\code{count}, all of which accumulate data in a variable and expect that -variable to be of a certain type (a list for the first two, an integer -for the latter). Using \method{ensure{\_}value()} means that scripts using -your action don't have to worry about setting a default value for the -option destinations in question; they can just leave the default as -None and \method{ensure{\_}value()} will take care of getting it right when -it's needed. - -\end{itemize} -% $Id: extending.txt 517 2006-06-10 16:18:11Z gward $ - diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex deleted file mode 100644 index 826e9fa..0000000 --- a/Doc/lib/libos.tex +++ /dev/null @@ -1,1980 +0,0 @@ -\section{\module{os} --- - Miscellaneous operating system interfaces} - -\declaremodule{standard}{os} -\modulesynopsis{Miscellaneous operating system interfaces.} - - -This module provides a more portable way of using operating system -dependent functionality than importing a operating system dependent -built-in module like \refmodule{posix} or \module{nt}. - -This module searches for an operating system dependent built-in module like -\module{mac} or \refmodule{posix} and exports the same functions and data -as found there. The design of all Python's built-in operating system dependent -modules is such that as long as the same functionality is available, -it uses the same interface; for example, the function -\code{os.stat(\var{path})} returns stat information about \var{path} in -the same format (which happens to have originated with the -\POSIX{} interface). - -Extensions peculiar to a particular operating system are also -available through the \module{os} module, but using them is of course a -threat to portability! - -Note that after the first time \module{os} is imported, there is -\emph{no} performance penalty in using functions from \module{os} -instead of directly from the operating system dependent built-in module, -so there should be \emph{no} reason not to use \module{os}! - - -% Frank Stajano <fstajano@uk.research.att.com> complained that it -% wasn't clear that the entries described in the subsections were all -% available at the module level (most uses of subsections are -% different); I think this is only a problem for the HTML version, -% where the relationship may not be as clear. -% -\ifhtml -The \module{os} module contains many functions and data values. -The items below and in the following sub-sections are all available -directly from the \module{os} module. -\fi - - -\begin{excdesc}{error} -This exception is raised when a function returns a system-related -error (not for illegal argument types or other incidental errors). -This is also known as the built-in exception \exception{OSError}. The -accompanying value is a pair containing the numeric error code from -\cdata{errno} and the corresponding string, as would be printed by the -C function \cfunction{perror()}. See the module -\refmodule{errno}\refbimodindex{errno}, which contains names for the -error codes defined by the underlying operating system. - -When exceptions are classes, this exception carries two attributes, -\member{errno} and \member{strerror}. The first holds the value of -the C \cdata{errno} variable, and the latter holds the corresponding -error message from \cfunction{strerror()}. For exceptions that -involve a file system path (such as \function{chdir()} or -\function{unlink()}), the exception instance will contain a third -attribute, \member{filename}, which is the file name passed to the -function. -\end{excdesc} - -\begin{datadesc}{name} -The name of the operating system dependent module imported. The -following names have currently been registered: \code{'posix'}, -\code{'nt'}, \code{'mac'}, \code{'os2'}, \code{'ce'}, -\code{'java'}, \code{'riscos'}. -\end{datadesc} - -\begin{datadesc}{path} -The corresponding operating system dependent standard module for pathname -operations, such as \module{posixpath} or \module{macpath}. Thus, -given the proper imports, \code{os.path.split(\var{file})} is -equivalent to but more portable than -\code{posixpath.split(\var{file})}. Note that this is also an -importable module: it may be imported directly as -\refmodule{os.path}. -\end{datadesc} - - - -\subsection{Process Parameters \label{os-procinfo}} - -These functions and data items provide information and operate on the -current process and user. - -\begin{datadesc}{environ} -A mapping object representing the string environment. For example, -\code{environ['HOME']} is the pathname of your home directory (on some -platforms), and is equivalent to \code{getenv("HOME")} in C. - -This mapping is captured the first time the \module{os} module is -imported, typically during Python startup as part of processing -\file{site.py}. Changes to the environment made after this time are -not reflected in \code{os.environ}, except for changes made by modifying -\code{os.environ} directly. - -If the platform supports the \function{putenv()} function, this -mapping may be used to modify the environment as well as query the -environment. \function{putenv()} will be called automatically when -the mapping is modified. -\note{Calling \function{putenv()} directly does not change -\code{os.environ}, so it's better to modify \code{os.environ}.} -\note{On some platforms, including FreeBSD and Mac OS X, setting -\code{environ} may cause memory leaks. Refer to the system documentation -for \cfunction{putenv()}.} - -If \function{putenv()} is not provided, a modified copy of this mapping -may be passed to the appropriate process-creation functions to cause -child processes to use a modified environment. - -If the platform supports the \function{unsetenv()} function, you can -delete items in this mapping to unset environment variables. -\function{unsetenv()} will be called automatically when an item is -deleted from \code{os.environ}. - -\end{datadesc} - -\begin{funcdescni}{chdir}{path} -\funclineni{fchdir}{fd} -\funclineni{getcwd}{} -These functions are described in ``Files and Directories'' (section -\ref{os-file-dir}). -\end{funcdescni} - -\begin{funcdesc}{ctermid}{} -Return the filename corresponding to the controlling terminal of the -process. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getegid}{} -Return the effective group id of the current process. This -corresponds to the `set id' bit on the file being executed in the -current process. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{geteuid}{} -\index{user!effective id} -Return the current process' effective user id. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getgid}{} -\index{process!group} -Return the real group id of the current process. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getgroups}{} -Return list of supplemental group ids associated with the current -process. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getlogin}{} -Return the name of the user logged in on the controlling terminal of -the process. For most purposes, it is more useful to use the -environment variable \envvar{LOGNAME} to find out who the user is, -or \code{pwd.getpwuid(os.getuid())[0]} to get the login name -of the currently effective user ID. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getpgid}{pid} -Return the process group id of the process with process id \var{pid}. -If \var{pid} is 0, the process group id of the current process is -returned. Availability: \UNIX. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{getpgrp}{} -\index{process!group} -Return the id of the current process group. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getpid}{} -\index{process!id} -Return the current process id. -Availability: \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{getppid}{} -\index{process!id of parent} -Return the parent's process id. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getuid}{} -\index{user!id} -Return the current process' user id. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getenv}{varname\optional{, value}} -Return the value of the environment variable \var{varname} if it -exists, or \var{value} if it doesn't. \var{value} defaults to -\code{None}. -Availability: most flavors of \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{putenv}{varname, value} -\index{environment variables!setting} -Set the environment variable named \var{varname} to the string -\var{value}. Such changes to the environment affect subprocesses -started with \function{os.system()}, \function{popen()} or -\function{fork()} and \function{execv()}. -Availability: most flavors of \UNIX, Windows. - -\note{On some platforms, including FreeBSD and Mac OS X, -setting \code{environ} may cause memory leaks. -Refer to the system documentation for putenv.} - -When \function{putenv()} is -supported, assignments to items in \code{os.environ} are automatically -translated into corresponding calls to \function{putenv()}; however, -calls to \function{putenv()} don't update \code{os.environ}, so it is -actually preferable to assign to items of \code{os.environ}. -\end{funcdesc} - -\begin{funcdesc}{setegid}{egid} -Set the current process's effective group id. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{seteuid}{euid} -Set the current process's effective user id. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{setgid}{gid} -Set the current process' group id. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{setgroups}{groups} -Set the list of supplemental group ids associated with the current -process to \var{groups}. \var{groups} must be a sequence, and each -element must be an integer identifying a group. This operation is -typical available only to the superuser. -Availability: \UNIX. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{setpgrp}{} -Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0, -0)} depending on which version is implemented (if any). See the -\UNIX{} manual for the semantics. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{setpgid}{pid, pgrp} Calls the system call -\cfunction{setpgid()} to set the process group id of the process with -id \var{pid} to the process group with id \var{pgrp}. See the \UNIX{} -manual for the semantics. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{setreuid}{ruid, euid} -Set the current process's real and effective user ids. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{setregid}{rgid, egid} -Set the current process's real and effective group ids. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getsid}{pid} -Calls the system call \cfunction{getsid()}. See the \UNIX{} manual -for the semantics. -Availability: \UNIX. \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{setsid}{} -Calls the system call \cfunction{setsid()}. See the \UNIX{} manual -for the semantics. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{setuid}{uid} -\index{user!id, setting} -Set the current process' user id. -Availability: \UNIX. -\end{funcdesc} - -% placed in this section since it relates to errno.... a little weak -\begin{funcdesc}{strerror}{code} -Return the error message corresponding to the error code in -\var{code}. -Availability: \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{umask}{mask} -Set the current numeric umask and returns the previous umask. -Availability: \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{uname}{} -Return a 5-tuple containing information identifying the current -operating system. The tuple contains 5 strings: -\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version}, -\var{machine})}. Some systems truncate the nodename to 8 -characters or to the leading component; a better way to get the -hostname is \function{socket.gethostname()} -\withsubitem{(in module socket)}{\ttindex{gethostname()}} -or even -\withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}} -\code{socket.gethostbyaddr(socket.gethostname())}. -Availability: recent flavors of \UNIX. -\end{funcdesc} - -\begin{funcdesc}{unsetenv}{varname} -\index{environment variables!deleting} -Unset (delete) the environment variable named \var{varname}. Such -changes to the environment affect subprocesses started with -\function{os.system()}, \function{popen()} or \function{fork()} and -\function{execv()}. Availability: most flavors of \UNIX, Windows. - -When \function{unsetenv()} is -supported, deletion of items in \code{os.environ} is automatically -translated into a corresponding call to \function{unsetenv()}; however, -calls to \function{unsetenv()} don't update \code{os.environ}, so it is -actually preferable to delete items of \code{os.environ}. -\end{funcdesc} - -\subsection{File Object Creation \label{os-newstreams}} - -These functions create new file objects. - - -\begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}} -Return an open file object connected to the file descriptor \var{fd}. -\index{I/O control!buffering} -The \var{mode} and \var{bufsize} arguments have the same meaning as -the corresponding arguments to the built-in \function{open()} -function. -Availability: Macintosh, \UNIX, Windows. - -\versionchanged[When specified, the \var{mode} argument must now start - with one of the letters \character{r}, \character{w}, or \character{a}, - otherwise a \exception{ValueError} is raised]{2.3} -\versionchanged[On \UNIX, when the \var{mode} argument starts with - \character{a}, the \var{O_APPEND} flag is set on the file descriptor - (which the \cfunction{fdopen()} implementation already does on most - platforms)]{2.5} -\end{funcdesc} - -\begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}} -Open a pipe to or from \var{command}. The return value is an open -file object connected to the pipe, which can be read or written -depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}. -The \var{bufsize} argument has the same meaning as the corresponding -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. -Availability: Macintosh, \UNIX, Windows. - -\deprecated{2.6}{This function is obsolete. Use the - \module{subprocess} module.} - -\versionchanged[This function worked unreliably under Windows in - earlier versions of Python. This was due to the use of the - \cfunction{_popen()} function from the libraries provided with - Windows. Newer versions of Python do not use the broken - implementation from the Windows libraries]{2.0} -\end{funcdesc} - -\begin{funcdesc}{tmpfile}{} -Return a new file object opened in update mode (\samp{w+b}). The file -has no directory entries associated with it and will be automatically -deleted once there are no file descriptors for the file. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - - -\subsection{File Descriptor Operations \label{os-fd-ops}} - -These functions operate on I/O streams referenced using file -descriptors. - -File descriptors are small integers corresponding to a file that has -been opened by the current process. For example, standard input is -usually file descriptor 0, standard output is 1, and standard error is -2. Further files opened by a process will then be assigned 3, 4, 5, -and so forth. The name ``file descriptor'' is slightly deceptive; on -{\UNIX} platforms, sockets and pipes are also referenced by file descriptors. - - -\begin{funcdesc}{close}{fd} -Close file descriptor \var{fd}. -Availability: Macintosh, \UNIX, Windows. - -\begin{notice} -This function is intended for low-level I/O and must be applied -to a file descriptor as returned by \function{open()} or -\function{pipe()}. To close a ``file object'' returned by the -built-in function \function{open()} or by \function{popen()} or -\function{fdopen()}, use its \method{close()} method. -\end{notice} -\end{funcdesc} - -\begin{funcdesc}{dup}{fd} -Return a duplicate of file descriptor \var{fd}. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{dup2}{fd, fd2} -Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter -first if necessary. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{fdatasync}{fd} -Force write of file with filedescriptor \var{fd} to disk. -Does not force update of metadata. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{fpathconf}{fd, name} -Return system configuration information relevant to an open file. -\var{name} specifies the configuration value to retrieve; it may be a -string which is the name of a defined system value; these names are -specified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, and -others). Some platforms define additional names as well. The names -known to the host operating system are given in the -\code{pathconf_names} dictionary. For configuration variables not -included in that mapping, passing an integer for \var{name} is also -accepted. -Availability: Macintosh, \UNIX. - -If \var{name} is a string and is not known, \exception{ValueError} is -raised. If a specific value for \var{name} is not supported by the -host system, even if it is included in \code{pathconf_names}, an -\exception{OSError} is raised with \constant{errno.EINVAL} for the -error number. -\end{funcdesc} - -\begin{funcdesc}{fstat}{fd} -Return status for file descriptor \var{fd}, like \function{stat()}. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{fstatvfs}{fd} -Return information about the filesystem containing the file associated -with file descriptor \var{fd}, like \function{statvfs()}. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{fsync}{fd} -Force write of file with filedescriptor \var{fd} to disk. On \UNIX, -this calls the native \cfunction{fsync()} function; on Windows, the -MS \cfunction{_commit()} function. - -If you're starting with a Python file object \var{f}, first do -\code{\var{f}.flush()}, and then do \code{os.fsync(\var{f}.fileno())}, -to ensure that all internal buffers associated with \var{f} are written -to disk. -Availability: Macintosh, \UNIX, and Windows starting in 2.2.3. -\end{funcdesc} - -\begin{funcdesc}{ftruncate}{fd, length} -Truncate the file corresponding to file descriptor \var{fd}, -so that it is at most \var{length} bytes in size. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{isatty}{fd} -Return \code{True} if the file descriptor \var{fd} is open and -connected to a tty(-like) device, else \code{False}. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{lseek}{fd, pos, how} -Set the current position of file descriptor \var{fd} to position -\var{pos}, modified by \var{how}: \code{0} to set the position -relative to the beginning of the file; \code{1} to set it relative to -the current position; \code{2} to set it relative to the end of the -file. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{open}{file, flags\optional{, mode}} -Open the file \var{file} and set various flags according to -\var{flags} and possibly its mode according to \var{mode}. -The default \var{mode} is \code{0777} (octal), and the current umask -value is first masked out. Return the file descriptor for the newly -opened file. -Availability: Macintosh, \UNIX, Windows. - -For a description of the flag and mode values, see the C run-time -documentation; flag constants (like \constant{O_RDONLY} and -\constant{O_WRONLY}) are defined in this module too (see below). - -\begin{notice} -This function is intended for low-level I/O. For normal usage, -use the built-in function \function{open()}, which returns a ``file -object'' with \method{read()} and \method{write()} methods (and many -more). To wrap a file descriptor in a ``file object'', use -\function{fdopen()}. -\end{notice} -\end{funcdesc} - -\begin{funcdesc}{openpty}{} -Open a new pseudo-terminal pair. Return a pair of file descriptors -\code{(\var{master}, \var{slave})} for the pty and the tty, -respectively. For a (slightly) more portable approach, use the -\refmodule{pty}\refstmodindex{pty} module. -Availability: Macintosh, Some flavors of \UNIX. -\end{funcdesc} - -\begin{funcdesc}{pipe}{} -Create a pipe. Return a pair of file descriptors \code{(\var{r}, -\var{w})} usable for reading and writing, respectively. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{read}{fd, n} -Read at most \var{n} bytes from file descriptor \var{fd}. -Return a string containing the bytes read. If the end of the file -referred to by \var{fd} has been reached, an empty string is -returned. -Availability: Macintosh, \UNIX, Windows. - -\begin{notice} -This function is intended for low-level I/O and must be applied -to a file descriptor as returned by \function{open()} or -\function{pipe()}. To read a ``file object'' returned by the -built-in function \function{open()} or by \function{popen()} or -\function{fdopen()}, or \code{sys.stdin}, use its -\method{read()} or \method{readline()} methods. -\end{notice} -\end{funcdesc} - -\begin{funcdesc}{tcgetpgrp}{fd} -Return the process group associated with the terminal given by -\var{fd} (an open file descriptor as returned by \function{open()}). -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{tcsetpgrp}{fd, pg} -Set the process group associated with the terminal given by -\var{fd} (an open file descriptor as returned by \function{open()}) -to \var{pg}. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{ttyname}{fd} -Return a string which specifies the terminal device associated with -file-descriptor \var{fd}. If \var{fd} is not associated with a terminal -device, an exception is raised. -Availability:Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{write}{fd, str} -Write the string \var{str} to file descriptor \var{fd}. -Return the number of bytes actually written. -Availability: Macintosh, \UNIX, Windows. - -\begin{notice} -This function is intended for low-level I/O and must be applied -to a file descriptor as returned by \function{open()} or -\function{pipe()}. To write a ``file object'' returned by the -built-in function \function{open()} or by \function{popen()} or -\function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use -its \method{write()} method. -\end{notice} -\end{funcdesc} - - -The following data items are available for use in constructing the -\var{flags} parameter to the \function{open()} function. Some items will -not be available on all platforms. For descriptions of their availability -and use, consult \manpage{open}{2}. - -\begin{datadesc}{O_RDONLY} -\dataline{O_WRONLY} -\dataline{O_RDWR} -\dataline{O_APPEND} -\dataline{O_CREAT} -\dataline{O_EXCL} -\dataline{O_TRUNC} -Options for the \var{flag} argument to the \function{open()} function. -These can be bit-wise OR'd together. -Availability: Macintosh, \UNIX, Windows. -\end{datadesc} - -\begin{datadesc}{O_DSYNC} -\dataline{O_RSYNC} -\dataline{O_SYNC} -\dataline{O_NDELAY} -\dataline{O_NONBLOCK} -\dataline{O_NOCTTY} -\dataline{O_SHLOCK} -\dataline{O_EXLOCK} -More options for the \var{flag} argument to the \function{open()} function. -Availability: Macintosh, \UNIX. -\end{datadesc} - -\begin{datadesc}{O_BINARY} -Option for the \var{flag} argument to the \function{open()} function. -This can be bit-wise OR'd together with those listed above. -Availability: Windows. -% XXX need to check on the availability of this one. -\end{datadesc} - -\begin{datadesc}{O_NOINHERIT} -\dataline{O_SHORT_LIVED} -\dataline{O_TEMPORARY} -\dataline{O_RANDOM} -\dataline{O_SEQUENTIAL} -\dataline{O_TEXT} -Options for the \var{flag} argument to the \function{open()} function. -These can be bit-wise OR'd together. -Availability: Windows. -\end{datadesc} - -\begin{datadesc}{SEEK_SET} -\dataline{SEEK_CUR} -\dataline{SEEK_END} -Parameters to the \function{lseek()} function. -Their values are 0, 1, and 2, respectively. -Availability: Windows, Macintosh, \UNIX. -\versionadded{2.5} -\end{datadesc} - -\subsection{Files and Directories \label{os-file-dir}} - -\begin{funcdesc}{access}{path, mode} -Use the real uid/gid to test for access to \var{path}. Note that most -operations will use the effective uid/gid, therefore this routine can -be used in a suid/sgid environment to test if the invoking user has the -specified access to \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 \constant{True} if access is allowed, -\constant{False} if not. -See the \UNIX{} man page \manpage{access}{2} for more information. -Availability: Macintosh, \UNIX, Windows. - -\note{Using \function{access()} to check if a user is authorized to e.g. -open a file before actually doing so using \function{open()} creates a -security hole, because the user might exploit the short time interval -between checking and opening the file to manipulate it.} - -\note{I/O operations may fail even when \function{access()} -indicates that they would succeed, particularly for operations -on network filesystems which may have permissions semantics -beyond the usual \POSIX{} permission-bit model.} -\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}. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{fchdir}{fd} -Change the current working directory to the directory represented by -the file descriptor \var{fd}. The descriptor must refer to an opened -directory, not an open file. -Availability: \UNIX. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{getcwd}{} -Return a string representing the current working directory. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{getcwdu}{} -Return a Unicode object representing the current working directory. -Availability: Macintosh, \UNIX, Windows. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{chflags}{path, flags} -Set the flags of \var{path} to the numeric \var{flags}. -\var{flags} may take a combination (bitwise OR) of the following values -(as defined in the \module{stat} module): -\begin{itemize} - \item \code{UF_NODUMP} - \item \code{UF_IMMUTABLE} - \item \code{UF_APPEND} - \item \code{UF_OPAQUE} - \item \code{UF_NOUNLINK} - \item \code{SF_ARCHIVED} - \item \code{SF_IMMUTABLE} - \item \code{SF_APPEND} - \item \code{SF_NOUNLINK} - \item \code{SF_SNAPSHOT} -\end{itemize} -Availability: Macintosh, \UNIX. -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{chroot}{path} -Change the root directory of the current process to \var{path}. -Availability: Macintosh, \UNIX. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{chmod}{path, mode} -Change the mode of \var{path} to the numeric \var{mode}. -\var{mode} may take one of the following values -(as defined in the \module{stat} module) or bitwise or-ed -combinations of them: -\begin{itemize} - \item \code{S_ISUID} - \item \code{S_ISGID} - \item \code{S_ENFMT} - \item \code{S_ISVTX} - \item \code{S_IREAD} - \item \code{S_IWRITE} - \item \code{S_IEXEC} - \item \code{S_IRWXU} - \item \code{S_IRUSR} - \item \code{S_IWUSR} - \item \code{S_IXUSR} - \item \code{S_IRWXG} - \item \code{S_IRGRP} - \item \code{S_IWGRP} - \item \code{S_IXGRP} - \item \code{S_IRWXO} - \item \code{S_IROTH} - \item \code{S_IWOTH} - \item \code{S_IXOTH} -\end{itemize} -Availability: Macintosh, \UNIX, Windows. - -\note{Although Windows supports \function{chmod()}, you can only -set the file's read-only flag with it (via the \code{S_IWRITE} -and \code{S_IREAD} constants or a corresponding integer value). -All other bits are ignored.} -\end{funcdesc} - -\begin{funcdesc}{chown}{path, uid, gid} -Change the owner and group id of \var{path} to the numeric \var{uid} -and \var{gid}. To leave one of the ids unchanged, set it to -1. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{lchflags}{path, flags} -Set the flags of \var{path} to the numeric \var{flags}, like -\function{chflags()}, but do not follow symbolic links. -Availability: \UNIX. -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{lchown}{path, uid, gid} -Change the owner and group id of \var{path} to the numeric \var{uid} -and gid. This function will not follow symbolic links. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{link}{src, dst} -Create a hard link pointing to \var{src} named \var{dst}. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{listdir}{path} -Return a list containing the names of the entries in the directory. -The list is in arbitrary order. It does not include the special -entries \code{'.'} and \code{'..'} even if they are present in the -directory. -Availability: Macintosh, \UNIX, Windows. - -\versionchanged[On Windows NT/2k/XP and \UNIX, if \var{path} is a Unicode -object, the result will be a list of Unicode objects]{2.3} -\end{funcdesc} - -\begin{funcdesc}{lstat}{path} -Like \function{stat()}, but do not follow symbolic links. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{mkfifo}{path\optional{, mode}} -Create a FIFO (a named pipe) named \var{path} with numeric mode -\var{mode}. The default \var{mode} is \code{0666} (octal). The current -umask value is first masked out from the mode. -Availability: Macintosh, \UNIX. - -FIFOs are pipes that can be accessed like regular files. FIFOs exist -until they are deleted (for example with \function{os.unlink()}). -Generally, FIFOs are used as rendezvous between ``client'' and -``server'' type processes: the server opens the FIFO for reading, and -the client opens it for writing. Note that \function{mkfifo()} -doesn't open the FIFO --- it just creates the rendezvous point. -\end{funcdesc} - -\begin{funcdesc}{mknod}{filename\optional{, mode=0600, device}} -Create a filesystem node (file, device special file or named pipe) -named \var{filename}. \var{mode} specifies both the permissions to use and -the type of node to be created, being combined (bitwise OR) with one -of S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are -available in \module{stat}). For S_IFCHR and S_IFBLK, \var{device} -defines the newly created device special file (probably using -\function{os.makedev()}), otherwise it is ignored. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{major}{device} -Extracts the device major number from a raw device number (usually -the \member{st_dev} or \member{st_rdev} field from \ctype{stat}). -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{minor}{device} -Extracts the device minor number from a raw device number (usually -the \member{st_dev} or \member{st_rdev} field from \ctype{stat}). -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{makedev}{major, minor} -Composes a raw device number from the major and minor device numbers. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{mkdir}{path\optional{, mode}} -Create a directory named \var{path} with numeric mode \var{mode}. -The default \var{mode} is \code{0777} (octal). On some systems, -\var{mode} is ignored. Where it is used, the current umask value is -first masked out. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{makedirs}{path\optional{, mode}} -Recursive directory creation function.\index{directory!creating} -\index{UNC paths!and \function{os.makedirs()}} -Like \function{mkdir()}, -but makes all intermediate-level directories needed to contain the -leaf directory. Throws an \exception{error} exception if the leaf -directory already exists or cannot be created. The default \var{mode} -is \code{0777} (octal). On some systems, \var{mode} is ignored. -Where it is used, the current umask value is first masked out. -\note{\function{makedirs()} will become confused if the path elements -to create include \var{os.pardir}.} -\versionadded{1.5.2} -\versionchanged[This function now handles UNC paths correctly]{2.3} -\end{funcdesc} - -\begin{funcdesc}{pathconf}{path, name} -Return system configuration information relevant to a named file. -\var{name} specifies the configuration value to retrieve; it may be a -string which is the name of a defined system value; these names are -specified in a number of standards (\POSIX.1, \UNIX{} 95, \UNIX{} 98, and -others). Some platforms define additional names as well. The names -known to the host operating system are given in the -\code{pathconf_names} dictionary. For configuration variables not -included in that mapping, passing an integer for \var{name} is also -accepted. -Availability: Macintosh, \UNIX. - -If \var{name} is a string and is not known, \exception{ValueError} is -raised. If a specific value for \var{name} is not supported by the -host system, even if it is included in \code{pathconf_names}, an -\exception{OSError} is raised with \constant{errno.EINVAL} for the -error number. -\end{funcdesc} - -\begin{datadesc}{pathconf_names} -Dictionary mapping names accepted by \function{pathconf()} and -\function{fpathconf()} to the integer values defined for those names -by the host operating system. This can be used to determine the set -of names known to the system. -Availability: Macintosh, \UNIX. -\end{datadesc} - -\begin{funcdesc}{readlink}{path} -Return a string representing the path to which the symbolic link -points. The result may be either an absolute or relative pathname; if -it is relative, it may be converted to an absolute pathname using -\code{os.path.join(os.path.dirname(\var{path}), \var{result})}. -\versionchanged [If the \var{path} is a Unicode object the result will also -be a Unicode object]{2.6} -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{remove}{path} -Remove the file \var{path}. If \var{path} is a directory, -\exception{OSError} is raised; see \function{rmdir()} below to remove -a directory. This is identical to the \function{unlink()} function -documented below. On Windows, attempting to remove a file that is in -use causes an exception to be raised; on \UNIX, the directory entry is -removed but the storage allocated to the file is not made available -until the original file is no longer in use. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{removedirs}{path} -\index{directory!deleting} -Removes directories recursively. Works like -\function{rmdir()} except that, if the leaf directory is -successfully removed, \function{removedirs()} -tries to successively remove every parent directory mentioned in -\var{path} until an error is raised (which is ignored, because -it generally means that a parent directory is not empty). -For example, \samp{os.removedirs('foo/bar/baz')} will first remove -the directory \samp{'foo/bar/baz'}, and then remove \samp{'foo/bar'} -and \samp{'foo'} if they are empty. -Raises \exception{OSError} if the leaf directory could not be -successfully removed. -\versionadded{1.5.2} -\end{funcdesc} - -\begin{funcdesc}{rename}{src, dst} -Rename the file or directory \var{src} to \var{dst}. If \var{dst} is -a directory, \exception{OSError} will be raised. On \UNIX, if -\var{dst} exists and is a file, it will be removed silently if the -user has permission. The operation may fail on some \UNIX{} flavors -if \var{src} and \var{dst} are on different filesystems. If -successful, the renaming will be an atomic operation (this is a -\POSIX{} requirement). On Windows, if \var{dst} already exists, -\exception{OSError} will be raised even if it is a file; there may be -no way to implement an atomic rename when \var{dst} names an existing -file. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{renames}{old, new} -Recursive directory or file renaming function. -Works like \function{rename()}, except creation of any intermediate -directories needed to make the new pathname good is attempted first. -After the rename, directories corresponding to rightmost path segments -of the old name will be pruned away using \function{removedirs()}. -\versionadded{1.5.2} - -\begin{notice} -This function can fail with the new directory structure made if -you lack permissions needed to remove the leaf directory or file. -\end{notice} -\end{funcdesc} - -\begin{funcdesc}{rmdir}{path} -Remove the directory \var{path}. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{stat}{path} -Perform a \cfunction{stat()} system call on the given path. The -return value is an object whose attributes correspond to the members of -the \ctype{stat} structure, namely: -\member{st_mode} (protection bits), -\member{st_ino} (inode number), -\member{st_dev} (device), -\member{st_nlink} (number of hard links), -\member{st_uid} (user ID of owner), -\member{st_gid} (group ID of owner), -\member{st_size} (size of file, in bytes), -\member{st_atime} (time of most recent access), -\member{st_mtime} (time of most recent content modification), -\member{st_ctime} -(platform dependent; time of most recent metadata change on \UNIX, or -the time of creation on Windows): - -\begin{verbatim} ->>> import os ->>> statinfo = os.stat('somefile.txt') ->>> statinfo -(33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732) ->>> statinfo.st_size -926L ->>> -\end{verbatim} - -\versionchanged [If \function{stat_float_times} returns true, the time -values are floats, measuring seconds. Fractions of a second may be -reported if the system supports that. On Mac OS, the times are always -floats. See \function{stat_float_times} for further discussion]{2.3} - -On some \UNIX{} systems (such as Linux), the following attributes may -also be available: -\member{st_blocks} (number of blocks allocated for file), -\member{st_blksize} (filesystem blocksize), -\member{st_rdev} (type of device if an inode device). -\member{st_flags} (user defined flags for file). - -On other \UNIX{} systems (such as FreeBSD), the following attributes -may be available (but may be only filled out if root tries to -use them): -\member{st_gen} (file generation number), -\member{st_birthtime} (time of file creation). - -On Mac OS systems, the following attributes may also be available: -\member{st_rsize}, -\member{st_creator}, -\member{st_type}. - -On RISCOS systems, the following attributes are also available: -\member{st_ftype} (file type), -\member{st_attrs} (attributes), -\member{st_obtype} (object type). - -For backward compatibility, the return value of \function{stat()} is -also accessible as a tuple of at least 10 integers giving the most -important (and portable) members of the \ctype{stat} structure, in the -order -\member{st_mode}, -\member{st_ino}, -\member{st_dev}, -\member{st_nlink}, -\member{st_uid}, -\member{st_gid}, -\member{st_size}, -\member{st_atime}, -\member{st_mtime}, -\member{st_ctime}. -More items may be added at the end by some implementations. -The standard module \refmodule{stat}\refstmodindex{stat} defines -functions and constants that are useful for extracting information -from a \ctype{stat} structure. -(On Windows, some items are filled with dummy values.) - -\note{The exact meaning and resolution of the \member{st_atime}, - \member{st_mtime}, and \member{st_ctime} members depends on the - operating system and the file system. For example, on Windows systems - using the FAT or FAT32 file systems, \member{st_mtime} has 2-second - resolution, and \member{st_atime} has only 1-day resolution. See - your operating system documentation for details.} - -Availability: Macintosh, \UNIX, Windows. - -\versionchanged -[Added access to values as attributes of the returned object]{2.2} -\versionchanged[Added st_gen, st_birthtime]{2.5} -\end{funcdesc} - -\begin{funcdesc}{stat_float_times}{\optional{newvalue}} -Determine whether \class{stat_result} represents time stamps as float -objects. If \var{newvalue} is \code{True}, future calls to \function{stat()} -return floats, if it is \code{False}, future calls return ints. -If \var{newvalue} is omitted, return the current setting. - -For compatibility with older Python versions, accessing -\class{stat_result} as a tuple always returns integers. - -\versionchanged[Python now returns float values by default. Applications -which do not work correctly with floating point time stamps can use -this function to restore the old behaviour]{2.5} - -The resolution of the timestamps (that is the smallest possible fraction) -depends on the system. Some systems only support second resolution; -on these systems, the fraction will always be zero. - -It is recommended that this setting is only changed at program startup -time in the \var{__main__} module; libraries should never change this -setting. If an application uses a library that works incorrectly if -floating point time stamps are processed, this application should turn -the feature off until the library has been corrected. - -\end{funcdesc} - -\begin{funcdesc}{statvfs}{path} -Perform a \cfunction{statvfs()} system call on the given path. The -return value is an object whose attributes describe the filesystem on -the given path, and correspond to the members of the -\ctype{statvfs} structure, namely: -\member{f_bsize}, -\member{f_frsize}, -\member{f_blocks}, -\member{f_bfree}, -\member{f_bavail}, -\member{f_files}, -\member{f_ffree}, -\member{f_favail}, -\member{f_flag}, -\member{f_namemax}. -Availability: \UNIX. - -For backward compatibility, the return value is also accessible as a -tuple whose values correspond to the attributes, in the order given above. -The standard module \refmodule{statvfs}\refstmodindex{statvfs} -defines constants that are useful for extracting information -from a \ctype{statvfs} structure when accessing it as a sequence; this -remains useful when writing code that needs to work with versions of -Python that don't support accessing the fields as attributes. - -\versionchanged -[Added access to values as attributes of the returned object]{2.2} -\end{funcdesc} - -\begin{funcdesc}{symlink}{src, dst} -Create a symbolic link pointing to \var{src} named \var{dst}. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{tempnam}{\optional{dir\optional{, prefix}}} -Return a unique path name that is reasonable for creating a temporary -file. This will be an absolute path that names a potential directory -entry in the directory \var{dir} or a common location for temporary -files if \var{dir} is omitted or \code{None}. If given and not -\code{None}, \var{prefix} is used to provide a short prefix to the -filename. Applications are responsible for properly creating and -managing files created using paths returned by \function{tempnam()}; -no automatic cleanup is provided. -On \UNIX, the environment variable \envvar{TMPDIR} overrides -\var{dir}, while on Windows the \envvar{TMP} is used. The specific -behavior of this function depends on the C library implementation; -some aspects are underspecified in system documentation. -\warning{Use of \function{tempnam()} is vulnerable to symlink attacks; -consider using \function{tmpfile()} (section \ref{os-newstreams}) -instead.} Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{tmpnam}{} -Return a unique path name that is reasonable for creating a temporary -file. This will be an absolute path that names a potential directory -entry in a common location for temporary files. Applications are -responsible for properly creating and managing files created using -paths returned by \function{tmpnam()}; no automatic cleanup is -provided. -\warning{Use of \function{tmpnam()} is vulnerable to symlink attacks; -consider using \function{tmpfile()} (section \ref{os-newstreams}) -instead.} Availability: \UNIX, Windows. This function probably -shouldn't be used on Windows, though: Microsoft's implementation of -\function{tmpnam()} always creates a name in the root directory of the -current drive, and that's generally a poor location for a temp file -(depending on privileges, you may not even be able to open a file -using this name). -\end{funcdesc} - -\begin{datadesc}{TMP_MAX} -The maximum number of unique names that \function{tmpnam()} will -generate before reusing names. -\end{datadesc} - -\begin{funcdesc}{unlink}{path} -Remove the file \var{path}. This is the same function as -\function{remove()}; the \function{unlink()} name is its traditional -\UNIX{} name. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{utime}{path, times} -Set the access and modified times of the file specified by \var{path}. -If \var{times} is \code{None}, then the file's access and modified -times are set to the current time. Otherwise, \var{times} must be a -2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})} -which is used to set the access and modified times, respectively. -Whether a directory can be given for \var{path} depends on whether the -operating system implements directories as files (for example, Windows -does not). Note that the exact times you set here may not be returned -by a subsequent \function{stat()} call, depending on the resolution -with which your operating system records access and modification times; -see \function{stat()}. -\versionchanged[Added support for \code{None} for \var{times}]{2.0} -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{walk}{top\optional{, topdown\code{=True} - \optional{, onerror\code{=None}\optional{, - followlinks\code{=False}}}}} -\index{directory!walking} -\index{directory!traversal} -\function{walk()} generates the file names in a directory tree, by -walking the tree either top down or bottom up. -For each directory in the tree rooted at directory \var{top} (including -\var{top} itself), it yields a 3-tuple -\code{(\var{dirpath}, \var{dirnames}, \var{filenames})}. - -\var{dirpath} is a string, the path to the directory. \var{dirnames} is -a list of the names of the subdirectories in \var{dirpath} -(excluding \code{'.'} and \code{'..'}). \var{filenames} is a list of -the names of the non-directory files in \var{dirpath}. Note that the -names in the lists contain no path components. To get a full -path (which begins with \var{top}) to a file or directory in -\var{dirpath}, do \code{os.path.join(\var{dirpath}, \var{name})}. - -If optional argument \var{topdown} is true or not specified, the triple -for a directory is generated before the triples for any of its -subdirectories (directories are generated top down). If \var{topdown} is -false, the triple for a directory is generated after the triples for all -of its subdirectories (directories are generated bottom up). - -When \var{topdown} is true, the caller can modify the \var{dirnames} list -in-place (perhaps using \keyword{del} or slice assignment), and -\function{walk()} will only recurse into the subdirectories whose names -remain in \var{dirnames}; this can be used to prune the search, -impose a specific order of visiting, or even to inform \function{walk()} -about directories the caller creates or renames before it resumes -\function{walk()} again. Modifying \var{dirnames} when \var{topdown} is -false is ineffective, because in bottom-up mode the directories in -\var{dirnames} are generated before \var{dirpath} itself is generated. - -By default errors from the \code{os.listdir()} call are ignored. If -optional argument \var{onerror} is specified, it should be a function; -it will be called with one argument, an \exception{OSError} instance. It can -report the error to continue with the walk, or raise the exception -to abort the walk. Note that the filename is available as the -\code{filename} attribute of the exception object. - -By default, \function{walk()} will not walk down into symbolic links that -resolve to directories. Set \var{followlinks} to True to visit directories -pointed to by symlinks, on systems that support them. - -\versionadded[The \var{followlinks} parameter]{2.6} - -\begin{notice} -Be aware that setting \var{followlinks} to true can lead to infinite recursion -if a link points to a parent directory of itself. \function{walk()} does not -keep track of the directories it visited already. -\end{notice} - -\begin{notice} -If you pass a relative pathname, don't change the current working -directory between resumptions of \function{walk()}. \function{walk()} -never changes the current directory, and assumes that its caller -doesn't either. -\end{notice} - -This example displays the number of bytes taken by non-directory files -in each directory under the starting directory, except that it doesn't -look under any CVS subdirectory: - -\begin{verbatim} -import os -from os.path import join, getsize -for root, dirs, files in os.walk('python/Lib/email'): - print root, "consumes", - print sum(getsize(join(root, name)) for name in files), - print "bytes in", len(files), "non-directory files" - if 'CVS' in dirs: - dirs.remove('CVS') # don't visit CVS directories -\end{verbatim} - -In the next example, walking the tree bottom up is essential: -\function{rmdir()} doesn't allow deleting a directory before the -directory is empty: - -\begin{verbatim} -# Delete everything reachable from the directory named in 'top', -# assuming there are no symbolic links. -# CAUTION: This is dangerous! For example, if top == '/', it -# could delete all your disk files. -import os -for root, dirs, files in os.walk(top, topdown=False): - for name in files: - os.remove(os.path.join(root, name)) - for name in dirs: - os.rmdir(os.path.join(root, name)) -\end{verbatim} - -\versionadded{2.3} -\end{funcdesc} - -\subsection{Process Management \label{os-process}} - -These functions may be used to create and manage processes. - -The various \function{exec*()} functions take a list of arguments for -the new program loaded into the process. In each case, the first of -these arguments is passed to the new program as its own name rather -than as an argument a user may have typed on a command line. For the -C programmer, this is the \code{argv[0]} passed to a program's -\cfunction{main()}. For example, \samp{os.execv('/bin/echo', ['foo', -'bar'])} will only print \samp{bar} on standard output; \samp{foo} -will seem to be ignored. - - -\begin{funcdesc}{abort}{} -Generate a \constant{SIGABRT} signal to the current process. On -\UNIX, the default behavior is to produce a core dump; on Windows, the -process immediately returns an exit code of \code{3}. Be aware that -programs which use \function{signal.signal()} to register a handler -for \constant{SIGABRT} will behave differently. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{execl}{path, arg0, arg1, \moreargs} -\funcline{execle}{path, arg0, arg1, \moreargs, env} -\funcline{execlp}{file, arg0, arg1, \moreargs} -\funcline{execlpe}{file, arg0, arg1, \moreargs, env} -\funcline{execv}{path, args} -\funcline{execve}{path, args, env} -\funcline{execvp}{file, args} -\funcline{execvpe}{file, args, env} -These functions all execute a new program, replacing the current -process; they do not return. On \UNIX, the new executable is loaded -into the current process, and will have the same process ID as the -caller. Errors will be reported as \exception{OSError} exceptions. - -The \character{l} and \character{v} variants of the -\function{exec*()} functions differ in how command-line arguments are -passed. The \character{l} variants are perhaps the easiest to work -with if the number of parameters is fixed when the code is written; -the individual parameters simply become additional parameters to the -\function{execl*()} functions. The \character{v} variants are good -when the number of parameters is variable, with the arguments being -passed in a list or tuple as the \var{args} parameter. In either -case, the arguments to the child process should start with the name of -the command being run, but this is not enforced. - -The variants which include a \character{p} near the end -(\function{execlp()}, \function{execlpe()}, \function{execvp()}, -and \function{execvpe()}) will use the \envvar{PATH} environment -variable to locate the program \var{file}. When the environment is -being replaced (using one of the \function{exec*e()} variants, -discussed in the next paragraph), the -new environment is used as the source of the \envvar{PATH} variable. -The other variants, \function{execl()}, \function{execle()}, -\function{execv()}, and \function{execve()}, will not use the -\envvar{PATH} variable to locate the executable; \var{path} must -contain an appropriate absolute or relative path. - -For \function{execle()}, \function{execlpe()}, \function{execve()}, -and \function{execvpe()} (note that these all end in \character{e}), -the \var{env} parameter must be a mapping which is used to define the -environment variables for the new process; the \function{execl()}, -\function{execlp()}, \function{execv()}, and \function{execvp()} -all cause the new process to inherit the environment of the current -process. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{_exit}{n} -Exit to the system with status \var{n}, without calling cleanup -handlers, flushing stdio buffers, etc. -Availability: Macintosh, \UNIX, Windows. - -\begin{notice} -The standard way to exit is \code{sys.exit(\var{n})}. -\function{_exit()} should normally only be used in the child process -after a \function{fork()}. -\end{notice} -\end{funcdesc} - -The following exit codes are a defined, and can be used with -\function{_exit()}, although they are not required. These are -typically used for system programs written in Python, such as a -mail server's external command delivery program. -\note{Some of these may not be available on all \UNIX{} platforms, -since there is some variation. These constants are defined where they -are defined by the underlying platform.} - -\begin{datadesc}{EX_OK} -Exit code that means no error occurred. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_USAGE} -Exit code that means the command was used incorrectly, such as when -the wrong number of arguments are given. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_DATAERR} -Exit code that means the input data was incorrect. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_NOINPUT} -Exit code that means an input file did not exist or was not readable. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_NOUSER} -Exit code that means a specified user did not exist. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_NOHOST} -Exit code that means a specified host did not exist. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_UNAVAILABLE} -Exit code that means that a required service is unavailable. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_SOFTWARE} -Exit code that means an internal software error was detected. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_OSERR} -Exit code that means an operating system error was detected, such as -the inability to fork or create a pipe. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_OSFILE} -Exit code that means some system file did not exist, could not be -opened, or had some other kind of error. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_CANTCREAT} -Exit code that means a user specified output file could not be created. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_IOERR} -Exit code that means that an error occurred while doing I/O on some file. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_TEMPFAIL} -Exit code that means a temporary failure occurred. This indicates -something that may not really be an error, such as a network -connection that couldn't be made during a retryable operation. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_PROTOCOL} -Exit code that means that a protocol exchange was illegal, invalid, or -not understood. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_NOPERM} -Exit code that means that there were insufficient permissions to -perform the operation (but not intended for file system problems). -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_CONFIG} -Exit code that means that some kind of configuration error occurred. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{EX_NOTFOUND} -Exit code that means something like ``an entry was not found''. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -\begin{funcdesc}{fork}{} -Fork a child process. Return \code{0} in the child, the child's -process id in the parent. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{forkpty}{} -Fork a child process, using a new pseudo-terminal as the child's -controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})}, -where \var{pid} is \code{0} in the child, the new child's process id -in the parent, and \var{fd} is the file descriptor of the master end -of the pseudo-terminal. For a more portable approach, use the -\refmodule{pty} module. -Availability: Macintosh, Some flavors of \UNIX. -\end{funcdesc} - -\begin{funcdesc}{kill}{pid, sig} -\index{process!killing} -\index{process!signalling} -Send signal \var{sig} to the process \var{pid}. Constants for the -specific signals available on the host platform are defined in the -\refmodule{signal} module. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{killpg}{pgid, sig} -\index{process!killing} -\index{process!signalling} -Send the signal \var{sig} to the process group \var{pgid}. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{nice}{increment} -Add \var{increment} to the process's ``niceness''. Return the new -niceness. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{plock}{op} -Lock program segments into memory. The value of \var{op} -(defined in \code{<sys/lock.h>}) determines which segments are locked. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdescni}{popen}{\unspecified} -Run child processes, returning opened pipes for communications. These -functions are described in section \ref{os-newstreams}. -\end{funcdescni} - -\begin{funcdesc}{spawnl}{mode, path, \moreargs} -\funcline{spawnle}{mode, path, \moreargs, env} -\funcline{spawnlp}{mode, file, \moreargs} -\funcline{spawnlpe}{mode, file, \moreargs, env} -\funcline{spawnv}{mode, path, args} -\funcline{spawnve}{mode, path, args, env} -\funcline{spawnvp}{mode, file, args} -\funcline{spawnvpe}{mode, file, args, env} -Execute the program \var{path} in a new process. - -(Note that the \module{subprocess} module provides more powerful -facilities for spawning new processes and retrieving their results; -using that module is preferable to using these functions.) - -If \var{mode} is -\constant{P_NOWAIT}, this function returns the process ID of the new -process; if \var{mode} is \constant{P_WAIT}, returns the process's -exit code if it exits normally, or \code{-\var{signal}}, where -\var{signal} is the signal that killed the process. On Windows, the -process ID will actually be the process handle, so can be used with -the \function{waitpid()} function. - -The \character{l} and \character{v} variants of the -\function{spawn*()} functions differ in how command-line arguments are -passed. The \character{l} variants are perhaps the easiest to work -with if the number of parameters is fixed when the code is written; -the individual parameters simply become additional parameters to the -\function{spawnl*()} functions. The \character{v} variants are good -when the number of parameters is variable, with the arguments being -passed in a list or tuple as the \var{args} parameter. In either -case, the arguments to the child process must start with the name of -the command being run. - -The variants which include a second \character{p} near the end -(\function{spawnlp()}, \function{spawnlpe()}, \function{spawnvp()}, -and \function{spawnvpe()}) will use the \envvar{PATH} environment -variable to locate the program \var{file}. When the environment is -being replaced (using one of the \function{spawn*e()} variants, -discussed in the next paragraph), the new environment is used as the -source of the \envvar{PATH} variable. The other variants, -\function{spawnl()}, \function{spawnle()}, \function{spawnv()}, and -\function{spawnve()}, will not use the \envvar{PATH} variable to -locate the executable; \var{path} must contain an appropriate absolute -or relative path. - -For \function{spawnle()}, \function{spawnlpe()}, \function{spawnve()}, -and \function{spawnvpe()} (note that these all end in \character{e}), -the \var{env} parameter must be a mapping which is used to define the -environment variables for the new process; the \function{spawnl()}, -\function{spawnlp()}, \function{spawnv()}, and \function{spawnvp()} -all cause the new process to inherit the environment of the current -process. - -As an example, the following calls to \function{spawnlp()} and -\function{spawnvpe()} are equivalent: - -\begin{verbatim} -import os -os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null') - -L = ['cp', 'index.html', '/dev/null'] -os.spawnvpe(os.P_WAIT, 'cp', L, os.environ) -\end{verbatim} - -Availability: \UNIX, Windows. \function{spawnlp()}, -\function{spawnlpe()}, \function{spawnvp()} and \function{spawnvpe()} -are not available on Windows. -\versionadded{1.6} -\end{funcdesc} - -\begin{datadesc}{P_NOWAIT} -\dataline{P_NOWAITO} -Possible values for the \var{mode} parameter to the \function{spawn*()} -family of functions. If either of these values is given, the -\function{spawn*()} functions will return as soon as the new process -has been created, with the process ID as the return value. -Availability: Macintosh, \UNIX, Windows. -\versionadded{1.6} -\end{datadesc} - -\begin{datadesc}{P_WAIT} -Possible value for the \var{mode} parameter to the \function{spawn*()} -family of functions. If this is given as \var{mode}, the -\function{spawn*()} functions will not return until the new process -has run to completion and will return the exit code of the process the -run is successful, or \code{-\var{signal}} if a signal kills the -process. -Availability: Macintosh, \UNIX, Windows. -\versionadded{1.6} -\end{datadesc} - -\begin{datadesc}{P_DETACH} -\dataline{P_OVERLAY} -Possible values for the \var{mode} parameter to the -\function{spawn*()} family of functions. These are less portable than -those listed above. -\constant{P_DETACH} is similar to \constant{P_NOWAIT}, but the new -process is detached from the console of the calling process. -If \constant{P_OVERLAY} is used, the current process will be replaced; -the \function{spawn*()} function will not return. -Availability: Windows. -\versionadded{1.6} -\end{datadesc} - -\begin{funcdesc}{startfile}{path\optional{, operation}} -Start a file with its associated application. - -When \var{operation} is not specified or \code{'open'}, this acts like -double-clicking the file in Windows Explorer, or giving the file name -as an argument to the \program{start} command from the interactive -command shell: the file is opened with whatever application (if any) -its extension is associated. - -When another \var{operation} is given, it must be a ``command verb'' -that specifies what should be done with the file. -Common verbs documented by Microsoft are \code{'print'} and -\code{'edit'} (to be used on files) as well as \code{'explore'} and -\code{'find'} (to be used on directories). - -\function{startfile()} returns as soon as the associated application -is launched. There is no option to wait for the application to close, -and no way to retrieve the application's exit status. The \var{path} -parameter is relative to the current directory. If you want to use an -absolute path, make sure the first character is not a slash -(\character{/}); the underlying Win32 \cfunction{ShellExecute()} -function doesn't work if it is. Use the \function{os.path.normpath()} -function to ensure that the path is properly encoded for Win32. -Availability: Windows. -\versionadded{2.0} -\versionadded[The \var{operation} parameter]{2.5} -\end{funcdesc} - -\begin{funcdesc}{system}{command} -Execute the command (a string) in a subshell. This is implemented by -calling the Standard C function \cfunction{system()}, and has the -same limitations. Changes to \code{posix.environ}, \code{sys.stdin}, -etc.\ are not reflected in the environment of the executed command. - -On \UNIX, the return value is the exit status of the process encoded in the -format specified for \function{wait()}. Note that \POSIX{} does not -specify the meaning of the return value of the C \cfunction{system()} -function, so the return value of the Python function is system-dependent. - -On Windows, the return value is that returned by the system shell after -running \var{command}, given by the Windows environment variable -\envvar{COMSPEC}: on \program{command.com} systems (Windows 95, 98 and ME) -this is always \code{0}; on \program{cmd.exe} systems (Windows NT, 2000 -and XP) this is the exit status of the command run; on systems using -a non-native shell, consult your shell documentation. - -Availability: Macintosh, \UNIX, Windows. - -The \module{subprocess} module provides more powerful facilities for -spawning new processes and retrieving their results; using that module -is preferable to using this function. -\end{funcdesc} - -\begin{funcdesc}{times}{} -Return a 5-tuple of floating point numbers indicating accumulated -(processor or other) -times, in seconds. The items are: user time, system time, children's -user time, children's system time, and elapsed real time since a fixed -point in the past, in that order. See the \UNIX{} manual page -\manpage{times}{2} or the corresponding Windows Platform API -documentation. -Availability: Macintosh, \UNIX, Windows. -\end{funcdesc} - -\begin{funcdesc}{wait}{} -Wait for completion of a child process, and return a tuple containing -its pid and exit status indication: a 16-bit number, whose low byte is -the signal number that killed the process, and whose high byte is the -exit status (if the signal number is zero); the high bit of the low -byte is set if a core file was produced. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{waitpid}{pid, options} -The details of this function differ on \UNIX{} and Windows. - -On \UNIX: -Wait for completion of a child process given by process id \var{pid}, -and return a tuple containing its process id and exit status -indication (encoded as for \function{wait()}). The semantics of the -call are affected by the value of the integer \var{options}, which -should be \code{0} for normal operation. - -If \var{pid} is greater than \code{0}, \function{waitpid()} requests -status information for that specific process. If \var{pid} is -\code{0}, the request is for the status of any child in the process -group of the current process. If \var{pid} is \code{-1}, the request -pertains to any child of the current process. If \var{pid} is less -than \code{-1}, status is requested for any process in the process -group \code{-\var{pid}} (the absolute value of \var{pid}). - -On Windows: -Wait for completion of a process given by process handle \var{pid}, -and return a tuple containing \var{pid}, -and its exit status shifted left by 8 bits (shifting makes cross-platform -use of the function easier). -A \var{pid} less than or equal to \code{0} has no special meaning on -Windows, and raises an exception. -The value of integer \var{options} has no effect. -\var{pid} can refer to any process whose id is known, not necessarily a -child process. -The \function{spawn()} functions called with \constant{P_NOWAIT} -return suitable process handles. -\end{funcdesc} - -\begin{funcdesc}{wait3}{\optional{options}} -Similar to \function{waitpid()}, except no process id argument is given and -a 3-element tuple containing the child's process id, exit status indication, -and resource usage information is returned. Refer to -\module{resource}.\function{getrusage()} -for details on resource usage information. The option argument is the same -as that provided to \function{waitpid()} and \function{wait4()}. -Availability: \UNIX. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{wait4}{pid, options} -Similar to \function{waitpid()}, except a 3-element tuple, containing the -child's process id, exit status indication, and resource usage information -is returned. Refer to \module{resource}.\function{getrusage()} for details -on resource usage information. The arguments to \function{wait4()} are -the same as those provided to \function{waitpid()}. -Availability: \UNIX. -\versionadded{2.5} -\end{funcdesc} - -\begin{datadesc}{WNOHANG} -The option for \function{waitpid()} to return immediately if no child -process status is available immediately. The function returns -\code{(0, 0)} in this case. -Availability: Macintosh, \UNIX. -\end{datadesc} - -\begin{datadesc}{WCONTINUED} -This option causes child processes to be reported if they have been -continued from a job control stop since their status was last -reported. -Availability: Some \UNIX{} systems. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{WUNTRACED} -This option causes child processes to be reported if they have been -stopped but their current state has not been reported since they were -stopped. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{datadesc} - -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}{WCOREDUMP}{status} -Returns \code{True} if a core dump was generated for the process, -otherwise it returns \code{False}. -Availability: Macintosh, \UNIX. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{WIFCONTINUED}{status} -Returns \code{True} if the process has been continued from a job -control stop, otherwise it returns \code{False}. -Availability: \UNIX. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{WIFSTOPPED}{status} -Returns \code{True} if the process has been stopped, otherwise it -returns \code{False}. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{WIFSIGNALED}{status} -Returns \code{True} if the process exited due to a signal, otherwise -it returns \code{False}. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{WIFEXITED}{status} -Returns \code{True} if the process exited using the \manpage{exit}{2} -system call, otherwise it returns \code{False}. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{WEXITSTATUS}{status} -If \code{WIFEXITED(\var{status})} is true, return the integer -parameter to the \manpage{exit}{2} system call. Otherwise, the return -value is meaningless. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{WSTOPSIG}{status} -Return the signal which caused the process to stop. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{WTERMSIG}{status} -Return the signal which caused the process to exit. -Availability: Macintosh, \UNIX. -\end{funcdesc} - - -\subsection{Miscellaneous System Information \label{os-path}} - - -\begin{funcdesc}{confstr}{name} -Return string-valued system configuration values. -\var{name} specifies the configuration value to retrieve; it may be a -string which is the name of a defined system value; these names are -specified in a number of standards (\POSIX, \UNIX{} 95, \UNIX{} 98, and -others). Some platforms define additional names as well. The names -known to the host operating system are given as the keys of the -\code{confstr_names} dictionary. For configuration variables not -included in that mapping, passing an integer for \var{name} is also -accepted. -Availability: Macintosh, \UNIX. - -If the configuration value specified by \var{name} isn't defined, -\code{None} is returned. - -If \var{name} is a string and is not known, \exception{ValueError} is -raised. If a specific value for \var{name} is not supported by the -host system, even if it is included in \code{confstr_names}, an -\exception{OSError} is raised with \constant{errno.EINVAL} for the -error number. -\end{funcdesc} - -\begin{datadesc}{confstr_names} -Dictionary mapping names accepted by \function{confstr()} to the -integer values defined for those names by the host operating system. -This can be used to determine the set of names known to the system. -Availability: Macintosh, \UNIX. -\end{datadesc} - -\begin{funcdesc}{getloadavg}{} -Return the number of processes in the system run queue averaged over -the last 1, 5, and 15 minutes or raises \exception{OSError} if the load -average was unobtainable. - -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{sysconf}{name} -Return integer-valued system configuration values. -If the configuration value specified by \var{name} isn't defined, -\code{-1} is returned. The comments regarding the \var{name} -parameter for \function{confstr()} apply here as well; the dictionary -that provides information on the known names is given by -\code{sysconf_names}. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{datadesc}{sysconf_names} -Dictionary mapping names accepted by \function{sysconf()} to the -integer values defined for those names by the host operating system. -This can be used to determine the set of names known to the system. -Availability: Macintosh, \UNIX. -\end{datadesc} - - -The follow data values are used to support path manipulation -operations. These are defined for all platforms. - -Higher-level operations on pathnames are defined in the -\refmodule{os.path} module. - - -\begin{datadesc}{curdir} -The constant string used by the operating system to refer to the current -directory. -For example: \code{'.'} for \POSIX{} or \code{':'} for Mac OS 9. -Also available via \module{os.path}. -\end{datadesc} - -\begin{datadesc}{pardir} -The constant string used by the operating system to refer to the parent -directory. -For example: \code{'..'} for \POSIX{} or \code{'::'} for Mac OS 9. -Also available via \module{os.path}. -\end{datadesc} - -\begin{datadesc}{sep} -The character used by the operating system to separate pathname components, -for example, \character{/} for \POSIX{} or \character{:} for -Mac OS 9. Note that knowing this is not sufficient to be able to -parse or concatenate pathnames --- use \function{os.path.split()} and -\function{os.path.join()} --- but it is occasionally useful. -Also available via \module{os.path}. -\end{datadesc} - -\begin{datadesc}{altsep} -An alternative character used by the operating system to separate pathname -components, or \code{None} if only one separator character exists. This is -set to \character{/} on Windows systems where \code{sep} is a -backslash. -Also available via \module{os.path}. -\end{datadesc} - -\begin{datadesc}{extsep} -The character which separates the base filename from the extension; -for example, the \character{.} in \file{os.py}. -Also available via \module{os.path}. -\versionadded{2.2} -\end{datadesc} - -\begin{datadesc}{pathsep} -The character conventionally used by the operating system to separate -search path components (as in \envvar{PATH}), such as \character{:} for -\POSIX{} or \character{;} for Windows. -Also available via \module{os.path}. -\end{datadesc} - -\begin{datadesc}{defpath} -The default search path used by \function{exec*p*()} and -\function{spawn*p*()} if the environment doesn't have a \code{'PATH'} -key. -Also available via \module{os.path}. -\end{datadesc} - -\begin{datadesc}{linesep} -The string used to separate (or, rather, terminate) lines on the -current platform. This may be a single character, such as -\code{'\e n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple -characters, for example, \code{'\e r\e n'} for Windows. -Do not use \var{os.linesep} as a line terminator when writing files -opened in text mode (the default); use a single \code{'\e n'} instead, -on all platforms. -\end{datadesc} - -\begin{datadesc}{devnull} -The file path of the null device. -For example: \code{'/dev/null'} for \POSIX{} or \code{'Dev:Nul'} for -Mac OS 9. -Also available via \module{os.path}. -\versionadded{2.4} -\end{datadesc} - - -\subsection{Miscellaneous Functions \label{os-miscfunc}} - -\begin{funcdesc}{urandom}{n} -Return a string of \var{n} random bytes suitable for cryptographic use. - -This function returns random bytes from an OS-specific -randomness source. The returned data should be unpredictable enough for -cryptographic applications, though its exact quality depends on the OS -implementation. On a UNIX-like system this will query /dev/urandom, and -on Windows it will use CryptGenRandom. If a randomness source is not -found, \exception{NotImplementedError} will be raised. -\versionadded{2.4} -\end{funcdesc} - - - - diff --git a/Doc/lib/libossaudiodev.tex b/Doc/lib/libossaudiodev.tex deleted file mode 100644 index 4c19aaf..0000000 --- a/Doc/lib/libossaudiodev.tex +++ /dev/null @@ -1,401 +0,0 @@ -\section{\module{ossaudiodev} --- - Access to OSS-compatible audio devices} - -\declaremodule{builtin}{ossaudiodev} -\platform{Linux, FreeBSD} -\modulesynopsis{Access to OSS-compatible audio devices.} - -\versionadded{2.3} - -This module allows you to access the OSS (Open Sound System) audio -interface. OSS is available for a wide range of open-source and -commercial Unices, and is the standard audio interface for Linux and -recent versions of FreeBSD. - -% Things will get more complicated for future Linux versions, since -% ALSA is in the standard kernel as of 2.5.x. Presumably if you -% use ALSA, you'll have to make sure its OSS compatibility layer -% is active to use ossaudiodev, but you're gonna need it for the vast -% majority of Linux audio apps anyways. -% -% Sounds like things are also complicated for other BSDs. In response -% to my python-dev query, Thomas Wouters said: -% -% > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial -% > OSS installation manual tells you to remove references to OSS/Free from the -% > kernel :) -% -% but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes -% from its <soundcard.h>: -% > * WARNING! WARNING! -% > * This is an OSS (Linux) audio emulator. -% > * Use the Native NetBSD API for developing new code, and this -% > * only for compiling Linux programs. -% -% There's also an ossaudio manpage on OpenBSD that explains things -% further. Presumably NetBSD and OpenBSD have a different standard -% audio interface. That's the great thing about standards, there are so -% many to choose from ... ;-) -% -% This probably all warrants a footnote or two, but I don't understand -% things well enough right now to write it! --GPW - -\begin{seealso} -\seetitle[http://www.opensound.com/pguide/oss.pdf] - {Open Sound System Programmer's Guide} {the official - documentation for the OSS C API} -\seetext{The module defines a large number of constants supplied by - the OSS device driver; see \code{<sys/soundcard.h>} on either - Linux or FreeBSD for a listing .} -\end{seealso} - -\module{ossaudiodev} defines the following variables and functions: - -\begin{excdesc}{OSSAudioError} -This exception is raised on certain errors. The argument is a string -describing what went wrong. - -(If \module{ossaudiodev} receives an error from a system call such as -\cfunction{open()}, \cfunction{write()}, or \cfunction{ioctl()}, it -raises \exception{IOError}. Errors detected directly by -\module{ossaudiodev} result in \exception{OSSAudioError}.) - -(For backwards compatibility, the exception class is also available as -\code{ossaudiodev.error}.) -\end{excdesc} - -\begin{funcdesc}{open}{\optional{device, }mode} -Open an audio device and return an OSS audio device object. This -object supports many file-like methods, such as \method{read()}, -\method{write()}, and \method{fileno()} (although there are subtle -differences between conventional \UNIX{} read/write semantics and those of -OSS audio devices). It also supports a number of audio-specific -methods; see below for the complete list of methods. - -\var{device} is the audio device filename to use. If it is not -specified, this module first looks in the environment variable -\envvar{AUDIODEV} for a device to use. If not found, it falls back to -\file{/dev/dsp}. - -\var{mode} is one of \code{'r'} for read-only (record) access, -\code{'w'} for write-only (playback) access and \code{'rw'} for both. -Since many sound cards only allow one process to have the recorder or -player open at a time, it is a good idea to open the device only for the -activity needed. Further, some sound cards are half-duplex: they can be -opened for reading or writing, but not both at once. - -Note the unusual calling syntax: the \emph{first} argument is optional, -and the second is required. This is a historical artifact for -compatibility with the older \module{linuxaudiodev} module which -\module{ossaudiodev} supersedes. % XXX it might also be motivated -% by my unfounded-but-still-possibly-true belief that the default -% audio device varies unpredictably across operating systems. -GW -\end{funcdesc} - -\begin{funcdesc}{openmixer}{\optional{device}} -Open a mixer device and return an OSS mixer device object. -\var{device} is the mixer device filename to use. If it is -not specified, this module first looks in the environment variable -\envvar{MIXERDEV} for a device to use. If not found, it falls back to -\file{/dev/mixer}. - -\end{funcdesc} - -\subsection{Audio Device Objects \label{ossaudio-device-objects}} - -Before you can write to or read from an audio device, you must call -three methods in the correct order: -\begin{enumerate} -\item \method{setfmt()} to set the output format -\item \method{channels()} to set the number of channels -\item \method{speed()} to set the sample rate -\end{enumerate} -Alternately, you can use the \method{setparameters()} method to set all -three audio parameters at once. This is more convenient, but may not be -as flexible in all cases. - -The audio device objects returned by \function{open()} define the -following methods and (read-only) attributes: - -\begin{methoddesc}[audio device]{close}{} -Explicitly close the audio device. When you are done writing to or -reading from an audio device, you should explicitly close it. A closed -device cannot be used again. -\end{methoddesc} - -\begin{methoddesc}[audio device]{fileno}{} -Return the file descriptor associated with the device. -\end{methoddesc} - -\begin{methoddesc}[audio device]{read}{size} -Read \var{size} bytes from the audio input and return them as a Python -string. Unlike most \UNIX{} device drivers, OSS audio devices in -blocking mode (the default) will block \function{read()} until the -entire requested amount of data is available. -\end{methoddesc} - -\begin{methoddesc}[audio device]{write}{data} -Write the Python string \var{data} to the audio device and return the -number of bytes written. If the audio device is in blocking mode (the -default), the entire string is always written (again, this is different -from usual \UNIX{} device semantics). If the device is in non-blocking -mode, some data may not be written---see \method{writeall()}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{writeall}{data} -Write the entire Python string \var{data} to the audio device: waits -until the audio device is able to accept data, writes as much data as it -will accept, and repeats until \var{data} has been completely written. -If the device is in blocking mode (the default), this has the same -effect as \method{write()}; \method{writeall()} is only useful in -non-blocking mode. Has no return value, since the amount of data -written is always equal to the amount of data supplied. -\end{methoddesc} - -The following methods each map to exactly one -\function{ioctl()} system call. The correspondence is obvious: for -example, \method{setfmt()} corresponds to the \code{SNDCTL_DSP_SETFMT} -ioctl, and \method{sync()} to \code{SNDCTL_DSP_SYNC} (this can be useful -when consulting the OSS documentation). If the underlying -\function{ioctl()} fails, they all raise \exception{IOError}. - -\begin{methoddesc}[audio device]{nonblock}{} -Put the device into non-blocking mode. Once in non-blocking mode, there -is no way to return it to blocking mode. -\end{methoddesc} - -\begin{methoddesc}[audio device]{getfmts}{} -Return a bitmask of the audio output formats supported by the -soundcard. Some of the formats supported by OSS are: - -\begin{tableii}{l|l}{constant}{Format}{Description} -\lineii{AFMT_MU_LAW} - {a logarithmic encoding (used by Sun \code{.au} files and - \filenq{/dev/audio})} -\lineii{AFMT_A_LAW} - {a logarithmic encoding} -\lineii{AFMT_IMA_ADPCM} - {a 4:1 compressed format defined by the Interactive Multimedia - Association} -\lineii{AFMT_U8} - {Unsigned, 8-bit audio} -\lineii{AFMT_S16_LE} - {Signed, 16-bit audio, little-endian byte order (as used by - Intel processors)} -\lineii{AFMT_S16_BE} - {Signed, 16-bit audio, big-endian byte order (as used by 68k, - PowerPC, Sparc)} -\lineii{AFMT_S8} - {Signed, 8 bit audio} -\lineii{AFMT_U16_LE} - {Unsigned, 16-bit little-endian audio} -\lineii{AFMT_U16_BE} - {Unsigned, 16-bit big-endian audio} -\end{tableii} -Consult the OSS documentation for a full list of audio formats, and note -that most devices support only a subset of these formats. Some older -devices only support \constant{AFMT_U8}; the most common format used -today is \constant{AFMT_S16_LE}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{setfmt}{format} -Try to set the current audio format to \var{format}---see -\method{getfmts()} for a list. Returns the audio format that the device -was set to, which may not be the requested format. May also be used to -return the current audio format---do this by passing an ``audio format'' -of -\constant{AFMT_QUERY}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{channels}{nchannels} -Set the number of output channels to \var{nchannels}. A value of 1 -indicates monophonic sound, 2 stereophonic. Some devices may have more -than 2 channels, and some high-end devices may not support mono. -Returns the number of channels the device was set to. -\end{methoddesc} - -\begin{methoddesc}[audio device]{speed}{samplerate} -Try to set the audio sampling rate to \var{samplerate} samples per -second. Returns the rate actually set. Most sound devices don't -support arbitrary sampling rates. Common rates are: -\begin{tableii}{l|l}{textrm}{Rate}{Description} -\lineii{8000}{default rate for \filenq{/dev/audio}} -\lineii{11025}{speech recording} -\lineii{22050}{} -\lineii{44100}{CD quality audio (at 16 bits/sample and 2 channels)} -\lineii{96000}{DVD quality audio (at 24 bits/sample)} -\end{tableii} -\end{methoddesc} - -\begin{methoddesc}[audio device]{sync}{} -Wait until the sound device has played every byte in its buffer. (This -happens implicitly when the device is closed.) The OSS documentation -recommends closing and re-opening the device rather than using -\method{sync()}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{reset}{} -Immediately stop playing or recording and return the device to a -state where it can accept commands. The OSS documentation recommends -closing and re-opening the device after calling \method{reset()}. -\end{methoddesc} - -\begin{methoddesc}[audio device]{post}{} -Tell the driver that there is likely to be a pause in the output, making -it possible for the device to handle the pause more intelligently. You -might use this after playing a spot sound effect, before waiting for -user input, or before doing disk I/O. -\end{methoddesc} - -The following convenience methods combine several ioctls, or one ioctl -and some simple calculations. - -\begin{methoddesc}[audio device]{setparameters} - {format, nchannels, samplerate \optional{, strict=False}} - -Set the key audio sampling parameters---sample format, number of -channels, and sampling rate---in one method call. \var{format}, -\var{nchannels}, and \var{samplerate} should be as specified in the -\method{setfmt()}, \method{channels()}, and \method{speed()} -methods. If \var{strict} is true, \method{setparameters()} checks to -see if each parameter was actually set to the requested value, and -raises \exception{OSSAudioError} if not. Returns a tuple (\var{format}, -\var{nchannels}, \var{samplerate}) indicating the parameter values that -were actually set by the device driver (i.e., the same as the return -values of \method{setfmt()}, \method{channels()}, and \method{speed()}). - -For example, -\begin{verbatim} - (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate) -\end{verbatim} -is equivalent to -\begin{verbatim} - fmt = dsp.setfmt(fmt) - channels = dsp.channels(channels) - rate = dsp.rate(channels) -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[audio device]{bufsize}{} -Returns the size of the hardware buffer, in samples. -\end{methoddesc} - -\begin{methoddesc}[audio device]{obufcount}{} -Returns the number of samples that are in the hardware buffer yet to be -played. -\end{methoddesc} - -\begin{methoddesc}[audio device]{obuffree}{} -Returns the number of samples that could be queued into the hardware -buffer to be played without blocking. -\end{methoddesc} - -Audio device objects also support several read-only attributes: - -\begin{memberdesc}[audio device]{closed}{} -Boolean indicating whether the device has been closed. -\end{memberdesc} - -\begin{memberdesc}[audio device]{name}{} -String containing the name of the device file. -\end{memberdesc} - -\begin{memberdesc}[audio device]{mode}{} -The I/O mode for the file, either \code{"r"}, \code{"rw"}, or \code{"w"}. -\end{memberdesc} - - -\subsection{Mixer Device Objects \label{mixer-device-objects}} - -The mixer object provides two file-like methods: - -\begin{methoddesc}[mixer device]{close}{} -This method closes the open mixer device file. Any further attempts to -use the mixer after this file is closed will raise an \exception{IOError}. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{fileno}{} -Returns the file handle number of the open mixer device file. -\end{methoddesc} - -The remaining methods are specific to audio mixing: - -\begin{methoddesc}[mixer device]{controls}{} -This method returns a bitmask specifying the available mixer controls -(``Control'' being a specific mixable ``channel'', such as -\constant{SOUND_MIXER_PCM} or \constant{SOUND_MIXER_SYNTH}). This -bitmask indicates a subset of all available mixer controls---the -\constant{SOUND_MIXER_*} constants defined at module level. To determine if, -for example, the current mixer object supports a PCM mixer, use the -following Python code: - -\begin{verbatim} -mixer=ossaudiodev.openmixer() -if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM): - # PCM is supported - ... code ... -\end{verbatim} - -For most purposes, the \constant{SOUND_MIXER_VOLUME} (master volume) and -\constant{SOUND_MIXER_PCM} controls should suffice---but code that uses the -mixer should be flexible when it comes to choosing mixer controls. On -the Gravis Ultrasound, for example, \constant{SOUND_MIXER_VOLUME} does not -exist. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{stereocontrols}{} -Returns a bitmask indicating stereo mixer controls. If a bit is set, -the corresponding control is stereo; if it is unset, the control is -either monophonic or not supported by the mixer (use in combination with -\method{controls()} to determine which). - -See the code example for the \method{controls()} function for an example -of getting data from a bitmask. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{reccontrols}{} -Returns a bitmask specifying the mixer controls that may be used to -record. See the code example for \method{controls()} for an example of -reading from a bitmask. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{get}{control} -Returns the volume of a given mixer control. The returned volume is a -2-tuple \code{(left_volume,right_volume)}. Volumes are specified as -numbers from 0 (silent) to 100 (full volume). If the control is -monophonic, a 2-tuple is still returned, but both volumes are -the same. - -Raises \exception{OSSAudioError} if an invalid control was is specified, -or \exception{IOError} if an unsupported control is specified. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{set}{control, (left, right)} -Sets the volume for a given mixer control to \code{(left,right)}. -\code{left} and \code{right} must be ints and between 0 (silent) and 100 -(full volume). On success, the new volume is returned as a 2-tuple. -Note that this may not be exactly the same as the volume specified, -because of the limited resolution of some soundcard's mixers. - -Raises \exception{OSSAudioError} if an invalid mixer control was -specified, or if the specified volumes were out-of-range. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{get_recsrc}{} -This method returns a bitmask indicating which control(s) are -currently being used as a recording source. -\end{methoddesc} - -\begin{methoddesc}[mixer device]{set_recsrc}{bitmask} -Call this function to specify a recording source. Returns a bitmask -indicating the new recording source (or sources) if successful; raises -\exception{IOError} if an invalid source was specified. To set the current -recording source to the microphone input: - -\begin{verbatim} -mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC) -\end{verbatim} -\end{methoddesc} - - - diff --git a/Doc/lib/libparser.tex b/Doc/lib/libparser.tex deleted file mode 100644 index a993624..0000000 --- a/Doc/lib/libparser.tex +++ /dev/null @@ -1,712 +0,0 @@ -\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 -% of the Python distribution. No fee may be charged for this document -% in any representation, either on paper or electronically. This -% restriction does not affect other elements in a distributed package -% in any way. - -\declaremodule{builtin}{parser} -\modulesynopsis{Access parse trees for Python source code.} -\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -\index{parsing!Python source code} - -The \module{parser} module provides an interface to Python's internal -parser and byte-code compiler. The primary purpose for this interface -is to allow Python code to edit the parse tree of a Python expression -and create executable code from this. This is better than trying -to parse and modify an arbitrary Python code fragment as a string -because parsing is performed in a manner identical to the code -forming the application. It is also faster. - -There are a few things to note about this module which are important -to making use of the data structures created. This is not a tutorial -on editing the parse trees for Python code, but some examples of using -the \module{parser} module are presented. - -Most importantly, a good understanding of the Python grammar processed -by the internal parser is required. For full information on the -language syntax, refer to the \citetitle[../ref/ref.html]{Python -Language Reference}. The parser itself is created from a grammar -specification defined in the file \file{Grammar/Grammar} in the -standard Python distribution. The parse trees stored in the AST -objects created by this module are the actual output from the internal -parser when created by the \function{expr()} or \function{suite()} -functions, described below. The AST objects created by -\function{sequence2ast()} faithfully simulate those structures. Be -aware that the values of the sequences which are considered -``correct'' will vary from one version of Python to another as the -formal grammar for the language is revised. However, transporting -code from one Python version to another as source text will always -allow correct parse trees to be created in the target version, with -the only restriction being that migrating to an older version of the -interpreter will not support more recent language constructs. The -parse trees are not typically compatible from one version to another, -whereas source code has always been forward-compatible. - -Each element of the sequences returned by \function{ast2list()} or -\function{ast2tuple()} has a simple form. Sequences representing -non-terminal elements in the grammar always have a length greater than -one. The first element is an integer which identifies a production in -the grammar. These integers are given symbolic names in the C header -file \file{Include/graminit.h} and the Python module -\refmodule{symbol}. Each additional element of the sequence represents -a component of the production as recognized in the input string: these -are always sequences which have the same form as the parent. An -important aspect of this structure which should be noted is that -keywords used to identify the parent node type, such as the keyword -\keyword{if} in an \constant{if_stmt}, are included in the node tree without -any special treatment. For example, the \keyword{if} keyword is -represented by the tuple \code{(1, 'if')}, where \code{1} is the -numeric value associated with all \constant{NAME} tokens, including -variable and function names defined by the user. In an alternate form -returned when line number information is requested, the same token -might be represented as \code{(1, 'if', 12)}, where the \code{12} -represents the line number at which the terminal symbol was found. - -Terminal elements are represented in much the same way, but without -any child elements and the addition of the source text which was -identified. The example of the \keyword{if} keyword above is -representative. The various types of terminal symbols are defined in -the C header file \file{Include/token.h} and the Python module -\refmodule{token}. - -The AST objects are not required to support the functionality of this -module, but are provided for three purposes: to allow an application -to amortize the cost of processing complex parse trees, to provide a -parse tree representation which conserves memory space when compared -to the Python list or tuple representation, and to ease the creation -of additional modules in C which manipulate parse trees. A simple -``wrapper'' class may be created in Python to hide the use of AST -objects. - -The \module{parser} module defines functions for a few distinct -purposes. The most important purposes are to create AST objects and -to convert AST objects to other representations such as parse trees -and compiled code objects, but there are also functions which serve to -query the type of parse tree represented by an AST object. - - -\begin{seealso} - \seemodule{symbol}{Useful constants representing internal nodes of - the parse tree.} - \seemodule{token}{Useful constants representing leaf nodes of the - parse tree and functions for testing node values.} -\end{seealso} - - -\subsection{Creating AST Objects \label{Creating ASTs}} - -AST objects may be created from source code or from a parse tree. -When creating an AST object from source, different functions are used -to create the \code{'eval'} and \code{'exec'} forms. - -\begin{funcdesc}{expr}{source} -The \function{expr()} function parses the parameter \var{source} -as if it were an input to \samp{compile(\var{source}, 'file.py', -'eval')}. If the parse succeeds, an AST object is created to hold the -internal parse tree representation, otherwise an appropriate exception -is thrown. -\end{funcdesc} - -\begin{funcdesc}{suite}{source} -The \function{suite()} function parses the parameter \var{source} -as if it were an input to \samp{compile(\var{source}, 'file.py', -'exec')}. If the parse succeeds, an AST object is created to hold the -internal parse tree representation, otherwise an appropriate exception -is thrown. -\end{funcdesc} - -\begin{funcdesc}{sequence2ast}{sequence} -This function accepts a parse tree represented as a sequence and -builds an internal representation if possible. If it can validate -that the tree conforms to the Python grammar and all nodes are valid -node types in the host version of Python, an AST object is created -from the internal representation and returned to the called. If there -is a problem creating the internal representation, or if the tree -cannot be validated, a \exception{ParserError} exception is thrown. An AST -object created this way should not be assumed to compile correctly; -normal exceptions thrown by compilation may still be initiated when -the AST object is passed to \function{compileast()}. This may indicate -problems not related to syntax (such as a \exception{MemoryError} -exception), but may also be due to constructs such as the result of -parsing \code{del f(0)}, which escapes the Python parser but is -checked by the bytecode compiler. - -Sequences representing terminal tokens may be represented as either -two-element lists of the form \code{(1, 'name')} or as three-element -lists of the form \code{(1, 'name', 56)}. If the third element is -present, it is assumed to be a valid line number. The line number -may be specified for any subset of the terminal symbols in the input -tree. -\end{funcdesc} - -\begin{funcdesc}{tuple2ast}{sequence} -This is the same function as \function{sequence2ast()}. This entry point -is maintained for backward compatibility. -\end{funcdesc} - - -\subsection{Converting AST Objects \label{Converting ASTs}} - -AST objects, regardless of the input used to create them, may be -converted to parse trees represented as list- or tuple- trees, or may -be compiled into executable code objects. Parse trees may be -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 -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 -inspection, \function{ast2tuple()} should be used instead to reduce memory -consumption and fragmentation. When the list representation is -required, this function is significantly faster than retrieving a -tuple representation and converting that to nested lists. - -If \var{line_info} is true, line number information will be -included for all terminal tokens as a third element of the list -representing the token. Note that the line number provided specifies -the line on which the token \emph{ends}. This information is -omitted if the flag is false or omitted. -\end{funcdesc} - -\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 -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 -included for all terminal tokens as a third element of the list -representing the token. This information is omitted if the flag is -false or omitted. -\end{funcdesc} - -\begin{funcdesc}{compileast}{ast\optional{, filename\code{ = '<ast>'}}} -The Python byte compiler can be invoked on an AST object to produce -code objects which can be used as part of a call to the built-in -\function{exec()}\bifuncindex{exec} or \function{eval()} -\bifuncindex{eval} functions. -This function provides the interface to the compiler, passing the -internal parse tree from \var{ast} to the parser, using the -source file name specified by the \var{filename} parameter. -The default value supplied for \var{filename} indicates that -the source was an AST object. - -Compiling an AST object may result in exceptions related to -compilation; an example would be a \exception{SyntaxError} caused by the -parse tree for \code{del f(0)}: this statement is considered legal -within the formal grammar for Python but is not a legal language -construct. The \exception{SyntaxError} raised for this condition is -actually generated by the Python byte-compiler normally, which is why -it can be raised at this point by the \module{parser} module. Most -causes of compilation failure can be diagnosed programmatically by -inspection of the parse tree. -\end{funcdesc} - - -\subsection{Queries on AST Objects \label{Querying ASTs}} - -Two functions are provided which allow an application to determine if -an AST was created as an expression or a suite. Neither of these -functions can be used to determine if an AST was created from source -code via \function{expr()} or \function{suite()} or from a parse tree -via \function{sequence2ast()}. - -\begin{funcdesc}{isexpr}{ast} -When \var{ast} represents an \code{'eval'} form, this function -returns true, otherwise it returns false. This is useful, since code -objects normally cannot be queried for this information using existing -built-in functions. Note that the code objects created by -\function{compileast()} cannot be queried like this either, and are -identical to those created by the built-in -\function{compile()}\bifuncindex{compile} function. -\end{funcdesc} - - -\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 equivalent -to \samp{not isexpr(\var{ast})}, as additional syntactic fragments may -be supported in the future. -\end{funcdesc} - - -\subsection{Exceptions and Error Handling \label{AST Errors}} - -The parser module defines a single exception, but may also pass other -built-in exceptions from other portions of the Python runtime -environment. See each function for information about the exceptions -it can raise. - -\begin{excdesc}{ParserError} -Exception raised when a failure occurs within the parser module. This -is generally produced for validation failures rather than the built in -\exception{SyntaxError} thrown during normal parsing. -The exception argument is either a string describing the reason of the -failure or a tuple containing a sequence causing the failure from a parse -tree passed to \function{sequence2ast()} and an explanatory string. Calls to -\function{sequence2ast()} need to be able to handle either type of exception, -while calls to other functions in the module will only need to be -aware of the simple string values. -\end{excdesc} - -Note that the functions \function{compileast()}, \function{expr()}, and -\function{suite()} may throw exceptions which are normally thrown by the -parsing and compilation process. These include the built in -exceptions \exception{MemoryError}, \exception{OverflowError}, -\exception{SyntaxError}, and \exception{SystemError}. In these cases, these -exceptions carry all the meaning normally associated with them. Refer -to the descriptions of each function for detailed information. - - -\subsection{AST Objects \label{AST Objects}} - -Ordered and equality comparisons are supported between AST objects. -Pickling of AST objects (using the \refmodule{pickle} module) is also -supported. - -\begin{datadesc}{ASTType} -The type of the objects returned by \function{expr()}, -\function{suite()} and \function{sequence2ast()}. -\end{datadesc} - - -AST objects have the following methods: - - -\begin{methoddesc}[AST]{compile}{\optional{filename}} -Same as \code{compileast(\var{ast}, \var{filename})}. -\end{methoddesc} - -\begin{methoddesc}[AST]{isexpr}{} -Same as \code{isexpr(\var{ast})}. -\end{methoddesc} - -\begin{methoddesc}[AST]{issuite}{} -Same as \code{issuite(\var{ast})}. -\end{methoddesc} - -\begin{methoddesc}[AST]{tolist}{\optional{line_info}} -Same as \code{ast2list(\var{ast}, \var{line_info})}. -\end{methoddesc} - -\begin{methoddesc}[AST]{totuple}{\optional{line_info}} -Same as \code{ast2tuple(\var{ast}, \var{line_info})}. -\end{methoddesc} - - -\subsection{Examples \label{AST Examples}} - -The parser modules allows operations to be performed on the parse tree -of Python source code before the bytecode is generated, and provides -for inspection of the parse tree for information gathering purposes. -Two examples are presented. The simple example demonstrates emulation -of the \function{compile()}\bifuncindex{compile} built-in function and -the complex example shows the use of a parse tree for information -discovery. - -\subsubsection{Emulation of \function{compile()}} - -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 equivalent to the code - -\begin{verbatim} ->>> code = compile('a + 5', 'file.py', 'eval') ->>> a = 5 ->>> eval(code) -10 -\end{verbatim} - -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: - -\begin{verbatim} ->>> import parser ->>> ast = parser.expr('a + 5') ->>> code = ast.compile('file.py') ->>> a = 5 ->>> eval(code) -10 -\end{verbatim} - -An application which needs both AST and code objects can package this -code into readily available functions: - -\begin{verbatim} -import parser - -def load_suite(source_string): - ast = parser.suite(source_string) - return ast, ast.compile() - -def load_expression(source_string): - ast = parser.expr(source_string) - return ast, ast.compile() -\end{verbatim} - -\subsubsection{Information Discovery} - -Some applications benefit from direct access to the parse tree. The -remainder of this section demonstrates how the parse tree provides -access to module documentation defined in -docstrings\index{string!documentation}\index{docstrings} without -requiring that the code being examined be loaded into a running -interpreter via \keyword{import}. This can be very useful for -performing analyses of untrusted code. - -Generally, the example will demonstrate how the parse tree may be -traversed to distill interesting information. Two functions and a set -of classes are developed which provide programmatic access to high -level function and class definitions provided by a module. The -classes extract information from the parse tree and provide access to -the information at a useful semantic level, one function provides a -simple low-level pattern matching capability, and the other function -defines a high-level interface to the classes by handling file -operations on behalf of the caller. All source files mentioned here -which are not part of the Python installation are located in the -\file{Demo/parser/} directory of the distribution. - -The dynamic nature of Python allows the programmer a great deal of -flexibility, but most modules need only a limited measure of this when -defining classes, functions, and methods. In this example, the only -definitions that will be considered are those which are defined in the -top level of their context, e.g., a function defined by a \keyword{def} -statement at column zero of a module, but not a function defined -within a branch of an \keyword{if} ... \keyword{else} construct, though -there are some good reasons for doing so in some situations. Nesting -of definitions will be handled by the code developed in the example. - -To construct the upper-level extraction methods, we need to know what -the parse tree structure looks like and how much of it we actually -need to be concerned about. Python uses a moderately deep parse tree -so there are a large number of intermediate nodes. It is important to -read and understand the formal grammar used by Python. This is -specified in the file \file{Grammar/Grammar} in the distribution. -Consider the simplest case of interest when searching for docstrings: -a module consisting of a docstring and nothing else. (See file -\file{docstring.py}.) - -\begin{verbatim} -"""Some documentation. -""" -\end{verbatim} - -Using the interpreter to take a look at the parse tree, we find a -bewildering mass of numbers and parentheses, with the documentation -buried deep in nested tuples. - -\begin{verbatim} ->>> import parser ->>> import pprint ->>> ast = parser.suite(open('docstring.py').read()) ->>> tup = ast.totuple() ->>> pprint.pprint(tup) -(257, - (264, - (265, - (266, - (267, - (307, - (287, - (288, - (289, - (290, - (292, - (293, - (294, - (295, - (296, - (297, - (298, - (299, - (300, (3, '"""Some documentation.\n"""'))))))))))))))))), - (4, ''))), - (4, ''), - (0, '')) -\end{verbatim} - -The numbers at the first element of each node in the tree are the node -types; they map directly to terminal and non-terminal symbols in the -grammar. Unfortunately, they are represented as integers in the -internal representation, and the Python structures generated do not -change that. However, the \refmodule{symbol} and \refmodule{token} modules -provide symbolic names for the node types and dictionaries which map -from the integers to the symbolic names for the node types. - -In the output presented above, the outermost tuple contains four -elements: the integer \code{257} and three additional tuples. Node -type \code{257} has the symbolic name \constant{file_input}. Each of -these inner tuples contains an integer as the first element; these -integers, \code{264}, \code{4}, and \code{0}, represent the node types -\constant{stmt}, \constant{NEWLINE}, and \constant{ENDMARKER}, -respectively. -Note that these values may change depending on the version of Python -you are using; consult \file{symbol.py} and \file{token.py} for -details of the mapping. It should be fairly clear that the outermost -node is related primarily to the input source rather than the contents -of the file, and may be disregarded for the moment. The \constant{stmt} -node is much more interesting. In particular, all docstrings are -found in subtrees which are formed exactly as this node is formed, -with the only difference being the string itself. The association -between the docstring in a similar tree and the defined entity (class, -function, or module) which it describes is given by the position of -the docstring subtree within the tree defining the described -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 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 -\code{['variable_name']}. A simple recursive function can implement -the pattern matching, returning a Boolean and a dictionary of variable -name to value mappings. (See file \file{example.py}.) - -\begin{verbatim} -from types import ListType, TupleType - -def match(pattern, data, vars=None): - if vars is None: - vars = {} - if type(pattern) is ListType: - vars[pattern[0]] = data - return 1, vars - if type(pattern) is not TupleType: - return (pattern == data), vars - if len(data) != len(pattern): - return 0, vars - for pattern, data in map(None, pattern, data): - same, vars = match(pattern, data, vars) - if not same: - break - return same, vars -\end{verbatim} - -Using this simple representation for syntactic variables and the symbolic -node types, the pattern for the candidate docstring subtrees becomes -fairly readable. (See file \file{example.py}.) - -\begin{verbatim} -import symbol -import token - -DOCSTRING_STMT_PATTERN = ( - symbol.stmt, - (symbol.simple_stmt, - (symbol.small_stmt, - (symbol.expr_stmt, - (symbol.testlist, - (symbol.test, - (symbol.and_test, - (symbol.not_test, - (symbol.comparison, - (symbol.expr, - (symbol.xor_expr, - (symbol.and_expr, - (symbol.shift_expr, - (symbol.arith_expr, - (symbol.term, - (symbol.factor, - (symbol.power, - (symbol.atom, - (token.STRING, ['docstring']) - )))))))))))))))), - (token.NEWLINE, '') - )) -\end{verbatim} - -Using the \function{match()} function with this pattern, extracting the -module docstring from the parse tree created previously is easy: - -\begin{verbatim} ->>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1]) ->>> found -1 ->>> vars -{'docstring': '"""Some documentation.\n"""'} -\end{verbatim} - -Once specific data can be extracted from a location where it is -expected, the question of where information can be expected -needs to be answered. When dealing with docstrings, the answer is -fairly simple: the docstring is the first \constant{stmt} node in a code -block (\constant{file_input} or \constant{suite} node types). A module -consists of a single \constant{file_input} node, and class and function -definitions each contain exactly one \constant{suite} node. Classes and -functions are readily identified as subtrees of code block nodes which -start with \code{(stmt, (compound_stmt, (classdef, ...} or -\code{(stmt, (compound_stmt, (funcdef, ...}. Note that these subtrees -cannot be matched by \function{match()} since it does not support multiple -sibling nodes to match without regard to number. A more elaborate -matching function could be used to overcome this limitation, but this -is sufficient for the example. - -Given the ability to determine whether a statement might be a -docstring and extract the actual string from the statement, some work -needs to be performed to walk the parse tree for an entire module and -extract information about the names defined in each context of the -module and associate any docstrings with the names. The code to -perform this work is not complicated, but bears some explanation. - -The public interface to the classes is straightforward and should -probably be somewhat more flexible. Each ``major'' block of the -module is described by an object providing several methods for inquiry -and a constructor which accepts at least the subtree of the complete -parse tree which it represents. The \class{ModuleInfo} constructor -accepts an optional \var{name} parameter since it cannot -otherwise determine the name of the module. - -The public classes include \class{ClassInfo}, \class{FunctionInfo}, -and \class{ModuleInfo}. All objects provide the -methods \method{get_name()}, \method{get_docstring()}, -\method{get_class_names()}, and \method{get_class_info()}. The -\class{ClassInfo} objects support \method{get_method_names()} and -\method{get_method_info()} while the other classes provide -\method{get_function_names()} and \method{get_function_info()}. - -Within each of the forms of code block that the public classes -represent, most of the required information is in the same form and is -accessed in the same way, with classes having the distinction that -functions defined at the top level are referred to as ``methods.'' -Since the difference in nomenclature reflects a real semantic -distinction from functions defined outside of a class, the -implementation needs to maintain the distinction. -Hence, most of the functionality of the public classes can be -implemented in a common base class, \class{SuiteInfoBase}, with the -accessors for function and method information provided elsewhere. -Note that there is only one class which represents function and method -information; this parallels the use of the \keyword{def} statement to -define both types of elements. - -Most of the accessor functions are declared in \class{SuiteInfoBase} -and do not need to be overridden by subclasses. More importantly, the -extraction of most information from a parse tree is handled through a -method called by the \class{SuiteInfoBase} constructor. The example -code for most of the classes is clear when read alongside the formal -grammar, but the method which recursively creates new information -objects requires further examination. Here is the relevant part of -the \class{SuiteInfoBase} definition from \file{example.py}: - -\begin{verbatim} -class SuiteInfoBase: - _docstring = '' - _name = '' - - def __init__(self, tree = None): - self._class_info = {} - self._function_info = {} - if tree: - self._extract_info(tree) - - def _extract_info(self, tree): - # extract docstring - if len(tree) == 2: - found, vars = match(DOCSTRING_STMT_PATTERN[1], tree[1]) - else: - found, vars = match(DOCSTRING_STMT_PATTERN, tree[3]) - if found: - self._docstring = eval(vars['docstring']) - # discover inner definitions - for node in tree[1:]: - found, vars = match(COMPOUND_STMT_PATTERN, node) - if found: - cstmt = vars['compound'] - if cstmt[0] == symbol.funcdef: - name = cstmt[2][1] - self._function_info[name] = FunctionInfo(cstmt) - elif cstmt[0] == symbol.classdef: - name = cstmt[2][1] - self._class_info[name] = ClassInfo(cstmt) -\end{verbatim} - -After initializing some internal state, the constructor calls the -\method{_extract_info()} method. This method performs the bulk of the -information extraction which takes place in the entire example. The -extraction has two distinct phases: the location of the docstring for -the parse tree passed in, and the discovery of additional definitions -within the code block represented by the parse tree. - -The initial \keyword{if} test determines whether the nested suite is of -the ``short form'' or the ``long form.'' The short form is used when -the code block is on the same line as the definition of the code -block, as in - -\begin{verbatim} -def square(x): "Square an argument."; return x ** 2 -\end{verbatim} - -while the long form uses an indented block and allows nested -definitions: - -\begin{verbatim} -def make_power(exp): - "Make a function that raises an argument to the exponent `exp'." - def raiser(x, y=exp): - return x ** y - return raiser -\end{verbatim} - -When the short form is used, the code block may contain a docstring as -the first, and possibly only, \constant{small_stmt} element. The -extraction of such a docstring is slightly different and requires only -a portion of the complete pattern used in the more common case. As -implemented, the docstring will only be found if there is only -one \constant{small_stmt} node in the \constant{simple_stmt} node. -Since most functions and methods which use the short form do not -provide a docstring, this may be considered sufficient. The -extraction of the docstring proceeds using the \function{match()} function -as described above, and the value of the docstring is stored as an -attribute of the \class{SuiteInfoBase} object. - -After docstring extraction, a simple definition discovery -algorithm operates on the \constant{stmt} nodes of the -\constant{suite} node. The special case of the short form is not -tested; since there are no \constant{stmt} nodes in the short form, -the algorithm will silently skip the single \constant{simple_stmt} -node and correctly not discover any nested definitions. - -Each statement in the code block is categorized as -a class definition, function or method definition, or -something else. For the definition statements, the name of the -element defined is extracted and a representation object -appropriate to the definition is created with the defining subtree -passed as an argument to the constructor. The representation objects -are stored in instance variables and may be retrieved by name using -the appropriate accessor methods. - -The public classes provide any accessors required which are more -specific than those provided by the \class{SuiteInfoBase} class, but -the real extraction algorithm remains common to all forms of code -blocks. A high-level function can be used to extract the complete set -of information from a source file. (See file \file{example.py}.) - -\begin{verbatim} -def get_docs(fileName): - import os - import parser - - source = open(fileName).read() - basename = os.path.basename(os.path.splitext(fileName)[0]) - ast = parser.suite(source) - return ModuleInfo(ast.totuple(), basename) -\end{verbatim} - -This provides an easy-to-use interface to the documentation of a -module. If information is required which is not extracted by the code -of this example, the code may be extended at clearly defined points to -provide additional capabilities. diff --git a/Doc/lib/libpdb.tex b/Doc/lib/libpdb.tex deleted file mode 100644 index 45e778c..0000000 --- a/Doc/lib/libpdb.tex +++ /dev/null @@ -1,464 +0,0 @@ -\chapter{The Python Debugger \label{debugger}} - -\declaremodule{standard}{pdb} -\modulesynopsis{The Python debugger for interactive interpreters.} - - -The module \module{pdb} defines an interactive source code -debugger\index{debugging} for Python programs. It supports setting -(conditional) breakpoints and single stepping at the source line -level, inspection of stack frames, source code listing, and evaluation -of arbitrary Python code in the context of any stack frame. It also -supports post-mortem debugging and can be called under program -control. - -The debugger is extensible --- it is actually defined as the class -\class{Pdb}\withsubitem{(class in pdb)}{\ttindex{Pdb}}. -This is currently undocumented but easily understood by reading the -source. The extension interface uses the modules -\module{bdb}\refstmodindex{bdb} (undocumented) and -\refmodule{cmd}\refstmodindex{cmd}. - -The debugger's prompt is \samp{(Pdb) }. -Typical usage to run a program under control of the debugger is: - -\begin{verbatim} ->>> import pdb ->>> import mymodule ->>> pdb.run('mymodule.test()') -> <string>(0)?() -(Pdb) continue -> <string>(1)?() -(Pdb) continue -NameError: 'spam' -> <string>(1)?() -(Pdb) -\end{verbatim} - -\file{pdb.py} can also be invoked as -a script to debug other scripts. For example: - -\begin{verbatim} -python -m pdb myscript.py -\end{verbatim} - -When invoked as a script, pdb will automatically enter post-mortem debugging -if the program being debugged exits abnormally. After post-mortem debugging -(or after normal exit of the program), pdb will restart the program. -Automatic restarting preserves pdb's state (such as breakpoints) and in most -cases is more useful than quitting the debugger upon program's exit. -\versionadded[Restarting post-mortem behavior added]{2.4} - -Typical usage to inspect a crashed program is: - -\begin{verbatim} ->>> import pdb ->>> import mymodule ->>> mymodule.test() -Traceback (most recent call last): - File "<stdin>", line 1, in ? - File "./mymodule.py", line 4, in test - test2() - File "./mymodule.py", line 3, in test2 - print spam -NameError: spam ->>> pdb.pm() -> ./mymodule.py(3)test2() --> print spam -(Pdb) -\end{verbatim} - -The module defines the following functions; each enters the debugger -in a slightly different way: - -\begin{funcdesc}{run}{statement\optional{, globals\optional{, locals}}} -Execute the \var{statement} (given as a string) under debugger -control. The debugger prompt appears before any code is executed; you -can set breakpoints and type \samp{continue}, or you can step through -the statement using \samp{step} or \samp{next} (all these commands are -explained below). The optional \var{globals} and \var{locals} -arguments specify the environment in which the code is executed; by -default the dictionary of the module \refmodule[main]{__main__} is -used. (See the explanation of the built-in \function{exec()} or -\function{eval()} functions.) -\end{funcdesc} - -\begin{funcdesc}{runeval}{expression\optional{, globals\optional{, locals}}} -Evaluate the \var{expression} (given as a string) under debugger -control. When \function{runeval()} returns, it returns the value of the -expression. Otherwise this function is similar to -\function{run()}. -\end{funcdesc} - -\begin{funcdesc}{runcall}{function\optional{, argument, ...}} -Call the \var{function} (a function or method object, not a string) -with the given arguments. When \function{runcall()} returns, it returns -whatever the function call returned. The debugger prompt appears as -soon as the function is entered. -\end{funcdesc} - -\begin{funcdesc}{set_trace}{} -Enter the debugger at the calling stack frame. This is useful to -hard-code a breakpoint at a given point in a program, even if the code -is not otherwise being debugged (e.g. when an assertion fails). -\end{funcdesc} - -\begin{funcdesc}{post_mortem}{traceback} -Enter post-mortem debugging of the given \var{traceback} object. -\end{funcdesc} - -\begin{funcdesc}{pm}{} -Enter post-mortem debugging of the traceback found in -\code{sys.last_traceback}. -\end{funcdesc} - - -\section{Debugger Commands \label{debugger-commands}} - -The debugger recognizes the following commands. Most commands can be -abbreviated to one or two letters; e.g. \samp{h(elp)} means that -either \samp{h} or \samp{help} can be used to enter the help -command (but not \samp{he} or \samp{hel}, nor \samp{H} or -\samp{Help} or \samp{HELP}). Arguments to commands must be -separated by whitespace (spaces or tabs). Optional arguments are -enclosed in square brackets (\samp{[]}) in the command syntax; the -square brackets must not be typed. Alternatives in the command syntax -are separated by a vertical bar (\samp{|}). - -Entering a blank line repeats the last command entered. Exception: if -the last command was a \samp{list} command, the next 11 lines are -listed. - -Commands that the debugger doesn't recognize are assumed to be Python -statements and are executed in the context of the program being -debugged. Python statements can also be prefixed with an exclamation -point (\samp{!}). This is a powerful way to inspect the program -being debugged; it is even possible to change a variable or call a -function. When an -exception occurs in such a statement, the exception name is printed -but the debugger's state is not changed. - -Multiple commands may be entered on a single line, separated by -\samp{;;}. (A single \samp{;} is not used as it is -the separator for multiple commands in a line that is passed to -the Python parser.) -No intelligence is applied to separating the commands; -the input is split at the first \samp{;;} pair, even if it is in -the middle of a quoted string. - -The debugger supports aliases. Aliases can have parameters which -allows one a certain level of adaptability to the context under -examination. - -If a file \file{.pdbrc} -\indexii{.pdbrc}{file}\indexiii{debugger}{configuration}{file} -exists in the user's home directory or in the current directory, it is -read in and executed as if it had been typed at the debugger prompt. -This is particularly useful for aliases. If both files exist, the one -in the home directory is read first and aliases defined there can be -overridden by the local file. - -\begin{description} - -\item[h(elp) \optional{\var{command}}] - -Without argument, print the list of available commands. With a -\var{command} as argument, print help about that command. \samp{help -pdb} displays the full documentation file; if the environment variable -\envvar{PAGER} is defined, the file is piped through that command -instead. Since the \var{command} argument must be an identifier, -\samp{help exec} must be entered to get help on the \samp{!} command. - -\item[w(here)] - -Print a stack trace, with the most recent frame at the bottom. An -arrow indicates the current frame, which determines the context of -most commands. - -\item[d(own)] - -Move the current frame one level down in the stack trace -(to a newer frame). - -\item[u(p)] - -Move the current frame one level up in the stack trace -(to an older frame). - -\item[b(reak) \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}] - -With a \var{lineno} argument, set a break there in the current -file. With a \var{function} argument, set a break at the first -executable statement within that function. -The line number may be prefixed with a filename and a colon, -to specify a breakpoint in another file (probably one that -hasn't been loaded yet). The file is searched on \code{sys.path}. -Note that each breakpoint is assigned a number to which all the other -breakpoint commands refer. - -If a second argument is present, it is an expression which must -evaluate to true before the breakpoint is honored. - -Without argument, list all breaks, including for each breakpoint, -the number of times that breakpoint has been hit, the current -ignore count, and the associated condition if any. - -\item[tbreak \optional{\optional{\var{filename}:}\var{lineno}\code{\Large{|}}\var{function}\optional{, \var{condition}}}] - -Temporary breakpoint, which is removed automatically when it is -first hit. The arguments are the same as break. - -\item[cl(ear) \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] - -With a space separated list of breakpoint numbers, clear those -breakpoints. Without argument, clear all breaks (but first -ask confirmation). - -\item[disable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] - -Disables the breakpoints given as a space separated list of -breakpoint numbers. Disabling a breakpoint means it cannot cause -the program to stop execution, but unlike clearing a breakpoint, it -remains in the list of breakpoints and can be (re-)enabled. - -\item[enable \optional{\var{bpnumber} \optional{\var{bpnumber ...}}}] - -Enables the breakpoints specified. - -\item[ignore \var{bpnumber} \optional{\var{count}}] - -Sets the ignore count for the given breakpoint number. If -count is omitted, the ignore count is set to 0. A breakpoint -becomes active when the ignore count is zero. When non-zero, -the count is decremented each time the breakpoint is reached -and the breakpoint is not disabled and any associated condition -evaluates to true. - -\item[condition \var{bpnumber} \optional{\var{condition}}] - -Condition is an expression which must evaluate to true before -the breakpoint is honored. If condition is absent, any existing -condition is removed; i.e., the breakpoint is made unconditional. - -\item[commands \optional{\var{bpnumber}}] - -Specify a list of commands for breakpoint number \var{bpnumber}. The -commands themselves appear on the following lines. Type a line -containing just 'end' to terminate the commands. An example: - -\begin{verbatim} -(Pdb) commands 1 -(com) print some_variable -(com) end -(Pdb) -\end{verbatim} - -To remove all commands from a breakpoint, type commands and -follow it immediately with end; that is, give no commands. - -With no \var{bpnumber} argument, commands refers to the last -breakpoint set. - -You can use breakpoint commands to start your program up again. -Simply use the continue command, or step, or any other -command that resumes execution. - -Specifying any command resuming execution (currently continue, -step, next, return, jump, quit and their abbreviations) terminates -the command list (as if that command was immediately followed by end). -This is because any time you resume execution -(even with a simple next or step), you may encounter· -another breakpoint--which could have its own command list, leading to -ambiguities about which list to execute. - - If you use the 'silent' command in the command list, the -usual message about stopping at a breakpoint is not printed. This may -be desirable for breakpoints that are to print a specific message and -then continue. If none of the other commands print anything, you -see no sign that the breakpoint was reached. - -\versionadded{2.5} - -\item[s(tep)] - -Execute the current line, stop at the first possible occasion -(either in a function that is called or on the next line in the -current function). - -\item[n(ext)] - -Continue execution until the next line in the current function -is reached or it returns. (The difference between \samp{next} and -\samp{step} is that \samp{step} stops inside a called function, while -\samp{next} executes called functions at (nearly) full speed, only -stopping at the next line in the current function.) - -\item[r(eturn)] - -Continue execution until the current function returns. - -\item[c(ont(inue))] - -Continue execution, only stop when a breakpoint is encountered. - -\item[j(ump) \var{lineno}] - -Set the next line that will be executed. Only available in the -bottom-most frame. This lets you jump back and execute code -again, or jump forward to skip code that you don't want to run. - -It should be noted that not all jumps are allowed --- for instance it -is not possible to jump into the middle of a \keyword{for} loop or out -of a \keyword{finally} clause. - -\item[l(ist) \optional{\var{first}\optional{, \var{last}}}] - -List source code for the current file. Without arguments, list 11 -lines around the current line or continue the previous listing. With -one argument, list 11 lines around at that line. With two arguments, -list the given range; if the second argument is less than the first, -it is interpreted as a count. - -\item[a(rgs)] - -Print the argument list of the current function. - -\item[p \var{expression}] - -Evaluate the \var{expression} in the current context and print its -value. \note{\samp{print} can also be used, but is not a debugger -command --- this executes the Python \keyword{print} statement.} - -\item[pp \var{expression}] - -Like the \samp{p} command, except the value of the expression is -pretty-printed using the \module{pprint} module. - -\item[alias \optional{\var{name} \optional{command}}] - -Creates an alias called \var{name} that executes \var{command}. The -command must \emph{not} be enclosed in quotes. Replaceable parameters -can be indicated by \samp{\%1}, \samp{\%2}, and so on, while \samp{\%*} is -replaced by all the parameters. If no command is given, the current -alias for \var{name} is shown. If no arguments are given, all -aliases are listed. - -Aliases may be nested and can contain anything that can be -legally typed at the pdb prompt. Note that internal pdb commands -\emph{can} be overridden by aliases. Such a command is -then hidden until the alias is removed. Aliasing is recursively -applied to the first word of the command line; all other words -in the line are left alone. - -As an example, here are two useful aliases (especially when placed -in the \file{.pdbrc} file): - -\begin{verbatim} -#Print instance variables (usage "pi classInst") -alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k] -#Print instance variables in self -alias ps pi self -\end{verbatim} - -\item[unalias \var{name}] - -Deletes the specified alias. - -\item[\optional{!}\var{statement}] - -Execute the (one-line) \var{statement} in the context of -the current stack frame. -The exclamation point can be omitted unless the first word -of the statement resembles a debugger command. -To set a global variable, you can prefix the assignment -command with a \samp{global} command on the same line, e.g.: - -\begin{verbatim} -(Pdb) global list_options; list_options = ['-l'] -(Pdb) -\end{verbatim} - -\item[run \optional{\var{args} ...}] -Restart the debugged python program. If an argument is supplied, it is -splitted with "shlex" and the result is used as the new sys.argv. -History, breakpoints, actions and debugger options are preserved. -"restart" is an alias for "run". - -\versionadded{2.6} - -\item[q(uit)] - -Quit from the debugger. -The program being executed is aborted. - -\end{description} - -\section{How It Works \label{debugger-hooks}} - -Some changes were made to the interpreter: - -\begin{itemize} -\item \code{sys.settrace(\var{func})} sets the global trace function -\item there can also a local trace function (see later) -\end{itemize} - -Trace functions have three arguments: \var{frame}, \var{event}, and -\var{arg}. \var{frame} is the current stack frame. \var{event} is a -string: \code{'call'}, \code{'line'}, \code{'return'}, \code{'exception'}, - \code{'c_call'}, \code{'c_return'}, or \code{'c_exception'}. \var{arg} - depends on the event type. - -The global trace function is invoked (with \var{event} set to -\code{'call'}) whenever a new local scope is entered; it should return -a reference to the local trace function to be used that scope, or -\code{None} if the scope shouldn't be traced. - -The local trace function should return a reference to itself (or to -another function for further tracing in that scope), or \code{None} to -turn off tracing in that scope. - -Instance methods are accepted (and very useful!) as trace functions. - -The events have the following meaning: - -\begin{description} - -\item[\code{'call'}] -A function is called (or some other code block entered). The global -trace function is called; \var{arg} is \code{None}; -the return value specifies the local trace function. - -\item[\code{'line'}] -The interpreter is about to execute a new line of code (sometimes -multiple line events on one line exist). The local trace function is -called; \var{arg} is \code{None}; the return value specifies the new -local trace function. - -\item[\code{'return'}] -A function (or other code block) is about to return. The local trace -function is called; \var{arg} is the value that will be returned. The -trace function's return value is ignored. - -\item[\code{'exception'}] -An exception has occurred. The local trace function is called; -\var{arg} is a triple \code{(\var{exception}, \var{value}, -\var{traceback})}; the return value specifies the new local trace -function. - -\item[\code{'c_call'}] -A C function is about to be called. This may be an extension function -or a builtin. \var{arg} is the C function object. - -\item[\code{'c_return'}] -A C function has returned. \var{arg} is \code{None}. - -\item[\code{'c_exception'}] -A C function has thrown an exception. \var{arg} is \code{None}. - -\end{description} - -Note that as an exception is propagated down the chain of callers, an -\code{'exception'} event is generated at each level. - -For more information on code and frame objects, refer to the -\citetitle[../ref/ref.html]{Python Reference Manual}. diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex deleted file mode 100644 index 0c4cd98..0000000 --- a/Doc/lib/libpickle.tex +++ /dev/null @@ -1,888 +0,0 @@ -\section{\module{pickle} --- Python object serialization} - -\declaremodule{standard}{pickle} -\modulesynopsis{Convert Python objects to streams of bytes and back.} -% Substantial improvements by Jim Kerr <jbkerr@sr.hp.com>. -% Rewritten by Barry Warsaw <barry@zope.com> - -\index{persistence} -\indexii{persistent}{objects} -\indexii{serializing}{objects} -\indexii{marshalling}{objects} -\indexii{flattening}{objects} -\indexii{pickling}{objects} - -The \module{pickle} module implements a fundamental, but powerful -algorithm for serializing and de-serializing a Python object -structure. ``Pickling'' is the process whereby a Python object -hierarchy is converted into a byte stream, and ``unpickling'' is the -inverse operation, whereby a byte stream is converted back into an -object hierarchy. Pickling (and unpickling) is alternatively known as -``serialization'', ``marshalling,''\footnote{Don't confuse this with -the \refmodule{marshal} module} or ``flattening'', -however, to avoid confusion, the terms used here are ``pickling'' and -``unpickling''. - -This documentation describes both the \module{pickle} module and the -\refmodule{cPickle} module. - -\subsection{Relationship to other Python modules} - -The \module{pickle} module has an optimized cousin called the -\module{cPickle} module. As its name implies, \module{cPickle} is -written in C, so it can be up to 1000 times faster than -\module{pickle}. However it does not support subclassing of the -\function{Pickler()} and \function{Unpickler()} classes, because in -\module{cPickle} these are functions, not classes. Most applications -have no need for this functionality, and can benefit from the improved -performance of \module{cPickle}. Other than that, the interfaces of -the two modules are nearly identical; the common interface is -described in this manual and differences are pointed out where -necessary. In the following discussions, we use the term ``pickle'' -to collectively describe the \module{pickle} and -\module{cPickle} modules. - -The data streams the two modules produce are guaranteed to be -interchangeable. - -Python has a more primitive serialization module called -\refmodule{marshal}, but in general -\module{pickle} should always be the preferred way to serialize Python -objects. \module{marshal} exists primarily to support Python's -\file{.pyc} files. - -The \module{pickle} module differs from \refmodule{marshal} several -significant ways: - -\begin{itemize} - -\item The \module{pickle} module keeps track of the objects it has - already serialized, so that later references to the same object - won't be serialized again. \module{marshal} doesn't do this. - - This has implications both for recursive objects and object - sharing. Recursive objects are objects that contain references - to themselves. These are not handled by marshal, and in fact, - attempting to marshal recursive objects will crash your Python - interpreter. Object sharing happens when there are multiple - references to the same object in different places in the object - hierarchy being serialized. \module{pickle} stores such objects - only 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 \module{marshal} cannot be used to serialize user-defined - classes and their instances. \module{pickle} can save and - restore class instances transparently, however the class - definition must be importable and live in the same module as - when the object was stored. - -\item The \module{marshal} serialization format is not guaranteed to - be portable across Python versions. Because its primary job in - life is to support \file{.pyc} files, the Python implementers - reserve the right to change the serialization format in - non-backwards compatible ways should the need arise. The - \module{pickle} serialization format is guaranteed to be - backwards compatible across Python releases. - -\end{itemize} - -\begin{notice}[warning] -The \module{pickle} module is not intended to be secure against -erroneous or maliciously constructed data. Never unpickle data -received from an untrusted or unauthenticated source. -\end{notice} - -Note that serialization is a more primitive notion than persistence; -although -\module{pickle} reads and writes file objects, it does not handle the -issue of naming persistent objects, nor the (even more complicated) -issue of concurrent access to persistent objects. The \module{pickle} -module can transform a complex object into a byte stream and it can -transform the byte stream into an object with the same internal -structure. Perhaps the most obvious thing to do with these byte -streams is to write them onto a file, but it is also conceivable to -send them across a network or store them in a database. The module -\refmodule{shelve} provides a simple interface -to pickle and unpickle objects on DBM-style database files. - -\subsection{Data stream format} - -The data format used by \module{pickle} is Python-specific. This has -the advantage that there are no restrictions imposed by external -standards such as XDR\index{XDR}\index{External Data Representation} -(which can't represent pointer sharing); however it means that -non-Python programs may not be able to reconstruct pickled Python -objects. - -By default, the \module{pickle} data format uses a printable \ASCII{} -representation. This is slightly more voluminous than a binary -representation. The big advantage of using printable \ASCII{} (and of -some other characteristics of \module{pickle}'s representation) is that -for debugging or recovery purposes it is possible for a human to read -the pickled file with a standard text editor. - -There are currently 3 different protocols which can be used for pickling. - -\begin{itemize} - -\item Protocol version 0 is the original ASCII protocol and is backwards -compatible with earlier versions of Python. - -\item Protocol version 1 is the old binary format which is also compatible -with earlier versions of Python. - -\item Protocol version 2 was introduced in Python 2.3. It provides -much more efficient pickling of new-style classes. - -\end{itemize} - -Refer to PEP 307 for more information. - -If a \var{protocol} is not specified, protocol 0 is used. -If \var{protocol} is specified as a negative value -or \constant{HIGHEST_PROTOCOL}, -the highest protocol version available will be used. - -\versionchanged[Introduced the \var{protocol} parameter]{2.3} - -A binary format, which is slightly more efficient, can be chosen by -specifying a \var{protocol} version >= 1. - -\subsection{Usage} - -To serialize an object hierarchy, you first create a pickler, then you -call the pickler's \method{dump()} method. To de-serialize a data -stream, you first create an unpickler, then you call the unpickler's -\method{load()} method. The \module{pickle} module provides the -following constant: - -\begin{datadesc}{HIGHEST_PROTOCOL} -The highest protocol version available. This value can be passed -as a \var{protocol} value. -\versionadded{2.3} -\end{datadesc} - -\note{Be sure to always open pickle files created with protocols >= 1 in - binary mode. For the old ASCII-based pickle protocol 0 you can use - either text mode or binary mode as long as you stay consistent. - - A pickle file written with protocol 0 in binary mode will contain - lone linefeeds as line terminators and therefore will look ``funny'' - when viewed in Notepad or other editors which do not support this - format.} - -The \module{pickle} module provides the -following functions to make the pickling process more convenient: - -\begin{funcdesc}{dump}{obj, file\optional{, protocol}} -Write a pickled representation of \var{obj} to the open file object -\var{file}. This is equivalent to -\code{Pickler(\var{file}, \var{protocol}).dump(\var{obj})}. - -If the \var{protocol} parameter is omitted, protocol 0 is used. -If \var{protocol} is specified as a negative value -or \constant{HIGHEST_PROTOCOL}, -the highest protocol version will be used. - -\versionchanged[Introduced the \var{protocol} parameter]{2.3} - -\var{file} must have a \method{write()} method that accepts a single -string argument. It can thus be a file object opened for writing, a -\refmodule{StringIO} object, or any other custom -object that meets this interface. -\end{funcdesc} - -\begin{funcdesc}{load}{file} -Read a string from the open file object \var{file} and interpret it as -a pickle data stream, reconstructing and returning the original object -hierarchy. This is equivalent to \code{Unpickler(\var{file}).load()}. - -\var{file} must have two methods, a \method{read()} method that takes -an integer argument, and a \method{readline()} method that requires no -arguments. Both methods should return a string. Thus \var{file} can -be a file object opened for reading, a -\module{StringIO} object, or any other custom -object that meets this interface. - -This function automatically determines whether the data stream was -written in binary mode or not. -\end{funcdesc} - -\begin{funcdesc}{dumps}{obj\optional{, protocol}} -Return the pickled representation of the object as a string, instead -of writing it to a file. - -If the \var{protocol} parameter is omitted, protocol 0 is used. -If \var{protocol} is specified as a negative value -or \constant{HIGHEST_PROTOCOL}, -the highest protocol version will be used. - -\versionchanged[The \var{protocol} parameter was added]{2.3} - -\end{funcdesc} - -\begin{funcdesc}{loads}{string} -Read a pickled object hierarchy from a string. Characters in the -string past the pickled object's representation are ignored. -\end{funcdesc} - -The \module{pickle} module also defines three exceptions: - -\begin{excdesc}{PickleError} -A common base class for the other exceptions defined below. This -inherits from \exception{Exception}. -\end{excdesc} - -\begin{excdesc}{PicklingError} -This exception is raised when an unpicklable object is passed to -the \method{dump()} method. -\end{excdesc} - -\begin{excdesc}{UnpicklingError} -This exception is raised when there is a problem unpickling an object. -Note that other exceptions may also be raised during unpickling, -including (but not necessarily limited to) \exception{AttributeError}, -\exception{EOFError}, \exception{ImportError}, and \exception{IndexError}. -\end{excdesc} - -The \module{pickle} module also exports two callables\footnote{In the -\module{pickle} module these callables are classes, which you could -subclass to customize the behavior. However, in the \refmodule{cPickle} -module these callables are factory functions and so cannot be -subclassed. One common reason to subclass is to control what -objects can actually be unpickled. See section~\ref{pickle-sub} for -more details.}, \class{Pickler} and \class{Unpickler}: - -\begin{classdesc}{Pickler}{file\optional{, protocol}} -This takes a file-like object to which it will write a pickle data -stream. - -If the \var{protocol} parameter is omitted, protocol 0 is used. -If \var{protocol} is specified as a negative value, -the highest protocol version will be used. - -\versionchanged[Introduced the \var{protocol} parameter]{2.3} - -\var{file} must have a \method{write()} method that accepts a single -string argument. It can thus be an open file object, a -\module{StringIO} object, or any other custom -object that meets this interface. -\end{classdesc} - -\class{Pickler} objects define one (or two) public methods: - -\begin{methoddesc}[Pickler]{dump}{obj} -Write a pickled representation of \var{obj} to the open file object -given in the constructor. Either the binary or \ASCII{} format will -be used, depending on the value of the \var{protocol} argument passed to the -constructor. -\end{methoddesc} - -\begin{methoddesc}[Pickler]{clear_memo}{} -Clears the pickler's ``memo''. The memo is the data structure that -remembers which objects the pickler has already seen, so that shared -or recursive objects pickled by reference and not by value. This -method is useful when re-using picklers. - -\begin{notice} -Prior to Python 2.3, \method{clear_memo()} was only available on the -picklers created by \refmodule{cPickle}. In the \module{pickle} module, -picklers have an instance variable called \member{memo} which is a -Python dictionary. So to clear the memo for a \module{pickle} module -pickler, you could do the following: - -\begin{verbatim} -mypickler.memo.clear() -\end{verbatim} - -Code that does not need to support older versions of Python should -simply use \method{clear_memo()}. -\end{notice} -\end{methoddesc} - -It is possible to make multiple calls to the \method{dump()} method of -the same \class{Pickler} instance. These must then be matched to the -same number of calls to the \method{load()} method of the -corresponding \class{Unpickler} instance. If the same object is -pickled by multiple \method{dump()} calls, the \method{load()} will -all yield references to the same object.\footnote{\emph{Warning}: this -is intended for pickling multiple objects without intervening -modifications to the objects or their parts. If you modify an object -and then pickle it again using the same \class{Pickler} instance, the -object is not pickled again --- a reference to it is pickled and the -\class{Unpickler} will return the old value, not the modified one. -There are two problems here: (1) detecting changes, and (2) -marshalling a minimal set of changes. Garbage Collection may also -become a problem here.} - -\class{Unpickler} objects are defined as: - -\begin{classdesc}{Unpickler}{file} -This takes a file-like object from which it will read a pickle data -stream. This class automatically determines whether the data stream -was written in binary mode or not, so it does not need a flag as in -the \class{Pickler} factory. - -\var{file} must have two methods, a \method{read()} method that takes -an integer argument, and a \method{readline()} method that requires no -arguments. Both methods should return a string. Thus \var{file} can -be a file object opened for reading, a -\module{StringIO} object, or any other custom -object that meets this interface. -\end{classdesc} - -\class{Unpickler} objects have one (or two) public methods: - -\begin{methoddesc}[Unpickler]{load}{} -Read a pickled object representation from the open file object given -in the constructor, and return the reconstituted object hierarchy -specified therein. -\end{methoddesc} - -\begin{methoddesc}[Unpickler]{noload}{} -This is just like \method{load()} except that it doesn't actually -create any objects. This is useful primarily for finding what's -called ``persistent ids'' that may be referenced in a pickle data -stream. See section~\ref{pickle-protocol} below for more details. - -\strong{Note:} the \method{noload()} method is currently only -available on \class{Unpickler} objects created with the -\module{cPickle} module. \module{pickle} module \class{Unpickler}s do -not have the \method{noload()} method. -\end{methoddesc} - -\subsection{What can be pickled and unpickled?} - -The following types can be pickled: - -\begin{itemize} - -\item \code{None}, \code{True}, and \code{False} - -\item integers, long integers, floating point numbers, complex numbers - -\item normal and Unicode strings - -\item tuples, lists, sets, and dictionaries containing only picklable objects - -\item functions defined at the top level of a module - -\item built-in functions defined at the top level of a module - -\item classes that are defined at the top level of a module - -\item instances of such classes whose \member{__dict__} or -\method{__setstate__()} is picklable (see -section~\ref{pickle-protocol} for details) - -\end{itemize} - -Attempts to pickle unpicklable objects will raise the -\exception{PicklingError} exception; when this happens, an unspecified -number of bytes may have already been written to the underlying file. -Trying to pickle a highly recursive data structure may exceed the -maximum recursion depth, a \exception{RuntimeError} will be raised -in this case. You can carefully raise this limit with -\function{sys.setrecursionlimit()}. - -Note that functions (built-in and user-defined) are pickled by ``fully -qualified'' name reference, not by value. This means that only the -function name is pickled, along with the name of module the function -is defined in. Neither the function's code, nor any of its function -attributes are pickled. Thus the defining module must be importable -in the unpickling environment, and the module must contain the named -object, otherwise an exception will be raised.\footnote{The exception -raised will likely be an \exception{ImportError} or an -\exception{AttributeError} but it could be something else.} - -Similarly, classes are pickled by named reference, so the same -restrictions in the unpickling environment apply. Note that none of -the class's code or data is pickled, so in the following example the -class attribute \code{attr} is not restored in the unpickling -environment: - -\begin{verbatim} -class Foo: - attr = 'a class attr' - -picklestring = pickle.dumps(Foo) -\end{verbatim} - -These restrictions are why picklable functions and classes must be -defined in the top level of a module. - -Similarly, when class instances are pickled, their class's code and -data are not pickled along with them. Only the instance data are -pickled. This is done on purpose, so you can fix bugs in a class or -add methods to the class and still load objects that were created with -an earlier version of the class. If you plan to have long-lived -objects that will see many versions of a class, it may be worthwhile -to put a version number in the objects so that suitable conversions -can be made by the class's \method{__setstate__()} method. - -\subsection{The pickle protocol -\label{pickle-protocol}}\setindexsubitem{(pickle protocol)} - -This section describes the ``pickling protocol'' that defines the -interface between the pickler/unpickler and the objects that are being -serialized. This protocol provides a standard way for you to define, -customize, and control how your objects are serialized and -de-serialized. The description in this section doesn't cover specific -customizations that you can employ to make the unpickling environment -slightly safer from untrusted pickle data streams; see section~\ref{pickle-sub} -for more details. - -\subsubsection{Pickling and unpickling normal class - instances\label{pickle-inst}} - -When a pickled class instance is unpickled, its \method{__init__()} -method is normally \emph{not} invoked. If it is desirable that the -\method{__init__()} method be called on unpickling, an old-style class -can define a method \method{__getinitargs__()}, which should return a -\emph{tuple} containing the arguments to be passed to the class -constructor (\method{__init__()} for example). The -\method{__getinitargs__()} method is called at -pickle time; the tuple it returns is incorporated in the pickle for -the instance. -\withsubitem{(copy protocol)}{\ttindex{__getinitargs__()}} -\withsubitem{(instance constructor)}{\ttindex{__init__()}} - -\withsubitem{(copy protocol)}{\ttindex{__getnewargs__()}} - -New-style types can provide a \method{__getnewargs__()} method that is -used for protocol 2. Implementing this method is needed if the type -establishes some internal invariants when the instance is created, or -if the memory allocation is affected by the values passed to the -\method{__new__()} method for the type (as it is for tuples and -strings). Instances of a new-style type \class{C} are created using - -\begin{alltt} -obj = C.__new__(C, *\var{args}) -\end{alltt} - -where \var{args} is the result of calling \method{__getnewargs__()} on -the original object; if there is no \method{__getnewargs__()}, an -empty tuple is assumed. - -\withsubitem{(copy protocol)}{ - \ttindex{__getstate__()}\ttindex{__setstate__()}} -\withsubitem{(instance attribute)}{ - \ttindex{__dict__}} - -Classes can further influence how their instances are pickled; if the -class defines the method \method{__getstate__()}, it is called and the -return state is pickled as the contents for the instance, instead of -the contents of the instance's dictionary. If there is no -\method{__getstate__()} method, the instance's \member{__dict__} is -pickled. - -Upon unpickling, if the class also defines the method -\method{__setstate__()}, it is called with the unpickled -state.\footnote{These methods can also be used to implement copying -class instances.} If there is no \method{__setstate__()} method, the -pickled state must be a dictionary and its items are assigned to the -new instance's dictionary. If a class defines both -\method{__getstate__()} and \method{__setstate__()}, the state object -needn't be a dictionary and these methods can do what they -want.\footnote{This protocol is also used by the shallow and deep -copying operations defined in the -\refmodule{copy} module.} - -\begin{notice}[warning] - For new-style classes, if \method{__getstate__()} returns a false - value, the \method{__setstate__()} method will not be called. -\end{notice} - - -\subsubsection{Pickling and unpickling extension types} - -When the \class{Pickler} encounters an object of a type it knows -nothing about --- such as an extension type --- it looks in two places -for a hint of how to pickle it. One alternative is for the object to -implement a \method{__reduce__()} method. If provided, at pickling -time \method{__reduce__()} will be called with no arguments, and it -must return either a string or a tuple. - -If a string is returned, it names a global variable whose contents are -pickled as normal. The string returned by \method{__reduce__} should -be the object's local name relative to its module; the pickle module -searches the module namespace to determine the object's module. - -When a tuple is returned, it must be between two and five elements -long. Optional elements can either be omitted, or \code{None} can be provided -as their value. The semantics of each element are: - -\begin{itemize} - -\item A callable object that will be called to create the initial -version of the object. The next element of the tuple will provide -arguments for this callable, and later elements provide additional -state information that will subsequently be used to fully reconstruct -the pickled data. - -In the unpickling environment this object must be either a class, a -callable registered as a ``safe constructor'' (see below), or it must -have an attribute \member{__safe_for_unpickling__} with a true value. -Otherwise, an \exception{UnpicklingError} will be raised in the -unpickling environment. Note that as usual, the callable itself is -pickled by name. - -\item A tuple of arguments for the callable object. -\versionchanged[Formerly, this argument could also be \code{None}]{2.5} - -\item Optionally, the object's state, which will be passed to - the object's \method{__setstate__()} method as described in - section~\ref{pickle-inst}. If the object has no - \method{__setstate__()} method, then, as above, the value must - be a dictionary and it will be added to the object's - \member{__dict__}. - -\item Optionally, an iterator (and not a sequence) yielding successive -list items. These list items will be pickled, and appended to the -object using either \code{obj.append(\var{item})} or -\code{obj.extend(\var{list_of_items})}. This is primarily used for -list subclasses, but may be used by other classes as long as they have -\method{append()} and \method{extend()} methods with the appropriate -signature. (Whether \method{append()} or \method{extend()} is used -depends on which pickle protocol version is used as well as the number -of items to append, so both must be supported.) - -\item Optionally, an iterator (not a sequence) -yielding successive dictionary items, which should be tuples of the -form \code{(\var{key}, \var{value})}. These items will be pickled -and stored to the object using \code{obj[\var{key}] = \var{value}}. -This is primarily used for dictionary subclasses, but may be used by -other classes as long as they implement \method{__setitem__}. - -\end{itemize} - -It is sometimes useful to know the protocol version when implementing -\method{__reduce__}. This can be done by implementing a method named -\method{__reduce_ex__} instead of \method{__reduce__}. -\method{__reduce_ex__}, when it exists, is called in preference over -\method{__reduce__} (you may still provide \method{__reduce__} for -backwards compatibility). The \method{__reduce_ex__} method will be -called with a single integer argument, the protocol version. - -The \class{object} class implements both \method{__reduce__} and -\method{__reduce_ex__}; however, if a subclass overrides -\method{__reduce__} but not \method{__reduce_ex__}, the -\method{__reduce_ex__} implementation detects this and calls -\method{__reduce__}. - -An alternative to implementing a \method{__reduce__()} method on the -object to be pickled, is to register the callable with the -\refmodule[copyreg]{copy_reg} module. This module provides a way -for programs to register ``reduction functions'' and constructors for -user-defined types. Reduction functions have the same semantics and -interface as the \method{__reduce__()} method described above, except -that they are called with a single argument, the object to be pickled. - -The registered constructor is deemed a ``safe constructor'' for purposes -of unpickling as described above. - - -\subsubsection{Pickling and unpickling external objects} - -For the benefit of object persistence, the \module{pickle} module -supports the notion of a reference to an object outside the pickled -data stream. Such objects are referenced by a ``persistent id'', -which is just an arbitrary string of printable \ASCII{} characters. -The resolution of such names is not defined by the \module{pickle} -module; it will delegate this resolution to user defined functions on -the pickler and unpickler.\footnote{The actual mechanism for -associating these user defined functions is slightly different for -\module{pickle} and \module{cPickle}. The description given here -works the same for both implementations. Users of the \module{pickle} -module could also use subclassing to effect the same results, -overriding the \method{persistent_id()} and \method{persistent_load()} -methods in the derived classes.} - -To define external persistent id resolution, you need to set the -\member{persistent_id} attribute of the pickler object and the -\member{persistent_load} attribute of the unpickler object. - -To pickle objects that have an external persistent id, the pickler -must have a custom \function{persistent_id()} method that takes an -object as an argument and returns either \code{None} or the persistent -id for that object. When \code{None} is returned, the pickler simply -pickles the object as normal. When a persistent id string is -returned, the pickler will pickle that string, along with a marker -so that the unpickler will recognize the string as a persistent id. - -To unpickle external objects, the unpickler must have a custom -\function{persistent_load()} function that takes a persistent id -string and returns the referenced object. - -Here's a silly example that \emph{might} shed more light: - -\begin{verbatim} -import pickle -from cStringIO import StringIO - -src = StringIO() -p = pickle.Pickler(src) - -def persistent_id(obj): - if hasattr(obj, 'x'): - return 'the value %d' % obj.x - else: - return None - -p.persistent_id = persistent_id - -class Integer: - def __init__(self, x): - self.x = x - def __str__(self): - return 'My name is integer %d' % self.x - -i = Integer(7) -print i -p.dump(i) - -datastream = src.getvalue() -print repr(datastream) -dst = StringIO(datastream) - -up = pickle.Unpickler(dst) - -class FancyInteger(Integer): - def __str__(self): - return 'I am the integer %d' % self.x - -def persistent_load(persid): - if persid.startswith('the value '): - value = int(persid.split()[2]) - return FancyInteger(value) - else: - raise pickle.UnpicklingError, 'Invalid persistent id' - -up.persistent_load = persistent_load - -j = up.load() -print j -\end{verbatim} - -In the \module{cPickle} module, the unpickler's -\member{persistent_load} attribute can also be set to a Python -list, in which case, when the unpickler reaches a persistent id, the -persistent id string will simply be appended to this list. This -functionality exists so that a pickle data stream can be ``sniffed'' -for object references without actually instantiating all the objects -in a pickle.\footnote{We'll leave you with the image of Guido and Jim -sitting around sniffing pickles in their living rooms.} Setting -\member{persistent_load} to a list is usually used in conjunction with -the \method{noload()} method on the Unpickler. - -% BAW: Both pickle and cPickle support something called -% inst_persistent_id() which appears to give unknown types a second -% shot at producing a persistent id. Since Jim Fulton can't remember -% why it was added or what it's for, I'm leaving it undocumented. - -\subsection{Subclassing Unpicklers \label{pickle-sub}} - -By default, unpickling will import any class that it finds in the -pickle data. You can control exactly what gets unpickled and what -gets called by customizing your unpickler. Unfortunately, exactly how -you do this is different depending on whether you're using -\module{pickle} or \module{cPickle}.\footnote{A word of caution: the -mechanisms described here use internal attributes and methods, which -are subject to change in future versions of Python. We intend to -someday provide a common interface for controlling this behavior, -which will work in either \module{pickle} or \module{cPickle}.} - -In the \module{pickle} module, you need to derive a subclass from -\class{Unpickler}, overriding the \method{load_global()} -method. \method{load_global()} should read two lines from the pickle -data stream where the first line will the name of the module -containing the class and the second line will be the name of the -instance's class. It then looks up the class, possibly importing the -module and digging out the attribute, then it appends what it finds to -the unpickler's stack. Later on, this class will be assigned to the -\member{__class__} attribute of an empty class, as a way of magically -creating an instance without calling its class's \method{__init__()}. -Your job (should you choose to accept it), would be to have -\method{load_global()} push onto the unpickler's stack, a known safe -version of any class you deem safe to unpickle. It is up to you to -produce such a class. Or you could raise an error if you want to -disallow all unpickling of instances. If this sounds like a hack, -you're right. Refer to the source code to make this work. - -Things are a little cleaner with \module{cPickle}, but not by much. -To control what gets unpickled, you can set the unpickler's -\member{find_global} attribute to a function or \code{None}. If it is -\code{None} then any attempts to unpickle instances will raise an -\exception{UnpicklingError}. If it is a function, -then it should accept a module name and a class name, and return the -corresponding class object. It is responsible for looking up the -class and performing any necessary imports, and it may raise an -error to prevent instances of the class from being unpickled. - -The moral of the story is that you should be really careful about the -source of the strings your application unpickles. - -\subsection{Example \label{pickle-example}} - -For the simplest code, use the \function{dump()} and \function{load()} -functions. Note that a self-referencing list is pickled and restored -correctly. - -\begin{verbatim} -import pickle - -data1 = {'a': [1, 2.0, 3, 4+6j], - 'b': ('string', u'Unicode string'), - 'c': None} - -selfref_list = [1, 2, 3] -selfref_list.append(selfref_list) - -output = open('data.pkl', 'wb') - -# Pickle dictionary using protocol 0. -pickle.dump(data1, output) - -# Pickle the list using the highest protocol available. -pickle.dump(selfref_list, output, -1) - -output.close() -\end{verbatim} - -The following example reads the resulting pickled data. When reading -a pickle-containing file, you should open the file in binary mode -because you can't be sure if the ASCII or binary format was used. - -\begin{verbatim} -import pprint, pickle - -pkl_file = open('data.pkl', 'rb') - -data1 = pickle.load(pkl_file) -pprint.pprint(data1) - -data2 = pickle.load(pkl_file) -pprint.pprint(data2) - -pkl_file.close() -\end{verbatim} - -Here's a larger example that shows 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} -class TextReader: - """Print and number lines in a text file.""" - def __init__(self, file): - self.file = file - self.fh = open(file) - self.lineno = 0 - - def readline(self): - self.lineno = self.lineno + 1 - line = self.fh.readline() - if not line: - return None - if line.endswith("\n"): - line = line[:-1] - return "%d: %s" % (self.lineno, line) - - def __getstate__(self): - odict = self.__dict__.copy() # copy the dict since we change it - del odict['fh'] # remove filehandle entry - return odict - - 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 - self.__dict__.update(dict) # update attributes - self.fh = fh # save the file object -\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', 'wb')) -\end{verbatim} - -If you want to see that \refmodule{pickle} works across Python -processes, start another Python session, before continuing. What -follows can happen from either the same process or a new process. - -\begin{verbatim} ->>> import pickle ->>> reader = pickle.load(open('save.p', 'rb')) ->>> reader.readline() -'8: "Print and number lines in a text file."' -\end{verbatim} - - -\begin{seealso} - \seemodule[copyreg]{copy_reg}{Pickle interface constructor - registration for extension types.} - - \seemodule{shelve}{Indexed databases of objects; uses \module{pickle}.} - - \seemodule{copy}{Shallow and deep object copying.} - - \seemodule{marshal}{High-performance serialization of built-in types.} -\end{seealso} - - -\section{\module{cPickle} --- A faster \module{pickle}} - -\declaremodule{builtin}{cPickle} -\modulesynopsis{Faster version of \refmodule{pickle}, but not subclassable.} -\moduleauthor{Jim Fulton}{jim@zope.com} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -The \module{cPickle} module supports serialization and -de-serialization of Python objects, providing an interface and -functionality nearly identical to the -\refmodule{pickle}\refstmodindex{pickle} module. There are several -differences, the most important being performance and subclassability. - -First, \module{cPickle} can be up to 1000 times faster than -\module{pickle} because the former is implemented in C. Second, in -the \module{cPickle} module the callables \function{Pickler()} and -\function{Unpickler()} are functions, not classes. This means that -you cannot use them to derive custom pickling and unpickling -subclasses. Most applications have no need for this functionality and -should benefit from the greatly improved performance of the -\module{cPickle} module. - -The pickle data stream produced by \module{pickle} and -\module{cPickle} are identical, so it is possible to use -\module{pickle} and \module{cPickle} interchangeably with existing -pickles.\footnote{Since the pickle data format is actually a tiny -stack-oriented programming language, and some freedom is taken in the -encodings of certain objects, it is possible that the two modules -produce different data streams for the same input objects. However it -is guaranteed that they will always be able to read each other's -data streams.} - -There are additional minor differences in API between \module{cPickle} -and \module{pickle}, however for most applications, they are -interchangeable. More documentation is provided in the -\module{pickle} module documentation, which -includes a list of the documented differences. - - diff --git a/Doc/lib/libpickletools.tex b/Doc/lib/libpickletools.tex deleted file mode 100644 index 8f63626..0000000 --- a/Doc/lib/libpickletools.tex +++ /dev/null @@ -1,34 +0,0 @@ -\section{\module{pickletools} --- Tools for pickle developers.} - -\declaremodule{standard}{pickletools} -\modulesynopsis{Contains extensive comments about the pickle protocols and pickle-machine opcodes, as well as some useful functions.} - -\versionadded{2.3} - -This module contains various constants relating to the intimate -details of the \refmodule{pickle} module, some lengthy comments about -the implementation, and a few useful functions for analyzing pickled -data. The contents of this module are useful for Python core -developers who are working on the \module{pickle} and \module{cPickle} -implementations; ordinary users of the \module{pickle} module probably -won't find the \module{pickletools} module relevant. - -\begin{funcdesc}{dis}{pickle\optional{, out=None, memo=None, indentlevel=4}} -Outputs a symbolic disassembly of the pickle to the file-like object -\var{out}, defaulting to \code{sys.stdout}. \var{pickle} can be a -string or a file-like object. \var{memo} can be a Python dictionary -that will be used as the pickle's memo; it can be used to perform -disassemblies across multiple pickles created by the same pickler. -Successive levels, indicated by \code{MARK} opcodes in the stream, are -indented by \var{indentlevel} spaces. -\end{funcdesc} - -\begin{funcdesc}{genops}{pickle} -Provides an iterator over all of the opcodes in a pickle, returning a -sequence of \code{(\var{opcode}, \var{arg}, \var{pos})} triples. -\var{opcode} is an instance of an \class{OpcodeInfo} class; \var{arg} -is the decoded value, as a Python object, of the opcode's argument; -\var{pos} is the position at which this opcode is located. -\var{pickle} can be a string or a file-like object. -\end{funcdesc} - diff --git a/Doc/lib/libpipes.tex b/Doc/lib/libpipes.tex deleted file mode 100644 index de25fb5..0000000 --- a/Doc/lib/libpipes.tex +++ /dev/null @@ -1,84 +0,0 @@ -\section{\module{pipes} --- - Interface to shell pipelines} - -\declaremodule{standard}{pipes} - \platform{Unix} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{A Python interface to \UNIX\ shell pipelines.} - - -The \module{pipes} module defines a class to abstract the concept of -a \emph{pipeline} --- a sequence of converters from one file to -another. - -Because the module uses \program{/bin/sh} command lines, a \POSIX{} or -compatible shell for \function{os.system()} and \function{os.popen()} -is required. - -The \module{pipes} module defines the following class: - -\begin{classdesc}{Template}{} -An abstraction of a pipeline. -\end{classdesc} - -Example: - -\begin{verbatim} ->>> import pipes ->>> t=pipes.Template() ->>> t.append('tr a-z A-Z', '--') ->>> f=t.open('/tmp/1', 'w') ->>> f.write('hello world') ->>> f.close() ->>> open('/tmp/1').read() -'HELLO WORLD' -\end{verbatim} - - -\subsection{Template Objects \label{template-objects}} - -Template objects following methods: - -\begin{methoddesc}[Template]{reset}{} -Restore a pipeline template to its initial state. -\end{methoddesc} - -\begin{methoddesc}[Template]{clone}{} -Return a new, equivalent, pipeline template. -\end{methoddesc} - -\begin{methoddesc}[Template]{debug}{flag} -If \var{flag} is true, turn debugging on. Otherwise, turn debugging -off. When debugging is on, commands to be executed are printed, and -the shell is given \code{set -x} command to be more verbose. -\end{methoddesc} - -\begin{methoddesc}[Template]{append}{cmd, kind} -Append a new action at the end. The \var{cmd} variable must be a valid -bourne shell command. The \var{kind} variable consists of two letters. - -The first letter can be either of \code{'-'} (which means the command -reads its standard input), \code{'f'} (which means the commands reads -a given file on the command line) or \code{'.'} (which means the commands -reads no input, and hence must be first.) - -Similarly, the second letter can be either of \code{'-'} (which means -the command writes to standard output), \code{'f'} (which means the -command writes a file on the command line) or \code{'.'} (which means -the command does not write anything, and hence must be last.) -\end{methoddesc} - -\begin{methoddesc}[Template]{prepend}{cmd, kind} -Add a new action at the beginning. See \method{append()} for explanations -of the arguments. -\end{methoddesc} - -\begin{methoddesc}[Template]{open}{file, mode} -Return a file-like object, open to \var{file}, but read from or -written to by the pipeline. Note that only one of \code{'r'}, -\code{'w'} may be given. -\end{methoddesc} - -\begin{methoddesc}[Template]{copy}{infile, outfile} -Copy \var{infile} to \var{outfile} through the pipe. -\end{methoddesc} diff --git a/Doc/lib/libpkgutil.tex b/Doc/lib/libpkgutil.tex deleted file mode 100644 index a286f00..0000000 --- a/Doc/lib/libpkgutil.tex +++ /dev/null @@ -1,45 +0,0 @@ -\section{\module{pkgutil} --- - Package extension utility} - -\declaremodule{standard}{pkgutil} -\modulesynopsis{Utilities to support extension of packages.} - -\versionadded{2.3} - -This module provides a single function: - -\begin{funcdesc}{extend_path}{path, name} - Extend the search path for the modules which comprise a package. - Intended use is to place the following code in a package's - \file{__init__.py}: - -\begin{verbatim} -from pkgutil import extend_path -__path__ = extend_path(__path__, __name__) -\end{verbatim} - - This will add to the package's \code{__path__} all subdirectories of - directories on \code{sys.path} named after the package. This is - useful if one wants to distribute different parts of a single - logical package as multiple directories. - - It also looks for \file{*.pkg} files beginning where \code{*} - matches the \var{name} argument. This feature is similar to - \file{*.pth} files (see the \refmodule{site} module for more - information), except that it doesn't special-case lines starting - with \code{import}. A \file{*.pkg} file is trusted at face value: - apart from checking for duplicates, all entries found in a - \file{*.pkg} file are added to the path, regardless of whether they - exist on the filesystem. (This is a feature.) - - If the input path is not a list (as is the case for frozen - packages) it is returned unchanged. The input path is not - modified; an extended copy is returned. Items are only appended - to the copy at the end. - - It is assumed that \code{sys.path} is a sequence. Items of - \code{sys.path} that are not (Unicode or 8-bit) strings referring to - existing directories are ignored. Unicode items on \code{sys.path} - that cause errors when used as filenames may cause this function to - raise an exception (in line with \function{os.path.isdir()} behavior). -\end{funcdesc} diff --git a/Doc/lib/libplatform.tex b/Doc/lib/libplatform.tex deleted file mode 100644 index a2f1913..0000000 --- a/Doc/lib/libplatform.tex +++ /dev/null @@ -1,238 +0,0 @@ -\section{\module{platform} --- - Access to underlying platform's identifying data.} - -\declaremodule{standard}{platform} -\modulesynopsis{Retrieves as much platform identifying data as possible.} -\moduleauthor{Marc-Andre Lemburg}{mal@egenix.com} -\sectionauthor{Bjorn Pettersen}{bpettersen@corp.fairisaac.com} - -\versionadded{2.3} - -\begin{notice} - Specific platforms listed alphabetically, with Linux included in the - \UNIX{} section. -\end{notice} - -\subsection{Cross Platform} - -\begin{funcdesc}{architecture}{executable=sys.executable, bits='', linkage=''} - Queries the given executable (defaults to the Python interpreter - binary) for various architecture information. - - Returns a tuple \code{(bits, linkage)} which contain information about - the bit architecture and the linkage format used for the - executable. Both values are returned as strings. - - Values that cannot be determined are returned as given by the - parameter presets. If bits is given as \code{''}, the - \cfunction{sizeof(pointer)} - (or \cfunction{sizeof(long)} on Python version < 1.5.2) is used as - indicator for the supported pointer size. - - The function relies on the system's \file{file} command to do the - actual work. This is available on most if not all \UNIX{} - platforms and some non-\UNIX{} platforms and then only if the - executable points to the Python interpreter. Reasonable defaults - are used when the above needs are not met. -\end{funcdesc} - -\begin{funcdesc}{machine}{} - Returns the machine type, e.g. \code{'i386'}. - An empty string is returned if the value cannot be determined. -\end{funcdesc} - -\begin{funcdesc}{node}{} - Returns the computer's network name (may not be fully qualified!). - An empty string is returned if the value cannot be determined. -\end{funcdesc} - -\begin{funcdesc}{platform}{aliased=0, terse=0} - Returns a single string identifying the underlying platform - with as much useful information as possible. - - The output is intended to be \emph{human readable} rather than - machine parseable. It may look different on different platforms and - this is intended. - - If \var{aliased} is true, the function will use aliases for various - platforms that report system names which differ from their common - names, for example SunOS will be reported as Solaris. The - \function{system_alias()} function is used to implement this. - - Setting \var{terse} to true causes the function to return only the - absolute minimum information needed to identify the platform. -\end{funcdesc} - -\begin{funcdesc}{processor}{} - Returns the (real) processor name, e.g. \code{'amdk6'}. - - An empty string is returned if the value cannot be determined. Note - that many platforms do not provide this information or simply return - the same value as for \function{machine()}. NetBSD does this. -\end{funcdesc} - -\begin{funcdesc}{python_build}{} - Returns a tuple \code{(\var{buildno}, \var{builddate})} stating the - Python build number and date as strings. -\end{funcdesc} - -\begin{funcdesc}{python_compiler}{} - Returns a string identifying the compiler used for compiling Python. -\end{funcdesc} - -\begin{funcdesc}{python_branch}{} - Returns a string identifying the Python implementation SCM branch. - \versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{python_implementation}{} - Returns a string identifying the Python implementation. - Possible return values are: 'CPython', 'IronPython', 'Jython' - \versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{python_revision}{} - Returns a string identifying the Python implementation SCM revision. - \versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{python_version}{} - Returns the Python version as string \code{'major.minor.patchlevel'} - - Note that unlike the Python \code{sys.version}, the returned value - will always include the patchlevel (it defaults to 0). -\end{funcdesc} - -\begin{funcdesc}{python_version_tuple}{} - Returns the Python version as tuple \code{(\var{major}, \var{minor}, - \var{patchlevel})} of strings. - - Note that unlike the Python \code{sys.version}, the returned value - will always include the patchlevel (it defaults to \code{'0'}). -\end{funcdesc} - -\begin{funcdesc}{release}{} - Returns the system's release, e.g. \code{'2.2.0'} or \code{'NT'} - An empty string is returned if the value cannot be determined. -\end{funcdesc} - -\begin{funcdesc}{system}{} - Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'}, - or \code{'Java'}. - An empty string is returned if the value cannot be determined. -\end{funcdesc} - -\begin{funcdesc}{system_alias}{system, release, version} - Returns \code{(\var{system}, \var{release}, \var{version})} aliased - to common marketing names used for some systems. It also does some - reordering of the information in some cases where it would otherwise - cause confusion. -\end{funcdesc} - -\begin{funcdesc}{version}{} - Returns the system's release version, e.g. \code{'\#3 on degas'}. - An empty string is returned if the value cannot be determined. -\end{funcdesc} - -\begin{funcdesc}{uname}{} - Fairly portable uname interface. Returns a tuple of strings - \code{(\var{system}, \var{node}, \var{release}, \var{version}, - \var{machine}, \var{processor})} identifying the underlying - platform. - - Note that unlike the \function{os.uname()} function this also returns - possible processor information as additional tuple entry. - - Entries which cannot be determined are set to \code{''}. -\end{funcdesc} - - -\subsection{Java Platform} - -\begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''), - osinfo=('','','')} - Version interface for JPython. - - Returns a tuple \code{(\var{release}, \var{vendor}, \var{vminfo}, - \var{osinfo})} with \var{vminfo} being a tuple \code{(\var{vm_name}, - \var{vm_release}, \var{vm_vendor})} and \var{osinfo} being a tuple - \code{(\var{os_name}, \var{os_version}, \var{os_arch})}. - Values which cannot be determined are set to the defaults - given as parameters (which all default to \code{''}). -\end{funcdesc} - - -\subsection{Windows Platform} - -\begin{funcdesc}{win32_ver}{release='', version='', csd='', ptype=''} - Get additional version information from the Windows Registry - and return a tuple \code{(\var{version}, \var{csd}, \var{ptype})} - referring to version number, CSD level and OS type (multi/single - processor). - - As a hint: \var{ptype} is \code{'Uniprocessor Free'} on single - processor NT machines and \code{'Multiprocessor Free'} on multi - processor machines. The \emph{'Free'} refers to the OS version being - free of debugging code. It could also state \emph{'Checked'} which - means the OS version uses debugging code, i.e. code that - checks arguments, ranges, etc. - - \begin{notice}[note] - This function only works if Mark Hammond's \module{win32all} - package is installed and (obviously) only runs on Win32 - compatible platforms. - \end{notice} -\end{funcdesc} - -\subsubsection{Win95/98 specific} - -\begin{funcdesc}{popen}{cmd, mode='r', bufsize=None} - Portable \function{popen()} interface. Find a working popen - implementation preferring \function{win32pipe.popen()}. On Windows - NT, \function{win32pipe.popen()} should work; on Windows 9x it hangs - due to bugs in the MS C library. - % This KnowledgeBase article appears to be missing... - %See also \ulink{MS KnowledgeBase article Q150956}{}. -\end{funcdesc} - - -\subsection{Mac OS Platform} - -\begin{funcdesc}{mac_ver}{release='', versioninfo=('','',''), machine=''} - Get Mac OS version information and return it as tuple - \code{(\var{release}, \var{versioninfo}, \var{machine})} with - \var{versioninfo} being a tuple \code{(\var{version}, - \var{dev_stage}, \var{non_release_version})}. - - Entries which cannot be determined are set to \code{''}. All tuple - entries are strings. - - Documentation for the underlying \cfunction{gestalt()} API is - available online at \url{http://www.rgaros.nl/gestalt/}. -\end{funcdesc} - - -\subsection{\UNIX{} Platforms} - -\begin{funcdesc}{dist}{distname='', version='', id='', - supported_dists=('SuSE','debian','redhat','mandrake')} - Tries to determine the name of the OS distribution name - Returns a tuple \code{(\var{distname}, \var{version}, \var{id})} - which defaults to the args given as parameters. -\end{funcdesc} - -% Document linux_distribution()? - -\begin{funcdesc}{libc_ver}{executable=sys.executable, lib='', - version='', chunksize=2048} - Tries to determine the libc version against which the file - executable (defaults to the Python interpreter) is linked. Returns - a tuple of strings \code{(\var{lib}, \var{version})} which default - to the given parameters in case the lookup fails. - - Note that this function has intimate knowledge of how different - libc versions add symbols to the executable is probably only - useable for executables compiled using \program{gcc}. - - The file is read and scanned in chunks of \var{chunksize} bytes. -\end{funcdesc} diff --git a/Doc/lib/libpoplib.tex b/Doc/lib/libpoplib.tex deleted file mode 100644 index 9ca5bbd..0000000 --- a/Doc/lib/libpoplib.tex +++ /dev/null @@ -1,187 +0,0 @@ -\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''. -%Revised by ESR, January 2000 - -\indexii{POP3}{protocol} - -This module defines a class, \class{POP3}, which encapsulates a -connection to a POP3 server and implements the protocol as defined in -\rfc{1725}. The \class{POP3} class supports both the minimal and -optional command sets. Additionally, this module provides a class -\class{POP3_SSL}, which provides support for connecting to POP3 -servers that use SSL as an underlying protocol layer. - - -Note that POP3, though widely supported, is obsolescent. The -implementation quality of POP3 servers varies widely, and too many are -quite poor. If your mailserver supports IMAP, you would be better off -using the \class{\refmodule{imaplib}.IMAP4} class, as IMAP -servers tend to be better implemented. - -A single class is provided by the \module{poplib} module: - -\begin{classdesc}{POP3}{host\optional{, port\optional{, timeout}}} -This class implements the actual POP3 protocol. The connection is -created when the instance is initialized. -If \var{port} is omitted, the standard POP3 port (110) is used. -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if not specified, or passed as None, the global default -timeout setting will be used). - -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - -\begin{classdesc}{POP3_SSL}{host\optional{, port\optional{, keyfile\optional{, certfile}}}} -This is a subclass of \class{POP3} that connects to the server over an -SSL encrypted socket. If \var{port} is not specified, 995, the -standard POP3-over-SSL port is used. \var{keyfile} and \var{certfile} -are also optional - they can contain a PEM formatted private key and -certificate chain file for the SSL connection. - -\versionadded{2.4} -\end{classdesc} - -One exception is defined as an attribute of the \module{poplib} module: - -\begin{excdesc}{error_proto} -Exception raised on any errors from this module (errors from -\module{socket} module are not caught). The reason for the exception -is passed to the constructor as a string. -\end{excdesc} - -\begin{seealso} - \seemodule{imaplib}{The standard Python IMAP module.} - \seetitle[http://www.catb.org/\~{}esr/fetchmail/fetchmail-FAQ.html] - {Frequently Asked Questions About Fetchmail} - {The FAQ for the \program{fetchmail} POP/IMAP client collects - information on POP3 server variations and RFC noncompliance - that may be useful if you need to write an application based - on the POP protocol.} -\end{seealso} - - -\subsection{POP3 Objects \label{pop3-objects}} - -All POP3 commands are represented by methods of the same name, -in lower-case; most return the response text sent by the server. - -An \class{POP3} instance has the following methods: - - -\begin{methoddesc}[POP3]{set_debuglevel}{level} -Set the instance's debugging level. This controls the amount of -debugging output printed. The default, \code{0}, produces no -debugging output. A value of \code{1} produces a moderate amount of -debugging output, generally a single line per request. A value of -\code{2} or higher produces the maximum amount of debugging output, -logging each line sent and received on the control connection. -\end{methoddesc} - -\begin{methoddesc}[POP3]{getwelcome}{} -Returns the greeting string sent by the POP3 server. -\end{methoddesc} - -\begin{methoddesc}[POP3]{user}{username} -Send user command, response should indicate that a password is required. -\end{methoddesc} - -\begin{methoddesc}[POP3]{pass_}{password} -Send password, response includes message count and mailbox size. -Note: the mailbox on the server is locked until \method{quit()} is -called. -\end{methoddesc} - -\begin{methoddesc}[POP3]{apop}{user, secret} -Use the more secure APOP authentication to log into the POP3 server. -\end{methoddesc} - -\begin{methoddesc}[POP3]{rpop}{user} -Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server. -\end{methoddesc} - -\begin{methoddesc}[POP3]{stat}{} -Get mailbox status. The result is a tuple of 2 integers: -\code{(\var{message count}, \var{mailbox size})}. -\end{methoddesc} - -\begin{methoddesc}[POP3]{list}{\optional{which}} -Request message list, result is in the form -\code{(\var{response}, ['mesg_num octets', ...], \var{octets})}. -If \var{which} is set, it is the message to list. -\end{methoddesc} - -\begin{methoddesc}[POP3]{retr}{which} -Retrieve whole message number \var{which}, and set its seen flag. -Result is in form \code{(\var{response}, ['line', ...], \var{octets})}. -\end{methoddesc} - -\begin{methoddesc}[POP3]{dele}{which} -Flag message number \var{which} for deletion. On most servers -deletions are not actually performed until QUIT (the major exception is -Eudora QPOP, which deliberately violates the RFCs by doing pending -deletes on any disconnect). -\end{methoddesc} - -\begin{methoddesc}[POP3]{rset}{} -Remove any deletion marks for the mailbox. -\end{methoddesc} - -\begin{methoddesc}[POP3]{noop}{} -Do nothing. Might be used as a keep-alive. -\end{methoddesc} - -\begin{methoddesc}[POP3]{quit}{} -Signoff: commit changes, unlock mailbox, drop connection. -\end{methoddesc} - -\begin{methoddesc}[POP3]{top}{which, howmuch} -Retrieves the message header plus \var{howmuch} lines of the message -after the header of message number \var{which}. Result is in form -\code{(\var{response}, ['line', ...], \var{octets})}. - -The POP3 TOP command this method uses, unlike the RETR command, -doesn't set the message's seen flag; unfortunately, TOP is poorly -specified in the RFCs and is frequently broken in off-brand servers. -Test this method by hand against the POP3 servers you will use before -trusting it. -\end{methoddesc} - -\begin{methoddesc}[POP3]{uidl}{\optional{which}} -Return message digest (unique id) list. -If \var{which} is specified, result contains the unique id for that -message in the form \code{'\var{response}\ \var{mesgnum}\ \var{uid}}, -otherwise result is list \code{(\var{response}, ['mesgnum uid', ...], -\var{octets})}. -\end{methoddesc} - -Instances of \class{POP3_SSL} have no additional methods. The -interface of this subclass is identical to its parent. - - -\subsection{POP3 Example \label{pop3-example}} - -Here is a minimal example (without error checking) that opens a -mailbox and retrieves and prints all messages: - -\begin{verbatim} -import getpass, poplib - -M = poplib.POP3('localhost') -M.user(getpass.getuser()) -M.pass_(getpass.getpass()) -numMessages = len(M.list()[1]) -for i in range(numMessages): - for j in M.retr(i+1)[1]: - print j -\end{verbatim} - -At the end of the module, there is a test section that contains a more -extensive example of usage. diff --git a/Doc/lib/libposix.tex b/Doc/lib/libposix.tex deleted file mode 100644 index aee6c0d..0000000 --- a/Doc/lib/libposix.tex +++ /dev/null @@ -1,97 +0,0 @@ -\section{\module{posix} --- - The most common \POSIX{} system calls} - -\declaremodule{builtin}{posix} - \platform{Unix} -\modulesynopsis{The most common \POSIX\ system calls (normally used - via module \refmodule{os}).} - - -This module provides access to operating system functionality that is -standardized by the C Standard and the \POSIX{} standard (a thinly -disguised \UNIX{} interface). - -\strong{Do not import this module directly.} Instead, import the -module \refmodule{os}, which provides a \emph{portable} version of this -interface. On \UNIX, the \refmodule{os} module provides a superset of -the \module{posix} interface. On non-\UNIX{} operating systems the -\module{posix} module is not available, but a subset is always -available through the \refmodule{os} interface. Once \refmodule{os} is -imported, there is \emph{no} performance penalty in using it instead -of \module{posix}. In addition, \refmodule{os}\refstmodindex{os} -provides some additional functionality, such as automatically calling -\function{putenv()} when an entry in \code{os.environ} is changed. - -The descriptions below are very terse; refer to the corresponding -\UNIX{} manual (or \POSIX{} documentation) entry for more information. -Arguments called \var{path} refer to a pathname given as a string. - -Errors are reported as exceptions; the usual exceptions are given for -type errors, while errors reported by the system calls raise -\exception{error} (a synonym for the standard exception -\exception{OSError}), described below. - - -\subsection{Large File Support \label{posix-large-files}} -\sectionauthor{Steve Clift}{clift@mail.anacapa.net} -\index{large files} -\index{file!large files} - - -Several operating systems (including AIX, HPUX, Irix and Solaris) -provide support for files that are larger than 2 Gb from a C -programming model where \ctype{int} and \ctype{long} are 32-bit -values. This is typically accomplished by defining the relevant size -and offset types as 64-bit values. Such files are sometimes referred -to as \dfn{large files}. - -Large file support is enabled in Python when the size of an -\ctype{off_t} is larger than a \ctype{long} and the \ctype{long long} -type is available and is at least as large as an \ctype{off_t}. Python -longs are then used to represent file sizes, offsets and other values -that can exceed the range of a Python int. It may be necessary to -configure and compile Python with certain compiler flags to enable -this mode. For example, it is enabled by default with recent versions -of Irix, but with Solaris 2.6 and 2.7 you need to do something like: - -\begin{verbatim} -CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \ - ./configure -\end{verbatim} % $ <-- bow to font-lock - -On large-file-capable Linux systems, this might work: - -\begin{verbatim} -CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \ - ./configure -\end{verbatim} % $ <-- bow to font-lock - - -\subsection{Module Contents \label{posix-contents}} - - -Module \module{posix} defines the following data item: - -\begin{datadesc}{environ} -A dictionary representing the string environment at the time the -interpreter was started. For example, \code{environ['HOME']} is the -pathname of your home directory, equivalent to -\code{getenv("HOME")} in C. - -Modifying this dictionary does not affect the string environment -passed on by \function{execv()}, \function{popen()} or -\function{system()}; if you need to change the environment, pass -\code{environ} to \function{execve()} or add variable assignments and -export statements to the command string for \function{system()} or -\function{popen()}. - -\note{The \refmodule{os} module provides an alternate -implementation of \code{environ} which updates the environment on -modification. Note also that updating \code{os.environ} will render -this dictionary obsolete. Use of the \refmodule{os} module version of -this is recommended over direct access to the \module{posix} module.} -\end{datadesc} - -Additional contents of this module should only be accessed via the -\refmodule{os} module; refer to the documentation for that module for -further information. diff --git a/Doc/lib/libposixpath.tex b/Doc/lib/libposixpath.tex deleted file mode 100644 index 7684fa0..0000000 --- a/Doc/lib/libposixpath.tex +++ /dev/null @@ -1,300 +0,0 @@ -\section{\module{os.path} --- - Common pathname manipulations} -\declaremodule{standard}{os.path} - -\modulesynopsis{Common pathname manipulations.} - -This module implements some useful functions on pathnames. -\index{path!operations} - -\warning{On Windows, many of these functions do not properly -support UNC pathnames. \function{splitunc()} and \function{ismount()} -do handle them correctly.} - - -\begin{funcdesc}{abspath}{path} -Return a normalized absolutized version of the pathname \var{path}. -On most platforms, this is equivalent to -\code{normpath(join(os.getcwd(), \var{path}))}. -\versionadded{1.5.2} -\end{funcdesc} - -\begin{funcdesc}{basename}{path} -Return the base name of pathname \var{path}. This is the second half -of the pair returned by \code{split(\var{path})}. Note that the -result of this function is different from the -\UNIX{} \program{basename} program; where \program{basename} for -\code{'/foo/bar/'} returns \code{'bar'}, the \function{basename()} -function returns an empty string (\code{''}). -\end{funcdesc} - -\begin{funcdesc}{commonprefix}{list} -Return the longest path prefix (taken character-by-character) that is a -prefix of all paths in -\var{list}. If \var{list} is empty, return the empty string -(\code{''}). Note that this may return invalid paths because it works a -character at a time. -\end{funcdesc} - -\begin{funcdesc}{dirname}{path} -Return the directory name of pathname \var{path}. This is the first -half of the pair returned by \code{split(\var{path})}. -\end{funcdesc} - -\begin{funcdesc}{exists}{path} -Return \code{True} if \var{path} refers to an existing path. Returns -\code{False} for broken symbolic links. On some platforms, this -function may return \code{False} if permission is not granted to -execute \function{os.stat()} on the requested file, even if the -\var{path} physically exists. -\end{funcdesc} - -\begin{funcdesc}{lexists}{path} -Return \code{True} if \var{path} refers to an existing path. -Returns \code{True} for broken symbolic links. -Equivalent to \function{exists()} on platforms lacking -\function{os.lstat()}. -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{expanduser}{path} -On \UNIX{} and Windows, return the argument with an initial component of -\samp{\~} or \samp{\~\var{user}} replaced by that \var{user}'s home directory. - -On \UNIX, an initial \samp{\~} is replaced by the environment variable -\envvar{HOME} if it is set; otherwise the current user's home directory -is looked up in the password directory through the built-in module -\refmodule{pwd}\refbimodindex{pwd}. -An initial \samp{\~\var{user}} is looked up directly in the -password directory. - -On Windows, \envvar{HOME} and \envvar{USERPROFILE} will be used if set, -otherwise a combination of \envvar{HOMEPATH} and \envvar{HOMEDRIVE} will be -used. An initial \samp{\~\var{user}} is handled by stripping the last -directory component from the created user path derived above. - -If the expansion fails or if the -path does not begin with a tilde, the path is returned unchanged. -\end{funcdesc} - -\begin{funcdesc}{expandvars}{path} -Return the argument with environment variables expanded. Substrings -of the form \samp{\$\var{name}} or \samp{\$\{\var{name}\}} are -replaced by the value of environment variable \var{name}. Malformed -variable names and references to non-existing variables are left -unchanged. - -On Windows, \samp{\%\var{name}\%} expansions are supported in addition to -\samp{\$\var{name}} and \samp{\$\{\var{name}\}}. -\end{funcdesc} - -\begin{funcdesc}{getatime}{path} -Return the time of last access of \var{path}. The return -value is a number giving the number of seconds since the epoch (see the -\refmodule{time} module). Raise \exception{os.error} if the file does -not exist or is inaccessible. -\versionadded{1.5.2} -\versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3} -\end{funcdesc} - -\begin{funcdesc}{getmtime}{path} -Return the time of last modification of \var{path}. The return -value is a number giving the number of seconds since the epoch (see the -\refmodule{time} module). Raise \exception{os.error} if the file does -not exist or is inaccessible. -\versionadded{1.5.2} -\versionchanged[If \function{os.stat_float_times()} returns True, the result is a floating point number]{2.3} -\end{funcdesc} - -\begin{funcdesc}{getctime}{path} -Return the system's ctime which, on some systems (like \UNIX) is the -time of the last change, and, on others (like Windows), is the -creation time for \var{path}. The return -value is a number giving the number of seconds since the epoch (see the -\refmodule{time} module). Raise \exception{os.error} if the file does -not exist or is inaccessible. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{getsize}{path} -Return the size, in bytes, of \var{path}. Raise -\exception{os.error} if the file does not exist or is inaccessible. -\versionadded{1.5.2} -\end{funcdesc} - -\begin{funcdesc}{isabs}{path} -Return \code{True} if \var{path} is an absolute pathname (begins with a -slash). -\end{funcdesc} - -\begin{funcdesc}{isfile}{path} -Return \code{True} if \var{path} is an existing regular file. This follows -symbolic links, so both \function{islink()} and \function{isfile()} -can be true for the same path. -\end{funcdesc} - -\begin{funcdesc}{isdir}{path} -Return \code{True} if \var{path} is an existing directory. This follows -symbolic links, so both \function{islink()} and \function{isdir()} can -be true for the same path. -\end{funcdesc} - -\begin{funcdesc}{islink}{path} -Return \code{True} if \var{path} refers to a directory entry that is a -symbolic link. Always \code{False} if symbolic links are not supported. -\end{funcdesc} - -\begin{funcdesc}{ismount}{path} -Return \code{True} if pathname \var{path} is a \dfn{mount point}: a point in -a file system where a different file system has been mounted. The -function checks whether \var{path}'s parent, \file{\var{path}/..}, is -on a different device than \var{path}, or whether \file{\var{path}/..} -and \var{path} point to the same i-node on the same device --- this -should detect mount points for all \UNIX{} and \POSIX{} variants. -\end{funcdesc} - -\begin{funcdesc}{join}{path1\optional{, path2\optional{, ...}}} -Join one or more path components intelligently. If any component is -an absolute path, all previous components (on Windows, including the -previous drive letter, if there was one) are thrown away, and joining -continues. The return value is the concatenation of \var{path1}, and -optionally \var{path2}, etc., with exactly one directory separator -(\code{os.sep}) inserted between components, unless \var{path2} is -empty. Note that on Windows, since there is a current directory for -each drive, \function{os.path.join("c:", "foo")} represents a path -relative to the current directory on drive \file{C:} (\file{c:foo}), not -\file{c:\textbackslash\textbackslash foo}. -\end{funcdesc} - -\begin{funcdesc}{normcase}{path} -Normalize the case of a pathname. On \UNIX, this returns the path -unchanged; on case-insensitive filesystems, it converts the path to -lowercase. On Windows, it also converts forward slashes to backward -slashes. -\end{funcdesc} - -\begin{funcdesc}{normpath}{path} -Normalize a pathname. This collapses redundant separators and -up-level references so that \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 converts -forward slashes to backward slashes. It should be understood that this may -change the meaning of the path if it contains symbolic links! -\end{funcdesc} - -\begin{funcdesc}{realpath}{path} -Return the canonical path of the specified filename, eliminating any -symbolic links encountered in the path (if they are supported by the -operating system). -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{relpath}{path\optional{, start}} -Return a relative filepath to \var{path} either from the current -directory or from an optional \var{start} point. - -\var{start} defaults to \member{os.curdir}. -Availability: Windows, \UNIX. -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{samefile}{path1, path2} -Return \code{True} if both pathname arguments refer to the same file or -directory (as indicated by device number and i-node number). -Raise an exception if a \function{os.stat()} call on either pathname -fails. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{sameopenfile}{fp1, fp2} -Return \code{True} if the file descriptors \var{fp1} and \var{fp2} refer -to the same file. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{samestat}{stat1, stat2} -Return \code{True} if the stat tuples \var{stat1} and \var{stat2} refer to -the same file. These structures may have been returned by -\function{fstat()}, \function{lstat()}, or \function{stat()}. This -function implements the underlying comparison used by -\function{samefile()} and \function{sameopenfile()}. -Availability: Macintosh, \UNIX. -\end{funcdesc} - -\begin{funcdesc}{split}{path} -Split the pathname \var{path} into a pair, \code{(\var{head}, -\var{tail})} where \var{tail} is the last pathname component and -\var{head} is everything leading up to that. The \var{tail} part will -never contain a slash; if \var{path} ends in a slash, \var{tail} will -be empty. If there is no slash in \var{path}, \var{head} will be -empty. If \var{path} is empty, both \var{head} and \var{tail} are -empty. Trailing slashes are stripped from \var{head} unless it is the -root (one or more slashes only). In nearly all cases, -\code{join(\var{head}, \var{tail})} equals \var{path} (the only -exception being when there were multiple slashes separating \var{head} -from \var{tail}). -\end{funcdesc} - -\begin{funcdesc}{splitdrive}{path} -Split the pathname \var{path} into a pair \code{(\var{drive}, -\var{tail})} where \var{drive} is either a drive specification or the -empty string. On systems which do not use drive specifications, -\var{drive} will always be the empty string. In all cases, -\code{\var{drive} + \var{tail}} will be the same as \var{path}. -\versionadded{1.3} -\end{funcdesc} - -\begin{funcdesc}{splitext}{path} -Split the pathname \var{path} into a pair \code{(\var{root}, \var{ext})} -such that \code{\var{root} + \var{ext} == \var{path}}, -and \var{ext} is empty or begins with a period and contains -at most one period. Leading periods on the basename are -ignored; \code{\var{splitext}.('.cshrc')} returns -\code{('.cshrc', '')}. - -\versionchanged[Earlier versions could produce an empty root when -the only period was the first character]{2.6} -\end{funcdesc} - -\begin{funcdesc}{splitunc}{path} -Split the pathname \var{path} into a pair \code{(\var{unc}, \var{rest})} -so that \var{unc} is the UNC mount point (such as \code{r'\e\e host\e mount'}), -if present, and \var{rest} the rest of the path (such as -\code{r'\e path\e file.ext'}). For paths containing drive letters, \var{unc} -will always be the empty string. -Availability: Windows. -\end{funcdesc} - -\begin{funcdesc}{walk}{path, visit, arg} -Calls the function \var{visit} with arguments -\code{(\var{arg}, \var{dirname}, \var{names})} for each directory in the -directory tree rooted at \var{path} (including \var{path} itself, if it -is a directory). The argument \var{dirname} specifies the visited -directory, the argument \var{names} lists the files in the directory -(gotten from \code{os.listdir(\var{dirname})}). -The \var{visit} function may modify \var{names} to -influence the set of directories visited below \var{dirname}, e.g. to -avoid visiting certain parts of the tree. (The object referred to by -\var{names} must be modified in place, using \keyword{del} or slice -assignment.) - -\begin{notice} -Symbolic links to directories are not treated as subdirectories, and -that \function{walk()} therefore will not visit them. To visit linked -directories you must identify them with -\code{os.path.islink(\var{file})} and -\code{os.path.isdir(\var{file})}, and invoke \function{walk()} as -necessary. -\end{notice} - -\note{The newer \function{\refmodule{os}.walk()} generator supplies - similar functionality and can be easier to use.} -\end{funcdesc} - -\begin{datadesc}{supports_unicode_filenames} -True if arbitrary Unicode strings can be used as file names (within -limitations imposed by the file system), and if -\function{os.listdir()} returns Unicode strings for a Unicode -argument. -\versionadded{2.3} -\end{datadesc} diff --git a/Doc/lib/libpprint.tex b/Doc/lib/libpprint.tex deleted file mode 100644 index ce35b44..0000000 --- a/Doc/lib/libpprint.tex +++ /dev/null @@ -1,210 +0,0 @@ -\section{\module{pprint} --- - Data pretty printer} - -\declaremodule{standard}{pprint} -\modulesynopsis{Data pretty printer.} -\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -The \module{pprint} module provides a capability to ``pretty-print'' -arbitrary Python data structures in a form which can be used as input -to the interpreter. If the formatted structures include objects which -are not fundamental Python types, the representation may not be -loadable. This may be the case if objects such as files, sockets, -classes, or instances are included, as well as many other builtin -objects which are not representable as Python constants. - -The formatted representation keeps objects on a single line if it can, -and breaks them onto multiple lines if they don't fit within the -allowed width. Construct \class{PrettyPrinter} objects explicitly if -you need to adjust the width constraint. - -\versionchanged[Dictionaries are sorted by key before the display is -computed; before 2.5, a dictionary was sorted only if its display -required more than one line, although that wasn't documented]{2.5} - -The \module{pprint} module defines one class: - - -% First the implementation class: - -\begin{classdesc}{PrettyPrinter}{...} -Construct a \class{PrettyPrinter} instance. This constructor -understands several keyword parameters. An output stream may be set -using the \var{stream} keyword; the only method used on the stream -object is the file protocol's \method{write()} method. If not -specified, the \class{PrettyPrinter} adopts \code{sys.stdout}. Three -additional parameters may be used to control the formatted -representation. The keywords are \var{indent}, \var{depth}, and -\var{width}. The amount of indentation added for each recursive level -is specified by \var{indent}; the default is one. Other values can -cause output to look a little odd, but can make nesting easier to -spot. The number of levels which may be printed is controlled by -\var{depth}; if the data structure being printed is too deep, the next -contained level is replaced by \samp{...}. By default, there is no -constraint on the depth of the objects being formatted. The desired -output width is constrained using the \var{width} parameter; the -default is eighty characters. If a structure cannot be formatted -within the constrained width, a best effort will be made. - -\begin{verbatim} ->>> import pprint, sys ->>> stuff = sys.path[:] ->>> stuff.insert(0, stuff[:]) ->>> pp = pprint.PrettyPrinter(indent=4) ->>> pp.pprint(stuff) -[ [ '', - '/usr/local/lib/python1.5', - '/usr/local/lib/python1.5/test', - '/usr/local/lib/python1.5/sunos5', - '/usr/local/lib/python1.5/sharedmodules', - '/usr/local/lib/python1.5/tkinter'], - '', - '/usr/local/lib/python1.5', - '/usr/local/lib/python1.5/test', - '/usr/local/lib/python1.5/sunos5', - '/usr/local/lib/python1.5/sharedmodules', - '/usr/local/lib/python1.5/tkinter'] ->>> ->>> import parser ->>> tup = parser.ast2tuple( -... parser.suite(open('pprint.py').read()))[1][1][1] ->>> pp = pprint.PrettyPrinter(depth=6) ->>> pp.pprint(tup) -(266, (267, (307, (287, (288, (...)))))) -\end{verbatim} -\end{classdesc} - - -% Now the derivative functions: - -The \class{PrettyPrinter} class supports several derivative functions: - -\begin{funcdesc}{pformat}{object\optional{, indent\optional{, -width\optional{, depth}}}} -Return the formatted representation of \var{object} as a string. \var{indent}, -\var{width} and \var{depth} will be passed to the \class{PrettyPrinter} -constructor as formatting parameters. -\versionchanged[The parameters \var{indent}, \var{width} and \var{depth} -were added]{2.4} -\end{funcdesc} - -\begin{funcdesc}{pprint}{object\optional{, stream\optional{, -indent\optional{, width\optional{, depth}}}}} -Prints the formatted representation of \var{object} on \var{stream}, -followed by a newline. If \var{stream} is omitted, \code{sys.stdout} -is used. This may be used in the interactive interpreter instead of a -\keyword{print} statement for inspecting values. \var{indent}, -\var{width} and \var{depth} will be passed to the \class{PrettyPrinter} -constructor as formatting parameters. - -\begin{verbatim} ->>> stuff = sys.path[:] ->>> stuff.insert(0, stuff) ->>> pprint.pprint(stuff) -[<Recursion on list with id=869440>, - '', - '/usr/local/lib/python1.5', - '/usr/local/lib/python1.5/test', - '/usr/local/lib/python1.5/sunos5', - '/usr/local/lib/python1.5/sharedmodules', - '/usr/local/lib/python1.5/tkinter'] -\end{verbatim} -\versionchanged[The parameters \var{indent}, \var{width} and \var{depth} -were added]{2.4} -\end{funcdesc} - -\begin{funcdesc}{isreadable}{object} -Determine if the formatted representation of \var{object} is -``readable,'' or can be used to reconstruct the value using -\function{eval()}\bifuncindex{eval}. This always returns \code{False} for -recursive objects. - -\begin{verbatim} ->>> pprint.isreadable(stuff) -False -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{isrecursive}{object} -Determine if \var{object} requires a recursive representation. -\end{funcdesc} - - -One more support function is also defined: - -\begin{funcdesc}{saferepr}{object} -Return a string representation of \var{object}, protected against -recursive data structures. If the representation of \var{object} -exposes a recursive entry, the recursive reference will be represented -as \samp{<Recursion on \var{typename} with id=\var{number}>}. The -representation is not otherwise formatted. -\end{funcdesc} - -% This example is outside the {funcdesc} to keep it from running over -% the right margin. -\begin{verbatim} ->>> pprint.saferepr(stuff) -"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca -l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python -1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']" -\end{verbatim} - - -\subsection{PrettyPrinter Objects} -\label{PrettyPrinter Objects} - -\class{PrettyPrinter} instances have the following methods: - - -\begin{methoddesc}[PrettyPrinter]{pformat}{object} -Return the formatted representation of \var{object}. This takes into -account the options passed to the \class{PrettyPrinter} constructor. -\end{methoddesc} - -\begin{methoddesc}[PrettyPrinter]{pprint}{object} -Print the formatted representation of \var{object} on the configured -stream, followed by a newline. -\end{methoddesc} - -The following methods provide the implementations for the -corresponding functions of the same names. Using these methods on an -instance is slightly more efficient since new \class{PrettyPrinter} -objects don't need to be created. - -\begin{methoddesc}[PrettyPrinter]{isreadable}{object} -Determine if the formatted representation of the object is -``readable,'' or can be used to reconstruct the value using -\function{eval()}\bifuncindex{eval}. Note that this returns \code{False} for -recursive objects. If the \var{depth} parameter of the -\class{PrettyPrinter} is set and the object is deeper than allowed, -this returns \code{False}. -\end{methoddesc} - -\begin{methoddesc}[PrettyPrinter]{isrecursive}{object} -Determine if the object requires a recursive representation. -\end{methoddesc} - -This method is provided as a hook to allow subclasses to modify the -way objects are converted to strings. The default implementation uses -the internals of the \function{saferepr()} implementation. - -\begin{methoddesc}[PrettyPrinter]{format}{object, context, maxlevels, level} -Returns three values: the formatted version of \var{object} as a -string, a flag indicating whether the result is readable, and a flag -indicating whether recursion was detected. The first argument is the -object to be presented. The second is a dictionary which contains the -\function{id()} of objects that are part of the current presentation -context (direct and indirect containers for \var{object} that are -affecting the presentation) as the keys; if an object needs to be -presented which is already represented in \var{context}, the third -return value should be \code{True}. Recursive calls to the \method{format()} -method should add additional entries for containers to this -dictionary. The third argument, \var{maxlevels}, gives the requested -limit to recursion; this will be \code{0} if there is no requested -limit. This argument should be passed unmodified to recursive calls. -The fourth argument, \var{level}, gives the current level; recursive -calls should be passed a value less than that of the current call. -\versionadded{2.3} -\end{methoddesc} diff --git a/Doc/lib/libprofile.tex b/Doc/lib/libprofile.tex deleted file mode 100644 index 79a168c..0000000 --- a/Doc/lib/libprofile.tex +++ /dev/null @@ -1,722 +0,0 @@ -\chapter{The Python Profilers \label{profile}} - -\sectionauthor{James Roskind}{} - -Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved. -\index{InfoSeek Corporation} - -Written by James Roskind.\footnote{ - Updated and converted to \LaTeX\ by Guido van Rossum. - Further updated by Armin Rigo to integrate the documentation for the new - \module{cProfile} module of Python 2.5.} - -Permission to use, copy, modify, and distribute this Python software -and its associated documentation for any purpose (subject to the -restriction in the following sentence) without fee is hereby granted, -provided that the above copyright notice appears in all copies, and -that both that copyright notice and this permission notice appear in -supporting documentation, and that the name of InfoSeek not be used in -advertising or publicity pertaining to distribution of the software -without specific, written prior permission. This permission is -explicitly restricted to the copying and modification of the software -to remain in Python, compiled Python, or other languages (such as C) -wherein the modified or derived code is exclusively imported into a -Python module. - -INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS -SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND -FITNESS. IN NO EVENT SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY -SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER -RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF -CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN -CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - - -The profiler was written after only programming in Python for 3 weeks. -As a result, it is probably clumsy code, but I don't know for sure yet -'cause I'm a beginner :-). I did work hard to make the code run fast, -so that profiling would be a reasonable thing to do. I tried not to -repeat code fragments, but I'm sure I did some stuff in really awkward -ways at times. Please send suggestions for improvements to: -\email{jar@netscape.com}. I won't promise \emph{any} support. ...but -I'd appreciate the feedback. - - -\section{Introduction to the profilers} -\nodename{Profiler Introduction} - -A \dfn{profiler} is a program that describes the run time performance -of a program, providing a variety of statistics. This documentation -describes the profiler functionality provided in the modules -\module{profile} and \module{pstats}. This profiler provides -\dfn{deterministic profiling} of any Python programs. It also -provides a series of report generation tools to allow users to rapidly -examine the results of a profile operation. -\index{deterministic profiling} -\index{profiling, deterministic} - -The Python standard library provides three different profilers: - -\begin{enumerate} -\item \module{profile}, a pure Python module, described in the sequel. - Copyright \copyright{} 1994, by InfoSeek Corporation. - \versionchanged[also reports the time spent in calls to built-in - functions and methods]{2.4} - -\item \module{cProfile}, a module written in C, with a reasonable - overhead that makes it suitable for profiling long-running programs. - Based on \module{lsprof}, contributed by Brett Rosen and Ted Czotter. - \versionadded{2.5} - -\item \module{hotshot}, a C module focusing on minimizing the overhead - while profiling, at the expense of long data post-processing times. - \versionchanged[the results should be more meaningful than in the - past: the timing core contained a critical bug]{2.5} -\end{enumerate} - -The \module{profile} and \module{cProfile} modules export the same -interface, so they are mostly interchangeables; \module{cProfile} has a -much lower overhead but is not so far as well-tested and might not be -available on all systems. \module{cProfile} is really a compatibility -layer on top of the internal \module{_lsprof} module. The -\module{hotshot} module is reserved to specialized usages. - -%\section{How Is This Profiler Different From The Old Profiler?} -%\nodename{Profiler Changes} -% -%(This section is of historical importance only; the old profiler -%discussed here was last seen in Python 1.1.) -% -%The big changes from old profiling module are that you get more -%information, and you pay less CPU time. It's not a trade-off, it's a -%trade-up. -% -%To be specific: -% -%\begin{description} -% -%\item[Bugs removed:] -%Local stack frame is no longer molested, execution time is now charged -%to correct functions. -% -%\item[Accuracy increased:] -%Profiler execution time is no longer charged to user's code, -%calibration for platform is supported, file reads are not done \emph{by} -%profiler \emph{during} profiling (and charged to user's code!). -% -%\item[Speed increased:] -%Overhead CPU cost was reduced by more than a factor of two (perhaps a -%factor of five), lightweight profiler module is all that must be -%loaded, and the report generating module (\module{pstats}) is not needed -%during profiling. -% -%\item[Recursive functions support:] -%Cumulative times in recursive functions are correctly calculated; -%recursive entries are counted. -% -%\item[Large growth in report generating UI:] -%Distinct profiles runs can be added together forming a comprehensive -%report; functions that import statistics take arbitrary lists of -%files; sorting criteria is now based on keywords (instead of 4 integer -%options); reports shows what functions were profiled as well as what -%profile file was referenced; output format has been improved. -% -%\end{description} - - -\section{Instant User's Manual \label{profile-instant}} - -This section is provided for users that ``don't want to read the -manual.'' It provides a very brief overview, and allows a user to -rapidly perform profiling on an existing application. - -To profile an application with a main entry point of \function{foo()}, -you would add the following to your module: - -\begin{verbatim} -import cProfile -cProfile.run('foo()') -\end{verbatim} - -(Use \module{profile} instead of \module{cProfile} if the latter is not -available on your system.) - -The above action would cause \function{foo()} to be run, and a series of -informative lines (the profile) to be printed. The above approach is -most useful when working with the interpreter. If you would like to -save the results of a profile into a file for later examination, you -can supply a file name as the second argument to the \function{run()} -function: - -\begin{verbatim} -import cProfile -cProfile.run('foo()', 'fooprof') -\end{verbatim} - -The file \file{cProfile.py} can also be invoked as -a script to profile another script. For example: - -\begin{verbatim} -python -m cProfile myscript.py -\end{verbatim} - -\file{cProfile.py} accepts two optional arguments on the command line: - -\begin{verbatim} -cProfile.py [-o output_file] [-s sort_order] -\end{verbatim} - -\programopt{-s} only applies to standard output (\programopt{-o} is -not supplied). Look in the \class{Stats} documentation for valid sort -values. - -When you wish to review the profile, you should use the methods in the -\module{pstats} module. Typically you would load the statistics data as -follows: - -\begin{verbatim} -import pstats -p = pstats.Stats('fooprof') -\end{verbatim} - -The class \class{Stats} (the above code just created an instance of -this class) has a variety of methods for manipulating and printing the -data that was just read into \code{p}. When you ran -\function{cProfile.run()} above, what was printed was the result of three -method calls: - -\begin{verbatim} -p.strip_dirs().sort_stats(-1).print_stats() -\end{verbatim} - -The first method removed the extraneous path from all the module -names. The second method sorted all the entries according to the -standard module/line/name string that is printed. -%(this is to comply with the semantics of the old profiler). -The third method printed out -all the statistics. You might try the following sort calls: - -\begin{verbatim} -p.sort_stats('name') -p.print_stats() -\end{verbatim} - -The first call will actually sort the list by function name, and the -second call will print out the statistics. The following are some -interesting calls to experiment with: - -\begin{verbatim} -p.sort_stats('cumulative').print_stats(10) -\end{verbatim} - -This sorts the profile by cumulative time in a function, and then only -prints the ten most significant lines. If you want to understand what -algorithms are taking time, the above line is what you would use. - -If you were looking to see what functions were looping a lot, and -taking a lot of time, you would do: - -\begin{verbatim} -p.sort_stats('time').print_stats(10) -\end{verbatim} - -to sort according to time spent within each function, and then print -the statistics for the top ten functions. - -You might also try: - -\begin{verbatim} -p.sort_stats('file').print_stats('__init__') -\end{verbatim} - -This will sort all the statistics by file name, and then print out -statistics for only the class init methods (since they are spelled -with \code{__init__} in them). As one final example, you could try: - -\begin{verbatim} -p.sort_stats('time', 'cum').print_stats(.5, 'init') -\end{verbatim} - -This line sorts statistics with a primary key of time, and a secondary -key of cumulative time, and then prints out some of the statistics. -To be specific, the list is first culled down to 50\% (re: \samp{.5}) -of its original size, then only lines containing \code{init} are -maintained, and that sub-sub-list is printed. - -If you wondered what functions called the above functions, you could -now (\code{p} is still sorted according to the last criteria) do: - -\begin{verbatim} -p.print_callers(.5, 'init') -\end{verbatim} - -and you would get a list of callers for each of the listed functions. - -If you want more functionality, you're going to have to read the -manual, or guess what the following functions do: - -\begin{verbatim} -p.print_callees() -p.add('fooprof') -\end{verbatim} - -Invoked as a script, the \module{pstats} module is a statistics -browser for reading and examining profile dumps. It has a simple -line-oriented interface (implemented using \refmodule{cmd}) and -interactive help. - -\section{What Is Deterministic Profiling?} -\nodename{Deterministic Profiling} - -\dfn{Deterministic profiling} is meant to reflect the fact that all -\emph{function call}, \emph{function return}, and \emph{exception} events -are monitored, and precise timings are made for the intervals between -these events (during which time the user's code is executing). In -contrast, \dfn{statistical profiling} (which is not done by this -module) randomly samples the effective instruction pointer, and -deduces where time is being spent. The latter technique traditionally -involves less overhead (as the code does not need to be instrumented), -but provides only relative indications of where time is being spent. - -In Python, since there is an interpreter active during execution, the -presence of instrumented code is not required to do deterministic -profiling. Python automatically provides a \dfn{hook} (optional -callback) for each event. In addition, the interpreted nature of -Python tends to add so much overhead to execution, that deterministic -profiling tends to only add small processing overhead in typical -applications. The result is that deterministic profiling is not that -expensive, yet provides extensive run time statistics about the -execution of a Python program. - -Call count statistics can be used to identify bugs in code (surprising -counts), and to identify possible inline-expansion points (high call -counts). Internal time statistics can be used to identify ``hot -loops'' that should be carefully optimized. Cumulative time -statistics should be used to identify high level errors in the -selection of algorithms. Note that the unusual handling of cumulative -times in this profiler allows statistics for recursive implementations -of algorithms to be directly compared to iterative implementations. - - -\section{Reference Manual -- \module{profile} and \module{cProfile}} - -\declaremodule{standard}{profile} -\declaremodule{standard}{cProfile} -\modulesynopsis{Python profiler} - - - -The primary entry point for the profiler is the global function -\function{profile.run()} (resp. \function{cProfile.run()}). -It is typically used to create any profile -information. The reports are formatted and printed using methods of -the class \class{pstats.Stats}. The following is a description of all -of these standard entry points and functions. For a more in-depth -view of some of the code, consider reading the later section on -Profiler Extensions, which includes discussion of how to derive -``better'' profilers from the classes presented, or reading the source -code for these modules. - -\begin{funcdesc}{run}{command\optional{, filename}} - -This function takes a single argument that can be passed to the -\function{exec()} function, and an optional file name. In all cases this -routine attempts to \function{exec()} its first argument, and gather profiling -statistics from the execution. If no file name is present, then this -function automatically prints a simple profiling report, sorted by the -standard name string (file/line/function-name) that is presented in -each line. The following is a typical output from such a call: - -\begin{verbatim} - 2706 function calls (2004 primitive calls) in 4.504 CPU seconds - -Ordered by: standard name - -ncalls tottime percall cumtime percall filename:lineno(function) - 2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects) - 43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate) - ... -\end{verbatim} - -The first line indicates that 2706 calls were -monitored. Of those calls, 2004 were \dfn{primitive}. We define -\dfn{primitive} to mean that the call was not induced via recursion. -The next line: \code{Ordered by:\ standard name}, indicates that -the text string in the far right column was used to sort the output. -The column headings include: - -\begin{description} - -\item[ncalls ] -for the number of calls, - -\item[tottime ] -for the total time spent in the given function (and excluding time -made in calls to sub-functions), - -\item[percall ] -is the quotient of \code{tottime} divided by \code{ncalls} - -\item[cumtime ] -is the total time spent in this and all subfunctions (from invocation -till exit). This figure is accurate \emph{even} for recursive -functions. - -\item[percall ] -is the quotient of \code{cumtime} divided by primitive calls - -\item[filename:lineno(function) ] -provides the respective data of each function - -\end{description} - -When there are two numbers in the first column (for example, -\samp{43/3}), then the latter is the number of primitive calls, and -the former is the actual number of calls. Note that when the function -does not recurse, these two values are the same, and only the single -figure is printed. - -\end{funcdesc} - -\begin{funcdesc}{runctx}{command, globals, locals\optional{, filename}} -This function is similar to \function{run()}, with added -arguments to supply the globals and locals dictionaries for the -\var{command} string. -\end{funcdesc} - -Analysis of the profiler data is done using the \class{Stats} class. - -\note{The \class{Stats} class is defined in the \module{pstats} module.} - -% now switch modules.... -% (This \stmodindex use may be hard to change ;-( ) -\stmodindex{pstats} - -\begin{classdesc}{Stats}{filename\optional{, stream=sys.stdout\optional{, \moreargs}}} -This class constructor creates an instance of a ``statistics object'' -from a \var{filename} (or set of filenames). \class{Stats} objects are -manipulated by methods, in order to print useful reports. You may specify -an alternate output stream by giving the keyword argument, \code{stream}. - -The file selected by the above constructor must have been created by the -corresponding version of \module{profile} or \module{cProfile}. To be -specific, there is \emph{no} file compatibility guaranteed with future -versions of this profiler, and there is no compatibility with files produced -by other profilers. -%(such as the old system profiler). - -If several files are provided, all the statistics for identical -functions will be coalesced, so that an overall view of several -processes can be considered in a single report. If additional files -need to be combined with data in an existing \class{Stats} object, the -\method{add()} method can be used. - -\versionchanged[The \var{stream} parameter was added]{2.5} -\end{classdesc} - - -\subsection{The \class{Stats} Class \label{profile-stats}} - -\class{Stats} objects have the following methods: - -\begin{methoddesc}[Stats]{strip_dirs}{} -This method for the \class{Stats} class removes all leading path -information from file names. It is very useful in reducing the size -of the printout to fit within (close to) 80 columns. This method -modifies the object, and the stripped information is lost. After -performing a strip operation, the object is considered to have its -entries in a ``random'' order, as it was just after object -initialization and loading. If \method{strip_dirs()} causes two -function names to be indistinguishable (they are on the same -line of the same filename, and have the same function name), then the -statistics for these two entries are accumulated into a single entry. -\end{methoddesc} - - -\begin{methoddesc}[Stats]{add}{filename\optional{, \moreargs}} -This method of the \class{Stats} class accumulates additional -profiling information into the current profiling object. Its -arguments should refer to filenames created by the corresponding -version of \function{profile.run()} or \function{cProfile.run()}. -Statistics for identically named -(re: file, line, name) functions are automatically accumulated into -single function statistics. -\end{methoddesc} - -\begin{methoddesc}[Stats]{dump_stats}{filename} -Save the data loaded into the \class{Stats} object to a file named -\var{filename}. The file is created if it does not exist, and is -overwritten if it already exists. This is equivalent to the method of -the same name on the \class{profile.Profile} and -\class{cProfile.Profile} classes. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[Stats]{sort_stats}{key\optional{, \moreargs}} -This method modifies the \class{Stats} object by sorting it according -to the supplied criteria. The argument is typically a string -identifying the basis of a sort (example: \code{'time'} or -\code{'name'}). - -When more than one key is provided, then additional keys are used as -secondary criteria when there is equality in all keys selected -before them. For example, \code{sort_stats('name', 'file')} will sort -all the entries according to their function name, and resolve all ties -(identical function names) by sorting by file name. - -Abbreviations can be used for any key names, as long as the -abbreviation is unambiguous. The following are the keys currently -defined: - -\begin{tableii}{l|l}{code}{Valid Arg}{Meaning} - \lineii{'calls'}{call count} - \lineii{'cumulative'}{cumulative time} - \lineii{'file'}{file name} - \lineii{'module'}{file name} - \lineii{'pcalls'}{primitive call count} - \lineii{'line'}{line number} - \lineii{'name'}{function name} - \lineii{'nfl'}{name/file/line} - \lineii{'stdname'}{standard name} - \lineii{'time'}{internal time} -\end{tableii} - -Note that all sorts on statistics are in descending order (placing -most time consuming items first), where as name, file, and line number -searches are in ascending order (alphabetical). The subtle -distinction between \code{'nfl'} and \code{'stdname'} is that the -standard name is a sort of the name as printed, which means that the -embedded line numbers get compared in an odd way. For example, lines -3, 20, and 40 would (if the file names were the same) appear in the -string order 20, 3 and 40. In contrast, \code{'nfl'} does a numeric -compare of the line numbers. In fact, \code{sort_stats('nfl')} is the -same as \code{sort_stats('name', 'file', 'line')}. - -%For compatibility with the old profiler, -For backward-compatibility reasons, the numeric arguments -\code{-1}, \code{0}, \code{1}, and \code{2} are permitted. They are -interpreted as \code{'stdname'}, \code{'calls'}, \code{'time'}, and -\code{'cumulative'} respectively. If this old style format (numeric) -is used, only one sort key (the numeric key) will be used, and -additional arguments will be silently ignored. -\end{methoddesc} - - -\begin{methoddesc}[Stats]{reverse_order}{} -This method for the \class{Stats} class reverses the ordering of the basic -list within the object. %This method is provided primarily for -%compatibility with the old profiler. -Note that by default ascending vs descending order is properly selected -based on the sort key of choice. -\end{methoddesc} - -\begin{methoddesc}[Stats]{print_stats}{\optional{restriction, \moreargs}} -This method for the \class{Stats} class prints out a report as described -in the \function{profile.run()} definition. - -The order of the printing is based on the last \method{sort_stats()} -operation done on the object (subject to caveats in \method{add()} and -\method{strip_dirs()}). - -The arguments provided (if any) can be used to limit the list down to -the significant entries. Initially, the list is taken to be the -complete set of profiled functions. Each restriction is either an -integer (to select a count of lines), or a decimal fraction between -0.0 and 1.0 inclusive (to select a percentage of lines), or a regular -expression (to pattern match the standard name that is printed; as of -Python 1.5b1, this uses the Perl-style regular expression syntax -defined by the \refmodule{re} module). If several restrictions are -provided, then they are applied sequentially. For example: - -\begin{verbatim} -print_stats(.1, 'foo:') -\end{verbatim} - -would first limit the printing to first 10\% of list, and then only -print functions that were part of filename \file{.*foo:}. In -contrast, the command: - -\begin{verbatim} -print_stats('foo:', .1) -\end{verbatim} - -would limit the list to all functions having file names \file{.*foo:}, -and then proceed to only print the first 10\% of them. -\end{methoddesc} - - -\begin{methoddesc}[Stats]{print_callers}{\optional{restriction, \moreargs}} -This method for the \class{Stats} class prints a list of all functions -that called each function in the profiled database. The ordering is -identical to that provided by \method{print_stats()}, and the definition -of the restricting argument is also identical. Each caller is reported on -its own line. The format differs slightly depending on the profiler that -produced the stats: - -\begin{itemize} -\item With \module{profile}, a number is shown in parentheses after each - caller to show how many times this specific call was made. For - convenience, a second non-parenthesized number repeats the cumulative - time spent in the function at the right. - -\item With \module{cProfile}, each caller is preceeded by three numbers: - the number of times this specific call was made, and the total and - cumulative times spent in the current function while it was invoked by - this specific caller. -\end{itemize} -\end{methoddesc} - -\begin{methoddesc}[Stats]{print_callees}{\optional{restriction, \moreargs}} -This method for the \class{Stats} class prints a list of all function -that were called by the indicated function. Aside from this reversal -of direction of calls (re: called vs was called by), the arguments and -ordering are identical to the \method{print_callers()} method. -\end{methoddesc} - - -\section{Limitations \label{profile-limits}} - -One limitation has to do with accuracy of timing information. -There is a fundamental problem with deterministic profilers involving -accuracy. The most obvious restriction is that the underlying ``clock'' -is only ticking at a rate (typically) of about .001 seconds. Hence no -measurements will be more accurate than the underlying clock. If -enough measurements are taken, then the ``error'' will tend to average -out. Unfortunately, removing this first error induces a second source -of error. - -The second problem is that it ``takes a while'' from when an event is -dispatched until the profiler's call to get the time actually -\emph{gets} the state of the clock. Similarly, there is a certain lag -when exiting the profiler event handler from the time that the clock's -value was obtained (and then squirreled away), until the user's code -is once again executing. As a result, functions that are called many -times, or call many functions, will typically accumulate this error. -The error that accumulates in this fashion is typically less than the -accuracy of the clock (less than one clock tick), but it -\emph{can} accumulate and become very significant. - -The problem is more important with \module{profile} than with the -lower-overhead \module{cProfile}. For this reason, \module{profile} -provides a means of calibrating itself for a given platform so that -this error can be probabilistically (on the average) removed. -After the profiler is calibrated, it will be more accurate (in a least -square sense), but it will sometimes produce negative numbers (when -call counts are exceptionally low, and the gods of probability work -against you :-). ) Do \emph{not} be alarmed by negative numbers in -the profile. They should \emph{only} appear if you have calibrated -your profiler, and the results are actually better than without -calibration. - - -\section{Calibration \label{profile-calibration}} - -The profiler of the \module{profile} module subtracts a constant from each -event handling time to compensate for the overhead of calling the time -function, and socking away the results. By default, the constant is 0. -The following procedure can -be used to obtain a better constant for a given platform (see discussion -in section Limitations above). - -\begin{verbatim} -import profile -pr = profile.Profile() -for i in range(5): - print pr.calibrate(10000) -\end{verbatim} - -The method executes the number of Python calls given by the argument, -directly and again under the profiler, measuring the time for both. -It then computes the hidden overhead per profiler event, and returns -that as a float. For example, on an 800 MHz Pentium running -Windows 2000, and using Python's time.clock() as the timer, -the magical number is about 12.5e-6. - -The object of this exercise is to get a fairly consistent result. -If your computer is \emph{very} fast, or your timer function has poor -resolution, you might have to pass 100000, or even 1000000, to get -consistent results. - -When you have a consistent answer, -there are three ways you can use it:\footnote{Prior to Python 2.2, it - was necessary to edit the profiler source code to embed the bias as - a literal number. You still can, but that method is no longer - described, because no longer needed.} - -\begin{verbatim} -import profile - -# 1. Apply computed bias to all Profile instances created hereafter. -profile.Profile.bias = your_computed_bias - -# 2. Apply computed bias to a specific Profile instance. -pr = profile.Profile() -pr.bias = your_computed_bias - -# 3. Specify computed bias in instance constructor. -pr = profile.Profile(bias=your_computed_bias) -\end{verbatim} - -If you have a choice, you are better off choosing a smaller constant, and -then your results will ``less often'' show up as negative in profile -statistics. - - -\section{Extensions --- Deriving Better Profilers} -\nodename{Profiler Extensions} - -The \class{Profile} class of both modules, \module{profile} and -\module{cProfile}, were written so that -derived classes could be developed to extend the profiler. The details -are not described here, as doing this successfully requires an expert -understanding of how the \class{Profile} class works internally. Study -the source code of the module carefully if you want to -pursue this. - -If all you want to do is change how current time is determined (for -example, to force use of wall-clock time or elapsed process time), -pass the timing function you want to the \class{Profile} class -constructor: - -\begin{verbatim} -pr = profile.Profile(your_time_func) -\end{verbatim} - -The resulting profiler will then call \function{your_time_func()}. - -\begin{description} -\item[\class{profile.Profile}] -\function{your_time_func()} should return a single number, or a list of -numbers whose sum is the current time (like what \function{os.times()} -returns). If the function returns a single time number, or the list of -returned numbers has length 2, then you will get an especially fast -version of the dispatch routine. - -Be warned that you should calibrate the profiler class for the -timer function that you choose. For most machines, a timer that -returns a lone integer value will provide the best results in terms of -low overhead during profiling. (\function{os.times()} is -\emph{pretty} bad, as it returns a tuple of floating point values). If -you want to substitute a better timer in the cleanest fashion, -derive a class and hardwire a replacement dispatch method that best -handles your timer call, along with the appropriate calibration -constant. - -\item[\class{cProfile.Profile}] -\function{your_time_func()} should return a single number. If it returns -plain integers, you can also invoke the class constructor with a second -argument specifying the real duration of one unit of time. For example, -if \function{your_integer_time_func()} returns times measured in thousands -of seconds, you would constuct the \class{Profile} instance as follows: - -\begin{verbatim} -pr = profile.Profile(your_integer_time_func, 0.001) -\end{verbatim} - -As the \module{cProfile.Profile} class cannot be calibrated, custom -timer functions should be used with care and should be as fast as -possible. For the best results with a custom timer, it might be -necessary to hard-code it in the C source of the internal -\module{_lsprof} module. - -\end{description} diff --git a/Doc/lib/libpty.tex b/Doc/lib/libpty.tex deleted file mode 100644 index 2db7503..0000000 --- a/Doc/lib/libpty.tex +++ /dev/null @@ -1,44 +0,0 @@ -\section{\module{pty} --- - Pseudo-terminal utilities} -\declaremodule{standard}{pty} - \platform{IRIX, Linux} -\modulesynopsis{Pseudo-Terminal Handling for SGI and Linux.} -\moduleauthor{Steen Lumholt}{} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} - - -The \module{pty} module defines operations for handling the -pseudo-terminal concept: starting another process and being able to -write to and read from its controlling terminal programmatically. - -Because pseudo-terminal handling is highly platform dependant, there -is code to do it only for SGI and Linux. (The Linux code is supposed -to work on other platforms, but hasn't been tested yet.) - -The \module{pty} module defines the following functions: - -\begin{funcdesc}{fork}{} -Fork. Connect the child's controlling terminal to a pseudo-terminal. -Return value is \code{(\var{pid}, \var{fd})}. Note that the child -gets \var{pid} 0, and the \var{fd} is \emph{invalid}. The parent's -return value is the \var{pid} of the child, and \var{fd} is a file -descriptor connected to the child's controlling terminal (and also -to the child's standard input and output). -\end{funcdesc} - -\begin{funcdesc}{openpty}{} -Open a new pseudo-terminal pair, using \function{os.openpty()} if -possible, or emulation code for SGI and generic \UNIX{} systems. -Return a pair of file descriptors \code{(\var{master}, \var{slave})}, -for the master and the slave end, respectively. -\end{funcdesc} - -\begin{funcdesc}{spawn}{argv\optional{, master_read\optional{, stdin_read}}} -Spawn a process, and connect its controlling terminal with the current -process's standard io. This is often used to baffle programs which -insist on reading from the controlling terminal. - -The functions \var{master_read} and \var{stdin_read} should be -functions which read from a file-descriptor. The defaults try to read -1024 bytes each time they are called. -\end{funcdesc} diff --git a/Doc/lib/libpwd.tex b/Doc/lib/libpwd.tex deleted file mode 100644 index 0c74d26..0000000 --- a/Doc/lib/libpwd.tex +++ /dev/null @@ -1,57 +0,0 @@ -\section{\module{pwd} --- - The password database} - -\declaremodule{builtin}{pwd} - \platform{Unix} -\modulesynopsis{The password database (\function{getpwnam()} and friends).} - -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 a tuple-like object, whose -attributes correspond to the members of the \code{passwd} structure -(Attribute field below, see \code{<pwd.h>}): - -\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{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. - -\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 -\var{pw_passwd} field only contains an asterisk (\code{'*'}) or the -letter \character{x} where the encrypted password is stored in a file -\file{/etc/shadow} which is not world readable. Whether the \var{pw_passwd} -field contains anything useful is system-dependent. If available, the -\module{spwd} module should be used where access to the encrypted password -is required.} - -It defines the following items: - -\begin{funcdesc}{getpwuid}{uid} -Return the password database entry for the given numeric user ID. -\end{funcdesc} - -\begin{funcdesc}{getpwnam}{name} -Return the password database entry for the given user name. -\end{funcdesc} - -\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.} - \seemodule{spwd}{An interface to the shadow password database, similar to this.} -\end{seealso} diff --git a/Doc/lib/libpyclbr.tex b/Doc/lib/libpyclbr.tex deleted file mode 100644 index 0dedb9e..0000000 --- a/Doc/lib/libpyclbr.tex +++ /dev/null @@ -1,102 +0,0 @@ -\section{\module{pyclbr} --- - Python class browser support} - -\declaremodule{standard}{pyclbr} -\modulesynopsis{Supports information extraction for a Python class - browser.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -The \module{pyclbr} can be used to determine some limited information -about the classes, methods and top-level functions -defined in a module. The information -provided is sufficient to implement a traditional three-pane class -browser. The information is extracted from the source code rather -than by importing the module, so this module is safe to use with -untrusted source code. This restriction makes it impossible to use -this module with modules not implemented in Python, including many -standard and optional extension modules. - - -\begin{funcdesc}{readmodule}{module\optional{, path}} - % The 'inpackage' parameter appears to be for internal use only.... - Read a module and return a dictionary mapping class names to class - descriptor objects. The parameter \var{module} should be the name - of a module as a string; it may be the name of a module within a - package. The \var{path} parameter should be a sequence, and is used - to augment the value of \code{sys.path}, which is used to locate - module source code. -\end{funcdesc} - -\begin{funcdesc}{readmodule_ex}{module\optional{, path}} - % The 'inpackage' parameter appears to be for internal use only.... - Like \function{readmodule()}, but the returned dictionary, in addition - to mapping class names to class descriptor objects, also maps - top-level function names to function descriptor objects. Moreover, if - the module being read is a package, the key \code{'__path__'} in the - returned dictionary has as its value a list which contains the package - search path. -\end{funcdesc} - - -\subsection{Class Descriptor Objects \label{pyclbr-class-objects}} - -The class descriptor objects used as values in the dictionary returned -by \function{readmodule()} and \function{readmodule_ex()} -provide the following data members: - - -\begin{memberdesc}[class descriptor]{module} - The name of the module defining the class described by the class - descriptor. -\end{memberdesc} - -\begin{memberdesc}[class descriptor]{name} - The name of the class. -\end{memberdesc} - -\begin{memberdesc}[class descriptor]{super} - A list of class descriptors which describe the immediate base - classes of the class being described. Classes which are named as - superclasses but which are not discoverable by - \function{readmodule()} are listed as a string with the class name - instead of class descriptors. -\end{memberdesc} - -\begin{memberdesc}[class descriptor]{methods} - A dictionary mapping method names to line numbers. -\end{memberdesc} - -\begin{memberdesc}[class descriptor]{file} - Name of the file containing the \code{class} statement defining the class. -\end{memberdesc} - -\begin{memberdesc}[class descriptor]{lineno} - The line number of the \code{class} statement within the file named by - \member{file}. -\end{memberdesc} - -\subsection{Function Descriptor Objects \label{pyclbr-function-objects}} - -The function descriptor objects used as values in the dictionary returned -by \function{readmodule_ex()} provide the following data members: - - -\begin{memberdesc}[function descriptor]{module} - The name of the module defining the function described by the function - descriptor. -\end{memberdesc} - -\begin{memberdesc}[function descriptor]{name} - The name of the function. -\end{memberdesc} - -\begin{memberdesc}[function descriptor]{file} - Name of the file containing the \code{def} statement defining the function. -\end{memberdesc} - -\begin{memberdesc}[function descriptor]{lineno} - The line number of the \code{def} statement within the file named by - \member{file}. -\end{memberdesc} - diff --git a/Doc/lib/libpycompile.tex b/Doc/lib/libpycompile.tex deleted file mode 100644 index 85f0aaa..0000000 --- a/Doc/lib/libpycompile.tex +++ /dev/null @@ -1,53 +0,0 @@ -\section{\module{py_compile} --- - Compile Python source files} - -% Documentation based on module docstrings, by Fred L. Drake, Jr. -% <fdrake@acm.org> - -\declaremodule[pycompile]{standard}{py_compile} - -\modulesynopsis{Compile Python source files to byte-code files.} - - -\indexii{file}{byte-code} -The \module{py_compile} module provides a function to generate a -byte-code file from a source file, and another function used when the -module source file is invoked as a script. - -Though not often needed, this function can be useful when installing -modules for shared use, especially if some of the users may not have -permission to write the byte-code cache files in the directory -containing the source code. - -\begin{excdesc}{PyCompileError} -Exception raised when an error occurs while attempting to compile the file. -\end{excdesc} - -\begin{funcdesc}{compile}{file\optional{, cfile\optional{, dfile\optional{, doraise}}}} - Compile a source file to byte-code and write out the byte-code cache - file. The source code is loaded from the file name \var{file}. The - byte-code is written to \var{cfile}, which defaults to \var{file} - \code{+} \code{'c'} (\code{'o'} if optimization is enabled in the - current interpreter). If \var{dfile} is specified, it is used as - the name of the source file in error messages instead of \var{file}. - If \var{doraise} is true, a \exception{PyCompileError} is raised when - an error is encountered while compiling \var{file}. If \var{doraise} - is false (the default), an error string is written to \code{sys.stderr}, - but no exception is raised. -\end{funcdesc} - -\begin{funcdesc}{main}{\optional{args}} - Compile several source files. The files named in \var{args} (or on - the command line, if \var{args} is not specified) are compiled and - the resulting bytecode is cached in the normal manner. This - function does not search a directory structure to locate source - files; it only compiles files named explicitly. -\end{funcdesc} - -When this module is run as a script, the \function{main()} is used to -compile all the files named on the command line. - -\begin{seealso} - \seemodule{compileall}{Utilities to compile all Python source files - in a directory tree.} -\end{seealso} diff --git a/Doc/lib/libpydoc.tex b/Doc/lib/libpydoc.tex deleted file mode 100644 index bb74df6..0000000 --- a/Doc/lib/libpydoc.tex +++ /dev/null @@ -1,67 +0,0 @@ -\section{\module{pydoc} --- - Documentation generator and online help system} - -\declaremodule{standard}{pydoc} -\modulesynopsis{Documentation generator and online help system.} -\moduleauthor{Ka-Ping Yee}{ping@lfw.org} -\sectionauthor{Ka-Ping Yee}{ping@lfw.org} - -\versionadded{2.1} -\index{documentation!generation} -\index{documentation!online} -\index{help!online} - -The \module{pydoc} module automatically generates documentation from -Python modules. The documentation can be presented as pages of text -on the console, served to a Web browser, or saved to HTML files. - -The built-in function \function{help()} invokes the online help system -in the interactive interpreter, which uses \module{pydoc} to generate -its documentation as text on the console. The same text documentation -can also be viewed from outside the Python interpreter by running -\program{pydoc} as a script at the operating system's command prompt. -For example, running - -\begin{verbatim} -pydoc sys -\end{verbatim} - -at a shell prompt will display documentation on the \refmodule{sys} -module, in a style similar to the manual pages shown by the \UNIX{} -\program{man} command. The argument to \program{pydoc} can be the name -of a function, module, or package, or a dotted reference to a class, -method, or function within a module or module in a package. If the -argument to \program{pydoc} looks like a path (that is, it contains the -path separator for your operating system, such as a slash in \UNIX), -and refers to an existing Python source file, then documentation is -produced for that file. - -Specifying a \programopt{-w} flag before the argument will cause HTML -documentation to be written out to a file in the current directory, -instead of displaying text on the console. - -Specifying a \programopt{-k} flag before the argument will search the -synopsis lines of all available modules for the keyword given as the -argument, again in a manner similar to the \UNIX{} \program{man} -command. The synopsis line of a module is the first line of its -documentation string. - -You can also use \program{pydoc} to start an HTTP server on the local -machine that will serve documentation to visiting Web browsers. -\program{pydoc} \programopt{-p 1234} will start a HTTP server on port -1234, allowing you to browse the documentation at -\code{http://localhost:1234/} in your preferred Web browser. -\program{pydoc} \programopt{-g} will start the server and additionally -bring up a small \refmodule{Tkinter}-based graphical interface to help -you search for documentation pages. - -When \program{pydoc} generates documentation, it uses the current -environment and path to locate modules. Thus, invoking -\program{pydoc} \programopt{spam} documents precisely the version of -the module you would get if you started the Python interpreter and -typed \samp{import spam}. - -Module docs for core modules are assumed to reside in -{}\url{http://www.python.org/doc/current/lib/}. This can be overridden by -setting the \envvar{PYTHONDOCS} environment variable to a different URL or -to a local directory containing the Library Reference Manual pages. diff --git a/Doc/lib/libpyexpat.tex b/Doc/lib/libpyexpat.tex deleted file mode 100644 index ed0bf6a..0000000 --- a/Doc/lib/libpyexpat.tex +++ /dev/null @@ -1,766 +0,0 @@ -\section{\module{xml.parsers.expat} --- - Fast XML parsing using Expat} - -% Markup notes: -% -% Many of the attributes of the XMLParser objects are callbacks. -% Since signature information must be presented, these are described -% using the methoddesc environment. Since they are attributes which -% are set by client code, in-text references to these attributes -% should be marked using the \member macro and should not include the -% parentheses used when marking functions and methods. - -\declaremodule{standard}{xml.parsers.expat} -\modulesynopsis{An interface to the Expat non-validating XML parser.} -\moduleauthor{Paul Prescod}{paul@prescod.net} - -\versionadded{2.0} - -The \module{xml.parsers.expat} module is a Python interface to the -Expat\index{Expat} non-validating XML parser. -The module provides a single extension type, \class{xmlparser}, that -represents the current state of an XML parser. After an -\class{xmlparser} object has been created, various attributes of the object -can be set to handler functions. When an XML document is then fed to -the parser, the handler functions are called for the character data -and markup in the XML document. - -This module uses the \module{pyexpat}\refbimodindex{pyexpat} module to -provide access to the Expat parser. Direct use of the -\module{pyexpat} module is deprecated. - -This module provides one exception and one type object: - -\begin{excdesc}{ExpatError} - The exception raised when Expat reports an error. See section - \ref{expaterror-objects}, ``ExpatError Exceptions,'' for more - information on interpreting Expat errors. -\end{excdesc} - -\begin{excdesc}{error} - Alias for \exception{ExpatError}. -\end{excdesc} - -\begin{datadesc}{XMLParserType} - The type of the return values from the \function{ParserCreate()} - function. -\end{datadesc} - - -The \module{xml.parsers.expat} module contains two functions: - -\begin{funcdesc}{ErrorString}{errno} -Returns an explanatory string for a given error number \var{errno}. -\end{funcdesc} - -\begin{funcdesc}{ParserCreate}{\optional{encoding\optional{, - namespace_separator}}} -Creates and returns a new \class{xmlparser} object. -\var{encoding}, if specified, must be a string naming the encoding -used by the XML data. Expat doesn't support as many encodings as -Python does, and its repertoire of encodings can't be extended; it -supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If -\var{encoding} is given it will override the implicit or explicit -encoding of the document. - -Expat can optionally do XML namespace processing for you, enabled by -providing a value for \var{namespace_separator}. The value must be a -one-character string; a \exception{ValueError} will be raised if the -string has an illegal length (\code{None} is considered the same as -omission). When namespace processing is enabled, element type names -and attribute names that belong to a namespace will be expanded. The -element name passed to the element handlers -\member{StartElementHandler} and \member{EndElementHandler} -will be the concatenation of the namespace URI, the namespace -separator character, and the local part of the name. If the namespace -separator is a zero byte (\code{chr(0)}) then the namespace URI and -the local part will be concatenated without any separator. - -For example, if \var{namespace_separator} is set to a space character -(\character{ }) and the following document is parsed: - -\begin{verbatim} -<?xml version="1.0"?> -<root xmlns = "http://default-namespace.org/" - xmlns:py = "http://www.python.org/ns/"> - <py:elem1 /> - <elem2 xmlns="" /> -</root> -\end{verbatim} - -\member{StartElementHandler} will receive the following strings -for each element: - -\begin{verbatim} -http://default-namespace.org/ root -http://www.python.org/ns/ elem1 -elem2 -\end{verbatim} -\end{funcdesc} - - -\begin{seealso} - \seetitle[http://www.libexpat.org/]{The Expat XML Parser} - {Home page of the Expat project.} -\end{seealso} - - -\subsection{XMLParser Objects \label{xmlparser-objects}} - -\class{xmlparser} objects have the following methods: - -\begin{methoddesc}[xmlparser]{Parse}{data\optional{, isfinal}} -Parses the contents of the string \var{data}, calling the appropriate -handler functions to process the parsed data. \var{isfinal} must be -true on the final call to this method. \var{data} can be the empty -string at any time. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{ParseFile}{file} -Parse XML data reading from the object \var{file}. \var{file} only -needs to provide the \method{read(\var{nbytes})} method, returning the -empty string when there's no more data. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{SetBase}{base} -Sets the base to be used for resolving relative URIs in system -identifiers in declarations. Resolving relative identifiers is left -to the application: this value will be passed through as the -\var{base} argument to the \function{ExternalEntityRefHandler}, -\function{NotationDeclHandler}, and -\function{UnparsedEntityDeclHandler} functions. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{GetBase}{} -Returns a string containing the base set by a previous call to -\method{SetBase()}, or \code{None} if -\method{SetBase()} hasn't been called. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{GetInputContext}{} -Returns the input data that generated the current event as a string. -The data is in the encoding of the entity which contains the text. -When called while an event handler is not active, the return value is -\code{None}. -\versionadded{2.1} -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{ExternalEntityParserCreate}{context\optional{, - encoding}} -Create a ``child'' parser which can be used to parse an external -parsed entity referred to by content parsed by the parent parser. The -\var{context} parameter should be the string passed to the -\method{ExternalEntityRefHandler()} handler function, described below. -The child parser is created with the \member{ordered_attributes} -and \member{specified_attributes} set to the -values of this parser. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{UseForeignDTD}{\optional{flag}} -Calling this with a true value for \var{flag} (the default) will cause -Expat to call the \member{ExternalEntityRefHandler} with -\constant{None} for all arguments to allow an alternate DTD to be -loaded. If the document does not contain a document type declaration, -the \member{ExternalEntityRefHandler} will still be called, but the -\member{StartDoctypeDeclHandler} and \member{EndDoctypeDeclHandler} -will not be called. - -Passing a false value for \var{flag} will cancel a previous call that -passed a true value, but otherwise has no effect. - -This method can only be called before the \method{Parse()} or -\method{ParseFile()} methods are called; calling it after either of -those have been called causes \exception{ExpatError} to be raised with -the \member{code} attribute set to -\constant{errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING}. - -\versionadded{2.3} -\end{methoddesc} - - -\class{xmlparser} objects have the following attributes: - -\begin{memberdesc}[xmlparser]{buffer_size} -The size of the buffer used when \member{buffer_text} is true. This -value cannot be changed at this time. -\versionadded{2.3} -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{buffer_text} -Setting this to true causes the \class{xmlparser} object to buffer -textual content returned by Expat to avoid multiple calls to the -\method{CharacterDataHandler()} callback whenever possible. This can -improve performance substantially since Expat normally breaks -character data into chunks at every line ending. This attribute is -false by default, and may be changed at any time. -\versionadded{2.3} -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{buffer_used} -If \member{buffer_text} is enabled, the number of bytes stored in the -buffer. These bytes represent UTF-8 encoded text. This attribute has -no meaningful interpretation when \member{buffer_text} is false. -\versionadded{2.3} -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{ordered_attributes} -Setting this attribute to a non-zero integer causes the attributes to -be reported as a list rather than a dictionary. The attributes are -presented in the order found in the document text. For each -attribute, two list entries are presented: the attribute name and the -attribute value. (Older versions of this module also used this -format.) By default, this attribute is false; it may be changed at -any time. -\versionadded{2.1} -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{specified_attributes} -If set to a non-zero integer, the parser will report only those -attributes which were specified in the document instance and not those -which were derived from attribute declarations. Applications which -set this need to be especially careful to use what additional -information is available from the declarations as needed to comply -with the standards for the behavior of XML processors. By default, -this attribute is false; it may be changed at any time. -\versionadded{2.1} -\end{memberdesc} - -The following attributes contain values relating to the most recent -error encountered by an \class{xmlparser} object, and will only have -correct values once a call to \method{Parse()} or \method{ParseFile()} -has raised a \exception{xml.parsers.expat.ExpatError} exception. - -\begin{memberdesc}[xmlparser]{ErrorByteIndex} -Byte index at which an error occurred. -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{ErrorCode} -Numeric code specifying the problem. This value can be passed to the -\function{ErrorString()} function, or compared to one of the constants -defined in the \code{errors} object. -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{ErrorColumnNumber} -Column number at which an error occurred. -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{ErrorLineNumber} -Line number at which an error occurred. -\end{memberdesc} - -The following attributes contain values relating to the current parse -location in an \class{xmlparser} object. During a callback reporting -a parse event they indicate the location of the first of the sequence -of characters that generated the event. When called outside of a -callback, the position indicated will be just past the last parse -event (regardless of whether there was an associated callback). -\versionadded{2.4} - -\begin{memberdesc}[xmlparser]{CurrentByteIndex} -Current byte index in the parser input. -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{CurrentColumnNumber} -Current column number in the parser input. -\end{memberdesc} - -\begin{memberdesc}[xmlparser]{CurrentLineNumber} -Current line number in the parser input. -\end{memberdesc} - -Here is the list of handlers that can be set. To set a handler on an -\class{xmlparser} object \var{o}, use -\code{\var{o}.\var{handlername} = \var{func}}. \var{handlername} must -be taken from the following list, and \var{func} must be a callable -object accepting the correct number of arguments. The arguments are -all strings, unless otherwise stated. - -\begin{methoddesc}[xmlparser]{XmlDeclHandler}{version, encoding, standalone} -Called when the XML declaration is parsed. The XML declaration is the -(optional) declaration of the applicable version of the XML -recommendation, the encoding of the document text, and an optional -``standalone'' declaration. \var{version} and \var{encoding} will be -strings, and \var{standalone} will be \code{1} if the document is -declared standalone, \code{0} if it is declared not to be standalone, -or \code{-1} if the standalone clause was omitted. -This is only available with Expat version 1.95.0 or newer. -\versionadded{2.1} -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{StartDoctypeDeclHandler}{doctypeName, - systemId, publicId, - has_internal_subset} -Called when Expat begins parsing the document type declaration -(\code{<!DOCTYPE \ldots}). The \var{doctypeName} is provided exactly -as presented. The \var{systemId} and \var{publicId} parameters give -the system and public identifiers if specified, or \code{None} if -omitted. \var{has_internal_subset} will be true if the document -contains and internal document declaration subset. -This requires Expat version 1.2 or newer. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{EndDoctypeDeclHandler}{} -Called when Expat is done parsing the document type declaration. -This requires Expat version 1.2 or newer. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{ElementDeclHandler}{name, model} -Called once for each element type declaration. \var{name} is the name -of the element type, and \var{model} is a representation of the -content model. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{AttlistDeclHandler}{elname, attname, - type, default, required} -Called for each declared attribute for an element type. If an -attribute list declaration declares three attributes, this handler is -called three times, once for each attribute. \var{elname} is the name -of the element to which the declaration applies and \var{attname} is -the name of the attribute declared. The attribute type is a string -passed as \var{type}; the possible values are \code{'CDATA'}, -\code{'ID'}, \code{'IDREF'}, ... -\var{default} gives the default value for the attribute used when the -attribute is not specified by the document instance, or \code{None} if -there is no default value (\code{\#IMPLIED} values). If the attribute -is required to be given in the document instance, \var{required} will -be true. -This requires Expat version 1.95.0 or newer. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{StartElementHandler}{name, attributes} -Called for the start of every element. \var{name} is a string -containing the element name, and \var{attributes} is a dictionary -mapping attribute names to their values. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{EndElementHandler}{name} -Called for the end of every element. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{ProcessingInstructionHandler}{target, data} -Called for every processing instruction. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{CharacterDataHandler}{data} -Called for character data. This will be called for normal character -data, CDATA marked content, and ignorable whitespace. Applications -which must distinguish these cases can use the -\member{StartCdataSectionHandler}, \member{EndCdataSectionHandler}, -and \member{ElementDeclHandler} callbacks to collect the required -information. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{UnparsedEntityDeclHandler}{entityName, base, - systemId, publicId, - notationName} -Called for unparsed (NDATA) entity declarations. This is only present -for version 1.2 of the Expat library; for more recent versions, use -\member{EntityDeclHandler} instead. (The underlying function in the -Expat library has been declared obsolete.) -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{EntityDeclHandler}{entityName, - is_parameter_entity, value, - base, systemId, - publicId, - notationName} -Called for all entity declarations. For parameter and internal -entities, \var{value} will be a string giving the declared contents -of the entity; this will be \code{None} for external entities. The -\var{notationName} parameter will be \code{None} for parsed entities, -and the name of the notation for unparsed entities. -\var{is_parameter_entity} will be true if the entity is a parameter -entity or false for general entities (most applications only need to -be concerned with general entities). -This is only available starting with version 1.95.0 of the Expat -library. -\versionadded{2.1} -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{NotationDeclHandler}{notationName, base, - systemId, publicId} -Called for notation declarations. \var{notationName}, \var{base}, and -\var{systemId}, and \var{publicId} are strings if given. If the -public identifier is omitted, \var{publicId} will be \code{None}. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{StartNamespaceDeclHandler}{prefix, uri} -Called when an element contains a namespace declaration. Namespace -declarations are processed before the \member{StartElementHandler} is -called for the element on which declarations are placed. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{EndNamespaceDeclHandler}{prefix} -Called when the closing tag is reached for an element -that contained a namespace declaration. This is called once for each -namespace declaration on the element in the reverse of the order for -which the \member{StartNamespaceDeclHandler} was called to indicate -the start of each namespace declaration's scope. Calls to this -handler are made after the corresponding \member{EndElementHandler} -for the end of the element. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{CommentHandler}{data} -Called for comments. \var{data} is the text of the comment, excluding -the leading `\code{<!-}\code{-}' and trailing `\code{-}\code{->}'. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{StartCdataSectionHandler}{} -Called at the start of a CDATA section. This and -\member{EndCdataSectionHandler} are needed to be able to identify -the syntactical start and end for CDATA sections. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{EndCdataSectionHandler}{} -Called at the end of a CDATA section. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{DefaultHandler}{data} -Called for any characters in the XML document for -which no applicable handler has been specified. This means -characters that are part of a construct which could be reported, but -for which no handler has been supplied. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{DefaultHandlerExpand}{data} -This is the same as the \function{DefaultHandler}, -but doesn't inhibit expansion of internal entities. -The entity reference will not be passed to the default handler. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{NotStandaloneHandler}{} Called if the -XML document hasn't been declared as being a standalone document. -This happens when there is an external subset or a reference to a -parameter entity, but the XML declaration does not set standalone to -\code{yes} in an XML declaration. If this handler returns \code{0}, -then the parser will throw an \constant{XML_ERROR_NOT_STANDALONE} -error. If this handler is not set, no exception is raised by the -parser for this condition. -\end{methoddesc} - -\begin{methoddesc}[xmlparser]{ExternalEntityRefHandler}{context, base, - systemId, publicId} -Called for references to external entities. \var{base} is the current -base, as set by a previous call to \method{SetBase()}. The public and -system identifiers, \var{systemId} and \var{publicId}, are strings if -given; if the public identifier is not given, \var{publicId} will be -\code{None}. The \var{context} value is opaque and should only be -used as described below. - -For external entities to be parsed, this handler must be implemented. -It is responsible for creating the sub-parser using -\code{ExternalEntityParserCreate(\var{context})}, initializing it with -the appropriate callbacks, and parsing the entity. This handler -should return an integer; if it returns \code{0}, the parser will -throw an \constant{XML_ERROR_EXTERNAL_ENTITY_HANDLING} error, -otherwise parsing will continue. - -If this handler is not provided, external entities are reported by the -\member{DefaultHandler} callback, if provided. -\end{methoddesc} - - -\subsection{ExpatError Exceptions \label{expaterror-objects}} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -\exception{ExpatError} exceptions have a number of interesting -attributes: - -\begin{memberdesc}[ExpatError]{code} - Expat's internal error number for the specific error. This will - match one of the constants defined in the \code{errors} object from - this module. - \versionadded{2.1} -\end{memberdesc} - -\begin{memberdesc}[ExpatError]{lineno} - Line number on which the error was detected. The first line is - numbered \code{1}. - \versionadded{2.1} -\end{memberdesc} - -\begin{memberdesc}[ExpatError]{offset} - Character offset into the line where the error occurred. The first - column is numbered \code{0}. - \versionadded{2.1} -\end{memberdesc} - - -\subsection{Example \label{expat-example}} - -The following program defines three handlers that just print out their -arguments. - -\begin{verbatim} -import xml.parsers.expat - -# 3 handler functions -def start_element(name, attrs): - print 'Start element:', name, attrs -def end_element(name): - print 'End element:', name -def char_data(data): - print 'Character data:', repr(data) - -p = xml.parsers.expat.ParserCreate() - -p.StartElementHandler = start_element -p.EndElementHandler = end_element -p.CharacterDataHandler = char_data - -p.Parse("""<?xml version="1.0"?> -<parent id="top"><child1 name="paul">Text goes here</child1> -<child2 name="fred">More text</child2> -</parent>""", 1) -\end{verbatim} - -The output from this program is: - -\begin{verbatim} -Start element: parent {'id': 'top'} -Start element: child1 {'name': 'paul'} -Character data: 'Text goes here' -End element: child1 -Character data: '\n' -Start element: child2 {'name': 'fred'} -Character data: 'More text' -End element: child2 -Character data: '\n' -End element: parent -\end{verbatim} - - -\subsection{Content Model Descriptions \label{expat-content-models}} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -Content modules are described using nested tuples. Each tuple -contains four values: the type, the quantifier, the name, and a tuple -of children. Children are simply additional content module -descriptions. - -The values of the first two fields are constants defined in the -\code{model} object of the \module{xml.parsers.expat} module. These -constants can be collected in two groups: the model type group and the -quantifier group. - -The constants in the model type group are: - -\begin{datadescni}{XML_CTYPE_ANY} -The element named by the model name was declared to have a content -model of \code{ANY}. -\end{datadescni} - -\begin{datadescni}{XML_CTYPE_CHOICE} -The named element allows a choice from a number of options; this is -used for content models such as \code{(A | B | C)}. -\end{datadescni} - -\begin{datadescni}{XML_CTYPE_EMPTY} -Elements which are declared to be \code{EMPTY} have this model type. -\end{datadescni} - -\begin{datadescni}{XML_CTYPE_MIXED} -\end{datadescni} - -\begin{datadescni}{XML_CTYPE_NAME} -\end{datadescni} - -\begin{datadescni}{XML_CTYPE_SEQ} -Models which represent a series of models which follow one after the -other are indicated with this model type. This is used for models -such as \code{(A, B, C)}. -\end{datadescni} - - -The constants in the quantifier group are: - -\begin{datadescni}{XML_CQUANT_NONE} -No modifier is given, so it can appear exactly once, as for \code{A}. -\end{datadescni} - -\begin{datadescni}{XML_CQUANT_OPT} -The model is optional: it can appear once or not at all, as for -\code{A?}. -\end{datadescni} - -\begin{datadescni}{XML_CQUANT_PLUS} -The model must occur one or more times (like \code{A+}). -\end{datadescni} - -\begin{datadescni}{XML_CQUANT_REP} -The model must occur zero or more times, as for \code{A*}. -\end{datadescni} - - -\subsection{Expat error constants \label{expat-errors}} - -The following constants are provided in the \code{errors} object of -the \refmodule{xml.parsers.expat} module. These constants are useful -in interpreting some of the attributes of the \exception{ExpatError} -exception objects raised when an error has occurred. - -The \code{errors} object has the following attributes: - -\begin{datadescni}{XML_ERROR_ASYNC_ENTITY} -\end{datadescni} - -\begin{datadescni}{XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF} -An entity reference in an attribute value referred to an external -entity instead of an internal entity. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_BAD_CHAR_REF} -A character reference referred to a character which is illegal in XML -(for example, character \code{0}, or `\code{\&\#0;}'). -\end{datadescni} - -\begin{datadescni}{XML_ERROR_BINARY_ENTITY_REF} -An entity reference referred to an entity which was declared with a -notation, so cannot be parsed. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_DUPLICATE_ATTRIBUTE} -An attribute was used more than once in a start tag. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_INCORRECT_ENCODING} -\end{datadescni} - -\begin{datadescni}{XML_ERROR_INVALID_TOKEN} -Raised when an input byte could not properly be assigned to a -character; for example, a NUL byte (value \code{0}) in a UTF-8 input -stream. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_JUNK_AFTER_DOC_ELEMENT} -Something other than whitespace occurred after the document element. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_MISPLACED_XML_PI} -An XML declaration was found somewhere other than the start of the -input data. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_NO_ELEMENTS} -The document contains no elements (XML requires all documents to -contain exactly one top-level element).. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_NO_MEMORY} -Expat was not able to allocate memory internally. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_PARAM_ENTITY_REF} -A parameter entity reference was found where it was not allowed. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_PARTIAL_CHAR} -An incomplete character was found in the input. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_RECURSIVE_ENTITY_REF} -An entity reference contained another reference to the same entity; -possibly via a different name, and possibly indirectly. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_SYNTAX} -Some unspecified syntax error was encountered. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_TAG_MISMATCH} -An end tag did not match the innermost open start tag. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_UNCLOSED_TOKEN} -Some token (such as a start tag) was not closed before the end of the -stream or the next token was encountered. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_UNDEFINED_ENTITY} -A reference was made to a entity which was not defined. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_UNKNOWN_ENCODING} -The document encoding is not supported by Expat. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_UNCLOSED_CDATA_SECTION} -A CDATA marked section was not closed. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_EXTERNAL_ENTITY_HANDLING} -\end{datadescni} - -\begin{datadescni}{XML_ERROR_NOT_STANDALONE} -The parser determined that the document was not ``standalone'' though -it declared itself to be in the XML declaration, and the -\member{NotStandaloneHandler} was set and returned \code{0}. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_UNEXPECTED_STATE} -\end{datadescni} - -\begin{datadescni}{XML_ERROR_ENTITY_DECLARED_IN_PE} -\end{datadescni} - -\begin{datadescni}{XML_ERROR_FEATURE_REQUIRES_XML_DTD} -An operation was requested that requires DTD support to be compiled -in, but Expat was configured without DTD support. This should never -be reported by a standard build of the \module{xml.parsers.expat} -module. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING} -A behavioral change was requested after parsing started that can only -be changed before parsing has started. This is (currently) only -raised by \method{UseForeignDTD()}. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_UNBOUND_PREFIX} -An undeclared prefix was found when namespace processing was enabled. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_UNDECLARING_PREFIX} -The document attempted to remove the namespace declaration associated -with a prefix. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_INCOMPLETE_PE} -A parameter entity contained incomplete markup. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_XML_DECL} -The document contained no document element at all. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_TEXT_DECL} -There was an error parsing a text declaration in an external entity. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_PUBLICID} -Characters were found in the public id that are not allowed. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_SUSPENDED} -The requested operation was made on a suspended parser, but isn't -allowed. This includes attempts to provide additional input or to -stop the parser. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_NOT_SUSPENDED} -An attempt to resume the parser was made when the parser had not been -suspended. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_ABORTED} -This should not be reported to Python applications. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_FINISHED} -The requested operation was made on a parser which was finished -parsing input, but isn't allowed. This includes attempts to provide -additional input or to stop the parser. -\end{datadescni} - -\begin{datadescni}{XML_ERROR_SUSPEND_PE} -\end{datadescni} diff --git a/Doc/lib/libpython.tex b/Doc/lib/libpython.tex deleted file mode 100644 index c41c386..0000000 --- a/Doc/lib/libpython.tex +++ /dev/null @@ -1,8 +0,0 @@ -\chapter{Python Runtime Services - \label{python}} - -The modules described in this chapter provide a wide range of services -related to the Python interpreter and its interaction with its -environment. Here's an overview: - -\localmoduletable diff --git a/Doc/lib/libqueue.tex b/Doc/lib/libqueue.tex deleted file mode 100644 index 591a910..0000000 --- a/Doc/lib/libqueue.tex +++ /dev/null @@ -1,145 +0,0 @@ - -\section{\module{Queue} --- - A synchronized queue class} - -\declaremodule{standard}{Queue} -\modulesynopsis{A synchronized queue class.} - - -The \module{Queue} module implements a multi-producer, multi-consumer -FIFO queue. It is especially useful in threads programming when -information must be exchanged safely between multiple threads. The -\class{Queue} class in this module implements all the required locking -semantics. It depends on the availability of thread support in -Python. - -The \module{Queue} module defines the following class and exception: - - -\begin{classdesc}{Queue}{maxsize} -Constructor for the class. \var{maxsize} is an integer that sets the -upperbound limit on the number of items that can be placed in the -queue. Insertion will block once this size has been reached, until -queue items are consumed. If \var{maxsize} is less than or equal to -zero, the queue size is infinite. -\end{classdesc} - -\begin{excdesc}{Empty} -Exception raised when non-blocking \method{get()} (or -\method{get_nowait()}) is called on a \class{Queue} object which is -empty. -\end{excdesc} - -\begin{excdesc}{Full} -Exception raised when non-blocking \method{put()} (or -\method{put_nowait()}) is called on a \class{Queue} object which is -full. -\end{excdesc} - -\subsection{Queue Objects} -\label{QueueObjects} - -Class \class{Queue} implements queue objects and has the methods -described below. This class can be derived from in order to implement -other queue organizations (e.g. stack) but the inheritable interface -is not described here. See the source code for details. The public -methods are: - -\begin{methoddesc}[Queue]{qsize}{} -Return the approximate size of the queue. Because of multithreading -semantics, this number is not reliable. -\end{methoddesc} - -\begin{methoddesc}[Queue]{empty}{} -Return \code{True} if the queue is empty, \code{False} otherwise. -Because of multithreading semantics, this is not reliable. -\end{methoddesc} - -\begin{methoddesc}[Queue]{full}{} -Return \code{True} if the queue is full, \code{False} otherwise. -Because of multithreading semantics, this is not reliable. -\end{methoddesc} - -\begin{methoddesc}[Queue]{put}{item\optional{, block\optional{, timeout}}} -Put \var{item} into the queue. If optional args \var{block} is true -and \var{timeout} is None (the default), block if necessary until a -free slot is available. If \var{timeout} is a positive number, it -blocks at most \var{timeout} seconds and raises the \exception{Full} -exception if no free slot was available within that time. -Otherwise (\var{block} is false), put an item on the queue if a free -slot is immediately available, else raise the \exception{Full} -exception (\var{timeout} is ignored in that case). - -\versionadded[the timeout parameter]{2.3} - -\end{methoddesc} - -\begin{methoddesc}[Queue]{put_nowait}{item} -Equivalent to \code{put(\var{item}, False)}. -\end{methoddesc} - -\begin{methoddesc}[Queue]{get}{\optional{block\optional{, timeout}}} -Remove and return an item from the queue. If optional args -\var{block} is true and \var{timeout} is None (the default), -block if necessary until an item is available. If \var{timeout} is -a positive number, it blocks at most \var{timeout} seconds and raises -the \exception{Empty} exception if no item was available within that -time. Otherwise (\var{block} is false), return an item if one is -immediately available, else raise the \exception{Empty} exception -(\var{timeout} is ignored in that case). - -\versionadded[the timeout parameter]{2.3} - -\end{methoddesc} - -\begin{methoddesc}[Queue]{get_nowait}{} -Equivalent to \code{get(False)}. -\end{methoddesc} - -Two methods are offered to support tracking whether enqueued tasks have -been fully processed by daemon consumer threads. - -\begin{methoddesc}[Queue]{task_done}{} -Indicate that a formerly enqueued task is complete. Used by queue consumer -threads. For each \method{get()} used to fetch a task, a subsequent call to -\method{task_done()} tells the queue that the processing on the task is complete. - -If a \method{join()} is currently blocking, it will resume when all items -have been processed (meaning that a \method{task_done()} call was received -for every item that had been \method{put()} into the queue). - -Raises a \exception{ValueError} if called more times than there were items -placed in the queue. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[Queue]{join}{} -Blocks until all items in the queue have been gotten and processed. - -The count of unfinished tasks goes up whenever an item is added to the -queue. The count goes down whenever a consumer thread calls \method{task_done()} -to indicate that the item was retrieved and all work on it is complete. -When the count of unfinished tasks drops to zero, join() unblocks. -\versionadded{2.5} -\end{methoddesc} - -Example of how to wait for enqueued tasks to be completed: - -\begin{verbatim} - def worker(): - while True: - item = q.get() - do_work(item) - q.task_done() - - q = Queue() - for i in range(num_worker_threads): - t = Thread(target=worker) - t.setDaemon(True) - t.start() - - for item in source(): - q.put(item) - - q.join() # block until all tasks are done -\end{verbatim} diff --git a/Doc/lib/libquopri.tex b/Doc/lib/libquopri.tex deleted file mode 100644 index 9e7895b..0000000 --- a/Doc/lib/libquopri.tex +++ /dev/null @@ -1,61 +0,0 @@ -\section{\module{quopri} --- - Encode and decode MIME quoted-printable data} - -\declaremodule{standard}{quopri} -\modulesynopsis{Encode and decode files using the MIME - quoted-printable encoding.} - - -This module performs quoted-printable transport encoding and decoding, -as defined in \rfc{1521}: ``MIME (Multipurpose Internet Mail -Extensions) Part One: Mechanisms for Specifying and Describing the -Format of Internet Message Bodies''. The quoted-printable encoding is -designed for data where there are relatively few nonprintable -characters; the base64 encoding scheme available via the -\refmodule{base64} module is more compact if there are many such -characters, as when sending a graphics file. -\indexii{quoted-printable}{encoding} -\index{MIME!quoted-printable encoding} - - -\begin{funcdesc}{decode}{input, output\optional{,header}} -Decode the contents of the \var{input} file and write the resulting -decoded binary data to the \var{output} file. -\var{input} and \var{output} must either be file objects or objects that -mimic the file object interface. \var{input} will be read until -\code{\var{input}.readline()} returns an empty string. -If the optional argument \var{header} is present and true, underscore -will be decoded as space. This is used to decode -``Q''-encoded headers as described in \rfc{1522}: ``MIME (Multipurpose Internet Mail Extensions) -Part Two: Message Header Extensions for Non-ASCII Text''. -\end{funcdesc} - -\begin{funcdesc}{encode}{input, output, quotetabs} -Encode the contents of the \var{input} file and write the resulting -quoted-printable data to the \var{output} file. -\var{input} and \var{output} must either be file objects or objects that -mimic the file object interface. \var{input} will be read until -\code{\var{input}.readline()} returns an empty string. -\var{quotetabs} is a flag which controls whether to encode embedded -spaces and tabs; when true it encodes such embedded whitespace, and -when false it leaves them unencoded. Note that spaces and tabs -appearing at the end of lines are always encoded, as per \rfc{1521}. -\end{funcdesc} - -\begin{funcdesc}{decodestring}{s\optional{,header}} -Like \function{decode()}, except that it accepts a source string and -returns the corresponding decoded string. -\end{funcdesc} - -\begin{funcdesc}{encodestring}{s\optional{, quotetabs}} -Like \function{encode()}, except that it accepts a source string and -returns the corresponding encoded string. \var{quotetabs} is optional -(defaulting to 0), and is passed straight through to -\function{encode()}. -\end{funcdesc} - - -\begin{seealso} - \seemodule{mimify}{General utilities for processing of MIME messages.} - \seemodule{base64}{Encode and decode MIME base64 data} -\end{seealso} diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex deleted file mode 100644 index a9bd5ac..0000000 --- a/Doc/lib/librandom.tex +++ /dev/null @@ -1,309 +0,0 @@ -\section{\module{random} --- - Generate pseudo-random numbers} - -\declaremodule{standard}{random} -\modulesynopsis{Generate pseudo-random numbers with various common - distributions.} - - -This module implements pseudo-random number generators for various -distributions. - -For integers, uniform selection from a range. -For sequences, uniform selection of a random element, a function to -generate a random permutation of a list in-place, and a function for -random sampling without replacement. - -On the real line, there are functions to compute uniform, normal (Gaussian), -lognormal, negative exponential, gamma, and beta distributions. -For generating distributions of angles, the von Mises distribution -is available. - -Almost all module functions depend on the basic function -\function{random()}, which generates a random float uniformly in -the semi-open range [0.0, 1.0). Python uses the Mersenne Twister as -the core generator. It produces 53-bit precision floats and has a -period of 2**19937-1. The underlying implementation in C -is both fast and threadsafe. The Mersenne Twister is one of the most -extensively tested random number generators in existence. However, being -completely deterministic, it is not suitable for all purposes, and is -completely unsuitable for cryptographic purposes. - -The functions supplied by this module are actually bound methods of a -hidden instance of the \class{random.Random} class. You can -instantiate your own instances of \class{Random} to get generators -that don't share state. This is especially useful for multi-threaded -programs, creating a different instance of \class{Random} for each -thread, and using the \method{jumpahead()} method to make it likely that the -generated sequences seen by each thread don't overlap. - -Class \class{Random} can also be subclassed if you want to use a -different basic generator of your own devising: in that case, override -the \method{random()}, \method{seed()}, \method{getstate()}, -\method{setstate()} and \method{jumpahead()} methods. -Optionally, a new generator can supply a \method{getrandombits()} -method --- this allows \method{randrange()} to produce selections -over an arbitrarily large range. -\versionadded[the \method{getrandombits()} method]{2.4} - -As an example of subclassing, the \module{random} module provides -the \class{WichmannHill} class that implements an alternative generator -in pure Python. The class provides a backward compatible way to -reproduce results from earlier versions of Python, which used the -Wichmann-Hill algorithm as the core generator. Note that this Wichmann-Hill -generator can no longer be recommended: its period is too short by -contemporary standards, and the sequence generated is known to fail some -stringent randomness tests. See the references below for a recent -variant that repairs these flaws. -\versionchanged[Substituted MersenneTwister for Wichmann-Hill]{2.3} - - -Bookkeeping functions: - -\begin{funcdesc}{seed}{\optional{x}} - Initialize the basic random number generator. - Optional argument \var{x} can be any hashable object. - If \var{x} is omitted or \code{None}, current system time is used; - current system time is also used to initialize the generator when the - module is first imported. If randomness sources are provided by the - operating system, they are used instead of the system time (see the - \function{os.urandom()} - function for details on availability). \versionchanged[formerly, - operating system resources were not used]{2.4} - If \var{x} is not \code{None} or an int or long, - \code{hash(\var{x})} is used instead. - If \var{x} is an int or long, \var{x} is used directly. -\end{funcdesc} - -\begin{funcdesc}{getstate}{} - Return an object capturing the current internal state of the - generator. This object can be passed to \function{setstate()} to - restore the state. - \versionadded{2.1} -\end{funcdesc} - -\begin{funcdesc}{setstate}{state} - \var{state} should have been obtained from a previous call to - \function{getstate()}, and \function{setstate()} restores the - internal state of the generator to what it was at the time - \function{setstate()} was called. - \versionadded{2.1} -\end{funcdesc} - -\begin{funcdesc}{jumpahead}{n} - Change the internal state to one different from and likely far away from - the current state. \var{n} is a non-negative integer which is used to - scramble the current state vector. This is most useful in multi-threaded - programs, in conjuction with multiple instances of the \class{Random} - class: \method{setstate()} or \method{seed()} can be used to force all - instances into the same internal state, and then \method{jumpahead()} - can be used to force the instances' states far apart. - \versionadded{2.1} - \versionchanged[Instead of jumping to a specific state, \var{n} steps - ahead, \method{jumpahead(\var{n})} jumps to another state likely to be - separated by many steps]{2.3} - \end{funcdesc} - -\begin{funcdesc}{getrandbits}{k} - Returns a python \class{long} int with \var{k} random bits. - This method is supplied with the MersenneTwister generator and some - other generators may also provide it as an optional part of the API. - When available, \method{getrandbits()} enables \method{randrange()} - to handle arbitrarily large ranges. - \versionadded{2.4} -\end{funcdesc} - -Functions for integers: - -\begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}} - Return a randomly selected element from \code{range(\var{start}, - \var{stop}, \var{step})}. This is equivalent to - \code{choice(range(\var{start}, \var{stop}, \var{step}))}, - but doesn't actually build a range object. - \versionadded{1.5.2} -\end{funcdesc} - -\begin{funcdesc}{randint}{a, b} - Return a random integer \var{N} such that - \code{\var{a} <= \var{N} <= \var{b}}. -\end{funcdesc} - - -Functions for sequences: - -\begin{funcdesc}{choice}{seq} - Return a random element from the non-empty sequence \var{seq}. - If \var{seq} is empty, raises \exception{IndexError}. -\end{funcdesc} - -\begin{funcdesc}{shuffle}{x\optional{, random}} - Shuffle the sequence \var{x} in place. - The optional argument \var{random} is a 0-argument function - returning a random float in [0.0, 1.0); by default, this is the - function \function{random()}. - - Note that for even rather small \code{len(\var{x})}, the total - number of permutations of \var{x} is larger than the period of most - random number generators; this implies that most permutations of a - long sequence can never be generated. -\end{funcdesc} - -\begin{funcdesc}{sample}{population, k} - Return a \var{k} length list of unique elements chosen from the - population sequence. Used for random sampling without replacement. - \versionadded{2.3} - - Returns a new list containing elements from the population while - leaving the original population unchanged. The resulting list is - in selection order so that all sub-slices will also be valid random - samples. This allows raffle winners (the sample) to be partitioned - into grand prize and second place winners (the subslices). - - Members of the population need not be hashable or unique. If the - population contains repeats, then each occurrence is a possible - selection in the sample. - - To choose a sample from a range of integers, use an \function{range()} - object as an argument. This is especially fast and space efficient for - sampling from a large population: \code{sample(range(10000000), 60)}. -\end{funcdesc} - - -The following functions generate specific real-valued distributions. -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. - -\begin{funcdesc}{random}{} - Return the next random floating point number in the range [0.0, 1.0). -\end{funcdesc} - -\begin{funcdesc}{uniform}{a, b} - Return a random real number \var{N} such that - \code{\var{a} <= \var{N} < \var{b}}. -\end{funcdesc} - -\begin{funcdesc}{betavariate}{alpha, beta} - Beta distribution. Conditions on the parameters are - \code{\var{alpha} > 0} and \code{\var{beta} > 0}. - Returned values range between 0 and 1. -\end{funcdesc} - -\begin{funcdesc}{expovariate}{lambd} - Exponential distribution. \var{lambd} is 1.0 divided by the desired - mean. (The parameter would be called ``lambda'', but that is a - reserved word in Python.) Returned values range from 0 to - positive infinity. -\end{funcdesc} - -\begin{funcdesc}{gammavariate}{alpha, beta} - Gamma distribution. (\emph{Not} the gamma function!) Conditions on - the parameters are \code{\var{alpha} > 0} and \code{\var{beta} > 0}. -\end{funcdesc} - -\begin{funcdesc}{gauss}{mu, sigma} - Gaussian distribution. \var{mu} is the mean, and \var{sigma} is the - standard deviation. This is slightly faster than the - \function{normalvariate()} function defined below. -\end{funcdesc} - -\begin{funcdesc}{lognormvariate}{mu, sigma} - Log normal distribution. If you take the natural logarithm of this - distribution, you'll get a normal distribution with mean \var{mu} - and standard deviation \var{sigma}. \var{mu} can have any value, - and \var{sigma} must be greater than zero. -\end{funcdesc} - -\begin{funcdesc}{normalvariate}{mu, sigma} - Normal distribution. \var{mu} is the mean, and \var{sigma} is the - standard deviation. -\end{funcdesc} - -\begin{funcdesc}{vonmisesvariate}{mu, kappa} - \var{mu} is the mean angle, expressed in radians between 0 and - 2*\emph{pi}, and \var{kappa} is the concentration parameter, which - must be greater than or equal to zero. If \var{kappa} is equal to - zero, this distribution reduces to a uniform random angle over the - range 0 to 2*\emph{pi}. -\end{funcdesc} - -\begin{funcdesc}{paretovariate}{alpha} - Pareto distribution. \var{alpha} is the shape parameter. -\end{funcdesc} - -\begin{funcdesc}{weibullvariate}{alpha, beta} - Weibull distribution. \var{alpha} is the scale parameter and - \var{beta} is the shape parameter. -\end{funcdesc} - -Alternative Generators: - -\begin{classdesc}{WichmannHill}{\optional{seed}} -Class that implements the Wichmann-Hill algorithm as the core generator. -Has all of the same methods as \class{Random} plus the \method{whseed()} -method described below. Because this class is implemented in pure -Python, it is not threadsafe and may require locks between calls. The -period of the generator is 6,953,607,871,644 which is small enough to -require care that two independent random sequences do not overlap. -\end{classdesc} - -\begin{funcdesc}{whseed}{\optional{x}} - This is obsolete, supplied for bit-level compatibility with versions - of Python prior to 2.1. - See \function{seed()} for details. \function{whseed()} does not guarantee - that distinct integer arguments yield distinct internal states, and can - yield no more than about 2**24 distinct internal states in all. -\end{funcdesc} - -\begin{classdesc}{SystemRandom}{\optional{seed}} -Class that uses the \function{os.urandom()} function for generating -random numbers from sources provided by the operating system. -Not available on all systems. -Does not rely on software state and sequences are not reproducible. -Accordingly, the \method{seed()} and \method{jumpahead()} methods -have no effect and are ignored. The \method{getstate()} and -\method{setstate()} methods raise \exception{NotImplementedError} if -called. -\versionadded{2.4} -\end{classdesc} - -Examples of basic usage: - -\begin{verbatim} ->>> random.random() # Random float x, 0.0 <= x < 1.0 -0.37444887175646646 ->>> random.uniform(1, 10) # Random float x, 1.0 <= x < 10.0 -1.1800146073117523 ->>> random.randint(1, 10) # Integer from 1 to 10, endpoints included -7 ->>> random.randrange(0, 101, 2) # Even integer from 0 to 100 -26 ->>> random.choice('abcdefghij') # Choose a random element -'c' - ->>> items = [1, 2, 3, 4, 5, 6, 7] ->>> random.shuffle(items) ->>> items -[7, 3, 2, 5, 6, 4, 1] - ->>> random.sample([1, 2, 3, 4, 5], 3) # Choose 3 elements -[4, 1, 5] - -\end{verbatim} - -\begin{seealso} - \seetext{M. Matsumoto and T. Nishimura, ``Mersenne Twister: A - 623-dimensionally equidistributed uniform pseudorandom - number generator'', - \citetitle{ACM Transactions on Modeling and Computer Simulation} - Vol. 8, No. 1, January pp.3-30 1998.} - - \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.} - - \seeurl{http://www.npl.co.uk/ssfm/download/abstracts.html\#196}{A modern - variation of the Wichmann-Hill generator that greatly increases - the period, and passes now-standard statistical tests that the - original generator failed.} -\end{seealso} diff --git a/Doc/lib/libre.tex b/Doc/lib/libre.tex deleted file mode 100644 index a0b8b51..0000000 --- a/Doc/lib/libre.tex +++ /dev/null @@ -1,954 +0,0 @@ -\section{\module{re} --- - Regular expression operations} -\declaremodule{standard}{re} -\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com} -\sectionauthor{Andrew M. Kuchling}{amk@amk.ca} - - -\modulesynopsis{Regular expression search and match operations with a - Perl-style expression syntax.} - - -This module provides regular expression matching operations similar to -those found in Perl. Regular expression pattern strings may not -contain null bytes, but can specify the null byte using the -\code{\e\var{number}} notation. Both patterns and strings to be -searched can be Unicode strings as well as 8-bit strings. The -\module{re} module is always available. - -Regular expressions use the backslash character (\character{\e}) to -indicate special forms or to allow special characters to be used -without invoking their special meaning. This collides with Python's -usage of the same character for the same purpose in string literals; -for example, to match a literal backslash, one might have to write -\code{'\e\e\e\e'} as the pattern string, because the regular expression -must be \samp{\e\e}, and each backslash must be expressed as -\samp{\e\e} inside a regular Python string literal. - -The solution is to use Python's raw string notation for regular -expression patterns; backslashes are not handled in any special way in -a string literal prefixed with \character{r}. So \code{r"\e n"} is a -two-character string containing \character{\e} and \character{n}, -while \code{"\e n"} is a one-character string containing a newline. -Usually patterns will be expressed in Python code using this raw -string notation. - -\begin{seealso} - \seetitle{Mastering Regular Expressions}{Book on regular expressions - by Jeffrey Friedl, published by O'Reilly. The second - edition of the book no longer covers Python at all, - but the first edition covered writing good regular expression - patterns in great detail.} -\end{seealso} - - -\subsection{Regular Expression Syntax \label{re-syntax}} - -A regular expression (or RE) specifies a set of strings that matches -it; the functions in this module let you check if a particular string -matches a given regular expression (or if a given regular expression -matches a particular string, which comes down to the same thing). - -Regular expressions can be concatenated to form new regular -expressions; if \emph{A} and \emph{B} are both regular expressions, -then \emph{AB} is also a regular expression. In general, if a string -\emph{p} matches \emph{A} and another string \emph{q} matches \emph{B}, -the string \emph{pq} will match AB. This holds unless \emph{A} or -\emph{B} contain low precedence operations; boundary conditions between -\emph{A} and \emph{B}; or have numbered group references. Thus, complex -expressions can easily be constructed from simpler primitive -expressions like the ones described here. For details of the theory -and implementation of regular expressions, consult the Friedl book -referenced above, or almost any textbook about compiler construction. - -A brief explanation of the format of regular expressions follows. For -further information and a gentler presentation, consult the Regular -Expression HOWTO, accessible from \url{http://www.python.org/doc/howto/}. - -Regular expressions can contain both special and ordinary characters. -Most ordinary characters, like \character{A}, \character{a}, or -\character{0}, are the simplest regular expressions; they simply match -themselves. You can concatenate ordinary characters, so \regexp{last} -matches the string \code{'last'}. (In the rest of this section, we'll -write RE's in \regexp{this special style}, usually without quotes, and -strings to be matched \code{'in single quotes'}.) - -Some characters, like \character{|} or \character{(}, are special. -Special characters either stand for classes of ordinary characters, or -affect how the regular expressions around them are interpreted. - -The special characters are: -% -\begin{description} - -\item[\character{.}] (Dot.) In the default mode, this matches any -character except a newline. If the \constant{DOTALL} flag has been -specified, this matches any character including a newline. - -\item[\character{\textasciicircum}] (Caret.) Matches the start of the -string, and in \constant{MULTILINE} mode also matches immediately -after each newline. - -\item[\character{\$}] Matches the end of the string or just before the -newline at the end of the string, and in \constant{MULTILINE} mode -also matches before a newline. \regexp{foo} matches both 'foo' and -'foobar', while the regular expression \regexp{foo\$} matches only -'foo'. More interestingly, searching for \regexp{foo.\$} in -'foo1\textbackslash nfoo2\textbackslash n' matches 'foo2' normally, -but 'foo1' in \constant{MULTILINE} mode. - -\item[\character{*}] Causes the resulting RE to -match 0 or more repetitions of the preceding RE, as many repetitions -as are possible. \regexp{ab*} will -match 'a', 'ab', or 'a' followed by any number of 'b's. - -\item[\character{+}] Causes the -resulting RE to match 1 or more repetitions of the preceding RE. -\regexp{ab+} will match 'a' followed by any non-zero number of 'b's; it -will not match just 'a'. - -\item[\character{?}] Causes the resulting RE to -match 0 or 1 repetitions of the preceding RE. \regexp{ab?} will -match either 'a' or 'ab'. - -\item[\code{*?}, \code{+?}, \code{??}] The \character{*}, -\character{+}, and \character{?} qualifiers are all \dfn{greedy}; they -match as much text as possible. Sometimes this behaviour isn't -desired; if the RE \regexp{<.*>} is matched against -\code{'<H1>title</H1>'}, it will match the entire string, and not just -\code{'<H1>'}. Adding \character{?} after the qualifier makes it -perform the match in \dfn{non-greedy} or \dfn{minimal} fashion; as -\emph{few} characters as possible will be matched. Using \regexp{.*?} -in the previous expression will match only \code{'<H1>'}. - -\item[\code{\{\var{m}\}}] -Specifies that exactly \var{m} copies of the previous RE should be -matched; fewer matches cause the entire RE not to match. For example, -\regexp{a\{6\}} will match exactly six \character{a} characters, but -not five. - -\item[\code{\{\var{m},\var{n}\}}] Causes the resulting RE to match from -\var{m} to \var{n} repetitions of the preceding RE, attempting to -match as many repetitions as possible. For example, \regexp{a\{3,5\}} -will match from 3 to 5 \character{a} characters. Omitting \var{m} -specifies a lower bound of zero, -and omitting \var{n} specifies an infinite upper bound. As an -example, \regexp{a\{4,\}b} will match \code{aaaab} or a thousand -\character{a} characters followed by a \code{b}, but not \code{aaab}. -The comma may not be omitted or the modifier would be confused with -the previously described form. - -\item[\code{\{\var{m},\var{n}\}?}] Causes the resulting RE to -match from \var{m} to \var{n} repetitions of the preceding RE, -attempting to match as \emph{few} repetitions as possible. This is -the non-greedy version of the previous qualifier. For example, on the -6-character string \code{'aaaaaa'}, \regexp{a\{3,5\}} will match 5 -\character{a} characters, while \regexp{a\{3,5\}?} will only match 3 -characters. - -\item[\character{\e}] Either escapes special characters (permitting -you to match characters like \character{*}, \character{?}, and so -forth), or signals a special sequence; special sequences are discussed -below. - -If you're not using a raw string to -express the pattern, remember that Python also uses the -backslash as an escape sequence in string literals; if the escape -sequence isn't recognized by Python's parser, the backslash and -subsequent character are included in the resulting string. However, -if Python would recognize the resulting sequence, the backslash should -be repeated twice. This is complicated and hard to understand, so -it's highly recommended that you use raw strings for all but the -simplest expressions. - -\item[\code{[]}] Used to indicate a set of characters. Characters can -be listed individually, or a range of characters can be indicated by -giving two characters and separating them by a \character{-}. Special -characters are not active inside sets. For example, \regexp{[akm\$]} -will match any of the characters \character{a}, \character{k}, -\character{m}, or \character{\$}; \regexp{[a-z]} -will match any lowercase letter, and \code{[a-zA-Z0-9]} matches any -letter or digit. Character classes such as \code{\e w} or \code{\e S} -(defined below) are also acceptable inside a range. If you want to -include a \character{]} or a \character{-} inside a set, precede it with a -backslash, or place it as the first character. The -pattern \regexp{[]]} will match \code{']'}, for example. - -You can match the characters not within a range by \dfn{complementing} -the set. This is indicated by including a -\character{\textasciicircum} as the first character of the set; -\character{\textasciicircum} elsewhere will simply match the -\character{\textasciicircum} character. For example, -\regexp{[{\textasciicircum}5]} will match -any character except \character{5}, and -\regexp{[\textasciicircum\code{\textasciicircum}]} will match any character -except \character{\textasciicircum}. - -\item[\character{|}]\code{A|B}, where A and B can be arbitrary REs, -creates a regular expression that will match either A or B. An -arbitrary number of REs can be separated by the \character{|} in this -way. This can be used inside groups (see below) as well. As the target -string is scanned, REs separated by \character{|} are tried from left to -right. When one pattern completely matches, that branch is accepted. -This means that once \code{A} matches, \code{B} will not be tested further, -even if it would produce a longer overall match. In other words, the -\character{|} operator is never greedy. To match a literal \character{|}, -use \regexp{\e|}, or enclose it inside a character class, as in \regexp{[|]}. - -\item[\code{(...)}] Matches whatever regular expression is inside the -parentheses, and indicates the start and end of a group; the contents -of a group can be retrieved after a match has been performed, and can -be matched later in the string with the \regexp{\e \var{number}} special -sequence, described below. To match the literals \character{(} or -\character{)}, use \regexp{\e(} or \regexp{\e)}, or enclose them -inside a character class: \regexp{[(] [)]}. - -\item[\code{(?...)}] This is an extension notation (a \character{?} -following a \character{(} is not meaningful otherwise). The first -character after the \character{?} -determines what the meaning and further syntax of the construct is. -Extensions usually do not create a new group; -\regexp{(?P<\var{name}>...)} is the only exception to this rule. -Following are the currently supported extensions. - -\item[\code{(?iLmsux)}] (One or more letters from the set \character{i}, -\character{L}, \character{m}, \character{s}, \character{u}, -\character{x}.) The group matches the empty string; the letters set -the corresponding flags (\constant{re.I}, \constant{re.L}, -\constant{re.M}, \constant{re.S}, \constant{re.U}, \constant{re.X}) -for the entire regular expression. This is useful if you wish to -include the flags as part of the regular expression, instead of -passing a \var{flag} argument to the \function{compile()} function. - -Note that the \regexp{(?x)} flag changes how the expression is parsed. -It should be used first in the expression string, or after one or more -whitespace characters. If there are non-whitespace characters before -the flag, the results are undefined. - -\item[\code{(?:...)}] A non-grouping version of regular parentheses. -Matches whatever regular expression is inside the parentheses, but the -substring matched by the -group \emph{cannot} be retrieved after performing a match or -referenced later in the pattern. - -\item[\code{(?P<\var{name}>...)}] Similar to regular parentheses, but -the substring matched by the group is accessible via the symbolic group -name \var{name}. Group names must be valid Python identifiers, and -each group name must be defined only once within a regular expression. A -symbolic group is also a numbered group, just as if the group were not -named. So the group named 'id' in the example above can also be -referenced as the numbered group 1. - -For example, if the pattern is -\regexp{(?P<id>[a-zA-Z_]\e w*)}, the group can be referenced by its -name in arguments to methods of match objects, such as -\code{m.group('id')} or \code{m.end('id')}, and also by name in -pattern text (for example, \regexp{(?P=id)}) and replacement text -(such as \code{\e g<id>}). - -\item[\code{(?P=\var{name})}] Matches whatever text was matched by the -earlier group named \var{name}. - -\item[\code{(?\#...)}] A comment; the contents of the parentheses are -simply ignored. - -\item[\code{(?=...)}] Matches if \regexp{...} matches next, but doesn't -consume any of the string. This is called a lookahead assertion. For -example, \regexp{Isaac (?=Asimov)} will match \code{'Isaac~'} only if it's -followed by \code{'Asimov'}. - -\item[\code{(?!...)}] Matches if \regexp{...} doesn't match next. This -is a negative lookahead assertion. For example, -\regexp{Isaac (?!Asimov)} will match \code{'Isaac~'} only if it's \emph{not} -followed by \code{'Asimov'}. - -\item[\code{(?<=...)}] Matches if the current position in the string -is preceded by a match for \regexp{...} that ends at the current -position. This is called a \dfn{positive lookbehind assertion}. -\regexp{(?<=abc)def} will find a match in \samp{abcdef}, since the -lookbehind will back up 3 characters and check if the contained -pattern matches. The contained pattern must only match strings of -some fixed length, meaning that \regexp{abc} or \regexp{a|b} are -allowed, but \regexp{a*} and \regexp{a\{3,4\}} are not. Note that -patterns which start with positive lookbehind assertions will never -match at the beginning of the string being searched; you will most -likely want to use the \function{search()} function rather than the -\function{match()} function: - -\begin{verbatim} ->>> import re ->>> m = re.search('(?<=abc)def', 'abcdef') ->>> m.group(0) -'def' -\end{verbatim} - -This example looks for a word following a hyphen: - -\begin{verbatim} ->>> m = re.search('(?<=-)\w+', 'spam-egg') ->>> m.group(0) -'egg' -\end{verbatim} - -\item[\code{(?<!...)}] Matches if the current position in the string -is not preceded by a match for \regexp{...}. This is called a -\dfn{negative lookbehind assertion}. Similar to positive lookbehind -assertions, the contained pattern must only match strings of some -fixed length. Patterns which start with negative lookbehind -assertions may match at the beginning of the string being searched. - -\item[\code{(?(\var{id/name})yes-pattern|no-pattern)}] Will try to match -with \regexp{yes-pattern} if the group with given \var{id} or \var{name} -exists, and with \regexp{no-pattern} if it doesn't. \regexp{|no-pattern} -is optional and can be omitted. For example, -\regexp{(<)?(\e w+@\e w+(?:\e .\e w+)+)(?(1)>)} is a poor email matching -pattern, which will match with \code{'<user@host.com>'} as well as -\code{'user@host.com'}, but not with \code{'<user@host.com'}. -\versionadded{2.4} - -\end{description} - -The special sequences consist of \character{\e} and a character from the -list below. If the ordinary character is not on the list, then the -resulting RE will match the second character. For example, -\regexp{\e\$} matches the character \character{\$}. -% -\begin{description} - -\item[\code{\e \var{number}}] Matches the contents of the group of the -same number. Groups are numbered starting from 1. For example, -\regexp{(.+) \e 1} matches \code{'the the'} or \code{'55 55'}, but not -\code{'the end'} (note -the space after the group). This special sequence can only be used to -match one of the first 99 groups. If the first digit of \var{number} -is 0, or \var{number} is 3 octal digits long, it will not be interpreted -as a group match, but as the character with octal value \var{number}. -Inside the \character{[} and \character{]} of a character class, all numeric -escapes are treated as characters. - -\item[\code{\e A}] Matches only at the start of the string. - -\item[\code{\e b}] Matches the empty string, but only at the -beginning or end of a word. A word is defined as a sequence of -alphanumeric or underscore characters, so the end of a word is indicated by -whitespace or a non-alphanumeric, non-underscore character. Note that -{}\code{\e b} is defined as the boundary between \code{\e w} and \code{\e -W}, so the precise set of characters deemed to be alphanumeric depends on the -values of the \code{UNICODE} and \code{LOCALE} flags. Inside a character -range, \regexp{\e b} represents the backspace character, for compatibility -with Python's string literals. - -\item[\code{\e B}] Matches the empty string, but only when it is \emph{not} -at the beginning or end of a word. This is just the opposite of {}\code{\e -b}, so is also subject to the settings of \code{LOCALE} and \code{UNICODE}. - -\item[\code{\e d}]When the \constant{UNICODE} flag is not specified, matches -any decimal digit; this is equivalent to the set \regexp{[0-9]}. -With \constant{UNICODE}, it will match whatever is classified as a digit -in the Unicode character properties database. - -\item[\code{\e D}]When the \constant{UNICODE} flag is not specified, matches -any non-digit character; this is equivalent to the set -\regexp{[{\textasciicircum}0-9]}. With \constant{UNICODE}, it will match -anything other than character marked as digits in the Unicode character -properties database. - -\item[\code{\e s}]When the \constant{LOCALE} and \constant{UNICODE} -flags are not specified, matches any whitespace character; this is -equivalent to the set \regexp{[ \e t\e n\e r\e f\e v]}. -With \constant{LOCALE}, it will match this set plus whatever characters -are defined as space for the current locale. If \constant{UNICODE} is set, -this will match the characters \regexp{[ \e t\e n\e r\e f\e v]} plus -whatever is classified as space in the Unicode character properties -database. - -\item[\code{\e S}]When the \constant{LOCALE} and \constant{UNICODE} -flags are not specified, matches any non-whitespace character; this is -equivalent to the set \regexp{[\textasciicircum\ \e t\e n\e r\e f\e v]} -With \constant{LOCALE}, it will match any character not in this set, -and not defined as space in the current locale. If \constant{UNICODE} -is set, this will match anything other than \regexp{[ \e t\e n\e r\e f\e v]} -and characters marked as space in the Unicode character properties database. - -\item[\code{\e w}]When the \constant{LOCALE} and \constant{UNICODE} -flags are not specified, matches any alphanumeric character and the -underscore; this is equivalent to the set -\regexp{[a-zA-Z0-9_]}. With \constant{LOCALE}, it will match the set -\regexp{[0-9_]} plus whatever characters are defined as alphanumeric for -the current locale. If \constant{UNICODE} is set, this will match the -characters \regexp{[0-9_]} plus whatever is classified as alphanumeric -in the Unicode character properties database. - -\item[\code{\e W}]When the \constant{LOCALE} and \constant{UNICODE} -flags are not specified, matches any non-alphanumeric character; this -is equivalent to the set \regexp{[{\textasciicircum}a-zA-Z0-9_]}. With -\constant{LOCALE}, it will match any character not in the set -\regexp{[0-9_]}, and not defined as alphanumeric for the current locale. -If \constant{UNICODE} is set, this will match anything other than -\regexp{[0-9_]} and characters marked as alphanumeric in the Unicode -character properties database. - -\item[\code{\e Z}]Matches only at the end of the string. - -\end{description} - -Most of the standard escapes supported by Python string literals are -also accepted by the regular expression parser: - -\begin{verbatim} -\a \b \f \n -\r \t \v \x -\\ -\end{verbatim} - -Octal escapes are included in a limited form: If the first digit is a -0, or if there are three octal digits, it is considered an octal -escape. Otherwise, it is a group reference. As for string literals, -octal escapes are always at most three digits in length. - - -% Note the lack of a period in the section title; it causes problems -% with readers of the GNU info version. See http://www.python.org/sf/581414. -\subsection{Matching vs Searching \label{matching-searching}} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -Python offers two different primitive operations based on regular -expressions: match and search. If you are accustomed to Perl's -semantics, the search operation is what you're looking for. See the -\function{search()} function and corresponding method of compiled -regular expression objects. - -Note that match may differ from search using a regular expression -beginning with \character{\textasciicircum}: -\character{\textasciicircum} matches only at the -start of the string, or in \constant{MULTILINE} mode also immediately -following a newline. The ``match'' operation succeeds only if the -pattern matches at the start of the string regardless of mode, or at -the starting position given by the optional \var{pos} argument -regardless of whether a newline precedes it. - -% Examples from Tim Peters: -\begin{verbatim} -re.compile("a").match("ba", 1) # succeeds -re.compile("^a").search("ba", 1) # fails; 'a' not at start -re.compile("^a").search("\na", 1) # fails; 'a' not at start -re.compile("^a", re.M).search("\na", 1) # succeeds -re.compile("^a", re.M).search("ba", 1) # fails; no preceding \n -\end{verbatim} - - -\subsection{Module Contents} -\nodename{Contents of Module re} - -The module defines several functions, constants, and an exception. Some of the -functions are simplified versions of the full featured methods for compiled -regular expressions. Most non-trivial applications always use the compiled -form. - -\begin{funcdesc}{compile}{pattern\optional{, flags}} - Compile a regular expression pattern into a regular expression - object, which can be used for matching using its \function{match()} and - \function{search()} methods, described below. - - The expression's behaviour can be modified by specifying a - \var{flags} value. Values can be any of the following variables, - combined using bitwise OR (the \code{|} operator). - -The sequence - -\begin{verbatim} -prog = re.compile(pat) -result = prog.match(str) -\end{verbatim} - -is equivalent to - -\begin{verbatim} -result = re.match(pat, str) -\end{verbatim} - -but the version using \function{compile()} is more efficient when the -expression will be used several times in a single program. -%(The compiled version of the last pattern passed to -%\function{re.match()} or \function{re.search()} is cached, so -%programs that use only a single regular expression at a time needn't -%worry about compiling regular expressions.) -\end{funcdesc} - -\begin{datadesc}{I} -\dataline{IGNORECASE} -Perform case-insensitive matching; expressions like \regexp{[A-Z]} -will match lowercase letters, too. This is not affected by the -current locale. -\end{datadesc} - -\begin{datadesc}{L} -\dataline{LOCALE} -Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, \regexp{\e B}, -\regexp{\e s} and \regexp{\e S} dependent on the current locale. -\end{datadesc} - -\begin{datadesc}{M} -\dataline{MULTILINE} -When specified, the pattern character \character{\textasciicircum} -matches at the beginning of the string and at the beginning of each -line (immediately following each newline); and the pattern character -\character{\$} matches at the end of the string and at the end of each -line (immediately preceding each newline). By default, -\character{\textasciicircum} matches only at the beginning of the -string, and \character{\$} only at the end of the string and -immediately before the newline (if any) at the end of the string. -\end{datadesc} - -\begin{datadesc}{S} -\dataline{DOTALL} -Make the \character{.} special character match any character at all, -including a newline; without this flag, \character{.} will match -anything \emph{except} a newline. -\end{datadesc} - -\begin{datadesc}{U} -\dataline{UNICODE} -Make \regexp{\e w}, \regexp{\e W}, \regexp{\e b}, \regexp{\e B}, -\regexp{\e d}, \regexp{\e D}, \regexp{\e s} and \regexp{\e S} -dependent on the Unicode character properties database. -\versionadded{2.0} -\end{datadesc} - -\begin{datadesc}{X} -\dataline{VERBOSE} -This flag allows you to write regular expressions that look nicer. -Whitespace within the pattern is ignored, -except when in a character class or preceded by an unescaped -backslash, and, when a line contains a \character{\#} neither in a -character class or preceded by an unescaped backslash, all characters -from the leftmost such \character{\#} through the end of the line are -ignored. -% XXX should add an example here -\end{datadesc} - - -\begin{funcdesc}{search}{pattern, string\optional{, flags}} - Scan through \var{string} looking for a location where the regular - expression \var{pattern} produces a match, and return a - corresponding \class{MatchObject} instance. - Return \code{None} if no - position in the string matches the pattern; note that this is - different from finding a zero-length match at some point in the string. -\end{funcdesc} - -\begin{funcdesc}{match}{pattern, string\optional{, flags}} - If zero or more characters at the beginning of \var{string} match - the regular expression \var{pattern}, return a corresponding - \class{MatchObject} instance. Return \code{None} if the string does not - match the pattern; note that this is different from a zero-length - match. - - \note{If you want to locate a match anywhere in - \var{string}, use \method{search()} instead.} -\end{funcdesc} - -\begin{funcdesc}{split}{pattern, string\optional{, maxsplit\code{ = 0}}} - Split \var{string} by the occurrences of \var{pattern}. If - capturing parentheses are used in \var{pattern}, then the text of all - groups in the pattern are also returned as part of the resulting list. - If \var{maxsplit} is nonzero, at most \var{maxsplit} splits - occur, and the remainder of the string is returned as the final - element of the list. (Incompatibility note: in the original Python - 1.5 release, \var{maxsplit} was ignored. This has been fixed in - later releases.) - -\begin{verbatim} ->>> re.split('\W+', 'Words, words, words.') -['Words', 'words', 'words', ''] ->>> re.split('(\W+)', 'Words, words, words.') -['Words', ', ', 'words', ', ', 'words', '.', ''] ->>> re.split('\W+', 'Words, words, words.', 1) -['Words', 'words, words.'] -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{findall}{pattern, string\optional{, flags}} - Return a list of all non-overlapping matches of \var{pattern} in - \var{string}. If one or more groups are present in the pattern, - return a list of groups; this will be a list of tuples if the - pattern has more than one group. Empty matches are included in the - result unless they touch the beginning of another match. - \versionadded{1.5.2} - \versionchanged[Added the optional flags argument]{2.4} -\end{funcdesc} - -\begin{funcdesc}{finditer}{pattern, string\optional{, flags}} - Return an iterator over all non-overlapping matches for the RE - \var{pattern} in \var{string}. For each match, the iterator returns - a match object. Empty matches are included in the result unless they - touch the beginning of another match. - \versionadded{2.2} - \versionchanged[Added the optional flags argument]{2.4} -\end{funcdesc} - -\begin{funcdesc}{sub}{pattern, repl, string\optional{, count}} - Return the string obtained by replacing the leftmost non-overlapping - occurrences of \var{pattern} in \var{string} by the replacement - \var{repl}. If the pattern isn't found, \var{string} is returned - unchanged. \var{repl} can be a string or a function; if it is a - string, any backslash escapes in it are processed. That is, - \samp{\e n} is converted to a single newline character, \samp{\e r} - is converted to a linefeed, and so forth. Unknown escapes such as - \samp{\e j} are left alone. Backreferences, such as \samp{\e6}, are - replaced with the substring matched by group 6 in the pattern. For - example: - -\begin{verbatim} ->>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):', -... r'static PyObject*\npy_\1(void)\n{', -... 'def myfunc():') -'static PyObject*\npy_myfunc(void)\n{' -\end{verbatim} - - If \var{repl} is a function, it is called for every non-overlapping - occurrence of \var{pattern}. The function takes a single match - object argument, and returns the replacement string. For example: - -\begin{verbatim} ->>> def dashrepl(matchobj): -... if matchobj.group(0) == '-': return ' ' -... else: return '-' ->>> re.sub('-{1,2}', dashrepl, 'pro----gram-files') -'pro--gram files' -\end{verbatim} - - The pattern may be a string or an RE object; if you need to specify - regular expression flags, you must use a RE object, or use embedded - modifiers in a pattern; for example, \samp{sub("(?i)b+", "x", "bbbb - BBBB")} returns \code{'x x'}. - - The optional argument \var{count} is the maximum number of pattern - occurrences to be replaced; \var{count} must be a non-negative - integer. If omitted or zero, all occurrences will be replaced. - Empty matches for the pattern are replaced only when not adjacent to - a previous match, so \samp{sub('x*', '-', 'abc')} returns - \code{'-a-b-c-'}. - - In addition to character escapes and backreferences as described - above, \samp{\e g<name>} will use the substring matched by the group - named \samp{name}, as defined by the \regexp{(?P<name>...)} syntax. - \samp{\e g<number>} uses the corresponding group number; - \samp{\e g<2>} is therefore equivalent to \samp{\e 2}, but isn't - ambiguous in a replacement such as \samp{\e g<2>0}. \samp{\e 20} - would be interpreted as a reference to group 20, not a reference to - group 2 followed by the literal character \character{0}. The - backreference \samp{\e g<0>} substitutes in the entire substring - matched by the RE. -\end{funcdesc} - -\begin{funcdesc}{subn}{pattern, repl, string\optional{, count}} - Perform the same operation as \function{sub()}, but return a tuple - \code{(\var{new_string}, \var{number_of_subs_made})}. -\end{funcdesc} - -\begin{funcdesc}{escape}{string} - Return \var{string} with all non-alphanumerics backslashed; this is - useful if you want to match an arbitrary literal string that may have - regular expression metacharacters in it. -\end{funcdesc} - -\begin{excdesc}{error} - Exception raised when a string passed to one of the functions here - is not a valid regular expression (for example, it might contain - unmatched parentheses) or when some other error occurs during - compilation or matching. It is never an error if a string contains - no match for a pattern. -\end{excdesc} - - -\subsection{Regular Expression Objects \label{re-objects}} - -Compiled regular expression objects support the following methods and -attributes: - -\begin{methoddesc}[RegexObject]{match}{string\optional{, pos\optional{, - endpos}}} - If zero or more characters at the beginning of \var{string} match - this regular expression, return a corresponding - \class{MatchObject} instance. Return \code{None} if the string does not - match the pattern; note that this is different from a zero-length - match. - - \note{If you want to locate a match anywhere in - \var{string}, use \method{search()} instead.} - - The optional second parameter \var{pos} gives an index in the string - where the search is to start; it defaults to \code{0}. This is not - completely equivalent to slicing the string; the - \code{'\textasciicircum'} pattern - character matches at the real beginning of the string and at positions - just after a newline, but not necessarily at the index where the search - is to start. - - The optional parameter \var{endpos} limits how far the string will - be searched; it will be as if the string is \var{endpos} characters - long, so only the characters from \var{pos} to \code{\var{endpos} - - 1} will be searched for a match. If \var{endpos} is less than - \var{pos}, no match will be found, otherwise, if \var{rx} is a - compiled regular expression object, - \code{\var{rx}.match(\var{string}, 0, 50)} is equivalent to - \code{\var{rx}.match(\var{string}[:50], 0)}. -\end{methoddesc} - -\begin{methoddesc}[RegexObject]{search}{string\optional{, pos\optional{, - endpos}}} - Scan through \var{string} looking for a location where this regular - expression produces a match, and return a - corresponding \class{MatchObject} instance. Return \code{None} if no - position in the string matches the pattern; note that this is - different from finding a zero-length match at some point in the string. - - The optional \var{pos} and \var{endpos} parameters have the same - meaning as for the \method{match()} method. -\end{methoddesc} - -\begin{methoddesc}[RegexObject]{split}{string\optional{, - maxsplit\code{ = 0}}} -Identical to the \function{split()} function, using the compiled pattern. -\end{methoddesc} - -\begin{methoddesc}[RegexObject]{findall}{string\optional{, pos\optional{, - endpos}}} -Identical to the \function{findall()} function, using the compiled pattern. -\end{methoddesc} - -\begin{methoddesc}[RegexObject]{finditer}{string\optional{, pos\optional{, - endpos}}} -Identical to the \function{finditer()} function, using the compiled pattern. -\end{methoddesc} - -\begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}} -Identical to the \function{sub()} function, using the compiled pattern. -\end{methoddesc} - -\begin{methoddesc}[RegexObject]{subn}{repl, string\optional{, - count\code{ = 0}}} -Identical to the \function{subn()} function, using the compiled pattern. -\end{methoddesc} - - -\begin{memberdesc}[RegexObject]{flags} -The flags argument used when the RE object was compiled, or -\code{0} if no flags were provided. -\end{memberdesc} - -\begin{memberdesc}[RegexObject]{groupindex} -A dictionary mapping any symbolic group names defined by -\regexp{(?P<\var{id}>)} to group numbers. The dictionary is empty if no -symbolic groups were used in the pattern. -\end{memberdesc} - -\begin{memberdesc}[RegexObject]{pattern} -The pattern string from which the RE object was compiled. -\end{memberdesc} - - -\subsection{Match Objects \label{match-objects}} - -\class{MatchObject} instances support the following methods and -attributes: - -\begin{methoddesc}[MatchObject]{expand}{template} - Return the string obtained by doing backslash substitution on the -template string \var{template}, as done by the \method{sub()} method. -Escapes such as \samp{\e n} are converted to the appropriate -characters, and numeric backreferences (\samp{\e 1}, \samp{\e 2}) and -named backreferences (\samp{\e g<1>}, \samp{\e g<name>}) are replaced -by the contents of the corresponding group. -\end{methoddesc} - -\begin{methoddesc}[MatchObject]{group}{\optional{group1, \moreargs}} -Returns one or more subgroups of the match. If there is a single -argument, the result is a single string; if there are -multiple arguments, the result is a tuple with one item per argument. -Without arguments, \var{group1} defaults to zero (the whole match -is returned). -If a \var{groupN} argument is zero, the corresponding return value is the -entire matching string; if it is in the inclusive range [1..99], it is -the string matching the corresponding parenthesized group. If a -group number is negative or larger than the number of groups defined -in the pattern, an \exception{IndexError} exception is raised. -If a group is contained in a part of the pattern that did not match, -the corresponding result is \code{None}. If a group is contained in a -part of the pattern that matched multiple times, the last match is -returned. - -If the regular expression uses the \regexp{(?P<\var{name}>...)} syntax, -the \var{groupN} arguments may also be strings identifying groups by -their group name. If a string argument is not used as a group name in -the pattern, an \exception{IndexError} exception is raised. - -A moderately complicated example: - -\begin{verbatim} -m = re.match(r"(?P<int>\d+)\.(\d*)", '3.14') -\end{verbatim} - -After performing this match, \code{m.group(1)} is \code{'3'}, as is -\code{m.group('int')}, and \code{m.group(2)} is \code{'14'}. -\end{methoddesc} - -\begin{methoddesc}[MatchObject]{groups}{\optional{default}} -Return a tuple containing all the subgroups of the match, from 1 up to -however many groups are in the pattern. The \var{default} argument is -used for groups that did not participate in the match; it defaults to -\code{None}. (Incompatibility note: in the original Python 1.5 -release, if the tuple was one element long, a string would be returned -instead. In later versions (from 1.5.1 on), a singleton tuple is -returned in such cases.) -\end{methoddesc} - -\begin{methoddesc}[MatchObject]{groupdict}{\optional{default}} -Return a dictionary containing all the \emph{named} subgroups of the -match, keyed by the subgroup name. The \var{default} argument is -used for groups that did not participate in the match; it defaults to -\code{None}. -\end{methoddesc} - -\begin{methoddesc}[MatchObject]{start}{\optional{group}} -\methodline[MatchObject]{end}{\optional{group}} -Return the indices of the start and end of the substring -matched by \var{group}; \var{group} defaults to zero (meaning the whole -matched substring). -Return \code{-1} if \var{group} exists but -did not contribute to the match. For a match object -\var{m}, and a group \var{g} that did contribute to the match, the -substring matched by group \var{g} (equivalent to -\code{\var{m}.group(\var{g})}) is - -\begin{verbatim} -m.string[m.start(g):m.end(g)] -\end{verbatim} - -Note that -\code{m.start(\var{group})} will equal \code{m.end(\var{group})} if -\var{group} matched a null string. For example, after \code{\var{m} = -re.search('b(c?)', 'cba')}, \code{\var{m}.start(0)} is 1, -\code{\var{m}.end(0)} is 2, \code{\var{m}.start(1)} and -\code{\var{m}.end(1)} are both 2, and \code{\var{m}.start(2)} raises -an \exception{IndexError} exception. -\end{methoddesc} - -\begin{methoddesc}[MatchObject]{span}{\optional{group}} -For \class{MatchObject} \var{m}, return the 2-tuple -\code{(\var{m}.start(\var{group}), \var{m}.end(\var{group}))}. -Note that if \var{group} did not contribute to the match, this is -\code{(-1, -1)}. Again, \var{group} defaults to zero. -\end{methoddesc} - -\begin{memberdesc}[MatchObject]{pos} -The value of \var{pos} which was passed to the \function{search()} or -\function{match()} method of the \class{RegexObject}. This is the -index into the string at which the RE engine started looking for a -match. -\end{memberdesc} - -\begin{memberdesc}[MatchObject]{endpos} -The value of \var{endpos} which was passed to the \function{search()} -or \function{match()} method of the \class{RegexObject}. This is the -index into the string beyond which the RE engine will not go. -\end{memberdesc} - -\begin{memberdesc}[MatchObject]{lastindex} -The integer index of the last matched capturing group, or \code{None} -if no group was matched at all. For example, the expressions -\regexp{(a)b}, \regexp{((a)(b))}, and \regexp{((ab))} will have -\code{lastindex == 1} if applied to the string \code{'ab'}, -while the expression \regexp{(a)(b)} will have \code{lastindex == 2}, -if applied to the same string. -\end{memberdesc} - -\begin{memberdesc}[MatchObject]{lastgroup} -The name of the last matched capturing group, or \code{None} if the -group didn't have a name, or if no group was matched at all. -\end{memberdesc} - -\begin{memberdesc}[MatchObject]{re} -The regular expression object whose \method{match()} or -\method{search()} method produced this \class{MatchObject} instance. -\end{memberdesc} - -\begin{memberdesc}[MatchObject]{string} -The string passed to \function{match()} or \function{search()}. -\end{memberdesc} - -\subsection{Examples} - -\leftline{\strong{Simulating \cfunction{scanf()}}} - -Python does not currently have an equivalent to \cfunction{scanf()}. -\ttindex{scanf()} -Regular expressions are generally more powerful, though also more -verbose, than \cfunction{scanf()} format strings. The table below -offers some more-or-less equivalent mappings between -\cfunction{scanf()} format tokens and regular expressions. - -\begin{tableii}{l|l}{textrm}{\cfunction{scanf()} Token}{Regular Expression} - \lineii{\code{\%c}} - {\regexp{.}} - \lineii{\code{\%5c}} - {\regexp{.\{5\}}} - \lineii{\code{\%d}} - {\regexp{[-+]?\e d+}} - \lineii{\code{\%e}, \code{\%E}, \code{\%f}, \code{\%g}} - {\regexp{[-+]?(\e d+(\e.\e d*)?|\e.\e d+)([eE][-+]?\e d+)?}} - \lineii{\code{\%i}} - {\regexp{[-+]?(0[xX][\e dA-Fa-f]+|0[0-7]*|\e d+)}} - \lineii{\code{\%o}} - {\regexp{0[0-7]*}} - \lineii{\code{\%s}} - {\regexp{\e S+}} - \lineii{\code{\%u}} - {\regexp{\e d+}} - \lineii{\code{\%x}, \code{\%X}} - {\regexp{0[xX][\e dA-Fa-f]+}} -\end{tableii} - -To extract the filename and numbers from a string like - -\begin{verbatim} - /usr/sbin/sendmail - 0 errors, 4 warnings -\end{verbatim} - -you would use a \cfunction{scanf()} format like - -\begin{verbatim} - %s - %d errors, %d warnings -\end{verbatim} - -The equivalent regular expression would be - -\begin{verbatim} - (\S+) - (\d+) errors, (\d+) warnings -\end{verbatim} - -\leftline{\strong{Avoiding recursion}} - -If you create regular expressions that require the engine to perform a -lot of recursion, you may encounter a \exception{RuntimeError} exception with -the message \code{maximum recursion limit} exceeded. For example, - -\begin{verbatim} ->>> import re ->>> s = 'Begin ' + 1000*'a very long string ' + 'end' ->>> re.match('Begin (\w| )*? end', s).end() -Traceback (most recent call last): - File "<stdin>", line 1, in ? - File "/usr/local/lib/python2.5/re.py", line 132, in match - return _compile(pattern, flags).match(string) -RuntimeError: maximum recursion limit exceeded -\end{verbatim} - -You can often restructure your regular expression to avoid recursion. - -Starting with Python 2.3, simple uses of the \regexp{*?} pattern are -special-cased to avoid recursion. Thus, the above regular expression -can avoid recursion by being recast as -\regexp{Begin [a-zA-Z0-9_ ]*?end}. As a further benefit, such regular -expressions will run faster than their recursive equivalents. diff --git a/Doc/lib/libreadline.tex b/Doc/lib/libreadline.tex deleted file mode 100644 index dec37b6..0000000 --- a/Doc/lib/libreadline.tex +++ /dev/null @@ -1,196 +0,0 @@ -\section{\module{readline} --- - GNU readline interface} - -\declaremodule{builtin}{readline} - \platform{Unix} -\sectionauthor{Skip Montanaro}{skip@mojam.com} -\modulesynopsis{GNU readline support for Python.} - - -The \module{readline} module defines a number of functions to -facilitate completion and reading/writing of history files from the -Python interpreter. This module can be used directly or via the -\refmodule{rlcompleter} module. Settings made using -this module affect the behaviour of both the interpreter's interactive prompt -and the prompts offered by the \function{raw_input()} and \function{input()} -built-in functions. - -The \module{readline} module defines the following functions: - - -\begin{funcdesc}{parse_and_bind}{string} -Parse and execute single line of a readline init file. -\end{funcdesc} - -\begin{funcdesc}{get_line_buffer}{} -Return the current contents of the line buffer. -\end{funcdesc} - -\begin{funcdesc}{insert_text}{string} -Insert text into the command line. -\end{funcdesc} - -\begin{funcdesc}{read_init_file}{\optional{filename}} -Parse a readline initialization file. -The default filename is the last filename used. -\end{funcdesc} - -\begin{funcdesc}{read_history_file}{\optional{filename}} -Load a readline history file. -The default filename is \file{\~{}/.history}. -\end{funcdesc} - -\begin{funcdesc}{write_history_file}{\optional{filename}} -Save a readline history file. -The default filename is \file{\~{}/.history}. -\end{funcdesc} - -\begin{funcdesc}{clear_history}{} -Clear the current history. (Note: this function is not available if -the installed version of GNU readline doesn't support it.) -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{get_history_length}{} -Return the desired length of the history file. Negative values imply -unlimited history file size. -\end{funcdesc} - -\begin{funcdesc}{set_history_length}{length} -Set the number of lines to save in the history file. -\function{write_history_file()} uses this value to truncate the -history file when saving. Negative values imply unlimited history -file size. -\end{funcdesc} - -\begin{funcdesc}{get_current_history_length}{} -Return the number of lines currently in the history. (This is different -from \function{get_history_length()}, which returns the maximum number of -lines that will be written to a history file.) \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{get_history_item}{index} -Return the current contents of history item at \var{index}. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{remove_history_item}{pos} -Remove history item specified by its position from the history. -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{replace_history_item}{pos, line} -Replace history item specified by its position with the given line. -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{redisplay}{} -Change what's displayed on the screen to reflect the current contents -of the line buffer. \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{set_startup_hook}{\optional{function}} -Set or remove the startup_hook function. If \var{function} is specified, -it will be used as the new startup_hook function; if omitted or -\code{None}, any hook function already installed is removed. The -startup_hook function is called with no arguments just -before readline prints the first prompt. -\end{funcdesc} - -\begin{funcdesc}{set_pre_input_hook}{\optional{function}} -Set or remove the pre_input_hook function. If \var{function} is specified, -it will be used as the new pre_input_hook function; if omitted or -\code{None}, any hook function already installed is removed. The -pre_input_hook function is called with no arguments after the first prompt -has been printed and just before readline starts reading input characters. -\end{funcdesc} - -\begin{funcdesc}{set_completer}{\optional{function}} -Set or remove the completer function. If \var{function} is specified, -it will be used as the new completer function; if omitted or -\code{None}, any completer function already installed is removed. The -completer function is called as \code{\var{function}(\var{text}, -\var{state})}, for \var{state} in \code{0}, \code{1}, \code{2}, ..., -until it returns a non-string value. It should return the next -possible completion starting with \var{text}. -\end{funcdesc} - -\begin{funcdesc}{get_completer}{} -Get the completer function, or \code{None} if no completer function -has been set. \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{get_begidx}{} -Get the beginning index of the readline tab-completion scope. -\end{funcdesc} - -\begin{funcdesc}{get_endidx}{} -Get the ending index of the readline tab-completion scope. -\end{funcdesc} - -\begin{funcdesc}{set_completer_delims}{string} -Set the readline word delimiters for tab-completion. -\end{funcdesc} - -\begin{funcdesc}{get_completer_delims}{} -Get the readline word delimiters for tab-completion. -\end{funcdesc} - -\begin{funcdesc}{add_history}{line} -Append a line to the history buffer, as if it was the last line typed. -\end{funcdesc} - -\begin{seealso} - \seemodule{rlcompleter}{Completion of Python identifiers at the - interactive prompt.} -\end{seealso} - - -\subsection{Example \label{readline-example}} - -The following example demonstrates how to use the -\module{readline} module's history reading and writing functions to -automatically load and save a history file named \file{.pyhist} from -the user's home directory. The code below would normally be executed -automatically during interactive sessions from the user's -\envvar{PYTHONSTARTUP} file. - -\begin{verbatim} -import os -histfile = os.path.join(os.environ["HOME"], ".pyhist") -try: - readline.read_history_file(histfile) -except IOError: - pass -import atexit -atexit.register(readline.write_history_file, histfile) -del os, histfile -\end{verbatim} - -The following example extends the \class{code.InteractiveConsole} class to -support history save/restore. - -\begin{verbatim} -import code -import readline -import atexit -import os - -class HistoryConsole(code.InteractiveConsole): - def __init__(self, locals=None, filename="<console>", - histfile=os.path.expanduser("~/.console-history")): - code.InteractiveConsole.__init__(self) - self.init_history(histfile) - - def init_history(self, histfile): - readline.parse_and_bind("tab: complete") - if hasattr(readline, "read_history_file"): - try: - readline.read_history_file(histfile) - except IOError: - pass - atexit.register(self.save_history, histfile) - - def save_history(self, histfile): - readline.write_history_file(histfile) -\end{verbatim} diff --git a/Doc/lib/librepr.tex b/Doc/lib/librepr.tex deleted file mode 100644 index 2876448..0000000 --- a/Doc/lib/librepr.tex +++ /dev/null @@ -1,133 +0,0 @@ -\section{\module{repr} --- - Alternate \function{repr()} implementation} - -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\declaremodule{standard}{repr} -\modulesynopsis{Alternate \function{repr()} implementation with size limits.} - - -The \module{repr} module provides a means for producing object -representations with limits on the size of the resulting strings. -This is used in the Python debugger and may be useful in other -contexts as well. - -This module provides a class, an instance, and a function: - - -\begin{classdesc}{Repr}{} - Class which provides formatting services useful in implementing - functions similar to the built-in \function{repr()}; size limits for - different object types are added to avoid the generation of - representations which are excessively long. -\end{classdesc} - - -\begin{datadesc}{aRepr} - This is an instance of \class{Repr} which is used to provide the - \function{repr()} function described below. Changing the attributes - of this object will affect the size limits used by \function{repr()} - and the Python debugger. -\end{datadesc} - - -\begin{funcdesc}{repr}{obj} - This is the \method{repr()} method of \code{aRepr}. It returns a - string similar to that returned by the built-in function of the same - name, but with limits on most sizes. -\end{funcdesc} - - -\subsection{Repr Objects \label{Repr-objects}} - -\class{Repr} instances provide several members which can be used to -provide size limits for the representations of different object types, -and methods which format specific object types. - - -\begin{memberdesc}[Repr]{maxlevel} - Depth limit on the creation of recursive representations. The - default is \code{6}. -\end{memberdesc} - -\begin{memberdesc}[Repr]{maxdict} -\memberline[Repr]{maxlist} -\memberline[Repr]{maxtuple} -\memberline[Repr]{maxset} -\memberline[Repr]{maxfrozenset} -\memberline[Repr]{maxdeque} -\memberline[Repr]{maxarray} - Limits on the number of entries represented for the named object - type. The default is \code{4} for \member{maxdict}, \code{5} for - \member{maxarray}, and \code{6} for the others. - \versionadded[\member{maxset}, \member{maxfrozenset}, - and \member{set}]{2.4}. -\end{memberdesc} - -\begin{memberdesc}[Repr]{maxlong} - Maximum number of characters in the representation for a long - integer. Digits are dropped from the middle. The default is - \code{40}. -\end{memberdesc} - -\begin{memberdesc}[Repr]{maxstring} - Limit on the number of characters in the representation of the - string. Note that the ``normal'' representation of the string is - used as the character source: if escape sequences are needed in the - representation, these may be mangled when the representation is - shortened. The default is \code{30}. -\end{memberdesc} - -\begin{memberdesc}[Repr]{maxother} - This limit is used to control the size of object types for which no - specific formatting method is available on the \class{Repr} object. - It is applied in a similar manner as \member{maxstring}. The - default is \code{20}. -\end{memberdesc} - -\begin{methoddesc}[Repr]{repr}{obj} - The equivalent to the built-in \function{repr()} that uses the - formatting imposed by the instance. -\end{methoddesc} - -\begin{methoddesc}[Repr]{repr1}{obj, level} - Recursive implementation used by \method{repr()}. This uses the - type of \var{obj} to determine which formatting method to call, - passing it \var{obj} and \var{level}. The type-specific methods - should call \method{repr1()} to perform recursive formatting, with - \code{\var{level} - 1} for the value of \var{level} in the recursive - call. -\end{methoddesc} - -\begin{methoddescni}[Repr]{repr_\var{type}}{obj, level} - Formatting methods for specific types are implemented as methods - with a name based on the type name. In the method name, \var{type} - is replaced by - \code{string.join(string.split(type(\var{obj}).__name__, '_'))}. - Dispatch to these methods is handled by \method{repr1()}. - Type-specific methods which need to recursively format a value - should call \samp{self.repr1(\var{subobj}, \var{level} - 1)}. -\end{methoddescni} - - -\subsection{Subclassing Repr Objects \label{subclassing-reprs}} - -The use of dynamic dispatching by \method{Repr.repr1()} allows -subclasses of \class{Repr} to add support for additional built-in -object types or to modify the handling of types already supported. -This example shows how special support for file objects could be -added: - -\begin{verbatim} -import repr -import sys - -class MyRepr(repr.Repr): - def repr_file(self, obj, level): - if obj.name in ['<stdin>', '<stdout>', '<stderr>']: - return obj.name - else: - return `obj` - -aRepr = MyRepr() -print aRepr.repr(sys.stdin) # prints '<stdin>' -\end{verbatim} diff --git a/Doc/lib/libresource.tex b/Doc/lib/libresource.tex deleted file mode 100644 index 8e102b8..0000000 --- a/Doc/lib/libresource.tex +++ /dev/null @@ -1,215 +0,0 @@ -\section{\module{resource} --- - Resource usage information} - -\declaremodule{builtin}{resource} - \platform{Unix} -\modulesynopsis{An interface to provide resource usage information on - the current process.} -\moduleauthor{Jeremy Hylton}{jeremy@alum.mit.edu} -\sectionauthor{Jeremy Hylton}{jeremy@alum.mit.edu} - - -This module provides basic mechanisms for measuring and controlling -system resources utilized by a program. - -Symbolic constants are used to specify particular system resources and -to request usage information about either the current process or its -children. - -A single exception is defined for errors: - - -\begin{excdesc}{error} - The functions described below may raise this error if the underlying - system call failures unexpectedly. -\end{excdesc} - -\subsection{Resource Limits} - -Resources usage can be limited using the \function{setrlimit()} function -described below. Each resource is controlled by a pair of limits: a -soft limit and a hard limit. The soft limit is the current limit, and -may be lowered or raised by a process over time. The soft limit can -never exceed the hard limit. The hard limit can be lowered to any -value greater than the soft limit, but not raised. (Only processes with -the effective UID of the super-user can raise a hard limit.) - -The specific resources that can be limited are system dependent. They -are described in the \manpage{getrlimit}{2} man page. The resources -listed below are supported when the underlying operating system -supports them; resources which cannot be checked or controlled by the -operating system are not defined in this module for those platforms. - -\begin{funcdesc}{getrlimit}{resource} - Returns a tuple \code{(\var{soft}, \var{hard})} with the current - soft and hard limits of \var{resource}. Raises \exception{ValueError} if - an invalid resource is specified, or \exception{error} if the - underlying system call fails unexpectedly. -\end{funcdesc} - -\begin{funcdesc}{setrlimit}{resource, limits} - Sets new limits of consumption of \var{resource}. The \var{limits} - argument must be a tuple \code{(\var{soft}, \var{hard})} of two - integers describing the new limits. A value of \code{-1} can be used to - specify the maximum possible upper limit. - - Raises \exception{ValueError} if an invalid resource is specified, - if the new soft limit exceeds the hard limit, or if a process tries - to raise its hard limit (unless the process has an effective UID of - super-user). Can also raise \exception{error} if the underlying - system call fails. -\end{funcdesc} - -These symbols define resources whose consumption can be controlled -using the \function{setrlimit()} and \function{getrlimit()} functions -described below. The values of these symbols are exactly the constants -used by \C{} programs. - -The \UNIX{} man page for \manpage{getrlimit}{2} lists the available -resources. Note that not all systems use the same symbol or same -value to denote the same resource. This module does not attempt to -mask platform differences --- symbols not defined for a platform will -not be available from this module on that platform. - -\begin{datadesc}{RLIMIT_CORE} - The maximum size (in bytes) of a core file that the current process - can create. This may result in the creation of a partial core file - if a larger core would be required to contain the entire process - image. -\end{datadesc} - -\begin{datadesc}{RLIMIT_CPU} - The maximum amount of processor time (in seconds) that a process can - use. If this limit is exceeded, a \constant{SIGXCPU} signal is sent to - the process. (See the \refmodule{signal} module documentation for - information about how to catch this signal and do something useful, - e.g. flush open files to disk.) -\end{datadesc} - -\begin{datadesc}{RLIMIT_FSIZE} - The maximum size of a file which the process may create. This only - affects the stack of the main thread in a multi-threaded process. -\end{datadesc} - -\begin{datadesc}{RLIMIT_DATA} - The maximum size (in bytes) of the process's heap. -\end{datadesc} - -\begin{datadesc}{RLIMIT_STACK} - The maximum size (in bytes) of the call stack for the current - process. -\end{datadesc} - -\begin{datadesc}{RLIMIT_RSS} - The maximum resident set size that should be made available to the - process. -\end{datadesc} - -\begin{datadesc}{RLIMIT_NPROC} - The maximum number of processes the current process may create. -\end{datadesc} - -\begin{datadesc}{RLIMIT_NOFILE} - The maximum number of open file descriptors for the current - process. -\end{datadesc} - -\begin{datadesc}{RLIMIT_OFILE} - The BSD name for \constant{RLIMIT_NOFILE}. -\end{datadesc} - -\begin{datadesc}{RLIMIT_MEMLOCK} - The maximum address space which may be locked in memory. -\end{datadesc} - -\begin{datadesc}{RLIMIT_VMEM} - The largest area of mapped memory which the process may occupy. -\end{datadesc} - -\begin{datadesc}{RLIMIT_AS} - The maximum area (in bytes) of address space which may be taken by - the process. -\end{datadesc} - -\subsection{Resource Usage} - -These functions are used to retrieve resource usage information: - -\begin{funcdesc}{getrusage}{who} - This function returns an object that describes the resources - consumed by either the current process or its children, as specified - by the \var{who} parameter. The \var{who} parameter should be - specified using one of the \constant{RUSAGE_*} constants described - below. - - The fields of the return value each describe how a particular system - resource has been used, e.g. amount of time spent running is user mode - or number of times the process was swapped out of main memory. Some - values are dependent on the clock tick internal, e.g. the amount of - memory the process is using. - - For backward compatibility, the return value is also accessible as - a tuple of 16 elements. - - The fields \member{ru_utime} and \member{ru_stime} of the return value - are floating point values representing the amount of time spent - executing in user mode and the amount of time spent executing in system - mode, respectively. The remaining values are integers. Consult the - \manpage{getrusage}{2} man page for detailed information about these - values. A brief summary is presented here: - -\begin{tableiii}{r|l|l}{code}{Index}{Field}{Resource} - \lineiii{0}{\member{ru_utime}}{time in user mode (float)} - \lineiii{1}{\member{ru_stime}}{time in system mode (float)} - \lineiii{2}{\member{ru_maxrss}}{maximum resident set size} - \lineiii{3}{\member{ru_ixrss}}{shared memory size} - \lineiii{4}{\member{ru_idrss}}{unshared memory size} - \lineiii{5}{\member{ru_isrss}}{unshared stack size} - \lineiii{6}{\member{ru_minflt}}{page faults not requiring I/O} - \lineiii{7}{\member{ru_majflt}}{page faults requiring I/O} - \lineiii{8}{\member{ru_nswap}}{number of swap outs} - \lineiii{9}{\member{ru_inblock}}{block input operations} - \lineiii{10}{\member{ru_oublock}}{block output operations} - \lineiii{11}{\member{ru_msgsnd}}{messages sent} - \lineiii{12}{\member{ru_msgrcv}}{messages received} - \lineiii{13}{\member{ru_nsignals}}{signals received} - \lineiii{14}{\member{ru_nvcsw}}{voluntary context switches} - \lineiii{15}{\member{ru_nivcsw}}{involuntary context switches} -\end{tableiii} - - This function will raise a \exception{ValueError} if an invalid - \var{who} parameter is specified. It may also raise - \exception{error} exception in unusual circumstances. - - \versionchanged[Added access to values as attributes of the - returned object]{2.3} -\end{funcdesc} - -\begin{funcdesc}{getpagesize}{} - Returns the number of bytes in a system page. (This need not be the - same as the hardware page size.) This function is useful for - determining the number of bytes of memory a process is using. The - third element of the tuple returned by \function{getrusage()} describes - memory usage in pages; multiplying by page size produces number of - bytes. -\end{funcdesc} - -The following \constant{RUSAGE_*} symbols are passed to the -\function{getrusage()} function to specify which processes information -should be provided for. - -\begin{datadesc}{RUSAGE_SELF} - \constant{RUSAGE_SELF} should be used to - request information pertaining only to the process itself. -\end{datadesc} - -\begin{datadesc}{RUSAGE_CHILDREN} - Pass to \function{getrusage()} to request resource information for - child processes of the calling process. -\end{datadesc} - -\begin{datadesc}{RUSAGE_BOTH} - Pass to \function{getrusage()} to request resources consumed by both - the current process and child processes. May not be available on all - systems. -\end{datadesc} diff --git a/Doc/lib/librfc822.tex b/Doc/lib/librfc822.tex deleted file mode 100644 index b59e6ad..0000000 --- a/Doc/lib/librfc822.tex +++ /dev/null @@ -1,336 +0,0 @@ -\section{\module{rfc822} --- - Parse RFC 2822 mail headers} - -\declaremodule{standard}{rfc822} -\modulesynopsis{Parse \rfc{2822} style mail messages.} - -\deprecated{2.3}{The \refmodule{email} package should be used in - preference to the \module{rfc822} module. This - module is present only to maintain backward - compatibility.} - -This module defines a class, \class{Message}, which represents an -``email message'' as defined by the Internet standard -\rfc{2822}.\footnote{This module originally conformed to \rfc{822}, -hence the name. Since then, \rfc{2822} has been released as an -update to \rfc{822}. This module should be considered -\rfc{2822}-conformant, especially in cases where the -syntax or semantics have changed since \rfc{822}.} Such messages -consist of a collection of message headers, and a message body. This -module also defines a helper class -\class{AddressList} for parsing \rfc{2822} addresses. Please refer to -the RFC for information on the specific syntax of \rfc{2822} messages. - -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 -parameter. Message relies only on the input object having a -\method{readline()} method; in particular, ordinary file objects -qualify. Instantiation reads headers from the input object up to a -delimiter line (normally a blank line) and stores them in the -instance. The message body, following the headers, is not consumed. - -This class can work with any input object that supports a -\method{readline()} method. If the input object has seek and tell -capability, the \method{rewindbody()} method will work; also, illegal -lines will be pushed back onto the input stream. If the input object -lacks seek but has an \method{unread()} method that can push back a -line of input, \class{Message} will use that to push back illegal -lines. Thus this class can be used to parse messages coming from a -buffered stream. - -The optional \var{seekable} argument is provided as a workaround for -certain stdio libraries in which \cfunction{tell()} discards buffered -data before discovering that the \cfunction{lseek()} system call -doesn't work. For maximum portability, you should set the seekable -argument to zero to prevent that initial \method{tell()} when passing -in an unseekable object such as a file object created from a socket -object. - -Input lines as read from the file may either be terminated by CR-LF or -by a single linefeed; a terminating CR-LF is replaced by a single -linefeed before the line is stored. - -All header matching is done independent of upper or lower case; -e.g.\ \code{\var{m}['From']}, \code{\var{m}['from']} and -\code{\var{m}['FROM']} all yield the same result. -\end{classdesc} - -\begin{classdesc}{AddressList}{field} -You may instantiate the \class{AddressList} helper class using a single -string parameter, a comma-separated list of \rfc{2822} addresses to be -parsed. (The parameter \code{None} yields an empty list.) -\end{classdesc} - -\begin{funcdesc}{quote}{str} -Return a new string with backslashes in \var{str} replaced by two -backslashes and double quotes replaced by backslash-double quote. -\end{funcdesc} - -\begin{funcdesc}{unquote}{str} -Return a new string which is an \emph{unquoted} version of \var{str}. -If \var{str} ends and begins with double quotes, they are stripped -off. Likewise if \var{str} ends and begins with angle brackets, they -are stripped off. -\end{funcdesc} - -\begin{funcdesc}{parseaddr}{address} -Parse \var{address}, which should be the value of some -address-containing field such as \mailheader{To} or \mailheader{Cc}, -into its constituent ``realname'' and ``email address'' parts. -Returns a tuple of that information, unless the parse fails, in which -case a 2-tuple \code{(None, None)} is returned. -\end{funcdesc} - -\begin{funcdesc}{dump_address_pair}{pair} -The inverse of \method{parseaddr()}, this takes a 2-tuple of the form -\code{(\var{realname}, \var{email_address})} and returns the string -value suitable for a \mailheader{To} or \mailheader{Cc} header. If -the first element of \var{pair} is false, then the second element is -returned unmodified. -\end{funcdesc} - -\begin{funcdesc}{parsedate}{date} -Attempts to parse a date according to the rules in \rfc{2822}. -however, some mailers don't follow that format as specified, so -\function{parsedate()} tries to guess correctly in such cases. -\var{date} is a string containing an \rfc{2822} date, such as -\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. Note that indexes 6, 7, and 8 of the result tuple are not -usable. -\end{funcdesc} - -\begin{funcdesc}{parsedate_tz}{date} -Performs the same function as \function{parsedate()}, but returns -either \code{None} or a 10-tuple; the first 9 elements make up a tuple -that can be passed directly to \function{time.mktime()}, and the tenth -is the offset of the date's timezone from UTC (which is the official -term for Greenwich Mean Time). (Note that the sign of the timezone -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{2822}.) If the input -string has no timezone, the last element of the tuple returned is -\code{None}. Note that indexes 6, 7, and 8 of the result tuple are not -usable. -\end{funcdesc} - -\begin{funcdesc}{mktime_tz}{tuple} -Turn a 10-tuple as returned by \function{parsedate_tz()} into a UTC -timestamp. If the timezone item in the tuple is \code{None}, assume -local time. Minor deficiency: this first interprets the first 8 -elements as a local time and then compensates for the timezone -difference; this may yield a slight error around daylight savings time -switch dates. Not enough to worry about for common use. -\end{funcdesc} - - -\begin{seealso} - \seemodule{email}{Comprehensive email handling package; supersedes - the \module{rfc822} module.} - \seemodule{mailbox}{Classes to read various mailbox formats produced - by end-user mail programs.} - \seemodule{mimetools}{Subclass of \class{rfc822.Message} that - handles MIME encoded messages.} -\end{seealso} - - -\subsection{Message Objects \label{message-objects}} - -A \class{Message} instance has the following methods: - -\begin{methoddesc}[Message]{rewindbody}{} -Seek to the start of the message body. This only works if the file -object is seekable. -\end{methoddesc} - -\begin{methoddesc}[Message]{isheader}{line} -Returns a line's canonicalized fieldname (the dictionary key that will -be used to index it) if the line is a legal \rfc{2822} header; otherwise -returns \code{None} (implying that parsing should stop here and the -line be pushed back on the input stream). It is sometimes useful to -override this method in a subclass. -\end{methoddesc} - -\begin{methoddesc}[Message]{islast}{line} -Return true if the given line is a delimiter on which Message should -stop. The delimiter line is consumed, and the file object's read -location positioned immediately after it. By default this method just -checks that the line is blank, but you can override it in a subclass. -\end{methoddesc} - -\begin{methoddesc}[Message]{iscomment}{line} -Return \code{True} if the given line should be ignored entirely, just skipped. -By default this is a stub that always returns \code{False}, but you can -override it in a subclass. -\end{methoddesc} - -\begin{methoddesc}[Message]{getallmatchingheaders}{name} -Return a list of lines consisting of all headers matching -\var{name}, if any. Each physical line, whether it is a continuation -line or not, is a separate list item. Return the empty list if no -header matches \var{name}. -\end{methoddesc} - -\begin{methoddesc}[Message]{getfirstmatchingheader}{name} -Return a list of lines comprising the first header matching -\var{name}, and its continuation line(s), if any. Return -\code{None} if there is no header matching \var{name}. -\end{methoddesc} - -\begin{methoddesc}[Message]{getrawheader}{name} -Return a single string consisting of the text after the colon in the -first header matching \var{name}. This includes leading whitespace, -the trailing linefeed, and internal linefeeds and whitespace if there -any continuation line(s) were present. Return \code{None} if there is -no header matching \var{name}. -\end{methoddesc} - -\begin{methoddesc}[Message]{getheader}{name\optional{, default}} -Like \code{getrawheader(\var{name})}, but strip leading and trailing -whitespace. Internal whitespace is not stripped. The optional -\var{default} argument can be used to specify a different default to -be returned when there is no header matching \var{name}. -\end{methoddesc} - -\begin{methoddesc}[Message]{get}{name\optional{, default}} -An alias for \method{getheader()}, to make the interface more compatible -with regular dictionaries. -\end{methoddesc} - -\begin{methoddesc}[Message]{getaddr}{name} -Return a pair \code{(\var{full name}, \var{email address})} parsed -from the string returned by \code{getheader(\var{name})}. If no -header matching \var{name} exists, return \code{(None, None)}; -otherwise both the full name and the address are (possibly empty) -strings. - -Example: If \var{m}'s first \mailheader{From} header contains the -string \code{'jack@cwi.nl (Jack Jansen)'}, then -\code{m.getaddr('From')} will yield the pair -\code{('Jack Jansen', 'jack@cwi.nl')}. -If the header contained -\code{'Jack Jansen <jack@cwi.nl>'} instead, it would yield the -exact same result. -\end{methoddesc} - -\begin{methoddesc}[Message]{getaddrlist}{name} -This is similar to \code{getaddr(\var{list})}, but parses a header -containing a list of email addresses (e.g.\ a \mailheader{To} header) and -returns a list of \code{(\var{full name}, \var{email address})} pairs -(even if there was only one address in the header). If there is no -header matching \var{name}, return an empty list. - -If multiple headers exist that match the named header (e.g. if there -are several \mailheader{Cc} headers), all are parsed for addresses. -Any continuation lines the named headers contain are also parsed. -\end{methoddesc} - -\begin{methoddesc}[Message]{getdate}{name} -Retrieve a header using \method{getheader()} and parse it into a 9-tuple -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 -the standard. While it has been tested and found correct on a large -collection of email from many sources, it is still possible that this -function may occasionally yield an incorrect result. -\end{methoddesc} - -\begin{methoddesc}[Message]{getdate_tz}{name} -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. 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} - -\class{Message} instances also support a limited mapping interface. -In particular: \code{\var{m}[name]} is like -\code{\var{m}.getheader(name)} but raises \exception{KeyError} if -there is no matching header; and \code{len(\var{m})}, -\code{\var{m}.get(\var{name}\optional{, \var{default}})}, -\code{\var{m}.has_key(\var{name})}, \code{\var{m}.keys()}, -\code{\var{m}.values()} \code{\var{m}.items()}, and -\code{\var{m}.setdefault(\var{name}\optional{, \var{default}})} act as -expected, with the one difference that \method{setdefault()} uses -an empty string as the default value. \class{Message} instances -also support the mapping writable interface \code{\var{m}[name] = -value} and \code{del \var{m}[name]}. \class{Message} objects do not -support the \method{clear()}, \method{copy()}, \method{popitem()}, or -\method{update()} methods of the mapping interface. (Support for -\method{get()} and \method{setdefault()} was only added in Python -2.2.) - -Finally, \class{Message} instances have some public instance variables: - -\begin{memberdesc}[Message]{headers} -A list containing the entire set of header lines, in the order in -which they were read (except that setitem calls may disturb this -order). Each line contains a trailing newline. The -blank line terminating the headers is not contained in the list. -\end{memberdesc} - -\begin{memberdesc}[Message]{fp} -The file or file-like object passed at instantiation time. This can -be used to read the message content. -\end{memberdesc} - -\begin{memberdesc}[Message]{unixfrom} -The \UNIX{} \samp{From~} line, if the message had one, or an empty -string. This is needed to regenerate the message in some contexts, -such as an \code{mbox}-style mailbox file. -\end{memberdesc} - - -\subsection{AddressList Objects \label{addresslist-objects}} - -An \class{AddressList} instance has the following methods: - -\begin{methoddesc}[AddressList]{__len__}{} -Return the number of addresses in the address list. -\end{methoddesc} - -\begin{methoddesc}[AddressList]{__str__}{} -Return a canonicalized string representation of the address list. -Addresses are rendered in "name" <host@domain> form, comma-separated. -\end{methoddesc} - -\begin{methoddesc}[AddressList]{__add__}{alist} -Return a new \class{AddressList} instance that contains all addresses -in both \class{AddressList} operands, with duplicates removed (set -union). -\end{methoddesc} - -\begin{methoddesc}[AddressList]{__iadd__}{alist} -In-place version of \method{__add__()}; turns this \class{AddressList} -instance into the union of itself and the right-hand instance, -\var{alist}. -\end{methoddesc} - -\begin{methoddesc}[AddressList]{__sub__}{alist} -Return a new \class{AddressList} instance that contains every address -in the left-hand \class{AddressList} operand that is not present in -the right-hand address operand (set difference). -\end{methoddesc} - -\begin{methoddesc}[AddressList]{__isub__}{alist} -In-place version of \method{__sub__()}, removing addresses in this -list which are also in \var{alist}. -\end{methoddesc} - - -Finally, \class{AddressList} instances have one public instance variable: - -\begin{memberdesc}[AddressList]{addresslist} -A list of tuple string pairs, one per address. In each member, the -first is the canonicalized name part, the second is the -actual route-address (\character{@}-separated username-host.domain -pair). -\end{memberdesc} diff --git a/Doc/lib/librlcompleter.tex b/Doc/lib/librlcompleter.tex deleted file mode 100644 index cb2ac59..0000000 --- a/Doc/lib/librlcompleter.tex +++ /dev/null @@ -1,65 +0,0 @@ -\section{\module{rlcompleter} --- - Completion function for GNU readline} - -\declaremodule{standard}{rlcompleter} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Python identifier completion, suitable for the GNU readline library.} - -The \module{rlcompleter} module defines a completion function suitable for -the \refmodule{readline} module by completing valid Python identifiers -and keywords. - -When this module is imported on a \UNIX\ platform with the \module{readline} -module available, an instance of the \class{Completer} class is automatically -created and its \method{complete} method is set as the \module{readline} -completer. - -Example: - -\begin{verbatim} ->>> import rlcompleter ->>> import readline ->>> readline.parse_and_bind("tab: complete") ->>> readline. <TAB PRESSED> -readline.__doc__ readline.get_line_buffer readline.read_init_file -readline.__file__ readline.insert_text readline.set_completer -readline.__name__ readline.parse_and_bind ->>> readline. -\end{verbatim} - -The \module{rlcompleter} module is designed for use with Python's -interactive mode. A user can add the following lines to his or her -initialization file (identified by the \envvar{PYTHONSTARTUP} -environment variable) to get automatic \kbd{Tab} completion: - -\begin{verbatim} -try: - import readline -except ImportError: - print "Module readline not available." -else: - import rlcompleter - readline.parse_and_bind("tab: complete") -\end{verbatim} - - -On platforms without \module{readline}, the \class{Completer} class defined -by this module can still be used for custom purposes. - -\subsection{Completer Objects \label{completer-objects}} - -Completer objects have the following method: - -\begin{methoddesc}[Completer]{complete}{text, state} -Return the \var{state}th completion for \var{text}. - -If called for \var{text} that doesn't include a period character -(\character{.}), it will complete from names currently defined in -\refmodule[main]{__main__}, \refmodule[builtin]{__builtin__} and -keywords (as defined by the \refmodule{keyword} module). - -If called for a dotted name, it will try to evaluate anything without -obvious side-effects (functions will not be evaluated, but it -can generate calls to \method{__getattr__()}) up to the last part, and -find matches for the rest via the \function{dir()} function. -\end{methoddesc} diff --git a/Doc/lib/librobotparser.tex b/Doc/lib/librobotparser.tex deleted file mode 100644 index 5eac528..0000000 --- a/Doc/lib/librobotparser.tex +++ /dev/null @@ -1,66 +0,0 @@ -\section{\module{robotparser} --- - Parser for robots.txt} - -\declaremodule{standard}{robotparser} -\modulesynopsis{Loads a \protect\file{robots.txt} file and - answers questions about fetchability of other URLs.} -\sectionauthor{Skip Montanaro}{skip@mojam.com} - -\index{WWW} -\index{World Wide Web} -\index{URL} -\index{robots.txt} - -This module provides a single class, \class{RobotFileParser}, which answers -questions about whether or not a particular user agent can fetch a URL on -the Web site that published the \file{robots.txt} file. For more details on -the structure of \file{robots.txt} files, see -\url{http://www.robotstxt.org/wc/norobots.html}. - -\begin{classdesc}{RobotFileParser}{} - -This class provides a set of methods to read, parse and answer questions -about a single \file{robots.txt} file. - -\begin{methoddesc}{set_url}{url} -Sets the URL referring to a \file{robots.txt} file. -\end{methoddesc} - -\begin{methoddesc}{read}{} -Reads the \file{robots.txt} URL and feeds it to the parser. -\end{methoddesc} - -\begin{methoddesc}{parse}{lines} -Parses the lines argument. -\end{methoddesc} - -\begin{methoddesc}{can_fetch}{useragent, url} -Returns \code{True} if the \var{useragent} is allowed to fetch the \var{url} -according to the rules contained in the parsed \file{robots.txt} file. -\end{methoddesc} - -\begin{methoddesc}{mtime}{} -Returns the time the \code{robots.txt} file was last fetched. This is -useful for long-running web spiders that need to check for new -\code{robots.txt} files periodically. -\end{methoddesc} - -\begin{methoddesc}{modified}{} -Sets the time the \code{robots.txt} file was last fetched to the current -time. -\end{methoddesc} - -\end{classdesc} - -The following example demonstrates basic use of the RobotFileParser class. - -\begin{verbatim} ->>> import robotparser ->>> rp = robotparser.RobotFileParser() ->>> rp.set_url("http://www.musi-cal.com/robots.txt") ->>> rp.read() ->>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco") -False ->>> rp.can_fetch("*", "http://www.musi-cal.com/") -True -\end{verbatim} diff --git a/Doc/lib/librunpy.tex b/Doc/lib/librunpy.tex deleted file mode 100644 index 60707ca..0000000 --- a/Doc/lib/librunpy.tex +++ /dev/null @@ -1,76 +0,0 @@ -\section{\module{runpy} --- - Locating and executing Python modules.} - -\declaremodule{standard}{runpy} % standard library, in Python - -\moduleauthor{Nick Coghlan}{ncoghlan@gmail.com} - -\modulesynopsis{Locate and execute Python modules as scripts} - -\versionadded{2.5} - -The \module{runpy} module is used to locate and run Python modules -without importing them first. Its main use is to implement the -\programopt{-m} command line switch that allows scripts to be located -using the Python module namespace rather than the filesystem. - -When executed as a script, the module effectively operates as follows: -\begin{verbatim} - del sys.argv[0] # Remove the runpy module from the arguments - run_module(sys.argv[0], run_name="__main__", alter_sys=True) -\end{verbatim} - -The \module{runpy} module provides a single function: - -\begin{funcdesc}{run_module}{mod_name\optional{, init_globals} -\optional{, run_name}\optional{, alter_sys}} -Execute the code of the specified module and return the resulting -module globals dictionary. The module's code is first located using -the standard import mechanism (refer to PEP 302 for details) and -then executed in a fresh module namespace. - -The optional dictionary argument \var{init_globals} may be used to -pre-populate the globals dictionary before the code is executed. -The supplied dictionary will not be modified. If any of the special -global variables below are defined in the supplied dictionary, those -definitions are overridden by the \code{run_module} function. - -The special global variables \code{__name__}, \code{__file__}, -\code{__loader__} and \code{__builtins__} are set in the globals -dictionary before the module code is executed. - -\code{__name__} is set to \var{run_name} if this optional argument is -supplied, and the \var{mod_name} argument otherwise. - -\code{__loader__} is set to the PEP 302 module loader used to retrieve -the code for the module (This loader may be a wrapper around the -standard import mechanism). - -\code{__file__} is set to the name provided by the module loader. If -the loader does not make filename information available, this -variable is set to \code{None}. - -\code{__builtins__} is automatically initialised with a reference to -the top level namespace of the \module{__builtin__} module. - -If the argument \var{alter_sys} is supplied and evaluates to -\code{True}, then \code{sys.argv[0]} is updated with the value of -\code{__file__} and \code{sys.modules[__name__]} is updated with a -new module object for the module being executed. Note that neither -\code{sys.argv[0]} nor \code{sys.modules[__name__]} are restored to -their original values before the function returns - if client code -needs these values preserved, it must either save them explicitly or -else avoid enabling the automatic alterations to \module{sys}. - -Note that this manipulation of \module{sys} is not thread-safe. Other -threads may see the partially initialised module, as well as the -altered list of arguments. It is recommended that the \module{sys} -module be left alone when invoking this function from threaded code. -\end{funcdesc} - -\begin{seealso} - -\seepep{338}{Executing modules as scripts}{PEP written and -implemented by Nick Coghlan.} - -\end{seealso} diff --git a/Doc/lib/libsched.tex b/Doc/lib/libsched.tex deleted file mode 100644 index 75bab7e..0000000 --- a/Doc/lib/libsched.tex +++ /dev/null @@ -1,97 +0,0 @@ -\section{\module{sched} --- - Event scheduler} - -% LaTeXed and enhanced from comments in file - -\declaremodule{standard}{sched} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{General purpose event scheduler.} - -The \module{sched} module defines a class which implements a general -purpose event scheduler:\index{event scheduling} - -\begin{classdesc}{scheduler}{timefunc, delayfunc} -The \class{scheduler} class defines a generic interface to scheduling -events. It needs two functions to actually deal with the ``outside world'' ---- \var{timefunc} should be callable without arguments, and return -a number (the ``time'', in any units whatsoever). The \var{delayfunc} -function should be callable with one argument, compatible with the output -of \var{timefunc}, and should delay that many time units. -\var{delayfunc} will also be called with the argument \code{0} after -each event is run to allow other threads an opportunity to run in -multi-threaded applications. -\end{classdesc} - -Example: - -\begin{verbatim} ->>> import sched, time ->>> s=sched.scheduler(time.time, time.sleep) ->>> def print_time(): print "From print_time", time.time() -... ->>> def print_some_times(): -... print time.time() -... s.enter(5, 1, print_time, ()) -... s.enter(10, 1, print_time, ()) -... s.run() -... print time.time() -... ->>> print_some_times() -930343690.257 -From print_time 930343695.274 -From print_time 930343700.273 -930343700.276 -\end{verbatim} - - -\subsection{Scheduler Objects \label{scheduler-objects}} - -\class{scheduler} instances have the following methods: - -\begin{methoddesc}[scheduler]{enterabs}{time, priority, action, argument} -Schedule a new event. The \var{time} argument should be a numeric type -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}. - -Executing the event means executing -\code{\var{action}(*\var{argument})}. \var{argument} must be a -sequence holding the parameters for \var{action}. - -Return value is an event which may be used for later cancellation of -the event (see \method{cancel()}). -\end{methoddesc} - -\begin{methoddesc}[scheduler]{enter}{delay, priority, action, argument} -Schedule an event for \var{delay} more time units. Other then the -relative time, the other arguments, the effect and the return value -are the same as those for \method{enterabs()}. -\end{methoddesc} - -\begin{methoddesc}[scheduler]{cancel}{event} -Remove the event from the queue. If \var{event} is not an event -currently in the queue, this method will raise a -\exception{RuntimeError}. -\end{methoddesc} - -\begin{methoddesc}[scheduler]{empty}{} -Return true if the event queue is empty. -\end{methoddesc} - -\begin{methoddesc}[scheduler]{run}{} -Run all scheduled events. This function will wait -(using the \function{delayfunc} function passed to the constructor) -for the next event, then execute it and so on until there are no more -scheduled events. - -Either \var{action} or \var{delayfunc} can raise an exception. In -either case, the scheduler will maintain a consistent state and -propagate the exception. If an exception is raised by \var{action}, -the event will not be attempted in future calls to \method{run()}. - -If a sequence of events takes longer to run than the time available -before the next event, the scheduler will simply fall behind. No -events will be dropped; the calling code is responsible for canceling -events which are no longer pertinent. -\end{methoddesc} diff --git a/Doc/lib/libselect.tex b/Doc/lib/libselect.tex deleted file mode 100644 index 69583d4..0000000 --- a/Doc/lib/libselect.tex +++ /dev/null @@ -1,132 +0,0 @@ -\section{\module{select} --- - Waiting for I/O completion} - -\declaremodule{builtin}{select} -\modulesynopsis{Wait for I/O completion on multiple streams.} - - -This module provides access to the \cfunction{select()} -and \cfunction{poll()} functions -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 on regular files to determine whether a file has grown since -it was last read. - -The module defines the following: - -\begin{excdesc}{error} -The exception raised when an error occurs. The accompanying value is -a pair containing the numeric error code from \cdata{errno} and the -corresponding string, as would be printed by the \C{} function -\cfunction{perror()}. -\end{excdesc} - -\begin{funcdesc}{poll}{} -(Not supported by all operating systems.) Returns a polling object, -which supports registering and unregistering file descriptors, and -then polling them for I/O events; -see section~\ref{poll-objects} below for the methods supported by -polling objects. -\end{funcdesc} - -\begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}} -This is a straightforward interface to the \UNIX{} \cfunction{select()} -system call. The first three arguments are sequences of `waitable -objects': either integers representing file descriptors or -objects with a parameterless method named \method{fileno()} returning -such an integer. The three sequences of waitable objects are for input, -output and `exceptional conditions', respectively. Empty sequences are -allowed, but acceptance of three empty sequences is platform-dependent. -(It is known to work on \UNIX{} but not on Windows.) The optional -\var{timeout} argument specifies a time-out as a floating point number -in seconds. When the \var{timeout} argument is omitted the function -blocks until at least one file descriptor is ready. A time-out value -of zero specifies a poll and never blocks. - -The return value is a triple of lists of objects that are ready: -subsets of the first three arguments. When the time-out is reached -without a file descriptor becoming ready, three empty lists are -returned. - -Among the acceptable object types in the sequences are Python file -objects (e.g. \code{sys.stdin}, or objects returned by -\function{open()} or \function{os.popen()}), socket objects -returned by \function{socket.socket()}.% -\withsubitem{(in module socket)}{\ttindex{socket()}} -\withsubitem{(in module os)}{\ttindex{popen()}} -You may also define a \dfn{wrapper} class yourself, as long as it has -an appropriate \method{fileno()} method (that really returns a file -descriptor, not just a random integer). -\note{File objects on Windows are not acceptable, but sockets -are.\index{WinSock} On Windows, the underlying \cfunction{select()} -function is provided by the WinSock library, and does not handle file -descriptors that don't originate from WinSock.} -\end{funcdesc} - -\subsection{Polling Objects - \label{poll-objects}} - -The \cfunction{poll()} system call, supported on most \UNIX{} systems, -provides better scalability for network servers that service many, -many clients at the same time. -\cfunction{poll()} scales better because the system call only -requires listing the file descriptors of interest, while \cfunction{select()} -builds a bitmap, turns on bits for the fds of interest, and then -afterward the whole bitmap has to be linearly scanned again. -\cfunction{select()} is O(highest file descriptor), while -\cfunction{poll()} is O(number of file descriptors). - -\begin{methoddesc}[poll]{register}{fd\optional{, eventmask}} -Register a file descriptor with the polling object. Future calls to -the \method{poll()} method will then check whether the file descriptor -has any pending I/O events. \var{fd} can be either an integer, or an -object with a \method{fileno()} method that returns an integer. File -objects implement -\method{fileno()}, so they can also be used as the argument. - -\var{eventmask} is an optional bitmask describing the type of events you -want to check for, and can be a combination of the constants -\constant{POLLIN}, \constant{POLLPRI}, and \constant{POLLOUT}, -described in the table below. If not specified, the default value -used will check for all 3 types of events. - -\begin{tableii}{l|l}{constant}{Constant}{Meaning} - \lineii{POLLIN}{There is data to read} - \lineii{POLLPRI}{There is urgent data to read} - \lineii{POLLOUT}{Ready for output: writing will not block} - \lineii{POLLERR}{Error condition of some sort} - \lineii{POLLHUP}{Hung up} - \lineii{POLLNVAL}{Invalid request: descriptor not open} -\end{tableii} - -Registering a file descriptor that's already registered is not an -error, and has the same effect as registering the descriptor exactly -once. -\end{methoddesc} - -\begin{methoddesc}[poll]{unregister}{fd} -Remove a file descriptor being tracked by a polling object. Just like -the \method{register()} method, \var{fd} can be an integer or an -object with a \method{fileno()} method that returns an integer. - -Attempting to remove a file descriptor that was never registered -causes a \exception{KeyError} exception to be raised. -\end{methoddesc} - -\begin{methoddesc}[poll]{poll}{\optional{timeout}} -Polls the set of registered file descriptors, and returns a -possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples -for the descriptors that have events or errors to report. -\var{fd} is the file descriptor, and \var{event} is a bitmask -with bits set for the reported events for that descriptor ---- \constant{POLLIN} for waiting input, -\constant{POLLOUT} to indicate that the descriptor can be written to, and -so forth. -An empty list indicates that the call timed out and no file -descriptors had any events to report. -If \var{timeout} is given, it specifies the length of time in -milliseconds which the system will wait for events before returning. -If \var{timeout} is omitted, negative, or \constant{None}, the call will -block until there is an event for this poll object. -\end{methoddesc} diff --git a/Doc/lib/libsgmllib.tex b/Doc/lib/libsgmllib.tex deleted file mode 100644 index 1fe0d63..0000000 --- a/Doc/lib/libsgmllib.tex +++ /dev/null @@ -1,271 +0,0 @@ -\section{\module{sgmllib} --- - Simple SGML parser} - -\declaremodule{standard}{sgmllib} -\modulesynopsis{Only as much of an SGML parser as needed to parse HTML.} - -\index{SGML} - -This module defines a class \class{SGMLParser} which serves as the -basis for parsing text files formatted in SGML (Standard Generalized -Mark-up Language). In fact, it does not provide a full SGML parser ---- it only parses SGML insofar as it is used by HTML, and the module -only exists as a base for the \refmodule{htmllib} module. Another -HTML parser which supports XHTML and offers a somewhat different -interface is available in the \refmodule{HTMLParser} module. - -\begin{classdesc}{SGMLParser}{} -The \class{SGMLParser} class is instantiated without arguments. -The parser is hardcoded to recognize the following -constructs: - -\begin{itemize} -\item -Opening and closing tags of the form -\samp{<\var{tag} \var{attr}="\var{value}" ...>} and -\samp{</\var{tag}>}, respectively. - -\item -Numeric character references of the form \samp{\&\#\var{name};}. - -\item -Entity references of the form \samp{\&\var{name};}. - -\item -SGML comments of the form \samp{<!--\var{text}-->}. Note that -spaces, tabs, and newlines are allowed between the trailing -\samp{>} and the immediately preceding \samp{--}. - -\end{itemize} -\end{classdesc} - -A single exception is defined as well: - -\begin{excdesc}{SGMLParseError} -Exception raised by the \class{SGMLParser} class when it encounters an -error while parsing. -\versionadded{2.1} -\end{excdesc} - - -\class{SGMLParser} instances have the following methods: - - -\begin{methoddesc}{reset}{} -Reset the instance. Loses all unprocessed data. This is called -implicitly at instantiation time. -\end{methoddesc} - -\begin{methoddesc}{setnomoretags}{} -Stop processing tags. Treat all following input as literal input -(CDATA). (This is only provided so the HTML tag -\code{<PLAINTEXT>} can be implemented.) -\end{methoddesc} - -\begin{methoddesc}{setliteral}{} -Enter literal mode (CDATA mode). -\end{methoddesc} - -\begin{methoddesc}{feed}{data} -Feed some text to the parser. It is processed insofar as it consists -of complete elements; incomplete data is buffered until more data is -fed or \method{close()} is called. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Force processing of all buffered data as if it were followed by an -end-of-file mark. This method may be redefined by a derived class to -define additional processing at the end of the input, but the -redefined version should always call \method{close()}. -\end{methoddesc} - -\begin{methoddesc}{get_starttag_text}{} -Return the text of the most recently opened start tag. This should -not normally be needed for structured processing, but may be useful in -dealing with HTML ``as deployed'' or for re-generating input with -minimal changes (whitespace between attributes can be preserved, -etc.). -\end{methoddesc} - -\begin{methoddesc}{handle_starttag}{tag, method, attributes} -This method is called to handle start tags for which either a -\method{start_\var{tag}()} or \method{do_\var{tag}()} method has been -defined. The \var{tag} argument is the name of the tag converted to -lower case, and the \var{method} argument is the bound method which -should be used to support semantic interpretation of the start tag. -The \var{attributes} argument is a list of \code{(\var{name}, -\var{value})} pairs containing the attributes found inside the tag's -\code{<>} brackets. - -The \var{name} has been translated to lower case. -Double quotes and backslashes in the \var{value} have been interpreted, -as well as known character references and known entity references -terminated by a semicolon (normally, entity references can be terminated -by any non-alphanumerical character, but this would break the very -common case of \code{<A HREF="url?spam=1\&eggs=2">} when \code{eggs} -is a valid entity name). - -For instance, for the tag \code{<A HREF="http://www.cwi.nl/">}, this -method would be called as \samp{unknown_starttag('a', [('href', -'http://www.cwi.nl/')])}. The base implementation simply calls -\var{method} with \var{attributes} as the only argument. -\versionadded[Handling of entity and character references within - attribute values]{2.5} -\end{methoddesc} - -\begin{methoddesc}{handle_endtag}{tag, method} -This method is called to handle endtags for which an -\method{end_\var{tag}()} method has been defined. The -\var{tag} argument is the name of the tag converted to lower case, and -the \var{method} argument is the bound method which should be used to -support semantic interpretation of the end tag. If no -\method{end_\var{tag}()} method is defined for the closing element, -this handler is not called. The base implementation simply calls -\var{method}. -\end{methoddesc} - -\begin{methoddesc}{handle_data}{data} -This method is called to process arbitrary data. It is intended to be -overridden by a derived class; the base class implementation does -nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_charref}{ref} -This method is called to process a character reference of the form -\samp{\&\#\var{ref};}. The base implementation uses -\method{convert_charref()} to convert the reference to a string. If -that method returns a string, it is passed to \method{handle_data()}, -otherwise \method{unknown_charref(\var{ref})} is called to handle the -error. -\versionchanged[Use \method{convert_charref()} instead of hard-coding -the conversion]{2.5} -\end{methoddesc} - -\begin{methoddesc}{convert_charref}{ref} -Convert a character reference to a string, or \code{None}. \var{ref} -is the reference passed in as a string. In the base implementation, -\var{ref} must be a decimal number in the range 0-255. It converts -the code point found using the \method{convert_codepoint()} method. -If \var{ref} is invalid or out of range, this method returns -\code{None}. This method is called by the default -\method{handle_charref()} implementation and by the attribute value -parser. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}{convert_codepoint}{codepoint} -Convert a codepoint to a \class{str} value. Encodings can be handled -here if appropriate, though the rest of \module{sgmllib} is oblivious -on this matter. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}{handle_entityref}{ref} -This method is called to process a general entity reference of the -form \samp{\&\var{ref};} where \var{ref} is an general entity -reference. It converts \var{ref} by passing it to -\method{convert_entityref()}. If a translation is returned, it -calls the method \method{handle_data()} with the translation; -otherwise, it calls the method \code{unknown_entityref(\var{ref})}. -The default \member{entitydefs} defines translations for -\code{\&}, \code{\&apos}, \code{\>}, \code{\<}, and -\code{\"}. -\versionchanged[Use \method{convert_entityref()} instead of hard-coding -the conversion]{2.5} -\end{methoddesc} - -\begin{methoddesc}{convert_entityref}{ref} -Convert a named entity reference to a \class{str} value, or -\code{None}. The resulting value will not be parsed. \var{ref} will -be only the name of the entity. The default implementation looks for -\var{ref} in the instance (or class) variable \member{entitydefs} -which should be a mapping from entity names to corresponding -translations. If no translation is available for \var{ref}, this -method returns \code{None}. This method is called by the default -\method{handle_entityref()} implementation and by the attribute value -parser. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}{handle_comment}{comment} -This method is called when a comment is encountered. The -\var{comment} argument is a string containing the text between the -\samp{<!--} and \samp{-->} delimiters, but not the delimiters -themselves. For example, the comment \samp{<!--text-->} will -cause this method to be called with the argument \code{'text'}. The -default method does nothing. -\end{methoddesc} - -\begin{methoddesc}{handle_decl}{data} -Method called when an SGML declaration is read by the parser. In -practice, the \code{DOCTYPE} declaration is the only thing observed in -HTML, but the parser does not discriminate among different (or broken) -declarations. Internal subsets in a \code{DOCTYPE} declaration are -not supported. The \var{data} parameter will be the entire contents -of the declaration inside the \code{<!}...\code{>} markup. The -default implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}{report_unbalanced}{tag} -This method is called when an end tag is found which does not -correspond to any open element. -\end{methoddesc} - -\begin{methoddesc}{unknown_starttag}{tag, attributes} -This method is called to process an unknown start tag. It is intended -to be overridden by a derived class; the base class implementation -does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_endtag}{tag} -This method is called to process an unknown end tag. It is intended -to be overridden by a derived class; the base class implementation -does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_charref}{ref} -This method is called to process unresolvable numeric character -references. Refer to \method{handle_charref()} to determine what is -handled by default. It is intended to be overridden by a derived -class; the base class implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}{unknown_entityref}{ref} -This method is called to process an unknown entity reference. It is -intended to be overridden by a derived class; the base class -implementation does nothing. -\end{methoddesc} - -Apart from overriding or extending the methods listed above, derived -classes may also define methods of the following form to define -processing of specific tags. Tag names in the input stream are case -independent; the \var{tag} occurring in method names must be in lower -case: - -\begin{methoddescni}{start_\var{tag}}{attributes} -This method is called to process an opening tag \var{tag}. It has -preference over \method{do_\var{tag}()}. The -\var{attributes} argument has the same meaning as described for -\method{handle_starttag()} above. -\end{methoddescni} - -\begin{methoddescni}{do_\var{tag}}{attributes} -This method is called to process an opening tag \var{tag} -for which no \method{start_\var{tag}} method is defined. -The \var{attributes} argument -has the same meaning as described for \method{handle_starttag()} above. -\end{methoddescni} - -\begin{methoddescni}{end_\var{tag}}{} -This method is called to process a closing tag \var{tag}. -\end{methoddescni} - -Note that the parser maintains a stack of open elements for which no -end tag has been found yet. Only tags processed by -\method{start_\var{tag}()} are pushed on this stack. Definition of an -\method{end_\var{tag}()} method is optional for these tags. For tags -processed by \method{do_\var{tag}()} or by \method{unknown_tag()}, no -\method{end_\var{tag}()} method must be defined; if defined, it will -not be used. If both \method{start_\var{tag}()} and -\method{do_\var{tag}()} methods exist for a tag, the -\method{start_\var{tag}()} method takes precedence. diff --git a/Doc/lib/libshelve.tex b/Doc/lib/libshelve.tex deleted file mode 100644 index 6ca3576..0000000 --- a/Doc/lib/libshelve.tex +++ /dev/null @@ -1,174 +0,0 @@ -\section{\module{shelve} --- - Python object persistence} - -\declaremodule{standard}{shelve} -\modulesynopsis{Python object persistence.} - - -A ``shelf'' is a persistent, dictionary-like object. The difference -with ``dbm'' databases is that the values (not the keys!) in a shelf -can be essentially arbitrary Python objects --- anything that the -\refmodule{pickle} module can handle. This includes most class -instances, recursive data types, and objects containing lots of shared -sub-objects. The keys are ordinary strings. -\refstmodindex{pickle} - -\begin{funcdesc}{open}{filename\optional{,flag='c'\optional{,protocol=\code{None}\optional{,writeback=\code{False}}}}} -Open a persistent dictionary. The filename specified is the base filename -for the underlying database. As a side-effect, an extension may be added to -the filename and more than one file may be created. By default, the -underlying database file is opened for reading and writing. The optional -{}\var{flag} parameter has the same interpretation as the \var{flag} -parameter of \function{anydbm.open}. - -By default, version 0 pickles are used to serialize values. -The version of the pickle protocol can be specified with the -\var{protocol} parameter. \versionchanged[The \var{protocol} -parameter was added]{2.3} - -By default, mutations to persistent-dictionary mutable entries are not -automatically written back. If the optional \var{writeback} parameter -is set to {}\var{True}, all entries accessed are cached in memory, and -written back at close time; this can make it handier to mutate mutable -entries in the persistent dictionary, but, if many entries are -accessed, it can consume vast amounts of memory for the cache, and it -can make the close operation very slow since all accessed entries are -written back (there is no way to determine which accessed entries are -mutable, nor which ones were actually mutated). - -\end{funcdesc} - -Shelve objects support all methods supported by dictionaries. This eases -the transition from dictionary based scripts to those requiring persistent -storage. - -One additional method is supported: -\begin{methoddesc}[Shelf]{sync}{} -Write back all entries in the cache if the shelf was opened with -\var{writeback} set to \var{True}. Also empty the cache and synchronize -the persistent dictionary on disk, if feasible. This is called automatically -when the shelf is closed with \method{close()}. -\end{methoddesc} - -\subsection{Restrictions} - -\begin{itemize} - -\item -The choice of which database package will be used -(such as \refmodule{dbm}, \refmodule{gdbm} or \refmodule{bsddb}) depends on -which interface is available. Therefore it is not safe to open the database -directly using \refmodule{dbm}. The database is also (unfortunately) subject -to the limitations of \refmodule{dbm}, if it is used --- this means -that (the pickled representation of) the objects stored in the -database should be fairly small, and in rare cases key collisions may -cause the database to refuse updates. -\refbimodindex{dbm} -\refbimodindex{gdbm} -\refbimodindex{bsddb} - -\item -Depending on the implementation, closing a persistent dictionary may -or may not be necessary to flush changes to disk. The \method{__del__} -method of the \class{Shelf} class calls the \method{close} method, so the -programmer generally need not do this explicitly. - -\item -The \module{shelve} module does not support \emph{concurrent} read/write -access to shelved objects. (Multiple simultaneous read accesses are -safe.) When a program has a shelf open for writing, no other program -should have it open for reading or writing. \UNIX{} file locking can -be used to solve this, but this differs across \UNIX{} versions and -requires knowledge about the database implementation used. - -\end{itemize} - -\begin{classdesc}{Shelf}{dict\optional{, protocol=None\optional{, writeback=False}}} -A subclass of \class{UserDict.DictMixin} which stores pickled values in the -\var{dict} object. - -By default, version 0 pickles are used to serialize values. The -version of the pickle protocol can be specified with the -\var{protocol} parameter. See the \module{pickle} documentation for a -discussion of the pickle protocols. \versionchanged[The \var{protocol} -parameter was added]{2.3} - -If the \var{writeback} parameter is \code{True}, the object will hold a -cache of all entries accessed and write them back to the \var{dict} at -sync and close times. This allows natural operations on mutable entries, -but can consume much more memory and make sync and close take a long time. -\end{classdesc} - -\begin{classdesc}{BsdDbShelf}{dict\optional{, protocol=None\optional{, writeback=False}}} - -A subclass of \class{Shelf} which exposes \method{first}, -\method{next}, \method{previous}, \method{last} and -\method{set_location} which are available in the \module{bsddb} module -but not in other database modules. The \var{dict} object passed to -the constructor must support those methods. This is generally -accomplished by calling one of \function{bsddb.hashopen}, -\function{bsddb.btopen} or \function{bsddb.rnopen}. The optional -\var{protocol} and \var{writeback} parameters have the -same interpretation as for the \class{Shelf} class. - -\end{classdesc} - -\begin{classdesc}{DbfilenameShelf}{filename\optional{, flag='c'\optional{, protocol=None\optional{, writeback=False}}}} - -A subclass of \class{Shelf} which accepts a \var{filename} instead of -a dict-like object. The underlying file will be opened using -{}\function{anydbm.open}. By default, the file will be created and -opened for both read and write. The optional \var{flag} parameter has -the same interpretation as for the \function{open} function. The -optional \var{protocol} and \var{writeback} parameters -have the same interpretation as for the \class{Shelf} class. - -\end{classdesc} - -\subsection{Example} - -To summarize the interface (\code{key} is a string, \code{data} is an -arbitrary object): - -\begin{verbatim} -import shelve - -d = shelve.open(filename) # open -- file may get suffix added by low-level - # library - -d[key] = data # store data at key (overwrites old data if - # using an existing key) -data = d[key] # retrieve a COPY of data at key (raise KeyError if no - # such key) -del d[key] # delete data stored at key (raises KeyError - # if no such key) -flag = d.has_key(key) # true if the key exists -klist = d.keys() # a list of all existing keys (slow!) - -# as d was opened WITHOUT writeback=True, beware: -d['xx'] = range(4) # this works as expected, but... -d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!!! - -# having opened d without writeback=True, you need to code carefully: -temp = d['xx'] # extracts the copy -temp.append(5) # mutates the copy -d['xx'] = temp # stores the copy right back, to persist it - -# or, d=shelve.open(filename,writeback=True) would let you just code -# d['xx'].append(5) and have it work as expected, BUT it would also -# consume more memory and make the d.close() operation slower. - -d.close() # close it -\end{verbatim} - -\begin{seealso} - \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.} - \seemodule{bsddb}{BSD \code{db} database interface.} - \seemodule{dbhash}{Thin layer around the \module{bsddb} which provides an - \function{open} function like the other database modules.} - \seemodule{dbm}{Standard \UNIX{} database interface.} - \seemodule{dumbdbm}{Portable implementation of the \code{dbm} interface.} - \seemodule{gdbm}{GNU database interface, based on the \code{dbm} interface.} - \seemodule{pickle}{Object serialization used by \module{shelve}.} - \seemodule{cPickle}{High-performance version of \refmodule{pickle}.} -\end{seealso} diff --git a/Doc/lib/libshlex.tex b/Doc/lib/libshlex.tex deleted file mode 100644 index 230ae9f..0000000 --- a/Doc/lib/libshlex.tex +++ /dev/null @@ -1,279 +0,0 @@ -\section{\module{shlex} --- - Simple lexical analysis} - -\declaremodule{standard}{shlex} -\modulesynopsis{Simple lexical analysis for \UNIX\ shell-like languages.} -\moduleauthor{Eric S. Raymond}{esr@snark.thyrsus.com} -\moduleauthor{Gustavo Niemeyer}{niemeyer@conectiva.com} -\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} -\sectionauthor{Gustavo Niemeyer}{niemeyer@conectiva.com} - -\versionadded{1.5.2} - -The \class{shlex} class makes it easy to write lexical analyzers for -simple syntaxes resembling that of the \UNIX{} shell. This will often -be useful for writing minilanguages, (for example, in run control -files for Python applications) or for parsing quoted strings. - -\note{The \module{shlex} module currently does not support Unicode input.} - -The \module{shlex} module defines the following functions: - -\begin{funcdesc}{split}{s\optional{, comments\optional{, posix}}} -Split the string \var{s} using shell-like syntax. If \var{comments} is -\constant{False} (the default), the parsing of comments in the given -string will be disabled (setting the \member{commenters} member of the -\class{shlex} instance to the empty string). This function operates -in \POSIX{} mode by default, but uses non-\POSIX{} mode if the -\var{posix} argument is false. -\versionadded{2.3} -\versionchanged[Added the \var{posix} parameter]{2.6} -\note{Since the \function{split()} function instantiates a \class{shlex} - instance, passing \code{None} for \var{s} will read the string - to split from standard input.} -\end{funcdesc} - -The \module{shlex} module defines the following class: - -\begin{classdesc}{shlex}{\optional{instream\optional{, - infile\optional{, posix}}}} -A \class{shlex} instance or subclass instance is a lexical analyzer -object. The initialization argument, if present, specifies where to -read characters from. It must be a file-/stream-like object with -\method{read()} and \method{readline()} methods, or a string (strings -are accepted since Python 2.3). If no argument is given, input will be -taken from \code{sys.stdin}. The second optional argument is a filename -string, which sets the initial value of the \member{infile} member. If -the \var{instream} argument is omitted or equal to \code{sys.stdin}, -this second argument defaults to ``stdin''. The \var{posix} argument -was introduced in Python 2.3, and defines the operational mode. When -\var{posix} is not true (default), the \class{shlex} instance will -operate in compatibility mode. When operating in \POSIX{} mode, -\class{shlex} will try to be as close as possible to the \POSIX{} shell -parsing rules. See section~\ref{shlex-objects}. -\end{classdesc} - -\begin{seealso} - \seemodule{ConfigParser}{Parser for configuration files similar to the - Windows \file{.ini} files.} -\end{seealso} - - -\subsection{shlex Objects \label{shlex-objects}} - -A \class{shlex} instance has the following methods: - -\begin{methoddesc}[shlex]{get_token}{} -Return a token. If tokens have been stacked using -\method{push_token()}, pop a token off the stack. Otherwise, read one -from the input stream. If reading encounters an immediate -end-of-file, \member{self.eof} is returned (the empty string (\code{''}) -in non-\POSIX{} mode, and \code{None} in \POSIX{} mode). -\end{methoddesc} - -\begin{methoddesc}[shlex]{push_token}{str} -Push the argument onto the token stack. -\end{methoddesc} - -\begin{methoddesc}[shlex]{read_token}{} -Read a raw token. Ignore the pushback stack, and do not interpret source -requests. (This is not ordinarily a useful entry point, and is -documented here only for the sake of completeness.) -\end{methoddesc} - -\begin{methoddesc}[shlex]{sourcehook}{filename} -When \class{shlex} detects a source request (see -\member{source} below) this method is given the following token as -argument, and expected to return a tuple consisting of a filename and -an open file-like object. - -Normally, this method first strips any quotes off the argument. If -the result is an absolute pathname, or there was no previous source -request in effect, or the previous source was a stream -(such as \code{sys.stdin}), the result is left alone. Otherwise, if the -result is a relative pathname, the directory part of the name of the -file immediately before it on the source inclusion stack is prepended -(this behavior is like the way the C preprocessor handles -\code{\#include "file.h"}). - -The result of the manipulations is treated as a filename, and returned -as the first component of the tuple, with -\function{open()} called on it to yield the second component. (Note: -this is the reverse of the order of arguments in instance initialization!) - -This hook is exposed so that you can use it to implement directory -search paths, addition of file extensions, and other namespace hacks. -There is no corresponding `close' hook, but a shlex instance will call -the \method{close()} method of the sourced input stream when it -returns \EOF. - -For more explicit control of source stacking, use the -\method{push_source()} and \method{pop_source()} methods. -\end{methoddesc} - -\begin{methoddesc}[shlex]{push_source}{stream\optional{, filename}} -Push an input source stream onto the input stack. If the filename -argument is specified it will later be available for use in error -messages. This is the same method used internally by the -\method{sourcehook} method. -\versionadded{2.1} -\end{methoddesc} - -\begin{methoddesc}[shlex]{pop_source}{} -Pop the last-pushed input source from the input stack. -This is the same method used internally when the lexer reaches -\EOF{} on a stacked input stream. -\versionadded{2.1} -\end{methoddesc} - -\begin{methoddesc}[shlex]{error_leader}{\optional{file\optional{, line}}} -This method generates an error message leader in the format of a -\UNIX{} C compiler error label; the format is \code{'"\%s", line \%d: '}, -where the \samp{\%s} is replaced with the name of the current source -file and the \samp{\%d} with the current input line number (the -optional arguments can be used to override these). - -This convenience is provided to encourage \module{shlex} users to -generate error messages in the standard, parseable format understood -by Emacs and other \UNIX{} tools. -\end{methoddesc} - -Instances of \class{shlex} subclasses have some public instance -variables which either control lexical analysis or can be used for -debugging: - -\begin{memberdesc}[shlex]{commenters} -The string of characters that are recognized as comment beginners. -All characters from the comment beginner to end of line are ignored. -Includes just \character{\#} by default. -\end{memberdesc} - -\begin{memberdesc}[shlex]{wordchars} -The string of characters that will accumulate into multi-character -tokens. By default, includes all \ASCII{} alphanumerics and -underscore. -\end{memberdesc} - -\begin{memberdesc}[shlex]{whitespace} -Characters that will be considered whitespace and skipped. Whitespace -bounds tokens. By default, includes space, tab, linefeed and -carriage-return. -\end{memberdesc} - -\begin{memberdesc}[shlex]{escape} -Characters that will be considered as escape. This will be only used -in \POSIX{} mode, and includes just \character{\textbackslash} by default. -\versionadded{2.3} -\end{memberdesc} - -\begin{memberdesc}[shlex]{quotes} -Characters that will be considered string quotes. The token -accumulates until the same quote is encountered again (thus, different -quote types protect each other as in the shell.) By default, includes -\ASCII{} single and double quotes. -\end{memberdesc} - -\begin{memberdesc}[shlex]{escapedquotes} -Characters in \member{quotes} that will interpret escape characters -defined in \member{escape}. This is only used in \POSIX{} mode, and -includes just \character{"} by default. -\versionadded{2.3} -\end{memberdesc} - -\begin{memberdesc}[shlex]{whitespace_split} -If \code{True}, tokens will only be split in whitespaces. This is useful, for -example, for parsing command lines with \class{shlex}, getting tokens -in a similar way to shell arguments. -\versionadded{2.3} -\end{memberdesc} - -\begin{memberdesc}[shlex]{infile} -The name of the current input file, as initially set at class -instantiation time or stacked by later source requests. It may -be useful to examine this when constructing error messages. -\end{memberdesc} - -\begin{memberdesc}[shlex]{instream} -The input stream from which this \class{shlex} instance is reading -characters. -\end{memberdesc} - -\begin{memberdesc}[shlex]{source} -This member is \code{None} by default. If you assign a string to it, -that string will be recognized as a lexical-level inclusion request -similar to the \samp{source} keyword in various shells. That is, the -immediately following token will opened as a filename and input taken -from that stream until \EOF, at which point the \method{close()} -method of that stream will be called and the input source will again -become the original input stream. Source requests may be stacked any -number of levels deep. -\end{memberdesc} - -\begin{memberdesc}[shlex]{debug} -If this member is numeric and \code{1} or more, a \class{shlex} -instance will print verbose progress output on its behavior. If you -need to use this, you can read the module source code to learn the -details. -\end{memberdesc} - -\begin{memberdesc}[shlex]{lineno} -Source line number (count of newlines seen so far plus one). -\end{memberdesc} - -\begin{memberdesc}[shlex]{token} -The token buffer. It may be useful to examine this when catching -exceptions. -\end{memberdesc} - -\begin{memberdesc}[shlex]{eof} -Token used to determine end of file. This will be set to the empty -string (\code{''}), in non-\POSIX{} mode, and to \code{None} in -\POSIX{} mode. -\versionadded{2.3} -\end{memberdesc} - -\subsection{Parsing Rules\label{shlex-parsing-rules}} - -When operating in non-\POSIX{} mode, \class{shlex} will try to obey to -the following rules. - -\begin{itemize} -\item Quote characters are not recognized within words - (\code{Do"Not"Separate} is parsed as the single word - \code{Do"Not"Separate}); -\item Escape characters are not recognized; -\item Enclosing characters in quotes preserve the literal value of - all characters within the quotes; -\item Closing quotes separate words (\code{"Do"Separate} is parsed - as \code{"Do"} and \code{Separate}); -\item If \member{whitespace_split} is \code{False}, any character not - declared to be a word character, whitespace, or a quote will be - returned as a single-character token. If it is \code{True}, - \class{shlex} will only split words in whitespaces; -\item EOF is signaled with an empty string (\code{''}); -\item It's not possible to parse empty strings, even if quoted. -\end{itemize} - -When operating in \POSIX{} mode, \class{shlex} will try to obey to the -following parsing rules. - -\begin{itemize} -\item Quotes are stripped out, and do not separate words - (\code{"Do"Not"Separate"} is parsed as the single word - \code{DoNotSeparate}); -\item Non-quoted escape characters (e.g. \character{\textbackslash}) - preserve the literal value of the next character that follows; -\item Enclosing characters in quotes which are not part of - \member{escapedquotes} (e.g. \character{'}) preserve the literal - value of all characters within the quotes; -\item Enclosing characters in quotes which are part of - \member{escapedquotes} (e.g. \character{"}) preserves the literal - value of all characters within the quotes, with the exception of - the characters mentioned in \member{escape}. The escape characters - retain its special meaning only when followed by the quote in use, - or the escape character itself. Otherwise the escape character - will be considered a normal character. -\item EOF is signaled with a \constant{None} value; -\item Quoted empty strings (\code{''}) are allowed; -\end{itemize} - diff --git a/Doc/lib/libshutil.tex b/Doc/lib/libshutil.tex deleted file mode 100644 index 65cba54..0000000 --- a/Doc/lib/libshutil.tex +++ /dev/null @@ -1,152 +0,0 @@ -\section{\module{shutil} --- - High-level file operations} - -\declaremodule{standard}{shutil} -\modulesynopsis{High-level file operations, including copying.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -% partly based on the docstrings - - -The \module{shutil} module offers a number of high-level operations on -files and collections of files. In particular, functions are provided -which support file copying and removal. -\index{file!copying} -\index{copying files} - -\strong{Caveat:} On MacOS, the resource fork and other metadata are -not used. For file copies, this means that resources will be lost and -file type and creator codes will not be correct. - - -\begin{funcdesc}{copyfile}{src, dst} - Copy the contents of the file named \var{src} to a file named - \var{dst}. The destination location must be writable; otherwise, - an \exception{IOError} exception will be raised. - If \var{dst} already exists, it will be replaced. - Special files such as character or block devices - and pipes cannot be copied with this function. \var{src} and - \var{dst} are path names given as strings. -\end{funcdesc} - -\begin{funcdesc}{copyfileobj}{fsrc, fdst\optional{, length}} - Copy the contents of the file-like object \var{fsrc} to the - file-like object \var{fdst}. The integer \var{length}, if given, - is the buffer size. In particular, a negative \var{length} value - means to copy the data without looping over the source data in - chunks; by default the data is read in chunks to avoid uncontrolled - memory consumption. Note that if the current file position of the - \var{fsrc} object is not 0, only the contents from the current file - position to the end of the file will be copied. -\end{funcdesc} - -\begin{funcdesc}{copymode}{src, dst} - Copy the permission bits from \var{src} to \var{dst}. The file - contents, owner, and group are unaffected. \var{src} and \var{dst} - are path names given as strings. -\end{funcdesc} - -\begin{funcdesc}{copystat}{src, dst} - Copy the permission bits, last access time, last modification time, - and flags from \var{src} to \var{dst}. The file contents, owner, and - group are unaffected. \var{src} and \var{dst} are path names given - as strings. -\end{funcdesc} - -\begin{funcdesc}{copy}{src, dst} - Copy the file \var{src} to the file or directory \var{dst}. If - \var{dst} is a directory, a file with the same basename as \var{src} - is created (or overwritten) in the directory specified. Permission - bits are copied. \var{src} and \var{dst} are path names given as - strings. -\end{funcdesc} - -\begin{funcdesc}{copy2}{src, dst} - Similar to \function{copy()}, but last access time and last - modification time are copied as well. This is similar to the - \UNIX{} command \program{cp} \programopt{-p}. -\end{funcdesc} - -\begin{funcdesc}{copytree}{src, dst\optional{, symlinks}} - Recursively copy an entire directory tree rooted at \var{src}. The - destination directory, named by \var{dst}, must not already exist; - it will be created as well as missing parent directories. - Permissions and times of directories are copied with \function{copystat()}, - individual files are copied using \function{copy2()}. - If \var{symlinks} is true, symbolic links in - the source tree are represented as symbolic links in the new tree; - if false or omitted, the contents of the linked files are copied to - the new tree. If exception(s) occur, an \exception{Error} is raised - with a list of reasons. - - The source code for this should be considered an example rather than - a tool. - - \versionchanged[\exception{Error} is raised if any exceptions occur during - copying, rather than printing a message]{2.3} - - \versionchanged[Create intermediate directories needed to create \var{dst}, - rather than raising an error. Copy permissions and times of - directories using \function{copystat()}]{2.5} - -\end{funcdesc} - -\begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}} - \index{directory!deleting} - Delete an entire directory tree (\var{path} must point to a directory). - If \var{ignore_errors} is true, errors resulting from failed removals - will be ignored; if false or omitted, such errors are handled by - calling a handler specified by \var{onerror} or, if that is omitted, - they raise an exception. - - If \var{onerror} is provided, it must be a callable that accepts - three parameters: \var{function}, \var{path}, and \var{excinfo}. - The first parameter, \var{function}, is the function which raised - the exception; it will be \function{os.listdir()}, \function{os.remove()} or - \function{os.rmdir()}. The second parameter, \var{path}, will be - the path name passed to \var{function}. The third parameter, - \var{excinfo}, will be the exception information return by - \function{sys.exc_info()}. Exceptions raised by \var{onerror} will - not be caught. -\end{funcdesc} - -\begin{funcdesc}{move}{src, dst} -Recursively move a file or directory to another location. - -If the destination is on our current filesystem, then simply use -rename. Otherwise, copy src to the dst and then remove src. - -\versionadded{2.3} -\end{funcdesc} - -\begin{excdesc}{Error} -This exception collects exceptions that raised during a mult-file -operation. For \function{copytree}, the exception argument is a -list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}). - -\versionadded{2.3} -\end{excdesc} - -\subsection{Example \label{shutil-example}} - -This example is the implementation of the \function{copytree()} -function, described above, with the docstring omitted. It -demonstrates many of the other functions provided by this module. - -\begin{verbatim} -def copytree(src, dst, symlinks=0): - names = os.listdir(src) - os.mkdir(dst) - for name in names: - srcname = os.path.join(src, name) - dstname = os.path.join(dst, name) - try: - if symlinks and os.path.islink(srcname): - linkto = os.readlink(srcname) - os.symlink(linkto, dstname) - elif os.path.isdir(srcname): - copytree(srcname, dstname, symlinks) - else: - copy2(srcname, dstname) - except (IOError, os.error) as why: - print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why)) -\end{verbatim} diff --git a/Doc/lib/libsignal.tex b/Doc/lib/libsignal.tex deleted file mode 100644 index e98aa90..0000000 --- a/Doc/lib/libsignal.tex +++ /dev/null @@ -1,173 +0,0 @@ -\section{\module{signal} --- - Set handlers for asynchronous events} - -\declaremodule{builtin}{signal} -\modulesynopsis{Set handlers for asynchronous events.} - - -This module provides mechanisms to use signal handlers in Python. -Some general rules for working with signals and their handlers: - -\begin{itemize} - -\item -A handler for a particular signal, once set, remains installed until -it is explicitly reset (Python emulates the BSD style interface -regardless of the underlying implementation), with the exception of -the handler for \constant{SIGCHLD}, which follows the underlying -implementation. - -\item -There is no way to ``block'' signals temporarily from critical -sections (since this is not supported by all \UNIX{} flavors). - -\item -Although Python signal handlers are called asynchronously as far as -the Python user is concerned, they can only occur between the -``atomic'' instructions of the Python interpreter. This means that -signals arriving during long calculations implemented purely in C -(such as regular expression matches on large bodies of text) may be -delayed for an arbitrary amount of time. - -\item -When a signal arrives during an I/O operation, it is possible that the -I/O operation raises an exception after the signal handler returns. -This is dependent on the underlying \UNIX{} system's semantics regarding -interrupted system calls. - -\item -Because the \C{} signal handler always returns, it makes little sense to -catch synchronous errors like \constant{SIGFPE} or \constant{SIGSEGV}. - -\item -Python installs a small number of signal handlers by default: -\constant{SIGPIPE} is ignored (so write errors on pipes and sockets can be -reported as ordinary Python exceptions) and \constant{SIGINT} is translated -into a \exception{KeyboardInterrupt} exception. All of these can be -overridden. - -\item -Some care must be taken if both signals and threads are used in the -same program. The fundamental thing to remember in using signals and -threads simultaneously is:\ always perform \function{signal()} operations -in the main thread of execution. Any thread can perform an -\function{alarm()}, \function{getsignal()}, or \function{pause()}; -only the main thread can set a new signal handler, and the main thread -will be the only one to receive signals (this is enforced by the -Python \module{signal} module, even if the underlying thread -implementation supports sending signals to individual threads). This -means that signals can't be used as a means of inter-thread -communication. Use locks instead. - -\end{itemize} - -The variables defined in the \module{signal} module are: - -\begin{datadesc}{SIG_DFL} - This is one of two standard signal handling options; it will simply - perform the default function for the signal. For example, on most - systems the default action for \constant{SIGQUIT} is to dump core - and exit, while the default action for \constant{SIGCLD} is to - simply ignore it. -\end{datadesc} - -\begin{datadesc}{SIG_IGN} - This is another standard signal handler, which will simply ignore - the given signal. -\end{datadesc} - -\begin{datadesc}{SIG*} - All the signal numbers are defined symbolically. For example, the - hangup signal is defined as \constant{signal.SIGHUP}; the variable names - are identical to the names used in C programs, as found in - \code{<signal.h>}. - The \UNIX{} man page for `\cfunction{signal()}' lists the existing - signals (on some systems this is \manpage{signal}{2}, on others the - list is in \manpage{signal}{7}). - Note that not all systems define the same set of signal names; only - those names defined by the system are defined by this module. -\end{datadesc} - -\begin{datadesc}{NSIG} - One more than the number of the highest signal number. -\end{datadesc} - -The \module{signal} module defines the following functions: - -\begin{funcdesc}{alarm}{time} - If \var{time} is non-zero, this function requests that a - \constant{SIGALRM} signal be sent to the process in \var{time} seconds. - Any previously scheduled alarm is canceled (only one alarm can - be scheduled at any time). The returned value is then the number of - seconds before any previously set alarm was to have been delivered. - If \var{time} is zero, no alarm is scheduled, and any scheduled - alarm is canceled. If the return value - is zero, no alarm is currently scheduled. (See the \UNIX{} man page - \manpage{alarm}{2}.) - Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{getsignal}{signalnum} - Return the current signal handler for the signal \var{signalnum}. - The returned value may be a callable Python object, or one of the - special values \constant{signal.SIG_IGN}, \constant{signal.SIG_DFL} or - \constant{None}. Here, \constant{signal.SIG_IGN} means that the - signal was previously ignored, \constant{signal.SIG_DFL} means that the - default way of handling the signal was previously in use, and - \code{None} means that the previous signal handler was not installed - from Python. -\end{funcdesc} - -\begin{funcdesc}{pause}{} - Cause the process to sleep until a signal is received; the - appropriate handler will then be called. Returns nothing. Not on - Windows. (See the \UNIX{} man page \manpage{signal}{2}.) -\end{funcdesc} - -\begin{funcdesc}{signal}{signalnum, handler} - Set the handler for signal \var{signalnum} to the function - \var{handler}. \var{handler} can be a callable Python object - taking two arguments (see below), or - one of the special values \constant{signal.SIG_IGN} or - \constant{signal.SIG_DFL}. The previous signal handler will be returned - (see the description of \function{getsignal()} above). (See the - \UNIX{} man page \manpage{signal}{2}.) - - When threads are enabled, this function can only be called from the - main thread; attempting to call it from other threads will cause a - \exception{ValueError} exception to be raised. - - The \var{handler} is called with two arguments: the signal number - and the current stack frame (\code{None} or a frame object; - for a description of frame objects, see the reference manual section - on the standard type hierarchy or see the attribute descriptions in - the \refmodule{inspect} module). -\end{funcdesc} - -\subsection{Example} -\nodename{Signal Example} - -Here is a minimal example program. It uses the \function{alarm()} -function to limit the time spent waiting to open a file; this is -useful if the file is for a serial device that may not be turned on, -which would normally cause the \function{os.open()} to hang -indefinitely. The solution is to set a 5-second alarm before opening -the file; if the operation takes too long, the alarm signal will be -sent, and the handler raises an exception. - -\begin{verbatim} -import signal, os - -def handler(signum, frame): - print 'Signal handler called with signal', signum - raise IOError, "Couldn't open device!" - -# Set the signal handler and a 5-second alarm -signal.signal(signal.SIGALRM, handler) -signal.alarm(5) - -# This open() may hang indefinitely -fd = os.open('/dev/ttyS0', os.O_RDWR) - -signal.alarm(0) # Disable the alarm -\end{verbatim} diff --git a/Doc/lib/libsimplehttp.tex b/Doc/lib/libsimplehttp.tex deleted file mode 100644 index efb40ec..0000000 --- a/Doc/lib/libsimplehttp.tex +++ /dev/null @@ -1,86 +0,0 @@ -\section{\module{SimpleHTTPServer} --- - Simple HTTP request handler} - -\declaremodule{standard}{SimpleHTTPServer} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{This module provides a basic request handler for HTTP - servers.} - - -The \module{SimpleHTTPServer} module defines a request-handler class, -interface-compatible with \class{BaseHTTPServer.BaseHTTPRequestHandler}, -that serves files only from a base directory. - -The \module{SimpleHTTPServer} module defines the following class: - -\begin{classdesc}{SimpleHTTPRequestHandler}{request, client_address, server} -This class is used to serve files from the current directory and below, -directly mapping the directory structure to HTTP requests. - -A lot of the work, such as parsing the request, is done by the base -class \class{BaseHTTPServer.BaseHTTPRequestHandler}. This class -implements the \function{do_GET()} and \function{do_HEAD()} functions. -\end{classdesc} - -The \class{SimpleHTTPRequestHandler} defines the following member -variables: - -\begin{memberdesc}{server_version} -This will be \code{"SimpleHTTP/" + __version__}, where \code{__version__} -is defined in the module. -\end{memberdesc} - -\begin{memberdesc}{extensions_map} -A dictionary mapping suffixes into MIME types. The default is signified -by an empty string, and is considered to be \code{application/octet-stream}. -The mapping is used case-insensitively, and so should contain only -lower-cased keys. -\end{memberdesc} - -The \class{SimpleHTTPRequestHandler} defines the following methods: - -\begin{methoddesc}{do_HEAD}{} -This method serves the \code{'HEAD'} request type: it sends the -headers it would send for the equivalent \code{GET} request. See the -\method{do_GET()} method for a more complete explanation of the possible -headers. -\end{methoddesc} - -\begin{methoddesc}{do_GET}{} -The request is mapped to a local file by interpreting the request as -a path relative to the current working directory. - -If the request was mapped to a directory, the directory is checked for -a file named \code{index.html} or \code{index.htm} (in that order). -If found, the file's contents are returned; otherwise a directory -listing is generated by calling the \method{list_directory()} method. -This method uses \function{os.listdir()} to scan the directory, and -returns a \code{404} error response if the \function{listdir()} fails. - -If the request was mapped to a file, it is opened and the contents are -returned. Any \exception{IOError} exception in opening the requested -file is mapped to a \code{404}, \code{'File not found'} -error. Otherwise, the content type is guessed by calling the -\method{guess_type()} method, which in turn uses the -\var{extensions_map} variable. - -A \code{'Content-type:'} header with the guessed content type is -output, followed by a \code{'Content-Length:'} header with the file's -size and a \code{'Last-Modified:'} header with the file's modification -time. - -Then follows a blank line signifying the end of the headers, -and then the contents of the file are output. If the file's MIME type -starts with \code{text/} the file is opened in text mode; otherwise -binary mode is used. - -For example usage, see the implementation of the \function{test()} -function. -\versionadded[The \code{'Last-Modified'} header]{2.5} -\end{methoddesc} - - -\begin{seealso} - \seemodule{BaseHTTPServer}{Base class implementation for Web server - and request handler.} -\end{seealso} diff --git a/Doc/lib/libsimplexmlrpc.tex b/Doc/lib/libsimplexmlrpc.tex deleted file mode 100644 index 235905e..0000000 --- a/Doc/lib/libsimplexmlrpc.tex +++ /dev/null @@ -1,235 +0,0 @@ -\section{\module{SimpleXMLRPCServer} --- - Basic XML-RPC server} - -\declaremodule{standard}{SimpleXMLRPCServer} -\modulesynopsis{Basic XML-RPC server implementation.} -\moduleauthor{Brian Quinlan}{brianq@activestate.com} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -\versionadded{2.2} - -The \module{SimpleXMLRPCServer} module provides a basic server -framework for XML-RPC servers written in Python. Servers can either -be free standing, using \class{SimpleXMLRPCServer}, or embedded in a -CGI environment, using \class{CGIXMLRPCRequestHandler}. - -\begin{classdesc}{SimpleXMLRPCServer}{addr\optional{, - requestHandler\optional{, - logRequests\optional{, - allow_none\optional{, - encoding}}}}} - - Create a new server instance. This class - provides methods for registration of functions that can be called by - the XML-RPC protocol. The \var{requestHandler} parameter - should be a factory for request handler instances; it defaults to - \class{SimpleXMLRPCRequestHandler}. The \var{addr} and - \var{requestHandler} parameters are passed to the - \class{\refmodule{SocketServer}.TCPServer} constructor. If - \var{logRequests} is true (the default), requests will be logged; - setting this parameter to false will turn off logging. - The \var{allow_none} and \var{encoding} parameters are passed on to - \module{xmlrpclib} and control the XML-RPC responses that will be returned - from the server. The \var{bind_and_activate} parameter controls whether - \method{server_bind()} and \method{server_activate()} are called immediately - by the constructor; it defaults to true. Setting it to false allows code to - manipulate the \var{allow_reuse_address} class variable before the address - is bound. - \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5} - \versionchanged[The \var{bind_and_activate} parameter was added]{2.6} -\end{classdesc} - -\begin{classdesc}{CGIXMLRPCRequestHandler}{\optional{allow_none\optional{, encoding}}} - Create a new instance to handle XML-RPC requests in a CGI - environment. - The \var{allow_none} and \var{encoding} parameters are passed on to - \module{xmlrpclib} and control the XML-RPC responses that will be returned - from the server. - \versionadded{2.3} - \versionchanged[The \var{allow_none} and \var{encoding} parameters were added]{2.5} -\end{classdesc} - -\begin{classdesc}{SimpleXMLRPCRequestHandler}{} - Create a new request handler instance. This request handler - supports \code{POST} requests and modifies logging so that the - \var{logRequests} parameter to the \class{SimpleXMLRPCServer} - constructor parameter is honored. -\end{classdesc} - - -\subsection{SimpleXMLRPCServer Objects \label{simple-xmlrpc-servers}} - -The \class{SimpleXMLRPCServer} class is based on -\class{SocketServer.TCPServer} and provides a means of creating -simple, stand alone XML-RPC servers. - -\begin{methoddesc}[SimpleXMLRPCServer]{register_function}{function\optional{, - name}} - Register a function that can respond to XML-RPC requests. If - \var{name} is given, it will be the method name associated with - \var{function}, otherwise \code{\var{function}.__name__} will be - used. \var{name} can be either a normal or Unicode string, and may - contain characters not legal in Python identifiers, including the - period character. -\end{methoddesc} - -\begin{methoddesc}[SimpleXMLRPCServer]{register_instance}{instance\optional{, - allow_dotted_names}} - Register an object which is used to expose method names which have - not been registered using \method{register_function()}. If - \var{instance} contains a \method{_dispatch()} method, it is called - with the requested method name and the parameters from the request. Its - API is \code{def \method{_dispatch}(self, method, params)} (note that - \var{params} does not represent a variable argument list). If it calls an - underlying function to perform its task, that function is called as - \code{func(*params)}, expanding the parameter list. - The return value from \method{_dispatch()} is returned to the client as - the result. If - \var{instance} does not have a \method{_dispatch()} method, it is - searched for an attribute matching the name of the requested method. - - If the optional \var{allow_dotted_names} argument is true and the - instance does not have a \method{_dispatch()} method, then - if the requested method name contains periods, each component of the - method name is searched for individually, with the effect that a - simple hierarchical search is performed. The value found from this - search is then called with the parameters from the request, and the - return value is passed back to the client. - - \begin{notice}[warning] - Enabling the \var{allow_dotted_names} option allows intruders to access - your module's global variables and may allow intruders to execute - arbitrary code on your machine. Only use this option on a secure, - closed network. - \end{notice} - - \versionchanged[\var{allow_dotted_names} was added to plug a security hole; - prior versions are insecure]{2.3.5, 2.4.1} - -\end{methoddesc} - -\begin{methoddesc}[SimpleXMLRPCServer]{register_introspection_functions}{} - Registers the XML-RPC introspection functions \code{system.listMethods}, - \code{system.methodHelp} and \code{system.methodSignature}. - \versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[SimpleXMLRPCServer]{register_multicall_functions}{} - Registers the XML-RPC multicall function system.multicall. -\end{methoddesc} - -\begin{memberdesc}[SimpleXMLRPCServer]{rpc_paths} -An attribute value that must be a tuple listing valid path portions of -the URL for receiving XML-RPC requests. Requests posted to other -paths will result in a 404 ``no such page'' HTTP error. If this -tuple is empty, all paths will be considered valid. -The default value is \code{('/', '/RPC2')}. - \versionadded{2.5} -\end{memberdesc} - -Example: - -\begin{verbatim} -from SimpleXMLRPCServer import SimpleXMLRPCServer - -# Create server -server = SimpleXMLRPCServer(("localhost", 8000)) -server.register_introspection_functions() - -# Register pow() function; this will use the value of -# pow.__name__ as the name, which is just 'pow'. -server.register_function(pow) - -# Register a function under a different name -def adder_function(x,y): - return x + y -server.register_function(adder_function, 'add') - -# Register an instance; all the methods of the instance are -# published as XML-RPC methods (in this case, just 'div'). -class MyFuncs: - def div(self, x, y): - return x // y - -server.register_instance(MyFuncs()) - -# Run the server's main loop -server.serve_forever() -\end{verbatim} - -The following client code will call the methods made available by -the preceding server: - -\begin{verbatim} -import xmlrpclib - -s = xmlrpclib.Server('http://localhost:8000') -print s.pow(2,3) # Returns 2**3 = 8 -print s.add(2,3) # Returns 5 -print s.div(5,2) # Returns 5//2 = 2 - -# Print list of available methods -print s.system.listMethods() -\end{verbatim} - - -\subsection{CGIXMLRPCRequestHandler} - -The \class{CGIXMLRPCRequestHandler} class can be used to -handle XML-RPC requests sent to Python CGI scripts. - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_function}{function\optional{, name}} -Register a function that can respond to XML-RPC requests. If -\var{name} is given, it will be the method name associated with -function, otherwise \var{function.__name__} will be used. \var{name} -can be either a normal or Unicode string, and may contain -characters not legal in Python identifiers, including the period -character. -\end{methoddesc} - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_instance}{instance} -Register an object which is used to expose method names -which have not been registered using \method{register_function()}. If -instance contains a \method{_dispatch()} method, it is called with the -requested method name and the parameters from the -request; the return value is returned to the client as the result. -If instance does not have a \method{_dispatch()} method, it is searched -for an attribute matching the name of the requested method; if -the requested method name contains periods, each -component of the method name is searched for individually, -with the effect that a simple hierarchical search is performed. -The value found from this search is then called with the -parameters from the request, and the return value is passed -back to the client. -\end{methoddesc} - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_introspection_functions}{} -Register the XML-RPC introspection functions -\code{system.listMethods}, \code{system.methodHelp} and -\code{system.methodSignature}. -\end{methoddesc} - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{register_multicall_functions}{} -Register the XML-RPC multicall function \code{system.multicall}. -\end{methoddesc} - -\begin{methoddesc}[CGIXMLRPCRequestHandler]{handle_request}{\optional{request_text = None}} -Handle a XML-RPC request. If \var{request_text} is given, it -should be the POST data provided by the HTTP server, -otherwise the contents of stdin will be used. -\end{methoddesc} - -Example: - -\begin{verbatim} -class MyFuncs: - def div(self, x, y) : return x // y - - -handler = CGIXMLRPCRequestHandler() -handler.register_function(pow) -handler.register_function(lambda x,y: x+y, 'add') -handler.register_introspection_functions() -handler.register_instance(MyFuncs()) -handler.handle_request() -\end{verbatim} diff --git a/Doc/lib/libsite.tex b/Doc/lib/libsite.tex deleted file mode 100644 index 11858d1..0000000 --- a/Doc/lib/libsite.tex +++ /dev/null @@ -1,93 +0,0 @@ -\section{\module{site} --- - Site-specific configuration hook} - -\declaremodule{standard}{site} -\modulesynopsis{A standard way to reference site-specific modules.} - - -\strong{This module is automatically imported during initialization.} -The automatic import can be suppressed using the interpreter's -\programopt{-S} option. - -Importing this module will append site-specific paths to the module -search path. -\indexiii{module}{search}{path} - -It starts by constructing up to four directories from a head and a -tail part. For the head part, it uses \code{sys.prefix} and -\code{sys.exec_prefix}; empty heads are skipped. For -the tail part, it uses the empty string and then -\file{lib/site-packages} (on Windows) or -\file{lib/python\shortversion/site-packages} and then -\file{lib/site-python} (on \UNIX{} and Macintosh). For each of the -distinct head-tail combinations, it sees if it refers to an existing -directory, and if so, adds it to \code{sys.path} and also inspects -the newly added path for configuration files. -\indexii{site-python}{directory} -\indexii{site-packages}{directory} - -A path configuration file is a file whose name has the form -\file{\var{package}.pth} and exists in one of the four directories -mentioned above; its contents are additional items (one per line) to -be added to \code{sys.path}. Non-existing items are never added to -\code{sys.path}, but no check is made that the item refers to a -directory (rather than a file). No item is added to \code{sys.path} -more than once. Blank lines and lines beginning with \code{\#} are -skipped. Lines starting with \code{import} (followed by space or tab) -are executed. - -\versionchanged[A space or tab is now required after the import -keyword]{2.6} - -\index{package} -\indexiii{path}{configuration}{file} - -For example, suppose \code{sys.prefix} and \code{sys.exec_prefix} are -set to \file{/usr/local}. The Python \version\ library is then -installed in \file{/usr/local/lib/python\shortversion} (where only the -first three characters of \code{sys.version} are used to form the -installation path name). Suppose this has a subdirectory -\file{/usr/local/lib/python\shortversion/site-packages} with three -subsubdirectories, \file{foo}, \file{bar} and \file{spam}, and two -path configuration files, \file{foo.pth} and \file{bar.pth}. Assume -\file{foo.pth} contains the following: - -\begin{verbatim} -# foo package configuration - -foo -bar -bletch -\end{verbatim} - -and \file{bar.pth} contains: - -\begin{verbatim} -# bar package configuration - -bar -\end{verbatim} - -Then the following directories are added to \code{sys.path}, in this -order: - -\begin{verbatim} -/usr/local/lib/python2.3/site-packages/bar -/usr/local/lib/python2.3/site-packages/foo -\end{verbatim} - -Note that \file{bletch} is omitted because it doesn't exist; the -\file{bar} directory precedes the \file{foo} directory because -\file{bar.pth} comes alphabetically before \file{foo.pth}; and -\file{spam} is omitted because it is not mentioned in either path -configuration file. - -After these path manipulations, an attempt is made to import a module -named \module{sitecustomize}\refmodindex{sitecustomize}, which can -perform arbitrary site-specific customizations. If this import fails -with an \exception{ImportError} exception, it is silently ignored. - -Note that for some non-\UNIX{} systems, \code{sys.prefix} and -\code{sys.exec_prefix} are empty, and the path manipulations are -skipped; however the import of -\module{sitecustomize}\refmodindex{sitecustomize} is still attempted. diff --git a/Doc/lib/libsmtpd.tex b/Doc/lib/libsmtpd.tex deleted file mode 100644 index 657050d..0000000 --- a/Doc/lib/libsmtpd.tex +++ /dev/null @@ -1,63 +0,0 @@ -\section{\module{smtpd} --- - SMTP Server} - -\declaremodule{standard}{smtpd} - -\moduleauthor{Barry Warsaw}{barry@zope.com} -\sectionauthor{Moshe Zadka}{moshez@moshez.org} - -\modulesynopsis{Implement a flexible SMTP server} - -This module offers several classes to implement SMTP servers. One is -a generic do-nothing implementation, which can be overridden, while -the other two offer specific mail-sending strategies. - - -\subsection{SMTPServer Objects} - -\begin{classdesc}{SMTPServer}{localaddr, remoteaddr} -Create a new \class{SMTPServer} object, which binds to local address -\var{localaddr}. It will treat \var{remoteaddr} as an upstream SMTP -relayer. It inherits from \class{asyncore.dispatcher}, and so will -insert itself into \refmodule{asyncore}'s event loop on instantiation. -\end{classdesc} - -\begin{methoddesc}[SMTPServer]{process_message}{peer, mailfrom, rcpttos, data} -Raise \exception{NotImplementedError} exception. Override this in -subclasses to do something useful with this message. Whatever was -passed in the constructor as \var{remoteaddr} will be available as the -\member{_remoteaddr} attribute. \var{peer} is the remote host's address, -\var{mailfrom} is the envelope originator, \var{rcpttos} are the -envelope recipients and \var{data} is a string containing the contents -of the e-mail (which should be in \rfc{2822} format). -\end{methoddesc} - - -\subsection{DebuggingServer Objects} - -\begin{classdesc}{DebuggingServer}{localaddr, remoteaddr} -Create a new debugging server. Arguments are as per -\class{SMTPServer}. Messages will be discarded, and printed on -stdout. -\end{classdesc} - - -\subsection{PureProxy Objects} - -\begin{classdesc}{PureProxy}{localaddr, remoteaddr} -Create a new pure proxy server. Arguments are as per \class{SMTPServer}. -Everything will be relayed to \var{remoteaddr}. Note that running -this has a good chance to make you into an open relay, so please be -careful. -\end{classdesc} - - -\subsection{MailmanProxy Objects} - -\begin{classdesc}{MailmanProxy}{localaddr, remoteaddr} -Create a new pure proxy server. Arguments are as per -\class{SMTPServer}. Everything will be relayed to \var{remoteaddr}, -unless local mailman configurations knows about an address, in which -case it will be handled via mailman. Note that running this has a -good chance to make you into an open relay, so please be careful. -\end{classdesc} diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex deleted file mode 100644 index 7786102..0000000 --- a/Doc/lib/libsmtplib.tex +++ /dev/null @@ -1,344 +0,0 @@ -\section{\module{smtplib} --- - SMTP protocol client} - -\declaremodule{standard}{smtplib} -\modulesynopsis{SMTP protocol client (requires sockets).} -\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} - -\indexii{SMTP}{protocol} -\index{Simple Mail Transfer Protocol} - -The \module{smtplib} module defines an SMTP client session object that -can be used to send mail to any Internet machine with an SMTP or ESMTP -listener daemon. For details of SMTP and ESMTP operation, consult -\rfc{821} (\citetitle{Simple Mail Transfer Protocol}) and \rfc{1869} -(\citetitle{SMTP Service Extensions}). - -\begin{classdesc}{SMTP}{\optional{host\optional{, port\optional{, - local_hostname\optional{, timeout}}}}} -A \class{SMTP} instance encapsulates an SMTP connection. It has -methods that support a full repertoire of SMTP and ESMTP -operations. If the optional host and port parameters are given, the -SMTP \method{connect()} method is called with those parameters during -initialization. An \exception{SMTPConnectError} is raised if the -specified host doesn't respond correctly. -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if not specified, or passed as None, the global -default timeout setting will be used). - -For normal use, you should only require the initialization/connect, -\method{sendmail()}, and \method{quit()} methods. An example is -included below. - -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - -\begin{classdesc}{SMTP_SSL}{\optional{host\optional{, port\optional{, - local_hostname\optional{, - keyfile\optional{, - certfile\optional{, timeout}}}}}}} -A \class{SMTP_SSL} instance behaves exactly the same as instances of \class{SMTP}. -\class{SMTP_SSL} should be used for situations where SSL is required from -the beginning of the connection and using \method{starttls()} is not appropriate. -If \var{host} is not specified, the local host is used. If \var{port} is -omitted, the standard SMTP-over-SSL port (465) is used. \var{keyfile} and \var{certfile} -are also optional, and can contain a PEM formatted private key and -certificate chain file for the SSL connection. -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if not specified, or passed as None, the global -default timeout setting will be used). - -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - -\begin{classdesc}{LMTP}{\optional{host\optional{, port\optional{, - local_hostname}}}} - -The LMTP protocol, which is very similar to ESMTP, is heavily based -on the standard SMTP client. It's common to use Unix sockets for LMTP, -so our connect() method must support that as well as a regular -host:port server. To specify a Unix socket, you must use an absolute -path for \var{host}, starting with a '/'. - -Authentication is supported, using the regular SMTP mechanism. When -using a Unix socket, LMTP generally don't support or require any -authentication, but your mileage might vary. - -\versionadded{2.6} - -\end{classdesc} - -A nice selection of exceptions is defined as well: - -\begin{excdesc}{SMTPException} - Base exception class for all exceptions raised by this module. -\end{excdesc} - -\begin{excdesc}{SMTPServerDisconnected} - This exception is raised when the server unexpectedly disconnects, - or when an attempt is made to use the \class{SMTP} instance before - connecting it to a server. -\end{excdesc} - -\begin{excdesc}{SMTPResponseException} - Base class for all exceptions that include an SMTP error code. - These exceptions are generated in some instances when the SMTP - server returns an error code. The error code is stored in the - \member{smtp_code} attribute of the error, and the - \member{smtp_error} attribute is set to the error message. -\end{excdesc} - -\begin{excdesc}{SMTPSenderRefused} - Sender address refused. In addition to the attributes set by on all - \exception{SMTPResponseException} exceptions, this sets `sender' to - the string that the SMTP server refused. -\end{excdesc} - -\begin{excdesc}{SMTPRecipientsRefused} - All recipient addresses refused. The errors for each recipient are - accessible through the attribute \member{recipients}, which is a - dictionary of exactly the same sort as \method{SMTP.sendmail()} - returns. -\end{excdesc} - -\begin{excdesc}{SMTPDataError} - The SMTP server refused to accept the message data. -\end{excdesc} - -\begin{excdesc}{SMTPConnectError} - Error occurred during establishment of a connection with the server. -\end{excdesc} - -\begin{excdesc}{SMTPHeloError} - The server refused our \samp{HELO} message. -\end{excdesc} - -\begin{excdesc}{SMTPAuthenticationError} - SMTP authentication went wrong. Most probably the server didn't accept - the username/password combination provided. -\end{excdesc} - -\begin{seealso} - \seerfc{821}{Simple Mail Transfer Protocol}{Protocol definition for - SMTP. This document covers the model, operating procedure, - and protocol details for SMTP.} - \seerfc{1869}{SMTP Service Extensions}{Definition of the ESMTP - extensions for SMTP. This describes a framework for - extending SMTP with new commands, supporting dynamic - discovery of the commands provided by the server, and - defines a few additional commands.} -\end{seealso} - - -\subsection{SMTP Objects \label{SMTP-objects}} - -An \class{SMTP} instance has the following methods: - -\begin{methoddesc}[SMTP]{set_debuglevel}{level} -Set the debug output level. A true value for \var{level} results in -debug messages for connection and for all messages sent to and -received from the server. -\end{methoddesc} - -\begin{methoddesc}[SMTP]{connect}{\optional{host\optional{, port}}} -Connect to a host on a given port. The defaults are to connect to the -local host at the standard SMTP port (25). -If the hostname ends with a colon (\character{:}) followed by a -number, that suffix will be stripped off and the number interpreted as -the port number to use. -This method is automatically invoked by the constructor if a -host is specified during instantiation. -\end{methoddesc} - -\begin{methoddesc}[SMTP]{docmd}{cmd, \optional{, argstring}} -Send a command \var{cmd} to the server. The optional argument -\var{argstring} is simply concatenated to the command, separated by a -space. - -This returns a 2-tuple composed of a numeric response code and the -actual response line (multiline responses are joined into one long -line.) - -In normal operation it should not be necessary to call this method -explicitly. It is used to implement other methods and may be useful -for testing private extensions. - -If the connection to the server is lost while waiting for the reply, -\exception{SMTPServerDisconnected} will be raised. -\end{methoddesc} - -\begin{methoddesc}[SMTP]{helo}{\optional{hostname}} -Identify yourself to the SMTP server using \samp{HELO}. The hostname -argument defaults to the fully qualified domain name of the local -host. - -In normal operation it should not be necessary to call this method -explicitly. It will be implicitly called by the \method{sendmail()} -when necessary. -\end{methoddesc} - -\begin{methoddesc}[SMTP]{ehlo}{\optional{hostname}} -Identify yourself to an ESMTP server using \samp{EHLO}. The hostname -argument defaults to the fully qualified domain name of the local -host. Examine the response for ESMTP option and store them for use by -\method{has_extn()}. - -Unless you wish to use \method{has_extn()} before sending -mail, it should not be necessary to call this method explicitly. It -will be implicitly called by \method{sendmail()} when necessary. -\end{methoddesc} - -\begin{methoddesc}[SMTP]{has_extn}{name} -Return \constant{True} if \var{name} is in the set of SMTP service -extensions returned by the server, \constant{False} otherwise. -Case is ignored. -\end{methoddesc} - -\begin{methoddesc}[SMTP]{verify}{address} -Check the validity of an address on this server using SMTP \samp{VRFY}. -Returns a tuple consisting of code 250 and a full \rfc{822} address -(including human name) if the user address is valid. Otherwise returns -an SMTP error code of 400 or greater and an error string. - -\note{Many sites disable SMTP \samp{VRFY} in order to foil spammers.} -\end{methoddesc} - -\begin{methoddesc}[SMTP]{login}{user, password} -Log in on an SMTP server that requires authentication. -The arguments are the username and the password to authenticate with. -If there has been no previous \samp{EHLO} or \samp{HELO} command this -session, this method tries ESMTP \samp{EHLO} first. -This method will return normally if the authentication was successful, -or may raise the following exceptions: - -\begin{description} - \item[\exception{SMTPHeloError}] - The server didn't reply properly to the \samp{HELO} greeting. - \item[\exception{SMTPAuthenticationError}] - The server didn't accept the username/password combination. - \item[\exception{SMTPException}] - No suitable authentication method was found. -\end{description} -\end{methoddesc} - -\begin{methoddesc}[SMTP]{starttls}{\optional{keyfile\optional{, certfile}}} -Put the SMTP connection in TLS (Transport Layer Security) mode. All -SMTP commands that follow will be encrypted. You should then call -\method{ehlo()} again. - -If \var{keyfile} and \var{certfile} are provided, these are passed to -the \refmodule{socket} module's \function{ssl()} function. -\end{methoddesc} - -\begin{methoddesc}[SMTP]{sendmail}{from_addr, to_addrs, msg\optional{, - mail_options, rcpt_options}} -Send mail. The required arguments are an \rfc{822} from-address -string, a list of \rfc{822} to-address strings (a bare string will be -treated as a list with 1 address), and a message string. The caller -may pass a list of ESMTP options (such as \samp{8bitmime}) to be used -in \samp{MAIL FROM} commands as \var{mail_options}. ESMTP options -(such as \samp{DSN} commands) that should be used with all \samp{RCPT} -commands can be passed as \var{rcpt_options}. (If you 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.) - -\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 -to it (if the option is in the feature set the server advertises). If -\samp{EHLO} fails, \samp{HELO} will be tried and ESMTP options -suppressed. - -This method will return normally if the mail is accepted for at least -one recipient. Otherwise it will throw an exception. That is, if this -method does not throw an exception, then someone should get your mail. -If this method does not throw an exception, it returns a dictionary, -with one entry for each recipient that was refused. Each entry -contains a tuple of the SMTP error code and the accompanying error -message sent by the server. - -This method may raise the following exceptions: - -\begin{description} -\item[\exception{SMTPRecipientsRefused}] -All recipients were refused. Nobody got the mail. The -\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 \samp{HELO} greeting. - -\item[\exception{SMTPSenderRefused}] -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{description} - -Unless otherwise noted, the connection will be open even after -an exception is raised. - -\end{methoddesc} - -\begin{methoddesc}[SMTP]{quit}{} -Terminate the SMTP session and close the connection. -\end{methoddesc} - -Low-level methods corresponding to the standard SMTP/ESMTP commands -\samp{HELP}, \samp{RSET}, \samp{NOOP}, \samp{MAIL}, \samp{RCPT}, and -\samp{DATA} are also supported. Normally these do not need to be -called directly, so they are not documented here. For details, -consult the module code. - - -\subsection{SMTP Example \label{SMTP-example}} - -This example prompts the user for addresses needed in the message -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 smtplib - -def raw_input(prompt): - import sys - sys.stdout.write(prompt) - sys.stdout.flush() - return sys.stdin.readline() - -def prompt(prompt): - return raw_input(prompt).strip() - -fromaddr = prompt("From: ") -toaddrs = prompt("To: ").split() -print "Enter message, end with ^D (Unix) or ^Z (Windows):" - -# Add the From: and To: headers at the start! -msg = ("From: %s\r\nTo: %s\r\n\r\n" - % (fromaddr, ", ".join(toaddrs))) -while 1: - try: - line = raw_input() - except EOFError: - break - if not line: - break - msg = msg + line - -print "Message length is " + repr(len(msg)) - -server = smtplib.SMTP('localhost') -server.set_debuglevel(1) -server.sendmail(fromaddr, toaddrs, msg) -server.quit() -\end{verbatim} diff --git a/Doc/lib/libsndhdr.tex b/Doc/lib/libsndhdr.tex deleted file mode 100644 index a7f8c6e..0000000 --- a/Doc/lib/libsndhdr.tex +++ /dev/null @@ -1,41 +0,0 @@ -\section{\module{sndhdr} --- - Determine type of sound file} - -\declaremodule{standard}{sndhdr} -\modulesynopsis{Determine type of a sound file.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -% Based on comments in the module source file. - - -The \module{sndhdr} provides utility functions which attempt to -determine the type of sound data which is in a file. When these -functions are able to determine what type of sound data is stored in a -file, they return a tuple \code{(\var{type}, \var{sampling_rate}, -\var{channels}, \var{frames}, \var{bits_per_sample})}. The value for -\var{type} indicates the data type and will be one of the strings -\code{'aifc'}, \code{'aiff'}, \code{'au'}, \code{'hcom'}, -\code{'sndr'}, \code{'sndt'}, \code{'voc'}, \code{'wav'}, -\code{'8svx'}, \code{'sb'}, \code{'ub'}, or \code{'ul'}. The -\var{sampling_rate} will be either the actual value or \code{0} if -unknown or difficult to decode. Similarly, \var{channels} will be -either the number of channels or \code{0} if it cannot be determined -or if the value is difficult to decode. The value for \var{frames} -will be either the number of frames or \code{-1}. The last item in -the tuple, \var{bits_per_sample}, will either be the sample size in -bits or \code{'A'} for A-LAW\index{A-LAW} or \code{'U'} for -u-LAW\index{u-LAW}. - - -\begin{funcdesc}{what}{filename} - Determines the type of sound data stored in the file \var{filename} - using \function{whathdr()}. If it succeeds, returns a tuple as - described above, otherwise \code{None} is returned. -\end{funcdesc} - - -\begin{funcdesc}{whathdr}{filename} - Determines the type of sound data stored in a file based on the file - header. The name of the file is given by \var{filename}. This - function returns a tuple as described above on success, or - \code{None}. -\end{funcdesc} diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex deleted file mode 100644 index e3fce23..0000000 --- a/Doc/lib/libsocket.tex +++ /dev/null @@ -1,921 +0,0 @@ -\section{\module{socket} --- - Low-level networking interface} - -\declaremodule{builtin}{socket} -\modulesynopsis{Low-level networking interface.} - - -This module provides access to the BSD \emph{socket} interface. -It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS, -OS/2, and probably additional platforms. \note{Some behavior may be -platform dependent, since calls are made to the operating system socket APIs.} - -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 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. -For IPv6-ready APIs, readers may want to refer to \rfc{2553} titled -\citetitle{Basic Socket Interface Extensions for IPv6}. - -The Python interface is a straightforward transliteration of the -\UNIX{} system call and library interface for sockets to Python's -object-oriented style: the \function{socket()} function returns a -\dfn{socket object}\obindex{socket} whose methods implement the -various socket system calls. Parameter types are somewhat -higher-level than in the C interface: as with \method{read()} and -\method{write()} operations on Python files, buffer allocation on -receive operations is automatic, and buffer length is implicit on send -operations. - -Socket addresses are represented as follows: -A single string is used for the \constant{AF_UNIX} address family. -A pair \code{(\var{host}, \var{port})} is used for the -\constant{AF_INET} address family, where \var{host} is a string -representing either a hostname in Internet domain notation like -\code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'}, -and \var{port} is an integral port number. -For \constant{AF_INET6} address family, a four-tuple -\code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is -used, where \var{flowinfo} and \var{scopeid} represents -\code{sin6_flowinfo} and \code{sin6_scope_id} member in -\constant{struct sockaddr_in6} in C. -For \module{socket} module methods, \var{flowinfo} and \var{scopeid} -can be omitted just for backward compatibility. Note, however, -omission of \var{scopeid} can cause problems in manipulating scoped -IPv6 addresses. Other address families are currently not supported. -The address format required by a particular socket object is -automatically selected based on the address family specified when the -socket object was created. - -For IPv4 addresses, two special forms are accepted instead of a host -address: the empty string represents \constant{INADDR_ANY}, and the string -\code{'<broadcast>'} represents \constant{INADDR_BROADCAST}. -The behavior is not available for IPv6 for backward compatibility, -therefore, you may want to avoid these if you intend to support IPv6 with -your Python programs. - -If you use a hostname in the \var{host} portion of IPv4/v6 socket -address, the program may show a nondeterministic behavior, as Python -uses the first address returned from the DNS resolution. The socket -address will be resolved differently into an actual IPv4/v6 address, -depending on the results from DNS resolution and/or the host -configuration. For deterministic behavior use a numeric address in -\var{host} portion. - -\versionadded[AF_NETLINK sockets are represented as -pairs \code{\var{pid}, \var{groups}}]{2.5} - -All errors raise exceptions. The normal exceptions for invalid -argument types and out-of-memory conditions can be raised; errors -related to socket or address semantics raise the error -\exception{socket.error}. - -Non-blocking mode is supported through -\method{setblocking()}. A generalization of this based on timeouts -is supported through \method{settimeout()}. - -The module \module{socket} exports the following constants and functions: - - -\begin{excdesc}{error} -This exception is raised for socket-related errors. -The accompanying value is either a string telling what went wrong or a -pair \code{(\var{errno}, \var{string})} -representing an error returned by a system -call, similar to the value accompanying \exception{os.error}. -See the module \refmodule{errno}\refbimodindex{errno}, which contains -names for the error codes defined by the underlying operating system. -\end{excdesc} - -\begin{excdesc}{herror} -This exception is raised for address-related errors, i.e. for -functions that use \var{h_errno} in the C API, including -\function{gethostbyname_ex()} and \function{gethostbyaddr()}. - -The accompanying value is a pair \code{(\var{h_errno}, \var{string})} -representing an error returned by a library call. \var{string} -represents the description of \var{h_errno}, as returned by -the \cfunction{hstrerror()} C function. -\end{excdesc} - -\begin{excdesc}{gaierror} -This exception is raised for address-related errors, for -\function{getaddrinfo()} and \function{getnameinfo()}. -The accompanying value is a pair \code{(\var{error}, \var{string})} -representing an error returned by a library call. -\var{string} represents the description of \var{error}, as returned -by the \cfunction{gai_strerror()} C function. -The \var{error} value will match one of the \constant{EAI_*} constants -defined in this module. -\end{excdesc} - -\begin{excdesc}{timeout} -This exception is raised when a timeout occurs on a socket which has -had timeouts enabled via a prior call to \method{settimeout()}. The -accompanying value is a string whose value is currently always ``timed -out''. -\versionadded{2.3} -\end{excdesc} - -\begin{datadesc}{AF_UNIX} -\dataline{AF_INET} -\dataline{AF_INET6} -These constants represent the address (and protocol) families, -used for the first argument to \function{socket()}. If the -\constant{AF_UNIX} constant is not defined then this protocol is -unsupported. -\end{datadesc} - -\begin{datadesc}{SOCK_STREAM} -\dataline{SOCK_DGRAM} -\dataline{SOCK_RAW} -\dataline{SOCK_RDM} -\dataline{SOCK_SEQPACKET} -These constants represent the socket types, -used for the second argument to \function{socket()}. -(Only \constant{SOCK_STREAM} and -\constant{SOCK_DGRAM} appear to be generally useful.) -\end{datadesc} - -\begin{datadesc}{SO_*} -\dataline{SOMAXCONN} -\dataline{MSG_*} -\dataline{SOL_*} -\dataline{IPPROTO_*} -\dataline{IPPORT_*} -\dataline{INADDR_*} -\dataline{IP_*} -\dataline{IPV6_*} -\dataline{EAI_*} -\dataline{AI_*} -\dataline{NI_*} -\dataline{TCP_*} -Many constants of these forms, documented in the \UNIX{} documentation on -sockets and/or the IP protocol, are also defined in the socket module. -They are generally used in arguments to the \method{setsockopt()} and -\method{getsockopt()} methods of socket objects. In most cases, only -those symbols that are defined in the \UNIX{} header files are defined; -for a few symbols, default values are provided. -\end{datadesc} - -\begin{datadesc}{has_ipv6} -This constant contains a boolean value which indicates if IPv6 is -supported on this platform. -\versionadded{2.3} -\end{datadesc} - -\begin{funcdesc}{create_connection}{address\optional{, timeout}} -Connects to the \var{address} received (as usual, a \code{(host, port)} -pair), with an optional timeout for the connection. Specially useful for -higher-level protocols, it is not normally used directly from -application-level code. Passing the optional \var{timeout} parameter -will set the timeout on the socket instance (if it is not given or -\code{None}, the global default timeout setting is used). -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{, - socktype\optional{, proto\optional{, - flags}}}}} -Resolves the \var{host}/\var{port} argument, into a sequence of -5-tuples that contain all the necessary argument for the sockets -manipulation. \var{host} is a domain name, a string representation of -IPv4/v6 address or \code{None}. -\var{port} is a string service name (like \code{'http'}), a numeric -port number or \code{None}. - -The rest of the arguments are optional and must be numeric if -specified. For \var{host} and \var{port}, by passing either an empty -string or \code{None}, you can pass \code{NULL} to the C API. The -\function{getaddrinfo()} function returns a list of 5-tuples with -the following structure: - -\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname}, - \var{sockaddr})} - -\var{family}, \var{socktype}, \var{proto} are all integer and are meant to -be passed to the \function{socket()} function. -\var{canonname} is a string representing the canonical name of the \var{host}. -It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified -for a numeric \var{host}. -\var{sockaddr} is a tuple describing a socket address, as described above. -See the source for the \refmodule{httplib} and other library modules -for a typical usage of the function. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{getfqdn}{\optional{name}} -Return a fully qualified domain name for \var{name}. -If \var{name} is omitted or empty, it is interpreted as the local -host. To find the fully qualified name, the hostname returned by -\function{gethostbyaddr()} is checked, then aliases for the host, if -available. The first name which includes a period is selected. In -case no fully qualified domain name is available, the hostname as -returned by \function{gethostname()} is returned. -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{gethostbyname}{hostname} -Translate a host name to IPv4 address format. The IPv4 address is -returned as a string, such as \code{'100.50.200.5'}. If the host name -is an IPv4 address itself it is returned unchanged. See -\function{gethostbyname_ex()} for a more complete interface. -\function{gethostbyname()} does not support IPv6 name resolution, and -\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support. -\end{funcdesc} - -\begin{funcdesc}{gethostbyname_ex}{hostname} -Translate a host name to IPv4 address format, extended interface. -Return a triple \code{(\var{hostname}, \var{aliaslist}, -\var{ipaddrlist})} where -\var{hostname} is the primary host name responding to the given -\var{ip_address}, \var{aliaslist} is a (possibly empty) list of -alternative host names for the same address, and \var{ipaddrlist} is -a list of IPv4 addresses for the same interface on the same -host (often but not always a single address). -\function{gethostbyname_ex()} does not support IPv6 name resolution, and -\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support. -\end{funcdesc} - -\begin{funcdesc}{gethostname}{} -Return a string containing the hostname of the machine where -the Python interpreter is currently executing. -If you want to know the current machine's IP address, you may want to use -\code{gethostbyname(gethostname())}. -This operation assumes that there is a valid address-to-host mapping for -the host, and the assumption does not always hold. -Note: \function{gethostname()} doesn't always return the fully qualified -domain name; use \code{getfqdn()} -(see above). -\end{funcdesc} - -\begin{funcdesc}{gethostbyaddr}{ip_address} -Return a triple \code{(\var{hostname}, \var{aliaslist}, -\var{ipaddrlist})} where \var{hostname} is the primary host name -responding to the given \var{ip_address}, \var{aliaslist} is a -(possibly empty) list of alternative host names for the same address, -and \var{ipaddrlist} is a list of IPv4/v6 addresses for the same interface -on the same host (most likely containing only a single address). -To find the fully qualified domain name, use the function -\function{getfqdn()}. -\function{gethostbyaddr} supports both IPv4 and IPv6. -\end{funcdesc} - -\begin{funcdesc}{getnameinfo}{sockaddr, flags} -Translate a socket address \var{sockaddr} into a 2-tuple -\code{(\var{host}, \var{port})}. -Depending on the settings of \var{flags}, the result can contain a -fully-qualified domain name or numeric address representation in -\var{host}. Similarly, \var{port} can contain a string port name or a -numeric port number. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{getprotobyname}{protocolname} -Translate an Internet protocol name (for example, \code{'icmp'}) to a constant -suitable for passing as the (optional) third argument to the -\function{socket()} function. This is usually only needed for sockets -opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket -modes, the correct protocol is chosen automatically if the protocol is -omitted or zero. -\end{funcdesc} - -\begin{funcdesc}{getservbyname}{servicename\optional{, protocolname}} -Translate an Internet service name and protocol name to a port number -for that service. The optional protocol name, if given, should be -\code{'tcp'} or \code{'udp'}, otherwise any protocol will match. -\end{funcdesc} - -\begin{funcdesc}{getservbyport}{port\optional{, protocolname}} -Translate an Internet port number and protocol name to a service name -for that service. The optional protocol name, if given, should be -\code{'tcp'} or \code{'udp'}, otherwise any protocol will match. -\end{funcdesc} - -\begin{funcdesc}{socket}{\optional{family\optional{, - type\optional{, proto}}}} -Create a new socket using the given address family, socket type and -protocol number. The address family should be \constant{AF_INET} (the -default), \constant{AF_INET6} or \constant{AF_UNIX}. The socket type -should be \constant{SOCK_STREAM} (the default), \constant{SOCK_DGRAM} -or perhaps one of the other \samp{SOCK_} constants. The protocol -number is usually zero and may be omitted in that case. -\end{funcdesc} - -\begin{funcdesc}{ssl}{sock\optional{, keyfile, certfile}} -Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is -the name of a PEM formatted file that contains your private -key. \var{certfile} is a PEM formatted certificate chain file. On -success, a new \class{SSLObject} is returned. - -\warning{This does not do any certificate verification!} -\end{funcdesc} - -\begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, proto}}}} -Build a pair of connected socket objects using the given address -family, socket type, and protocol number. Address family, socket type, -and protocol number are as for the \function{socket()} function above. -The default family is \constant{AF_UNIX} if defined on the platform; -otherwise, the default is \constant{AF_INET}. -Availability: \UNIX. \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}} -Duplicate the file descriptor \var{fd} (an integer as returned by a file -object's \method{fileno()} method) and build a socket object from the -result. Address family, socket type and protocol number are as for the -\function{socket()} function above. -The file descriptor should refer to a socket, but this is not -checked --- subsequent operations on the object may fail if the file -descriptor is invalid. This function is rarely needed, but can be -used to get or set socket options on a socket passed to a program as -standard input or output (such as a server started by the \UNIX{} inet -daemon). The socket is assumed to be in blocking mode. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{ntohl}{x} -Convert 32-bit positive integers from network to host byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 4-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{ntohs}{x} -Convert 16-bit positive integers from network to host byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 2-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{htonl}{x} -Convert 32-bit positive integers from host to network byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 4-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{htons}{x} -Convert 16-bit positive integers from host to network byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 2-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{inet_aton}{ip_string} -Convert an IPv4 address from dotted-quad string format (for example, -'123.45.67.89') to 32-bit packed binary format, as a string four -characters in length. This is useful when conversing with a program -that uses the standard C library and needs objects of type -\ctype{struct in_addr}, which is the C type for the 32-bit packed -binary this function returns. - -If the IPv4 address string passed to this function is invalid, -\exception{socket.error} will be raised. Note that exactly what is -valid depends on the underlying C implementation of -\cfunction{inet_aton()}. - -\function{inet_aton()} does not support IPv6, and -\function{getnameinfo()} should be used instead for IPv4/v6 dual stack -support. -\end{funcdesc} - -\begin{funcdesc}{inet_ntoa}{packed_ip} -Convert a 32-bit packed IPv4 address (a string four characters in -length) to its standard dotted-quad string representation (for -example, '123.45.67.89'). This is useful when conversing with a -program that uses the standard C library and needs objects of type -\ctype{struct in_addr}, which is the C type for the 32-bit packed -binary data this function takes as an argument. - -If the string passed to this function is not exactly 4 bytes in -length, \exception{socket.error} will be raised. -\function{inet_ntoa()} does not support IPv6, and -\function{getnameinfo()} should be used instead for IPv4/v6 dual stack -support. -\end{funcdesc} - -\begin{funcdesc}{inet_pton}{address_family, ip_string} -Convert an IP address from its family-specific string format to a packed, -binary format. -\function{inet_pton()} is useful when a library or network protocol calls for -an object of type \ctype{struct in_addr} (similar to \function{inet_aton()}) -or \ctype{struct in6_addr}. - -Supported values for \var{address_family} are currently -\constant{AF_INET} and \constant{AF_INET6}. -If the IP address string \var{ip_string} is invalid, -\exception{socket.error} will be raised. Note that exactly what is valid -depends on both the value of \var{address_family} and the underlying -implementation of \cfunction{inet_pton()}. - -Availability: \UNIX{} (maybe not all platforms). -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{inet_ntop}{address_family, packed_ip} -Convert a packed IP address (a string of some number of characters) to -its standard, family-specific string representation (for example, -\code{'7.10.0.5'} or \code{'5aef:2b::8'}) -\function{inet_ntop()} is useful when a library or network protocol returns -an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()}) -or \ctype{struct in6_addr}. - -Supported values for \var{address_family} are currently -\constant{AF_INET} and \constant{AF_INET6}. -If the string \var{packed_ip} is not the correct length for the -specified address family, \exception{ValueError} will be raised. A -\exception{socket.error} is raised for errors from the call to -\function{inet_ntop()}. - -Availability: \UNIX{} (maybe not all platforms). -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{getdefaulttimeout}{} -Return the default timeout in floating seconds for new socket objects. -A value of \code{None} indicates that new socket objects have no timeout. -When the socket module is first imported, the default is \code{None}. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{setdefaulttimeout}{timeout} -Set the default timeout in floating seconds for new socket objects. -A value of \code{None} indicates that new socket objects have no timeout. -When the socket module is first imported, the default is \code{None}. -\versionadded{2.3} -\end{funcdesc} - -\begin{datadesc}{SocketType} -This is a Python type object that represents the socket object type. -It is the same as \code{type(socket(...))}. -\end{datadesc} - - -\begin{seealso} - \seemodule{SocketServer}{Classes that simplify writing network servers.} -\end{seealso} - - -\subsection{Socket Objects \label{socket-objects}} - -Socket objects have the following methods. Except for -\method{makefile()} these correspond to \UNIX{} system calls -applicable to sockets. - -\begin{methoddesc}[socket]{accept}{} -Accept a connection. -The socket must be bound to an address and listening for connections. -The return value is a pair \code{(\var{conn}, \var{address})} -where \var{conn} is a \emph{new} socket object usable to send and -receive data on the connection, and \var{address} is the address bound -to the socket on the other end of the connection. -\end{methoddesc} - -\begin{methoddesc}[socket]{bind}{address} -Bind the socket to \var{address}. The socket must not already be bound. -(The format of \var{address} depends on the address family --- see -above.) \note{This method has historically accepted a pair -of parameters for \constant{AF_INET} addresses instead of only a -tuple. This was never intentional and is no longer available in -Python 2.0 and later.} -\end{methoddesc} - -\begin{methoddesc}[socket]{close}{} -Close the socket. All future operations on the socket object will fail. -The remote end will receive no more data (after queued data is flushed). -Sockets are automatically closed when they are garbage-collected. -\end{methoddesc} - -\begin{methoddesc}[socket]{connect}{address} -Connect to a remote socket at \var{address}. -(The format of \var{address} depends on the address family --- see -above.) \note{This method has historically accepted a pair -of parameters for \constant{AF_INET} addresses instead of only a -tuple. This was never intentional and is no longer available in -Python 2.0 and later.} -\end{methoddesc} - -\begin{methoddesc}[socket]{connect_ex}{address} -Like \code{connect(\var{address})}, but return an error indicator -instead of raising an exception for errors returned by the C-level -\cfunction{connect()} call (other problems, such as ``host not found,'' -can still raise exceptions). The error indicator is \code{0} if the -operation succeeded, otherwise the value of the \cdata{errno} -variable. This is useful to support, for example, asynchronous connects. -\note{This method has historically accepted a pair of -parameters for \constant{AF_INET} addresses instead of only a tuple. -This was never intentional and is no longer available in Python -2.0 and later.} -\end{methoddesc} - -\begin{methoddesc}[socket]{fileno}{} -Return the socket's file descriptor (a small integer). This is useful -with \function{select.select()}. - -Under Windows the small integer returned by this method cannot be used where -a file descriptor can be used (such as \function{os.fdopen()}). \UNIX{} does -not have this limitation. -\end{methoddesc} - -\begin{methoddesc}[socket]{getpeername}{} -Return the remote address to which the socket is connected. This is -useful to find out the port number of a remote IPv4/v6 socket, for instance. -(The format of the address returned depends on the address family --- -see above.) On some systems this function is not supported. -\end{methoddesc} - -\begin{methoddesc}[socket]{getsockname}{} -Return the socket's own address. This is useful to find out the port -number of an IPv4/v6 socket, for instance. -(The format of the address returned depends on the address family --- -see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}} -Return the value of the given socket option (see the \UNIX{} man page -\manpage{getsockopt}{2}). The needed symbolic constants -(\constant{SO_*} etc.) are defined in this module. If \var{buflen} -is absent, an integer option is assumed and its integer value -is returned by the function. If \var{buflen} is present, it specifies -the maximum length of the buffer used to receive the option in, and -this buffer is returned as a string. It is up to the caller to decode -the contents of the buffer (see the optional built-in module -\refmodule{struct} for a way to decode C structures encoded as strings). -\end{methoddesc} - -\begin{methoddesc}[socket]{listen}{backlog} -Listen for connections made to the socket. The \var{backlog} argument -specifies the maximum number of queued connections and should be at -least 1; the maximum value is system-dependent (usually 5). -\end{methoddesc} - -\begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}} -Return a \dfn{file object} associated with the socket. (File objects -are described in \ref{bltin-file-objects}, ``File Objects.'') -The file object references a \cfunction{dup()}ped version of the -socket file descriptor, so the file object and socket object may be -closed or garbage-collected independently. -The socket must be in blocking mode (it can not have a timeout). -\index{I/O control!buffering}The optional \var{mode} -and \var{bufsize} arguments are interpreted the same way as by the -built-in \function{file()} function; see ``Built-in Functions'' -(section \ref{built-in-funcs}) for more information. -\end{methoddesc} - -\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}} -Receive data from the socket. The return value is a string representing -the data received. The maximum amount of data to be received -at once is specified by \var{bufsize}. See the \UNIX{} manual page -\manpage{recv}{2} for the meaning of the optional argument -\var{flags}; it defaults to zero. -\note{For best match with hardware and network realities, the value of -\var{bufsize} should be a relatively small power of 2, for example, 4096.} -\end{methoddesc} - -\begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}} -Receive data from the socket. The return value is a pair -\code{(\var{string}, \var{address})} where \var{string} is a string -representing the data received and \var{address} is the address of the -socket sending the data. See the \UNIX{} manual page -\manpage{recv}{2} for the meaning of the optional argument -\var{flags}; it defaults to zero. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{recvfrom_into}{buffer\optional{, nbytes\optional{, flags}}} -Receive data from the socket, writing it into \var{buffer} instead of -creating a new string. The return value is a pair -\code{(\var{nbytes}, \var{address})} where \var{nbytes} is the number -of bytes received and \var{address} is the address of the socket -sending the data. See the \UNIX{} manual page -\manpage{recv}{2} for the meaning of the optional argument -\var{flags}; it defaults to zero. (The format of \var{address} -depends on the address family --- see above.) -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[socket]{recv_into}{buffer\optional{, nbytes\optional{, flags}}} -Receive up to \var{nbytes} bytes from the socket, -storing the data into a buffer rather than creating a new string. -If \var{nbytes} is not specified (or 0), -receive up to the size available in the given buffer. -See the \UNIX{} manual page \manpage{recv}{2} for the meaning of the -optional argument \var{flags}; it defaults to zero. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[socket]{send}{string\optional{, flags}} -Send data to the socket. The socket must be connected to a remote -socket. The optional \var{flags} argument has the same meaning as for -\method{recv()} above. Returns the number of bytes sent. -Applications are responsible for checking that all data has been sent; -if only some of the data was transmitted, the application needs to -attempt delivery of the remaining data. -\end{methoddesc} - -\begin{methoddesc}[socket]{sendall}{string\optional{, flags}} -Send data to the socket. The socket must be connected to a remote -socket. The optional \var{flags} argument has the same meaning as for -\method{recv()} above. Unlike \method{send()}, this method continues -to send data from \var{string} until either all data has been sent or -an error occurs. \code{None} is returned on success. On error, an -exception is raised, and there is no way to determine how much data, -if any, was successfully sent. -\end{methoddesc} - -\begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address} -Send data to the socket. The socket should not be connected to a -remote socket, since the destination socket is specified by -\var{address}. The optional \var{flags} argument has the same -meaning as for \method{recv()} above. Return the number of bytes sent. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{setblocking}{flag} -Set blocking or non-blocking mode of the socket: if \var{flag} is 0, -the socket is set to non-blocking, else to blocking mode. Initially -all sockets are in blocking mode. In non-blocking mode, if a -\method{recv()} call doesn't find any data, or if a -\method{send()} call can't immediately dispose of the data, a -\exception{error} exception is raised; in blocking mode, the calls -block until they can proceed. -\code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)}; -\code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}. -\end{methoddesc} - -\begin{methoddesc}[socket]{settimeout}{value} -Set a timeout on blocking socket operations. The \var{value} argument -can be a nonnegative float expressing seconds, or \code{None}. -If a float is -given, subsequent socket operations will raise an \exception{timeout} -exception if the timeout period \var{value} has elapsed before the -operation has completed. Setting a timeout of \code{None} disables -timeouts on socket operations. -\code{s.settimeout(0.0)} is equivalent to \code{s.setblocking(0)}; -\code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[socket]{gettimeout}{} -Return the timeout in floating seconds associated with socket -operations, or \code{None} if no timeout is set. This reflects -the last call to \method{setblocking()} or \method{settimeout()}. -\versionadded{2.3} -\end{methoddesc} - -Some notes on socket blocking and timeouts: A socket object can be in -one of three modes: blocking, non-blocking, or timeout. Sockets are -always created in blocking mode. In blocking mode, operations block -until complete. In non-blocking mode, operations fail (with an error -that is unfortunately system-dependent) if they cannot be completed -immediately. In timeout mode, operations fail if they cannot be -completed within the timeout specified for the socket. The -\method{setblocking()} method is simply a shorthand for certain -\method{settimeout()} calls. - -Timeout mode internally sets the socket in non-blocking mode. The -blocking and timeout modes are shared between file descriptors and -socket objects that refer to the same network endpoint. A consequence -of this is that file objects returned by the \method{makefile()} -method must only be used when the socket is in blocking mode; in -timeout or non-blocking mode file operations that cannot be completed -immediately will fail. - -Note that the \method{connect()} operation is subject to the timeout -setting, and in general it is recommended to call -\method{settimeout()} before calling \method{connect()}. - -\begin{methoddesc}[socket]{setsockopt}{level, optname, value} -Set the value of the given socket option (see the \UNIX{} manual page -\manpage{setsockopt}{2}). The needed symbolic constants are defined in -the \module{socket} module (\constant{SO_*} etc.). The value can be an -integer or a string representing a buffer. In the latter case it is -up to the caller to ensure that the string contains the proper bits -(see the optional built-in module -\refmodule{struct}\refbimodindex{struct} for a way to encode C -structures as strings). -\end{methoddesc} - -\begin{methoddesc}[socket]{shutdown}{how} -Shut down one or both halves of the connection. If \var{how} is -\constant{SHUT_RD}, further receives are disallowed. If \var{how} is \constant{SHUT_WR}, -further sends are disallowed. If \var{how} is \constant{SHUT_RDWR}, further sends -and receives are disallowed. -\end{methoddesc} - -Note that there are no methods \method{read()} or \method{write()}; -use \method{recv()} and \method{send()} without \var{flags} argument -instead. - - -Socket objects also have these (read-only) attributes that correspond -to the values given to the \class{socket} constructor. - -\begin{memberdesc}[socket]{family} -The socket family. -\versionadded{2.5} -\end{memberdesc} - -\begin{memberdesc}[socket]{type} -The socket type. -\versionadded{2.5} -\end{memberdesc} - -\begin{memberdesc}[socket]{proto} -The socket protocol. -\versionadded{2.5} -\end{memberdesc} - - -\subsection{SSL Objects \label{ssl-objects}} - -SSL objects have the following methods. - -\begin{methoddesc}[SSL]{write}{s} -Writes the string \var{s} to the on the object's SSL connection. -The return value is the number of bytes written. -\end{methoddesc} - -\begin{methoddesc}[SSL]{read}{\optional{n}} -If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise -read until EOF. The return value is a string of the bytes read. -\end{methoddesc} - -\begin{methoddesc}[SSL]{server}{} -Returns a string describing the server's certificate. -Useful for debugging purposes; do not parse the content of this string -because its format can't be parsed unambiguously. -\end{methoddesc} - -\begin{methoddesc}[SSL]{issuer}{} -Returns a string describing the issuer of the server's certificate. -Useful for debugging purposes; do not parse the content of this string -because its format can't be parsed unambiguously. -\end{methoddesc} - -\subsection{Example \label{socket-example}} - -Here are four minimal example programs using the TCP/IP protocol:\ a -server that echoes all data that it receives back (servicing only one -client), and a client using it. Note that a server must perform the -sequence \function{socket()}, \method{bind()}, \method{listen()}, -\method{accept()} (possibly repeating the \method{accept()} to service -more than one client), while a client only needs the sequence -\function{socket()}, \method{connect()}. Also note that the server -does not \method{send()}/\method{recv()} on the -socket it is listening on but on the new socket returned by -\method{accept()}. - -The first two examples support IPv4 only. - -\begin{verbatim} -# Echo server program -import socket - -HOST = '' # Symbolic name meaning the local host -PORT = 50007 # Arbitrary non-privileged port -s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) -s.bind((HOST, PORT)) -s.listen(1) -conn, addr = s.accept() -print 'Connected by', addr -while 1: - data = conn.recv(1024) - if not data: break - conn.send(data) -conn.close() -\end{verbatim} - -\begin{verbatim} -# Echo client program -import socket - -HOST = 'daring.cwi.nl' # The remote host -PORT = 50007 # The same port as used by the server -s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) -s.connect((HOST, PORT)) -s.send('Hello, world') -data = s.recv(1024) -s.close() -print 'Received', repr(data) -\end{verbatim} - -The next two examples are identical to the above two, but support both -IPv4 and IPv6. -The server side will listen to the first address family available -(it should listen to both instead). -On most of IPv6-ready systems, IPv6 will take precedence -and the server may not accept IPv4 traffic. -The client side will try to connect to the all addresses returned as a result -of the name resolution, and sends traffic to the first one connected -successfully. - -\begin{verbatim} -# Echo server program -import socket -import sys - -HOST = '' # Symbolic name meaning the local host -PORT = 50007 # Arbitrary non-privileged port -s = None -for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE): - af, socktype, proto, canonname, sa = res - try: - s = socket.socket(af, socktype, proto) - except socket.error as msg: - s = None - continue - try: - s.bind(sa) - s.listen(1) - except socket.error as msg: - s.close() - s = None - continue - break -if s is None: - print 'could not open socket' - sys.exit(1) -conn, addr = s.accept() -print 'Connected by', addr -while 1: - data = conn.recv(1024) - if not data: break - conn.send(data) -conn.close() -\end{verbatim} - -\begin{verbatim} -# Echo client program -import socket -import sys - -HOST = 'daring.cwi.nl' # The remote host -PORT = 50007 # The same port as used by the server -s = None -for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM): - af, socktype, proto, canonname, sa = res - try: - s = socket.socket(af, socktype, proto) - except socket.error as msg: - s = None - continue - try: - s.connect(sa) - except socket.error as msg: - s.close() - s = None - continue - break -if s is None: - print 'could not open socket' - sys.exit(1) -s.send('Hello, world') -data = s.recv(1024) -s.close() -print 'Received', repr(data) -\end{verbatim} - -This example connects to an SSL server, prints the -server and issuer's distinguished names, sends some bytes, -and reads part of the response: - -\begin{verbatim} -import socket - -s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) -s.connect(('www.verisign.com', 443)) - -ssl_sock = socket.ssl(s) - -print repr(ssl_sock.server()) -print repr(ssl_sock.issuer()) - -# Set a simple HTTP request -- use httplib in actual code. -ssl_sock.write("""GET / HTTP/1.0\r -Host: www.verisign.com\r\n\r\n""") - -# Read a chunk of data. Will not necessarily -# read all the data returned by the server. -data = ssl_sock.read() - -# Note that you need to close the underlying socket, not the SSL object. -del ssl_sock -s.close() -\end{verbatim} - -At this writing, this SSL example prints the following output (line -breaks inserted for readability): - -\begin{verbatim} -'/C=US/ST=California/L=Mountain View/ - O=VeriSign, Inc./OU=Production Services/ - OU=Terms of use at www.verisign.com/rpa (c)00/ - CN=www.verisign.com' -'/O=VeriSign Trust Network/OU=VeriSign, Inc./ - OU=VeriSign International Server CA - Class 3/ - OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign' -\end{verbatim} diff --git a/Doc/lib/libsocksvr.tex b/Doc/lib/libsocksvr.tex deleted file mode 100644 index c7b28ea..0000000 --- a/Doc/lib/libsocksvr.tex +++ /dev/null @@ -1,293 +0,0 @@ -\section{\module{SocketServer} --- - A framework for network servers} - -\declaremodule{standard}{SocketServer} -\modulesynopsis{A framework for network servers.} - - -The \module{SocketServer} module simplifies the task of writing network -servers. - -There are four basic server classes: \class{TCPServer} uses the -Internet TCP protocol, which provides for continuous streams of data -between the client and server. \class{UDPServer} uses datagrams, which -are discrete packets of information that may arrive out of order or be -lost while in transit. The more infrequently used -\class{UnixStreamServer} and \class{UnixDatagramServer} classes are -similar, but use \UNIX{} domain sockets; they're not available on -non-\UNIX{} platforms. For more details on network programming, consult -a book such as W. Richard Steven's \citetitle{UNIX Network Programming} -or Ralph Davis's \citetitle{Win32 Network Programming}. - -These four classes process requests \dfn{synchronously}; each request -must be completed before the next request can be started. This isn't -suitable if each request takes a long time to complete, because it -requires a lot of computation, or because it returns a lot of data -which the client is slow to process. The solution is to create a -separate process or thread to handle each request; the -\class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes can be -used to support asynchronous behaviour. - -Creating a server requires several steps. First, you must create a -request handler class by subclassing the \class{BaseRequestHandler} -class and overriding its \method{handle()} method; this method will -process incoming requests. Second, you must instantiate one of the -server classes, passing it the server's address and the request -handler class. Finally, call the \method{handle_request()} or -\method{serve_forever()} method of the server object to process one or -many requests. - -When inheriting from \class{ThreadingMixIn} for threaded connection -behavior, you should explicitly declare how you want your threads -to behave on an abrupt shutdown. The \class{ThreadingMixIn} class -defines an attribute \var{daemon_threads}, which indicates whether -or not the server should wait for thread termination. You should -set the flag explicitly if you would like threads to behave -autonomously; the default is \constant{False}, meaning that Python -will not exit until all threads created by \class{ThreadingMixIn} have -exited. - -Server classes have the same external methods and attributes, no -matter what network protocol they use: - -\setindexsubitem{(SocketServer protocol)} - -\subsection{Server Creation Notes} - -There are five classes in an inheritance diagram, four of which represent -synchronous servers of four types: - -\begin{verbatim} - +------------+ - | BaseServer | - +------------+ - | - v - +-----------+ +------------------+ - | TCPServer |------->| UnixStreamServer | - +-----------+ +------------------+ - | - v - +-----------+ +--------------------+ - | UDPServer |------->| UnixDatagramServer | - +-----------+ +--------------------+ -\end{verbatim} - -Note that \class{UnixDatagramServer} derives from \class{UDPServer}, not -from \class{UnixStreamServer} --- the only difference between an IP and a -\UNIX{} stream server is the address family, which is simply repeated in both -\UNIX{} server classes. - -Forking and threading versions of each type of server can be created using -the \class{ForkingMixIn} and \class{ThreadingMixIn} mix-in classes. For -instance, a threading UDP server class is created as follows: - -\begin{verbatim} - class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass -\end{verbatim} - -The mix-in class must come first, since it overrides a method defined in -\class{UDPServer}. Setting the various member variables also changes the -behavior of the underlying server mechanism. - -To implement a service, you must derive a class from -\class{BaseRequestHandler} and redefine its \method{handle()} method. You -can then run various versions of the service by combining one of the server -classes with your request handler class. The request handler class must be -different for datagram or stream services. This can be hidden by using the -handler subclasses \class{StreamRequestHandler} or \class{DatagramRequestHandler}. - -Of course, you still have to use your head! For instance, it makes no sense -to use a forking server if the service contains state in memory that can be -modified by different requests, since the modifications in the child process -would never reach the initial state kept in the parent process and passed to -each child. In this case, you can use a threading server, but you will -probably have to use locks to protect the integrity of the shared data. - -On the other hand, if you are building an HTTP server where all data is -stored externally (for instance, in the file system), a synchronous class -will essentially render the service "deaf" while one request is being -handled -- which may be for a very long time if a client is slow to receive -all the data it has requested. Here a threading or forking server is -appropriate. - -In some cases, it may be appropriate to process part of a request -synchronously, but to finish processing in a forked child depending on the -request data. This can be implemented by using a synchronous server and -doing an explicit fork in the request handler class \method{handle()} -method. - -Another approach to handling multiple simultaneous requests in an -environment that supports neither threads nor \function{fork()} (or where -these are too expensive or inappropriate for the service) is to maintain an -explicit table of partially finished requests and to use \function{select()} -to decide which request to work on next (or whether to handle a new incoming -request). This is particularly important for stream services where each -client can potentially be connected for a long time (if threads or -subprocesses cannot be used). - -%XXX should data and methods be intermingled, or separate? -% how should the distinction between class and instance variables be -% drawn? - -\subsection{Server Objects} - -\begin{funcdesc}{fileno}{} -Return an integer file descriptor for the socket on which the server -is listening. This function is most commonly passed to -\function{select.select()}, to allow monitoring multiple servers in the -same process. -\end{funcdesc} - -\begin{funcdesc}{handle_request}{} -Process a single request. This function calls the following methods -in order: \method{get_request()}, \method{verify_request()}, and -\method{process_request()}. If the user-provided \method{handle()} -method of the handler class raises an exception, the server's -\method{handle_error()} method will be called. -\end{funcdesc} - -\begin{funcdesc}{serve_forever}{} -Handle an infinite number of requests. This simply calls -\method{handle_request()} inside an infinite loop. -\end{funcdesc} - -\begin{datadesc}{address_family} -The family of protocols to which the server's socket belongs. -\constant{socket.AF_INET} and \constant{socket.AF_UNIX} are two -possible values. -\end{datadesc} - -\begin{datadesc}{RequestHandlerClass} -The user-provided request handler class; an instance of this class is -created for each request. -\end{datadesc} - -\begin{datadesc}{server_address} -The address on which the server is listening. The format of addresses -varies depending on the protocol family; see the documentation for the -socket module for details. For Internet protocols, this is a tuple -containing a string giving the address, and an integer port number: -\code{('127.0.0.1', 80)}, for example. -\end{datadesc} - -\begin{datadesc}{socket} -The socket object on which the server will listen for incoming requests. -\end{datadesc} - -% XXX should class variables be covered before instance variables, or -% vice versa? - -The server classes support the following class variables: - -\begin{datadesc}{allow_reuse_address} -Whether the server will allow the reuse of an address. This defaults -to \constant{False}, and can be set in subclasses to change the policy. -\end{datadesc} - -\begin{datadesc}{request_queue_size} -The size of the request queue. If it takes a long time to process a -single request, any requests that arrive while the server is busy are -placed into a queue, up to \member{request_queue_size} requests. Once -the queue is full, further requests from clients will get a -``Connection denied'' error. The default value is usually 5, but this -can be overridden by subclasses. -\end{datadesc} - -\begin{datadesc}{socket_type} -The type of socket used by the server; \constant{socket.SOCK_STREAM} -and \constant{socket.SOCK_DGRAM} are two possible values. -\end{datadesc} - -There are various server methods that can be overridden by subclasses -of base server classes like \class{TCPServer}; these methods aren't -useful to external users of the server object. - -% should the default implementations of these be documented, or should -% it be assumed that the user will look at SocketServer.py? - -\begin{funcdesc}{finish_request}{} -Actually processes the request by instantiating -\member{RequestHandlerClass} and calling its \method{handle()} method. -\end{funcdesc} - -\begin{funcdesc}{get_request}{} -Must accept a request from the socket, and return a 2-tuple containing -the \emph{new} socket object to be used to communicate with the -client, and the client's address. -\end{funcdesc} - -\begin{funcdesc}{handle_error}{request, client_address} -This function is called if the \member{RequestHandlerClass}'s -\method{handle()} method raises an exception. The default action is -to print the traceback to standard output and continue handling -further requests. -\end{funcdesc} - -\begin{funcdesc}{process_request}{request, client_address} -Calls \method{finish_request()} to create an instance of the -\member{RequestHandlerClass}. If desired, this function can create a -new process or thread to handle the request; the \class{ForkingMixIn} -and \class{ThreadingMixIn} classes do this. -\end{funcdesc} - -% Is there any point in documenting the following two functions? -% What would the purpose of overriding them be: initializing server -% instance variables, adding new network families? - -\begin{funcdesc}{server_activate}{} -Called by the server's constructor to activate the server. The default -behavior just \method{listen}s to the server's socket. -May be overridden. -\end{funcdesc} - -\begin{funcdesc}{server_bind}{} -Called by the server's constructor to bind the socket to the desired -address. May be overridden. -\end{funcdesc} - -\begin{funcdesc}{verify_request}{request, client_address} -Must return a Boolean value; if the value is \constant{True}, the request will be -processed, and if it's \constant{False}, the request will be denied. -This function can be overridden to implement access controls for a server. -The default implementation always returns \constant{True}. -\end{funcdesc} - -\subsection{RequestHandler Objects} - -The request handler class must define a new \method{handle()} method, -and can override any of the following methods. A new instance is -created for each request. - -\begin{funcdesc}{finish}{} -Called after the \method{handle()} method to perform any clean-up -actions required. The default implementation does nothing. If -\method{setup()} or \method{handle()} raise an exception, this -function will not be called. -\end{funcdesc} - -\begin{funcdesc}{handle}{} -This function must do all the work required to service a request. -The default implementation does nothing. -Several instance attributes are available to it; the request is -available as \member{self.request}; the client address as -\member{self.client_address}; and the server instance as -\member{self.server}, in case it needs access to per-server -information. - -The type of \member{self.request} is different for datagram or stream -services. For stream services, \member{self.request} is a socket -object; for datagram services, \member{self.request} is a string. -However, this can be hidden by using the request handler subclasses -\class{StreamRequestHandler} or \class{DatagramRequestHandler}, which -override the \method{setup()} and \method{finish()} methods, and -provide \member{self.rfile} and \member{self.wfile} attributes. -\member{self.rfile} and \member{self.wfile} can be read or written, -respectively, to get the request data or return data to the client. -\end{funcdesc} - -\begin{funcdesc}{setup}{} -Called before the \method{handle()} method to perform any -initialization actions required. The default implementation does -nothing. -\end{funcdesc} diff --git a/Doc/lib/libsomeos.tex b/Doc/lib/libsomeos.tex deleted file mode 100644 index 680c590..0000000 --- a/Doc/lib/libsomeos.tex +++ /dev/null @@ -1,10 +0,0 @@ -\chapter{Optional Operating System Services} -\label{someos} - -The modules described in this chapter provide interfaces to operating -system features that are available on selected operating systems only. -The interfaces are generally modeled after the \UNIX{} or \C{} -interfaces but they are available on some other systems as well -(e.g. Windows or NT). Here's an overview: - -\localmoduletable diff --git a/Doc/lib/libspwd.tex b/Doc/lib/libspwd.tex deleted file mode 100644 index 5f0e6f1..0000000 --- a/Doc/lib/libspwd.tex +++ /dev/null @@ -1,48 +0,0 @@ -\section{\module{spwd} --- - The shadow password database} - -\declaremodule{builtin}{spwd} - \platform{Unix} -\modulesynopsis{The shadow password database (\function{getspnam()} and friends).} -\versionadded{2.5} - -This module provides access to the \UNIX{} shadow password database. -It is available on various \UNIX{} versions. - -You must have enough privileges to access the shadow password database -(this usually means you have to be root). - -Shadow password database entries are reported as a tuple-like object, whose -attributes correspond to the members of the \code{spwd} structure -(Attribute field below, see \code{<shadow.h>}): - -\begin{tableiii}{r|l|l}{textrm}{Index}{Attribute}{Meaning} - \lineiii{0}{\code{sp_nam}}{Login name} - \lineiii{1}{\code{sp_pwd}}{Encrypted password} - \lineiii{2}{\code{sp_lstchg}}{Date of last change} - \lineiii{3}{\code{sp_min}}{Minimal number of days between changes} - \lineiii{4}{\code{sp_max}}{Maximum number of days between changes} - \lineiii{5}{\code{sp_warn}}{Number of days before password expires to warn user about it} - \lineiii{6}{\code{sp_inact}}{Number of days after password expires until account is blocked} - \lineiii{7}{\code{sp_expire}}{Number of days since 1970-01-01 until account is disabled} - \lineiii{8}{\code{sp_flag}}{Reserved} -\end{tableiii} - -The sp_nam and sp_pwd items are strings, all others are integers. -\exception{KeyError} is raised if the entry asked for cannot be found. - -It defines the following items: - -\begin{funcdesc}{getspnam}{name} -Return the shadow password database entry for the given user name. -\end{funcdesc} - -\begin{funcdesc}{getspall}{} -Return a list of all available shadow password database entries, in arbitrary order. -\end{funcdesc} - - -\begin{seealso} - \seemodule{grp}{An interface to the group database, similar to this.} - \seemodule{pwd}{An interface to the normal password database, similar to this.} -\end{seealso} diff --git a/Doc/lib/libsqlite3.tex b/Doc/lib/libsqlite3.tex deleted file mode 100644 index a7a0e94..0000000 --- a/Doc/lib/libsqlite3.tex +++ /dev/null @@ -1,648 +0,0 @@ -\section{\module{sqlite3} --- - DB-API 2.0 interface for SQLite databases} - -\declaremodule{builtin}{sqlite3} -\modulesynopsis{A DB-API 2.0 implementation using SQLite 3.x.} -\sectionauthor{Gerhard Häring}{gh@ghaering.de} -\versionadded{2.5} - -SQLite is a C library that provides a lightweight disk-based database -that doesn't require a separate server process and allows accessing -the database using a nonstandard variant of the SQL query language. -Some applications can use SQLite for internal data storage. It's also -possible to prototype an application using SQLite and then port the -code to a larger database such as PostgreSQL or Oracle. - -pysqlite was written by Gerhard H\"aring and provides a SQL interface -compliant with the DB-API 2.0 specification described by -\pep{249}. - -To use the module, you must first create a \class{Connection} object -that represents the database. Here the data will be stored in the -\file{/tmp/example} file: - -\begin{verbatim} -conn = sqlite3.connect('/tmp/example') -\end{verbatim} - -You can also supply the special name \samp{:memory:} to create -a database in RAM. - -Once you have a \class{Connection}, you can create a \class{Cursor} -object and call its \method{execute()} method to perform SQL commands: - -\begin{verbatim} -c = conn.cursor() - -# Create table -c.execute('''create table stocks -(date text, trans text, symbol text, - qty real, price real)''') - -# Insert a row of data -c.execute("""insert into stocks - values ('2006-01-05','BUY','RHAT',100,35.14)""") - -# Save (commit) the changes -conn.commit() - -# We can also close the cursor if we are done with it -c.close() -\end{verbatim} - -Usually your SQL operations will need to use values from Python -variables. You shouldn't assemble your query using Python's string -operations because doing so is insecure; it makes your program -vulnerable to an SQL injection attack. - -Instead, use the DB-API's parameter substitution. Put \samp{?} as a -placeholder wherever you want to use a value, and then provide a tuple -of values as the second argument to the cursor's \method{execute()} -method. (Other database modules may use a different placeholder, -such as \samp{\%s} or \samp{:1}.) For example: - -\begin{verbatim} -# Never do this -- insecure! -symbol = 'IBM' -c.execute("... where symbol = '%s'" % symbol) - -# Do this instead -t = (symbol,) -c.execute('select * from stocks where symbol=?', t) - -# Larger example -for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00), - ('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00), - ('2006-04-06', 'SELL', 'IBM', 500, 53.00), - ): - c.execute('insert into stocks values (?,?,?,?,?)', t) -\end{verbatim} - -To retrieve data after executing a SELECT statement, you can either -treat the cursor as an iterator, call the cursor's \method{fetchone()} -method to retrieve a single matching row, -or call \method{fetchall()} to get a list of the matching rows. - -This example uses the iterator form: - -\begin{verbatim} ->>> c = conn.cursor() ->>> c.execute('select * from stocks order by price') ->>> for row in c: -... print row -... -(u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001) -(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0) -(u'2006-04-06', u'SELL', u'IBM', 500, 53.0) -(u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0) ->>> -\end{verbatim} - -\begin{seealso} - -\seeurl{http://www.pysqlite.org} -{The pysqlite web page.} - -\seeurl{http://www.sqlite.org} -{The SQLite web page; the documentation describes the syntax and the -available data types for the supported SQL dialect.} - -\seepep{249}{Database API Specification 2.0}{PEP written by -Marc-Andr\'e Lemburg.} - -\end{seealso} - - -\subsection{Module functions and constants\label{sqlite3-Module-Contents}} - -\begin{datadesc}{PARSE_DECLTYPES} -This constant is meant to be used with the \var{detect_types} parameter of the -\function{connect} function. - -Setting it makes the \module{sqlite3} module parse the declared type for each column it -returns. It will parse out the first word of the declared type, i. e. for -"integer primary key", it will parse out "integer". Then for that column, it -will look into the converters dictionary and use the converter function -registered for that type there. Converter names are case-sensitive! -\end{datadesc} - - -\begin{datadesc}{PARSE_COLNAMES} -This constant is meant to be used with the \var{detect_types} parameter of the -\function{connect} function. - -Setting this makes the SQLite interface parse the column name for each column -it returns. It will look for a string formed [mytype] in there, and then -decide that 'mytype' is the type of the column. It will try to find an entry of -'mytype' in the converters dictionary and then use the converter function found -there to return the value. The column name found in \member{cursor.description} is only -the first word of the column name, i. e. if you use something like -\code{'as "x [datetime]"'} in your SQL, then we will parse out everything until the -first blank for the column name: the column name would simply be "x". -\end{datadesc} - -\begin{funcdesc}{connect}{database\optional{, timeout, isolation_level, detect_types, factory}} -Opens a connection to the SQLite database file \var{database}. You can use -\code{":memory:"} to open a database connection to a database that resides in -RAM instead of on disk. - -When a database is accessed by multiple connections, and one of the processes -modifies the database, the SQLite database is locked until that transaction is -committed. The \var{timeout} parameter specifies how long the connection should -wait for the lock to go away until raising an exception. The default for the -timeout parameter is 5.0 (five seconds). - -For the \var{isolation_level} parameter, please see the \member{isolation_level} -property of \class{Connection} objects in section~\ref{sqlite3-Connection-IsolationLevel}. - -SQLite natively supports only the types TEXT, INTEGER, FLOAT, BLOB and NULL. If -you want to use other types you must add support for them yourself. -The \var{detect_types} parameter and the using custom \strong{converters} registered with -the module-level \function{register_converter} function allow you to easily do that. - -\var{detect_types} defaults to 0 (i. e. off, no type detection), you can set it -to any combination of \constant{PARSE_DECLTYPES} and \constant{PARSE_COLNAMES} to turn type -detection on. - -By default, the \module{sqlite3} module uses its \class{Connection} class for the -connect call. You can, however, subclass the \class{Connection} class and make -\function{connect} use your class instead by providing your class for the -\var{factory} parameter. - -Consult the section \ref{sqlite3-Types} of this manual for details. - -The \module{sqlite3} module internally uses a statement cache to avoid SQL parsing -overhead. If you want to explicitly set the number of statements that are -cached for the connection, you can set the \var{cached_statements} parameter. -The currently implemented default is to cache 100 statements. -\end{funcdesc} - -\begin{funcdesc}{register_converter}{typename, callable} -Registers a callable to convert a bytestring from the database into a custom -Python type. The callable will be invoked for all database values that are of -the type \var{typename}. Confer the parameter \var{detect_types} of the -\function{connect} function for how the type detection works. Note that the case of -\var{typename} and the name of the type in your query must match! -\end{funcdesc} - -\begin{funcdesc}{register_adapter}{type, callable} -Registers a callable to convert the custom Python type \var{type} into one of -SQLite's supported types. The callable \var{callable} accepts as single -parameter the Python value, and must return a value of the following types: -int, long, float, str (UTF-8 encoded), unicode or buffer. -\end{funcdesc} - -\begin{funcdesc}{complete_statement}{sql} -Returns \constant{True} if the string \var{sql} contains one or more complete SQL -statements terminated by semicolons. It does not verify that the SQL is -syntactically correct, only that there are no unclosed string literals and the -statement is terminated by a semicolon. - -This can be used to build a shell for SQLite, as in the following example: - - \verbatiminput{sqlite3/complete_statement.py} -\end{funcdesc} - -\begin{funcdesc}{enable_callback_tracebacks}{flag} -By default you will not get any tracebacks in user-defined functions, -aggregates, converters, authorizer callbacks etc. If you want to debug them, -you can call this function with \var{flag} as True. Afterwards, you will get -tracebacks from callbacks on \code{sys.stderr}. Use \constant{False} to disable -the feature again. -\end{funcdesc} - -\subsection{Connection Objects \label{sqlite3-Connection-Objects}} - -A \class{Connection} instance has the following attributes and methods: - -\label{sqlite3-Connection-IsolationLevel} -\begin{memberdesc}[Connection]{isolation_level} - Get or set the current isolation level. None for autocommit mode or one of - "DEFERRED", "IMMEDIATE" or "EXLUSIVE". See ``Controlling Transactions'', - section~\ref{sqlite3-Controlling-Transactions}, for a more detailed explanation. -\end{memberdesc} - -\begin{methoddesc}[Connection]{cursor}{\optional{cursorClass}} - The cursor method accepts a single optional parameter \var{cursorClass}. - If supplied, this must be a custom cursor class that extends - \class{sqlite3.Cursor}. -\end{methoddesc} - -\begin{methoddesc}[Connection]{execute}{sql, \optional{parameters}} -This is a nonstandard shortcut that creates an intermediate cursor object by -calling the cursor method, then calls the cursor's \method{execute} method with the -parameters given. -\end{methoddesc} - -\begin{methoddesc}[Connection]{executemany}{sql, \optional{parameters}} -This is a nonstandard shortcut that creates an intermediate cursor object by -calling the cursor method, then calls the cursor's \method{executemany} method with the -parameters given. -\end{methoddesc} - -\begin{methoddesc}[Connection]{executescript}{sql_script} -This is a nonstandard shortcut that creates an intermediate cursor object by -calling the cursor method, then calls the cursor's \method{executescript} method with the -parameters given. -\end{methoddesc} - -\begin{methoddesc}[Connection]{create_function}{name, num_params, func} - -Creates a user-defined function that you can later use from within SQL -statements under the function name \var{name}. \var{num_params} is the number -of parameters the function accepts, and \var{func} is a Python callable that is -called as the SQL function. - -The function can return any of the types supported by SQLite: unicode, str, -int, long, float, buffer and None. - -Example: - - \verbatiminput{sqlite3/md5func.py} -\end{methoddesc} - -\begin{methoddesc}[Connection]{create_aggregate}{name, num_params, aggregate_class} - -Creates a user-defined aggregate function. - -The aggregate class must implement a \code{step} method, which accepts the -number of parameters \var{num_params}, and a \code{finalize} method which -will return the final result of the aggregate. - -The \code{finalize} method can return any of the types supported by SQLite: -unicode, str, int, long, float, buffer and None. - -Example: - - \verbatiminput{sqlite3/mysumaggr.py} -\end{methoddesc} - -\begin{methoddesc}[Connection]{create_collation}{name, callable} - -Creates a collation with the specified \var{name} and \var{callable}. The -callable will be passed two string arguments. It should return -1 if the first -is ordered lower than the second, 0 if they are ordered equal and 1 if the -first is ordered higher than the second. Note that this controls sorting -(ORDER BY in SQL) so your comparisons don't affect other SQL operations. - -Note that the callable will get its parameters as Python bytestrings, which -will normally be encoded in UTF-8. - -The following example shows a custom collation that sorts "the wrong way": - - \verbatiminput{sqlite3/collation_reverse.py} - -To remove a collation, call \code{create_collation} with None as callable: - -\begin{verbatim} - con.create_collation("reverse", None) -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[Connection]{interrupt}{} - -You can call this method from a different thread to abort any queries that -might be executing on the connection. The query will then abort and the caller -will get an exception. -\end{methoddesc} - -\begin{methoddesc}[Connection]{set_authorizer}{authorizer_callback} - -This routine registers a callback. The callback is invoked for each attempt to -access a column of a table in the database. The callback should return -\constant{SQLITE_OK} if access is allowed, \constant{SQLITE_DENY} if the entire -SQL statement should be aborted with an error and \constant{SQLITE_IGNORE} if -the column should be treated as a NULL value. These constants are available in -the \module{sqlite3} module. - -The first argument to the callback signifies what kind of operation is to be -authorized. The second and third argument will be arguments or \constant{None} -depending on the first argument. The 4th argument is the name of the database -("main", "temp", etc.) if applicable. The 5th argument is the name of the -inner-most trigger or view that is responsible for the access attempt or -\constant{None} if this access attempt is directly from input SQL code. - -Please consult the SQLite documentation about the possible values for the first -argument and the meaning of the second and third argument depending on the -first one. All necessary constants are available in the \module{sqlite3} -module. -\end{methoddesc} - -\begin{memberdesc}[Connection]{row_factory} - You can change this attribute to a callable that accepts the cursor and - the original row as a tuple and will return the real result row. This - way, you can implement more advanced ways of returning results, such - as returning an object that can also access columns by name. - - Example: - - \verbatiminput{sqlite3/row_factory.py} - - If returning a tuple doesn't suffice and you want name-based - access to columns, you should consider setting \member{row_factory} to the - highly-optimized \class{sqlite3.Row} type. \class{Row} provides both - index-based and case-insensitive name-based access to columns with almost - no memory overhead. It will probably be better than your own custom - dictionary-based approach or even a db_row based solution. - % XXX what's a db_row-based solution? -\end{memberdesc} - -\begin{memberdesc}[Connection]{text_factory} - Using this attribute you can control what objects are returned for the - TEXT data type. By default, this attribute is set to \class{unicode} and - the \module{sqlite3} module will return Unicode objects for TEXT. If you want to return - bytestrings instead, you can set it to \class{str}. - - For efficiency reasons, there's also a way to return Unicode objects only - for non-ASCII data, and bytestrings otherwise. To activate it, set this - attribute to \constant{sqlite3.OptimizedUnicode}. - - You can also set it to any other callable that accepts a single bytestring - parameter and returns the resulting object. - - See the following example code for illustration: - - \verbatiminput{sqlite3/text_factory.py} -\end{memberdesc} - -\begin{memberdesc}[Connection]{total_changes} - Returns the total number of database rows that have been modified, inserted, - or deleted since the database connection was opened. -\end{memberdesc} - - - - - -\subsection{Cursor Objects \label{sqlite3-Cursor-Objects}} - -A \class{Cursor} instance has the following attributes and methods: - -\begin{methoddesc}[Cursor]{execute}{sql, \optional{parameters}} - -Executes a SQL statement. The SQL statement may be parametrized (i. e. -placeholders instead of SQL literals). The \module{sqlite3} module supports two kinds of -placeholders: question marks (qmark style) and named placeholders (named -style). - -This example shows how to use parameters with qmark style: - - \verbatiminput{sqlite3/execute_1.py} - -This example shows how to use the named style: - - \verbatiminput{sqlite3/execute_2.py} - - \method{execute()} will only execute a single SQL statement. If you try to - execute more than one statement with it, it will raise a Warning. Use - \method{executescript()} if you want to execute multiple SQL statements with one - call. -\end{methoddesc} - - -\begin{methoddesc}[Cursor]{executemany}{sql, seq_of_parameters} -Executes a SQL command against all parameter sequences or mappings found in the -sequence \var{sql}. The \module{sqlite3} module also allows -using an iterator yielding parameters instead of a sequence. - -\verbatiminput{sqlite3/executemany_1.py} - -Here's a shorter example using a generator: - -\verbatiminput{sqlite3/executemany_2.py} -\end{methoddesc} - -\begin{methoddesc}[Cursor]{executescript}{sql_script} - -This is a nonstandard convenience method for executing multiple SQL statements -at once. It issues a COMMIT statement first, then executes the SQL script it -gets as a parameter. - -\var{sql_script} can be a bytestring or a Unicode string. - -Example: - -\verbatiminput{sqlite3/executescript.py} -\end{methoddesc} - -\begin{memberdesc}[Cursor]{rowcount} - Although the \class{Cursor} class of the \module{sqlite3} module implements this - attribute, the database engine's own support for the determination of "rows - affected"/"rows selected" is quirky. - - For \code{SELECT} statements, \member{rowcount} is always None because we cannot - determine the number of rows a query produced until all rows were fetched. - - For \code{DELETE} statements, SQLite reports \member{rowcount} as 0 if you make a - \code{DELETE FROM table} without any condition. - - For \method{executemany} statements, the number of modifications are summed - up into \member{rowcount}. - - As required by the Python DB API Spec, the \member{rowcount} attribute "is -1 - in case no executeXX() has been performed on the cursor or the rowcount - of the last operation is not determinable by the interface". -\end{memberdesc} - -\subsection{SQLite and Python types\label{sqlite3-Types}} - -\subsubsection{Introduction} - -SQLite natively supports the following types: NULL, INTEGER, REAL, TEXT, BLOB. - -The following Python types can thus be sent to SQLite without any problem: - -\begin{tableii} {c|l}{code}{Python type}{SQLite type} -\lineii{None}{NULL} -\lineii{int}{INTEGER} -\lineii{long}{INTEGER} -\lineii{float}{REAL} -\lineii{str (UTF8-encoded)}{TEXT} -\lineii{unicode}{TEXT} -\lineii{buffer}{BLOB} -\end{tableii} - -This is how SQLite types are converted to Python types by default: - -\begin{tableii} {c|l}{code}{SQLite type}{Python type} -\lineii{NULL}{None} -\lineii{INTEGER}{int or long, depending on size} -\lineii{REAL}{float} -\lineii{TEXT}{depends on text_factory, unicode by default} -\lineii{BLOB}{buffer} -\end{tableii} - -The type system of the \module{sqlite3} module is extensible in two ways: you can store -additional Python types in a SQLite database via object adaptation, and you can -let the \module{sqlite3} module convert SQLite types to different Python types via -converters. - -\subsubsection{Using adapters to store additional Python types in SQLite databases} - -As described before, SQLite supports only a limited set of types natively. To -use other Python types with SQLite, you must \strong{adapt} them to one of the sqlite3 -module's supported types for SQLite: one of NoneType, int, long, float, -str, unicode, buffer. - -The \module{sqlite3} module uses Python object adaptation, as described in \pep{246} for this. The protocol to use is \class{PrepareProtocol}. - -There are two ways to enable the \module{sqlite3} module to adapt a custom Python type -to one of the supported ones. - -\paragraph{Letting your object adapt itself} - -This is a good approach if you write the class yourself. Let's suppose you have -a class like this: - -\begin{verbatim} -class Point(object): - def __init__(self, x, y): - self.x, self.y = x, y -\end{verbatim} - -Now you want to store the point in a single SQLite column. First you'll have to -choose one of the supported types first to be used for representing the point. -Let's just use str and separate the coordinates using a semicolon. Then you -need to give your class a method \code{__conform__(self, protocol)} which must -return the converted value. The parameter \var{protocol} will be -\class{PrepareProtocol}. - -\verbatiminput{sqlite3/adapter_point_1.py} - -\paragraph{Registering an adapter callable} - -The other possibility is to create a function that converts the type to the -string representation and register the function with \method{register_adapter}. - -\begin{notice} -The type/class to adapt must be a new-style class, i. e. it must have -\class{object} as one of its bases. -\end{notice} - - \verbatiminput{sqlite3/adapter_point_2.py} - -The \module{sqlite3} module has two default adapters for Python's built-in -\class{datetime.date} and \class{datetime.datetime} types. Now let's suppose -we want to store \class{datetime.datetime} objects not in ISO representation, -but as a \UNIX{} timestamp. - - \verbatiminput{sqlite3/adapter_datetime.py} - -\subsubsection{Converting SQLite values to custom Python types} - -Writing an adapter lets you send custom Python types to SQLite. -But to make it really useful we need to make the Python to SQLite to Python -roundtrip work. - -Enter converters. - -Let's go back to the \class{Point} class. We stored the x and y -coordinates separated via semicolons as strings in SQLite. - -First, we'll define a converter function that accepts the string as a -parameter and constructs a \class{Point} object from it. - -\begin{notice} -Converter functions \strong{always} get called with a string, no matter -under which data type you sent the value to SQLite. -\end{notice} - -\begin{notice} -Converter names are looked up in a case-sensitive manner. -\end{notice} - - -\begin{verbatim} - def convert_point(s): - x, y = map(float, s.split(";")) - return Point(x, y) -\end{verbatim} - -Now you need to make the \module{sqlite3} module know that what you select from the -database is actually a point. There are two ways of doing this: - -\begin{itemize} - \item Implicitly via the declared type - \item Explicitly via the column name -\end{itemize} - -Both ways are described in ``Module Constants'', section~\ref{sqlite3-Module-Contents}, in -the entries for the constants \constant{PARSE_DECLTYPES} and -\constant{PARSE_COLNAMES}. - - -The following example illustrates both approaches. - - \verbatiminput{sqlite3/converter_point.py} - -\subsubsection{Default adapters and converters} - -There are default adapters for the date and datetime types in the datetime -module. They will be sent as ISO dates/ISO timestamps to SQLite. - -The default converters are registered under the name "date" for \class{datetime.date} -and under the name "timestamp" for \class{datetime.datetime}. - -This way, you can use date/timestamps from Python without any additional -fiddling in most cases. The format of the adapters is also compatible with the -experimental SQLite date/time functions. - -The following example demonstrates this. - - \verbatiminput{sqlite3/pysqlite_datetime.py} - -\subsection{Controlling Transactions \label{sqlite3-Controlling-Transactions}} - -By default, the \module{sqlite3} module opens transactions implicitly before a Data Modification Language (DML) -statement (i.e. INSERT/UPDATE/DELETE/REPLACE), and commits transactions implicitly -before a non-DML, non-query statement (i. e. anything other than -SELECT/INSERT/UPDATE/DELETE/REPLACE). - -So if you are within a transaction and issue a command like \code{CREATE TABLE -...}, \code{VACUUM}, \code{PRAGMA}, the \module{sqlite3} module will commit implicitly -before executing that command. There are two reasons for doing that. The first -is that some of these commands don't work within transactions. The other reason -is that pysqlite needs to keep track of the transaction state (if a transaction -is active or not). - -You can control which kind of "BEGIN" statements pysqlite implicitly executes -(or none at all) via the \var{isolation_level} parameter to the -\function{connect} call, or via the \member{isolation_level} property of -connections. - -If you want \strong{autocommit mode}, then set \member{isolation_level} to None. - -Otherwise leave it at its default, which will result in a plain "BEGIN" -statement, or set it to one of SQLite's supported isolation levels: DEFERRED, -IMMEDIATE or EXCLUSIVE. - -As the \module{sqlite3} module needs to keep track of the transaction state, you should -not use \code{OR ROLLBACK} or \code{ON CONFLICT ROLLBACK} in your SQL. Instead, -catch the \exception{IntegrityError} and call the \method{rollback} method of -the connection yourself. - -\subsection{Using pysqlite efficiently} - -\subsubsection{Using shortcut methods} - -Using the nonstandard \method{execute}, \method{executemany} and -\method{executescript} methods of the \class{Connection} object, your code can -be written more concisely because you don't have to create the (often -superfluous) \class{Cursor} objects explicitly. Instead, the \class{Cursor} -objects are created implicitly and these shortcut methods return the cursor -objects. This way, you can execute a SELECT statement and iterate -over it directly using only a single call on the \class{Connection} object. - - \verbatiminput{sqlite3/shortcut_methods.py} - -\subsubsection{Accessing columns by name instead of by index} - -One useful feature of the \module{sqlite3} module is the builtin \class{sqlite3.Row} class -designed to be used as a row factory. - -Rows wrapped with this class can be accessed both by index (like tuples) and -case-insensitively by name: - - \verbatiminput{sqlite3/rowclass.py} - - diff --git a/Doc/lib/libstat.tex b/Doc/lib/libstat.tex deleted file mode 100644 index d5353f1..0000000 --- a/Doc/lib/libstat.tex +++ /dev/null @@ -1,157 +0,0 @@ -\section{\module{stat} --- - Interpreting \function{stat()} results} - -\declaremodule{standard}{stat} -\modulesynopsis{Utilities for interpreting the results of - \function{os.stat()}, \function{os.lstat()} and \function{os.fstat()}.} -\sectionauthor{Skip Montanaro}{skip@automatrix.com} - - -The \module{stat} module defines constants and functions for -interpreting the results of \function{os.stat()}, -\function{os.fstat()} and \function{os.lstat()} (if they exist). For -complete details about the \cfunction{stat()}, \cfunction{fstat()} and -\cfunction{lstat()} calls, consult the documentation for your system. - -The \module{stat} module defines the following functions to test for -specific file types: - - -\begin{funcdesc}{S_ISDIR}{mode} -Return non-zero if the mode is from a directory. -\end{funcdesc} - -\begin{funcdesc}{S_ISCHR}{mode} -Return non-zero if the mode is from a character special device file. -\end{funcdesc} - -\begin{funcdesc}{S_ISBLK}{mode} -Return non-zero if the mode is from a block special device file. -\end{funcdesc} - -\begin{funcdesc}{S_ISREG}{mode} -Return non-zero if the mode is from a regular file. -\end{funcdesc} - -\begin{funcdesc}{S_ISFIFO}{mode} -Return non-zero if the mode is from a FIFO (named pipe). -\end{funcdesc} - -\begin{funcdesc}{S_ISLNK}{mode} -Return non-zero if the mode is from a symbolic link. -\end{funcdesc} - -\begin{funcdesc}{S_ISSOCK}{mode} -Return non-zero if the mode is from a socket. -\end{funcdesc} - -Two additional functions are defined for more general manipulation of -the file's mode: - -\begin{funcdesc}{S_IMODE}{mode} -Return the portion of the file's mode that can be set by -\function{os.chmod()}---that is, the file's permission bits, plus the -sticky bit, set-group-id, and set-user-id bits (on systems that support -them). -\end{funcdesc} - -\begin{funcdesc}{S_IFMT}{mode} -Return the portion of the file's mode that describes the file type (used -by the \function{S_IS*()} functions above). -\end{funcdesc} - -Normally, you would use the \function{os.path.is*()} functions for -testing the type of a file; the functions here are useful when you are -doing multiple tests of the same file and wish to avoid the overhead of -the \cfunction{stat()} system call for each test. These are also -useful when checking for information about a file that isn't handled -by \refmodule{os.path}, like the tests for block and character -devices. - -All the variables below are simply symbolic indexes into the 10-tuple -returned by \function{os.stat()}, \function{os.fstat()} or -\function{os.lstat()}. - -\begin{datadesc}{ST_MODE} -Inode protection mode. -\end{datadesc} - -\begin{datadesc}{ST_INO} -Inode number. -\end{datadesc} - -\begin{datadesc}{ST_DEV} -Device inode resides on. -\end{datadesc} - -\begin{datadesc}{ST_NLINK} -Number of links to the inode. -\end{datadesc} - -\begin{datadesc}{ST_UID} -User id of the owner. -\end{datadesc} - -\begin{datadesc}{ST_GID} -Group id of the owner. -\end{datadesc} - -\begin{datadesc}{ST_SIZE} -Size in bytes of a plain file; amount of data waiting on some special -files. -\end{datadesc} - -\begin{datadesc}{ST_ATIME} -Time of last access. -\end{datadesc} - -\begin{datadesc}{ST_MTIME} -Time of last modification. -\end{datadesc} - -\begin{datadesc}{ST_CTIME} -The ``ctime'' as reported by the operating system. On some systems -(like \UNIX) is the time of the last metadata change, and, on others -(like Windows), is the creation time (see platform documentation for -details). -\end{datadesc} - -The interpretation of ``file size'' changes according to the file -type. For plain files this is the size of the file in bytes. For -FIFOs and sockets under most flavors of \UNIX{} (including Linux in -particular), the ``size'' is the number of bytes waiting to be read at -the time of the call to \function{os.stat()}, \function{os.fstat()}, -or \function{os.lstat()}; this can sometimes be useful, especially for -polling one of these special files after a non-blocking open. The -meaning of the size field for other character and block devices varies -more, depending on the implementation of the underlying system call. - -Example: - -\begin{verbatim} -import os, sys -from stat import * - -def walktree(top, callback): - '''recursively descend the directory tree rooted at top, - calling the callback function for each regular file''' - - for f in os.listdir(top): - pathname = os.path.join(top, f) - mode = os.stat(pathname)[ST_MODE] - if S_ISDIR(mode): - # It's a directory, recurse into it - walktree(pathname, callback) - elif S_ISREG(mode): - # It's a file, call the callback function - callback(pathname) - else: - # Unknown file type, print a message - print 'Skipping %s' % pathname - -def visitfile(file): - print 'visiting', file - -if __name__ == '__main__': - walktree(sys.argv[1], visitfile) -\end{verbatim} diff --git a/Doc/lib/libstatvfs.tex b/Doc/lib/libstatvfs.tex deleted file mode 100644 index 2dc8933..0000000 --- a/Doc/lib/libstatvfs.tex +++ /dev/null @@ -1,55 +0,0 @@ -\section{\module{statvfs} --- - Constants used with \function{os.statvfs()}} - -\declaremodule{standard}{statvfs} -% LaTeX'ed from comments in module -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Constants for interpreting the result of - \function{os.statvfs()}.} - -The \module{statvfs} module defines constants so interpreting the result -if \function{os.statvfs()}, which returns a tuple, can be made without -remembering ``magic numbers.'' Each of the constants defined in this -module is the \emph{index} of the entry in the tuple returned by -\function{os.statvfs()} that contains the specified information. - - -\begin{datadesc}{F_BSIZE} -Preferred file system block size. -\end{datadesc} - -\begin{datadesc}{F_FRSIZE} -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} - -\begin{datadesc}{F_BAVAIL} -Free blocks available to non-super user. -\end{datadesc} - -\begin{datadesc}{F_FILES} -Total number of file nodes. -\end{datadesc} - -\begin{datadesc}{F_FFREE} -Total number of free file nodes. -\end{datadesc} - -\begin{datadesc}{F_FAVAIL} -Free nodes available to non-super user. -\end{datadesc} - -\begin{datadesc}{F_FLAG} -Flags. System dependent: see \cfunction{statvfs()} man page. -\end{datadesc} - -\begin{datadesc}{F_NAMEMAX} -Maximum file name length. -\end{datadesc} diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex deleted file mode 100644 index 95033f9..0000000 --- a/Doc/lib/libstdtypes.tex +++ /dev/null @@ -1,2070 +0,0 @@ -\chapter{Built-in Types \label{types}} - -The following sections describe the standard types that are built into -the interpreter. -\note{Historically (until release 2.2), Python's built-in types have -differed from user-defined types because it was not possible to use -the built-in types as the basis for object-oriented inheritance. -This limitation does not exist any longer.} - -The principal built-in types are numerics, sequences, mappings, files, -classes, instances and exceptions. -\indexii{built-in}{types} - -Some operations are supported by several object types; in particular, -practically all objects can be compared, tested for truth value, -and converted to a string (with -the \function{repr()} function or the slightly different -\function{str()} function). The latter -function is implicitly used when an object is written by the -\keyword{print}\stindex{print} statement. -(Information on the \ulink{\keyword{print} statement}{../ref/print.html} -and other language statements can be found in the -\citetitle[../ref/ref.html]{Python Reference Manual} and the -\citetitle[../tut/tut.html]{Python Tutorial}.) - - -\section{Truth Value Testing\label{truth}} - -Any object can be tested for truth value, for use in an \keyword{if} or -\keyword{while} condition or as operand of the Boolean operations below. -The following values are considered false: -\stindex{if} -\stindex{while} -\indexii{truth}{value} -\indexii{Boolean}{operations} -\index{false} - -\begin{itemize} - -\item \code{None} - \withsubitem{(Built-in object)}{\ttindex{None}} - -\item \code{False} - \withsubitem{(Built-in object)}{\ttindex{False}} - -\item zero of any numeric type, for example, \code{0}, \code{0L}, - \code{0.0}, \code{0j}. - -\item any empty sequence, for example, \code{''}, \code{()}, \code{[]}. - -\item any empty mapping, for example, \code{\{\}}. - -\item instances of user-defined classes, if the class defines a - \method{__bool__()} or \method{__len__()} method, when that - method returns the integer zero or \class{bool} value - \code{False}.\footnote{Additional -information on these special methods may be found in the -\citetitle[../ref/ref.html]{Python Reference Manual}.} - -\end{itemize} - -All other values are considered true --- so objects of many types are -always true. -\index{true} - -Operations and built-in functions that have a Boolean result always -return \code{0} or \code{False} for false and \code{1} or \code{True} -for true, unless otherwise stated. (Important exception: the Boolean -operations \samp{or}\opindex{or} and \samp{and}\opindex{and} always -return one of their operands.) -\index{False} -\index{True} - -\section{Boolean Operations --- - \keyword{and}, \keyword{or}, \keyword{not} - \label{boolean}} - -These are the Boolean operations, ordered by ascending priority: -\indexii{Boolean}{operations} - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{x} or \var{y}} - {if \var{x} is false, then \var{y}, else \var{x}}{(1)} - \lineiii{\var{x} and \var{y}} - {if \var{x} is false, then \var{x}, else \var{y}}{(1)} - \hline - \lineiii{not \var{x}} - {if \var{x} is false, then \code{True}, else \code{False}}{(2)} -\end{tableiii} -\opindex{and} -\opindex{or} -\opindex{not} - -\noindent -Notes: - -\begin{description} - -\item[(1)] -These only evaluate their second argument if needed for their outcome. - -\item[(2)] -\samp{not} has a lower priority than non-Boolean operators, so -\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} - - -\section{Comparisons \label{comparisons}} - -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; 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: - -\begin{tableiii}{c|l|c}{code}{Operation}{Meaning}{Notes} - \lineiii{<}{strictly less than}{} - \lineiii{<=}{less than or equal}{} - \lineiii{>}{strictly greater than}{} - \lineiii{>=}{greater than or equal}{} - \lineiii{==}{equal}{} - \lineiii{!=}{not equal}{} - \lineiii{is}{object identity}{} - \lineiii{is not}{negated object identity}{} -\end{tableiii} -\indexii{operator}{comparison} -\opindex{==} % XXX *All* others have funny characters < ! > -\opindex{is} -\opindex{is not} - -Objects of different types, except different numeric types and different string types, never -compare equal; such objects are ordered consistently but arbitrarily -(so that sorting a heterogeneous array yields a consistent result). -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. The \code{<}, \code{<=}, \code{>} and \code{>=} -operators will raise a \exception{TypeError} exception when any operand -is a complex number. -\indexii{object}{numeric} -\indexii{objects}{comparing} - -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 -\citetitle[../ref/customization.html]{Python Reference Manual} for -information on the use of this method to effect object comparisons. - -\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). - - -\section{Numeric Types --- - \class{int}, \class{float}, \class{long}, \class{complex} - \label{typesnumeric}} - -There are four distinct numeric types: \dfn{plain integers}, -\dfn{long integers}, -\dfn{floating point numbers}, and \dfn{complex numbers}. -In addition, Booleans are a subtype of plain integers. -Plain integers (also just called \dfn{integers}) -are implemented using \ctype{long} in C, which gives them at least 32 -bits of precision (\code{sys.maxint} is always set to the maximum -plain integer value for the current platform, the minimum value is -\code{-sys.maxint - 1}). Long integers have unlimited precision. -Floating 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. -\obindex{numeric} -\obindex{Boolean} -\obindex{integer} -\obindex{long integer} -\obindex{floating point} -\obindex{complex number} -\indexii{C}{language} - -Complex numbers have a real and imaginary part, which are each -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 unless the value they denote -is too large to be represented as a plain integer, in which case -they yield a long integer. 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 with a -zero real part. A complex numeric literal is the sum of a real and -an imaginary part. -\indexii{numeric}{literals} -\indexii{integer}{literals} -\indexiii{long}{integer}{literals} -\indexii{floating point}{literals} -\indexii{complex number}{literals} -\indexii{hexadecimal}{literals} -\indexii{octal}{literals} - -Python fully supports mixed arithmetic: when a binary arithmetic -operator has operands of different numeric types, the operand with the -``narrower'' type is widened to that of the other, where plain -integer is narrower than long integer is narrower than floating point is -narrower than complex. -Comparisons between numbers of mixed type use the same rule.\footnote{ - As a consequence, the list \code{[1, 2]} is considered equal - to \code{[1.0, 2.0]}, and similarly for tuples. -} The constructors \function{int()}, \function{long()}, \function{float()}, -and \function{complex()} can be used -to produce numbers of a specific type. -\index{arithmetic} -\bifuncindex{int} -\bifuncindex{long} -\bifuncindex{float} -\bifuncindex{complex} - -All numeric types (except complex) support the following operations, -sorted by ascending priority (operations in the same box have the same -priority; all numeric operations have a higher priority than -comparison operations): - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{} - \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{} - \hline - \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{} - \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(1)} - \lineiii{\var{x} // \var{y}}{(floored) quotient of \var{x} and \var{y}}{(5)} - \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{(4)} - \hline - \lineiii{-\var{x}}{\var{x} negated}{} - \lineiii{+\var{x}}{\var{x} unchanged}{} - \hline - \lineiii{abs(\var{x})}{absolute value or magnitude of \var{x}}{} - \lineiii{int(\var{x})}{\var{x} converted to integer}{(2)} - \lineiii{long(\var{x})}{\var{x} converted to long integer}{(2)} - \lineiii{float(\var{x})}{\var{x} converted to floating point}{} - \lineiii{complex(\var{re},\var{im})}{a complex number with real part \var{re}, imaginary part \var{im}. \var{im} defaults to zero.}{} - \lineiii{\var{c}.conjugate()}{conjugate of the complex number \var{c}}{} - \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} // \var{y}, \var{x} \%{} \var{y})}}{(3)(4)} - \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{} - \lineiii{\var{x} ** \var{y}}{\var{x} to the power \var{y}}{} -\end{tableiii} -\indexiii{operations on}{numeric}{types} -\withsubitem{(complex number method)}{\ttindex{conjugate()}} - -\noindent -Notes: -\begin{description} - -\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. 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 the \refmodule{math}\refbimodindex{math} module -for well-defined conversions. -\withsubitem{(in module math)}{\ttindex{floor()}\ttindex{ceil()}} -\indexii{numeric}{conversions} -\indexii{C}{language} - -\item[(3)] -See section \ref{built-in-funcs}, ``Built-in Functions,'' for a full -description. - -\item[(4)] -Complex floor division operator, modulo operator, and \function{divmod()}. - -\deprecated{2.3}{Instead convert to float using \function{abs()} -if appropriate.} - -\item[(5)] -Also referred to as integer division. The resultant value is a whole integer, -though the result's type is not necessarily int. -\end{description} -% XXXJH exceptions: overflow (when? what operations?) zerodivision - -\subsection{Bit-string Operations on Integer Types \label{bitstring-ops}} -\nodename{Bit-string Operations} - -Plain and long integer types support additional operations that make -sense only for bit-strings. Negative numbers are treated as their 2's -complement value (for long integers, this assumes a sufficiently large -number of bits that no overflow occurs during the operation). - -The priorities of the binary bit-wise operations are all lower than -the numeric operations and higher than the comparisons; the unary -operation \samp{\~} has the same priority as the other unary numeric -operations (\samp{+} and \samp{-}). - -This table lists the bit-string operations sorted in ascending -priority (operations in the same box have the same priority): - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{} - \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{} - \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{} - % The empty groups below prevent conversion to guillemets. - \lineiii{\var{x} <{}< \var{n}}{\var{x} shifted left by \var{n} bits}{(1), (2)} - \lineiii{\var{x} >{}> \var{n}}{\var{x} shifted right by \var{n} bits}{(1), (3)} - \hline - \lineiii{\~\var{x}}{the bits of \var{x} inverted}{} -\end{tableiii} -\indexiii{operations on}{integer}{types} -\indexii{bit-string}{operations} -\indexii{shifting}{operations} -\indexii{masking}{operations} - -\noindent -Notes: -\begin{description} -\item[(1)] Negative shift counts are illegal and cause a -\exception{ValueError} to be raised. -\item[(2)] A left shift by \var{n} bits is equivalent to -multiplication by \code{pow(2, \var{n})} without overflow check. -\item[(3)] A right shift by \var{n} bits is equivalent to -division by \code{pow(2, \var{n})} without overflow check. -\end{description} - - -\section{Iterator Types \label{typeiter}} - -\versionadded{2.2} -\index{iterator protocol} -\index{protocol!iterator} -\index{sequence!iteration} -\index{container!iteration over} - -Python supports a concept of iteration over containers. This is -implemented using two distinct methods; these are used to allow -user-defined classes to support iteration. Sequences, described below -in more detail, always support the iteration methods. - -One method needs to be defined for container objects to provide -iteration support: - -\begin{methoddesc}[container]{__iter__}{} - Return an iterator object. The object is required to support the - iterator protocol described below. If a container supports - different types of iteration, additional methods can be provided to - specifically request iterators for those iteration types. (An - example of an object supporting multiple forms of iteration would be - a tree structure which supports both breadth-first and depth-first - traversal.) This method corresponds to the \member{tp_iter} slot of - the type structure for Python objects in the Python/C API. -\end{methoddesc} - -The iterator objects themselves are required to support the following -two methods, which together form the \dfn{iterator protocol}: - -\begin{methoddesc}[iterator]{__iter__}{} - Return the iterator object itself. This is required to allow both - containers and iterators to be used with the \keyword{for} and - \keyword{in} statements. This method corresponds to the - \member{tp_iter} slot of the type structure for Python objects in - the Python/C API. -\end{methoddesc} - -\begin{methoddesc}[iterator]{next}{} - Return the next item from the container. If there are no further - items, raise the \exception{StopIteration} exception. This method - corresponds to the \member{tp_iternext} slot of the type structure - for Python objects in the Python/C API. -\end{methoddesc} - -Python defines several iterator objects to support iteration over -general and specific sequence types, dictionaries, and other more -specialized forms. The specific types are not important beyond their -implementation of the iterator protocol. - -The intention of the protocol is that once an iterator's \method{__next__()} -method raises \exception{StopIteration}, it will continue to do so on subsequent -calls. Implementations that do not obey this property are deemed broken. (This -constraint was added in Python 2.3; in Python 2.2, various iterators are broken -according to this rule.) - -Python's generators provide a convenient way to implement the iterator protocol. -If a container object's \method{__iter__()} method is implemented as a -generator, it will automatically return an iterator object (technically, a -generator object) supplying the \method{__iter__()} and \method{__next__()} -methods. - - -\section{Sequence Types --- - \class{str}, \class{unicode}, \class{list}, - \class{tuple}, \class{buffer}, \class{range} - \label{typesseq}} - -There are six sequence types: strings, Unicode strings, lists, -tuples, buffers, and range objects. - -String literals are written in single or double quotes: -\code{'xyzzy'}, \code{"frobozz"}. See chapter 2 of the -\citetitle[../ref/strings.html]{Python Reference Manual} for more about -string literals. Unicode strings are much like strings, but are -specified in the syntax using a preceding \character{u} character: -\code{u'abc'}, \code{u"def"}. Lists are constructed with square brackets, -separating items with commas: \code{[a, b, c]}. Tuples are -constructed by the comma operator (not within square brackets), with -or without enclosing parentheses, but an empty tuple must have the -enclosing parentheses, such as \code{a, b, c} or \code{()}. A single -item tuple must have a trailing comma, such as \code{(d,)}. -\obindex{sequence} -\obindex{string} -\obindex{Unicode} -\obindex{tuple} -\obindex{list} - -Buffer objects are not directly supported by Python syntax, but can be -created by calling the builtin function -\function{buffer()}.\bifuncindex{buffer} They don't support -concatenation or repetition. -\obindex{buffer} - -Xrange objects are similar to buffers in that there is no specific -syntax to create them, but they are created using the \function{range()} -function.\bifuncindex{range} They don't support slicing, -concatenation or repetition, and using \code{in}, \code{not in}, -\function{min()} or \function{max()} on them is inefficient. -\obindex{range} - -Most sequence types support the following operations. The \samp{in} and -\samp{not in} operations have the same priorities as the comparison -operations. The \samp{+} and \samp{*} operations have the same -priority as the corresponding numeric operations.\footnote{They must -have since the parser can't tell the type of the operands.} - -This table lists the sequence operations sorted in ascending priority -(operations in the same box have the same priority). In the table, -\var{s} and \var{t} are sequences of the same type; \var{n}, \var{i} -and \var{j} are integers: - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{x} in \var{s}}{\code{True} if an item of \var{s} is equal to \var{x}, else \code{False}}{(1)} - \lineiii{\var{x} not in \var{s}}{\code{False} if an item of \var{s} is -equal to \var{x}, else \code{True}}{(1)} - \hline - \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{(6)} - \lineiii{\var{s} * \var{n}\textrm{,} \var{n} * \var{s}}{\var{n} shallow copies of \var{s} concatenated}{(2)} - \hline - \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(3)} - \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(3), (4)} - \lineiii{\var{s}[\var{i}:\var{j}:\var{k}]}{slice of \var{s} from \var{i} to \var{j} with step \var{k}}{(3), (5)} - \hline - \lineiii{len(\var{s})}{length of \var{s}}{} - \lineiii{min(\var{s})}{smallest item of \var{s}}{} - \lineiii{max(\var{s})}{largest item of \var{s}}{} -\end{tableiii} -\indexiii{operations on}{sequence}{types} -\bifuncindex{len} -\bifuncindex{min} -\bifuncindex{max} -\indexii{concatenation}{operation} -\indexii{repetition}{operation} -\indexii{subscript}{operation} -\indexii{slice}{operation} -\indexii{extended slice}{operation} -\opindex{in} -\opindex{not in} - -\noindent -Notes: - -\begin{description} -\item[(1)] When \var{s} is a string or Unicode string object the -\code{in} and \code{not in} operations act like a substring test. In -Python versions before 2.3, \var{x} had to be a string of length 1. -In Python 2.3 and beyond, \var{x} may be a string of any length. - -\item[(2)] 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}). Note also that the copies are shallow; nested structures - are not copied. This often haunts new Python programmers; consider: - -\begin{verbatim} ->>> lists = [[]] * 3 ->>> lists -[[], [], []] ->>> lists[0].append(3) ->>> lists -[[3], [3], [3]] -\end{verbatim} - - What has happened is that \code{[[]]} is a one-element list containing - an empty list, so all three elements of \code{[[]] * 3} are (pointers to) - this single empty list. Modifying any of the elements of \code{lists} - modifies this single list. You can create a list of different lists this - way: - -\begin{verbatim} ->>> lists = [[] for i in range(3)] ->>> lists[0].append(3) ->>> lists[1].append(5) ->>> lists[2].append(7) ->>> lists -[[3], [5], [7]] -\end{verbatim} - -\item[(3)] If \var{i} or \var{j} is negative, the index is relative to - the end of the string: \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[(4)] 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 - or \code{None}, use \code{0}. If \var{j} is omitted or \code{None}, - use \code{len(\var{s})}. If \var{i} is greater than or equal to \var{j}, - the slice is empty. - -\item[(5)] The slice of \var{s} from \var{i} to \var{j} with step - \var{k} is defined as the sequence of items with index - \code{\var{x} = \var{i} + \var{n}*\var{k}} such that - $0 \leq n < \frac{j-i}{k}$. In other words, the indices - are \code{i}, \code{i+k}, \code{i+2*k}, \code{i+3*k} and so on, stopping when - \var{j} is reached (but never including \var{j}). If \var{i} or \var{j} - is greater than \code{len(\var{s})}, use \code{len(\var{s})}. If - \var{i} or \var{j} are omitted or \code{None}, they become ``end'' values - (which end depends on the sign of \var{k}). Note, \var{k} cannot - be zero. If \var{k} is \code{None}, it is treated like \code{1}. - -\item[(6)] If \var{s} and \var{t} are both strings, some Python -implementations such as CPython can usually perform an in-place optimization -for assignments of the form \code{\var{s}=\var{s}+\var{t}} or -\code{\var{s}+=\var{t}}. When applicable, this optimization makes -quadratic run-time much less likely. This optimization is both version -and implementation dependent. For performance sensitive code, it is -preferable to use the \method{str.join()} method which assures consistent -linear concatenation performance across versions and implementations. -\versionchanged[Formerly, string concatenation never occurred in-place]{2.4} - -\end{description} - - -\subsection{String Methods \label{string-methods}} -\indexii{string}{methods} - -These are the string methods which both 8-bit strings and Unicode -objects support: - -\begin{methoddesc}[str]{capitalize}{} -Return a copy of the string with only its first character capitalized. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{center}{width\optional{, fillchar}} -Return centered in a string of length \var{width}. Padding is done -using the specified \var{fillchar} (default is a space). -\versionchanged[Support for the \var{fillchar} argument]{2.4} -\end{methoddesc} - -\begin{methoddesc}[str]{count}{sub\optional{, start\optional{, end}}} -Return the number of occurrences of substring \var{sub} in string -S\code{[\var{start}:\var{end}]}. Optional arguments \var{start} and -\var{end} are interpreted as in slice notation. -\end{methoddesc} - -\begin{methoddesc}[str]{decode}{\optional{encoding\optional{, errors}}} -Decodes the string using the codec registered for \var{encoding}. -\var{encoding} defaults to the default string encoding. \var{errors} -may be given to set a different error handling scheme. The default is -\code{'strict'}, meaning that encoding errors raise -\exception{UnicodeError}. Other possible values are \code{'ignore'}, -\code{'replace'} and any other name registered via -\function{codecs.register_error}, see section~\ref{codec-base-classes}. -\versionadded{2.2} -\versionchanged[Support for other error handling schemes added]{2.3} -\end{methoddesc} - -\begin{methoddesc}[str]{encode}{\optional{encoding\optional{,errors}}} -Return an encoded version of the string. Default encoding is the current -default string encoding. \var{errors} may be given to set a different -error handling scheme. The default for \var{errors} is -\code{'strict'}, meaning that encoding errors raise a -\exception{UnicodeError}. Other possible values are \code{'ignore'}, -\code{'replace'}, \code{'xmlcharrefreplace'}, \code{'backslashreplace'} -and any other name registered via \function{codecs.register_error}, -see section~\ref{codec-base-classes}. -For a list of possible encodings, see section~\ref{standard-encodings}. -\versionadded{2.0} -\versionchanged[Support for \code{'xmlcharrefreplace'} and -\code{'backslashreplace'} and other error handling schemes added]{2.3} -\end{methoddesc} - -\begin{methoddesc}[str]{endswith}{suffix\optional{, start\optional{, end}}} -Return \code{True} if the string ends with the specified \var{suffix}, -otherwise return \code{False}. \var{suffix} can also be a tuple of -suffixes to look for. With optional \var{start}, test beginning at -that position. With optional \var{end}, stop comparing at that position. - -\versionchanged[Accept tuples as \var{suffix}]{2.5} -\end{methoddesc} - -\begin{methoddesc}[str]{expandtabs}{\optional{tabsize}} -Return a copy of the string where all tab characters are expanded -using spaces. If \var{tabsize} is not given, a tab size of \code{8} -characters is assumed. -\end{methoddesc} - -\begin{methoddesc}[str]{find}{sub\optional{, start\optional{, end}}} -Return the lowest index in the string where substring \var{sub} is -found, such that \var{sub} is contained in the range [\var{start}, -\var{end}]. Optional arguments \var{start} and \var{end} are -interpreted as in slice notation. Return \code{-1} if \var{sub} is -not found. -\end{methoddesc} - -\begin{methoddesc}[str]{index}{sub\optional{, start\optional{, end}}} -Like \method{find()}, but raise \exception{ValueError} when the -substring is not found. -\end{methoddesc} - -\begin{methoddesc}[str]{isalnum}{} -Return true if all characters in the string are alphanumeric and there -is at least one character, false otherwise. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{isalpha}{} -Return true if all characters in the string are alphabetic and there -is at least one character, false otherwise. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{isdigit}{} -Return true if all characters in the string are digits and there -is at least one character, false otherwise. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{isidentifier}{} -Return True if S is a valid identifier according -to the language definition. -\end{methoddesc} - -\begin{methoddesc}[str]{islower}{} -Return true if all cased characters in the string are lowercase and -there is at least one cased character, false otherwise. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{isspace}{} -Return true if there are only whitespace characters in the string and -there is at least one character, false otherwise. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{istitle}{} -Return true if the string is a titlecased string and there is at least one -character, for example uppercase characters may only follow uncased -characters and lowercase characters only cased ones. Return false -otherwise. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{isupper}{} -Return true if all cased characters in the string are uppercase and -there is at least one cased character, false otherwise. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{join}{seq} -Return a string which is the concatenation of the strings in the -sequence \var{seq}. The separator between elements is the string -providing this method. -\end{methoddesc} - -\begin{methoddesc}[str]{ljust}{width\optional{, fillchar}} -Return the string left justified in a string of length \var{width}. -Padding is done using the specified \var{fillchar} (default is a -space). The original string is returned if -\var{width} is less than \code{len(\var{s})}. -\versionchanged[Support for the \var{fillchar} argument]{2.4} -\end{methoddesc} - -\begin{methoddesc}[str]{lower}{} -Return a copy of the string converted to lowercase. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{lstrip}{\optional{chars}} -Return a copy of the string with leading characters removed. The -\var{chars} argument is a string specifying the set of characters -to be removed. If omitted or \code{None}, the \var{chars} argument -defaults to removing whitespace. The \var{chars} argument is not -a prefix; rather, all combinations of its values are stripped: -\begin{verbatim} - >>> ' spacious '.lstrip() - 'spacious ' - >>> 'www.example.com'.lstrip('cmowz.') - 'example.com' -\end{verbatim} -\versionchanged[Support for the \var{chars} argument]{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[str]{partition}{sep} -Split the string at the first occurrence of \var{sep}, and return -a 3-tuple containing the part before the separator, the separator -itself, and the part after the separator. If the separator is not -found, return a 3-tuple containing the string itself, followed by -two empty strings. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[str]{replace}{old, new\optional{, count}} -Return a copy of the string with all occurrences of substring -\var{old} replaced by \var{new}. If the optional argument -\var{count} is given, only the first \var{count} occurrences are -replaced. -\end{methoddesc} - -\begin{methoddesc}[str]{rfind}{sub \optional{,start \optional{,end}}} -Return the highest index in the string where substring \var{sub} is -found, such that \var{sub} is contained within s[start,end]. Optional -arguments \var{start} and \var{end} are interpreted as in slice -notation. Return \code{-1} on failure. -\end{methoddesc} - -\begin{methoddesc}[str]{rindex}{sub\optional{, start\optional{, end}}} -Like \method{rfind()} but raises \exception{ValueError} when the -substring \var{sub} is not found. -\end{methoddesc} - -\begin{methoddesc}[str]{rjust}{width\optional{, fillchar}} -Return the string right justified in a string of length \var{width}. -Padding is done using the specified \var{fillchar} (default is a space). -The original string is returned if -\var{width} is less than \code{len(\var{s})}. -\versionchanged[Support for the \var{fillchar} argument]{2.4} -\end{methoddesc} - -\begin{methoddesc}[str]{rpartition}{sep} -Split the string at the last occurrence of \var{sep}, and return -a 3-tuple containing the part before the separator, the separator -itself, and the part after the separator. If the separator is not -found, return a 3-tuple containing two empty strings, followed by -the string itself. -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[str]{rsplit}{\optional{sep \optional{,maxsplit}}} -Return a list of the words in the string, using \var{sep} as the -delimiter string. If \var{maxsplit} is given, at most \var{maxsplit} -splits are done, the \emph{rightmost} ones. If \var{sep} is not specified -or \code{None}, any whitespace string is a separator. Except for splitting -from the right, \method{rsplit()} behaves like \method{split()} which -is described in detail below. -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[str]{rstrip}{\optional{chars}} -Return a copy of the string with trailing characters removed. The -\var{chars} argument is a string specifying the set of characters -to be removed. If omitted or \code{None}, the \var{chars} argument -defaults to removing whitespace. The \var{chars} argument is not -a suffix; rather, all combinations of its values are stripped: -\begin{verbatim} - >>> ' spacious '.rstrip() - ' spacious' - >>> 'mississippi'.rstrip('ipz') - 'mississ' -\end{verbatim} -\versionchanged[Support for the \var{chars} argument]{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[str]{split}{\optional{sep \optional{,maxsplit}}} -Return a list of the words in the string, using \var{sep} as the -delimiter string. If \var{maxsplit} is given, at most \var{maxsplit} -splits are done. (thus, the list will have at most \code{\var{maxsplit}+1} -elements). If \var{maxsplit} is not specified, then there -is no limit on the number of splits (all possible splits are made). -Consecutive delimiters are not grouped together and are -deemed to delimit empty strings (for example, \samp{'1,,2'.split(',')} -returns \samp{['1', '', '2']}). The \var{sep} argument may consist of -multiple characters (for example, \samp{'1, 2, 3'.split(', ')} returns -\samp{['1', '2', '3']}). Splitting an empty string with a specified -separator returns \samp{['']}. - -If \var{sep} is not specified or is \code{None}, a different splitting -algorithm is applied. First, whitespace characters (spaces, tabs, -newlines, returns, and formfeeds) are stripped from both ends. Then, -words are separated by arbitrary length strings of whitespace -characters. Consecutive whitespace delimiters are treated as a single -delimiter (\samp{'1 2 3'.split()} returns \samp{['1', '2', '3']}). -Splitting an empty string or a string consisting of just whitespace -returns an empty list. -\end{methoddesc} - -\begin{methoddesc}[str]{splitlines}{\optional{keepends}} -Return a list of the lines in the string, breaking at line -boundaries. Line breaks are not included in the resulting list unless -\var{keepends} is given and true. -\end{methoddesc} - -\begin{methoddesc}[str]{startswith}{prefix\optional{, - start\optional{, end}}} -Return \code{True} if string starts with the \var{prefix}, otherwise -return \code{False}. \var{prefix} can also be a tuple of -prefixes to look for. With optional \var{start}, test string beginning at -that position. With optional \var{end}, stop comparing string at that -position. - -\versionchanged[Accept tuples as \var{prefix}]{2.5} -\end{methoddesc} - -\begin{methoddesc}[str]{strip}{\optional{chars}} -Return a copy of the string with the leading and trailing characters -removed. The \var{chars} argument is a string specifying the set of -characters to be removed. If omitted or \code{None}, the \var{chars} -argument defaults to removing whitespace. The \var{chars} argument is not -a prefix or suffix; rather, all combinations of its values are stripped: -\begin{verbatim} - >>> ' spacious '.strip() - 'spacious' - >>> 'www.example.com'.strip('cmowz.') - 'example' -\end{verbatim} -\versionchanged[Support for the \var{chars} argument]{2.2.2} -\end{methoddesc} - -\begin{methoddesc}[str]{swapcase}{} -Return a copy of the string with uppercase characters converted to -lowercase and vice versa. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{title}{} -Return a titlecased version of the string: words start with uppercase -characters, all remaining cased characters are lowercase. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{translate}{table\optional{, deletechars}} -Return a copy of the string where all characters occurring in the -optional argument \var{deletechars} are removed, and the remaining -characters have been mapped through the given translation table, which -must be a string of length 256. - -You can use the \function{maketrans()} helper function in the -\refmodule{string} module to create a translation table. -For string objects, set the \var{table} argument to \code{None} -for translations that only delete characters: -\begin{verbatim} - >>> 'read this short text'.translate(None, 'aeiou') - 'rd ths shrt txt' -\end{verbatim} -\versionadded[Support for a \code{None} \var{table} argument]{2.6} - -For Unicode objects, the \method{translate()} method does not -accept the optional \var{deletechars} argument. Instead, it -returns a copy of the \var{s} where all characters have been mapped -through the given translation table which must be a mapping of -Unicode ordinals to Unicode ordinals, Unicode strings or \code{None}. -Unmapped characters are left untouched. Characters mapped to \code{None} -are deleted. Note, a more flexible approach is to create a custom -character mapping codec using the \refmodule{codecs} module (see -\module{encodings.cp1251} for an example). -\end{methoddesc} - -\begin{methoddesc}[str]{upper}{} -Return a copy of the string converted to uppercase. - -For 8-bit strings, this method is locale-dependent. -\end{methoddesc} - -\begin{methoddesc}[str]{zfill}{width} -Return the numeric string left filled with zeros in a string -of length \var{width}. The original string is returned if -\var{width} is less than \code{len(\var{s})}. -\versionadded{2.2.2} -\end{methoddesc} - - -\subsection{String Formatting Operations \label{typesseq-strings}} - -\index{formatting, string (\%{})} -\index{interpolation, string (\%{})} -\index{string!formatting} -\index{string!interpolation} -\index{printf-style formatting} -\index{sprintf-style formatting} -\index{\protect\%{} formatting} -\index{\protect\%{} interpolation} - -String and Unicode objects have one unique built-in operation: the -\code{\%} operator (modulo). This is also known as the string -\emph{formatting} or \emph{interpolation} operator. Given -\code{\var{format} \% \var{values}} (where \var{format} is a string or -Unicode object), \code{\%} conversion specifications in \var{format} -are replaced with zero or more elements of \var{values}. The effect -is similar to the using \cfunction{sprintf()} in the C language. If -\var{format} is a Unicode object, or if any of the objects being -converted using the \code{\%s} conversion are Unicode objects, the -result will also be a Unicode object. - -If \var{format} requires a single argument, \var{values} may be a -single non-tuple object.\footnote{To format only a tuple you -should therefore provide a singleton tuple whose only element -is the tuple to be formatted.} Otherwise, \var{values} must be a tuple with -exactly the number of items specified by the format string, or a -single mapping object (for example, a dictionary). - -A conversion specifier contains two or more characters and has the -following components, which must occur in this order: - -\begin{enumerate} - \item The \character{\%} character, which marks the start of the - specifier. - \item Mapping key (optional), consisting of a parenthesised sequence - of characters (for example, \code{(somename)}). - \item Conversion flags (optional), which affect the result of some - conversion types. - \item Minimum field width (optional). If specified as an - \character{*} (asterisk), the actual width is read from the - next element of the tuple in \var{values}, and the object to - convert comes after the minimum field width and optional - precision. - \item Precision (optional), given as a \character{.} (dot) followed - by the precision. If specified as \character{*} (an - asterisk), the actual width is read from the next element of - the tuple in \var{values}, and the value to convert comes after - the precision. - \item Length modifier (optional). - \item Conversion type. -\end{enumerate} - -When the right argument is a dictionary (or other mapping type), then -the formats in the string \emph{must} include a parenthesised mapping key into -that dictionary inserted immediately after the \character{\%} -character. The mapping key selects the value to be formatted from the -mapping. For example: - -\begin{verbatim} ->>> print '%(language)s has %(#)03d quote types.' % \ - {'language': "Python", "#": 2} -Python has 002 quote types. -\end{verbatim} - -In this case no \code{*} specifiers may occur in a format (since they -require a sequential parameter list). - -The conversion flag characters are: - -\begin{tableii}{c|l}{character}{Flag}{Meaning} - \lineii{\#}{The value conversion will use the ``alternate form'' - (where defined below).} - \lineii{0}{The conversion will be zero padded for numeric values.} - \lineii{-}{The converted value is left adjusted (overrides - the \character{0} conversion if both are given).} - \lineii{{~}}{(a space) A blank should be left before a positive number - (or empty string) produced by a signed conversion.} - \lineii{+}{A sign character (\character{+} or \character{-}) will - precede the conversion (overrides a "space" flag).} -\end{tableii} - -A length modifier (\code{h}, \code{l}, or \code{L}) may be -present, but is ignored as it is not necessary for Python. - -The conversion types are: - -\begin{tableiii}{c|l|c}{character}{Conversion}{Meaning}{Notes} - \lineiii{d}{Signed integer decimal.}{} - \lineiii{i}{Signed integer decimal.}{} - \lineiii{o}{Unsigned octal.}{(1)} - \lineiii{u}{Unsigned decimal.}{} - \lineiii{x}{Unsigned hexadecimal (lowercase).}{(2)} - \lineiii{X}{Unsigned hexadecimal (uppercase).}{(2)} - \lineiii{e}{Floating point exponential format (lowercase).}{(3)} - \lineiii{E}{Floating point exponential format (uppercase).}{(3)} - \lineiii{f}{Floating point decimal format.}{(3)} - \lineiii{F}{Floating point decimal format.}{(3)} - \lineiii{g}{Floating point format. Uses exponential format - if exponent is greater than -4 or less than precision, - decimal format otherwise.}{(4)} - \lineiii{G}{Floating point format. Uses exponential format - if exponent is greater than -4 or less than precision, - decimal format otherwise.}{(4)} - \lineiii{c}{Single character (accepts integer or single character - string).}{} - \lineiii{r}{String (converts any python object using - \function{repr()}).}{(5)} - \lineiii{s}{String (converts any python object using - \function{str()}).}{(6)} - \lineiii{\%}{No argument is converted, results in a \character{\%} - character in the result.}{} -\end{tableiii} - -\noindent -Notes: -\begin{description} - \item[(1)] - The alternate form causes a leading zero (\character{0}) to be - inserted between left-hand padding and the formatting of the - number if the leading character of the result is not already a - zero. - \item[(2)] - The alternate form causes a leading \code{'0x'} or \code{'0X'} - (depending on whether the \character{x} or \character{X} format - was used) to be inserted between left-hand padding and the - formatting of the number if the leading character of the result is - not already a zero. - \item[(3)] - The alternate form causes the result to always contain a decimal - point, even if no digits follow it. - - The precision determines the number of digits after the decimal - point and defaults to 6. - \item[(4)] - The alternate form causes the result to always contain a decimal - point, and trailing zeroes are not removed as they would - otherwise be. - - The precision determines the number of significant digits before - and after the decimal point and defaults to 6. - \item[(5)] - The \code{\%r} conversion was added in Python 2.0. - - The precision determines the maximal number of characters used. - \item[(6)] - If the object or format provided is a \class{unicode} string, - the resulting string will also be \class{unicode}. - - The precision determines the maximal number of characters used. -\end{description} - -% XXX Examples? - -Since Python strings have an explicit length, \code{\%s} conversions -do not assume that \code{'\e0'} is the end of the string. - -For safety reasons, floating point precisions are clipped to 50; -\code{\%f} conversions for numbers whose absolute value is over 1e25 -are replaced by \code{\%g} conversions.\footnote{ - These numbers are fairly arbitrary. They are intended to - avoid printing endless strings of meaningless digits without hampering - correct use and without having to know the exact precision of floating - point values on a particular machine. -} All other errors raise exceptions. - -Additional string operations are defined in standard modules -\refmodule{string}\refstmodindex{string}\ and -\refmodule{re}.\refstmodindex{re} - - -\subsection{XRange Type \label{typesseq-range}} - -The \class{range}\obindex{range} type is an immutable sequence which -is commonly used for looping. The advantage of the \class{range} -type is that an \class{range} object will always take the same amount -of memory, no matter the size of the range it represents. There are -no consistent performance advantages. - -XRange objects have very little behavior: they only support indexing, -iteration, and the \function{len()} function. - - -\subsection{Mutable Sequence Types \label{typesseq-mutable}} - -List objects support additional operations that allow in-place -modification of the object. -Other mutable sequence types (when added to the language) should -also support these operations. -Strings and tuples are immutable sequence types: such objects cannot -be modified once created. -The following operations are defined on mutable sequence types (where -\var{x} is an arbitrary object): -\indexiii{mutable}{sequence}{types} -\obindex{list} - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{\var{s}[\var{i}] = \var{x}} - {item \var{i} of \var{s} is replaced by \var{x}}{} - \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}} - {slice of \var{s} from \var{i} to \var{j} - is replaced by the contents of the iterable \var{t}}{} - \lineiii{del \var{s}[\var{i}:\var{j}]} - {same as \code{\var{s}[\var{i}:\var{j}] = []}}{} - \lineiii{\var{s}[\var{i}:\var{j}:\var{k}] = \var{t}} - {the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} are replaced by those of \var{t}}{(1)} - \lineiii{del \var{s}[\var{i}:\var{j}:\var{k}]} - {removes the elements of \code{\var{s}[\var{i}:\var{j}:\var{k}]} from the list}{} - \lineiii{\var{s}.append(\var{x})} - {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{(2)} - \lineiii{\var{s}.extend(\var{x})} - {same as \code{\var{s}[len(\var{s}):len(\var{s})] = \var{x}}}{(3)} - \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}\optional{, \var{i}\optional{, \var{j}}})} - {return smallest \var{k} such that \code{\var{s}[\var{k}] == \var{x}} and - \code{\var{i} <= \var{k} < \var{j}}}{(4)} - \lineiii{\var{s}.insert(\var{i}, \var{x})} - {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}}{(5)} - \lineiii{\var{s}.pop(\optional{\var{i}})} - {same as \code{\var{x} = \var{s}[\var{i}]; del \var{s}[\var{i}]; return \var{x}}}{(6)} - \lineiii{\var{s}.remove(\var{x})} - {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(4)} - \lineiii{\var{s}.reverse()} - {reverses the items of \var{s} in place}{(7)} - \lineiii{\var{s}.sort(\optional{\var{cmp}\optional{, - \var{key}\optional{, \var{reverse}}}})} - {sort the items of \var{s} in place}{(7), (8), (9), (10)} -\end{tableiii} -\indexiv{operations on}{mutable}{sequence}{types} -\indexiii{operations on}{sequence}{types} -\indexiii{operations on}{list}{type} -\indexii{subscript}{assignment} -\indexii{slice}{assignment} -\indexii{extended slice}{assignment} -\stindex{del} -\withsubitem{(list method)}{ - \ttindex{append()}\ttindex{extend()}\ttindex{count()}\ttindex{index()} - \ttindex{insert()}\ttindex{pop()}\ttindex{remove()}\ttindex{reverse()} - \ttindex{sort()}} -\noindent -Notes: -\begin{description} -\item[(1)] \var{t} must have the same length as the slice it is - replacing. - -\item[(2)] The C implementation of Python has historically accepted - multiple parameters and implicitly joined them into a tuple; this - no longer works in Python 2.0. Use of this misfeature has been - deprecated since Python 1.4. - -\item[(3)] \var{x} can be any iterable object. - -\item[(4)] Raises \exception{ValueError} when \var{x} is not found in - \var{s}. When a negative index is passed as the second or third parameter - to the \method{index()} method, the list length is added, as for slice - indices. If it is still negative, it is truncated to zero, as for - slice indices. \versionchanged[Previously, \method{index()} didn't - have arguments for specifying start and stop positions]{2.3} - -\item[(5)] When a negative index is passed as the first parameter to - the \method{insert()} method, the list length is added, as for slice - indices. If it is still negative, it is truncated to zero, as for - slice indices. \versionchanged[Previously, all negative indices - were truncated to zero]{2.3} - -\item[(6)] The \method{pop()} method is only supported by the list and - array types. The optional argument \var{i} defaults to \code{-1}, - so that by default the last item is removed and returned. - -\item[(7)] The \method{sort()} and \method{reverse()} methods modify the - list in place for economy of space when sorting or reversing a large - list. To remind you that they operate by side effect, they don't return - the sorted or reversed list. - -\item[(8)] The \method{sort()} method takes optional arguments for - controlling the comparisons. - - \var{cmp} specifies a custom comparison function of two arguments - (list items) which should return a negative, zero or positive number - depending on whether the first argument is considered smaller than, - equal to, or larger than the second argument: - \samp{\var{cmp}=\keyword{lambda} \var{x},\var{y}: - \function{cmp}(x.lower(), y.lower())} - - \var{key} specifies a function of one argument that is used to - extract a comparison key from each list element: - \samp{\var{key}=\function{str.lower}} - - \var{reverse} is a boolean value. If set to \code{True}, then the - list elements are sorted as if each comparison were reversed. - - In general, the \var{key} and \var{reverse} conversion processes are - much faster than specifying an equivalent \var{cmp} function. This is - because \var{cmp} is called multiple times for each list element while - \var{key} and \var{reverse} touch each element only once. - - \versionchanged[Support for \code{None} as an equivalent to omitting - \var{cmp} was added]{2.3} - - \versionchanged[Support for \var{key} and \var{reverse} was added]{2.4} - -\item[(9)] Starting with Python 2.3, the \method{sort()} method is - guaranteed to be stable. A sort is stable if it guarantees not to - change the relative order of elements that compare equal --- this is - helpful for sorting in multiple passes (for example, sort by - department, then by salary grade). - -\item[(10)] While a list is being sorted, the effect of attempting to - mutate, or even inspect, the list is undefined. The C - implementation of Python 2.3 and newer makes the list appear empty - for the duration, and raises \exception{ValueError} if it can detect - that the list has been mutated during a sort. -\end{description} - -\section{Set Types --- - \class{set}, \class{frozenset} - \label{types-set}} -\obindex{set} - -A \dfn{set} object is an unordered collection of distinct hashable objects. -Common uses include membership testing, removing duplicates from a sequence, -and computing mathematical operations such as intersection, union, difference, -and symmetric difference. -\versionadded{2.4} - -Like other collections, sets support \code{\var{x} in \var{set}}, -\code{len(\var{set})}, and \code{for \var{x} in \var{set}}. Being an -unordered collection, sets do not record element position or order of -insertion. Accordingly, sets do not support indexing, slicing, or -other sequence-like behavior. - -There are currently two builtin set types, \class{set} and \class{frozenset}. -The \class{set} type is mutable --- the contents can be changed using methods -like \method{add()} and \method{remove()}. Since it is mutable, it has no -hash value and cannot be used as either a dictionary key or as an element of -another set. The \class{frozenset} type is immutable and hashable --- its -contents cannot be altered after is created; however, it can be used as -a dictionary key or as an element of another set. - -Instances of \class{set} and \class{frozenset} provide the following operations: - -\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result} - \lineiii{len(\var{s})}{}{cardinality of set \var{s}} - - \hline - \lineiii{\var{x} in \var{s}}{} - {test \var{x} for membership in \var{s}} - \lineiii{\var{x} not in \var{s}}{} - {test \var{x} for non-membership in \var{s}} - \lineiii{\var{s}.issubset(\var{t})}{\code{\var{s} <= \var{t}}} - {test whether every element in \var{s} is in \var{t}} - \lineiii{\var{s}.issuperset(\var{t})}{\code{\var{s} >= \var{t}}} - {test whether every element in \var{t} is in \var{s}} - - \hline - \lineiii{\var{s}.union(\var{t})}{\var{s} | \var{t}} - {new set with elements from both \var{s} and \var{t}} - \lineiii{\var{s}.intersection(\var{t})}{\var{s} \&\ \var{t}} - {new set with elements common to \var{s} and \var{t}} - \lineiii{\var{s}.difference(\var{t})}{\var{s} - \var{t}} - {new set with elements in \var{s} but not in \var{t}} - \lineiii{\var{s}.symmetric_difference(\var{t})}{\var{s} \^\ \var{t}} - {new set with elements in either \var{s} or \var{t} but not both} - \lineiii{\var{s}.copy()}{} - {new set with a shallow copy of \var{s}} -\end{tableiii} - -Note, the non-operator versions of \method{union()}, \method{intersection()}, -\method{difference()}, and \method{symmetric_difference()}, -\method{issubset()}, and \method{issuperset()} methods will accept any -iterable as an argument. In contrast, their operator based counterparts -require their arguments to be sets. This precludes error-prone constructions -like \code{set('abc') \&\ 'cbs'} in favor of the more readable -\code{set('abc').intersection('cbs')}. - -Both \class{set} and \class{frozenset} support set to set comparisons. -Two sets are equal if and only if every element of each set is contained in -the other (each is a subset of the other). -A set is less than another set if and only if the first set is a proper -subset of the second set (is a subset, but is not equal). -A set is greater than another set if and only if the first set is a proper -superset of the second set (is a superset, but is not equal). - -Instances of \class{set} are compared to instances of \class{frozenset} based -on their members. For example, \samp{set('abc') == frozenset('abc')} returns -\code{True}. - -The subset and equality comparisons do not generalize to a complete -ordering function. For example, any two disjoint sets are not equal and -are not subsets of each other, so \emph{all} of the following return -\code{False}: \code{\var{a}<\var{b}}, \code{\var{a}==\var{b}}, or -\code{\var{a}>\var{b}}. -Accordingly, sets do not implement the \method{__cmp__} method. - -Since sets only define partial ordering (subset relationships), the output -of the \method{list.sort()} method is undefined for lists of sets. - -Set elements are like dictionary keys; they need to define both -\method{__hash__} and \method{__eq__} methods. - -Binary operations that mix \class{set} instances with \class{frozenset} -return the type of the first operand. For example: -\samp{frozenset('ab') | set('bc')} returns an instance of \class{frozenset}. - -The following table lists operations available for \class{set} -that do not apply to immutable instances of \class{frozenset}: - -\begin{tableiii}{c|c|l}{code}{Operation}{Equivalent}{Result} - \lineiii{\var{s}.update(\var{t})} - {\var{s} |= \var{t}} - {update set \var{s}, adding elements from \var{t}} - \lineiii{\var{s}.intersection_update(\var{t})} - {\var{s} \&= \var{t}} - {update set \var{s}, keeping only elements found in both \var{s} and \var{t}} - \lineiii{\var{s}.difference_update(\var{t})} - {\var{s} -= \var{t}} - {update set \var{s}, removing elements found in \var{t}} - \lineiii{\var{s}.symmetric_difference_update(\var{t})} - {\var{s} \textasciicircum= \var{t}} - {update set \var{s}, keeping only elements found in either \var{s} or \var{t} - but not in both} - - \hline - \lineiii{\var{s}.add(\var{x})}{} - {add element \var{x} to set \var{s}} - \lineiii{\var{s}.remove(\var{x})}{} - {remove \var{x} from set \var{s}; raises \exception{KeyError} - if not present} - \lineiii{\var{s}.discard(\var{x})}{} - {removes \var{x} from set \var{s} if present} - \lineiii{\var{s}.pop()}{} - {remove and return an arbitrary element from \var{s}; raises - \exception{KeyError} if empty} - \lineiii{\var{s}.clear()}{} - {remove all elements from set \var{s}} -\end{tableiii} - -Note, the non-operator versions of the \method{update()}, -\method{intersection_update()}, \method{difference_update()}, and -\method{symmetric_difference_update()} methods will accept any iterable -as an argument. - - -\section{Mapping Types --- \class{dict} \label{typesmapping}} -\obindex{mapping} -\obindex{dictionary} - -A \dfn{mapping} object maps immutable values to -arbitrary objects. Mappings are mutable objects. There is currently -only one standard mapping type, the \dfn{dictionary}. A dictionary's keys are -almost arbitrary values. Only values containing lists, dictionaries -or other mutable types (that are compared by value rather than by -object identity) may not be used as keys. -Numeric types used for keys obey the normal rules for numeric -comparison: if two numbers compare equal (such as \code{1} and -\code{1.0}) then they can be used interchangeably to index the same -dictionary entry. - -Dictionaries are created by placing a comma-separated list of -\code{\var{key}: \var{value}} pairs within braces, for example: -\code{\{'jack': 4098, 'sjoerd': 4127\}} or -\code{\{4098: 'jack', 4127: 'sjoerd'\}}. - -The following operations are defined on mappings (where \var{a} and -\var{b} are mappings, \var{k} is a key, and \var{v} and \var{x} are -arbitrary objects): -\indexiii{operations on}{mapping}{types} -\indexiii{operations on}{dictionary}{type} -\stindex{del} -\bifuncindex{len} -\withsubitem{(dictionary method)}{ - \ttindex{clear()} - \ttindex{copy()} - \ttindex{has_key()} - \ttindex{fromkeys()} - \ttindex{items()} - \ttindex{keys()} - \ttindex{update()} - \ttindex{values()} - \ttindex{get()} - \ttindex{setdefault()} - \ttindex{pop()} - \ttindex{popitem()} - \ttindex{iteritems()} - \ttindex{iterkeys()} - \ttindex{itervalues()}} - -\begin{tableiii}{c|l|c}{code}{Operation}{Result}{Notes} - \lineiii{len(\var{a})}{the number of items in \var{a}}{} - \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1), (10)} - \lineiii{\var{a}[\var{k}] = \var{v}} - {set \code{\var{a}[\var{k}]} to \var{v}} - {} - \lineiii{del \var{a}[\var{k}]} - {remove \code{\var{a}[\var{k}]} from \var{a}} - {(1)} - \lineiii{\var{a}.clear()}{remove all items from \code{a}}{} - \lineiii{\var{a}.copy()}{a (shallow) copy of \code{a}}{} - \lineiii{\var{k} in \var{a}} - {\code{True} if \var{a} has a key \var{k}, else \code{False}} - {(2)} - \lineiii{\var{k} not in \var{a}} - {Equivalent to \code{not} \var{k} in \var{a}} - {(2)} - \lineiii{\var{a}.has_key(\var{k})} - {Equivalent to \var{k} \code{in} \var{a}, use that form in new code} - {} - \lineiii{\var{a}.items()} - {a copy of \var{a}'s list of (\var{key}, \var{value}) pairs} - {(3)} - \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(3)} - \lineiii{\var{a}.update(\optional{\var{b}})} - {updates \var{a} with key/value pairs from \var{b}, overwriting - existing keys, returns \code{None}} - {(9)} - \lineiii{\var{a}.fromkeys(\var{seq}\optional{, \var{value}})} - {Creates a new dictionary with keys from \var{seq} and values set to \var{value}} - {(7)} - \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(3)} - \lineiii{\var{a}.get(\var{k}\optional{, \var{x}})} - {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}}, - else \var{x}} - {(4)} - \lineiii{\var{a}.setdefault(\var{k}\optional{, \var{x}})} - {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}}, - else \var{x} (also setting it)} - {(5)} - \lineiii{\var{a}.pop(\var{k}\optional{, \var{x}})} - {\code{\var{a}[\var{k}]} if \code{\var{k} in \var{a}}, - else \var{x} (and remove k)} - {(8)} - \lineiii{\var{a}.popitem()} - {remove and return an arbitrary (\var{key}, \var{value}) pair} - {(6)} - \lineiii{\var{a}.iteritems()} - {return an iterator over (\var{key}, \var{value}) pairs} - {(2), (3)} - \lineiii{\var{a}.iterkeys()} - {return an iterator over the mapping's keys} - {(2), (3)} - \lineiii{\var{a}.itervalues()} - {return an iterator over the mapping's values} - {(2), (3)} -\end{tableiii} - -\noindent -Notes: -\begin{description} -\item[(1)] Raises a \exception{KeyError} exception if \var{k} is not -in the map. - -\item[(2)] \versionadded{2.2} - -\item[(3)] Keys and values are listed in an arbitrary order which is -non-random, varies across Python implementations, and depends on the -dictionary's history of insertions and deletions. -If \method{items()}, \method{keys()}, \method{values()}, -\method{iteritems()}, \method{iterkeys()}, and \method{itervalues()} -are called with no intervening modifications to the dictionary, the -lists will directly correspond. This allows the creation of -\code{(\var{value}, \var{key})} pairs using \function{zip()}: -\samp{pairs = zip(\var{a}.values(), \var{a}.keys())}. The same -relationship holds for the \method{iterkeys()} and -\method{itervalues()} methods: \samp{pairs = zip(\var{a}.itervalues(), -\var{a}.iterkeys())} provides the same value for \code{pairs}. -Another way to create the same list is \samp{pairs = [(v, k) for (k, -v) in \var{a}.iteritems()]}. - -\item[(4)] Never raises an exception if \var{k} is not in the map, -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. - -\item[(5)] \function{setdefault()} is like \function{get()}, except -that if \var{k} is missing, \var{x} is both returned and inserted into -the dictionary as the value of \var{k}. \var{x} defaults to \code{None}. - -\item[(6)] \function{popitem()} is useful to destructively iterate -over a dictionary, as often used in set algorithms. If the dictionary -is empty, calling \function{popitem()} raises a \exception{KeyError}. - -\item[(7)] \function{fromkeys()} is a class method that returns a -new dictionary. \var{value} defaults to \code{None}. \versionadded{2.3} - -\item[(8)] \function{pop()} raises a \exception{KeyError} when no default -value is given and the key is not found. \versionadded{2.3} - -\item[(9)] \function{update()} accepts either another mapping object -or an iterable of key/value pairs (as a tuple or other iterable of -length two). If keyword arguments are specified, the mapping is -then is updated with those key/value pairs: -\samp{d.update(red=1, blue=2)}. -\versionchanged[Allowed the argument to be an iterable of key/value - pairs and allowed keyword arguments]{2.4} - -\item[(10)] If a subclass of dict defines a method \method{__missing__}, -if the key \var{k} is not present, the \var{a}[\var{k}] operation calls -that method with the key \var{k} as argument. The \var{a}[\var{k}] -operation then returns or raises whatever is returned or raised by the -\function{__missing__}(\var{k}) call if the key is not present. -No other operations or methods invoke \method{__missing__}(). -If \method{__missing__} is not defined, \exception{KeyError} is raised. -\method{__missing__} must be a method; it cannot be an instance variable. -For an example, see \module{collections}.\class{defaultdict}. -\versionadded{2.5} - -\end{description} - -\section{File Objects - \label{bltin-file-objects}} - -File objects\obindex{file} are implemented using C's \code{stdio} -package and can be created with the built-in constructor -\function{file()}\bifuncindex{file} described in section -\ref{built-in-funcs}, ``Built-in Functions.''\footnote{\function{file()} -is new in Python 2.2. The older built-in \function{open()} is an -alias for \function{file()}.} File objects are also returned -by some other built-in functions and methods, such as -\function{os.popen()} and \function{os.fdopen()} and the -\method{makefile()} method of socket objects. -\refstmodindex{os} -\refbimodindex{socket} - -When a file operation fails for an I/O-related reason, the exception -\exception{IOError} is raised. This includes situations where the -operation is not defined for some reason, like \method{seek()} on a tty -device or writing a file opened for reading. - -Files have the following methods: - - -\begin{methoddesc}[file]{close}{} - Close the file. A closed file cannot be read or written any more. - Any operation which requires that the file be open will raise a - \exception{ValueError} after the file has been closed. Calling - \method{close()} more than once is allowed. - - As of Python 2.5, you can avoid having to call this method explicitly - if you use the \keyword{with} statement. For example, the following - code will automatically close \code{f} when the \keyword{with} block - is exited: - -\begin{verbatim} -from __future__ import with_statement - -with open("hello.txt") as f: - for line in f: - print line -\end{verbatim} - - In older versions of Python, you would have needed to do this to get - the same effect: - -\begin{verbatim} -f = open("hello.txt") -try: - for line in f: - print line -finally: - f.close() -\end{verbatim} - - \note{Not all ``file-like'' types in Python support use as a context - manager for the \keyword{with} statement. If your code is intended to - work with any file-like object, you can use the \function{closing()} - function in the \module{contextlib} module instead of using the object - directly. See section~\ref{context-closing} for details.} - -\end{methoddesc} - -\begin{methoddesc}[file]{flush}{} - Flush the internal buffer, like \code{stdio}'s - \cfunction{fflush()}. This may be a no-op on some file-like - objects. -\end{methoddesc} - -\begin{methoddesc}[file]{fileno}{} - \index{file descriptor} - \index{descriptor, file} - Return the integer ``file descriptor'' that is used by the - underlying implementation to request I/O operations from the - operating system. This can be useful for other, lower level - interfaces that use file descriptors, such as the - \refmodule{fcntl}\refbimodindex{fcntl} module or - \function{os.read()} and friends. \note{File-like objects - which do not have a real file descriptor should \emph{not} provide - this method!} -\end{methoddesc} - -\begin{methoddesc}[file]{isatty}{} - Return \code{True} if the file is connected to a tty(-like) device, else - \code{False}. \note{If a file-like object is not associated - with a real file, this method should \emph{not} be implemented.} -\end{methoddesc} - -\begin{methoddesc}[file]{__next__}{} -A file object is its own iterator, for example \code{iter(\var{f})} returns -\var{f} (unless \var{f} is closed). When a file is used as an -iterator, typically in a \keyword{for} loop (for example, -\code{for line in f: print line}), the \method{__next__()} method is -called repeatedly. This method returns the next input line, or raises -\exception{StopIteration} when \EOF{} is hit when the file is open for -reading (behavior is undefined when the file is open for writing). In -order to make a \keyword{for} loop the most efficient way of looping -over the lines of a file (a very common operation), the -\method{__next__()} method uses a hidden read-ahead buffer. As a -consequence of using a read-ahead buffer, combining \method{__next__()} -with other file methods (like \method{readline()}) does not work -right. However, using \method{seek()} to reposition the file to an -absolute position will flush the read-ahead buffer. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[file]{read}{\optional{size}} - Read at most \var{size} bytes from the file (less if the read hits - \EOF{} before obtaining \var{size} bytes). If the \var{size} - argument is negative or omitted, read all data until \EOF{} is - reached. The bytes are returned as a string object. An empty - string is returned when \EOF{} is encountered immediately. (For - certain files, like ttys, it makes sense to continue reading after - an \EOF{} is hit.) Note that this method may call the underlying - C function \cfunction{fread()} more than once in an effort to - acquire as close to \var{size} bytes as possible. Also note that - when in non-blocking mode, less data than what was requested may - be returned, even if no \var{size} parameter was given. -\end{methoddesc} - -\begin{methoddesc}[file]{readline}{\optional{size}} - Read one entire line from the file. A trailing newline character is - kept in the string (but may be absent when a file ends with an - incomplete line).\footnote{ - The advantage of leaving the newline on is that - returning an empty string is then an unambiguous \EOF{} - indication. It is also possible (in cases where it might - matter, for example, if you - want to make an exact copy of a file while scanning its lines) - to tell whether the last line of a file ended in a newline - or not (yes this happens!). - } If the \var{size} argument is present and - non-negative, it is a maximum byte count (including the trailing - newline) and an incomplete line may be returned. - An empty string is returned \emph{only} when \EOF{} is encountered - 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} - -\begin{methoddesc}[file]{readlines}{\optional{sizehint}} - Read until \EOF{} using \method{readline()} and return a list containing - the lines thus read. If the optional \var{sizehint} argument is - present, instead of reading up to \EOF, whole lines totalling - approximately \var{sizehint} bytes (possibly after rounding up to an - internal buffer size) are read. Objects implementing a file-like - interface may choose to ignore \var{sizehint} if it cannot be - implemented, or cannot be implemented efficiently. -\end{methoddesc} - -\begin{methoddesc}[file]{seek}{offset\optional{, whence}} - Set the file's current position, like \code{stdio}'s \cfunction{fseek()}. - The \var{whence} argument is optional and defaults to - \code{os.SEEK_SET} or \code{0} - (absolute file positioning); other values are \code{os.SEEK_CUR} or \code{1} - (seek - relative to the current position) and \code{os.SEEK_END} or \code{2} - (seek relative to the - file's end). There is no return value. Note that if the file is - opened for appending (mode \code{'a'} or \code{'a+'}), any - \method{seek()} operations will be undone at the next write. If the - file is only opened for writing in append mode (mode \code{'a'}), - this method is essentially a no-op, but it remains useful for files - opened in append mode with reading enabled (mode \code{'a+'}). If the - file is opened in text mode (without \code{'b'}), only offsets returned - by \method{tell()} are legal. Use of other offsets causes undefined - behavior. - - Note that not all file objects are seekable. - \versionchanged{Passing float values as offset has been deprecated}[2.6] -\end{methoddesc} - -\begin{methoddesc}[file]{tell}{} - Return the file's current position, like \code{stdio}'s - \cfunction{ftell()}. - - \note{On Windows, \method{tell()} can return illegal values (after an - \cfunction{fgets()}) when reading files with \UNIX{}-style line-endings. - Use binary mode (\code{'rb'}) to circumvent this problem.} -\end{methoddesc} - -\begin{methoddesc}[file]{truncate}{\optional{size}} - Truncate the file's size. If the optional \var{size} argument is - present, the file is truncated to (at most) that size. The size - defaults to the current position. The current file position is - not changed. Note that if a specified size exceeds the file's - current size, the result is platform-dependent: possibilities - include that the file may remain unchanged, increase to the specified - size as if zero-filled, or increase to the specified size with - undefined new content. - Availability: Windows, many \UNIX{} variants. -\end{methoddesc} - -\begin{methoddesc}[file]{write}{str} - Write a string to the file. There is no return value. 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} - -\begin{methoddesc}[file]{writelines}{sequence} - Write a sequence of strings to the file. The sequence can be any - iterable object producing strings, typically a list of strings. - There is no return value. - (The name is intended to match \method{readlines()}; - \method{writelines()} does not add line separators.) -\end{methoddesc} - - -Files support the iterator protocol. Each iteration returns the same -result as \code{\var{file}.readline()}, and iteration ends when the -\method{readline()} method returns an empty string. - - -File objects also offer a number of other interesting attributes. -These are not required for file-like objects, but should be -implemented if they make sense for the particular object. - -\begin{memberdesc}[file]{closed} -bool indicating the current state of the file object. This is a -read-only attribute; the \method{close()} method changes the value. -It may not be available on all file-like objects. -\end{memberdesc} - -\begin{memberdesc}[file]{encoding} -The encoding that this file uses. When Unicode strings are written -to a file, they will be converted to byte strings using this encoding. -In addition, when the file is connected to a terminal, the attribute -gives the encoding that the terminal is likely to use (that -information might be incorrect if the user has misconfigured the -terminal). The attribute is read-only and may not be present on -all file-like objects. It may also be \code{None}, in which case -the file uses the system default encoding for converting Unicode -strings. - -\versionadded{2.3} -\end{memberdesc} - -\begin{memberdesc}[file]{mode} -The I/O mode for the file. If the file was created using the -\function{open()} built-in function, this will be the value of the -\var{mode} parameter. This is a read-only attribute and may not be -present on all file-like objects. -\end{memberdesc} - -\begin{memberdesc}[file]{name} -If the file object was created using \function{open()}, the name of -the file. Otherwise, some string that indicates the source of the -file object, of the form \samp{<\mbox{\ldots}>}. This is a read-only -attribute and may not be present on all file-like objects. -\end{memberdesc} - -\begin{memberdesc}[file]{newlines} -If Python was built with the \longprogramopt{with-universal-newlines} -option to \program{configure} (the default) this read-only attribute -exists, and for files opened in -universal newline read mode it keeps track of the types of newlines -encountered while reading the file. The values it can take are -\code{'\e r'}, \code{'\e n'}, \code{'\e r\e n'}, \code{None} (unknown, -no newlines read yet) or a tuple containing all the newline -types seen, to indicate that multiple -newline conventions were encountered. For files not opened in universal -newline read mode the value of this attribute will be \code{None}. -\end{memberdesc} - -\begin{memberdesc}[file]{softspace} -Boolean that indicates whether a space character needs to be printed -before another value when using the \keyword{print} statement. -Classes that are trying to simulate a file object should also have a -writable \member{softspace} attribute, which should be initialized to -zero. This will be automatic for most classes implemented in Python -(care may be needed for objects that override attribute access); types -implemented in C will have to provide a writable -\member{softspace} attribute. -\note{This attribute is not used to control the -\keyword{print} statement, but to allow the implementation of -\keyword{print} to keep track of its internal state.} -\end{memberdesc} - - -\section{Context Manager Types \label{typecontextmanager}} - -\versionadded{2.5} -\index{context manager} -\index{context management protocol} -\index{protocol!context management} - -Python's \keyword{with} statement supports the concept of a runtime -context defined by a context manager. This is implemented using -two separate methods that allow user-defined classes to define -a runtime context that is entered before the statement body is -executed and exited when the statement ends. - -The \dfn{context management protocol} consists of a pair of -methods that need to be provided for a context manager object to -define a runtime context: - -\begin{methoddesc}[context manager]{__enter__}{} - Enter the runtime context and return either this object or another - object related to the runtime context. The value returned by this - method is bound to the identifier in the \keyword{as} clause of - \keyword{with} statements using this context manager. - - An example of a context manager that returns itself is a file object. - File objects return themselves from __enter__() to allow - \function{open()} to be used as the context expression in a - \keyword{with} statement. - - An example of a context manager that returns a related - object is the one returned by \code{decimal.Context.get_manager()}. - These managers set the active decimal context to a copy of the - original decimal context and then return the copy. This allows - changes to be made to the current decimal context in the body of - the \keyword{with} statement without affecting code outside - the \keyword{with} statement. -\end{methoddesc} - -\begin{methoddesc}[context manager]{__exit__}{exc_type, exc_val, exc_tb} - Exit the runtime context and return a Boolean flag indicating if any - expection that occurred should be suppressed. If an exception - occurred while executing the body of the \keyword{with} statement, the - arguments contain the exception type, value and traceback information. - Otherwise, all three arguments are \code{None}. - - Returning a true value from this method will cause the \keyword{with} - statement to suppress the exception and continue execution with the - statement immediately following the \keyword{with} statement. Otherwise - the exception continues propagating after this method has finished - executing. Exceptions that occur during execution of this method will - replace any exception that occurred in the body of the \keyword{with} - statement. - - The exception passed in should never be reraised explicitly - instead, - this method should return a false value to indicate that the method - completed successfully and does not want to suppress the raised - exception. This allows context management code (such as - \code{contextlib.nested}) to easily detect whether or not an - \method{__exit__()} method has actually failed. -\end{methoddesc} - -Python defines several context managers to support easy thread -synchronisation, prompt closure of files or other objects, and -simpler manipulation of the active decimal arithmetic -context. The specific types are not treated specially beyond -their implementation of the context management protocol. - -Python's generators and the \code{contextlib.contextfactory} decorator -provide a convenient way to implement these protocols. If a generator -function is decorated with the \code{contextlib.contextfactory} -decorator, it will return a context manager implementing the necessary -\method{__enter__()} and \method{__exit__()} methods, rather than the -iterator produced by an undecorated generator function. - -Note that there is no specific slot for any of these methods in the -type structure for Python objects in the Python/C API. Extension -types wanting to define these methods must provide them as a normal -Python accessible method. Compared to the overhead of setting up the -runtime context, the overhead of a single class dictionary lookup -is negligible. - - -\section{Other Built-in Types \label{typesother}} - -The interpreter supports several other kinds of objects. -Most of these support only one or two operations. - - -\subsection{Modules \label{typesmodules}} - -The only special operation on a module is attribute access: -\code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} -accesses a name defined in \var{m}'s symbol table. Module attributes -can be assigned to. (Note that the \keyword{import} statement is not, -strictly speaking, an operation on a module object; \code{import -\var{foo}} does not require a module object named \var{foo} to exist, -rather it requires an (external) \emph{definition} for a module named -\var{foo} somewhere.) - -A special member of every module is \member{__dict__}. -This is the dictionary containing the module's symbol table. -Modifying this dictionary will actually change the module's symbol -table, but direct assignment to the \member{__dict__} attribute is not -possible (you can write \code{\var{m}.__dict__['a'] = 1}, which -defines \code{\var{m}.a} to be \code{1}, but you can't write -\code{\var{m}.__dict__ = \{\}}). Modifying \member{__dict__} directly -is not recommended. - -Modules built into the interpreter are written like this: -\code{<module 'sys' (built-in)>}. If loaded from a file, they are -written as \code{<module 'os' from -'/usr/local/lib/python\shortversion/os.pyc'>}. - - -\subsection{Classes and Class Instances \label{typesobjects}} -\nodename{Classes and Instances} - -See chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python -Reference Manual} for these. - - -\subsection{Functions \label{typesfunctions}} - -Function objects are created by function definitions. The only -operation on a function object is to call it: -\code{\var{func}(\var{argument-list})}. - -There are really two flavors of function objects: built-in functions -and user-defined functions. Both support the same operation (to call -the function), but the implementation is different, hence the -different object types. - -See the \citetitle[../ref/ref.html]{Python Reference Manual} for more -information. - -\subsection{Methods \label{typesmethods}} -\obindex{method} - -Methods are functions that are called using the attribute notation. -There are two flavors: built-in methods (such as \method{append()} on -lists) and class instance methods. Built-in methods are described -with the types that support them. - -The implementation adds two special read-only attributes to class -instance methods: \code{\var{m}.im_self} is the object on which the -method operates, and \code{\var{m}.im_func} is the function -implementing the method. Calling \code{\var{m}(\var{arg-1}, -\var{arg-2}, \textrm{\ldots}, \var{arg-n})} is completely equivalent to -calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1}, -\var{arg-2}, \textrm{\ldots}, \var{arg-n})}. - -Class instance methods are either \emph{bound} or \emph{unbound}, -referring to whether the method was accessed through an instance or a -class, respectively. When a method is unbound, its \code{im_self} -attribute will be \code{None} and if called, an explicit \code{self} -object must be passed as the first argument. In this case, -\code{self} must be an instance of the unbound method's class (or a -subclass of that class), otherwise a \exception{TypeError} is raised. - -Like function objects, methods objects support getting -arbitrary attributes. However, since method attributes are actually -stored on the underlying function object (\code{meth.im_func}), -setting method attributes on either bound or unbound methods is -disallowed. Attempting to set a method attribute results in a -\exception{TypeError} being raised. In order to set a method attribute, -you need to explicitly set it on the underlying function object: - -\begin{verbatim} -class C: - def method(self): - pass - -c = C() -c.method.im_func.whoami = 'my name is c' -\end{verbatim} - -See the \citetitle[../ref/ref.html]{Python Reference Manual} for more -information. - - -\subsection{Code Objects \label{bltin-code-objects}} -\obindex{code} - -Code objects are used by the implementation to represent -``pseudo-compiled'' executable Python code such as a function body. -They differ from function objects because they don't contain a -reference to their global execution environment. Code objects are -returned by the built-in \function{compile()} function and can be -extracted from function objects through their \member{__code__} -attribute. -\bifuncindex{compile} -\withsubitem{(function object attribute)}{\ttindex{__code__}} - -A code object can be executed or evaluated by passing it (instead of a -source string) to the \function{exec()} or \function{eval()} -built-in functions. -\bifuncindex{exec} -\bifuncindex{eval} - -See the \citetitle[../ref/ref.html]{Python Reference Manual} for more -information. - - -\subsection{Type Objects \label{bltin-type-objects}} - -Type objects represent the various object types. An object's type is -accessed by the built-in function \function{type()}. There are no special -operations on types. The standard module \refmodule{types} defines names -for all standard built-in types. -\bifuncindex{type} -\refstmodindex{types} - -Types are written like this: \code{<type 'int'>}. - - -\subsection{The Null Object \label{bltin-null-object}} - -This object is returned by functions that don't explicitly return a -value. It supports no special operations. There is exactly one null -object, named \code{None} (a built-in name). - -It is written as \code{None}. - - -\subsection{The Ellipsis Object \label{bltin-ellipsis-object}} - -This object is mostly used by extended slice notation (see the -\citetitle[../ref/ref.html]{Python Reference Manual}). It supports no -special operations. There is exactly one ellipsis object, named -\constant{Ellipsis} (a built-in name). - -It is written as \code{Ellipsis} or \code{...}. - -\subsection{Boolean Values} - -Boolean values are the two constant objects \code{False} and -\code{True}. They are used to represent truth values (although other -values can also be considered false or true). In numeric contexts -(for example when used as the argument to an arithmetic operator), -they behave like the integers 0 and 1, respectively. The built-in -function \function{bool()} can be used to cast any value to a Boolean, -if the value can be interpreted as a truth value (see section Truth -Value Testing above). - -They are written as \code{False} and \code{True}, respectively. -\index{False} -\index{True} -\indexii{Boolean}{values} - - -\subsection{Internal Objects \label{typesinternal}} - -See the \citetitle[../ref/ref.html]{Python Reference Manual} for this -information. It describes stack frame objects, traceback objects, and -slice objects. - - -\section{Special Attributes \label{specialattrs}} - -The implementation adds a few special read-only attributes to several -object types, where they are relevant. Some of these are not reported -by the \function{dir()} built-in function. - -\begin{memberdesc}[object]{__dict__} -A dictionary or other mapping object used to store an -object's (writable) attributes. -\end{memberdesc} - -\begin{memberdesc}[instance]{__class__} -The class to which a class instance belongs. -\end{memberdesc} - -\begin{memberdesc}[class]{__bases__} -The tuple of base classes of a class object. If there are no base -classes, this will be an empty tuple. -\end{memberdesc} - -\begin{memberdesc}[class]{__name__} -The name of the class or type. -\end{memberdesc} diff --git a/Doc/lib/libstring.tex b/Doc/lib/libstring.tex deleted file mode 100644 index 9948cb7..0000000 --- a/Doc/lib/libstring.tex +++ /dev/null @@ -1,425 +0,0 @@ -\section{\module{string} --- - Common string operations} - -\declaremodule{standard}{string} -\modulesynopsis{Common string operations.} - -The \module{string} module contains a number of useful constants and classes, -as well as some deprecated legacy functions that are also available as methods -on strings. See the module \refmodule{re}\refstmodindex{re} for string -functions based on regular expressions. - -\subsection{String constants} - -The constants defined in this module are: - -\begin{datadesc}{ascii\_letters} - The concatenation of the \constant{ascii_lowercase} and - \constant{ascii_uppercase} constants described below. This value is - not locale-dependent. -\end{datadesc} - -\begin{datadesc}{ascii\_lowercase} - The lowercase letters \code{'abcdefghijklmnopqrstuvwxyz'}. This - value is not locale-dependent and will not change. -\end{datadesc} - -\begin{datadesc}{ascii\_uppercase} - The uppercase letters \code{'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. This - value is not locale-dependent and will not change. -\end{datadesc} - -\begin{datadesc}{digits} - The string \code{'0123456789'}. -\end{datadesc} - -\begin{datadesc}{hexdigits} - The string \code{'0123456789abcdefABCDEF'}. -\end{datadesc} - -\begin{datadesc}{octdigits} - The string \code{'01234567'}. -\end{datadesc} - -\begin{datadesc}{punctuation} - String of \ASCII{} characters which are considered punctuation - characters in the \samp{C} locale. -\end{datadesc} - -\begin{datadesc}{printable} - String of characters which are considered printable. This is a - combination of \constant{digits}, \constant{letters}, - \constant{punctuation}, and \constant{whitespace}. -\end{datadesc} - -\begin{datadesc}{whitespace} - A string containing all characters that are considered whitespace. - On most systems this includes the characters space, tab, linefeed, - return, formfeed, and vertical tab. Do not change its definition --- - the effect on the routines \function{strip()} and \function{split()} - is undefined. -\end{datadesc} - -\subsection{Template strings} - -Templates provide simpler string substitutions as described in \pep{292}. -Instead of the normal \samp{\%}-based substitutions, Templates support -\samp{\$}-based substitutions, using the following rules: - -\begin{itemize} -\item \samp{\$\$} is an escape; it is replaced with a single \samp{\$}. - -\item \samp{\$identifier} names a substitution placeholder matching a mapping - key of "identifier". By default, "identifier" must spell a Python - identifier. The first non-identifier character after the \samp{\$} - character terminates this placeholder specification. - -\item \samp{\$\{identifier\}} is equivalent to \samp{\$identifier}. It is - required when valid identifier characters follow the placeholder but are - not part of the placeholder, such as "\$\{noun\}ification". -\end{itemize} - -Any other appearance of \samp{\$} in the string will result in a -\exception{ValueError} being raised. - -\versionadded{2.4} - -The \module{string} module provides a \class{Template} class that implements -these rules. The methods of \class{Template} are: - -\begin{classdesc}{Template}{template} -The constructor takes a single argument which is the template string. -\end{classdesc} - -\begin{methoddesc}[Template]{substitute}{mapping\optional{, **kws}} -Performs the template substitution, returning a new string. \var{mapping} is -any dictionary-like object with keys that match the placeholders in the -template. Alternatively, you can provide keyword arguments, where the -keywords are the placeholders. When both \var{mapping} and \var{kws} are -given and there are duplicates, the placeholders from \var{kws} take -precedence. -\end{methoddesc} - -\begin{methoddesc}[Template]{safe_substitute}{mapping\optional{, **kws}} -Like \method{substitute()}, except that if placeholders are missing from -\var{mapping} and \var{kws}, instead of raising a \exception{KeyError} -exception, the original placeholder will appear in the resulting string -intact. Also, unlike with \method{substitute()}, any other appearances of the -\samp{\$} will simply return \samp{\$} instead of raising -\exception{ValueError}. - -While other exceptions may still occur, this method is called ``safe'' because -substitutions always tries to return a usable string instead of raising an -exception. In another sense, \method{safe_substitute()} may be anything other -than safe, since it will silently ignore malformed templates containing -dangling delimiters, unmatched braces, or placeholders that are not valid -Python identifiers. -\end{methoddesc} - -\class{Template} instances also provide one public data attribute: - -\begin{memberdesc}[string]{template} -This is the object passed to the constructor's \var{template} argument. In -general, you shouldn't change it, but read-only access is not enforced. -\end{memberdesc} - -Here is an example of how to use a Template: - -\begin{verbatim} ->>> from string import Template ->>> s = Template('$who likes $what') ->>> s.substitute(who='tim', what='kung pao') -'tim likes kung pao' ->>> d = dict(who='tim') ->>> Template('Give $who $100').substitute(d) -Traceback (most recent call last): -[...] -ValueError: Invalid placeholder in string: line 1, col 10 ->>> Template('$who likes $what').substitute(d) -Traceback (most recent call last): -[...] -KeyError: 'what' ->>> Template('$who likes $what').safe_substitute(d) -'tim likes $what' -\end{verbatim} - -Advanced usage: you can derive subclasses of \class{Template} to customize the -placeholder syntax, delimiter character, or the entire regular expression used -to parse template strings. To do this, you can override these class -attributes: - -\begin{itemize} -\item \var{delimiter} -- This is the literal string describing a placeholder - introducing delimiter. The default value \samp{\$}. Note that this - should \emph{not} be a regular expression, as the implementation will - call \method{re.escape()} on this string as needed. -\item \var{idpattern} -- This is the regular expression describing the pattern - for non-braced placeholders (the braces will be added automatically as - appropriate). The default value is the regular expression - \samp{[_a-z][_a-z0-9]*}. -\end{itemize} - -Alternatively, you can provide the entire regular expression pattern by -overriding the class attribute \var{pattern}. If you do this, the value must -be a regular expression object with four named capturing groups. The -capturing groups correspond to the rules given above, along with the invalid -placeholder rule: - -\begin{itemize} -\item \var{escaped} -- This group matches the escape sequence, - e.g. \samp{\$\$}, in the default pattern. -\item \var{named} -- This group matches the unbraced placeholder name; it - should not include the delimiter in capturing group. -\item \var{braced} -- This group matches the brace enclosed placeholder name; - it should not include either the delimiter or braces in the capturing - group. -\item \var{invalid} -- This group matches any other delimiter pattern (usually - a single delimiter), and it should appear last in the regular - expression. -\end{itemize} - -\subsection{String functions} - -The following functions are available to operate on string and Unicode -objects. They are not available as string methods. - -\begin{funcdesc}{capwords}{s} - Split the argument into words using \function{split()}, capitalize - each word using \function{capitalize()}, and join the capitalized - words using \function{join()}. Note that this replaces runs of - whitespace characters by a single space, and removes leading and - trailing whitespace. -\end{funcdesc} - -\begin{funcdesc}{maketrans}{from, to} - Return a translation table suitable for passing to - \function{translate()}, that will map - each character in \var{from} into the character at the same position - in \var{to}; \var{from} and \var{to} must have the same length. - - \warning{Don't use strings derived from \constant{lowercase} - and \constant{uppercase} as arguments; in some locales, these don't have - the same length. For case conversions, always use - \function{lower()} and \function{upper()}.} -\end{funcdesc} - -\subsection{Deprecated string functions} - -The following list of functions are also defined as methods of string and -Unicode objects; see ``String Methods'' (section -\ref{string-methods}) for more information on those. You should consider -these functions as deprecated, although they will not be removed until Python -3.0. The functions defined in this module are: - -\begin{funcdesc}{atof}{s} - \deprecated{2.0}{Use the \function{float()} built-in function.} - Convert a string to a floating point number. The string must have - the standard syntax for a floating point literal in Python, - optionally preceded by a sign (\samp{+} or \samp{-}). Note that - this behaves identical to the built-in function - \function{float()}\bifuncindex{float} when passed a string. - - \note{When passing in a string, values for NaN\index{NaN} - and Infinity\index{Infinity} may be returned, depending on the - underlying C library. The specific set of strings accepted which - cause these values to be returned depends entirely on the C library - and is known to vary.} -\end{funcdesc} - -\begin{funcdesc}{atoi}{s\optional{, base}} - \deprecated{2.0}{Use the \function{int()} built-in function.} - Convert string \var{s} to an integer in the given \var{base}. The - string must consist of one or more digits, optionally preceded by a - sign (\samp{+} or \samp{-}). The \var{base} defaults to 10. If it - is 0, a default base is chosen depending on the leading characters - of the string (after stripping the sign): \samp{0x} or \samp{0X} - means 16, \samp{0} means 8, anything else means 10. If \var{base} - is 16, a leading \samp{0x} or \samp{0X} is always accepted, though - not required. This behaves identically to the built-in function - \function{int()} when passed a string. (Also note: for a more - flexible interpretation of numeric literals, use the built-in - function \function{eval()}\bifuncindex{eval}.) -\end{funcdesc} - -\begin{funcdesc}{atol}{s\optional{, base}} - \deprecated{2.0}{Use the \function{long()} built-in function.} - Convert string \var{s} to a long integer in the given \var{base}. - The string must consist of one or more digits, optionally preceded - by a sign (\samp{+} or \samp{-}). The \var{base} argument has the - same meaning as for \function{atoi()}. A trailing \samp{l} or - \samp{L} is not allowed, except if the base is 0. Note that when - invoked without \var{base} or with \var{base} set to 10, this - behaves identical to the built-in function - \function{long()}\bifuncindex{long} when passed a string. -\end{funcdesc} - -\begin{funcdesc}{capitalize}{word} - Return a copy of \var{word} with only its first character capitalized. -\end{funcdesc} - -\begin{funcdesc}{expandtabs}{s\optional{, tabsize}} - Expand tabs in a string replacing them by one or more spaces, - depending on the current column and the given tab size. The column - number is reset to zero after each newline occurring in the string. - This doesn't understand other non-printing characters or escape - sequences. The tab size defaults to 8. -\end{funcdesc} - -\begin{funcdesc}{find}{s, sub\optional{, start\optional{,end}}} - Return the lowest index in \var{s} where the substring \var{sub} is - found such that \var{sub} is wholly contained in - \code{\var{s}[\var{start}:\var{end}]}. Return \code{-1} on failure. - Defaults for \var{start} and \var{end} and interpretation of - negative values is the same as for slices. -\end{funcdesc} - -\begin{funcdesc}{rfind}{s, sub\optional{, start\optional{, end}}} - Like \function{find()} but find the highest index. -\end{funcdesc} - -\begin{funcdesc}{index}{s, sub\optional{, start\optional{, end}}} - Like \function{find()} but raise \exception{ValueError} when the - substring is not found. -\end{funcdesc} - -\begin{funcdesc}{rindex}{s, sub\optional{, start\optional{, end}}} - Like \function{rfind()} but raise \exception{ValueError} when the - substring is not found. -\end{funcdesc} - -\begin{funcdesc}{count}{s, sub\optional{, start\optional{, end}}} - Return the number of (non-overlapping) occurrences of substring - \var{sub} in string \code{\var{s}[\var{start}:\var{end}]}. - Defaults for \var{start} and \var{end} and interpretation of - negative values are the same as for slices. -\end{funcdesc} - -\begin{funcdesc}{lower}{s} - Return a copy of \var{s}, but with upper case letters converted to - lower case. -\end{funcdesc} - -\begin{funcdesc}{split}{s\optional{, sep\optional{, maxsplit}}} - Return a list of the words of the string \var{s}. If the optional - second argument \var{sep} is absent or \code{None}, the words are - separated by arbitrary strings of whitespace characters (space, tab, - newline, return, formfeed). If the second argument \var{sep} is - present and not \code{None}, it specifies a string to be used as the - word separator. The returned list will then have one more item - than the number of non-overlapping occurrences of the separator in - the string. The optional third argument \var{maxsplit} defaults to - 0. If it is nonzero, at most \var{maxsplit} number of splits occur, - and the remainder of the string is returned as the final element of - the list (thus, the list will have at most \code{\var{maxsplit}+1} - elements). - - The behavior of split on an empty string depends on the value of \var{sep}. - If \var{sep} is not specified, or specified as \code{None}, the result will - be an empty list. If \var{sep} is specified as any string, the result will - be a list containing one element which is an empty string. -\end{funcdesc} - -\begin{funcdesc}{rsplit}{s\optional{, sep\optional{, maxsplit}}} - Return a list of the words of the string \var{s}, scanning \var{s} - from the end. To all intents and purposes, the resulting list of - words is the same as returned by \function{split()}, except when the - optional third argument \var{maxsplit} is explicitly specified and - nonzero. When \var{maxsplit} is nonzero, at most \var{maxsplit} - number of splits -- the \emph{rightmost} ones -- occur, and the remainder - of the string is returned as the first element of the list (thus, the - list will have at most \code{\var{maxsplit}+1} elements). - \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{splitfields}{s\optional{, sep\optional{, maxsplit}}} - This function behaves identically to \function{split()}. (In the - past, \function{split()} was only used with one argument, while - \function{splitfields()} was only used with two arguments.) -\end{funcdesc} - -\begin{funcdesc}{join}{words\optional{, sep}} - Concatenate a list or tuple of words with intervening occurrences of - \var{sep}. The default value for \var{sep} is a single space - character. It is always true that - \samp{string.join(string.split(\var{s}, \var{sep}), \var{sep})} - equals \var{s}. -\end{funcdesc} - -\begin{funcdesc}{joinfields}{words\optional{, sep}} - This function behaves identically to \function{join()}. (In the past, - \function{join()} was only used with one argument, while - \function{joinfields()} was only used with two arguments.) - Note that there is no \method{joinfields()} method on string - objects; use the \method{join()} method instead. -\end{funcdesc} - -\begin{funcdesc}{lstrip}{s\optional{, chars}} -Return a copy of the string with leading characters removed. If -\var{chars} is omitted or \code{None}, whitespace characters are -removed. If given and not \code{None}, \var{chars} must be a string; -the characters in the string will be stripped from the beginning of -the string this method is called on. -\versionchanged[The \var{chars} parameter was added. The \var{chars} -parameter cannot be passed in earlier 2.2 versions]{2.2.3} -\end{funcdesc} - -\begin{funcdesc}{rstrip}{s\optional{, chars}} -Return a copy of the string with trailing characters removed. If -\var{chars} is omitted or \code{None}, whitespace characters are -removed. If given and not \code{None}, \var{chars} must be a string; -the characters in the string will be stripped from the end of the -string this method is called on. -\versionchanged[The \var{chars} parameter was added. The \var{chars} -parameter cannot be passed in earlier 2.2 versions]{2.2.3} -\end{funcdesc} - -\begin{funcdesc}{strip}{s\optional{, chars}} -Return a copy of the string with leading and trailing characters -removed. If \var{chars} is omitted or \code{None}, whitespace -characters are removed. If given and not \code{None}, \var{chars} -must be a string; the characters in the string will be stripped from -the both ends of the string this method is called on. -\versionchanged[The \var{chars} parameter was added. The \var{chars} -parameter cannot be passed in earlier 2.2 versions]{2.2.3} -\end{funcdesc} - -\begin{funcdesc}{swapcase}{s} - Return a copy of \var{s}, but with lower case letters - converted to upper case and vice versa. -\end{funcdesc} - -\begin{funcdesc}{translate}{s, table\optional{, deletechars}} - Delete all characters from \var{s} that are in \var{deletechars} (if - present), and then translate the characters using \var{table}, which - must be a 256-character string giving the translation for each - character value, indexed by its ordinal. If \var{table} is \code{None}, - then only the character deletion step is performed. -\end{funcdesc} - -\begin{funcdesc}{upper}{s} - Return a copy of \var{s}, but with lower case letters converted to - upper case. -\end{funcdesc} - -\begin{funcdesc}{ljust}{s, width} -\funcline{rjust}{s, width} -\funcline{center}{s, width} - These functions respectively left-justify, right-justify and center - a string in a field of given width. They return a string that is at - least \var{width} characters wide, created by padding the string - \var{s} with spaces until the given width on the right, left or both - sides. The string is never truncated. -\end{funcdesc} - -\begin{funcdesc}{zfill}{s, width} - Pad a numeric string on the left with zero digits until the given - width is reached. Strings starting with a sign are handled - correctly. -\end{funcdesc} - -\begin{funcdesc}{replace}{str, old, new\optional{, maxreplace}} - Return a copy of string \var{str} with all occurrences of substring - \var{old} replaced by \var{new}. If the optional argument - \var{maxreplace} is given, the first \var{maxreplace} occurrences are - replaced. -\end{funcdesc} diff --git a/Doc/lib/libstringio.tex b/Doc/lib/libstringio.tex deleted file mode 100644 index 73ff0e4..0000000 --- a/Doc/lib/libstringio.tex +++ /dev/null @@ -1,125 +0,0 @@ -\section{\module{StringIO} --- - Read and write strings as files} - -\declaremodule{standard}{StringIO} -\modulesynopsis{Read and write strings as if they were files.} - - -This module implements a file-like class, \class{StringIO}, -that reads and writes a string buffer (also known as \emph{memory -files}). See the description of file objects for operations (section -\ref{bltin-file-objects}). - -\begin{classdesc}{StringIO}{\optional{buffer}} -When a \class{StringIO} object is created, it can be initialized -to an existing string by passing the string to the constructor. -If no string is given, the \class{StringIO} will start empty. -In both cases, the initial file position starts at zero. - -The \class{StringIO} object can accept either Unicode or 8-bit -strings, but mixing the two may take some care. If both are used, -8-bit strings that cannot be interpreted as 7-bit \ASCII{} (that -use the 8th bit) will cause a \exception{UnicodeError} to be raised -when \method{getvalue()} is called. -\end{classdesc} - -The following methods of \class{StringIO} objects require special -mention: - -\begin{methoddesc}{getvalue}{} -Retrieve the entire contents of the ``file'' at any time before the -\class{StringIO} object's \method{close()} method is called. See the -note above for information about mixing Unicode and 8-bit strings; -such mixing can cause this method to raise \exception{UnicodeError}. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Free the memory buffer. -\end{methoddesc} - -Example usage: - -\begin{verbatim} -import StringIO - -output = StringIO.StringIO() -output.write('First line.\n') -print >>output, 'Second line.' - -# Retrieve file contents -- this will be -# 'First line.\nSecond line.\n' -contents = output.getvalue() - -# Close object and discard memory buffer -- -# .getvalue() will now raise an exception. -output.close() -\end{verbatim} - - -\section{\module{cStringIO} --- - Faster version of \module{StringIO}} - -\declaremodule{builtin}{cStringIO} -\modulesynopsis{Faster version of \module{StringIO}, but not - subclassable.} -\moduleauthor{Jim Fulton}{jim@zope.com} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -The module \module{cStringIO} provides an interface similar to that of -the \refmodule{StringIO} module. Heavy use of \class{StringIO.StringIO} -objects can be made more efficient by using the function -\function{StringIO()} from this module instead. - -Since this module provides a factory function which returns objects of -built-in types, there's no way to build your own version using -subclassing. Use the original \refmodule{StringIO} module in that case. - -Unlike the memory files implemented by the \refmodule{StringIO} -module, those provided by this module are not able to accept Unicode -strings that cannot be encoded as plain \ASCII{} strings. - -Calling \function{StringIO()} with a Unicode string parameter populates -the object with the buffer representation of the Unicode string, instead of -encoding the string. - -Another difference from the \refmodule{StringIO} module is that calling -\function{StringIO()} with a string parameter creates a read-only object. -Unlike an object created without a string parameter, it does not have -write methods. These objects are not generally visible. They turn up in -tracebacks as \class{StringI} and \class{StringO}. - -The following data objects are provided as well: - - -\begin{datadesc}{InputType} - The type object of the objects created by calling - \function{StringIO} with a string parameter. -\end{datadesc} - -\begin{datadesc}{OutputType} - The type object of the objects returned by calling - \function{StringIO} with no parameters. -\end{datadesc} - - -There is a C API to the module as well; refer to the module source for -more information. - -Example usage: - -\begin{verbatim} -import cStringIO - -output = cStringIO.StringIO() -output.write('First line.\n') -print >>output, 'Second line.' - -# Retrieve file contents -- this will be -# 'First line.\nSecond line.\n' -contents = output.getvalue() - -# Close object and discard memory buffer -- -# .getvalue() will now raise an exception. -output.close() -\end{verbatim} - diff --git a/Doc/lib/libstringprep.tex b/Doc/lib/libstringprep.tex deleted file mode 100644 index 2614314..0000000 --- a/Doc/lib/libstringprep.tex +++ /dev/null @@ -1,136 +0,0 @@ -\section{\module{stringprep} --- - Internet String Preparation} - -\declaremodule{standard}{stringprep} -\modulesynopsis{String preparation, as per RFC 3453} -\moduleauthor{Martin v. L\"owis}{martin@v.loewis.de} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} - -\versionadded{2.3} - -When identifying things (such as host names) in the internet, it is -often necessary to compare such identifications for -``equality''. Exactly how this comparison is executed may depend on -the application domain, e.g. whether it should be case-insensitive or -not. It may be also necessary to restrict the possible -identifications, to allow only identifications consisting of -``printable'' characters. - -\rfc{3454} defines a procedure for ``preparing'' Unicode strings in -internet protocols. Before passing strings onto the wire, they are -processed with the preparation procedure, after which they have a -certain normalized form. The RFC defines a set of tables, which can be -combined into profiles. Each profile must define which tables it uses, -and what other optional parts of the \code{stringprep} procedure are -part of the profile. One example of a \code{stringprep} profile is -\code{nameprep}, which is used for internationalized domain names. - -The module \module{stringprep} only exposes the tables from RFC -3454. As these tables would be very large to represent them as -dictionaries or lists, the module uses the Unicode character database -internally. The module source code itself was generated using the -\code{mkstringprep.py} utility. - -As a result, these tables are exposed as functions, not as data -structures. There are two kinds of tables in the RFC: sets and -mappings. For a set, \module{stringprep} provides the ``characteristic -function'', i.e. a function that returns true if the parameter is part -of the set. For mappings, it provides the mapping function: given the -key, it returns the associated value. Below is a list of all functions -available in the module. - -\begin{funcdesc}{in_table_a1}{code} -Determine whether \var{code} is in table{A.1} (Unassigned code points -in Unicode 3.2). -\end{funcdesc} - -\begin{funcdesc}{in_table_b1}{code} -Determine whether \var{code} is in table{B.1} (Commonly mapped to -nothing). -\end{funcdesc} - -\begin{funcdesc}{map_table_b2}{code} -Return the mapped value for \var{code} according to table{B.2} -(Mapping for case-folding used with NFKC). -\end{funcdesc} - -\begin{funcdesc}{map_table_b3}{code} -Return the mapped value for \var{code} according to table{B.3} -(Mapping for case-folding used with no normalization). -\end{funcdesc} - -\begin{funcdesc}{in_table_c11}{code} -Determine whether \var{code} is in table{C.1.1} -(ASCII space characters). -\end{funcdesc} - -\begin{funcdesc}{in_table_c12}{code} -Determine whether \var{code} is in table{C.1.2} -(Non-ASCII space characters). -\end{funcdesc} - -\begin{funcdesc}{in_table_c11_c12}{code} -Determine whether \var{code} is in table{C.1} -(Space characters, union of C.1.1 and C.1.2). -\end{funcdesc} - -\begin{funcdesc}{in_table_c21}{code} -Determine whether \var{code} is in table{C.2.1} -(ASCII control characters). -\end{funcdesc} - -\begin{funcdesc}{in_table_c22}{code} -Determine whether \var{code} is in table{C.2.2} -(Non-ASCII control characters). -\end{funcdesc} - -\begin{funcdesc}{in_table_c21_c22}{code} -Determine whether \var{code} is in table{C.2} -(Control characters, union of C.2.1 and C.2.2). -\end{funcdesc} - -\begin{funcdesc}{in_table_c3}{code} -Determine whether \var{code} is in table{C.3} -(Private use). -\end{funcdesc} - -\begin{funcdesc}{in_table_c4}{code} -Determine whether \var{code} is in table{C.4} -(Non-character code points). -\end{funcdesc} - -\begin{funcdesc}{in_table_c5}{code} -Determine whether \var{code} is in table{C.5} -(Surrogate codes). -\end{funcdesc} - -\begin{funcdesc}{in_table_c6}{code} -Determine whether \var{code} is in table{C.6} -(Inappropriate for plain text). -\end{funcdesc} - -\begin{funcdesc}{in_table_c7}{code} -Determine whether \var{code} is in table{C.7} -(Inappropriate for canonical representation). -\end{funcdesc} - -\begin{funcdesc}{in_table_c8}{code} -Determine whether \var{code} is in table{C.8} -(Change display properties or are deprecated). -\end{funcdesc} - -\begin{funcdesc}{in_table_c9}{code} -Determine whether \var{code} is in table{C.9} -(Tagging characters). -\end{funcdesc} - -\begin{funcdesc}{in_table_d1}{code} -Determine whether \var{code} is in table{D.1} -(Characters with bidirectional property ``R'' or ``AL''). -\end{funcdesc} - -\begin{funcdesc}{in_table_d2}{code} -Determine whether \var{code} is in table{D.2} -(Characters with bidirectional property ``L''). -\end{funcdesc} - diff --git a/Doc/lib/libstrings.tex b/Doc/lib/libstrings.tex deleted file mode 100644 index f3a31f4..0000000 --- a/Doc/lib/libstrings.tex +++ /dev/null @@ -1,10 +0,0 @@ -\chapter{String Services} -\label{strings} - -The modules described in this chapter provide a wide range of string -manipulation operations. Here's an overview: - -\localmoduletable - -Information on the methods of string objects can be found in -section~\ref{string-methods}, ``String Methods.'' diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex deleted file mode 100644 index 68c5c9a..0000000 --- a/Doc/lib/libstruct.tex +++ /dev/null @@ -1,269 +0,0 @@ -\section{\module{struct} --- - Interpret strings as packed binary data} -\declaremodule{builtin}{struct} - -\modulesynopsis{Interpret strings as packed binary data.} - -\indexii{C}{structures} -\indexiii{packing}{binary}{data} - -This module performs conversions between Python values and C -structs represented as Python strings. It uses \dfn{format strings} -(explained below) as compact descriptions of the lay-out of the C -structs and the intended conversion to/from Python values. This can -be used in handling binary data stored in files or from network -connections, among other sources. - -The module defines the following exception and functions: - - -\begin{excdesc}{error} - Exception raised on various occasions; argument is a string - describing what is wrong. -\end{excdesc} - -\begin{funcdesc}{pack}{fmt, v1, v2, \textrm{\ldots}} - Return a string containing the values - \code{\var{v1}, \var{v2}, \textrm{\ldots}} packed according to the given - format. The arguments must match the values required by the format - exactly. -\end{funcdesc} - -\begin{funcdesc}{pack_into}{fmt, buffer, offset, v1, v2, \moreargs} - Pack the values \code{\var{v1}, \var{v2}, \textrm{\ldots}} according to the given - format, write the packed bytes into the writable \var{buffer} starting at - \var{offset}. - Note that the offset is not an optional argument. - - \versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{unpack}{fmt, string} - Unpack the string (presumably packed by \code{pack(\var{fmt}, - \textrm{\ldots})}) according to the given format. The result is a - tuple even if it contains exactly one item. The string must contain - exactly the amount of data required by the format - (\code{len(\var{string})} must equal \code{calcsize(\var{fmt})}). -\end{funcdesc} - -\begin{funcdesc}{unpack_from}{fmt, buffer\optional{,offset \code{= 0}}} - Unpack the \var{buffer} according to tthe given format. - The result is a tuple even if it contains exactly one item. The - \var{buffer} must contain at least the amount of data required by the - format (\code{len(buffer[offset:])} must be at least - \code{calcsize(\var{fmt})}). - - \versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{calcsize}{fmt} - Return the size of the struct (and hence of the string) - corresponding to the given format. -\end{funcdesc} - -Format characters have the following meaning; the conversion between -C and Python values should be obvious given their types: - -\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{t}{\ctype{_Bool}}{bool}{(1)} - \lineiv{h}{\ctype{short}}{integer}{} - \lineiv{H}{\ctype{unsigned short}}{integer}{} - \lineiv{i}{\ctype{int}}{integer}{} - \lineiv{I}{\ctype{unsigned int}}{long}{} - \lineiv{l}{\ctype{long}}{integer}{} - \lineiv{L}{\ctype{unsigned long}}{long}{} - \lineiv{q}{\ctype{long long}}{long}{(2)} - \lineiv{Q}{\ctype{unsigned long long}}{long}{(2)} - \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{t} conversion code corresponds to the \ctype{_Bool} type - defined by C99. If this type is not available, it is simulated using a - \ctype{char}. In standard mode, it is always represented by one byte. - \versionadded{2.6} -\item[(2)] - The \character{q} and \character{Q} conversion codes are available in - native mode only if the platform C compiler supports C \ctype{long long}, - or, on Windows, \ctype{__int64}. They are always available in standard - modes. - \versionadded{2.2} -\end{description} - - -A format character may be preceded by an integral repeat count. For -example, the format string \code{'4h'} means exactly the same as -\code{'hhhh'}. - -Whitespace characters between formats are ignored; a count and its -format must not contain whitespace though. - -For the \character{s} format character, the count is interpreted as the -size of the string, not a repeat count like for the other format -characters; for example, \code{'10s'} means a single 10-byte string, while -\code{'10c'} means 10 characters. For packing, the string is -truncated or padded with null bytes as appropriate to make it fit. -For unpacking, the resulting string always has exactly the specified -number of bytes. As a special case, \code{'0s'} means a single, empty -string (while \code{'0c'} means 0 characters). - -The \character{p} format character encodes a "Pascal string", meaning -a short variable-length string stored in a fixed number of bytes. -The count is the total number of bytes stored. The first byte stored is -the length of the string, or 255, whichever is smaller. The bytes -of the string follow. If the string passed in to \function{pack()} is too -long (longer than the count minus 1), only the leading count-1 bytes of the -string are stored. If the string is shorter than count-1, it is padded -with null bytes so that exactly count bytes in all are used. Note that -for \function{unpack()}, the \character{p} format character consumes count -bytes, but that the string returned can never contain more than 255 -characters. - -For the \character{I}, \character{L}, \character{q} and \character{Q} -format characters, the return value is a Python long integer. - -For the \character{P} format character, the return value is a Python -integer or long integer, depending on the size needed to hold a -pointer when it has been cast to an integer type. A \NULL{} pointer will -always be returned as the Python integer \code{0}. When packing pointer-sized -values, Python integer or long integer objects may be used. For -example, the Alpha and Merced processors use 64-bit pointer values, -meaning a Python long integer will be used to hold the pointer; other -platforms use 32-bit pointers and will use a Python integer. - -For the \character{t} format character, the return value is either -\constant{True} or \constant{False}. When packing, the truth value -of the argument object is used. Either 0 or 1 in the native or standard -bool representation will be packed, and any non-zero value will be True -when unpacking. - -By default, C numbers are represented in the machine's native format -and byte order, and properly aligned by skipping pad bytes if -necessary (according to the rules used by the C compiler). - -Alternatively, the first character of the format string can be used to -indicate the byte order, size and alignment of the packed data, -according to the following table: - -\begin{tableiii}{c|l|l}{samp}{Character}{Byte order}{Size and alignment} - \lineiii{@}{native}{native} - \lineiii{=}{native}{standard} - \lineiii{<}{little-endian}{standard} - \lineiii{>}{big-endian}{standard} - \lineiii{!}{network (= big-endian)}{standard} -\end{tableiii} - -If the first character is not one of these, \character{@} is assumed. - -Native byte order is big-endian or little-endian, depending on the -host system. For example, Motorola and Sun processors are big-endian; -Intel and DEC processors are little-endian. - -Native size and alignment are determined using the C compiler's -\keyword{sizeof} expression. This is always combined with native byte -order. - -Standard size and alignment are as follows: no alignment is required -for any type (so you have to use pad bytes); -\ctype{short} is 2 bytes; -\ctype{int} and \ctype{long} are 4 bytes; -\ctype{long long} (\ctype{__int64} on Windows) is 8 bytes; -\ctype{float} and \ctype{double} are 32-bit and 64-bit -IEEE floating point numbers, respectively. -\ctype{_Bool} is 1 byte. - -Note the difference between \character{@} and \character{=}: both use -native byte order, but the size and alignment of the latter is -standardized. - -The form \character{!} is available for those poor souls who claim they -can't remember whether network byte order is big-endian or -little-endian. - -There is no way to indicate non-native byte order (force -byte-swapping); use the appropriate choice of \character{<} or -\character{>}. - -The \character{P} format character is only available for the native -byte ordering (selected as the default or with the \character{@} byte -order character). The byte order character \character{=} chooses to -use little- or big-endian ordering based on the host system. The -struct module does not interpret this as native ordering, so the -\character{P} format is not available. - -Examples (all using native byte order, size and alignment, on a -big-endian machine): - -\begin{verbatim} ->>> from struct import * ->>> pack('hhl', 1, 2, 3) -'\x00\x01\x00\x02\x00\x00\x00\x03' ->>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03') -(1, 2, 3) ->>> calcsize('hhl') -8 -\end{verbatim} - -Hint: to align the end of a structure to the alignment requirement of -a particular type, end the format with the code for that type with a -repeat count of zero. For example, the format \code{'llh0l'} -specifies two pad bytes at the end, assuming longs are aligned on -4-byte boundaries. This only works when native size and alignment are -in effect; standard size and alignment does not enforce any alignment. - -\begin{seealso} - \seemodule{array}{Packed binary storage of homogeneous data.} - \seemodule{xdrlib}{Packing and unpacking of XDR data.} -\end{seealso} - -\subsection{Struct Objects \label{struct-objects}} - -The \module{struct} module also defines the following type: - -\begin{classdesc}{Struct}{format} - Return a new Struct object which writes and reads binary data according to - the format string \var{format}. Creating a Struct object once and calling - its methods is more efficient than calling the \module{struct} functions - with the same format since the format string only needs to be compiled once. - - \versionadded{2.5} -\end{classdesc} - -Compiled Struct objects support the following methods and attributes: - -\begin{methoddesc}[Struct]{pack}{v1, v2, \moreargs} - Identical to the \function{pack()} function, using the compiled format. - (\code{len(result)} will equal \member{self.size}.) -\end{methoddesc} - -\begin{methoddesc}[Struct]{pack_into}{buffer, offset, v1, v2, \moreargs} - Identical to the \function{pack_into()} function, using the compiled format. -\end{methoddesc} - -\begin{methoddesc}[Struct]{unpack}{string} - Identical to the \function{unpack()} function, using the compiled format. - (\code{len(string)} must equal \member{self.size}). -\end{methoddesc} - -\begin{methoddesc}[Struct]{unpack_from}{buffer\optional{,offset - \code{= 0}}} - Identical to the \function{unpack_from()} function, using the compiled format. - (\code{len(buffer[offset:])} must be at least \member{self.size}). -\end{methoddesc} - -\begin{memberdesc}[Struct]{format} - The format string used to construct this Struct object. -\end{memberdesc} - diff --git a/Doc/lib/libsubprocess.tex b/Doc/lib/libsubprocess.tex deleted file mode 100644 index e2a9bb6..0000000 --- a/Doc/lib/libsubprocess.tex +++ /dev/null @@ -1,340 +0,0 @@ -\section{\module{subprocess} --- Subprocess management} - -\declaremodule{standard}{subprocess} -\modulesynopsis{Subprocess management.} -\moduleauthor{Peter \AA strand}{astrand@lysator.liu.se} -\sectionauthor{Peter \AA strand}{astrand@lysator.liu.se} - -\versionadded{2.4} - -The \module{subprocess} module allows you to spawn new processes, -connect to their input/output/error pipes, and obtain their return -codes. This module intends to replace several other, older modules -and functions, such as: - -\begin{verbatim} -os.system -os.spawn* -commands.* -\end{verbatim} - -Information about how the \module{subprocess} module can be used to -replace these modules and functions can be found in the following -sections. - -\subsection{Using the subprocess Module} - -This module defines one class called \class{Popen}: - -\begin{classdesc}{Popen}{args, bufsize=0, executable=None, - stdin=None, stdout=None, stderr=None, - preexec_fn=None, close_fds=False, shell=False, - cwd=None, env=None, universal_newlines=False, - startupinfo=None, creationflags=0} - -Arguments are: - -\var{args} should be a string, or a sequence of program arguments. The -program to execute is normally the first item in the args sequence or -string, but can be explicitly set by using the executable argument. - -On \UNIX{}, with \var{shell=False} (default): In this case, the Popen -class uses \method{os.execvp()} to execute the child program. -\var{args} should normally be a sequence. A string will be treated as a -sequence with the string as the only item (the program to execute). - -On \UNIX{}, with \var{shell=True}: If args is a string, it specifies the -command string to execute through the shell. If \var{args} is a -sequence, the first item specifies the command string, and any -additional items will be treated as additional shell arguments. - -On Windows: the \class{Popen} class uses CreateProcess() to execute -the child program, which operates on strings. If \var{args} is a -sequence, it will be converted to a string using the -\method{list2cmdline} method. Please note that not all MS Windows -applications interpret the command line the same way: -\method{list2cmdline} is designed for applications using the same -rules as the MS C runtime. - -\var{bufsize}, if given, has the same meaning as the corresponding -argument to the built-in open() function: \constant{0} means unbuffered, -\constant{1} means line buffered, any other positive value means use a -buffer of (approximately) that size. A negative \var{bufsize} means to -use the system default, which usually means fully buffered. The default -value for \var{bufsize} is \constant{0} (unbuffered). - -The \var{executable} argument specifies the program to execute. It is -very seldom needed: Usually, the program to execute is defined by the -\var{args} argument. If \code{shell=True}, the \var{executable} -argument specifies which shell to use. On \UNIX{}, the default shell -is \file{/bin/sh}. On Windows, the default shell is specified by the -\envvar{COMSPEC} environment variable. - -\var{stdin}, \var{stdout} and \var{stderr} specify the executed -programs' standard input, standard output and standard error file -handles, respectively. Valid values are \code{PIPE}, an existing file -descriptor (a positive integer), an existing file object, and -\code{None}. \code{PIPE} indicates that a new pipe to the child -should be created. With \code{None}, no redirection will occur; the -child's file handles will be inherited from the parent. Additionally, -\var{stderr} can be \code{STDOUT}, which indicates that the stderr -data from the applications should be captured into the same file -handle as for stdout. - -If \var{preexec_fn} is set to a callable object, this object will be -called in the child process just before the child is executed. -(\UNIX{} only) - -If \var{close_fds} is true, all file descriptors except \constant{0}, -\constant{1} and \constant{2} will be closed before the child process is -executed. (\UNIX{} only). Or, on Windows, if \var{close_fds} is true -then no handles will be inherited by the child process. Note that on -Windows, you cannot set \var{close_fds} to true and also redirect the -standard handles by setting \var{stdin}, \var{stdout} or \var{stderr}. - -If \var{shell} is \constant{True}, the specified command will be -executed through the shell. - -If \var{cwd} is not \code{None}, the child's current directory will be -changed to \var{cwd} before it is executed. Note that this directory -is not considered when searching the executable, so you can't specify -the program's path relative to \var{cwd}. - -If \var{env} is not \code{None}, it defines the environment variables -for the new process. - -If \var{universal_newlines} is \constant{True}, the file objects stdout -and stderr are opened as text files, but lines may be terminated by -any of \code{'\e n'}, the \UNIX{} end-of-line convention, \code{'\e r'}, -the Macintosh convention or \code{'\e r\e n'}, the Windows convention. -All of these external representations are seen as \code{'\e n'} by the -Python program. \note{This feature is only available if Python is built -with universal newline support (the default). Also, the newlines -attribute of the file objects \member{stdout}, \member{stdin} and -\member{stderr} are not updated by the communicate() method.} - -The \var{startupinfo} and \var{creationflags}, if given, will be -passed to the underlying CreateProcess() function. They can specify -things such as appearance of the main window and priority for the new -process. (Windows only) -\end{classdesc} - -\subsubsection{Convenience Functions} - -This module also defines two shortcut functions: - -\begin{funcdesc}{call}{*popenargs, **kwargs} -Run command with arguments. Wait for command to complete, then -return the \member{returncode} attribute. - -The arguments are the same as for the Popen constructor. Example: - -\begin{verbatim} - retcode = call(["ls", "-l"]) -\end{verbatim} -\end{funcdesc} - -\begin{funcdesc}{check_call}{*popenargs, **kwargs} -Run command with arguments. Wait for command to complete. If the exit -code was zero then return, otherwise raise \exception{CalledProcessError.} -The \exception{CalledProcessError} object will have the return code in the -\member{returncode} attribute. - -The arguments are the same as for the Popen constructor. Example: - -\begin{verbatim} - check_call(["ls", "-l"]) -\end{verbatim} - -\versionadded{2.5} -\end{funcdesc} - -\subsubsection{Exceptions} - -Exceptions raised in the child process, before the new program has -started to execute, will be re-raised in the parent. Additionally, -the exception object will have one extra attribute called -\member{child_traceback}, which is a string containing traceback -information from the childs point of view. - -The most common exception raised is \exception{OSError}. This occurs, -for example, when trying to execute a non-existent file. Applications -should prepare for \exception{OSError} exceptions. - -A \exception{ValueError} will be raised if \class{Popen} is called -with invalid arguments. - -check_call() will raise \exception{CalledProcessError}, if the called -process returns a non-zero return code. - - -\subsubsection{Security} - -Unlike some other popen functions, this implementation will never call -/bin/sh implicitly. This means that all characters, including shell -metacharacters, can safely be passed to child processes. - - -\subsection{Popen Objects} - -Instances of the \class{Popen} class have the following methods: - -\begin{methoddesc}[Popen]{poll}{} -Check if child process has terminated. Returns returncode -attribute. -\end{methoddesc} - -\begin{methoddesc}[Popen]{wait}{} -Wait for child process to terminate. Returns returncode attribute. -\end{methoddesc} - -\begin{methoddesc}[Popen]{communicate}{input=None} -Interact with process: Send data to stdin. Read data from stdout and -stderr, until end-of-file is reached. Wait for process to terminate. -The optional \var{input} argument should be a string to be sent to the -child process, or \code{None}, if no data should be sent to the child. - -communicate() returns a tuple (stdout, stderr). - -\note{The data read is buffered in memory, so do not use this method -if the data size is large or unlimited.} -\end{methoddesc} - -The following attributes are also available: - -\begin{memberdesc}[Popen]{stdin} -If the \var{stdin} argument is \code{PIPE}, this attribute is a file -object that provides input to the child process. Otherwise, it is -\code{None}. -\end{memberdesc} - -\begin{memberdesc}[Popen]{stdout} -If the \var{stdout} argument is \code{PIPE}, this attribute is a file -object that provides output from the child process. Otherwise, it is -\code{None}. -\end{memberdesc} - -\begin{memberdesc}[Popen]{stderr} -If the \var{stderr} argument is \code{PIPE}, this attribute is file -object that provides error output from the child process. Otherwise, -it is \code{None}. -\end{memberdesc} - -\begin{memberdesc}[Popen]{pid} -The process ID of the child process. -\end{memberdesc} - -\begin{memberdesc}[Popen]{returncode} -The child return code. A \code{None} value indicates that the process -hasn't terminated yet. A negative value -N indicates that the child -was terminated by signal N (\UNIX{} only). -\end{memberdesc} - - -\subsection{Replacing Older Functions with the subprocess Module} - -In this section, "a ==> b" means that b can be used as a replacement -for a. - -\note{All functions in this section fail (more or less) silently if -the executed program cannot be found; this module raises an -\exception{OSError} exception.} - -In the following examples, we assume that the subprocess module is -imported with "from subprocess import *". - -\subsubsection{Replacing /bin/sh shell backquote} - -\begin{verbatim} -output=`mycmd myarg` -==> -output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0] -\end{verbatim} - -\subsubsection{Replacing shell pipe line} - -\begin{verbatim} -output=`dmesg | grep hda` -==> -p1 = Popen(["dmesg"], stdout=PIPE) -p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE) -output = p2.communicate()[0] -\end{verbatim} - -\subsubsection{Replacing os.system()} - -\begin{verbatim} -sts = os.system("mycmd" + " myarg") -==> -p = Popen("mycmd" + " myarg", shell=True) -sts = os.waitpid(p.pid, 0) -\end{verbatim} - -Notes: - -\begin{itemize} -\item Calling the program through the shell is usually not required. -\item It's easier to look at the \member{returncode} attribute than - the exit status. -\end{itemize} - -A more realistic example would look like this: - -\begin{verbatim} -try: - retcode = call("mycmd" + " myarg", shell=True) - if retcode < 0: - print >>sys.stderr, "Child was terminated by signal", -retcode - else: - print >>sys.stderr, "Child returned", retcode -except OSError as e: - print >>sys.stderr, "Execution failed:", e -\end{verbatim} - -\subsubsection{Replacing os.spawn*} - -P_NOWAIT example: - -\begin{verbatim} -pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg") -==> -pid = Popen(["/bin/mycmd", "myarg"]).pid -\end{verbatim} - -P_WAIT example: - -\begin{verbatim} -retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg") -==> -retcode = call(["/bin/mycmd", "myarg"]) -\end{verbatim} - -Vector example: - -\begin{verbatim} -os.spawnvp(os.P_NOWAIT, path, args) -==> -Popen([path] + args[1:]) -\end{verbatim} - -Environment example: - -\begin{verbatim} -os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env) -==> -Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"}) -\end{verbatim} - -\subsubsection{Replacing os.popen*} - -\begin{verbatim} -pipe = os.popen(cmd, mode='r', bufsize) -==> -pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout -\end{verbatim} - -\begin{verbatim} -pipe = os.popen(cmd, mode='w', bufsize) -==> -pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin -\end{verbatim} diff --git a/Doc/lib/libsunau.tex b/Doc/lib/libsunau.tex deleted file mode 100644 index 235bc3b..0000000 --- a/Doc/lib/libsunau.tex +++ /dev/null @@ -1,218 +0,0 @@ -\section{\module{sunau} --- - Read and write Sun AU files} - -\declaremodule{standard}{sunau} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Provide an interface to the Sun AU sound format.} - -The \module{sunau} module provides a convenient interface to the Sun -AU sound format. Note that this module is interface-compatible with -the modules \refmodule{aifc} and \refmodule{wave}. - -An audio file consists of a header followed by the data. The fields -of the header are: - -\begin{tableii}{l|l}{textrm}{Field}{Contents} - \lineii{magic word}{The four bytes \samp{.snd}.} - \lineii{header size}{Size of the header, including info, in bytes.} - \lineii{data size}{Physical size of the data, in bytes.} - \lineii{encoding}{Indicates how the audio samples are encoded.} - \lineii{sample rate}{The sampling rate.} - \lineii{\# of channels}{The number of channels in the samples.} - \lineii{info}{\ASCII{} string giving a description of the audio - file (padded with null bytes).} -\end{tableii} - -Apart from the info field, all header fields are 4 bytes in size. -They are all 32-bit unsigned integers encoded in big-endian byte -order. - - -The \module{sunau} module defines the following functions: - -\begin{funcdesc}{open}{file, mode} -If \var{file} is a string, open the file by that name, otherwise treat it -as a seekable file-like object. \var{mode} can be any of -\begin{description} - \item[\code{'r'}] Read only mode. - \item[\code{'w'}] Write only mode. -\end{description} -Note that it does not allow read/write files. - -A \var{mode} of \code{'r'} returns a \class{AU_read} -object, while a \var{mode} of \code{'w'} or \code{'wb'} returns -a \class{AU_write} object. -\end{funcdesc} - -\begin{funcdesc}{openfp}{file, mode} -A synonym for \function{open}, maintained for backwards compatibility. -\end{funcdesc} - -The \module{sunau} module defines the following exception: - -\begin{excdesc}{Error} -An error raised when something is impossible because of Sun AU specs or -implementation deficiency. -\end{excdesc} - -The \module{sunau} module defines the following data items: - -\begin{datadesc}{AUDIO_FILE_MAGIC} -An integer every valid Sun AU file begins with, stored in big-endian -form. This is the string \samp{.snd} interpreted as an integer. -\end{datadesc} - -\begin{datadesc}{AUDIO_FILE_ENCODING_MULAW_8} -\dataline{AUDIO_FILE_ENCODING_LINEAR_8} -\dataline{AUDIO_FILE_ENCODING_LINEAR_16} -\dataline{AUDIO_FILE_ENCODING_LINEAR_24} -\dataline{AUDIO_FILE_ENCODING_LINEAR_32} -\dataline{AUDIO_FILE_ENCODING_ALAW_8} -Values of the encoding field from the AU header which are supported by -this module. -\end{datadesc} - -\begin{datadesc}{AUDIO_FILE_ENCODING_FLOAT} -\dataline{AUDIO_FILE_ENCODING_DOUBLE} -\dataline{AUDIO_FILE_ENCODING_ADPCM_G721} -\dataline{AUDIO_FILE_ENCODING_ADPCM_G722} -\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_3} -\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_5} -Additional known values of the encoding field from the AU header, but -which are not supported by this module. -\end{datadesc} - - -\subsection{AU_read Objects \label{au-read-objects}} - -AU_read objects, as returned by \function{open()} above, have the -following methods: - -\begin{methoddesc}[AU_read]{close}{} -Close the stream, and make the instance unusable. (This is -called automatically on deletion.) -\end{methoddesc} - -\begin{methoddesc}[AU_read]{getnchannels}{} -Returns number of audio channels (1 for mone, 2 for stereo). -\end{methoddesc} - -\begin{methoddesc}[AU_read]{getsampwidth}{} -Returns sample width in bytes. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{getframerate}{} -Returns sampling frequency. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{getnframes}{} -Returns number of audio frames. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{getcomptype}{} -Returns compression type. -Supported compression types are \code{'ULAW'}, \code{'ALAW'} and \code{'NONE'}. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{getcompname}{} -Human-readable version of \method{getcomptype()}. -The supported types have the respective names \code{'CCITT G.711 -u-law'}, \code{'CCITT G.711 A-law'} and \code{'not compressed'}. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{getparams}{} -Returns a tuple \code{(\var{nchannels}, \var{sampwidth}, -\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, -equivalent to output of the \method{get*()} methods. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{readframes}{n} -Reads and returns at most \var{n} frames of audio, as a string of -bytes. The data will be returned in linear format. If the original -data is in u-LAW format, it will be converted. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{rewind}{} -Rewind the file pointer to the beginning of the audio stream. -\end{methoddesc} - -The following two methods define a term ``position'' which is compatible -between them, and is otherwise implementation dependent. - -\begin{methoddesc}[AU_read]{setpos}{pos} -Set the file pointer to the specified position. Only values returned -from \method{tell()} should be used for \var{pos}. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{tell}{} -Return current file pointer position. Note that the returned value -has nothing to do with the actual position in the file. -\end{methoddesc} - -The following two functions are defined for compatibility with the -\refmodule{aifc}, and don't do anything interesting. - -\begin{methoddesc}[AU_read]{getmarkers}{} -Returns \code{None}. -\end{methoddesc} - -\begin{methoddesc}[AU_read]{getmark}{id} -Raise an error. -\end{methoddesc} - - -\subsection{AU_write Objects \label{au-write-objects}} - -AU_write objects, as returned by \function{open()} above, have the -following methods: - -\begin{methoddesc}[AU_write]{setnchannels}{n} -Set the number of channels. -\end{methoddesc} - -\begin{methoddesc}[AU_write]{setsampwidth}{n} -Set the sample width (in bytes.) -\end{methoddesc} - -\begin{methoddesc}[AU_write]{setframerate}{n} -Set the frame rate. -\end{methoddesc} - -\begin{methoddesc}[AU_write]{setnframes}{n} -Set the number of frames. This can be later changed, when and if more -frames are written. -\end{methoddesc} - - -\begin{methoddesc}[AU_write]{setcomptype}{type, name} -Set the compression type and description. -Only \code{'NONE'} and \code{'ULAW'} are supported on output. -\end{methoddesc} - -\begin{methoddesc}[AU_write]{setparams}{tuple} -The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth}, -\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with -values valid for the \method{set*()} methods. Set all parameters. -\end{methoddesc} - -\begin{methoddesc}[AU_write]{tell}{} -Return current position in the file, with the same disclaimer for -the \method{AU_read.tell()} and \method{AU_read.setpos()} methods. -\end{methoddesc} - -\begin{methoddesc}[AU_write]{writeframesraw}{data} -Write audio frames, without correcting \var{nframes}. -\end{methoddesc} - -\begin{methoddesc}[AU_write]{writeframes}{data} -Write audio frames and make sure \var{nframes} is correct. -\end{methoddesc} - -\begin{methoddesc}[AU_write]{close}{} -Make sure \var{nframes} is correct, and close the file. - -This method is called upon deletion. -\end{methoddesc} - -Note that it is invalid to set any parameters after calling -\method{writeframes()} or \method{writeframesraw()}. diff --git a/Doc/lib/libsymbol.tex b/Doc/lib/libsymbol.tex deleted file mode 100644 index 54cabeb..0000000 --- a/Doc/lib/libsymbol.tex +++ /dev/null @@ -1,30 +0,0 @@ -\section{\module{symbol} --- - Constants used with Python parse trees} - -\declaremodule{standard}{symbol} -\modulesynopsis{Constants representing internal nodes of the parse tree.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -This module provides constants which represent the numeric values of -internal nodes of the parse tree. Unlike most Python constants, these -use lower-case names. Refer to the file \file{Grammar/Grammar} in the -Python distribution for the definitions of the names in the context of -the language grammar. The specific numeric values which the names map -to may change between Python versions. - -This module also provides one additional data object: - - -\begin{datadesc}{sym_name} - Dictionary mapping the numeric values of the constants defined in - this module back to name strings, allowing more human-readable - representation of parse trees to be generated. -\end{datadesc} - - -\begin{seealso} - \seemodule{parser}{The second example for the \refmodule{parser} - module shows how to use the \module{symbol} - module.} -\end{seealso} diff --git a/Doc/lib/libsys.tex b/Doc/lib/libsys.tex deleted file mode 100644 index 4ab3247..0000000 --- a/Doc/lib/libsys.tex +++ /dev/null @@ -1,582 +0,0 @@ -\section{\module{sys} --- - System-specific parameters and functions} - -\declaremodule{builtin}{sys} -\modulesynopsis{Access system-specific parameters and functions.} - -This module provides access to some variables used or maintained by the -interpreter and to functions that interact strongly with the interpreter. -It is always available. - - -\begin{datadesc}{argv} - The list of command line arguments passed to a Python script. - \code{argv[0]} is the script name (it is operating system dependent - whether this is a full pathname or not). If the command was - executed using the \programopt{-c} command line option to the - interpreter, \code{argv[0]} is set to the string \code{'-c'}. If no - script name was passed to the Python interpreter, \code{argv[0]} is - the empty string. -\end{datadesc} - -\begin{datadesc}{byteorder} - An indicator of the native byte order. This will have the value - \code{'big'} on big-endian (most-significant byte first) platforms, - and \code{'little'} on little-endian (least-significant byte first) - platforms. - \versionadded{2.0} -\end{datadesc} - -\begin{datadesc}{subversion} - A triple (repo, branch, version) representing the Subversion - information of the Python interpreter. - \var{repo} is the name of the repository, \code{'CPython'}. - \var{branch} is a string of one of the forms \code{'trunk'}, - \code{'branches/name'} or \code{'tags/name'}. - \var{version} is the output of \code{svnversion}, if the - interpreter was built from a Subversion checkout; it contains - the revision number (range) and possibly a trailing 'M' if - there were local modifications. If the tree was exported - (or svnversion was not available), it is the revision of - \code{Include/patchlevel.h} if the branch is a tag. Otherwise, - it is \code{None}. - \versionadded{2.5} -\end{datadesc} - -\begin{datadesc}{builtin_module_names} - A tuple of strings giving the names of all modules that are compiled - into this Python interpreter. (This information is not available in - any other way --- \code{modules.keys()} only lists the imported - modules.) -\end{datadesc} - -\begin{datadesc}{copyright} - A string containing the copyright pertaining to the Python - interpreter. -\end{datadesc} - -\begin{funcdesc}{_current_frames}{} - Return a dictionary mapping each thread's identifier to the topmost stack - frame currently active in that thread at the time the function is called. - Note that functions in the \refmodule{traceback} module can build the - call stack given such a frame. - - This is most useful for debugging deadlock: this function does not - require the deadlocked threads' cooperation, and such threads' call stacks - are frozen for as long as they remain deadlocked. The frame returned - for a non-deadlocked thread may bear no relationship to that thread's - current activity by the time calling code examines the frame. - - This function should be used for internal and specialized purposes - only. - \versionadded{2.5} -\end{funcdesc} - -\begin{datadesc}{dllhandle} - Integer specifying the handle of the Python DLL. - Availability: Windows. -\end{datadesc} - -\begin{funcdesc}{displayhook}{\var{value}} - If \var{value} is not \code{None}, this function prints it to - \code{sys.stdout}, and saves it in \code{__builtin__._}. - - \code{sys.displayhook} is called on the result of evaluating an - expression entered in an interactive Python session. The display of - these values can be customized by assigning another one-argument - function to \code{sys.displayhook}. -\end{funcdesc} - -\begin{funcdesc}{excepthook}{\var{type}, \var{value}, \var{traceback}} - This function prints out a given traceback and exception to - \code{sys.stderr}. - - When an exception is raised and uncaught, the interpreter calls - \code{sys.excepthook} with three arguments, the exception class, - exception instance, and a traceback object. In an interactive - session this happens just before control is returned to the prompt; - in a Python program this happens just before the program exits. The - handling of such top-level exceptions can be customized by assigning - another three-argument function to \code{sys.excepthook}. -\end{funcdesc} - -\begin{datadesc}{__displayhook__} -\dataline{__excepthook__} - These objects contain the original values of \code{displayhook} and - \code{excepthook} at the start of the program. They are saved so - that \code{displayhook} and \code{excepthook} can be restored in - case they happen to get replaced with broken objects. -\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 returned is specific both to the current thread and to - the current stack frame. If the current stack frame is not handling - an exception, the information is taken from the calling stack frame, - or its caller, and so on until a stack frame is found that is - handling an exception. Here, ``handling an exception'' is defined - as ``executing or having executed an except clause.'' For any stack - frame, only information about the most recently handled exception is - accessible. - - If no exception is being handled anywhere on the stack, a tuple - containing three \code{None} values is returned. Otherwise, the - values returned are \code{(\var{type}, \var{value}, - \var{traceback})}. Their meaning is: \var{type} gets the exception - type of the exception being handled (a class object); - \var{value} gets the exception parameter (its \dfn{associated value} - or the second argument to \keyword{raise}, which is always a class - instance if the exception type is a class object); \var{traceback} - gets a traceback object (see the Reference Manual) which - encapsulates the call stack at the point where the exception - originally occurred. \obindex{traceback} - - \warning{Assigning the \var{traceback} return value to a - local variable in a function that is handling an exception will - cause a circular reference. This will prevent anything referenced - by a local variable in the same function or by the traceback from - being garbage collected. Since most functions don't need access to - the traceback, the best solution is to use something like - \code{exctype, value = sys.exc_info()[:2]} to extract only the - exception type and value. If you do need the traceback, make sure - to delete it after use (best done with a \keyword{try} - ... \keyword{finally} statement) or to call \function{exc_info()} in - a function that does not itself handle an exception.} \note{Beginning - with Python 2.2, such cycles are automatically reclaimed when garbage - collection is enabled and they become unreachable, but it remains more - efficient to avoid creating cycles.} -\end{funcdesc} - -\begin{datadesc}{exec_prefix} - A string giving the site-specific directory prefix where the - platform-dependent Python files are installed; by default, this is - also \code{'/usr/local'}. This can be set at build time with the - \longprogramopt{exec-prefix} argument to the \program{configure} - script. Specifically, all configuration files (e.g. the - \file{pyconfig.h} header file) are installed in the directory - \code{exec_prefix + '/lib/python\var{version}/config'}, and shared - library modules are installed in \code{exec_prefix + - '/lib/python\var{version}/lib-dynload'}, where \var{version} is - equal to \code{version[:3]}. -\end{datadesc} - -\begin{datadesc}{executable} - A string giving the name of the executable binary for the Python - interpreter, on systems where this makes sense. -\end{datadesc} - -\begin{funcdesc}{exit}{\optional{arg}} - Exit from Python. This is implemented by raising the - \exception{SystemExit} exception, so cleanup actions specified by - finally clauses of \keyword{try} statements are honored, and it is - possible to intercept the exit attempt at an outer level. The - optional argument \var{arg} can be an integer giving the exit status - (defaulting to zero), or another type of object. If it is an - integer, zero is considered ``successful termination'' and any - nonzero value is considered ``abnormal termination'' by shells and - the like. Most systems require it to be in the range 0-127, and - produce undefined results otherwise. Some systems have a convention - for assigning specific meanings to specific exit codes, but these - are generally underdeveloped; \UNIX{} programs generally use 2 for - command line syntax errors and 1 for all other kind of errors. If - another type of object is passed, \code{None} is equivalent to - passing zero, and any other object is printed to \code{sys.stderr} - and results in an exit code of 1. In particular, - \code{sys.exit("some error message")} is a quick way to exit a - program when an error occurs. -\end{funcdesc} - -\begin{funcdesc}{getcheckinterval}{} - Return the interpreter's ``check interval''; - see \function{setcheckinterval()}. - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{getdefaultencoding}{} - Return the name of the current default string encoding used by the - Unicode implementation. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{getdlopenflags}{} - Return the current value of the flags that are used for - \cfunction{dlopen()} calls. The flag constants are defined in the - \refmodule{dl} and \module{DLFCN} modules. - Availability: \UNIX. - \versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{getfilesystemencoding}{} - Return the name of the encoding used to convert Unicode filenames - into system file names, or \code{None} if the system default encoding - is used. The result value depends on the operating system: -\begin{itemize} -\item On Windows 9x, the encoding is ``mbcs''. -\item On Mac OS X, the encoding is ``utf-8''. -\item On \UNIX, the encoding is the user's preference - according to the result of nl_langinfo(CODESET), or \constant{None} - if the \code{nl_langinfo(CODESET)} failed. -\item On Windows NT+, file names are Unicode natively, so no conversion - is performed. \function{getfilesystemencoding()} still returns - \code{'mbcs'}, as this is the encoding that applications should use - when they explicitly want to convert Unicode strings to byte strings - that are equivalent when used as file names. -\end{itemize} - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{getrefcount}{object} - Return the reference count of the \var{object}. The count returned - is generally one higher than you might expect, because it includes - the (temporary) reference as an argument to - \function{getrefcount()}. -\end{funcdesc} - -\begin{funcdesc}{getrecursionlimit}{} - Return the current value of the recursion limit, the maximum depth - of the Python interpreter stack. This limit prevents infinite - recursion from causing an overflow of the C stack and crashing - Python. It can be set by \function{setrecursionlimit()}. -\end{funcdesc} - -\begin{funcdesc}{_getframe}{\optional{depth}} - Return a frame object from the call stack. If optional integer - \var{depth} is given, return the frame object that many calls below - the top of the stack. If that is deeper than the call stack, - \exception{ValueError} is raised. The default for \var{depth} is - zero, returning the frame at the top of the call stack. - - This function should be used for internal and specialized purposes - only. -\end{funcdesc} - -\begin{funcdesc}{getwindowsversion}{} - Return a tuple containing five components, describing the Windows - version currently running. The elements are \var{major}, \var{minor}, - \var{build}, \var{platform}, and \var{text}. \var{text} contains - a string while all other values are integers. - - \var{platform} may be one of the following values: - - \begin{tableii}{l|l}{constant}{Constant}{Platform} - \lineii{0 (VER_PLATFORM_WIN32s)} {Win32s on Windows 3.1} - \lineii{1 (VER_PLATFORM_WIN32_WINDOWS)}{Windows 95/98/ME} - \lineii{2 (VER_PLATFORM_WIN32_NT)} {Windows NT/2000/XP} - \lineii{3 (VER_PLATFORM_WIN32_CE)} {Windows CE} - \end{tableii} - - This function wraps the Win32 \cfunction{GetVersionEx()} function; - see the Microsoft documentation for more information about these - fields. - - Availability: Windows. - \versionadded{2.3} -\end{funcdesc} - -\begin{datadesc}{hexversion} - The version number encoded as a single integer. This is guaranteed - to increase with each version, including proper support for - non-production releases. For example, to test that the Python - interpreter is at least version 1.5.2, use: - -\begin{verbatim} -if sys.hexversion >= 0x010502F0: - # use some advanced feature - ... -else: - # use an alternative implementation or warn the user - ... -\end{verbatim} - - This is called \samp{hexversion} since it only really looks - meaningful when viewed as the result of passing it to the built-in - \function{hex()} function. The \code{version_info} value may be - used for a more human-friendly encoding of the same information. - \versionadded{1.5.2} -\end{datadesc} - -\begin{funcdesc}{intern}{string} - Enter \var{string} in the table of ``interned'' strings and return - the interned string -- which is \var{string} itself or a copy. - Interning strings is useful to gain a little performance on - dictionary lookup -- if the keys in a dictionary are interned, and - the lookup key is interned, the key comparisons (after hashing) can - be done by a pointer compare instead of a string compare. Normally, - the names used in Python programs are automatically interned, and - the dictionaries used to hold module, class or instance attributes - have interned keys. \versionchanged[Interned strings are not - immortal (like they used to be in Python 2.2 and before); - you must keep a reference to the return value of \function{intern()} - around to benefit from it]{2.3} -\end{funcdesc} - -\begin{datadesc}{last_type} -\dataline{last_value} -\dataline{last_traceback} - These three variables are not always defined; they are set when an - exception is not handled and the interpreter prints an error message - and a stack traceback. Their intended use is to allow an - interactive user to import a debugger module and engage in - post-mortem debugging without having to re-execute the command that - caused the error. (Typical use is \samp{import pdb; pdb.pm()} to - enter the post-mortem debugger; see chapter~\ref{debugger}, ``The - Python Debugger,'' for more information.) - - The meaning of the variables is the same as that of the return - values from \function{exc_info()} above. (Since there is only one - interactive thread, thread-safety is not a concern for these - variables, unlike for \code{exc_type} etc.) -\end{datadesc} - -\begin{datadesc}{maxint} - The largest positive integer supported by Python's regular integer - type. This is at least 2**31-1. The largest negative integer is - \code{-maxint-1} --- the asymmetry results from the use of 2's - complement binary arithmetic. -\end{datadesc} - -\begin{datadesc}{maxunicode} - An integer giving the largest supported code point for a Unicode - character. The value of this depends on the configuration option - that specifies whether Unicode characters are stored as UCS-2 or - UCS-4. -\end{datadesc} - -\begin{datadesc}{modules} - This is a dictionary that maps module names to modules which have - already been loaded. This can be manipulated to force reloading of - modules and other tricks. -\end{datadesc} - -\begin{datadesc}{path} -\indexiii{module}{search}{path} - A list of strings that specifies the search path for modules. - Initialized from the environment variable \envvar{PYTHONPATH}, plus an - installation-dependent default. - - As initialized upon program startup, - the first item of this list, \code{path[0]}, is the directory - containing the script that was used to invoke the Python - interpreter. If the script directory is not available (e.g. if the - interpreter is invoked interactively or if the script is read from - standard input), \code{path[0]} is the empty string, which directs - Python to search modules in the current directory first. Notice - that the script directory is inserted \emph{before} the entries - inserted as a result of \envvar{PYTHONPATH}. - - A program is free to modify this list for its own purposes. - - \versionchanged[Unicode strings are no longer ignored]{2.3} -\end{datadesc} - -\begin{datadesc}{platform} - This string contains a platform identifier, e.g. \code{'sunos5'} or - \code{'linux1'}. This can be used to append platform-specific - components to \code{path}, for instance. -\end{datadesc} - -\begin{datadesc}{prefix} - A string giving the site-specific directory prefix where the - platform independent Python files are installed; by default, this is - the string \code{'/usr/local'}. This can be set at build time with - the \longprogramopt{prefix} argument to the \program{configure} - script. The main collection of Python library modules is installed - in the directory \code{prefix + '/lib/python\var{version}'} while - the platform independent header files (all except \file{pyconfig.h}) - are stored in \code{prefix + '/include/python\var{version}'}, where - \var{version} is equal to \code{version[:3]}. -\end{datadesc} - -\begin{datadesc}{ps1} -\dataline{ps2} -\index{interpreter prompts} -\index{prompts, interpreter} - Strings specifying the primary and secondary prompt of the - interpreter. These are only defined if the interpreter is in - interactive mode. Their initial values in this case are - \code{'>>>~'} and \code{'...~'}. If a non-string object is - assigned to either variable, its \function{str()} is re-evaluated - each time the interpreter prepares to read a new interactive - command; this can be used to implement a dynamic prompt. -\end{datadesc} - -\begin{funcdesc}{setcheckinterval}{interval} - Set the interpreter's ``check interval''. This integer value - determines how often the interpreter checks for periodic things such - as thread switches and signal handlers. The default is \code{100}, - meaning the check is performed every 100 Python virtual instructions. - Setting it to a larger value may increase performance for programs - using threads. Setting it to a value \code{<=} 0 checks every - virtual instruction, maximizing responsiveness as well as overhead. -\end{funcdesc} - -\begin{funcdesc}{setdefaultencoding}{name} - Set the current default string encoding used by the Unicode - implementation. If \var{name} does not match any available - encoding, \exception{LookupError} is raised. This function is only - intended to be used by the \refmodule{site} module implementation - and, where needed, by \module{sitecustomize}. Once used by the - \refmodule{site} module, it is removed from the \module{sys} - module's namespace. -% Note that \refmodule{site} is not imported if -% the \programopt{-S} option is passed to the interpreter, in which -% case this function will remain available. - \versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{setdlopenflags}{n} - Set the flags used by the interpreter for \cfunction{dlopen()} - calls, such as when the interpreter loads extension modules. Among - other things, this will enable a lazy resolving of symbols when - importing a module, if called as \code{sys.setdlopenflags(0)}. To - share symbols across extension modules, call as - \code{sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)}. Symbolic - names for the flag modules can be either found in the \refmodule{dl} - module, or in the \module{DLFCN} module. If \module{DLFCN} is not - available, it can be generated from \file{/usr/include/dlfcn.h} - using the \program{h2py} script. - Availability: \UNIX. - \versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{setprofile}{profilefunc} - Set the system's profile function,\index{profile function} which - allows you to implement a Python source code profiler in - Python.\index{profiler} See chapter~\ref{profile} for more - information on the Python profiler. The system's profile function - is called similarly to the system's trace function (see - \function{settrace()}), but it isn't called for each executed line - of code (only on call and return, but the return event is reported - even when an exception has been set). The function is - thread-specific, but there is no way for the profiler to know about - context switches between threads, so it does not make sense to use - this in the presence of multiple threads. - Also, its return value is not used, so it can simply return - \code{None}. -\end{funcdesc} - -\begin{funcdesc}{setrecursionlimit}{limit} - Set the maximum depth of the Python interpreter stack to - \var{limit}. This limit prevents infinite recursion from causing an - overflow of the C stack and crashing Python. - - The highest possible limit is platform-dependent. A user may need - to set the limit higher when she has a program that requires deep - recursion and a platform that supports a higher limit. This should - be done with care, because a too-high limit can lead to a crash. -\end{funcdesc} - -\begin{funcdesc}{settrace}{tracefunc} - Set the system's trace function,\index{trace function} which allows - you to implement a Python source code debugger in Python. See - section \ref{debugger-hooks}, ``How It Works,'' in the chapter on - the Python debugger.\index{debugger} The function is - thread-specific; for a debugger to support multiple threads, it must - be registered using \function{settrace()} for each thread being - debugged. \note{The \function{settrace()} function is intended only - for implementing debuggers, profilers, coverage tools and the like. - Its behavior is part of the implementation platform, rather than - part of the language definition, and thus may not be available in - all Python implementations.} -\end{funcdesc} - -\begin{funcdesc}{settscdump}{on_flag} - Activate dumping of VM measurements using the Pentium timestamp - counter, if \var{on_flag} is true. Deactivate these dumps if - \var{on_flag} is off. The function is available only if Python - was compiled with \longprogramopt{with-tsc}. To understand the - output of this dump, read \file{Python/ceval.c} in the Python - sources. - \versionadded{2.4} -\end{funcdesc} - -\begin{datadesc}{stdin} -\dataline{stdout} -\dataline{stderr} - File objects corresponding to the interpreter's standard input, - output and error streams. \code{stdin} is used for all interpreter - input except for scripts. \code{stdout} is - used for the output of \keyword{print} and expression statements. - The interpreter's own prompts and (almost all of) its error messages - go to \code{stderr}. \code{stdout} and \code{stderr} needn't be - built-in file objects: any object is acceptable as long as it has a - \method{write()} method that takes a string argument. (Changing - these objects doesn't affect the standard I/O streams of processes - executed by \function{os.popen()}, \function{os.system()} or the - \function{exec*()} family of functions in the \refmodule{os} - module.) -\end{datadesc} - -\begin{datadesc}{__stdin__} -\dataline{__stdout__} -\dataline{__stderr__} - These objects contain the original values of \code{stdin}, - \code{stderr} and \code{stdout} at the start of the program. They - are used during finalization, and could be useful to restore the - actual files to known working file objects in case they have been - overwritten with a broken object. -\end{datadesc} - -\begin{datadesc}{tracebacklimit} - When this variable is set to an integer value, it determines the - maximum number of levels of traceback information printed when an - unhandled exception occurs. The default is \code{1000}. When set - to \code{0} or less, all traceback information is suppressed and - only the exception type and value are printed. -\end{datadesc} - -\begin{datadesc}{version} - 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}{api_version} - The C API version for this interpreter. Programmers may find this useful - when debugging version conflicts between Python and extension - modules. \versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{version_info} - A tuple containing the five components of the version number: - \var{major}, \var{minor}, \var{micro}, \var{releaselevel}, and - \var{serial}. All values except \var{releaselevel} are integers; - the release level is \code{'alpha'}, \code{'beta'}, - \code{'candidate'}, or \code{'final'}. The \code{version_info} - value corresponding to the Python version 2.0 is \code{(2, 0, 0, - 'final', 0)}. - \versionadded{2.0} -\end{datadesc} - -\begin{datadesc}{warnoptions} - This is an implementation detail of the warnings framework; do not - modify this value. Refer to the \refmodule{warnings} module for - more information on the warnings framework. -\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} - - -\begin{seealso} - \seemodule{site} - {This describes how to use .pth files to extend \code{sys.path}.} -\end{seealso} diff --git a/Doc/lib/libsyslog.tex b/Doc/lib/libsyslog.tex deleted file mode 100644 index fc59776..0000000 --- a/Doc/lib/libsyslog.tex +++ /dev/null @@ -1,76 +0,0 @@ -\section{\module{syslog} --- - \UNIX{} syslog library routines} - -\declaremodule{builtin}{syslog} - \platform{Unix} -\modulesynopsis{An interface to the \UNIX\ syslog library routines.} - - -This module provides an interface to the \UNIX{} \code{syslog} library -routines. Refer to the \UNIX{} manual pages for a detailed description -of the \code{syslog} facility. - -The module defines the following functions: - - -\begin{funcdesc}{syslog}{\optional{priority,} message} -Send the string \var{message} to the system logger. A trailing -newline is added if necessary. Each message is tagged with a priority -composed of a \var{facility} and a \var{level}. The optional -\var{priority} argument, which defaults to \constant{LOG_INFO}, -determines the message priority. If the facility is not encoded in -\var{priority} using logical-or (\code{LOG_INFO | LOG_USER}), the -value given in the \function{openlog()} call is used. -\end{funcdesc} - -\begin{funcdesc}{openlog}{ident\optional{, logopt\optional{, facility}}} -Logging options other than the defaults can be set by explicitly -opening the log file with \function{openlog()} prior to calling -\function{syslog()}. The defaults are (usually) \var{ident} = -\code{'syslog'}, \var{logopt} = \code{0}, \var{facility} = -\constant{LOG_USER}. The \var{ident} argument is a string which is -prepended to every message. The optional \var{logopt} argument is a -bit field - see below for possible values to combine. The optional -\var{facility} argument sets the default facility for messages which -do not have a facility explicitly encoded. -\end{funcdesc} - -\begin{funcdesc}{closelog}{} -Close the log file. -\end{funcdesc} - -\begin{funcdesc}{setlogmask}{maskpri} -Set the priority mask to \var{maskpri} and return the -previous mask value. Calls to \function{syslog()} with a priority -level not set in \var{maskpri} are ignored. The default is to log all -priorities. The function \code{LOG_MASK(\var{pri})} calculates the -mask for the individual priority \var{pri}. The function -\code{LOG_UPTO(\var{pri})} calculates the mask for all priorities up -to and including \var{pri}. -\end{funcdesc} - - -The module defines the following constants: - -\begin{description} - -\item[Priority levels (high to low):] - -\constant{LOG_EMERG}, \constant{LOG_ALERT}, \constant{LOG_CRIT}, -\constant{LOG_ERR}, \constant{LOG_WARNING}, \constant{LOG_NOTICE}, -\constant{LOG_INFO}, \constant{LOG_DEBUG}. - -\item[Facilities:] - -\constant{LOG_KERN}, \constant{LOG_USER}, \constant{LOG_MAIL}, -\constant{LOG_DAEMON}, \constant{LOG_AUTH}, \constant{LOG_LPR}, -\constant{LOG_NEWS}, \constant{LOG_UUCP}, \constant{LOG_CRON} and -\constant{LOG_LOCAL0} to \constant{LOG_LOCAL7}. - -\item[Log options:] - -\constant{LOG_PID}, \constant{LOG_CONS}, \constant{LOG_NDELAY}, -\constant{LOG_NOWAIT} and \constant{LOG_PERROR} if defined in -\code{<syslog.h>}. - -\end{description} diff --git a/Doc/lib/libtabnanny.tex b/Doc/lib/libtabnanny.tex deleted file mode 100644 index 12b9385..0000000 --- a/Doc/lib/libtabnanny.tex +++ /dev/null @@ -1,62 +0,0 @@ -\section{\module{tabnanny} --- - Detection of ambiguous indentation} - -% rudimentary documentation based on module comments, by Peter Funk -% <pf@artcom-gmbh.de> - -\declaremodule{standard}{tabnanny} -\modulesynopsis{Tool for detecting white space related problems - in Python source files in a directory tree.} -\moduleauthor{Tim Peters}{tim_one@users.sourceforge.net} -\sectionauthor{Peter Funk}{pf@artcom-gmbh.de} - -For the time being this module is intended to be called as a script. -However it is possible to import it into an IDE and use the function -\function{check()} described below. - -\warning{The API provided by this module is likely to change -in future releases; such changes may not be backward compatible.} - -\begin{funcdesc}{check}{file_or_dir} - If \var{file_or_dir} is a directory and not a symbolic link, then - recursively descend the directory tree named by \var{file_or_dir}, - checking all \file{.py} files along the way. If \var{file_or_dir} - is an ordinary Python source file, it is checked for whitespace - related problems. The diagnostic messages are written to standard - output using the print statement. -\end{funcdesc} - - -\begin{datadesc}{verbose} - Flag indicating whether to print verbose messages. - This is incremented by the \code{-v} option if called as a script. -\end{datadesc} - - -\begin{datadesc}{filename_only} - Flag indicating whether to print only the filenames of files - containing whitespace related problems. This is set to true by the - \code{-q} option if called as a script. -\end{datadesc} - - -\begin{excdesc}{NannyNag} - Raised by \function{tokeneater()} if detecting an ambiguous indent. - Captured and handled in \function{check()}. -\end{excdesc} - - -\begin{funcdesc}{tokeneater}{type, token, start, end, line} - This function is used by \function{check()} as a callback parameter to - the function \function{tokenize.tokenize()}. -\end{funcdesc} - -% XXX FIXME: Document \function{errprint}, -% \function{format_witnesses} \class{Whitespace} -% check_equal, indents -% \function{reset_globals} - -\begin{seealso} - \seemodule{tokenize}{Lexical scanner for Python source code.} - % XXX may be add a reference to IDLE? -\end{seealso} diff --git a/Doc/lib/libtarfile.tex b/Doc/lib/libtarfile.tex deleted file mode 100644 index 95ea051..0000000 --- a/Doc/lib/libtarfile.tex +++ /dev/null @@ -1,664 +0,0 @@ -\section{\module{tarfile} --- Read and write tar archive files} - -\declaremodule{standard}{tarfile} -\modulesynopsis{Read and write tar-format archive files.} -\versionadded{2.3} - -\moduleauthor{Lars Gust\"abel}{lars@gustaebel.de} -\sectionauthor{Lars Gust\"abel}{lars@gustaebel.de} - -The \module{tarfile} module makes it possible to read and create tar archives. -Some facts and figures: - -\begin{itemize} -\item reads and writes \module{gzip} and \module{bzip2} compressed archives. -\item read/write support for the \POSIX{}.1-1988 (ustar) format. -\item read/write support for the GNU tar format including \emph{longname} and - \emph{longlink} extensions, read-only support for the \emph{sparse} - extension. -\item read/write support for the \POSIX{}.1-2001 (pax) format. - \versionadded{2.6} -\item handles directories, regular files, hardlinks, symbolic links, fifos, - character devices and block devices and is able to acquire and - restore file information like timestamp, access permissions and owner. -\item can handle tape devices. -\end{itemize} - -\begin{funcdesc}{open}{name\optional{, mode\optional{, - fileobj\optional{, bufsize}}}, **kwargs} - Return a \class{TarFile} object for the pathname \var{name}. - For detailed information on \class{TarFile} objects and the keyword - arguments that are allowed, see \citetitle{TarFile Objects} - (section \ref{tarfile-objects}). - - \var{mode} has to be a string of the form \code{'filemode[:compression]'}, - it defaults to \code{'r'}. Here is a full list of mode combinations: - - \begin{tableii}{c|l}{code}{mode}{action} - \lineii{'r' or 'r:*'}{Open for reading with transparent compression (recommended).} - \lineii{'r:'}{Open for reading exclusively without compression.} - \lineii{'r:gz'}{Open for reading with gzip compression.} - \lineii{'r:bz2'}{Open for reading with bzip2 compression.} - \lineii{'a' or 'a:'}{Open for appending with no compression. The file - is created if it does not exist.} - \lineii{'w' or 'w:'}{Open for uncompressed writing.} - \lineii{'w:gz'}{Open for gzip compressed writing.} - \lineii{'w:bz2'}{Open for bzip2 compressed writing.} - \end{tableii} - - Note that \code{'a:gz'} or \code{'a:bz2'} is not possible. - If \var{mode} is not suitable to open a certain (compressed) file for - reading, \exception{ReadError} is raised. Use \var{mode} \code{'r'} to - avoid this. If a compression method is not supported, - \exception{CompressionError} is raised. - - If \var{fileobj} is specified, it is used as an alternative to a file - object opened for \var{name}. It is supposed to be at position 0. - - For special purposes, there is a second format for \var{mode}: - \code{'filemode|[compression]'}. \function{open()} will return a - \class{TarFile} object that processes its data as a stream of - blocks. No random seeking will be done on the file. If given, - \var{fileobj} may be any object that has a \method{read()} or - \method{write()} method (depending on the \var{mode}). - \var{bufsize} specifies the blocksize and defaults to \code{20 * - 512} bytes. Use this variant in combination with - e.g. \code{sys.stdin}, a socket file object or a tape device. - However, such a \class{TarFile} object is limited in that it does - not allow to be accessed randomly, see ``Examples'' - (section~\ref{tar-examples}). The currently possible modes: - - \begin{tableii}{c|l}{code}{Mode}{Action} - \lineii{'r|*'}{Open a \emph{stream} of tar blocks for reading with transparent compression.} - \lineii{'r|'}{Open a \emph{stream} of uncompressed tar blocks for reading.} - \lineii{'r|gz'}{Open a gzip compressed \emph{stream} for reading.} - \lineii{'r|bz2'}{Open a bzip2 compressed \emph{stream} for reading.} - \lineii{'w|'}{Open an uncompressed \emph{stream} for writing.} - \lineii{'w|gz'}{Open an gzip compressed \emph{stream} for writing.} - \lineii{'w|bz2'}{Open an bzip2 compressed \emph{stream} for writing.} - \end{tableii} -\end{funcdesc} - -\begin{classdesc*}{TarFile} - Class for reading and writing tar archives. Do not use this - class directly, better use \function{open()} instead. - See ``TarFile Objects'' (section~\ref{tarfile-objects}). -\end{classdesc*} - -\begin{funcdesc}{is_tarfile}{name} - Return \constant{True} if \var{name} is a tar archive file, that - the \module{tarfile} module can read. -\end{funcdesc} - -\begin{classdesc}{TarFileCompat}{filename\optional{, mode\optional{, - compression}}} - Class for limited access to tar archives with a - \refmodule{zipfile}-like interface. Please consult the - documentation of the \refmodule{zipfile} module for more details. - \var{compression} must be one of the following constants: - \begin{datadesc}{TAR_PLAIN} - Constant for an uncompressed tar archive. - \end{datadesc} - \begin{datadesc}{TAR_GZIPPED} - Constant for a \refmodule{gzip} compressed tar archive. - \end{datadesc} -\end{classdesc} - -\begin{excdesc}{TarError} - Base class for all \module{tarfile} exceptions. -\end{excdesc} - -\begin{excdesc}{ReadError} - Is raised when a tar archive is opened, that either cannot be handled by - the \module{tarfile} module or is somehow invalid. -\end{excdesc} - -\begin{excdesc}{CompressionError} - Is raised when a compression method is not supported or when the data - cannot be decoded properly. -\end{excdesc} - -\begin{excdesc}{StreamError} - Is raised for the limitations that are typical for stream-like - \class{TarFile} objects. -\end{excdesc} - -\begin{excdesc}{ExtractError} - Is raised for \emph{non-fatal} errors when using \method{extract()}, but - only if \member{TarFile.errorlevel}\code{ == 2}. -\end{excdesc} - -\begin{excdesc}{HeaderError} - Is raised by \method{frombuf()} if the buffer it gets is invalid. - \versionadded{2.6} -\end{excdesc} - -Each of the following constants defines a tar archive format that the -\module{tarfile} module is able to create. See section \ref{tar-formats} for -details. - -\begin{datadesc}{USTAR_FORMAT} - \POSIX{}.1-1988 (ustar) format. -\end{datadesc} - -\begin{datadesc}{GNU_FORMAT} - GNU tar format. -\end{datadesc} - -\begin{datadesc}{PAX_FORMAT} - \POSIX{}.1-2001 (pax) format. -\end{datadesc} - -\begin{datadesc}{DEFAULT_FORMAT} - The default format for creating archives. This is currently - \constant{GNU_FORMAT}. -\end{datadesc} - -\begin{seealso} - \seemodule{zipfile}{Documentation of the \refmodule{zipfile} - standard module.} - - \seetitle[http://www.gnu.org/software/tar/manual/html_node/tar_134.html\#SEC134] - {GNU tar manual, Basic Tar Format}{Documentation for tar archive files, - including GNU tar extensions.} -\end{seealso} - -%----------------- -% TarFile Objects -%----------------- - -\subsection{TarFile Objects \label{tarfile-objects}} - -The \class{TarFile} object provides an interface to a tar archive. A tar -archive is a sequence of blocks. An archive member (a stored file) is made up -of a header block followed by data blocks. It is possible to store a file in a -tar archive several times. Each archive member is represented by a -\class{TarInfo} object, see \citetitle{TarInfo Objects} (section -\ref{tarinfo-objects}) for details. - -\begin{classdesc}{TarFile}{name=None, mode='r', fileobj=None, - format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, - ignore_zeros=False, encoding=None, errors=None, pax_headers=None, - debug=0, errorlevel=0} - - All following arguments are optional and can be accessed as instance - attributes as well. - - \var{name} is the pathname of the archive. It can be omitted if - \var{fileobj} is given. In this case, the file object's \member{name} - attribute is used if it exists. - - \var{mode} is either \code{'r'} to read from an existing archive, - \code{'a'} to append data to an existing file or \code{'w'} to create a new - file overwriting an existing one. - - If \var{fileobj} is given, it is used for reading or writing data. - If it can be determined, \var{mode} is overridden by \var{fileobj}'s mode. - \var{fileobj} will be used from position 0. - \begin{notice} - \var{fileobj} is not closed, when \class{TarFile} is closed. - \end{notice} - - \var{format} controls the archive format. It must be one of the constants - \constant{USTAR_FORMAT}, \constant{GNU_FORMAT} or \constant{PAX_FORMAT} - that are defined at module level. - \versionadded{2.6} - - The \var{tarinfo} argument can be used to replace the default - \class{TarInfo} class with a different one. - \versionadded{2.6} - - If \var{dereference} is \code{False}, add symbolic and hard links to the - archive. If it is \code{True}, add the content of the target files to the - archive. This has no effect on systems that do not support symbolic links. - - If \var{ignore_zeros} is \code{False}, treat an empty block as the end of - the archive. If it is \var{True}, skip empty (and invalid) blocks and try - to get as many members as possible. This is only useful for reading - concatenated or damaged archives. - - \var{debug} can be set from \code{0} (no debug messages) up to \code{3} - (all debug messages). The messages are written to \code{sys.stderr}. - - If \var{errorlevel} is \code{0}, all errors are ignored when using - \method{extract()}. Nevertheless, they appear as error messages in the - debug output, when debugging is enabled. If \code{1}, all \emph{fatal} - errors are raised as \exception{OSError} or \exception{IOError} exceptions. - If \code{2}, all \emph{non-fatal} errors are raised as \exception{TarError} - exceptions as well. - - The \var{encoding} and \var{errors} arguments control the way strings are - converted to unicode objects and vice versa. The default settings will work - for most users. See section \ref{tar-unicode} for in-depth information. - \versionadded{2.6} - - The \var{pax_headers} argument is an optional dictionary of unicode strings - which will be added as a pax global header if \var{format} is - \constant{PAX_FORMAT}. - \versionadded{2.6} -\end{classdesc} - -\begin{methoddesc}{open}{...} - Alternative constructor. The \function{open()} function on module level is - actually a shortcut to this classmethod. See section~\ref{module-tarfile} - for details. -\end{methoddesc} - -\begin{methoddesc}{getmember}{name} - Return a \class{TarInfo} object for member \var{name}. If \var{name} can - not be found in the archive, \exception{KeyError} is raised. - \begin{notice} - If a member occurs more than once in the archive, its last - occurrence is assumed to be the most up-to-date version. - \end{notice} -\end{methoddesc} - -\begin{methoddesc}{getmembers}{} - Return the members of the archive as a list of \class{TarInfo} objects. - The list has the same order as the members in the archive. -\end{methoddesc} - -\begin{methoddesc}{getnames}{} - Return the members as a list of their names. It has the same order as - the list returned by \method{getmembers()}. -\end{methoddesc} - -\begin{methoddesc}{list}{verbose=True} - Print a table of contents to \code{sys.stdout}. If \var{verbose} is - \constant{False}, only the names of the members are printed. If it is - \constant{True}, output similar to that of \program{ls -l} is produced. -\end{methoddesc} - -\begin{methoddesc}{next}{} - Return the next member of the archive as a \class{TarInfo} object, when - \class{TarFile} is opened for reading. Return \code{None} if there is no - more available. -\end{methoddesc} - -\begin{methoddesc}{extractall}{\optional{path\optional{, members}}} - Extract all members from the archive to the current working directory - or directory \var{path}. If optional \var{members} is given, it must be - a subset of the list returned by \method{getmembers()}. - Directory information like owner, modification time and permissions are - set after all members have been extracted. This is done to work around two - problems: A directory's modification time is reset each time a file is - created in it. And, if a directory's permissions do not allow writing, - extracting files to it will fail. - \versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}{extract}{member\optional{, path}} - Extract a member from the archive to the current working directory, - using its full name. Its file information is extracted as accurately as - possible. - \var{member} may be a filename or a \class{TarInfo} object. - You can specify a different directory using \var{path}. - \begin{notice} - Because the \method{extract()} method allows random access to a tar - archive there are some issues you must take care of yourself. See the - description for \method{extractall()} above. - \end{notice} -\end{methoddesc} - -\begin{methoddesc}{extractfile}{member} - Extract a member from the archive as a file object. - \var{member} may be a filename or a \class{TarInfo} object. - If \var{member} is a regular file, a file-like object is returned. - If \var{member} is a link, a file-like object is constructed from the - link's target. - If \var{member} is none of the above, \code{None} is returned. - \begin{notice} - The file-like object is read-only and provides the following methods: - \method{read()}, \method{readline()}, \method{readlines()}, - \method{seek()}, \method{tell()}. - \end{notice} -\end{methoddesc} - -\begin{methoddesc}{add}{name\optional{, arcname\optional{, recursive\optional{, exclude}}}} - Add the file \var{name} to the archive. \var{name} may be any type - of file (directory, fifo, symbolic link, etc.). - If given, \var{arcname} specifies an alternative name for the file in the - archive. Directories are added recursively by default. - This can be avoided by setting \var{recursive} to \constant{False}. - If \var{exclude} is given it must be a function that takes one filename - argument and returns a boolean value. Depending on this value the - respective file is either excluded (\constant{True}) or added - (\constant{False}). - \versionchanged[Added the \var{exclude} parameter]{2.6} -\end{methoddesc} - -\begin{methoddesc}{addfile}{tarinfo\optional{, fileobj}} - Add the \class{TarInfo} object \var{tarinfo} to the archive. - If \var{fileobj} is given, \code{\var{tarinfo}.size} bytes are read - from it and added to the archive. You can create \class{TarInfo} objects - using \method{gettarinfo()}. - \begin{notice} - On Windows platforms, \var{fileobj} should always be opened with mode - \code{'rb'} to avoid irritation about the file size. - \end{notice} -\end{methoddesc} - -\begin{methoddesc}{gettarinfo}{\optional{name\optional{, - arcname\optional{, fileobj}}}} - Create a \class{TarInfo} object for either the file \var{name} or - the file object \var{fileobj} (using \function{os.fstat()} on its - file descriptor). You can modify some of the \class{TarInfo}'s - attributes before you add it using \method{addfile()}. If given, - \var{arcname} specifies an alternative name for the file in the - archive. -\end{methoddesc} - -\begin{methoddesc}{close}{} - Close the \class{TarFile}. In write mode, two finishing zero - blocks are appended to the archive. -\end{methoddesc} - -\begin{memberdesc}{posix} - Setting this to \constant{True} is equivalent to setting the - \member{format} attribute to \constant{USTAR_FORMAT}, - \constant{False} is equivalent to \constant{GNU_FORMAT}. - \versionchanged[\var{posix} defaults to \constant{False}]{2.4} - \deprecated{2.6}{Use the \member{format} attribute instead.} -\end{memberdesc} - -\begin{memberdesc}{pax_headers} - A dictionary containing key-value pairs of pax global headers. - \versionadded{2.6} -\end{memberdesc} - -%----------------- -% TarInfo Objects -%----------------- - -\subsection{TarInfo Objects \label{tarinfo-objects}} - -A \class{TarInfo} object represents one member in a -\class{TarFile}. Aside from storing all required attributes of a file -(like file type, size, time, permissions, owner etc.), it provides -some useful methods to determine its type. It does \emph{not} contain -the file's data itself. - -\class{TarInfo} objects are returned by \class{TarFile}'s methods -\method{getmember()}, \method{getmembers()} and \method{gettarinfo()}. - -\begin{classdesc}{TarInfo}{\optional{name}} - Create a \class{TarInfo} object. -\end{classdesc} - -\begin{methoddesc}{frombuf}{buf} - Create and return a \class{TarInfo} object from string buffer \var{buf}. - \versionadded[Raises \exception{HeaderError} if the buffer is - invalid.]{2.6} -\end{methoddesc} - -\begin{methoddesc}{fromtarfile}{tarfile} - Read the next member from the \class{TarFile} object \var{tarfile} and - return it as a \class{TarInfo} object. - \versionadded{2.6} -\end{methoddesc} - -\begin{methoddesc}{tobuf}{\optional{format\optional{, encoding - \optional{, errors}}}} - Create a string buffer from a \class{TarInfo} object. For information - on the arguments see the constructor of the \class{TarFile} class. - \versionchanged[The arguments were added]{2.6} -\end{methoddesc} - -A \code{TarInfo} object has the following public data attributes: - -\begin{memberdesc}{name} - Name of the archive member. -\end{memberdesc} - -\begin{memberdesc}{size} - Size in bytes. -\end{memberdesc} - -\begin{memberdesc}{mtime} - Time of last modification. -\end{memberdesc} - -\begin{memberdesc}{mode} - Permission bits. -\end{memberdesc} - -\begin{memberdesc}{type} - File type. \var{type} is usually one of these constants: - \constant{REGTYPE}, \constant{AREGTYPE}, \constant{LNKTYPE}, - \constant{SYMTYPE}, \constant{DIRTYPE}, \constant{FIFOTYPE}, - \constant{CONTTYPE}, \constant{CHRTYPE}, \constant{BLKTYPE}, - \constant{GNUTYPE_SPARSE}. To determine the type of a - \class{TarInfo} object more conveniently, use the \code{is_*()} - methods below. -\end{memberdesc} - -\begin{memberdesc}{linkname} - Name of the target file name, which is only present in - \class{TarInfo} objects of type \constant{LNKTYPE} and - \constant{SYMTYPE}. -\end{memberdesc} - -\begin{memberdesc}{uid} - User ID of the user who originally stored this member. -\end{memberdesc} - -\begin{memberdesc}{gid} - Group ID of the user who originally stored this member. -\end{memberdesc} - -\begin{memberdesc}{uname} - User name. -\end{memberdesc} - -\begin{memberdesc}{gname} - Group name. -\end{memberdesc} - -\begin{memberdesc}{pax_headers} - A dictionary containing key-value pairs of an associated pax - extended header. - \versionadded{2.6} -\end{memberdesc} - -A \class{TarInfo} object also provides some convenient query methods: - -\begin{methoddesc}{isfile}{} - Return \constant{True} if the \class{Tarinfo} object is a regular - file. -\end{methoddesc} - -\begin{methoddesc}{isreg}{} - Same as \method{isfile()}. -\end{methoddesc} - -\begin{methoddesc}{isdir}{} - Return \constant{True} if it is a directory. -\end{methoddesc} - -\begin{methoddesc}{issym}{} - Return \constant{True} if it is a symbolic link. -\end{methoddesc} - -\begin{methoddesc}{islnk}{} - Return \constant{True} if it is a hard link. -\end{methoddesc} - -\begin{methoddesc}{ischr}{} - Return \constant{True} if it is a character device. -\end{methoddesc} - -\begin{methoddesc}{isblk}{} - Return \constant{True} if it is a block device. -\end{methoddesc} - -\begin{methoddesc}{isfifo}{} - Return \constant{True} if it is a FIFO. -\end{methoddesc} - -\begin{methoddesc}{isdev}{} - Return \constant{True} if it is one of character device, block - device or FIFO. -\end{methoddesc} - -%------------------------ -% Examples -%------------------------ - -\subsection{Examples \label{tar-examples}} - -How to extract an entire tar archive to the current working directory: -\begin{verbatim} -import tarfile -tar = tarfile.open("sample.tar.gz") -tar.extractall() -tar.close() -\end{verbatim} - -How to create an uncompressed tar archive from a list of filenames: -\begin{verbatim} -import tarfile -tar = tarfile.open("sample.tar", "w") -for name in ["foo", "bar", "quux"]: - tar.add(name) -tar.close() -\end{verbatim} - -How to read a gzip compressed tar archive and display some member information: -\begin{verbatim} -import tarfile -tar = tarfile.open("sample.tar.gz", "r:gz") -for tarinfo in tar: - print tarinfo.name, "is", tarinfo.size, "bytes in size and is", - if tarinfo.isreg(): - print "a regular file." - elif tarinfo.isdir(): - print "a directory." - else: - print "something else." -tar.close() -\end{verbatim} - -How to create a tar archive with faked information: -\begin{verbatim} -import tarfile -tar = tarfile.open("sample.tar.gz", "w:gz") -for name in namelist: - tarinfo = tar.gettarinfo(name, "fakeproj-1.0/" + name) - tarinfo.uid = 123 - tarinfo.gid = 456 - tarinfo.uname = "johndoe" - tarinfo.gname = "fake" - tar.addfile(tarinfo, file(name)) -tar.close() -\end{verbatim} - -The \emph{only} way to extract an uncompressed tar stream from -\code{sys.stdin}: -\begin{verbatim} -import sys -import tarfile -tar = tarfile.open(mode="r|", fileobj=sys.stdin) -for tarinfo in tar: - tar.extract(tarinfo) -tar.close() -\end{verbatim} - -%------------ -% Tar format -%------------ - -\subsection{Supported tar formats \label{tar-formats}} - -There are three tar formats that can be created with the \module{tarfile} -module: - -\begin{itemize} - -\item -The \POSIX{}.1-1988 ustar format (\constant{USTAR_FORMAT}). It supports -filenames up to a length of at best 256 characters and linknames up to 100 -characters. The maximum file size is 8 gigabytes. This is an old and limited -but widely supported format. - -\item -The GNU tar format (\constant{GNU_FORMAT}). It supports long filenames and -linknames, files bigger than 8 gigabytes and sparse files. It is the de facto -standard on GNU/Linux systems. \module{tarfile} fully supports the GNU tar -extensions for long names, sparse file support is read-only. - -\item -The \POSIX{}.1-2001 pax format (\constant{PAX_FORMAT}). It is the most -flexible format with virtually no limits. It supports long filenames and -linknames, large files and stores pathnames in a portable way. However, not -all tar implementations today are able to handle pax archives properly. - -The \emph{pax} format is an extension to the existing \emph{ustar} format. It -uses extra headers for information that cannot be stored otherwise. There are -two flavours of pax headers: Extended headers only affect the subsequent file -header, global headers are valid for the complete archive and affect all -following files. All the data in a pax header is encoded in \emph{UTF-8} for -portability reasons. - -\end{itemize} - -There are some more variants of the tar format which can be read, but not -created: - -\begin{itemize} - -\item -The ancient V7 format. This is the first tar format from \UNIX{} Seventh -Edition, storing only regular files and directories. Names must not be longer -than 100 characters, there is no user/group name information. Some archives -have miscalculated header checksums in case of fields with non-\ASCII{} -characters. - -\item -The SunOS tar extended format. This format is a variant of the \POSIX{}.1-2001 -pax format, but is not compatible. - -\end{itemize} - -%---------------- -% Unicode issues -%---------------- - -\subsection{Unicode issues \label{tar-unicode}} - -The tar format was originally conceived to make backups on tape drives with the -main focus on preserving file system information. Nowadays tar archives are -commonly used for file distribution and exchanging archives over networks. One -problem of the original format (that all other formats are merely variants of) -is that there is no concept of supporting different character encodings. -For example, an ordinary tar archive created on a \emph{UTF-8} system cannot be -read correctly on a \emph{Latin-1} system if it contains non-\ASCII{} -characters. Names (i.e. filenames, linknames, user/group names) containing -these characters will appear damaged. Unfortunately, there is no way to -autodetect the encoding of an archive. - -The pax format was designed to solve this problem. It stores non-\ASCII{} names -using the universal character encoding \emph{UTF-8}. When a pax archive is -read, these \emph{UTF-8} names are converted to the encoding of the local -file system. - -The details of unicode conversion are controlled by the \var{encoding} and -\var{errors} keyword arguments of the \class{TarFile} class. - -The default value for \var{encoding} is the local character encoding. It is -deduced from \function{sys.getfilesystemencoding()} and -\function{sys.getdefaultencoding()}. In read mode, \var{encoding} is used -exclusively to convert unicode names from a pax archive to strings in the local -character encoding. In write mode, the use of \var{encoding} depends on the -chosen archive format. In case of \constant{PAX_FORMAT}, input names that -contain non-\ASCII{} characters need to be decoded before being stored as -\emph{UTF-8} strings. The other formats do not make use of \var{encoding} -unless unicode objects are used as input names. These are converted to -8-bit character strings before they are added to the archive. - -The \var{errors} argument defines how characters are treated that cannot be -converted to or from \var{encoding}. Possible values are listed in section -\ref{codec-base-classes}. In read mode, there is an additional scheme -\code{'utf-8'} which means that bad characters are replaced by their -\emph{UTF-8} representation. This is the default scheme. In write mode the -default value for \var{errors} is \code{'strict'} to ensure that name -information is not altered unnoticed. diff --git a/Doc/lib/libtelnetlib.tex b/Doc/lib/libtelnetlib.tex deleted file mode 100644 index 853788f..0000000 --- a/Doc/lib/libtelnetlib.tex +++ /dev/null @@ -1,228 +0,0 @@ -\section{\module{telnetlib} --- - Telnet client} - -\declaremodule{standard}{telnetlib} -\modulesynopsis{Telnet client class.} -\sectionauthor{Skip Montanaro}{skip@mojam.com} - -\index{protocol!Telnet} - -The \module{telnetlib} module provides a \class{Telnet} class that -implements the Telnet protocol. See \rfc{854} for details about the -protocol. In addition, it provides symbolic constants for the protocol -characters (see below), and for the telnet options. The -symbolic names of the telnet options follow the definitions in -\code{arpa/telnet.h}, with the leading \code{TELOPT_} removed. For -symbolic names of options which are traditionally not included in -\code{arpa/telnet.h}, see the module source itself. - -The symbolic constants for the telnet commands are: IAC, DONT, DO, -WONT, WILL, SE (Subnegotiation End), NOP (No Operation), DM (Data -Mark), BRK (Break), IP (Interrupt process), AO (Abort output), AYT -(Are You There), EC (Erase Character), EL (Erase Line), GA (Go Ahead), -SB (Subnegotiation Begin). - - -\begin{classdesc}{Telnet}{\optional{host\optional{, port\optional{, timeout}}}} -\class{Telnet} represents a connection to a Telnet server. The -instance is initially not connected by default; the \method{open()} -method must be used to establish a connection. Alternatively, the -host name and optional port number can be passed to the constructor, -to, in which case the connection to the server will be established -before the constructor returns. -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if not specified, or passed as None, the global default -timeout setting will be used). - -Do not reopen an already connected instance. - -This class has many \method{read_*()} methods. Note that some of them -raise \exception{EOFError} when the end of the connection is read, -because they can return an empty string for other reasons. See the -individual descriptions below. -\versionchanged[\var{timeout} was added]{2.6} -\end{classdesc} - - -\begin{seealso} - \seerfc{854}{Telnet Protocol Specification}{ - Definition of the Telnet protocol.} -\end{seealso} - - - -\subsection{Telnet Objects \label{telnet-objects}} - -\class{Telnet} instances have the following methods: - - -\begin{methoddesc}[Telnet]{read_until}{expected\optional{, timeout}} -Read until a given string, \var{expected}, is encountered or until -\var{timeout} seconds have passed. - -When no match is found, return whatever is available instead, -possibly the empty string. Raise \exception{EOFError} if the connection -is closed and no cooked data is available. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_all}{} -Read all data until \EOF; block until connection closed. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_some}{} -Read at least one byte of cooked data unless \EOF{} is hit. -Return \code{''} if \EOF{} is hit. Block if no data is immediately -available. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_very_eager}{} -Read everything that can be without blocking in I/O (eager). - -Raise \exception{EOFError} if connection closed and no cooked data -available. Return \code{''} if no cooked data available otherwise. -Do not block unless in the midst of an IAC sequence. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_eager}{} -Read readily available data. - -Raise \exception{EOFError} if connection closed and no cooked data -available. Return \code{''} if no cooked data available otherwise. -Do not block unless in the midst of an IAC sequence. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_lazy}{} -Process and return data already in the queues (lazy). - -Raise \exception{EOFError} if connection closed and no data available. -Return \code{''} if no cooked data available otherwise. Do not block -unless in the midst of an IAC sequence. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_very_lazy}{} -Return any data available in the cooked queue (very lazy). - -Raise \exception{EOFError} if connection closed and no data available. -Return \code{''} if no cooked data available otherwise. This method -never blocks. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{read_sb_data}{} -Return the data collected between a SB/SE pair (suboption begin/end). -The callback should access these data when it was invoked with a -\code{SE} command. This method never blocks. - -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[Telnet]{open}{host\optional{, port\optional{, timeout}}} -Connect to a host. -The optional second argument is the port number, which -defaults to the standard Telnet port (23). -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if not specified, or passed as None, the global default -timeout setting will be used). - -Do not try to reopen an already connected instance. -\versionchanged[\var{timeout} was added]{2.6} -\end{methoddesc} - -\begin{methoddesc}[Telnet]{msg}{msg\optional{, *args}} -Print a debug message when the debug level is \code{>} 0. -If extra arguments are present, they are substituted in the -message using the standard string formatting operator. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{set_debuglevel}{debuglevel} -Set the debug level. The higher the value of \var{debuglevel}, the -more debug output you get (on \code{sys.stdout}). -\end{methoddesc} - -\begin{methoddesc}[Telnet]{close}{} -Close the connection. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{get_socket}{} -Return the socket object used internally. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{fileno}{} -Return the file descriptor of the socket object used internally. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{write}{buffer} -Write a string to the socket, doubling any IAC characters. -This can block if the connection is blocked. May raise -\exception{socket.error} if the connection is closed. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{interact}{} -Interaction function, emulates a very dumb Telnet client. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{mt_interact}{} -Multithreaded version of \method{interact()}. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{expect}{list\optional{, timeout}} -Read until one from a list of a regular expressions matches. - -The first argument is a list of regular expressions, either -compiled (\class{re.RegexObject} instances) or uncompiled (strings). -The optional second argument is a timeout, in seconds; the default -is to block indefinitely. - -Return a tuple of three items: the index in the list of the -first regular expression that matches; the match object -returned; and the text read up till and including the match. - -If end of file is found and no text was read, raise -\exception{EOFError}. Otherwise, when nothing matches, return -\code{(-1, None, \var{text})} where \var{text} is the text received so -far (may be the empty string if a timeout happened). - -If a regular expression ends with a greedy match (such as \regexp{.*}) -or if more than one expression can match the same input, the -results are indeterministic, and may depend on the I/O timing. -\end{methoddesc} - -\begin{methoddesc}[Telnet]{set_option_negotiation_callback}{callback} -Each time a telnet option is read on the input flow, this -\var{callback} (if set) is called with the following parameters : -callback(telnet socket, command (DO/DONT/WILL/WONT), option). No other -action is done afterwards by telnetlib. -\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 - -def raw_input(prompt): - sys.stdout.write(prompt) - sys.stdout.flush() - return sys.stdin.readline() - -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/libtempfile.tex b/Doc/lib/libtempfile.tex deleted file mode 100644 index 8bc559e..0000000 --- a/Doc/lib/libtempfile.tex +++ /dev/null @@ -1,214 +0,0 @@ -\section{\module{tempfile} --- - Generate temporary files and directories} -\sectionauthor{Zack Weinberg}{zack@codesourcery.com} - -\declaremodule{standard}{tempfile} -\modulesynopsis{Generate temporary files and directories.} - -\indexii{temporary}{file name} -\indexii{temporary}{file} - -This module generates temporary files and directories. It works on -all supported platforms. - -In version 2.3 of Python, this module was overhauled for enhanced -security. It now provides three new functions, -\function{NamedTemporaryFile()}, \function{mkstemp()}, and -\function{mkdtemp()}, which should eliminate all remaining need to use -the insecure \function{mktemp()} function. Temporary file names created -by this module no longer contain the process ID; instead a string of -six random characters is used. - -Also, all the user-callable functions now take additional arguments -which allow direct control over the location and name of temporary -files. It is no longer necessary to use the global \var{tempdir} and -\var{template} variables. To maintain backward compatibility, the -argument order is somewhat odd; it is recommended to use keyword -arguments for clarity. - -The module defines the following user-callable functions: - -\begin{funcdesc}{TemporaryFile}{\optional{mode=\code{'w+b'}\optional{, - bufsize=\code{-1}\optional{, - suffix\optional{, prefix\optional{, dir}}}}}} -Return a file (or file-like) object that can be used as a temporary -storage area. The file is created using \function{mkstemp}. It will -be destroyed as soon as it is closed (including an implicit close when -the object is garbage collected). Under \UNIX, the directory entry -for the file is removed immediately after the file is created. Other -platforms do not support this; your code should not rely on a -temporary file created using this function having or not having a -visible name in the file system. - -The \var{mode} parameter defaults to \code{'w+b'} so that the file -created can be read and written without being closed. Binary mode is -used so that it behaves consistently on all platforms without regard -for the data that is stored. \var{bufsize} defaults to \code{-1}, -meaning that the operating system default is used. - -The \var{dir}, \var{prefix} and \var{suffix} parameters are passed to -\function{mkstemp()}. -\end{funcdesc} - -\begin{funcdesc}{NamedTemporaryFile}{\optional{mode=\code{'w+b'}\optional{, - bufsize=\code{-1}\optional{, - suffix\optional{, prefix\optional{, - dir\optional{, delete}}}}}}} -This function operates exactly as \function{TemporaryFile()} does, -except that the file is guaranteed to have a visible name in the file -system (on \UNIX, the directory entry is not unlinked). That name can -be retrieved from the \member{name} member of the file object. Whether -the name can be used to open the file a second time, while the -named temporary file is still open, varies across platforms (it can -be so used on \UNIX; it cannot on Windows NT or later). -If \var{delete} is true (the default), the file is deleted as soon as -it is closed. -\versionadded{2.3} -\versionadded[The \var{delete} parameter]{2.6} -\end{funcdesc} - -\begin{funcdesc}{SpooledTemporaryFile}{\optional{max\_size=\code{0}, - \optional{mode=\code{'w+b'}\optional{, - bufsize=\code{-1}\optional{, - suffix\optional{, prefix\optional{, - dir}}}}}}} -This function operates exactly as \function{TemporaryFile()} does, -except that data is spooled in memory until the file size exceeds -\var{max_size}, or until the file's \function{fileno()} method is -called, at which point the contents are written to disk and operation -proceeds as with \function{TemporaryFile()}. - -The resulting file has one additional method, \function{rollover()}, -which causes the file to roll over to an on-disk file regardless of -its size. -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{mkstemp}{\optional{suffix\optional{, - prefix\optional{, dir\optional{, text}}}}} -Creates a temporary file in the most secure manner possible. There -are no race conditions in the file's creation, assuming that the -platform properly implements the \constant{O_EXCL} flag for -\function{os.open()}. The file is readable and writable only by the -creating user ID. If the platform uses permission bits to indicate -whether a file is executable, the file is executable by no one. The -file descriptor is not inherited by child processes. - -Unlike \function{TemporaryFile()}, the user of \function{mkstemp()} is -responsible for deleting the temporary file when done with it. - -If \var{suffix} is specified, the file name will end with that suffix, -otherwise there will be no suffix. \function{mkstemp()} does not put a -dot between the file name and the suffix; if you need one, put it at -the beginning of \var{suffix}. - -If \var{prefix} is specified, the file name will begin with that -prefix; otherwise, a default prefix is used. - -If \var{dir} is specified, the file will be created in that directory; -otherwise, a default directory is used. The default directory is chosen -from a platform-dependent list, but the user of the application can control -the directory location by setting the \var{TMPDIR}, \var{TEMP} or \var{TMP} -environment variables. There is thus no guarantee that the generated -filename will have any nice properties, such as not requiring quoting when -passed to external commands via \code{os.popen()}. - -If \var{text} is specified, it indicates whether to open the file in -binary mode (the default) or text mode. On some platforms, this makes -no difference. - -\function{mkstemp()} returns a tuple containing an OS-level handle to -an open file (as would be returned by \function{os.open()}) and the -absolute pathname of that file, in that order. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{mkdtemp}{\optional{suffix\optional{, prefix\optional{, dir}}}} -Creates a temporary directory in the most secure manner possible. -There are no race conditions in the directory's creation. The -directory is readable, writable, and searchable only by the -creating user ID. - -The user of \function{mkdtemp()} is responsible for deleting the -temporary directory and its contents when done with it. - -The \var{prefix}, \var{suffix}, and \var{dir} arguments are the same -as for \function{mkstemp()}. - -\function{mkdtemp()} returns the absolute pathname of the new directory. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{mktemp}{\optional{suffix\optional{, prefix\optional{, dir}}}} -\deprecated{2.3}{Use \function{mkstemp()} instead.} -Return an absolute pathname of a file that did not exist at the time -the call is made. The \var{prefix}, \var{suffix}, and \var{dir} -arguments are the same as for \function{mkstemp()}. - -\warning{Use of this function may introduce a security hole in your -program. By the time you get around to doing anything with the file -name it returns, someone else may have beaten you to the punch.} -\end{funcdesc} - -The module uses two global variables that tell it how to construct a -temporary name. They are initialized at the first call to any of the -functions above. The caller may change them, but this is discouraged; -use the appropriate function arguments, instead. - -\begin{datadesc}{tempdir} -When set to a value other than \code{None}, this variable defines the -default value for the \var{dir} argument to all the functions defined -in this module. - -If \code{tempdir} is unset or \code{None} at any call to any of the -above functions, Python searches a standard list of directories and -sets \var{tempdir} to the first one which the calling user can create -files in. The list is: - -\begin{enumerate} -\item The directory named by the \envvar{TMPDIR} environment variable. -\item The directory named by the \envvar{TEMP} environment variable. -\item The directory named by the \envvar{TMP} environment variable. -\item A platform-specific location: - \begin{itemize} - \item On RiscOS, the directory named by the - \envvar{Wimp\$ScrapDir} environment variable. - \item On Windows, the directories - \file{C:$\backslash$TEMP}, - \file{C:$\backslash$TMP}, - \file{$\backslash$TEMP}, and - \file{$\backslash$TMP}, in that order. - \item On all other platforms, the directories - \file{/tmp}, \file{/var/tmp}, and \file{/usr/tmp}, in that order. - \end{itemize} -\item As a last resort, the current working directory. -\end{enumerate} -\end{datadesc} - -\begin{funcdesc}{gettempdir}{} -Return the directory currently selected to create temporary files in. -If \code{tempdir} is not \code{None}, this simply returns its contents; -otherwise, the search described above is performed, and the result -returned. -\end{funcdesc} - -\begin{datadesc}{template} -\deprecated{2.0}{Use \function{gettempprefix()} instead.} -When set to a value other than \code{None}, this variable defines the -prefix of the final component of the filenames returned by -\function{mktemp()}. A string of six random letters and digits is -appended to the prefix to make the filename unique. On Windows, -the default prefix is \file{\textasciitilde{}T}; on all other systems -it is \file{tmp}. - -Older versions of this module used to require that \code{template} be -set to \code{None} after a call to \function{os.fork()}; this has not -been necessary since version 1.5.2. -\end{datadesc} - -\begin{funcdesc}{gettempprefix}{} -Return the filename prefix used to create temporary files. This does -not contain the directory component. Using this function is preferred -over reading the \var{template} variable directly. -\versionadded{1.5.2} -\end{funcdesc} diff --git a/Doc/lib/libtermios.tex b/Doc/lib/libtermios.tex deleted file mode 100644 index 64f3438..0000000 --- a/Doc/lib/libtermios.tex +++ /dev/null @@ -1,112 +0,0 @@ -\section{\module{termios} --- - \POSIX{} style tty control} - -\declaremodule{builtin}{termios} - \platform{Unix} -\modulesynopsis{\POSIX\ style tty control.} - -\indexii{\POSIX}{I/O control} -\indexii{tty}{I/O control} - - -This module provides an interface to the \POSIX{} calls for tty I/O -control. For a complete description of these calls, see the \POSIX{} or -\UNIX{} manual pages. It is only available for those \UNIX{} versions -that support \POSIX{} \emph{termios} style tty I/O control (and then -only if configured at installation time). - -All functions in this module take a file descriptor \var{fd} as their -first argument. This can be an integer file descriptor, such as -returned by \code{sys.stdin.fileno()}, or a file object, such as -\code{sys.stdin} itself. - -This module also defines all the constants needed to work with the -functions provided here; these have the same name as their -counterparts in C. Please refer to your system documentation for more -information on using these terminal control interfaces. - -The module defines the following functions: - -\begin{funcdesc}{tcgetattr}{fd} -Return a list containing the tty attributes for file descriptor -\var{fd}, as follows: \code{[}\var{iflag}, \var{oflag}, \var{cflag}, -\var{lflag}, \var{ispeed}, \var{ospeed}, \var{cc}\code{]} where -\var{cc} is a list of the tty special characters (each a string of -length 1, except the items with indices \constant{VMIN} and -\constant{VTIME}, which are integers when these fields are -defined). The interpretation of the flags and the speeds as well as -the indexing in the \var{cc} array must be done using the symbolic -constants defined in the \module{termios} -module. -\end{funcdesc} - -\begin{funcdesc}{tcsetattr}{fd, when, attributes} -Set the tty attributes for file descriptor \var{fd} from the -\var{attributes}, which is a list like the one returned by -\function{tcgetattr()}. The \var{when} argument determines when the -attributes are changed: \constant{TCSANOW} to change immediately, -\constant{TCSADRAIN} to change after transmitting all queued output, -or \constant{TCSAFLUSH} to change after transmitting all queued -output and discarding all queued input. -\end{funcdesc} - -\begin{funcdesc}{tcsendbreak}{fd, duration} -Send a break on file descriptor \var{fd}. A zero \var{duration} sends -a break for 0.25--0.5 seconds; a nonzero \var{duration} has a system -dependent meaning. -\end{funcdesc} - -\begin{funcdesc}{tcdrain}{fd} -Wait until all output written to file descriptor \var{fd} has been -transmitted. -\end{funcdesc} - -\begin{funcdesc}{tcflush}{fd, queue} -Discard queued data on file descriptor \var{fd}. The \var{queue} -selector specifies which queue: \constant{TCIFLUSH} for the input -queue, \constant{TCOFLUSH} for the output queue, or -\constant{TCIOFLUSH} for both queues. -\end{funcdesc} - -\begin{funcdesc}{tcflow}{fd, action} -Suspend or resume input or output on file descriptor \var{fd}. The -\var{action} argument can be \constant{TCOOFF} to suspend output, -\constant{TCOON} to restart output, \constant{TCIOFF} to suspend -input, or \constant{TCION} to restart input. -\end{funcdesc} - - -\begin{seealso} - \seemodule{tty}{Convenience functions for common terminal control - operations.} -\end{seealso} - - -\subsection{Example} -\nodename{termios Example} - -Here's a function that prompts for a password with echoing turned -off. Note the technique using a separate \function{tcgetattr()} call -and a \keyword{try} ... \keyword{finally} statement to ensure that the -old tty attributes are restored exactly no matter what happens: - -\begin{verbatim} -def raw_input(prompt): - import sys - sys.stdout.write(prompt) - sys.stdout.flush() - return sys.stdin.readline() - -def getpass(prompt = "Password: "): - import termios, sys - fd = sys.stdin.fileno() - old = termios.tcgetattr(fd) - new = termios.tcgetattr(fd) - new[3] = new[3] & ~termios.ECHO # lflags - try: - termios.tcsetattr(fd, termios.TCSADRAIN, new) - passwd = raw_input(prompt) - finally: - termios.tcsetattr(fd, termios.TCSADRAIN, old) - return passwd -\end{verbatim} diff --git a/Doc/lib/libtest.tex b/Doc/lib/libtest.tex deleted file mode 100644 index d258089..0000000 --- a/Doc/lib/libtest.tex +++ /dev/null @@ -1,316 +0,0 @@ -\section{\module{test} --- - Regression tests package for Python} - -\declaremodule{standard}{test} -\sectionauthor{Brett Cannon}{brett@python.org} -\modulesynopsis{Regression tests package containing the testing suite - for Python.} - - -The \module{test} package contains all regression tests for Python as -well as the modules \module{test.test_support} and -\module{test.regrtest}. \module{test.test_support} is used to enhance -your tests while \module{test.regrtest} drives the testing suite. - -Each module in the \module{test} package whose name starts with -\samp{test_} is a testing suite for a specific module or feature. -All new tests should be written using the \refmodule{unittest} or -\refmodule{doctest} module. Some older tests are -written using a ``traditional'' testing style that compares output -printed to \code{sys.stdout}; this style of test is considered -deprecated. - -\begin{seealso} -\seemodule{unittest}{Writing PyUnit regression tests.} -\seemodule{doctest}{Tests embedded in documentation strings.} -\end{seealso} - - -\subsection{Writing Unit Tests for the \module{test} package% - \label{writing-tests}} - -It is preferred that tests that use the \refmodule{unittest} module -follow a few guidelines. -One is to name the test module by starting it with \samp{test_} and end it with -the name of the module being tested. -The test methods in the test module should start with \samp{test_} and end with -a description of what the method is testing. -This is needed so that the methods are recognized by the test driver as -test methods. -Also, no documentation string for the method should be included. -A comment (such as -\samp{\# Tests function returns only True or False}) should be used to provide -documentation for test methods. -This is done because documentation strings get printed out if they exist and -thus what test is being run is not stated. - -A basic boilerplate is often used: - -\begin{verbatim} -import unittest -from test import test_support - -class MyTestCase1(unittest.TestCase): - - # Only use setUp() and tearDown() if necessary - - def setUp(self): - ... code to execute in preparation for tests ... - - def tearDown(self): - ... code to execute to clean up after tests ... - - def test_feature_one(self): - # Test feature one. - ... testing code ... - - def test_feature_two(self): - # Test feature two. - ... testing code ... - - ... more test methods ... - -class MyTestCase2(unittest.TestCase): - ... same structure as MyTestCase1 ... - -... more test classes ... - -def test_main(): - test_support.run_unittest(MyTestCase1, - MyTestCase2, - ... list other tests ... - ) - -if __name__ == '__main__': - test_main() -\end{verbatim} - -This boilerplate code allows the testing suite to be run by -\module{test.regrtest} as well as on its own as a script. - -The goal for regression testing is to try to break code. -This leads to a few guidelines to be followed: - -\begin{itemize} -\item The testing suite should exercise all classes, functions, and - constants. - This includes not just the external API that is to be presented to the - outside world but also "private" code. -\item Whitebox testing (examining the code being tested when the tests are - being written) is preferred. - Blackbox testing (testing only the published user interface) is not - complete enough to make sure all boundary and edge cases are tested. -\item Make sure all possible values are tested including invalid ones. - This makes sure that not only all valid values are acceptable but also - that improper values are handled correctly. -\item Exhaust as many code paths as possible. - Test where branching occurs and thus tailor input to make sure as many - different paths through the code are taken. -\item Add an explicit test for any bugs discovered for the tested code. - This will make sure that the error does not crop up again if the code is - changed in the future. -\item Make sure to clean up after your tests (such as close and remove all - temporary files). -\item If a test is dependent on a specific condition of the operating system - then verify the condition already exists before attempting the test. -\item Import as few modules as possible and do it as soon as possible. - This minimizes external dependencies of tests and also minimizes possible - anomalous behavior from side-effects of importing a module. -\item Try to maximize code reuse. - On occasion, tests will vary by something as small as what type - of input is used. - Minimize code duplication by subclassing a basic test class with a class - that specifies the input: -\begin{verbatim} -class TestFuncAcceptsSequences(unittest.TestCase): - - func = mySuperWhammyFunction - - def test_func(self): - self.func(self.arg) - -class AcceptLists(TestFuncAcceptsSequences): - arg = [1,2,3] - -class AcceptStrings(TestFuncAcceptsSequences): - arg = 'abc' - -class AcceptTuples(TestFuncAcceptsSequences): - arg = (1,2,3) -\end{verbatim} -\end{itemize} - -\begin{seealso} -\seetitle{Test Driven Development} - {A book by Kent Beck on writing tests before code.} -\end{seealso} - - -\subsection{Running tests using \module{test.regrtest} \label{regrtest}} - -\module{test.regrtest} can be used as a script to drive Python's -regression test suite. -Running the script by itself automatically starts running all -regression tests in the \module{test} package. -It does this by finding all modules in the package whose name starts with -\samp{test_}, importing them, and executing the function -\function{test_main()} if present. -The names of tests to execute may also be passed to the script. -Specifying a single regression test (\program{python regrtest.py} -\programopt{test_spam.py}) will minimize output and only print whether -the test passed or failed and thus minimize output. - -Running \module{test.regrtest} directly allows what resources are -available for tests to use to be set. -You do this by using the \programopt{-u} command-line option. -Run \program{python regrtest.py} \programopt{-uall} to turn on all -resources; specifying \programopt{all} as an option for -\programopt{-u} enables all possible resources. -If all but one resource is desired (a more common case), a -comma-separated list of resources that are not desired may be listed after -\programopt{all}. -The command \program{python regrtest.py} -\programopt{-uall,-audio,-largefile} will run \module{test.regrtest} -with all resources except the \programopt{audio} and -\programopt{largefile} resources. -For a list of all resources and more command-line options, run -\program{python regrtest.py} \programopt{-h}. - -Some other ways to execute the regression tests depend on what platform the -tests are being executed on. -On \UNIX{}, you can run \program{make} \programopt{test} at the -top-level directory where Python was built. -On Windows, executing \program{rt.bat} from your \file{PCBuild} -directory will run all regression tests. - - -\section{\module{test.test_support} --- - Utility functions for tests} - -\declaremodule[test.testsupport]{standard}{test.test_support} -\modulesynopsis{Support for Python regression tests.} - -The \module{test.test_support} module provides support for Python's -regression tests. - -This module defines the following exceptions: - -\begin{excdesc}{TestFailed} -Exception to be raised when a test fails. This is deprecated in favor -of \module{unittest}-based tests and \class{unittest.TestCase}'s -assertion methods. -\end{excdesc} - -\begin{excdesc}{TestSkipped} -Subclass of \exception{TestFailed}. -Raised when a test is skipped. -This occurs when a needed resource (such as a network connection) is not -available at the time of testing. -\end{excdesc} - -\begin{excdesc}{ResourceDenied} -Subclass of \exception{TestSkipped}. -Raised when a resource (such as a network connection) is not available. -Raised by the \function{requires()} function. -\end{excdesc} - - -The \module{test.test_support} module defines the following constants: - -\begin{datadesc}{verbose} -\constant{True} when verbose output is enabled. -Should be checked when more detailed information is desired about a running -test. -\var{verbose} is set by \module{test.regrtest}. -\end{datadesc} - -\begin{datadesc}{have_unicode} -\constant{True} when Unicode support is available. -\end{datadesc} - -\begin{datadesc}{is_jython} -\constant{True} if the running interpreter is Jython. -\end{datadesc} - -\begin{datadesc}{TESTFN} -Set to the path that a temporary file may be created at. -Any temporary that is created should be closed and unlinked (removed). -\end{datadesc} - - -The \module{test.test_support} module defines the following functions: - -\begin{funcdesc}{forget}{module_name} -Removes the module named \var{module_name} from \code{sys.modules} and deletes -any byte-compiled files of the module. -\end{funcdesc} - -\begin{funcdesc}{is_resource_enabled}{resource} -Returns \constant{True} if \var{resource} is enabled and available. -The list of available resources is only set when \module{test.regrtest} -is executing the tests. -\end{funcdesc} - -\begin{funcdesc}{requires}{resource\optional{, msg}} -Raises \exception{ResourceDenied} if \var{resource} is not available. -\var{msg} is the argument to \exception{ResourceDenied} if it is raised. -Always returns true if called by a function whose \code{__name__} is -\code{'__main__'}. -Used when tests are executed by \module{test.regrtest}. -\end{funcdesc} - -\begin{funcdesc}{findfile}{filename} -Return the path to the file named \var{filename}. -If no match is found \var{filename} is returned. -This does not equal a failure since it could be the path to the file. -\end{funcdesc} - -\begin{funcdesc}{guard_warnings_filter}{} -Returns a context manager that guards the \module{warnings} module's -filter settings. -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{run_unittest}{*classes} -Execute \class{unittest.TestCase} subclasses passed to the function. -The function scans the classes for methods starting with the prefix -\samp{test_} and executes the tests individually. - -It is also legal to pass strings as parameters; these should be keys in -\code{sys.modules}. Each associated module will be scanned by -\code{unittest.TestLoader.loadTestsFromModule()}. This is usually seen in -the following \function{test_main()} function: - -\begin{verbatim} -def test_main(): - test_support.run_unittest(__name__) -\end{verbatim} - -This will run all tests defined in the named module. -\end{funcdesc} - -The \module{test.test_support} module defines the following classes: - -\begin{classdesc}{TransientResource}{exc\optional{, **kwargs}} -Create a context manager that raises \class{ResourceDenied} if the specified -exception type is raised. Any keyword arguments are treated as name/value -pairs to be compared against any exception raised with the \code{with} -statement. Only if all pairs match is \class{ResourceDenied} raised. -\versionadded{2.6} -\end{classdesc} - -\begin{classdesc}{EnvironmentVarGuard}{} -Class used to temporarily set or unset environment variables. Instances can be -used as a context manager. -\versionadded{2.6} -\end{classdesc} - -\begin{methoddesc}{set}{envvar, value} -Temporarily set the environment variable \code{envvar} to the value of -\code{value}. -\end{methoddesc} - -\begin{methoddesc}{unset}{envvar} -Temporarily unset the environment variable \code{envvar}. -\end{methoddesc} - diff --git a/Doc/lib/libtextwrap.tex b/Doc/lib/libtextwrap.tex deleted file mode 100644 index 8ea25a8..0000000 --- a/Doc/lib/libtextwrap.tex +++ /dev/null @@ -1,188 +0,0 @@ -\section{\module{textwrap} --- - Text wrapping and filling} - -\declaremodule{standard}{textwrap} -\modulesynopsis{Text wrapping and filling} -\moduleauthor{Greg Ward}{gward@python.net} -\sectionauthor{Greg Ward}{gward@python.net} - -\versionadded{2.3} - -The \module{textwrap} module provides two convenience functions, -\function{wrap()} and \function{fill()}, as well as -\class{TextWrapper}, the class that does all the work, and a utility function -\function{dedent()}. If you're just wrapping or filling one or two -text strings, the convenience functions should be good enough; otherwise, -you should use an instance of \class{TextWrapper} for efficiency. - -\begin{funcdesc}{wrap}{text\optional{, width\optional{, \moreargs}}} -Wraps the single paragraph in \var{text} (a string) so every line is at -most \var{width} characters long. Returns a list of output lines, -without final newlines. - -Optional keyword arguments correspond to the instance attributes of -\class{TextWrapper}, documented below. \var{width} defaults to -\code{70}. -\end{funcdesc} - -\begin{funcdesc}{fill}{text\optional{, width\optional{, \moreargs}}} -Wraps the single paragraph in \var{text}, and returns a single string -containing the wrapped paragraph. \function{fill()} is shorthand for -\begin{verbatim} -"\n".join(wrap(text, ...)) -\end{verbatim} - -In particular, \function{fill()} accepts exactly the same keyword -arguments as \function{wrap()}. -\end{funcdesc} - -Both \function{wrap()} and \function{fill()} work by creating a -\class{TextWrapper} instance and calling a single method on it. That -instance is not reused, so for applications that wrap/fill many text -strings, it will be more efficient for you to create your own -\class{TextWrapper} object. - -An additional utility function, \function{dedent()}, is provided to -remove indentation from strings that have unwanted whitespace to the -left of the text. - -\begin{funcdesc}{dedent}{text} -Remove any common leading whitespace from every line in \var{text}. - -This can be used to make triple-quoted strings line up with the left -edge of the display, while still presenting them in the source code -in indented form. - -Note that tabs and spaces are both treated as whitespace, but they are -not equal: the lines \code{" {} hello"} and \code{"\e thello"} -are considered to have no common leading whitespace. (This behaviour is -new in Python 2.5; older versions of this module incorrectly expanded -tabs before searching for common leading whitespace.) - -For example: -\begin{verbatim} -def test(): - # end first line with \ to avoid the empty line! - s = '''\ - hello - world - ''' - print repr(s) # prints ' hello\n world\n ' - print repr(dedent(s)) # prints 'hello\n world\n' -\end{verbatim} -\end{funcdesc} - -\begin{classdesc}{TextWrapper}{...} -The \class{TextWrapper} constructor accepts a number of optional -keyword arguments. Each argument corresponds to one instance attribute, -so for example -\begin{verbatim} -wrapper = TextWrapper(initial_indent="* ") -\end{verbatim} -is the same as -\begin{verbatim} -wrapper = TextWrapper() -wrapper.initial_indent = "* " -\end{verbatim} - -You can re-use the same \class{TextWrapper} object many times, and you -can change any of its options through direct assignment to instance -attributes between uses. -\end{classdesc} - -The \class{TextWrapper} instance attributes (and keyword arguments to -the constructor) are as follows: - -\begin{memberdesc}{width} -(default: \code{70}) The maximum length of wrapped lines. As long as -there are no individual words in the input text longer than -\member{width}, \class{TextWrapper} guarantees that no output line -will be longer than \member{width} characters. -\end{memberdesc} - -\begin{memberdesc}{expand_tabs} -(default: \code{True}) If true, then all tab characters in \var{text} -will be expanded to spaces using the \method{expandtabs()} method of -\var{text}. -\end{memberdesc} - -\begin{memberdesc}{replace_whitespace} -(default: \code{True}) If true, each whitespace character (as defined -by \code{string.whitespace}) remaining after tab expansion will be -replaced by a single space. \note{If \member{expand_tabs} is false -and \member{replace_whitespace} is true, each tab character will be -replaced by a single space, which is \emph{not} the same as tab -expansion.} -\end{memberdesc} - -\begin{memberdesc}{drop_whitespace} -(default: \code{True}) If true, whitespace that, after wrapping, happens -to end up at the beginning or end of a line is dropped (leading whitespace -in the first line is always preserved, though). -\versionadded[Whitespace was always dropped in earlier versions]{2.6} -\end{memberdesc} - -\begin{memberdesc}{initial_indent} -(default: \code{''}) String that will be prepended to the first line -of wrapped output. Counts towards the length of the first line. -\end{memberdesc} - -\begin{memberdesc}{subsequent_indent} -(default: \code{''}) String that will be prepended to all lines of -wrapped output except the first. Counts towards the length of each -line except the first. -\end{memberdesc} - -\begin{memberdesc}{fix_sentence_endings} -(default: \code{False}) If true, \class{TextWrapper} attempts to detect -sentence endings and ensure that sentences are always separated by -exactly two spaces. This is generally desired for text in a monospaced -font. However, the sentence detection algorithm is imperfect: it -assumes that a sentence ending consists of a lowercase letter followed -by one of \character{.}, -\character{!}, or \character{?}, possibly followed by one of -\character{"} or \character{'}, followed by a space. One problem -with this is algorithm is that it is unable to detect the difference -between ``Dr.'' in - -\begin{verbatim} -[...] Dr. Frankenstein's monster [...] -\end{verbatim} - -and ``Spot.'' in - -\begin{verbatim} -[...] See Spot. See Spot run [...] -\end{verbatim} - -\member{fix_sentence_endings} is false by default. - -Since the sentence detection algorithm relies on -\code{string.lowercase} for the definition of ``lowercase letter,'' -and a convention of using two spaces after a period to separate -sentences on the same line, it is specific to English-language texts. -\end{memberdesc} - -\begin{memberdesc}{break_long_words} -(default: \code{True}) If true, then words longer than -\member{width} will be broken in order to ensure that no lines are -longer than \member{width}. If it is false, long words will not be -broken, and some lines may be longer than \member{width}. (Long words -will be put on a line by themselves, in order to minimize the amount -by which \member{width} is exceeded.) -\end{memberdesc} - -\class{TextWrapper} also provides two public methods, analogous to the -module-level convenience functions: - -\begin{methoddesc}{wrap}{text} -Wraps the single paragraph in \var{text} (a string) so every line is -at most \member{width} characters long. All wrapping options are -taken from instance attributes of the \class{TextWrapper} instance. -Returns a list of output lines, without final newlines. -\end{methoddesc} - -\begin{methoddesc}{fill}{text} -Wraps the single paragraph in \var{text}, and returns a single string -containing the wrapped paragraph. -\end{methoddesc} diff --git a/Doc/lib/libthread.tex b/Doc/lib/libthread.tex deleted file mode 100644 index d007eec..0000000 --- a/Doc/lib/libthread.tex +++ /dev/null @@ -1,173 +0,0 @@ -\section{\module{thread} --- - Multiple threads of control} - -\declaremodule{builtin}{thread} -\modulesynopsis{Create multiple threads of control within one interpreter.} - - -This module provides low-level primitives for working with multiple -threads (a.k.a.\ \dfn{light-weight processes} or \dfn{tasks}) --- multiple -threads of control sharing their global data space. For -synchronization, simple locks (a.k.a.\ \dfn{mutexes} or \dfn{binary -semaphores}) are provided. -\index{light-weight processes} -\index{processes, light-weight} -\index{binary semaphores} -\index{semaphores, binary} - -The module is optional. It is supported on Windows, Linux, SGI -IRIX, Solaris 2.x, as well as on systems that have a \POSIX{} thread -(a.k.a. ``pthread'') implementation. For systems lacking the \module{thread} -module, the \refmodule[dummythread]{dummy_thread} module is available. -It duplicates this module's interface and can be -used as a drop-in replacement. -\index{pthreads} -\indexii{threads}{\POSIX} - -It defines the following constant and functions: - -\begin{excdesc}{error} -Raised on thread-specific errors. -\end{excdesc} - -\begin{datadesc}{LockType} -This is the type of lock objects. -\end{datadesc} - -\begin{funcdesc}{start_new_thread}{function, args\optional{, kwargs}} -Start a new thread and return its identifier. The thread executes the function -\var{function} with the argument list \var{args} (which must be a tuple). The -optional \var{kwargs} argument specifies a dictionary of keyword arguments. -When the function returns, the thread silently exits. When the function -terminates with an unhandled exception, a stack trace is printed and -then the thread exits (but other threads continue to run). -\end{funcdesc} - -\begin{funcdesc}{interrupt_main}{} -Raise a \exception{KeyboardInterrupt} exception in the main thread. A subthread -can use this function to interrupt the main thread. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{exit}{} -Raise the \exception{SystemExit} exception. When not caught, this -will cause the thread to exit silently. -\end{funcdesc} - -%\begin{funcdesc}{exit_prog}{status} -%Exit all threads and report the value of the integer argument -%\var{status} as the exit status of the entire program. -%\strong{Caveat:} code in pending \keyword{finally} clauses, in this thread -%or in other threads, is not executed. -%\end{funcdesc} - -\begin{funcdesc}{allocate_lock}{} -Return a new lock object. Methods of locks are described below. The -lock is initially unlocked. -\end{funcdesc} - -\begin{funcdesc}{get_ident}{} -Return the `thread identifier' of the current thread. This is a -nonzero integer. Its value has no direct meaning; it is intended as a -magic cookie to be used e.g. to index a dictionary of thread-specific -data. Thread identifiers may be recycled when a thread exits and -another thread is created. -\end{funcdesc} - -\begin{funcdesc}{stack_size}{\optional{size}} -Return the thread stack size used when creating new threads. The -optional \var{size} argument specifies the stack size to be used for -subsequently created threads, and must be 0 (use platform or -configured default) or a positive integer value of at least 32,768 (32kB). -If changing the thread stack size is unsupported, a \exception{ThreadError} -is raised. If the specified stack size is invalid, a \exception{ValueError} -is raised and the stack size is unmodified. 32kB is currently the minimum -supported stack size value to guarantee sufficient stack space for the -interpreter itself. Note that some platforms may have particular -restrictions on values for the stack size, such as requiring a minimum -stack size > 32kB or requiring allocation in multiples of the system -memory page size - platform documentation should be referred to for -more information (4kB pages are common; using multiples of 4096 for -the stack size is the suggested approach in the absence of more -specific information). -Availability: Windows, systems with \POSIX{} threads. -\versionadded{2.5} -\end{funcdesc} - - -Lock objects have the following methods: - -\begin{methoddesc}[lock]{acquire}{\optional{waitflag}} -Without the optional argument, this method acquires the lock -unconditionally, if necessary waiting until it is released by another -thread (only one thread at a time can acquire a lock --- that's their -reason for existence). If the integer -\var{waitflag} argument is present, the action depends on its -value: if it is zero, the lock is only acquired if it can be acquired -immediately without waiting, while if it is nonzero, the lock is -acquired unconditionally as before. The -return value is \code{True} if the lock is acquired successfully, -\code{False} if not. -\end{methoddesc} - -\begin{methoddesc}[lock]{release}{} -Releases the lock. The lock must have been acquired earlier, but not -necessarily by the same thread. -\end{methoddesc} - -\begin{methoddesc}[lock]{locked}{} -Return the status of the lock:\ \code{True} if it has been acquired by -some thread, \code{False} if not. -\end{methoddesc} - -In addition to these methods, lock objects can also be used via the -\keyword{with} statement, e.g.: - -\begin{verbatim} -from __future__ import with_statement -import thread - -a_lock = thread.allocate_lock() - -with a_lock: - print "a_lock is locked while this executes" -\end{verbatim} - -\strong{Caveats:} - -\begin{itemize} -\item -Threads interact strangely with interrupts: the -\exception{KeyboardInterrupt} exception will be received by an -arbitrary thread. (When the \refmodule{signal}\refbimodindex{signal} -module is available, interrupts always go to the main thread.) - -\item -Calling \function{sys.exit()} or raising the \exception{SystemExit} -exception is equivalent to calling \function{exit()}. - -\item -Not all built-in functions that may block waiting for I/O allow other -threads to run. (The most popular ones (\function{time.sleep()}, -\method{\var{file}.read()}, \function{select.select()}) work as -expected.) - -\item -It is not possible to interrupt the \method{acquire()} method on a lock ---- the \exception{KeyboardInterrupt} exception will happen after the -lock has been acquired. - -\item -When the main thread exits, it is system defined whether the other -threads survive. On SGI IRIX using the native thread implementation, -they survive. On most other systems, they are killed without -executing \keyword{try} ... \keyword{finally} clauses or executing -object destructors. -\indexii{threads}{IRIX} - -\item -When the main thread exits, it does not do any of its usual cleanup -(except that \keyword{try} ... \keyword{finally} clauses are honored), -and the standard I/O files are not flushed. - -\end{itemize} diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex deleted file mode 100644 index 19c496e..0000000 --- a/Doc/lib/libthreading.tex +++ /dev/null @@ -1,728 +0,0 @@ -\section{\module{threading} --- - Higher-level threading interface} - -\declaremodule{standard}{threading} -\modulesynopsis{Higher-level threading interface.} - - -This module constructs higher-level threading interfaces on top of the -lower level \refmodule{thread} module. - -The \refmodule[dummythreading]{dummy_threading} module is provided for -situations where \module{threading} cannot be used because -\refmodule{thread} is missing. - -This module defines the following functions and objects: - -\begin{funcdesc}{activeCount}{} -Return the number of \class{Thread} objects currently alive. The -returned count is equal to the length of the list returned by -\function{enumerate()}. -\end{funcdesc} - -\begin{funcdescni}{Condition}{} -A factory function that returns a new condition variable object. -A condition variable allows one or more threads to wait until they -are notified by another thread. -\end{funcdescni} - -\begin{funcdesc}{currentThread}{} -Return the current \class{Thread} object, corresponding to the -caller's thread of control. If the caller's thread of control was not -created through the -\module{threading} module, a dummy thread object with limited functionality -is returned. -\end{funcdesc} - -\begin{funcdesc}{enumerate}{} -Return a list of all \class{Thread} objects currently alive. The list -includes daemonic threads, dummy thread objects created by -\function{currentThread()}, and the main thread. It excludes -terminated threads and threads that have not yet been started. -\end{funcdesc} - -\begin{funcdescni}{Event}{} -A factory function that returns a new event object. An event manages -a flag that can be set to true with the \method{set()} method and -reset to false with the \method{clear()} method. The \method{wait()} -method blocks until the flag is true. -\end{funcdescni} - -\begin{classdesc*}{local}{} -A class that represents thread-local data. Thread-local data are data -whose values are thread specific. To manage thread-local data, just -create an instance of \class{local} (or a subclass) and store -attributes on it: - -\begin{verbatim} -mydata = threading.local() -mydata.x = 1 -\end{verbatim} - -The instance's values will be different for separate threads. - -For more details and extensive examples, see the documentation string -of the \module{_threading_local} module. - -\versionadded{2.4} -\end{classdesc*} - -\begin{funcdesc}{Lock}{} -A factory function that returns a new primitive lock object. Once -a thread has acquired it, subsequent attempts to acquire it block, -until it is released; any thread may release it. -\end{funcdesc} - -\begin{funcdesc}{RLock}{} -A factory function that returns a new reentrant lock object. -A reentrant lock must be released by the thread that acquired it. -Once a thread has acquired a reentrant lock, the same thread may -acquire it again without blocking; the thread must release it once -for each time it has acquired it. -\end{funcdesc} - -\begin{funcdescni}{Semaphore}{\optional{value}} -A factory function that returns a new semaphore object. A -semaphore manages a counter representing the number of \method{release()} -calls minus the number of \method{acquire()} calls, plus an initial value. -The \method{acquire()} method blocks if necessary until it can return -without making the counter negative. If not given, \var{value} defaults to -1. -\end{funcdescni} - -\begin{funcdesc}{BoundedSemaphore}{\optional{value}} -A factory function that returns a new bounded semaphore object. A bounded -semaphore checks to make sure its current value doesn't exceed its initial -value. If it does, \exception{ValueError} is raised. In most situations -semaphores are used to guard resources with limited capacity. If the -semaphore is released too many times it's a sign of a bug. If not given, -\var{value} defaults to 1. -\end{funcdesc} - -\begin{classdesc*}{Thread} -A class that represents a thread of control. This class can be safely -subclassed in a limited fashion. -\end{classdesc*} - -\begin{classdesc*}{Timer} -A thread that executes a function after a specified interval has passed. -\end{classdesc*} - -\begin{funcdesc}{settrace}{func} -Set a trace function\index{trace function} for all threads started -from the \module{threading} module. The \var{func} will be passed to -\function{sys.settrace()} for each thread, before its \method{run()} -method is called. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{setprofile}{func} -Set a profile function\index{profile function} for all threads started -from the \module{threading} module. The \var{func} will be passed to -\function{sys.setprofile()} for each thread, before its \method{run()} -method is called. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{stack_size}{\optional{size}} -Return the thread stack size used when creating new threads. The -optional \var{size} argument specifies the stack size to be used for -subsequently created threads, and must be 0 (use platform or -configured default) or a positive integer value of at least 32,768 (32kB). -If changing the thread stack size is unsupported, a \exception{ThreadError} -is raised. If the specified stack size is invalid, a \exception{ValueError} -is raised and the stack size is unmodified. 32kB is currently the minimum -supported stack size value to guarantee sufficient stack space for the -interpreter itself. Note that some platforms may have particular -restrictions on values for the stack size, such as requiring a minimum -stack size > 32kB or requiring allocation in multiples of the system -memory page size - platform documentation should be referred to for -more information (4kB pages are common; using multiples of 4096 for -the stack size is the suggested approach in the absence of more -specific information). -Availability: Windows, systems with \POSIX{} threads. -\versionadded{2.5} -\end{funcdesc} - -Detailed interfaces for the objects are documented below. - -The design of this module is loosely based on Java's threading model. -However, where Java makes locks and condition variables basic behavior -of every object, they are separate objects in Python. Python's \class{Thread} -class supports a subset of the behavior of Java's Thread class; -currently, there are no priorities, no thread groups, and threads -cannot be destroyed, stopped, suspended, resumed, or interrupted. The -static methods of Java's Thread class, when implemented, are mapped to -module-level functions. - -All of the methods described below are executed atomically. - - -\subsection{Lock Objects \label{lock-objects}} - -A primitive lock is a synchronization primitive that is not owned -by a particular thread when locked. In Python, it is currently -the lowest level synchronization primitive available, implemented -directly by the \refmodule{thread} extension module. - -A primitive lock is in one of two states, ``locked'' or ``unlocked''. -It is created in the unlocked state. It has two basic methods, -\method{acquire()} and \method{release()}. When the state is -unlocked, \method{acquire()} changes the state to locked and returns -immediately. When the state is locked, \method{acquire()} blocks -until a call to \method{release()} in another thread changes it to -unlocked, then the \method{acquire()} call resets it to locked and -returns. The \method{release()} method should only be called in the -locked state; it changes the state to unlocked and returns -immediately. If an attempt is made to release an unlocked lock, a -\exception{RuntimeError} will be raised. - -When more than one thread is blocked in \method{acquire()} waiting for -the state to turn to unlocked, only one thread proceeds when a -\method{release()} call resets the state to unlocked; which one of the -waiting threads proceeds is not defined, and may vary across -implementations. - -All methods are executed atomically. - -\begin{methoddesc}[Lock]{acquire}{\optional{blocking\code{ = 1}}} -Acquire a lock, blocking or non-blocking. - -When invoked without arguments, block until the lock is -unlocked, then set it to locked, and return true. - -When invoked with the \var{blocking} argument set to true, do the -same thing as when called without arguments, and return true. - -When invoked with the \var{blocking} argument set to false, do not -block. If a call without an argument would block, return false -immediately; otherwise, do the same thing as when called -without arguments, and return true. -\end{methoddesc} - -\begin{methoddesc}[Lock]{release}{} -Release a lock. - -When the lock is locked, reset it to unlocked, and return. If -any other threads are blocked waiting for the lock to become -unlocked, allow exactly one of them to proceed. - -Do not call this method when the lock is unlocked. - -There is no return value. -\end{methoddesc} - - -\subsection{RLock Objects \label{rlock-objects}} - -A reentrant lock is a synchronization primitive that may be -acquired multiple times by the same thread. Internally, it uses -the concepts of ``owning thread'' and ``recursion level'' in -addition to the locked/unlocked state used by primitive locks. In -the locked state, some thread owns the lock; in the unlocked -state, no thread owns it. - -To lock the lock, a thread calls its \method{acquire()} method; this -returns once the thread owns the lock. To unlock the lock, a -thread calls its \method{release()} method. -\method{acquire()}/\method{release()} call pairs may be nested; only -the final \method{release()} (the \method{release()} of the outermost -pair) resets the lock to unlocked and allows another thread blocked in -\method{acquire()} to proceed. - -\begin{methoddesc}[RLock]{acquire}{\optional{blocking\code{ = 1}}} -Acquire a lock, blocking or non-blocking. - -When invoked without arguments: if this thread already owns -the lock, increment the recursion level by one, and return -immediately. Otherwise, if another thread owns the lock, -block until the lock is unlocked. Once the lock is unlocked -(not owned by any thread), then grab ownership, set the -recursion level to one, and return. If more than one thread -is blocked waiting until the lock is unlocked, only one at a -time will be able to grab ownership of the lock. There is no -return value in this case. - -When invoked with the \var{blocking} argument set to true, do the -same thing as when called without arguments, and return true. - -When invoked with the \var{blocking} argument set to false, do not -block. If a call without an argument would block, return false -immediately; otherwise, do the same thing as when called -without arguments, and return true. -\end{methoddesc} - -\begin{methoddesc}[RLock]{release}{} -Release a lock, decrementing the recursion level. If after the -decrement it is zero, reset the lock to unlocked (not owned by any -thread), and if any other threads are blocked waiting for the lock to -become unlocked, allow exactly one of them to proceed. If after the -decrement the recursion level is still nonzero, the lock remains -locked and owned by the calling thread. - -Only call this method when the calling thread owns the lock. A -\exception{RuntimeError} is raised if this method is called when the -lock is unlocked. - -There is no return value. -\end{methoddesc} - - -\subsection{Condition Objects \label{condition-objects}} - -A condition variable is always associated with some kind of lock; -this can be passed in or one will be created by default. (Passing -one in is useful when several condition variables must share the -same lock.) - -A condition variable has \method{acquire()} and \method{release()} -methods that call the corresponding methods of the associated lock. -It also has a \method{wait()} method, and \method{notify()} and -\method{notifyAll()} methods. These three must only be called when -the calling thread has acquired the lock, otherwise a -\exception{RuntimeError} is raised. - -The \method{wait()} method releases the lock, and then blocks until it -is awakened by a \method{notify()} or \method{notifyAll()} call for -the same condition variable in another thread. Once awakened, it -re-acquires the lock and returns. It is also possible to specify a -timeout. - -The \method{notify()} method wakes up one of the threads waiting for -the condition variable, if any are waiting. The \method{notifyAll()} -method wakes up all threads waiting for the condition variable. - -Note: the \method{notify()} and \method{notifyAll()} methods don't -release the lock; this means that the thread or threads awakened will -not return from their \method{wait()} call immediately, but only when -the thread that called \method{notify()} or \method{notifyAll()} -finally relinquishes ownership of the lock. - -Tip: the typical programming style using condition variables uses the -lock to synchronize access to some shared state; threads that are -interested in a particular change of state call \method{wait()} -repeatedly until they see the desired state, while threads that modify -the state call \method{notify()} or \method{notifyAll()} when they -change the state in such a way that it could possibly be a desired -state for one of the waiters. For example, the following code is a -generic producer-consumer situation with unlimited buffer capacity: - -\begin{verbatim} -# Consume one item -cv.acquire() -while not an_item_is_available(): - cv.wait() -get_an_available_item() -cv.release() - -# Produce one item -cv.acquire() -make_an_item_available() -cv.notify() -cv.release() -\end{verbatim} - -To choose between \method{notify()} and \method{notifyAll()}, consider -whether one state change can be interesting for only one or several -waiting threads. E.g. in a typical producer-consumer situation, -adding one item to the buffer only needs to wake up one consumer -thread. - -\begin{classdesc}{Condition}{\optional{lock}} -If the \var{lock} argument is given and not \code{None}, it must be a -\class{Lock} or \class{RLock} object, and it is used as the underlying -lock. Otherwise, a new \class{RLock} object is created and used as -the underlying lock. -\end{classdesc} - -\begin{methoddesc}{acquire}{*args} -Acquire the underlying lock. -This method calls the corresponding method on the underlying -lock; the return value is whatever that method returns. -\end{methoddesc} - -\begin{methoddesc}{release}{} -Release the underlying lock. -This method calls the corresponding method on the underlying -lock; there is no return value. -\end{methoddesc} - -\begin{methoddesc}{wait}{\optional{timeout}} -Wait until notified or until a timeout occurs. If the calling thread -has not acquired the lock when this method is called, a -\exception{RuntimeError} is raised. - -This method releases the underlying lock, and then blocks until it is -awakened by a \method{notify()} or \method{notifyAll()} call for the -same condition variable in another thread, or until the optional -timeout occurs. Once awakened or timed out, it re-acquires the lock -and returns. - -When the \var{timeout} argument is present and not \code{None}, it -should be a floating point number specifying a timeout for the -operation in seconds (or fractions thereof). - -When the underlying lock is an \class{RLock}, it is not released using -its \method{release()} method, since this may not actually unlock the -lock when it was acquired multiple times recursively. Instead, an -internal interface of the \class{RLock} class is used, which really -unlocks it even when it has been recursively acquired several times. -Another internal interface is then used to restore the recursion level -when the lock is reacquired. -\end{methoddesc} - -\begin{methoddesc}{notify}{} -Wake up a thread waiting on this condition, if any. Wait until -notified or until a timeout occurs. If the calling thread has not -acquired the lock when this method is called, a -\exception{RuntimeError} is raised. - -This method wakes up one of the threads waiting for the condition -variable, if any are waiting; it is a no-op if no threads are waiting. - -The current implementation wakes up exactly one thread, if any are -waiting. However, it's not safe to rely on this behavior. A future, -optimized implementation may occasionally wake up more than one -thread. - -Note: the awakened thread does not actually return from its -\method{wait()} call until it can reacquire the lock. Since -\method{notify()} does not release the lock, its caller should. -\end{methoddesc} - -\begin{methoddesc}{notifyAll}{} -Wake up all threads waiting on this condition. This method acts like -\method{notify()}, but wakes up all waiting threads instead of one. If -the calling thread has not acquired the lock when this method is -called, a \exception{RuntimeError} is raised. -\end{methoddesc} - - -\subsection{Semaphore Objects \label{semaphore-objects}} - -This is one of the oldest synchronization primitives in the history of -computer science, invented by the early Dutch computer scientist -Edsger W. Dijkstra (he used \method{P()} and \method{V()} instead of -\method{acquire()} and \method{release()}). - -A semaphore manages an internal counter which is decremented by each -\method{acquire()} call and incremented by each \method{release()} -call. The counter can never go below zero; when \method{acquire()} -finds that it is zero, it blocks, waiting until some other thread -calls \method{release()}. - -\begin{classdesc}{Semaphore}{\optional{value}} -The optional argument gives the initial \var{value} for the internal -counter; it defaults to \code{1}. If the \var{value} given is less -than 0, \exception{ValueError} is raised. -\end{classdesc} - -\begin{methoddesc}{acquire}{\optional{blocking}} -Acquire a semaphore. - -When invoked without arguments: if the internal counter is larger than -zero on entry, decrement it by one and return immediately. If it is -zero on entry, block, waiting until some other thread has called -\method{release()} to make it larger than zero. This is done with -proper interlocking so that if multiple \method{acquire()} calls are -blocked, \method{release()} will wake exactly one of them up. The -implementation may pick one at random, so the order in which blocked -threads are awakened should not be relied on. There is no return -value in this case. - -When invoked with \var{blocking} set to true, do the same thing as -when called without arguments, and return true. - -When invoked with \var{blocking} set to false, do not block. If a -call without an argument would block, return false immediately; -otherwise, do the same thing as when called without arguments, and -return true. -\end{methoddesc} - -\begin{methoddesc}{release}{} -Release a semaphore, -incrementing the internal counter by one. When it was zero on -entry and another thread is waiting for it to become larger -than zero again, wake up that thread. -\end{methoddesc} - - -\subsubsection{\class{Semaphore} Example \label{semaphore-examples}} - -Semaphores are often used to guard resources with limited capacity, for -example, a database server. In any situation where the size of the resource -size is fixed, you should use a bounded semaphore. Before spawning any -worker threads, your main thread would initialize the semaphore: - -\begin{verbatim} -maxconnections = 5 -... -pool_sema = BoundedSemaphore(value=maxconnections) -\end{verbatim} - -Once spawned, worker threads call the semaphore's acquire and release -methods when they need to connect to the server: - -\begin{verbatim} -pool_sema.acquire() -conn = connectdb() -... use connection ... -conn.close() -pool_sema.release() -\end{verbatim} - -The use of a bounded semaphore reduces the chance that a programming error -which causes the semaphore to be released more than it's acquired will go -undetected. - - -\subsection{Event Objects \label{event-objects}} - -This is one of the simplest mechanisms for communication between -threads: one thread signals an event and other threads wait for it. - -An event object manages an internal flag that can be set to true with -the \method{set()} method and reset to false with the \method{clear()} -method. The \method{wait()} method blocks until the flag is true. - - -\begin{classdesc}{Event}{} -The internal flag is initially false. -\end{classdesc} - -\begin{methoddesc}{isSet}{} -Return true if and only if the internal flag is true. -\end{methoddesc} - -\begin{methoddesc}{set}{} -Set the internal flag to true. -All threads waiting for it to become true are awakened. -Threads that call \method{wait()} once the flag is true will not block -at all. -\end{methoddesc} - -\begin{methoddesc}{clear}{} -Reset the internal flag to false. -Subsequently, threads calling \method{wait()} will block until -\method{set()} is called to set the internal flag to true again. -\end{methoddesc} - -\begin{methoddesc}{wait}{\optional{timeout}} -Block until the internal flag is true. -If the internal flag is true on entry, return immediately. Otherwise, -block until another thread calls \method{set()} to set the flag to -true, or until the optional timeout occurs. - -When the timeout argument is present and not \code{None}, it should be a -floating point number specifying a timeout for the operation in -seconds (or fractions thereof). -\end{methoddesc} - - -\subsection{Thread Objects \label{thread-objects}} - -This class represents an activity that is run in a separate thread -of control. There are two ways to specify the activity: by -passing a callable object to the constructor, or by overriding the -\method{run()} method in a subclass. No other methods (except for the -constructor) should be overridden in a subclass. In other words, -\emph{only} override the \method{__init__()} and \method{run()} -methods of this class. - -Once a thread object is created, its activity must be started by -calling the thread's \method{start()} method. This invokes the -\method{run()} method in a separate thread of control. - -Once the thread's activity is started, the thread is considered -'alive'. It stops being alive when its \method{run()} method terminates --- either normally, or by raising an unhandled exception. The -\method{isAlive()} method tests whether the thread is alive. - -Other threads can call a thread's \method{join()} method. This blocks -the calling thread until the thread whose \method{join()} method is -called is terminated. - -A thread has a name. The name can be passed to the constructor, -set with the \method{setName()} method, and retrieved with the -\method{getName()} method. - -A thread can be flagged as a ``daemon thread''. The significance -of this flag is that the entire Python program exits when only -daemon threads are left. The initial value is inherited from the -creating thread. The flag can be set with the \method{setDaemon()} -method and retrieved with the \method{isDaemon()} method. - -There is a ``main thread'' object; this corresponds to the -initial thread of control in the Python program. It is not a -daemon thread. - -There is the possibility that ``dummy thread objects'' are created. -These are thread objects corresponding to ``alien threads'', which -are threads of control started outside the threading module, such as -directly from C code. Dummy thread objects have limited -functionality; they are always considered alive and daemonic, and -cannot be \method{join()}ed. They are never deleted, since it is -impossible to detect the termination of alien threads. - - -\begin{classdesc}{Thread}{group=None, target=None, name=None, - args=(), kwargs=\{\}} -This constructor should always be called with keyword -arguments. Arguments are: - -\var{group} should be \code{None}; reserved for future extension when -a \class{ThreadGroup} class is implemented. - -\var{target} is the callable object to be invoked by the -\method{run()} method. Defaults to \code{None}, meaning nothing is -called. - -\var{name} is the thread name. By default, a unique name is -constructed of the form ``Thread-\var{N}'' where \var{N} is a small -decimal number. - -\var{args} is the argument tuple for the target invocation. Defaults -to \code{()}. - -\var{kwargs} is a dictionary of keyword arguments for the target -invocation. Defaults to \code{\{\}}. - -If the subclass overrides the constructor, it must make sure -to invoke the base class constructor (\code{Thread.__init__()}) -before doing anything else to the thread. -\end{classdesc} - -\begin{methoddesc}{start}{} -Start the thread's activity. - -It must be called at most once per thread object. It arranges for the -object's \method{run()} method to be invoked in a separate thread of -control. - -This method will raise a \exception{RuntimeException} if called more -than once on the same thread object. -\end{methoddesc} - -\begin{methoddesc}{run}{} -Method representing the thread's activity. - -You may override this method in a subclass. The standard -\method{run()} method invokes the callable object passed to the -object's constructor as the \var{target} argument, if any, with -sequential and keyword arguments taken from the \var{args} and -\var{kwargs} arguments, respectively. -\end{methoddesc} - -\begin{methoddesc}{join}{\optional{timeout}} -Wait until the thread terminates. -This blocks the calling thread until the thread whose \method{join()} -method is called terminates -- either normally or through an -unhandled exception -- or until the optional timeout occurs. - -When the \var{timeout} argument is present and not \code{None}, it -should be a floating point number specifying a timeout for the -operation in seconds (or fractions thereof). As \method{join()} always -returns \code{None}, you must call \method{isAlive()} to decide whether -a timeout happened. - -When the \var{timeout} argument is not present or \code{None}, the -operation will block until the thread terminates. - -A thread can be \method{join()}ed many times. - -\method{join()} may throw a \exception{RuntimeError}, if an attempt is -made to join the current thread as that would cause a deadlock. It is -also an error to \method{join()} a thread before it has been started -and attempts to do so raises same exception. -\end{methoddesc} - -\begin{methoddesc}{getName}{} -Return the thread's name. -\end{methoddesc} - -\begin{methoddesc}{setName}{name} -Set the thread's name. - -The name is a string used for identification purposes only. -It has no semantics. Multiple threads may be given the same -name. The initial name is set by the constructor. -\end{methoddesc} - -\begin{methoddesc}{isAlive}{} -Return whether the thread is alive. - -Roughly, a thread is alive from the moment the \method{start()} method -returns until its \method{run()} method terminates. The module -function \function{enumerate()} returns a list of all alive threads. -\end{methoddesc} - -\begin{methoddesc}{isDaemon}{} -Return the thread's daemon flag. -\end{methoddesc} - -\begin{methoddesc}{setDaemon}{daemonic} -Set the thread's daemon flag to the Boolean value \var{daemonic}. -This must be called before \method{start()} is called, otherwise -\exception{RuntimeError} is raised. - -The initial value is inherited from the creating thread. - -The entire Python program exits when no alive non-daemon threads are -left. -\end{methoddesc} - - -\subsection{Timer Objects \label{timer-objects}} - -This class represents an action that should be run only after a -certain amount of time has passed --- a timer. \class{Timer} is a -subclass of \class{Thread} and as such also functions as an example of -creating custom threads. - -Timers are started, as with threads, by calling their \method{start()} -method. The timer can be stopped (before its action has begun) by -calling the \method{cancel()} method. The interval the timer will -wait before executing its action may not be exactly the same as the -interval specified by the user. - -For example: -\begin{verbatim} -def hello(): - print "hello, world" - -t = Timer(30.0, hello) -t.start() # after 30 seconds, "hello, world" will be printed -\end{verbatim} - -\begin{classdesc}{Timer}{interval, function, args=[], kwargs=\{\}} -Create a timer that will run \var{function} with arguments \var{args} and -keyword arguments \var{kwargs}, after \var{interval} seconds have passed. -\end{classdesc} - -\begin{methoddesc}{cancel}{} -Stop the timer, and cancel the execution of the timer's action. This -will only work if the timer is still in its waiting stage. -\end{methoddesc} - -\subsection{Using locks, conditions, and semaphores in the \keyword{with} -statement \label{with-locks}} - -All of the objects provided by this module that have \method{acquire()} and -\method{release()} methods can be used as context managers for a \keyword{with} -statement. The \method{acquire()} method will be called when the block is -entered, and \method{release()} will be called when the block is exited. - -Currently, \class{Lock}, \class{RLock}, \class{Condition}, \class{Semaphore}, -and \class{BoundedSemaphore} objects may be used as \keyword{with} -statement context managers. For example: - -\begin{verbatim} -from __future__ import with_statement -import threading - -some_rlock = threading.RLock() - -with some_rlock: - print "some_rlock is locked while this executes" -\end{verbatim} - diff --git a/Doc/lib/libtime.tex b/Doc/lib/libtime.tex deleted file mode 100644 index 8a45bfcc..0000000 --- a/Doc/lib/libtime.tex +++ /dev/null @@ -1,475 +0,0 @@ -\section{\module{time} --- - Time access and conversions} - -\declaremodule{builtin}{time} -\modulesynopsis{Time access and conversions.} - - -This module provides various time-related functions. It is always -available, but not all functions are available on all platforms. Most -of the functions defined in this module call platform C library -functions with the same name. It may sometimes be helpful to consult -the platform documentation, because the semantics of these functions -varies among platforms. - -An explanation of some terminology and conventions is in order. - -\begin{itemize} - -\item -The \dfn{epoch}\index{epoch} is the point where the time starts. On -January 1st of that year, at 0 hours, the ``time since the epoch'' is -zero. For \UNIX, the epoch is 1970. To find out what the epoch is, -look at \code{gmtime(0)}. - -\item -The functions in this module do not handle dates and times before the -epoch or far in the future. The cut-off point in the future is -determined by the C library; for \UNIX, it is typically in -2038\index{Year 2038}. - -\item -\strong{Year 2000 (Y2K) issues}:\index{Year 2000}\index{Y2K} Python -depends on the platform's C library, which generally doesn't have year -2000 issues, since all dates and times are represented internally as -seconds since the epoch. Functions accepting a \class{struct_time} -(see below) generally require a 4-digit year. For backward -compatibility, 2-digit years are supported if the module variable -\code{accept2dyear} is a non-zero integer; this variable is -initialized to \code{1} unless the environment variable -\envvar{PYTHONY2K} is set to a non-empty string, in which case it is -initialized to \code{0}. Thus, you can set -\envvar{PYTHONY2K} to a non-empty string in the environment to require 4-digit -years for all year input. When 2-digit years are accepted, they are -converted according to the \POSIX{} or X/Open standard: values 69-99 -are mapped to 1969-1999, and values 0--68 are mapped to 2000--2068. -Values 100--1899 are always illegal. Note that this is new as of -Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1, -would add 1900 to year values below 1900. - -\item -UTC\index{UTC} is Coordinated Universal Time\index{Coordinated -Universal Time} (formerly known as Greenwich Mean -Time,\index{Greenwich Mean Time} or GMT). The acronym UTC is not a -mistake but a compromise between English and French. - -\item -DST is Daylight Saving Time,\index{Daylight Saving Time} an adjustment -of the timezone by (usually) one hour during part of the year. DST -rules are magic (determined by local law) and can change from year to -year. The C library has a table containing the local rules (often it -is read from a system file for flexibility) and is the only source of -True Wisdom in this respect. - -\item -The precision of the various real-time functions may be less than -suggested by the units in which their value or argument is expressed. -E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a -second, and on the Mac, times are only accurate to whole seconds. - -\item -On the other hand, the precision of \function{time()} and -\function{sleep()} is better than their \UNIX{} equivalents: times are -expressed as floating point numbers, \function{time()} returns the -most accurate time available (using \UNIX{} \cfunction{gettimeofday()} -where available), and \function{sleep()} will accept a time with a -nonzero fraction (\UNIX{} \cfunction{select()} is used to implement -this, where available). - -\item -The time value as returned by \function{gmtime()}, -\function{localtime()}, and \function{strptime()}, and accepted by -\function{asctime()}, \function{mktime()} and \function{strftime()}, -is a sequence of 9 integers. The return values of \function{gmtime()}, -\function{localtime()}, and \function{strptime()} also offer attribute -names for individual fields. - -\begin{tableiii}{c|l|l}{textrm}{Index}{Attribute}{Values} - \lineiii{0}{\member{tm_year}}{(for example, 1993)} - \lineiii{1}{\member{tm_mon}}{range [1,12]} - \lineiii{2}{\member{tm_mday}}{range [1,31]} - \lineiii{3}{\member{tm_hour}}{range [0,23]} - \lineiii{4}{\member{tm_min}}{range [0,59]} - \lineiii{5}{\member{tm_sec}}{range [0,61]; see \strong{(1)} in \function{strftime()} description} - \lineiii{6}{\member{tm_wday}}{range [0,6], Monday is 0} - \lineiii{7}{\member{tm_yday}}{range [1,366]} - \lineiii{8}{\member{tm_isdst}}{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 the -daylight savings flag, passed to \function{mktime()} will usually -result in the correct daylight savings state to be filled in. - -When a tuple with an incorrect length is passed to a function -expecting a \class{struct_time}, or having elements of the wrong type, a -\exception{TypeError} is raised. - -\versionchanged[The time value sequence was changed from a tuple to a - \class{struct_time}, with the addition of attribute names - for the fields]{2.2} -\end{itemize} - -The module defines the following functions and data items: - - -\begin{datadesc}{accept2dyear} -Boolean value indicating whether two-digit year values will be -accepted. This is true by default, but will be set to false if the -environment variable \envvar{PYTHONY2K} has been set to a non-empty -string. It may also be modified at run time. -\end{datadesc} - -\begin{datadesc}{altzone} -The offset of the local DST timezone, in seconds west of UTC, if one -is defined. This is negative if the local DST timezone is east of UTC -(as in Western Europe, including the UK). Only use this if -\code{daylight} is nonzero. -\end{datadesc} - -\begin{funcdesc}{asctime}{\optional{t}} -Convert a tuple or \class{struct_time} representing a time as returned -by \function{gmtime()} -or \function{localtime()} to a 24-character string of the following form: -\code{'Sun Jun 20 23:21:05 1993'}. If \var{t} is not provided, the -current time as returned by \function{localtime()} is used. -Locale information is not used by \function{asctime()}. -\note{Unlike the C function of the same name, there is no trailing -newline.} -\versionchanged[Allowed \var{t} to be omitted]{2.1} -\end{funcdesc} - -\begin{funcdesc}{clock}{} -On \UNIX, return -the current processor time as a floating point number expressed in -seconds. The precision, and in fact the very definition of the meaning -of ``processor time''\index{CPU time}\index{processor time}, depends -on that of the C function of the same name, but in any case, this is -the function to use for benchmarking\index{benchmarking} Python or -timing algorithms. - -On Windows, this function returns wall-clock seconds elapsed since the -first call to this function, as a floating point number, -based on the Win32 function \cfunction{QueryPerformanceCounter()}. -The resolution is typically better than one microsecond. -\end{funcdesc} - -\begin{funcdesc}{ctime}{\optional{secs}} -Convert a time expressed in seconds since the epoch to a string -representing local time. If \var{secs} is not provided or -\constant{None}, the current time as returned by \function{time()} is -used. \code{ctime(\var{secs})} is equivalent to -\code{asctime(localtime(\var{secs}))}. -Locale information is not used by \function{ctime()}. -\versionchanged[Allowed \var{secs} to be omitted]{2.1} -\versionchanged[If \var{secs} is \constant{None}, the current time is - used]{2.4} -\end{funcdesc} - -\begin{datadesc}{daylight} -Nonzero if a DST timezone is defined. -\end{datadesc} - -\begin{funcdesc}{gmtime}{\optional{secs}} -Convert a time expressed in seconds since the epoch to a \class{struct_time} -in UTC in which the dst flag is always zero. If \var{secs} is not -provided or \constant{None}, the current time as returned by -\function{time()} is used. Fractions of a second are ignored. See -above for a description of the \class{struct_time} object. See -\function{calendar.timegm()} for the inverse of this function. -\versionchanged[Allowed \var{secs} to be omitted]{2.1} -\versionchanged[If \var{secs} is \constant{None}, the current time is - used]{2.4} -\end{funcdesc} - -\begin{funcdesc}{localtime}{\optional{secs}} -Like \function{gmtime()} but converts to local time. If \var{secs} is -not provided or \constant{None}, the current time as returned by -\function{time()} is used. The dst flag is set to \code{1} when DST -applies to the given time. -\versionchanged[Allowed \var{secs} to be omitted]{2.1} -\versionchanged[If \var{secs} is \constant{None}, the current time is - used]{2.4} -\end{funcdesc} - -\begin{funcdesc}{mktime}{t} -This is the inverse function of \function{localtime()}. Its argument -is the \class{struct_time} or full 9-tuple (since the dst flag is -needed; use \code{-1} as the dst flag if it is unknown) which -expresses the time in -\emph{local} time, not UTC. It returns a floating point number, for -compatibility with \function{time()}. If the input value cannot be -represented as a valid time, either \exception{OverflowError} or -\exception{ValueError} will be raised (which depends on whether the -invalid value is caught by Python or the underlying C libraries). The -earliest date for which it can generate a time is platform-dependent. -\end{funcdesc} - -\begin{funcdesc}{sleep}{secs} -Suspend execution for the given number of seconds. The argument may -be a floating point number to indicate a more precise sleep time. -The actual suspension time may be less than that requested because any -caught signal will terminate the \function{sleep()} following -execution of that signal's catching routine. Also, the suspension -time may be longer than requested by an arbitrary amount because of -the scheduling of other activity in the system. -\end{funcdesc} - -\begin{funcdesc}{strftime}{format\optional{, t}} -Convert a tuple or \class{struct_time} representing a time as returned -by \function{gmtime()} or \function{localtime()} to a string as -specified by the \var{format} argument. If \var{t} is not -provided, the current time as returned by \function{localtime()} is -used. \var{format} must be a string. \exception{ValueError} is raised -if any field in \var{t} is outside of the allowed range. -\versionchanged[Allowed \var{t} to be omitted]{2.1} -\versionchanged[\exception{ValueError} raised if a field in \var{t} is -out of range]{2.4} -\versionchanged[0 is now a legal argument for any position in the time tuple; -if it is normally illegal the value is forced to a correct one.]{2.5} - - -The following directives can be embedded in the \var{format} string. -They are shown without the optional field width and precision -specification, and are replaced by the indicated characters in the -\function{strftime()} result: - -\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.}{(1)} - \lineiii{\%S}{Second as a decimal number [00,61].}{(2)} - \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.}{(3)} - \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 Monday are considered to be in week 0.}{(3)} - \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 (no characters if no time zone exists).}{} - \lineiii{\%\%}{A literal \character{\%} character.}{} -\end{tableiii} - -\noindent -Notes: - -\begin{description} - \item[(1)] - When used with the \function{strptime()} function, the \code{\%p} - directive only affects the output hour field if the \code{\%I} directive - is used to parse the hour. - \item[(2)] - The range really is \code{0} to \code{61}; this accounts for leap - seconds and the (very rare) double leap seconds. - \item[(3)] - When used with the \function{strptime()} function, \code{\%U} and \code{\%W} - are only used in calculations when the day of the week and the year are - specified. -\end{description} - -Here is an example, a format for dates compatible with that specified -in the \rfc{2822} Internet email standard. - \footnote{The use of \code{\%Z} is now - deprecated, but the \code{\%z} escape that expands to the preferred - hour/minute offset is not supported by all ANSI C libraries. Also, - a strict reading of the original 1982 \rfc{822} standard calls for - a two-digit year (\%y rather than \%Y), but practice moved to - 4-digit years long before the year 2000. The 4-digit year has - been mandated by \rfc{2822}, which obsoletes \rfc{822}.} - -\begin{verbatim} ->>> from time import gmtime, strftime ->>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime()) -'Thu, 28 Jun 2001 14:17:15 +0000' -\end{verbatim} - -Additional directives may be supported on certain platforms, but -only the ones listed here have a meaning standardized by ANSI C. - -On some platforms, an optional field width and precision -specification can immediately follow the initial \character{\%} of a -directive in the following order; this is also not portable. -The field width is normally 2 except for \code{\%j} where it is 3. -\end{funcdesc} - -\begin{funcdesc}{strptime}{string\optional{, format}} -Parse a string representing a time according to a format. The return -value is a \class{struct_time} as returned by \function{gmtime()} or -\function{localtime()}. - -The \var{format} parameter uses the same directives as those used by -\function{strftime()}; it defaults to \code{"\%a \%b \%d \%H:\%M:\%S - \%Y"} which matches the formatting returned by \function{ctime()}. -If \var{string} cannot be parsed according to \var{format}, or if it -has excess data after parsing, \exception{ValueError} is raised. The -default values used to fill in any missing data when more accurate -values cannot be inferred are \code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)}. - -For example: - -\begin{verbatim} ->>> import time ->>> time.strptime("30 Nov 00", "%d %b %y") -(2000, 11, 30, 0, 0, 0, 3, 335, -1) -\end{verbatim} - -Support for the \code{\%Z} directive is based on the values contained in -\code{tzname} and whether \code{daylight} is true. Because of this, -it is platform-specific except for recognizing UTC and GMT which are -always known (and are considered to be non-daylight savings -timezones). - -Only the directives specified in the documentation are supported. Because -\code{strftime()} is implemented per platform it can sometimes offer more -directives than those listed. But \code{strptime()} is independent of any -platform and thus does not necessarily support all directives available that -are not documented as supported. -\end{funcdesc} - -\begin{datadesc}{struct_time} -The type of the time value sequence returned by \function{gmtime()}, -\function{localtime()}, and \function{strptime()}. -\versionadded{2.2} -\end{datadesc} - -\begin{funcdesc}{time}{} -Return the time as a floating point number expressed in seconds since -the epoch, in UTC. Note that even though the time is always returned -as a floating point number, not all systems provide time with a better -precision than 1 second. While this function normally returns -non-decreasing values, it can return a lower value than a previous -call if the system clock has been set back between the two calls. -\end{funcdesc} - -\begin{datadesc}{timezone} -The offset of the local (non-DST) timezone, in seconds west of UTC -(negative in most of Western Europe, positive in the US, zero in the -UK). -\end{datadesc} - -\begin{datadesc}{tzname} -A tuple of two strings: the first is the name of the local non-DST -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{funcdesc}{tzset}{} -Resets the time conversion rules used by the library routines. -The environment variable \envvar{TZ} specifies how this is done. -\versionadded{2.3} - -Availability: \UNIX. - -\begin{notice} -Although in many cases, changing the \envvar{TZ} environment variable -may affect the output of functions like \function{localtime} without calling -\function{tzset}, this behavior should not be relied on. - -The \envvar{TZ} environment variable should contain no whitespace. -\end{notice} - -The standard format of the \envvar{TZ} environment variable is: -(whitespace added for clarity) -\begin{itemize} - \item[std offset [dst [offset] [,start[/time], end[/time]]]] -\end{itemize} - -Where: - -\begin{itemize} - \item[std and dst] - Three or more alphanumerics giving the timezone abbreviations. - These will be propagated into time.tzname - - \item[offset] - The offset has the form: \plusminus{} hh[:mm[:ss]]. - This indicates the value added the local time to arrive at UTC. - If preceded by a '-', the timezone is east of the Prime - Meridian; otherwise, it is west. If no offset follows - dst, summer time is assumed to be one hour ahead of standard time. - - \item[start[/time],end[/time]] - Indicates when to change to and back from DST. The format of the - start and end dates are one of the following: - - \begin{itemize} - \item[J\var{n}] - The Julian day \var{n} (1 <= \var{n} <= 365). Leap days are not - counted, so in all years February 28 is day 59 and - March 1 is day 60. - - \item[\var{n}] - The zero-based Julian day (0 <= \var{n} <= 365). Leap days are - counted, and it is possible to refer to February 29. - - \item[M\var{m}.\var{n}.\var{d}] - The \var{d}'th day (0 <= \var{d} <= 6) or week \var{n} - of month \var{m} of the year (1 <= \var{n} <= 5, - 1 <= \var{m} <= 12, where week 5 means "the last \var{d} day - in month \var{m}" which may occur in either the fourth or - the fifth week). Week 1 is the first week in which the - \var{d}'th day occurs. Day zero is Sunday. - \end{itemize} - - time has the same format as offset except that no leading sign ('-' or - '+') is allowed. The default, if time is not given, is 02:00:00. -\end{itemize} - - -\begin{verbatim} ->>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0' ->>> time.tzset() ->>> time.strftime('%X %x %Z') -'02:07:36 05/08/03 EDT' ->>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0' ->>> time.tzset() ->>> time.strftime('%X %x %Z') -'16:08:12 05/08/03 AEST' -\end{verbatim} - -On many \UNIX{} systems (including *BSD, Linux, Solaris, and Darwin), it -is more convenient to use the system's zoneinfo (\manpage{tzfile}{5}) -database to specify the timezone rules. To do this, set the -\envvar{TZ} environment variable to the path of the required timezone -datafile, relative to the root of the systems 'zoneinfo' timezone database, -usually located at \file{/usr/share/zoneinfo}. For example, -\code{'US/Eastern'}, \code{'Australia/Melbourne'}, \code{'Egypt'} or -\code{'Europe/Amsterdam'}. - -\begin{verbatim} ->>> os.environ['TZ'] = 'US/Eastern' ->>> time.tzset() ->>> time.tzname -('EST', 'EDT') ->>> os.environ['TZ'] = 'Egypt' ->>> time.tzset() ->>> time.tzname -('EET', 'EEST') -\end{verbatim} - -\end{funcdesc} - - -\begin{seealso} - \seemodule{datetime}{More object-oriented interface to dates and times.} - \seemodule{locale}{Internationalization services. The locale - settings can affect the return values for some of - the functions in the \module{time} module.} - \seemodule{calendar}{General calendar-related functions. - \function{timegm()} is the inverse of - \function{gmtime()} from this module.} -\end{seealso} diff --git a/Doc/lib/libtimeit.tex b/Doc/lib/libtimeit.tex deleted file mode 100644 index 968728f..0000000 --- a/Doc/lib/libtimeit.tex +++ /dev/null @@ -1,249 +0,0 @@ -\section{\module{timeit} --- - Measure execution time of small code snippets} - -\declaremodule{standard}{timeit} -\modulesynopsis{Measure the execution time of small code snippets.} - -\versionadded{2.3} -\index{Benchmarking} -\index{Performance} - -This module provides a simple way to time small bits of Python code. -It has both command line as well as callable interfaces. It avoids a -number of common traps for measuring execution times. See also Tim -Peters' introduction to the ``Algorithms'' chapter in the -\citetitle{Python Cookbook}, published by O'Reilly. - -The module defines the following public class: - -\begin{classdesc}{Timer}{\optional{stmt=\code{'pass'} - \optional{, setup=\code{'pass'} - \optional{, timer=<timer function>}}}} -Class for timing execution speed of small code snippets. - -The constructor takes a statement to be timed, an additional statement -used for setup, and a timer function. Both statements default to -\code{'pass'}; the timer function is platform-dependent (see the -module doc string). The statements may contain newlines, as long as -they don't contain multi-line string literals. - -To measure the execution time of the first statement, use the -\method{timeit()} method. The \method{repeat()} method is a -convenience to call \method{timeit()} multiple times and return a list -of results. - -\versionchanged[The \var{stmt} and \var{setup} parameters can now also - take objects that are callable without arguments. This - will embed calls to them in a timer function that will - then be executed by \method{timeit()}. Note that the timing - overhead is a little larger in this case because of the - extra function calls]{2.6} -\end{classdesc} - -\begin{methoddesc}{print_exc}{\optional{file=\constant{None}}} -Helper to print a traceback from the timed code. - -Typical use: - -\begin{verbatim} - t = Timer(...) # outside the try/except - try: - t.timeit(...) # or t.repeat(...) - except: - t.print_exc() -\end{verbatim} - -The advantage over the standard traceback is that source lines in the -compiled template will be displayed. -The optional \var{file} argument directs where the traceback is sent; -it defaults to \code{sys.stderr}. -\end{methoddesc} - -\begin{methoddesc}{repeat}{\optional{repeat\code{=3} \optional{, - number\code{=1000000}}}} -Call \method{timeit()} a few times. - -This is a convenience function that calls the \method{timeit()} -repeatedly, returning a list of results. The first argument specifies -how many times to call \method{timeit()}. The second argument -specifies the \var{number} argument for \function{timeit()}. - -\begin{notice} -It's tempting to calculate mean and standard deviation from the result -vector and report these. However, this is not very useful. In a typical -case, the lowest value gives a lower bound for how fast your machine can run -the given code snippet; higher values in the result vector are typically not -caused by variability in Python's speed, but by other processes interfering -with your timing accuracy. So the \function{min()} of the result is -probably the only number you should be interested in. After that, you -should look at the entire vector and apply common sense rather than -statistics. -\end{notice} -\end{methoddesc} - -\begin{methoddesc}{timeit}{\optional{number\code{=1000000}}} -Time \var{number} executions of the main statement. -This executes the setup statement once, and then -returns the time it takes to execute the main statement a number of -times, measured in seconds as a float. The argument is the number of -times through the loop, defaulting to one million. The main -statement, the setup statement and the timer function to be used are -passed to the constructor. - -\begin{notice} -By default, \method{timeit()} temporarily turns off garbage collection -during the timing. The advantage of this approach is that it makes -independent timings more comparable. This disadvantage is that GC -may be an important component of the performance of the function being -measured. If so, GC can be re-enabled as the first statement in the -\var{setup} string. For example: -\begin{verbatim} - timeit.Timer('for i in range(10): oct(i)', 'gc.enable()').timeit() -\end{verbatim} -\end{notice} -\end{methoddesc} - - -Starting with version 2.6, the module also defines two convenience functions: - -\begin{funcdesc}{repeat}{stmt\optional{, setup\optional{, timer\optional{, - repeat\code{=3} \optional{, number\code{=1000000}}}}}} -Create a \class{Timer} instance with the given statement, setup code and timer -function and run its \method{repeat} method with the given repeat count and -\var{number} executions. -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{timeit}{stmt\optional{, setup\optional{, timer\optional{, - number\code{=1000000}}}}} -Create a \class{Timer} instance with the given statement, setup code and timer -function and run its \method{timeit} method with \var{number} executions. -\versionadded{2.6} -\end{funcdesc} - - -\subsection{Command Line Interface} - -When called as a program from the command line, the following form is used: - -\begin{verbatim} -python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...] -\end{verbatim} - -where the following options are understood: - -\begin{description} -\item[-n N/\longprogramopt{number=N}] how many times to execute 'statement' -\item[-r N/\longprogramopt{repeat=N}] how many times to repeat the timer (default 3) -\item[-s S/\longprogramopt{setup=S}] statement to be executed once initially (default -\code{'pass'}) -\item[-t/\longprogramopt{time}] use \function{time.time()} -(default on all platforms but Windows) -\item[-c/\longprogramopt{clock}] use \function{time.clock()} (default on Windows) -\item[-v/\longprogramopt{verbose}] print raw timing results; repeat for more digits -precision -\item[-h/\longprogramopt{help}] print a short usage message and exit -\end{description} - -A multi-line statement may be given by specifying each line as a -separate statement argument; indented lines are possible by enclosing -an argument in quotes and using leading spaces. Multiple -\programopt{-s} options are treated similarly. - -If \programopt{-n} is not given, a suitable number of loops is -calculated by trying successive powers of 10 until the total time is -at least 0.2 seconds. - -The default timer function is platform dependent. On Windows, -\function{time.clock()} has microsecond granularity but -\function{time.time()}'s granularity is 1/60th of a second; on \UNIX, -\function{time.clock()} has 1/100th of a second granularity and -\function{time.time()} is much more precise. On either platform, the -default timer functions measure wall clock time, not the CPU time. -This means that other processes running on the same computer may -interfere with the timing. The best thing to do when accurate timing -is necessary is to repeat the timing a few times and use the best -time. The \programopt{-r} option is good for this; the default of 3 -repetitions is probably enough in most cases. On \UNIX, you can use -\function{time.clock()} to measure CPU time. - -\begin{notice} - There is a certain baseline overhead associated with executing a - pass statement. The code here doesn't try to hide it, but you - should be aware of it. The baseline overhead can be measured by - invoking the program without arguments. -\end{notice} - -The baseline overhead differs between Python versions! Also, to -fairly compare older Python versions to Python 2.3, you may want to -use Python's \programopt{-O} option for the older versions to avoid -timing \code{SET_LINENO} instructions. - -\subsection{Examples} - -Here are two example sessions (one using the command line, one using -the module interface) that compare the cost of using -\function{hasattr()} vs. \keyword{try}/\keyword{except} to test for -missing and present object attributes. - -\begin{verbatim} -% timeit.py 'try:' ' str.__bool__' 'except AttributeError:' ' pass' -100000 loops, best of 3: 15.7 usec per loop -% timeit.py 'if hasattr(str, "__bool__"): pass' -100000 loops, best of 3: 4.26 usec per loop -% timeit.py 'try:' ' int.__bool__' 'except AttributeError:' ' pass' -1000000 loops, best of 3: 1.43 usec per loop -% timeit.py 'if hasattr(int, "__bool__"): pass' -100000 loops, best of 3: 2.23 usec per loop -\end{verbatim} - -\begin{verbatim} ->>> import timeit ->>> s = """\ -... try: -... str.__bool__ -... except AttributeError: -... pass -... """ ->>> t = timeit.Timer(stmt=s) ->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000) -17.09 usec/pass ->>> s = """\ -... if hasattr(str, '__bool__'): pass -... """ ->>> t = timeit.Timer(stmt=s) ->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000) -4.85 usec/pass ->>> s = """\ -... try: -... int.__bool__ -... except AttributeError: -... pass -... """ ->>> t = timeit.Timer(stmt=s) ->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000) -1.97 usec/pass ->>> s = """\ -... if hasattr(int, '__bool__'): pass -... """ ->>> t = timeit.Timer(stmt=s) ->>> print "%.2f usec/pass" % (1000000 * t.timeit(number=100000)/100000) -3.15 usec/pass -\end{verbatim} - -To give the \module{timeit} module access to functions you -define, you can pass a \code{setup} parameter which contains an import -statement: - -\begin{verbatim} -def test(): - "Stupid test function" - L = [] - for i in range(100): - L.append(i) - -if __name__=='__main__': - from timeit import Timer - t = Timer("test()", "from __main__ import test") - print t.timeit() -\end{verbatim} diff --git a/Doc/lib/libtoken.tex b/Doc/lib/libtoken.tex deleted file mode 100644 index 47f4750..0000000 --- a/Doc/lib/libtoken.tex +++ /dev/null @@ -1,44 +0,0 @@ -\section{\module{token} --- - Constants used with Python parse trees} - -\declaremodule{standard}{token} -\modulesynopsis{Constants representing terminal nodes of the parse tree.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -This module provides constants which represent the numeric values of -leaf nodes of the parse tree (terminal tokens). Refer to the file -\file{Grammar/Grammar} in the Python distribution for the definitions -of the names in the context of the language grammar. The specific -numeric values which the names map to may change between Python -versions. - -This module also provides one data object and some functions. The -functions mirror definitions in the Python C header files. - - - -\begin{datadesc}{tok_name} -Dictionary mapping the numeric values of the constants defined in this -module back to name strings, allowing more human-readable -representation of parse trees to be generated. -\end{datadesc} - -\begin{funcdesc}{ISTERMINAL}{x} -Return true for terminal token values. -\end{funcdesc} - -\begin{funcdesc}{ISNONTERMINAL}{x} -Return true for non-terminal token values. -\end{funcdesc} - -\begin{funcdesc}{ISEOF}{x} -Return true if \var{x} is the marker indicating the end of input. -\end{funcdesc} - - -\begin{seealso} - \seemodule{parser}{The second example for the \refmodule{parser} - module shows how to use the \module{symbol} - module.} -\end{seealso} diff --git a/Doc/lib/libtokenize.tex b/Doc/lib/libtokenize.tex deleted file mode 100644 index 8c9ad3e..0000000 --- a/Doc/lib/libtokenize.tex +++ /dev/null @@ -1,119 +0,0 @@ -\section{\module{tokenize} --- - Tokenizer for Python source} - -\declaremodule{standard}{tokenize} -\modulesynopsis{Lexical scanner for Python source code.} -\moduleauthor{Ka Ping Yee}{} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -The \module{tokenize} module provides a lexical scanner for Python -source code, implemented in Python. The scanner in this module -returns comments as tokens as well, making it useful for implementing -``pretty-printers,'' including colorizers for on-screen displays. - -The primary entry point is a generator: - -\begin{funcdesc}{generate_tokens}{readline} - The \function{generate_tokens()} generator requires one argment, - \var{readline}, which must be a callable object which - provides the same interface as the \method{readline()} method of - built-in file objects (see section~\ref{bltin-file-objects}). Each - call to the function should return one line of input as a string. - - The generator produces 5-tuples with these members: - the token type; - the token string; - a 2-tuple \code{(\var{srow}, \var{scol})} of ints specifying the - row and column where the token begins in the source; - a 2-tuple \code{(\var{erow}, \var{ecol})} of ints specifying the - row and column where the token ends in the source; - and the line on which the token was found. - The line passed is the \emph{logical} line; - continuation lines are included. - \versionadded{2.2} -\end{funcdesc} - -An older entry point is retained for backward compatibility: - -\begin{funcdesc}{tokenize}{readline\optional{, tokeneater}} - The \function{tokenize()} function accepts two parameters: one - representing the input stream, and one providing an output mechanism - for \function{tokenize()}. - - The first parameter, \var{readline}, must be a callable object which - provides the same interface as the \method{readline()} method of - built-in file objects (see section~\ref{bltin-file-objects}). Each - call to the function should return one line of input as a string. - Alternately, \var{readline} may be a callable object that signals - completion by raising \exception{StopIteration}. - \versionchanged[Added \exception{StopIteration} support]{2.5} - - The second parameter, \var{tokeneater}, must also be a callable - object. It is called once for each token, with five arguments, - corresponding to the tuples generated by \function{generate_tokens()}. -\end{funcdesc} - - -All constants from the \refmodule{token} module are also exported from -\module{tokenize}, as are two additional token type values that might be -passed to the \var{tokeneater} function by \function{tokenize()}: - -\begin{datadesc}{COMMENT} - Token value used to indicate a comment. -\end{datadesc} -\begin{datadesc}{NL} - Token value used to indicate a non-terminating newline. The NEWLINE - token indicates the end of a logical line of Python code; NL tokens - are generated when a logical line of code is continued over multiple - physical lines. -\end{datadesc} - -Another function is provided to reverse the tokenization process. -This is useful for creating tools that tokenize a script, modify -the token stream, and write back the modified script. - -\begin{funcdesc}{untokenize}{iterable} - Converts tokens back into Python source code. The \var{iterable} - must return sequences with at least two elements, the token type and - the token string. Any additional sequence elements are ignored. - - The reconstructed script is returned as a single string. The - result is guaranteed to tokenize back to match the input so that - the conversion is lossless and round-trips are assured. The - guarantee applies only to the token type and token string as - the spacing between tokens (column positions) may change. - \versionadded{2.5} -\end{funcdesc} - -Example of a script re-writer that transforms float literals into -Decimal objects: -\begin{verbatim} -def decistmt(s): - """Substitute Decimals for floats in a string of statements. - - >>> from decimal import Decimal - >>> s = 'print +21.3e-5*-.1234/81.7' - >>> decistmt(s) - "print +Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7')" - - >>> exec(s) - -3.21716034272e-007 - >>> exec(decistmt(s)) - -3.217160342717258261933904529E-7 - - """ - result = [] - g = generate_tokens(StringIO(s).readline) # tokenize the string - for toknum, tokval, _, _, _ in g: - if toknum == NUMBER and '.' in tokval: # replace NUMBER tokens - result.extend([ - (NAME, 'Decimal'), - (OP, '('), - (STRING, repr(tokval)), - (OP, ')') - ]) - else: - result.append((toknum, tokval)) - return untokenize(result) -\end{verbatim} diff --git a/Doc/lib/libtrace.tex b/Doc/lib/libtrace.tex deleted file mode 100644 index 2465aac..0000000 --- a/Doc/lib/libtrace.tex +++ /dev/null @@ -1,125 +0,0 @@ -\section{\module{trace} --- - Trace or track Python statement execution} - -\declaremodule{standard}{trace} -\modulesynopsis{Trace or track Python statement execution.} - -The \module{trace} module allows you to trace program execution, generate -annotated statement coverage listings, print caller/callee relationships and -list functions executed during a program run. It can be used in another -program or from the command line. - -\subsection{Command Line Usage\label{trace-cli}} - -The \module{trace} module can be invoked from the command line. It can be -as simple as - -\begin{verbatim} -python -m trace --count somefile.py ... -\end{verbatim} - -The above will generate annotated listings of all Python modules imported -during the execution of \file{somefile.py}. - -The following command-line arguments are supported: - -\begin{description} -\item[\longprogramopt{trace}, \programopt{-t}] -Display lines as they are executed. - -\item[\longprogramopt{count}, \programopt{-c}] -Produce a set of annotated listing files upon program -completion that shows how many times each statement was executed. - -\item[\longprogramopt{report}, \programopt{-r}] -Produce an annotated list from an earlier program run that -used the \longprogramopt{count} and \longprogramopt{file} arguments. - -\item[\longprogramopt{no-report}, \programopt{-R}] -Do not generate annotated listings. This is useful if you intend to make -several runs with \longprogramopt{count} then produce a single set -of annotated listings at the end. - -\item[\longprogramopt{listfuncs}, \programopt{-l}] -List the functions executed by running the program. - -\item[\longprogramopt{trackcalls}, \programopt{-T}] -Generate calling relationships exposed by running the program. - -\item[\longprogramopt{file}, \programopt{-f}] -Name a file containing (or to contain) counts. - -\item[\longprogramopt{coverdir}, \programopt{-C}] -Name a directory in which to save annotated listing files. - -\item[\longprogramopt{missing}, \programopt{-m}] -When generating annotated listings, mark lines which -were not executed with `\code{>>>>>>}'. - -\item[\longprogramopt{summary}, \programopt{-s}] -When using \longprogramopt{count} or \longprogramopt{report}, write a -brief summary to stdout for each file processed. - -\item[\longprogramopt{ignore-module}] -Ignore the named module and its submodules (if it is -a package). May be given multiple times. - -\item[\longprogramopt{ignore-dir}] -Ignore all modules and packages in the named directory -and subdirectories. May be given multiple times. -\end{description} - -\subsection{Programming Interface\label{trace-api}} - -\begin{classdesc}{Trace}{\optional{count=1\optional{, trace=1\optional{, - countfuncs=0\optional{, countcallers=0\optional{, - ignoremods=()\optional{, ignoredirs=()\optional{, - infile=None\optional{, outfile=None}}}}}}}}} -Create an object to trace execution of a single statement or expression. -All parameters are optional. \var{count} enables counting of line numbers. -\var{trace} enables line execution tracing. \var{countfuncs} enables -listing of the functions called during the run. \var{countcallers} enables -call relationship tracking. \var{ignoremods} is a list of modules or -packages to ignore. \var{ignoredirs} is a list of directories whose modules -or packages should be ignored. \var{infile} is the file from which to read -stored count information. \var{outfile} is a file in which to write updated -count information. -\end{classdesc} - -\begin{methoddesc}[Trace]{run}{cmd} -Run \var{cmd} under control of the Trace object with the current tracing -parameters. -\end{methoddesc} - -\begin{methoddesc}[Trace]{runctx}{cmd\optional{, globals=None\optional{, - locals=None}}} -Run \var{cmd} under control of the Trace object with the current tracing -parameters in the defined global and local environments. If not defined, -\var{globals} and \var{locals} default to empty dictionaries. -\end{methoddesc} - -\begin{methoddesc}[Trace]{runfunc}{func, *args, **kwds} -Call \var{func} with the given arguments under control of the -\class{Trace} object with the current tracing parameters. -\end{methoddesc} - -This is a simple example showing the use of this module: - -\begin{verbatim} -import sys -import trace - -# create a Trace object, telling it what to ignore, and whether to -# do tracing or line-counting or both. -tracer = trace.Trace( - ignoredirs=[sys.prefix, sys.exec_prefix], - trace=0, - count=1) - -# run the new command using the given tracer -tracer.run('main()') - -# make a report, placing output in /tmp -r = tracer.results() -r.write_results(show_missing=True, coverdir="/tmp") -\end{verbatim} diff --git a/Doc/lib/libtraceback.tex b/Doc/lib/libtraceback.tex deleted file mode 100644 index a87b1ef..0000000 --- a/Doc/lib/libtraceback.tex +++ /dev/null @@ -1,152 +0,0 @@ -\section{\module{traceback} --- - Print or retrieve a stack traceback} - -\declaremodule{standard}{traceback} -\modulesynopsis{Print or retrieve a stack traceback.} - - -This module provides a standard interface to extract, format and print -stack traces of Python programs. It exactly mimics the behavior of -the Python interpreter when it prints a stack trace. This is useful -when you want to print stack traces under program control, such as in a -``wrapper'' around the interpreter. - -The module uses traceback objects --- this is the object type that is -stored in the \code{sys.last_traceback} variable and returned -as the third item from \function{sys.exc_info()}. -\obindex{traceback} - -The module defines the following functions: - -\begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}} -Print up to \var{limit} stack trace entries from \var{traceback}. If -\var{limit} is omitted or \code{None}, all entries are printed. -If \var{file} is omitted or \code{None}, the output goes to -\code{sys.stderr}; otherwise it should be an open file or file-like -object to receive the output. -\end{funcdesc} - -\begin{funcdesc}{print_exception}{type, value, traceback\optional{, - limit\optional{, file}}} -Print exception information and up to \var{limit} stack trace entries -from \var{traceback} to \var{file}. -This differs from \function{print_tb()} in the -following ways: (1) if \var{traceback} is not \code{None}, it prints a -header \samp{Traceback (most recent call last):}; (2) it prints the -exception \var{type} and \var{value} after the stack trace; (3) if -\var{type} is \exception{SyntaxError} and \var{value} has the -appropriate format, it prints the line where the syntax error occurred -with a caret indicating the approximate position of the error. -\end{funcdesc} - -\begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}} -This is a shorthand for \code{print_exception(*\function{sys.exc_info()}}. -\end{funcdesc} - -\begin{funcdesc}{format_exc}{\optional{limit}} -This is like \code{print_exc(\var{limit})} but returns a string -instead of printing to a file. -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{print_last}{\optional{limit\optional{, file}}} -This is a shorthand for \code{print_exception(sys.last_type, -sys.last_value, sys.last_traceback, \var{limit}, \var{file})}. -\end{funcdesc} - -\begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}} -This function prints a stack trace from its invocation point. The -optional \var{f} argument can be used to specify an alternate stack -frame to start. The optional \var{limit} and \var{file} arguments have the -same meaning as for \function{print_exception()}. -\end{funcdesc} - -\begin{funcdesc}{extract_tb}{traceback\optional{, limit}} -Return a list of up to \var{limit} ``pre-processed'' stack trace -entries extracted from the traceback object \var{traceback}. It is -useful for alternate formatting of stack traces. If \var{limit} is -omitted or \code{None}, all entries are extracted. A -``pre-processed'' stack trace entry is a quadruple (\var{filename}, -\var{line number}, \var{function name}, \var{text}) representing -the information that is usually printed for a stack trace. The -\var{text} is a string with leading and trailing whitespace -stripped; if the source is not available it is \code{None}. -\end{funcdesc} - -\begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}} -Extract the raw traceback from the current stack frame. The return -value has the same format as for \function{extract_tb()}. The -optional \var{f} and \var{limit} arguments have the same meaning as -for \function{print_stack()}. -\end{funcdesc} - -\begin{funcdesc}{format_list}{list} -Given a list of tuples as returned by \function{extract_tb()} or -\function{extract_stack()}, return a list of strings ready for -printing. Each string in the resulting list corresponds to the item -with the same index in the argument list. Each string ends in a -newline; the strings may contain internal newlines as well, for those -items whose source text line is not \code{None}. -\end{funcdesc} - -\begin{funcdesc}{format_exception_only}{type, value} -Format the exception part of a traceback. The arguments are the -exception type and value such as given by \code{sys.last_type} and -\code{sys.last_value}. The return value is a list of strings, each -ending in a newline. Normally, the list contains a single string; -however, for \exception{SyntaxError} exceptions, it contains several -lines that (when printed) display detailed information about where the -syntax error occurred. The message indicating which exception -occurred is the always last string in the list. -\end{funcdesc} - -\begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}} -Format a stack trace and the exception information. The arguments -have the same meaning as the corresponding arguments to -\function{print_exception()}. The return value is a list of strings, -each ending in a newline and some containing internal newlines. When -these lines are concatenated and printed, exactly the same text is -printed as does \function{print_exception()}. -\end{funcdesc} - -\begin{funcdesc}{format_tb}{tb\optional{, limit}} -A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}. -\end{funcdesc} - -\begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}} -A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}. -\end{funcdesc} - -\begin{funcdesc}{tb_lineno}{tb} -This function returns the current line number set in the traceback -object. This function was necessary because in versions of Python -prior to 2.3 when the \programopt{-O} flag was passed to Python the -\code{\var{tb}.tb_lineno} was not updated correctly. This function -has no use in versions past 2.3. -\end{funcdesc} - - -\subsection{Traceback Example \label{traceback-example}} - -This simple example implements a basic read-eval-print loop, similar -to (but less useful than) the standard Python interactive interpreter -loop. For a more complete implementation of the interpreter loop, -refer to the \refmodule{code} module. - -\begin{verbatim} -import sys, traceback - -def run_user_code(envdir): - source = raw_input(">>> ") - try: - exec(source, envdir) - except: - print "Exception in user code:" - print '-'*60 - traceback.print_exc(file=sys.stdout) - print '-'*60 - -envdir = {} -while 1: - run_user_code(envdir) -\end{verbatim} diff --git a/Doc/lib/libtty.tex b/Doc/lib/libtty.tex deleted file mode 100644 index d42771a..0000000 --- a/Doc/lib/libtty.tex +++ /dev/null @@ -1,34 +0,0 @@ -\section{\module{tty} --- - Terminal control functions} - -\declaremodule{standard}{tty} - \platform{Unix} -\moduleauthor{Steen Lumholt}{} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Utility functions that perform common terminal control - operations.} - -The \module{tty} module defines functions for putting the tty into -cbreak and raw modes. - -Because it requires the \refmodule{termios} module, it will work -only on \UNIX. - -The \module{tty} module defines the following functions: - -\begin{funcdesc}{setraw}{fd\optional{, when}} -Change the mode of the file descriptor \var{fd} to raw. If \var{when} -is omitted, it defaults to \constant{termios.TCSAFLUSH}, and is passed -to \function{termios.tcsetattr()}. -\end{funcdesc} - -\begin{funcdesc}{setcbreak}{fd\optional{, when}} -Change the mode of file descriptor \var{fd} to cbreak. If \var{when} -is omitted, it defaults to \constant{termios.TCSAFLUSH}, and is passed -to \function{termios.tcsetattr()}. -\end{funcdesc} - - -\begin{seealso} - \seemodule{termios}{Low-level terminal control interface.} -\end{seealso} diff --git a/Doc/lib/libturtle.tex b/Doc/lib/libturtle.tex deleted file mode 100644 index fa8f0dd..0000000 --- a/Doc/lib/libturtle.tex +++ /dev/null @@ -1,268 +0,0 @@ -\section{\module{turtle} --- - Turtle graphics for Tk} - -\declaremodule{standard}{turtle} - \platform{Tk} -\moduleauthor{Guido van Rossum}{guido@python.org} -\modulesynopsis{An environment for turtle graphics.} - -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} - - -The \module{turtle} module provides turtle graphics primitives, in both an -object-oriented and procedure-oriented ways. Because it uses \module{Tkinter} -for the underlying graphics, it needs a version of python installed with -Tk support. - -The procedural interface uses a pen and a canvas which are automagically -created when any of the functions are called. - -The \module{turtle} module defines the following functions: - -\begin{funcdesc}{degrees}{} -Set angle measurement units to degrees. -\end{funcdesc} - -\begin{funcdesc}{radians}{} -Set angle measurement units to radians. -\end{funcdesc} - -\begin{funcdesc}{setup}{**kwargs} -Sets the size and position of the main window. Keywords are: -\begin{itemize} - \item \code{width}: either a size in pixels or a fraction of the screen. - The default is 50\% of the screen. - \item \code{height}: either a size in pixels or a fraction of the screen. - The default is 50\% of the screen. - \item \code{startx}: starting position in pixels from the left edge - of the screen. \code{None} is the default value and - centers the window horizontally on screen. - \item \code{starty}: starting position in pixels from the top edge - of the screen. \code{None} is the default value and - centers the window vertically on screen. -\end{itemize} - - Examples: - -\begin{verbatim} -# Uses default geometry: 50% x 50% of screen, centered. -setup() - -# Sets window to 200x200 pixels, in upper left of screen -setup (width=200, height=200, startx=0, starty=0) - -# Sets window to 75% of screen by 50% of screen, and centers it. -setup(width=.75, height=0.5, startx=None, starty=None) -\end{verbatim} - -\end{funcdesc} - -\begin{funcdesc}{title}{title_str} -Set the window's title to \var{title}. -\end{funcdesc} - -\begin{funcdesc}{done}{} -Enters the Tk main loop. The window will continue to -be displayed until the user closes it or the process is killed. -\end{funcdesc} - -\begin{funcdesc}{reset}{} -Clear the screen, re-center the pen, and set variables to the default -values. -\end{funcdesc} - -\begin{funcdesc}{clear}{} -Clear the screen. -\end{funcdesc} - -\begin{funcdesc}{tracer}{flag} -Set tracing on/off (according to whether flag is true or not). Tracing -means line are drawn more slowly, with an animation of an arrow along the -line. -\end{funcdesc} - -\begin{funcdesc}{speed}{speed} -Set the speed of the turtle. Valid values for the parameter -\var{speed} are \code{'fastest'} (no delay), \code{'fast'}, -(delay 5ms), \code{'normal'} (delay 10ms), \code{'slow'} -(delay 15ms), and \code{'slowest'} (delay 20ms). -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{delay}{delay} -Set the speed of the turtle to \var{delay}, which is given -in ms. \versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{forward}{distance} -Go forward \var{distance} steps. -\end{funcdesc} - -\begin{funcdesc}{backward}{distance} -Go backward \var{distance} steps. -\end{funcdesc} - -\begin{funcdesc}{left}{angle} -Turn left \var{angle} units. Units are by default degrees, but can be -set via the \function{degrees()} and \function{radians()} functions. -\end{funcdesc} - -\begin{funcdesc}{right}{angle} -Turn right \var{angle} units. Units are by default degrees, but can be -set via the \function{degrees()} and \function{radians()} functions. -\end{funcdesc} - -\begin{funcdesc}{up}{} -Move the pen up --- stop drawing. -\end{funcdesc} - -\begin{funcdesc}{down}{} -Move the pen down --- draw when moving. -\end{funcdesc} - -\begin{funcdesc}{width}{width} -Set the line width to \var{width}. -\end{funcdesc} - -\begin{funcdesc}{color}{s} -\funclineni{color}{(r, g, b)} -\funclineni{color}{r, g, b} -Set the pen color. In the first form, the color is specified as a -Tk color specification as a string. The second form specifies the -color as a tuple of the RGB values, each in the range [0..1]. For the -third form, the color is specified giving the RGB values as three -separate parameters (each in the range [0..1]). -\end{funcdesc} - -\begin{funcdesc}{write}{text\optional{, move}} -Write \var{text} at the current pen position. If \var{move} is true, -the pen is moved to the bottom-right corner of the text. By default, -\var{move} is false. -\end{funcdesc} - -\begin{funcdesc}{fill}{flag} -The complete specifications are rather complex, but the recommended -usage is: call \code{fill(1)} before drawing a path you want to fill, -and call \code{fill(0)} when you finish to draw the path. -\end{funcdesc} - -\begin{funcdesc}{begin\_fill}{} -Switch turtle into filling mode; -Must eventually be followed by a corresponding end_fill() call. -Otherwise it will be ignored. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{end\_fill}{} -End filling mode, and fill the shape; equivalent to \code{fill(0)}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{circle}{radius\optional{, extent}} -Draw a circle with radius \var{radius} whose center-point is -\var{radius} units left of the turtle. -\var{extent} determines which part of a circle is drawn: if -not given it defaults to a full circle. - -If \var{extent} is not a full circle, one endpoint of the arc is the -current pen position. The arc is drawn in a counter clockwise -direction if \var{radius} is positive, otherwise in a clockwise -direction. In the process, the direction of the turtle is changed -by the amount of the \var{extent}. -\end{funcdesc} - -\begin{funcdesc}{goto}{x, y} -\funclineni{goto}{(x, y)} -Go to co-ordinates \var{x}, \var{y}. The co-ordinates may be -specified either as two separate arguments or as a 2-tuple. -\end{funcdesc} - -\begin{funcdesc}{towards}{x, y} -Return the angle of the line from the turtle's position -to the point \var{x}, \var{y}. The co-ordinates may be -specified either as two separate arguments, as a 2-tuple, -or as another pen object. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{heading}{} -Return the current orientation of the turtle. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{setheading}{angle} -Set the orientation of the turtle to \var{angle}. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{position}{} -Return the current location of the turtle as an \code{(x,y)} pair. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{setx}{x} -Set the x coordinate of the turtle to \var{x}. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{sety}{y} -Set the y coordinate of the turtle to \var{y}. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{window\_width}{} -Return the width of the canvas window. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{window\_height}{} -Return the height of the canvas window. -\versionadded{2.3} -\end{funcdesc} - -This module also does \code{from math import *}, so see the -documentation for the \refmodule{math} module for additional constants -and functions useful for turtle graphics. - -\begin{funcdesc}{demo}{} -Exercise the module a bit. -\end{funcdesc} - -\begin{excdesc}{Error} -Exception raised on any error caught by this module. -\end{excdesc} - -For examples, see the code of the \function{demo()} function. - -This module defines the following classes: - -\begin{classdesc}{Pen}{} -Define a pen. All above functions can be called as a methods on the given -pen. The constructor automatically creates a canvas do be drawn on. -\end{classdesc} - -\begin{classdesc}{Turtle}{} -Define a pen. This is essentially a synonym for \code{Pen()}; -\class{Turtle} is an empty subclass of \class{Pen}. -\end{classdesc} - -\begin{classdesc}{RawPen}{canvas} -Define a pen which draws on a canvas \var{canvas}. This is useful if -you want to use the module to create graphics in a ``real'' program. -\end{classdesc} - -\subsection{Turtle, Pen and RawPen Objects \label{pen-rawpen-objects}} - -Most of the global functions available in the module are also -available as methods of the \class{Turtle}, \class{Pen} and -\class{RawPen} classes, affecting only the state of the given pen. - -The only method which is more powerful as a method is -\function{degrees()}, which takes an optional argument letting -you specify the number of units corresponding to a full circle: - -\begin{methoddesc}[Turtle]{degrees}{\optional{fullcircle}} -\var{fullcircle} is by default 360. This can cause the pen to have any -angular units whatever: give \var{fullcircle} 2*$\pi$ for radians, or -400 for gradians. -\end{methoddesc} diff --git a/Doc/lib/libtypes.tex b/Doc/lib/libtypes.tex deleted file mode 100644 index 2b143b9..0000000 --- a/Doc/lib/libtypes.tex +++ /dev/null @@ -1,211 +0,0 @@ -\section{\module{types} --- - Names for built-in types} - -\declaremodule{standard}{types} -\modulesynopsis{Names for built-in types.} - - -This module defines names for some object types that are used by -the standard Python interpreter, but not for the types defined by various -extension modules. Also, it does not include some of the types that -arise during processing such as the \code{listiterator} type. -It is safe to use \samp{from types import *} --- -the module does not export any names besides the ones listed here. -New names exported by future versions of this module will all end in -\samp{Type}. - -Typical use is for functions that do different things depending on -their argument types, like the following: - -\begin{verbatim} -from types import * -def delete(mylist, item): - if type(item) is IntType: - del mylist[item] - else: - mylist.remove(item) -\end{verbatim} - -Starting in Python 2.2, built-in factory functions such as -\function{int()} and \function{str()} are also names for the -corresponding types. This is now the preferred way to access -the type instead of using the \module{types} module. Accordingly, -the example above should be written as follows: - -\begin{verbatim} -def delete(mylist, item): - if isinstance(item, int): - del mylist[item] - else: - mylist.remove(item) -\end{verbatim} - -The module defines the following names: - -\begin{datadesc}{NoneType} -The type of \code{None}. -\end{datadesc} - -\begin{datadesc}{TypeType} -The type of type objects (such as returned by -\function{type()}\bifuncindex{type}). -\end{datadesc} - -\begin{datadesc}{BooleanType} -The type of the \class{bool} values \code{True} and \code{False}; this -is an alias of the built-in \function{bool()} function. -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{IntType} -The type of integers (e.g. \code{1}). -\end{datadesc} - -\begin{datadesc}{LongType} -The type of long integers (e.g. \code{1L}). -\end{datadesc} - -\begin{datadesc}{FloatType} -The type of floating point numbers (e.g. \code{1.0}). -\end{datadesc} - -\begin{datadesc}{ComplexType} -The type of complex numbers (e.g. \code{1.0j}). This is not defined -if Python was built without complex number support. -\end{datadesc} - -\begin{datadesc}{StringType} -The type of character strings (e.g. \code{'Spam'}). -\end{datadesc} - -\begin{datadesc}{UnicodeType} -The type of Unicode character strings (e.g. \code{u'Spam'}). This is -not defined if Python was built without Unicode support. -\end{datadesc} - -\begin{datadesc}{TupleType} -The type of tuples (e.g. \code{(1, 2, 3, 'Spam')}). -\end{datadesc} - -\begin{datadesc}{ListType} -The type of lists (e.g. \code{[0, 1, 2, 3]}). -\end{datadesc} - -\begin{datadesc}{DictType} -The type of dictionaries (e.g. \code{\{'Bacon': 1, 'Ham': 0\}}). -\end{datadesc} - -\begin{datadesc}{DictionaryType} -An alternate name for \code{DictType}. -\end{datadesc} - -\begin{datadesc}{FunctionType} -The type of user-defined functions and lambdas. -\end{datadesc} - -\begin{datadesc}{LambdaType} -An alternate name for \code{FunctionType}. -\end{datadesc} - -\begin{datadesc}{GeneratorType} -The type of generator-iterator objects, produced by calling a -generator function. -\versionadded{2.2} -\end{datadesc} - -\begin{datadesc}{CodeType} -The type for code objects such as returned by -\function{compile()}\bifuncindex{compile}. -\end{datadesc} - -\begin{datadesc}{ClassType} -The type of user-defined classes. -\end{datadesc} - -\begin{datadesc}{MethodType} -The type of methods of user-defined class instances. -\end{datadesc} - -\begin{datadesc}{UnboundMethodType} -An alternate name for \code{MethodType}. -\end{datadesc} - -\begin{datadesc}{BuiltinFunctionType} -The type of built-in functions like \function{len()} or -\function{sys.exit()}. -\end{datadesc} - -\begin{datadesc}{BuiltinMethodType} -An alternate name for \code{BuiltinFunction}. -\end{datadesc} - -\begin{datadesc}{ModuleType} -The type of modules. -\end{datadesc} - -\begin{datadesc}{FileType} -The type of open file objects such as \code{sys.stdout}. -\end{datadesc} - -\begin{datadesc}{RangeType} -The type of range objects returned by -\function{range()}\bifuncindex{range}. -\end{datadesc} - -\begin{datadesc}{SliceType} -The type of objects returned by -\function{slice()}\bifuncindex{slice}. -\end{datadesc} - -\begin{datadesc}{EllipsisType} -The type of \code{Ellipsis}. -\end{datadesc} - -\begin{datadesc}{TracebackType} -The type of traceback objects such as found in -\code{sys.exc_info()[2]}. -\end{datadesc} - -\begin{datadesc}{FrameType} -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} - -\begin{datadesc}{DictProxyType} -The type of dict proxies, such as \code{TypeType.__dict__}. -\end{datadesc} - -\begin{datadesc}{NotImplementedType} -The type of \code{NotImplemented} -\end{datadesc} - -\begin{datadesc}{GetSetDescriptorType} -The type of objects defined in extension modules with \code{PyGetSetDef}, such -as \code{FrameType.f_locals} or \code{array.array.typecode}. This constant is -not defined in implementations of Python that do not have such extension -types, so for portable code use \code{hasattr(types, 'GetSetDescriptorType')}. -\versionadded{2.5} -\end{datadesc} - -\begin{datadesc}{MemberDescriptorType} -The type of objects defined in extension modules with \code{PyMemberDef}, such -as \code {datetime.timedelta.days}. This constant is not defined in -implementations of Python that do not have such extension types, so for -portable code use \code{hasattr(types, 'MemberDescriptorType')}. -\versionadded{2.5} -\end{datadesc} - -\begin{datadesc}{StringTypes} -A sequence containing \code{StringType} and \code{UnicodeType} used to -facilitate easier checking for any string object. Using this is more -portable than using a sequence of the two string types constructed -elsewhere since it only contains \code{UnicodeType} if it has been -built in the running version of Python. For example: -\code{isinstance(s, types.StringTypes)}. -\versionadded{2.2} -\end{datadesc} diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex deleted file mode 100644 index 6f51eee..0000000 --- a/Doc/lib/libundoc.tex +++ /dev/null @@ -1,82 +0,0 @@ -\chapter{Undocumented Modules \label{undoc}} - -Here's a quick listing of modules that are currently undocumented, but -that should be documented. Feel free to contribute documentation for -them! (Send via email to \email{docs@python.org}.) - -The idea and original contents for this chapter were taken -from a posting by Fredrik Lundh; the specific contents of this chapter -have been substantially revised. - - -\section{Frameworks} - -Frameworks tend to be harder to document, but are well worth the -effort spent. - -\begin{description} -\item None at this time. -\end{description} - - -\section{Miscellaneous useful utilities} - -Some of these are very old and/or not very robust; marked with ``hmm.'' - -\begin{description} -\item[\module{bdb}] ---- A generic Python debugger base class (used by pdb). - -\item[\module{ihooks}] ---- Import hook support (for \refmodule{rexec}; may become obsolete). -\end{description} - - - -\section{Platform specific modules} - -These modules are used to implement the \refmodule{os.path} module, -and are not documented beyond this mention. There's little need to -document these. - -\begin{description} -\item[\module{ntpath}] ---- Implementation of \module{os.path} on Win32, Win64, WinCE, and - OS/2 platforms. - -\item[\module{posixpath}] ---- Implementation of \module{os.path} on \POSIX. -\end{description} - - -\section{Multimedia} - -\begin{description} -\item[\module{sunaudio}] ---- Interpret Sun audio headers (may become obsolete or a tool/demo). -\end{description} - - -\section{Obsolete \label{obsolete-modules}} - -These modules are not normally available for import; additional work -must be done to make them available. - -%%% lib-old is empty as of Python 2.5 -% 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}. - -These 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. - -% XXX need Windows instructions! - -\begin{description} -\item ---- This section should be empty for Python 3.0. -\end{description} diff --git a/Doc/lib/libunicodedata.tex b/Doc/lib/libunicodedata.tex deleted file mode 100644 index 435466a..0000000 --- a/Doc/lib/libunicodedata.tex +++ /dev/null @@ -1,160 +0,0 @@ -\section{\module{unicodedata} --- - Unicode Database} - -\declaremodule{standard}{unicodedata} -\modulesynopsis{Access the Unicode Database.} -\moduleauthor{Marc-Andre Lemburg}{mal@lemburg.com} -\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} - -\index{Unicode} -\index{character} -\indexii{Unicode}{database} - -This module provides access to the Unicode Character Database which -defines character properties for all Unicode characters. The data in -this database is based on the \file{UnicodeData.txt} file version -4.1.0 which is publicly available from \url{ftp://ftp.unicode.org/}. - -The module uses the same names and symbols as defined by the -UnicodeData File Format 4.1.0 (see -\url{http://www.unicode.org/Public/4.1.0/ucd/UCD.html}). It -defines the following functions: - -\begin{funcdesc}{lookup}{name} - Look up character by name. If a character with the - given name is found, return the corresponding Unicode - character. If not found, \exception{KeyError} is raised. -\end{funcdesc} - -\begin{funcdesc}{name}{unichr\optional{, default}} - Returns the name assigned to the Unicode character - \var{unichr} as a string. If no name is defined, - \var{default} is returned, or, if not given, - \exception{ValueError} is raised. -\end{funcdesc} - -\begin{funcdesc}{decimal}{unichr\optional{, default}} - Returns the decimal value assigned to the Unicode character - \var{unichr} as integer. If no such value is defined, - \var{default} is returned, or, if not given, - \exception{ValueError} is raised. -\end{funcdesc} - -\begin{funcdesc}{digit}{unichr\optional{, default}} - Returns the digit value assigned to the Unicode character - \var{unichr} as integer. If no such value is defined, - \var{default} is returned, or, if not given, - \exception{ValueError} is raised. -\end{funcdesc} - -\begin{funcdesc}{numeric}{unichr\optional{, default}} - Returns the numeric value assigned to the Unicode character - \var{unichr} as float. If no such value is defined, \var{default} is - returned, or, if not given, \exception{ValueError} is raised. -\end{funcdesc} - -\begin{funcdesc}{category}{unichr} - Returns the general category assigned to the Unicode character - \var{unichr} as string. -\end{funcdesc} - -\begin{funcdesc}{bidirectional}{unichr} - Returns the bidirectional category assigned to the Unicode character - \var{unichr} as string. If no such value is defined, an empty string - is returned. -\end{funcdesc} - -\begin{funcdesc}{combining}{unichr} - Returns the canonical combining class assigned to the Unicode - character \var{unichr} as integer. Returns \code{0} if no combining - class is defined. -\end{funcdesc} - -\begin{funcdesc}{east_asian_width}{unichr} - Returns the east asian width assigned to the Unicode character - \var{unichr} as string. -\versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{mirrored}{unichr} - Returns the mirrored property assigned to the Unicode character - \var{unichr} as integer. Returns \code{1} if the character has been - identified as a ``mirrored'' character in bidirectional text, - \code{0} otherwise. -\end{funcdesc} - -\begin{funcdesc}{decomposition}{unichr} - Returns the character decomposition mapping assigned to the Unicode - character \var{unichr} as string. An empty string is returned in case - no such mapping is defined. -\end{funcdesc} - -\begin{funcdesc}{normalize}{form, unistr} - -Return the normal form \var{form} for the Unicode string \var{unistr}. -Valid values for \var{form} are 'NFC', 'NFKC', 'NFD', and 'NFKD'. - -The Unicode standard defines various normalization forms of a Unicode -string, based on the definition of canonical equivalence and -compatibility equivalence. In Unicode, several characters can be -expressed in various way. For example, the character U+00C7 (LATIN -CAPITAL LETTER C WITH CEDILLA) can also be expressed as the sequence -U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA). - -For each character, there are two normal forms: normal form C and -normal form D. Normal form D (NFD) is also known as canonical -decomposition, and translates each character into its decomposed form. -Normal form C (NFC) first applies a canonical decomposition, then -composes pre-combined characters again. - -In addition to these two forms, there are two additional normal forms -based on compatibility equivalence. In Unicode, certain characters are -supported which normally would be unified with other characters. For -example, U+2160 (ROMAN NUMERAL ONE) is really the same thing as U+0049 -(LATIN CAPITAL LETTER I). However, it is supported in Unicode for -compatibility with existing character sets (e.g. gb2312). - -The normal form KD (NFKD) will apply the compatibility decomposition, -i.e. replace all compatibility characters with their equivalents. The -normal form KC (NFKC) first applies the compatibility decomposition, -followed by the canonical composition. - -\versionadded{2.3} -\end{funcdesc} - -In addition, the module exposes the following constant: - -\begin{datadesc}{unidata_version} -The version of the Unicode database used in this module. - -\versionadded{2.3} -\end{datadesc} - -\begin{datadesc}{ucd_3_2_0} -This is an object that has the same methods as the entire -module, but uses the Unicode database version 3.2 instead, -for applications that require this specific version of -the Unicode database (such as IDNA). - -\versionadded{2.5} -\end{datadesc} - -Examples: - -\begin{verbatim} ->>> unicodedata.lookup('LEFT CURLY BRACKET') -u'{' ->>> unicodedata.name(u'/') -'SOLIDUS' ->>> unicodedata.decimal(u'9') -9 ->>> unicodedata.decimal(u'a') -Traceback (most recent call last): - File "<stdin>", line 1, in ? -ValueError: not a decimal ->>> unicodedata.category(u'A') # 'L'etter, 'u'ppercase -'Lu' ->>> unicodedata.bidirectional(u'\u0660') # 'A'rabic, 'N'umber -'AN' -\end{verbatim} diff --git a/Doc/lib/libunittest.tex b/Doc/lib/libunittest.tex deleted file mode 100644 index fa198c7..0000000 --- a/Doc/lib/libunittest.tex +++ /dev/null @@ -1,978 +0,0 @@ -\section{\module{unittest} --- - Unit testing framework} - -\declaremodule{standard}{unittest} -\modulesynopsis{Unit testing framework for Python.} -\moduleauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com} -\sectionauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\sectionauthor{Raymond Hettinger}{python@rcn.com} - -\versionadded{2.1} - -The Python unit testing framework, sometimes referred to as ``PyUnit,'' is -a Python language version of JUnit, by Kent Beck and Erich Gamma. -JUnit is, in turn, a Java version of Kent's Smalltalk testing -framework. Each is the de facto standard unit testing framework for -its respective language. - -\module{unittest} supports test automation, sharing of setup and shutdown -code for tests, aggregation of tests into collections, and independence of -the tests from the reporting framework. The \module{unittest} module -provides classes that make it easy to support these qualities for a -set of tests. - -To achieve this, \module{unittest} supports some important concepts: - -\begin{definitions} -\term{test fixture} -A \dfn{test fixture} represents the preparation needed to perform one -or more tests, and any associate cleanup actions. This may involve, -for example, creating temporary or proxy databases, directories, or -starting a server process. - -\term{test case} -A \dfn{test case} is the smallest unit of testing. It checks for a -specific response to a particular set of inputs. \module{unittest} -provides a base class, \class{TestCase}, which may be used to create -new test cases. - -\term{test suite} -A \dfn{test suite} is a collection of test cases, test suites, or -both. It is used to aggregate tests that should be executed -together. - -\term{test runner} -A \dfn{test runner} is a component which orchestrates the execution of -tests and provides the outcome to the user. The runner may use a -graphical interface, a textual interface, or return a special value to -indicate the results of executing the tests. -\end{definitions} - - -The test case and test fixture concepts are supported through the -\class{TestCase} and \class{FunctionTestCase} classes; the former -should be used when creating new tests, and the latter can be used when -integrating existing test code with a \module{unittest}-driven framework. -When building test fixtures using \class{TestCase}, the \method{setUp()} -and \method{tearDown()} methods can be overridden to provide -initialization and cleanup for the fixture. With -\class{FunctionTestCase}, existing functions can be passed to the -constructor for these purposes. When the test is run, the -fixture initialization is run first; if it succeeds, the cleanup -method is run after the test has been executed, regardless of the -outcome of the test. Each instance of the \class{TestCase} will only -be used to run a single test method, so a new fixture is created for -each test. - -Test suites are implemented by the \class{TestSuite} class. This -class allows individual tests and test suites to be aggregated; when -the suite is executed, all tests added directly to the suite and in -``child'' test suites are run. - -A test runner is an object that provides a single method, -\method{run()}, which accepts a \class{TestCase} or \class{TestSuite} -object as a parameter, and returns a result object. The class -\class{TestResult} is provided for use as the result object. -\module{unittest} provides the \class{TextTestRunner} as an example -test runner which reports test results on the standard error stream by -default. Alternate runners can be implemented for other environments -(such as graphical environments) without any need to derive from a -specific class. - - -\begin{seealso} - \seemodule{doctest}{Another test-support module with a very - different flavor.} - \seetitle[http://www.XProgramming.com/testfram.htm]{Simple Smalltalk - Testing: With Patterns}{Kent Beck's original paper on - testing frameworks using the pattern shared by - \module{unittest}.} -\end{seealso} - - -\subsection{Basic example \label{unittest-minimal-example}} - -The \module{unittest} module provides a rich set of tools for -constructing and running tests. This section demonstrates that a -small subset of the tools suffice to meet the needs of most users. - -Here is a short script to test three functions from the -\refmodule{random} module: - -\begin{verbatim} -import random -import unittest - -class TestSequenceFunctions(unittest.TestCase): - - def setUp(self): - self.seq = range(10) - - def testshuffle(self): - # make sure the shuffled sequence does not lose any elements - random.shuffle(self.seq) - self.seq.sort() - self.assertEqual(self.seq, range(10)) - - def testchoice(self): - element = random.choice(self.seq) - self.assert_(element in self.seq) - - def testsample(self): - self.assertRaises(ValueError, random.sample, self.seq, 20) - for element in random.sample(self.seq, 5): - self.assert_(element in self.seq) - -if __name__ == '__main__': - unittest.main() -\end{verbatim} - -A testcase is created by subclassing \class{unittest.TestCase}. -The three individual tests are defined with methods whose names start with -the letters \samp{test}. This naming convention informs the test runner -about which methods represent tests. - -The crux of each test is a call to \method{assertEqual()} to -check for an expected result; \method{assert_()} to verify a condition; -or \method{assertRaises()} to verify that an expected exception gets -raised. These methods are used instead of the \keyword{assert} statement -so the test runner can accumulate all test results and produce a report. - -When a \method{setUp()} method is defined, the test runner will run that -method prior to each test. Likewise, if a \method{tearDown()} method is -defined, the test runner will invoke that method after each test. In the -example, \method{setUp()} was used to create a fresh sequence for each test. - -The final block shows a simple way to run the tests. -\function{unittest.main()} provides a command line interface to the -test script. When run from the command line, the above script -produces an output that looks like this: - -\begin{verbatim} -... ----------------------------------------------------------------------- -Ran 3 tests in 0.000s - -OK -\end{verbatim} - -Instead of \function{unittest.main()}, there are other ways to run the tests -with a finer level of control, less terse output, and no requirement to be -run from the command line. For example, the last two lines may be replaced -with: - -\begin{verbatim} -suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions) -unittest.TextTestRunner(verbosity=2).run(suite) -\end{verbatim} - -Running the revised script from the interpreter or another script -produces the following output: - -\begin{verbatim} -testchoice (__main__.TestSequenceFunctions) ... ok -testsample (__main__.TestSequenceFunctions) ... ok -testshuffle (__main__.TestSequenceFunctions) ... ok - ----------------------------------------------------------------------- -Ran 3 tests in 0.110s - -OK -\end{verbatim} - -The above examples show the most commonly used \module{unittest} features -which are sufficient to meet many everyday testing needs. The remainder -of the documentation explores the full feature set from first principles. - - -\subsection{Organizing test code - \label{organizing-tests}} - -The basic building blocks of unit testing are \dfn{test cases} --- -single scenarios that must be set up and checked for correctness. In -\module{unittest}, test cases are represented by instances of -\module{unittest}'s \class{TestCase} class. To make -your own test cases you must write subclasses of \class{TestCase}, or -use \class{FunctionTestCase}. - -An instance of a \class{TestCase}-derived class is an object that can -completely run a single test method, together with optional set-up -and tidy-up code. - -The testing code of a \class{TestCase} instance should be entirely -self contained, such that it can be run either in isolation or in -arbitrary combination with any number of other test cases. - -The simplest \class{TestCase} subclass will simply override the -\method{runTest()} method in order to perform specific testing code: - -\begin{verbatim} -import unittest - -class DefaultWidgetSizeTestCase(unittest.TestCase): - def runTest(self): - widget = Widget('The widget') - self.assertEqual(widget.size(), (50, 50), 'incorrect default size') -\end{verbatim} - -Note that in order to test something, we use the one of the -\method{assert*()} or \method{fail*()} methods provided by the -\class{TestCase} base class. If the test fails, an exception will be -raised, and \module{unittest} will identify the test case as a -\dfn{failure}. Any other exceptions will be treated as \dfn{errors}. -This helps you identify where the problem is: \dfn{failures} are caused by -incorrect results - a 5 where you expected a 6. \dfn{Errors} are caused by -incorrect code - e.g., a \exception{TypeError} caused by an incorrect -function call. - -The way to run a test case will be described later. For now, note -that to construct an instance of such a test case, we call its -constructor without arguments: - -\begin{verbatim} -testCase = DefaultWidgetSizeTestCase() -\end{verbatim} - -Now, such test cases can be numerous, and their set-up can be -repetitive. In the above case, constructing a \class{Widget} in each of -100 Widget test case subclasses would mean unsightly duplication. - -Luckily, we can factor out such set-up code by implementing a method -called \method{setUp()}, which the testing framework will -automatically call for us when we run the test: - -\begin{verbatim} -import unittest - -class SimpleWidgetTestCase(unittest.TestCase): - def setUp(self): - self.widget = Widget('The widget') - -class DefaultWidgetSizeTestCase(SimpleWidgetTestCase): - def runTest(self): - self.failUnless(self.widget.size() == (50,50), - 'incorrect default size') - -class WidgetResizeTestCase(SimpleWidgetTestCase): - def runTest(self): - self.widget.resize(100,150) - self.failUnless(self.widget.size() == (100,150), - 'wrong size after resize') -\end{verbatim} - -If the \method{setUp()} method raises an exception while the test is -running, the framework will consider the test to have suffered an -error, and the \method{runTest()} method will not be executed. - -Similarly, we can provide a \method{tearDown()} method that tidies up -after the \method{runTest()} method has been run: - -\begin{verbatim} -import unittest - -class SimpleWidgetTestCase(unittest.TestCase): - def setUp(self): - self.widget = Widget('The widget') - - def tearDown(self): - self.widget.dispose() - self.widget = None -\end{verbatim} - -If \method{setUp()} succeeded, the \method{tearDown()} method will be -run whether \method{runTest()} succeeded or not. - -Such a working environment for the testing code is called a -\dfn{fixture}. - -Often, many small test cases will use the same fixture. In this case, -we would end up subclassing \class{SimpleWidgetTestCase} into many -small one-method classes such as -\class{DefaultWidgetSizeTestCase}. This is time-consuming and - -discouraging, so in the same vein as JUnit, \module{unittest} provides -a simpler mechanism: - -\begin{verbatim} -import unittest - -class WidgetTestCase(unittest.TestCase): - def setUp(self): - self.widget = Widget('The widget') - - def tearDown(self): - self.widget.dispose() - self.widget = None - - def testDefaultSize(self): - self.failUnless(self.widget.size() == (50,50), - 'incorrect default size') - - def testResize(self): - self.widget.resize(100,150) - self.failUnless(self.widget.size() == (100,150), - 'wrong size after resize') -\end{verbatim} - -Here we have not provided a \method{runTest()} method, but have -instead provided two different test methods. Class instances will now -each run one of the \method{test*()} methods, with \code{self.widget} -created and destroyed separately for each instance. When creating an -instance we must specify the test method it is to run. We do this by -passing the method name in the constructor: - -\begin{verbatim} -defaultSizeTestCase = WidgetTestCase('testDefaultSize') -resizeTestCase = WidgetTestCase('testResize') -\end{verbatim} - -Test case instances are grouped together according to the features -they test. \module{unittest} provides a mechanism for this: the -\dfn{test suite}, represented by \module{unittest}'s \class{TestSuite} -class: - -\begin{verbatim} -widgetTestSuite = unittest.TestSuite() -widgetTestSuite.addTest(WidgetTestCase('testDefaultSize')) -widgetTestSuite.addTest(WidgetTestCase('testResize')) -\end{verbatim} - -For the ease of running tests, as we will see later, it is a good -idea to provide in each test module a callable object that returns a -pre-built test suite: - -\begin{verbatim} -def suite(): - suite = unittest.TestSuite() - suite.addTest(WidgetTestCase('testDefaultSize')) - suite.addTest(WidgetTestCase('testResize')) - return suite -\end{verbatim} - -or even: - -\begin{verbatim} -def suite(): - tests = ['testDefaultSize', 'testResize'] - - return unittest.TestSuite(map(WidgetTestCase, tests)) -\end{verbatim} - -Since it is a common pattern to create a \class{TestCase} subclass -with many similarly named test functions, \module{unittest} provides a -\class{TestLoader} class that can be used to automate the process of -creating a test suite and populating it with individual tests. -For example, - -\begin{verbatim} -suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase) -\end{verbatim} - -will create a test suite that will run -\code{WidgetTestCase.testDefaultSize()} and \code{WidgetTestCase.testResize}. -\class{TestLoader} uses the \code{'test'} method name prefix to identify -test methods automatically. - -Note that the order in which the various test cases will be run is -determined by sorting the test function names with the built-in -\function{cmp()} function. - -Often it is desirable to group suites of test cases together, so as to -run tests for the whole system at once. This is easy, since -\class{TestSuite} instances can be added to a \class{TestSuite} just -as \class{TestCase} instances can be added to a \class{TestSuite}: - -\begin{verbatim} -suite1 = module1.TheTestSuite() -suite2 = module2.TheTestSuite() -alltests = unittest.TestSuite([suite1, suite2]) -\end{verbatim} - -You can place the definitions of test cases and test suites in the -same modules as the code they are to test (such as \file{widget.py}), -but there are several advantages to placing the test code in a -separate module, such as \file{test_widget.py}: - -\begin{itemize} - \item The test module can be run standalone from the command line. - \item The test code can more easily be separated from shipped code. - \item There is less temptation to change test code to fit the code - it tests without a good reason. - \item Test code should be modified much less frequently than the - code it tests. - \item Tested code can be refactored more easily. - \item Tests for modules written in C must be in separate modules - anyway, so why not be consistent? - \item If the testing strategy changes, there is no need to change - the source code. -\end{itemize} - - -\subsection{Re-using old test code - \label{legacy-unit-tests}} - -Some users will find that they have existing test code that they would -like to run from \module{unittest}, without converting every old test -function to a \class{TestCase} subclass. - -For this reason, \module{unittest} provides a \class{FunctionTestCase} -class. This subclass of \class{TestCase} can be used to wrap an existing -test function. Set-up and tear-down functions can also be provided. - -Given the following test function: - -\begin{verbatim} -def testSomething(): - something = makeSomething() - assert something.name is not None - # ... -\end{verbatim} - -one can create an equivalent test case instance as follows: - -\begin{verbatim} -testcase = unittest.FunctionTestCase(testSomething) -\end{verbatim} - -If there are additional set-up and tear-down methods that should be -called as part of the test case's operation, they can also be provided -like so: - -\begin{verbatim} -testcase = unittest.FunctionTestCase(testSomething, - setUp=makeSomethingDB, - tearDown=deleteSomethingDB) -\end{verbatim} - -To make migrating existing test suites easier, \module{unittest} -supports tests raising \exception{AssertionError} to indicate test failure. -However, it is recommended that you use the explicit -\method{TestCase.fail*()} and \method{TestCase.assert*()} methods instead, -as future versions of \module{unittest} may treat \exception{AssertionError} -differently. - -\note{Even though \class{FunctionTestCase} can be used to quickly convert -an existing test base over to a \module{unittest}-based system, this -approach is not recommended. Taking the time to set up proper -\class{TestCase} subclasses will make future test refactorings infinitely -easier.} - - - -\subsection{Classes and functions - \label{unittest-contents}} - -\begin{classdesc}{TestCase}{\optional{methodName}} - Instances of the \class{TestCase} class represent the smallest - testable units in the \module{unittest} universe. This class is - intended to be used as a base class, with specific tests being - implemented by concrete subclasses. This class implements the - interface needed by the test runner to allow it to drive the - test, and methods that the test code can use to check for and - report various kinds of failure. - - Each instance of \class{TestCase} will run a single test method: - the method named \var{methodName}. If you remember, we had an - earlier example that went something like this: - - \begin{verbatim} - def suite(): - suite = unittest.TestSuite() - suite.addTest(WidgetTestCase('testDefaultSize')) - suite.addTest(WidgetTestCase('testResize')) - return suite - \end{verbatim} - - Here, we create two instances of \class{WidgetTestCase}, each of - which runs a single test. - - \var{methodName} defaults to \code{'runTest'}. -\end{classdesc} - -\begin{classdesc}{FunctionTestCase}{testFunc\optional{, - setUp\optional{, tearDown\optional{, description}}}} - This class implements the portion of the \class{TestCase} interface - which allows the test runner to drive the test, but does not provide - the methods which test code can use to check and report errors. - This is used to create test cases using legacy test code, allowing - it to be integrated into a \refmodule{unittest}-based test - framework. -\end{classdesc} - -\begin{classdesc}{TestSuite}{\optional{tests}} - This class represents an aggregation of individual tests cases and - test suites. The class presents the interface needed by the test - runner to allow it to be run as any other test case. Running a - \class{TestSuite} instance is the same as iterating over the suite, - running each test individually. - - If \var{tests} is given, it must be an iterable of individual test cases or - other test suites that will be used to build the suite initially. - Additional methods are provided to add test cases and suites to the - collection later on. -\end{classdesc} - -\begin{classdesc}{TestLoader}{} - This class is responsible for loading tests according to various - criteria and returning them wrapped in a \class{TestSuite}. - It can load all tests within a given module or \class{TestCase} - subclass. -\end{classdesc} - -\begin{classdesc}{TestResult}{} - This class is used to compile information about which tests have succeeded - and which have failed. -\end{classdesc} - -\begin{datadesc}{defaultTestLoader} - Instance of the \class{TestLoader} class intended to be shared. If no - customization of the \class{TestLoader} is needed, this instance can - be used instead of repeatedly creating new instances. -\end{datadesc} - -\begin{classdesc}{TextTestRunner}{\optional{stream\optional{, - descriptions\optional{, verbosity}}}} - A basic test runner implementation which prints results on standard - error. It has a few configurable parameters, but is essentially - very simple. Graphical applications which run test suites should - provide alternate implementations. -\end{classdesc} - -\begin{funcdesc}{main}{\optional{module\optional{, - defaultTest\optional{, argv\optional{, - testRunner\optional{, testLoader}}}}}} - A command-line program that runs a set of tests; this is primarily - for making test modules conveniently executable. The simplest use - for this function is to include the following line at the end of a - test script: - -\begin{verbatim} -if __name__ == '__main__': - unittest.main() -\end{verbatim} - - The \var{testRunner} argument can either be a test runner class or - an already created instance of it. -\end{funcdesc} - -In some cases, the existing tests may have been written using the -\refmodule{doctest} module. If so, that module provides a -\class{DocTestSuite} class that can automatically build -\class{unittest.TestSuite} instances from the existing -\module{doctest}-based tests. -\versionadded{2.3} - - -\subsection{TestCase Objects - \label{testcase-objects}} - -Each \class{TestCase} instance represents a single test, but each -concrete subclass may be used to define multiple tests --- the -concrete class represents a single test fixture. The fixture is -created and cleaned up for each test case. - -\class{TestCase} instances provide three groups of methods: one group -used to run the test, another used by the test implementation to -check conditions and report failures, and some inquiry methods -allowing information about the test itself to be gathered. - -Methods in the first group (running the test) are: - -\begin{methoddesc}[TestCase]{setUp}{} - Method called to prepare the test fixture. This is called - immediately before calling the test method; any exception raised by - this method will be considered an error rather than a test failure. - The default implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{tearDown}{} - Method called immediately after the test method has been called and - the result recorded. This is called even if the test method raised - an exception, so the implementation in subclasses may need to be - particularly careful about checking internal state. Any exception - raised by this method will be considered an error rather than a test - failure. This method will only be called if the \method{setUp()} - succeeds, regardless of the outcome of the test method. - The default implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{run}{\optional{result}} - Run the test, collecting the result into the test result object - passed as \var{result}. If \var{result} is omitted or \constant{None}, - a temporary result object is created (by calling the - \method{defaultTestCase()} method) and used; this result object is not - returned to \method{run()}'s caller. - - The same effect may be had by simply calling the \class{TestCase} - instance. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{debug}{} - Run the test without collecting the result. This allows exceptions - raised by the test to be propagated to the caller, and can be used - to support running tests under a debugger. -\end{methoddesc} - - -The test code can use any of the following methods to check for and -report failures. - -\begin{methoddesc}[TestCase]{assert_}{expr\optional{, msg}} -\methodline[TestCase]{failUnless}{expr\optional{, msg}} - Signal a test failure if \var{expr} is false; the explanation for - the error will be \var{msg} if given, otherwise it will be - \constant{None}. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{assertEqual}{first, second\optional{, msg}} -\methodline[TestCase]{failUnlessEqual}{first, second\optional{, msg}} - Test that \var{first} and \var{second} are equal. If the values do - not compare equal, the test will fail with the explanation given by - \var{msg}, or \constant{None}. Note that using \method{failUnlessEqual()} - improves upon doing the comparison as the first parameter to - \method{failUnless()}: the default value for \var{msg} can be - computed to include representations of both \var{first} and - \var{second}. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{assertNotEqual}{first, second\optional{, msg}} -\methodline[TestCase]{failIfEqual}{first, second\optional{, msg}} - Test that \var{first} and \var{second} are not equal. If the values - do compare equal, the test will fail with the explanation given by - \var{msg}, or \constant{None}. Note that using \method{failIfEqual()} - improves upon doing the comparison as the first parameter to - \method{failUnless()} is that the default value for \var{msg} can be - computed to include representations of both \var{first} and - \var{second}. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{assertAlmostEqual}{first, second\optional{, - places\optional{, msg}}} -\methodline[TestCase]{failUnlessAlmostEqual}{first, second\optional{, - places\optional{, msg}}} - Test that \var{first} and \var{second} are approximately equal - by computing the difference, rounding to the given number of \var{places}, - and comparing to zero. Note that comparing a given number of decimal places - is not the same as comparing a given number of significant digits. - If the values do not compare equal, the test will fail with the explanation - given by \var{msg}, or \constant{None}. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{assertNotAlmostEqual}{first, second\optional{, - places\optional{, msg}}} -\methodline[TestCase]{failIfAlmostEqual}{first, second\optional{, - places\optional{, msg}}} - Test that \var{first} and \var{second} are not approximately equal - by computing the difference, rounding to the given number of \var{places}, - and comparing to zero. Note that comparing a given number of decimal places - is not the same as comparing a given number of significant digits. - If the values do not compare equal, the test will fail with the explanation - given by \var{msg}, or \constant{None}. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{assertRaises}{exception, callable, \moreargs} -\methodline[TestCase]{failUnlessRaises}{exception, callable, \moreargs} - Test that an exception is raised when \var{callable} is called with - any positional or keyword arguments that are also passed to - \method{assertRaises()}. The test passes if \var{exception} is - raised, is an error if another exception is raised, or fails if no - exception is raised. To catch any of a group of exceptions, a tuple - containing the exception classes may be passed as \var{exception}. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{failIf}{expr\optional{, msg}} - The inverse of the \method{failUnless()} method is the - \method{failIf()} method. This signals a test failure if \var{expr} - is true, with \var{msg} or \constant{None} for the error message. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{fail}{\optional{msg}} - Signals a test failure unconditionally, with \var{msg} or - \constant{None} for the error message. -\end{methoddesc} - -\begin{memberdesc}[TestCase]{failureException} - This class attribute gives the exception raised by the - \method{test()} method. If a test framework needs to use a - specialized exception, possibly to carry additional information, it - must subclass this exception in order to ``play fair'' with the - framework. The initial value of this attribute is - \exception{AssertionError}. -\end{memberdesc} - - -Testing frameworks can use the following methods to collect -information on the test: - -\begin{methoddesc}[TestCase]{countTestCases}{} - Return the number of tests represented by this test object. For - \class{TestCase} instances, this will always be \code{1}. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{defaultTestResult}{} - Return an instance of the test result class that should be used - for this test case class (if no other result instance is provided - to the \method{run()} method). - - For \class{TestCase} instances, this will always be an instance of - \class{TestResult}; subclasses of \class{TestCase} should - override this as necessary. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{id}{} - Return a string identifying the specific test case. This is usually - the full name of the test method, including the module and class - name. -\end{methoddesc} - -\begin{methoddesc}[TestCase]{shortDescription}{} - Returns a one-line description of the test, or \constant{None} if no - description has been provided. The default implementation of this - method returns the first line of the test method's docstring, if - available, or \constant{None}. -\end{methoddesc} - - -\subsection{TestSuite Objects - \label{testsuite-objects}} - -\class{TestSuite} objects behave much like \class{TestCase} objects, -except they do not actually implement a test. Instead, they are used -to aggregate tests into groups of tests that should be run together. -Some additional methods are available to add tests to \class{TestSuite} -instances: - -\begin{methoddesc}[TestSuite]{addTest}{test} - Add a \class{TestCase} or \class{TestSuite} to the suite. -\end{methoddesc} - -\begin{methoddesc}[TestSuite]{addTests}{tests} - Add all the tests from an iterable of \class{TestCase} and - \class{TestSuite} instances to this test suite. - - This is equivalent to iterating over \var{tests}, calling - \method{addTest()} for each element. -\end{methoddesc} - -\class{TestSuite} shares the following methods with \class{TestCase}: - -\begin{methoddesc}[TestSuite]{run}{result} - Run the tests associated with this suite, collecting the result into - the test result object passed as \var{result}. Note that unlike - \method{TestCase.run()}, \method{TestSuite.run()} requires the - result object to be passed in. -\end{methoddesc} - -\begin{methoddesc}[TestSuite]{debug}{} - Run the tests associated with this suite without collecting the result. - This allows exceptions raised by the test to be propagated to the caller - and can be used to support running tests under a debugger. -\end{methoddesc} - -\begin{methoddesc}[TestSuite]{countTestCases}{} - Return the number of tests represented by this test object, including - all individual tests and sub-suites. -\end{methoddesc} - -In the typical usage of a \class{TestSuite} object, the \method{run()} -method is invoked by a \class{TestRunner} rather than by the end-user -test harness. - - -\subsection{TestResult Objects - \label{testresult-objects}} - -A \class{TestResult} object stores the results of a set of tests. The -\class{TestCase} and \class{TestSuite} classes ensure that results are -properly recorded; test authors do not need to worry about recording the -outcome of tests. - -Testing frameworks built on top of \refmodule{unittest} may want -access to the \class{TestResult} object generated by running a set of -tests for reporting purposes; a \class{TestResult} instance is -returned by the \method{TestRunner.run()} method for this purpose. - -\class{TestResult} instances have the following attributes that will -be of interest when inspecting the results of running a set of tests: - -\begin{memberdesc}[TestResult]{errors} - A list containing 2-tuples of \class{TestCase} instances and - strings holding formatted tracebacks. Each tuple represents a test which - raised an unexpected exception. - \versionchanged[Contains formatted tracebacks instead of - \function{sys.exc_info()} results]{2.2} -\end{memberdesc} - -\begin{memberdesc}[TestResult]{failures} - A list containing 2-tuples of \class{TestCase} instances and strings - holding formatted tracebacks. Each tuple represents a test where a failure - was explicitly signalled using the \method{TestCase.fail*()} or - \method{TestCase.assert*()} methods. - \versionchanged[Contains formatted tracebacks instead of - \function{sys.exc_info()} results]{2.2} -\end{memberdesc} - -\begin{memberdesc}[TestResult]{testsRun} - The total number of tests run so far. -\end{memberdesc} - -\begin{methoddesc}[TestResult]{wasSuccessful}{} - Returns \constant{True} if all tests run so far have passed, - otherwise returns \constant{False}. -\end{methoddesc} - -\begin{methoddesc}[TestResult]{stop}{} - This method can be called to signal that the set of tests being run - should be aborted by setting the \class{TestResult}'s \code{shouldStop} - attribute to \constant{True}. \class{TestRunner} objects should respect - this flag and return without running any additional tests. - - For example, this feature is used by the \class{TextTestRunner} class - to stop the test framework when the user signals an interrupt from - the keyboard. Interactive tools which provide \class{TestRunner} - implementations can use this in a similar manner. -\end{methoddesc} - - -The following methods of the \class{TestResult} class are used to -maintain the internal data structures, and may be extended in -subclasses to support additional reporting requirements. This is -particularly useful in building tools which support interactive -reporting while tests are being run. - -\begin{methoddesc}[TestResult]{startTest}{test} - Called when the test case \var{test} is about to be run. - - The default implementation simply increments the instance's - \code{testsRun} counter. -\end{methoddesc} - -\begin{methoddesc}[TestResult]{stopTest}{test} - Called after the test case \var{test} has been executed, regardless - of the outcome. - - The default implementation does nothing. -\end{methoddesc} - -\begin{methoddesc}[TestResult]{addError}{test, err} - Called when the test case \var{test} raises an unexpected exception - \var{err} is a tuple of the form returned by \function{sys.exc_info()}: - \code{(\var{type}, \var{value}, \var{traceback})}. - - The default implementation appends \code{(\var{test}, \var{err})} to - the instance's \code{errors} attribute. -\end{methoddesc} - -\begin{methoddesc}[TestResult]{addFailure}{test, err} - Called when the test case \var{test} signals a failure. - \var{err} is a tuple of the form returned by - \function{sys.exc_info()}: \code{(\var{type}, \var{value}, - \var{traceback})}. - - The default implementation appends \code{(\var{test}, \var{err})} to - the instance's \code{failures} attribute. -\end{methoddesc} - -\begin{methoddesc}[TestResult]{addSuccess}{test} - Called when the test case \var{test} succeeds. - - The default implementation does nothing. -\end{methoddesc} - - - -\subsection{TestLoader Objects - \label{testloader-objects}} - -The \class{TestLoader} class is used to create test suites from -classes and modules. Normally, there is no need to create an instance -of this class; the \refmodule{unittest} module provides an instance -that can be shared as \code{unittest.defaultTestLoader}. -Using a subclass or instance, however, allows customization of some -configurable properties. - -\class{TestLoader} objects have the following methods: - -\begin{methoddesc}[TestLoader]{loadTestsFromTestCase}{testCaseClass} - Return a suite of all tests cases contained in the - \class{TestCase}-derived \class{testCaseClass}. -\end{methoddesc} - -\begin{methoddesc}[TestLoader]{loadTestsFromModule}{module} - Return a suite of all tests cases contained in the given module. - This method searches \var{module} for classes derived from - \class{TestCase} and creates an instance of the class for each test - method defined for the class. - - \warning{While using a hierarchy of - \class{TestCase}-derived classes can be convenient in sharing - fixtures and helper functions, defining test methods on base classes - that are not intended to be instantiated directly does not play well - with this method. Doing so, however, can be useful when the - fixtures are different and defined in subclasses.} -\end{methoddesc} - -\begin{methoddesc}[TestLoader]{loadTestsFromName}{name\optional{, module}} - Return a suite of all tests cases given a string specifier. - - The specifier \var{name} is a ``dotted name'' that may resolve - either to a module, a test case class, a test method within a test - case class, a \class{TestSuite} instance, or a callable object which - returns a \class{TestCase} or \class{TestSuite} instance. These checks - are applied in the order listed here; that is, a method on a possible - test case class will be picked up as ``a test method within a test - case class'', rather than ``a callable object''. - - For example, if you have a module \module{SampleTests} containing a - \class{TestCase}-derived class \class{SampleTestCase} with three test - methods (\method{test_one()}, \method{test_two()}, and - \method{test_three()}), the specifier \code{'SampleTests.SampleTestCase'} - would cause this method to return a suite which will run all three test - methods. Using the specifier \code{'SampleTests.SampleTestCase.test_two'} - would cause it to return a test suite which will run only the - \method{test_two()} test method. The specifier can refer to modules - and packages which have not been imported; they will be imported as - a side-effect. - - The method optionally resolves \var{name} relative to the given - \var{module}. -\end{methoddesc} - -\begin{methoddesc}[TestLoader]{loadTestsFromNames}{names\optional{, module}} - Similar to \method{loadTestsFromName()}, but takes a sequence of - names rather than a single name. The return value is a test suite - which supports all the tests defined for each name. -\end{methoddesc} - -\begin{methoddesc}[TestLoader]{getTestCaseNames}{testCaseClass} - Return a sorted sequence of method names found within - \var{testCaseClass}; this should be a subclass of \class{TestCase}. -\end{methoddesc} - - -The following attributes of a \class{TestLoader} can be configured -either by subclassing or assignment on an instance: - -\begin{memberdesc}[TestLoader]{testMethodPrefix} - String giving the prefix of method names which will be interpreted - as test methods. The default value is \code{'test'}. - - This affects \method{getTestCaseNames()} and all the - \method{loadTestsFrom*()} methods. -\end{memberdesc} - -\begin{memberdesc}[TestLoader]{sortTestMethodsUsing} - Function to be used to compare method names when sorting them in - \method{getTestCaseNames()} and all the \method{loadTestsFrom*()} methods. - The default value is the built-in \function{cmp()} function; the attribute - can also be set to \constant{None} to disable the sort. -\end{memberdesc} - -\begin{memberdesc}[TestLoader]{suiteClass} - Callable object that constructs a test suite from a list of tests. - No methods on the resulting object are needed. The default value is - the \class{TestSuite} class. - - This affects all the \method{loadTestsFrom*()} methods. -\end{memberdesc} diff --git a/Doc/lib/libunix.tex b/Doc/lib/libunix.tex deleted file mode 100644 index 686df01..0000000 --- a/Doc/lib/libunix.tex +++ /dev/null @@ -1,8 +0,0 @@ -\chapter{Unix Specific Services} -\label{unix} - -The modules described in this chapter provide interfaces to features -that are unique to the \UNIX{} operating system, or in some cases to -some or many variants of it. Here's an overview: - -\localmoduletable diff --git a/Doc/lib/liburllib.tex b/Doc/lib/liburllib.tex deleted file mode 100644 index 77dfb8f..0000000 --- a/Doc/lib/liburllib.tex +++ /dev/null @@ -1,494 +0,0 @@ -\section{\module{urllib} --- - Open arbitrary resources by URL} - -\declaremodule{standard}{urllib} -\modulesynopsis{Open an arbitrary network resource by URL (requires sockets).} - -\index{WWW} -\index{World Wide Web} -\index{URL} - - -This module provides a high-level interface for fetching data across -the World Wide Web. In particular, the \function{urlopen()} function -is similar to the built-in function \function{open()}, but accepts -Universal Resource Locators (URLs) instead of filenames. Some -restrictions apply --- it can only open URLs for reading, and no seek -operations are available. - -It defines the following public functions: - -\begin{funcdesc}{urlopen}{url\optional{, data\optional{, proxies}}} -Open a network object denoted by a URL for reading. If the URL does -not have a scheme identifier, or if it has \file{file:} as its scheme -identifier, this opens a local file (without universal newlines); -otherwise it opens a socket to a server somewhere on the network. If -the connection cannot be made -the \exception{IOError} exception is raised. If all went well, a -file-like object is returned. This supports the following methods: -\method{read()}, \method{readline()}, \method{readlines()}, \method{fileno()}, -\method{close()}, \method{info()} and \method{geturl()}. It also has -proper support for the iterator protocol. -One caveat: the \method{read()} method, if the size argument is -omitted or negative, may not read until the end of the data stream; -there is no good way to determine that the entire stream from a socket -has been read in the general case. - -Except for the \method{info()} and \method{geturl()} methods, -these methods have the same interface as for -file objects --- see section \ref{bltin-file-objects} in this -manual. (It is not a built-in file object, however, so it can't be -used at those few places where a true built-in file object is -required.) - -The \method{info()} method returns an instance of the class -\class{mimetools.Message} containing meta-information associated -with the URL. When the method is HTTP, these headers are those -returned by the server at the head of the retrieved HTML page -(including Content-Length and Content-Type). When the method is FTP, -a Content-Length header will be present if (as is now usual) the -server passed back a file length in response to the FTP retrieval -request. A Content-Type header will be present if the MIME type can -be guessed. When the method is local-file, returned headers will include -a Date representing the file's last-modified time, a Content-Length -giving file size, and a Content-Type containing a guess at the file's -type. See also the description of the -\refmodule{mimetools}\refstmodindex{mimetools} module. - -The \method{geturl()} method returns the real URL of the page. In -some cases, the HTTP server redirects a client to another URL. The -\function{urlopen()} function handles this transparently, but in some -cases the caller needs to know which URL the client was redirected -to. The \method{geturl()} method can be used to get at this -redirected URL. - -If the \var{url} uses the \file{http:} scheme identifier, the optional -\var{data} argument may be given to specify a \code{POST} request -(normally the request type is \code{GET}). The \var{data} argument -must be in standard \mimetype{application/x-www-form-urlencoded} format; -see the \function{urlencode()} function below. - -The \function{urlopen()} function works transparently with proxies -which do not require authentication. In a \UNIX{} or Windows -environment, set the \envvar{http_proxy}, or \envvar{ftp_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 Windows environment, if no proxy environment variables are set, -proxy settings are obtained from the registry's Internet Settings -section. - -In a Macintosh environment, \function{urlopen()} will retrieve proxy -information from Internet\index{Internet Config} Config. - -Alternatively, the optional \var{proxies} argument may be used to -explicitly specify proxies. It must be a dictionary mapping scheme -names to proxy URLs, where an empty dictionary causes no proxies to be -used, and \code{None} (the default value) causes environmental proxy -settings to be used as discussed above. For example: - -\begin{verbatim} -# Use http://www.someproxy.com:3128 for http proxying -proxies = {'http': 'http://www.someproxy.com:3128'} -filehandle = urllib.urlopen(some_url, proxies=proxies) -# Don't use any proxies -filehandle = urllib.urlopen(some_url, proxies={}) -# Use proxies from environment - both versions are equivalent -filehandle = urllib.urlopen(some_url, proxies=None) -filehandle = urllib.urlopen(some_url) -\end{verbatim} - -The \function{urlopen()} function does not support explicit proxy -specification. If you need to override environmental proxy settings, -use \class{URLopener}, or a subclass such as \class{FancyURLopener}. - -Proxies which require authentication for use are not currently -supported; this is considered an implementation limitation. - -\versionchanged[Added the \var{proxies} support]{2.3} -\end{funcdesc} - -\begin{funcdesc}{urlretrieve}{url\optional{, filename\optional{, - reporthook\optional{, data}}}} -Copy a network object denoted by a URL to a local file, if necessary. -If the URL points to a local file, or a valid cached copy of the -object exists, the object is not copied. Return a tuple -\code{(\var{filename}, \var{headers})} where \var{filename} is the -local file name under which the object can be found, and \var{headers} -is whatever the \method{info()} method of the object returned by -\function{urlopen()} returned (for a remote object, possibly cached). -Exceptions are the same as for \function{urlopen()}. - -The second argument, if present, specifies the file location to copy -to (if absent, the location will be a tempfile with a generated name). -The third argument, if present, is a hook function that will be called -once on establishment of the network connection and once after each -block read thereafter. The hook will be passed three arguments; a -count of blocks transferred so far, a block size in bytes, and the -total size of the file. The third argument may be \code{-1} on older -FTP servers which do not return a file size in response to a retrieval -request. - -If the \var{url} uses the \file{http:} scheme identifier, the optional -\var{data} argument may be given to specify a \code{POST} request -(normally the request type is \code{GET}). The \var{data} argument -must in standard \mimetype{application/x-www-form-urlencoded} format; -see the \function{urlencode()} function below. - -\versionchanged[ -\function{urlretrieve()} will raise \exception{ContentTooShortError} -when it detects that the amount of data available -was less than the expected amount (which is the size reported by a -\var{Content-Length} header). This can occur, for example, when the -download is interrupted. - -The \var{Content-Length} is treated as a lower bound: if there's more data -to read, urlretrieve reads more data, but if less data is available, -it raises the exception. - -You can still retrieve the downloaded data in this case, it is stored -in the \member{content} attribute of the exception instance. - -If no \var{Content-Length} header was supplied, urlretrieve can -not check the size of the data it has downloaded, and just returns it. -In this case you just have to assume that the download was successful]{2.5} - -\end{funcdesc} - -\begin{datadesc}{_urlopener} -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 -an instance of that class to the -\code{urllib._urlopener} variable before calling the desired function. -For example, applications may want to specify a different -\mailheader{User-Agent} header than \class{URLopener} defines. This -can be accomplished with the following code: - -\begin{verbatim} -import urllib - -class AppURLopener(urllib.FancyURLopener): - version = "App/1.7" - -urllib._urlopener = AppURLopener() -\end{verbatim} -\end{datadesc} - -\begin{funcdesc}{urlcleanup}{} -Clear the cache that may have been built up by previous calls to -\function{urlretrieve()}. -\end{funcdesc} - -\begin{funcdesc}{quote}{string\optional{, safe}} -Replace special characters in \var{string} using the \samp{\%xx} escape. -Letters, digits, and the characters \character{_.-} are never quoted. -The optional \var{safe} parameter specifies additional characters -that should not be quoted --- its default value is \code{'/'}. - -Example: \code{quote('/\~{}connolly/')} yields \code{'/\%7econnolly/'}. -\end{funcdesc} - -\begin{funcdesc}{quote_plus}{string\optional{, safe}} -Like \function{quote()}, but also replaces spaces by plus signs, as -required for quoting HTML form values. Plus signs in the original -string are escaped unless they are included in \var{safe}. It also -does not have \var{safe} default to \code{'/'}. -\end{funcdesc} - -\begin{funcdesc}{unquote}{string} -Replace \samp{\%xx} escapes by their single-character equivalent. - -Example: \code{unquote('/\%7Econnolly/')} yields \code{'/\~{}connolly/'}. -\end{funcdesc} - -\begin{funcdesc}{unquote_plus}{string} -Like \function{unquote()}, but also replaces plus signs by spaces, as -required for unquoting HTML form values. -\end{funcdesc} - -\begin{funcdesc}{urlencode}{query\optional{, doseq}} -Convert a mapping object or a sequence of two-element tuples to a -``url-encoded'' string, suitable to pass to -\function{urlopen()} above as the optional \var{data} argument. This -is useful to pass a dictionary of form fields to a \code{POST} -request. The resulting string is a series of -\code{\var{key}=\var{value}} pairs separated by \character{\&} -characters, where both \var{key} and \var{value} are quoted using -\function{quote_plus()} above. If the optional parameter \var{doseq} is -present and evaluates to true, individual \code{\var{key}=\var{value}} pairs -are generated for each element of the sequence. -When a sequence of two-element tuples is used as the \var{query} argument, -the first element of each tuple is a key and the second is a value. The -order of parameters in the encoded string will match the order of parameter -tuples in the sequence. -The \refmodule{cgi} module provides the functions -\function{parse_qs()} and \function{parse_qsl()} which are used to -parse query strings into Python data structures. -\end{funcdesc} - -\begin{funcdesc}{pathname2url}{path} -Convert the pathname \var{path} from the local syntax for a path to -the form used in the path component of a URL. This does not produce a -complete URL. The return value will already be quoted using the -\function{quote()} function. -\end{funcdesc} - -\begin{funcdesc}{url2pathname}{path} -Convert the path component \var{path} from an encoded URL to the local -syntax for a path. This does not accept a complete URL. This -function uses \function{unquote()} to decode \var{path}. -\end{funcdesc} - -\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:}, -or \file{file:}, you probably want to use -\class{FancyURLopener}. - -By default, the \class{URLopener} class sends a -\mailheader{User-Agent} header of \samp{urllib/\var{VVV}}, where -\var{VVV} is the \module{urllib} version number. Applications can -define their own \mailheader{User-Agent} header by subclassing -\class{URLopener} or \class{FancyURLopener} and setting the class -attribute \member{version} to an appropriate string value in the -subclass definition. - -The optional \var{proxies} parameter should be a dictionary mapping -scheme names to proxy URLs, where an empty dictionary turns proxies -off completely. Its default value is \code{None}, in which case -environmental proxy settings will be used if present, as discussed in -the definition of \function{urlopen()}, above. - -Additional keyword parameters, collected in \var{x509}, may be used for -authentication of the client when using the \file{https:} scheme. The keywords -\var{key_file} and \var{cert_file} are supported to provide an -SSL key and certificate; both are needed to support client authentication. - -\class{URLopener} objects will raise an \exception{IOError} exception -if the server returns an error code. -\end{classdesc} - -\begin{classdesc}{FancyURLopener}{...} -\class{FancyURLopener} subclasses \class{URLopener} providing default -handling for the following HTTP response codes: 301, 302, 303, 307 and -401. For the 30x response codes listed above, the -\mailheader{Location} header is used to fetch the actual URL. For 401 -response codes (authentication required), basic HTTP authentication is -performed. For the 30x response codes, recursion is bounded by the -value of the \var{maxtries} attribute, which defaults to 10. - -For all other response codes, the method \method{http_error_default()} -is called which you can override in subclasses to handle the error -appropriately. - -\note{According to the letter of \rfc{2616}, 301 and 302 responses to - POST requests must not be automatically redirected without - confirmation by the user. In reality, browsers do allow automatic - redirection of these responses, changing the POST to a GET, and - \module{urllib} reproduces this behaviour.} - -The parameters to the constructor are the same as those for -\class{URLopener}. - -\note{When performing basic authentication, a -\class{FancyURLopener} instance calls its -\method{prompt_user_passwd()} method. The default implementation asks -the users for the required information on the controlling terminal. A -subclass may override this method to support more appropriate behavior -if needed.} -\end{classdesc} - -\begin{excclassdesc}{ContentTooShortError}{msg\optional{, content}} -This exception is raised when the \function{urlretrieve()} function -detects that the amount of the downloaded data is less than the -expected amount (given by the \var{Content-Length} header). The -\member{content} attribute stores the downloaded (and supposedly -truncated) data. -\versionadded{2.5} -\end{excclassdesc} - -Restrictions: - -\begin{itemize} - -\item -Currently, only the following protocols are supported: HTTP, (versions -0.9 and 1.0), FTP, and local files. -\indexii{HTTP}{protocol} -\indexii{FTP}{protocol} - -\item -The caching feature of \function{urlretrieve()} has been disabled -until I find the time to hack proper processing of Expiration time -headers. - -\item -There should be a function to query whether a particular URL is in -the cache. - -\item -For backward compatibility, if a URL appears to point to a local file -but the file can't be opened, the URL is re-interpreted using the FTP -protocol. This can sometimes cause confusing error messages. - -\item -The \function{urlopen()} and \function{urlretrieve()} functions can -cause arbitrarily long delays while waiting for a network connection -to be set up. This means that it is difficult to build an interactive -Web client using these functions without using threads. - -\item -The data returned by \function{urlopen()} or \function{urlretrieve()} -is the raw data returned by the server. This may be binary data -(such as an image), plain text or (for example) HTML\index{HTML}. The -HTTP\indexii{HTTP}{protocol} protocol provides type information in the -reply header, which can be inspected by looking at the -\mailheader{Content-Type} header. If the -returned data is HTML, you can use the module -\refmodule{htmllib}\refstmodindex{htmllib} to parse it. - -\item -The code handling the FTP\index{FTP} protocol cannot differentiate -between a file and a directory. This can lead to unexpected behavior -when attempting to read a URL that points to a file that is not -accessible. If the URL ends in a \code{/}, it is assumed to refer to -a directory and will be handled accordingly. But if an attempt to -read a file leads to a 550 error (meaning the URL cannot be found or -is not accessible, often for permission reasons), then the path is -treated as a directory in order to handle the case when a directory is -specified by a URL but the trailing \code{/} has been left off. This can -cause misleading results when you try to fetch a file whose read -permissions make it inaccessible; the FTP code will try to read it, -fail with a 550 error, and then perform a directory listing for the -unreadable file. If fine-grained control is needed, consider using the -\module{ftplib} module, subclassing \class{FancyURLOpener}, or changing -\var{_urlopener} to meet your needs. - -\item -This module does not support the use of proxies which require -authentication. This may be implemented in the future. - -\item -Although the \module{urllib} module contains (undocumented) routines -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 attributes. - -\begin{methoddesc}[URLopener]{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}[URLopener]{open_unknown}{fullurl\optional{, data}} -Overridable interface to open unknown URL types. -\end{methoddesc} - -\begin{methoddesc}[URLopener]{retrieve}{url\optional{, - filename\optional{, - reporthook\optional{, data}}}} -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 \code{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. - -If the \var{url} uses the \file{http:} scheme identifier, the optional -\var{data} argument may be given to specify a \code{POST} request -(normally the request type is \code{GET}). The \var{data} argument -must in standard \mimetype{application/x-www-form-urlencoded} format; -see the \function{urlencode()} function below. -\end{methoddesc} - -\begin{memberdesc}[URLopener]{version} -Variable that specifies the user agent of the opener object. To get -\refmodule{urllib} to tell servers that it is a particular user agent, -set this in a subclass as a class variable or in the constructor -before calling the base constructor. -\end{memberdesc} - -The \class{FancyURLopener} class offers one additional method that -should be overloaded to provide the appropriate behavior: - -\begin{methoddesc}[FancyURLopener]{prompt_user_passwd}{host, realm} -Return information needed to authenticate the user at the given host -in the specified security realm. The return value should be a tuple, -\code{(\var{user}, \var{password})}, which can be used for basic -authentication. - -The implementation prompts for this information on the terminal; an -application should override this method to use an appropriate -interaction model in the local environment. -\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} - -The following example uses an explicitly specified HTTP proxy, -overriding environment settings: - -\begin{verbatim} ->>> import urllib ->>> proxies = {'http': 'http://proxy.example.com:8080/'} ->>> opener = urllib.FancyURLopener(proxies) ->>> f = opener.open("http://www.python.org") ->>> f.read() -\end{verbatim} - -The following example uses no proxies at all, overriding environment -settings: - -\begin{verbatim} ->>> import urllib ->>> opener = urllib.FancyURLopener({}) ->>> f = opener.open("http://www.python.org/") ->>> f.read() -\end{verbatim} diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex deleted file mode 100644 index 9d2c382..0000000 --- a/Doc/lib/liburllib2.tex +++ /dev/null @@ -1,872 +0,0 @@ -\section{\module{urllib2} --- - extensible library for opening URLs} - -\declaremodule{standard}{urllib2} -\moduleauthor{Jeremy Hylton}{jhylton@users.sourceforge.net} -\sectionauthor{Moshe Zadka}{moshez@users.sourceforge.net} - -\modulesynopsis{An extensible library for opening URLs using a variety of - protocols} - -The \module{urllib2} module defines functions and classes which help -in opening URLs (mostly HTTP) in a complex world --- basic and digest -authentication, redirections, cookies and more. - -The \module{urllib2} module defines the following functions: - -\begin{funcdesc}{urlopen}{url\optional{, data}\optional{, timeout}} -Open the URL \var{url}, which can be either a string or a \class{Request} -object. - -\var{data} may be a string specifying additional data to send to the -server, or \code{None} if no such data is needed. -Currently HTTP requests are the only ones that use \var{data}; -the HTTP request will be a POST instead of a GET when the \var{data} -parameter is provided. \var{data} should be a buffer in the standard -\mimetype{application/x-www-form-urlencoded} format. The -\function{urllib.urlencode()} function takes a mapping or sequence of -2-tuples and returns a string in this format. - -The optional \var{timeout} parameter specifies a timeout in seconds for the -connection attempt (if not specified, or passed as None, the global default -timeout setting will be used). This actually only work for HTTP, HTTPS, FTP -and FTPS connections. - -This function returns a file-like object with two additional methods: - -\begin{itemize} - \item \method{geturl()} --- return the URL of the resource retrieved - \item \method{info()} --- return the meta-information of the page, as - a dictionary-like object -\end{itemize} - -Raises \exception{URLError} on errors. - -Note that \code{None} may be returned if no handler handles the -request (though the default installed global \class{OpenerDirector} -uses \class{UnknownHandler} to ensure this never happens). - -\versionchanged[\var{timeout} was added]{2.6} -\end{funcdesc} - -\begin{funcdesc}{install_opener}{opener} -Install an \class{OpenerDirector} instance as the default global -opener. Installing an opener is only necessary if you want urlopen to -use that opener; otherwise, simply call \method{OpenerDirector.open()} -instead of \function{urlopen()}. The code does not check for a real -\class{OpenerDirector}, and any class with the appropriate interface -will work. -\end{funcdesc} - -\begin{funcdesc}{build_opener}{\optional{handler, \moreargs}} -Return an \class{OpenerDirector} instance, which chains the -handlers in the order given. \var{handler}s can be either instances -of \class{BaseHandler}, or subclasses of \class{BaseHandler} (in -which case it must be possible to call the constructor without -any parameters). Instances of the following classes will be in -front of the \var{handler}s, unless the \var{handler}s contain -them, instances of them or subclasses of them: -\class{ProxyHandler}, \class{UnknownHandler}, \class{HTTPHandler}, -\class{HTTPDefaultErrorHandler}, \class{HTTPRedirectHandler}, -\class{FTPHandler}, \class{FileHandler}, \class{HTTPErrorProcessor}. - -If the Python installation has SSL support (\function{socket.ssl()} -exists), \class{HTTPSHandler} will also be added. - -Beginning in Python 2.3, a \class{BaseHandler} subclass may also -change its \member{handler_order} member variable to modify its -position in the handlers list. -\end{funcdesc} - - -The following exceptions are raised as appropriate: - -\begin{excdesc}{URLError} -The handlers raise this exception (or derived exceptions) when they -run into a problem. It is a subclass of \exception{IOError}. -\end{excdesc} - -\begin{excdesc}{HTTPError} -A subclass of \exception{URLError}, it can also function as a -non-exceptional file-like return value (the same thing that -\function{urlopen()} returns). This is useful when handling exotic -HTTP errors, such as requests for authentication. -\end{excdesc} - - -The following classes are provided: - -\begin{classdesc}{Request}{url\optional{, data}\optional{, headers} - \optional{, origin_req_host}\optional{, unverifiable}} -This class is an abstraction of a URL request. - -\var{url} should be a string containing a valid URL. - -\var{data} may be a string specifying additional data to send to the -server, or \code{None} if no such data is needed. -Currently HTTP requests are the only ones that use \var{data}; -the HTTP request will be a POST instead of a GET when the \var{data} -parameter is provided. \var{data} should be a buffer in the standard -\mimetype{application/x-www-form-urlencoded} format. The -\function{urllib.urlencode()} function takes a mapping or sequence of -2-tuples and returns a string in this format. - -\var{headers} should be a dictionary, and will be treated as if -\method{add_header()} was called with each key and value as arguments. - -The final two arguments are only of interest for correct handling of -third-party HTTP cookies: - -\var{origin_req_host} should be the request-host of the origin -transaction, as defined by \rfc{2965}. It defaults to -\code{cookielib.request_host(self)}. This is the host name or IP -address of the original request that was initiated by the user. For -example, if the request is for an image in an HTML document, this -should be the request-host of the request for the page containing the -image. - -\var{unverifiable} should indicate whether the request is -unverifiable, as defined by RFC 2965. It defaults to False. An -unverifiable request is one whose URL the user did not have the option -to approve. For example, if the request is for an image in an HTML -document, and the user had no option to approve the automatic fetching -of the image, this should be true. -\end{classdesc} - -\begin{classdesc}{OpenerDirector}{} -The \class{OpenerDirector} class opens URLs via \class{BaseHandler}s -chained together. It manages the chaining of handlers, and recovery -from errors. -\end{classdesc} - -\begin{classdesc}{BaseHandler}{} -This is the base class for all registered handlers --- and handles only -the simple mechanics of registration. -\end{classdesc} - -\begin{classdesc}{HTTPDefaultErrorHandler}{} -A class which defines a default handler for HTTP error responses; all -responses are turned into \exception{HTTPError} exceptions. -\end{classdesc} - -\begin{classdesc}{HTTPRedirectHandler}{} -A class to handle redirections. -\end{classdesc} - -\begin{classdesc}{HTTPCookieProcessor}{\optional{cookiejar}} -A class to handle HTTP Cookies. -\end{classdesc} - -\begin{classdesc}{ProxyHandler}{\optional{proxies}} -Cause requests to go through a proxy. -If \var{proxies} is given, it must be a dictionary mapping -protocol names to URLs of proxies. -The default is to read the list of proxies from the environment -variables \envvar{<protocol>_proxy}. -\end{classdesc} - -\begin{classdesc}{HTTPPasswordMgr}{} -Keep a database of -\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})} -mappings. -\end{classdesc} - -\begin{classdesc}{HTTPPasswordMgrWithDefaultRealm}{} -Keep a database of -\code{(\var{realm}, \var{uri}) -> (\var{user}, \var{password})} mappings. -A realm of \code{None} is considered a catch-all realm, which is searched -if no other realm fits. -\end{classdesc} - -\begin{classdesc}{AbstractBasicAuthHandler}{\optional{password_mgr}} -This is a mixin class that helps with HTTP authentication, both -to the remote host and to a proxy. -\var{password_mgr}, if given, should be something that is compatible -with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} -for information on the interface that must be supported. -\end{classdesc} - -\begin{classdesc}{HTTPBasicAuthHandler}{\optional{password_mgr}} -Handle authentication with the remote host. -\var{password_mgr}, if given, should be something that is compatible -with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} -for information on the interface that must be supported. -\end{classdesc} - -\begin{classdesc}{ProxyBasicAuthHandler}{\optional{password_mgr}} -Handle authentication with the proxy. -\var{password_mgr}, if given, should be something that is compatible -with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} -for information on the interface that must be supported. -\end{classdesc} - -\begin{classdesc}{AbstractDigestAuthHandler}{\optional{password_mgr}} -This is a mixin class that helps with HTTP authentication, both -to the remote host and to a proxy. -\var{password_mgr}, if given, should be something that is compatible -with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} -for information on the interface that must be supported. -\end{classdesc} - -\begin{classdesc}{HTTPDigestAuthHandler}{\optional{password_mgr}} -Handle authentication with the remote host. -\var{password_mgr}, if given, should be something that is compatible -with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} -for information on the interface that must be supported. -\end{classdesc} - -\begin{classdesc}{ProxyDigestAuthHandler}{\optional{password_mgr}} -Handle authentication with the proxy. -\var{password_mgr}, if given, should be something that is compatible -with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr} -for information on the interface that must be supported. -\end{classdesc} - -\begin{classdesc}{HTTPHandler}{} -A class to handle opening of HTTP URLs. -\end{classdesc} - -\begin{classdesc}{HTTPSHandler}{} -A class to handle opening of HTTPS URLs. -\end{classdesc} - -\begin{classdesc}{FileHandler}{} -Open local files. -\end{classdesc} - -\begin{classdesc}{FTPHandler}{} -Open FTP URLs. -\end{classdesc} - -\begin{classdesc}{CacheFTPHandler}{} -Open FTP URLs, keeping a cache of open FTP connections to minimize -delays. -\end{classdesc} - -\begin{classdesc}{UnknownHandler}{} -A catch-all class to handle unknown URLs. -\end{classdesc} - - -\subsection{Request Objects \label{request-objects}} - -The following methods describe all of \class{Request}'s public interface, -and so all must be overridden in subclasses. - -\begin{methoddesc}[Request]{add_data}{data} -Set the \class{Request} data to \var{data}. This is ignored by all -handlers except HTTP handlers --- and there it should be a byte -string, and will change the request to be \code{POST} rather than -\code{GET}. -\end{methoddesc} - -\begin{methoddesc}[Request]{get_method}{} -Return a string indicating the HTTP request method. This is only -meaningful for HTTP requests, and currently always returns -\code{'GET'} or \code{'POST'}. -\end{methoddesc} - -\begin{methoddesc}[Request]{has_data}{} -Return whether the instance has a non-\code{None} data. -\end{methoddesc} - -\begin{methoddesc}[Request]{get_data}{} -Return the instance's data. -\end{methoddesc} - -\begin{methoddesc}[Request]{add_header}{key, val} -Add another header to the request. Headers are currently ignored by -all handlers except HTTP handlers, where they are added to the list -of headers sent to the server. Note that there cannot be more than -one header with the same name, and later calls will overwrite -previous calls in case the \var{key} collides. Currently, this is -no loss of HTTP functionality, since all headers which have meaning -when used more than once have a (header-specific) way of gaining the -same functionality using only one header. -\end{methoddesc} - -\begin{methoddesc}[Request]{add_unredirected_header}{key, header} -Add a header that will not be added to a redirected request. -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[Request]{has_header}{header} -Return whether the instance has the named header (checks both regular -and unredirected). -\versionadded{2.4} -\end{methoddesc} - -\begin{methoddesc}[Request]{get_full_url}{} -Return the URL given in the constructor. -\end{methoddesc} - -\begin{methoddesc}[Request]{get_type}{} -Return the type of the URL --- also known as the scheme. -\end{methoddesc} - -\begin{methoddesc}[Request]{get_host}{} -Return the host to which a connection will be made. -\end{methoddesc} - -\begin{methoddesc}[Request]{get_selector}{} -Return the selector --- the part of the URL that is sent to -the server. -\end{methoddesc} - -\begin{methoddesc}[Request]{set_proxy}{host, type} -Prepare the request by connecting to a proxy server. The \var{host} -and \var{type} will replace those of the instance, and the instance's -selector will be the original URL given in the constructor. -\end{methoddesc} - -\begin{methoddesc}[Request]{get_origin_req_host}{} -Return the request-host of the origin transaction, as defined by -\rfc{2965}. See the documentation for the \class{Request} -constructor. -\end{methoddesc} - -\begin{methoddesc}[Request]{is_unverifiable}{} -Return whether the request is unverifiable, as defined by RFC 2965. -See the documentation for the \class{Request} constructor. -\end{methoddesc} - - -\subsection{OpenerDirector Objects \label{opener-director-objects}} - -\class{OpenerDirector} instances have the following methods: - -\begin{methoddesc}[OpenerDirector]{add_handler}{handler} -\var{handler} should be an instance of \class{BaseHandler}. The -following methods are searched, and added to the possible chains (note -that HTTP errors are a special case). - -\begin{itemize} - \item \method{\var{protocol}_open()} --- - signal that the handler knows how to open \var{protocol} URLs. - \item \method{http_error_\var{type}()} --- - signal that the handler knows how to handle HTTP errors with HTTP - error code \var{type}. - \item \method{\var{protocol}_error()} --- - signal that the handler knows how to handle errors from - (non-\code{http}) \var{protocol}. - \item \method{\var{protocol}_request()} --- - signal that the handler knows how to pre-process \var{protocol} - requests. - \item \method{\var{protocol}_response()} --- - signal that the handler knows how to post-process \var{protocol} - responses. -\end{itemize} -\end{methoddesc} - -\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}{\optional{, timeout}}} -Open the given \var{url} (which can be a request object or a string), -optionally passing the given \var{data}. -Arguments, return values and exceptions raised are the same as those -of \function{urlopen()} (which simply calls the \method{open()} method -on the currently installed global \class{OpenerDirector}). The optional -\var{timeout} parameter specifies a timeout in seconds for the connection -attempt (if not specified, or passed as None, the global default timeout -setting will be used; this actually only work for HTTP, HTTPS, FTP -and FTPS connections). - -\versionchanged[\var{timeout} was added]{2.6} -\end{methoddesc} - -\begin{methoddesc}[OpenerDirector]{error}{proto\optional{, - arg\optional{, \moreargs}}} -Handle an error of the given protocol. This will call the registered -error handlers for the given protocol with the given arguments (which -are protocol specific). The HTTP protocol is a special case which -uses the HTTP response code to determine the specific error handler; -refer to the \method{http_error_*()} methods of the handler classes. - -Return values and exceptions raised are the same as those -of \function{urlopen()}. -\end{methoddesc} - -OpenerDirector objects open URLs in three stages: - -The order in which these methods are called within each stage is -determined by sorting the handler instances. - -\begin{enumerate} - \item Every handler with a method named like - \method{\var{protocol}_request()} has that method called to - pre-process the request. - - \item Handlers with a method named like - \method{\var{protocol}_open()} are called to handle the request. - This stage ends when a handler either returns a - non-\constant{None} value (ie. a response), or raises an exception - (usually \exception{URLError}). Exceptions are allowed to propagate. - - In fact, the above algorithm is first tried for methods named - \method{default_open}. If all such methods return - \constant{None}, the algorithm is repeated for methods named like - \method{\var{protocol}_open()}. If all such methods return - \constant{None}, the algorithm is repeated for methods named - \method{unknown_open()}. - - Note that the implementation of these methods may involve calls of - the parent \class{OpenerDirector} instance's \method{.open()} and - \method{.error()} methods. - - \item Every handler with a method named like - \method{\var{protocol}_response()} has that method called to - post-process the response. - -\end{enumerate} - -\subsection{BaseHandler Objects \label{base-handler-objects}} - -\class{BaseHandler} objects provide a couple of methods that are -directly useful, and others that are meant to be used by derived -classes. These are intended for direct use: - -\begin{methoddesc}[BaseHandler]{add_parent}{director} -Add a director as parent. -\end{methoddesc} - -\begin{methoddesc}[BaseHandler]{close}{} -Remove any parents. -\end{methoddesc} - -The following members and methods should only be used by classes -derived from \class{BaseHandler}. \note{The convention has been -adopted that subclasses defining \method{\var{protocol}_request()} or -\method{\var{protocol}_response()} methods are named -\class{*Processor}; all others are named \class{*Handler}.} - - -\begin{memberdesc}[BaseHandler]{parent} -A valid \class{OpenerDirector}, which can be used to open using a -different protocol, or handle errors. -\end{memberdesc} - -\begin{methoddesc}[BaseHandler]{default_open}{req} -This method is \emph{not} defined in \class{BaseHandler}, but -subclasses should define it if they want to catch all URLs. - -This method, if implemented, will be called by the parent -\class{OpenerDirector}. It should return a file-like object as -described in the return value of the \method{open()} of -\class{OpenerDirector}, or \code{None}. It should raise -\exception{URLError}, unless a truly exceptional thing happens (for -example, \exception{MemoryError} should not be mapped to -\exception{URLError}). - -This method will be called before any protocol-specific open method. -\end{methoddesc} - -\begin{methoddescni}[BaseHandler]{\var{protocol}_open}{req} -This method is \emph{not} defined in \class{BaseHandler}, but -subclasses should define it if they want to handle URLs with the given -protocol. - -This method, if defined, will be called by the parent -\class{OpenerDirector}. Return values should be the same as for -\method{default_open()}. -\end{methoddescni} - -\begin{methoddesc}[BaseHandler]{unknown_open}{req} -This method is \var{not} defined in \class{BaseHandler}, but -subclasses should define it if they want to catch all URLs with no -specific registered handler to open it. - -This method, if implemented, will be called by the \member{parent} -\class{OpenerDirector}. Return values should be the same as for -\method{default_open()}. -\end{methoddesc} - -\begin{methoddesc}[BaseHandler]{http_error_default}{req, fp, code, msg, hdrs} -This method is \emph{not} defined in \class{BaseHandler}, but -subclasses should override it if they intend to provide a catch-all -for otherwise unhandled HTTP errors. It will be called automatically -by the \class{OpenerDirector} getting the error, and should not -normally be called in other circumstances. - -\var{req} will be a \class{Request} object, \var{fp} will be a -file-like object with the HTTP error body, \var{code} will be the -three-digit code of the error, \var{msg} will be the user-visible -explanation of the code and \var{hdrs} will be a mapping object with -the headers of the error. - -Return values and exceptions raised should be the same as those -of \function{urlopen()}. -\end{methoddesc} - -\begin{methoddesc}[BaseHandler]{http_error_\var{nnn}}{req, fp, code, msg, hdrs} -\var{nnn} should be a three-digit HTTP error code. This method is -also not defined in \class{BaseHandler}, but will be called, if it -exists, on an instance of a subclass, when an HTTP error with code -\var{nnn} occurs. - -Subclasses should override this method to handle specific HTTP -errors. - -Arguments, return values and exceptions raised should be the same as -for \method{http_error_default()}. -\end{methoddesc} - -\begin{methoddescni}[BaseHandler]{\var{protocol}_request}{req} -This method is \emph{not} defined in \class{BaseHandler}, but -subclasses should define it if they want to pre-process requests of -the given protocol. - -This method, if defined, will be called by the parent -\class{OpenerDirector}. \var{req} will be a \class{Request} object. -The return value should be a \class{Request} object. -\end{methoddescni} - -\begin{methoddescni}[BaseHandler]{\var{protocol}_response}{req, response} -This method is \emph{not} defined in \class{BaseHandler}, but -subclasses should define it if they want to post-process responses of -the given protocol. - -This method, if defined, will be called by the parent -\class{OpenerDirector}. \var{req} will be a \class{Request} object. -\var{response} will be an object implementing the same interface as -the return value of \function{urlopen()}. The return value should -implement the same interface as the return value of -\function{urlopen()}. -\end{methoddescni} - -\subsection{HTTPRedirectHandler Objects \label{http-redirect-handler}} - -\note{Some HTTP redirections require action from this module's client - code. If this is the case, \exception{HTTPError} is raised. See - \rfc{2616} for details of the precise meanings of the various - redirection codes.} - -\begin{methoddesc}[HTTPRedirectHandler]{redirect_request}{req, - fp, code, msg, hdrs} -Return a \class{Request} or \code{None} in response to a redirect. -This is called by the default implementations of the -\method{http_error_30*()} methods when a redirection is received from -the server. If a redirection should take place, return a new -\class{Request} to allow \method{http_error_30*()} to perform the -redirect. Otherwise, raise \exception{HTTPError} if no other handler -should try to handle this URL, or return \code{None} if you can't but -another handler might. - -\begin{notice} - The default implementation of this method does not strictly - follow \rfc{2616}, which says that 301 and 302 responses to \code{POST} - requests must not be automatically redirected without confirmation by - the user. In reality, browsers do allow automatic redirection of - these responses, changing the POST to a \code{GET}, and the default - implementation reproduces this behavior. -\end{notice} -\end{methoddesc} - - -\begin{methoddesc}[HTTPRedirectHandler]{http_error_301}{req, - fp, code, msg, hdrs} -Redirect to the \code{Location:} URL. This method is called by -the parent \class{OpenerDirector} when getting an HTTP -`moved permanently' response. -\end{methoddesc} - -\begin{methoddesc}[HTTPRedirectHandler]{http_error_302}{req, - fp, code, msg, hdrs} -The same as \method{http_error_301()}, but called for the -`found' response. -\end{methoddesc} - -\begin{methoddesc}[HTTPRedirectHandler]{http_error_303}{req, - fp, code, msg, hdrs} -The same as \method{http_error_301()}, but called for the -`see other' response. -\end{methoddesc} - -\begin{methoddesc}[HTTPRedirectHandler]{http_error_307}{req, - fp, code, msg, hdrs} -The same as \method{http_error_301()}, but called for the -`temporary redirect' response. -\end{methoddesc} - - -\subsection{HTTPCookieProcessor Objects \label{http-cookie-processor}} - -\versionadded{2.4} - -\class{HTTPCookieProcessor} instances have one attribute: - -\begin{memberdesc}[HTTPCookieProcessor]{cookiejar} -The \class{cookielib.CookieJar} in which cookies are stored. -\end{memberdesc} - - -\subsection{ProxyHandler Objects \label{proxy-handler}} - -\begin{methoddescni}[ProxyHandler]{\var{protocol}_open}{request} -The \class{ProxyHandler} will have a method -\method{\var{protocol}_open()} for every \var{protocol} which has a -proxy in the \var{proxies} dictionary given in the constructor. The -method will modify requests to go through the proxy, by calling -\code{request.set_proxy()}, and call the next handler in the chain to -actually execute the protocol. -\end{methoddescni} - - -\subsection{HTTPPasswordMgr Objects \label{http-password-mgr}} - -These methods are available on \class{HTTPPasswordMgr} and -\class{HTTPPasswordMgrWithDefaultRealm} objects. - -\begin{methoddesc}[HTTPPasswordMgr]{add_password}{realm, uri, user, passwd} -\var{uri} can be either a single URI, or a sequence of URIs. \var{realm}, -\var{user} and \var{passwd} must be strings. This causes -\code{(\var{user}, \var{passwd})} to be used as authentication tokens -when authentication for \var{realm} and a super-URI of any of the -given URIs is given. -\end{methoddesc} - -\begin{methoddesc}[HTTPPasswordMgr]{find_user_password}{realm, authuri} -Get user/password for given realm and URI, if any. This method will -return \code{(None, None)} if there is no matching user/password. - -For \class{HTTPPasswordMgrWithDefaultRealm} objects, the realm -\code{None} will be searched if the given \var{realm} has no matching -user/password. -\end{methoddesc} - - -\subsection{AbstractBasicAuthHandler Objects - \label{abstract-basic-auth-handler}} - -\begin{methoddesc}[AbstractBasicAuthHandler]{http_error_auth_reqed} - {authreq, host, req, headers} -Handle an authentication request by getting a user/password pair, and -re-trying the request. \var{authreq} should be the name of the header -where the information about the realm is included in the request, -\var{host} specifies the URL and path to authenticate for, \var{req} -should be the (failed) \class{Request} object, and \var{headers} -should be the error headers. - -\var{host} is either an authority (e.g. \code{"python.org"}) or a URL -containing an authority component (e.g. \code{"http://python.org/"}). -In either case, the authority must not contain a userinfo component -(so, \code{"python.org"} and \code{"python.org:80"} are fine, -\code{"joe:password@python.org"} is not). -\end{methoddesc} - - -\subsection{HTTPBasicAuthHandler Objects - \label{http-basic-auth-handler}} - -\begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code, - msg, hdrs} -Retry the request with authentication information, if available. -\end{methoddesc} - - -\subsection{ProxyBasicAuthHandler Objects - \label{proxy-basic-auth-handler}} - -\begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code, - msg, hdrs} -Retry the request with authentication information, if available. -\end{methoddesc} - - -\subsection{AbstractDigestAuthHandler Objects - \label{abstract-digest-auth-handler}} - -\begin{methoddesc}[AbstractDigestAuthHandler]{http_error_auth_reqed} - {authreq, host, req, headers} -\var{authreq} should be the name of the header where the information about -the realm is included in the request, \var{host} should be the host to -authenticate to, \var{req} should be the (failed) \class{Request} -object, and \var{headers} should be the error headers. -\end{methoddesc} - - -\subsection{HTTPDigestAuthHandler Objects - \label{http-digest-auth-handler}} - -\begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code, - msg, hdrs} -Retry the request with authentication information, if available. -\end{methoddesc} - - -\subsection{ProxyDigestAuthHandler Objects - \label{proxy-digest-auth-handler}} - -\begin{methoddesc}[ProxyDigestAuthHandler]{http_error_407}{req, fp, code, - msg, hdrs} -Retry the request with authentication information, if available. -\end{methoddesc} - - -\subsection{HTTPHandler Objects \label{http-handler-objects}} - -\begin{methoddesc}[HTTPHandler]{http_open}{req} -Send an HTTP request, which can be either GET or POST, depending on -\code{\var{req}.has_data()}. -\end{methoddesc} - - -\subsection{HTTPSHandler Objects \label{https-handler-objects}} - -\begin{methoddesc}[HTTPSHandler]{https_open}{req} -Send an HTTPS request, which can be either GET or POST, depending on -\code{\var{req}.has_data()}. -\end{methoddesc} - - -\subsection{FileHandler Objects \label{file-handler-objects}} - -\begin{methoddesc}[FileHandler]{file_open}{req} -Open the file locally, if there is no host name, or -the host name is \code{'localhost'}. Change the -protocol to \code{ftp} otherwise, and retry opening -it using \member{parent}. -\end{methoddesc} - - -\subsection{FTPHandler Objects \label{ftp-handler-objects}} - -\begin{methoddesc}[FTPHandler]{ftp_open}{req} -Open the FTP file indicated by \var{req}. -The login is always done with empty username and password. -\end{methoddesc} - - -\subsection{CacheFTPHandler Objects \label{cacheftp-handler-objects}} - -\class{CacheFTPHandler} objects are \class{FTPHandler} objects with -the following additional methods: - -\begin{methoddesc}[CacheFTPHandler]{setTimeout}{t} -Set timeout of connections to \var{t} seconds. -\end{methoddesc} - -\begin{methoddesc}[CacheFTPHandler]{setMaxConns}{m} -Set maximum number of cached connections to \var{m}. -\end{methoddesc} - - -\subsection{UnknownHandler Objects \label{unknown-handler-objects}} - -\begin{methoddesc}[UnknownHandler]{unknown_open}{} -Raise a \exception{URLError} exception. -\end{methoddesc} - - -\subsection{HTTPErrorProcessor Objects \label{http-error-processor-objects}} - -\versionadded{2.4} - -\begin{methoddesc}[HTTPErrorProcessor]{unknown_open}{} -Process HTTP error responses. - -For 200 error codes, the response object is returned immediately. - -For non-200 error codes, this simply passes the job on to the -\method{\var{protocol}_error_\var{code}()} handler methods, via -\method{OpenerDirector.error()}. Eventually, -\class{urllib2.HTTPDefaultErrorHandler} will raise an -\exception{HTTPError} if no other handler handles the error. -\end{methoddesc} - - -\subsection{Examples \label{urllib2-examples}} - -This example gets the python.org main page and displays the first 100 -bytes of it: - -\begin{verbatim} ->>> import urllib2 ->>> f = urllib2.urlopen('http://www.python.org/') ->>> print f.read(100) -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<?xml-stylesheet href="./css/ht2html -\end{verbatim} - -Here we are sending a data-stream to the stdin of a CGI and reading -the data it returns to us. Note that this example will only work when the -Python installation supports SSL. - -\begin{verbatim} ->>> import urllib2 ->>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi', -... data='This data is passed to stdin of the CGI') ->>> f = urllib2.urlopen(req) ->>> print f.read() -Got Data: "This data is passed to stdin of the CGI" -\end{verbatim} - -The code for the sample CGI used in the above example is: - -\begin{verbatim} -#!/usr/bin/env python -import sys -data = sys.stdin.read() -print 'Content-type: text-plain\n\nGot Data: "%s"' % data -\end{verbatim} - - -Use of Basic HTTP Authentication: - -\begin{verbatim} -import urllib2 -# Create an OpenerDirector with support for Basic HTTP Authentication... -auth_handler = urllib2.HTTPBasicAuthHandler() -auth_handler.add_password(realm='PDQ Application', - uri='https://mahler:8092/site-updates.py', - user='klem', - passwd='kadidd!ehopper') -opener = urllib2.build_opener(auth_handler) -# ...and install it globally so it can be used with urlopen. -urllib2.install_opener(opener) -urllib2.urlopen('http://www.example.com/login.html') -\end{verbatim} - -\function{build_opener()} provides many handlers by default, including a -\class{ProxyHandler}. By default, \class{ProxyHandler} uses the -environment variables named \code{<scheme>_proxy}, where \code{<scheme>} -is the URL scheme involved. For example, the \envvar{http_proxy} -environment variable is read to obtain the HTTP proxy's URL. - -This example replaces the default \class{ProxyHandler} with one that uses -programatically-supplied proxy URLs, and adds proxy authorization support -with \class{ProxyBasicAuthHandler}. - -\begin{verbatim} -proxy_handler = urllib2.ProxyHandler({'http': 'http://www.example.com:3128/'}) -proxy_auth_handler = urllib2.HTTPBasicAuthHandler() -proxy_auth_handler.add_password('realm', 'host', 'username', 'password') - -opener = build_opener(proxy_handler, proxy_auth_handler) -# This time, rather than install the OpenerDirector, we use it directly: -opener.open('http://www.example.com/login.html') -\end{verbatim} - - -Adding HTTP headers: - -Use the \var{headers} argument to the \class{Request} constructor, or: - -\begin{verbatim} -import urllib2 -req = urllib2.Request('http://www.example.com/') -req.add_header('Referer', 'http://www.python.org/') -r = urllib2.urlopen(req) -\end{verbatim} - -\class{OpenerDirector} automatically adds a \mailheader{User-Agent} -header to every \class{Request}. To change this: - -\begin{verbatim} -import urllib2 -opener = urllib2.build_opener() -opener.addheaders = [('User-agent', 'Mozilla/5.0')] -opener.open('http://www.example.com/') -\end{verbatim} - -Also, remember that a few standard headers -(\mailheader{Content-Length}, \mailheader{Content-Type} and -\mailheader{Host}) are added when the \class{Request} is passed to -\function{urlopen()} (or \method{OpenerDirector.open()}). diff --git a/Doc/lib/liburlparse.tex b/Doc/lib/liburlparse.tex deleted file mode 100644 index 16f38a0..0000000 --- a/Doc/lib/liburlparse.tex +++ /dev/null @@ -1,253 +0,0 @@ -\section{\module{urlparse} --- - Parse URLs into components} -\declaremodule{standard}{urlparse} - -\modulesynopsis{Parse URLs into components.} - -\index{WWW} -\index{World Wide Web} -\index{URL} -\indexii{URL}{parsing} -\indexii{relative}{URL} - - -This module defines a standard interface to break Uniform Resource -Locator (URL) strings up in components (addressing scheme, network -location, path etc.), to combine the components back into a URL -string, and to convert a ``relative URL'' to an absolute URL given a -``base URL.'' - -The module has been designed to match the Internet RFC on Relative -Uniform Resource Locators (and discovered a bug in an earlier -draft!). It supports the following URL schemes: -\code{file}, \code{ftp}, \code{gopher}, \code{hdl}, \code{http}, -\code{https}, \code{imap}, \code{mailto}, \code{mms}, \code{news}, -\code{nntp}, \code{prospero}, \code{rsync}, \code{rtsp}, \code{rtspu}, -\code{sftp}, \code{shttp}, \code{sip}, \code{sips}, \code{snews}, \code{svn}, -\code{svn+ssh}, \code{telnet}, \code{wais}. - -\versionadded[Support for the \code{sftp} and \code{sips} schemes]{2.5} - -The \module{urlparse} module defines the following functions: - -\begin{funcdesc}{urlparse}{urlstring\optional{, - default_scheme\optional{, allow_fragments}}} -Parse a URL into six components, returning a 6-tuple. This -corresponds to the general structure of a URL: -\code{\var{scheme}://\var{netloc}/\var{path};\var{parameters}?\var{query}\#\var{fragment}}. -Each tuple item is a string, possibly empty. -The components are not broken up in smaller parts (for example, the network -location is a single string), and \% escapes are not expanded. -The delimiters as shown above are not part of the result, -except for a leading slash in the \var{path} component, which is -retained if present. For example: - -\begin{verbatim} ->>> from urlparse import urlparse ->>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html') ->>> o -('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '') ->>> o.scheme -'http' ->>> o.port -80 ->>> o.geturl() -'http://www.cwi.nl:80/%7Eguido/Python.html' -\end{verbatim} - -If the \var{default_scheme} argument is specified, it gives the -default addressing scheme, to be used only if the URL does not -specify one. The default value for this argument is the empty string. - -If the \var{allow_fragments} argument is false, fragment identifiers -are not allowed, even if the URL's addressing scheme normally does -support them. The default value for this argument is \constant{True}. - -The return value is actually an instance of a subclass of -\pytype{tuple}. This class has the following additional read-only -convenience attributes: - -\begin{tableiv}{l|c|l|c}{member}{Attribute}{Index}{Value}{Value if not present} - \lineiv{scheme} {0} {URL scheme specifier} {empty string} - \lineiv{netloc} {1} {Network location part} {empty string} - \lineiv{path} {2} {Hierarchical path} {empty string} - \lineiv{params} {3} {Parameters for last path element} {empty string} - \lineiv{query} {4} {Query component} {empty string} - \lineiv{fragment}{5} {Fragment identifier} {empty string} - \lineiv{username}{ } {User name} {\constant{None}} - \lineiv{password}{ } {Password} {\constant{None}} - \lineiv{hostname}{ } {Host name (lower case)} {\constant{None}} - \lineiv{port} { } {Port number as integer, if present} {\constant{None}} -\end{tableiv} - -See section~\ref{urlparse-result-object}, ``Results of -\function{urlparse()} and \function{urlsplit()},'' for more -information on the result object. - -\versionchanged[Added attributes to return value]{2.5} -\end{funcdesc} - -\begin{funcdesc}{urlunparse}{parts} -Construct a URL from a tuple as returned by \code{urlparse()}. -The \var{parts} argument can be any six-item iterable. -This may result in a slightly different, but equivalent URL, if the -URL that was parsed originally had unnecessary delimiters (for example, -a ? with an empty query; the RFC states that these are equivalent). -\end{funcdesc} - -\begin{funcdesc}{urlsplit}{urlstring\optional{, - default_scheme\optional{, allow_fragments}}} -This is similar to \function{urlparse()}, but does not split the -params from the URL. This should generally be used instead of -\function{urlparse()} if the more recent URL syntax allowing -parameters to be applied to each segment of the \var{path} portion of -the URL (see \rfc{2396}) is wanted. A separate function is needed to -separate the path segments and parameters. This function returns a -5-tuple: (addressing scheme, network location, path, query, fragment -identifier). - -The return value is actually an instance of a subclass of -\pytype{tuple}. This class has the following additional read-only -convenience attributes: - -\begin{tableiv}{l|c|l|c}{member}{Attribute}{Index}{Value}{Value if not present} - \lineiv{scheme} {0} {URL scheme specifier} {empty string} - \lineiv{netloc} {1} {Network location part} {empty string} - \lineiv{path} {2} {Hierarchical path} {empty string} - \lineiv{query} {3} {Query component} {empty string} - \lineiv{fragment} {4} {Fragment identifier} {empty string} - \lineiv{username} { } {User name} {\constant{None}} - \lineiv{password} { } {Password} {\constant{None}} - \lineiv{hostname} { } {Host name (lower case)} {\constant{None}} - \lineiv{port} { } {Port number as integer, if present} {\constant{None}} -\end{tableiv} - -See section~\ref{urlparse-result-object}, ``Results of -\function{urlparse()} and \function{urlsplit()},'' for more -information on the result object. - -\versionadded{2.2} -\versionchanged[Added attributes to return value]{2.5} -\end{funcdesc} - -\begin{funcdesc}{urlunsplit}{parts} -Combine the elements of a tuple as returned by \function{urlsplit()} -into a complete URL as a string. -The \var{parts} argument can be any five-item iterable. -This may result in a slightly different, but equivalent URL, if the -URL that was parsed originally had unnecessary delimiters (for example, -a ? with an empty query; the RFC states that these are equivalent). -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{urljoin}{base, url\optional{, allow_fragments}} -Construct a full (``absolute'') URL by combining a ``base URL'' -(\var{base}) with another URL (\var{url}). Informally, this -uses components of the base URL, in particular the addressing scheme, -the network location and (part of) the path, to provide missing -components in the relative URL. For example: - -\begin{verbatim} ->>> from urlparse import urljoin ->>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html') -'http://www.cwi.nl/%7Eguido/FAQ.html' -\end{verbatim} - -The \var{allow_fragments} argument has the same meaning and default as -for \function{urlparse()}. - -\note{If \var{url} is an absolute URL (that is, starting with \code{//} - or \code{scheme://}), the \var{url}'s host name and/or scheme - will be present in the result. For example:} - -\begin{verbatim} ->>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', -... '//www.python.org/%7Eguido') -'http://www.python.org/%7Eguido' -\end{verbatim} - -If you do not want that behavior, preprocess -the \var{url} with \function{urlsplit()} and \function{urlunsplit()}, -removing possible \emph{scheme} and \emph{netloc} parts. -\end{funcdesc} - -\begin{funcdesc}{urldefrag}{url} -If \var{url} contains a fragment identifier, returns a modified -version of \var{url} with no fragment identifier, and the fragment -identifier as a separate string. If there is no fragment identifier -in \var{url}, returns \var{url} unmodified and an empty string. -\end{funcdesc} - - -\begin{seealso} - \seerfc{1738}{Uniform Resource Locators (URL)}{ - This specifies the formal syntax and semantics of absolute - URLs.} - \seerfc{1808}{Relative Uniform Resource Locators}{ - This Request For Comments includes the rules for joining an - absolute and a relative URL, including a fair number of - ``Abnormal Examples'' which govern the treatment of border - cases.} - \seerfc{2396}{Uniform Resource Identifiers (URI): Generic Syntax}{ - Document describing the generic syntactic requirements for - both Uniform Resource Names (URNs) and Uniform Resource - Locators (URLs).} -\end{seealso} - - -\subsection{Results of \function{urlparse()} and \function{urlsplit()} - \label{urlparse-result-object}} - -The result objects from the \function{urlparse()} and -\function{urlsplit()} functions are subclasses of the \pytype{tuple} -type. These subclasses add the attributes described in those -functions, as well as provide an additional method: - -\begin{methoddesc}[ParseResult]{geturl}{} - Return the re-combined version of the original URL as a string. - This may differ from the original URL in that the scheme will always - be normalized to lower case and empty components may be dropped. - Specifically, empty parameters, queries, and fragment identifiers - will be removed. - - The result of this method is a fixpoint if passed back through the - original parsing function: - -\begin{verbatim} ->>> import urlparse ->>> url = 'HTTP://www.Python.org/doc/#' - ->>> r1 = urlparse.urlsplit(url) ->>> r1.geturl() -'http://www.Python.org/doc/' - ->>> r2 = urlparse.urlsplit(r1.geturl()) ->>> r2.geturl() -'http://www.Python.org/doc/' -\end{verbatim} - -\versionadded{2.5} -\end{methoddesc} - -The following classes provide the implementations of the parse results:: - -\begin{classdesc*}{BaseResult} - Base class for the concrete result classes. This provides most of - the attribute definitions. It does not provide a \method{geturl()} - method. It is derived from \class{tuple}, but does not override the - \method{__init__()} or \method{__new__()} methods. -\end{classdesc*} - - -\begin{classdesc}{ParseResult}{scheme, netloc, path, params, query, fragment} - Concrete class for \function{urlparse()} results. The - \method{__new__()} method is overridden to support checking that the - right number of arguments are passed. -\end{classdesc} - - -\begin{classdesc}{SplitResult}{scheme, netloc, path, query, fragment} - Concrete class for \function{urlsplit()} results. The - \method{__new__()} method is overridden to support checking that the - right number of arguments are passed. -\end{classdesc} diff --git a/Doc/lib/libuser.tex b/Doc/lib/libuser.tex deleted file mode 100644 index 6dd1546..0000000 --- a/Doc/lib/libuser.tex +++ /dev/null @@ -1,71 +0,0 @@ -\section{\module{user} --- - User-specific configuration hook} - -\declaremodule{standard}{user} -\modulesynopsis{A standard way to reference user-specific modules.} - - -\indexii{.pythonrc.py}{file} -\indexiii{user}{configuration}{file} - -As a policy, Python doesn't run user-specified code on startup of -Python programs. (Only interactive sessions execute the script -specified in the \envvar{PYTHONSTARTUP} environment variable if it -exists). - -However, some programs or sites may find it convenient to allow users -to have a standard customization file, which gets run when a program -requests it. This module implements such a mechanism. A program -that wishes to use the mechanism must execute the statement - -\begin{verbatim} -import user -\end{verbatim} - -The \module{user} module looks for a file \file{.pythonrc.py} in the user's -home directory and if it can be opened, executes it (using -\function{exec()}\bifuncindex{exec}) in its own (the -module \module{user}'s) global namespace. Errors during this phase -are not caught; that's up to the program that imports the -\module{user} module, if it wishes. The home directory is assumed to -be named by the \envvar{HOME} environment variable; if this is not set, -the current directory is used. - -The user's \file{.pythonrc.py} could conceivably test for -\code{sys.version} if it wishes to do different things depending on -the Python version. - -A warning to users: be very conservative in what you place in your -\file{.pythonrc.py} file. Since you don't know which programs will -use it, changing the behavior of standard modules or functions is -generally not a good idea. - -A suggestion for programmers who wish to use this mechanism: a simple -way to let users specify options for your package is to have them -define variables in their \file{.pythonrc.py} file that you test in -your module. For example, a module \module{spam} that has a verbosity -level can look for a variable \code{user.spam_verbose}, as follows: - -\begin{verbatim} -import user - -verbose = bool(getattr(user, "spam_verbose", 0)) -\end{verbatim} - -(The three-argument form of \function{getattr()} is used in case -the user has not defined \code{spam_verbose} in their -\file{.pythonrc.py} file.) - -Programs with extensive customization needs are better off reading a -program-specific customization file. - -Programs with security or privacy concerns should \emph{not} import -this module; a user can easily break into a program by placing -arbitrary code in the \file{.pythonrc.py} file. - -Modules for general use should \emph{not} import this module; it may -interfere with the operation of the importing program. - -\begin{seealso} - \seemodule{site}{Site-wide customization mechanism.} -\end{seealso} diff --git a/Doc/lib/libuserdict.tex b/Doc/lib/libuserdict.tex deleted file mode 100644 index 0bb57c8..0000000 --- a/Doc/lib/libuserdict.tex +++ /dev/null @@ -1,181 +0,0 @@ -\section{\module{UserDict} --- - Class wrapper for dictionary objects} - -\declaremodule{standard}{UserDict} -\modulesynopsis{Class wrapper for dictionary objects.} - - -The module defines a mixin, \class{DictMixin}, defining all dictionary -methods for classes that already have a minimum mapping interface. This -greatly simplifies writing classes that need to be substitutable for -dictionaries (such as the shelve module). - -This also module defines a class, \class{UserDict}, that acts as a wrapper -around dictionary objects. The need for this class has been largely -supplanted by the ability to subclass directly from \class{dict} (a feature -that became available starting with Python version 2.2). Prior to the -introduction of \class{dict}, the \class{UserDict} class was used to -create dictionary-like sub-classes that obtained new behaviors by overriding -existing methods or adding new ones. - -The \module{UserDict} module defines the \class{UserDict} class -and \class{DictMixin}: - -\begin{classdesc}{UserDict}{\optional{initialdata}} -Class that simulates a dictionary. The instance's contents are kept -in a regular dictionary, which is accessible via the \member{data} -attribute of \class{UserDict} instances. If \var{initialdata} is -provided, \member{data} is initialized with its contents; note that a -reference to \var{initialdata} will not be kept, allowing it be used -for other purposes. \note{For backward compatibility, instances of -\class{UserDict} are not iterable.} -\end{classdesc} - -\begin{classdesc}{IterableUserDict}{\optional{initialdata}} -Subclass of \class{UserDict} that supports direct iteration (e.g. -\code{for key in myDict}). -\end{classdesc} - -In addition to supporting the methods and operations of mappings (see -section \ref{typesmapping}), \class{UserDict} and -\class{IterableUserDict} instances provide the following attribute: - -\begin{memberdesc}{data} -A real dictionary used to store the contents of the \class{UserDict} -class. -\end{memberdesc} - -\begin{classdesc}{DictMixin}{} -Mixin defining all dictionary methods for classes that already have -a minimum dictionary interface including \method{__getitem__()}, -\method{__setitem__()}, \method{__delitem__()}, and \method{keys()}. - -This mixin should be used as a superclass. Adding each of the -above methods adds progressively more functionality. For instance, -defining all but \method{__delitem__} will preclude only \method{pop} -and \method{popitem} from the full interface. - -In addition to the four base methods, progressively more efficiency -comes with defining \method{__contains__()}, \method{__iter__()}, and -\method{iteritems()}. - -Since the mixin has no knowledge of the subclass constructor, it -does not define \method{__init__()} or \method{copy()}. -\end{classdesc} - - -\section{\module{UserList} --- - Class wrapper for list objects} - -\declaremodule{standard}{UserList} -\modulesynopsis{Class wrapper for list objects.} - - -\note{This module is available for backward compatibility only. If -you are writing code that does not need to work with versions of -Python earlier than Python 2.2, please consider subclassing directly -from the built-in \class{list} type.} - -This module defines a class that acts as a wrapper around -list objects. It is a useful base class for -your own list-like classes, which can inherit from -them and override existing methods or add new ones. In this way one -can add new behaviors to lists. - -The \module{UserList} module defines the \class{UserList} class: - -\begin{classdesc}{UserList}{\optional{list}} -Class that simulates a list. The instance's -contents are kept in a regular list, which is accessible via the -\member{data} attribute of \class{UserList} instances. The instance's -contents are initially set to a copy of \var{list}, defaulting to the -empty list \code{[]}. \var{list} can be either a regular Python list, -or an instance of \class{UserList} (or a subclass). -\end{classdesc} - -In addition to supporting the methods and operations of mutable -sequences (see section \ref{typesseq}), \class{UserList} instances -provide the following attribute: - -\begin{memberdesc}{data} -A real Python list object used to store the contents of the -\class{UserList} class. -\end{memberdesc} - -\strong{Subclassing requirements:} -Subclasses of \class{UserList} are expect to offer a constructor which -can be called with either no arguments or one argument. List -operations which return a new sequence attempt to create an instance -of the actual implementation class. To do so, it assumes that the -constructor can be called with a single parameter, which is a sequence -object used as a data source. - -If a derived class does not wish to comply with this requirement, all -of the special methods supported by this class will need to be -overridden; please consult the sources for information about the -methods which need to be provided in that case. - -\versionchanged[Python versions 1.5.2 and 1.6 also required that the - constructor be callable with no parameters, and offer - a mutable \member{data} attribute. Earlier versions - of Python did not attempt to create instances of the - derived class]{2.0} - - -\section{\module{UserString} --- - Class wrapper for string objects} - -\declaremodule{standard}{UserString} -\modulesynopsis{Class wrapper for string objects.} -\moduleauthor{Peter Funk}{pf@artcom-gmbh.de} -\sectionauthor{Peter Funk}{pf@artcom-gmbh.de} - -\note{This \class{UserString} class from this module is available for -backward compatibility only. If you are writing code that does not -need to work with versions of Python earlier than Python 2.2, please -consider subclassing directly from the built-in \class{str} type -instead of using \class{UserString} (there is no built-in equivalent -to \class{MutableString}).} - -This module defines a class that acts as a wrapper around string -objects. It is a useful base class for your own string-like classes, -which can inherit from them and override existing methods or add new -ones. In this way one can add new behaviors to strings. - -It should be noted that these classes are highly inefficient compared -to real string or Unicode objects; this is especially the case for -\class{MutableString}. - -The \module{UserString} module defines the following classes: - -\begin{classdesc}{UserString}{\optional{sequence}} -Class that simulates a string or a Unicode string -object. The instance's content is kept in a regular string or Unicode -string object, which is accessible via the \member{data} attribute of -\class{UserString} instances. The instance's contents are initially -set to a copy of \var{sequence}. \var{sequence} can be either a -regular Python string or Unicode string, an instance of -\class{UserString} (or a subclass) or an arbitrary sequence which can -be converted into a string using the built-in \function{str()} function. -\end{classdesc} - -\begin{classdesc}{MutableString}{\optional{sequence}} -This class is derived from the \class{UserString} above and redefines -strings to be \emph{mutable}. Mutable strings can't be used as -dictionary keys, because dictionaries require \emph{immutable} objects as -keys. The main intention of this class is to serve as an educational -example for inheritance and necessity to remove (override) the -\method{__hash__()} method in order to trap attempts to use a -mutable object as dictionary key, which would be otherwise very -error prone and hard to track down. -\end{classdesc} - -In addition to supporting the methods and operations of string and -Unicode objects (see section \ref{string-methods}, ``String -Methods''), \class{UserString} instances provide the following -attribute: - -\begin{memberdesc}{data} -A real Python string or Unicode object used to store the content of the -\class{UserString} class. -\end{memberdesc} diff --git a/Doc/lib/libuu.tex b/Doc/lib/libuu.tex deleted file mode 100644 index 7e546a0..0000000 --- a/Doc/lib/libuu.tex +++ /dev/null @@ -1,58 +0,0 @@ -\section{\module{uu} --- - Encode and decode uuencode files} - -\declaremodule{standard}{uu} -\modulesynopsis{Encode and decode files in uuencode format.} -\moduleauthor{Lance Ellinghouse}{} - - -This module encodes and decodes files in uuencode format, allowing -arbitrary binary data to be transferred over ASCII-only connections. -Wherever a file argument is expected, the methods accept a file-like -object. For backwards compatibility, a string containing a pathname -is also accepted, and the corresponding file will be opened for -reading and writing; the pathname \code{'-'} is understood to mean the -standard input or output. However, this interface is deprecated; it's -better for the caller to open the file itself, and be sure that, when -required, the mode is \code{'rb'} or \code{'wb'} on Windows. - -This code was contributed by Lance Ellinghouse, and modified by Jack -Jansen. -\index{Jansen, Jack} -\index{Ellinghouse, Lance} - -The \module{uu} module defines the following functions: - -\begin{funcdesc}{encode}{in_file, out_file\optional{, name\optional{, mode}}} - Uuencode file \var{in_file} into file \var{out_file}. The uuencoded - file will have the header specifying \var{name} and \var{mode} as - the defaults for the results of decoding the file. The default - defaults are taken from \var{in_file}, or \code{'-'} and \code{0666} - respectively. -\end{funcdesc} - -\begin{funcdesc}{decode}{in_file\optional{, out_file\optional{, mode\optional{, quiet}}}} - This call decodes uuencoded file \var{in_file} placing the result on - file \var{out_file}. If \var{out_file} is a pathname, \var{mode} is - used to set the permission bits if the file must be - created. Defaults for \var{out_file} and \var{mode} are taken from - the uuencode header. However, if the file specified in the header - already exists, a \exception{uu.Error} is raised. - - \function{decode()} may print a warning to standard error if the - input was produced by an incorrect uuencoder and Python could - recover from that error. Setting \var{quiet} to a true value - silences this warning. -\end{funcdesc} - -\begin{excclassdesc}{Error}{} - Subclass of \exception{Exception}, this can be raised by - \function{uu.decode()} under various situations, such as described - above, but also including a badly formatted header, or truncated - input file. -\end{excclassdesc} - -\begin{seealso} - \seemodule{binascii}{Support module containing \ASCII-to-binary - and binary-to-\ASCII{} conversions.} -\end{seealso} diff --git a/Doc/lib/libuuid.tex b/Doc/lib/libuuid.tex deleted file mode 100644 index 5aa9d8c..0000000 --- a/Doc/lib/libuuid.tex +++ /dev/null @@ -1,233 +0,0 @@ -\section{\module{uuid} --- - UUID objects according to RFC 4122} -\declaremodule{builtin}{uuid} -\modulesynopsis{UUID objects (universally unique identifiers) according to RFC 4122} -\moduleauthor{Ka-Ping Yee}{ping@zesty.ca} -\sectionauthor{George Yoshida}{quiver@users.sourceforge.net} - -\versionadded{2.5} - -This module provides immutable \class{UUID} objects (the \class{UUID} class) -and the functions \function{uuid1()}, \function{uuid3()}, -\function{uuid4()}, \function{uuid5()} for generating version 1, 3, 4, -and 5 UUIDs as specified in \rfc{4122}. - -If all you want is a unique ID, you should probably call -\function{uuid1()} or \function{uuid4()}. Note that \function{uuid1()} -may compromise privacy since it creates a UUID containing the computer's -network address. \function{uuid4()} creates a random UUID. - -\begin{classdesc}{UUID}{\optional{hex\optional{, bytes\optional{, -bytes_le\optional{, fields\optional{, int\optional{, version}}}}}}} - -Create a UUID from either a string of 32 hexadecimal digits, -a string of 16 bytes as the \var{bytes} argument, a string of 16 bytes -in little-endian order as the \var{bytes_le} argument, a tuple of six -integers (32-bit \var{time_low}, 16-bit \var{time_mid}, -16-bit \var{time_hi_version}, -8-bit \var{clock_seq_hi_variant}, 8-bit \var{clock_seq_low}, 48-bit \var{node}) -as the \var{fields} argument, or a single 128-bit integer as the \var{int} -argument. When a string of hex digits is given, curly braces, -hyphens, and a URN prefix are all optional. For example, these -expressions all yield the same UUID: - -\begin{verbatim} -UUID('{12345678-1234-5678-1234-567812345678}') -UUID('12345678123456781234567812345678') -UUID('urn:uuid:12345678-1234-5678-1234-567812345678') -UUID(bytes='\x12\x34\x56\x78'*4) -UUID(bytes_le='\x78\x56\x34\x12\x34\x12\x78\x56' + - '\x12\x34\x56\x78\x12\x34\x56\x78') -UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678)) -UUID(int=0x12345678123456781234567812345678) -\end{verbatim} - -Exactly one of \var{hex}, \var{bytes}, \var{bytes_le}, \var{fields}, -or \var{int} must -be given. The \var{version} argument is optional; if given, the -resulting UUID will have its variant and version number set according to -RFC 4122, overriding bits in the given \var{hex}, \var{bytes}, -\var{bytes_le}, \var{fields}, or \var{int}. - -\end{classdesc} - -\class{UUID} instances have these read-only attributes: - -\begin{memberdesc}{bytes} -The UUID as a 16-byte string (containing the six -integer fields in big-endian byte order). -\end{memberdesc} - -\begin{memberdesc}{bytes_le} -The UUID as a 16-byte string (with \var{time_low}, \var{time_mid}, -and \var{time_hi_version} in little-endian byte order). -\end{memberdesc} - -\begin{memberdesc}{fields} -A tuple of the six integer fields of the UUID, which are also available -as six individual attributes and two derived attributes: - -\begin{tableii}{l|l}{member}{Field}{Meaning} - \lineii{time_low}{the first 32 bits of the UUID} - \lineii{time_mid}{the next 16 bits of the UUID} - \lineii{time_hi_version}{the next 16 bits of the UUID} - \lineii{clock_seq_hi_variant}{the next 8 bits of the UUID} - \lineii{clock_seq_low}{the next 8 bits of the UUID} - \lineii{node}{the last 48 bits of the UUID} - \lineii{time}{the 60-bit timestamp} - \lineii{clock_seq}{the 14-bit sequence number} -\end{tableii} - - -\end{memberdesc} - -\begin{memberdesc}{hex} -The UUID as a 32-character hexadecimal string. -\end{memberdesc} - -\begin{memberdesc}{int} -The UUID as a 128-bit integer. -\end{memberdesc} - -\begin{memberdesc}{urn} -The UUID as a URN as specified in RFC 4122. -\end{memberdesc} - -\begin{memberdesc}{variant} -The UUID variant, which determines the internal layout of the UUID. -This will be one of the integer constants -\constant{RESERVED_NCS}, -\constant{RFC_4122}, \constant{RESERVED_MICROSOFT}, or -\constant{RESERVED_FUTURE}. -\end{memberdesc} - -\begin{memberdesc}{version} -The UUID version number (1 through 5, meaningful only -when the variant is \constant{RFC_4122}). -\end{memberdesc} - -The \module{uuid} module defines the following functions: - -\begin{funcdesc}{getnode}{} -Get the hardware address as a 48-bit positive integer. The first time this -runs, it may launch a separate program, which could be quite slow. If all -attempts to obtain the hardware address fail, we choose a random 48-bit -number with its eighth bit set to 1 as recommended in RFC 4122. "Hardware -address" means the MAC address of a network interface, and on a machine -with multiple network interfaces the MAC address of any one of them may -be returned. -\end{funcdesc} -\index{getnode} - -\begin{funcdesc}{uuid1}{\optional{node\optional{, clock_seq}}} -Generate a UUID from a host ID, sequence number, and the current time. -If \var{node} is not given, \function{getnode()} is used to obtain the -hardware address. -If \var{clock_seq} is given, it is used as the sequence number; -otherwise a random 14-bit sequence number is chosen. -\end{funcdesc} -\index{uuid1} - -\begin{funcdesc}{uuid3}{namespace, name} -Generate a UUID based on the MD5 hash -of a namespace identifier (which is a UUID) and a name (which is a string). -\end{funcdesc} -\index{uuid3} - -\begin{funcdesc}{uuid4}{} -Generate a random UUID. -\end{funcdesc} -\index{uuid4} - -\begin{funcdesc}{uuid5}{namespace, name} -Generate a UUID based on the SHA-1 hash -of a namespace identifier (which is a UUID) and a name (which is a string). -\end{funcdesc} -\index{uuid5} - -The \module{uuid} module defines the following namespace identifiers -for use with \function{uuid3()} or \function{uuid5()}. - -\begin{datadesc}{NAMESPACE_DNS} -When this namespace is specified, -the \var{name} string is a fully-qualified domain name. -\end{datadesc} - -\begin{datadesc}{NAMESPACE_URL} -When this namespace is specified, -the \var{name} string is a URL. -\end{datadesc} - -\begin{datadesc}{NAMESPACE_OID} -When this namespace is specified, -the \var{name} string is an ISO OID. -\end{datadesc} - -\begin{datadesc}{NAMESPACE_X500} -When this namespace is specified, -the \var{name} string is an X.500 DN in DER or a text output format. -\end{datadesc} - -The \module{uuid} module defines the following constants -for the possible values of the \member{variant} attribute: - -\begin{datadesc}{RESERVED_NCS} -Reserved for NCS compatibility. -\end{datadesc} - -\begin{datadesc}{RFC_4122} -Specifies the UUID layout given in \rfc{4122}. -\end{datadesc} - -\begin{datadesc}{RESERVED_MICROSOFT} -Reserved for Microsoft compatibility. -\end{datadesc} - -\begin{datadesc}{RESERVED_FUTURE} -Reserved for future definition. -\end{datadesc} - - -\begin{seealso} - \seerfc{4122}{A Universally Unique IDentifier (UUID) URN Namespace}{ -This specification defines a Uniform Resource Name namespace for UUIDs, -the internal format of UUIDs, and methods of generating UUIDs.} -\end{seealso} - -\subsection{Example \label{uuid-example}} - -Here are some examples of typical usage of the \module{uuid} module: -\begin{verbatim} ->>> import uuid - -# make a UUID based on the host ID and current time ->>> uuid.uuid1() -UUID('a8098c1a-f86e-11da-bd1a-00112444be1e') - -# make a UUID using an MD5 hash of a namespace UUID and a name ->>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org') -UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e') - -# make a random UUID ->>> uuid.uuid4() -UUID('16fd2706-8baf-433b-82eb-8c7fada847da') - -# make a UUID using a SHA-1 hash of a namespace UUID and a name ->>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org') -UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d') - -# make a UUID from a string of hex digits (braces and hyphens ignored) ->>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}') - -# convert a UUID to a string of hex digits in standard form ->>> str(x) -'00010203-0405-0607-0809-0a0b0c0d0e0f' - -# get the raw 16 bytes of the UUID ->>> x.bytes -'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f' - -# make a UUID from a 16-byte string ->>> uuid.UUID(bytes=x.bytes) -UUID('00010203-0405-0607-0809-0a0b0c0d0e0f') -\end{verbatim} diff --git a/Doc/lib/libwarnings.tex b/Doc/lib/libwarnings.tex deleted file mode 100644 index a37a9f5..0000000 --- a/Doc/lib/libwarnings.tex +++ /dev/null @@ -1,253 +0,0 @@ -\section{\module{warnings} --- - Warning control} - -\declaremodule{standard}{warnings} -\modulesynopsis{Issue warning messages and control their disposition.} -\index{warnings} - -\versionadded{2.1} - -Warning messages are typically issued in situations where it is useful -to alert the user of some condition in a program, where that condition -(normally) doesn't warrant raising an exception and terminating the -program. For example, one might want to issue a warning when a -program uses an obsolete module. - -Python programmers issue warnings by calling the \function{warn()} -function defined in this module. (C programmers use -\cfunction{PyErr_Warn()}; see the -\citetitle[../api/exceptionHandling.html]{Python/C API Reference -Manual} for details). - -Warning messages are normally written to \code{sys.stderr}, but their -disposition can be changed flexibly, from ignoring all warnings to -turning them into exceptions. The disposition of warnings can vary -based on the warning category (see below), the text of the warning -message, and the source location where it is issued. Repetitions of a -particular warning for the same source location are typically -suppressed. - -There are two stages in warning control: first, each time a warning is -issued, a determination is made whether a message should be issued or -not; next, if a message is to be issued, it is formatted and printed -using a user-settable hook. - -The determination whether to issue a warning message is controlled by -the warning filter, which is a sequence of matching rules and actions. -Rules can be added to the filter by calling -\function{filterwarnings()} and reset to its default state by calling -\function{resetwarnings()}. - -The printing of warning messages is done by calling -\function{showwarning()}, which may be overridden; the default -implementation of this function formats the message by calling -\function{formatwarning()}, which is also available for use by custom -implementations. - - -\subsection{Warning Categories \label{warning-categories}} - -There are a number of built-in exceptions that represent warning -categories. This categorization is useful to be able to filter out -groups of warnings. The following warnings category classes are -currently defined: - -\begin{tableii}{l|l}{exception}{Class}{Description} - -\lineii{Warning}{This is the base class of all warning category -classes. It is a subclass of \exception{Exception}.} - -\lineii{UserWarning}{The default category for \function{warn()}.} - -\lineii{DeprecationWarning}{Base category for warnings about -deprecated features.} - -\lineii{SyntaxWarning}{Base category for warnings about dubious -syntactic features.} - -\lineii{RuntimeWarning}{Base category for warnings about dubious -runtime features.} - -\lineii{FutureWarning}{Base category for warnings about constructs -that will change semantically in the future.} - -\lineii{PendingDeprecationWarning}{Base category for warnings about -features that will be deprecated in the future (ignored by default).} - -\lineii{ImportWarning}{Base category for warnings triggered during the -process of importing a module (ignored by default).} - -\lineii{UnicodeWarning}{Base category for warnings related to Unicode.} - -\end{tableii} - -While these are technically built-in exceptions, they are documented -here, because conceptually they belong to the warnings mechanism. - -User code can define additional warning categories by subclassing one -of the standard warning categories. A warning category must always be -a subclass of the \exception{Warning} class. - - -\subsection{The Warnings Filter \label{warning-filter}} - -The warnings filter controls whether warnings are ignored, displayed, -or turned into errors (raising an exception). - -Conceptually, the warnings filter maintains an ordered list of filter -specifications; any specific warning is matched against each filter -specification in the list in turn until a match is found; the match -determines the disposition of the match. Each entry is a tuple of the -form (\var{action}, \var{message}, \var{category}, \var{module}, -\var{lineno}), where: - -\begin{itemize} - -\item \var{action} is one of the following strings: - - \begin{tableii}{l|l}{code}{Value}{Disposition} - - \lineii{"error"}{turn matching warnings into exceptions} - - \lineii{"ignore"}{never print matching warnings} - - \lineii{"always"}{always print matching warnings} - - \lineii{"default"}{print the first occurrence of matching - warnings for each location where the warning is issued} - - \lineii{"module"}{print the first occurrence of matching - warnings for each module where the warning is issued} - - \lineii{"once"}{print only the first occurrence of matching - warnings, regardless of location} - - \end{tableii} - -\item \var{message} is a string containing a regular expression that -the warning message must match (the match is compiled to always be -case-insensitive) - -\item \var{category} is a class (a subclass of \exception{Warning}) of - which the warning category must be a subclass in order to match - -\item \var{module} is a string containing a regular expression that the module - name must match (the match is compiled to be case-sensitive) - -\item \var{lineno} is an integer that the line number where the - warning occurred must match, or \code{0} to match all line - numbers - -\end{itemize} - -Since the \exception{Warning} class is derived from the built-in -\exception{Exception} class, to turn a warning into an error we simply -raise \code{category(message)}. - -The warnings filter is initialized by \programopt{-W} options passed -to the Python interpreter command line. The interpreter saves the -arguments for all \programopt{-W} options without interpretation in -\code{sys.warnoptions}; the \module{warnings} module parses these when -it is first imported (invalid options are ignored, after printing a -message to \code{sys.stderr}). - -The warnings that are ignored by default may be enabled by passing - \programopt{-Wd} to the interpreter. This enables default handling -for all warnings, including those that are normally ignored by -default. This is particular useful for enabling ImportWarning when -debugging problems importing a developed package. ImportWarning can -also be enabled explicitly in Python code using: - -\begin{verbatim} - warnings.simplefilter('default', ImportWarning) -\end{verbatim} - - -\subsection{Available Functions \label{warning-functions}} - -\begin{funcdesc}{warn}{message\optional{, category\optional{, stacklevel}}} -Issue a warning, or maybe ignore it or raise an exception. The -\var{category} argument, if given, must be a warning category class -(see above); it defaults to \exception{UserWarning}. Alternatively -\var{message} can be a \exception{Warning} instance, in which case -\var{category} will be ignored and \code{message.__class__} will be used. -In this case the message text will be \code{str(message)}. This function -raises an exception if the particular warning issued is changed -into an error by the warnings filter see above. The \var{stacklevel} -argument can be used by wrapper functions written in Python, like -this: - -\begin{verbatim} -def deprecation(message): - warnings.warn(message, DeprecationWarning, stacklevel=2) -\end{verbatim} - -This makes the warning refer to \function{deprecation()}'s caller, -rather than to the source of \function{deprecation()} itself (since -the latter would defeat the purpose of the warning message). -\end{funcdesc} - -\begin{funcdesc}{warn_explicit}{message, category, filename, - lineno\optional{, module\optional{, registry\optional{, - module_globals}}}} -This is a low-level interface to the functionality of -\function{warn()}, passing in explicitly the message, category, -filename and line number, and optionally the module name and the -registry (which should be the \code{__warningregistry__} dictionary of -the module). The module name defaults to the filename with \code{.py} -stripped; if no registry is passed, the warning is never suppressed. -\var{message} must be a string and \var{category} a subclass of -\exception{Warning} or \var{message} may be a \exception{Warning} instance, -in which case \var{category} will be ignored. - -\var{module_globals}, if supplied, should be the global namespace in use -by the code for which the warning is issued. (This argument is used to -support displaying source for modules found in zipfiles or other -non-filesystem import sources, and was added in Python 2.5.) -\end{funcdesc} - -\begin{funcdesc}{showwarning}{message, category, filename, - lineno\optional{, file}} -Write a warning to a file. The default implementation calls -\code{formatwarning(\var{message}, \var{category}, \var{filename}, -\var{lineno})} and writes the resulting string to \var{file}, which -defaults to \code{sys.stderr}. You may replace this function with an -alternative implementation by assigning to -\code{warnings.showwarning}. -\end{funcdesc} - -\begin{funcdesc}{formatwarning}{message, category, filename, lineno} -Format a warning the standard way. This returns a string which may -contain embedded newlines and ends in a newline. -\end{funcdesc} - -\begin{funcdesc}{filterwarnings}{action\optional{, - message\optional{, category\optional{, - module\optional{, lineno\optional{, append}}}}}} -Insert an entry into the list of warnings filters. The entry is -inserted at the front by default; if \var{append} is true, it is -inserted at the end. -This checks the types of the arguments, compiles the message and -module regular expressions, and inserts them as a tuple in the -list of warnings filters. Entries closer to the front of the list -override entries later in the list, if both match a particular -warning. Omitted arguments default to a value that matches -everything. -\end{funcdesc} - -\begin{funcdesc}{simplefilter}{action\optional{, - category\optional{, - lineno\optional{, append}}}} -Insert a simple entry into the list of warnings filters. The meaning -of the function parameters is as for \function{filterwarnings()}, but -regular expressions are not needed as the filter inserted always -matches any message in any module as long as the category and line -number match. -\end{funcdesc} - -\begin{funcdesc}{resetwarnings}{} -Reset the warnings filter. This discards the effect of all previous -calls to \function{filterwarnings()}, including that of the -\programopt{-W} command line options and calls to -\function{simplefilter()}. -\end{funcdesc} diff --git a/Doc/lib/libwave.tex b/Doc/lib/libwave.tex deleted file mode 100644 index 936bbed..0000000 --- a/Doc/lib/libwave.tex +++ /dev/null @@ -1,171 +0,0 @@ -% Documentations stolen and LaTeX'ed from comments in file. -\section{\module{wave} --- - Read and write WAV files} - -\declaremodule{standard}{wave} -\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} -\modulesynopsis{Provide an interface to the WAV sound format.} - -The \module{wave} module provides a convenient interface to the WAV sound -format. It does not support compression/decompression, but it does support -mono/stereo. - -The \module{wave} module defines the following function and exception: - -\begin{funcdesc}{open}{file\optional{, mode}} -If \var{file} is a string, open the file by that name, other treat it -as a seekable file-like object. \var{mode} can be any of -\begin{description} - \item[\code{'r'}, \code{'rb'}] Read only mode. - \item[\code{'w'}, \code{'wb'}] Write only mode. -\end{description} -Note that it does not allow read/write WAV files. - -A \var{mode} of \code{'r'} or \code{'rb'} returns a \class{Wave_read} -object, while a \var{mode} of \code{'w'} or \code{'wb'} returns -a \class{Wave_write} object. If \var{mode} is omitted and a file-like -object is passed as \var{file}, \code{\var{file}.mode} is used as the -default value for \var{mode} (the \character{b} flag is still added if -necessary). -\end{funcdesc} - -\begin{funcdesc}{openfp}{file, mode} -A synonym for \function{open()}, maintained for backwards compatibility. -\end{funcdesc} - -\begin{excdesc}{Error} -An error raised when something is impossible because it violates the -WAV specification or hits an implementation deficiency. -\end{excdesc} - - -\subsection{Wave_read Objects \label{Wave-read-objects}} - -Wave_read objects, as returned by \function{open()}, have the -following methods: - -\begin{methoddesc}[Wave_read]{close}{} -Close the stream, and make the instance unusable. This is -called automatically on object collection. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{getnchannels}{} -Returns number of audio channels (\code{1} for mono, \code{2} for -stereo). -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{getsampwidth}{} -Returns sample width in bytes. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{getframerate}{} -Returns sampling frequency. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{getnframes}{} -Returns number of audio frames. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{getcomptype}{} -Returns compression type (\code{'NONE'} is the only supported type). -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{getcompname}{} -Human-readable version of \method{getcomptype()}. -Usually \code{'not compressed'} parallels \code{'NONE'}. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{getparams}{} -Returns a tuple -\code{(\var{nchannels}, \var{sampwidth}, \var{framerate}, -\var{nframes}, \var{comptype}, \var{compname})}, equivalent to output -of the \method{get*()} methods. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{readframes}{n} -Reads and returns at most \var{n} frames of audio, as a string of bytes. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{rewind}{} -Rewind the file pointer to the beginning of the audio stream. -\end{methoddesc} - -The following two methods are defined for compatibility with the -\refmodule{aifc} module, and don't do anything interesting. - -\begin{methoddesc}[Wave_read]{getmarkers}{} -Returns \code{None}. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{getmark}{id} -Raise an error. -\end{methoddesc} - -The following two methods define a term ``position'' which is compatible -between them, and is otherwise implementation dependent. - -\begin{methoddesc}[Wave_read]{setpos}{pos} -Set the file pointer to the specified position. -\end{methoddesc} - -\begin{methoddesc}[Wave_read]{tell}{} -Return current file pointer position. -\end{methoddesc} - - -\subsection{Wave_write Objects \label{Wave-write-objects}} - -Wave_write objects, as returned by \function{open()}, have the -following methods: - -\begin{methoddesc}[Wave_write]{close}{} -Make sure \var{nframes} is correct, and close the file. -This method is called upon deletion. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{setnchannels}{n} -Set the number of channels. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{setsampwidth}{n} -Set the sample width to \var{n} bytes. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{setframerate}{n} -Set the frame rate to \var{n}. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{setnframes}{n} -Set the number of frames to \var{n}. This will be changed later if -more frames are written. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{setcomptype}{type, name} -Set the compression type and description. -At the moment, only compression type \samp{NONE} is supported, -meaning no compression. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{setparams}{tuple} -The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth}, -\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with -values valid for the \method{set*()} methods. Sets all parameters. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{tell}{} -Return current position in the file, with the same disclaimer for -the \method{Wave_read.tell()} and \method{Wave_read.setpos()} -methods. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{writeframesraw}{data} -Write audio frames, without correcting \var{nframes}. -\end{methoddesc} - -\begin{methoddesc}[Wave_write]{writeframes}{data} -Write audio frames and make sure \var{nframes} is correct. -\end{methoddesc} - -Note that it is invalid to set any parameters after calling -\method{writeframes()} or \method{writeframesraw()}, and any attempt -to do so will raise \exception{wave.Error}. diff --git a/Doc/lib/libweakref.tex b/Doc/lib/libweakref.tex deleted file mode 100644 index 6f676a2..0000000 --- a/Doc/lib/libweakref.tex +++ /dev/null @@ -1,336 +0,0 @@ -\section{\module{weakref} --- - Weak references} - -\declaremodule{extension}{weakref} -\modulesynopsis{Support for weak references and weak dictionaries.} -\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\moduleauthor{Neil Schemenauer}{nas@arctrix.com} -\moduleauthor{Martin von L\"owis}{martin@loewis.home.cs.tu-berlin.de} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -\versionadded{2.1} - -% When making changes to the examples in this file, be sure to update -% Lib/test/test_weakref.py::libreftest too! - -The \module{weakref} module allows the Python programmer to create -\dfn{weak references} to objects. - -In the following, the term \dfn{referent} means the -object which is referred to by a weak reference. - -A weak reference to an object is not enough to keep the object alive: -when the only remaining references to a referent are weak references, -garbage collection is free to destroy the referent and reuse its memory -for something else. A primary use for weak references is to implement -caches or mappings holding large objects, where it's desired that a -large object not be kept alive solely because it appears in a cache or -mapping. For example, if you have a number of large binary image objects, -you may wish to associate a name with each. If you used a Python -dictionary to map names to images, or images to names, the image objects -would remain alive just because they appeared as values or keys in the -dictionaries. The \class{WeakKeyDictionary} and -\class{WeakValueDictionary} classes supplied by the \module{weakref} -module are an alternative, using weak references to construct mappings -that don't keep objects alive solely because they appear in the mapping -objects. If, for example, an image object is a value in a -\class{WeakValueDictionary}, then when the last remaining -references to that image object are the weak references held by weak -mappings, garbage collection can reclaim the object, and its corresponding -entries in weak mappings are simply deleted. - -\class{WeakKeyDictionary} and \class{WeakValueDictionary} use weak -references in their implementation, setting up callback functions on -the weak references that notify the weak dictionaries when a key or value -has been reclaimed by garbage collection. Most programs should find that -using one of these weak dictionary types is all they need -- it's -not usually necessary to create your own weak references directly. The -low-level machinery used by the weak dictionary implementations is exposed -by the \module{weakref} module for the benefit of advanced uses. - -Not all objects can be weakly referenced; those objects which can -include class instances, functions written in Python (but not in C), -methods (both bound and unbound), sets, frozensets, file objects, -generators, type objects, DBcursor objects from the \module{bsddb} module, -sockets, arrays, deques, and regular expression pattern objects. -\versionchanged[Added support for files, sockets, arrays, and patterns]{2.4} - -Several builtin types such as \class{list} and \class{dict} do not -directly support weak references but can add support through subclassing: - -\begin{verbatim} -class Dict(dict): - pass - -obj = Dict(red=1, green=2, blue=3) # this object is weak referencable -\end{verbatim} - -Extension types can easily be made to support weak references; see -``\ulink{Weak Reference Support}{../ext/weakref-support.html}'' in -\citetitle[../ext/ext.html]{Extending and Embedding the Python -Interpreter}. -% The referenced section used to appear in this document with the -% \label weakref-extension. It would be good to be able to generate a -% redirect for the corresponding HTML page (weakref-extension.html) -% for on-line versions of this document. - -\begin{classdesc}{ref}{object\optional{, callback}} - Return a weak reference to \var{object}. The original object can be - retrieved by calling the reference object if the referent is still - alive; if the referent is no longer alive, calling the reference - object will cause \constant{None} to be returned. If \var{callback} is - provided and not \constant{None}, and the returned weakref object is - still alive, the callback will be called when the object is about to be - finalized; the weak reference object will be passed as the only - parameter to the callback; the referent will no longer be available. - - It is allowable for many weak references to be constructed for the - same object. Callbacks registered for each weak reference will be - called from the most recently registered callback to the oldest - registered callback. - - Exceptions raised by the callback will be noted on the standard - error output, but cannot be propagated; they are handled in exactly - the same way as exceptions raised from an object's - \method{__del__()} method. - - Weak references are hashable if the \var{object} is hashable. They - will maintain their hash value even after the \var{object} was - deleted. If \function{hash()} is called the first time only after - the \var{object} was deleted, the call will raise - \exception{TypeError}. - - Weak references support tests for equality, but not ordering. If - the referents are still alive, two references have the same - equality relationship as their referents (regardless of the - \var{callback}). If either referent has been deleted, the - references are equal only if the reference objects are the same - object. - - \versionchanged[This is now a subclassable type rather than a - factory function; it derives from \class{object}] - {2.4} -\end{classdesc} - -\begin{funcdesc}{proxy}{object\optional{, callback}} - Return a proxy to \var{object} which uses a weak reference. This - supports use of the proxy in most contexts instead of requiring the - explicit dereferencing used with weak reference objects. The - returned object will have a type of either \code{ProxyType} or - \code{CallableProxyType}, depending on whether \var{object} is - callable. Proxy objects are not hashable regardless of the - referent; this avoids a number of problems related to their - fundamentally mutable nature, and prevent their use as dictionary - keys. \var{callback} is the same as the parameter of the same name - to the \function{ref()} function. -\end{funcdesc} - -\begin{funcdesc}{getweakrefcount}{object} - Return the number of weak references and proxies which refer to - \var{object}. -\end{funcdesc} - -\begin{funcdesc}{getweakrefs}{object} - Return a list of all weak reference and proxy objects which refer to - \var{object}. -\end{funcdesc} - -\begin{classdesc}{WeakKeyDictionary}{\optional{dict}} - Mapping class that references keys weakly. Entries in the - dictionary will be discarded when there is no longer a strong - reference to the key. This can be used to associate additional data - with an object owned by other parts of an application without adding - attributes to those objects. This can be especially useful with - objects that override attribute accesses. - - \note{Caution: Because a \class{WeakKeyDictionary} is built on top - of a Python dictionary, it must not change size when iterating - over it. This can be difficult to ensure for a - \class{WeakKeyDictionary} because actions performed by the - program during iteration may cause items in the dictionary - to vanish "by magic" (as a side effect of garbage collection).} -\end{classdesc} - -\class{WeakKeyDictionary} objects have the following additional -methods. These expose the internal references directly. The -references are not guaranteed to be ``live'' at the time they are -used, so the result of calling the references needs to be checked -before being used. This can be used to avoid creating references that -will cause the garbage collector to keep the keys around longer than -needed. - -\begin{methoddesc}{iterkeyrefs}{} - Return an iterator that yields the weak references to the keys. - \versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}{keyrefs}{} - Return a list of weak references to the keys. - \versionadded{2.5} -\end{methoddesc} - -\begin{classdesc}{WeakValueDictionary}{\optional{dict}} - Mapping class that references values weakly. Entries in the - dictionary will be discarded when no strong reference to the value - exists any more. - - \note{Caution: Because a \class{WeakValueDictionary} is built on top - of a Python dictionary, it must not change size when iterating - over it. This can be difficult to ensure for a - \class{WeakValueDictionary} because actions performed by the - program during iteration may cause items in the dictionary - to vanish "by magic" (as a side effect of garbage collection).} -\end{classdesc} - -\class{WeakValueDictionary} objects have the following additional -methods. These method have the same issues as the -\method{iterkeyrefs()} and \method{keyrefs()} methods of -\class{WeakKeyDictionary} objects. - -\begin{methoddesc}{itervaluerefs}{} - Return an iterator that yields the weak references to the values. - \versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}{valuerefs}{} - Return a list of weak references to the values. - \versionadded{2.5} -\end{methoddesc} - -\begin{datadesc}{ReferenceType} - The type object for weak references objects. -\end{datadesc} - -\begin{datadesc}{ProxyType} - The type object for proxies of objects which are not callable. -\end{datadesc} - -\begin{datadesc}{CallableProxyType} - The type object for proxies of callable objects. -\end{datadesc} - -\begin{datadesc}{ProxyTypes} - Sequence containing all the type objects for proxies. This can make - it simpler to test if an object is a proxy without being dependent - on naming both proxy types. -\end{datadesc} - -\begin{excdesc}{ReferenceError} - Exception raised when a proxy object is used but the underlying - object has been collected. This is the same as the standard - \exception{ReferenceError} exception. -\end{excdesc} - - -\begin{seealso} - \seepep{0205}{Weak References}{The proposal and rationale for this - feature, including links to earlier implementations - and information about similar features in other - languages.} -\end{seealso} - - -\subsection{Weak Reference Objects - \label{weakref-objects}} - -Weak reference objects have no attributes or methods, but do allow the -referent to be obtained, if it still exists, by calling it: - -\begin{verbatim} ->>> import weakref ->>> class Object: -... pass -... ->>> o = Object() ->>> r = weakref.ref(o) ->>> o2 = r() ->>> o is o2 -True -\end{verbatim} - -If the referent no longer exists, calling the reference object returns -\constant{None}: - -\begin{verbatim} ->>> del o, o2 ->>> print r() -None -\end{verbatim} - -Testing that a weak reference object is still live should be done -using the expression \code{\var{ref}() is not None}. Normally, -application code that needs to use a reference object should follow -this pattern: - -\begin{verbatim} -# r is a weak reference object -o = r() -if o is None: - # referent has been garbage collected - print "Object has been deallocated; can't frobnicate." -else: - print "Object is still live!" - o.do_something_useful() -\end{verbatim} - -Using a separate test for ``liveness'' creates race conditions in -threaded applications; another thread can cause a weak reference to -become invalidated before the weak reference is called; the -idiom shown above is safe in threaded applications as well as -single-threaded applications. - -Specialized versions of \class{ref} objects can be created through -subclassing. This is used in the implementation of the -\class{WeakValueDictionary} to reduce the memory overhead for each -entry in the mapping. This may be most useful to associate additional -information with a reference, but could also be used to insert -additional processing on calls to retrieve the referent. - -This example shows how a subclass of \class{ref} can be used to store -additional information about an object and affect the value that's -returned when the referent is accessed: - -\begin{verbatim} -import weakref - -class ExtendedRef(weakref.ref): - def __init__(self, ob, callback=None, **annotations): - super(ExtendedRef, self).__init__(ob, callback) - self.__counter = 0 - for k, v in annotations.iteritems(): - setattr(self, k, v) - - def __call__(self): - """Return a pair containing the referent and the number of - times the reference has been called. - """ - ob = super(ExtendedRef, self).__call__() - if ob is not None: - self.__counter += 1 - ob = (ob, self.__counter) - return ob -\end{verbatim} - - -\subsection{Example \label{weakref-example}} - -This simple example shows how an application can use objects IDs to -retrieve objects that it has seen before. The IDs of the objects can -then be used in other data structures without forcing the objects to -remain alive, but the objects can still be retrieved by ID if they -do. - -% Example contributed by Tim Peters. -\begin{verbatim} -import weakref - -_id2obj_dict = weakref.WeakValueDictionary() - -def remember(obj): - oid = id(obj) - _id2obj_dict[oid] = obj - return oid - -def id2obj(oid): - return _id2obj_dict[oid] -\end{verbatim} diff --git a/Doc/lib/libwebbrowser.tex b/Doc/lib/libwebbrowser.tex deleted file mode 100644 index 5d5f236..0000000 --- a/Doc/lib/libwebbrowser.tex +++ /dev/null @@ -1,173 +0,0 @@ -\section{\module{webbrowser} --- - Convenient Web-browser controller} - -\declaremodule{standard}{webbrowser} -\modulesynopsis{Easy-to-use controller for Web browsers.} -\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -The \module{webbrowser} module provides a high-level interface to -allow displaying Web-based documents to users. Under most -circumstances, simply calling the \function{open()} function from this -module will do the right thing. - -Under \UNIX{}, graphical browsers are preferred under X11, but text-mode -browsers will be used if graphical browsers are not available or an X11 -display isn't available. If text-mode browsers are used, the calling -process will block until the user exits the browser. - -If the environment variable \envvar{BROWSER} exists, it -is interpreted to override the platform default list of browsers, as a -os.pathsep-separated list of browsers to try in order. When the value of -a list part contains the string \code{\%s}, then it is -interpreted as a literal browser command line to be used with the argument URL -substituted for \code{\%s}; if the part does not contain -\code{\%s}, it is simply interpreted as the name of the browser to -launch. - -For non-\UNIX{} platforms, or when a remote browser is available on -\UNIX{}, the controlling process will not wait for the user to finish -with the browser, but allow the remote browser to maintain its own -windows on the display. If remote browsers are not available on \UNIX{}, -the controlling process will launch a new browser and wait. - -The script \program{webbrowser} can be used as a command-line interface -for the module. It accepts an URL as the argument. It accepts the following -optional parameters: \programopt{-n} opens the URL in a new browser window, -if possible; \programopt{-t} opens the URL in a new browser page ("tab"). The -options are, naturally, mutually exclusive. - -The following exception is defined: - -\begin{excdesc}{Error} - Exception raised when a browser control error occurs. -\end{excdesc} - -The following functions are defined: - -\begin{funcdesc}{open}{url\optional{, new=0\optional{, autoraise=1}}} - Display \var{url} using the default browser. If \var{new} is 0, the - \var{url} is opened in the same browser window if possible. If \var{new} is 1, - a new browser window is opened if possible. If \var{new} is 2, - a new browser page ("tab") is opened if possible. If \var{autoraise} is - true, the window is raised if possible (note that under many window - managers this will occur regardless of the setting of this variable). -\versionchanged[\var{new} can now be 2]{2.5} -\end{funcdesc} - -\begin{funcdesc}{open_new}{url} - Open \var{url} in a new window of the default browser, if possible, - otherwise, open \var{url} in the only browser window. -\end{funcdesc} - -\begin{funcdesc}{open_new_tab}{url} - Open \var{url} in a new page ("tab") of the default browser, if possible, - otherwise equivalent to \function{open_new}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{get}{\optional{name}} - Return a controller object for the browser type \var{name}. If - \var{name} is empty, return a controller for a default browser - appropriate to the caller's environment. -\end{funcdesc} - -\begin{funcdesc}{register}{name, constructor\optional{, instance}} - Register the browser type \var{name}. Once a browser type is - registered, the \function{get()} function can return a controller - for that browser type. If \var{instance} is not provided, or is - \code{None}, \var{constructor} will be called without parameters to - create an instance when needed. If \var{instance} is provided, - \var{constructor} will never be called, and may be \code{None}. - - This entry point is only useful if you plan to either set the - \envvar{BROWSER} variable or call \function{get} with a nonempty - argument matching the name of a handler you declare. -\end{funcdesc} - -A number of browser types are predefined. This table gives the type -names that may be passed to the \function{get()} function and the -corresponding instantiations for the controller classes, all defined -in this module. - -\begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes} - \lineiii{'mozilla'}{\class{Mozilla('mozilla')}}{} - \lineiii{'firefox'}{\class{Mozilla('mozilla')}}{} - \lineiii{'netscape'}{\class{Mozilla('netscape')}}{} - \lineiii{'galeon'}{\class{Galeon('galeon')}}{} - \lineiii{'epiphany'}{\class{Galeon('epiphany')}}{} - \lineiii{'skipstone'}{\class{BackgroundBrowser('skipstone')}}{} - \lineiii{'kfmclient'}{\class{Konqueror()}}{(1)} - \lineiii{'konqueror'}{\class{Konqueror()}}{(1)} - \lineiii{'kfm'}{\class{Konqueror()}}{(1)} - \lineiii{'mosaic'}{\class{BackgroundBrowser('mosaic')}}{} - \lineiii{'opera'}{\class{Opera()}}{} - \lineiii{'grail'}{\class{Grail()}}{} - \lineiii{'links'}{\class{GenericBrowser('links')}}{} - \lineiii{'elinks'}{\class{Elinks('elinks')}}{} - \lineiii{'lynx'}{\class{GenericBrowser('lynx')}}{} - \lineiii{'w3m'}{\class{GenericBrowser('w3m')}}{} - \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)} - \lineiii{'internet-config'}{\class{InternetConfig}}{(3)} - \lineiii{'macosx'}{\class{MacOSX('default')}}{(4)} -\end{tableiii} - -\noindent -Notes: - -\begin{description} -\item[(1)] -``Konqueror'' is the file manager for the KDE desktop environment for -\UNIX{}, and only makes sense to use if KDE is running. Some way of -reliably detecting KDE would be nice; the \envvar{KDEDIR} variable is -not sufficient. Note also that the name ``kfm'' is used even when -using the \program{konqueror} command with KDE 2 --- the -implementation selects the best strategy for running Konqueror. - -\item[(2)] -Only on Windows platforms. - -\item[(3)] -Only on MacOS platforms; requires the standard MacPython \module{ic} -module, described in the \citetitle[../mac/module-ic.html]{Macintosh -Library Modules} manual. - -\item[(4)] -Only on MacOS X platform. -\end{description} - -Here are some simple examples: - -\begin{verbatim} -url = 'http://www.python.org' - -# Open URL in a new tab, if a browser window is already open. -webbrowser.open_new_tab(url + '/doc') - -# Open URL in new window, raising the window if possible. -webbrowser.open_new(url) -\end{verbatim} - - -\subsection{Browser Controller Objects \label{browser-controllers}} - -Browser controllers provide two methods which parallel two of the -module-level convenience functions: - -\begin{methoddesc}[controller]{open}{url\optional{, new\optional{, autoraise=1}}} - Display \var{url} using the browser handled by this controller. - If \var{new} is 1, a new browser window is opened if possible. - If \var{new} is 2, a new browser page ("tab") is opened if possible. -\end{methoddesc} - -\begin{methoddesc}[controller]{open_new}{url} - Open \var{url} in a new window of the browser handled by this - controller, if possible, otherwise, open \var{url} in the only - browser window. Alias \function{open_new}. -\end{methoddesc} - -\begin{methoddesc}[controller]{open_new_tab}{url} - Open \var{url} in a new page ("tab") of the browser handled by this - controller, if possible, otherwise equivalent to \function{open_new}. -\versionadded{2.5} -\end{methoddesc} diff --git a/Doc/lib/libwhichdb.tex b/Doc/lib/libwhichdb.tex deleted file mode 100644 index 92d37e7..0000000 --- a/Doc/lib/libwhichdb.tex +++ /dev/null @@ -1,20 +0,0 @@ -\section{\module{whichdb} --- - Guess which DBM module created a database} - -\declaremodule{standard}{whichdb} -\modulesynopsis{Guess which DBM-style module created a given database.} - - -The single function in this module attempts to guess which of the -several simple database modules available--\refmodule{dbm}, -\refmodule{gdbm}, or \refmodule{dbhash}--should be used to open a -given file. - -\begin{funcdesc}{whichdb}{filename} -Returns one of the following values: \code{None} if the file can't be -opened because it's unreadable or doesn't exist; the empty string -(\code{''}) if the file's format can't be guessed; or a string -containing the required module name, such as \code{'dbm'} or -\code{'gdbm'}. -\end{funcdesc} - diff --git a/Doc/lib/libwinreg.tex b/Doc/lib/libwinreg.tex deleted file mode 100644 index d31c3ca..0000000 --- a/Doc/lib/libwinreg.tex +++ /dev/null @@ -1,414 +0,0 @@ -\section{\module{_winreg} -- - Windows registry access} - -\declaremodule[-winreg]{extension}{_winreg} - \platform{Windows} -\modulesynopsis{Routines and objects for manipulating the Windows registry.} -\sectionauthor{Mark Hammond}{MarkH@ActiveState.com} - -\versionadded{2.0} - -These functions expose the Windows registry API to Python. Instead of -using an integer as the registry handle, a handle object is used to -ensure that the handles are closed correctly, even if the programmer -neglects to explicitly close them. - -This module exposes a very low-level interface to the Windows -registry; it is expected that in the future a new \code{winreg} -module will be created offering a higher-level interface to the -registry API. - -This module offers the following functions: - - -\begin{funcdesc}{CloseKey}{hkey} - Closes a previously opened registry key. - The hkey argument specifies a previously opened key. - - Note that if \var{hkey} is not closed using this method (or via - \method{handle.Close()}), it is closed when the \var{hkey} object - is destroyed by Python. -\end{funcdesc} - - -\begin{funcdesc}{ConnectRegistry}{computer_name, key} - Establishes a connection to a predefined registry handle on - another computer, and returns a \dfn{handle object} - - \var{computer_name} is the name of the remote computer, of the - form \code{r"\e\e computername"}. If \code{None}, the local computer - is used. - - \var{key} is the predefined handle to connect to. - - The return value is the handle of the opened key. - If the function fails, an \exception{EnvironmentError} exception is - raised. -\end{funcdesc} - - -\begin{funcdesc}{CreateKey}{key, sub_key} - Creates or opens the specified key, returning a \dfn{handle object} - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - \var{sub_key} is a string that names the key this method opens - or creates. - - If \var{key} is one of the predefined keys, \var{sub_key} may - be \code{None}. In that case, the handle returned is the same key handle - passed in to the function. - - If the key already exists, this function opens the existing key. - - The return value is the handle of the opened key. - If the function fails, an \exception{EnvironmentError} exception is - raised. -\end{funcdesc} - -\begin{funcdesc}{DeleteKey}{key, sub_key} - Deletes the specified key. - - \var{key} is an already open key, or any one of the predefined - \constant{HKEY_*} constants. - - \var{sub_key} is a string that must be a subkey of the key - identified by the \var{key} parameter. This value must not be - \code{None}, and the key may not have subkeys. - - \emph{This method can not delete keys with subkeys.} - - If the method succeeds, the entire key, including all of its values, - is removed. If the method fails, an \exception{EnvironmentError} - exception is raised. -\end{funcdesc} - - -\begin{funcdesc}{DeleteValue}{key, value} - Removes a named value from a registry key. - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - \var{value} is a string that identifies the value to remove. -\end{funcdesc} - - -\begin{funcdesc}{EnumKey}{key, index} - Enumerates subkeys of an open registry key, returning a string. - - \var{key} is an already open key, or any one of the predefined - \constant{HKEY_*} constants. - - \var{index} is an integer that identifies the index of the key to - retrieve. - - The function retrieves the name of one subkey each time it - is called. It is typically called repeatedly until an - \exception{EnvironmentError} exception - is raised, indicating, no more values are available. -\end{funcdesc} - - -\begin{funcdesc}{EnumValue}{key, index} - Enumerates values of an open registry key, returning a tuple. - - \var{key} is an already open key, or any one of the predefined - \constant{HKEY_*} constants. - - \var{index} is an integer that identifies the index of the value - to retrieve. - - The function retrieves the name of one subkey each time it is - called. It is typically called repeatedly, until an - \exception{EnvironmentError} exception is raised, indicating - no more values. - - The result is a tuple of 3 items: - - \begin{tableii}{c|p{3in}}{code}{Index}{Meaning} - \lineii{0}{A string that identifies the value name} - \lineii{1}{An object that holds the value data, and whose - type depends on the underlying registry type} - \lineii{2}{An integer that identifies the type of the value data} - \end{tableii} - -\end{funcdesc} - - -\begin{funcdesc}{FlushKey}{key} - Writes all the attributes of a key to the registry. - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - It is not necessary to call RegFlushKey to change a key. - Registry changes are flushed to disk by the registry using its lazy - flusher. Registry changes are also flushed to disk at system - shutdown. Unlike \function{CloseKey()}, the \function{FlushKey()} method - returns only when all the data has been written to the registry. - An application should only call \function{FlushKey()} if it requires absolute - certainty that registry changes are on disk. - - \note{If you don't know whether a \function{FlushKey()} call is required, it - probably isn't.} - -\end{funcdesc} - - -\begin{funcdesc}{RegLoadKey}{key, sub_key, file_name} - Creates a subkey under the specified key and stores registration - information from a specified file into that subkey. - - \var{key} is an already open key, or any of the predefined - \constant{HKEY_*} constants. - - \var{sub_key} is a string that identifies the sub_key to load. - - \var {file_name} is the name of the file to load registry data from. - This file must have been created with the \function{SaveKey()} function. - Under the file allocation table (FAT) file system, the filename may not - have an extension. - - A call to LoadKey() fails if the calling process does not have the - \constant{SE_RESTORE_PRIVILEGE} privilege. Note that privileges - are different than permissions - see the Win32 documentation for - more details. - - If \var{key} is a handle returned by \function{ConnectRegistry()}, - then the path specified in \var{fileName} is relative to the - remote computer. - - The Win32 documentation implies \var{key} must be in the - \constant{HKEY_USER} or \constant{HKEY_LOCAL_MACHINE} tree. - This may or may not be true. -\end{funcdesc} - - -\begin{funcdesc}{OpenKey}{key, sub_key\optional{, res\code{ = 0}}\optional{, sam\code{ = \constant{KEY_READ}}}} - Opens the specified key, returning a \dfn{handle object} - - \var{key} is an already open key, or any one of the predefined - \constant{HKEY_*} constants. - - \var{sub_key} is a string that identifies the sub_key to open. - - \var{res} is a reserved integer, and must be zero. The default is zero. - - \var{sam} is an integer that specifies an access mask that describes - the desired security access for the key. Default is \constant{KEY_READ} - - The result is a new handle to the specified key. - - If the function fails, \exception{EnvironmentError} is raised. -\end{funcdesc} - - -\begin{funcdesc}{OpenKeyEx}{} - The functionality of \function{OpenKeyEx()} is provided via - \function{OpenKey()}, by the use of default arguments. -\end{funcdesc} - - -\begin{funcdesc}{QueryInfoKey}{key} - Returns information about a key, as a tuple. - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - The result is a tuple of 3 items: - - \begin{tableii}{c|p{3in}}{code}{Index}{Meaning} - \lineii{0}{An integer giving the number of sub keys this key has.} - \lineii{1}{An integer giving the number of values this key has.} - \lineii{2}{A long integer giving when the key was last modified (if - available) as 100's of nanoseconds since Jan 1, 1600.} - \end{tableii} -\end{funcdesc} - - -\begin{funcdesc}{QueryValue}{key, sub_key} - Retrieves the unnamed value for a key, as a string - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - \var{sub_key} is a string that holds the name of the subkey with which - the value is associated. If this parameter is \code{None} or empty, the - function retrieves the value set by the \function{SetValue()} method - for the key identified by \var{key}. - - Values in the registry have name, type, and data components. This - method retrieves the data for a key's first value that has a NULL name. - But the underlying API call doesn't return the type, Lame Lame Lame, - DO NOT USE THIS!!! -\end{funcdesc} - - -\begin{funcdesc}{QueryValueEx}{key, value_name} - Retrieves the type and data for a specified value name associated with - an open registry key. - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - \var{value_name} is a string indicating the value to query. - - The result is a tuple of 2 items: - - \begin{tableii}{c|p{3in}}{code}{Index}{Meaning} - \lineii{0}{The value of the registry item.} - \lineii{1}{An integer giving the registry type for this value.} - \end{tableii} -\end{funcdesc} - - -\begin{funcdesc}{SaveKey}{key, file_name} - Saves the specified key, and all its subkeys to the specified file. - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - \var{file_name} is the name of the file to save registry data to. - This file cannot already exist. If this filename includes an extension, - it cannot be used on file allocation table (FAT) file systems by the - \method{LoadKey()}, \method{ReplaceKey()} or - \method{RestoreKey()} methods. - - If \var{key} represents a key on a remote computer, the path - described by \var{file_name} is relative to the remote computer. - The caller of this method must possess the \constant{SeBackupPrivilege} - security privilege. Note that privileges are different than permissions - - see the Win32 documentation for more details. - - This function passes NULL for \var{security_attributes} to the API. -\end{funcdesc} - - -\begin{funcdesc}{SetValue}{key, sub_key, type, value} - Associates a value with a specified key. - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - \var{sub_key} is a string that names the subkey with which the value - is associated. - - \var{type} is an integer that specifies the type of the data. - Currently this must be \constant{REG_SZ}, meaning only strings are - supported. Use the \function{SetValueEx()} function for support for - other data types. - - \var{value} is a string that specifies the new value. - - If the key specified by the \var{sub_key} parameter does not exist, - the SetValue function creates it. - - Value lengths are limited by available memory. Long values (more than - 2048 bytes) should be stored as files with the filenames stored in - the configuration registry. This helps the registry perform - efficiently. - - The key identified by the \var{key} parameter must have been - opened with \constant{KEY_SET_VALUE} access. -\end{funcdesc} - - -\begin{funcdesc}{SetValueEx}{key, value_name, reserved, type, value} - Stores data in the value field of an open registry key. - - \var{key} is an already open key, or one of the predefined - \constant{HKEY_*} constants. - - \var{value_name} is a string that names the subkey with which the - value is associated. - - \var{type} is an integer that specifies the type of the data. - This should be one of the following constants defined in this module: - - \begin{tableii}{l|p{3in}}{constant}{Constant}{Meaning} - \lineii{REG_BINARY}{Binary data in any form.} - \lineii{REG_DWORD}{A 32-bit number.} - \lineii{REG_DWORD_LITTLE_ENDIAN}{A 32-bit number in little-endian format.} - \lineii{REG_DWORD_BIG_ENDIAN}{A 32-bit number in big-endian format.} - \lineii{REG_EXPAND_SZ}{Null-terminated string containing references - to environment variables (\samp{\%PATH\%}).} - \lineii{REG_LINK}{A Unicode symbolic link.} - \lineii{REG_MULTI_SZ}{A sequence of null-terminated strings, - terminated by two null characters. (Python handles - this termination automatically.)} - \lineii{REG_NONE}{No defined value type.} - \lineii{REG_RESOURCE_LIST}{A device-driver resource list.} - \lineii{REG_SZ}{A null-terminated string.} - \end{tableii} - - \var{reserved} can be anything - zero is always passed to the - API. - - \var{value} is a string that specifies the new value. - - This method can also set additional value and type information for the - specified key. The key identified by the key parameter must have been - opened with \constant{KEY_SET_VALUE} access. - - To open the key, use the \function{CreateKeyEx()} or - \function{OpenKey()} methods. - - Value lengths are limited by available memory. Long values (more than - 2048 bytes) should be stored as files with the filenames stored in - the configuration registry. This helps the registry perform efficiently. -\end{funcdesc} - - - -\subsection{Registry Handle Objects \label{handle-object}} - - This object wraps a Windows HKEY object, automatically closing it when - the object is destroyed. To guarantee cleanup, you can call either - the \method{Close()} method on the object, or the - \function{CloseKey()} function. - - All registry functions in this module return one of these objects. - - All registry functions in this module which accept a handle object - also accept an integer, however, use of the handle object is - encouraged. - - Handle objects provide semantics for \method{__bool__()} - thus -\begin{verbatim} - if handle: - print "Yes" -\end{verbatim} - will print \code{Yes} if the handle is currently valid (has not been - closed or detached). - - The object also support comparison semantics, so handle - objects will compare true if they both reference the same - underlying Windows handle value. - - Handle objects can be converted to an integer (e.g., using the - builtin \function{int()} function), in which case the underlying - Windows handle value is returned. You can also use the - \method{Detach()} method to return the integer handle, and - also disconnect the Windows handle from the handle object. - -\begin{methoddesc}[PyHKEY]{Close}{} - Closes the underlying Windows handle. - - If the handle is already closed, no error is raised. -\end{methoddesc} - - -\begin{methoddesc}[PyHKEY]{Detach}{} - Detaches the Windows handle from the handle object. - - The result is an integer (or long on 64 bit Windows) that holds - the value of the handle before it is detached. If the - handle is already detached or closed, this will return zero. - - After calling this function, the handle is effectively invalidated, - but the handle is not closed. You would call this function when - you need the underlying Win32 handle to exist beyond the lifetime - of the handle object. -\end{methoddesc} diff --git a/Doc/lib/libwinsound.tex b/Doc/lib/libwinsound.tex deleted file mode 100644 index 5f5b15e..0000000 --- a/Doc/lib/libwinsound.tex +++ /dev/null @@ -1,142 +0,0 @@ -\section{\module{winsound} --- - Sound-playing interface for Windows} - -\declaremodule{builtin}{winsound} - \platform{Windows} -\modulesynopsis{Access to the sound-playing machinery for Windows.} -\moduleauthor{Toby Dickenson}{htrd90@zepler.org} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -\versionadded{1.5.2} - -The \module{winsound} module provides access to the basic -sound-playing machinery provided by Windows platforms. It includes -functions and several constants. - - -\begin{funcdesc}{Beep}{frequency, duration} - Beep the PC's speaker. - The \var{frequency} parameter specifies frequency, in hertz, of the - sound, and must be in the range 37 through 32,767. - The \var{duration} parameter specifies the number of milliseconds the - sound should last. If the system is not - able to beep the speaker, \exception{RuntimeError} is raised. - \note{Under Windows 95 and 98, the Windows \cfunction{Beep()} - function exists but is useless (it ignores its arguments). In that - case Python simulates it via direct port manipulation (added in version - 2.1). It's unknown whether that will work on all systems.} - \versionadded{1.6} -\end{funcdesc} - -\begin{funcdesc}{PlaySound}{sound, flags} - Call the underlying \cfunction{PlaySound()} function from the - Platform API. The \var{sound} parameter may be a filename, audio - data as a string, or \code{None}. Its interpretation depends on the - value of \var{flags}, which can be a bit-wise ORed combination of - the constants described below. If the system indicates an error, - \exception{RuntimeError} is raised. -\end{funcdesc} - -\begin{funcdesc}{MessageBeep}{\optional{type=\code{MB_OK}}} - Call the underlying \cfunction{MessageBeep()} function from the - Platform API. This plays a sound as specified in the registry. The - \var{type} argument specifies which sound to play; possible values - are \code{-1}, \code{MB_ICONASTERISK}, \code{MB_ICONEXCLAMATION}, - \code{MB_ICONHAND}, \code{MB_ICONQUESTION}, and \code{MB_OK}, all - described below. The value \code{-1} produces a ``simple beep''; - this is the final fallback if a sound cannot be played otherwise. - \versionadded{2.3} -\end{funcdesc} - -\begin{datadesc}{SND_FILENAME} - The \var{sound} parameter is the name of a WAV file. - Do not use with \constant{SND_ALIAS}. -\end{datadesc} - -\begin{datadesc}{SND_ALIAS} - The \var{sound} parameter is a sound association name from the - registry. If the registry contains no such name, play the system - default sound unless \constant{SND_NODEFAULT} is also specified. - If no default sound is registered, raise \exception{RuntimeError}. - Do not use with \constant{SND_FILENAME}. - - All Win32 systems support at least the following; most systems support - many more: - -\begin{tableii}{l|l}{code} - {\function{PlaySound()} \var{name}} - {Corresponding Control Panel Sound name} - \lineii{'SystemAsterisk'} {Asterisk} - \lineii{'SystemExclamation'}{Exclamation} - \lineii{'SystemExit'} {Exit Windows} - \lineii{'SystemHand'} {Critical Stop} - \lineii{'SystemQuestion'} {Question} -\end{tableii} - - For example: - -\begin{verbatim} -import winsound -# Play Windows exit sound. -winsound.PlaySound("SystemExit", winsound.SND_ALIAS) - -# Probably play Windows default sound, if any is registered (because -# "*" probably isn't the registered name of any sound). -winsound.PlaySound("*", winsound.SND_ALIAS) -\end{verbatim} -\end{datadesc} - -\begin{datadesc}{SND_LOOP} - Play the sound repeatedly. The \constant{SND_ASYNC} flag must also - be used to avoid blocking. Cannot be used with \constant{SND_MEMORY}. -\end{datadesc} - -\begin{datadesc}{SND_MEMORY} - The \var{sound} parameter to \function{PlaySound()} is a memory - image of a WAV file, as a string. - - \note{This module does not support playing from a memory - image asynchronously, so a combination of this flag and - \constant{SND_ASYNC} will raise \exception{RuntimeError}.} -\end{datadesc} - -\begin{datadesc}{SND_PURGE} - Stop playing all instances of the specified sound. -\end{datadesc} - -\begin{datadesc}{SND_ASYNC} - Return immediately, allowing sounds to play asynchronously. -\end{datadesc} - -\begin{datadesc}{SND_NODEFAULT} - If the specified sound cannot be found, do not play the system default - sound. -\end{datadesc} - -\begin{datadesc}{SND_NOSTOP} - Do not interrupt sounds currently playing. -\end{datadesc} - -\begin{datadesc}{SND_NOWAIT} - Return immediately if the sound driver is busy. -\end{datadesc} - -\begin{datadesc}{MB_ICONASTERISK} - Play the \code{SystemDefault} sound. -\end{datadesc} - -\begin{datadesc}{MB_ICONEXCLAMATION} - Play the \code{SystemExclamation} sound. -\end{datadesc} - -\begin{datadesc}{MB_ICONHAND} - Play the \code{SystemHand} sound. -\end{datadesc} - -\begin{datadesc}{MB_ICONQUESTION} - Play the \code{SystemQuestion} sound. -\end{datadesc} - -\begin{datadesc}{MB_OK} - Play the \code{SystemDefault} sound. -\end{datadesc} diff --git a/Doc/lib/libwsgiref.tex b/Doc/lib/libwsgiref.tex deleted file mode 100755 index 37ded9f..0000000 --- a/Doc/lib/libwsgiref.tex +++ /dev/null @@ -1,782 +0,0 @@ -\section{\module{wsgiref} --- WSGI Utilities and Reference -Implementation} -\declaremodule{}{wsgiref} -\moduleauthor{Phillip J. Eby}{pje@telecommunity.com} -\sectionauthor{Phillip J. Eby}{pje@telecommunity.com} -\modulesynopsis{WSGI Utilities and Reference Implementation} - -\versionadded{2.5} - -The Web Server Gateway Interface (WSGI) is a standard interface -between web server software and web applications written in Python. -Having a standard interface makes it easy to use an application -that supports WSGI with a number of different web servers. - -Only authors of web servers and programming frameworks need to know -every detail and corner case of the WSGI design. You don't need to -understand every detail of WSGI just to install a WSGI application or -to write a web application using an existing framework. - -\module{wsgiref} is a reference implementation of the WSGI specification -that can be used to add WSGI support to a web server or framework. It -provides utilities for manipulating WSGI environment variables and -response headers, base classes for implementing WSGI servers, a demo -HTTP server that serves WSGI applications, and a validation tool that -checks WSGI servers and applications for conformance to the -WSGI specification (\pep{333}). - -% XXX If you're just trying to write a web application... - -See \url{http://www.wsgi.org} for more information about WSGI, -and links to tutorials and other resources. - - - - - - - - - - - - - -\subsection{\module{wsgiref.util} -- WSGI environment utilities} -\declaremodule{}{wsgiref.util} - -This module provides a variety of utility functions for working with -WSGI environments. A WSGI environment is a dictionary containing -HTTP request variables as described in \pep{333}. All of the functions -taking an \var{environ} parameter expect a WSGI-compliant dictionary to -be supplied; please see \pep{333} for a detailed specification. - -\begin{funcdesc}{guess_scheme}{environ} -Return a guess for whether \code{wsgi.url_scheme} should be ``http'' or -``https'', by checking for a \code{HTTPS} environment variable in the -\var{environ} dictionary. The return value is a string. - -This function is useful when creating a gateway that wraps CGI or a -CGI-like protocol such as FastCGI. Typically, servers providing such -protocols will include a \code{HTTPS} variable with a value of ``1'' -``yes'', or ``on'' when a request is received via SSL. So, this -function returns ``https'' if such a value is found, and ``http'' -otherwise. -\end{funcdesc} - -\begin{funcdesc}{request_uri}{environ \optional{, include_query=1}} -Return the full request URI, optionally including the query string, -using the algorithm found in the ``URL Reconstruction'' section of -\pep{333}. If \var{include_query} is false, the query string is -not included in the resulting URI. -\end{funcdesc} - -\begin{funcdesc}{application_uri}{environ} -Similar to \function{request_uri}, except that the \code{PATH_INFO} and -\code{QUERY_STRING} variables are ignored. The result is the base URI -of the application object addressed by the request. -\end{funcdesc} - -\begin{funcdesc}{shift_path_info}{environ} -Shift a single name from \code{PATH_INFO} to \code{SCRIPT_NAME} and -return the name. The \var{environ} dictionary is \emph{modified} -in-place; use a copy if you need to keep the original \code{PATH_INFO} -or \code{SCRIPT_NAME} intact. - -If there are no remaining path segments in \code{PATH_INFO}, \code{None} -is returned. - -Typically, this routine is used to process each portion of a request -URI path, for example to treat the path as a series of dictionary keys. -This routine modifies the passed-in environment to make it suitable for -invoking another WSGI application that is located at the target URI. -For example, if there is a WSGI application at \code{/foo}, and the -request URI path is \code{/foo/bar/baz}, and the WSGI application at -\code{/foo} calls \function{shift_path_info}, it will receive the string -``bar'', and the environment will be updated to be suitable for passing -to a WSGI application at \code{/foo/bar}. That is, \code{SCRIPT_NAME} -will change from \code{/foo} to \code{/foo/bar}, and \code{PATH_INFO} -will change from \code{/bar/baz} to \code{/baz}. - -When \code{PATH_INFO} is just a ``/'', this routine returns an empty -string and appends a trailing slash to \code{SCRIPT_NAME}, even though -empty path segments are normally ignored, and \code{SCRIPT_NAME} doesn't -normally end in a slash. This is intentional behavior, to ensure that -an application can tell the difference between URIs ending in \code{/x} -from ones ending in \code{/x/} when using this routine to do object -traversal. - -\end{funcdesc} - -\begin{funcdesc}{setup_testing_defaults}{environ} -Update \var{environ} with trivial defaults for testing purposes. - -This routine adds various parameters required for WSGI, including -\code{HTTP_HOST}, \code{SERVER_NAME}, \code{SERVER_PORT}, -\code{REQUEST_METHOD}, \code{SCRIPT_NAME}, \code{PATH_INFO}, and all of -the \pep{333}-defined \code{wsgi.*} variables. It only supplies default -values, and does not replace any existing settings for these variables. - -This routine is intended to make it easier for unit tests of WSGI -servers and applications to set up dummy environments. It should NOT -be used by actual WSGI servers or applications, since the data is fake! -\end{funcdesc} - - - -In addition to the environment functions above, the -\module{wsgiref.util} module also provides these miscellaneous -utilities: - -\begin{funcdesc}{is_hop_by_hop}{header_name} -Return true if 'header_name' is an HTTP/1.1 ``Hop-by-Hop'' header, as -defined by \rfc{2616}. -\end{funcdesc} - -\begin{classdesc}{FileWrapper}{filelike \optional{, blksize=8192}} -A wrapper to convert a file-like object to an iterator. The resulting -objects support both \method{__getitem__} and \method{__iter__} -iteration styles, for compatibility with Python 2.1 and Jython. -As the object is iterated over, the optional \var{blksize} parameter -will be repeatedly passed to the \var{filelike} object's \method{read()} -method to obtain strings to yield. When \method{read()} returns an -empty string, iteration is ended and is not resumable. - -If \var{filelike} has a \method{close()} method, the returned object -will also have a \method{close()} method, and it will invoke the -\var{filelike} object's \method{close()} method when called. -\end{classdesc} - - - - - - - - - - - - - - - - - - - -\subsection{\module{wsgiref.headers} -- WSGI response header tools} -\declaremodule{}{wsgiref.headers} - -This module provides a single class, \class{Headers}, for convenient -manipulation of WSGI response headers using a mapping-like interface. - -\begin{classdesc}{Headers}{headers} -Create a mapping-like object wrapping \var{headers}, which must be a -list of header name/value tuples as described in \pep{333}. Any changes -made to the new \class{Headers} object will directly update the -\var{headers} list it was created with. - -\class{Headers} objects support typical mapping operations including -\method{__getitem__}, \method{get}, \method{__setitem__}, -\method{setdefault}, \method{__delitem__}, \method{__contains__} and -\method{has_key}. For each of these methods, the key is the header name -(treated case-insensitively), and the value is the first value -associated with that header name. Setting a header deletes any existing -values for that header, then adds a new value at the end of the wrapped -header list. Headers' existing order is generally maintained, with new -headers added to the end of the wrapped list. - -Unlike a dictionary, \class{Headers} objects do not raise an error when -you try to get or delete a key that isn't in the wrapped header list. -Getting a nonexistent header just returns \code{None}, and deleting -a nonexistent header does nothing. - -\class{Headers} objects also support \method{keys()}, \method{values()}, -and \method{items()} methods. The lists returned by \method{keys()} -and \method{items()} can include the same key more than once if there -is a multi-valued header. The \code{len()} of a \class{Headers} object -is the same as the length of its \method{items()}, which is the same -as the length of the wrapped header list. In fact, the \method{items()} -method just returns a copy of the wrapped header list. - -Calling \code{str()} on a \class{Headers} object returns a formatted -string suitable for transmission as HTTP response headers. Each header -is placed on a line with its value, separated by a colon and a space. -Each line is terminated by a carriage return and line feed, and the -string is terminated with a blank line. - -In addition to their mapping interface and formatting features, -\class{Headers} objects also have the following methods for querying -and adding multi-valued headers, and for adding headers with MIME -parameters: - -\begin{methoddesc}{get_all}{name} -Return a list of all the values for the named header. - -The returned list will be sorted in the order they appeared in the -original header list or were added to this instance, and may contain -duplicates. Any fields deleted and re-inserted are always appended to -the header list. If no fields exist with the given name, returns an -empty list. -\end{methoddesc} - - -\begin{methoddesc}{add_header}{name, value, **_params} -Add a (possibly multi-valued) header, with optional MIME parameters -specified via keyword arguments. - -\var{name} is the header field to add. Keyword arguments can be used to -set MIME parameters for the header field. Each parameter must be a -string or \code{None}. Underscores in parameter names are converted to -dashes, since dashes are illegal in Python identifiers, but many MIME -parameter names include dashes. If the parameter value is a string, it -is added to the header value parameters in the form \code{name="value"}. -If it is \code{None}, only the parameter name is added. (This is used -for MIME parameters without a value.) Example usage: - -\begin{verbatim} -h.add_header('content-disposition', 'attachment', filename='bud.gif') -\end{verbatim} - -The above will add a header that looks like this: - -\begin{verbatim} -Content-Disposition: attachment; filename="bud.gif" -\end{verbatim} -\end{methoddesc} -\end{classdesc} - -\subsection{\module{wsgiref.simple_server} -- a simple WSGI HTTP server} -\declaremodule[wsgiref.simpleserver]{}{wsgiref.simple_server} - -This module implements a simple HTTP server (based on -\module{BaseHTTPServer}) that serves WSGI applications. Each server -instance serves a single WSGI application on a given host and port. If -you want to serve multiple applications on a single host and port, you -should create a WSGI application that parses \code{PATH_INFO} to select -which application to invoke for each request. (E.g., using the -\function{shift_path_info()} function from \module{wsgiref.util}.) - - -\begin{funcdesc}{make_server}{host, port, app -\optional{, server_class=\class{WSGIServer} \optional{, -handler_class=\class{WSGIRequestHandler}}}} -Create a new WSGI server listening on \var{host} and \var{port}, -accepting connections for \var{app}. The return value is an instance of -the supplied \var{server_class}, and will process requests using the -specified \var{handler_class}. \var{app} must be a WSGI application -object, as defined by \pep{333}. - -Example usage: -\begin{verbatim}from wsgiref.simple_server import make_server, demo_app - -httpd = make_server('', 8000, demo_app) -print "Serving HTTP on port 8000..." - -# Respond to requests until process is killed -httpd.serve_forever() - -# Alternative: serve one request, then exit -##httpd.handle_request() -\end{verbatim} - -\end{funcdesc} - - - - - - -\begin{funcdesc}{demo_app}{environ, start_response} -This function is a small but complete WSGI application that -returns a text page containing the message ``Hello world!'' -and a list of the key/value pairs provided in the -\var{environ} parameter. It's useful for verifying that a WSGI server -(such as \module{wsgiref.simple_server}) is able to run a simple WSGI -application correctly. -\end{funcdesc} - - -\begin{classdesc}{WSGIServer}{server_address, RequestHandlerClass} -Create a \class{WSGIServer} instance. \var{server_address} should be -a \code{(host,port)} tuple, and \var{RequestHandlerClass} should be -the subclass of \class{BaseHTTPServer.BaseHTTPRequestHandler} that will -be used to process requests. - -You do not normally need to call this constructor, as the -\function{make_server()} function can handle all the details for you. - -\class{WSGIServer} is a subclass -of \class{BaseHTTPServer.HTTPServer}, so all of its methods (such as -\method{serve_forever()} and \method{handle_request()}) are available. -\class{WSGIServer} also provides these WSGI-specific methods: - -\begin{methoddesc}{set_app}{application} -Sets the callable \var{application} as the WSGI application that will -receive requests. -\end{methoddesc} - -\begin{methoddesc}{get_app}{} -Returns the currently-set application callable. -\end{methoddesc} - -Normally, however, you do not need to use these additional methods, as -\method{set_app()} is normally called by \function{make_server()}, and -the \method{get_app()} exists mainly for the benefit of request handler -instances. -\end{classdesc} - - - -\begin{classdesc}{WSGIRequestHandler}{request, client_address, server} -Create an HTTP handler for the given \var{request} (i.e. a socket), -\var{client_address} (a \code{(\var{host},\var{port})} tuple), and -\var{server} (\class{WSGIServer} instance). - -You do not need to create instances of this class directly; they are -automatically created as needed by \class{WSGIServer} objects. You -can, however, subclass this class and supply it as a \var{handler_class} -to the \function{make_server()} function. Some possibly relevant -methods for overriding in subclasses: - -\begin{methoddesc}{get_environ}{} -Returns a dictionary containing the WSGI environment for a request. The -default implementation copies the contents of the \class{WSGIServer} -object's \member{base_environ} dictionary attribute and then adds -various headers derived from the HTTP request. Each call to this method -should return a new dictionary containing all of the relevant CGI -environment variables as specified in \pep{333}. -\end{methoddesc} - -\begin{methoddesc}{get_stderr}{} -Return the object that should be used as the \code{wsgi.errors} stream. -The default implementation just returns \code{sys.stderr}. -\end{methoddesc} - -\begin{methoddesc}{handle}{} -Process the HTTP request. The default implementation creates a handler -instance using a \module{wsgiref.handlers} class to implement the actual -WSGI application interface. -\end{methoddesc} - -\end{classdesc} - - - - - - - - - -\subsection{\module{wsgiref.validate} -- WSGI conformance checker} -\declaremodule{}{wsgiref.validate} -When creating new WSGI application objects, frameworks, servers, or -middleware, it can be useful to validate the new code's conformance -using \module{wsgiref.validate}. This module provides a function that -creates WSGI application objects that validate communications between -a WSGI server or gateway and a WSGI application object, to check both -sides for protocol conformance. - -Note that this utility does not guarantee complete \pep{333} compliance; -an absence of errors from this module does not necessarily mean that -errors do not exist. However, if this module does produce an error, -then it is virtually certain that either the server or application is -not 100\% compliant. - -This module is based on the \module{paste.lint} module from Ian -Bicking's ``Python Paste'' library. - -\begin{funcdesc}{validator}{application} -Wrap \var{application} and return a new WSGI application object. The -returned application will forward all requests to the original -\var{application}, and will check that both the \var{application} and -the server invoking it are conforming to the WSGI specification and to -RFC 2616. - -Any detected nonconformance results in an \exception{AssertionError} -being raised; note, however, that how these errors are handled is -server-dependent. For example, \module{wsgiref.simple_server} and other -servers based on \module{wsgiref.handlers} (that don't override the -error handling methods to do something else) will simply output a -message that an error has occurred, and dump the traceback to -\code{sys.stderr} or some other error stream. - -This wrapper may also generate output using the \module{warnings} module -to indicate behaviors that are questionable but which may not actually -be prohibited by \pep{333}. Unless they are suppressed using Python -command-line options or the \module{warnings} API, any such warnings -will be written to \code{sys.stderr} (\emph{not} \code{wsgi.errors}, -unless they happen to be the same object). -\end{funcdesc} - -\subsection{\module{wsgiref.handlers} -- server/gateway base classes} -\declaremodule{}{wsgiref.handlers} - -This module provides base handler classes for implementing WSGI servers -and gateways. These base classes handle most of the work of -communicating with a WSGI application, as long as they are given a -CGI-like environment, along with input, output, and error streams. - - -\begin{classdesc}{CGIHandler}{} -CGI-based invocation via \code{sys.stdin}, \code{sys.stdout}, -\code{sys.stderr} and \code{os.environ}. This is useful when you have -a WSGI application and want to run it as a CGI script. Simply invoke -\code{CGIHandler().run(app)}, where \code{app} is the WSGI application -object you wish to invoke. - -This class is a subclass of \class{BaseCGIHandler} that sets -\code{wsgi.run_once} to true, \code{wsgi.multithread} to false, and -\code{wsgi.multiprocess} to true, and always uses \module{sys} and -\module{os} to obtain the necessary CGI streams and environment. -\end{classdesc} - - -\begin{classdesc}{BaseCGIHandler}{stdin, stdout, stderr, environ -\optional{, multithread=True \optional{, multiprocess=False}}} - -Similar to \class{CGIHandler}, but instead of using the \module{sys} and -\module{os} modules, the CGI environment and I/O streams are specified -explicitly. The \var{multithread} and \var{multiprocess} values are -used to set the \code{wsgi.multithread} and \code{wsgi.multiprocess} -flags for any applications run by the handler instance. - -This class is a subclass of \class{SimpleHandler} intended for use with -software other than HTTP ``origin servers''. If you are writing a -gateway protocol implementation (such as CGI, FastCGI, SCGI, etc.) that -uses a \code{Status:} header to send an HTTP status, you probably want -to subclass this instead of \class{SimpleHandler}. -\end{classdesc} - - - -\begin{classdesc}{SimpleHandler}{stdin, stdout, stderr, environ -\optional{,multithread=True \optional{, multiprocess=False}}} - -Similar to \class{BaseCGIHandler}, but designed for use with HTTP origin -servers. If you are writing an HTTP server implementation, you will -probably want to subclass this instead of \class{BaseCGIHandler} - -This class is a subclass of \class{BaseHandler}. It overrides the -\method{__init__()}, \method{get_stdin()}, \method{get_stderr()}, -\method{add_cgi_vars()}, \method{_write()}, and \method{_flush()} -methods to support explicitly setting the environment and streams via -the constructor. The supplied environment and streams are stored in -the \member{stdin}, \member{stdout}, \member{stderr}, and -\member{environ} attributes. -\end{classdesc} - -\begin{classdesc}{BaseHandler}{} -This is an abstract base class for running WSGI applications. Each -instance will handle a single HTTP request, although in principle you -could create a subclass that was reusable for multiple requests. - -\class{BaseHandler} instances have only one method intended for external -use: - -\begin{methoddesc}{run}{app} -Run the specified WSGI application, \var{app}. -\end{methoddesc} - -All of the other \class{BaseHandler} methods are invoked by this method -in the process of running the application, and thus exist primarily to -allow customizing the process. - -The following methods MUST be overridden in a subclass: - -\begin{methoddesc}{_write}{data} -Buffer the string \var{data} for transmission to the client. It's okay -if this method actually transmits the data; \class{BaseHandler} -just separates write and flush operations for greater efficiency -when the underlying system actually has such a distinction. -\end{methoddesc} - -\begin{methoddesc}{_flush}{} -Force buffered data to be transmitted to the client. It's okay if this -method is a no-op (i.e., if \method{_write()} actually sends the data). -\end{methoddesc} - -\begin{methoddesc}{get_stdin}{} -Return an input stream object suitable for use as the \code{wsgi.input} -of the request currently being processed. -\end{methoddesc} - -\begin{methoddesc}{get_stderr}{} -Return an output stream object suitable for use as the -\code{wsgi.errors} of the request currently being processed. -\end{methoddesc} - -\begin{methoddesc}{add_cgi_vars}{} -Insert CGI variables for the current request into the \member{environ} -attribute. -\end{methoddesc} - -Here are some other methods and attributes you may wish to override. -This list is only a summary, however, and does not include every method -that can be overridden. You should consult the docstrings and source -code for additional information before attempting to create a customized -\class{BaseHandler} subclass. - - - - - - - - - - - - - - - - -Attributes and methods for customizing the WSGI environment: - -\begin{memberdesc}{wsgi_multithread} -The value to be used for the \code{wsgi.multithread} environment -variable. It defaults to true in \class{BaseHandler}, but may have -a different default (or be set by the constructor) in the other -subclasses. -\end{memberdesc} - -\begin{memberdesc}{wsgi_multiprocess} -The value to be used for the \code{wsgi.multiprocess} environment -variable. It defaults to true in \class{BaseHandler}, but may have -a different default (or be set by the constructor) in the other -subclasses. -\end{memberdesc} - -\begin{memberdesc}{wsgi_run_once} -The value to be used for the \code{wsgi.run_once} environment -variable. It defaults to false in \class{BaseHandler}, but -\class{CGIHandler} sets it to true by default. -\end{memberdesc} - -\begin{memberdesc}{os_environ} -The default environment variables to be included in every request's -WSGI environment. By default, this is a copy of \code{os.environ} at -the time that \module{wsgiref.handlers} was imported, but subclasses can -either create their own at the class or instance level. Note that the -dictionary should be considered read-only, since the default value is -shared between multiple classes and instances. -\end{memberdesc} - -\begin{memberdesc}{server_software} -If the \member{origin_server} attribute is set, this attribute's value -is used to set the default \code{SERVER_SOFTWARE} WSGI environment -variable, and also to set a default \code{Server:} header in HTTP -responses. It is ignored for handlers (such as \class{BaseCGIHandler} -and \class{CGIHandler}) that are not HTTP origin servers. -\end{memberdesc} - - - -\begin{methoddesc}{get_scheme}{} -Return the URL scheme being used for the current request. The default -implementation uses the \function{guess_scheme()} function from -\module{wsgiref.util} to guess whether the scheme should be ``http'' or -``https'', based on the current request's \member{environ} variables. -\end{methoddesc} - -\begin{methoddesc}{setup_environ}{} -Set the \member{environ} attribute to a fully-populated WSGI -environment. The default implementation uses all of the above methods -and attributes, plus the \method{get_stdin()}, \method{get_stderr()}, -and \method{add_cgi_vars()} methods and the \member{wsgi_file_wrapper} -attribute. It also inserts a \code{SERVER_SOFTWARE} key if not present, -as long as the \member{origin_server} attribute is a true value and the -\member{server_software} attribute is set. -\end{methoddesc} - - - - - - - - - - - - - - - - - - - - - - - - - -Methods and attributes for customizing exception handling: - -\begin{methoddesc}{log_exception}{exc_info} -Log the \var{exc_info} tuple in the server log. \var{exc_info} is a -\code{(\var{type}, \var{value}, \var{traceback})} tuple. The default -implementation simply writes the traceback to the request's -\code{wsgi.errors} stream and flushes it. Subclasses can override this -method to change the format or retarget the output, mail the traceback -to an administrator, or whatever other action may be deemed suitable. -\end{methoddesc} - -\begin{memberdesc}{traceback_limit} -The maximum number of frames to include in tracebacks output by the -default \method{log_exception()} method. If \code{None}, all frames -are included. -\end{memberdesc} - -\begin{methoddesc}{error_output}{environ, start_response} -This method is a WSGI application to generate an error page for the -user. It is only invoked if an error occurs before headers are sent -to the client. - -This method can access the current error information using -\code{sys.exc_info()}, and should pass that information to -\var{start_response} when calling it (as described in the ``Error -Handling'' section of \pep{333}). - -The default implementation just uses the \member{error_status}, -\member{error_headers}, and \member{error_body} attributes to generate -an output page. Subclasses can override this to produce more dynamic -error output. - -Note, however, that it's not recommended from a security perspective to -spit out diagnostics to any old user; ideally, you should have to do -something special to enable diagnostic output, which is why the default -implementation doesn't include any. -\end{methoddesc} - - - - -\begin{memberdesc}{error_status} -The HTTP status used for error responses. This should be a status -string as defined in \pep{333}; it defaults to a 500 code and message. -\end{memberdesc} - -\begin{memberdesc}{error_headers} -The HTTP headers used for error responses. This should be a list of -WSGI response headers (\code{(\var{name}, \var{value})} tuples), as -described in \pep{333}. The default list just sets the content type -to \code{text/plain}. -\end{memberdesc} - -\begin{memberdesc}{error_body} -The error response body. This should be an HTTP response body string. -It defaults to the plain text, ``A server error occurred. Please -contact the administrator.'' -\end{memberdesc} - - - - - - - - - - - - - - - - - - - - - - - - -Methods and attributes for \pep{333}'s ``Optional Platform-Specific File -Handling'' feature: - -\begin{memberdesc}{wsgi_file_wrapper} -A \code{wsgi.file_wrapper} factory, or \code{None}. The default value -of this attribute is the \class{FileWrapper} class from -\module{wsgiref.util}. -\end{memberdesc} - -\begin{methoddesc}{sendfile}{} -Override to implement platform-specific file transmission. This method -is called only if the application's return value is an instance of -the class specified by the \member{wsgi_file_wrapper} attribute. It -should return a true value if it was able to successfully transmit the -file, so that the default transmission code will not be executed. -The default implementation of this method just returns a false value. -\end{methoddesc} - - -Miscellaneous methods and attributes: - -\begin{memberdesc}{origin_server} -This attribute should be set to a true value if the handler's -\method{_write()} and \method{_flush()} are being used to communicate -directly to the client, rather than via a CGI-like gateway protocol that -wants the HTTP status in a special \code{Status:} header. - -This attribute's default value is true in \class{BaseHandler}, but -false in \class{BaseCGIHandler} and \class{CGIHandler}. -\end{memberdesc} - -\begin{memberdesc}{http_version} -If \member{origin_server} is true, this string attribute is used to -set the HTTP version of the response set to the client. It defaults to -\code{"1.0"}. -\end{memberdesc} - - - - - -\end{classdesc} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/Doc/lib/libxdrlib.tex b/Doc/lib/libxdrlib.tex deleted file mode 100644 index 56474b7..0000000 --- a/Doc/lib/libxdrlib.tex +++ /dev/null @@ -1,251 +0,0 @@ -\section{\module{xdrlib} --- - Encode and decode XDR data} - -\declaremodule{standard}{xdrlib} -\modulesynopsis{Encoders and decoders for the External Data - Representation (XDR).} - -\index{XDR} -\index{External Data Representation} - -The \module{xdrlib} module supports the External Data Representation -Standard as described in \rfc{1014}, written by Sun Microsystems, -Inc. June 1987. It supports most of the data types described in the -RFC. - -The \module{xdrlib} module defines two classes, one for packing -variables into XDR representation, and another for unpacking from XDR -representation. There are also two exception classes. - -\begin{classdesc}{Packer}{} -\class{Packer} is the class for packing data into XDR representation. -The \class{Packer} class is instantiated with no arguments. -\end{classdesc} - -\begin{classdesc}{Unpacker}{data} -\code{Unpacker} is the complementary class which unpacks XDR data -values from a string buffer. The input buffer is given as -\var{data}. -\end{classdesc} - - -\begin{seealso} - \seerfc{1014}{XDR: External Data Representation Standard}{This RFC - defined the encoding of data which was XDR at the time - this module was originally written. It has - apparently been obsoleted by \rfc{1832}.} - - \seerfc{1832}{XDR: External Data Representation Standard}{Newer RFC - that provides a revised definition of XDR.} -\end{seealso} - - -\subsection{Packer Objects \label{xdr-packer-objects}} - -\class{Packer} instances have the following methods: - -\begin{methoddesc}[Packer]{get_buffer}{} -Returns the current pack buffer as a string. -\end{methoddesc} - -\begin{methoddesc}[Packer]{reset}{} -Resets the pack buffer to the empty string. -\end{methoddesc} - -In general, you can pack any of the most common XDR data types by -calling the appropriate \code{pack_\var{type}()} method. Each method -takes a single argument, the value to pack. The following simple data -type packing methods are supported: \method{pack_uint()}, -\method{pack_int()}, \method{pack_enum()}, \method{pack_bool()}, -\method{pack_uhyper()}, and \method{pack_hyper()}. - -\begin{methoddesc}[Packer]{pack_float}{value} -Packs the single-precision floating point number \var{value}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_double}{value} -Packs the double-precision floating point number \var{value}. -\end{methoddesc} - -The following methods support packing strings, bytes, and opaque data: - -\begin{methoddesc}[Packer]{pack_fstring}{n, s} -Packs a fixed length string, \var{s}. \var{n} is the length of the -string but it is \emph{not} packed into the data buffer. The string -is padded with null bytes if necessary to guaranteed 4 byte alignment. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_fopaque}{n, data} -Packs a fixed length opaque data stream, similarly to -\method{pack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_string}{s} -Packs a variable length string, \var{s}. The length of the string is -first packed as an unsigned integer, then the string data is packed -with \method{pack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_opaque}{data} -Packs a variable length opaque data string, similarly to -\method{pack_string()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_bytes}{bytes} -Packs a variable length byte stream, similarly to \method{pack_string()}. -\end{methoddesc} - -The following methods support packing arrays and lists: - -\begin{methoddesc}[Packer]{pack_list}{list, pack_item} -Packs a \var{list} of homogeneous items. This method is useful for -lists with an indeterminate size; i.e. the size is not available until -the entire list has been walked. For each item in the list, an -unsigned integer \code{1} is packed first, followed by the data value -from the list. \var{pack_item} is the function that is called to pack -the individual item. At the end of the list, an unsigned integer -\code{0} is packed. - -For example, to pack a list of integers, the code might appear like -this: - -\begin{verbatim} -import xdrlib -p = xdrlib.Packer() -p.pack_list([1, 2, 3], p.pack_int) -\end{verbatim} -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_farray}{n, array, pack_item} -Packs a fixed length list (\var{array}) of homogeneous items. \var{n} -is the length of the list; it is \emph{not} packed into the buffer, -but a \exception{ValueError} exception is raised if -\code{len(\var{array})} is not equal to \var{n}. As above, -\var{pack_item} is the function used to pack each element. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_array}{list, pack_item} -Packs a variable length \var{list} of homogeneous items. First, the -length of the list is packed as an unsigned integer, then each element -is packed as in \method{pack_farray()} above. -\end{methoddesc} - - -\subsection{Unpacker Objects \label{xdr-unpacker-objects}} - -The \class{Unpacker} class offers the following methods: - -\begin{methoddesc}[Unpacker]{reset}{data} -Resets the string buffer with the given \var{data}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{get_position}{} -Returns the current unpack position in the data buffer. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{set_position}{position} -Sets the data buffer unpack position to \var{position}. You should be -careful about using \method{get_position()} and \method{set_position()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{get_buffer}{} -Returns the current unpack data buffer as a string. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{done}{} -Indicates unpack completion. Raises an \exception{Error} exception -if all of the data has not been unpacked. -\end{methoddesc} - -In addition, every data type that can be packed with a \class{Packer}, -can be unpacked with an \class{Unpacker}. Unpacking methods are of the -form \code{unpack_\var{type}()}, and take no arguments. They return the -unpacked object. - -\begin{methoddesc}[Unpacker]{unpack_float}{} -Unpacks a single-precision floating point number. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_double}{} -Unpacks a double-precision floating point number, similarly to -\method{unpack_float()}. -\end{methoddesc} - -In addition, the following methods unpack strings, bytes, and opaque -data: - -\begin{methoddesc}[Unpacker]{unpack_fstring}{n} -Unpacks and returns a fixed length string. \var{n} is the number of -characters expected. Padding with null bytes to guaranteed 4 byte -alignment is assumed. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_fopaque}{n} -Unpacks and returns a fixed length opaque data stream, similarly to -\method{unpack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_string}{} -Unpacks and returns a variable length string. The length of the -string is first unpacked as an unsigned integer, then the string data -is unpacked with \method{unpack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_opaque}{} -Unpacks and returns a variable length opaque data string, similarly to -\method{unpack_string()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_bytes}{} -Unpacks and returns a variable length byte stream, similarly to -\method{unpack_string()}. -\end{methoddesc} - -The following methods support unpacking arrays and lists: - -\begin{methoddesc}[Unpacker]{unpack_list}{unpack_item} -Unpacks and returns a list of homogeneous items. The list is unpacked -one element at a time -by first unpacking an unsigned integer flag. If the flag is \code{1}, -then the item is unpacked and appended to the list. A flag of -\code{0} indicates the end of the list. \var{unpack_item} is the -function that is called to unpack the items. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_farray}{n, unpack_item} -Unpacks and returns (as a list) a fixed length array of homogeneous -items. \var{n} is number of list elements to expect in the buffer. -As above, \var{unpack_item} is the function used to unpack each element. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_array}{unpack_item} -Unpacks and returns a variable length \var{list} of homogeneous items. -First, the length of the list is unpacked as an unsigned integer, then -each element is unpacked as in \method{unpack_farray()} above. -\end{methoddesc} - - -\subsection{Exceptions \label{xdr-exceptions}} - -Exceptions in this module are coded as class instances: - -\begin{excdesc}{Error} -The base exception class. \exception{Error} has a single public data -member \member{msg} containing the description of the error. -\end{excdesc} - -\begin{excdesc}{ConversionError} -Class derived from \exception{Error}. Contains no additional instance -variables. -\end{excdesc} - -Here is an example of how you would catch one of these exceptions: - -\begin{verbatim} -import xdrlib -p = xdrlib.Packer() -try: - p.pack_double(8.01) -except xdrlib.ConversionError as instance: - print 'packing the double failed:', instance.msg -\end{verbatim} diff --git a/Doc/lib/libxmlrpclib.tex b/Doc/lib/libxmlrpclib.tex deleted file mode 100644 index 22f29b8..0000000 --- a/Doc/lib/libxmlrpclib.tex +++ /dev/null @@ -1,391 +0,0 @@ -\section{\module{xmlrpclib} --- XML-RPC client access} - -\declaremodule{standard}{xmlrpclib} -\modulesynopsis{XML-RPC client access.} -\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com} -\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} - -% Not everything is documented yet. It might be good to describe -% Marshaller, Unmarshaller, getparser, dumps, loads, and Transport. - -\versionadded{2.2} - -XML-RPC is a Remote Procedure Call method that uses XML passed via -HTTP as a transport. With it, a client can call methods with -parameters on a remote server (the server is named by a URI) and get back -structured data. This module supports writing XML-RPC client code; it -handles all the details of translating between conformable Python -objects and XML on the wire. - -\begin{classdesc}{ServerProxy}{uri\optional{, transport\optional{, - encoding\optional{, verbose\optional{, - allow_none\optional{, use_datetime}}}}}} -A \class{ServerProxy} instance is an object that manages communication -with a remote XML-RPC server. The required first argument is a URI -(Uniform Resource Indicator), and will normally be the URL of the -server. The optional second argument is a transport factory instance; -by default it is an internal \class{SafeTransport} instance for https: -URLs and an internal HTTP \class{Transport} instance otherwise. The -optional third argument is an encoding, by default UTF-8. The optional -fourth argument is a debugging flag. If \var{allow_none} is true, -the Python constant \code{None} will be translated into XML; the -default behaviour is for \code{None} to raise a \exception{TypeError}. -This is a commonly-used extension to the XML-RPC specification, but isn't -supported by all clients and servers; see -\url{http://ontosys.com/xml-rpc/extensions.php} for a description. -The \var{use_datetime} flag can be used to cause date/time values to be -presented as \class{\refmodule{datetime}.datetime} objects; this is false -by default. \class{\refmodule{datetime}.datetime}, -\class{\refmodule{datetime}.date} and \class{\refmodule{datetime}.time} -objects may be passed to calls. \class{\refmodule{datetime}.date} objects -are converted with a time of ``00:00:00''. -\class{\refmodule{datetime}.time} objects are converted using today's date. - -Both the HTTP and HTTPS transports support the URL syntax extension for -HTTP Basic Authentication: \code{http://user:pass@host:port/path}. The -\code{user:pass} portion will be base64-encoded as an HTTP `Authorization' -header, and sent to the remote server as part of the connection process -when invoking an XML-RPC method. You only need to use this if the -remote server requires a Basic Authentication user and password. - -The returned instance is a proxy object with methods that can be used -to invoke corresponding RPC calls on the remote server. If the remote -server supports the introspection API, the proxy can also be used to query -the remote server for the methods it supports (service discovery) and -fetch other server-associated metadata. - -\class{ServerProxy} instance methods take Python basic types and objects as -arguments and return Python basic types and classes. Types that are -conformable (e.g. that can be marshalled through XML), include the -following (and except where noted, they are unmarshalled as the same -Python type): - -\begin{tableii}{l|l}{constant}{Name}{Meaning} - \lineii{boolean}{The \constant{True} and \constant{False} constants} - \lineii{integers}{Pass in directly} - \lineii{floating-point numbers}{Pass in directly} - \lineii{strings}{Pass in directly} - \lineii{arrays}{Any Python sequence type containing conformable - elements. Arrays are returned as lists} - \lineii{structures}{A Python dictionary. Keys must be strings, - values may be any conformable type. Objects - of user-defined classes can be passed in; - only their \var{__dict__} attribute is - transmitted.} - \lineii{dates}{in seconds since the epoch (pass in an instance of the - \class{DateTime} class) or a - \class{\refmodule{datetime}.datetime}, - \class{\refmodule{datetime}.date} or - \class{\refmodule{datetime}.time} instance} - \lineii{binary data}{pass in an instance of the \class{Binary} - wrapper class} -\end{tableii} - -This is the full set of data types supported by XML-RPC. Method calls -may also raise a special \exception{Fault} instance, used to signal -XML-RPC server errors, or \exception{ProtocolError} used to signal an -error in the HTTP/HTTPS transport layer. Both \exception{Fault} and -\exception{ProtocolError} derive from a base class called -\exception{Error}. Note that even though starting with Python 2.2 you -can subclass builtin types, the xmlrpclib module currently does not -marshal instances of such subclasses. - -When passing strings, characters special to XML such as \samp{<}, -\samp{>}, and \samp{\&} will be automatically escaped. However, it's -the caller's responsibility to ensure that the string is free of -characters that aren't allowed in XML, such as the control characters -with ASCII values between 0 and 31 (except, of course, tab, newline and -carriage return); failing to do this will result in -an XML-RPC request that isn't well-formed XML. If you have to pass -arbitrary strings via XML-RPC, use the \class{Binary} wrapper class -described below. - -\class{Server} is retained as an alias for \class{ServerProxy} for backwards -compatibility. New code should use \class{ServerProxy}. - -\versionchanged[The \var{use_datetime} flag was added]{2.5} - -\versionchanged[Instances of new-style classes can be passed in -if they have an \var{__dict__} attribute and don't have a base class -that is marshalled in a special way]{2.6} -\end{classdesc} - - -\begin{seealso} - \seetitle[http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html] - {XML-RPC HOWTO}{A good description of XML operation and - client software in several languages. Contains pretty much - everything an XML-RPC client developer needs to know.} - \seetitle[http://xmlrpc-c.sourceforge.net/hacks.php] - {XML-RPC Hacks page}{Extensions for various open-source - libraries to support introspection and multicall.} -\end{seealso} - - -\subsection{ServerProxy Objects \label{serverproxy-objects}} - -A \class{ServerProxy} instance has a method corresponding to -each remote procedure call accepted by the XML-RPC server. Calling -the method performs an RPC, dispatched by both name and argument -signature (e.g. the same method name can be overloaded with multiple -argument signatures). The RPC finishes by returning a value, which -may be either returned data in a conformant type or a \class{Fault} or -\class{ProtocolError} object indicating an error. - -Servers that support the XML introspection API support some common -methods grouped under the reserved \member{system} member: - -\begin{methoddesc}[ServerProxy]{system.listMethods}{} -This method returns a list of strings, one for each (non-system) -method supported by the XML-RPC server. -\end{methoddesc} - -\begin{methoddesc}[ServerProxy]{system.methodSignature}{name} -This method takes one parameter, the name of a method implemented by -the XML-RPC server.It returns an array of possible signatures for this -method. A signature is an array of types. The first of these types is -the return type of the method, the rest are parameters. - -Because multiple signatures (ie. overloading) is permitted, this method -returns a list of signatures rather than a singleton. - -Signatures themselves are restricted to the top level parameters -expected by a method. For instance if a method expects one array of -structs as a parameter, and it returns a string, its signature is -simply "string, array". If it expects three integers and returns a -string, its signature is "string, int, int, int". - -If no signature is defined for the method, a non-array value is -returned. In Python this means that the type of the returned -value will be something other that list. -\end{methoddesc} - -\begin{methoddesc}[ServerProxy]{system.methodHelp}{name} -This method takes one parameter, the name of a method implemented by -the XML-RPC server. It returns a documentation string describing the -use of that method. If no such string is available, an empty string is -returned. The documentation string may contain HTML markup. -\end{methoddesc} - -Introspection methods are currently supported by servers written in -PHP, C and Microsoft .NET. Partial introspection support is included -in recent updates to UserLand Frontier. Introspection support for -Perl, Python and Java is available at the \ulink{XML-RPC -Hacks}{http://xmlrpc-c.sourceforge.net/hacks.php} page. - - -\subsection{Boolean Objects \label{boolean-objects}} - -This class may be initialized from any Python value; the instance -returned depends only on its truth value. It supports various Python -operators through \method{__cmp__()}, \method{__repr__()}, -\method{__int__()}, and \method{__bool__()} methods, all -implemented in the obvious ways. - -It also has the following method, supported mainly for internal use by -the unmarshalling code: - -\begin{methoddesc}[Boolean]{encode}{out} -Write the XML-RPC encoding of this Boolean item to the out stream object. -\end{methoddesc} - - -\subsection{DateTime Objects \label{datetime-objects}} - -This class may be initialized with seconds since the epoch, a time tuple, an -ISO 8601 time/date string, or a {}\class{\refmodule{datetime}.datetime}, -{}\class{\refmodule{datetime}.date} or {}\class{\refmodule{datetime}.time} -instance. It has the following methods, supported mainly for internal use -by the marshalling/unmarshalling code: - -\begin{methoddesc}[DateTime]{decode}{string} -Accept a string as the instance's new time value. -\end{methoddesc} - -\begin{methoddesc}[DateTime]{encode}{out} -Write the XML-RPC encoding of this \class{DateTime} item to the -\var{out} stream object. -\end{methoddesc} - -It also supports certain of Python's built-in operators through -\method{__cmp__()} and \method{__repr__()} methods. - - -\subsection{Binary Objects \label{binary-objects}} - -This class may be initialized from string data (which may include NULs). -The primary access to the content of a \class{Binary} object is -provided by an attribute: - -\begin{memberdesc}[Binary]{data} -The binary data encapsulated by the \class{Binary} instance. The data -is provided as an 8-bit string. -\end{memberdesc} - -\class{Binary} objects have the following methods, supported mainly -for internal use by the marshalling/unmarshalling code: - -\begin{methoddesc}[Binary]{decode}{string} -Accept a base64 string and decode it as the instance's new data. -\end{methoddesc} - -\begin{methoddesc}[Binary]{encode}{out} -Write the XML-RPC base 64 encoding of this binary item to the out -stream object. -\end{methoddesc} - -It also supports certain of Python's built-in operators through a -\method{__cmp__()} method. - - -\subsection{Fault Objects \label{fault-objects}} - -A \class{Fault} object encapsulates the content of an XML-RPC fault tag. -Fault objects have the following members: - -\begin{memberdesc}[Fault]{faultCode} -A string indicating the fault type. -\end{memberdesc} - -\begin{memberdesc}[Fault]{faultString} -A string containing a diagnostic message associated with the fault. -\end{memberdesc} - - -\subsection{ProtocolError Objects \label{protocol-error-objects}} - -A \class{ProtocolError} object describes a protocol error in the -underlying transport layer (such as a 404 `not found' error if the -server named by the URI does not exist). It has the following -members: - -\begin{memberdesc}[ProtocolError]{url} -The URI or URL that triggered the error. -\end{memberdesc} - -\begin{memberdesc}[ProtocolError]{errcode} -The error code. -\end{memberdesc} - -\begin{memberdesc}[ProtocolError]{errmsg} -The error message or diagnostic string. -\end{memberdesc} - -\begin{memberdesc}[ProtocolError]{headers} -A string containing the headers of the HTTP/HTTPS request that -triggered the error. -\end{memberdesc} - -\subsection{MultiCall Objects} - -\versionadded{2.4} - -In \url{http://www.xmlrpc.com/discuss/msgReader\%241208}, an approach -is presented to encapsulate multiple calls to a remote server into a -single request. - -\begin{classdesc}{MultiCall}{server} - -Create an object used to boxcar method calls. \var{server} is the -eventual target of the call. Calls can be made to the result object, -but they will immediately return \code{None}, and only store the -call name and parameters in the \class{MultiCall} object. Calling -the object itself causes all stored calls to be transmitted as -a single \code{system.multicall} request. The result of this call -is a generator; iterating over this generator yields the individual -results. - -\end{classdesc} - -A usage example of this class is - -\begin{verbatim} -multicall = MultiCall(server_proxy) -multicall.add(2,3) -multicall.get_address("Guido") -add_result, address = multicall() -\end{verbatim} - -\subsection{Convenience Functions} - -\begin{funcdesc}{boolean}{value} -Convert any Python value to one of the XML-RPC Boolean constants, -\code{True} or \code{False}. -\end{funcdesc} - -\begin{funcdesc}{dumps}{params\optional{, methodname\optional{, - methodresponse\optional{, encoding\optional{, - allow_none}}}}} -Convert \var{params} into an XML-RPC request. -or into a response if \var{methodresponse} is true. -\var{params} can be either a tuple of arguments or an instance of the -\exception{Fault} exception class. If \var{methodresponse} is true, -only a single value can be returned, meaning that \var{params} must be of length 1. -\var{encoding}, if supplied, is the encoding to use in the generated -XML; the default is UTF-8. Python's \constant{None} value cannot be -used in standard XML-RPC; to allow using it via an extension, -provide a true value for \var{allow_none}. -\end{funcdesc} - -\begin{funcdesc}{loads}{data\optional{, use_datetime}} -Convert an XML-RPC request or response into Python objects, a -\code{(\var{params}, \var{methodname})}. \var{params} is a tuple of argument; \var{methodname} -is a string, or \code{None} if no method name is present in the packet. -If the XML-RPC packet represents a fault condition, this -function will raise a \exception{Fault} exception. -The \var{use_datetime} flag can be used to cause date/time values to be -presented as \class{\refmodule{datetime}.datetime} objects; this is false -by default. -Note that even if you call an XML-RPC method with -\class{\refmodule{datetime}.date} or \class{\refmodule{datetime}.time} -objects, they are converted to \class{DateTime} objects internally, so only -{}\class{\refmodule{datetime}.datetime} objects will be returned. - -\versionchanged[The \var{use_datetime} flag was added]{2.5} -\end{funcdesc} - - - -\subsection{Example of Client Usage \label{xmlrpc-client-example}} - -\begin{verbatim} -# simple test program (from the XML-RPC specification) -from xmlrpclib import ServerProxy, Error - -# server = ServerProxy("http://localhost:8000") # local server -server = ServerProxy("http://betty.userland.com") - -print server - -try: - print server.examples.getStateName(41) -except Error as v: - print "ERROR", v -\end{verbatim} - -To access an XML-RPC server through a proxy, you need to define -a custom transport. The following example, -written by NoboNobo, % fill in original author's name if we ever learn it -shows how: - -% Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html -\begin{verbatim} -import xmlrpclib, httplib - -class ProxiedTransport(xmlrpclib.Transport): - def set_proxy(self, proxy): - self.proxy = proxy - def make_connection(self, host): - self.realhost = host - h = httplib.HTTP(self.proxy) - return h - def send_request(self, connection, handler, request_body): - connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler)) - def send_host(self, connection, host): - connection.putheader('Host', self.realhost) - -p = ProxiedTransport() -p.set_proxy('proxy-server:8080') -server = xmlrpclib.Server('http://time.xmlrpc.com/RPC2', transport=p) -print server.currentTime.getCurrentTime() -\end{verbatim} diff --git a/Doc/lib/libzipfile.tex b/Doc/lib/libzipfile.tex deleted file mode 100644 index 366cee9..0000000 --- a/Doc/lib/libzipfile.tex +++ /dev/null @@ -1,371 +0,0 @@ -\section{\module{zipfile} --- - Work with ZIP archives} - -\declaremodule{standard}{zipfile} -\modulesynopsis{Read and write ZIP-format archive files.} -\moduleauthor{James C. Ahlstrom}{jim@interet.com} -\sectionauthor{James C. Ahlstrom}{jim@interet.com} -% LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org> - -\versionadded{1.6} - -The ZIP file format is a common archive and compression standard. -This module provides tools to create, read, write, append, and list a -ZIP file. Any advanced use of this module will require an -understanding of the format, as defined in -\citetitle[http://www.pkware.com/business_and_developers/developer/appnote/] -{PKZIP Application Note}. - -This module does not currently handle ZIP files which have appended -comments, or multi-disk ZIP files. It can handle ZIP files that use -the ZIP64 extensions (that is ZIP files that are more than 4 GByte in -size). It supports decryption of encrypted files in ZIP archives, but -it cannot currently create an encrypted file. - -The available attributes of this module are: - -\begin{excdesc}{BadZipfile} - The error raised for bad ZIP files (old name: \code{zipfile.error}). -\end{excdesc} - -\begin{excdesc}{LargeZipFile} - The error raised when a ZIP file would require ZIP64 functionality but that - has not been enabled. -\end{excdesc} - -\begin{classdesc*}{ZipFile} - The class for reading and writing ZIP files. See - ``\citetitle{ZipFile Objects}'' (section \ref{zipfile-objects}) for - constructor details. -\end{classdesc*} - -\begin{classdesc*}{PyZipFile} - Class for creating ZIP archives containing Python libraries. -\end{classdesc*} - -\begin{classdesc}{ZipInfo}{\optional{filename\optional{, date_time}}} - Class used to represent information about a member of an archive. - Instances of this class are returned by the \method{getinfo()} and - \method{infolist()} methods of \class{ZipFile} objects. Most users - of the \module{zipfile} module will not need to create these, but - only use those created by this module. - \var{filename} should be the full name of the archive member, and - \var{date_time} should be a tuple containing six fields which - describe the time of the last modification to the file; the fields - are described in section \ref{zipinfo-objects}, ``ZipInfo Objects.'' -\end{classdesc} - -\begin{funcdesc}{is_zipfile}{filename} - Returns \code{True} if \var{filename} is a valid ZIP file based on its magic - number, otherwise returns \code{False}. This module does not currently - handle ZIP files which have appended comments. -\end{funcdesc} - -\begin{datadesc}{ZIP_STORED} - The numeric constant for an uncompressed archive member. -\end{datadesc} - -\begin{datadesc}{ZIP_DEFLATED} - The numeric constant for the usual ZIP compression method. This - requires the zlib module. No other compression methods are - currently supported. -\end{datadesc} - - -\begin{seealso} - \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/] - {PKZIP Application Note}{Documentation on the ZIP file format by - Phil Katz, the creator of the format and algorithms used.} - - \seetitle[http://www.info-zip.org/pub/infozip/]{Info-ZIP Home Page}{ - Information about the Info-ZIP project's ZIP archive - programs and development libraries.} -\end{seealso} - - -\subsection{ZipFile Objects \label{zipfile-objects}} - -\begin{classdesc}{ZipFile}{file\optional{, mode\optional{, compression\optional{, allowZip64}}}} - Open a ZIP file, where \var{file} can be either a path to a file - (a string) or a file-like object. The \var{mode} parameter - should be \code{'r'} to read an existing file, \code{'w'} to - truncate and write a new file, or \code{'a'} to append to an - existing file. If \var{mode} is \code{'a'} and \var{file} - refers to an existing ZIP file, then additional files are added to - it. If \var{file} does not refer to a ZIP file, then a new ZIP - archive is appended to the file. This is meant for adding a ZIP - archive to another file, such as \file{python.exe}. Using - -\begin{verbatim} -cat myzip.zip >> python.exe -\end{verbatim} - - also works, and at least \program{WinZip} can read such files. - If \var{mode} is \code{a} and the file does not exist at all, - it is created. - \var{compression} is the ZIP compression method to use when writing - the archive, and should be \constant{ZIP_STORED} or - \constant{ZIP_DEFLATED}; unrecognized values will cause - \exception{RuntimeError} to be raised. If \constant{ZIP_DEFLATED} - is specified but the \refmodule{zlib} module is not available, - \exception{RuntimeError} is also raised. The default is - \constant{ZIP_STORED}. - If \var{allowZip64} is \code{True} zipfile will create ZIP files that use - the ZIP64 extensions when the zipfile is larger than 2 GB. If it is - false (the default) \module{zipfile} will raise an exception when the - ZIP file would require ZIP64 extensions. ZIP64 extensions are disabled by - default because the default \program{zip} and \program{unzip} commands on - \UNIX{} (the InfoZIP utilities) don't support these extensions. - - \versionchanged[If the file does not exist, it is created if the - mode is 'a']{2.6} -\end{classdesc} - -\begin{methoddesc}{close}{} - Close the archive file. You must call \method{close()} before - exiting your program or essential records will not be written. -\end{methoddesc} - -\begin{methoddesc}{getinfo}{name} - Return a \class{ZipInfo} object with information about the archive - member \var{name}. Calling \method{getinfo()} for a name not currently - contained in the archive will raise a \exception{KeyError}. -\end{methoddesc} - -\begin{methoddesc}{infolist}{} - Return a list containing a \class{ZipInfo} object for each member of - the archive. The objects are in the same order as their entries in - the actual ZIP file on disk if an existing archive was opened. -\end{methoddesc} - -\begin{methoddesc}{namelist}{} - Return a list of archive members by name. -\end{methoddesc} - -\begin{methoddesc}{open}{name\optional{, mode\optional{, pwd}}} - Extract a member from the archive as a file-like object (ZipExtFile). - \var{name} is the name of the file in the archive. The \var{mode} - parameter, if included, must be one of the following: \code{'r'} (the - default), \code{'U'}, or \code{'rU'}. Choosing \code{'U'} or - \code{'rU'} will enable universal newline support in the read-only - object. \var{pwd} is the password used for encrypted files. Calling - \method{open()} on a closed ZipFile will raise a - \exception{RuntimeError}. - \begin{notice} - The file-like object is read-only and provides the following methods: - \method{read()}, \method{readline()}, \method{readlines()}, - \method{__iter__()}, \method{next()}. - \end{notice} - \begin{notice} - If the ZipFile was created by passing in a file-like object as the - first argument to the constructor, then the object returned by - \method{open()} shares the ZipFile's file pointer. Under these - circumstances, the object returned by \method{open()} should not - be used after any additional operations are performed on the - ZipFile object. If the ZipFile was created by passing in a string - (the filename) as the first argument to the constructor, then - \method{open()} will create a new file object that will be held - by the ZipExtFile, allowing it to operate independently of the - ZipFile. - \end{notice} - - \versionadded{2.6} -\end{methoddesc} - -\begin{methoddesc}{printdir}{} - Print a table of contents for the archive to \code{sys.stdout}. -\end{methoddesc} - -\begin{methoddesc}{setpassword}{pwd} - Set \var{pwd} as default password to extract encrypted files. - \versionadded{2.6} -\end{methoddesc} - -\begin{methoddesc}{read}{name\optional{, pwd}} - Return the bytes of the file in the archive. The archive must be - open for read or append. \var{pwd} is the password used for encrypted - files and, if specified, it will override the default password set with - \method{setpassword()}. Calling \method{read()} on a closed ZipFile - will raise a \exception{RuntimeError}. - - \versionchanged[\var{pwd} was added]{2.6} -\end{methoddesc} - -\begin{methoddesc}{testzip}{} - Read all the files in the archive and check their CRC's and file - headers. Return the name of the first bad file, or else return \code{None}. - Calling \method{testzip()} on a closed ZipFile will raise a - \exception{RuntimeError}. -\end{methoddesc} - -\begin{methoddesc}{write}{filename\optional{, arcname\optional{, - compress_type}}} - Write the file named \var{filename} to the archive, giving it the - archive name \var{arcname} (by default, this will be the same as - \var{filename}, but without a drive letter and with leading path - separators removed). If given, \var{compress_type} overrides the - value given for the \var{compression} parameter to the constructor - for the new entry. The archive must be open with mode \code{'w'} - or \code{'a'} -- calling \method{write()} on a ZipFile created with - mode \code{'r'} will raise a \exception{RuntimeError}. Calling - \method{write()} on a closed ZipFile will raise a - \exception{RuntimeError}. - - \note{There is no official file name encoding for ZIP files. - If you have unicode file names, please convert them to byte strings - in your desired encoding before passing them to \method{write()}. - WinZip interprets all file names as encoded in CP437, also known - as DOS Latin.} - - \note{Archive names should be relative to the archive root, that is, - they should not start with a path separator.} - - \note{If \code{arcname} (or \code{filename}, if \code{arcname} is - not given) contains a null byte, the name of the file in the archive will - be truncated at the null byte.} - -\end{methoddesc} - -\begin{methoddesc}{writestr}{zinfo_or_arcname, bytes} - Write the string \var{bytes} to the archive; \var{zinfo_or_arcname} - is either the file name it will be given in the archive, or a - \class{ZipInfo} instance. If it's an instance, at least the - filename, date, and time must be given. If it's a name, the date - and time is set to the current date and time. The archive must be - opened with mode \code{'w'} or \code{'a'} -- calling - \method{writestr()} on a ZipFile created with mode \code{'r'} - will raise a \exception{RuntimeError}. Calling \method{writestr()} - on a closed ZipFile will raise a \exception{RuntimeError}. -\end{methoddesc} - - -The following data attribute is also available: - -\begin{memberdesc}{debug} - The level of debug output to use. This may be set from \code{0} - (the default, no output) to \code{3} (the most output). Debugging - information is written to \code{sys.stdout}. -\end{memberdesc} - - -\subsection{PyZipFile Objects \label{pyzipfile-objects}} - -The \class{PyZipFile} constructor takes the same parameters as the -\class{ZipFile} constructor. Instances have one method in addition to -those of \class{ZipFile} objects. - -\begin{methoddesc}[PyZipFile]{writepy}{pathname\optional{, basename}} - Search for files \file{*.py} and add the corresponding file to the - archive. The corresponding file is a \file{*.pyo} file if - available, else a \file{*.pyc} file, compiling if necessary. If the - pathname is a file, the filename must end with \file{.py}, and just - the (corresponding \file{*.py[co]}) file is added at the top level - (no path information). If the pathname is a file that does not end with - \file{.py}, a \exception{RuntimeError} will be raised. If it is a - directory, and the directory is not a package directory, then all the - files \file{*.py[co]} are added at the top level. If the directory is - a package directory, then all \file{*.py[co]} are added under the package - name as a file path, and if any subdirectories are package directories, all - of these are added recursively. \var{basename} is intended for - internal use only. The \method{writepy()} method makes archives - with file names like this: - -\begin{verbatim} - string.pyc # Top level name - test/__init__.pyc # Package directory - test/testall.pyc # Module test.testall - test/bogus/__init__.pyc # Subpackage directory - test/bogus/myfile.pyc # Submodule test.bogus.myfile -\end{verbatim} -\end{methoddesc} - - -\subsection{ZipInfo Objects \label{zipinfo-objects}} - -Instances of the \class{ZipInfo} class are returned by the -\method{getinfo()} and \method{infolist()} methods of -\class{ZipFile} objects. Each object stores information about a -single member of the ZIP archive. - -Instances have the following attributes: - -\begin{memberdesc}[ZipInfo]{filename} - Name of the file in the archive. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{date_time} - The time and date of the last modification to the archive - member. This is a tuple of six values: - -\begin{tableii}{c|l}{code}{Index}{Value} - \lineii{0}{Year} - \lineii{1}{Month (one-based)} - \lineii{2}{Day of month (one-based)} - \lineii{3}{Hours (zero-based)} - \lineii{4}{Minutes (zero-based)} - \lineii{5}{Seconds (zero-based)} -\end{tableii} -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{compress_type} - Type of compression for the archive member. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{comment} - Comment for the individual archive member. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{extra} - Expansion field data. The - \citetitle[http://www.pkware.com/business_and_developers/developer/appnote/] - {PKZIP Application Note} contains some comments on the internal - structure of the data contained in this string. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{create_system} - System which created ZIP archive. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{create_version} - PKZIP version which created ZIP archive. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{extract_version} - PKZIP version needed to extract archive. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{reserved} - Must be zero. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{flag_bits} - ZIP flag bits. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{volume} - Volume number of file header. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{internal_attr} - Internal attributes. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{external_attr} - External file attributes. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{header_offset} - Byte offset to the file header. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{CRC} - CRC-32 of the uncompressed file. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{compress_size} - Size of the compressed data. -\end{memberdesc} - -\begin{memberdesc}[ZipInfo]{file_size} - Size of the uncompressed file. -\end{memberdesc} diff --git a/Doc/lib/libzipimport.tex b/Doc/lib/libzipimport.tex deleted file mode 100644 index 8ebe3c5..0000000 --- a/Doc/lib/libzipimport.tex +++ /dev/null @@ -1,128 +0,0 @@ -\section{\module{zipimport} --- - Import modules from Zip archives} - -\declaremodule{standard}{zipimport} -\modulesynopsis{support for importing Python modules from ZIP archives.} -\moduleauthor{Just van Rossum}{just@letterror.com} - -\versionadded{2.3} - -This module adds the ability to import Python modules (\file{*.py}, -\file{*.py[co]}) and packages from ZIP-format archives. It is usually -not needed to use the \module{zipimport} module explicitly; it is -automatically used by the builtin \keyword{import} mechanism for -\code{sys.path} items that are paths to ZIP archives. - -Typically, \code{sys.path} is a list of directory names as strings. This -module also allows an item of \code{sys.path} to be a string naming a ZIP -file archive. The ZIP archive can contain a subdirectory structure to -support package imports, and a path within the archive can be specified to -only import from a subdirectory. For example, the path -\file{/tmp/example.zip/lib/} would only import from the -\file{lib/} subdirectory within the archive. - -Any files may be present in the ZIP archive, but only files \file{.py} and -\file{.py[co]} are available for import. ZIP import of dynamic modules -(\file{.pyd}, \file{.so}) is disallowed. Note that if an archive only -contains \file{.py} files, Python will not attempt to modify the archive -by adding the corresponding \file{.pyc} or \file{.pyo} file, meaning that -if a ZIP archive doesn't contain \file{.pyc} files, importing may be rather -slow. - -The available attributes of this module are: - -\begin{excdesc}{ZipImportError} - Exception raised by zipimporter objects. It's a subclass of - \exception{ImportError}, so it can be caught as \exception{ImportError}, - too. -\end{excdesc} - -\begin{classdesc*}{zipimporter} - The class for importing ZIP files. See - ``\citetitle{zipimporter Objects}'' (section \ref{zipimporter-objects}) - for constructor details. -\end{classdesc*} - - -\begin{seealso} - \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/] - {PKZIP Application Note}{Documentation on the ZIP file format by - Phil Katz, the creator of the format and algorithms used.} - - \seepep{0273}{Import Modules from Zip Archives}{Written by James C. - Ahlstrom, who also provided an implementation. Python 2.3 - follows the specification in PEP 273, but uses an - implementation written by Just van Rossum that uses the import - hooks described in PEP 302.} - - \seepep{0302}{New Import Hooks}{The PEP to add the import hooks that help - this module work.} -\end{seealso} - - -\subsection{zipimporter Objects \label{zipimporter-objects}} - -\begin{classdesc}{zipimporter}{archivepath} - Create a new zipimporter instance. \var{archivepath} must be a path to - a zipfile. \exception{ZipImportError} is raised if \var{archivepath} - doesn't point to a valid ZIP archive. -\end{classdesc} - -\begin{methoddesc}{find_module}{fullname\optional{, path}} - Search for a module specified by \var{fullname}. \var{fullname} must be - the fully qualified (dotted) module name. It returns the zipimporter - instance itself if the module was found, or \constant{None} if it wasn't. - The optional \var{path} argument is ignored---it's there for - compatibility with the importer protocol. -\end{methoddesc} - -\begin{methoddesc}{get_code}{fullname} - Return the code object for the specified module. Raise - \exception{ZipImportError} if the module couldn't be found. -\end{methoddesc} - -\begin{methoddesc}{get_data}{pathname} - Return the data associated with \var{pathname}. Raise \exception{IOError} - if the file wasn't found. -\end{methoddesc} - -\begin{methoddesc}{get_source}{fullname} - Return the source code for the specified module. Raise - \exception{ZipImportError} if the module couldn't be found, return - \constant{None} if the archive does contain the module, but has - no source for it. -\end{methoddesc} - -\begin{methoddesc}{is_package}{fullname} - Return True if the module specified by \var{fullname} is a package. - Raise \exception{ZipImportError} if the module couldn't be found. -\end{methoddesc} - -\begin{methoddesc}{load_module}{fullname} - Load the module specified by \var{fullname}. \var{fullname} must be the - fully qualified (dotted) module name. It returns the imported - module, or raises \exception{ZipImportError} if it wasn't found. -\end{methoddesc} - -\subsection{Examples} -\nodename{zipimport Examples} - -Here is an example that imports a module from a ZIP archive - note that -the \module{zipimport} module is not explicitly used. - -\begin{verbatim} -$ unzip -l /tmp/example.zip -Archive: /tmp/example.zip - Length Date Time Name - -------- ---- ---- ---- - 8467 11-26-02 22:30 jwzthreading.py - -------- ------- - 8467 1 file -$ ./python -Python 2.3 (#1, Aug 1 2003, 19:54:32) ->>> import sys ->>> sys.path.insert(0, '/tmp/example.zip') # Add .zip file to front of path ->>> import jwzthreading ->>> jwzthreading.__file__ -'/tmp/example.zip/jwzthreading.py' -\end{verbatim} diff --git a/Doc/lib/libzlib.tex b/Doc/lib/libzlib.tex deleted file mode 100644 index 3cc7b3c..0000000 --- a/Doc/lib/libzlib.tex +++ /dev/null @@ -1,197 +0,0 @@ -\section{\module{zlib} --- - Compression compatible with \program{gzip}} - -\declaremodule{builtin}{zlib} -\modulesynopsis{Low-level interface to compression and decompression - routines compatible with \program{gzip}.} - - -For applications that require data compression, the functions in this -module allow compression and decompression, using the zlib library. -The zlib library has its own home page at \url{http://www.zlib.net}. -There are known incompatibilities between the Python module and -versions of the zlib library earlier than 1.1.3; 1.1.3 has a security -vulnerability, so we recommend using 1.1.4 or later. - -zlib's functions have many options and often need to be used in a -particular order. This documentation doesn't attempt to cover all of -the permutations; consult the zlib manual at -\url{http://www.zlib.net/manual.html} for authoritative information. - -The available exception and functions in this module are: - -\begin{excdesc}{error} - Exception raised on compression and decompression errors. -\end{excdesc} - - -\begin{funcdesc}{adler32}{string\optional{, value}} - Computes a Adler-32 checksum of \var{string}. (An Adler-32 - checksum is almost as reliable as a CRC32 but can be computed much - more quickly.) If \var{value} is present, it is used as the - starting value of the checksum; otherwise, a fixed default value is - used. This allows computing a running checksum over the - concatenation of several input strings. The algorithm is not - cryptographically strong, and should not be used for - authentication or digital signatures. Since the algorithm is - designed for use as a checksum algorithm, it is not suitable for - use as a general hash algorithm. -\end{funcdesc} - -\begin{funcdesc}{compress}{string\optional{, level}} - Compresses the data in \var{string}, returning a string contained - compressed data. \var{level} is an integer from \code{1} to - \code{9} controlling the level of compression; \code{1} is fastest - and produces the least compression, \code{9} is slowest and produces - the most. The default value is \code{6}. Raises the - \exception{error} exception if any error occurs. -\end{funcdesc} - -\begin{funcdesc}{compressobj}{\optional{level}} - Returns a compression object, to be used for compressing data streams - that won't fit into memory at once. \var{level} is an integer from - \code{1} to \code{9} controlling the level of compression; \code{1} is - fastest and produces the least compression, \code{9} is slowest and - produces the most. The default value is \code{6}. -\end{funcdesc} - -\begin{funcdesc}{crc32}{string\optional{, value}} - Computes a CRC (Cyclic Redundancy Check)% - \index{Cyclic Redundancy Check} - \index{checksum!Cyclic Redundancy Check} - checksum of \var{string}. If - \var{value} is present, it is used as the starting value of the - checksum; otherwise, a fixed default value is used. This allows - computing a running checksum over the concatenation of several - input strings. The algorithm is not cryptographically strong, and - should not be used for authentication or digital signatures. Since - the algorithm is designed for use as a checksum algorithm, it is not - suitable for use as a general hash algorithm. -\end{funcdesc} - -\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{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}} - Returns a decompression object, to be used for decompressing data - streams that won't fit into memory at once. The \var{wbits} - parameter controls the size of the window buffer. -\end{funcdesc} - -Compression objects support the following methods: - -\begin{methoddesc}[Compress]{compress}{string} -Compress \var{string}, returning a string containing compressed data -for at least part of the data in \var{string}. This data should be -concatenated to the output produced by any preceding calls to the -\method{compress()} method. Some input may be kept in internal buffers -for later processing. -\end{methoddesc} - -\begin{methoddesc}[Compress]{flush}{\optional{mode}} -All pending input is processed, and a string containing the remaining -compressed output is returned. \var{mode} can be selected from the -constants \constant{Z_SYNC_FLUSH}, \constant{Z_FULL_FLUSH}, or -\constant{Z_FINISH}, defaulting to \constant{Z_FINISH}. \constant{Z_SYNC_FLUSH} and -\constant{Z_FULL_FLUSH} allow compressing further strings of data, while -\constant{Z_FINISH} finishes the compressed stream and -prevents compressing any more data. After calling -\method{flush()} with \var{mode} set to \constant{Z_FINISH}, the -\method{compress()} method cannot be called again; the only realistic -action is to delete the object. -\end{methoddesc} - -\begin{methoddesc}[Compress]{copy}{} -Returns a copy of the compression object. This can be used to efficiently -compress a set of data that share a common initial prefix. -\versionadded{2.5} -\end{methoddesc} - -Decompression objects support the following methods, and two attributes: - -\begin{memberdesc}[Decompress]{unused_data} -A string which contains any bytes past the end of the compressed data. -That is, this remains \code{""} until the last byte that contains -compression data is available. 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 followed by some non-empty string into a -decompression object's \method{decompress} method until the -\member{unused_data} attribute is no longer the empty string. -\end{memberdesc} - -\begin{memberdesc}[Decompress]{unconsumed_tail} -A string that contains any data that was not consumed by the last -\method{decompress} call because it exceeded the limit for the -uncompressed data buffer. This data has not yet been seen by the zlib -machinery, so you must feed it (possibly with further data -concatenated to it) back to a subsequent \method{decompress} method -call in order to get correct output. -\end{memberdesc} - - -\begin{methoddesc}[Decompress]{decompress}{string\optional{, max_length}} -Decompress \var{string}, returning a string containing the -uncompressed data corresponding to at least part of the data in -\var{string}. This data should be concatenated to the output produced -by any preceding calls to the -\method{decompress()} method. Some of the input data may be preserved -in internal buffers for later processing. - -If the optional parameter \var{max_length} is supplied then the return value -will be no longer than \var{max_length}. This may mean that not all of the -compressed input can be processed; and unconsumed data will be stored -in the attribute \member{unconsumed_tail}. This string must be passed -to a subsequent call to \method{decompress()} if decompression is to -continue. If \var{max_length} is not supplied then the whole input is -decompressed, and \member{unconsumed_tail} is an empty string. -\end{methoddesc} - -\begin{methoddesc}[Decompress]{flush}{\optional{length}} -All pending input is processed, and a string containing the remaining -uncompressed output is returned. After calling \method{flush()}, the -\method{decompress()} method cannot be called again; the only realistic -action is to delete the object. - -The optional parameter \var{length} sets the initial size of the -output buffer. -\end{methoddesc} - -\begin{methoddesc}[Decompress]{copy}{} -Returns a copy of the decompression object. This can be used to save the -state of the decompressor midway through the data stream in order to speed up -random seeks into the stream at a future point. -\versionadded{2.5} -\end{methoddesc} - -\begin{seealso} - \seemodule{gzip}{Reading and writing \program{gzip}-format files.} - \seeurl{http://www.zlib.net}{The zlib library home page.} - \seeurl{http://www.zlib.net/manual.html}{The zlib manual explains - the semantics and usage of the library's many functions.} -\end{seealso} diff --git a/Doc/lib/markup.tex b/Doc/lib/markup.tex deleted file mode 100644 index 0d923a72..0000000 --- a/Doc/lib/markup.tex +++ /dev/null @@ -1,29 +0,0 @@ -\chapter{Structured Markup Processing Tools - \label{markup}} - -Python supports a variety of modules to work with various forms of -structured data markup. This includes modules to work with the -Standard Generalized Markup Language (SGML) and the Hypertext Markup -Language (HTML), and several interfaces for working with the -Extensible Markup Language (XML). - -It is important to note that modules in the \module{xml} package -require that there be at least one SAX-compliant XML parser available. -Starting with Python 2.3, the Expat parser is included with Python, so -the \refmodule{xml.parsers.expat} module will always be available. -You may still want to be aware of the \ulink{PyXML add-on -package}{http://pyxml.sourceforge.net/}; that package provides an -extended set of XML libraries for Python. - -The documentation for the \module{xml.dom} and \module{xml.sax} -packages are the definition of the Python bindings for the DOM and SAX -interfaces. - -\localmoduletable - -\begin{seealso} - \seetitle[http://pyxml.sourceforge.net/] - {Python/XML Libraries} - {Home page for the PyXML package, containing an extension - of \module{xml} package bundled with Python.} -\end{seealso} diff --git a/Doc/lib/mimelib.tex b/Doc/lib/mimelib.tex deleted file mode 100644 index 491d844..0000000 --- a/Doc/lib/mimelib.tex +++ /dev/null @@ -1,65 +0,0 @@ -% This document is largely a stub used to allow the email package docs -% to be formatted separately from the rest of the Python -% documentation. This allows the documentation to be released -% independently of the rest of Python since the email package is being -% maintained for multiple Python versions, and on an accelerated -% schedule. - -\documentclass{howto} - -\title{email Package Reference} -\author{Barry Warsaw} -\authoraddress{\email{barry@python.org}} - -\date{\today} -\release{4.0} % software release, not documentation -\setreleaseinfo{} % empty for final release -\setshortversion{4.0} % major.minor only for software - -\begin{document} - -\maketitle - -\begin{abstract} - The \module{email} package provides classes and utilities to create, - parse, generate, and modify email messages, conforming to all the - relevant email and MIME related RFCs. -\end{abstract} - -% The ugly "%begin{latexonly}" pseudo-environment suppresses the table -% of contents for HTML generation. -% -%begin{latexonly} -\tableofcontents -%end{latexonly} - -\section{Introduction} -The \module{email} package provides classes and utilities to create, -parse, generate, and modify email messages, conforming to all the -relevant email and MIME related RFCs. - -This document describes version 4.0 of the \module{email} package, which is -distributed with Python 2.5 and is available as a standalone distutils-based -package for use with earlier Python versions. \module{email} 4.0 is not -compatible with Python versions earlier than 2.3. For more information about -the \module{email} package, including download links and mailing lists, see -\ulink{Python's email SIG}{http://www.python.org/sigs/email-sig}. - -The documentation that follows was written for the Python project, so -if you're reading this as part of the standalone \module{email} -package documentation, there are a few notes to be aware of: - -\begin{itemize} -\item Deprecation and ``version added'' notes are relative to the - Python version a feature was added or deprecated. See - the package history in section \ref{email-pkg-history} for details. - -\item If you're reading this documentation as part of the - standalone \module{email} package, some of the internal links to - other sections of the Python standard library may not resolve. - -\end{itemize} - -\input{email} - -\end{document} diff --git a/Doc/lib/minidom-example.py b/Doc/lib/minidom-example.py deleted file mode 100644 index c30c4e0..0000000 --- a/Doc/lib/minidom-example.py +++ /dev/null @@ -1,64 +0,0 @@ -import xml.dom.minidom - -document = """\ -<slideshow> -<title>Demo slideshow</title> -<slide><title>Slide title</title> -<point>This is a demo</point> -<point>Of a program for processing slides</point> -</slide> - -<slide><title>Another demo slide</title> -<point>It is important</point> -<point>To have more than</point> -<point>one slide</point> -</slide> -</slideshow> -""" - -dom = xml.dom.minidom.parseString(document) - -def getText(nodelist): - rc = "" - for node in nodelist: - if node.nodeType == node.TEXT_NODE: - rc = rc + node.data - return rc - -def handleSlideshow(slideshow): - print "<html>" - handleSlideshowTitle(slideshow.getElementsByTagName("title")[0]) - slides = slideshow.getElementsByTagName("slide") - handleToc(slides) - handleSlides(slides) - print "</html>" - -def handleSlides(slides): - for slide in slides: - handleSlide(slide) - -def handleSlide(slide): - handleSlideTitle(slide.getElementsByTagName("title")[0]) - handlePoints(slide.getElementsByTagName("point")) - -def handleSlideshowTitle(title): - print "<title>%s</title>" % getText(title.childNodes) - -def handleSlideTitle(title): - print "<h2>%s</h2>" % getText(title.childNodes) - -def handlePoints(points): - print "<ul>" - for point in points: - handlePoint(point) - print "</ul>" - -def handlePoint(point): - print "<li>%s</li>" % getText(point.childNodes) - -def handleToc(slides): - for slide in slides: - title = slide.getElementsByTagName("title")[0] - print "<p>%s</p>" % getText(title.childNodes) - -handleSlideshow(dom) diff --git a/Doc/lib/modules.tex b/Doc/lib/modules.tex deleted file mode 100644 index e23d051..0000000 --- a/Doc/lib/modules.tex +++ /dev/null @@ -1,9 +0,0 @@ -\chapter{Importing Modules} -\label{modules} - -The modules described in this chapter provide new ways to import other -Python modules and hooks for customizing the import process. - -The full list of modules described in this chapter is: - -\localmoduletable diff --git a/Doc/lib/netdata.tex b/Doc/lib/netdata.tex deleted file mode 100644 index 08062d0..0000000 --- a/Doc/lib/netdata.tex +++ /dev/null @@ -1,6 +0,0 @@ -\chapter{Internet Data Handling \label{netdata}} - -This chapter describes modules which support handling data formats -commonly used on the Internet. - -\localmoduletable diff --git a/Doc/lib/numeric.tex b/Doc/lib/numeric.tex deleted file mode 100644 index a9a9e18..0000000 --- a/Doc/lib/numeric.tex +++ /dev/null @@ -1,13 +0,0 @@ -\chapter{Numeric and Mathematical Modules} -\label{numeric} - -The modules described in this chapter provide -numeric and math-related functions and data types. -The \module{math} and \module{cmath} contain -various mathematical functions for floating-point and complex numbers. -For users more interested in decimal accuracy than in speed, the -\module{decimal} module supports exact representations of decimal numbers. - -The following modules are documented in this chapter: - -\localmoduletable diff --git a/Doc/lib/persistence.tex b/Doc/lib/persistence.tex deleted file mode 100644 index 0bcdad2..0000000 --- a/Doc/lib/persistence.tex +++ /dev/null @@ -1,15 +0,0 @@ -\chapter{Data Persistence} -\label{persistence} - -The modules described in this chapter support storing Python data in a -persistent form on disk. The \module{pickle} and \module{marshal} -modules can turn many Python data types into a stream of bytes and -then recreate the objects from the bytes. The various DBM-related -modules support a family of hash-based file formats that store a -mapping of strings to other strings. The \module{bsddb} module also -provides such disk-based string-to-string mappings based on hashing, -and also supports B-Tree and record-based formats. - -The list of modules described in this chapter is: - -\localmoduletable diff --git a/Doc/lib/required_1.py b/Doc/lib/required_1.py deleted file mode 100755 index 6be5668..0000000 --- a/Doc/lib/required_1.py +++ /dev/null @@ -1,20 +0,0 @@ -import optparse - -class OptionParser (optparse.OptionParser): - - def check_required (self, opt): - option = self.get_option(opt) - - # Assumes the option's 'default' is set to None! - if getattr(self.values, option.dest) is None: - self.error("%s option not supplied" % option) - - -parser = OptionParser() -parser.add_option("-v", action="count", dest="verbose") -parser.add_option("-f", "--file", default=None) -(options, args) = parser.parse_args() - -print "verbose:", options.verbose -print "file:", options.file -parser.check_required("-f") diff --git a/Doc/lib/required_2.py b/Doc/lib/required_2.py deleted file mode 100755 index 421514a..0000000 --- a/Doc/lib/required_2.py +++ /dev/null @@ -1,41 +0,0 @@ -import optparse - -class Option (optparse.Option): - ATTRS = optparse.Option.ATTRS + ['required'] - - def _check_required (self): - if self.required and not self.takes_value(): - raise OptionError( - "required flag set for option that doesn't take a value", - self) - - # Make sure _check_required() is called from the constructor! - CHECK_METHODS = optparse.Option.CHECK_METHODS + [_check_required] - - def process (self, opt, value, values, parser): - optparse.Option.process(self, opt, value, values, parser) - parser.option_seen[self] = 1 - - -class OptionParser (optparse.OptionParser): - - def _init_parsing_state (self): - optparse.OptionParser._init_parsing_state(self) - self.option_seen = {} - - def check_values (self, values, args): - for option in self.option_list: - if (isinstance(option, Option) and - option.required and - not self.option_seen.has_key(option)): - self.error("%s not supplied" % option) - return (values, args) - - -parser = OptionParser(option_list=[ - Option("-v", action="count", dest="verbose"), - Option("-f", "--file", required=1)]) -(options, args) = parser.parse_args() - -print "verbose:", options.verbose -print "file:", options.file diff --git a/Doc/lib/sqlite3/adapter_datetime.py b/Doc/lib/sqlite3/adapter_datetime.py deleted file mode 100644 index 5869e22..0000000 --- a/Doc/lib/sqlite3/adapter_datetime.py +++ /dev/null @@ -1,14 +0,0 @@ -import sqlite3 -import datetime, time - -def adapt_datetime(ts): - return time.mktime(ts.timetuple()) - -sqlite3.register_adapter(datetime.datetime, adapt_datetime) - -con = sqlite3.connect(":memory:") -cur = con.cursor() - -now = datetime.datetime.now() -cur.execute("select ?", (now,)) -print(cur.fetchone()[0]) diff --git a/Doc/lib/sqlite3/adapter_point_1.py b/Doc/lib/sqlite3/adapter_point_1.py deleted file mode 100644 index 1343acd..0000000 --- a/Doc/lib/sqlite3/adapter_point_1.py +++ /dev/null @@ -1,16 +0,0 @@ -import sqlite3 - -class Point(object): - def __init__(self, x, y): - self.x, self.y = x, y - - def __conform__(self, protocol): - if protocol is sqlite3.PrepareProtocol: - return "%f;%f" % (self.x, self.y) - -con = sqlite3.connect(":memory:") -cur = con.cursor() - -p = Point(4.0, -3.2) -cur.execute("select ?", (p,)) -print(cur.fetchone()[0]) diff --git a/Doc/lib/sqlite3/adapter_point_2.py b/Doc/lib/sqlite3/adapter_point_2.py deleted file mode 100644 index 1e1719a..0000000 --- a/Doc/lib/sqlite3/adapter_point_2.py +++ /dev/null @@ -1,17 +0,0 @@ -import sqlite3 - -class Point(object): - def __init__(self, x, y): - self.x, self.y = x, y - -def adapt_point(point): - return "%f;%f" % (point.x, point.y) - -sqlite3.register_adapter(Point, adapt_point) - -con = sqlite3.connect(":memory:") -cur = con.cursor() - -p = Point(4.0, -3.2) -cur.execute("select ?", (p,)) -print(cur.fetchone()[0]) diff --git a/Doc/lib/sqlite3/collation_reverse.py b/Doc/lib/sqlite3/collation_reverse.py deleted file mode 100644 index bfd7f5b..0000000 --- a/Doc/lib/sqlite3/collation_reverse.py +++ /dev/null @@ -1,15 +0,0 @@ -import sqlite3 - -def collate_reverse(string1, string2): - return -cmp(string1, string2) - -con = sqlite3.connect(":memory:") -con.create_collation("reverse", collate_reverse) - -cur = con.cursor() -cur.execute("create table test(x)") -cur.executemany("insert into test(x) values (?)", [("a",), ("b",)]) -cur.execute("select x from test order by x collate reverse") -for row in cur: - print(row) -con.close() diff --git a/Doc/lib/sqlite3/complete_statement.py b/Doc/lib/sqlite3/complete_statement.py deleted file mode 100644 index cd38d73..0000000 --- a/Doc/lib/sqlite3/complete_statement.py +++ /dev/null @@ -1,30 +0,0 @@ -# A minimal SQLite shell for experiments - -import sqlite3 - -con = sqlite3.connect(":memory:") -con.isolation_level = None -cur = con.cursor() - -buffer = "" - -print("Enter your SQL commands to execute in sqlite3.") -print("Enter a blank line to exit.") - -while True: - line = input() - if line == "": - break - buffer += line - if sqlite3.complete_statement(buffer): - try: - buffer = buffer.strip() - cur.execute(buffer) - - if buffer.lstrip().upper().startswith("SELECT"): - print(cur.fetchall()) - except sqlite3.Error as e: - print("An error occurred:", e.args[0]) - buffer = "" - -con.close() diff --git a/Doc/lib/sqlite3/connect_db_1.py b/Doc/lib/sqlite3/connect_db_1.py deleted file mode 100644 index 1b97523..0000000 --- a/Doc/lib/sqlite3/connect_db_1.py +++ /dev/null @@ -1,3 +0,0 @@ -import sqlite3 - -con = sqlite3.connect("mydb") diff --git a/Doc/lib/sqlite3/connect_db_2.py b/Doc/lib/sqlite3/connect_db_2.py deleted file mode 100644 index f9728b36..0000000 --- a/Doc/lib/sqlite3/connect_db_2.py +++ /dev/null @@ -1,3 +0,0 @@ -import sqlite3 - -con = sqlite3.connect(":memory:") diff --git a/Doc/lib/sqlite3/converter_point.py b/Doc/lib/sqlite3/converter_point.py deleted file mode 100644 index d0707ab..0000000 --- a/Doc/lib/sqlite3/converter_point.py +++ /dev/null @@ -1,47 +0,0 @@ -import sqlite3 - -class Point(object): - def __init__(self, x, y): - self.x, self.y = x, y - - def __repr__(self): - return "(%f;%f)" % (self.x, self.y) - -def adapt_point(point): - return "%f;%f" % (point.x, point.y) - -def convert_point(s): - x, y = list(map(float, s.split(";"))) - return Point(x, y) - -# Register the adapter -sqlite3.register_adapter(Point, adapt_point) - -# Register the converter -sqlite3.register_converter("point", convert_point) - -p = Point(4.0, -3.2) - -######################### -# 1) Using declared types -con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES) -cur = con.cursor() -cur.execute("create table test(p point)") - -cur.execute("insert into test(p) values (?)", (p,)) -cur.execute("select p from test") -print("with declared types:", cur.fetchone()[0]) -cur.close() -con.close() - -####################### -# 1) Using column names -con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES) -cur = con.cursor() -cur.execute("create table test(p)") - -cur.execute("insert into test(p) values (?)", (p,)) -cur.execute('select p as "p [point]" from test') -print("with column names:", cur.fetchone()[0]) -cur.close() -con.close() diff --git a/Doc/lib/sqlite3/countcursors.py b/Doc/lib/sqlite3/countcursors.py deleted file mode 100644 index ef3e70a..0000000 --- a/Doc/lib/sqlite3/countcursors.py +++ /dev/null @@ -1,15 +0,0 @@ -import sqlite3 - -class CountCursorsConnection(sqlite3.Connection): - def __init__(self, *args, **kwargs): - sqlite3.Connection.__init__(self, *args, **kwargs) - self.numcursors = 0 - - def cursor(self, *args, **kwargs): - self.numcursors += 1 - return sqlite3.Connection.cursor(self, *args, **kwargs) - -con = sqlite3.connect(":memory:", factory=CountCursorsConnection) -cur1 = con.cursor() -cur2 = con.cursor() -print(con.numcursors) diff --git a/Doc/lib/sqlite3/createdb.py b/Doc/lib/sqlite3/createdb.py deleted file mode 100644 index ee2950b..0000000 --- a/Doc/lib/sqlite3/createdb.py +++ /dev/null @@ -1,28 +0,0 @@ -# Not referenced from the documentation, but builds the database file the other -# code snippets expect. - -import sqlite3 -import os - -DB_FILE = "mydb" - -if os.path.exists(DB_FILE): - os.remove(DB_FILE) - -con = sqlite3.connect(DB_FILE) -cur = con.cursor() -cur.execute(""" - create table people - ( - name_last varchar(20), - age integer - ) - """) - -cur.execute("insert into people (name_last, age) values ('Yeltsin', 72)") -cur.execute("insert into people (name_last, age) values ('Putin', 51)") - -con.commit() - -cur.close() -con.close() diff --git a/Doc/lib/sqlite3/execsql_fetchonerow.py b/Doc/lib/sqlite3/execsql_fetchonerow.py deleted file mode 100644 index 078873b..0000000 --- a/Doc/lib/sqlite3/execsql_fetchonerow.py +++ /dev/null @@ -1,17 +0,0 @@ -import sqlite3 - -con = sqlite3.connect("mydb") - -cur = con.cursor() -SELECT = "select name_last, age from people order by age, name_last" - -# 1. Iterate over the rows available from the cursor, unpacking the -# resulting sequences to yield their elements (name_last, age): -cur.execute(SELECT) -for (name_last, age) in cur: - print('%s is %d years old.' % (name_last, age)) - -# 2. Equivalently: -cur.execute(SELECT) -for row in cur: - print('%s is %d years old.' % (row[0], row[1])) diff --git a/Doc/lib/sqlite3/execsql_printall_1.py b/Doc/lib/sqlite3/execsql_printall_1.py deleted file mode 100644 index a4ce5c5..0000000 --- a/Doc/lib/sqlite3/execsql_printall_1.py +++ /dev/null @@ -1,13 +0,0 @@ -import sqlite3 - -# Create a connection to the database file "mydb": -con = sqlite3.connect("mydb") - -# Get a Cursor object that operates in the context of Connection con: -cur = con.cursor() - -# Execute the SELECT statement: -cur.execute("select * from people order by age") - -# Retrieve all rows as a sequence and print that sequence: -print(cur.fetchall()) diff --git a/Doc/lib/sqlite3/execute_1.py b/Doc/lib/sqlite3/execute_1.py deleted file mode 100644 index 3d08840..0000000 --- a/Doc/lib/sqlite3/execute_1.py +++ /dev/null @@ -1,11 +0,0 @@ -import sqlite3 - -con = sqlite3.connect("mydb") - -cur = con.cursor() - -who = "Yeltsin" -age = 72 - -cur.execute("select name_last, age from people where name_last=? and age=?", (who, age)) -print(cur.fetchone()) diff --git a/Doc/lib/sqlite3/execute_2.py b/Doc/lib/sqlite3/execute_2.py deleted file mode 100644 index 84734f9..0000000 --- a/Doc/lib/sqlite3/execute_2.py +++ /dev/null @@ -1,12 +0,0 @@ -import sqlite3 - -con = sqlite3.connect("mydb") - -cur = con.cursor() - -who = "Yeltsin" -age = 72 - -cur.execute("select name_last, age from people where name_last=:who and age=:age", - {"who": who, "age": age}) -print(cur.fetchone()) diff --git a/Doc/lib/sqlite3/execute_3.py b/Doc/lib/sqlite3/execute_3.py deleted file mode 100644 index 0353683..0000000 --- a/Doc/lib/sqlite3/execute_3.py +++ /dev/null @@ -1,12 +0,0 @@ -import sqlite3 - -con = sqlite3.connect("mydb") - -cur = con.cursor() - -who = "Yeltsin" -age = 72 - -cur.execute("select name_last, age from people where name_last=:who and age=:age", - locals()) -print(cur.fetchone()) diff --git a/Doc/lib/sqlite3/executemany_1.py b/Doc/lib/sqlite3/executemany_1.py deleted file mode 100644 index efae106..0000000 --- a/Doc/lib/sqlite3/executemany_1.py +++ /dev/null @@ -1,24 +0,0 @@ -import sqlite3 - -class IterChars: - def __init__(self): - self.count = ord('a') - - def __iter__(self): - return self - - def __next__(self): - if self.count > ord('z'): - raise StopIteration - self.count += 1 - return (chr(self.count - 1),) # this is a 1-tuple - -con = sqlite3.connect(":memory:") -cur = con.cursor() -cur.execute("create table characters(c)") - -theIter = IterChars() -cur.executemany("insert into characters(c) values (?)", theIter) - -cur.execute("select c from characters") -print(cur.fetchall()) diff --git a/Doc/lib/sqlite3/executemany_2.py b/Doc/lib/sqlite3/executemany_2.py deleted file mode 100644 index 518cd94..0000000 --- a/Doc/lib/sqlite3/executemany_2.py +++ /dev/null @@ -1,15 +0,0 @@ -import sqlite3 - -def char_generator(): - import string - for c in string.letters[:26]: - yield (c,) - -con = sqlite3.connect(":memory:") -cur = con.cursor() -cur.execute("create table characters(c)") - -cur.executemany("insert into characters(c) values (?)", char_generator()) - -cur.execute("select c from characters") -print(cur.fetchall()) diff --git a/Doc/lib/sqlite3/executescript.py b/Doc/lib/sqlite3/executescript.py deleted file mode 100644 index 7e53581..0000000 --- a/Doc/lib/sqlite3/executescript.py +++ /dev/null @@ -1,24 +0,0 @@ -import sqlite3 - -con = sqlite3.connect(":memory:") -cur = con.cursor() -cur.executescript(""" - create table person( - firstname, - lastname, - age - ); - - create table book( - title, - author, - published - ); - - insert into book(title, author, published) - values ( - 'Dirk Gently''s Holistic Detective Agency', - 'Douglas Adams', - 1987 - ); - """) diff --git a/Doc/lib/sqlite3/insert_more_people.py b/Doc/lib/sqlite3/insert_more_people.py deleted file mode 100644 index edbc79e..0000000 --- a/Doc/lib/sqlite3/insert_more_people.py +++ /dev/null @@ -1,16 +0,0 @@ -import sqlite3 - -con = sqlite3.connect("mydb") - -cur = con.cursor() - -newPeople = ( - ('Lebed' , 53), - ('Zhirinovsky' , 57), - ) - -for person in newPeople: - cur.execute("insert into people (name_last, age) values (?, ?)", person) - -# The changes will not be saved unless the transaction is committed explicitly: -con.commit() diff --git a/Doc/lib/sqlite3/md5func.py b/Doc/lib/sqlite3/md5func.py deleted file mode 100644 index b7bc05b..0000000 --- a/Doc/lib/sqlite3/md5func.py +++ /dev/null @@ -1,11 +0,0 @@ -import sqlite3 -import hashlib - -def md5sum(t): - return hashlib.md5(t).hexdigest() - -con = sqlite3.connect(":memory:") -con.create_function("md5", 1, md5sum) -cur = con.cursor() -cur.execute("select md5(?)", ("foo",)) -print(cur.fetchone()[0]) diff --git a/Doc/lib/sqlite3/mysumaggr.py b/Doc/lib/sqlite3/mysumaggr.py deleted file mode 100644 index d2dfd2c..0000000 --- a/Doc/lib/sqlite3/mysumaggr.py +++ /dev/null @@ -1,20 +0,0 @@ -import sqlite3 - -class MySum: - def __init__(self): - self.count = 0 - - def step(self, value): - self.count += value - - def finalize(self): - return self.count - -con = sqlite3.connect(":memory:") -con.create_aggregate("mysum", 1, MySum) -cur = con.cursor() -cur.execute("create table test(i)") -cur.execute("insert into test(i) values (1)") -cur.execute("insert into test(i) values (2)") -cur.execute("select mysum(i) from test") -print(cur.fetchone()[0]) diff --git a/Doc/lib/sqlite3/parse_colnames.py b/Doc/lib/sqlite3/parse_colnames.py deleted file mode 100644 index cc68c76..0000000 --- a/Doc/lib/sqlite3/parse_colnames.py +++ /dev/null @@ -1,8 +0,0 @@ -import sqlite3 -import datetime - -con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES) -cur = con.cursor() -cur.execute('select ? as "x [timestamp]"', (datetime.datetime.now(),)) -dt = cur.fetchone()[0] -print(dt, type(dt)) diff --git a/Doc/lib/sqlite3/pysqlite_datetime.py b/Doc/lib/sqlite3/pysqlite_datetime.py deleted file mode 100644 index 68d4935..0000000 --- a/Doc/lib/sqlite3/pysqlite_datetime.py +++ /dev/null @@ -1,20 +0,0 @@ -import sqlite3 -import datetime - -con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES|sqlite3.PARSE_COLNAMES) -cur = con.cursor() -cur.execute("create table test(d date, ts timestamp)") - -today = datetime.date.today() -now = datetime.datetime.now() - -cur.execute("insert into test(d, ts) values (?, ?)", (today, now)) -cur.execute("select d, ts from test") -row = cur.fetchone() -print(today, "=>", row[0], type(row[0])) -print(now, "=>", row[1], type(row[1])) - -cur.execute('select current_date as "d [date]", current_timestamp as "ts [timestamp]"') -row = cur.fetchone() -print("current_date", row[0], type(row[0])) -print("current_timestamp", row[1], type(row[1])) diff --git a/Doc/lib/sqlite3/row_factory.py b/Doc/lib/sqlite3/row_factory.py deleted file mode 100644 index e436ffc..0000000 --- a/Doc/lib/sqlite3/row_factory.py +++ /dev/null @@ -1,13 +0,0 @@ -import sqlite3 - -def dict_factory(cursor, row): - d = {} - for idx, col in enumerate(cursor.description): - d[col[0]] = row[idx] - return d - -con = sqlite3.connect(":memory:") -con.row_factory = dict_factory -cur = con.cursor() -cur.execute("select 1 as a") -print(cur.fetchone()["a"]) diff --git a/Doc/lib/sqlite3/rowclass.py b/Doc/lib/sqlite3/rowclass.py deleted file mode 100644 index 3fa0b87..0000000 --- a/Doc/lib/sqlite3/rowclass.py +++ /dev/null @@ -1,12 +0,0 @@ -import sqlite3 - -con = sqlite3.connect("mydb") -con.row_factory = sqlite3.Row - -cur = con.cursor() -cur.execute("select name_last, age from people") -for row in cur: - assert row[0] == row["name_last"] - assert row["name_last"] == row["nAmE_lAsT"] - assert row[1] == row["age"] - assert row[1] == row["AgE"] diff --git a/Doc/lib/sqlite3/shared_cache.py b/Doc/lib/sqlite3/shared_cache.py deleted file mode 100644 index bf1d7b4..0000000 --- a/Doc/lib/sqlite3/shared_cache.py +++ /dev/null @@ -1,6 +0,0 @@ -import sqlite3 - -# The shared cache is only available in SQLite versions 3.3.3 or later -# See the SQLite documentaton for details. - -sqlite3.enable_shared_cache(True) diff --git a/Doc/lib/sqlite3/shortcut_methods.py b/Doc/lib/sqlite3/shortcut_methods.py deleted file mode 100644 index 596d87c..0000000 --- a/Doc/lib/sqlite3/shortcut_methods.py +++ /dev/null @@ -1,21 +0,0 @@ -import sqlite3 - -persons = [ - ("Hugo", "Boss"), - ("Calvin", "Klein") - ] - -con = sqlite3.connect(":memory:") - -# Create the table -con.execute("create table person(firstname, lastname)") - -# Fill the table -con.executemany("insert into person(firstname, lastname) values (?, ?)", persons) - -# Print the table contents -for row in con.execute("select firstname, lastname from person"): - print(row) - -# Using a dummy WHERE clause to not let SQLite take the shortcut table deletes. -print("I just deleted", con.execute("delete from person where 1=1").rowcount, "rows") diff --git a/Doc/lib/sqlite3/simple_tableprinter.py b/Doc/lib/sqlite3/simple_tableprinter.py deleted file mode 100644 index 231d872..0000000 --- a/Doc/lib/sqlite3/simple_tableprinter.py +++ /dev/null @@ -1,26 +0,0 @@ -import sqlite3 - -FIELD_MAX_WIDTH = 20 -TABLE_NAME = 'people' -SELECT = 'select * from %s order by age, name_last' % TABLE_NAME - -con = sqlite3.connect("mydb") - -cur = con.cursor() -cur.execute(SELECT) - -# Print a header. -for fieldDesc in cur.description: - print(fieldDesc[0].ljust(FIELD_MAX_WIDTH), end=' ') -print() # Finish the header with a newline. -print('-' * 78) - -# For each row, print the value of each field left-justified within -# the maximum possible width of that field. -fieldIndices = range(len(cur.description)) -for row in cur: - for fieldIndex in fieldIndices: - fieldValue = str(row[fieldIndex]) - print(fieldValue.ljust(FIELD_MAX_WIDTH), end=' ') - - print() # Finish the row with a newline. diff --git a/Doc/lib/sqlite3/text_factory.py b/Doc/lib/sqlite3/text_factory.py deleted file mode 100644 index 2dab8e4..0000000 --- a/Doc/lib/sqlite3/text_factory.py +++ /dev/null @@ -1,42 +0,0 @@ -import sqlite3 - -con = sqlite3.connect(":memory:") -cur = con.cursor() - -# Create the table -con.execute("create table person(lastname, firstname)") - -AUSTRIA = "\xd6sterreich" - -# by default, rows are returned as Unicode -cur.execute("select ?", (AUSTRIA,)) -row = cur.fetchone() -assert row[0] == AUSTRIA - -# but we can make pysqlite always return bytestrings ... -con.text_factory = str -cur.execute("select ?", (AUSTRIA,)) -row = cur.fetchone() -assert type(row[0]) == str -# the bytestrings will be encoded in UTF-8, unless you stored garbage in the -# database ... -assert row[0] == AUSTRIA.encode("utf-8") - -# we can also implement a custom text_factory ... -# here we implement one that will ignore Unicode characters that cannot be -# decoded from UTF-8 -con.text_factory = lambda x: str(x, "utf-8", "ignore") -cur.execute("select ?", ("this is latin1 and would normally create errors" + "\xe4\xf6\xfc".encode("latin1"),)) -row = cur.fetchone() -assert type(row[0]) == str - -# pysqlite offers a builtin optimized text_factory that will return bytestring -# objects, if the data is in ASCII only, and otherwise return unicode objects -con.text_factory = sqlite3.OptimizedUnicode -cur.execute("select ?", (AUSTRIA,)) -row = cur.fetchone() -assert type(row[0]) == str - -cur.execute("select ?", ("Germany",)) -row = cur.fetchone() -assert type(row[0]) == str diff --git a/Doc/lib/tkinter.tex b/Doc/lib/tkinter.tex deleted file mode 100644 index 20b2373..0000000 --- a/Doc/lib/tkinter.tex +++ /dev/null @@ -1,1873 +0,0 @@ -\chapter{Graphical User Interfaces with Tk \label{tkinter}} - -\index{GUI} -\index{Graphical User Interface} -\index{Tkinter} -\index{Tk} - -Tk/Tcl has long been an integral part of Python. It provides a robust -and platform independent windowing toolkit, that is available to -Python programmers using the \refmodule{Tkinter} module, and its -extension, the \refmodule{Tix} module. - -The \refmodule{Tkinter} module is a thin object-oriented layer on top of -Tcl/Tk. To use \refmodule{Tkinter}, you don't need to write Tcl code, -but you will need to consult the Tk documentation, and occasionally -the Tcl documentation. \refmodule{Tkinter} is a set of wrappers that -implement the Tk widgets as Python classes. In addition, the internal -module \module{\_tkinter} provides a threadsafe mechanism which allows -Python and Tcl to interact. - -Tk is not the only GUI for Python; see -section~\ref{other-gui-packages}, ``Other User Interface Modules and -Packages,'' for more information on other GUI toolkits for Python. - -% Other sections I have in mind are -% Tkinter internals -% Freezing Tkinter applications - -\localmoduletable - - -\section{\module{Tkinter} --- - Python interface to Tcl/Tk} - -\declaremodule{standard}{Tkinter} -\modulesynopsis{Interface to Tcl/Tk for graphical user interfaces} -\moduleauthor{Guido van Rossum}{guido@Python.org} - -The \module{Tkinter} module (``Tk interface'') is the standard Python -interface to the Tk GUI toolkit. Both Tk and \module{Tkinter} are -available on most \UNIX{} platforms, as well as on Windows and -Macintosh systems. (Tk itself is not part of Python; it is maintained -at ActiveState.) - -\begin{seealso} -\seetitle[http://www.python.org/topics/tkinter/] - {Python Tkinter Resources} - {The Python Tkinter Topic Guide provides a great - deal of information on using Tk from Python and links to - other sources of information on Tk.} - -\seetitle[http://www.pythonware.com/library/an-introduction-to-tkinter.htm] - {An Introduction to Tkinter} - {Fredrik Lundh's on-line reference material.} - -\seetitle[http://www.nmt.edu/tcc/help/pubs/lang.html] - {Tkinter reference: a GUI for Python} - {On-line reference material.} - -\seetitle[http://jtkinter.sourceforge.net] - {Tkinter for JPython} - {The Jython interface to Tkinter.} - -\seetitle[http://www.amazon.com/exec/obidos/ASIN/1884777813] - {Python and Tkinter Programming} - {The book by John Grayson (ISBN 1-884777-81-3).} -\end{seealso} - - -\subsection{Tkinter Modules} - -Most of the time, the \refmodule{Tkinter} module is all you really -need, but a number of additional modules are available as well. The -Tk interface is located in a binary module named \module{_tkinter}. -This module contains the low-level interface to Tk, and should never -be used directly by application programmers. It is usually a shared -library (or DLL), but might in some cases be statically linked with -the Python interpreter. - -In addition to the Tk interface module, \refmodule{Tkinter} includes a -number of Python modules. The two most important modules are the -\refmodule{Tkinter} module itself, and a module called -\module{Tkconstants}. The former automatically imports the latter, so -to use Tkinter, all you need to do is to import one module: - -\begin{verbatim} -import Tkinter -\end{verbatim} - -Or, more often: - -\begin{verbatim} -from Tkinter import * -\end{verbatim} - -\begin{classdesc}{Tk}{screenName=None, baseName=None, className='Tk', useTk=1} -The \class{Tk} class is instantiated without arguments. -This creates a toplevel widget of Tk which usually is the main window -of an application. Each instance has its own associated Tcl interpreter. -% FIXME: The following keyword arguments are currently recognized: -\versionchanged[The \var{useTk} parameter was added]{2.4} -\end{classdesc} - -\begin{funcdesc}{Tcl}{screenName=None, baseName=None, className='Tk', useTk=0} -The \function{Tcl} function is a factory function which creates an -object much like that created by the \class{Tk} class, except that it -does not initialize the Tk subsystem. This is most often useful when -driving the Tcl interpreter in an environment where one doesn't want -to create extraneous toplevel windows, or where one cannot (such as -\UNIX/Linux systems without an X server). An object created by the -\function{Tcl} object can have a Toplevel window created (and the Tk -subsystem initialized) by calling its \method{loadtk} method. -\versionadded{2.4} -\end{funcdesc} - -Other modules that provide Tk support include: - -\begin{description} -% \declaremodule{standard}{Tkconstants} -% \modulesynopsis{Constants used by Tkinter} -% FIXME - -\item[\refmodule{ScrolledText}] -Text widget with a vertical scroll bar built in. - -\item[\module{tkColorChooser}] -Dialog to let the user choose a color. - -\item[\module{tkCommonDialog}] -Base class for the dialogs defined in the other modules listed here. - -\item[\module{tkFileDialog}] -Common dialogs to allow the user to specify a file to open or save. - -\item[\module{tkFont}] -Utilities to help work with fonts. - -\item[\module{tkMessageBox}] -Access to standard Tk dialog boxes. - -\item[\module{tkSimpleDialog}] -Basic dialogs and convenience functions. - -\item[\module{Tkdnd}] -Drag-and-drop support for \refmodule{Tkinter}. -This is experimental and should become deprecated when it is replaced -with the Tk DND. - -\item[\refmodule{turtle}] -Turtle graphics in a Tk window. - -\end{description} - -\subsection{Tkinter Life Preserver} -\sectionauthor{Matt Conway}{} -% Converted to LaTeX by Mike Clarkson. - -This section is not designed to be an exhaustive tutorial on either -Tk or Tkinter. Rather, it is intended as a stop gap, providing some -introductory orientation on the system. - -Credits: -\begin{itemize} -\item Tkinter was written by Steen Lumholt and Guido van Rossum. -\item Tk was written by John Ousterhout while at Berkeley. -\item This Life Preserver was written by Matt Conway at -the University of Virginia. -\item The html rendering, and some liberal editing, was -produced from a FrameMaker version by Ken Manheimer. -\item Fredrik Lundh elaborated and revised the class interface descriptions, -to get them current with Tk 4.2. -\item Mike Clarkson converted the documentation to \LaTeX, and compiled the -User Interface chapter of the reference manual. -\end{itemize} - - -\subsubsection{How To Use This Section} - -This section is designed in two parts: the first half (roughly) covers -background material, while the second half can be taken to the -keyboard as a handy reference. - -When trying to answer questions of the form ``how do I do blah'', it -is often best to find out how to do``blah'' in straight Tk, and then -convert this back into the corresponding \refmodule{Tkinter} call. -Python programmers can often guess at the correct Python command by -looking at the Tk documentation. This means that in order to use -Tkinter, you will have to know a little bit about Tk. This document -can't fulfill that role, so the best we can do is point you to the -best documentation that exists. Here are some hints: - -\begin{itemize} -\item The authors strongly suggest getting a copy of the Tk man -pages. Specifically, the man pages in the \code{mann} directory are most -useful. The \code{man3} man pages describe the C interface to the Tk -library and thus are not especially helpful for script writers. - -\item Addison-Wesley publishes a book called \citetitle{Tcl and the -Tk Toolkit} by John Ousterhout (ISBN 0-201-63337-X) which is a good -introduction to Tcl and Tk for the novice. The book is not -exhaustive, and for many details it defers to the man pages. - -\item \file{Tkinter.py} is a last resort for most, but can be a good -place to go when nothing else makes sense. -\end{itemize} - -\begin{seealso} -\seetitle[http://tcl.activestate.com/] - {ActiveState Tcl Home Page} - {The Tk/Tcl development is largely taking place at - ActiveState.} -\seetitle[http://www.amazon.com/exec/obidos/ASIN/020163337X] - {Tcl and the Tk Toolkit} - {The book by John Ousterhout, the inventor of Tcl .} -\seetitle[http://www.amazon.com/exec/obidos/ASIN/0130220280] - {Practical Programming in Tcl and Tk} - {Brent Welch's encyclopedic book.} -\end{seealso} - - -\subsubsection{A Simple Hello World Program} % HelloWorld.html - -%begin{latexonly} -%\begin{figure}[hbtp] -%\centerline{\epsfig{file=HelloWorld.gif,width=.9\textwidth}} -%\vspace{.5cm} -%\caption{HelloWorld gadget image} -%\end{figure} -%See also the hello-world \ulink{notes}{classes/HelloWorld-notes.html} and -%\ulink{summary}{classes/HelloWorld-summary.html}. -%end{latexonly} - - -\begin{verbatim} -from Tkinter import * - -class Application(Frame): - def say_hi(self): - print "hi there, everyone!" - - def createWidgets(self): - self.QUIT = Button(self) - self.QUIT["text"] = "QUIT" - self.QUIT["fg"] = "red" - self.QUIT["command"] = self.quit - - self.QUIT.pack({"side": "left"}) - - self.hi_there = Button(self) - self.hi_there["text"] = "Hello", - self.hi_there["command"] = self.say_hi - - self.hi_there.pack({"side": "left"}) - - def __init__(self, master=None): - Frame.__init__(self, master) - self.pack() - self.createWidgets() - -root = Tk() -app = Application(master=root) -app.mainloop() -root.destroy() -\end{verbatim} - - -\subsection{A (Very) Quick Look at Tcl/Tk} % BriefTclTk.html - -The class hierarchy looks complicated, but in actual practice, -application programmers almost always refer to the classes at the very -bottom of the hierarchy. - -Notes: -\begin{itemize} -\item These classes are provided for the purposes of -organizing certain functions under one namespace. They aren't meant to -be instantiated independently. - -\item The \class{Tk} class is meant to be instantiated only once in -an application. Application programmers need not instantiate one -explicitly, the system creates one whenever any of the other classes -are instantiated. - -\item The \class{Widget} class is not meant to be instantiated, it -is meant only for subclassing to make ``real'' widgets (in \Cpp, this -is called an `abstract class'). -\end{itemize} - -To make use of this reference material, there will be times when you -will need to know how to read short passages of Tk and how to identify -the various parts of a Tk command. -(See section~\ref{tkinter-basic-mapping} for the -\refmodule{Tkinter} equivalents of what's below.) - -Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are -just lists of tokens separated by spaces. A Tk widget is just its -\emph{class}, the \emph{options} that help configure it, and the -\emph{actions} that make it do useful things. - -To make a widget in Tk, the command is always of the form: - -\begin{verbatim} - classCommand newPathname options -\end{verbatim} - -\begin{description} -\item[\var{classCommand}] -denotes which kind of widget to make (a button, a label, a menu...) - -\item[\var{newPathname}] -is the new name for this widget. All names in Tk must be unique. To -help enforce this, widgets in Tk are named with \emph{pathnames}, just -like files in a file system. The top level widget, the \emph{root}, -is called \code{.} (period) and children are delimited by more -periods. For example, \code{.myApp.controlPanel.okButton} might be -the name of a widget. - -\item[\var{options}] -configure the widget's appearance and in some cases, its -behavior. The options come in the form of a list of flags and values. -Flags are preceded by a `-', like \UNIX{} shell command flags, and -values are put in quotes if they are more than one word. -\end{description} - -For example: - -\begin{verbatim} - button .fred -fg red -text "hi there" - ^ ^ \_____________________/ - | | | - class new options - command widget (-opt val -opt val ...) -\end{verbatim} - -Once created, the pathname to the widget becomes a new command. This -new \var{widget command} is the programmer's handle for getting the new -widget to perform some \var{action}. In C, you'd express this as -someAction(fred, someOptions), in \Cpp, you would express this as -fred.someAction(someOptions), and in Tk, you say: - -\begin{verbatim} - .fred someAction someOptions -\end{verbatim} - -Note that the object name, \code{.fred}, starts with a dot. - -As you'd expect, the legal values for \var{someAction} will depend on -the widget's class: \code{.fred disable} works if fred is a -button (fred gets greyed out), but does not work if fred is a label -(disabling of labels is not supported in Tk). - -The legal values of \var{someOptions} is action dependent. Some -actions, like \code{disable}, require no arguments, others, like -a text-entry box's \code{delete} command, would need arguments -to specify what range of text to delete. - - -\subsection{Mapping Basic Tk into Tkinter - \label{tkinter-basic-mapping}} - -Class commands in Tk correspond to class constructors in Tkinter. - -\begin{verbatim} - button .fred =====> fred = Button() -\end{verbatim} - -The master of an object is implicit in the new name given to it at -creation time. In Tkinter, masters are specified explicitly. - -\begin{verbatim} - button .panel.fred =====> fred = Button(panel) -\end{verbatim} - -The configuration options in Tk are given in lists of hyphened tags -followed by values. In Tkinter, options are specified as -keyword-arguments in the instance constructor, and keyword-args for -configure calls or as instance indices, in dictionary style, for -established instances. See section~\ref{tkinter-setting-options} on -setting options. - -\begin{verbatim} - button .fred -fg red =====> fred = Button(panel, fg = "red") - .fred configure -fg red =====> fred["fg"] = red - OR ==> fred.config(fg = "red") -\end{verbatim} - -In Tk, to perform an action on a widget, use the widget name as a -command, and follow it with an action name, possibly with arguments -(options). In Tkinter, you call methods on the class instance to -invoke actions on the widget. The actions (methods) that a given -widget can perform are listed in the Tkinter.py module. - -\begin{verbatim} - .fred invoke =====> fred.invoke() -\end{verbatim} - -To give a widget to the packer (geometry manager), you call pack with -optional arguments. In Tkinter, the Pack class holds all this -functionality, and the various forms of the pack command are -implemented as methods. All widgets in \refmodule{Tkinter} are -subclassed from the Packer, and so inherit all the packing -methods. See the \refmodule{Tix} module documentation for additional -information on the Form geometry manager. - -\begin{verbatim} - pack .fred -side left =====> fred.pack(side = "left") -\end{verbatim} - - -\subsection{How Tk and Tkinter are Related} % Relationship.html - -\note{This was derived from a graphical image; the image will be used - more directly in a subsequent version of this document.} - -From the top down: -\begin{description} -\item[\b{Your App Here (Python)}] -A Python application makes a \refmodule{Tkinter} call. - -\item[\b{Tkinter (Python Module)}] -This call (say, for example, creating a button widget), is -implemented in the \emph{Tkinter} module, which is written in -Python. This Python function will parse the commands and the -arguments and convert them into a form that makes them look as if they -had come from a Tk script instead of a Python script. - -\item[\b{tkinter (C)}] -These commands and their arguments will be passed to a C function -in the \emph{tkinter} - note the lowercase - extension module. - -\item[\b{Tk Widgets} (C and Tcl)] -This C function is able to make calls into other C modules, -including the C functions that make up the Tk library. Tk is -implemented in C and some Tcl. The Tcl part of the Tk widgets is used -to bind certain default behaviors to widgets, and is executed once at -the point where the Python \refmodule{Tkinter} module is -imported. (The user never sees this stage). - -\item[\b{Tk (C)}] -The Tk part of the Tk Widgets implement the final mapping to ... - -\item[\b{Xlib (C)}] -the Xlib library to draw graphics on the screen. -\end{description} - - -\subsection{Handy Reference} - -\subsubsection{Setting Options - \label{tkinter-setting-options}} - -Options control things like the color and border width of a widget. -Options can be set in three ways: - -\begin{description} -\item[At object creation time, using keyword arguments]: -\begin{verbatim} -fred = Button(self, fg = "red", bg = "blue") -\end{verbatim} -\item[After object creation, treating the option name like a dictionary index]: -\begin{verbatim} -fred["fg"] = "red" -fred["bg"] = "blue" -\end{verbatim} -\item[Use the config() method to update multiple attrs subsequent to -object creation]: -\begin{verbatim} -fred.config(fg = "red", bg = "blue") -\end{verbatim} -\end{description} - -For a complete explanation of a given option and its behavior, see the -Tk man pages for the widget in question. - -Note that the man pages list "STANDARD OPTIONS" and "WIDGET SPECIFIC -OPTIONS" for each widget. The former is a list of options that are -common to many widgets, the latter are the options that are -idiosyncratic to that particular widget. The Standard Options are -documented on the \manpage{options}{3} man page. - -No distinction between standard and widget-specific options is made in -this document. Some options don't apply to some kinds of widgets. -Whether a given widget responds to a particular option depends on the -class of the widget; buttons have a \code{command} option, labels do not. - -The options supported by a given widget are listed in that widget's -man page, or can be queried at runtime by calling the -\method{config()} method without arguments, or by calling the -\method{keys()} method on that widget. The return value of these -calls is a dictionary whose key is the name of the option as a string -(for example, \code{'relief'}) and whose values are 5-tuples. - -Some options, like \code{bg} are synonyms for common options with long -names (\code{bg} is shorthand for "background"). Passing the -\code{config()} method the name of a shorthand option will return a -2-tuple, not 5-tuple. The 2-tuple passed back will contain the name of -the synonym and the ``real'' option (such as \code{('bg', -'background')}). - -\begin{tableiii}{c|l|l}{textrm}{Index}{Meaning}{Example} - \lineiii{0}{option name} {\code{'relief'}} - \lineiii{1}{option name for database lookup} {\code{'relief'}} - \lineiii{2}{option class for database lookup} {\code{'Relief'}} - \lineiii{3}{default value} {\code{'raised'}} - \lineiii{4}{current value} {\code{'groove'}} -\end{tableiii} - - -Example: - -\begin{verbatim} ->>> print fred.config() -{'relief' : ('relief', 'relief', 'Relief', 'raised', 'groove')} -\end{verbatim} - -Of course, the dictionary printed will include all the options -available and their values. This is meant only as an example. - - -\subsubsection{The Packer} % Packer.html -\index{packing (widgets)} - -The packer is one of Tk's geometry-management mechanisms. -% See also \citetitle[classes/ClassPacker.html]{the Packer class interface}. - -Geometry managers are used to specify the relative positioning of the -positioning of widgets within their container - their mutual -\emph{master}. In contrast to the more cumbersome \emph{placer} -(which is used less commonly, and we do not cover here), the packer -takes qualitative relationship specification - \emph{above}, \emph{to -the left of}, \emph{filling}, etc - and works everything out to -determine the exact placement coordinates for you. - -The size of any \emph{master} widget is determined by the size of -the "slave widgets" inside. The packer is used to control where slave -widgets appear inside the master into which they are packed. You can -pack widgets into frames, and frames into other frames, in order to -achieve the kind of layout you desire. Additionally, the arrangement -is dynamically adjusted to accommodate incremental changes to the -configuration, once it is packed. - -Note that widgets do not appear until they have had their geometry -specified with a geometry manager. It's a common early mistake to -leave out the geometry specification, and then be surprised when the -widget is created but nothing appears. A widget will appear only -after it has had, for example, the packer's \method{pack()} method -applied to it. - -The pack() method can be called with keyword-option/value pairs that -control where the widget is to appear within its container, and how it -is to behave when the main application window is resized. Here are -some examples: - -\begin{verbatim} - fred.pack() # defaults to side = "top" - fred.pack(side = "left") - fred.pack(expand = 1) -\end{verbatim} - - -\subsubsection{Packer Options} - -For more extensive information on the packer and the options that it -can take, see the man pages and page 183 of John Ousterhout's book. - -\begin{description} -\item[\b{anchor }] -Anchor type. Denotes where the packer is to place each slave in its -parcel. - -\item[\b{expand}] -Boolean, \code{0} or \code{1}. - -\item[\b{fill}] -Legal values: \code{'x'}, \code{'y'}, \code{'both'}, \code{'none'}. - -\item[\b{ipadx} and \b{ipady}] -A distance - designating internal padding on each side of the slave -widget. - -\item[\b{padx} and \b{pady}] -A distance - designating external padding on each side of the slave -widget. - -\item[\b{side}] -Legal values are: \code{'left'}, \code{'right'}, \code{'top'}, -\code{'bottom'}. -\end{description} - - -\subsubsection{Coupling Widget Variables} % VarCouplings.html - -The current-value setting of some widgets (like text entry widgets) -can be connected directly to application variables by using special -options. These options are \code{variable}, \code{textvariable}, -\code{onvalue}, \code{offvalue}, and \code{value}. This -connection works both ways: if the variable changes for any reason, -the widget it's connected to will be updated to reflect the new value. - -Unfortunately, in the current implementation of \refmodule{Tkinter} it is -not possible to hand over an arbitrary Python variable to a widget -through a \code{variable} or \code{textvariable} option. The only -kinds of variables for which this works are variables that are -subclassed from a class called Variable, defined in the -\refmodule{Tkinter} module. - -There are many useful subclasses of Variable already defined: -\class{StringVar}, \class{IntVar}, \class{DoubleVar}, and -\class{BooleanVar}. To read the current value of such a variable, -call the \method{get()} method on -it, and to change its value you call the \method{set()} method. If -you follow this protocol, the widget will always track the value of -the variable, with no further intervention on your part. - -For example: -\begin{verbatim} -class App(Frame): - def __init__(self, master=None): - Frame.__init__(self, master) - self.pack() - - self.entrythingy = Entry() - self.entrythingy.pack() - - # here is the application variable - self.contents = StringVar() - # set it to some value - self.contents.set("this is a variable") - # tell the entry widget to watch this variable - self.entrythingy["textvariable"] = self.contents - - # and here we get a callback when the user hits return. - # we will have the program print out the value of the - # application variable when the user hits return - self.entrythingy.bind('<Key-Return>', - self.print_contents) - - def print_contents(self, event): - print "hi. contents of entry is now ---->", \ - self.contents.get() -\end{verbatim} - - -\subsubsection{The Window Manager} % WindowMgr.html -\index{window manager (widgets)} - -In Tk, there is a utility command, \code{wm}, for interacting with the -window manager. Options to the \code{wm} command allow you to control -things like titles, placement, icon bitmaps, and the like. In -\refmodule{Tkinter}, these commands have been implemented as methods -on the \class{Wm} class. Toplevel widgets are subclassed from the -\class{Wm} class, and so can call the \class{Wm} methods directly. - -%See also \citetitle[classes/ClassWm.html]{the Wm class interface}. - -To get at the toplevel window that contains a given widget, you can -often just refer to the widget's master. Of course if the widget has -been packed inside of a frame, the master won't represent a toplevel -window. To get at the toplevel window that contains an arbitrary -widget, you can call the \method{_root()} method. This -method begins with an underscore to denote the fact that this function -is part of the implementation, and not an interface to Tk functionality. - -Here are some examples of typical usage: - -\begin{verbatim} -from Tkinter import * -class App(Frame): - def __init__(self, master=None): - Frame.__init__(self, master) - self.pack() - - -# create the application -myapp = App() - -# -# here are method calls to the window manager class -# -myapp.master.title("My Do-Nothing Application") -myapp.master.maxsize(1000, 400) - -# start the program -myapp.mainloop() -\end{verbatim} - - -\subsubsection{Tk Option Data Types} % OptionTypes.html - -\index{Tk Option Data Types} - -\begin{description} -\item[anchor] -Legal values are points of the compass: \code{"n"}, -\code{"ne"}, \code{"e"}, \code{"se"}, \code{"s"}, -\code{"sw"}, \code{"w"}, \code{"nw"}, and also -\code{"center"}. - -\item[bitmap] -There are eight built-in, named bitmaps: \code{'error'}, \code{'gray25'}, -\code{'gray50'}, \code{'hourglass'}, \code{'info'}, \code{'questhead'}, -\code{'question'}, \code{'warning'}. To specify an X bitmap -filename, give the full path to the file, preceded with an \code{@}, -as in \code{"@/usr/contrib/bitmap/gumby.bit"}. - -\item[boolean] -You can pass integers 0 or 1 or the strings \code{"yes"} or \code{"no"} . - -\item[callback] -This is any Python function that takes no arguments. For example: -\begin{verbatim} - def print_it(): - print "hi there" - fred["command"] = print_it -\end{verbatim} - -\item[color] -Colors can be given as the names of X colors in the rgb.txt file, -or as strings representing RGB values in 4 bit: \code{"\#RGB"}, 8 -bit: \code{"\#RRGGBB"}, 12 bit" \code{"\#RRRGGGBBB"}, or 16 bit -\code{"\#RRRRGGGGBBBB"} ranges, where R,G,B here represent any -legal hex digit. See page 160 of Ousterhout's book for details. - -\item[cursor] -The standard X cursor names from \file{cursorfont.h} can be used, -without the \code{XC_} prefix. For example to get a hand cursor -(\constant{XC_hand2}), use the string \code{"hand2"}. You can also -specify a bitmap and mask file of your own. See page 179 of -Ousterhout's book. - -\item[distance] -Screen distances can be specified in either pixels or absolute -distances. Pixels are given as numbers and absolute distances as -strings, with the trailing character denoting units: \code{c} -for centimetres, \code{i} for inches, \code{m} for millimetres, -\code{p} for printer's points. For example, 3.5 inches is expressed -as \code{"3.5i"}. - -\item[font] -Tk uses a list font name format, such as \code{\{courier 10 bold\}}. -Font sizes with positive numbers are measured in points; -sizes with negative numbers are measured in pixels. - -\item[geometry] -This is a string of the form \samp{\var{width}x\var{height}}, where -width and height are measured in pixels for most widgets (in -characters for widgets displaying text). For example: -\code{fred["geometry"] = "200x100"}. - -\item[justify] -Legal values are the strings: \code{"left"}, -\code{"center"}, \code{"right"}, and \code{"fill"}. - -\item[region] -This is a string with four space-delimited elements, each of -which is a legal distance (see above). For example: \code{"2 3 4 -5"} and \code{"3i 2i 4.5i 2i"} and \code{"3c 2c 4c 10.43c"} -are all legal regions. - -\item[relief] -Determines what the border style of a widget will be. Legal -values are: \code{"raised"}, \code{"sunken"}, -\code{"flat"}, \code{"groove"}, and \code{"ridge"}. - -\item[scrollcommand] -This is almost always the \method{set()} method of some scrollbar -widget, but can be any widget method that takes a single argument. -Refer to the file \file{Demo/tkinter/matt/canvas-with-scrollbars.py} -in the Python source distribution for an example. - -\item[wrap:] -Must be one of: \code{"none"}, \code{"char"}, or \code{"word"}. -\end{description} - - -\subsubsection{Bindings and Events} % Bindings.html - -\index{bind (widgets)} -\index{events (widgets)} - -The bind method from the widget command allows you to watch for -certain events and to have a callback function trigger when that event -type occurs. The form of the bind method is: - -\begin{verbatim} - def bind(self, sequence, func, add=''): -\end{verbatim} -where: - -\begin{description} -\item[sequence] -is a string that denotes the target kind of event. (See the bind -man page and page 201 of John Ousterhout's book for details). - -\item[func] -is a Python function, taking one argument, to be invoked when the -event occurs. An Event instance will be passed as the argument. -(Functions deployed this way are commonly known as \var{callbacks}.) - -\item[add] -is optional, either \samp{} or \samp{+}. Passing an empty string -denotes that this binding is to replace any other bindings that this -event is associated with. Preceeding with a \samp{+} means that this -function is to be added to the list of functions bound to this event type. -\end{description} - -For example: -\begin{verbatim} - def turnRed(self, event): - event.widget["activeforeground"] = "red" - - self.button.bind("<Enter>", self.turnRed) -\end{verbatim} - -Notice how the widget field of the event is being accessed in the -\method{turnRed()} callback. This field contains the widget that -caught the X event. The following table lists the other event fields -you can access, and how they are denoted in Tk, which can be useful -when referring to the Tk man pages. - -\begin{verbatim} -Tk Tkinter Event Field Tk Tkinter Event Field --- ------------------- -- ------------------- -%f focus %A char -%h height %E send_event -%k keycode %K keysym -%s state %N keysym_num -%t time %T type -%w width %W widget -%x x %X x_root -%y y %Y y_root -\end{verbatim} - - -\subsubsection{The index Parameter} % Index.html - -A number of widgets require``index'' parameters to be passed. These -are used to point at a specific place in a Text widget, or to -particular characters in an Entry widget, or to particular menu items -in a Menu widget. - -\begin{description} -\item[\b{Entry widget indexes (index, view index, etc.)}] -Entry widgets have options that refer to character positions in the -text being displayed. You can use these \refmodule{Tkinter} functions -to access these special points in text widgets: - -\begin{description} -\item[AtEnd()] -refers to the last position in the text - -\item[AtInsert()] -refers to the point where the text cursor is - -\item[AtSelFirst()] -indicates the beginning point of the selected text - -\item[AtSelLast()] -denotes the last point of the selected text and finally - -\item[At(x\optional{, y})] -refers to the character at pixel location \var{x}, \var{y} (with -\var{y} not used in the case of a text entry widget, which contains a -single line of text). -\end{description} - -\item[\b{Text widget indexes}] -The index notation for Text widgets is very rich and is best described -in the Tk man pages. - -\item[\b{Menu indexes (menu.invoke(), menu.entryconfig(), etc.)}] - -Some options and methods for menus manipulate specific menu entries. -Anytime a menu index is needed for an option or a parameter, you may -pass in: -\begin{itemize} -\item an integer which refers to the numeric position of the entry in -the widget, counted from the top, starting with 0; -\item the string \code{'active'}, which refers to the menu position that is -currently under the cursor; -\item the string \code{"last"} which refers to the last menu -item; -\item An integer preceded by \code{@}, as in \code{@6}, where the integer is -interpreted as a y pixel coordinate in the menu's coordinate system; -\item the string \code{"none"}, which indicates no menu entry at all, most -often used with menu.activate() to deactivate all entries, and -finally, -\item a text string that is pattern matched against the label of the -menu entry, as scanned from the top of the menu to the bottom. Note -that this index type is considered after all the others, which means -that matches for menu items labelled \code{last}, \code{active}, or -\code{none} may be interpreted as the above literals, instead. -\end{itemize} -\end{description} - -\subsubsection{Images} - -Bitmap/Pixelmap images can be created through the subclasses of -\class{Tkinter.Image}: - -\begin{itemize} -\item \class{BitmapImage} can be used for X11 bitmap data. -\item \class{PhotoImage} can be used for GIF and PPM/PGM color bitmaps. -\end{itemize} - -Either type of image is created through either the \code{file} or the -\code{data} option (other options are available as well). - -The image object can then be used wherever an \code{image} option is -supported by some widget (e.g. labels, buttons, menus). In these -cases, Tk will not keep a reference to the image. When the last Python -reference to the image object is deleted, the image data is deleted as -well, and Tk will display an empty box wherever the image was used. - -\section{\module{Tix} --- - Extension widgets for Tk} - -\declaremodule{standard}{Tix} -\modulesynopsis{Tk Extension Widgets for Tkinter} -\sectionauthor{Mike Clarkson}{mikeclarkson@users.sourceforge.net} - -\index{Tix} - -The \module{Tix} (Tk Interface Extension) module provides an -additional rich set of widgets. Although the standard Tk library has -many useful widgets, they are far from complete. The \module{Tix} -library provides most of the commonly needed widgets that are missing -from standard Tk: \class{HList}, \class{ComboBox}, \class{Control} -(a.k.a. SpinBox) and an assortment of scrollable widgets. \module{Tix} -also includes many more widgets that are generally useful in a wide -range of applications: \class{NoteBook}, \class{FileEntry}, -\class{PanedWindow}, etc; there are more than 40 of them. - -With all these new widgets, you can introduce new interaction -techniques into applications, creating more useful and more intuitive -user interfaces. You can design your application by choosing the most -appropriate widgets to match the special needs of your application and -users. - -\begin{seealso} -\seetitle[http://tix.sourceforge.net/] - {Tix Homepage} - {The home page for \module{Tix}. This includes links to - additional documentation and downloads.} -\seetitle[http://tix.sourceforge.net/dist/current/man/] - {Tix Man Pages} - {On-line version of the man pages and reference material.} -\seetitle[http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html] - {Tix Programming Guide} - {On-line version of the programmer's reference material.} -\seetitle[http://tix.sourceforge.net/Tide/] - {Tix Development Applications} - {Tix applications for development of Tix and Tkinter programs. - Tide applications work under Tk or Tkinter, and include - \program{TixInspect}, an inspector to remotely modify and - debug Tix/Tk/Tkinter applications.} -\end{seealso} - - -\subsection{Using Tix} - -\begin{classdesc}{Tix}{screenName\optional{, baseName\optional{, className}}} - Toplevel widget of Tix which represents mostly the main window - of an application. It has an associated Tcl interpreter. - -Classes in the \refmodule{Tix} module subclasses the classes in the -\refmodule{Tkinter} module. The former imports the latter, so to use -\refmodule{Tix} with Tkinter, all you need to do is to import one -module. In general, you can just import \refmodule{Tix}, and replace -the toplevel call to \class{Tkinter.Tk} with \class{Tix.Tk}: -\begin{verbatim} -import Tix -from Tkconstants import * -root = Tix.Tk() -\end{verbatim} -\end{classdesc} - -To use \refmodule{Tix}, you must have the \refmodule{Tix} widgets installed, -usually alongside your installation of the Tk widgets. -To test your installation, try the following: -\begin{verbatim} -import Tix -root = Tix.Tk() -root.tk.eval('package require Tix') -\end{verbatim} - -If this fails, you have a Tk installation problem which must be -resolved before proceeding. Use the environment variable \envvar{TIX_LIBRARY} -to point to the installed \refmodule{Tix} library directory, and -make sure you have the dynamic object library (\file{tix8183.dll} or -\file{libtix8183.so}) in the same directory that contains your Tk -dynamic object library (\file{tk8183.dll} or \file{libtk8183.so}). The -directory with the dynamic object library should also have a file -called \file{pkgIndex.tcl} (case sensitive), which contains the line: - -\begin{verbatim} -package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix] -\end{verbatim} % $ <-- bow to font-lock - - -\subsection{Tix Widgets} - -\ulink{Tix} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm} -introduces over 40 widget classes to the \refmodule{Tkinter} -repertoire. There is a demo of all the \refmodule{Tix} widgets in the -\file{Demo/tix} directory of the standard distribution. - - -% The Python sample code is still being added to Python, hence commented out - - -\subsubsection{Basic Widgets} - -\begin{classdesc}{Balloon}{} -A \ulink{Balloon} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm} -that pops up over a widget to provide help. When the user moves the -cursor inside a widget to which a Balloon widget has been bound, a -small pop-up window with a descriptive message will be shown on the -screen. -\end{classdesc} - -% Python Demo of: -% \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl} - -\begin{classdesc}{ButtonBox}{} -The \ulink{ButtonBox} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm} -widget creates a box of buttons, such as is commonly used for \code{Ok -Cancel}. -\end{classdesc} - -% Python Demo of: -% \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl} - -\begin{classdesc}{ComboBox}{} -The \ulink{ComboBox} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm} -widget is similar to the combo box control in MS Windows. The user can -select a choice by either typing in the entry subwdget or selecting -from the listbox subwidget. -\end{classdesc} - -% Python Demo of: -% \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl} - -\begin{classdesc}{Control}{} -The \ulink{Control} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm} -widget is also known as the \class{SpinBox} widget. The user can -adjust the value by pressing the two arrow buttons or by entering the -value directly into the entry. The new value will be checked against -the user-defined upper and lower limits. -\end{classdesc} - -% Python Demo of: -% \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl} - -\begin{classdesc}{LabelEntry}{} -The \ulink{LabelEntry} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm} -widget packages an entry widget and a label into one mega widget. It -can be used be used to simplify the creation of ``entry-form'' type of -interface. -\end{classdesc} - -% Python Demo of: -% \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl} - -\begin{classdesc}{LabelFrame}{} -The \ulink{LabelFrame} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm} -widget packages a frame widget and a label into one mega widget. To -create widgets inside a LabelFrame widget, one creates the new widgets -relative to the \member{frame} subwidget and manage them inside the -\member{frame} subwidget. -\end{classdesc} - -% Python Demo of: -% \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl} - -\begin{classdesc}{Meter}{} -The \ulink{Meter} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm} -widget can be used to show the progress of a background job which may -take a long time to execute. -\end{classdesc} - -% Python Demo of: -% \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl} - -\begin{classdesc}{OptionMenu}{} -The \ulink{OptionMenu} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm} -creates a menu button of options. -\end{classdesc} - -% Python Demo of: -% \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl} - -\begin{classdesc}{PopupMenu}{} -The \ulink{PopupMenu} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm} -widget can be used as a replacement of the \code{tk_popup} -command. The advantage of the \refmodule{Tix} \class{PopupMenu} widget -is it requires less application code to manipulate. -\end{classdesc} - -% Python Demo of: -% \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl} - -\begin{classdesc}{Select}{} -The \ulink{Select} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm} -widget is a container of button subwidgets. It can be used to provide -radio-box or check-box style of selection options for the user. -\end{classdesc} - -% Python Demo of: -% \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl} - -\begin{classdesc}{StdButtonBox}{} -The \ulink{StdButtonBox} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm} -widget is a group of standard buttons for Motif-like dialog boxes. -\end{classdesc} - -% Python Demo of: -% \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl} - - -\subsubsection{File Selectors} - -\begin{classdesc}{DirList}{} -The \ulink{DirList} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm} widget -displays a list view of a directory, its previous directories and its -sub-directories. The user can choose one of the directories displayed -in the list or change to another directory. -\end{classdesc} - -% Python Demo of: -% \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl} - -\begin{classdesc}{DirTree}{} -The \ulink{DirTree} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm} -widget displays a tree view of a directory, its previous directories -and its sub-directories. The user can choose one of the directories -displayed in the list or change to another directory. -\end{classdesc} - -% Python Demo of: -% \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl} - -\begin{classdesc}{DirSelectDialog}{} -The \ulink{DirSelectDialog} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm} -widget presents the directories in the file system in a dialog -window. The user can use this dialog window to navigate through the -file system to select the desired directory. -\end{classdesc} - -% Python Demo of: -% \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl} - -\begin{classdesc}{DirSelectBox}{} -The \class{DirSelectBox} is similar -to the standard Motif(TM) directory-selection box. It is generally used for -the user to choose a directory. DirSelectBox stores the directories mostly -recently selected into a ComboBox widget so that they can be quickly -selected again. -\end{classdesc} - -\begin{classdesc}{ExFileSelectBox}{} -The \ulink{ExFileSelectBox} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm} -widget is usually embedded in a tixExFileSelectDialog widget. It -provides an convenient method for the user to select files. The style -of the \class{ExFileSelectBox} widget is very similar to the standard -file dialog on MS Windows 3.1. -\end{classdesc} - -% Python Demo of: -%\ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl} - -\begin{classdesc}{FileSelectBox}{} -The \ulink{FileSelectBox} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm} -is similar to the standard Motif(TM) file-selection box. It is -generally used for the user to choose a file. FileSelectBox stores the -files mostly recently selected into a \class{ComboBox} widget so that -they can be quickly selected again. -\end{classdesc} - -% Python Demo of: -% \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl} - -\begin{classdesc}{FileEntry}{} -The \ulink{FileEntry} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm} -widget can be used to input a filename. The user can type in the -filename manually. Alternatively, the user can press the button widget -that sits next to the entry, which will bring up a file selection -dialog. -\end{classdesc} - -% Python Demo of: -% \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl} - - -\subsubsection{Hierachical ListBox} - -\begin{classdesc}{HList}{} -The \ulink{HList} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm} -widget can be used to display any data that have a hierarchical -structure, for example, file system directory trees. The list entries -are indented and connected by branch lines according to their places -in the hierarchy. -\end{classdesc} - -% Python Demo of: -% \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl} - -\begin{classdesc}{CheckList}{} -The \ulink{CheckList} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm} -widget displays a list of items to be selected by the user. CheckList -acts similarly to the Tk checkbutton or radiobutton widgets, except it -is capable of handling many more items than checkbuttons or -radiobuttons. -\end{classdesc} - -% Python Demo of: -% \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl} -% Python Demo of: -% \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl} -% Python Demo of: -% \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl} - -\begin{classdesc}{Tree}{} -The \ulink{Tree} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm} -widget can be used to display hierarchical data in a tree form. The -user can adjust the view of the tree by opening or closing parts of -the tree. -\end{classdesc} - -% Python Demo of: -% \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl} - -% Python Demo of: -% \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl} - - -\subsubsection{Tabular ListBox} - -\begin{classdesc}{TList}{} -The \ulink{TList} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm} -widget can be used to display data in a tabular format. The list -entries of a \class{TList} widget are similar to the entries in the Tk -listbox widget. The main differences are (1) the \class{TList} widget -can display the list entries in a two dimensional format and (2) you -can use graphical images as well as multiple colors and fonts for the -list entries. -\end{classdesc} - -% Python Demo of: -% \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl} -% Python Demo of: -% \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl} - -% Grid has yet to be added to Python -% \subsubsection{Grid Widget} -% Python Demo of: -% \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl} -% Python Demo of: -% \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl} -% Python Demo of: -% \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl} - - -\subsubsection{Manager Widgets} - -\begin{classdesc}{PanedWindow}{} -The \ulink{PanedWindow} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm} -widget allows the user to interactively manipulate the sizes of -several panes. The panes can be arranged either vertically or -horizontally. The user changes the sizes of the panes by dragging the -resize handle between two panes. -\end{classdesc} - -% Python Demo of: -% \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl} - -\begin{classdesc}{ListNoteBook}{} -The \ulink{ListNoteBook} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm} -widget is very similar to the \class{TixNoteBook} widget: it can be -used to display many windows in a limited space using a notebook -metaphor. The notebook is divided into a stack of pages (windows). At -one time only one of these pages can be shown. The user can navigate -through these pages by choosing the name of the desired page in the -\member{hlist} subwidget. -\end{classdesc} - -% Python Demo of: -% \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl} - -\begin{classdesc}{NoteBook}{} -The \ulink{NoteBook} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm} -widget can be used to display many windows in a limited space using a -notebook metaphor. The notebook is divided into a stack of pages. At -one time only one of these pages can be shown. The user can navigate -through these pages by choosing the visual ``tabs'' at the top of the -NoteBook widget. -\end{classdesc} - -% Python Demo of: -% \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl} - - -% \subsubsection{Scrolled Widgets} -% Python Demo of: -% \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl} -% Python Demo of: -% \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl} -% Python Demo of: -% \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl} -% Python Demo of: -% \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl} - - -\subsubsection{Image Types} - -The \refmodule{Tix} module adds: -\begin{itemize} -\item -\ulink{pixmap} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm} -capabilities to all \refmodule{Tix} and \refmodule{Tkinter} widgets to -create color images from XPM files. - -% Python Demo of: -% \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl} - -% Python Demo of: -% \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl} - -\item -\ulink{Compound} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm} -image types can be used to create images that consists of multiple -horizontal lines; each line is composed of a series of items (texts, -bitmaps, images or spaces) arranged from left to right. For example, a -compound image can be used to display a bitmap and a text string -simultaneously in a Tk \class{Button} widget. - -% Python Demo of: -% \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl} - -% Python Demo of: -% \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl} - -% Python Demo of: -% \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl} - -% Python Demo of: -% \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl} -\end{itemize} - - -\subsubsection{Miscellaneous Widgets} - -\begin{classdesc}{InputOnly}{} -The \ulink{InputOnly} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm} -widgets are to accept inputs from the user, which can be done with the -\code{bind} command (\UNIX{} only). -\end{classdesc} - -\subsubsection{Form Geometry Manager} - -In addition, \refmodule{Tix} augments \refmodule{Tkinter} by providing: - -\begin{classdesc}{Form}{} -The \ulink{Form} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm} -geometry manager based on attachment rules for all Tk widgets. -\end{classdesc} - - -%begin{latexonly} -%\subsection{Tix Class Structure} -% -%\begin{figure}[hbtp] -%\centerline{\epsfig{file=hierarchy.png,width=.9\textwidth}} -%\vspace{.5cm} -%\caption{The Class Hierarchy of Tix Widgets} -%\end{figure} -%end{latexonly} - -\subsection{Tix Commands} - -\begin{classdesc}{tixCommand}{} -The \ulink{tix commands} -{http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm} -provide access to miscellaneous elements of \refmodule{Tix}'s internal -state and the \refmodule{Tix} application context. Most of the information -manipulated by these methods pertains to the application as a whole, -or to a screen or display, rather than to a particular window. - -To view the current settings, the common usage is: -\begin{verbatim} -import Tix -root = Tix.Tk() -print root.tix_configure() -\end{verbatim} -\end{classdesc} - -\begin{methoddesc}{tix_configure}{\optional{cnf,} **kw} -Query or modify the configuration options of the Tix application -context. If no option is specified, returns a dictionary all of the -available options. If option is specified with no value, then the -method returns a list describing the one named option (this list will -be identical to the corresponding sublist of the value returned if no -option is specified). If one or more option-value pairs are -specified, then the method modifies the given option(s) to have the -given value(s); in this case the method returns an empty string. -Option may be any of the configuration options. -\end{methoddesc} - -\begin{methoddesc}{tix_cget}{option} -Returns the current value of the configuration option given by -\var{option}. Option may be any of the configuration options. -\end{methoddesc} - -\begin{methoddesc}{tix_getbitmap}{name} -Locates a bitmap file of the name \code{name.xpm} or \code{name} in -one of the bitmap directories (see the \method{tix_addbitmapdir()} -method). By using \method{tix_getbitmap()}, you can avoid hard -coding the pathnames of the bitmap files in your application. When -successful, it returns the complete pathname of the bitmap file, -prefixed with the character \samp{@}. The returned value can be used to -configure the \code{bitmap} option of the Tk and Tix widgets. -\end{methoddesc} - -\begin{methoddesc}{tix_addbitmapdir}{directory} -Tix maintains a list of directories under which the -\method{tix_getimage()} and \method{tix_getbitmap()} methods will -search for image files. The standard bitmap directory is -\file{\$TIX_LIBRARY/bitmaps}. The \method{tix_addbitmapdir()} method -adds \var{directory} into this list. By using this method, the image -files of an applications can also be located using the -\method{tix_getimage()} or \method{tix_getbitmap()} method. -\end{methoddesc} - -\begin{methoddesc}{tix_filedialog}{\optional{dlgclass}} -Returns the file selection dialog that may be shared among different -calls from this application. This method will create a file selection -dialog widget when it is called the first time. This dialog will be -returned by all subsequent calls to \method{tix_filedialog()}. An -optional dlgclass parameter can be passed as a string to specified -what type of file selection dialog widget is desired. Possible -options are \code{tix}, \code{FileSelectDialog} or -\code{tixExFileSelectDialog}. -\end{methoddesc} - - -\begin{methoddesc}{tix_getimage}{self, name} -Locates an image file of the name \file{name.xpm}, \file{name.xbm} or -\file{name.ppm} in one of the bitmap directories (see the -\method{tix_addbitmapdir()} method above). If more than one file with -the same name (but different extensions) exist, then the image type is -chosen according to the depth of the X display: xbm images are chosen -on monochrome displays and color images are chosen on color -displays. By using \method{tix_getimage()}, you can avoid hard coding -the pathnames of the image files in your application. When successful, -this method returns the name of the newly created image, which can be -used to configure the \code{image} option of the Tk and Tix widgets. -\end{methoddesc} - -\begin{methoddesc}{tix_option_get}{name} -Gets the options maintained by the Tix scheme mechanism. -\end{methoddesc} - -\begin{methoddesc}{tix_resetoptions}{newScheme, newFontSet\optional{, - newScmPrio}} -Resets the scheme and fontset of the Tix application to -\var{newScheme} and \var{newFontSet}, respectively. This affects only -those widgets created after this call. Therefore, it is best to call -the resetoptions method before the creation of any widgets in a Tix -application. - -The optional parameter \var{newScmPrio} can be given to reset the -priority level of the Tk options set by the Tix schemes. - -Because of the way Tk handles the X option database, after Tix has -been has imported and inited, it is not possible to reset the color -schemes and font sets using the \method{tix_config()} method. -Instead, the \method{tix_resetoptions()} method must be used. -\end{methoddesc} - - - -\section{\module{ScrolledText} --- - Scrolled Text Widget} - -\declaremodule{standard}{ScrolledText} - \platform{Tk} -\modulesynopsis{Text widget with a vertical scroll bar.} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - -The \module{ScrolledText} module provides a class of the same name -which implements a basic text widget which has a vertical scroll bar -configured to do the ``right thing.'' Using the \class{ScrolledText} -class is a lot easier than setting up a text widget and scroll bar -directly. The constructor is the same as that of the -\class{Tkinter.Text} class. - -The text widget and scrollbar are packed together in a \class{Frame}, -and the methods of the \class{Grid} and \class{Pack} geometry managers -are acquired from the \class{Frame} object. This allows the -\class{ScrolledText} widget to be used directly to achieve most normal -geometry management behavior. - -Should more specific control be necessary, the following attributes -are available: - -\begin{memberdesc}[ScrolledText]{frame} - The frame which surrounds the text and scroll bar widgets. -\end{memberdesc} - -\begin{memberdesc}[ScrolledText]{vbar} - The scroll bar widget. -\end{memberdesc} - - -\input{libturtle} - - -\section{Idle \label{idle}} - -%\declaremodule{standard}{idle} -%\modulesynopsis{A Python Integrated Development Environment} -\moduleauthor{Guido van Rossum}{guido@Python.org} - -Idle is the Python IDE built with the \refmodule{Tkinter} GUI toolkit. -\index{Idle} -\index{Python Editor} -\index{Integrated Development Environment} - - -IDLE has the following features: - -\begin{itemize} -\item coded in 100\% pure Python, using the \refmodule{Tkinter} GUI toolkit - -\item cross-platform: works on Windows and \UNIX{} (on Mac OS, there are -currently problems with Tcl/Tk) - -\item multi-window text editor with multiple undo, Python colorizing -and many other features, e.g. smart indent and call tips - -\item Python shell window (a.k.a. interactive interpreter) - -\item debugger (not complete, but you can set breakpoints, view and step) -\end{itemize} - - -\subsection{Menus} - -\subsubsection{File menu} - -\begin{description} -\item[New window] create a new editing window -\item[Open...] open an existing file -\item[Open module...] open an existing module (searches sys.path) -\item[Class browser] show classes and methods in current file -\item[Path browser] show sys.path directories, modules, classes and methods -\end{description} -\index{Class browser} -\index{Path browser} - -\begin{description} -\item[Save] save current window to the associated file (unsaved -windows have a * before and after the window title) - -\item[Save As...] save current window to new file, which becomes -the associated file -\item[Save Copy As...] save current window to different file -without changing the associated file -\end{description} - -\begin{description} -\item[Close] close current window (asks to save if unsaved) -\item[Exit] close all windows and quit IDLE (asks to save if unsaved) -\end{description} - - -\subsubsection{Edit menu} - -\begin{description} -\item[Undo] Undo last change to current window (max 1000 changes) -\item[Redo] Redo last undone change to current window -\end{description} - -\begin{description} -\item[Cut] Copy selection into system-wide clipboard; then delete selection -\item[Copy] Copy selection into system-wide clipboard -\item[Paste] Insert system-wide clipboard into window -\item[Select All] Select the entire contents of the edit buffer -\end{description} - -\begin{description} -\item[Find...] Open a search dialog box with many options -\item[Find again] Repeat last search -\item[Find selection] Search for the string in the selection -\item[Find in Files...] Open a search dialog box for searching files -\item[Replace...] Open a search-and-replace dialog box -\item[Go to line] Ask for a line number and show that line -\end{description} - -\begin{description} -\item[Indent region] Shift selected lines right 4 spaces -\item[Dedent region] Shift selected lines left 4 spaces -\item[Comment out region] Insert \#\# in front of selected lines -\item[Uncomment region] Remove leading \# or \#\# from selected lines -\item[Tabify region] Turns \emph{leading} stretches of spaces into tabs -\item[Untabify region] Turn \emph{all} tabs into the right number of spaces -\item[Expand word] Expand the word you have typed to match another - word in the same buffer; repeat to get a different expansion -\item[Format Paragraph] Reformat the current blank-line-separated paragraph -\end{description} - -\begin{description} -\item[Import module] Import or reload the current module -\item[Run script] Execute the current file in the __main__ namespace -\end{description} - -\index{Import module} -\index{Run script} - - -\subsubsection{Windows menu} - -\begin{description} -\item[Zoom Height] toggles the window between normal size (24x80) - and maximum height. -\end{description} - -The rest of this menu lists the names of all open windows; select one -to bring it to the foreground (deiconifying it if necessary). - - -\subsubsection{Debug menu (in the Python Shell window only)} - -\begin{description} -\item[Go to file/line] look around the insert point for a filename - and linenumber, open the file, and show the line. -\item[Open stack viewer] show the stack traceback of the last exception -\item[Debugger toggle] Run commands in the shell under the debugger -\item[JIT Stack viewer toggle] Open stack viewer on traceback -\end{description} - -\index{stack viewer} -\index{debugger} - - -\subsection{Basic editing and navigation} - -\begin{itemize} -\item \kbd{Backspace} deletes to the left; \kbd{Del} deletes to the right -\item Arrow keys and \kbd{Page Up}/\kbd{Page Down} to move around -\item \kbd{Home}/\kbd{End} go to begin/end of line -\item \kbd{C-Home}/\kbd{C-End} go to begin/end of file -\item Some \program{Emacs} bindings may also work, including \kbd{C-B}, - \kbd{C-P}, \kbd{C-A}, \kbd{C-E}, \kbd{C-D}, \kbd{C-L} -\end{itemize} - - -\subsubsection{Automatic indentation} - -After a block-opening statement, the next line is indented by 4 spaces -(in the Python Shell window by one tab). After certain keywords -(break, return etc.) the next line is dedented. In leading -indentation, \kbd{Backspace} deletes up to 4 spaces if they are there. -\kbd{Tab} inserts 1-4 spaces (in the Python Shell window one tab). -See also the indent/dedent region commands in the edit menu. - - -\subsubsection{Python Shell window} - -\begin{itemize} -\item \kbd{C-C} interrupts executing command -\item \kbd{C-D} sends end-of-file; closes window if typed at -a \samp{>>>~} prompt -\end{itemize} - -\begin{itemize} -\item \kbd{Alt-p} retrieves previous command matching what you have typed -\item \kbd{Alt-n} retrieves next -\item \kbd{Return} while on any previous command retrieves that command -\item \kbd{Alt-/} (Expand word) is also useful here -\end{itemize} - -\index{indentation} - - -\subsection{Syntax colors} - -The coloring is applied in a background ``thread,'' so you may -occasionally see uncolorized text. To change the color -scheme, edit the \code{[Colors]} section in \file{config.txt}. - -\begin{description} -\item[Python syntax colors:] - -\begin{description} -\item[Keywords] orange -\item[Strings ] green -\item[Comments] red -\item[Definitions] blue -\end{description} - -\item[Shell colors:] -\begin{description} -\item[Console output] brown -\item[stdout] blue -\item[stderr] dark green -\item[stdin] black -\end{description} -\end{description} - - -\subsubsection{Command line usage} - -\begin{verbatim} -idle.py [-c command] [-d] [-e] [-s] [-t title] [arg] ... - --c command run this command --d enable debugger --e edit mode; arguments are files to be edited --s run $IDLESTARTUP or $PYTHONSTARTUP first --t title set title of shell window -\end{verbatim} - -If there are arguments: - -\begin{enumerate} -\item If \programopt{-e} is used, arguments are files opened for - editing and \code{sys.argv} reflects the arguments passed to - IDLE itself. - -\item Otherwise, if \programopt{-c} is used, all arguments are - placed in \code{sys.argv[1:...]}, with \code{sys.argv[0]} set - to \code{'-c'}. - -\item Otherwise, if neither \programopt{-e} nor \programopt{-c} is - used, the first argument is a script which is executed with - the remaining arguments in \code{sys.argv[1:...]} and - \code{sys.argv[0]} set to the script name. If the script name - is '-', no script is executed but an interactive Python - session is started; the arguments are still available in - \code{sys.argv}. -\end{enumerate} - - -\section{Other Graphical User Interface Packages - \label{other-gui-packages}} - - -There are an number of extension widget sets to \refmodule{Tkinter}. - -\begin{seealso*} -\seetitle[http://pmw.sourceforge.net/]{Python megawidgets}{is a -toolkit for building high-level compound widgets in Python using the -\refmodule{Tkinter} module. It consists of a set of base classes and -a library of flexible and extensible megawidgets built on this -foundation. These megawidgets include notebooks, comboboxes, selection -widgets, paned widgets, scrolled widgets, dialog windows, etc. Also, -with the Pmw.Blt interface to BLT, the busy, graph, stripchart, tabset -and vector commands are be available. - -The initial ideas for Pmw were taken from the Tk \code{itcl} -extensions \code{[incr Tk]} by Michael McLennan and \code{[incr -Widgets]} by Mark Ulferts. Several of the megawidgets are direct -translations from the itcl to Python. It offers most of the range of -widgets that \code{[incr Widgets]} does, and is almost as complete as -Tix, lacking however Tix's fast \class{HList} widget for drawing trees. -} - -\seetitle[http://tkinter.effbot.org/]{Tkinter3000 Widget Construction - Kit (WCK)}{% -is a library that allows you to write new Tkinter widgets in pure -Python. The WCK framework gives you full control over widget -creation, configuration, screen appearance, and event handling. WCK -widgets can be very fast and light-weight, since they can operate -directly on Python data structures, without having to transfer data -through the Tk/Tcl layer.} -\end{seealso*} - -Other GUI packages are also available for Python: - -\begin{seealso*} -\seetitle[http://www.wxpython.org]{wxPython}{ -wxPython is a cross-platform GUI toolkit for Python that is built -around the popular \ulink{wxWidgets}{http://www.wxwidgets.org/} \Cpp{} -toolkit. It provides a native look and feel for applications on -Windows, Mac OS X, and \UNIX{} systems by using each platform's native -widgets where ever possible, (GTK+ on \UNIX-like systems). In -addition to an extensive set of widgets, wxPython provides classes for -online documentation and context sensitive help, printing, HTML -viewing, low-level device context drawing, drag and drop, system -clipboard access, an XML-based resource format and more, including an -ever growing library of user-contributed modules. Both the wxWidgets -and wxPython projects are under active development and continuous -improvement, and have active and helpful user and developer -communities. -} -\seetitle[http://www.amazon.com/exec/obidos/ASIN/1932394621] -{wxPython in Action}{ -The wxPython book, by Noel Rappin and Robin Dunn. -} -\seetitle{PyQt}{ -PyQt is a \program{sip}-wrapped binding to the Qt toolkit. Qt is an -extensive \Cpp{} GUI toolkit that is available for \UNIX, Windows and -Mac OS X. \program{sip} is a tool for generating bindings for \Cpp{} -libraries as Python classes, and is specifically designed for Python. -An online manual is available at -\url{http://www.opendocspublishing.com/pyqt/} (errata are located at -\url{http://www.valdyas.org/python/book.html}). -} -\seetitle[http://www.riverbankcomputing.co.uk/pykde/index.php]{PyKDE}{ -PyKDE is a \program{sip}-wrapped interface to the KDE desktop -libraries. KDE is a desktop environment for \UNIX{} computers; the -graphical components are based on Qt. -} -\seetitle[http://fxpy.sourceforge.net/]{FXPy}{ -is a Python extension module which provides an interface to the -\citetitle[http://www.cfdrc.com/FOX/fox.html]{FOX} GUI. -FOX is a \Cpp{} based Toolkit for developing Graphical User Interfaces -easily and effectively. It offers a wide, and growing, collection of -Controls, and provides state of the art facilities such as drag and -drop, selection, as well as OpenGL widgets for 3D graphical -manipulation. FOX also implements icons, images, and user-convenience -features such as status line help, and tooltips. - -Even though FOX offers a large collection of controls already, FOX -leverages \Cpp{} to allow programmers to easily build additional Controls -and GUI elements, simply by taking existing controls, and creating a -derived class which simply adds or redefines the desired behavior. -} -\seetitle[http://www.daa.com.au/\textasciitilde james/software/pygtk/]{PyGTK}{ -is a set of bindings for the \ulink{GTK}{http://www.gtk.org/} widget set. -It provides an object oriented interface that is slightly higher -level than the C one. It automatically does all the type casting and -reference counting that you would have to do normally with the C -API. There are also -\ulink{bindings}{http://www.daa.com.au/\textasciitilde james/gnome/} -to \ulink{GNOME}{http://www.gnome.org}, and a -\ulink{tutorial} -{http://laguna.fmedic.unam.mx/\textasciitilde daniel/pygtutorial/pygtutorial/index.html} -is available. -} -\end{seealso*} - -% XXX Reference URLs that compare the different UI packages diff --git a/Doc/lib/tzinfo-examples.py b/Doc/lib/tzinfo-examples.py deleted file mode 100644 index 5a2b8ad..0000000 --- a/Doc/lib/tzinfo-examples.py +++ /dev/null @@ -1,139 +0,0 @@ -from datetime import tzinfo, timedelta, datetime - -ZERO = timedelta(0) -HOUR = timedelta(hours=1) - -# A UTC class. - -class UTC(tzinfo): - """UTC""" - - def utcoffset(self, dt): - return ZERO - - def tzname(self, dt): - return "UTC" - - def dst(self, dt): - return ZERO - -utc = UTC() - -# A class building tzinfo objects for fixed-offset time zones. -# Note that FixedOffset(0, "UTC") is a different way to build a -# UTC tzinfo object. - -class FixedOffset(tzinfo): - """Fixed offset in minutes east from UTC.""" - - def __init__(self, offset, name): - self.__offset = timedelta(minutes = offset) - self.__name = name - - def utcoffset(self, dt): - return self.__offset - - def tzname(self, dt): - return self.__name - - def dst(self, dt): - return ZERO - -# A class capturing the platform's idea of local time. - -import time as _time - -STDOFFSET = timedelta(seconds = -_time.timezone) -if _time.daylight: - DSTOFFSET = timedelta(seconds = -_time.altzone) -else: - DSTOFFSET = STDOFFSET - -DSTDIFF = DSTOFFSET - STDOFFSET - -class LocalTimezone(tzinfo): - - def utcoffset(self, dt): - if self._isdst(dt): - return DSTOFFSET - else: - return STDOFFSET - - def dst(self, dt): - if self._isdst(dt): - return DSTDIFF - else: - return ZERO - - def tzname(self, dt): - return _time.tzname[self._isdst(dt)] - - def _isdst(self, dt): - tt = (dt.year, dt.month, dt.day, - dt.hour, dt.minute, dt.second, - dt.weekday(), 0, -1) - stamp = _time.mktime(tt) - tt = _time.localtime(stamp) - return tt.tm_isdst > 0 - -Local = LocalTimezone() - - -# A complete implementation of current DST rules for major US time zones. - -def first_sunday_on_or_after(dt): - days_to_go = 6 - dt.weekday() - if days_to_go: - dt += timedelta(days_to_go) - return dt - -# In the US, DST starts at 2am (standard time) on the first Sunday in April. -DSTSTART = datetime(1, 4, 1, 2) -# and ends at 2am (DST time; 1am standard time) on the last Sunday of Oct. -# which is the first Sunday on or after Oct 25. -DSTEND = datetime(1, 10, 25, 1) - -class USTimeZone(tzinfo): - - def __init__(self, hours, reprname, stdname, dstname): - self.stdoffset = timedelta(hours=hours) - self.reprname = reprname - self.stdname = stdname - self.dstname = dstname - - def __repr__(self): - return self.reprname - - def tzname(self, dt): - if self.dst(dt): - return self.dstname - else: - return self.stdname - - def utcoffset(self, dt): - return self.stdoffset + self.dst(dt) - - def dst(self, dt): - if dt is None or dt.tzinfo is None: - # An exception may be sensible here, in one or both cases. - # It depends on how you want to treat them. The default - # fromutc() implementation (called by the default astimezone() - # implementation) passes a datetime with dt.tzinfo is self. - return ZERO - assert dt.tzinfo is self - - # Find first Sunday in April & the last in October. - start = first_sunday_on_or_after(DSTSTART.replace(year=dt.year)) - end = first_sunday_on_or_after(DSTEND.replace(year=dt.year)) - - # Can't compare naive to aware objects, so strip the timezone from - # dt first. - if start <= dt.replace(tzinfo=None) < end: - return HOUR - else: - return ZERO - -Eastern = USTimeZone(-5, "Eastern", "EST", "EDT") -Central = USTimeZone(-6, "Central", "CST", "CDT") -Mountain = USTimeZone(-7, "Mountain", "MST", "MDT") -Pacific = USTimeZone(-8, "Pacific", "PST", "PDT") diff --git a/Doc/lib/windows.tex b/Doc/lib/windows.tex deleted file mode 100644 index ced3559..0000000 --- a/Doc/lib/windows.tex +++ /dev/null @@ -1,8 +0,0 @@ -\chapter{MS Windows Specific Services} - - -This chapter describes modules that are only available on MS Windows -platforms. - - -\localmoduletable diff --git a/Doc/lib/xmldom.tex b/Doc/lib/xmldom.tex deleted file mode 100644 index d651bf0..0000000 --- a/Doc/lib/xmldom.tex +++ /dev/null @@ -1,928 +0,0 @@ -\section{\module{xml.dom} --- - The Document Object Model API} - -\declaremodule{standard}{xml.dom} -\modulesynopsis{Document Object Model API for Python.} -\sectionauthor{Paul Prescod}{paul@prescod.net} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} - -\versionadded{2.0} - -The Document Object Model, or ``DOM,'' is a cross-language API from -the World Wide Web Consortium (W3C) for accessing and modifying XML -documents. A DOM implementation presents an XML document as a tree -structure, or allows client code to build such a structure from -scratch. It then gives access to the structure through a set of -objects which provided well-known interfaces. - -The DOM is extremely useful for random-access applications. SAX only -allows you a view of one bit of the document at a time. If you are -looking at one SAX element, you have no access to another. If you are -looking at a text node, you have no access to a containing element. -When you write a SAX application, you need to keep track of your -program's position in the document somewhere in your own code. SAX -does not do it for you. Also, if you need to look ahead in the XML -document, you are just out of luck. - -Some applications are simply impossible in an event driven model with -no access to a tree. Of course you could build some sort of tree -yourself in SAX events, but the DOM allows you to avoid writing that -code. The DOM is a standard tree representation for XML data. - -%What if your needs are somewhere between SAX and the DOM? Perhaps -%you cannot afford to load the entire tree in memory but you find the -%SAX model somewhat cumbersome and low-level. There is also a module -%called xml.dom.pulldom that allows you to build trees of only the -%parts of a document that you need structured access to. It also has -%features that allow you to find your way around the DOM. -% See http://www.prescod.net/python/pulldom - -The Document Object Model is being defined by the W3C in stages, or -``levels'' in their terminology. The Python mapping of the API is -substantially based on the DOM Level~2 recommendation. The mapping of -the Level~3 specification, currently only available in draft form, is -being developed by the \ulink{Python XML Special Interest -Group}{http://www.python.org/sigs/xml-sig/} as part of the -\ulink{PyXML package}{http://pyxml.sourceforge.net/}. Refer to the -documentation bundled with that package for information on the current -state of DOM Level~3 support. - -DOM applications typically start by parsing some XML into a DOM. How -this is accomplished is not covered at all by DOM Level~1, and Level~2 -provides only limited improvements: There is a -\class{DOMImplementation} object class which provides access to -\class{Document} creation methods, but no way to access an XML -reader/parser/Document builder in an implementation-independent way. -There is also no well-defined way to access these methods without an -existing \class{Document} object. In Python, each DOM implementation -will provide a function \function{getDOMImplementation()}. DOM Level~3 -adds a Load/Store specification, which defines an interface to the -reader, but this is not yet available in the Python standard library. - -Once you have a DOM document object, you can access the parts of your -XML document through its properties and methods. These properties are -defined in the DOM specification; this portion of the reference manual -describes the interpretation of the specification in Python. - -The specification provided by the W3C defines the DOM API for Java, -ECMAScript, and OMG IDL. The Python mapping defined here is based in -large part on the IDL version of the specification, but strict -compliance is not required (though implementations are free to support -the strict mapping from IDL). See section \ref{dom-conformance}, -``Conformance,'' for a detailed discussion of mapping requirements. - - -\begin{seealso} - \seetitle[http://www.w3.org/TR/DOM-Level-2-Core/]{Document Object - Model (DOM) Level~2 Specification} - {The W3C recommendation upon which the Python DOM API is - based.} - \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object - Model (DOM) Level~1 Specification} - {The W3C recommendation for the - DOM supported by \module{xml.dom.minidom}.} - \seetitle[http://pyxml.sourceforge.net]{PyXML}{Users that require a - full-featured implementation of DOM should use the PyXML - package.} - \seetitle[http://www.omg.org/docs/formal/02-11-05.pdf]{Python - Language Mapping Specification} - {This specifies the mapping from OMG IDL to Python.} -\end{seealso} - -\subsection{Module Contents} - -The \module{xml.dom} contains the following functions: - -\begin{funcdesc}{registerDOMImplementation}{name, factory} -Register the \var{factory} function with the name \var{name}. The -factory function should return an object which implements the -\class{DOMImplementation} interface. The factory function can return -the same object every time, or a new one for each call, as appropriate -for the specific implementation (e.g. if that implementation supports -some customization). -\end{funcdesc} - -\begin{funcdesc}{getDOMImplementation}{\optional{name\optional{, features}}} -Return a suitable DOM implementation. The \var{name} is either -well-known, the module name of a DOM implementation, or -\code{None}. If it is not \code{None}, imports the corresponding -module and returns a \class{DOMImplementation} object if the import -succeeds. If no name is given, and if the environment variable -\envvar{PYTHON_DOM} is set, this variable is used to find the -implementation. - -If name is not given, this examines the available implementations to -find one with the required feature set. If no implementation can be -found, raise an \exception{ImportError}. The features list must be a -sequence of \code{(\var{feature}, \var{version})} pairs which are -passed to the \method{hasFeature()} method on available -\class{DOMImplementation} objects. -\end{funcdesc} - - -Some convenience constants are also provided: - -\begin{datadesc}{EMPTY_NAMESPACE} - The value used to indicate that no namespace is associated with a - node in the DOM. This is typically found as the - \member{namespaceURI} of a node, or used as the \var{namespaceURI} - parameter to a namespaces-specific method. - \versionadded{2.2} -\end{datadesc} - -\begin{datadesc}{XML_NAMESPACE} - The namespace URI associated with the reserved prefix \code{xml}, as - defined by - \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML} - (section~4). - \versionadded{2.2} -\end{datadesc} - -\begin{datadesc}{XMLNS_NAMESPACE} - The namespace URI for namespace declarations, as defined by - \citetitle[http://www.w3.org/TR/DOM-Level-2-Core/core.html]{Document - Object Model (DOM) Level~2 Core Specification} (section~1.1.8). - \versionadded{2.2} -\end{datadesc} - -\begin{datadesc}{XHTML_NAMESPACE} - The URI of the XHTML namespace as defined by - \citetitle[http://www.w3.org/TR/xhtml1/]{XHTML 1.0: The Extensible - HyperText Markup Language} (section~3.1.1). - \versionadded{2.2} -\end{datadesc} - - -% Should the Node documentation go here? - -In addition, \module{xml.dom} contains a base \class{Node} class and -the DOM exception classes. The \class{Node} class provided by this -module does not implement any of the methods or attributes defined by -the DOM specification; concrete DOM implementations must provide -those. The \class{Node} class provided as part of this module does -provide the constants used for the \member{nodeType} attribute on -concrete \class{Node} objects; they are located within the class -rather than at the module level to conform with the DOM -specifications. - - -\subsection{Objects in the DOM \label{dom-objects}} - -The definitive documentation for the DOM is the DOM specification from -the W3C. - -Note that DOM attributes may also be manipulated as nodes instead of -as simple strings. It is fairly rare that you must do this, however, -so this usage is not yet documented. - - -\begin{tableiii}{l|l|l}{class}{Interface}{Section}{Purpose} - \lineiii{DOMImplementation}{\ref{dom-implementation-objects}} - {Interface to the underlying implementation.} - \lineiii{Node}{\ref{dom-node-objects}} - {Base interface for most objects in a document.} - \lineiii{NodeList}{\ref{dom-nodelist-objects}} - {Interface for a sequence of nodes.} - \lineiii{DocumentType}{\ref{dom-documenttype-objects}} - {Information about the declarations needed to process a document.} - \lineiii{Document}{\ref{dom-document-objects}} - {Object which represents an entire document.} - \lineiii{Element}{\ref{dom-element-objects}} - {Element nodes in the document hierarchy.} - \lineiii{Attr}{\ref{dom-attr-objects}} - {Attribute value nodes on element nodes.} - \lineiii{Comment}{\ref{dom-comment-objects}} - {Representation of comments in the source document.} - \lineiii{Text}{\ref{dom-text-objects}} - {Nodes containing textual content from the document.} - \lineiii{ProcessingInstruction}{\ref{dom-pi-objects}} - {Processing instruction representation.} -\end{tableiii} - -An additional section describes the exceptions defined for working -with the DOM in Python. - - -\subsubsection{DOMImplementation Objects - \label{dom-implementation-objects}} - -The \class{DOMImplementation} interface provides a way for -applications to determine the availability of particular features in -the DOM they are using. DOM Level~2 added the ability to create new -\class{Document} and \class{DocumentType} objects using the -\class{DOMImplementation} as well. - -\begin{methoddesc}[DOMImplementation]{hasFeature}{feature, version} -Return true if the feature identified by the pair of strings -\var{feature} and \var{version} is implemented. -\end{methoddesc} - -\begin{methoddesc}[DOMImplementation]{createDocument}{namespaceUri, qualifiedName, doctype} -Return a new \class{Document} object (the root of the DOM), with a -child \class{Element} object having the given \var{namespaceUri} and -\var{qualifiedName}. The \var{doctype} must be a \class{DocumentType} -object created by \method{createDocumentType()}, or \code{None}. -In the Python DOM API, the first two arguments can also be \code{None} -in order to indicate that no \class{Element} child is to be created. -\end{methoddesc} - -\begin{methoddesc}[DOMImplementation]{createDocumentType}{qualifiedName, publicId, systemId} -Return a new \class{DocumentType} object that encapsulates the given -\var{qualifiedName}, \var{publicId}, and \var{systemId} strings, -representing the information contained in an XML document type -declaration. -\end{methoddesc} - - -\subsubsection{Node Objects \label{dom-node-objects}} - -All of the components of an XML document are subclasses of -\class{Node}. - -\begin{memberdesc}[Node]{nodeType} -An integer representing the node type. Symbolic constants for the -types are on the \class{Node} object: -\constant{ELEMENT_NODE}, \constant{ATTRIBUTE_NODE}, -\constant{TEXT_NODE}, \constant{CDATA_SECTION_NODE}, -\constant{ENTITY_NODE}, \constant{PROCESSING_INSTRUCTION_NODE}, -\constant{COMMENT_NODE}, \constant{DOCUMENT_NODE}, -\constant{DOCUMENT_TYPE_NODE}, \constant{NOTATION_NODE}. -This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{parentNode} -The parent of the current node, or \code{None} for the document node. -The value is always a \class{Node} object or \code{None}. For -\class{Element} nodes, this will be the parent element, except for the -root element, in which case it will be the \class{Document} object. -For \class{Attr} nodes, this is always \code{None}. -This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{attributes} -A \class{NamedNodeMap} of attribute objects. Only elements have -actual values for this; others provide \code{None} for this attribute. -This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{previousSibling} -The node that immediately precedes this one with the same parent. For -instance the element with an end-tag that comes just before the -\var{self} element's start-tag. Of course, XML documents are made -up of more than just elements so the previous sibling could be text, a -comment, or something else. If this node is the first child of the -parent, this attribute will be \code{None}. -This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{nextSibling} -The node that immediately follows this one with the same parent. See -also \member{previousSibling}. If this is the last child of the -parent, this attribute will be \code{None}. -This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{childNodes} -A list of nodes contained within this node. -This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{firstChild} -The first child of the node, if there are any, or \code{None}. -This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{lastChild} -The last child of the node, if there are any, or \code{None}. -This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{localName} -The part of the \member{tagName} following the colon if there is one, -else the entire \member{tagName}. The value is a string. -\end{memberdesc} - -\begin{memberdesc}[Node]{prefix} -The part of the \member{tagName} preceding the colon if there is one, -else the empty string. The value is a string, or \code{None} -\end{memberdesc} - -\begin{memberdesc}[Node]{namespaceURI} -The namespace associated with the element name. This will be a -string or \code{None}. This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{nodeName} -This has a different meaning for each node type; see the DOM -specification for details. You can always get the information you -would get here from another property such as the \member{tagName} -property for elements or the \member{name} property for attributes. -For all node types, the value of this attribute will be either a -string or \code{None}. This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Node]{nodeValue} -This has a different meaning for each node type; see the DOM -specification for details. The situation is similar to that with -\member{nodeName}. The value is a string or \code{None}. -\end{memberdesc} - -\begin{methoddesc}[Node]{hasAttributes}{} -Returns true if the node has any attributes. -\end{methoddesc} - -\begin{methoddesc}[Node]{hasChildNodes}{} -Returns true if the node has any child nodes. -\end{methoddesc} - -\begin{methoddesc}[Node]{isSameNode}{other} -Returns true if \var{other} refers to the same node as this node. -This is especially useful for DOM implementations which use any sort -of proxy architecture (because more than one object can refer to the -same node). - -\begin{notice} - This is based on a proposed DOM Level~3 API which is still in the - ``working draft'' stage, but this particular interface appears - uncontroversial. Changes from the W3C will not necessarily affect - this method in the Python DOM interface (though any new W3C API for - this would also be supported). -\end{notice} -\end{methoddesc} - -\begin{methoddesc}[Node]{appendChild}{newChild} -Add a new child node to this node at the end of the list of children, -returning \var{newChild}. -\end{methoddesc} - -\begin{methoddesc}[Node]{insertBefore}{newChild, refChild} -Insert a new child node before an existing child. It must be the case -that \var{refChild} is a child of this node; if not, -\exception{ValueError} is raised. \var{newChild} is returned. If -\var{refChild} is \code{None}, it inserts \var{newChild} at the end of -the children's list. -\end{methoddesc} - -\begin{methoddesc}[Node]{removeChild}{oldChild} -Remove a child node. \var{oldChild} must be a child of this node; if -not, \exception{ValueError} is raised. \var{oldChild} is returned on -success. If \var{oldChild} will not be used further, its -\method{unlink()} method should be called. -\end{methoddesc} - -\begin{methoddesc}[Node]{replaceChild}{newChild, oldChild} -Replace an existing node with a new node. It must be the case that -\var{oldChild} is a child of this node; if not, -\exception{ValueError} is raised. -\end{methoddesc} - -\begin{methoddesc}[Node]{normalize}{} -Join adjacent text nodes so that all stretches of text are stored as -single \class{Text} instances. This simplifies processing text from a -DOM tree for many applications. -\versionadded{2.1} -\end{methoddesc} - -\begin{methoddesc}[Node]{cloneNode}{deep} -Clone this node. Setting \var{deep} means to clone all child nodes as -well. This returns the clone. -\end{methoddesc} - - -\subsubsection{NodeList Objects \label{dom-nodelist-objects}} - -A \class{NodeList} represents a sequence of nodes. These objects are -used in two ways in the DOM Core recommendation: the -\class{Element} objects provides one as its list of child nodes, and -the \method{getElementsByTagName()} and -\method{getElementsByTagNameNS()} methods of \class{Node} return -objects with this interface to represent query results. - -The DOM Level~2 recommendation defines one method and one attribute -for these objects: - -\begin{methoddesc}[NodeList]{item}{i} - Return the \var{i}'th item from the sequence, if there is one, or - \code{None}. The index \var{i} is not allowed to be less then zero - or greater than or equal to the length of the sequence. -\end{methoddesc} - -\begin{memberdesc}[NodeList]{length} - The number of nodes in the sequence. -\end{memberdesc} - -In addition, the Python DOM interface requires that some additional -support is provided to allow \class{NodeList} objects to be used as -Python sequences. All \class{NodeList} implementations must include -support for \method{__len__()} and \method{__getitem__()}; this allows -iteration over the \class{NodeList} in \keyword{for} statements and -proper support for the \function{len()} built-in function. - -If a DOM implementation supports modification of the document, the -\class{NodeList} implementation must also support the -\method{__setitem__()} and \method{__delitem__()} methods. - - -\subsubsection{DocumentType Objects \label{dom-documenttype-objects}} - -Information about the notations and entities declared by a document -(including the external subset if the parser uses it and can provide -the information) is available from a \class{DocumentType} object. The -\class{DocumentType} for a document is available from the -\class{Document} object's \member{doctype} attribute; if there is no -\code{DOCTYPE} declaration for the document, the document's -\member{doctype} attribute will be set to \code{None} instead of an -instance of this interface. - -\class{DocumentType} is a specialization of \class{Node}, and adds the -following attributes: - -\begin{memberdesc}[DocumentType]{publicId} - The public identifier for the external subset of the document type - definition. This will be a string or \code{None}. -\end{memberdesc} - -\begin{memberdesc}[DocumentType]{systemId} - The system identifier for the external subset of the document type - definition. This will be a URI as a string, or \code{None}. -\end{memberdesc} - -\begin{memberdesc}[DocumentType]{internalSubset} - A string giving the complete internal subset from the document. - This does not include the brackets which enclose the subset. If the - document has no internal subset, this should be \code{None}. -\end{memberdesc} - -\begin{memberdesc}[DocumentType]{name} - The name of the root element as given in the \code{DOCTYPE} - declaration, if present. -\end{memberdesc} - -\begin{memberdesc}[DocumentType]{entities} - This is a \class{NamedNodeMap} giving the definitions of external - entities. For entity names defined more than once, only the first - definition is provided (others are ignored as required by the XML - recommendation). This may be \code{None} if the information is not - provided by the parser, or if no entities are defined. -\end{memberdesc} - -\begin{memberdesc}[DocumentType]{notations} - This is a \class{NamedNodeMap} giving the definitions of notations. - For notation names defined more than once, only the first definition - is provided (others are ignored as required by the XML - recommendation). This may be \code{None} if the information is not - provided by the parser, or if no notations are defined. -\end{memberdesc} - - -\subsubsection{Document Objects \label{dom-document-objects}} - -A \class{Document} represents an entire XML document, including its -constituent elements, attributes, processing instructions, comments -etc. Remeber that it inherits properties from \class{Node}. - -\begin{memberdesc}[Document]{documentElement} -The one and only root element of the document. -\end{memberdesc} - -\begin{methoddesc}[Document]{createElement}{tagName} -Create and return a new element node. The element is not inserted -into the document when it is created. You need to explicitly insert -it with one of the other methods such as \method{insertBefore()} or -\method{appendChild()}. -\end{methoddesc} - -\begin{methoddesc}[Document]{createElementNS}{namespaceURI, tagName} -Create and return a new element with a namespace. The -\var{tagName} may have a prefix. The element is not inserted into the -document when it is created. You need to explicitly insert it with -one of the other methods such as \method{insertBefore()} or -\method{appendChild()}. -\end{methoddesc} - -\begin{methoddesc}[Document]{createTextNode}{data} -Create and return a text node containing the data passed as a -parameter. As with the other creation methods, this one does not -insert the node into the tree. -\end{methoddesc} - -\begin{methoddesc}[Document]{createComment}{data} -Create and return a comment node containing the data passed as a -parameter. As with the other creation methods, this one does not -insert the node into the tree. -\end{methoddesc} - -\begin{methoddesc}[Document]{createProcessingInstruction}{target, data} -Create and return a processing instruction node containing the -\var{target} and \var{data} passed as parameters. As with the other -creation methods, this one does not insert the node into the tree. -\end{methoddesc} - -\begin{methoddesc}[Document]{createAttribute}{name} -Create and return an attribute node. This method does not associate -the attribute node with any particular element. You must use -\method{setAttributeNode()} on the appropriate \class{Element} object -to use the newly created attribute instance. -\end{methoddesc} - -\begin{methoddesc}[Document]{createAttributeNS}{namespaceURI, qualifiedName} -Create and return an attribute node with a namespace. The -\var{tagName} may have a prefix. This method does not associate the -attribute node with any particular element. You must use -\method{setAttributeNode()} on the appropriate \class{Element} object -to use the newly created attribute instance. -\end{methoddesc} - -\begin{methoddesc}[Document]{getElementsByTagName}{tagName} -Search for all descendants (direct children, children's children, -etc.) with a particular element type name. -\end{methoddesc} - -\begin{methoddesc}[Document]{getElementsByTagNameNS}{namespaceURI, localName} -Search for all descendants (direct children, children's children, -etc.) with a particular namespace URI and localname. The localname is -the part of the namespace after the prefix. -\end{methoddesc} - - -\subsubsection{Element Objects \label{dom-element-objects}} - -\class{Element} is a subclass of \class{Node}, so inherits all the -attributes of that class. - -\begin{memberdesc}[Element]{tagName} -The element type name. In a namespace-using document it may have -colons in it. The value is a string. -\end{memberdesc} - -\begin{methoddesc}[Element]{getElementsByTagName}{tagName} -Same as equivalent method in the \class{Document} class. -\end{methoddesc} - -\begin{methoddesc}[Element]{getElementsByTagNameNS}{tagName} -Same as equivalent method in the \class{Document} class. -\end{methoddesc} - -\begin{methoddesc}[Element]{hasAttribute}{name} -Returns true if the element has an attribute named by \var{name}. -\end{methoddesc} - -\begin{methoddesc}[Element]{hasAttributeNS}{namespaceURI, localName} -Returns true if the element has an attribute named by -\var{namespaceURI} and \var{localName}. -\end{methoddesc} - -\begin{methoddesc}[Element]{getAttribute}{name} -Return the value of the attribute named by \var{name} as a -string. If no such attribute exists, an empty string is returned, -as if the attribute had no value. -\end{methoddesc} - -\begin{methoddesc}[Element]{getAttributeNode}{attrname} -Return the \class{Attr} node for the attribute named by -\var{attrname}. -\end{methoddesc} - -\begin{methoddesc}[Element]{getAttributeNS}{namespaceURI, localName} -Return the value of the attribute named by \var{namespaceURI} and -\var{localName} as a string. If no such attribute exists, an empty -string is returned, as if the attribute had no value. -\end{methoddesc} - -\begin{methoddesc}[Element]{getAttributeNodeNS}{namespaceURI, localName} -Return an attribute value as a node, given a \var{namespaceURI} and -\var{localName}. -\end{methoddesc} - -\begin{methoddesc}[Element]{removeAttribute}{name} -Remove an attribute by name. No exception is raised if there is no -matching attribute. -\end{methoddesc} - -\begin{methoddesc}[Element]{removeAttributeNode}{oldAttr} -Remove and return \var{oldAttr} from the attribute list, if present. -If \var{oldAttr} is not present, \exception{NotFoundErr} is raised. -\end{methoddesc} - -\begin{methoddesc}[Element]{removeAttributeNS}{namespaceURI, localName} -Remove an attribute by name. Note that it uses a localName, not a -qname. No exception is raised if there is no matching attribute. -\end{methoddesc} - -\begin{methoddesc}[Element]{setAttribute}{name, value} -Set an attribute value from a string. -\end{methoddesc} - -\begin{methoddesc}[Element]{setAttributeNode}{newAttr} -Add a new attribute node to the element, replacing an existing -attribute if necessary if the \member{name} attribute matches. If a -replacement occurs, the old attribute node will be returned. If -\var{newAttr} is already in use, \exception{InuseAttributeErr} will be -raised. -\end{methoddesc} - -\begin{methoddesc}[Element]{setAttributeNodeNS}{newAttr} -Add a new attribute node to the element, replacing an existing -attribute if necessary if the \member{namespaceURI} and -\member{localName} attributes match. If a replacement occurs, the old -attribute node will be returned. If \var{newAttr} is already in use, -\exception{InuseAttributeErr} will be raised. -\end{methoddesc} - -\begin{methoddesc}[Element]{setAttributeNS}{namespaceURI, qname, value} -Set an attribute value from a string, given a \var{namespaceURI} and a -\var{qname}. Note that a qname is the whole attribute name. This is -different than above. -\end{methoddesc} - - -\subsubsection{Attr Objects \label{dom-attr-objects}} - -\class{Attr} inherits from \class{Node}, so inherits all its -attributes. - -\begin{memberdesc}[Attr]{name} -The attribute name. In a namespace-using document it may have colons -in it. -\end{memberdesc} - -\begin{memberdesc}[Attr]{localName} -The part of the name following the colon if there is one, else the -entire name. This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[Attr]{prefix} -The part of the name preceding the colon if there is one, else the -empty string. -\end{memberdesc} - - -\subsubsection{NamedNodeMap Objects \label{dom-attributelist-objects}} - -\class{NamedNodeMap} does \emph{not} inherit from \class{Node}. - -\begin{memberdesc}[NamedNodeMap]{length} -The length of the attribute list. -\end{memberdesc} - -\begin{methoddesc}[NamedNodeMap]{item}{index} -Return an attribute with a particular index. The order you get the -attributes in is arbitrary but will be consistent for the life of a -DOM. Each item is an attribute node. Get its value with the -\member{value} attribute. -\end{methoddesc} - -There are also experimental methods that give this class more mapping -behavior. You can use them or you can use the standardized -\method{getAttribute*()} family of methods on the \class{Element} -objects. - - -\subsubsection{Comment Objects \label{dom-comment-objects}} - -\class{Comment} represents a comment in the XML document. It is a -subclass of \class{Node}, but cannot have child nodes. - -\begin{memberdesc}[Comment]{data} -The content of the comment as a string. The attribute contains all -characters between the leading \code{<!-}\code{-} and trailing -\code{-}\code{->}, but does not include them. -\end{memberdesc} - - -\subsubsection{Text and CDATASection Objects \label{dom-text-objects}} - -The \class{Text} interface represents text in the XML document. If -the parser and DOM implementation support the DOM's XML extension, -portions of the text enclosed in CDATA marked sections are stored in -\class{CDATASection} objects. These two interfaces are identical, but -provide different values for the \member{nodeType} attribute. - -These interfaces extend the \class{Node} interface. They cannot have -child nodes. - -\begin{memberdesc}[Text]{data} -The content of the text node as a string. -\end{memberdesc} - -\begin{notice} - The use of a \class{CDATASection} node does not indicate that the - node represents a complete CDATA marked section, only that the - content of the node was part of a CDATA section. A single CDATA - section may be represented by more than one node in the document - tree. There is no way to determine whether two adjacent - \class{CDATASection} nodes represent different CDATA marked - sections. -\end{notice} - - -\subsubsection{ProcessingInstruction Objects \label{dom-pi-objects}} - -Represents a processing instruction in the XML document; this inherits -from the \class{Node} interface and cannot have child nodes. - -\begin{memberdesc}[ProcessingInstruction]{target} -The content of the processing instruction up to the first whitespace -character. This is a read-only attribute. -\end{memberdesc} - -\begin{memberdesc}[ProcessingInstruction]{data} -The content of the processing instruction following the first -whitespace character. -\end{memberdesc} - - -\subsubsection{Exceptions \label{dom-exceptions}} - -\versionadded{2.1} - -The DOM Level~2 recommendation defines a single exception, -\exception{DOMException}, and a number of constants that allow -applications to determine what sort of error occurred. -\exception{DOMException} instances carry a \member{code} attribute -that provides the appropriate value for the specific exception. - -The Python DOM interface provides the constants, but also expands the -set of exceptions so that a specific exception exists for each of the -exception codes defined by the DOM. The implementations must raise -the appropriate specific exception, each of which carries the -appropriate value for the \member{code} attribute. - -\begin{excdesc}{DOMException} - Base exception class used for all specific DOM exceptions. This - exception class cannot be directly instantiated. -\end{excdesc} - -\begin{excdesc}{DomstringSizeErr} - Raised when a specified range of text does not fit into a string. - This is not known to be used in the Python DOM implementations, but - may be received from DOM implementations not written in Python. -\end{excdesc} - -\begin{excdesc}{HierarchyRequestErr} - Raised when an attempt is made to insert a node where the node type - is not allowed. -\end{excdesc} - -\begin{excdesc}{IndexSizeErr} - Raised when an index or size parameter to a method is negative or - exceeds the allowed values. -\end{excdesc} - -\begin{excdesc}{InuseAttributeErr} - Raised when an attempt is made to insert an \class{Attr} node that - is already present elsewhere in the document. -\end{excdesc} - -\begin{excdesc}{InvalidAccessErr} - Raised if a parameter or an operation is not supported on the - underlying object. -\end{excdesc} - -\begin{excdesc}{InvalidCharacterErr} - This exception is raised when a string parameter contains a - character that is not permitted in the context it's being used in by - the XML 1.0 recommendation. For example, attempting to create an - \class{Element} node with a space in the element type name will - cause this error to be raised. -\end{excdesc} - -\begin{excdesc}{InvalidModificationErr} - Raised when an attempt is made to modify the type of a node. -\end{excdesc} - -\begin{excdesc}{InvalidStateErr} - Raised when an attempt is made to use an object that is not defined or is no - longer usable. -\end{excdesc} - -\begin{excdesc}{NamespaceErr} - If an attempt is made to change any object in a way that is not - permitted with regard to the - \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML} - recommendation, this exception is raised. -\end{excdesc} - -\begin{excdesc}{NotFoundErr} - Exception when a node does not exist in the referenced context. For - example, \method{NamedNodeMap.removeNamedItem()} will raise this if - the node passed in does not exist in the map. -\end{excdesc} - -\begin{excdesc}{NotSupportedErr} - Raised when the implementation does not support the requested type - of object or operation. -\end{excdesc} - -\begin{excdesc}{NoDataAllowedErr} - This is raised if data is specified for a node which does not - support data. - % XXX a better explanation is needed! -\end{excdesc} - -\begin{excdesc}{NoModificationAllowedErr} - Raised on attempts to modify an object where modifications are not - allowed (such as for read-only nodes). -\end{excdesc} - -\begin{excdesc}{SyntaxErr} - Raised when an invalid or illegal string is specified. - % XXX how is this different from InvalidCharacterErr ??? -\end{excdesc} - -\begin{excdesc}{WrongDocumentErr} - Raised when a node is inserted in a different document than it - currently belongs to, and the implementation does not support - migrating the node from one document to the other. -\end{excdesc} - -The exception codes defined in the DOM recommendation map to the -exceptions described above according to this table: - -\begin{tableii}{l|l}{constant}{Constant}{Exception} - \lineii{DOMSTRING_SIZE_ERR}{\exception{DomstringSizeErr}} - \lineii{HIERARCHY_REQUEST_ERR}{\exception{HierarchyRequestErr}} - \lineii{INDEX_SIZE_ERR}{\exception{IndexSizeErr}} - \lineii{INUSE_ATTRIBUTE_ERR}{\exception{InuseAttributeErr}} - \lineii{INVALID_ACCESS_ERR}{\exception{InvalidAccessErr}} - \lineii{INVALID_CHARACTER_ERR}{\exception{InvalidCharacterErr}} - \lineii{INVALID_MODIFICATION_ERR}{\exception{InvalidModificationErr}} - \lineii{INVALID_STATE_ERR}{\exception{InvalidStateErr}} - \lineii{NAMESPACE_ERR}{\exception{NamespaceErr}} - \lineii{NOT_FOUND_ERR}{\exception{NotFoundErr}} - \lineii{NOT_SUPPORTED_ERR}{\exception{NotSupportedErr}} - \lineii{NO_DATA_ALLOWED_ERR}{\exception{NoDataAllowedErr}} - \lineii{NO_MODIFICATION_ALLOWED_ERR}{\exception{NoModificationAllowedErr}} - \lineii{SYNTAX_ERR}{\exception{SyntaxErr}} - \lineii{WRONG_DOCUMENT_ERR}{\exception{WrongDocumentErr}} -\end{tableii} - - -\subsection{Conformance \label{dom-conformance}} - -This section describes the conformance requirements and relationships -between the Python DOM API, the W3C DOM recommendations, and the OMG -IDL mapping for Python. - - -\subsubsection{Type Mapping \label{dom-type-mapping}} - -The primitive IDL types used in the DOM specification are mapped to -Python types according to the following table. - -\begin{tableii}{l|l}{code}{IDL Type}{Python Type} - \lineii{boolean}{\code{IntegerType} (with a value of \code{0} or \code{1})} - \lineii{int}{\code{IntegerType}} - \lineii{long int}{\code{IntegerType}} - \lineii{unsigned int}{\code{IntegerType}} -\end{tableii} - -Additionally, the \class{DOMString} defined in the recommendation is -mapped to a Python string or Unicode string. Applications should -be able to handle Unicode whenever a string is returned from the DOM. - -The IDL \keyword{null} value is mapped to \code{None}, which may be -accepted or provided by the implementation whenever \keyword{null} is -allowed by the API. - - -\subsubsection{Accessor Methods \label{dom-accessor-methods}} - -The mapping from OMG IDL to Python defines accessor functions for IDL -\keyword{attribute} declarations in much the way the Java mapping -does. Mapping the IDL declarations - -\begin{verbatim} -readonly attribute string someValue; - attribute string anotherValue; -\end{verbatim} - -yields three accessor functions: a ``get'' method for -\member{someValue} (\method{_get_someValue()}), and ``get'' and -``set'' methods for -\member{anotherValue} (\method{_get_anotherValue()} and -\method{_set_anotherValue()}). The mapping, in particular, does not -require that the IDL attributes are accessible as normal Python -attributes: \code{\var{object}.someValue} is \emph{not} required to -work, and may raise an \exception{AttributeError}. - -The Python DOM API, however, \emph{does} require that normal attribute -access work. This means that the typical surrogates generated by -Python IDL compilers are not likely to work, and wrapper objects may -be needed on the client if the DOM objects are accessed via CORBA. -While this does require some additional consideration for CORBA DOM -clients, the implementers with experience using DOM over CORBA from -Python do not consider this a problem. Attributes that are declared -\keyword{readonly} may not restrict write access in all DOM -implementations. - -In the Python DOM API, accessor functions are not required. If provided, -they should take the form defined by the Python IDL mapping, but -these methods are considered unnecessary since the attributes are -accessible directly from Python. ``Set'' accessors should never be -provided for \keyword{readonly} attributes. - -The IDL definitions do not fully embody the requirements of the W3C DOM -API, such as the notion of certain objects, such as the return value of -\method{getElementsByTagName()}, being ``live''. The Python DOM API -does not require implementations to enforce such requirements. diff --git a/Doc/lib/xmldomminidom.tex b/Doc/lib/xmldomminidom.tex deleted file mode 100644 index 093915f..0000000 --- a/Doc/lib/xmldomminidom.tex +++ /dev/null @@ -1,285 +0,0 @@ -\section{\module{xml.dom.minidom} --- - Lightweight DOM implementation} - -\declaremodule{standard}{xml.dom.minidom} -\modulesynopsis{Lightweight Document Object Model (DOM) implementation.} -\moduleauthor{Paul Prescod}{paul@prescod.net} -\sectionauthor{Paul Prescod}{paul@prescod.net} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} - -\versionadded{2.0} - -\module{xml.dom.minidom} is a light-weight implementation of the -Document Object Model interface. It is intended to be -simpler than the full DOM and also significantly smaller. - -DOM applications typically start by parsing some XML into a DOM. With -\module{xml.dom.minidom}, this is done through the parse functions: - -\begin{verbatim} -from xml.dom.minidom import parse, parseString - -dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name - -datasource = open('c:\\temp\\mydata.xml') -dom2 = parse(datasource) # parse an open file - -dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>') -\end{verbatim} - -The \function{parse()} function can take either a filename or an open -file object. - -\begin{funcdesc}{parse}{filename_or_file{, parser}} - Return a \class{Document} from the given input. \var{filename_or_file} - may be either a file name, or a file-like object. \var{parser}, if - given, must be a SAX2 parser object. This function will change the - document handler of the parser and activate namespace support; other - parser configuration (like setting an entity resolver) must have been - done in advance. -\end{funcdesc} - -If you have XML in a string, you can use the -\function{parseString()} function instead: - -\begin{funcdesc}{parseString}{string\optional{, parser}} - Return a \class{Document} that represents the \var{string}. This - method creates a \class{StringIO} object for the string and passes - that on to \function{parse}. -\end{funcdesc} - -Both functions return a \class{Document} object representing the -content of the document. - -What the \function{parse()} and \function{parseString()} functions do -is connect an XML parser with a ``DOM builder'' that can accept parse -events from any SAX parser and convert them into a DOM tree. The name -of the functions are perhaps misleading, but are easy to grasp when -learning the interfaces. The parsing of the document will be -completed before these functions return; it's simply that these -functions do not provide a parser implementation themselves. - -You can also create a \class{Document} by calling a method on a ``DOM -Implementation'' object. You can get this object either by calling -the \function{getDOMImplementation()} function in the -\refmodule{xml.dom} package or the \module{xml.dom.minidom} module. -Using the implementation from the \module{xml.dom.minidom} module will -always return a \class{Document} instance from the minidom -implementation, while the version from \refmodule{xml.dom} may provide -an alternate implementation (this is likely if you have the -\ulink{PyXML package}{http://pyxml.sourceforge.net/} installed). Once -you have a \class{Document}, you can add child nodes to it to populate -the DOM: - -\begin{verbatim} -from xml.dom.minidom import getDOMImplementation - -impl = getDOMImplementation() - -newdoc = impl.createDocument(None, "some_tag", None) -top_element = newdoc.documentElement -text = newdoc.createTextNode('Some textual content.') -top_element.appendChild(text) -\end{verbatim} - -Once you have a DOM document object, you can access the parts of your -XML document through its properties and methods. These properties are -defined in the DOM specification. The main property of the document -object is the \member{documentElement} property. It gives you the -main element in the XML document: the one that holds all others. Here -is an example program: - -\begin{verbatim} -dom3 = parseString("<myxml>Some data</myxml>") -assert dom3.documentElement.tagName == "myxml" -\end{verbatim} - -When you are finished with a DOM, you should clean it up. This is -necessary because some versions of Python do not support garbage -collection of objects that refer to each other in a cycle. Until this -restriction is removed from all versions of Python, it is safest to -write your code as if cycles would not be cleaned up. - -The way to clean up a DOM is to call its \method{unlink()} method: - -\begin{verbatim} -dom1.unlink() -dom2.unlink() -dom3.unlink() -\end{verbatim} - -\method{unlink()} is a \module{xml.dom.minidom}-specific extension to -the DOM API. After calling \method{unlink()} on a node, the node and -its descendants are essentially useless. - -\begin{seealso} - \seetitle[http://www.w3.org/TR/REC-DOM-Level-1/]{Document Object - Model (DOM) Level 1 Specification} - {The W3C recommendation for the - DOM supported by \module{xml.dom.minidom}.} -\end{seealso} - - -\subsection{DOM Objects \label{dom-objects}} - -The definition of the DOM API for Python is given as part of the -\refmodule{xml.dom} module documentation. This section lists the -differences between the API and \refmodule{xml.dom.minidom}. - - -\begin{methoddesc}[Node]{unlink}{} -Break internal references within the DOM so that it will be garbage -collected on versions of Python without cyclic GC. Even when cyclic -GC is available, using this can make large amounts of memory available -sooner, so calling this on DOM objects as soon as they are no longer -needed is good practice. This only needs to be called on the -\class{Document} object, but may be called on child nodes to discard -children of that node. -\end{methoddesc} - -\begin{methoddesc}[Node]{writexml}{writer\optional{,indent=""\optional{,addindent=""\optional{,newl=""}}}} -Write XML to the writer object. The writer should have a -\method{write()} method which matches that of the file object -interface. The \var{indent} parameter is the indentation of the current -node. The \var{addindent} parameter is the incremental indentation to use -for subnodes of the current one. The \var{newl} parameter specifies the -string to use to terminate newlines. - -\versionchanged[The optional keyword parameters -\var{indent}, \var{addindent}, and \var{newl} were added to support pretty -output]{2.1} - -\versionchanged[For the \class{Document} node, an additional keyword -argument \var{encoding} can be used to specify the encoding field of the XML -header]{2.3} -\end{methoddesc} - -\begin{methoddesc}[Node]{toxml}{\optional{encoding}} -Return the XML that the DOM represents as a string. - -With no argument, the XML header does not specify an encoding, and the -result is Unicode string if the default encoding cannot represent all -characters in the document. Encoding this string in an encoding other -than UTF-8 is likely incorrect, since UTF-8 is the default encoding of -XML. - -With an explicit \var{encoding} argument, the result is a byte string -in the specified encoding. It is recommended that this argument is -always specified. To avoid \exception{UnicodeError} exceptions in case of -unrepresentable text data, the encoding argument should be specified -as "utf-8". - -\versionchanged[the \var{encoding} argument was introduced]{2.3} -\end{methoddesc} - -\begin{methoddesc}[Node]{toprettyxml}{\optional{indent\optional{, newl}}} -Return a pretty-printed version of the document. \var{indent} specifies -the indentation string and defaults to a tabulator; \var{newl} specifies -the string emitted at the end of each line and defaults to \code{\e n}. - -\versionadded{2.1} -\versionchanged[the encoding argument; see \method{toxml()}]{2.3} -\end{methoddesc} - -The following standard DOM methods have special considerations with -\refmodule{xml.dom.minidom}: - -\begin{methoddesc}[Node]{cloneNode}{deep} -Although this method was present in the version of -\refmodule{xml.dom.minidom} packaged with Python 2.0, it was seriously -broken. This has been corrected for subsequent releases. -\end{methoddesc} - - -\subsection{DOM Example \label{dom-example}} - -This example program is a fairly realistic example of a simple -program. In this particular case, we do not take much advantage -of the flexibility of the DOM. - -\verbatiminput{minidom-example.py} - - -\subsection{minidom and the DOM standard \label{minidom-and-dom}} - -The \refmodule{xml.dom.minidom} module is essentially a DOM -1.0-compatible DOM with some DOM 2 features (primarily namespace -features). - -Usage of the DOM interface in Python is straight-forward. The -following mapping rules apply: - -\begin{itemize} -\item Interfaces are accessed through instance objects. Applications - should not instantiate the classes themselves; they should use - the creator functions available on the \class{Document} object. - Derived interfaces support all operations (and attributes) from - the base interfaces, plus any new operations. - -\item Operations are used as methods. Since the DOM uses only - \keyword{in} parameters, the arguments are passed in normal - order (from left to right). There are no optional - arguments. \keyword{void} operations return \code{None}. - -\item IDL attributes map to instance attributes. For compatibility - with the OMG IDL language mapping for Python, an attribute - \code{foo} can also be accessed through accessor methods - \method{_get_foo()} and \method{_set_foo()}. \keyword{readonly} - attributes must not be changed; this is not enforced at - runtime. - -\item The types \code{short int}, \code{unsigned int}, \code{unsigned - long long}, and \code{boolean} all map to Python integer - objects. - -\item The type \code{DOMString} maps to Python strings. - \refmodule{xml.dom.minidom} supports either byte or Unicode - strings, but will normally produce Unicode strings. Values - of type \code{DOMString} may also be \code{None} where allowed - to have the IDL \code{null} value by the DOM specification from - the W3C. - -\item \keyword{const} declarations map to variables in their - respective scope - (e.g. \code{xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE}); - they must not be changed. - -\item \code{DOMException} is currently not supported in - \refmodule{xml.dom.minidom}. Instead, - \refmodule{xml.dom.minidom} uses standard Python exceptions such - as \exception{TypeError} and \exception{AttributeError}. - -\item \class{NodeList} objects are implemented using Python's built-in - list type. Starting with Python 2.2, these objects provide the - interface defined in the DOM specification, but with earlier - versions of Python they do not support the official API. They - are, however, much more ``Pythonic'' than the interface defined - in the W3C recommendations. -\end{itemize} - - -The following interfaces have no implementation in -\refmodule{xml.dom.minidom}: - -\begin{itemize} -\item \class{DOMTimeStamp} - -\item \class{DocumentType} (added in Python 2.1) - -\item \class{DOMImplementation} (added in Python 2.1) - -\item \class{CharacterData} - -\item \class{CDATASection} - -\item \class{Notation} - -\item \class{Entity} - -\item \class{EntityReference} - -\item \class{DocumentFragment} -\end{itemize} - -Most of these reflect information in the XML document that is not of -general utility to most DOM users. diff --git a/Doc/lib/xmldompulldom.tex b/Doc/lib/xmldompulldom.tex deleted file mode 100644 index a2ce667..0000000 --- a/Doc/lib/xmldompulldom.tex +++ /dev/null @@ -1,61 +0,0 @@ -\section{\module{xml.dom.pulldom} --- - Support for building partial DOM trees} - -\declaremodule{standard}{xml.dom.pulldom} -\modulesynopsis{Support for building partial DOM trees from SAX events.} -\moduleauthor{Paul Prescod}{paul@prescod.net} - -\versionadded{2.0} - -\module{xml.dom.pulldom} allows building only selected portions of a -Document Object Model representation of a document from SAX events. - - -\begin{classdesc}{PullDOM}{\optional{documentFactory}} - \class{xml.sax.handler.ContentHandler} implementation that ... -\end{classdesc} - - -\begin{classdesc}{DOMEventStream}{stream, parser, bufsize} - ... -\end{classdesc} - - -\begin{classdesc}{SAX2DOM}{\optional{documentFactory}} - \class{xml.sax.handler.ContentHandler} implementation that ... -\end{classdesc} - - -\begin{funcdesc}{parse}{stream_or_string\optional{, - parser\optional{, bufsize}}} - ... -\end{funcdesc} - - -\begin{funcdesc}{parseString}{string\optional{, parser}} - ... -\end{funcdesc} - - -\begin{datadesc}{default_bufsize} - Default value for the \var{bufsize} parameter to \function{parse()}. - \versionchanged[The value of this variable can be changed before - calling \function{parse()} and the new value will - take effect]{2.1} -\end{datadesc} - - -\subsection{DOMEventStream Objects \label{domeventstream-objects}} - - -\begin{methoddesc}[DOMEventStream]{getEvent}{} - ... -\end{methoddesc} - -\begin{methoddesc}[DOMEventStream]{expandNode}{node} - ... -\end{methoddesc} - -\begin{methoddesc}[DOMEventStream]{reset}{} - ... -\end{methoddesc} diff --git a/Doc/lib/xmletree.tex b/Doc/lib/xmletree.tex deleted file mode 100644 index 789062d..0000000 --- a/Doc/lib/xmletree.tex +++ /dev/null @@ -1,27 +0,0 @@ -\section{\module{xml.etree} ---
- The ElementTree API for XML}
-
-\declaremodule{standard}{xml.etree}
-\modulesynopsis{Package containing common ElementTree modules.}
-\moduleauthor{Fredrik Lundh}{fredrik@pythonware.com}
-
-\versionadded{2.5}
-
-The ElementTree package is a simple, efficient, and quite popular
-library for XML manipulation in Python.
-
-The \module{xml.etree} package contains the most common components
-from the ElementTree API library.
-In the current release, this package contains the \module{ElementTree},
-\module{ElementPath}, and \module{ElementInclude} modules from the full
-ElementTree distribution.
-
-% XXX To be continued!
-
-\begin{seealso}
-\seetitle[http://effbot.org/tag/elementtree]
- {ElementTree Overview}
- {The home page for \module{ElementTree}. This includes links
- to additional documentation, alternative implementations, and
- other add-ons.}
-\end{seealso}
diff --git a/Doc/lib/xmlsax.tex b/Doc/lib/xmlsax.tex deleted file mode 100644 index 838c279..0000000 --- a/Doc/lib/xmlsax.tex +++ /dev/null @@ -1,143 +0,0 @@ -\section{\module{xml.sax} --- - Support for SAX2 parsers} - -\declaremodule{standard}{xml.sax} -\modulesynopsis{Package containing SAX2 base classes and convenience - functions.} -\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} - -\versionadded{2.0} - - -The \module{xml.sax} package provides a number of modules which -implement the Simple API for XML (SAX) interface for Python. The -package itself provides the SAX exceptions and the convenience -functions which will be most used by users of the SAX API. - -The convenience functions are: - -\begin{funcdesc}{make_parser}{\optional{parser_list}} - Create and return a SAX \class{XMLReader} object. The first parser - found will be used. If \var{parser_list} is provided, it must be a - sequence of strings which name modules that have a function named - \function{create_parser()}. Modules listed in \var{parser_list} - will be used before modules in the default list of parsers. -\end{funcdesc} - -\begin{funcdesc}{parse}{filename_or_stream, handler\optional{, error_handler}} - Create a SAX parser and use it to parse a document. The document, - passed in as \var{filename_or_stream}, can be a filename or a file - object. The \var{handler} parameter needs to be a SAX - \class{ContentHandler} instance. If \var{error_handler} is given, - it must be a SAX \class{ErrorHandler} instance; if omitted, - \exception{SAXParseException} will be raised on all errors. There - is no return value; all work must be done by the \var{handler} - passed in. -\end{funcdesc} - -\begin{funcdesc}{parseString}{string, handler\optional{, error_handler}} - Similar to \function{parse()}, but parses from a buffer \var{string} - received as a parameter. -\end{funcdesc} - -A typical SAX application uses three kinds of objects: readers, -handlers and input sources. ``Reader'' in this context is another -term for parser, i.e.\ some piece of code that reads the bytes or -characters from the input source, and produces a sequence of events. -The events then get distributed to the handler objects, i.e.\ the -reader invokes a method on the handler. A SAX application must -therefore obtain a reader object, create or open the input sources, -create the handlers, and connect these objects all together. As the -final step of preparation, the reader is called to parse the input. -During parsing, methods on the handler objects are called based on -structural and syntactic events from the input data. - -For these objects, only the interfaces are relevant; they are normally -not instantiated by the application itself. Since Python does not have -an explicit notion of interface, they are formally introduced as -classes, but applications may use implementations which do not inherit -from the provided classes. The \class{InputSource}, \class{Locator}, -\class{Attributes}, \class{AttributesNS}, and -\class{XMLReader} interfaces are defined in the module -\refmodule{xml.sax.xmlreader}. The handler interfaces are defined in -\refmodule{xml.sax.handler}. For convenience, \class{InputSource} -(which is often instantiated directly) and the handler classes are -also available from \module{xml.sax}. These interfaces are described -below. - -In addition to these classes, \module{xml.sax} provides the following -exception classes. - -\begin{excclassdesc}{SAXException}{msg\optional{, exception}} - Encapsulate an XML error or warning. This class can contain basic - error or warning information from either the XML parser or the - application: it can be subclassed to provide additional - functionality or to add localization. Note that although the - handlers defined in the \class{ErrorHandler} interface receive - instances of this exception, it is not required to actually raise - the exception --- it is also useful as a container for information. - - When instantiated, \var{msg} should be a human-readable description - of the error. The optional \var{exception} parameter, if given, - should be \code{None} or an exception that was caught by the parsing - code and is being passed along as information. - - This is the base class for the other SAX exception classes. -\end{excclassdesc} - -\begin{excclassdesc}{SAXParseException}{msg, exception, locator} - Subclass of \exception{SAXException} raised on parse errors. - Instances of this class are passed to the methods of the SAX - \class{ErrorHandler} interface to provide information about the - parse error. This class supports the SAX \class{Locator} interface - as well as the \class{SAXException} interface. -\end{excclassdesc} - -\begin{excclassdesc}{SAXNotRecognizedException}{msg\optional{, exception}} - Subclass of \exception{SAXException} raised when a SAX - \class{XMLReader} is confronted with an unrecognized feature or - property. SAX applications and extensions may use this class for - similar purposes. -\end{excclassdesc} - -\begin{excclassdesc}{SAXNotSupportedException}{msg\optional{, exception}} - Subclass of \exception{SAXException} raised when a SAX - \class{XMLReader} is asked to enable a feature that is not - supported, or to set a property to a value that the implementation - does not support. SAX applications and extensions may use this - class for similar purposes. -\end{excclassdesc} - - -\begin{seealso} - \seetitle[http://www.saxproject.org/]{SAX: The Simple API for - XML}{This site is the focal point for the definition of - the SAX API. It provides a Java implementation and online - documentation. Links to implementations and historical - information are also available.} - - \seemodule{xml.sax.handler}{Definitions of the interfaces for - application-provided objects.} - - \seemodule{xml.sax.saxutils}{Convenience functions for use in SAX - applications.} - - \seemodule{xml.sax.xmlreader}{Definitions of the interfaces for - parser-provided objects.} -\end{seealso} - - -\subsection{SAXException Objects \label{sax-exception-objects}} - -The \class{SAXException} exception class supports the following -methods: - -\begin{methoddesc}[SAXException]{getMessage}{} - Return a human-readable message describing the error condition. -\end{methoddesc} - -\begin{methoddesc}[SAXException]{getException}{} - Return an encapsulated exception object, or \code{None}. -\end{methoddesc} diff --git a/Doc/lib/xmlsaxhandler.tex b/Doc/lib/xmlsaxhandler.tex deleted file mode 100644 index c3c72e7..0000000 --- a/Doc/lib/xmlsaxhandler.tex +++ /dev/null @@ -1,381 +0,0 @@ -\section{\module{xml.sax.handler} --- - Base classes for SAX handlers} - -\declaremodule{standard}{xml.sax.handler} -\modulesynopsis{Base classes for SAX event handlers.} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} -\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no} - -\versionadded{2.0} - - -The SAX API defines four kinds of handlers: content handlers, DTD -handlers, error handlers, and entity resolvers. Applications normally -only need to implement those interfaces whose events they are -interested in; they can implement the interfaces in a single object or -in multiple objects. Handler implementations should inherit from the -base classes provided in the module \module{xml.sax.handler}, so that all -methods get default implementations. - -\begin{classdesc*}{ContentHandler} - This is the main callback interface in SAX, and the one most - important to applications. The order of events in this interface - mirrors the order of the information in the document. -\end{classdesc*} - -\begin{classdesc*}{DTDHandler} - Handle DTD events. - - This interface specifies only those DTD events required for basic - parsing (unparsed entities and attributes). -\end{classdesc*} - -\begin{classdesc*}{EntityResolver} - Basic interface for resolving entities. If you create an object - implementing this interface, then register the object with your - Parser, the parser will call the method in your object to resolve all - external entities. -\end{classdesc*} - -\begin{classdesc*}{ErrorHandler} - Interface used by the parser to present error and warning messages - to the application. The methods of this object control whether errors - are immediately converted to exceptions or are handled in some other - way. -\end{classdesc*} - -In addition to these classes, \module{xml.sax.handler} provides -symbolic constants for the feature and property names. - -\begin{datadesc}{feature_namespaces} - Value: \code{"http://xml.org/sax/features/namespaces"}\\ - true: Perform Namespace processing.\\ - false: Optionally do not perform Namespace processing - (implies namespace-prefixes; default).\\ - access: (parsing) read-only; (not parsing) read/write -\end{datadesc} - -\begin{datadesc}{feature_namespace_prefixes} - Value: \code{"http://xml.org/sax/features/namespace-prefixes"}\\ - true: Report the original prefixed names and attributes used for Namespace - declarations.\\ - false: Do not report attributes used for Namespace declarations, and - optionally do not report original prefixed names (default).\\ - access: (parsing) read-only; (not parsing) read/write -\end{datadesc} - -\begin{datadesc}{feature_string_interning} - Value: \code{"http://xml.org/sax/features/string-interning"}\\ - true: All element names, prefixes, attribute names, Namespace URIs, and - local names are interned using the built-in intern function.\\ - false: Names are not necessarily interned, although they may be (default).\\ - access: (parsing) read-only; (not parsing) read/write -\end{datadesc} - -\begin{datadesc}{feature_validation} - Value: \code{"http://xml.org/sax/features/validation"}\\ - true: Report all validation errors (implies external-general-entities and - external-parameter-entities).\\ - false: Do not report validation errors.\\ - access: (parsing) read-only; (not parsing) read/write -\end{datadesc} - -\begin{datadesc}{feature_external_ges} - Value: \code{"http://xml.org/sax/features/external-general-entities"}\\ - true: Include all external general (text) entities.\\ - false: Do not include external general entities.\\ - access: (parsing) read-only; (not parsing) read/write -\end{datadesc} - -\begin{datadesc}{feature_external_pes} - Value: \code{"http://xml.org/sax/features/external-parameter-entities"}\\ - true: Include all external parameter entities, including the external - DTD subset.\\ - false: Do not include any external parameter entities, even the external - DTD subset.\\ - access: (parsing) read-only; (not parsing) read/write -\end{datadesc} - -\begin{datadesc}{all_features} - List of all features. -\end{datadesc} - -\begin{datadesc}{property_lexical_handler} - Value: \code{"http://xml.org/sax/properties/lexical-handler"}\\ - data type: xml.sax.sax2lib.LexicalHandler (not supported in Python 2)\\ - description: An optional extension handler for lexical events like comments.\\ - access: read/write -\end{datadesc} - -\begin{datadesc}{property_declaration_handler} - Value: \code{"http://xml.org/sax/properties/declaration-handler"}\\ - data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)\\ - description: An optional extension handler for DTD-related events other - than notations and unparsed entities.\\ - access: read/write -\end{datadesc} - -\begin{datadesc}{property_dom_node} - Value: \code{"http://xml.org/sax/properties/dom-node"}\\ - data type: org.w3c.dom.Node (not supported in Python 2) \\ - description: When parsing, the current DOM node being visited if this is - a DOM iterator; when not parsing, the root DOM node for - iteration.\\ - access: (parsing) read-only; (not parsing) read/write -\end{datadesc} - -\begin{datadesc}{property_xml_string} - Value: \code{"http://xml.org/sax/properties/xml-string"}\\ - data type: String\\ - description: The literal string of characters that was the source for - the current event.\\ - access: read-only -\end{datadesc} - -\begin{datadesc}{all_properties} - List of all known property names. -\end{datadesc} - - -\subsection{ContentHandler Objects \label{content-handler-objects}} - -Users are expected to subclass \class{ContentHandler} to support their -application. The following methods are called by the parser on the -appropriate events in the input document: - -\begin{methoddesc}[ContentHandler]{setDocumentLocator}{locator} - Called by the parser to give the application a locator for locating - the origin of document events. - - SAX parsers are strongly encouraged (though not absolutely required) - to supply a locator: if it does so, it must supply the locator to - the application by invoking this method before invoking any of the - other methods in the DocumentHandler interface. - - The locator allows the application to determine the end position of - any document-related event, even if the parser is not reporting an - error. Typically, the application will use this information for - reporting its own errors (such as character content that does not - match an application's business rules). The information returned by - the locator is probably not sufficient for use with a search engine. - - Note that the locator will return correct information only during - the invocation of the events in this interface. The application - should not attempt to use it at any other time. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{startDocument}{} - Receive notification of the beginning of a document. - - The SAX parser will invoke this method only once, before any other - methods in this interface or in DTDHandler (except for - \method{setDocumentLocator()}). -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{endDocument}{} - Receive notification of the end of a document. - - The SAX parser will invoke this method only once, and it will be the - last method invoked during the parse. The parser shall not invoke - this method until it has either abandoned parsing (because of an - unrecoverable error) or reached the end of input. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{startPrefixMapping}{prefix, uri} - Begin the scope of a prefix-URI Namespace mapping. - - The information from this event is not necessary for normal - Namespace processing: the SAX XML reader will automatically replace - prefixes for element and attribute names when the - \code{feature_namespaces} feature is enabled (the default). - -%% XXX This is not really the default, is it? MvL - - There are cases, however, when applications need to use prefixes in - character data or in attribute values, where they cannot safely be - expanded automatically; the \method{startPrefixMapping()} and - \method{endPrefixMapping()} events supply the information to the - application to expand prefixes in those contexts itself, if - necessary. - - Note that \method{startPrefixMapping()} and - \method{endPrefixMapping()} events are not guaranteed to be properly - nested relative to each-other: all \method{startPrefixMapping()} - events will occur before the corresponding \method{startElement()} - event, and all \method{endPrefixMapping()} events will occur after - the corresponding \method{endElement()} event, but their order is - not guaranteed. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{endPrefixMapping}{prefix} - End the scope of a prefix-URI mapping. - - See \method{startPrefixMapping()} for details. This event will - always occur after the corresponding \method{endElement()} event, - but the order of \method{endPrefixMapping()} events is not otherwise - guaranteed. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{startElement}{name, attrs} - Signals the start of an element in non-namespace mode. - - The \var{name} parameter contains the raw XML 1.0 name of the - element type as a string and the \var{attrs} parameter holds an - object of the \ulink{\class{Attributes} - interface}{attributes-objects.html} containing the attributes of the - element. The object passed as \var{attrs} may be re-used by the - parser; holding on to a reference to it is not a reliable way to - keep a copy of the attributes. To keep a copy of the attributes, - use the \method{copy()} method of the \var{attrs} object. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{endElement}{name} - Signals the end of an element in non-namespace mode. - - The \var{name} parameter contains the name of the element type, just - as with the \method{startElement()} event. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{startElementNS}{name, qname, attrs} - Signals the start of an element in namespace mode. - - The \var{name} parameter contains the name of the element type as a - \code{(\var{uri}, \var{localname})} tuple, the \var{qname} parameter - contains the raw XML 1.0 name used in the source document, and the - \var{attrs} parameter holds an instance of the - \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html} - containing the attributes of the element. If no namespace is - associated with the element, the \var{uri} component of \var{name} - will be \code{None}. The object passed as \var{attrs} may be - re-used by the parser; holding on to a reference to it is not a - reliable way to keep a copy of the attributes. To keep a copy of - the attributes, use the \method{copy()} method of the \var{attrs} - object. - - Parsers may set the \var{qname} parameter to \code{None}, unless the - \code{feature_namespace_prefixes} feature is activated. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{endElementNS}{name, qname} - Signals the end of an element in namespace mode. - - The \var{name} parameter contains the name of the element type, just - as with the \method{startElementNS()} method, likewise the - \var{qname} parameter. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{characters}{content} - Receive notification of character data. - - The Parser will call this method to report each chunk of character - data. SAX parsers may return all contiguous character data in a - single chunk, or they may split it into several chunks; however, all - of the characters in any single event must come from the same - external entity so that the Locator provides useful information. - - \var{content} may be a Unicode string or a byte string; the - \code{expat} reader module produces always Unicode strings. - - \note{The earlier SAX 1 interface provided by the Python - XML Special Interest Group used a more Java-like interface for this - method. Since most parsers used from Python did not take advantage - of the older interface, the simpler signature was chosen to replace - it. To convert old code to the new interface, use \var{content} - instead of slicing content with the old \var{offset} and - \var{length} parameters.} -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{ignorableWhitespace}{whitespace} - Receive notification of ignorable whitespace in element content. - - Validating Parsers must use this method to report each chunk - of ignorable whitespace (see the W3C XML 1.0 recommendation, - section 2.10): non-validating parsers may also use this method - if they are capable of parsing and using content models. - - SAX parsers may return all contiguous whitespace in a single - chunk, or they may split it into several chunks; however, all - of the characters in any single event must come from the same - external entity, so that the Locator provides useful - information. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{processingInstruction}{target, data} - Receive notification of a processing instruction. - - The Parser will invoke this method once for each processing - instruction found: note that processing instructions may occur - before or after the main document element. - - A SAX parser should never report an XML declaration (XML 1.0, - section 2.8) or a text declaration (XML 1.0, section 4.3.1) using - this method. -\end{methoddesc} - -\begin{methoddesc}[ContentHandler]{skippedEntity}{name} - Receive notification of a skipped entity. - - The Parser will invoke this method once for each entity - skipped. Non-validating processors may skip entities if they have - not seen the declarations (because, for example, the entity was - declared in an external DTD subset). All processors may skip - external entities, depending on the values of the - \code{feature_external_ges} and the - \code{feature_external_pes} properties. -\end{methoddesc} - - -\subsection{DTDHandler Objects \label{dtd-handler-objects}} - -\class{DTDHandler} instances provide the following methods: - -\begin{methoddesc}[DTDHandler]{notationDecl}{name, publicId, systemId} - Handle a notation declaration event. -\end{methoddesc} - -\begin{methoddesc}[DTDHandler]{unparsedEntityDecl}{name, publicId, - systemId, ndata} - Handle an unparsed entity declaration event. -\end{methoddesc} - - -\subsection{EntityResolver Objects \label{entity-resolver-objects}} - -\begin{methoddesc}[EntityResolver]{resolveEntity}{publicId, systemId} - Resolve the system identifier of an entity and return either the - system identifier to read from as a string, or an InputSource to - read from. The default implementation returns \var{systemId}. -\end{methoddesc} - - -\subsection{ErrorHandler Objects \label{sax-error-handler}} - -Objects with this interface are used to receive error and warning -information from the \class{XMLReader}. If you create an object that -implements this interface, then register the object with your -\class{XMLReader}, the parser will call the methods in your object to -report all warnings and errors. There are three levels of errors -available: warnings, (possibly) recoverable errors, and unrecoverable -errors. All methods take a \exception{SAXParseException} as the only -parameter. Errors and warnings may be converted to an exception by -raising the passed-in exception object. - -\begin{methoddesc}[ErrorHandler]{error}{exception} - Called when the parser encounters a recoverable error. If this method - does not raise an exception, parsing may continue, but further document - information should not be expected by the application. Allowing the - parser to continue may allow additional errors to be discovered in the - input document. -\end{methoddesc} - -\begin{methoddesc}[ErrorHandler]{fatalError}{exception} - Called when the parser encounters an error it cannot recover from; - parsing is expected to terminate when this method returns. -\end{methoddesc} - -\begin{methoddesc}[ErrorHandler]{warning}{exception} - Called when the parser presents minor warning information to the - application. Parsing is expected to continue when this method returns, - and document information will continue to be passed to the application. - Raising an exception in this method will cause parsing to end. -\end{methoddesc} diff --git a/Doc/lib/xmlsaxreader.tex b/Doc/lib/xmlsaxreader.tex deleted file mode 100644 index d669581..0000000 --- a/Doc/lib/xmlsaxreader.tex +++ /dev/null @@ -1,351 +0,0 @@ -\section{\module{xml.sax.xmlreader} --- - Interface for XML parsers} - -\declaremodule{standard}{xml.sax.xmlreader} -\modulesynopsis{Interface which SAX-compliant XML parsers must implement.} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} -\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no} - -\versionadded{2.0} - - -SAX parsers implement the \class{XMLReader} interface. They are -implemented in a Python module, which must provide a function -\function{create_parser()}. This function is invoked by -\function{xml.sax.make_parser()} with no arguments to create a new -parser object. - -\begin{classdesc}{XMLReader}{} - Base class which can be inherited by SAX parsers. -\end{classdesc} - -\begin{classdesc}{IncrementalParser}{} - In some cases, it is desirable not to parse an input source at once, - but to feed chunks of the document as they get available. Note that - the reader will normally not read the entire file, but read it in - chunks as well; still \method{parse()} won't return until the entire - document is processed. So these interfaces should be used if the - blocking behaviour of \method{parse()} is not desirable. - - When the parser is instantiated it is ready to begin accepting data - from the feed method immediately. After parsing has been finished - with a call to close the reset method must be called to make the - parser ready to accept new data, either from feed or using the parse - method. - - Note that these methods must \emph{not} be called during parsing, - that is, after parse has been called and before it returns. - - By default, the class also implements the parse method of the - XMLReader interface using the feed, close and reset methods of the - IncrementalParser interface as a convenience to SAX 2.0 driver - writers. -\end{classdesc} - -\begin{classdesc}{Locator}{} - Interface for associating a SAX event with a document location. A - locator object will return valid results only during calls to - DocumentHandler methods; at any other time, the results are - unpredictable. If information is not available, methods may return - \code{None}. -\end{classdesc} - -\begin{classdesc}{InputSource}{\optional{systemId}} - Encapsulation of the information needed by the \class{XMLReader} to - read entities. - - This class may include information about the public identifier, - system identifier, byte stream (possibly with character encoding - information) and/or the character stream of an entity. - - Applications will create objects of this class for use in the - \method{XMLReader.parse()} method and for returning from - EntityResolver.resolveEntity. - - An \class{InputSource} belongs to the application, the - \class{XMLReader} is not allowed to modify \class{InputSource} objects - passed to it from the application, although it may make copies and - modify those. -\end{classdesc} - -\begin{classdesc}{AttributesImpl}{attrs} - This is an implementation of the \ulink{\class{Attributes} - interface}{attributes-objects.html} (see - section~\ref{attributes-objects}). This is a dictionary-like - object which represents the element attributes in a - \method{startElement()} call. In addition to the most useful - dictionary operations, it supports a number of other methods as - described by the interface. Objects of this class should be - instantiated by readers; \var{attrs} must be a dictionary-like - object containing a mapping from attribute names to attribute - values. -\end{classdesc} - -\begin{classdesc}{AttributesNSImpl}{attrs, qnames} - Namespace-aware variant of \class{AttributesImpl}, which will be - passed to \method{startElementNS()}. It is derived from - \class{AttributesImpl}, but understands attribute names as - two-tuples of \var{namespaceURI} and \var{localname}. In addition, - it provides a number of methods expecting qualified names as they - appear in the original document. This class implements the - \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html} - (see section~\ref{attributes-ns-objects}). -\end{classdesc} - - -\subsection{XMLReader Objects \label{xmlreader-objects}} - -The \class{XMLReader} interface supports the following methods: - -\begin{methoddesc}[XMLReader]{parse}{source} - Process an input source, producing SAX events. The \var{source} - object can be a system identifier (a string identifying the - input source -- typically a file name or an URL), a file-like - object, or an \class{InputSource} object. When \method{parse()} - returns, the input is completely processed, and the parser object - can be discarded or reset. As a limitation, the current implementation - only accepts byte streams; processing of character streams is for - further study. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{getContentHandler}{} - Return the current \class{ContentHandler}. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{setContentHandler}{handler} - Set the current \class{ContentHandler}. If no - \class{ContentHandler} is set, content events will be discarded. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{getDTDHandler}{} - Return the current \class{DTDHandler}. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{setDTDHandler}{handler} - Set the current \class{DTDHandler}. If no \class{DTDHandler} is - set, DTD events will be discarded. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{getEntityResolver}{} - Return the current \class{EntityResolver}. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{setEntityResolver}{handler} - Set the current \class{EntityResolver}. If no - \class{EntityResolver} is set, attempts to resolve an external - entity will result in opening the system identifier for the entity, - and fail if it is not available. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{getErrorHandler}{} - Return the current \class{ErrorHandler}. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{setErrorHandler}{handler} - Set the current error handler. If no \class{ErrorHandler} is set, - errors will be raised as exceptions, and warnings will be printed. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{setLocale}{locale} - Allow an application to set the locale for errors and warnings. - - SAX parsers are not required to provide localization for errors and - warnings; if they cannot support the requested locale, however, they - must throw a SAX exception. Applications may request a locale change - in the middle of a parse. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{getFeature}{featurename} - Return the current setting for feature \var{featurename}. If the - feature is not recognized, \exception{SAXNotRecognizedException} is - raised. The well-known featurenames are listed in the module - \module{xml.sax.handler}. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{setFeature}{featurename, value} - Set the \var{featurename} to \var{value}. If the feature is not - recognized, \exception{SAXNotRecognizedException} is raised. If the - feature or its setting is not supported by the parser, - \var{SAXNotSupportedException} is raised. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{getProperty}{propertyname} - Return the current setting for property \var{propertyname}. If the - property is not recognized, a \exception{SAXNotRecognizedException} - is raised. The well-known propertynames are listed in the module - \module{xml.sax.handler}. -\end{methoddesc} - -\begin{methoddesc}[XMLReader]{setProperty}{propertyname, value} - Set the \var{propertyname} to \var{value}. If the property is not - recognized, \exception{SAXNotRecognizedException} is raised. If the - property or its setting is not supported by the parser, - \var{SAXNotSupportedException} is raised. -\end{methoddesc} - - -\subsection{IncrementalParser Objects - \label{incremental-parser-objects}} - -Instances of \class{IncrementalParser} offer the following additional -methods: - -\begin{methoddesc}[IncrementalParser]{feed}{data} - Process a chunk of \var{data}. -\end{methoddesc} - -\begin{methoddesc}[IncrementalParser]{close}{} - Assume the end of the document. That will check well-formedness - conditions that can be checked only at the end, invoke handlers, and - may clean up resources allocated during parsing. -\end{methoddesc} - -\begin{methoddesc}[IncrementalParser]{reset}{} - This method is called after close has been called to reset the - parser so that it is ready to parse new documents. The results of - calling parse or feed after close without calling reset are - undefined. -\end{methoddesc} - - -\subsection{Locator Objects \label{locator-objects}} - -Instances of \class{Locator} provide these methods: - -\begin{methoddesc}[Locator]{getColumnNumber}{} - Return the column number where the current event ends. -\end{methoddesc} - -\begin{methoddesc}[Locator]{getLineNumber}{} - Return the line number where the current event ends. -\end{methoddesc} - -\begin{methoddesc}[Locator]{getPublicId}{} - Return the public identifier for the current event. -\end{methoddesc} - -\begin{methoddesc}[Locator]{getSystemId}{} - Return the system identifier for the current event. -\end{methoddesc} - - -\subsection{InputSource Objects \label{input-source-objects}} - -\begin{methoddesc}[InputSource]{setPublicId}{id} - Sets the public identifier of this \class{InputSource}. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{getPublicId}{} - Returns the public identifier of this \class{InputSource}. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{setSystemId}{id} - Sets the system identifier of this \class{InputSource}. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{getSystemId}{} - Returns the system identifier of this \class{InputSource}. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{setEncoding}{encoding} - Sets the character encoding of this \class{InputSource}. - - The encoding must be a string acceptable for an XML encoding - declaration (see section 4.3.3 of the XML recommendation). - - The encoding attribute of the \class{InputSource} is ignored if the - \class{InputSource} also contains a character stream. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{getEncoding}{} - Get the character encoding of this InputSource. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{setByteStream}{bytefile} - Set the byte stream (a Python file-like object which does not - perform byte-to-character conversion) for this input source. - - The SAX parser will ignore this if there is also a character stream - specified, but it will use a byte stream in preference to opening a - URI connection itself. - - If the application knows the character encoding of the byte stream, - it should set it with the setEncoding method. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{getByteStream}{} - Get the byte stream for this input source. - - The getEncoding method will return the character encoding for this - byte stream, or None if unknown. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{setCharacterStream}{charfile} - Set the character stream for this input source. (The stream must be - a Python 1.6 Unicode-wrapped file-like that performs conversion to - Unicode strings.) - - If there is a character stream specified, the SAX parser will ignore - any byte stream and will not attempt to open a URI connection to the - system identifier. -\end{methoddesc} - -\begin{methoddesc}[InputSource]{getCharacterStream}{} - Get the character stream for this input source. -\end{methoddesc} - - -\subsection{The \class{Attributes} Interface \label{attributes-objects}} - -\class{Attributes} objects implement a portion of the mapping -protocol, including the methods \method{copy()}, \method{get()}, -\method{has_key()}, \method{items()}, \method{keys()}, and -\method{values()}. The following methods are also provided: - -\begin{methoddesc}[Attributes]{getLength}{} - Return the number of attributes. -\end{methoddesc} - -\begin{methoddesc}[Attributes]{getNames}{} - Return the names of the attributes. -\end{methoddesc} - -\begin{methoddesc}[Attributes]{getType}{name} - Returns the type of the attribute \var{name}, which is normally - \code{'CDATA'}. -\end{methoddesc} - -\begin{methoddesc}[Attributes]{getValue}{name} - Return the value of attribute \var{name}. -\end{methoddesc} - -% getValueByQName, getNameByQName, getQNameByName, getQNames available -% here already, but documented only for derived class. - - -\subsection{The \class{AttributesNS} Interface \label{attributes-ns-objects}} - -This interface is a subtype of the \ulink{\class{Attributes} -interface}{attributes-objects.html} (see -section~\ref{attributes-objects}). All methods supported by that -interface are also available on \class{AttributesNS} objects. - -The following methods are also available: - -\begin{methoddesc}[AttributesNS]{getValueByQName}{name} - Return the value for a qualified name. -\end{methoddesc} - -\begin{methoddesc}[AttributesNS]{getNameByQName}{name} - Return the \code{(\var{namespace}, \var{localname})} pair for a - qualified \var{name}. -\end{methoddesc} - -\begin{methoddesc}[AttributesNS]{getQNameByName}{name} - Return the qualified name for a \code{(\var{namespace}, - \var{localname})} pair. -\end{methoddesc} - -\begin{methoddesc}[AttributesNS]{getQNames}{} - Return the qualified names of all attributes. -\end{methoddesc} diff --git a/Doc/lib/xmlsaxutils.tex b/Doc/lib/xmlsaxutils.tex deleted file mode 100644 index 64221f5..0000000 --- a/Doc/lib/xmlsaxutils.tex +++ /dev/null @@ -1,81 +0,0 @@ -\section{\module{xml.sax.saxutils} --- - SAX Utilities} - -\declaremodule{standard}{xml.sax.saxutils} -\modulesynopsis{Convenience functions and classes for use with SAX.} -\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de} -\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no} - -\versionadded{2.0} - - -The module \module{xml.sax.saxutils} contains a number of classes and -functions that are commonly useful when creating SAX applications, -either in direct use, or as base classes. - -\begin{funcdesc}{escape}{data\optional{, entities}} - Escape \character{\&}, \character{<}, and \character{>} in a string - of data. - - You can escape other strings of data by passing a dictionary as the - optional \var{entities} parameter. The keys and values must all be - strings; each key will be replaced with its corresponding value. -\end{funcdesc} - -\begin{funcdesc}{unescape}{data\optional{, entities}} - Unescape \character{\&}, \character{\<}, and \character{\>} - in a string of data. - - You can unescape other strings of data by passing a dictionary as the - optional \var{entities} parameter. The keys and values must all be - strings; each key will be replaced with its corresponding value. - - \versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{quoteattr}{data\optional{, entities}} - Similar to \function{escape()}, but also prepares \var{data} to be - used as an attribute value. The return value is a quoted version of - \var{data} with any additional required replacements. - \function{quoteattr()} will select a quote character based on the - content of \var{data}, attempting to avoid encoding any quote - characters in the string. If both single- and double-quote - characters are already in \var{data}, the double-quote characters - will be encoded and \var{data} will be wrapped in double-quotes. The - resulting string can be used directly as an attribute value: - -\begin{verbatim} ->>> print "<element attr=%s>" % quoteattr("ab ' cd \" ef") -<element attr="ab ' cd " ef"> -\end{verbatim} - - This function is useful when generating attribute values for HTML or - any SGML using the reference concrete syntax. - \versionadded{2.2} -\end{funcdesc} - -\begin{classdesc}{XMLGenerator}{\optional{out\optional{, encoding}}} - This class implements the \class{ContentHandler} interface by - writing SAX events back into an XML document. In other words, using - an \class{XMLGenerator} as the content handler will reproduce the - original document being parsed. \var{out} should be a file-like - object which will default to \var{sys.stdout}. \var{encoding} is the - encoding of the output stream which defaults to \code{'iso-8859-1'}. -\end{classdesc} - -\begin{classdesc}{XMLFilterBase}{base} - This class is designed to sit between an \class{XMLReader} and the - client application's event handlers. By default, it does nothing - but pass requests up to the reader and events on to the handlers - unmodified, but subclasses can override specific methods to modify - the event stream or the configuration requests as they pass through. -\end{classdesc} - -\begin{funcdesc}{prepare_input_source}{source\optional{, base}} - This function takes an input source and an optional base URL and - returns a fully resolved \class{InputSource} object ready for - reading. The input source can be given as a string, a file-like - object, or an \class{InputSource} object; parsers will use this - function to implement the polymorphic \var{source} argument to their - \method{parse()} method. -\end{funcdesc} |