Commits

Anonymous committed 7266b71

This commit was manufactured by cvs2svn to create tag 'r22a4'.

Comments (0)

Files changed (250)

Doc/lib/.cvsignore

-*.esis
-*.esis1
-*.xml

Doc/lib/asttable.tex

-\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{Backquote}{\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{Dict}{\member{items}}{}
-\hline 
-
-\lineiii{Discard}{\member{expr}}{}
-\hline 
-
-\lineiii{Div}{\member{left}}{}
-\lineiii{}{\member{right}}{}
-\hline 
-
-\lineiii{Ellipsis}{}{}
-\hline 
-
-\lineiii{Exec}{\member{expr}}{}
-\lineiii{}{\member{locals}}{}
-\lineiii{}{\member{globals}}{}
-\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{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{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{Yield}{\member{value}}{}
-\hline 
-
-\end{longtableiii}

Doc/lib/compiler.tex

-\chapter{Python compiler package \label{compiler}}
-
-\sectionauthor{Jeremy Hylton}{jeremy@zope.com}
-
-
-The Python compiler package is a tool for analyzing Python source code
-and generating Python bytecode.  The compiler contains libraries to
-generate an abstract syntax tree from Python source code and to
-generate Python bytecode from the tree.
-
-The \refmodule{compiler} package is a Python source to bytecode
-translator written in Python.  It uses the built-in parser and
-standard \refmodule{parser} module to generated a concrete syntax
-tree.  This tree is used to generate an abstract syntax tree (AST) and
-then Python bytecode.
-
-The full functionality of the package duplicates the builtin compiler
-provided with the Python interpreter.  It is intended to match its
-behavior almost exactly.  Why implement another compiler that does the
-same thing?  The package is useful for a variety of purposes.  It can
-be modified more easily than the builtin compiler.  The AST it
-generates is useful for analyzing Python source code.
-
-This chapter explains how the various components of the
-\refmodule{compiler} package work.  It blends reference material with
-a tutorial.
-
-The following modules are part of the \refmodule{compiler} package:
-
-\localmoduletable
-
-
-\subsection{The basic interface}
-
-\declaremodule{}{compiler}
-
-The top-level of the package defines four functions.  If you import
-\module{compiler}, you will get these functions and a collection of
-modules contained in the package.
-
-\begin{funcdesc}{parse}{buf}
-Returns an abstract syntax tree for the Python source code in \var{buf}.
-The function raises SyntaxError if there is an error in the source
-code.  The return value is a \class{compiler.ast.Module} instance that
-contains the tree.  
-\end{funcdesc}
-
-\begin{funcdesc}{parseFile}{path}
-Return an abstract syntax tree for the Python source code in the file
-specified by \var{path}.  It is equivalent to
-\code{parse(open(\var{path}).read())}.
-\end{funcdesc}
-
-\begin{funcdesc}{walk}{ast, visitor\optional{, verbose}}
-Do a pre-order walk over the abstract syntax tree \var{ast}.  Call the
-appropriate method on the \var{visitor} instance for each node
-encountered.
-\end{funcdesc}
-
-\begin{funcdesc}{compile}{path}
-Compile the file \var{path} and generate the corresponding \file{.pyc}
-file.
-\end{funcdesc}
-
-The \module{compiler} package contains the following modules:
-\refmodule[compiler.ast]{ast}, \module{consts}, \module{future},
-\module{misc}, \module{pyassem}, \module{pycodegen}, \module{symbols},
-\module{transformer}, and \refmodule[compiler.visitor]{visitor}.
-
-\subsection{Limitations}
-
-There are some problems with the error checking of the compiler
-package.  The interpreter detects syntax errors in two distinct
-phases.  One set of errors is detected by the interpreter's parser,
-the other set by the compiler.  The compiler package relies on the
-interpreter's parser, so it get the first phases of error checking for
-free.  It implements the second phase itself, and that implement is
-incomplete.  For example, the compiler package does not raise an error
-if a name appears more than once in an argument list: 
-\code{def f(x, x): ...}
-
-A future version of the compiler should fix these problems.
-
-\section{Python Abstract Syntax}
-
-The \module{compiler.ast} module defines an abstract syntax for
-Python.  In the abstract syntax tree, each node represents a syntactic
-construct.  The root of the tree is \class{Module} object.
-
-The abstract syntax offers a higher level interface to parsed Python
-source code.  The \ulink{\module{parser}}
-{http://www.python.org/doc/current/lib/module-parser.html}
-module and the compiler written in C for the Python interpreter use a
-concrete syntax tree.  The concrete syntax is tied closely to the
-grammar description used for the Python parser.  Instead of a single
-node for a construct, there are often several levels of nested nodes
-that are introduced by Python's precedence rules.
-
-The abstract syntax tree is created by the
-\module{compiler.transformer} module.  The transformer relies on the
-builtin Python parser to generate a concrete syntax tree.  It
-generates an abstract syntax tree from the concrete tree.  
-
-The \module{transformer} module was created by Greg
-Stein\index{Stein, Greg} and Bill Tutt\index{Tutt, Bill} for an
-experimental Python-to-C compiler.  The current version contains a
-number of modifications and improvements, but the basic form of the
-abstract syntax and of the transformer are due to Stein and Tutt.
-
-\subsection{AST Nodes}
-
-\declaremodule{}{compiler.ast}
-
-The \module{compiler.ast} module is generated from a text file that
-describes each node type and its elements.  Each node type is
-represented as a class that inherits from the abstract base class
-\class{compiler.ast.Node} and defines a set of named attributes for
-child nodes.
-
-\begin{classdesc}{Node}{}
-  
-  The \class{Node} instances are created automatically by the parser
-  generator.  The recommended interface for specific \class{Node}
-  instances is to use the public attributes to access child nodes.  A
-  public attribute may be bound to a single node or to a sequence of
-  nodes, depending on the \class{Node} type.  For example, the
-  \member{bases} attribute of the \class{Class} node, is bound to a
-  list of base class nodes, and the \member{doc} attribute is bound to
-  a single node.
-  
-  Each \class{Node} instance has a \member{lineno} attribute which may
-  be \code{None}.  XXX Not sure what the rules are for which nodes
-  will have a useful lineno.
-\end{classdesc}
-
-All \class{Node} objects offer the following methods:
-
-\begin{methoddesc}{getChildren}{}
-  Returns a flattened list of the child nodes and objects in the
-  order they occur.  Specifically, the order of the nodes is the
-  order in which they appear in the Python grammar.  Not all of the
-  children are \class{Node} instances.  The names of functions and
-  classes, for example, are plain strings.
-\end{methoddesc}
-
-\begin{methoddesc}{getChildNodes}{}
-  Returns a flattened list of the child nodes in the order they
-  occur.  This method is like \method{getChildren()}, except that it
-  only returns those children that are \class{Node} instances.
-\end{methoddesc}
-
-Two examples illustrate the general structure of \class{Node}
-classes.  The \keyword{while} statement is defined by the following
-grammar production: 
-
-\begin{verbatim}
-while_stmt:     "while" expression ":" suite
-               ["else" ":" suite]
-\end{verbatim}
-
-The \class{While} node has three attributes: \member{test},
-\member{body}, and \member{else_}.  (If the natural name for an
-attribute is also a Python reserved word, it can't be used as an
-attribute name.  An underscore is appended to the word to make it a
-legal identifier, hence \member{else_} instead of \keyword{else}.)
-
-The \keyword{if} statement is more complicated because it can include
-several tests.  
-
-\begin{verbatim}
-if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]
-\end{verbatim}
-
-The \class{If} node only defines two attributes: \member{tests} and
-\member{else_}.  The \member{tests} attribute is a sequence of test
-expression, consequent body pairs.  There is one pair for each
-\keyword{if}/\keyword{elif} clause.  The first element of the pair is
-the test expression.  The second elements is a \class{Stmt} node that
-contains the code to execute if the test is true.
-
-The \method{getChildren()} method of \class{If} returns a flat list of
-child nodes.  If there are three \keyword{if}/\keyword{elif} clauses
-and no \keyword{else} clause, then \method{getChildren()} will return
-a list of six elements: the first test expression, the first
-\class{Stmt}, the second text expression, etc.
-
-The following table lists each of the \class{Node} subclasses defined
-in \module{compiler.ast} and each of the public attributes available
-on their instances.  The values of most of the attributes are
-themselves \class{Node} instances or sequences of instances.  When the
-value is something other than an instance, the type is noted in the
-comment.  The attributes are listed in the order in which they are
-returned by \method{getChildren()} and \method{getChildNodes()}.
-
-\input{asttable}
-
-
-\subsection{Assignment nodes}
-
-There is a collection of nodes used to represent assignments.  Each
-assignment statement in the source code becomes a single
-\class{Assign} node in the AST.  The \member{nodes} attribute is a
-list that contains a node for each assignment target.  This is
-necessary because assignment can be chained, e.g. \code{a = b = 2}.
-Each \class{Node} in the list will be one of the following classes: 
-\class{AssAttr}, \class{AssList}, \class{AssName}, or
-\class{AssTuple}. 
-
-Each target assignment node will describe the kind of object being
-assigned to:  \class{AssName} for a simple name, e.g. \code{a = 1}.
-\class{AssAttr} for an attribute assigned, e.g. \code{a.x = 1}.
-\class{AssList} and \class{AssTuple} for list and tuple expansion
-respectively, e.g. \code{a, b, c = a_tuple}.
-
-The target assignment nodes also have a \member{flags} attribute that
-indicates whether the node is being used for assignment or in a delete
-statement.  The \class{AssName} is also used to represent a delete
-statement, e.g. \class{del x}.
-
-When an expression contains several attribute references, an
-assignment or delete statement will contain only one \class{AssAttr}
-node -- for the final attribute reference.  The other attribute
-references will be represented as \class{Getattr} nodes in the
-\member{expr} attribute of the \class{AssAttr} instance.
-
-\subsection{Examples}
-
-This section shows several simple examples of ASTs for Python source
-code.  The examples demonstrate how to use the \function{parse()}
-function, what the repr of an AST looks like, and how to access
-attributes of an AST node.
-
-The first module defines a single function.  Assume it is stored in
-\file{/tmp/doublelib.py}. 
-
-\begin{verbatim}
-"""This is an example module.
-
-This is the docstring.
-"""
-
-def double(x):
-    "Return twice the argument"
-    return x * 2
-\end{verbatim}
-
-In the interactive interpreter session below, I have reformatted the
-long AST reprs for readability.  The AST reprs use unqualified class
-names.  If you want to create an instance from a repr, you must import
-the class names from the \module{compiler.ast} module.
-
-\begin{verbatim}
->>> import compiler
->>> mod = compiler.parseFile("/tmp/doublelib.py")
->>> mod
-Module('This is an example module.\n\nThis is the docstring.\n', 
-       Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', 
-       Stmt([Return(Mul((Name('x'), Const(2))))]))]))
->>> from compiler.ast import *
->>> Module('This is an example module.\n\nThis is the docstring.\n', 
-...    Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', 
-...    Stmt([Return(Mul((Name('x'), Const(2))))]))]))
-Module('This is an example module.\n\nThis is the docstring.\n', 
-       Stmt([Function('double', ['x'], [], 0, 'Return twice the argument', 
-       Stmt([Return(Mul((Name('x'), Const(2))))]))]))
->>> mod.doc
-'This is an example module.\n\nThis is the docstring.\n'
->>> for node in mod.node.nodes:
-...     print node
-... 
-Function('double', ['x'], [], 0, 'Return twice the argument',
-         Stmt([Return(Mul((Name('x'), Const(2))))]))
->>> func = mod.node.nodes[0]
->>> func.code
-Stmt([Return(Mul((Name('x'), Const(2))))])
-\end{verbatim}
-
-\section{Using Visitors to Walk ASTs}
-
-\declaremodule{}{compiler.visitor}
-
-The visitor pattern is ...  The \refmodule{compiler} package uses a
-variant on the visitor pattern that takes advantage of Python's
-introspection features to elminiate the need for much of the visitor's
-infrastructure.
-
-The classes being visited do not need to be programmed to accept
-visitors.  The visitor need only define visit methods for classes it
-is specifically interested in; a default visit method can handle the
-rest. 
-
-XXX The magic \method{visit()} method for visitors.
-
-\begin{funcdesc}{walk}{tree, visitor\optional{, verbose}}
-\end{funcdesc}
-
-\begin{classdesc}{ASTVisitor}{}
-
-The \class{ASTVisitor} is responsible for walking over the tree in the
-correct order.  A walk begins with a call to \method{preorder()}.  For
-each node, it checks the \var{visitor} argument to \method{preorder()}
-for a method named `visitNodeType,' where NodeType is the name of the
-node's class, e.g. for a \class{While} node a \method{visitWhile()}
-would be called.  If the method exists, it is called with the node as
-its first argument.
-
-The visitor method for a particular node type can control how child
-nodes are visited during the walk.  The \class{ASTVisitor} modifies
-the visitor argument by adding a visit method to the visitor; this
-method can be used to visit a particular child node.  If no visitor is
-found for a particular node type, the \method{default()} method is
-called. 
-\end{classdesc}
-
-\class{ASTVisitor} objects have the following methods:
-
-XXX describe extra arguments
-
-\begin{methoddesc}{default}{node\optional{, \moreargs}}
-\end{methoddesc}
-
-\begin{methoddesc}{dispatch}{node\optional{, \moreargs}}
-\end{methoddesc}
-
-\begin{methoddesc}{preorder}{tree, visitor}
-\end{methoddesc}
-
-
-\section{Bytecode Generation}
-
-The code generator is a visitor that emits bytecodes.  Each visit method
-can call the \method{emit()} method to emit a new bytecode.  The basic
-code generator is specialized for modules, classes, and functions.  An
-assembler converts that emitted instructions to the low-level bytecode
-format.  It handles things like generator of constant lists of code
-objects and calculation of jump offsets.

Doc/lib/distutils.tex

-\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}.  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 installaion.}
-
-  \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}

Doc/lib/emailencoders.tex

-\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{MIMEImage} and \class{MIMEText} 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 \emph{Quoted-Printable} form and sets the
-\code{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 \emph{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}

Doc/lib/emailexc.tex

-\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 a \emph{Unix-From}
-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.
-\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}.
-\end{excclassdesc}

Doc/lib/emailgenerator.tex

-\declaremodule{standard}{email.Generator}
-\modulesynopsis{Generate flat text email messages from a message object tree.}
-
-One of the most common tasks is to generate the flat text of the email
-message represented by a message object tree.  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 tree 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 an object tree via the
-\class{Parser} class,
-and back to flat text, be idempotent (the input is identical to the
-output).
-
-Here are the public methods of the \class{Generator} class:
-
-\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 2.0 extended print statement.
-
-Optional \var{mangle_from_} is a flag that, when true, puts a ``>''
-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 front of the
-line).  This is the only guaranteed portable way to avoid having such
-lines be mistaken for \emph{Unix-From} headers (see
-\ulink{WHY THE CONTENT-LENGTH FORMAT IS BAD}
-{http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/content-length.html}
-for details).
-
-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 broken on semicolons and continued as per
-\rfc{2822}.  If no semicolon is found, then the header is left alone.
-Set to zero to disable wrapping headers.  Default is 78, as
-recommended (but not required) by \rfc{2822}.
-\end{classdesc}
-
-The other public \class{Generator} methods are:
-
-\begin{methoddesc}[Generator]{__call__}{msg\optional{, unixfrom}}
-Print the textual representation of the message object tree rooted at
-\var{msg} to the output file specified when the \class{Generator}
-instance was created.  Sub-objects 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
-\emph{Unix-From} (a.k.a. envelope header or \code{From_} header)
-delimiter before the first \rfc{2822} header of the root message
-object.  If the root object has no \emph{Unix-From} header, a standard
-one is crafted.  By default, this is set to 0 to inhibit the printing
-of the \emph{Unix-From} delimiter.
-
-Note that for sub-objects, no \emph{Unix-From} header is ever printed.
-\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}.

Doc/lib/emailiter.tex

-\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}
-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.
-\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}
-

Doc/lib/emailmessage.tex

-\declaremodule{standard}{email.Message}
-\modulesynopsis{The base class representing email messages.}
-
-The central class in the \module{email} package is the
-\class{Message} class; 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
-\emph{Unix-From} header, also known as the envelope header or the
-\code{From_} header.  The payload is either a string in the case of
-simple message objects, a list of \class{Message} objects for
-multipart MIME documents, or a single \class{Message} instance for
-\mimetype{message/rfc822} type objects.
-
-\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 formatted message as a string.  Optional
-\var{unixfrom}, when true, specifies to include the \emph{Unix-From}
-envelope header; it defaults to 0.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{__str__()}{}
-Equivalent to \method{aMessage.as_string(unixfrom=1)}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{is_multipart}{}
-Return 1 if the message's payload is a list of sub-\class{Message}
-objects, otherwise return 0.  When \method{is_multipart()} returns 0,
-the payload should either be a string object, or a single
-\class{Message} instance.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_unixfrom}{unixfrom}
-Set the \emph{Unix-From} (a.k.a envelope header or \code{From_}
-header) to \var{unixfrom}, which should be a string.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_unixfrom}{}
-Return the \emph{Unix-From} header.  Defaults to \code{None} if the
-\emph{Unix-From} header was never set.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{add_payload}{payload}
-Add \var{payload} to the message object's existing payload.  If, prior
-to calling this method, the object's payload was \code{None}
-(i.e. never before set), then after this method is called, the payload
-will be the argument \var{payload}.
-
-If the object's payload was already a list
-(i.e. \method{is_multipart()} returns 1), then \var{payload} is
-appended to the end of the existing payload list.
-
-For any other type of existing payload, \method{add_payload()} will
-transform the new payload into a list consisting of the old payload
-and \var{payload}, but only if the document is already a MIME
-multipart document.  This condition is satisfied if the message's
-\mailheader{Content-Type} header's main type is either
-\mimetype{multipart}, or there is no \mailheader{Content-Type}
-header.  In any other situation,
-\exception{MultipartConversionError} is raised.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{attach}{payload}
-Synonymous with \method{add_payload()}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_payload}{\optional{i\optional{, decode}}}
-Return the current payload, which will be a list of \class{Message}
-objects when \method{is_multipart()} returns 1, or a scalar (either a
-string or a single \class{Message} instance) when
-\method{is_multipart()} returns 0.
-
-With optional \var{i}, \method{get_payload()} will return the
-\var{i}-th element of the payload, counting from zero, if
-\method{is_multipart()} returns 1.  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 scalar
-(i.e. \method{is_multipart()} returns 0) 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 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, the payload is returned as-is (undecoded).  If the message is
-a multipart and the \var{decode} flag is true, then \code{None} is
-returned.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{set_payload}{payload}
-Set the entire message object's payload to \var{payload}.  It is the
-client's responsibility to ensure the payload invariants.
-\end{methoddesc}
-
-The following methods implement a mapping-like interface for accessing
-the message object'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, there is an explicit
-order.  These semantic differences are intentional and are biased
-toward maximal convenience.
-
-Note that in all cases, any optional \emph{Unix-From} header the message
-may have 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}.
-Match 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}, first use \method{__delitem__()} to delete all named
-fields, 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 1 if the message contains a header field named \var{name},
-otherwise return 0.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{keys}{}
-Return a list of all the message's header field names.  These keys
-will be sorted in the order in which they were added to the message
-via \method{__setitem__()}, and may contain duplicates.  Any fields
-deleted and then subsequently re-added are always appended to the end
-of the header list.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{values}{}
-Return a list of all the message's field values.  These will be sorted
-in the order in which they were added to the message via
-\method{__setitem__()}, and may contain duplicates.  Any fields
-deleted and then subsequently re-added are always appended to the end
-of the header list.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{items}{}
-Return a list of 2-tuples containing all the message's field headers and
-values.  These will be sorted in the order in which they were added to
-the message via \method{__setitem__()}, and may contain duplicates.
-Any fields deleted and then subsequently re-added are always appended
-to the end of the header list.
-\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}.  These
-will be sorted in the order in which they were added to the message
-via \method{__setitem__()}.  Any fields
-deleted and then subsequently re-added are always appended to the end
-of the list.
-
-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 to set 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]{get_type}{\optional{failobj}}
-Return the message's content type, as a string of the form
-\mimetype{maintype/subtype} as taken from the
-\mailheader{Content-Type} header.
-The returned string is coerced to lowercase.
-
-If there is no \mailheader{Content-Type} header in the message,
-\var{failobj} is returned (defaults to \code{None}).
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_main_type}{\optional{failobj}}
-Return the message's \emph{main} content type.  This essentially returns the
-\var{maintype} part of the string returned by \method{get_type()}, with the
-same semantics for \var{failobj}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_subtype}{\optional{failobj}}
-Return the message's sub-content type.  This essentially returns the
-\var{subtype} part of the string returned by \method{get_type()}, with the
-same semantics for \var{failobj}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_params}{\optional{failobj\optional{, header}}}
-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.  The value is always unquoted with \method{Utils.unquote()}.
-
-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}.
-\end{methoddesc}
-
-\begin{methoddesc}[Message]{get_param}{param\optional{,
-    failobj\optional{, header}}}
-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}.
-\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]{get_filename}{\optional{failobj}}
-Return the value of the \code{filename} parameter of the
-\mailheader{Content-Disposition} header of the message, or \var{failobj} if
-either the header is missing, or has no \code{filename} parameter.
-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} so you should not quote it yourself.  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]{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 ... in} loop; each
-iteration returns the next subpart.
-
-Here's an example that prints the MIME type of every part of a message
-object tree:
-
-\begin{verbatim}
->>> for part in msg.walk():
->>>     print part.get_type('text/plain')
-multipart/report
-text/plain
-message/delivery-status
-text/plain
-text/plain
-message/rfc822
-\end{verbatim}
-\end{methoddesc}
-
-\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.
-
-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.
-\end{datadesc}

Doc/lib/emailparser.tex

-\declaremodule{standard}{email.Parser}
-\modulesynopsis{Parse flat text email messages to produce a message
-	        object tree.}
-
-Message object trees 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{add_payload()} 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 tree.  For
-simple, non-MIME messages the payload of this root object will likely
-be a string (e.g. containing the text of the message).  For MIME
-messages, the root object will return 1 from its
-\method{is_multipart()} method, and the subparts can be accessed via
-the \method{get_payload()} and \method{walk()} methods.
-
-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 in any way it find necessary.
-
-\subsubsection{Parser class API}
-
-\begin{classdesc}{Parser}{\optional{_class}}
-The constructor for the \class{Parser} class takes a single optional
-argument \var{_class}.  This must be callable factory (i.e. 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}).  \var{_class} will be called with zero
-arguments.
-\end{classdesc}
-
-The other public \class{Parser} methods are:
-
-\begin{methoddesc}[Parser]{parse}{fp}
-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 preceeded by a
-\emph{Unix-From} 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).
-\end{methoddesc}
-
-\begin{methoddesc}[Parser]{parsestr}{text}
-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()}.
-\end{methoddesc}
-
-Since creating a message object tree 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}}
-Return a message object tree from a string.  This is exactly
-equivalent to \code{Parser().parsestr(s)}.  Optional \var{_class} is
-interpreted as with the \class{Parser} class constructor.
-\end{funcdesc}
-
-\begin{funcdesc}{message_from_file}{fp\optional{, _class}}
-Return a message object tree from an open file object.  This is exactly
-equivalent to \code{Parser().parse(fp)}.  Optional \var{_class} is
-interpreted as with the \class{Parser} class constructor.
-\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
-      0 for \method{is_multipart()}.
-\item One exception is for \mimetype{message/delivery-status} type
-      messages.  Because the body of such messages consist of
-      blocks of headers, \class{Parser} will create a non-multipart
-      object containing non-multipart subobjects for each header
-      block.
-\item Another exception is for \mimetype{message/*} types (i.e. more
-      general than \mimetype{message/delivery-status}).  These are
-      typically \mimetype{message/rfc822} type messages, represented as a
-      non-multipart object containing a singleton payload, another
-      non-multipart \class{Message} instance.
-\end{itemize}

Doc/lib/emailutil.tex

-\declaremodule{standard}{email.Utils}
-\modulesynopsis{Miscellaneous email package utilities.}
-
-There are several useful utilities provided with the \module{email}
-package.
-
-\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{(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{(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.getall()}.  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}{decode}{s}
-This method decodes a string according to the rules in \rfc{2047}.  It
-returns the decoded string as a Python unicode string.
-\end{funcdesc}
-
-\begin{funcdesc}{encode}{s\optional{, charset\optional{, encoding}}}
-This method encodes a string according to the rules in \rfc{2047}.  It
-is not actually the inverse of \function{decode()} since it doesn't
-handle multiple character sets or multiple string parts needing
-encoding.  In fact, the input string \var{s} must already be encoded
-in the \var{charset} character set (Python can't reliably guess what
-character set a string might be encoded in).  The default
-\var{charset} is \samp{iso-8859-1}.
-
-\var{encoding} must be either the letter \character{q} for
-Quoted-Printable or \character{b} for Base64 encoding.  If
-neither, a \exception{ValueError} is raised.  Both the \var{charset} and
-the \var{encoding} strings are case-insensitive, and coerced to lower
-case in the returned string.
-\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 fields 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 fields 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 worring about for
-common use.
-\end{funcdesc}
-
-\begin{funcdesc}{formatdate}{\optional{timeval}}
-Returns the time formatted as per Internet standards \rfc{2822}
-and updated by \rfc{1123}.  If \var{timeval} is provided, then it
-should be a floating point time value as expected by
-\method{time.gmtime()}, otherwise the current time is used.
-\end{funcdesc}

Doc/lib/internet.tex

-\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

Doc/lib/language.tex

-\chapter{Python Language Services
-         \label{language}}
-
-Python provides a number of modules to assist in working with the
-Python language.  These module support tokenizing, parsing, syntax
-analysis, bytecode disassembly, and various other facilities.
-
-These modules include:
-
-\localmoduletable

Doc/lib/libaifc.tex

-\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}

Doc/lib/libal.tex

-\section{\module{al} ---
-         Audio functions on the SGI}
-
-\declaremodule{builtin}{al}
-  \platform{IRIX}
-\modulesynopsis{Audio functions on the SGI.}
-
-
-This module provides access to the audio facilities of the SGI Indy
-and Indigo workstations.  See section 3A of the IRIX man pages for
-details.  You'll need to read those man pages to understand what these
-functions do!  Some of the functions are not available in IRIX
-releases before 4.0.5.  Again, see the manual to check whether a
-specific function is available on your platform.
-
-All functions and methods defined in this module are equivalent to
-the C functions with \samp{AL} prefixed to their name.
-
-Symbolic constants from the C header file \code{<audio.h>} are
-defined in the standard module
-\refmodule[al-constants]{AL}\refstmodindex{AL}, see below.
-
-\strong{Warning:} the current version of the audio library may dump core
-when bad argument values are passed rather than returning an error
-status.  Unfortunately, since the precise circumstances under which
-this may happen are undocumented and hard to check, the Python
-interface can provide no protection against this kind of problems.
-(One example is specifying an excessive queue size --- there is no
-documented upper limit.)
-
-The module defines the following functions:
-
-
-\begin{funcdesc}{openport}{name, direction\optional{, config}}
-The name and direction arguments are strings.  The optional
-\var{config} argument is a configuration object as returned by
-\function{newconfig()}.  The return value is an \dfn{audio port
-object}; methods of audio port objects are described below.
-\end{funcdesc}
-
-\begin{funcdesc}{newconfig}{}
-The return value is a new \dfn{audio configuration object}; methods of
-audio configuration objects are described below.
-\end{funcdesc}
-
-\begin{funcdesc}{queryparams}{device}
-The device argument is an integer.  The return value is a list of
-integers containing the data returned by \cfunction{ALqueryparams()}.
-\end{funcdesc}
-
-\begin{funcdesc}{getparams}{device, list}
-The \var{device} argument is an integer.  The list argument is a list
-such as returned by \function{queryparams()}; it is modified in place
-(!).
-\end{funcdesc}
-
-\begin{funcdesc}{setparams}{device, list}
-The \var{device} argument is an integer.  The \var{list} argument is a
-list such as returned by \function{queryparams()}.
-\end{funcdesc}
-
-
-\subsection{Configuration Objects \label{al-config-objects}}
-
-Configuration objects (returned by \function{newconfig()} have the
-following methods:
-
-\begin{methoddesc}[audio configuration]{getqueuesize}{}
-Return the queue size.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{setqueuesize}{size}
-Set the queue size.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{getwidth}{}
-Get the sample width.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{setwidth}{width}
-Set the sample width.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{getchannels}{}
-Get the channel count.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{setchannels}{nchannels}
-Set the channel count.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{getsampfmt}{}
-Get the sample format.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{setsampfmt}{sampfmt}
-Set the sample format.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{getfloatmax}{}
-Get the maximum value for floating sample formats.
-\end{methoddesc}
-
-\begin{methoddesc}[audio configuration]{setfloatmax}{floatmax}
-Set the maximum value for floating sample formats.
-\end{methoddesc}
-
-
-\subsection{Port Objects \label{al-port-objects}}
-
-Port objects, as returned by \function{openport()}, have the following
-methods:
-
-\begin{methoddesc}[audio port]{closeport}{}
-Close the port.
-\end{methoddesc}
-
-\begin{methoddesc}[audio port]{getfd}{}
-Return the file descriptor as an int.
-\end{methoddesc}
-
-\begin{methoddesc}[audio port]{getfilled}{}
-Return the number of filled samples.
-\end{methoddesc}
-
-\begin{methoddesc}[audio port]{getfillable}{}
-Return the number of fillable samples.
-\end{methoddesc}
-
-\begin{methoddesc}[audio port]{readsamps}{nsamples}
-Read a number of samples from the queue, blocking if necessary.
-Return the data as a string containing the raw data, (e.g., 2 bytes per
-sample in big-endian byte order (high byte, low byte) if you have set
-the sample width to 2 bytes).
-\end{methoddesc}
-
-\begin{methoddesc}[audio port]{writesamps}{samples}
-Write samples into the queue, blocking if necessary.  The samples are
-encoded as described for the \method{readsamps()} return value.
-\end{methoddesc}