classification
Title: xml.etree.ElementTree.find(all): docs are wrong
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eli.bendersky, hheimbuerger, python-dev, serhiy.storchaka, techtonik
Priority: normal Keywords: easy, patch

Created on 2011-03-02 01:44 by techtonik, last changed 2013-03-12 13:09 by eli.bendersky. This issue is now closed.

Files
File name Uploaded Description Edit
issue11367_branch27.diff hheimbuerger, 2013-02-23 17:07 Documentation changes for ElementTree.find() and .findtext() for 2.7 review
issue11367_branch32.diff hheimbuerger, 2013-02-23 17:07 Documentation changes for ElementTree.find() and .findtext() for 3.2 review
issue11367_branch27.patch hheimbuerger, 2013-03-08 15:06 Documentation changes for ElementTree on 2.7 review
issue11367_branch32.patch hheimbuerger, 2013-03-08 15:07 Documentation changes for ElementTree on 3.2 review
issue11367_branch27.patch hheimbuerger, 2013-03-11 11:10 Documentation changes for ElementTree on 2.7 review
issue11367_branch32.patch hheimbuerger, 2013-03-11 11:10 Documentation changes for ElementTree on 3.2 review
Messages (20)
msg129847 - (view) Author: anatoly techtonik (techtonik) Date: 2011-03-02 01:44
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.
msg180047 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-01-15 20:12
Already fixed in 3.3+.
msg180392 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-01-22 14:34
Patches to documentation of 3.2 and 2.7 are welcome
msg182769 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-02-23 17:07
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.
msg182770 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-02-23 17:07
Almost identical patch for 3.2, just differs in line numbers.
msg182940 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-02-25 14:06
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)?
msg183046 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-02-26 11:14
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.
msg183055 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-02-26 13:32
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).
msg183060 - (view) Author: anatoly techtonik (techtonik) Date: 2013-02-26 14:32
Thanks for working on this. It is always nice to see things moving.
msg183219 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-02-28 13:54
That sounds good, Eli! I'll check the implementations and then adapt the other ElementTree methods as well. Will take until next week, though.
msg183740 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-03-08 15:06
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?
msg183741 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-03-08 15:07
Patch for 3.2.
msg183820 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-03-09 14:12
Henrik, this patch fails to apply to 3.2

applying issue11367_branch32.patch
patching file Doc/library/xml.etree.elementtree.rst
Hunk #1 FAILED at 411
1 out of 1 hunks FAILED -- saving rejects to file Doc/library/xml.etree.elementtree.rst.rej
patching file Lib/xml/etree/ElementTree.py
Hunk #1 FAILED at 704
Hunk #2 FAILED at 725
Hunk #3 FAILED at 750
3 out of 3 hunks FAILED -- saving rejects to file Lib/xml/etree/ElementTree.py.rej
abort: patch failed to apply


I suspect this may be because of line endings. Are you generating the patches on a Windows machine? All patches to Python should be strictly in Unix format (LF for line ending, not CR LF). Can you configure your hg client and / or editor to do this?

I haven't touched Windows for some time but IIRC TortoiseHg does the right thing if your file is proper. In other words, perhaps it's the editor's fault. Your editor should not insert Windows line-endings into a Unix-y file (which Doc/library/xml.etree.elementtree.rst is).
msg183826 - (view) Author: anatoly techtonik (techtonik) Date: 2013-03-09 16:00
You can use patch.py utility from http://python-patch.googlecode.com/svn-history/trunk/patch.py to apply patch that doesn't have this CRLF problem.
msg183850 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-03-09 21:54
No, according to the devguide patches for Python have to be created with 'hg diff' and applicable with 'hg patch'. I can fix the patch in a number of ways, but I think it's important for a new contributor to learn how to generate a correct patch that can be applied without extra work. This should help the contributor create more useful patches in the future that get committed quickly.
msg183948 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-03-11 11:10
Eli, I fully understand. I was experimenting with working on Cloud9, but it unfortunately has no easy way to extract individual files, I had to recreate them locally. I hope it is correct now.
msg183949 - (view) Author: Henrik Heimbuerger (hheimbuerger) * Date: 2013-03-11 11:10
for 3.2
msg184022 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-03-12 13:07
New changeset 958217164846 by Eli Bendersky in branch '3.2':
Issue #11367: fix documentation of some find* methods in ElementTree
http://hg.python.org/cpython/rev/958217164846

New changeset 4012d4b41b2b by Eli Bendersky in branch '3.3':
Issue #11367: fix documentation of some find* methods in ElementTree
http://hg.python.org/cpython/rev/4012d4b41b2b

New changeset 7ae2c90f1ba2 by Eli Bendersky in branch 'default':
Issue #11367: fix documentation of some find* methods in ElementTree
http://hg.python.org/cpython/rev/7ae2c90f1ba2
msg184023 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-03-12 13:09
New changeset 8e6db2462a77 by Eli Bendersky in branch '2.7':
Issue #11367: fix documentation of some find* methods in ElementTree
http://hg.python.org/cpython/rev/8e6db2462a77
msg184024 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-03-12 13:09
Thanks for the patches - committed with slight adaptations (in default branch the internal documentation switched from comments to docstrings).
History
Date User Action Args
2013-03-12 13:09:54eli.benderskysetstatus: open -> closed
resolution: fixed
messages: + msg184024

stage: needs patch -> resolved
2013-03-12 13:09:09python-devsetmessages: + msg184023
2013-03-12 13:07:12python-devsetnosy: + python-dev
messages: + msg184022
2013-03-11 11:10:40hheimbuergersetfiles: + issue11367_branch32.patch

messages: + msg183949
2013-03-11 11:10:20hheimbuergersetfiles: + issue11367_branch27.patch

messages: + msg183948
2013-03-09 21:54:22eli.benderskysetmessages: + msg183850
2013-03-09 16:00:28techtoniksetmessages: + msg183826
2013-03-09 14:12:35eli.benderskysetmessages: + msg183820
2013-03-08 15:07:36hheimbuergersetfiles: + issue11367_branch32.patch

messages: + msg183741
2013-03-08 15:06:03hheimbuergersetfiles: + issue11367_branch27.patch

messages: + msg183740
2013-02-28 13:54:36hheimbuergersetmessages: + msg183219
2013-02-26 14:32:42techtoniksetmessages: + msg183060
2013-02-26 13:32:43eli.benderskysetmessages: + msg183055
2013-02-26 11:14:45hheimbuergersetmessages: + msg183046
2013-02-25 14:06:44eli.benderskysetmessages: + msg182940
2013-02-23 17:07:55hheimbuergersetfiles: + issue11367_branch32.diff

messages: + msg182770
2013-02-23 17:07:12hheimbuergersetfiles: + issue11367_branch27.diff

nosy: + hheimbuerger
messages: + msg182769

keywords: + patch
2013-01-22 14:34:55eli.benderskysetmessages: + msg180392
2013-01-15 20:12:43serhiy.storchakasettype: enhancement
versions: + Python 2.7, Python 3.2, - Python 2.6
keywords: + easy
nosy: + serhiy.storchaka, eli.bendersky

messages: + msg180047
stage: needs patch
2011-03-02 01:44:31techtonikcreate