268 lines
12 KiB
TeX
268 lines
12 KiB
TeX
\section{\module{xmllib} ---
|
|
A parser for XML documents}
|
|
|
|
\declaremodule{standard}{xmllib}
|
|
\modulesynopsis{A parser for XML documents.}
|
|
\moduleauthor{Sjoerd Mullender}{Sjoerd.Mullender@cwi.nl}
|
|
\sectionauthor{Sjoerd Mullender}{Sjoerd.Mullender@cwi.nl}
|
|
|
|
|
|
\index{XML}
|
|
\index{Extensible Markup Language}
|
|
|
|
\versionchanged{1.5.2}
|
|
|
|
This module defines a class \class{XMLParser} which serves as the basis
|
|
for parsing text files formatted in XML (Extensible Markup Language).
|
|
|
|
\begin{classdesc}{XMLParser}{}
|
|
The \class{XMLParser} class must be instantiated without
|
|
arguments.\footnote{Actually, a number of keyword arguments are
|
|
recognized which influence the parser to accept certain non-standard
|
|
constructs. The following keyword arguments are currently
|
|
recognized. The defaults for all of these is \code{0} (false) except
|
|
for the last one for which the default is \code{1} (true).
|
|
\var{accept_unquoted_attributes} (accept certain attribute values
|
|
without requiring quotes), \var{accept_missing_endtag_name} (accept
|
|
end tags that look like \code{</>}), \var{map_case} (map upper case to
|
|
lower case in tags and attributes), \var{accept_utf8} (allow UTF-8
|
|
characters in input; this is required according to the XML standard,
|
|
but Python does not as yet deal properly with these characters, so
|
|
this is not the default), \var{translate_attribute_references} (don't
|
|
attempt to translate character and entity references in attribute values).}
|
|
\end{classdesc}
|
|
|
|
This class provides the following interface methods and instance variables:
|
|
|
|
\begin{memberdesc}{attributes}
|
|
A mapping of element names to mappings. The latter mapping maps
|
|
attribute names that are valid for the element to the default value of
|
|
the attribute, or if there is no default to \code{None}. The default
|
|
value is the empty dictionary. This variable is meant to be
|
|
overridden, not extended since the default is shared by all instances
|
|
of \class{XMLParser}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{elements}
|
|
A mapping of element names to tuples. The tuples contain a function
|
|
for handling the start and end tag respectively of the element, or
|
|
\code{None} if the method \method{unknown_starttag()} or
|
|
\method{unknown_endtag()} is to be called. The default value is the
|
|
empty dictionary. This variable is meant to be overridden, not
|
|
extended since the default is shared by all instances of
|
|
\class{XMLParser}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{entitydefs}
|
|
A mapping of entitynames to their values. The default value contains
|
|
definitions for \code{'lt'}, \code{'gt'}, \code{'amp'}, \code{'quot'},
|
|
and \code{'apos'}.
|
|
\end{memberdesc}
|
|
|
|
\begin{methoddesc}{reset}{}
|
|
Reset the instance. Loses all unprocessed data. This is called
|
|
implicitly at the instantiation time.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{setnomoretags}{}
|
|
Stop processing tags. Treat all following input as literal input
|
|
(CDATA).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{setliteral}{}
|
|
Enter literal mode (CDATA mode). This mode is automatically exited
|
|
when the close tag matching the last unclosed open tag is encountered.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{feed}{data}
|
|
Feed some text to the parser. It is processed insofar as it consists
|
|
of complete tags; incomplete data is buffered until more data is
|
|
fed or \method{close()} is called.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
Force processing of all buffered data as if it were followed by an
|
|
end-of-file mark. This method may be redefined by a derived class to
|
|
define additional processing at the end of the input, but the
|
|
redefined version should always call \method{close()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{translate_references}{data}
|
|
Translate all entity and character references in \var{data} and
|
|
return the translated string.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_xml}{encoding, standalone}
|
|
This method is called when the \samp{<?xml ...?>} tag is processed.
|
|
The arguments are the values of the encoding and standalone attributes
|
|
in the tag. Both encoding and standalone are optional. The values
|
|
passed to \method{handle_xml()} default to \code{None} and the string
|
|
\code{'no'} respectively.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_doctype}{tag, pubid, syslit, data}
|
|
This method is called when the \samp{<!DOCTYPE...>} tag is processed.
|
|
The arguments are the name of the root element, the Formal Public
|
|
Identifier (or \code{None} if not specified), the system identifier,
|
|
and the uninterpreted contents of the internal DTD subset as a string
|
|
(or \code{None} if not present).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_starttag}{tag, method, attributes}
|
|
This method is called to handle start tags for which a start tag
|
|
handler is defined in the instance variable \member{elements}. The
|
|
\var{tag} argument is the name of the tag, and the \var{method}
|
|
argument is the function (method) which should be used to support semantic
|
|
interpretation of the start tag. The \var{attributes} argument is a
|
|
dictionary of attributes, the key being the \var{name} and the value
|
|
being the \var{value} of the attribute found inside the tag's
|
|
\code{<>} brackets. Character and entity references in the
|
|
\var{value} have been interpreted. For instance, for the start tag
|
|
\code{<A HREF="http://www.cwi.nl/">}, this method would be called as
|
|
\code{handle_starttag('A', self.elements['A'][0], \{'HREF': 'http://www.cwi.nl/'\})}.
|
|
The base implementation simply calls \var{method} with \var{attributes}
|
|
as the only argument.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_endtag}{tag, method}
|
|
This method is called to handle endtags for which an end tag handler
|
|
is defined in the instance variable \member{elements}. The \var{tag}
|
|
argument is the name of the tag, and the \var{method} argument is the
|
|
function (method) which should be used to support semantic
|
|
interpretation of the end tag. For instance, for the endtag
|
|
\code{</A>}, this method would be called as \code{handle_endtag('A',
|
|
self.elements['A'][1])}. The base implementation simply calls
|
|
\var{method}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_data}{data}
|
|
This method is called to process arbitrary data. It is intended to be
|
|
overridden by a derived class; the base class implementation does
|
|
nothing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_charref}{ref}
|
|
This method is called to process a character reference of the form
|
|
\samp{\&\#\var{ref};}. \var{ref} can either be a decimal number,
|
|
or a hexadecimal number when preceded by an \character{x}.
|
|
In the base implementation, \var{ref} must be a number in the
|
|
range 0-255. It translates the character to \ASCII{} and calls the
|
|
method \method{handle_data()} with the character as argument. If
|
|
\var{ref} is invalid or out of range, the method
|
|
\code{unknown_charref(\var{ref})} is called to handle the error. A
|
|
subclass must override this method to provide support for character
|
|
references outside of the \ASCII{} range.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_comment}{comment}
|
|
This method is called when a comment is encountered. The
|
|
\var{comment} argument is a string containing the text between the
|
|
\samp{<!--} and \samp{-->} delimiters, but not the delimiters
|
|
themselves. For example, the comment \samp{<!--text-->} will
|
|
cause this method to be called with the argument \code{'text'}. The
|
|
default method does nothing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_cdata}{data}
|
|
This method is called when a CDATA element is encountered. The
|
|
\var{data} argument is a string containing the text between the
|
|
\samp{<![CDATA[} and \samp{]]>} delimiters, but not the delimiters
|
|
themselves. For example, the entity \samp{<![CDATA[text]]>} will
|
|
cause this method to be called with the argument \code{'text'}. The
|
|
default method does nothing, and is intended to be overridden.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_proc}{name, data}
|
|
This method is called when a processing instruction (PI) is
|
|
encountered. The \var{name} is the PI target, and the \var{data}
|
|
argument is a string containing the text between the PI target and the
|
|
closing delimiter, but not the delimiter itself. For example, the
|
|
instruction \samp{<?XML text?>} will cause this method to be called
|
|
with the arguments \code{'XML'} and \code{'text'}. The default method
|
|
does nothing. Note that if a document starts with \samp{<?xml
|
|
..?>}, \method{handle_xml()} is called to handle it.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{handle_special}{data}
|
|
This method is called when a declaration is encountered. The
|
|
\var{data} argument is a string containing the text between the
|
|
\samp{<!} and \samp{>} delimiters, but not the delimiters
|
|
themselves. For example, the entity \samp{<!ENTITY text>} will
|
|
cause this method to be called with the argument \code{'ENTITY text'}. The
|
|
default method does nothing. Note that \samp{<!DOCTYPE ...>} is
|
|
handled separately if it is located at the start of the document.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{syntax_error}{message}
|
|
This method is called when a syntax error is encountered. The
|
|
\var{message} is a description of what was wrong. The default method
|
|
raises a \exception{RuntimeError} exception. If this method is
|
|
overridden, it is permissible for it to return. This method is only
|
|
called when the error can be recovered from. Unrecoverable errors
|
|
raise a \exception{RuntimeError} without first calling
|
|
\method{syntax_error()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{unknown_starttag}{tag, attributes}
|
|
This method is called to process an unknown start tag. It is intended
|
|
to be overridden by a derived class; the base class implementation
|
|
does nothing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{unknown_endtag}{tag}
|
|
This method is called to process an unknown end tag. It is intended
|
|
to be overridden by a derived class; the base class implementation
|
|
does nothing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{unknown_charref}{ref}
|
|
This method is called to process unresolvable numeric character
|
|
references. It is intended to be overridden by a derived class; the
|
|
base class implementation does nothing.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{unknown_entityref}{ref}
|
|
This method is called to process an unknown entity reference. It is
|
|
intended to be overridden by a derived class; the base class
|
|
implementation calls \method{syntax_error()} to signal an error.
|
|
\end{methoddesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seetext{The XML specification, published by the World Wide Web
|
|
Consortium (W3C), is available online at
|
|
\url{http://www.w3.org/TR/REC-xml}. References to
|
|
additional material on XML are available at
|
|
\url{http://www.w3.org/XML/}.}
|
|
|
|
\seetext{The Python XML Topic Guide provides a great deal of information
|
|
on using XML from Python and links to other sources of information
|
|
on XML. It's located on the Web at
|
|
\url{http://www.python.org/topics/xml/}.}
|
|
|
|
\seetext{The Python XML Special Interest Group is developing substantial
|
|
support for processing XML from Python. See
|
|
\url{http://www.python.org/sigs/xml-sig/} for more information.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{XML Namespaces \label{xml-namespace}}
|
|
|
|
This module has support for XML namespaces as defined in the XML
|
|
Namespaces proposed recommendation.
|
|
\indexii{XML}{namespaces}
|
|
|
|
Tag and attribute names that are defined in an XML namespace are
|
|
handled as if the name of the tag or element consisted of the
|
|
namespace (i.e. the URL that defines the namespace) followed by a
|
|
space and the name of the tag or attribute. For instance, the tag
|
|
\code{<html xmlns='http://www.w3.org/TR/REC-html40'>} is treated as if
|
|
the tag name was \code{'http://www.w3.org/TR/REC-html40 html'}, and
|
|
the tag \code{<html:a href='http://frob.com'>} inside the above
|
|
mentioned element is treated as if the tag name were
|
|
\code{'http://www.w3.org/TR/REC-html40 a'} and the attribute name as
|
|
if it were \code{'http://www.w3.org/TR/REC-html40 src'}.
|
|
|
|
An older draft of the XML Namespaces proposal is also recognized, but
|
|
triggers a warning.
|