Massive addition of SAX documentation from Martin von Loewis
<loewis@informatik.hu-berlin.de>.
Reorganized to be more like other parts of the documentation in its
arrangement, but with few content changes.
This closes SourceForge patch #101850.
diff --git a/Doc/lib/xmlsax.tex b/Doc/lib/xmlsax.tex
index d09777f..c1b94da 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 @@
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 @@
\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 0000000..77acc3e
--- /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 0000000..1970c24
--- /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 0000000..2ff1471
--- /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}