diff options
Diffstat (limited to 'Doc/lib/libxmllib.tex')
| -rw-r--r-- | Doc/lib/libxmllib.tex | 287 |
1 files changed, 0 insertions, 287 deletions
diff --git a/Doc/lib/libxmllib.tex b/Doc/lib/libxmllib.tex deleted file mode 100644 index f7197ca..0000000 --- a/Doc/lib/libxmllib.tex +++ /dev/null @@ -1,287 +0,0 @@ -\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 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}{getnamespace}{} -Return a mapping of namespace abbreviations to namespace URIs that are -currently 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 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\index{DOCTYPE declaration} method is called when the -\samp{<!DOCTYPE...>} declaration is processed. The arguments are the -tag name of the root element, the Formal Public\index{Formal Public -Identifier} 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 \index{ENTITY declaration}entity -declaration \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} - \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 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 (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 href'}. - -An older draft of the XML Namespaces proposal is also recognized, but -triggers 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} |