documentation of ElementTree.find

[patrickvrijlandt]

BPO	12321
Nosy	@terryjreedy, @florentx

^{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 2012-10-14.13:30:51.218>
created_at = <Date 2011-06-13.09:49:21.081>
labels = ['expert-XML', 'easy', 'type-bug']
title = 'documentation of ElementTree.find'
updated_at = <Date 2012-10-14.13:30:51.217>
user = 'https://bugs.python.org/patrickvrijlandt'

bugs.python.org fields:

activity = <Date 2012-10-14.13:30:51.217>
actor = 'eli.bendersky'
assignee = 'none'
closed = True
closed_date = <Date 2012-10-14.13:30:51.218>
closer = 'eli.bendersky'
components = ['XML']
creation = <Date 2011-06-13.09:49:21.081>
creator = 'patrick.vrijlandt'
dependencies = []
files = []
hgrepos = []
issue_num = 12321
keywords = ['easy']
message_count = 4.0
messages = ['138228', '138559', '138653', '172881']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'eli.bendersky', 'flox', 'patrick.vrijlandt']
pr_nums = []
priority = 'normal'
resolution = 'wont fix'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue12321'
versions = ['Python 3.2', 'Python 3.3', 'Python 3.4']

[patrickvrijlandt]

From the python docs for version 3.2:

19.12.3. ElementTree Objects
find(match)
[...] Same as getroot().find(match). [...]

This is not true: tree.find accepts an absolute path (like "/*") , whereas element.find doesn't. Also applies to findall and findtext.

[terryjreedy]

Are you requesting that the doc be changed or the code?
From the title, I would infer the doc (which is much easier ;-).
If so, can you suggest an actual revised text?

[patrickvrijlandt]

[...] Same as getroot().find(match). [...] ->
[...] For a relative path, this is equivalent to getroot().find(match).
Additionally, this form accepts an absolute path. [...]

This is easy, but might not be a very good solution.

Random thoughts/Points to consider:
It does help the novice in debugging his expressions.
A peculiarity of this implementation is documented.
As others have stated, the whole elementpath documentation within the python
docs is incomplete. Should we document the exception but not the rule?
It makes no real sense to do a an absolute search from an element. However,
it's not ambiguous.
lxml does accept the absolute path search from an element.

Actually, I think it's up to Fredrik to decide.

2011/6/18 Terry J. Reedy <report@bugs.python.org>

Terry J. Reedy <tjreedy@udel.edu> added the comment:

Are you requesting that the doc be changed or the code?
>From the title, I would infer the doc (which is much easier ;-).
If so, can you suggest an actual revised text?

----------
nosy: +terry.reedy
stage: -> needs patch
versions: +Python 3.3

---

Python tracker <report@bugs.python.org>
<http://bugs.python.org/issue12321\>

---

[elibendersky]

I think this may be intentional. Absolute searches on a ElementTree are discouraged with a warning:

    def find(self, path, namespaces=None):
        # assert self._root is not None
        if path[:1] == "/":
            path = "." + path
            warnings.warn(
                "This search is broken in 1.3 and earlier, and will be "
                "fixed in a future version.  If you rely on the current "
                "behaviour, change it to %r" % path,
                FutureWarning, stacklevel=2
                )
        return self._root.find(path, namespaces)

See what happens when an "absolute path" is attemped? The code just hacks it into a relative path and prints a menacing warning.

So, I would not change the documentation at this point. However, the problem should go away if and when the XPath support is improved to really support absolute paths.