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.

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:

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}

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}

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}