Kaydet (Commit) b083a9fb authored tarafından Guido van Rossum's avatar Guido van Rossum

Sjoerd Mullender writes:

Here is my current version of xmllib.py and the documentation.  This
version has some API changes with respect to the version currently in
Python (also the one in 1.5.2a).
This version supports XML namespaces.
üst 6de7d0c3
...@@ -14,7 +14,28 @@ for parsing text files formatted in XML (eXtended Markup Language). ...@@ -14,7 +14,28 @@ for parsing text files formatted in XML (eXtended Markup Language).
The \class{XMLParser} class must be instantiated without arguments. The \class{XMLParser} class must be instantiated without arguments.
\end{classdesc} \end{classdesc}
This class provides the following interface methods: 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.
\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.
\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}{} \begin{methoddesc}{reset}{}
Reset the instance. Loses all unprocessed data. This is called Reset the instance. Loses all unprocessed data. This is called
...@@ -33,7 +54,7 @@ when the close tag matching the last unclosed open tag is encountered. ...@@ -33,7 +54,7 @@ when the close tag matching the last unclosed open tag is encountered.
\begin{methoddesc}{feed}{data} \begin{methoddesc}{feed}{data}
Feed some text to the parser. It is processed insofar as it consists Feed some text to the parser. It is processed insofar as it consists
of complete elements; incomplete data is buffered until more data is of complete tags; incomplete data is buffered until more data is
fed or \method{close()} is called. fed or \method{close()} is called.
\end{methoddesc} \end{methoddesc}
...@@ -65,29 +86,29 @@ the root element. ...@@ -65,29 +86,29 @@ the root element.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{handle_starttag}{tag, method, attributes} \begin{methoddesc}{handle_starttag}{tag, method, attributes}
This method is called to handle start tags for which a This method is called to handle start tags for which a start tag
\method{start_\var{tag}()} method has been defined. The \var{tag} handler is defined in the instance variable \member{elements}. The
argument is the name of the tag, and the \var{method} argument is the \var{tag} argument is the name of the tag, and the \var{method}
bound method which should be used to support semantic interpretation argument is the function (method) which should be used to support semantic
of the start tag. The \var{attributes} argument is a dictionary of interpretation of the start tag. The \var{attributes} argument is a
attributes, the key being the \var{name} and the value being the dictionary of attributes, the key being the \var{name} and the value
\var{value} of the attribute found inside the tag's \code{<>} brackets. being the \var{value} of the attribute found inside the tag's
Character and entity references in the \var{value} have \code{<>} brackets. Character and entity references in the
been interpreted. For instance, for the tag \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{<A HREF="http://www.cwi.nl/">}, this method would be called as
\code{handle_starttag('A', self.start_A, \{'HREF': 'http://www.cwi.nl/'\})}. \code{handle_starttag('A', self.elements['A'][0], \{'HREF': 'http://www.cwi.nl/'\})}.
The base implementation simply calls \var{method} with \var{attributes} The base implementation simply calls \var{method} with \var{attributes}
as the only argument. as the only argument.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{handle_endtag}{tag, method} \begin{methoddesc}{handle_endtag}{tag, method}
This method is called to handle endtags for which an This method is called to handle endtags for which an end tag handler
\method{end_\var{tag}()} method has been defined. The \var{tag} is defined in the instance variable \member{elements}. The \var{tag}
argument is the name of the tag, and the argument is the name of the tag, and the \var{method} argument is the
\var{method} argument is the bound method which should be used to function (method) which should be used to support semantic
support semantic interpretation of the end tag. If no interpretation of the end tag. For instance, for the endtag
\method{end_\var{tag}()} method is defined for the closing element, this \code{</A>}, this method would be called as \code{handle_endtag('A',
handler is not called. The base implementation simply calls self.elements['A'][1])}. The base implementation simply calls
\var{method}. \var{method}.
\end{methoddesc} \end{methoddesc}
...@@ -149,7 +170,7 @@ closing delimiter, but not the delimiter itself. For example, the ...@@ -149,7 +170,7 @@ closing delimiter, but not the delimiter itself. For example, the
instruction \samp{<?XML text?>} will cause this method to be called instruction \samp{<?XML text?>} will cause this method to be called
with the arguments \code{'XML'} and \code{'text'}. The default method with the arguments \code{'XML'} and \code{'text'}. The default method
does nothing. Note that if a document starts with \samp{<?xml does nothing. Note that if a document starts with \samp{<?xml
...?>}, \method{handle_xml()} is called to handle it. ..?>}, \method{handle_xml()} is called to handle it.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}{handle_special}{data} \begin{methoddesc}{handle_special}{data}
...@@ -196,32 +217,21 @@ intended to be overridden by a derived class; the base class ...@@ -196,32 +217,21 @@ intended to be overridden by a derived class; the base class
implementation does nothing. implementation does nothing.
\end{methoddesc} \end{methoddesc}
Apart from overriding or extending the methods listed above, derived \subsection{XML Namespaces}
classes may also define methods and variables of the following form to
define processing of specific tags. Tag names in the input stream are This module has support for XML namespaces as defined in the XML
case dependent; the \var{tag} occurring in method names must be in the Namespaces proposed recommendation.
correct case:
Tag and attribute names that are defined in an XML namespace are
\begin{methoddescni}{start_\var{tag}}{attributes} handled as if the name of the tag or element consisted of the
This method is called to process an opening tag \var{tag}. The namespace (i.e. the URL that defines the namespace) followed by a
\var{attributes} argument has the same meaning as described for space and the name of the tag or attribute. For instance, the tag
\method{handle_starttag()} above. In fact, the base implementation of \code{<html xmlns='http://www.w3.org/TR/REC-html40'>} is treated as if
\method{handle_starttag()} calls this method. the tag name was \code{'http://www.w3.org/TR/REC-html40 html'}, and
\end{methoddescni} the tag \code{<html:a href='http://frob.com'>} inside the above
mentioned element is treated as if the tag name were
\begin{methoddescni}{end_\var{tag}}{} \code{'http://www.w3.org/TR/REC-html40 a'} and the attribute name as
This method is called to process a closing tag \var{tag}. if it were \code{'http://www.w3.org/TR/REC-html40 src'}.
\end{methoddescni}
An older draft of the XML Namespaces proposal is also recognized, but
\begin{memberdescni}{\var{tag}_attributes} triggers a warning.
If a class or instance variable \member{\var{tag}_attributes} exists, it
should be a list or a dictionary. If a list, the elements of the list
are the valid attributes for the element \var{tag}; if a dictionary,
the keys are the valid attributes for the element \var{tag}, and the
values the default values of the attributes, or \code{None} if there
is no default.
In addition to the attributes that were present in the tag, the
attribute dictionary that is passed to \method{handle_starttag()} and
\method{unknown_starttag()} contains values for all attributes that
have a default value.
\end{memberdescni}
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment