3 # $Id: ElementPath.py 3375 2008-02-13 08:05:08Z fredrik $
5 # limited xpath support for element trees
8 # 2003-05-23 fl created
9 # 2003-05-28 fl added support for // etc
10 # 2003-08-27 fl fixed parsing of periods in element names
11 # 2007-09-10 fl new selection engine
12 # 2007-09-12 fl fixed parent selector
13 # 2007-09-13 fl added iterfind; changed findall to return a list
14 # 2007-11-30 fl added namespaces support
15 # 2009-10-30 fl added child element value filter
17 # Copyright (c) 2003-2009 by Fredrik Lundh. All rights reserved.
19 # fredrik@pythonware.com
20 # http://www.pythonware.com
22 # --------------------------------------------------------------------
23 # The ElementTree toolkit is
25 # Copyright (c) 1999-2009 by Fredrik Lundh
27 # By obtaining, using, and/or copying this software and/or its
28 # associated documentation, you agree that you have read, understood,
29 # and will comply with the following terms and conditions:
31 # Permission to use, copy, modify, and distribute this software and
32 # its associated documentation for any purpose and without fee is
33 # hereby granted, provided that the above copyright notice appears in
34 # all copies, and that both that copyright notice and this permission
35 # notice appear in supporting documentation, and that the name of
36 # Secret Labs AB or the author not be used in advertising or publicity
37 # pertaining to distribution of the software without specific, written
40 # SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
41 # TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
42 # ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
43 # BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
44 # DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
45 # WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
46 # ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
48 # --------------------------------------------------------------------
50 # Licensed to PSF under a Contributor Agreement.
51 # See http://www.python.org/psf/license for licensing details.
54 # Implementation module for XPath support. There's usually no reason
55 # to import this module directly; the <b>ElementTree</b> does this for
61 xpath_tokenizer_re = re.compile(
69 "((?:\{[^}]+\})?[^/\[\]\(\)@=\s]+)|"
73 def xpath_tokenizer(pattern, namespaces=None):
74 for token in xpath_tokenizer_re.findall(pattern):
76 if tag and tag[0] != "{" and ":" in tag:
78 prefix, uri = tag.split(":", 1)
81 yield token[0], "{%s}%s" % (namespaces[prefix], uri)
83 raise SyntaxError("prefix %r not found in prefix map" % prefix)
87 def get_parent_map(context):
88 parent_map = context.parent_map
89 if parent_map is None:
90 context.parent_map = parent_map = {}
91 for p in context.root.iter():
96 def prepare_child(next, token):
98 def select(context, result):
105 def prepare_star(next, token):
106 def select(context, result):
111 def prepare_self(next, token):
112 def select(context, result):
116 def prepare_descendant(next, token):
123 raise SyntaxError("invalid descendant")
124 def select(context, result):
126 for e in elem.iter(tag):
131 def prepare_parent(next, token):
132 def select(context, result):
133 # FIXME: raise error if .. is applied at toplevel?
134 parent_map = get_parent_map(context)
137 if elem in parent_map:
138 parent = parent_map[elem]
139 if parent not in result_map:
140 result_map[parent] = None
144 def prepare_predicate(next, token):
145 # FIXME: replace with real parser!!! refs:
146 # http://effbot.org/zone/simple-iterator-parser.htm
147 # http://javascript.crockford.com/tdop/tdop.html
154 if token[0] and token[0][:1] in "'\"":
155 token = "'", token[0][1:-1]
156 signature.append(token[0] or "-")
157 predicate.append(token[1])
158 signature = "".join(signature)
159 # use signature to determine predicate type
160 if signature == "@-":
161 # [@attribute] predicate
163 def select(context, result):
165 if elem.get(key) is not None:
168 if signature == "@-='":
169 # [@attribute='value']
171 value = predicate[-1]
172 def select(context, result):
174 if elem.get(key) == value:
177 if signature == "-" and not re.match("\-?\d+$", predicate[0]):
180 def select(context, result):
182 if elem.find(tag) is not None:
185 if signature == "-='" and not re.match("\-?\d+$", predicate[0]):
188 value = predicate[-1]
189 def select(context, result):
191 for e in elem.findall(tag):
192 if "".join(e.itertext()) == value:
196 if signature == "-" or signature == "-()" or signature == "-()-":
197 # [index] or [last()] or [last()-index]
200 index = int(predicate[0]) - 1
202 raise SyntaxError("XPath position >= 1 expected")
204 if predicate[0] != "last":
205 raise SyntaxError("unsupported function")
206 if signature == "-()-":
208 index = int(predicate[2]) - 1
210 raise SyntaxError("unsupported expression")
212 raise SyntaxError("XPath offset from last() must be negative")
215 def select(context, result):
216 parent_map = get_parent_map(context)
219 parent = parent_map[elem]
220 # FIXME: what if the selector is "*" ?
221 elems = list(parent.findall(elem.tag))
222 if elems[index] is elem:
224 except (IndexError, KeyError):
227 raise SyntaxError("invalid predicate")
233 "..": prepare_parent,
234 "//": prepare_descendant,
235 "[": prepare_predicate,
240 class _SelectorContext:
242 def __init__(self, root):
245 # --------------------------------------------------------------------
248 # Generate all matching objects.
250 def iterfind(elem, path, namespaces=None):
251 # compile selector pattern
252 cache_key = (path, None if namespaces is None
253 else tuple(sorted(namespaces.items())))
255 path = path + "*" # implicit all (FIXME: keep this?)
257 selector = _cache[cache_key]
259 if len(_cache) > 100:
262 raise SyntaxError("cannot use absolute path on element")
263 next = iter(xpath_tokenizer(path, namespaces)).__next__
268 selector.append(ops[token[0]](next, token))
269 except StopIteration:
270 raise SyntaxError("invalid path")
275 except StopIteration:
277 _cache[cache_key] = selector
278 # execute selector pattern
280 context = _SelectorContext(elem)
281 for select in selector:
282 result = select(context, result)
286 # Find first matching object.
288 def find(elem, path, namespaces=None):
290 return next(iterfind(elem, path, namespaces))
291 except StopIteration:
295 # Find all matching objects.
297 def findall(elem, path, namespaces=None):
298 return list(iterfind(elem, path, namespaces))
301 # Find text for first matching object.
303 def findtext(elem, path, default=None, namespaces=None):
305 elem = next(iterfind(elem, path, namespaces))
306 return elem.text or ""
307 except StopIteration: