This isn't just a documentation issue. A function named getiterator(),
for which the docs say that it returns an iterator, should return an
iterator, not just an iterable. They have different semantics and can't
be used interchangeably, so the behaviour of getiterator() in
ElementTree is wrong. I was using this in my program:

iterator = element.getiterator()
next(iterator)
subelement = next(iterator)

Which broke when I tried switching to ElementTree from cElementTree,
even though the docs tell me that I'll get an iterator there.

Also, for findall() and friends, is there any reason why we can't stick
to either an iterator or list, and not both? The API will be more clear
if findall() always returned a list, or always an iterator, regardless
of the implementation. It is currently not clear what will happen if I do:

for x in tree.findall(path):
     mutate_tree(tree, x)