Incorrect statements in the xml.etree.ElementTree documentation

[serhiy-storchaka]

Several statements in the documentation of xml.etree.ElementTree do not match the behaviour.

• The parser argument of iterparse() is described as "a subclass of XMLParser", but it is an instance of it.

• XMLParser.feed() is described as accepting encoded data and XMLPullParser.feed() as accepting bytes, but both accept a string as well, and any bytes-like object.

• The element tag, the attribute names and values, the text of a comment and the data of TreeBuilder.data() are described as being "either bytestrings or Unicode strings". This is a Python 2 leftover. In Python 3 bytes are either rejected by the serializer or written as a repr:

>>> ET.tostring(ET.Comment(b'spam'))
b"<!--b'spam'-->"
>>> ET.tostring(ET.Element('t', {b'a': 'v'}))
b'<t b\'a\'="v" />'
>>> ET.tostring(ET.Element(b'tag'))
TypeError: cannot serialize b'tag' (type bytes)

The claims about bytes are better removed than corrected: the accurate description is more complicated than it seems, because a tag can also be None (a fragment) or a factory like Comment, and an attribute value can be a QName or, for the HTML method, None.

Linked PRs

• gh-156765: Fix inaccuracies in the ElementTree documentation #156766
• [3.15] gh-156765: Fix inaccuracies in the ElementTree documentation (GH-156766) #156848
• [3.14] gh-156765: Fix inaccuracies in the ElementTree documentation (GH-156766) #156849
• [3.13] gh-156765: Fix inaccuracies in the ElementTree documentation (GH-156766) #156850

[serhiy-storchaka]

Two more inaccurate statements, about Element.keys() and Element.items():

• They are described as returning a list and a sequence, but in the Python implementation they return the dict views returned by attrib.keys() and attrib.items(). Only the C implementation returns lists. The docstrings ("Get list of attribute names", "Return a list of (name, value) tuples") make the same claim.

• The attributes are said to be returned "in an arbitrary order". This dates back to the original ElementTree import, when attrib was an unordered dict. Since attribute order is now preserved (ElementTree not preserving attribute order #78341 in 3.8, and dicts keep the insertion order), both implementations return them in document order for a parsed document.

The wording is fixed in PR #156766 without changing the behaviour; the difference in the return type between the two implementations is left as is.