diff --git a/Doc/lib/xmlsax.tex b/Doc/lib/xmlsax.tex index d09777fea28..c1b94da4c2f 100644 --- a/Doc/lib/xmlsax.tex +++ b/Doc/lib/xmlsax.tex @@ -6,6 +6,7 @@ functions.} \moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no} \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} +\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de} \versionadded{2.0} @@ -41,8 +42,29 @@ The convenience functions are: received as a parameter. \end{funcdesc} +A typical SAX application uses three kinds of objects: readers, +handlers and input sources. ``Reader'' in this context is another term +for parser, ie. some piece of code that reads the bytes or characters +from the input source, and produces a sequence of events. The events +then get distributed to the handler objects, ie. the reader invokes a +method on the handler. A SAX application must therefore obtain a +handler object, create or open the input sources, create the handlers, +and connect these objects all together. As the final step, parsing is +invoked. During parsing -The SAX exceptions are also provided here: +For these objects, only the interfaces are relevant; they are normally +not instantiated by the application itself. Since Python does not have +an explicit notion of interface, they are formally introduced as +classes. The \class{InputSource}, \class{Locator}, +\class{AttributesImpl}, and \class{XMLReader} interfaces are defined +in the module \refmodule{xml.sax.xmlreader}. The handler interfaces +are defined in \refmodule{xml.sax.handler}. For convenience, +\class{InputSource} (which is often instantiated directly) and the +handler classes are also available from \module{xml.sax}. These +classes are described below. + +In addition to these classes, \module{xml.sax} provides the following +exception classes. \begin{excclassdesc}{SAXException}{msg\optional{, exception}} Encapsulate an XML error or warning. This class can contain basic @@ -94,7 +116,7 @@ The SAX exceptions are also provided here: \end{seealso} -\subsection{SAXException Objects \label{saxexception-objects}} +\subsection{SAXException Objects \label{sax-exception-objects}} The \class{SAXException} exception class supports the following methods: diff --git a/Doc/lib/xmlsaxhandler.tex b/Doc/lib/xmlsaxhandler.tex new file mode 100644 index 00000000000..77acc3e502c --- /dev/null +++ b/Doc/lib/xmlsaxhandler.tex @@ -0,0 +1,321 @@ +\section{\module{xml.sax.handler} --- + Base classes for SAX handlers} + +\declaremodule{standard}{xml.sax.handler} +\modulesynopsis{Base classes for SAX event handlers.} +\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de} +\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no} + +\versionadded{2.0} + + +The SAX API defines four kinds of handlers: content handlers, DTD +handlers, error handlers, and entity resolvers. Applications normally +only need to implement those interfaces whose events they are +interested in; they can implement the interfaces in a single object or +in multiple objects. Handler implementations should inherit from the +base classes provided in the module \module{xml.sax}, so that all +methods get default implementations. + +\begin{classdesc}{ContentHandler}{} + This is the main callback interface in SAX, and the one most + important to applications. The order of events in this interface + mirrors the order of the information in the document. +\end{classdesc} + +\begin{classdesc}{DTDHandler}{} + Handle DTD events. + + This interface specifies only those DTD events required for basic + parsing (unparsed entities and attributes). +\end{classdesc} + +\begin{classdesc}{EntityResolver}{} + Basic interface for resolving entities. If you create an object + implementing this interface, then register the object with your + Parser, the parser will call the method in your object to resolve all + external entities. +\end{classdesc} + +In addition to these classes, \module{xml.sax.handler} provides +symbolic constants for the feature and property names. + +\begin{datadesc}{feature_namespaces} + Value: \code{"http://xml.org/sax/features/namespaces"}\\ + true: Perform Namespace processing (default).\\ + false: Optionally do not perform Namespace processing + (implies namespace-prefixes).\\ + access: (parsing) read-only; (not parsing) read/write\\ +\end{datadesc} + +\begin{datadesc}{feature_namespace_prefixes} + Value: \code{"http://xml.org/sax/features/namespace-prefixes"}\\ + true: Report the original prefixed names and attributes used for Namespace + declarations.\\ + false: Do not report attributes used for Namespace declarations, and + optionally do not report original prefixed names (default).\\ + access: (parsing) read-only; (not parsing) read/write +\end{datadesc} + +\begin{datadesc}{feature_string_interning} + Value: \code{"http://xml.org/sax/features/string-interning"} + true: All element names, prefixes, attribute names, Namespace URIs, and + local names are interned using the built-in intern function.\\ + false: Names are not necessarily interned, although they may be (default).\\ + access: (parsing) read-only; (not parsing) read/write +\end{datadesc} + +\begin{datadesc}{feature_validation} + Value: \code{"http://xml.org/sax/features/validation"}\\ + true: Report all validation errors (implies external-general-entities and + external-parameter-entities).\\ + false: Do not report validation errors.\\ + access: (parsing) read-only; (not parsing) read/write +\end{datadesc} + +\begin{datadesc}{feature_external_ges} + Value: \code{"http://xml.org/sax/features/external-general-entities"}\\ + true: Include all external general (text) entities.\\ + false: Do not include external general entities.\\ + access: (parsing) read-only; (not parsing) read/write +\end{datadesc} + +\begin{datadesc}{feature_external_pes} + Value: \code{"http://xml.org/sax/features/external-parameter-entities"}\\ + true: Include all external parameter entities, including the external + DTD subset.\\ + false: Do not include any external parameter entities, even the external + DTD subset.\\ + access: (parsing) read-only; (not parsing) read/write +\end{datadesc} + +\begin{datadesc}{all_features} + List of all features. +\end{datadesc} + +\begin{datadesc}{property_lexical_handler} + Value: \code{"http://xml.org/sax/properties/lexical-handler"}\\ + data type: xml.sax.sax2lib.LexicalHandler (not supported in Python 2)\\ + description: An optional extension handler for lexical events like comments.\\ + access: read/write +\end{datadesc} + +\begin{datadesc}{property_declaration_handler} + Value: \code{"http://xml.org/sax/properties/declaration-handler"}\\ + data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)\\ + description: An optional extension handler for DTD-related events other + than notations and unparsed entities.\\ + access: read/write +\end{datadesc} + +\begin{datadesc}{property_dom_node} + Value: \code{"http://xml.org/sax/properties/dom-node"}\\ + data type: org.w3c.dom.Node (not supported in Python 2) \\ + description: When parsing, the current DOM node being visited if this is + a DOM iterator; when not parsing, the root DOM node for + iteration.\\ + access: (parsing) read-only; (not parsing) read/write +\end{datadesc} + +\begin{datadesc}{property_xml_string} + Value: \code{"http://xml.org/sax/properties/xml-string"}\\ + data type: String\\ + description: The literal string of characters that was the source for + the current event.\\ + access: read-only +\end{datadesc} + +\begin{datadesc}{all_properties} + List of all known property names. +\end{datadesc} + + +\subsection{ContentHandler Objects \label{content-handler-objects}} + +Users are expected to subclass \class{ContentHandler} to support their +application. The following methods are called by the parser on the +appropriate events in the input document: + +\begin{methoddesc}[ContentHandler]{setDocumentLocator}{locator} + Called by the parser to give the application a locator for locating + the origin of document events. + + SAX parsers are strongly encouraged (though not absolutely required) + to supply a locator: if it does so, it must supply the locator to + the application by invoking this method before invoking any of the + other methods in the DocumentHandler interface. + + The locator allows the application to determine the end position of + any document-related event, even if the parser is not reporting an + error. Typically, the application will use this information for + reporting its own errors (such as character content that does not + match an application's business rules). The information returned by + the locator is probably not sufficient for use with a search engine. + + Note that the locator will return correct information only during + the invocation of the events in this interface. The application + should not attempt to use it at any other time. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{startDocument}{} + Receive notification of the beginning of a document. + + The SAX parser will invoke this method only once, before any other + methods in this interface or in DTDHandler (except for + \method{setDocumentLocator()}). +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{endDocument}{} + Receive notification of the end of a document. + + The SAX parser will invoke this method only once, and it will be the + last method invoked during the parse. The parser shall not invoke + this method until it has either abandoned parsing (because of an + unrecoverable error) or reached the end of input. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{startPrefixMapping}{prefix, uri} + Begin the scope of a prefix-URI Namespace mapping. + + The information from this event is not necessary for normal + Namespace processing: the SAX XML reader will automatically replace + prefixes for element and attribute names when the + \code{http://xml.org/sax/features/namespaces} feature is true (the + default). + +%% XXX This is not really the default, is it? MvL + + There are cases, however, when applications need to use prefixes in + character data or in attribute values, where they cannot safely be + expanded automatically; the start/endPrefixMapping event supplies + the information to the application to expand prefixes in those + contexts itself, if necessary. + + Note that start/endPrefixMapping events are not guaranteed to be + properly nested relative to each-other: all + \method{startPrefixMapping()} events will occur before the + corresponding startElement event, and all \method{endPrefixMapping()} + events will occur after the corresponding \method{endElement()} event, + but their order is not guaranteed. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{endPrefixMapping}{prefix} + End the scope of a prefix-URI mapping. + + See \method{startPrefixMapping()} for details. This event will always + occur after the corresponding endElement event, but the order of + endPrefixMapping events is not otherwise guaranteed. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{startElement}{name, attrs} + Signals the start of an element in non-namespace mode. + + The \var{name} parameter contains the raw XML 1.0 name of the + element type as a string and the \var{attrs} parameter holds an + instance of the \class{Attributes} class containing the attributes + of the element. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{endElement}{name} + Signals the end of an element in non-namespace mode. + + The \var{name} parameter contains the name of the element type, just + as with the startElement event. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{startElementNS}{name, qname, attrs} + Signals the start of an element in namespace mode. + + The \var{name} parameter contains the name of the element type as a + (uri, localname) tuple, the \var{qname} parameter the raw XML 1.0 + name used in the source document, and the \var{attrs} parameter + holds an instance of the \class{AttributesNS} class containing the + attributes of the element. + + Parsers may set the \var{qname} parameter to \code{None}, unless the + \code{http://xml.org/sax/features/namespace-prefixes} feature is + activated. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{endElementNS}{name, qname} + Signals the end of an element in namespace mode. + + The \var{name} parameter contains the name of the element type, just + as with the startElementNS event, likewise the \var{qname} parameter. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{characters}{content} + Receive notification of character data. + + The Parser will call this method to report each chunk of character + data. SAX parsers may return all contiguous character data in a + single chunk, or they may split it into several chunks; however, all + of the characters in any single event must come from the same + external entity so that the Locator provides useful information. + + \var{content} may be a Unicode string or a byte string; the + \code{expat} reader module produces always Unicode strings. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{ignorableWhitespace}{} + Receive notification of ignorable whitespace in element content. + + Validating Parsers must use this method to report each chunk + of ignorable whitespace (see the W3C XML 1.0 recommendation, + section 2.10): non-validating parsers may also use this method + if they are capable of parsing and using content models. + + SAX parsers may return all contiguous whitespace in a single + chunk, or they may split it into several chunks; however, all + of the characters in any single event must come from the same + external entity, so that the Locator provides useful + information. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{processingInstruction}{target, data} + Receive notification of a processing instruction. + + The Parser will invoke this method once for each processing + instruction found: note that processing instructions may occur + before or after the main document element. + + A SAX parser should never report an XML declaration (XML 1.0, + section 2.8) or a text declaration (XML 1.0, section 4.3.1) using + this method. +\end{methoddesc} + +\begin{methoddesc}[ContentHandler]{skippedEntity}{name} + Receive notification of a skipped entity. + + The Parser will invoke this method once for each entity + skipped. Non-validating processors may skip entities if they have + not seen the declarations (because, for example, the entity was + declared in an external DTD subset). All processors may skip + external entities, depending on the values of the + \code{http://xml.org/sax/features/external-general-entities} and the + \code{http://xml.org/sax/features/external-parameter-entities} + properties. +\end{methoddesc} + + +\subsection{DTDHandler Objects \label{dtd-handler-objects}} + +\class{DTDHandler} instances provide the following methods: + +\begin{methoddesc}[DTDHandler]{notationDecl}{name, publicId, systemId} + Handle a notation declaration event. +\end{methoddesc} + +\begin{methoddesc}[DTDHandler]{unparsedEntityDecl}{name, publicId, + systemId, ndata} + Handle an unparsed entity declaration event. +\end{methoddesc} + + +\subsection{EntityResolver Objects \label{entity-resolver-objects}} + +\begin{methoddesc}[EntityResolver]{resolveEntity}{publicId, systemId} + Resolve the system identifier of an entity and return either the + system identifier to read from as a string, or an InputSource to + read from. The default implementation returns \var{systemId}. +\end{methoddesc} diff --git a/Doc/lib/xmlsaxreader.tex b/Doc/lib/xmlsaxreader.tex new file mode 100644 index 00000000000..1970c24b0ed --- /dev/null +++ b/Doc/lib/xmlsaxreader.tex @@ -0,0 +1,337 @@ +\section{\module{xml.sax.xmlreader} --- + Interface for XML parsers} + +\declaremodule{standard}{xml.sax.xmlreader} +\modulesynopsis{Interface which SAX-compliant XML parsers must implement.} +\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de} +\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no} + +\versionadded{2.0} + + +SAX parsers implement the \class{XMLReader} interface. They are +implemented in a Python module, which must provide a function +\function{create_parser()}. This function is invoked by +\function{xml.sax.make_parser()} with no arguments to create a new +parser object. + +\begin{classdesc}{XMLReader}{} + Base class which can be inherited by SAX parsers. +\end{classdesc} + +\begin{classdesc}{IncrementalParser}{} + In some cases, it is desirable not to parse an input source at once, + but to feed chunks of the document as they get available. Note that + the reader will normally not read the entire file, but read it in + chunks as well; still \method{parse()} won't return until the entire + document is processed. So these interfaces should be used if the + blocking behaviour of \method{parse()} is not desirable. + + When the parser is instantiated it is ready to begin accepting data + from the feed method immediately. After parsing has been finished + with a call to close the reset method must be called to make the + parser ready to accept new data, either from feed or using the parse + method. + + Note that these methods must \emph{not} be called during parsing, + that is, after parse has been called and before it returns. + + By default, the class also implements the parse method of the + XMLReader interface using the feed, close and reset methods of the + IncrementalParser interface as a convenience to SAX 2.0 driver + writers. +\end{classdesc} + +\begin{classdesc}{Locator}{} + Interface for associating a SAX event with a document location. A + locator object will return valid results only during calls to + DocumentHandler methods; at any other time, the results are + unpredictable. If information is not available, methods may return + \code{None}. +\end{classdesc} + +\begin{classdesc}{InputSource}{\optional{systemId}} + Encapsulation of the information needed by the \class{XMLReader} to + read entities. + + This class may include information about the public identifier, + system identifier, byte stream (possibly with character encoding + information) and/or the character stream of an entity. + + Applications will create objects of this class for use in the + \method{XMLReader.parse()} method and for returning from + EntityResolver.resolveEntity. + + An \class{InputSource} belongs to the application, the + \class{XMLReader} is not allowed to modify \class{InputSource} objects + passed to it from the application, although it may make copies and + modify those. +\end{classdesc} + +\begin{classdesc}{AttributesImpl}{attrs} + This is a dictionary-like object which represents the element + attributes in a \method{startElement()} call. In addition to the + most useful dictionary operations, it supports a number of other + methods as described below. Objects of this class should be + instantiated by readers; \var{attrs} must be a dictionary-like + object. +\end{classdesc} + +\begin{classdesc}{AttributesNSImpl}{attrs, qnames} + Namespace-aware variant of attributes, which will be passed to + \method{startElementNS()}. It is derived from \class{AttributesImpl}, + but understands attribute names as two-tuples of \var{namespaceURI} + and \var{localname}. In addition, it provides a number of methods + expecting qualified names as they appear in the original document. +\end{classdesc} + + +\subsection{XMLReader Objects \label{xmlreader-objects}} + +The \class{XMLReader} interface supports the following methods: + +\begin{methoddesc}[XMLReader]{parse}{source} + Process an input source, producing SAX events. The \var{source} + object can be a system identifier (i.e. a string identifying the + input source -- typically a file name or an URL), a file-like + object, or an \class{InputSource} object. When \method{parse()} + returns, the input is completely processed, and the parser object + can be discarded or reset. As a limitation, the current implementation + only accepts byte streams; processing of character streams is for + further study. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{getContentHandler}{} + Return the current \class{ContentHandler}. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{setContentHandler}{handler} + Set the current \class{ContentHandler}. If no + \class{ContentHandler} is set, content events will be discarded. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{getDTDHandler}{} + Return the current \class{DTDHandler}. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{setDTDHandler}{handler} + Set the current \class{DTDHandler}. If no \class{DTDHandler} is + set, DTD events will be discarded. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{getEntityResolver}{} + Return the current \class{EntityResolver}. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{setEntityResolver}{handler} + Set the current \class{EntityResolver}. If no + \class{EntityResolver} is set, attempts to resolve an external + entity will result in opening the system identifier for the entity, + and fail if it is not available. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{getErrorHandler}{} + Return the current \class{ErrorHandler}. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{setErrorHandler}{handler} + Set the current error handler. If no \class{ErrorHandler} is set, + errors will be raised as exceptions, and warnings will be printed. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{setLocale}{locale} + Allow an application to set the locale for errors and warnings. + + SAX parsers are not required to provide localization for errors and + warnings; if they cannot support the requested locale, however, they + must throw a SAX exception. Applications may request a locale change + in the middle of a parse. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{getFeature}{featurename} + Return the current setting for feature \var{featurename}. If the + feature is not recognized, \exception{SAXNotRecognizedException} is + raised. The well-known featurenames are listed in the module + \module{xml.sax.handler}. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{setFeature}{featurename, value} + Set the \var{featurename} to \var{value}. If the feature is not + recognized, \exception{SAXNotRecognizedException} is raised. If the + feature or its setting is not supported by the parser, + \var{SAXNotSupportedException} is raised. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{getProperty}{propertyname} + Return the current setting for property \var{propertyname}. If the + property is not recognized, a \exception{SAXNotRecognizedException} + is raised. The well-known propertynames are listed in the module + \module{xml.sax.handler}. +\end{methoddesc} + +\begin{methoddesc}[XMLReader]{setProperty}{propertyname, value} + Set the \var{propertyname} to \var{value}. If the property is not + recognized, \exception{SAXNotRecognizedException} is raised. If the + property or its setting is not supported by the parser, + \var{SAXNotSupportedException} is raised. +\end{methoddesc} + + +\subsection{IncrementalParser Objects + \label{incremental-parser-objects}} + +Instances of \class{IncrementalParser} offer the following additional +methods: + +\begin{methoddesc}[IncrementalParser]{feed}{data} + Process a chunk of \var{data}. +\end{methoddesc} + +\begin{methoddesc}[IncrementalParser]{close}{} + Assume the end of the document. That will check well-formedness + conditions that can be checked only at the end, invoke handlers, and + may clean up resources allocated during parsing. +\end{methoddesc} + +\begin{methoddesc}[IncrementalParser]{reset}{} + This method is called after close has been called to reset the + parser so that it is ready to parse new documents. The results of + calling parse or feed after close without calling reset are + undefined.""" +\end{methoddesc} + + +\subsection{Locator Objects \label{locator-objects}} + +Instances of \class{Locator} provide these methods: + +\begin{methoddesc}[Locator]{getColumnNumber}{} + Return the column number where the current event ends. +\end{methoddesc} + +\begin{methoddesc}[Locator]{getLineNumber}{} + Return the line number where the current event ends. +\end{methoddesc} + +\begin{methoddesc}[Locator]{getPublicId}{} + Return the public identifier for the current event. +\end{methoddesc} + +\begin{methoddesc}[Locator]{getSystemId}{} + Return the system identifier for the current event. +\end{methoddesc} + + +\subsection{InputSource Objects \label{input-source-objects}} + +\begin{methoddesc}[InputSource]{setPublicId}{id} + Sets the public identifier of this \class{InputSource}. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{getPublicId}{} + Returns the public identifier of this \class{InputSource}. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{setSystemId}{id} + Sets the system identifier of this \class{InputSource}. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{getSystemId}{} + Returns the system identifier of this \class{InputSource}. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{setEncoding}{encoding} + Sets the character encoding of this \class{InputSource}. + + The encoding must be a string acceptable for an XML encoding + declaration (see section 4.3.3 of the XML recommendation). + + The encoding attribute of the \class{InputSource} is ignored if the + \class{InputSource} also contains a character stream. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{getEncoding}{} + Get the character encoding of this InputSource. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{setByteStream}{bytefile} + Set the byte stream (a Python file-like object which does not + perform byte-to-character conversion) for this input source. + + The SAX parser will ignore this if there is also a character stream + specified, but it will use a byte stream in preference to opening a + URI connection itself. + + If the application knows the character encoding of the byte stream, + it should set it with the setEncoding method. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{getByteStream}{} + Get the byte stream for this input source. + + The getEncoding method will return the character encoding for this + byte stream, or None if unknown. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{setCharacterStream}{charfile} + Set the character stream for this input source. (The stream must be + a Python 1.6 Unicode-wrapped file-like that performs conversion to + Unicode strings.) + + If there is a character stream specified, the SAX parser will ignore + any byte stream and will not attempt to open a URI connection to the + system identifier. +\end{methoddesc} + +\begin{methoddesc}[InputSource]{getCharacterStream}{} + Get the character stream for this input source. +\end{methoddesc} + + +\subsection{AttributesImpl Objects \label{attributes-impl-objects}} + +\class{AttributesImpl} objects implement a portion of the mapping +protocol, and the methods \method{copy()}, \method{get()}, +\method{has_key()}, \method{items()}, \method{keys()}, and +\method{values()}. The following methods are also provided: + +\begin{methoddesc}[AttributesImpl]{getLength}{} + Return the number of attributes. +\end{methoddesc} + +\begin{methoddesc}[AttributesImpl]{getNames}{} + Return the names of the attributes. +\end{methoddesc} + +\begin{methoddesc}[AttributesImpl]{getType}{name} + Returns the type of the attribute \var{name}, which is normally + \code{'CDATA'}. +\end{methoddesc} + +\begin{methoddesc}[AttributesImpl]{getValue}{name} + Return the value of attribute \var{name}. +\end{methoddesc} + +% getValueByQName, getNameByQName, getQNameByName, getQNames available +% here already, but documented only for derived class. + + +\subsection{AttributesNSImpl Objects \label{attributes-ns-impl-objects}} + +\begin{methoddesc}[AttributesNSImpl]{getValueByQName}{name} + Return the value for a qualified name. +\end{methoddesc} + +\begin{methoddesc}[AttributesNSImpl]{getNameByQName}{name} + Return the \code{(\var{namespace}, \var{localname})} pair for a + qualified \var{name}. +\end{methoddesc} + +\begin{methoddesc}[AttributesNSImpl]{getQNameByName}{name} + Return the qualified name for a \code{(\var{namespace}, + \var{localname})} pair. +\end{methoddesc} + +\begin{methoddesc}[AttributesNSImpl]{getQNames}{} + Return the qualified names of all attributes. +\end{methoddesc} diff --git a/Doc/lib/xmlsaxutils.tex b/Doc/lib/xmlsaxutils.tex new file mode 100644 index 00000000000..2ff14716a86 --- /dev/null +++ b/Doc/lib/xmlsaxutils.tex @@ -0,0 +1,48 @@ +\section{\module{xml.sax.saxutils} --- + SAX Utilities} + +\declaremodule{standard}{xml.sax.saxutils} +\modulesynopsis{Convenience functions and classes for use with SAX.} +\sectionauthor{Martin v. L\"owis}{loewis@informatik.hu-berlin.de} +\moduleauthor{Lars Marius Garshol}{larsga@garshol.priv.no} + +\versionadded{2.0} + + +The module \module{xml.sax.saxutils} contains a number of classes and +functions that are commonly useful when creating SAX applications, +either in direct use, or as base classes. + +\begin{funcdesc}{escape}{data\optional{, entities}} + Escape \&, <, and > in a string of data. + + You can escape other strings of data by passing a dictionary as the + optional entities parameter. The keys and values must all be + strings; each key will be replaced with its corresponding value. +\end{funcdesc} + +\begin{classdesc}{XMLGenerator}{\optional{out\optional{, encoding}}} + This class implements the \class{ContentHandler} interface by + writing SAX events back into an XML document. In other words, using + an \class{XMLGenerator} as the content handler will reproduce the + original document being parsed. \var{out} should be a file-like + object which will default to \var{sys.stdout}. \var{encoding} is the + encoding of the output stream which defaults to \code{'iso-8859-1'}. +\end{classdesc} + +\begin{classdesc}{XMLFilterBase}{base} + This class is designed to sit between an \class{XMLReader} and the + client application's event handlers. By default, it does nothing + but pass requests up to the reader and events on to the handlers + unmodified, but subclasses can override specific methods to modify + the event stream or the configuration requests as they pass through. +\end{classdesc} + +\begin{funcdesc}{prepare_input_source}{source\optional{, base}} + This function takes an input source and an optional base URL and + returns a fully resolved \class{InputSource} object ready for + reading. The input source can be given as a string, a file-like + object, or an \class{InputSource} object; parsers will use this + function to implement the polymorphic \var{source} argument to their + \method{parse()} method. +\end{funcdesc}