diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 782ebe78533..813e0e369f3 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -35,10 +35,11 @@ and its sub-elements are done on the :class:`Element` level.
Parsing XML
^^^^^^^^^^^
-We'll be using the following XML document contained in a Python string as the
-sample data for this section::
+We'll be using the following XML document as the sample data for this section:
- countrydata = r'''
+.. code-block:: xml
+
+
1
@@ -61,18 +62,20 @@ sample data for this section::
- '''
-First, import the module and parse the data::
+We can import this data by reading from a file::
import xml.etree.ElementTree as ET
+ tree = ET.parse('country_data.xml')
+ root = tree.getroot()
- root = ET.fromstring(countrydata)
+Or directly from a string::
+
+ root = ET.fromstring(country_data_as_string)
:func:`fromstring` parses XML from a string directly into an :class:`Element`,
which is the root element of the parsed tree. Other parsing functions may
-create an :class:`ElementTree`. Make sure to check the documentation to be
-sure.
+create an :class:`ElementTree`. Check the documentation to be sure.
As an :class:`Element`, ``root`` has a tag and a dictionary of attributes::
@@ -111,13 +114,27 @@ the sub-tree below it (its children, their children, and so on). For example,
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}
+:meth:`Element.findall` finds only elements with a tag which are direct
+children of the current element. :meth:`Element.find` finds the *first* child
+with a particular tag, and :meth:`Element.text` accesses the element's text
+content. :meth:`Element.get` accesses the element's attributes::
+
+ >>> for country in root.findall('country'):
+ ... rank = country.find('rank').text
+ ... name = country.get('name')
+ ... print(name, rank)
+ ...
+ Liechtenshtein 1
+ Singapore 4
+ Panama 68
+
More sophisticated specification of which elements to look for is possible by
using :ref:`XPath `.
-Building XML documents
-^^^^^^^^^^^^^^^^^^^^^^
+Modifying an XML File
+^^^^^^^^^^^^^^^^^^^^^
-``ET`` provides a simple way to build XML documents and write them to files.
+:class:`ElementTree` provides a simple way to build XML documents and write them to files.
The :meth:`ElementTree.write` method serves this purpose.
Once created, an :class:`Element` object may be manipulated by directly changing
@@ -125,6 +142,78 @@ its fields (such as :attr:`Element.text`), adding and modifying attributes
(:meth:`Element.set` method), as well as adding new children (for example
with :meth:`Element.append`).
+Let's say we want to add one to each country's rank, and add an ``updated``
+attribute to the rank element::
+
+ >>> for rank in root.iter('rank'):
+ ... new_rank = int(rank.text) + 1
+ ... rank.text = str(new_rank)
+ ... rank.set('updated', 'yes')
+ ...
+ ... tree.write('output.xml')
+
+Our XML now looks like this:
+
+.. code-block:: xml
+
+
+
+
+ 2
+ 2008
+ 141100
+
+
+
+
+ 5
+ 2011
+ 59900
+
+
+
+ 69
+ 2011
+ 13600
+
+
+
+
+
+We can remove elements using :meth:`Element.remove`. Let's say we want to
+remove all countries with a rank higher than 50::
+
+ >>> for country in root.findall('country'):
+ ... rank = int(country.find('rank').text)
+ ... if rank > 50:
+ ... root.remove(country)
+ ...
+ ... tree.write('output.xml')
+
+Our XML now looks like this:
+
+.. code-block:: xml
+
+
+
+
+ 2
+ 2008
+ 141100
+
+
+
+
+ 5
+ 2011
+ 59900
+
+
+
+
+Building XML documents
+^^^^^^^^^^^^^^^^^^^^^^
+
The :func:`SubElement` function also provides a convenient way to create new
sub-elements for a given element::