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.