diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index bdd5fd564eed1f..8b94c2675c1d48 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 7ed22788d05043..2efaae0b100353 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. @@ -362,21 +359,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()