gh-156829: Fix inaccuracies in the xml.sax documentation (GH-156830)

Corrected:

* the name of the errorHandler argument of parse() and parseString();
* the default value of the parser_list argument of make_parser();
* the description of the source of parse();
* the types of the declaration-handler and dom-node properties;
* the way in which names are interned;
* the description of IncrementalParser.

Documented:

* default_parser_list and SAXReaderNotAvailable;
* property_encoding and property_interning_dict;
* IncrementalParser.prepareParser();
* XMLFilterBase.getParent() and setParent();
* which features and properties the parser based on Expat does not support.

Added missing docstrings to parse(), parseString(), AttributesImpl and
XMLGenerator.

Author: serhiy-storchaka

Doc/library/xml.sax.handler.rst

@@ -72,12 +72,15 @@ for the feature and property names.
      optionally do not report original prefixed names (default).
    | access: (parsing) read-only; (not parsing) read/write
 
+   The parser based on :mod:`xml.parsers.expat` does not support this feature.
+
 
 .. data:: feature_string_interning
 
    | value: ``"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.
+     local names are interned in a dictionary
+     (see :data:`property_interning_dict`).
    | false: Names are not necessarily interned, although they may be (default).
    | access: (parsing) read-only; (not parsing) read/write
 
@@ -90,6 +93,9 @@ for the feature and property names.
    | false: Do not report validation errors.
    | access: (parsing) read-only; (not parsing) read/write
 
+   The parser based on :mod:`xml.parsers.expat` does not support this feature,
+   because Expat is a non-validating parser.
+
 
 .. data:: feature_external_ges
 
@@ -116,6 +122,8 @@ for the feature and property names.
      DTD subset.
    | access: (parsing) read-only; (not parsing) read/write
 
+   The parser based on :mod:`xml.parsers.expat` does not support this feature.
+
 
 .. data:: all_features
 
@@ -125,7 +133,7 @@ for the feature and property names.
 .. data:: property_lexical_handler
 
    | value: ``"http://xml.org/sax/properties/lexical-handler"``
-   | data type: xml.sax.handler.LexicalHandler (not supported in Python 2)
+   | data type: :class:`~xml.sax.handler.LexicalHandler`
    | description: An optional extension handler for lexical events like
      comments.
    | access: read/write
@@ -134,28 +142,54 @@ for the feature and property names.
 .. data:: property_declaration_handler
 
    | value: ``"http://xml.org/sax/properties/declaration-handler"``
-   | data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)
+   | data type: an object implementing the SAX2 ``DeclHandler`` interface
    | description: An optional extension handler for DTD-related events other
      than notations and unparsed entities.
    | access: read/write
 
+   No parser in the standard library supports this property,
+   and the standard library provides no such handler.
+
 
 .. data:: property_dom_node
 
    | value: ``"http://xml.org/sax/properties/dom-node"``
-   | data type: org.w3c.dom.Node (not supported in Python 2)
+   | data type: :class:`xml.dom.Node`
    | 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
 
+   No parser in the standard library supports this property.
+
 
 .. data:: property_xml_string
 
    | value: ``"http://xml.org/sax/properties/xml-string"``
    | data type: Bytes
    | description: The literal string of characters that was the source for the
      current event.
-   | access: read-only
+   | access: read-only, and only during a handler callback
+
+
+.. data:: property_encoding
+
+   | value: ``"http://www.python.org/sax/properties/encoding"``
+   | data type: String
+   | description: The name of the encoding to assume for input data.
+   | access: read/write
+
+   No parser in the standard library supports this property.
+
+
+.. data:: property_interning_dict
+
+   | value: ``"http://www.python.org/sax/properties/interning-dict"``
+   | data type: Dictionary
+   | description: The dictionary used to intern names,
+     or ``None`` if names are not interned.
+     Setting it enables interning, as does the
+     :data:`feature_string_interning` feature.
+   | access: read/write
 
 
 .. data:: all_properties

Doc/library/xml.sax.reader.rst

@@ -216,6 +216,15 @@ Instances of :class:`IncrementalParser` offer the following additional methods:
    allocated during parsing.
 
 
+.. method:: IncrementalParser.prepareParser(source)
+
+   Prepare the parser for parsing *source*, an
+   :class:`InputSource` instance.
+   It is called by :meth:`~XMLReader.parse` before feeding the data.
+   The parser implementation must override this method;
+   the default implementation raises :exc:`NotImplementedError`.
+
+
 .. method:: IncrementalParser.reset()
 
    This method is called after close has been called to reset the parser so that it

Doc/library/xml.sax.rst

@@ -28,10 +28,10 @@ the SAX API.
    :meth:`~xml.sax.xmlreader.XMLReader.setFeature` on the parser object
    and argument :data:`~xml.sax.handler.feature_external_ges`.
 
-The convenience functions are:
+The convenience functions and data are:
 
 
-.. function:: make_parser(parser_list=[])
+.. function:: make_parser(parser_list=())
 
    Create and return a SAX :class:`~xml.sax.xmlreader.XMLReader` object.  The
    first parser found will
@@ -43,18 +43,23 @@ The convenience functions are:
       The *parser_list* argument can be any iterable, not just a list.
 
 
-.. function:: parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())
+.. function:: parse(filename_or_stream, handler, errorHandler=handler.ErrorHandler())
 
    Create a SAX parser and use it to parse a document.  The document, passed in as
-   *filename_or_stream*, can be a filename or a file object.  The *handler*
+   *filename_or_stream*, can be a system identifier (a string identifying the
+   input source -- typically a file name or a URL),
+   a :term:`path-like <path-like object>` object, or a file object.
+   A system identifier which does not refer to an existing file
+   is opened with :func:`urllib.request.urlopen`.
+   The *handler*
    parameter needs to be a SAX :class:`~handler.ContentHandler` instance.  If
-   *error_handler* is given, it must be a SAX :class:`~handler.ErrorHandler`
+   *errorHandler* is given, it must be a SAX :class:`~handler.ErrorHandler`
    instance; if
    omitted,  :exc:`SAXParseException` will be raised on all errors.  There is no
    return value; all work must be done by the *handler* passed in.
 
 
-.. function:: parseString(string, handler, error_handler=handler.ErrorHandler())
+.. function:: parseString(string, handler, errorHandler=handler.ErrorHandler())
 
    Similar to :func:`parse`, but parses from a buffer *string* received as a
    parameter.  *string* must be a :class:`str` instance or a
@@ -63,6 +68,15 @@ The convenience functions are:
    .. versionchanged:: 3.5
       Added support of :class:`str` instances.
 
+
+.. data:: default_parser_list
+
+   The list of the names of modules which are tried by :func:`make_parser`
+   after the modules named in its *parser_list* argument.
+   It contains ``'xml.sax.expatreader'``, or, if the
+   :envvar:`!PY_SAX_PARSER` environment variable is set and the environment
+   is not ignored, the comma-separated list of module names taken from it.
+
 A typical SAX application uses three kinds of objects: readers, handlers and
 input sources.  "Reader" in this context is another term for parser, i.e. some
 piece of code that reads the bytes or characters from the input source, and
@@ -135,6 +149,14 @@ classes.
    class for similar purposes.
 
 
+.. exception:: SAXReaderNotAvailable(msg, exception=None)
+
+   Subclass of :exc:`SAXNotSupportedException` raised when no parser is
+   available.  A parser module raises it when it is imported or during
+   parsing if the parser it provides cannot be used, and :func:`make_parser`
+   raises it if no module from the tried ones provides a usable parser.
+
+
 .. seealso::
 
    `SAX: The Simple API for XML <http://www.saxproject.org/>`_

Doc/library/xml.sax.utils.rst

@@ -81,6 +81,15 @@ or as base classes.
    override specific methods to modify the event stream or the configuration
    requests as they pass through.
 
+   .. method:: getParent()
+
+      Return the parent reader, or ``None`` if it is not set.
+
+
+   .. method:: setParent(parent)
+
+      Set the parent reader, which the events are read from.
+
 
 .. function:: prepare_input_source(source, base='')
 

Lib/xml/sax/__init__.py

@@ -27,12 +27,21 @@
 
 
 def parse(source, handler, errorHandler=ErrorHandler()):
+    """Parse an XML document with the default parser.
+
+    source is a system identifier, a path-like object or a file object,
+    handler is a ContentHandler instance, and errorHandler is an
+    ErrorHandler instance.  All work is done by the handler."""
     parser = make_parser()
     parser.setContentHandler(handler)
     parser.setErrorHandler(errorHandler)
     parser.parse(source)
 
 def parseString(string, handler, errorHandler=ErrorHandler()):
+    """Parse an XML document from a string with the default parser.
+
+    string is a str or a bytes-like object, the other arguments are the
+    same as for parse()."""
     import io
     if errorHandler is None:
         errorHandler = ErrorHandler()

Lib/xml/sax/saxutils.py

@@ -110,6 +110,7 @@ def __getattr__(self, name):
                             write_through=True)
 
 class XMLGenerator(handler.ContentHandler):
+    """Content handler which writes the events back as an XML document."""
 
     def __init__(self, out=None, encoding="iso-8859-1", short_empty_elements=False):
         handler.ContentHandler.__init__(self)

Lib/xml/sax/xmlreader.py

@@ -89,7 +89,7 @@ def setProperty(self, name, value):
         raise SAXNotRecognizedException("Property '%s' not recognized" % name)
 
 class IncrementalParser(XMLReader):
-    """This interface adds three extra methods to the XMLReader
+    """This interface adds four extra methods to the XMLReader
     interface that allow XML parsers to support incremental
     parsing. Support for this interface is optional, since not all
     underlying XML parsers support this functionality.
@@ -104,7 +104,7 @@ class IncrementalParser(XMLReader):
     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
+    interface using the prepareParser, feed and close methods of the
     IncrementalParser interface as a convenience to SAX 2.0 driver
     writers."""
 
@@ -274,6 +274,7 @@ def getCharacterStream(self):
 # ===== ATTRIBUTESIMPL =====
 
 class AttributesImpl:
+    """Implementation of the Attributes interface."""
 
     def __init__(self, attrs):
         """Non-NS-aware implementation.