xml.etree.ElementTree.find(all): docs are wrong

[techtonik]

BPO	11367
Nosy	@serhiy-storchaka
Files	issue11367_branch27.diff: Documentation changes for ElementTree.find() and .findtext() for 2.7 issue11367_branch32.diff: Documentation changes for ElementTree.find() and .findtext() for 3.2 issue11367_branch27.patch: Documentation changes for ElementTree on 2.7 issue11367_branch32.patch: Documentation changes for ElementTree on 3.2 issue11367_branch27.patch: Documentation changes for ElementTree on 2.7 issue11367_branch32.patch: Documentation changes for ElementTree on 3.2

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2013-03-12.13:09:54.848>
created_at = <Date 2011-03-02.01:44:31.280>
labels = ['easy', 'type-feature', 'docs']
title = 'xml.etree.ElementTree.find(all): docs are wrong'
updated_at = <Date 2013-03-12.13:09:54.847>
user = 'https://bugs.python.org/techtonik'

bugs.python.org fields:

activity = <Date 2013-03-12.13:09:54.847>
actor = 'eli.bendersky'
assignee = 'docs@python'
closed = True
closed_date = <Date 2013-03-12.13:09:54.848>
closer = 'eli.bendersky'
components = ['Documentation']
creation = <Date 2011-03-02.01:44:31.280>
creator = 'techtonik'
dependencies = []
files = ['29184', '29185', '29349', '29350', '29374', '29375']
hgrepos = []
issue_num = 11367
keywords = ['patch', 'easy']
message_count = 20.0
messages = ['129847', '180047', '180392', '182769', '182770', '182940', '183046', '183055', '183060', '183219', '183740', '183741', '183820', '183826', '183850', '183948', '183949', '184022', '184023', '184024']
nosy_count = 6.0
nosy_names = ['techtonik', 'eli.bendersky', 'docs@python', 'python-dev', 'serhiy.storchaka', 'hheimbuerger']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue11367'
versions = ['Python 2.7', 'Python 3.2']

[techtonik]

ElementTree.find(path) docs say:

"Finds the first toplevel element with given tag. Same as getroot().find(path). path is the element to look for."

That's not true. path can take the form of "//tag" to find any child element with given tag, not strictly top level.

[serhiy-storchaka]

Already fixed in 3.3+.

[elibendersky]

Patches to documentation of 3.2 and 2.7 are welcome

[hheimbuerger]

Attached patch file for the 2.7 branch. They not only touch find(), but also findtext(), which has the mistake in the documentation. Also does some related changes in the module's code comments.

[hheimbuerger]

Almost identical patch for 3.2, just differs in line numbers.

[elibendersky]

Henrik, there's no need to provide more information in 3.2 and 2.7 than in 3.3 and default. Could you just align your patches with those (i.e. same wording in the documentation)?

[hheimbuerger]

Eli, I tried to preserve the style (and detail) of the rest of the docs of the respective version. If I bring the 3.3 version of find() into 2.7, then it will have a lot less detail than f.e. findall() as a sibling method on the same class: http://docs.python.org/2/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree

Is that intentional? If so, I'll happily provide adjusted patches.

[elibendersky]

Henrik. Yes, I think the change in 3.3 was intentional in order to avoid duplication that can be a source of errors. If ET.find() does exactly what ET.getroot().find() does, it suffices to mention it with a link. Since Element docs come first and arguably Element's methods are much more widely used, I think it's a good tradeoff. Any duplication is yet another place to remember fixing when problems in the documentation are discovered (like the original problem leading to this issue).

So for consistency you can make all methods point to Element's methods (just backport 3.3's version, but please verify that the code behavior is indeed as documented in earlier versions).

[techtonik]

Thanks for working on this. It is always nice to see things moving.

[hheimbuerger]

That sounds good, Eli! I'll check the implementations and then adapt the other ElementTree methods as well. Will take until next week, though.

[hheimbuerger]

Brought the ElementTree docs for find(), findtext() and findall() in line with the default branch (now they are just referencing the methods from Element).

Made the same changes in the method comments of the implementation.

Separate patches for 2.7 and 3.2.

Note that the implementation method comments in default (and I assume 3.3) are still wrong. Would you accept patches for that as well?