[issue11367] xml.etree.ElementTree.find(all): docs are wrong
New submission from anatoly techtonik <techtonik@gmail.com>: 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. ---------- assignee: docs@python components: Documentation messages: 129847 nosy: docs@python, techtonik priority: normal severity: normal status: open title: xml.etree.ElementTree.find(all): docs are wrong versions: Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Serhiy Storchaka added the comment: Already fixed in 3.3+. ---------- keywords: +easy nosy: +eli.bendersky, serhiy.storchaka stage: -> needs patch type: -> enhancement versions: +Python 2.7, Python 3.2 -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Eli Bendersky added the comment: Patches to documentation of 3.2 and 2.7 are welcome ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Henrik Heimbuerger added the comment: 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. ---------- keywords: +patch nosy: +hheimbuerger Added file: http://bugs.python.org/file29184/issue11367_branch27.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Henrik Heimbuerger added the comment: Almost identical patch for 3.2, just differs in line numbers. ---------- Added file: http://bugs.python.org/file29185/issue11367_branch32.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Eli Bendersky added the comment: 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)? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Henrik Heimbuerger added the comment: 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.Elemen... Is that intentional? If so, I'll happily provide adjusted patches. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Eli Bendersky added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
anatoly techtonik added the comment: Thanks for working on this. It is always nice to see things moving. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Henrik Heimbuerger added the comment: That sounds good, Eli! I'll check the implementations and then adapt the other ElementTree methods as well. Will take until next week, though. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Henrik Heimbuerger added the comment: 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? ---------- Added file: http://bugs.python.org/file29349/issue11367_branch27.txt _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Henrik Heimbuerger added the comment: Patch for 3.2. ---------- Added file: http://bugs.python.org/file29350/issue11367_branch32.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Eli Bendersky added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
anatoly techtonik added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Eli Bendersky added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Henrik Heimbuerger added the comment: 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. ---------- Added file: http://bugs.python.org/file29374/issue11367_branch27.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Henrik Heimbuerger added the comment: for 3.2 ---------- Added file: http://bugs.python.org/file29375/issue11367_branch32.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Roundup Robot added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
Eli Bendersky added the comment: Thanks for the patches - committed with slight adaptations (in default branch the internal documentation switched from comments to docstrings). ---------- resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11367> _______________________________________
participants (5)
-
anatoly techtonik -
Eli Bendersky
-
Henrik Heimbuerger
-
Roundup Robot
-
Serhiy Storchaka