% Questions:
% Should xmllib.py be moved into xml.parsers?  What about pyexpat.so?
% Should ErrorPrinter go to standard error, not stdout?

\documentclass{howto}

\newcommand{\element}[1]{\code{#1}}
\newcommand{\attribute}[1]{\code{#1}}

\title{Python/XML Reference Guide}

\release{0.06}

\author{The Python/XML Special Interest Group}
\authoraddress{\email{xml-sig@python.org}\break (edited by \email{akuchling@acm.org})}

\begin{document}
\maketitle

\begin{abstract}
\noindent
XML is the eXtensible Markup Language, a subset of SGML, intended to
allow the creation and processing of application-specific markup
languages.  Python makes an excellent language for processing XML
data.  This document is the reference manual for the Python/XML
package, containing several XML modules.

This is a draft document; 'XXX' in the text indicates that something
has to be filled in later, or rewritten, or verified, or something.  

   THIS DOCUMENT IS SIGNIFICANTLY OUTDATED, DO NOT USE IT AS A BASIS OF
   APPLICATION DEVELOPMENT.

\end{abstract}

\tableofcontents

%\section{\module{xml.dom}}

\section{\module{xml.dom.ext.c14n} ---
         Canonical XML generation}

This module takes a DOM element node (and all its children) and generates
canonical XML as defined by the W3C candidate recommendation
\url{http://www.w3.org/TR/xml-c14n}.
(Unlike the specification, however, general document subsets are not
supported.)

The module name, \code{c14n}, comes from the standard way of abbreviating
the word "canonicalization."
This module is typically imported by doing
\code{from xml.dom.ext import Canonicalize}.

\begin{funcdesc}{Canonicalize}{node\optional{output\optional{**keywords}}}
This function generates the canonical format.
If \var{output} is specified, the data is sent by invoking its
\method{write} method, the the function will return \var{None}.
If \var{output} is omitted or has the value \var{None}, then
the \method{Canonicalize} will return the data as a string.

The keyword argument \var{comments}, if non-zero, directs the function
to leave any comment nodes in the output. By default, they are removed.

The keyword argument \var{stripspace}, if non-zero, directs the function
to strip all extra whitespace from text elements.
By default, whitespace is preserved.
This argument should be used with caution, as the canonicalization
specification directs that whitespace be preserved.

The keyword argument \var{nsdict} may be used to provide a namespace
dictionary that is assumed to be in the \var{node}'s containing
context.
The keys are namespace prefixes, and the values are the namespace URI's.
If \var{nsdict} is \code{None} or an empty dictionary, then an initial
dictionary containing just the URI's for the \code{xml} and \code{xmlns}
prefixes will be used.
\end{funcdesc}

%\section{builder}
%\section{core}
%\section{esis_builder}
%\section{html_builder}
%\section{sax_builder}
%\section{transform}
%\section{transformer}
%\section{walker}
%\section{writer}

%\section{\module{xml.marshal}}


\section{\module{xml.ns} ---
         XML Namespace constants}

\declaremodule{}{xml.ns}
\modulesynopsis{Constants giving the URIs for common namespaces.}
\moduleauthor{Rich Salz}{rsalz@zolera.com}
\sectionauthor{Rich Salz}{rsalz@zolera.com}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}

This module contains the definitions of namespaces (and sometimes
other URI's) used by a variety of XML standards.  Each class has a
short all-uppercase name, which should follow any (emerging)
convention for how that standard is commonly used.  For example,
\samp{ds} is almost always used as the namespace prefixes for items in
XML Signature, so \samp{DS} is the class name.  Attributes within that
class define symbolic names (hopefully evocative) for ``constants''
used in that standard.

\begin{classdesc*}{XMLNS}
  The \citetitle[http://www.w3.org/TR/REC-xml-names]{Namespaces in
  XML} recommendation defines the concept and syntactic constructs
  relating to XML namespaces.

  \begin{memberdesc}{BASE}
    The namespace URI assigned to namespace declarations.  This is
    assigned to attributes named \code{xmlns} and attributes which
    have a namespace prefix of \code{xmlns}.
  \end{memberdesc}

  \begin{memberdesc}{XML}
    The namespace bound to this URI is used for all elements and
    attributes which start with the letters \samp{xml}, regardless of
    case.  No other elements or attributes are allowed to use this
    namespace.
  \end{memberdesc}

  \begin{memberdesc}{HTML}
    This namespace is recommended for use with HTML 4.0.
  \end{memberdesc}
\end{classdesc*}


\begin{classdesc*}{XLINK}
  The \citetitle[http://www.w3.org/TR/xlink/]{XML Linking Language}
  defines document linking semantics and an attribute language that
  allows these semantics to be expressed in XML documents.

  \begin{memberdesc}{BASE}
    The URI of the global attributes defined in the XLink
    specification.  All attributes that define the presence and
    behavior of links are in this namespace.
  \end{memberdesc}
\end{classdesc*}


\begin{classdesc*}{SOAP}
  \citetitle[http://www.w3.org/TR/SOAP]{Simple Object Access Protocol}
  defines a means of communicating with objects on servers. It can be
  used as a remote procedure call (RPC) mechanism, or as a basis for
  message passing systems.

  \begin{memberdesc}{ENV}
    This URI is used for the namespace of the ``envelope'' which
    contains the message.  Elements in this namespace provide for
    destination identification and other information needed to route
    and decode the message.
  \end{memberdesc}

  \begin{memberdesc}{ENC}
    The namespace URI used for the optional payload encoding defined
    in section 5 of the SOAP specification.
  \end{memberdesc}

  \begin{memberdesc}{ACTOR_NEXT}
    The URI specified in section 4.2.2 of the SOAP specification which
    is used to indicate the destination of a SOAP message.
  \end{memberdesc}
\end{classdesc*}


\begin{classdesc*}{DSIG}
  The namespace URIs given here are defined by the XML digital
  signature specification.

  \begin{memberdesc}{BASE}
    The basic namespace defined by the specification.
  \end{memberdesc}

  \begin{memberdesc}{C14N}
    The URI by which
    \citetitle[http://www.w3.org/TR/xml-c14n]{Canonical XML} (Version
    1.0) is identified when used as a transformation or
    canonicalization method.
  \end{memberdesc}

  \begin{memberdesc}{C14N_COMM}
    This URI identifies ``canonical XML with comments,'' as described
    in \citetitle[http://www.w3.org/TR/xml-c14n]{Canonical XML}
    (Version 1.0), section 2.1.
  \end{memberdesc}

  \begin{memberdesc}{C14N_EXCL}
    The URI by which the canonicalization variant defined in
    \citetitle[http://www.w3.org/TR/xml-exc-c14n]{Exclusive XML
    Canonicalization} (Version 1.0) is identified when used as a
    transformation or canonicalization method.
  \end{memberdesc}

  The specification also assigns URIs to specific methods of computing
  message digests and signatures, and other encoding techniques used
  in the specification.

  \begin{memberdesc}{DIGEST_SHA1}
    The URI for the SHA-1 digest method.
  \end{memberdesc}

  \begin{memberdesc}{DIGEST_MD2}
    The URI for the MD2 digest method.
  \end{memberdesc}

  \begin{memberdesc}{DIGEST_MD5}
    The URI for the MD5 digest method.
  \end{memberdesc}

  \begin{memberdesc}{SIG_DSA_SHA1}
    The URI used to specify the Digital Signature Algorithm (DSA) with
    the SHA-1 hash algorithm.  DSA is specified in FIPS PUB 186-2,
    \citetitle
      [http://csrc.nist.gov/publications/fips/fips186-2/fips186-2.pdf]
      {Digital Signature Standard (DSS)}.
  \end{memberdesc}

  \begin{memberdesc}{SIG_RSA_SHA1}
    The URI indicating the RSA signature algorithm using SHA-1 for the
    secure hash.
  \end{memberdesc}

  \begin{memberdesc}{HMAC_SHA1}
    URI for the SHA-1 HMAC algorithm.
  \end{memberdesc}

  \begin{memberdesc}{ENC_BASE64}
    URI used to denote the base64 encoding and transform.
  \end{memberdesc}

  \begin{memberdesc}{ENVELOPED}
    URI used to specify the enveloped signature transform method
    (\ulink{section
    6.6.4}{http://www.w3.org/TR/xmldsig-core/#sec-EnvelopedSignature}
    of the specification).
  \end{memberdesc}

  \begin{memberdesc}{XPATH}
    URI used to specify the XPath filtering transform method
    (\ulink{section
    6.6.3}{http://www.w3.org/TR/xmldsig-core/#sec-XPath} of the
    specification).
  \end{memberdesc}

  \begin{memberdesc}{XSLT}
    URI used to specify the XSLT transform method (\ulink{section
    6.6.5}{http://www.w3.org/TR/xmldsig-core/#sec-XSLT} of the
    specification).
  \end{memberdesc}
\end{classdesc*}


\begin{classdesc*}{RNG}
  The URIs provided here are used with the Relax NG schema language.

  \begin{memberdesc}{BASE}
    The namespace URI of the elements defined by the
    \citetitle[http://www.oasis-open.org/committees/relax-ng/spec-20011203.html]
    {Relax NG Specification}.
  \end{memberdesc}
\end{classdesc*}


\begin{classdesc*}{SCHEMA}

  \begin{memberdesc}{BASE}
  \end{memberdesc}

  \begin{memberdesc}{XSD1}
  \end{memberdesc}

  \begin{memberdesc}{XSD2}
  \end{memberdesc}

  \begin{memberdesc}{XSD3}
  \end{memberdesc}

  \begin{memberdesc}{XSI1}
  \end{memberdesc}

  \begin{memberdesc}{XSI2}
  \end{memberdesc}

  \begin{memberdesc}{XSI3}
  \end{memberdesc}

  Two additional convenience attributes are defined:

  \begin{memberdesc}{XSD_LIST}
    A sequence of all ... namespaces.
  \end{memberdesc}

  \begin{memberdesc}{XSI_LIST}
    A sequence of all ... namespaces.
  \end{memberdesc}
\end{classdesc*}


\begin{classdesc*}{XSLT}
  XSLT, defined in \citetitle[http://www.w3.org/TR/]{XML Stylesheet
  Language --- Transformations}, defines a single namespace:

  \begin{memberdesc}{BASE}
    This URI is used as the namespace for all XSLT elements and for
    XSLT attributes attached to non-XSLT elements.
  \end{memberdesc}
\end{classdesc*}


%\begin{classdesc*}{XPATH}
  % Why does this class even exist if there are no namespaces?
%\end{classdesc*}


\begin{classdesc*}{WSDL}
  The Web Services Description Language (WSDL) defines a language to
  specify the logical interactions with applications that use Web
  technologies as their access mechanism; this can be thought of as an
  IDL for servers that speak HTTP instead of XDR or IIOP.

  \begin{memberdesc}{BASE}
    The basic namespace defined in this specification.
  \end{memberdesc}

  \begin{memberdesc}{BIND_SOAP}
    The URI of the SOAP binding for WSDL.
  \end{memberdesc}

  \begin{memberdesc}{BIND_HTTP}
    HTTP bindings for WSDL using the \code{GET} and \code{POST}
    methods.
  \end{memberdesc}

  \begin{memberdesc}{BIND_MIME}
    The URI of the namespace for MIME-type bindings for WSDL.
  \end{memberdesc}
\end{classdesc*}


\section{\module{xml.parsers.xmllib} ---
         Augmented version of \module{xmllib}}

This is a version of the \module{xmllib} module from Python 1.5,
modified to use the \module{sgmlop} C extension when it's available.
This produces a significant speedup, amounting to about a factor of 5.
The interface is unchanged from the original \module{xmllib} module;
consult the
\citetitle[http://www.python.org/doc/current/lib/module-xmllib.html]{Python
Library Reference} documentation for that module.


%\section{\module{xml.sax.drivers}}

%XXX Should all the driver modules be documented, or should they be
%treated as internal modules, whose details will be handled by a parser
%Factory function?

%\section{\module{xml.sax.drivers.drv_xmllib}}
%\section{\module{xml.sax.drivers.drv_xmlproc}}
%\section{\module{xml.sax.drivers.drv_xmlproc_val}}
%\section{\module{xml.sax.drivers.drv_xmltok}}
%\section{\module{xml.sax.drivers.drv_xmltoolkit}}

\section{\module{xml.sax.saxexts}}

\begin{funcdesc}{make_parser}{\optional{parser}}
A utility function that returns a \class{Parser} object for a
non-validating XML parser.  If \var{parser} is specified, it must be a 
parser name; otherwise, a list of available parsers is checked and the
fastest one chosen.
\end{funcdesc}

\begin{datadesc}{HTMLParserFactory}
An instance of the \class{ParserFactory} class that's already been
prepared with a list of HTML parsers.  Simply call its
\method{make_parser()} method to get a \class{Parser} object. 
\end{datadesc}

\begin{classdesc}{ParserFactory}{}
A general class to be used by applications for creating parsers on
foreign systems where the list of installed parsers is unknown.
\end{classdesc}

\begin{datadesc}{SGMLParserFactory}
An instance of the \class{ParserFactory} class that's already been
prepared with a list of SGML parsers.  Simply call its
\method{make_parser()} method to get a parser object. 
\end{datadesc}

\begin{datadesc}{XMLParserFactory}
An instance of the \class{ParserFactory} class that's already been
prepared with a list of nonvalidating XML parsers.  Simply call its
\method{make_parser()} method to get a parser object. 
\end{datadesc}

\begin{datadesc}{XMLValParserFactory}
An instance of the \class{ParserFactory} class that's already been
prepared with a list of validating XML parsers.  Simply call its
\method{make_parser()} method to get a parser object. 
\end{datadesc}

\begin{classdesc}{ExtendedParser}{}
This class is an experimental extended parser interface, that offers
additional functionality that may be useful.  However, it's not
specified by the SAX specification.
\end{classdesc}

\subsection{\class{ExtendedParser} methods}

\begin{methoddesc}{close}{}
Called after the last call to feed, when there are no more data.
\end{methoddesc}

\begin{methoddesc}{feed}{data}
Feeds \var{data} to the parser.
\end{methoddesc}

\begin{methoddesc}{get_parser_name}{}
Returns a single-word parser name.
\end{methoddesc}

\begin{methoddesc}{get_parser_version}{}
Returns the version of the imported parser, which may not be the
one the driver was implemented for.
\end{methoddesc}

\begin{methoddesc}{is_dtd_reading}{}
True if the parser is non-validating, but conforms to the XML specification by
reading the DTD.
\end{methoddesc}

\begin{methoddesc}{is_validating}{}
Returns true if the parser is validating, false otherwise.
\end{methoddesc}

\begin{methoddesc}{reset}{}
Makes the parser start parsing afresh.
\end{methoddesc}

\subsection{\class{ParserFactory} methods}

\begin{methoddesc}{get_parser_list}{}
Returns the list of possible drivers.  Currently this starts out as
\code{["xml.sax.drivers.drv_xmltok",
                      "xml.sax.drivers.drv_xmlproc",
                      "xml.sax.drivers.drv_xmltoolkit",
                      "xml.sax.drivers.drv_xmllib"]}.
\end{methoddesc}

\begin{methoddesc}{make_parser}{\optional{driver_name}}
Returns a SAX driver for the first available parser of the parsers
in the list. Note that the list contains drivers, so it first tries
the driver and if that exists imports it to see if the parser also
exists. If no parsers are available a \class{SAXException} is thrown.

Optionally, \var{driver_name} can be a string containing the name of
the driver to be used; the stored parser list will then not be used at
all.  
\end{methoddesc}

\begin{methoddesc}{set_parser_list}{list}
Sets the driver list to \var{list}.
\end{methoddesc}


\section{\module{xml.sax.saxlib}}

\begin{classdesc}{AttributeList}{}
Interface for an attribute list. This interface provides
    information about a list of attributes for an element (only
    specified or defaulted attributes will be reported). Note that the
    information returned by this object will be valid only during the
    scope of the \method{DocumentHandler.startElement} callback, and the
    attributes will not necessarily be provided in the order declared
    or specified.
\end{classdesc}

\begin{classdesc}{DocumentHandler}{}
Handle general document events. This is the main client
    interface for SAX: it contains callbacks for the most important
    document events, such as the start and end of elements. You need
    to create an object that implements this interface, and then
    register it with the \class{Parser}. If you do not want to implement
    the entire interface, you can derive a class from \class{HandlerBase},
    which implements the default functionality. You can find the
    location of any document event using the \class{Locator} interface
    supplied by \method{setDocumentLocator()}.
\end{classdesc}

\begin{classdesc}{DTDHandler}{}
Handle DTD events. This interface specifies only those DTD
    events required for basic parsing (unparsed entities and
    attributes). If you do not want to implement the entire interface,
    you can extend \class{HandlerBase}, which implements the default
    behaviour.
\end{classdesc}

\begin{classdesc}{EntityResolver}{}
This is the basic interface for resolving entities. If you create an object
    implementing this interface, then register the object with your
    \class{Parser} instance, the parser will call the method in your object to
    resolve all external entities. Note that \class{HandlerBase} implements
    this interface with the default behaviour.
\end{classdesc}

\begin{classdesc}{ErrorHandler}{}
This is the basic interface for SAX error handlers. If you create an object
    that implements this interface, then register the object with your
    Parser, 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 SAXParseException as the
    only parameter.
\end{classdesc}

\begin{classdesc}{HandlerBase}{}
Default base class for handlers. This class implements the default
    behaviour for four SAX interfaces, inheriting from them all:
    \class{EntityResolver}, \class{DTDHandler},
    \class{DocumentHandler}, and \class{ErrorHandler}.  Rather than
    implementing those full interfaces, you may simply extend this
    class and override the methods that you need. Note that the use of
    this class is optional, since you are free to implement the
    interfaces directly if you wish.
\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 methods of the \class{SAXDocumentHandler} class; 
at any other time, the results are unpredictable.
\end{classdesc}

\begin{classdesc}{Parser}{}
Basic interface for SAX parsers. All SAX
    parsers must implement this basic interface: it allows users to
    register handlers for different types of events and to initiate a
    parse from a URI, a character stream, or a byte stream. SAX
    parsers should also implement a zero-argument constructor.
\end{classdesc}


\begin{classdesc}{SAXException}{msg, exception, locator}
Encapsulate an XML error or warning. This class can contain
    basic error or warning information from either the XML parser or
    the application: you can subclass it to provide additional
    functionality, or to add localization. Note that although you will
    receive a \exception{SAXException} as the argument to the handlers in the
    \class{ErrorHandler} interface, you are not actually required to throw
    the exception; instead, you can simply read the information in
    it.
\end{classdesc}

\begin{classdesc}{SAXParseException}{msg, exception, locator}
Encapsulate an XML parse error or warning.
    
This exception will include information for locating the error in the
    original XML document. Note that although the application will
    receive a \exception{SAXParseException} as the argument to the
    handlers in the \class{ErrorHandler} interface, the application is not
    actually required to throw the exception; instead, it can simply
    read the information in it and take a different action.

Since this exception is a subclass of \exception{SAXException}, it inherits
    the ability to wrap another exception.
\end{classdesc}


\subsection{\class{AttributeList} methods}

The \class{AttributeList} class supports some of the behaviour of
Python dictionaries; the \method{len()}, \method{has_key()},
\method{keys()} methods are available, and \code{attr['href']} will
retrieve the value of the \attribute{href} attribute.  There are also
additional methods specific to \class{AttributeList}:

\begin{methoddesc}{getLength}{}
Return the number of attributes in the list.
\end{methoddesc}

\begin{methoddesc}{getName}{i}
Return the name of attribute \var{i} in the list.
\end{methoddesc}

\begin{methoddesc}{getType}{i}
Return the type of an attribute in the list. \var{i} can be
either the integer index or the attribute name.
\end{methoddesc}

\begin{methoddesc}{getValue}{i}
Return the value of an attribute in the list. \var{i} can be
either the integer index or the attribute name.
\end{methoddesc}

\subsection{\class{DocumentHandler} methods}

\begin{methoddesc}{characters}{ch, start, length}
Handle a character data event.
\end{methoddesc}

\begin{methoddesc}{endDocument}{}
Handle an event for the end of a document.
\end{methoddesc}

\begin{methoddesc}{endElement}{name}
Handle an event for the end of an element.
\end{methoddesc}

\begin{methoddesc}{ignorableWhitespace}{ch, start, length}
Handle an event for ignorable whitespace in element content.
\end{methoddesc}

\begin{methoddesc}{processingInstruction}{target, data}
Handle a processing instruction event.
\end{methoddesc}

\begin{methoddesc}{setDocumentLocator}{locator}
Receive 
an object for locating the origin of SAX document events.  You'll probably want to store the value of \var{locator} as an attribute of the handler instance.
\end{methoddesc}

\begin{methoddesc}{startDocument}{}
Handle an event for the beginning of a document.
\end{methoddesc}

\begin{methoddesc}{startElement}{name, attrs}
Handle an event for the beginning of an element.
\end{methoddesc}


\subsection{\class{DTDHandler} methods}

\begin{methoddesc}{notationDecl}{name, publicId, systemId}
Handle a notation declaration event.
\end{methoddesc}

\begin{methoddesc}{unparsedEntityDecl}{publicId, systemId, notationName}
Handle an unparsed entity declaration event.
\end{methoddesc}


\subsection{\class{EntityResolver} methods}

\begin{methoddesc}{resolveEntity}{name, publicId, systemId}
Resolve the system identifier of an entity.
\end{methoddesc}

\subsection{\class{ErrorHandler} methods}

\begin{methoddesc}{error}{exception}
Handle a recoverable error.
\end{methoddesc}

\begin{methoddesc}{fatalError}{exception}
Handle a non-recoverable error.
\end{methoddesc}

\begin{methoddesc}{warning}{exception}
Handle a warning.
\end{methoddesc}

\subsection{\class{Locator} methods}

\begin{methoddesc}{getColumnNumber}{}
Return the column number where the current event ends.
\end{methoddesc}

\begin{methoddesc}{getLineNumber}{}
Return the line number where the current event ends.
\end{methoddesc}

\begin{methoddesc}{getPublicId}{}
Return the public identifier for the current event.
\end{methoddesc}

\begin{methoddesc}{getSystemId}{}
Return the system identifier for the current event.
\end{methoddesc}

\subsection{\class{Parser} methods}

\begin{methoddesc}{parse}{systemId}
Parse an XML document from a system identifier.
\end{methoddesc}

\begin{methoddesc}{parseFile}{fileobj}
Parse an XML document from a file-like object.
\end{methoddesc}

\begin{methoddesc}{setDocumentHandler}{handler}
Register an object to receive basic document-related events.
\end{methoddesc}

\begin{methoddesc}{setDTDHandler}{handler}
Register an object to receive basic DTD-related events.
\end{methoddesc}

\begin{methoddesc}{setEntityResolver}{resolver}
Register an object to resolve external entities.
\end{methoddesc}

\begin{methoddesc}{setErrorHandler}{handler}
Register an object to receive error-message events.
\end{methoddesc}

\begin{methoddesc}{setLocale}{locale}
Allow an application to set the locale for errors and warnings. 
   
        SAX parsers are not required to provide localisation 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}

\subsection{\class{SAXException} methods}

\begin{methoddesc}{getException}{}
Return the embedded exception, if any.
\end{methoddesc}

\begin{methoddesc}{getMessage}{}
Return a message for this exception.
\end{methoddesc}

\subsection{\class{SAXParseException} methods}

The \class{SAXParseException} class has a \member{locator}
attribute, containing an instance of the \class{Locator} class, which
represents the location in the document where the parse error
occurred.  The following methods are delegated to this instance.

\begin{methoddesc}{getColumnNumber}{}
Return the column number of the end of the text where the exception
	occurred.
\end{methoddesc}

\begin{methoddesc}{getLineNumber}{}
Return the line number of the end of the text where the exception occurred.
\end{methoddesc}

\begin{methoddesc}{getPublicId}{}
Return the public identifier of the entity where the exception occurred.
\end{methoddesc}

\begin{methoddesc}{getSystemId}{}
Return the system identifier of the entity where the exception occurred.
\end{methoddesc}


\section{\module{xml.sax.saxutils}}

\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}{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 doule-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 &quot; ef">
\end{verbatim}

  This function is useful when generating attribute values for HTML or
  any SGML using the reference concrete syntax.
\end{funcdesc}

\begin{classdesc}{Canonizer}{writer}
A SAX document handler that produces canonicalized XML output.
\var{writer} must support a \method{write()} method which accepts a
single string.  
\end{classdesc}

\begin{classdesc}{ErrorPrinter}{}
A simple class that just prints error messages to standard error (\code{sys.stderr}).
\end{classdesc}

\begin{classdesc}{ESISDocHandler}{writer}
A SAX document handler that produces naive ESIS output.
\var{writer} must support a \method{write()} method which accepts a single string. 
\end{classdesc}

\begin{classdesc}{EventBroadcaster}{list}
Takes a list of objects and forwards any method calls received
    to all objects in the list. The attribute \member{list} holds the list and
    can freely be modified by clients.
\end{classdesc}

\begin{classdesc}{Location}{locator}
Represents a location in an XML entity. Initialized by being passed
a locator, from which it reads off the current location, which is then
stored internally.
\end{classdesc}

\subsection{\class{Location} methods}

\begin{methoddesc}{getColumnNumber}{}
Return the column number of the location.
\end{methoddesc}

\begin{methoddesc}{getLineNumber}{}
Return the line number of the location.
\end{methoddesc}

\begin{methoddesc}{getPublicId}{}
Return the public identifier for the location.
\end{methoddesc}

\begin{methoddesc}{getSystemId}{}
Return the system identifier for the location.
\end{methoddesc}

\section{\module{xml.utils.iso8601}
         %--- Utilities for handling ISO~8601 dates
         }

\declaremodule{}{xml.utils.iso8601}
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}


The \module{xml.utils.iso8601} module provides conversion routines
between the ISO~8601 representations of date/time values and the
floating point values used elsewhere in Python.  The floating point
represtentation is particularly useful in conjunction with the
standard \module{time} module.

Currently, this module supports a small superset of the ISO~8601
profile described by the World Wide Web Consortium (W3C).  This is a
subset of ISO~8601, but covers the cases expected to be used most
often in the context of XML processing and Web applications.  Future
versions of this module may support a larger subset of
ISO~8601-defined formats.


\begin{funcdesc}{parse}{s}
Parse an ISO~8601 date representation (with an optional time-of-day
component) and return the date in seconds since the epoch.
\end{funcdesc}


\begin{funcdesc}{parse_timezone}{timezone}
Parse an ISO~8601 time zone designator and return the offset relative
to Universal Coordinated Time (UTC) in seconds.  If \var{timezone} is
not valid, \exception{ValueError} is raised.
\end{funcdesc}


\begin{funcdesc}{tostring}{t\optional{, timezone}}
Return formatted date/time value according to the profile described by 
the W3C.  If \var{timezone} is provided, it must be the offset from
UTC in seconds specified as a number, or time zone designator which
can be parsed by \function{parse_timezone()}.  If \var{timezone} is
specified as a string and cannot be parsed by
\function{parse_timezone()}, \exception{ValueError} will be raised.
\end{funcdesc}


\begin{funcdesc}{ctime}{t}
Return formatter date/time value using the local timezone.  This is
equivalent to \samp{tostring(\var{t}, time.timezone)}.
\end{funcdesc}


\begin{seealso}
\seetext{International Organization for Standardization.  \emph{Data
elements and interchange formats --- Information interchange ---
Representation of dates and times.}  International Organization for
Standardization, 1988.}

\seetext{Gary Houston.  \emph{ISO~8601 date/time representations}.
January 1993.  Available online as compressed PostScript:
\url{ftp://ftp.informatik.uni-erlangen.de/pub/doc/ISO/ISO8601.ps.Z}.}

\seetext{Markus Kuhn.  \emph{A Summary of the International Standard
Dateand Time Notation}.  Available online at
\url{http://www.cl.cam.ac.uk/~mgk25/iso-time.html}.}

\seetext{Misha Wolf and Charles Wicksteed.  \emph{Date and Time
Formats}.  World Wide Web Consortium Technical Note, September 1998.
Available online at \url{http://www.w3.org/TR/NOTE-datetime}.}
\end{seealso}


\end{document}
