https://github.com/python/cpython/commit/436e68527077581f21f05fc0f8e1a8c1bb769ebf commit: 436e68527077581f21f05fc0f8e1a8c1bb769ebf branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: serhiy-storchaka <[email protected]> date: 2026-09-02T17:18:49Z summary:
[3.14] gh-156829: Fix inaccuracies in the xml.sax documentation (GH-156830) (GH-156843) 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. (cherry picked from commit 6f7941e0aac780d188a9970dbeeda98b2e3c9b88) Co-authored-by: Serhiy Storchaka <[email protected]> files: M Doc/library/xml.sax.handler.rst M Doc/library/xml.sax.reader.rst M Doc/library/xml.sax.rst M Doc/library/xml.sax.utils.rst M Lib/xml/sax/__init__.py M Lib/xml/sax/saxutils.py M Lib/xml/sax/xmlreader.py diff --git a/Doc/library/xml.sax.handler.rst b/Doc/library/xml.sax.handler.rst index 5079fc0f19ea96f..39e593c03a7ed0c 100644 --- a/Doc/library/xml.sax.handler.rst +++ b/Doc/library/xml.sax.handler.rst @@ -75,12 +75,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 @@ -93,6 +96,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 @@ -119,6 +125,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 @@ -128,7 +136,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 @@ -137,20 +145,25 @@ 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 @@ -158,7 +171,28 @@ for the feature and property names. | 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 diff --git a/Doc/library/xml.sax.reader.rst b/Doc/library/xml.sax.reader.rst index b0bc84062e07198..5b6ee5ec4748fbe 100644 --- a/Doc/library/xml.sax.reader.rst +++ b/Doc/library/xml.sax.reader.rst @@ -219,6 +219,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 diff --git a/Doc/library/xml.sax.rst b/Doc/library/xml.sax.rst index 148cb863aca2773..69e930bcdcb7f41 100644 --- a/Doc/library/xml.sax.rst +++ b/Doc/library/xml.sax.rst @@ -32,10 +32,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 @@ -47,18 +47,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 @@ -67,6 +72,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 @@ -139,6 +153,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/>`_ diff --git a/Doc/library/xml.sax.utils.rst b/Doc/library/xml.sax.utils.rst index f93fe374e1c862a..87800d93589f77b 100644 --- a/Doc/library/xml.sax.utils.rst +++ b/Doc/library/xml.sax.utils.rst @@ -84,6 +84,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='') diff --git a/Lib/xml/sax/__init__.py b/Lib/xml/sax/__init__.py index fe4582c6f8b758c..45f69c6bc223c5f 100644 --- a/Lib/xml/sax/__init__.py +++ b/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() diff --git a/Lib/xml/sax/saxutils.py b/Lib/xml/sax/saxutils.py index c1612ea1cebc5d0..77ab9ee2faf0388 100644 --- a/Lib/xml/sax/saxutils.py +++ b/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) diff --git a/Lib/xml/sax/xmlreader.py b/Lib/xml/sax/xmlreader.py index e906121d23b9ef3..98e93113fbb5ab9 100644 --- a/Lib/xml/sax/xmlreader.py +++ b/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. _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
