% Questions: % Should xmllib.py be moved into xml.parsers? % 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.8} \author{The Python/XML Special Interest Group} \authoraddress{\email{xml-sig@python.org}\break (edited by \email{amk@amk.ca})} \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. \end{abstract} \tableofcontents \section{\module{xml.dom} Extensions} \declaremodule{}{xml.dom} \modulesynopsis{Common aspects of the DOM interface.} \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} \begin{notice} The material in this section describes features of the \module{xml.dom} module that does not appear in the version of the module included with Python. This is written as a supplement to the \ulink{corresponding section}{http://www.python.org/doc/2.2.1/lib/module-xml.dom.html} in the Python 2.2.1 documentation. We intend that all or most of these additions be added to the Python standard library in a future release. \end{notice} Starting with PyXML 0.8, some features of the DOM Level~3 working drafts are being added. These features are based on working drafts and will be changed as the drafts are updated. Use at your own risk. \begin{excdesc}{ValidationErr} New exception. The validation features of the Level~3 DOM can raise this exception when validation constraints are not met. The rest of the validation features have not been implemented, but any Python DOM implementation would use the same exception, so it is offered at this point. \end{excdesc} % Written this way so I can copy the table line into the docs when % this gets integrated. The additional exception code defined in the Level~3 DOM specification map to the exception described above: \begin{tableii}{l|l}{constant}{Constant}{Exception} \lineii{VALIDATION_ERR}{\exception{ValidationErr}} \end{tableii} The \class{Node} class has grown a number of additional constants useful for some of the new methods added in DOM Level~3. These constants are: \constant{TREE_POSITION_PRECEDING}, \constant{TREE_POSITION_FOLLOWING}, \constant{TREE_POSITION_ANCESTOR}, \constant{TREE_POSITION_DESCENDENT}, \constant{TREE_POSITION_EQUIVALENT}, \constant{TREE_POSITION_SAME_NODE}, \constant{TREE_POSITION_DISCONNECTED}. Additional classes have been added to provide access to constants and serve as base classes for implementations: \begin{classdesc*}{UserDataHandler} The DOM Level~3 Core adds a method \method{setUserData()} which accepts an instance conforming to the \class{UserDataHandler} interface. This class provides the constants used as arguments to the \method{handle()} of that interface. The constants provided are \constant{NODE_CLONED}, \constant{NODE_IMPORTED}, \constant{NODE_DELETED}, and \constant{NODE_RENAMED}. Implementation classes may choose to subclass from this class, but there is no reason for them to do so. \end{classdesc*} \begin{classdesc*}{DOMError} The DOM Level~3 Core feature adds support for a user-settable error handler. This class provides the constants used to indicate the severity of an error, and may be used as a base class by DOM implementations. These constants should be used to test the value of the \member{severity} member of instances of this interface. The constants provided are \constant{SEVERITY_WARNING}, \constant{SEVERITY_ERROR}, and \constant{SEVERITY_FATA_ERROR}. \end{classdesc*} The \function{getDOMImplementation()} function has been extended to support DOM Level~3: \begin{funcdesc}{getDOMImplementation}{\optional{name\optional{, features}}} The \var{features} argument now accepts a string as well as a list of feature-version pairs. The string should contain a list of feature names, separated by whitespace, each followed by an optional version number. Version numbers begin with a digit; feature names must not begin with a digit (the draft specification does not adequately address this detail). If a feature name is not followed by a version number, any version of that feature is considered acceptable. \begin{notice} There is an API issue hiding in this addition: The function is still not really compatible with the DOM Level~3 version. The draft specification states that if no implementation is available that provides the desired features, \code{None} should be returned, but this function raises \exception{ImportError}. \end{notice} \end{funcdesc} \subsection{UserDataHandler Objects \label{userdatahandler}} The \class{UserDataHandler} interface, introduced in the DOM Level~3 Core (draft) specification, is used to allow DOM clients to manage node-specific application data stored using the \method{setUserData()} method on nodes. \class{UserDataHandler} implementations need only define one method: \begin{methoddesc}[UserDataHandler]{handle}{operation, key, data, src, dest} This method is called for a few particular events in the lifespan the node on which it was registered. For each type of event, \var{operation} indicates the specific operation being performed on the node, \var{key} gives the key for which \var{data} and the handler object were registered, \var{data} is the actual data object, and \var{src} is the node on which the handler was registered. The \var{dest} argument will always be either \code{None} or a different node, depending on the specific operation. If \var{operation} is \constant{NODE_CLONED}, then \var{dest} is the clone of \var{src}; \var{src} and \var{dest} will always belong to the same document unless \var{src} is a \constant{DOCUMENT_TYPE_NODE}. It \var{operation} is \constant{NODE_IMPORTED}, then \var{dest} is the imported version of \var{src}, and belongs to a different document. If \var{operation} is \constant{NODE_RENAMED}, then \var{src} and \var{dest} are intended to represent the same node, but different node objects are used. This is \emph{not} called when \method{Document.renameNode()} does not create a new node instance. If \var{operation} is \constant{NODE_DELETED}, then \var{src} is about to be deleted (not just removed from the document tree), and \var{dest} is \code{None}. It is not expected that Python implementations of the DOM will implement this, since doing so properly may interfere with the reclamation of unused nodes. The constants passed as the values for the \var{operation} argument of this method are available from the \class{xml.dom.UserDataHandler} class. \end{methoddesc} \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{\module{xml.dom.minidom} Extensions} The implementation of \module{xml.dom.minidom} in PyXML contains support for more of the DOM Level~2 Core specification than the version packaged in Python, and incorporates partial support for the draft DOM Level~3 Core and Load/Save specifications. This additional support includes the interfaces documented for the \refmodule{xml.dom.xmlbuilder} module. This section describes the major extensions beyond what's documented for this module in the \citetitle [http://www.python.org/doc/2.2.1/lib/module-xml.dom.minidom.html] {Python Library Reference} for Python 2.2.1. The \class{Entity} and \class{Notation} node types are now supported, and the \class{TypeInfo} interface is also supported. These additional \class{Node} attributes have been implemented or changed: \begin{methoddesc}[Node]{toxml}{\optional{encoding}} The optional \var{encoding} argument has been added to the \method{toxml()} method. When specified and not \code{None}, the output document uses the given encoding. \versionchanged[the \var{encoding} argument was added]{0.8} \end{methoddesc} \begin{methoddesc}[Node]{isSupported}{feature, version} This is equivalent to calling \code{hasFeature(\var{feature}, \var{version})} on the corresponding \class{DOMImplementation} object. Added in DOM Level~2 Core. \end{methoddesc} \begin{methoddesc}[Node]{getInterface}{feature} Return the interface object for the current node that supports the \var{feature} feature if \code{isSupported(\var{feature}, None)} returns true, otherwise returns \code{None}. It is not expected that Python DOM implementations will normally need this, but a DOM implementation that adds substantial new functionality may want to require the use of this method to provide access to a helper object that implements extension-specific methods. Added in DOM Level~3. \end{methoddesc} \begin{methoddesc}[Node]{getUserData}{key} Retrieve the data registered with the node for the key \var{key} using \method{setUserData()}. Returns \code{None} if no data was registered for \var{key}. Added in DOM Level~3. \end{methoddesc} \begin{methoddesc}[Node]{setUserData}{key, data, handler} Set the object \var{data} to be associated with a key \var{key} on the current node. \var{key} can be any hashable object, and will be used as a dictionary key. Any previous value registered for the same value of \var{key} will be discarded. The \var{handler} argument should be \code{None} or an implementation of the \class{UserDataHandler} interface. Added in DOM Level~3. \end{methoddesc} These additional \class{Text} attributes have been added based on the Level~3 drafts. These are also available on \class{CDATASection} nodes. \begin{memberdesc}[Text]{isWhitespaceInElementContent} \code{True} if the text node represents only whitespace and the immediately containing element has a content model that permits only elements as child nodes. If the content model for the containing element is not known, or if there is no containing element, this attribute will be \code{False}. \end{memberdesc} \begin{memberdesc}[Text]{wholeText} Returns the textual content for a contiguous range of nodes of type \constant{TEXT_NODE} and \constant{CDATA_SECTION_NODE} nodes containing the current node. \end{memberdesc} \begin{methoddesc}[Text]{replaceWholeText}{content} Replace a contiguous range of nodes of type \constant{TEXT_NODE} and \constant{CDATA_SECTION_NODE} nodes containing the current node, with a single node containing the text \var{content}. Returns the node containing \var{content}. If \var{content} is an empty string, removes the entire range of affected nodes and returns \code{None}. \end{methoddesc} These methods and attributes have been added to the \class{Document} interface: \begin{memberdesc}[Document]{actualEncoding} The encoding used by the parser, if it was overridden by source context (such as HTTP headers) rather than determined based on the bytes of the source document. If only the source document was used to determine the encoding, this is \code{None} Added in DOM Level~3. \end{memberdesc} \begin{memberdesc}[Document]{encoding} The encoding specified in the XML declaration, or \code{None} if the declaration or \attribute{encoding} pseudo-attribute were omitted. Added in DOM Level~3. \end{memberdesc} \begin{memberdesc}[Document]{standalone} If the \attribute{standalone} pseudo-attribute was given in the document's XML declaration, this will be \code{True} if the value was \samp{yes} or \code{False} if the value was \samp{no}. If the XML declaration or \attribute{standalone} pseudo-attribute were omitted, this will be \code{None}. Added in DOM Level~3. \end{memberdesc} \begin{memberdesc}[Document]{version} The value of the \attribute{version} pseudo-attribute from the XML declaration, if present, or \code{None}. Added in DOM Level~3. \end{memberdesc} \begin{methoddesc}[Document]{importNode}{node, deep} Imports a node \var{node} from another document. If \var{deep} is true, child nodes are recursively imported. Nodes of type \constant{DOCUMENT_NODE} and \constant{DOCUMENT_TYPE_NODE} cannot be imported; if \var{node} has one of these values for its \member{nodeType} attribute, \exception{xml.dom.NotSupportedErr} will be raised. Added in DOM Level~2. \end{methoddesc} \begin{methoddesc}[Document]{renameNode}{node, namespaceURI, name} Added in DOM Level~3. \end{methoddesc} The following have been added to the \class{Attr} class: \begin{memberdesc}[Attr]{isId} \code{True} if the attribute represents an ID while attached to it's current \member{ownerElement}, otherwise \code{False}. Added in DOM Level~3. \end{memberdesc} \begin{memberdesc}[Attr]{schemaType} The \class{TypeInfo} object representing the type of this attribute, taking into account the type of the element to which is it attached. Added in DOM Level~3. \end{memberdesc} The following attributes have been added to the \class{Element} class: \begin{memberdesc}[Element]{schemaType} The \class{TypeInfo} object representing the type of this element, taking into account the type of the element to which is it attached. Added in DOM Level~3. \end{memberdesc} \begin{methoddesc}[Element]{setIdAttribute}{name} \methodline{setIdAttributeNS}{namespaceURI, localName} \methodline{setIdAttributeNode}{idAttr} Set the specified attribute of the element to be an ID, even if the schema information does not cause it to be an ID. Existing IDs remain valid. The \member{schemaType} value is not changed. Added in DOM Level~3. \end{methoddesc} \class{TypeInfo} objects have the following attributes: \begin{memberdesc}[TypeInfo]{name} Name of the type. Type names are only meaningful within the context of a namespace defining type names. DTD-based types have no name, so this will be \code{None} for types from DTDs. \end{memberdesc} \begin{memberdesc}[TypeInfo]{namespace} Namespace URI for a type system. This will be \code{None} for DTD-based types. \end{memberdesc} \strong{Implementation specific behavior:} The DOM Level~2 Core specification leaves some room for differing behaviors for how some node types are handled by the \method{Node.cloneNode()} method. Before PyXML 0.8.1, the specific behavior exhibited by PyXML varied as an accident of implementation. Starting with PyXML 0.8.1, the following behavior is considered intentional and will be maintained. When called on a \class{Document} node, \method{cloneNode()} with the \var{deep} argument set to true will create a new document with the children recursively imported into the new document. When \var{deep} is false, \method{cloneNode()} will return \code{None}, as the operation is no reasonable meaning for the operation. When called on a \class{DocumentType} node, \method{cloneNode()} will return \code{None} if it is owned by a document. If it is not owned, a new document type node is created with all of the attributes copied over, except for the \member{entities} and \member{notations} fields. If \var{deep} is true, these will be new \class{NamedNodeMap} objects which hold clones of the \class{Entity} and \class{Notation} nodes, as appropriate. If \var{deep} is false, these will be initialized to new, empty \class{NamedNodeMap} objects. \section{\module{xml.dom.xmlbuilder} --- DOM Level~3 Load/Save Interface} \declaremodule{}{xml.dom.xmlbuilder} \modulesynopsis{DOM Level~3 Load/Save interface.} \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} \versionadded{0.8} \begin{notice}[warning] The \module{xml.dom.xmlbuilder} represents the DOM Level~3 Load/Save interface, which is only defined in a W3C working draft at this time. The Python API presented here is modelled on the 25 July 2002 version of the working draft, and is expected to change as new drafts are released. Backward compatibility to support older versions of this interface will not be preserved. \end{notice} This module provides API support for the DOM Level~3 Load/Save specification. It includes an implementation of the loading components of that specification only at this time. Tow groups of classes are provided. The first group implements the objects specific to the Load/Save specification, and the second provides a group of mixin classes that can be used by a DOM implementation to make use of the first group of classes. Implementation classes: \class{DOMInputSource} \class{DOMEntityResolver} \class{DOMBuilder} \class{DOMBuilderFilter} Mixin classes: \begin{classdesc*}{DOMImplementationLS} Class that can be mixed into an implementation of the \class{DOMImplementation} interface. This implementation provides the \constant{MODE_SYNCHRONOUS} and \constant{MODE_ASYNCHRONOUS} constants and the \method{createDOMBuilder()}, \method{createDOMWriter()}, and \method{createDOMInputSource()} methods. Most DOM implementations should be able to re-use the \method{createDOMInputSource()} method, and will need to override the \method{createDOMBuilder()} method if it will actually be using a different DOM builder. The \method{createDOMWriter()} method should be usable for all implementations once the \class{DOMWriter} has been implemented, but that has not yet been done in PyXML. \end{classdesc*} \begin{classdesc*}{DocumentLS} Class that can be mixed in to a \class{Document} implementation to provide access to features of the Load/Save interface. There isn't much that can be provided by this implementation, so most methods raise \exception{NotSupportedErr}. \end{classdesc*} \subsection{DOMImplementationLS Extensions} The \class{DOMImplementationLS} mixin class is designed to be used in an implementation of the \class{DOMImplementation} interface. This class provides the constants \constant{MODE_SYNCHRONOUS} and \constant{MODE_ASYNCHRONOUS}, and the following methods: \begin{methoddesc}[DOMImplementationLS]{createDOMBuilder}{mode, schemaType} Returns a \class{DOMBuilder} instance. Specific DOM implementations will usually need to override this to return a specialized subclass of the \class{DOMBuilder} class; see the documentation on the \class{DOMBuilder} for information on how and when to write a subclass of that. \end{methoddesc} \begin{methoddesc}[DOMImplementationLS]{createDOMWriter}{} For now, raises \exception{NotImplementedError} since the writer interface has not been implemented yet. \end{methoddesc} \begin{methoddesc}[DOMImplementationLS]{createDOMInputSource}{} Returns a \class{DOMInputSource} instance with all attributes set to \code{None}. \end{methoddesc} \subsection{DocumentLS Extensions} The \class{DocumentLS} mixin class for a \class{Document} adds the following methods: \begin{methoddesc}[DocumentLS]{load}{uri} Load a new document from a URI into this DOM \class{Document} instance. This is not yet implemented in PyXML. \end{methoddesc} \begin{methoddesc}[DocumentLS]{loadXML}{source} Load a new document from a \class{DOMInputSource} into this DOM \class{Document} instance. This is not yet implemented in PyXML. \end{methoddesc} \begin{methoddesc}[DocumentLS]{saveXML}{snode} Return an XML serialization of the DOM node \var{snode} as a string. \var{snode} must belong to this document; if not, \exception{xml.dom.WrongDocumentErr} will be raised. \end{methoddesc} The following attribute is also added: \begin{memberdesc}[DocumentLS]{async} If set to a true value, the \method{load()} and \method{loadXML()} methods should load documents asynchronously. If false, these methods will operate in a synchronous mode. PyXML does not support setting this to true. \end{memberdesc} \subsection{DOMBuilder Objects} The \class{DOMBuilder} class provides support for configuring the DOM construction process, and allows alternate DOM construction methods to be provided by subclasses. The general public API has two aspects, configuration and \class{Document} creation. The configuration aspect provides the following attributes and methods: \begin{methoddesc}[DOMBuilder]{canSetFeature}{name, state} Return true if the feature \var{name} can be set to \var{state}, otherwise returns false. If feature \var{name} is not supported, returns false. \end{methoddesc} \begin{methoddesc}[DOMBuilder]{getFeature}{name} Returns the state for the feature \var{name}. If \var{name} is unrecognized or not supported, \exception{xml.dom.NotFoundErr} is raised. \end{methoddesc} \begin{methoddesc}[DOMBuilder]{setFeature}{name, state} Set the feature \var{name} to \var{state}. If feature \var{name} is not recognized, \exception{xml.dom.NotFoundErr} is raised; if the specific state requested is not supported, \exception{xml.dom.NotSupportedErr} is raised. \end{methoddesc} \begin{methoddesc}[DOMBuilder]{supportsFeature}{name} Returns true if the feature \var{name} is supported at all, otherwise returns false. A true return does not imply that any particular value for the feature is supported. \end{methoddesc} The \class{Document}-creation aspect of the public API is provided by these methods: \begin{methoddesc}[DOMBuilder]{parse}{input} Returns a document based on the \class{DOMInputSource} given as \var{input}. \end{methoddesc} \begin{methoddesc}[DOMBuilder]{parseURI}{uri} Returns a document from the URI given by \var{uri}. \end{methoddesc} \begin{methoddesc}[DOMBuilder]{parseWithContext}{input, cnode, action} \note{Not implemented in the current version.} Legal values for \var{action} are given by the constants \constant{ACTION_REPLACE}, \constant{ACTION_APPEND_AS_CHILDREN}, \constant{ACTION_INSERT_AFTER}, and \constant{ACTION_INSERT_BEFORE}, all defined on the \class{DOMBuilder} class. \end{methoddesc} Subclasses are expected to define the following method to determine how the \class{Document} instances returned by the \method{parse()} method will be created. \begin{notice}[warning] The interface for subclasses is \emph{very} preliminary, and should be considered likely to change in future releases. \end{notice} \begin{methoddesc}[DOMBuilder]{_parse_bytestream}{stream, options} Returns a \class{Document} instance parsed from the file object given as \var{stream} using the configuration options in the \var{options} object. The default implementation uses \module{xml.parsers.expat} to construct documents using the \module{xml.dom.minidom} DOM implementation. \end{methoddesc} \subsection{Subclassing \class{DOMBuilder}} There are two important aspects to subclassing the \class{DOMBuilder}: implementing a useful subclass and getting a \class{DOMImplementation} that uses it. The first aspect is faily easy; to create a \class{DOMBuilder} that uses a different parser, use a subclass that overrides the \method{_parse_bytestream()} method, documented above. The implementation of a specialized DOM builder may not be trivial, but the integration with the provided \class{DOMBuilder} class will be reasonably direct. The second aspect, creating a DOM implementation that uses the new \class{DOMBuilder} implementation, is a little more tedious, but not excessively so. The \class{DOMImplementationLS} mixin class can be used, and the \method{createDOMBuilder()} method overridden to use the new \class{DOMBuilder} implementation. This makes less sense if you want to re-use most of an existing DOM implementation, however. To use a new \class{DOMBuilder} with existing DOM implementation code, such as \module{xml.dom.minidom}, the easiest approach is to subclass an existing \class{DOMImplementation} class. For \module{xml.dom.minidom}, this could be done this way: \begin{verbatim} import xml.dom from xml.dom.minidom import DOMImplementation from xml.dom.xmlbuilder import DOMBuilder class MyDOMBuilder(DOMBuilder): def __init__(self, implementation): self._implementation = implementation def _parse_bytestream(self, stream, options): raise xml.dom.NotSupportedErr( "I'm just an example; don't expect much.") class MyDOMImplementation(DOMImplementation): def createDOMBuilder(self, mode, schemaType): # check for the supported mode and schemaType if schemaType is not None: raise xml.dom.NotSupportedErr( "unsupported schema type: %s" % schemaType) if mode != DOMImplementation.MODE_SYNCHRONOUS: raise xml.dom.NotSupportedErr( "asynchronous loading not supported") return MyDOMBuilder(self) # minidom just stores the implementation on the class instance, # so we need to do the same to override that attribute on instances. # MyDOMImplementation.implementation = MyDOMImplementation() \end{verbatim} %\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 Namespaces} \declaremodule{}{xml.ns} \modulesynopsis{Constants giving the URIs for common namespaces, plus convenience classes.} \moduleauthor{Rich Salz}{rsalz@zolera.com} \sectionauthor{Rich Salz}{rsalz@zolera.com} \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} This module contains two groups of things: constants for common namespace URIs, and convenience classes representing namespaces and their local names. The URI definitions for namespaces (and sometimes other URI's) used by a variety of XML standards are provided as objects for each specification (or group of tightly related specifications) with attributes for each URI. Each object 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 name of the object. Attributes on that object 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} Namespaces defined for the W3C XML Schema specification. \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*} \begin{classdesc*}{DCMI} The Dublin Core Metadata Initiative (DCMI) defines a commonly-used set of general metadata elements. There is a base set of elements, a variety of refinements of those, a set of value encodings, and a \emph{type vocabulary} used to describe what something described in metadata actually is (for example, a text, a physical object, a collection). Documentation on the Dublin Core, including recommendations for encoding Dublin Core metadata in XML and HTML/XHTML can be found at the \ulink{DCMI website}{http://dublincore.org/}. \begin{memberdesc}{BASE} Prefix for all DCMI-defined namespaces. This is not normally used directly, as it does not correspond to a specific namespace. \end{memberdesc} \begin{memberdesc}{DCMES} \memberline{DCMES_1_1} Namespace for the core element set, as defined in \citetitle[http://dublincore.org/documents/dces/]{Dublin Core Metadata Element Set, Version 1.1: Reference Description}. \end{memberdesc} \begin{memberdesc}{TERMS} Namespace for the refinements and non-core metadata elements defined in \citetitle[http://dublincore.org/documents/dcmi-terms/]{DCMI Metadata Terms} sections 3 (``Other Elements and Element Refinements'') and 4 (``Encoding Schemes''). \end{memberdesc} \begin{memberdesc}{TYPE} Namespace for the types of objects described in metadata, using the controlled vocabulary defined in the \citetitle[http://dublincore.org/documents/dcmi-type-vocabulary/] {DCMI Type Vocabulary}. \end{memberdesc} \end{classdesc*} The convenience classes used to represent namespaces and their local names are completely separate from the objects used to represent groups of URI definitions. Instances of these classes are ``namespace objects.'' Namespace objects are a convenient way to 'spell' \code{(\var{uri}, \var{localName})} pairs in application code. A namespace object would be created to represent a namespace (URI), and attributes of the namespace object would represent the \code{(\var{uri}, \var{localName})} pairs. For example, a namespace object would be created by providing the URI are any known local names for that namespace to the constructor: \begin{verbatim} xbel = xml.ns.ClosedNamespace( 'http://www.python.org/topics/xml/xbel/', ['xbel', 'title', 'info', 'metadata', 'folder', 'bookmark', 'desc', 'separator', 'alias']) \end{verbatim} Specific \code{(\var{uri}, \var{localName})} pairs can then be referenced by convenient names: \begin{verbatim} xbel.title # ==> ('http://www.python.org/topics/xml/xbel/', 'title') \end{verbatim} This can be convenient in (for example) SAX ContentHandler implementations. There are two specific classes used to create namespace objects: \begin{classdesc}{ClosedNamespace}{uri, names} Namespace that doesn't allow names to be added after instantiation. \var{uri} is the URI of the namespace, and \var{names} is a sequence of local names. A ``closed'' namespace is useful when the set of names for the namespace is known in advance; using a \class{ClosedNamespace} doesn't allow names to be added inadvertently. \end{classdesc} \begin{classdesc}{OpenNamespace}{uri\optional{, names}} Namespace that allows names to be added automatically. The constructor arguments are the same as for \class{ClosedNamespace}, but \var{names} becomes optional, defaulting to an empty sequence. When attributes of these objects are referenced, \code{(\var{uri}, \var{localName})} pairs are generated for the name if they don't already exist. For example, using \class{OpenNamespace} instead of \class{ClosedNamespace} in the earlier example would allow additional names to be used in addition to known names: \begin{verbatim} xbel = xml.ns.OpenNamespace( 'http://www.python.org/topics/xml/xbel/', ['xbel', 'title', 'info', 'metadata', 'folder', 'bookmark', 'desc', 'separator', 'alias']) xbel.splat # ==> ('http://www.python.org/topics/xml/xbel/', 'splat') \end{verbatim} \end{classdesc} \section{\module{xml.parsers.expat} Extensions} The version of the \module{xml.parsers.expat} module currently shipped with PyXML extends that provided by the standard Python library by exposing features of recent versions of the C implementation of the underlying Expat parser. These extensions are described here; the base documentation for this module is that published as part of the \citetitle [http://www.python.org/doc/2.2.1/lib/module-xml.parsers.expat.html] {Python Library Reference}. The module provides a new data attribute: \begin{datadesc}{features} A list of \var{name}-\var{value} pairs giving some information about the compilation of Expat being used. This is generated directly from the feature information provided by Expat's \cfunction{XML_GetFeatureList()} function. It is unlikely to be of interest to most applications. This was added in PyXML 0.8.1 to support Expat 1.95.5 and newer. \end{datadesc} The parser provides a new method: \begin{methoddesc}[xmlparser]{UseForeignDTD}{\optional{flag}} Tells Expat whether is should attempt to load an application-provided external subset if one is not specified by the document type declaration. If \var{flag} is true or omitted, Expat will attempt to load an external subset by calling the \member{ExternalEntityRefHandler} callback with \var{systemId} and \var{publicId} both set to \code{None}; this is done \emph{only} if the document does not specify a external subset. If \var{flag} is false (or this method is never called), Expat will not attempt such a load. This method should only be called before parsing has actually started; \exception{ExpatError} will be raised if this is called after parsing has begun. This was added in PyXML 0.8.1 to support Expat 1.95.5 and newer. \end{methoddesc} and one new attribute: \begin{memberdesc}[xmlparser]{namespace_prefixes} Set to true on a parser with namespaces enabled to request that the actual prefix is reported as well as the namespace URI for each namespace-qualified name. This modifies the element or attribute names passed to the \member{StartElementHandler} and \member{EndElementHandler} callbacks, if true. If set to a true value, the names passed to these callbacks will have the prefix added to the end, separated from the local name by the value of the \var{namespace_separator} passed to the parser constructor. No additional information will be added if the name uses the default namespace. This should only be called before parsing has begun. This was added in PyXML 0.8 to support Expat 1.95.4 and newer. \end{memberdesc} One new callback method has been added as well: \begin{methoddesc}[xmlparser]{SkippedEntityHandler}{name, is_param_entity} This is called when an external entity is not read, and gives information about the entity. The entity name will have been previously reported by the \member{EntityDeclHandler}, if set. This was added in PyXML 0.8 to support Expat 1.95.4 and newer. \end{methoddesc} \begin{seealso} \seetitle[http://www.libexpat.org/]{Expat Home Page}{ The home page for the Expat project provides information about new versions of the library and user resources such as 3rd-party language bindings and mailing lists.} \end{seealso} \section{\module{xml.parsers.sgmllib} --- Accelerated SGML Parser} \declaremodule{}{xml.parsers.sgmllib} \moduleauthor{Fredrik Lundh}{effbot@effbot.org} This module is an alternate implementation of the \ulink{\module{sgmllib} module}{http://www.python.org/doc/current/lib/module-sgmllib.html} from the Python standard library. This implementation uses the \refmodule{xml.parsers.sgmlop} accelerator to improve performance. This module does create a cyclic reference. In order to break the cycle, be sure to call the \method{close()} method of the parser instances when done with them. \section{\module{xml.parsers.sgmlop} --- XML/SGML Parser Accelerator} \declaremodule{}{xml.parsers.sgmlop} \moduleauthor{Fredrik Lundh}{effbot@effbot.org} The \module{xml.parsers.sgmlop} module is a C implementation of a parser similar in interface to the \class{xmllib.XMLParser} and \class{sgmllib.SGMLParser} classes from the \ulink{Python standard library}{http://www.python.org/doc/current/lib/lib.html}. Additional support is provided for a basic tree-constructor which is intended to be used in conjunction with the parsers implemented by this 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 \function{len()} function and \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 "" % quoteattr("ab ' cd \" 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} \seetitle{Data elements and interchange formats --- Information interchange --- Representation of dates and times.}{The actual ISO~8601 standard published by the International Organization for Standardization, 1988.} \seetitle[ftp://ftp.informatik.uni-erlangen.de/pub/doc/ISO/ISO8601.ps.Z] {ISO~8601 date/time representations}{Gary Houston's description of the ISO~8601 formats for humans, written in January 1993.} \seetitle[http://www.cl.cam.ac.uk/~mgk25/iso-time.html]{A Summary of the International Standard Date and Time Notation}{Markus Kuhn's excellent discussion of international date/time representations.} \seetitle[http://www.w3.org/TR/NOTE-datetime]{Date and Time Formats} {World Wide Web Consortium Technical Note from September 1998, written by Misha Wolf and Charles Wicksteed.} \end{seealso} \end{document}