Python/XML Reference Guide _________________________________________________________________ _________________________________________________________________ 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. THIS DOCUMENT IS SIGNIFICANTLY OUTDATED, DO NOT USE IT AS A BASIS OF APPLICATION DEVELOPMENT. Contents * Contents * 1. xml.arch.xmlarch + 1.1 ArchDocHandler methods + 1.2 Architecture methods + 1.3 ArchParseState methods + 1.4 ArchException methods + 1.5 AttributeParser methods + 1.6 Normalizer methods * 2. xml.parsers.xmllib * 3. xml.sax.saxexts + 3.1 ExtendedParser methods + 3.2 ParserFactory methods * 4. xml.sax.saxlib + 4.1 AttributeList methods + 4.2 DocumentHandler methods + 4.3 DTDHandler methods + 4.4 EntityResolver methods + 4.5 ErrorHandler methods + 4.6 Locator methods + 4.7 Parser methods + 4.8 SAXException methods + 4.9 SAXParseException methods * 5. xml.sax.saxutils + 5.1 Location methods * 6. xml.utils.iso8601 24 1. xml.arch.xmlarch The xmlarch module contains an XML architectural forms processor written in Python. It allows you to process XML architectural forms using any parser that uses the SAX interfaces. The module allows you to process several architectures in one parsing pass. Architectural document events for an architecture can even be broadcasted to multiple DocumentHandlers. (e.g. you can have 2 handlers for the RDF architecture, 3 for the XLink architecture and perhaps one for the HyTime architecture.) The architecture processor uses the SAX DocumentHandler interface which means that you can register the architecture handler (ArchDocHandler) with any SAX 1.0 compliant parser. It currently does not process any meta document type definition documents (meta-DTDs). When a DTD parser module is available the code will be modified to use that in order to process meta-DTD information. Please note that validating and well-formed parsers may report different SAX events when parsing documents. The xmlarch module contains six classes: ArchDocHandler, Architecture, ArchParseState, ArchException, AttributeParser and Normalizer. * ArchDocHandler is a subclass of the saxlib.DocumentHandler interface. This is the class used for processing an architectural document. * Architecture contains information about an architecture. * ArchParseState holds information about an architecture's parse state when parsing a document. * AttributeParser parses architecture use declaration PIs (attribute strings). * ArchException holds information about an architectural exception thrown by an ArchDocHandler instance. * Normalizer is a document handler that outputs "normalized" XML. 1.1 ArchDocHandler methods Still undocumented. 1.2 Architecture methods Still undocumented. 1.3 ArchParseState methods Still undocumented. 1.4 ArchException methods Still undocumented. 1.5 AttributeParser methods Still undocumented. 1.6 Normalizer methods Still undocumented. 2. xml.parsers.xmllib This is a version of the xmllib module from Python 1.5, modified to use the _sgmlop C extension when it's available. This produces a significant speedup, amounting to about a factor of 5. The interface is unchanged from the original xmllib module; consult the Python Library Reference documentation for that module. 3. 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. 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. 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. 3.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. 3.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. 4. xml.sax.saxlib 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. 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(). 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. 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. 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. 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. 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. 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. 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. 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. 4.1 AttributeList methods The AttributeList class supports some of the behaviour of Python dictionaries; the len(), 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. 4.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. 4.3 DTDHandler methods notationDecl (name, publicId, systemId) Handle a notation declaration event. unparsedEntityDecl (publicId, systemId, notationName) Handle an unparsed entity declaration event. 4.4 EntityResolver methods resolveEntity (name, publicId, systemId) Resolve the system identifier of an entity. 4.5 ErrorHandler methods error (exception) Handle a recoverable error. fatalError (exception) Handle a non-recoverable error. warning (exception) Handle a warning. 4.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. 4.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. 4.8 SAXException methods getException () Return the embedded exception, if any. getMessage () Return a message for this exception. 4.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. 5. xml.sax.saxutils Canonizer (writer) A SAX document handler that produces canonicalized XML output. writer must support a write() method which accepts a single string. ErrorPrinter () A simple class that just prints error messages to standard error (sys.stderr). ESISDocHandler (writer) A SAX document handler that produces naive ESIS output. writer must support a write() method which accepts a single string. 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. 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. 5.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. 6. 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: International Organization for Standardization. Data elements and interchange formats -- Information interchange -- Representation of dates and times. International Organization for Standardization, 1988. Gary Houston. ISO 8601 date/time representations. January 1993. Available online as compressed PostScript: ftp://ftp.informatik.uni-erlangen.de/pub/doc/ISO/ISO8601.ps.Z. Markus Kuhn. A Summary of the International Standard Dateand Time Notation. Available online at http://www.cl.cam.ac.uk/~mgk25/iso-time.html. Misha Wolf and Charles Wicksteed. Date and Time Formats. World Wide Web Consortium Technical Note, September 1998. Available online at http://www.w3.org/TR/NOTE-datetime. 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. (fdrake@acm.org). Original navigation icons were contributed by Christopher Petrilli (petrilli@dworkin.amber.org). _________________________________________________________________ Python/XML Reference Guide _________________________________________________________________