[issue24724] Element.findall documentation misleading

[Eric S]

Eric S added the comment:

To my preference, the drop-in is verbose and I got a little confused on first read. The current documentation and example seem mostly OK to me. 

If we leave "children" as in "all <country> children of *root*", it doesn't illuminate the fact that if root had a great-great-grandchild also named <country>, then it would return that as well.

The only way I can think to simply clarify it is to use "direct descendents" or "all direct descendents".

Here's how the phrase "direct children" slipped me up when I first read the docs re:findall():

I thought I could rebuild the XML tree like this:

def rebuild_XML_as_whatever(parent)
    for child in parent.findall()
       code_that_attaches_child
       rebuild_XML_as_whatever(child)

instead I had to do this:

def rebuild_XML_as_whatever(parent)
    descendns = parent.findall("./")
    for child_n in range(len(descendns)):
        child = descendns[child_n]

        code_that_attaches_child
        rebuild_XML_as_whatever(child)        

RE:iterfind() if it fits a new format that's fine but renaming would, of course, interfere with backwards compatibility.

----------

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