Skip to content

gh-156765: Fix inaccuracies in the ElementTree documentation #156766

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
serhiy-storchaka merged 4 commits into from
Sep 2, 2026
Merged

gh-156765: Fix inaccuracies in the ElementTree documentation #156766

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
04cefb4
gh-156765: Fix inaccuracies in the ElementTree documentation
serhiy-storchaka Sep 1, 2026
f4eee16
Rewrap the description of the parser argument of iterparse()
serhiy-storchaka Sep 1, 2026
d502d73
Fix the description of Element.keys() and Element.items()
serhiy-storchaka Sep 1, 2026
26cadbb
Document what can be the element name, the attributes and the text
serhiy-storchaka Sep 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
gh-156765: Fix inaccuracies in the ElementTree documentation 
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.
Bytes are no longer said to be supported for the element tag, the attribute
names and values and the text of a comment: they are either rejected by the
serializer or written as a repr.
  • Loading branch information
@serhiy-storchaka
serhiy-storchaka committed Sep 1, 2026
commit 04cefb457cfb22e9bd0707897b33aa9202fd7df7
28 changes: 13 additions & 15 deletions Doc/library/xml.etree.elementtree.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -551,10 +551,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
Expand Down Expand Up @@ -622,9 +621,9 @@ Functions
(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;
: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
Expand Down Expand Up @@ -696,8 +695,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.
Expand Down Expand Up @@ -888,8 +886,7 @@ 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.

Expand Down Expand Up @@ -1296,8 +1293,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)
Expand Down Expand Up @@ -1400,7 +1396,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()
Expand Down Expand Up @@ -1479,7 +1476,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()

Expand Down
3 changes: 0 additions & 3 deletions Lib/xml/etree/ElementTree.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,9 +129,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.
Expand Down
Loading