diff -r 59223da36dec Doc/library/xml.etree.elementtree.rst
--- a/Doc/library/xml.etree.elementtree.rst Tue Aug 07 03:10:57 2012 -0700
+++ b/Doc/library/xml.etree.elementtree.rst Wed Aug 08 16:20:27 2012 -0400
@@ -35,10 +35,11 @@
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,13 +62,23 @@
- '''
-First, import the module and parse the data::
+We have a number of ways to import the data. Reading the file from disk::
import xml.etree.ElementTree as ET
+ tree = ET()
+ tree.parse('country_data.xml')
+ root = tree.getroot()
- root = ET.fromstring(countrydata)
+Reading the file from a remote URL::
+
+ import urllib
+ tree.parse(urllib.urlopen('http://example.com/country_data.xml'))
+ root = tree.getroot()
+
+Reading the data 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
@@ -111,13 +122,27 @@
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}
+If a more strict reliance on tree structure is desired, :meth:`Element.findall`
+can be used to find only elements with a tag which are direct children of the
+current element, and :meth:`Element.find` can be used to find the *first* child
+with a particular tag. :meth:`Element.get` safely accesses attributes.
+:meth:`Element.text` accesses the element's content::
+
+ >>> for country in root.findall('country'):
+ ... rank = country.find('rank').text
+ ... print(country.get('name'), rank)
+ ...
+ 1 Liechtenshtein
+ 4 Singapore
+ 68 Panama
+
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 +150,75 @@
(:meth:`Element.set` method), as well as adding new children (for example
with :meth:`Element.append`).
+Let's say we want to subtract one from each country's rank::
+
+ >>> 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'))
+ ... 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::