https://github.com/python/cpython/commit/798da2c9401ee470104898e3d8c886b23bb70eaa
commit: 798da2c9401ee470104898e3d8c886b23bb70eaa
branch: 3.13
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2026-09-02T17:46:50Z
summary:
[3.13] gh-156765: Fix inaccuracies in the ElementTree documentation (GH-156766)
(GH-156850)
Corrected:
* the parser argument of iterparse() is an instance of XMLParser or its
subclass, not a subclass;
* feed() accepts a string as well as encoded data;
* keys() and items() do not return a list in the Python implementation, and
the attributes are no longer returned in an arbitrary order.
Removed the claims that the element tag, the attribute names and values, the
text of a comment and the data of TreeBuilder.data() can be bytes. It is a
Python 2 leftover. Documented instead what they can be.
(cherry picked from commit 09ff4d443f0dc748bfa4d73c9bb6a22ae8a97993)
files:
M Doc/library/xml.etree.elementtree.rst
M Lib/xml/etree/ElementTree.py
diff --git a/Doc/library/xml.etree.elementtree.rst
b/Doc/library/xml.etree.elementtree.rst
index 00075ac2a23e6b..80af5c2835b2de 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -553,10 +553,9 @@ Functions
.. function:: Comment(text=None)
Comment element factory. This factory function creates a special element
- that will be serialized as an XML comment by the standard serializer. The
- comment string can be either a bytestring or a Unicode string. *text* is a
- string containing the comment string. Returns an element instance
- representing a comment.
+ that will be serialized as an XML comment by the standard serializer.
+ *text* is a string containing the comment string.
+ Returns an element instance representing a comment.
Note that :class:`XMLParser` skips over comments in the input
instead of creating comment objects for them. An :class:`ElementTree` will
@@ -623,10 +622,11 @@ Functions
``"pi"``, ``"start-ns"`` and ``"end-ns"``
(the "ns" events are used to get detailed namespace
information). If *events* is omitted, only ``"end"`` events are reported.
- *parser* is an optional parser instance. If not given, the standard
- :class:`XMLParser` parser is used. *parser* must be a subclass of
- :class:`XMLParser` and can only use the default :class:`TreeBuilder` as a
- target. Returns an :term:`iterator` providing ``(event, elem)`` pairs;
+ *parser* is an optional parser instance.
+ If not given, the standard :class:`XMLParser` parser is used.
+ *parser* must be an instance of :class:`XMLParser` or its subclass
+ and can only use the default :class:`TreeBuilder` as a target.
+ Returns an :term:`iterator` providing ``(event, elem)`` pairs;
it has a ``root`` attribute that references the root element of the
resulting XML tree once *source* is fully read.
The iterator has the :meth:`!close` method that closes the internal
@@ -694,8 +694,7 @@ Functions
Subelement factory. This function creates an element instance, and appends
it to an existing element.
- The element name, attribute names, and attribute values can be either
- bytestrings or Unicode strings. *parent* is the parent element. *tag* is
+ *parent* is the parent element. *tag* is
the subelement name. *attrib* is an optional dictionary, containing element
attributes. *extra* contains additional attributes, given as keyword
arguments. Returns an element instance.
@@ -880,11 +879,21 @@ Element Objects
Element class. This class defines the Element interface, and provides a
reference implementation of this interface.
- The element name, attribute names, and attribute values can be either
- bytestrings or Unicode strings. *tag* is the element name. *attrib* is
+ *tag* is the element name. *attrib* is
an optional dictionary, containing element attributes. *extra* contains
additional attributes, given as keyword arguments.
+ The element name and the attribute names and values are strings or
+ :class:`QName` instances, and the text and the tail are strings or
+ ``None``.
+ The element name can also be :func:`Comment` or
+ :func:`ProcessingInstruction`, which are used for special elements.
+ If it is ``None``, the element itself is not serialized: only its text
+ and its children are written, and its attributes are ignored.
+ This can be used for a fragment which contains several elements.
+ With ``method="html"`` the attribute value can also be ``None``,
+ which produces an empty attribute (such as ``checked``).
+ Other objects can be stored in the tree, but they cannot be serialized.
.. attribute:: tag
@@ -944,14 +953,12 @@ Element Objects
.. method:: items()
- Returns the element attributes as a sequence of (name, value) pairs. The
- attributes are returned in an arbitrary order.
+ Returns the element attributes as (name, value) pairs.
.. method:: keys()
- Returns the elements attribute names as a list. The names are returned
- in an arbitrary order.
+ Returns the element attribute names.
.. method:: set(key, value)
@@ -1282,8 +1289,7 @@ TreeBuilder Objects
.. method:: data(data)
- Adds text to the current element. *data* is a string. This should be
- either a bytestring, or a Unicode string.
+ Adds text to the current element. *data* is a string.
.. method:: end(tag)
@@ -1386,7 +1392,8 @@ XMLParser Objects
.. method:: feed(data)
- Feeds data to the parser. *data* is encoded data.
+ Feeds data to the parser. *data* is a string
+ or encoded data (:class:`bytes` or a :term:`bytes-like object`).
.. method:: flush()
@@ -1465,7 +1472,8 @@ XMLPullParser Objects
.. method:: feed(data)
- Feed the given bytes data to the parser.
+ Feed the given data to the parser. *data* is a string
+ or encoded data (:class:`bytes` or a :term:`bytes-like object`).
.. method:: flush()
diff --git a/Lib/xml/etree/ElementTree.py b/Lib/xml/etree/ElementTree.py
index 2429ef53d1804a..cf40d7c93be83c 100644
--- a/Lib/xml/etree/ElementTree.py
+++ b/Lib/xml/etree/ElementTree.py
@@ -135,9 +135,6 @@ class Element:
want to check if an element is truly empty, you should check BOTH
its length AND its text attribute.
- The element tag, attribute names, and attribute values can be either
- bytes or strings.
-
*tag* is the element name. *attrib* is an optional dictionary containing
element attributes. *extra* are additional element attributes given as
keyword arguments.
@@ -358,21 +355,17 @@ def set(self, key, value):
self.attrib[key] = value
def keys(self):
- """Get list of attribute names.
+ """Get attribute names.
- Names are returned in an arbitrary order, just like an ordinary
- Python dict. Equivalent to attrib.keys()
+ Equivalent to attrib.keys()
"""
return self.attrib.keys()
def items(self):
- """Get element attributes as a sequence.
-
- The attributes are returned in arbitrary order. Equivalent to
- attrib.items().
+ """Get element attributes as (name, value) pairs.
- Return a list of (name, value) tuples.
+ Equivalent to attrib.items().
"""
return self.attrib.items()
_______________________________________________
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]
