\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} \deprecated{2.0}{Use \refmodule{xml.sax} instead.  The newer XML                 package includes full support for XML 1.0.} \versionchanged[Added namespace support]{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 withoutarguments.\footnote{Actually, a number of keyword arguments arerecognized which influence the parser to accept certain non-standardconstructs.  The following keyword arguments are currentlyrecognized.  The defaults for all of these is \code{0} (false) exceptfor the last one for which the default is \code{1} (true).\var{accept_unquoted_attributes} (accept certain attribute valueswithout requiring quotes), \var{accept_missing_endtag_name} (acceptend tags that look like \code{</>}), \var{map_case} (map upper case tolower case in tags and attributes), \var{accept_utf8} (allow UTF-8characters in input; this is required according to the XML standard,but Python does not as yet deal properly with these characters, sothis is not the default), \var{translate_attribute_references} (don'tattempt 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 mapsattribute names that are valid for the element to the default value of the attribute, or if there is no default to \code{None}.  The defaultvalue is the empty dictionary.  This variable is meant to beoverridden, not extended since the default is shared by all instancesof \class{XMLParser}.\end{memberdesc} \begin{memberdesc}{elements} A mapping of element names to tuples.  The tuples contain a functionfor 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 theempty dictionary.  This variable is meant to be overridden, notextended 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 containsdefinitions 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 calledimplicitly 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 exitedwhen 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 consistsof complete tags; incomplete data is buffered until more data isfed or \method{close()} is called.\end{methoddesc} \begin{methoddesc}{close}{}Force processing of all buffered data as if it were followed by anend-of-file mark.  This method may be redefined by a derived class todefine additional processing at the end of the input, but theredefined version should always call \method{close()}.\end{methoddesc} \begin{methoddesc}{translate_references}{data}Translate all entity and character references in \var{data} andreturn the translated string.\end{methoddesc} \begin{methoddesc}{getnamespace}{}Return a mapping of namespace abbreviations to namespace URIs that arecurrently in effect.\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 valuespassed 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\index{DOCTYPE declaration} method is called when the\samp{<!DOCTYPE...>} declaration is processed.  The arguments are thetag name of the root element, the Formal Public\index{Formal PublicIdentifier} Identifier (or \code{None} if not specified), the systemidentifier, and the uninterpreted contents of the internal DTD subsetas 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 taghandler 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 tosupport semantic interpretation of the start tag.  The\var{attributes} argument is a dictionary of attributes, the key beingthe \var{name} and the value being the \var{value} of the attributefound inside the tag's \code{<>} brackets.  Character and entityreferences in the \var{value} have been interpreted.  For instance,for the start tag \code{<A HREF="http://www.cwi.nl/">}, this methodwould be called as \code{handle_starttag('A', self.elements['A'][0],\{'HREF': 'http://www.cwi.nl/'\})}.  The base implementation simplycalls \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 handleris defined in the instance variable \member{elements}.  The \var{tag}argument is the name of the tag, and the \var{method} argument is thefunction (method) which should be used to support semanticinterpretation 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 beoverridden by a derived class; the base class implementation doesnothing.\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 therange 0-255.  It translates the character to \ASCII{} and calls themethod \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.  Asubclass must override this method to provide support for characterreferences 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 delimitersthemselves.  For example, the comment \samp{<!--text-->} willcause this method to be called with the argument \code{'text'}.  Thedefault 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 delimitersthemselves.  For example, the entity \samp{<![CDATA[text]]>} willcause this method to be called with the argument \code{'text'}.  Thedefault 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) isencountered.  The \var{name} is the PI target, and the \var{data}argument is a string containing the text between the PI target and theclosing delimiter, but not the delimiter itself.  For example, theinstruction \samp{<?XML text?>} will cause this method to be calledwith the arguments \code{'XML'} and \code{'text'}.  The default methoddoes 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 delimitersthemselves.  For example, the \index{ENTITY declaration}entitydeclaration \samp{<!ENTITY text>} will cause this method to be calledwith the argument \code{'ENTITY text'}.  The default method doesnothing.  Note that \samp{<!DOCTYPE ...>} is handled separately if itis 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 isoverridden, it is permissible for it to return.  This method is onlycalled when the error can be recovered from.  Unrecoverable errorsraise 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 intendedto be overridden by a derived class; the base class implementationdoes nothing.\end{methoddesc} \begin{methoddesc}{unknown_endtag}{tag}This method is called to process an unknown end tag.  It is intendedto be overridden by a derived class; the base class implementationdoes nothing.\end{methoddesc} \begin{methoddesc}{unknown_charref}{ref}This method is called to process unresolvable numeric characterreferences.  It is intended to be overridden by a derived class; thebase class implementation does nothing.\end{methoddesc} \begin{methoddesc}{unknown_entityref}{ref}This method is called to process an unknown entity reference.  It isintended to be overridden by a derived class; the base classimplementation calls \method{syntax_error()} to signal an error.\end{methoddesc}  \begin{seealso}  \seetitle[http://www.w3.org/TR/REC-xml]{Extensible Markup Language            (XML) 1.0}{The XML specification, published by the World            Wide Web Consortium (W3C), defines the syntax and            processor requirements for XML.  References to additional            material on XML, including translations of the            specification, are available at            \url{http://www.w3.org/XML/}.}   \seetitle[http://www.python.org/topics/xml/]{Python and XML            Processing}{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.}   \seetitle[http://www.python.org/sigs/xml-sig/]{SIG for XML            Processing in Python}{The Python XML Special Interest            Group is developing substantial support for processing XML            from Python.}\end{seealso}  \subsection{XML Namespaces \label{xml-namespace}} This module has support for XML namespaces as defined in the XMLNamespaces proposed recommendation.\indexii{XML}{namespaces} Tag and attribute names that are defined in an XML namespace arehandled as if the name of the tag or element consisted of thenamespace (the URL that defines the namespace) followed by aspace 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'}, andthe tag \code{<html:a href='http://frob.com'>} inside the abovementioned element is treated as if the tag name were\code{'http://www.w3.org/TR/REC-html40 a'} and the attribute name asif it were \code{'http://www.w3.org/TR/REC-html40 href'}. An older draft of the XML Namespaces proposal is also recognized, buttriggers a warning. \begin{seealso}  \seetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}{           This World Wide Web Consortium recommendation describes the           proper syntax and processing requirements for namespaces in           XML.}\end{seealso}