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

Ned Deily report at bugs.python.org
Thu Apr 30 04:35:08 CEST 2015


Ned Deily added the comment:

(This issue is a followup to your Issue24072.)  Again, while the ElementTree documentation is certainly not nearly as complete as it should be, I don't think this is a documentation error per se.  The key issue is: with which element is each text string associated?  Perhaps this example will help:

>>> root4 = ET.fromstring('<a>ATEXT<b>BTEXT</b>BTAIL</a>')
>>> root4
<Element 'a' at 0x10224c228>
>>> root4.text
'ATEXT'
>>> root4.tail
>>> root4[0]
<Element 'b' at 0x1022ab278>
>>> root4[0].text
'BTEXT'
>>> root4[0].tail
'BTAIL'

As in your original example, any text following the element b is associated with b's tail attribute until a new tag is found, pushing or popping the tree stack.  While the description of the "text" attribute does not explicitly state this, the "tail" attribute description immediately following it does.  This is also explained in more detail in the ElementTree resources on effbot.org that are linked to from the Python Standard Library documentation.  Nevertheless, it probably would be helpful to expand the documentation on this point if someone is willing to put together a documentation patch for review.

With regard to your comment about "well formed xml", I don't think there is anything in the documentation that implies (or should imply) that the distinction between the "text" attribute and the "tail" attribute has anything to do with whether it is well-formed XML.  The tutorial for the third-party lxml package, which provides another implementation of ElementTree, goes into more detail about why, in general, both "text" and "tail" are necessary.

https://docs.python.org/3/library/xml.etree.elementtree.html#additional-resources
http://effbot.org/zone/element.htm#text-content
http://lxml.de/tutorial.html#elements-contain-text

----------
assignee:  -> docs at python
components: +Documentation -XML
nosy: +docs at python, ned.deily
stage:  -> needs patch
versions: +Python 2.7, Python 3.5

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


More information about the docs mailing list