xml.etree.ElementTree — The ElementTree XML API …

Source code: Lib/xml/etree/
The module implements a simple and efficient API
for parsing and creating XML data.
Changed in version 3. 3: This module will use a fast implementation whenever available.
Deprecated since version 3. 3: The module is deprecated.
Warning
The module is not secure against
maliciously constructed data. If you need to parse untrusted or
unauthenticated data see XML vulnerabilities.
Tutorial¶
This is a short tutorial for using (ET in
short). The goal is to demonstrate some of the building blocks and basic
concepts of the module.
XML tree and elements¶
XML is an inherently hierarchical data format, and the most natural way to
represent it is with a tree. ET has two classes for this purpose –
ElementTree represents the whole XML document as a tree, and
Element represents a single node in this tree. Interactions with
the whole document (reading and writing to/from files) are usually done
on the ElementTree level. Interactions with a single XML element
and its sub-elements are done on the Element level.
Parsing XML¶
We’ll be using the following XML document as the sample data for this section:



1
2008
141100




4
2011
59900


68
13600



We can import this data by reading from a file:
import as ET
tree = (”)
root = troot()
Or directly from a string:
root = omstring(country_data_as_string)
fromstring() parses XML from a string directly into an Element,
which is the root element of the parsed tree. Other parsing functions may
create an ElementTree. Check the documentation to be sure.
As an Element, root has a tag and a dictionary of attributes:
>>>
‘data’
{}
It also has children nodes over which we can iterate:
>>> for child in root:… print(, )…
country {‘name’: ‘Liechtenstein’}
country {‘name’: ‘Singapore’}
country {‘name’: ‘Panama’}
Children are nested, and we can access specific child nodes by index:
>>> root[0][1]
‘2008’
Note
Not all elements of the XML input will end up as elements of the
parsed tree. Currently, this module skips over any XML comments,
processing instructions, and document type declarations in the
input. Nevertheless, trees built using this module’s API rather
than parsing from XML text can have comments and processing
instructions in them; they will be included when generating XML
output. A document type declaration may be accessed by passing a
custom TreeBuilder instance to the XMLParser
constructor.
Pull API for non-blocking parsing¶
Most parsing functions provided by this module require the whole document
to be read at once before returning any result. It is possible to use an
XMLParser and feed data into it incrementally, but it is a push API that
calls methods on a callback target, which is too low-level and inconvenient for
most needs. Sometimes what the user really wants is to be able to parse XML
incrementally, without blocking operations, while enjoying the convenience of
fully constructed Element objects.
The most powerful tool for doing this is XMLPullParser. It does not
require a blocking read to obtain the XML data, and is instead fed with data
incrementally with () calls. To get the parsed XML
elements, call ad_events(). Here is an example:
>>> parser = ET. XMLPullParser([‘start’, ‘end’])
>>> (‘sometext’)
>>> list(ad_events())
[(‘start’, )]
>>> (‘ more text‘)
>>> for event, elem in ad_events():… print(event)… print(, ‘text=’, )…
end
The obvious use case is applications that operate in a non-blocking fashion
where the XML data is being received from a socket or read incrementally from
some storage device. In such cases, blocking reads are unacceptable.
Because it’s so flexible, XMLPullParser can be inconvenient to use for
simpler use-cases. If you don’t mind your application blocking on reading XML
data but would still like to have incremental parsing capabilities, take a look
at iterparse(). It can be useful when you’re reading a large XML document
and don’t want to hold it wholly in memory.
Finding interesting elements¶
Element has some useful methods that help iterate recursively over all
the sub-tree below it (its children, their children, and so on). For example,
():
>>> for neighbor in (‘neighbor’):… print()…
{‘name’: ‘Austria’, ‘direction’: ‘E’}
{‘name’: ‘Switzerland’, ‘direction’: ‘W’}
{‘name’: ‘Malaysia’, ‘direction’: ‘N’}
{‘name’: ‘Costa Rica’, ‘direction’: ‘W’}
{‘name’: ‘Colombia’, ‘direction’: ‘E’}
ndall() finds only elements with a tag which are direct
children of the current element. () finds the first child
with a particular tag, and accesses the element’s text
content. () accesses the element’s attributes:
>>> for country in ndall(‘country’):… rank = (‘rank’)… name = (‘name’)… print(name, rank)…
Liechtenstein 1
Singapore 4
Panama 68
More sophisticated specification of which elements to look for is possible by
using XPath.
Modifying an XML File¶
ElementTree provides a simple way to build XML documents and write them to files.
The () method serves this purpose.
Once created, an Element object may be manipulated by directly changing
its fields (such as), adding and modifying attributes
(() method), as well as adding new children (for example
with ()).
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 (‘rank’):… new_rank = int() + 1… = str(new_rank)… (‘updated’, ‘yes’)…
>>> (”)
Our XML now looks like this:
2
5
69
We can remove elements using (). Let’s say we want to
remove all countries with a rank higher than 50:
>>> for country in ndall(‘country’):… # using ndall() to avoid removal during traversal… rank = int((‘rank’))… if rank > 50:… (country)…
Note that concurrent modification while iterating can lead to problems,
just like when iterating and modifying Python lists or dicts.
Therefore, the example first collects all matching elements with
ndall(), and only then iterates over the list of matches.
Building XML documents¶
The SubElement() function also provides a convenient way to create new
sub-elements for a given element:
>>> a = ET. Element(‘a’)
>>> b = bElement(a, ‘b’)
>>> c = bElement(a, ‘c’)
>>> d = bElement(c, ‘d’)
>>> (a)

Parsing XML with Namespaces¶
If the XML input has namespaces, tags and attributes
with prefixes in the form prefix:sometag get expanded to
{uri}sometag where the prefix is replaced by the full URI.
Also, if there is a default namespace,
that full URI gets prepended to all of the non-prefixed tags.
Here is an XML example that incorporates two namespaces, one with the
prefix “fictional” and the other serving as the default namespace:



By default, the href attribute is treated as a file name. You can use custom loaders to override this behaviour. Also note that the standard helper does not support XPointer syntax.
To process this file, load it as usual, and pass the root element to the module:
from import ElementTree, ElementInclude
tree = (“”)
clude(root)
The ElementInclude module replaces the {include element with the root element from the document. The result might look something like this: This is a paragraph. If the parse attribute is omitted, it defaults to “xml”. The href attribute is required.
To include a text document, use the {include element, and set the parse attribute to “text”:
Copyright (c) .
The result might look something like:
Copyright (c) 2003.
(href, parse, encoding=None)¶
Default loader. This default loader reads an included resource from disk. href is a URL.
parse is for parse mode either “xml” or “text”. encoding
is an optional text encoding. If not given, encoding is utf-8. Returns the
expanded resource. If the parse mode is “xml”, this is an ElementTree
instance. If the parse mode is “text”, this is a Unicode string. If the
loader fails, it can return None or raise an exception.
(elem, loader=None, base_url=None, max_depth=6)¶
This function expands XInclude directives. elem is the root element. loader is
an optional resource loader. If omitted, it defaults to default_loader().
If given, it should be a callable that implements the same interface as
default_loader(). base_url is base URL of the original file, to resolve
relative include file references. max_depth is the maximum number of recursive
inclusions. Limited to reduce the risk of malicious content explosion. Pass a
negative value to disable the limitation.
Returns the expanded resource. If the parse mode is
“xml”, this is an ElementTree instance. If the parse mode is “text”,
this is a Unicode string. If the loader fails, it can return None or
raise an exception.
New in version 3. 9: The base_url and max_depth parameters.
Element Objects¶
class (tag, attrib={}, **extra)¶
Element class. This class defines the Element interface, and provides a
reference implementation of this interface.
bytestrings or Unicode strings. tag is the element name. attrib is
an optional dictionary, containing element attributes. extra contains
additional attributes, given as keyword arguments.
tag¶
A string identifying what kind of data this element represents (the
element type, in other words).
text¶
tail¶
These attributes can be used to hold additional data associated with
the element. Their values are usually strings but may be any
application-specific object. If the element is created from
an XML file, the text attribute holds either the text between
the element’s start tag and its first child or end tag, or None, and
the tail attribute holds either the text between the element’s
end tag and the next tag, or None. For the XML data
1234
the a element has None for both text and tail attributes,
the b element has text “1” and tail “4”,
the c element has text “2” and tail None,
and the d element has text None and tail “3”.
To collect the inner text of an element, see itertext(), for
example “”(ertext()).
Applications may store arbitrary objects in these attributes.
attrib¶
A dictionary containing the element’s attributes. Note that while the
attrib value is always a real mutable Python dictionary, an ElementTree
implementation may choose to use another internal representation, and
create the dictionary only if someone asks for it. To take advantage of
such implementations, use the dictionary methods below whenever possible.
The following dictionary-like methods work on the element attributes.
clear()¶
Resets an element. This function removes all subelements, clears all
attributes, and sets the text and tail attributes to None.
get(key, default=None)¶
Gets the element attribute named key.
Returns the attribute value, or default if the attribute was not found.
items()¶
Returns the element attributes as a sequence of (name, value) pairs. The
attributes are returned in an arbitrary order.
keys()¶
Returns the elements attribute names as a list. The names are returned
in an arbitrary order.
set(key, value)¶
Set the attribute key on the element to value.
The following methods work on the element’s children (subelements).
append(subelement)¶
Adds the element subelement to the end of this element’s internal list
of subelements. Raises TypeError if subelement is not an
Element.
extend(subelements)¶
Appends subelements from a sequence object with zero or more elements.
Raises TypeError if a subelement is not an Element.
find(match, namespaces=None)¶
Finds the first subelement matching match. match may be a tag name
or a path. Returns an element instance
or None. namespaces is an optional mapping from namespace prefix
to full name. Pass ” as prefix to move all unprefixed tag names
in the expression into the given namespace.
findall(match, namespaces=None)¶
Finds all matching subelements, by tag name or
path. Returns a list containing all matching
elements in document order. namespaces is an optional mapping from
namespace prefix to full name. Pass ” as prefix to move all
unprefixed tag names in the expression into the given namespace.
findtext(match, default=None, namespaces=None)¶
Finds text for the first subelement matching match. match may be
a tag name or a path. Returns the text content
of the first matching element, or default if no element was found.
Note that if the matching element has no text content an empty string
is returned. namespaces is an optional mapping from namespace prefix
insert(index, subelement)¶
Inserts subelement at the given position in this element. Raises
TypeError if subelement is not an Element.
iter(tag=None)¶
Creates a tree iterator with the current element as the root.
The iterator iterates over this element and all elements below it, in
document (depth first) order. If tag is not None or ‘*’, only
elements whose tag equals tag are returned from the iterator. If the
tree structure is modified during iteration, the result is undefined.
iterfind(match, namespaces=None)¶
path. Returns an iterable yielding all
matching elements in document order. namespaces is an optional mapping
from namespace prefix to full name.
itertext()¶
Creates a text iterator. The iterator loops over this element and all
subelements, in document order, and returns all inner text.
makeelement(tag, attrib)¶
Creates a new element object of the same type as this element. Do not
call this method, use the SubElement() factory function instead.
remove(subelement)¶
Removes subelement from the element. Unlike the find* methods this
method compares elements based on the instance identity, not on tag value
or contents.
Element objects also support the following sequence type methods
for working with subelements: __delitem__(),
__getitem__(), __setitem__(),
__len__().
Caution: Elements with no subelements will test as False. This behavior
will change in future versions. Use specific len(elem) or elem is
None test instead.
element = (‘foo’)
if not element: # careful!
print(“element not found, or element has no subelements”)
if element is None:
print(“element not found”)
Prior to Python 3. 8, the serialisation order of the XML attributes of
elements was artificially made predictable by sorting the attributes by
their name. Based on the now guaranteed ordering of dicts, this arbitrary
reordering was removed in Python 3. 8 to preserve the order in which
attributes were originally parsed or created by user code.
In general, user code should try not to depend on a specific ordering of
attributes, given that the XML Information Set explicitly excludes the attribute
order from conveying information. Code should be prepared to deal with
any ordering on input. In cases where deterministic XML output is required,
e. for cryptographic signing or test data sets, canonical serialisation
is available with the canonicalize() function.
In cases where canonical output is not applicable but a specific attribute
order is still desirable on output, code should aim for creating the
attributes directly in the desired order, to avoid perceptual mismatches
for readers of the code. In cases where this is difficult to achieve, a
recipe like the following can be applied prior to serialisation to enforce
an order independently from the Element creation:
def reorder_attributes(root):
for el in ():
attrib =
if len(attrib) > 1:
# adjust attribute order, e. by sorting
attribs = sorted(())
()
(attribs)
ElementTree Objects¶
class (element=None, file=None)¶
ElementTree wrapper class. This class represents an entire element
hierarchy, and adds some extra support for serialization to and from
standard XML.
element is the root element. The tree is initialized with the contents
of the XML file if given.
_setroot(element)¶
Replaces the root element for this tree. This discards the current
contents of the tree, and replaces it with the given element. Use with
care. element is an element instance.
Same as (), starting at the root of the tree.
Same as ndall(), starting at the root of the tree.
Same as ndtext(), starting at the root of the tree.
getroot()¶
Returns the root element for this tree.
Creates and returns a tree iterator for the root element. The iterator
loops over all elements in this tree, in section order. tag is the tag
to look for (default is to return all elements).
Same as erfind(), starting at the root of the tree.
parse(source, parser=None)¶
Loads an external XML section into this element tree. source is a file
name or file object. parser is an optional parser instance.
If not given, the standard XMLParser parser is used. Returns the
section root element.
write(file, encoding=”us-ascii”, xml_declaration=None, default_namespace=None, method=”xml”, *, short_empty_elements=True)¶
Writes the element tree to a file, as XML. file is a file name, or a
file object opened for writing. encoding 1 is the output
encoding (default is US-ASCII).
xml_declaration controls if an XML declaration should be added to the
file. Use False for never, True for always, None
for only if not US-ASCII or UTF-8 or Unicode (default is None).
default_namespace sets the default XML namespace (for “xmlns”).
method is either “xml”, “html” or “text” (default is
“xml”).
The keyword-only short_empty_elements parameter controls the formatting
of elements that contain no content. If True (the default), they are
emitted as a single self-closed tag, otherwise they are emitted as a pair
of start/end tags.
The output is either a string (str) or binary (bytes).
This is controlled by the encoding argument. If encoding is
“unicode”, the output is a string; otherwise, it’s binary. Note that
this may conflict with the type of file if it’s an open
file object; make sure you do not try to write a string to a
binary stream and vice versa.
Changed in version 3. 8: The write() method now preserves the attribute order specified
This is the XML file that is going to be manipulated: