gh-156765: Fix inaccuracies in the ElementTree documentation (GH-156766)

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 09ff4d4)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

Author: serhiy-storchaka

Doc/library/xml.etree.elementtree.rst

@@ -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
@@ -621,10 +620,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
@@ -696,8 +696,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.
@@ -888,11 +887,22 @@ 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.
+
    .. versionchanged:: 3.15
       *attrib* can now be a :class:`frozendict`.
 
@@ -958,14 +968,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)
@@ -1296,8 +1304,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)
@@ -1400,7 +1407,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()
@@ -1479,7 +1487,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()
 

Lib/xml/etree/ElementTree.py

@@ -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.
@@ -359,21 +356,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()