Python/XML Reference Guide _________________________________________________________________ The Python/XML Special Interest Group xml-sig@python.org (edited by akuchling@acm.org) Abstract: 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. Contents * 1 xml.dom Extensions + 1.1 UserDataHandler Objects * 2 xml.dom.ext.c14n -- Canonical XML generation * 3 xml.dom.minidom Extensions * 4 xml.dom.xmlbuilder -- DOM Level 3 Load/Save Interface + 4.1 DOMImplementationLS Extensions + 4.2 DocumentLS Extensions + 4.3 DOMBuilder Objects + 4.4 Subclassing DOMBuilder * 5 xml.ns -- XML Namespace constants * 6 xml.parsers.expat Extensions * 7 xml.parsers.sgmllib -- Accelerated SGML Parser * 8 xml.parsers.sgmlop -- XML/SGML Parser Accelerator * 9 xml.sax.saxexts + 9.1 ExtendedParser methods + 9.2 ParserFactory methods * 10 xml.sax.saxlib + 10.1 AttributeList methods + 10.2 DocumentHandler methods + 10.3 DTDHandler methods + 10.4 EntityResolver methods + 10.5 ErrorHandler methods + 10.6 Locator methods + 10.7 Parser methods + 10.8 SAXException methods + 10.9 SAXParseException methods * 11 xml.sax.saxutils + 11.1 Location methods * 12 xml.utils.iso8601 * About this document ... 1 xml.dom Extensions Note: The material in this section describes features of the xml.dom module that does not appear in the version of the module included with Python. This is written as a supplement to the corresponding section 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. 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. exception 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. The additional exception code defined in the Level 3 DOM specification map to the exception described above: Constant Exception VALIDATION_ERR ValidationErr The Node class has grown a number of additional constants useful for some of the new methods added in DOM Level 3. These constants are: TREE_POSITION_PRECEDING, TREE_POSITION_FOLLOWING, TREE_POSITION_ANCESTOR, TREE_POSITION_DESCENDENT, TREE_POSITION_EQUIVALENT, TREE_POSITION_SAME_NODE, TREE_POSITION_DISCONNECTED. Additional classes have been added to provide access to constants and serve as base classes for implementations: class UserDataHandler The DOM Level 3 Core adds a method setUserData() which accepts an instance conforming to the UserDataHandler interface. This class provides the constants used as arguments to the handle() of that interface. The constants provided are NODE_CLONED, NODE_IMPORTED, NODE_DELETED, and NODE_RENAMED. Implementation classes may choose to subclass from this class, but there is no reason for them to do so. class 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 severity member of instances of this interface. The constants provided are SEVERITY_WARNING, SEVERITY_ERROR, and SEVERITY_FATA_ERROR. 1.1 UserDataHandler Objects The 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 setUserData() method on nodes. UserDataHandler implementations need only define one method: 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, operation indicates the specific operation being performed on the node, key gives the key for which data and the handler object were registered, data is the actual data object, and src is the node on which the handler was registered. The dest argument will always be either None or a different node, depending on the specific operation. If operation is NODE_CLONED, then dest is the clone of src; src and dest will always belong to the same document unless src is a DOCUMENT_TYPE_NODE. It operation is NODE_IMPORTED, then dest is the imported version of src, and belongs to a different document. If operation is NODE_RENAMED, then src and dest are intended to represent the same node, but different node objects are used. This is not called when Document.renameNode() does not create a new node instance. If operation is NODE_DELETED, then src is about to be deleted (not just removed from the document tree), and dest is 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 operation argument of this method are available from the xml.dom.UserDataHandler class. 2 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 http://www.w3.org/TR/xml-c14n. (Unlike the specification, however, general document subsets are not supported.) The module name, c14n, comes from the standard way of abbreviating the word "canonicalization." This module is typically imported by doing from xml.dom.ext import Canonicalize. Canonicalize( node[output[**keywords]]) This function generates the canonical format. If output is specified, the data is sent by invoking its write method, the the function will return None. If output is omitted or has the value None, then the Canonicalize will return the data as a string. The keyword argument comments, if non-zero, directs the function to leave any comment nodes in the output. By default, they are removed. The keyword argument 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 nsdict may be used to provide a namespace dictionary that is assumed to be in the node's containing context. The keys are namespace prefixes, and the values are the namespace URI's. If nsdict is None or an empty dictionary, then an initial dictionary containing just the URI's for the xml and xmlns prefixes will be used. 3 xml.dom.minidom Extensions The implementation of 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 xml.dom.xmlbuilder module. This section describes the major extensions beyond what's documented for this module in the Python Library Reference for Python 2.2.1. The Entity and Notation node types are now supported. These additional Node attributes have been implemented or changed: toxml( [encoding]) The optional encoding argument has been added to the toxml() method. When specified and not None, the output document uses the given encoding. Changed in version 0.8: the encoding argument was added. isSupported( feature, version) This is equivalent to calling hasFeature(feature, version) on the corresponding DOMImplementation object. Added in DOM Level 2 Core. getInterface( feature) Return the interface object for the current node that supports the feature feature if isSupported(feature, None) returns true, otherwise returns 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. getUserData( key) Retrieve the data registered with the node for the key key using setUserData(). Returns None if no data was registered for key. Added in DOM Level 3. setUserData( key, data, handler) Set the object data to be associated with a key key on the current node. key can be any hashable object, and will be used as a dictionary key. Any previous value registered for the same value of key will be discarded. The handler argument should be None or an implementation of the UserDataHandler interface. Added in DOM Level 3. These additional Text attributes have been added based on the Level 3 drafts. These are also available on CDATASection nodes. wholeText Returns the textual content for a contiguous range of nodes of type TEXT_NODE and CDATA_SECTION_NODE nodes containing the current node. replaceWholeText( content) Replace a contiguous range of nodes of type TEXT_NODE and CDATA_SECTION_NODE nodes containing the current node, with a single node containing the text content. Returns the node containing content. If content is an empty string, removes the entire range of affected nodes and returns None. These methods and attributes have been added to the Document interface: 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 None Added in DOM Level 3. encoding The encoding specified in the XML declaration, or None if the declaration or encoding pseudo-attribute were omitted. Added in DOM Level 3. standalone If the standalone pseudo-attribute was given in the document's XML declaration, this will be True if the value was "yes" or False if the value was "no". If the XML declaration or standalone pseudo-attribute were omitted, this will be None. Added in DOM Level 3. version The value of the version pseudo-attribute from the XML declaration, if present, or None. Added in DOM Level 3. importNode( node, deep) Imports a node node from another document. If deep is true, child nodes are recursively imported. Nodes of type DOCUMENT_NODE and DOCUMENT_TYPE_NODE cannot be imported; if node has one of these values for its nodeType attribute, xml.dom.NotSupportedErr will be raised. Added in DOM Level 2. renameNode( node, namespaceURI, name) Added in DOM Level 3. Implementation specific behavior: The DOM Level 2 Core specification leaves some room for differing behaviors for how some node types are handled by the 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 Document node, cloneNode() with the deep argument set to true will create a new document with the children recursively imported into the new document. When deep is false, cloneNode() will return None, as the operation is no reasonable meaning for the operation. When called on a DocumentType node, cloneNode() will return 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 entities and notations fields. If deep is true, these will be new NamedNodeMap objects which hold clones of the Entity and Notation nodes, as appropriate. If deep is false, these will be initialized to new, empty NamedNodeMap objects. 4 xml.dom.xmlbuilder -- DOM Level 3 Load/Save Interface New in version 0.8. Warning: The 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. 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: DOMInputSource DOMEntityResolver DOMBuilder DOMBuilderFilter Mixin classes: class DOMImplementationLS Class that can be mixed into an implementation of the DOMImplementation interface. This implementation provides the MODE_SYNCHRONOUS and MODE_ASYNCHRONOUS constants and the createDOMBuilder(), createDOMWriter(), and createDOMInputSource() methods. Most DOM implementations should be able to re-use the createDOMInputSource() method, and will need to override the createDOMBuilder() method if it will actually be using a different DOM builder. The createDOMWriter() method should be usable for all implementations once the DOMWriter has been implemented, but that has not yet been done in PyXML. class DocumentLS Class that can be mixed in to a 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 NotSupportedErr. 4.1 DOMImplementationLS Extensions The DOMImplementationLS mixin class is designed to be used in an implementation of the DOMImplementation interface. This class provides the constants MODE_SYNCHRONOUS and MODE_ASYNCHRONOUS, and the following methods: createDOMBuilder( mode, schemaType) Returns a DOMBuilder instance. Specific DOM implementations will usually need to override this to return a specialized subclass of the DOMBuilder class; see the documentation on the DOMBuilder for information on how and when to write a subclass of that. createDOMWriter( ) For now, raises NotImplementedError since the writer interface has not been implemented yet. createDOMInputSource( ) Returns a DOMInputSource instance with all attributes set to None. 4.2 DocumentLS Extensions The DocumentLS mixin class for a Document adds the following methods: load( uri) Load a new document from a URI into this DOM Document instance. This is not yet implemented in PyXML. loadXML( source) Load a new document from a DOMInputSource into this DOM Document instance. This is not yet implemented in PyXML. saveXML( snode) Return an XML serialization of the DOM node snode as a string. snode must belong to this document; if not, xml.dom.WrongDocumentErr will be raised. The following attribute is also added: async If set to a true value, the load() and loadXML() methods should load documents asynchronously. If false, these methods will operate in a synchronous mode. PyXML does not support setting this to true. 4.3 DOMBuilder Objects The 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 Document creation. The configuration aspect provides the following attributes and methods: canSetFeature( name, state) Return true if the feature name can be set to state, otherwise returns false. If feature name is not supported, returns false. getFeature( name) Returns the state for the feature name. If name is unrecognized or not supported, xml.dom.NotFoundErr is raised. setFeature( name, state) Set the feature name to state. If feature name is not recognized, xml.dom.NotFoundErr is raised; if the specific state requested is not supported, xml.dom.NotSupportedErr is raised. supportsFeature( name) Returns true if the feature name is supported at all, otherwise returns false. A true return does not imply that any particular value for the feature is supported. The Document-creation aspect of the public API is provided by these methods: parse( input) Returns a document based on the DOMInputSource given as input. parseURI( uri) Returns a document from the URI given by uri. parseWithContext( input, cnode, action) Note: Not implemented in the current version. Legal values for action are given by the constants ACTION_REPLACE, ACTION_APPEND_AS_CHILDREN, ACTION_INSERT_AFTER, and ACTION_INSERT_BEFORE, all defined on the DOMBuilder class. Subclasses are expected to define the following method to determine how the Document instances returned by the parse() method will be created. Warning: The interface for subclasses is very preliminary, and should be considered likely to change in future releases. _parse_bytestream( stream, options) Returns a Document instance parsed from the file object given as stream using the configuration options in the options object. The default implementation uses xml.parsers.expat to construct documents using the xml.dom.minidom DOM implementation. 4.4 Subclassing DOMBuilder There are two important aspects to subclassing the DOMBuilder: implementing a useful subclass and getting a DOMImplementation that uses it. The first aspect is faily easy; to create a DOMBuilder that uses a different parser, use a subclass that overrides the _parse_bytestream() method, documented above. The implementation of a specialized DOM builder may not be trivial, but the integration with the provided DOMBuilder class will be reasonably direct. The second aspect, creating a DOM implementation that uses the new DOMBuilder implementation, is a little more tedious, but not excessively so. The DOMImplementationLS mixin class can be used, and the createDOMBuilder() method overridden to use the new DOMBuilder implementation. This makes less sense if you want to re-use most of an existing DOM implementation, however. To use a new DOMBuilder with existing DOM implementation code, such as xml.dom.minidom, the easiest approach is to subclass an existing DOMImplementation class. For xml.dom.minidom, this could be done this way: 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() 5 xml.ns -- XML Namespace constants 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, "ds" is almost always used as the namespace prefixes for items in XML Signature, so "DS" is the class name. Attributes within that class define symbolic names (hopefully evocative) for ``constants'' used in that standard. class XMLNS The Namespaces in XML recommendation defines the concept and syntactic constructs relating to XML namespaces. BASE The namespace URI assigned to namespace declarations. This is assigned to attributes named xmlns and attributes which have a namespace prefix of xmlns. XML The namespace bound to this URI is used for all elements and attributes which start with the letters "xml", regardless of case. No other elements or attributes are allowed to use this namespace. HTML This namespace is recommended for use with HTML 4.0. class XLINK The XML Linking Language defines document linking semantics and an attribute language that allows these semantics to be expressed in XML documents. 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. class 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. 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. ENC The namespace URI used for the optional payload encoding defined in section 5 of the SOAP specification. 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. class DSIG The namespace URIs given here are defined by the XML digital signature specification. BASE The basic namespace defined by the specification. C14N The URI by which Canonical XML (Version 1.0) is identified when used as a transformation or canonicalization method. C14N_COMM This URI identifies ``canonical XML with comments,'' as described in Canonical XML (Version 1.0), section 2.1. C14N_EXCL The URI by which the canonicalization variant defined in Exclusive XML Canonicalization (Version 1.0) is identified when used as a transformation or canonicalization method. The specification also assigns URIs to specific methods of computing message digests and signatures, and other encoding techniques used in the specification. DIGEST_SHA1 The URI for the SHA-1 digest method. DIGEST_MD2 The URI for the MD2 digest method. DIGEST_MD5 The URI for the MD5 digest method. 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, Digital Signature Standard (DSS). SIG_RSA_SHA1 The URI indicating the RSA signature algorithm using SHA-1 for the secure hash. HMAC_SHA1 URI for the SHA-1 HMAC algorithm. ENC_BASE64 URI used to denote the base64 encoding and transform. ENVELOPED URI used to specify the enveloped signature transform method (section 6.6.4 of the specification). XPATH URI used to specify the XPath filtering transform method (section 6.6.3 of the specification). XSLT URI used to specify the XSLT transform method (section 6.6.5 of the specification). class RNG The URIs provided here are used with the Relax NG schema language. BASE The namespace URI of the elements defined by the Relax NG Specification. class SCHEMA BASE XSD1 XSD2 XSD3 XSI1 XSI2 XSI3 Two additional convenience attributes are defined: XSD_LIST A sequence of all ... namespaces. XSI_LIST A sequence of all ... namespaces. class XSLT XSLT, defined in XML Stylesheet Language -- Transformations, defines a single namespace: BASE This URI is used as the namespace for all XSLT elements and for XSLT attributes attached to non-XSLT elements. class 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. BASE The basic namespace defined in this specification. BIND_SOAP The URI of the SOAP binding for WSDL. BIND_HTTP HTTP bindings for WSDL using the GET and POST methods. BIND_MIME The URI of the namespace for MIME-type bindings for WSDL. 6 xml.parsers.expat Extensions The version of the 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 Python Library Reference. The module provides a new data attribute: features A list of name-value pairs giving some information about the compilation of Expat being used. This is generated directly from the feature information provided by Expat's 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. The parser provides a new method: UseForeignDTD( [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 flag is true or omitted, Expat will attempt to load an external subset by calling the ExternalEntityRefHandler callback with systemId and publicId both set to None; this is done only if the document does not specify a external subset. If 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; 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. and one new attribute: 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 StartElementHandler and 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 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. One new callback method has been added as well: 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 EntityDeclHandler, if set. This was added in PyXML 0.8 to support Expat 1.95.4 and newer. See Also: 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. 7 xml.parsers.sgmllib -- Accelerated SGML Parser This module is an alternate implementation of the sgmllib module from the Python standard library. This implementation uses the 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 close() method of the parser instances when done with them. 8 xml.parsers.sgmlop -- XML/SGML Parser Accelerator The xml.parsers.sgmlop module is a C implementation of a parser similar in interface to the xmllib.XMLParser and sgmllib.SGMLParser classes from the Python standard library. Additional support is provided for a basic tree-constructor which is intended to be used in conjunction with the parsers implemented by this module. 9 xml.sax.saxexts make_parser( [parser]) A utility function that returns a Parser object for a non-validating XML parser. If parser is specified, it must be a parser name; otherwise, a list of available parsers is checked and the fastest one chosen. HTMLParserFactory An instance of the ParserFactory class that's already been prepared with a list of HTML parsers. Simply call its make_parser() method to get a Parser object. class ParserFactory( ) A general class to be used by applications for creating parsers on foreign systems where the list of installed parsers is unknown. SGMLParserFactory An instance of the ParserFactory class that's already been prepared with a list of SGML parsers. Simply call its make_parser() method to get a parser object. XMLParserFactory An instance of the ParserFactory class that's already been prepared with a list of nonvalidating XML parsers. Simply call its make_parser() method to get a parser object. XMLValParserFactory An instance of the ParserFactory class that's already been prepared with a list of validating XML parsers. Simply call its make_parser() method to get a parser object. class 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. 9.1 ExtendedParser methods close( ) Called after the last call to feed, when there are no more data. feed( data) Feeds data to the parser. get_parser_name( ) Returns a single-word parser name. get_parser_version( ) Returns the version of the imported parser, which may not be the one the driver was implemented for. is_dtd_reading( ) True if the parser is non-validating, but conforms to the XML specification by reading the DTD. is_validating( ) Returns true if the parser is validating, false otherwise. reset( ) Makes the parser start parsing afresh. 9.2 ParserFactory methods get_parser_list( ) Returns the list of possible drivers. Currently this starts out as ["xml.sax.drivers.drv_xmltok", "xml.sax.drivers.drv_xmlproc", "xml.sax.drivers.drv_xmltoolkit", "xml.sax.drivers.drv_xmllib"]. make_parser( [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 SAXException is thrown. Optionally, 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. set_parser_list( list) Sets the driver list to list. 10 xml.sax.saxlib class 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 DocumentHandler.startElement callback, and the attributes will not necessarily be provided in the order declared or specified. class 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 Parser. If you do not want to implement the entire interface, you can derive a class from HandlerBase, which implements the default functionality. You can find the location of any document event using the Locator interface supplied by setDocumentLocator(). class 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 HandlerBase, which implements the default behaviour. class EntityResolver( ) This is the basic interface for resolving entities. If you create an object implementing this interface, then register the object with your Parser instance, the parser will call the method in your object to resolve all external entities. Note that HandlerBase implements this interface with the default behaviour. class 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. class HandlerBase( ) Default base class for handlers. This class implements the default behaviour for four SAX interfaces, inheriting from them all: EntityResolver, DTDHandler, DocumentHandler, and 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. class 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 SAXDocumentHandler class; at any other time, the results are unpredictable. class 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. class 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 SAXException as the argument to the handlers in the ErrorHandler interface, you are not actually required to throw the exception; instead, you can simply read the information in it. class 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 SAXParseException as the argument to the handlers in the 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 SAXException, it inherits the ability to wrap another exception. 10.1 AttributeList methods The AttributeList class supports some of the behaviour of Python dictionaries; the len() function and has_key(), keys() methods are available, and attr['href'] will retrieve the value of the href attribute. There are also additional methods specific to AttributeList: getLength( ) Return the number of attributes in the list. getName( i) Return the name of attribute i in the list. getType( i) Return the type of an attribute in the list. i can be either the integer index or the attribute name. getValue( i) Return the value of an attribute in the list. i can be either the integer index or the attribute name. 10.2 DocumentHandler methods characters( ch, start, length) Handle a character data event. endDocument( ) Handle an event for the end of a document. endElement( name) Handle an event for the end of an element. ignorableWhitespace( ch, start, length) Handle an event for ignorable whitespace in element content. processingInstruction( target, data) Handle a processing instruction event. setDocumentLocator( locator) Receive an object for locating the origin of SAX document events. You'll probably want to store the value of locator as an attribute of the handler instance. startDocument( ) Handle an event for the beginning of a document. startElement( name, attrs) Handle an event for the beginning of an element. 10.3 DTDHandler methods notationDecl( name, publicId, systemId) Handle a notation declaration event. unparsedEntityDecl( publicId, systemId, notationName) Handle an unparsed entity declaration event. 10.4 EntityResolver methods resolveEntity( name, publicId, systemId) Resolve the system identifier of an entity. 10.5 ErrorHandler methods error( exception) Handle a recoverable error. fatalError( exception) Handle a non-recoverable error. warning( exception) Handle a warning. 10.6 Locator methods getColumnNumber( ) Return the column number where the current event ends. getLineNumber( ) Return the line number where the current event ends. getPublicId( ) Return the public identifier for the current event. getSystemId( ) Return the system identifier for the current event. 10.7 Parser methods parse( systemId) Parse an XML document from a system identifier. parseFile( fileobj) Parse an XML document from a file-like object. setDocumentHandler( handler) Register an object to receive basic document-related events. setDTDHandler( handler) Register an object to receive basic DTD-related events. setEntityResolver( resolver) Register an object to resolve external entities. setErrorHandler( handler) Register an object to receive error-message events. 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. 10.8 SAXException methods getException( ) Return the embedded exception, if any. getMessage( ) Return a message for this exception. 10.9 SAXParseException methods The SAXParseException class has a locator attribute, containing an instance of the Locator class, which represents the location in the document where the parse error occurred. The following methods are delegated to this instance. getColumnNumber( ) Return the column number of the end of the text where the exception occurred. getLineNumber( ) Return the line number of the end of the text where the exception occurred. getPublicId( ) Return the public identifier of the entity where the exception occurred. getSystemId( ) Return the system identifier of the entity where the exception occurred. 11 xml.sax.saxutils escape( data[, entities]) Escape "&", "<", and ">" in a string of data. You can escape other strings of data by passing a dictionary as the optional entities parameter. The keys and values must all be strings; each key will be replaced with its corresponding value. quoteattr( data[, entities]) Similar to escape(), but also prepares data to be used as an attribute value. The return value is a quoted version of data with any additional required replacements. quoteattr() will select a quote character based on the content of data, attempting to avoid encoding any quote characters in the string. If both single- and double-quote characters are already in data, the double-quote characters will be encoded and data will be wrapped in doule-quotes. The resulting string can be used directly as an attribute value: >>> print "" % quoteattr("ab ' cd \" ef") This function is useful when generating attribute values for HTML or any SGML using the reference concrete syntax. class Canonizer( writer) A SAX document handler that produces canonicalized XML output. writer must support a write() method which accepts a single string. class ErrorPrinter( ) A simple class that just prints error messages to standard error (sys.stderr). class ESISDocHandler( writer) A SAX document handler that produces naive ESIS output. writer must support a write() method which accepts a single string. class EventBroadcaster( list) Takes a list of objects and forwards any method calls received to all objects in the list. The attribute list holds the list and can freely be modified by clients. class 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. 11.1 Location methods getColumnNumber( ) Return the column number of the location. getLineNumber( ) Return the line number of the location. getPublicId( ) Return the public identifier for the location. getSystemId( ) Return the system identifier for the location. 12 xml.utils.iso8601 The 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 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. parse( s) Parse an ISO 8601 date representation (with an optional time-of-day component) and return the date in seconds since the epoch. parse_timezone( timezone) Parse an ISO 8601 time zone designator and return the offset relative to Universal Coordinated Time (UTC) in seconds. If timezone is not valid, ValueError is raised. tostring( t[, timezone]) Return formatted date/time value according to the profile described by the W3C. If 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 parse_timezone(). If timezone is specified as a string and cannot be parsed by parse_timezone(), ValueError will be raised. ctime( t) Return formatter date/time value using the local timezone. This is equivalent to "tostring(t, time.timezone)". See Also: 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. ISO 8601 date/time representations Gary Houston's description of the ISO 8601 formats for humans, written in January 1993. A Summary of the International Standard Date and Time Notation Markus Kuhn's excellent discussion of international date/time representations. Date and Time Formats World Wide Web Consortium Technical Note from September 1998, written by Misha Wolf and Charles Wicksteed. About this document ... Python/XML Reference Guide This document was generated using the LaTeX2HTML translator. LaTeX2HTML is Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney. The application of LaTeX2HTML to the Python documentation has been heavily tailored by Fred L. Drake, Jr. Original navigation icons were contributed by Christopher Petrilli. _________________________________________________________________ Python/XML Reference Guide _________________________________________________________________ Release 0.8.