Incorrect and missing statements in the xml.parsers.expat documentation

[serhiy-storchaka]

Several statements in the documentation of xml.parsers.expat do not match the behaviour, and a part of the API is not documented at all. Some docstrings have the same problems.

Incorrect:

• GetInputContext() is described as returning a string, but it returns bytes. Its result also extends to the end of the currently buffered input, so it can contain the data of the following events.
• Parse() is described as parsing "the string data", but data can be a bytes-like object as well as a string, and if it is a string, the encoding declaration is ignored.
• ParseFile() is described as reading from a file whose read() returns "the empty string when there's no more data", but only binary files are supported (expat ParseFile expects bytes, not string #60930).
• XML_ERROR_XML_DECL is described as "The document contained no document element at all". It means "XML declaration not well-formed"; the given description belongs to XML_ERROR_NO_ELEMENTS.
• UnparsedEntityDeclHandler is described as "only present for version 1.2 of the Expat library", but it is present and called with Expat 2.8.4.
• The docstring of GetSpecifiedAttributeCount() omits that the result is only meaningful if ordered_attributes is true.

Not documented:

• the intern parameter of ParserCreate() and the intern attribute, which xml.sax uses for the string interning feature;
• the namespace_prefixes attribute;
• the SkippedEntityHandler handler;
• XML_CTYPE_MIXED and XML_CTYPE_NAME, whose descriptions are empty;
• EXPAT_VERSION, version_info and features, although the XML security documentation already refers to EXPAT_VERSION.

Also, the notes about Expat versions 1.2 and 1.95.0 are obsolete, the list of attribute types in AttlistDeclHandler ends with "...", and all content model constants are marked with :noindex: although they have no other description, so they cannot be referenced.

Linked PRs

• gh-156821: Fix inaccuracies in the xml.parsers.expat documentation #156822
• [3.15] gh-156821: Fix inaccuracies in the xml.parsers.expat documentation (GH-156822) #156852
• [3.14] gh-156821: Fix inaccuracies in the xml.parsers.expat documentation (GH-156822) #156853
• [3.13] gh-156821: Fix inaccuracies in the xml.parsers.expat documentation (GH-156822) #156854