13.4.1 XMLParser Objects

xmlparser objects have the following methods:

Parse (data[, isfinal])
Parses the contents of the string data, calling the appropriate handler functions to process the parsed data. isfinal must be true on the final call to this method. data can be the empty string at any time.

ParseFile (file)
Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, returning the empty string when there's no more data.

SetBase (base)
Sets the base to be used for resolving relative URIs in system identifiers in declarations. Resolving relative identifiers is left to the application: this value will be passed through as the base argument to the ExternalEntityRefHandler, NotationDeclHandler, and UnparsedEntityDeclHandler functions.

GetBase ()
Returns a string containing the base set by a previous call to SetBase(), or None if SetBase() hasn't been called.

ExternalEntityParserCreate (context[, encoding])
Create a ``child'' parser which can be used to parse an external parsed entity referred to by content parsed by the parent parser. The context parameter should be the string passed to the ExternalEntityRefHandler() handler function, described below.

xmlparser objects have the following attributes:

returns_unicode
If this attribute is set to 1, the handler functions will be passed Unicode strings. If returns_unicode is 0, 8-bit strings containing UTF-8 encoded data will be passed to the handlers. Changed in version 1.6: Can be changed at any time to affect the result type..

The following attributes contain values relating to the most recent error encountered by an xmlparser object, and will only have correct values once a call to Parse() or ParseFile() has raised a xml.parsers.expat.error exception.

ErrorByteIndex
Byte index at which an error occurred.

ErrorCode
Numeric code specifying the problem. This value can be passed to the ErrorString() function, or compared to one of the constants defined in the errors object.

ErrorColumnNumber
Column number at which an error occurred.

ErrorLineNumber
Line number at which an error occurred.

Here is the list of handlers that can be set. To set a handler on an xmlparser object o, use o.handlername = func. handlername must be taken from the following list, and func must be a callable object accepting the correct number of arguments. The arguments are all strings, unless otherwise stated.

StartElementHandler (name, attributes)
Called for the start of every element. name is a string containing the element name, and attributes is a dictionary mapping attribute names to their values.

EndElementHandler (name)
Called for the end of every element.

ProcessingInstructionHandler (target, data)
Called for every processing instruction.

CharacterDataHandler (data)
Called for character data.

UnparsedEntityDeclHandler (entityName, base, systemId, publicId, notationName)
Called for unparsed (NDATA) entity declarations.

NotationDeclHandler (notationName, base, systemId, publicId)
Called for notation declarations.

StartNamespaceDeclHandler (prefix, uri)
Called when an element contains a namespace declaration.

EndNamespaceDeclHandler (prefix)
Called when the closing tag is reached for an element that contained a namespace declaration.

CommentHandler (data)
Called for comments.

StartCdataSectionHandler ()
Called at the start of a CDATA section.

EndCdataSectionHandler ()
Called at the end of a CDATA section.

DefaultHandler (data)
Called for any characters in the XML document for which no applicable handler has been specified. This means characters that are part of a construct which could be reported, but for which no handler has been supplied.

DefaultHandlerExpand (data)
This is the same as the DefaultHandler, but doesn't inhibit expansion of internal entities. The entity reference will not be passed to the default handler.

NotStandaloneHandler ()
Called if the XML document hasn't been declared as being a standalone document.

ExternalEntityRefHandler (context, base, systemId, publicId)
Called for references to external entities.

See About this document... for information on suggesting changes.