[docs] [issue24079] xml.etree.ElementTree.Element.text does not conform to the documentation

[Jérôme Laurens]

Jérôme Laurens added the comment:

Since the text and tail notions seem tightly coupled, I would vote for a more detailed explanation in the text doc and a forward link in the tail documentation.


"""
text

    The text attribute holds the text between the element's begin tag and the next tag or None. The tail attribute holds the text between the element's end tag and the next tag or None. For "<a><b>1<c>2<d/>3</c></b>4</a>" xml data, the a element has None for both text and tail attributes, the b element has text '1' and tail '4', the c element has text '2' and tail None, the d element hast text None and tail '3'.

To collect the inner text of an element, see `tostring` with method 'text'.

Applications may store arbitrary objects in this attribute.

tail

    The tail attribute holds the text between the element's end tag and the next tag or None. See `text` for more details.

Applications may store arbitrary objects in this attribute.
"""

It is very important to mention that the 'text' attribute does not always hold a string contrary to what would suggest its name.

BTW, I was not aware of the tostring method with 'text' argument. The fact is that the documentation reads "Returns an (optionally) encoded string containing the XML data." which is misleading because the text is not xml data in general. This also needs to be rephrased or simply removed.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue24079>
_______________________________________