Repository navigation
Incorrect statements in the xml.etree.ElementTree documentation #156765
Description
Several statements in the documentation of xml.etree.ElementTree do not match the behaviour.
-
The parser argument of
iterparse()is described as "a subclass ofXMLParser", but it is an instance of it. -
XMLParser.feed()is described as accepting encoded data andXMLPullParser.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
Activity
serhiy-storchaka commentedon Sep 1, 2026
Two more inaccurate statements, about
Element.keys()andElement.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()andattrib.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
attribwas 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.
gh-156765: Fix inaccuracies in the ElementTree documentation (GH-156766)
[3.13] gh-156765: Fix inaccuracies in the ElementTree documentation (G…
[3.14] gh-156765: Fix inaccuracies in the ElementTree documentation (G…
pythongh-156765: Fix inaccuracies in the ElementTree documentation (p…
[3.15] gh-156765: Fix inaccuracies in the ElementTree documentation (G…