cpython: e38f4cf482c7 (original) (raw)
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -45,10 +45,119 @@ docs.
The :mod:xml.etree.cElementTree module is deprecated.
+.. elementtree-xpath:
+
+XPath support
+-------------
+
+This module provides limited support for
+XPath expressions <http://www.w3.org/TR/xpath> for locating elements in a
+tree. The goal is to support a small subset of the abbreviated syntax; a full
+XPath engine is outside the scope of the module.
+
+Example
+^^^^^^^
+
+Here's an example that demonstrates some of the XPath capabilities of the
+module::
+
- import xml.etree.ElementTree as ET +
- xml = r'''
<country name="Liechtenshtein">[](#l1.27)<rank>1</rank>[](#l1.28)<year>2008</year>[](#l1.29)<gdppc>141100</gdppc>[](#l1.30)<neighbor name="Austria" direction="E"/>[](#l1.31)<neighbor name="Switzerland" direction="W"/>[](#l1.32)</country>[](#l1.33)<country name="Singapore">[](#l1.34)<rank>4</rank>[](#l1.35)<year>2011</year>[](#l1.36)<gdppc>59900</gdppc>[](#l1.37)<neighbor name="Malaysia" direction="N"/>[](#l1.38)</country>[](#l1.39)<country name="Panama">[](#l1.40)<rank>68</rank>[](#l1.41)<year>2011</year>[](#l1.42)<gdppc>13600</gdppc>[](#l1.43)<neighbor name="Costa Rica" direction="W"/>[](#l1.44)<neighbor name="Colombia" direction="E"/>[](#l1.45)</country>[](#l1.46)- ''' +
- tree = ET.fromstring(xml) +
Top-level elements
- tree.findall(".") +
All 'neighbor' grand-children of 'country' children of the top-level
elements
- tree.findall("./country/neighbor") +
Nodes with name='Singapore' that have a 'year' child
- tree.findall(".//year/..[@name='Singapore']") +
'year' nodes that are children of nodes with name='Singapore'
- tree.findall(".//*[@name='Singapore']/year") +
All 'neighbor' nodes that are the second child of their parent
- tree.findall(".//neighbor[2]") +
+Supported XPath syntax
+^^^^^^^^^^^^^^^^^^^^^^
+
++-----------------------+------------------------------------------------------+
+| Syntax | Meaning |
++=======================+======================================================+
+| tag | Selects all child elements with the given tag. |
+| | For example, spam selects all child elements |
+| | named spam, spam/egg selects all |
+| | grandchildren named egg in all children named |
+| | spam. |
++-----------------------+------------------------------------------------------+
+| * | Selects all child elements. For example, */egg |
+| | selects all grandchildren named egg. |
++-----------------------+------------------------------------------------------+
+| . | Selects the current node. This is mostly useful |
+| | at the beginning of the path, to indicate that it's |
+| | a relative path. |
++-----------------------+------------------------------------------------------+
+| // | Selects all subelements, on all levels beneath the |
+| | current element. For example, ./egg selects |
+| | all egg elements in the entire tree. |
++-----------------------+------------------------------------------------------+
+| .. | Selects the parent element. |
++-----------------------+------------------------------------------------------+
+| [@attrib] | Selects all elements that have the given attribute. |
++-----------------------+------------------------------------------------------+
+| [@attrib='value'] | Selects all elements for which the given attribute |
+| | has the given value. The value cannot contain |
+| | quotes. |
++-----------------------+------------------------------------------------------+
+| [tag] | Selects all elements that have a child named |
+| | tag. Only immediate children are supported. |
++-----------------------+------------------------------------------------------+
+| [position] | Selects all elements that are located at the given |
+| | position. The position can be either an integer |
+| | (1 is the first position), the expression last() |
+| | (for the last position), or a position relative to |
+| | the last position (e.g. last()-1). |
++-----------------------+------------------------------------------------------+
+
+Predicates (expressions within square brackets) must be preceded by a tag
+name, an asterisk, or another predicate. position predicates must be
+preceded by a tag name.
+
+Reference
+---------
+
.. _elementtree-functions:
Functions
----------
+^^^^^^^^^
.. function:: Comment(text=None)
@@ -199,7 +308,7 @@ Functions
.. _elementtree-element-objects:
Element Objects
----------------
+^^^^^^^^^^^^^^^
.. class:: Element(tag, attrib={}, **extra)
@@ -297,21 +406,24 @@ Element Objects
.. method:: find(match)
Finds the first subelement matching match. match may be a tag name
or path. Returns an element instance or ``None``.[](#l1.137)
or a :ref:`path <elementtree-xpath>`. Returns an element instance[](#l1.138)or ``None``.[](#l1.139)
Finds all matching subelements, by tag name or path. Returns a list[](#l1.144)containing all matching elements in document order.[](#l1.145)
Finds all matching subelements, by tag name or[](#l1.146):ref:`path <elementtree-xpath>`. Returns a list containing all matching[](#l1.147)elements in document order.[](#l1.148)
.. method:: findtext(match, default=None) Finds text for the first subelement matching match. match may be
a tag name or path. Returns the text content of the first matching[](#l1.154)element, or *default* if no element was found. Note that if the matching[](#l1.155)element has no text content an empty string is returned.[](#l1.156)
a tag name or a :ref:`path <elementtree-xpath>`. Returns the text content[](#l1.157)of the first matching element, or *default* if no element was found.[](#l1.158)Note that if the matching element has no text content an empty string[](#l1.159)is returned.[](#l1.160)
.. method:: getchildren() @@ -345,8 +457,9 @@ Element Objects .. method:: iterfind(match)
Finds all matching subelements, by tag name or path. Returns an iterable[](#l1.168)yielding all matching elements in document order.[](#l1.169)
Finds all matching subelements, by tag name or[](#l1.170):ref:`path <elementtree-xpath>`. Returns an iterable yielding all[](#l1.171)matching elements in document order.[](#l1.172)
.. versionadded:: 3.2 @@ -391,7 +504,7 @@ Element Objects .. _elementtree-elementtree-objects: ElementTree Objects -------------------- +^^^^^^^^^^^^^^^^^^^ .. class:: ElementTree(element=None, file=None) @@ -413,26 +526,17 @@ ElementTree Objects .. method:: find(match)
Finds the first toplevel element matching *match*. *match* may be a tag[](#l1.189)name or path. Same as getroot().find(match). Returns the first matching[](#l1.190)element, or ``None`` if no element was found.[](#l1.191)
Same as :meth:`Element.find`, starting at the root of the tree.[](#l1.192)
Finds all matching subelements, by tag name or path. Same as[](#l1.197)getroot().findall(match). *match* may be a tag name or path. Returns a[](#l1.198)list containing all matching elements, in document order.[](#l1.199)
Same as :meth:`Element.findall`, starting at the root of the tree.[](#l1.200)
.. method:: findtext(match, default=None)
Finds the element text for the first toplevel element with given tag.[](#l1.205)Same as getroot().findtext(match). *match* may be a tag name or path.[](#l1.206)*default* is the value to return if the element was not found. Returns[](#l1.207)the text content of the first matching element, or the default value no[](#l1.208)element was found. Note that if the element is found, but has no text[](#l1.209)content, this method returns an empty string.[](#l1.210)
Same as :meth:`Element.findtext`, starting at the root of the tree.[](#l1.211)
.. method:: getiterator(tag=None) @@ -455,9 +559,7 @@ ElementTree Objects .. method:: iterfind(match)
Finds all matching subelements, by tag name or path. Same as[](#l1.219)getroot().iterfind(match). Returns an iterable yielding all matching[](#l1.220)elements in document order.[](#l1.221)
Same as :meth:`Element.iterfind`, starting at the root of the tree.[](#l1.222)
.. versionadded:: 3.2 @@ -512,7 +614,7 @@ Example of changing the attribute "targe .. _elementtree-qname-objects: QName Objects -------------- +^^^^^^^^^^^^^ .. class:: QName(text_or_uri, tag=None) @@ -528,7 +630,7 @@ QName Objects .. _elementtree-treebuilder-objects: TreeBuilder Objects -------------------- +^^^^^^^^^^^^^^^^^^^ .. class:: TreeBuilder(element_factory=None) @@ -579,7 +681,7 @@ TreeBuilder Objects .. _elementtree-xmlparser-objects: XMLParser Objects ------------------ +^^^^^^^^^^^^^^^^^ .. class:: XMLParser(html=0, target=None, encoding=None) @@ -648,7 +750,7 @@ This is an example of counting the maxim 4 Exceptions ----------- +^^^^^^^^^^ .. class:: ParseError