1446 lines
133 KiB
HTML
1446 lines
133 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>xml.etree.ElementTree — The ElementTree XML API — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="xml.dom — The Document Object Model API" href="xml.dom.html" />
|
||
<link rel="prev" title="XML Processing Modules" href="xml.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/xml.etree.elementtree.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="xml.dom.html" title="xml.dom — The Document Object Model API"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="xml.html" title="XML Processing Modules"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="markup.html" accesskey="U">Structured Markup Processing Tools</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-xml.etree.ElementTree">
|
||
<span id="xml-etree-elementtree-the-elementtree-xml-api"></span><h1><a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> — The ElementTree XML API<a class="headerlink" href="#module-xml.etree.ElementTree" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/xml/etree/ElementTree.py">Lib/xml/etree/ElementTree.py</a></p>
|
||
<hr class="docutils" />
|
||
<p>The <a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> module implements a simple and efficient API
|
||
for parsing and creating XML data.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>This module will use a fast implementation whenever available.
|
||
The <code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.cElementTree</span></code> module is deprecated.</p>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>The <a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> module is not secure against
|
||
maliciously constructed data. If you need to parse untrusted or
|
||
unauthenticated data see <a class="reference internal" href="xml.html#xml-vulnerabilities"><span class="std std-ref">XML vulnerabilities</span></a>.</p>
|
||
</div>
|
||
<div class="section" id="tutorial">
|
||
<h2>Tutorial<a class="headerlink" href="#tutorial" title="Permalink to this headline">¶</a></h2>
|
||
<p>This is a short tutorial for using <a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> (<code class="docutils literal notranslate"><span class="pre">ET</span></code> in
|
||
short). The goal is to demonstrate some of the building blocks and basic
|
||
concepts of the module.</p>
|
||
<div class="section" id="xml-tree-and-elements">
|
||
<h3>XML tree and elements<a class="headerlink" href="#xml-tree-and-elements" title="Permalink to this headline">¶</a></h3>
|
||
<p>XML is an inherently hierarchical data format, and the most natural way to
|
||
represent it is with a tree. <code class="docutils literal notranslate"><span class="pre">ET</span></code> has two classes for this purpose -
|
||
<a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> represents the whole XML document as a tree, and
|
||
<a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> represents a single node in this tree. Interactions with
|
||
the whole document (reading and writing to/from files) are usually done
|
||
on the <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> level. Interactions with a single XML element
|
||
and its sub-elements are done on the <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> level.</p>
|
||
</div>
|
||
<div class="section" id="parsing-xml">
|
||
<span id="elementtree-parsing-xml"></span><h3>Parsing XML<a class="headerlink" href="#parsing-xml" title="Permalink to this headline">¶</a></h3>
|
||
<p>We’ll be using the following XML document as the sample data for this section:</p>
|
||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0"?></span>
|
||
<span class="nt"><data></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">></span>
|
||
<span class="nt"><rank></span>1<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2008<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>141100<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Austria"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Switzerland"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">></span>
|
||
<span class="nt"><rank></span>4<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>59900<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Malaysia"</span> <span class="na">direction=</span><span class="s">"N"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Panama"</span><span class="nt">></span>
|
||
<span class="nt"><rank></span>68<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>13600<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Costa Rica"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Colombia"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"></data></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>We can import this data by reading from a file:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">xml.etree.ElementTree</span> <span class="k">as</span> <span class="nn">ET</span>
|
||
<span class="n">tree</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s1">'country_data.xml'</span><span class="p">)</span>
|
||
<span class="n">root</span> <span class="o">=</span> <span class="n">tree</span><span class="o">.</span><span class="n">getroot</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Or directly from a string:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">root</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="n">country_data_as_string</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#xml.etree.ElementTree.fromstring" title="xml.etree.ElementTree.fromstring"><code class="xref py py-func docutils literal notranslate"><span class="pre">fromstring()</span></code></a> parses XML from a string directly into an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>,
|
||
which is the root element of the parsed tree. Other parsing functions may
|
||
create an <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a>. Check the documentation to be sure.</p>
|
||
<p>As an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>, <code class="docutils literal notranslate"><span class="pre">root</span></code> has a tag and a dictionary of attributes:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">tag</span>
|
||
<span class="go">'data'</span>
|
||
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">attrib</span>
|
||
<span class="go">{}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>It also has children nodes over which we can iterate:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">root</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">child</span><span class="o">.</span><span class="n">tag</span><span class="p">,</span> <span class="n">child</span><span class="o">.</span><span class="n">attrib</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">country {'name': 'Liechtenstein'}</span>
|
||
<span class="go">country {'name': 'Singapore'}</span>
|
||
<span class="go">country {'name': 'Panama'}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Children are nested, and we can access specific child nodes by index:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">root</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">text</span>
|
||
<span class="go">'2008'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>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 <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> instance to the <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a>
|
||
constructor.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="pull-api-for-non-blocking-parsing">
|
||
<span id="elementtree-pull-parsing"></span><h3>Pull API for non-blocking parsing<a class="headerlink" href="#pull-api-for-non-blocking-parsing" title="Permalink to this headline">¶</a></h3>
|
||
<p>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
|
||
<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> 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 <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> objects.</p>
|
||
<p>The most powerful tool for doing this is <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a>. It does not
|
||
require a blocking read to obtain the XML data, and is instead fed with data
|
||
incrementally with <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.feed" title="xml.etree.ElementTree.XMLPullParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLPullParser.feed()</span></code></a> calls. To get the parsed XML
|
||
elements, call <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLPullParser.read_events()</span></code></a>. Here is an example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">XMLPullParser</span><span class="p">([</span><span class="s1">'start'</span><span class="p">,</span> <span class="s1">'end'</span><span class="p">])</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="s1">'<mytag>sometext'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">read_events</span><span class="p">())</span>
|
||
<span class="go">[('start', <Element 'mytag' at 0x7fa66db2be58>)]</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="s1">' more text</mytag>'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">event</span><span class="p">,</span> <span class="n">elem</span> <span class="ow">in</span> <span class="n">parser</span><span class="o">.</span><span class="n">read_events</span><span class="p">():</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">elem</span><span class="o">.</span><span class="n">tag</span><span class="p">,</span> <span class="s1">'text='</span><span class="p">,</span> <span class="n">elem</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">end</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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.</p>
|
||
<p>Because it’s so flexible, <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a> 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 <a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code></a>. It can be useful when you’re reading a large XML document
|
||
and don’t want to hold it wholly in memory.</p>
|
||
</div>
|
||
<div class="section" id="finding-interesting-elements">
|
||
<h3>Finding interesting elements<a class="headerlink" href="#finding-interesting-elements" title="Permalink to this headline">¶</a></h3>
|
||
<p><a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> has some useful methods that help iterate recursively over all
|
||
the sub-tree below it (its children, their children, and so on). For example,
|
||
<a class="reference internal" href="#xml.etree.ElementTree.Element.iter" title="xml.etree.ElementTree.Element.iter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.iter()</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">neighbor</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iter</span><span class="p">(</span><span class="s1">'neighbor'</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">neighbor</span><span class="o">.</span><span class="n">attrib</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">{'name': 'Austria', 'direction': 'E'}</span>
|
||
<span class="go">{'name': 'Switzerland', 'direction': 'W'}</span>
|
||
<span class="go">{'name': 'Malaysia', 'direction': 'N'}</span>
|
||
<span class="go">{'name': 'Costa Rica', 'direction': 'W'}</span>
|
||
<span class="go">{'name': 'Colombia', 'direction': 'E'}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#xml.etree.ElementTree.Element.findall" title="xml.etree.ElementTree.Element.findall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.findall()</span></code></a> finds only elements with a tag which are direct
|
||
children of the current element. <a class="reference internal" href="#xml.etree.ElementTree.Element.find" title="xml.etree.ElementTree.Element.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.find()</span></code></a> finds the <em>first</em> child
|
||
with a particular tag, and <a class="reference internal" href="#xml.etree.ElementTree.Element.text" title="xml.etree.ElementTree.Element.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Element.text</span></code></a> accesses the element’s text
|
||
content. <a class="reference internal" href="#xml.etree.ElementTree.Element.get" title="xml.etree.ElementTree.Element.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.get()</span></code></a> accesses the element’s attributes:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">country</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">'country'</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">rank</span> <span class="o">=</span> <span class="n">country</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s1">'rank'</span><span class="p">)</span><span class="o">.</span><span class="n">text</span>
|
||
<span class="gp">... </span> <span class="n">name</span> <span class="o">=</span> <span class="n">country</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'name'</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">rank</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">Liechtenstein 1</span>
|
||
<span class="go">Singapore 4</span>
|
||
<span class="go">Panama 68</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>More sophisticated specification of which elements to look for is possible by
|
||
using <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">XPath</span></a>.</p>
|
||
</div>
|
||
<div class="section" id="modifying-an-xml-file">
|
||
<h3>Modifying an XML File<a class="headerlink" href="#modifying-an-xml-file" title="Permalink to this headline">¶</a></h3>
|
||
<p><a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> provides a simple way to build XML documents and write them to files.
|
||
The <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a> method serves this purpose.</p>
|
||
<p>Once created, an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> object may be manipulated by directly changing
|
||
its fields (such as <a class="reference internal" href="#xml.etree.ElementTree.Element.text" title="xml.etree.ElementTree.Element.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Element.text</span></code></a>), adding and modifying attributes
|
||
(<a class="reference internal" href="#xml.etree.ElementTree.Element.set" title="xml.etree.ElementTree.Element.set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.set()</span></code></a> method), as well as adding new children (for example
|
||
with <a class="reference internal" href="#xml.etree.ElementTree.Element.append" title="xml.etree.ElementTree.Element.append"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.append()</span></code></a>).</p>
|
||
<p>Let’s say we want to add one to each country’s rank, and add an <code class="docutils literal notranslate"><span class="pre">updated</span></code>
|
||
attribute to the rank element:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">rank</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iter</span><span class="p">(</span><span class="s1">'rank'</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">new_rank</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">rank</span><span class="o">.</span><span class="n">text</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span>
|
||
<span class="gp">... </span> <span class="n">rank</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">new_rank</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="n">rank</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'updated'</span><span class="p">,</span> <span class="s1">'yes'</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'output.xml'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Our XML now looks like this:</p>
|
||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0"?></span>
|
||
<span class="nt"><data></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>2<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2008<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>141100<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Austria"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Switzerland"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>5<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>59900<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Malaysia"</span> <span class="na">direction=</span><span class="s">"N"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Panama"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>69<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>13600<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Costa Rica"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Colombia"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"></data></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>We can remove elements using <a class="reference internal" href="#xml.etree.ElementTree.Element.remove" title="xml.etree.ElementTree.Element.remove"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.remove()</span></code></a>. Let’s say we want to
|
||
remove all countries with a rank higher than 50:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">country</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">'country'</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">rank</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">country</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s1">'rank'</span><span class="p">)</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">if</span> <span class="n">rank</span> <span class="o">></span> <span class="mi">50</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">root</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">country</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'output.xml'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Our XML now looks like this:</p>
|
||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0"?></span>
|
||
<span class="nt"><data></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>2<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2008<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>141100<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Austria"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Switzerland"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>5<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>59900<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Malaysia"</span> <span class="na">direction=</span><span class="s">"N"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"></data></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="building-xml-documents">
|
||
<h3>Building XML documents<a class="headerlink" href="#building-xml-documents" title="Permalink to this headline">¶</a></h3>
|
||
<p>The <a class="reference internal" href="#xml.etree.ElementTree.SubElement" title="xml.etree.ElementTree.SubElement"><code class="xref py py-func docutils literal notranslate"><span class="pre">SubElement()</span></code></a> function also provides a convenient way to create new
|
||
sub-elements for a given element:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s1">'a'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="s1">'c'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="s1">'d'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">ET</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
|
||
<span class="go"><a><b /><c><d /></c></a></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="parsing-xml-with-namespaces">
|
||
<h3>Parsing XML with Namespaces<a class="headerlink" href="#parsing-xml-with-namespaces" title="Permalink to this headline">¶</a></h3>
|
||
<p>If the XML input has <a class="reference external" href="https://en.wikipedia.org/wiki/XML_namespace">namespaces</a>, tags and attributes
|
||
with prefixes in the form <code class="docutils literal notranslate"><span class="pre">prefix:sometag</span></code> get expanded to
|
||
<code class="docutils literal notranslate"><span class="pre">{uri}sometag</span></code> where the <em>prefix</em> is replaced by the full <em>URI</em>.
|
||
Also, if there is a <a class="reference external" href="https://www.w3.org/TR/xml-names/#defaulting">default namespace</a>,
|
||
that full URI gets prepended to all of the non-prefixed tags.</p>
|
||
<p>Here is an XML example that incorporates two namespaces, one with the
|
||
prefix “fictional” and the other serving as the default namespace:</p>
|
||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0"?></span>
|
||
<span class="nt"><actors</span> <span class="na">xmlns:fictional=</span><span class="s">"http://characters.example.com"</span>
|
||
<span class="na">xmlns=</span><span class="s">"http://people.example.com"</span><span class="nt">></span>
|
||
<span class="nt"><actor></span>
|
||
<span class="nt"><name></span>John Cleese<span class="nt"></name></span>
|
||
<span class="nt"><fictional:character></span>Lancelot<span class="nt"></fictional:character></span>
|
||
<span class="nt"><fictional:character></span>Archie Leach<span class="nt"></fictional:character></span>
|
||
<span class="nt"></actor></span>
|
||
<span class="nt"><actor></span>
|
||
<span class="nt"><name></span>Eric Idle<span class="nt"></name></span>
|
||
<span class="nt"><fictional:character></span>Sir Robin<span class="nt"></fictional:character></span>
|
||
<span class="nt"><fictional:character></span>Gunther<span class="nt"></fictional:character></span>
|
||
<span class="nt"><fictional:character></span>Commander Clement<span class="nt"></fictional:character></span>
|
||
<span class="nt"></actor></span>
|
||
<span class="nt"></actors></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>One way to search and explore this XML example is to manually add the
|
||
URI to every tag or attribute in the xpath of a
|
||
<a class="reference internal" href="#xml.etree.ElementTree.Element.find" title="xml.etree.ElementTree.Element.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find()</span></code></a> or <a class="reference internal" href="#xml.etree.ElementTree.Element.findall" title="xml.etree.ElementTree.Element.findall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">findall()</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">root</span> <span class="o">=</span> <span class="n">fromstring</span><span class="p">(</span><span class="n">xml_text</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">actor</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">'{http://people.example.com}actor'</span><span class="p">):</span>
|
||
<span class="n">name</span> <span class="o">=</span> <span class="n">actor</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s1">'{http://people.example.com}name'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">name</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">char</span> <span class="ow">in</span> <span class="n">actor</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">'{http://characters.example.com}character'</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">' |-->'</span><span class="p">,</span> <span class="n">char</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A better way to search the namespaced XML example is to create a
|
||
dictionary with your own prefixes and use those in the search functions:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ns</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'real_person'</span><span class="p">:</span> <span class="s1">'http://people.example.com'</span><span class="p">,</span>
|
||
<span class="s1">'role'</span><span class="p">:</span> <span class="s1">'http://characters.example.com'</span><span class="p">}</span>
|
||
|
||
<span class="k">for</span> <span class="n">actor</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">'real_person:actor'</span><span class="p">,</span> <span class="n">ns</span><span class="p">):</span>
|
||
<span class="n">name</span> <span class="o">=</span> <span class="n">actor</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s1">'real_person:name'</span><span class="p">,</span> <span class="n">ns</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">name</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">char</span> <span class="ow">in</span> <span class="n">actor</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">'role:character'</span><span class="p">,</span> <span class="n">ns</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">' |-->'</span><span class="p">,</span> <span class="n">char</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>These two approaches both output:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">John</span> <span class="n">Cleese</span>
|
||
<span class="o">|--></span> <span class="n">Lancelot</span>
|
||
<span class="o">|--></span> <span class="n">Archie</span> <span class="n">Leach</span>
|
||
<span class="n">Eric</span> <span class="n">Idle</span>
|
||
<span class="o">|--></span> <span class="n">Sir</span> <span class="n">Robin</span>
|
||
<span class="o">|--></span> <span class="n">Gunther</span>
|
||
<span class="o">|--></span> <span class="n">Commander</span> <span class="n">Clement</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="additional-resources">
|
||
<h3>Additional resources<a class="headerlink" href="#additional-resources" title="Permalink to this headline">¶</a></h3>
|
||
<p>See <a class="reference external" href="http://effbot.org/zone/element-index.htm">http://effbot.org/zone/element-index.htm</a> for tutorials and links to other
|
||
docs.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="xpath-support">
|
||
<span id="elementtree-xpath"></span><h2>XPath support<a class="headerlink" href="#xpath-support" title="Permalink to this headline">¶</a></h2>
|
||
<p>This module provides limited support for
|
||
<a class="reference external" href="https://www.w3.org/TR/xpath">XPath expressions</a> 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.</p>
|
||
<div class="section" id="example">
|
||
<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
|
||
<p>Here’s an example that demonstrates some of the XPath capabilities of the
|
||
module. We’ll be using the <code class="docutils literal notranslate"><span class="pre">countrydata</span></code> XML document from the
|
||
<a class="reference internal" href="#elementtree-parsing-xml"><span class="std std-ref">Parsing XML</span></a> section:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">xml.etree.ElementTree</span> <span class="k">as</span> <span class="nn">ET</span>
|
||
|
||
<span class="n">root</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="n">countrydata</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Top-level elements</span>
|
||
<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">"."</span><span class="p">)</span>
|
||
|
||
<span class="c1"># All 'neighbor' grand-children of 'country' children of the top-level</span>
|
||
<span class="c1"># elements</span>
|
||
<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">"./country/neighbor"</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Nodes with name='Singapore' that have a 'year' child</span>
|
||
<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">".//year/..[@name='Singapore']"</span><span class="p">)</span>
|
||
|
||
<span class="c1"># 'year' nodes that are children of nodes with name='Singapore'</span>
|
||
<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">".//*[@name='Singapore']/year"</span><span class="p">)</span>
|
||
|
||
<span class="c1"># All 'neighbor' nodes that are the second child of their parent</span>
|
||
<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">".//neighbor[2]"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="supported-xpath-syntax">
|
||
<h3>Supported XPath syntax<a class="headerlink" href="#supported-xpath-syntax" title="Permalink to this headline">¶</a></h3>
|
||
<table class="docutils align-center">
|
||
<colgroup>
|
||
<col style="width: 30%" />
|
||
<col style="width: 70%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Syntax</p></th>
|
||
<th class="head"><p>Meaning</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">tag</span></code></p></td>
|
||
<td><p>Selects all child elements with the given tag.
|
||
For example, <code class="docutils literal notranslate"><span class="pre">spam</span></code> selects all child elements
|
||
named <code class="docutils literal notranslate"><span class="pre">spam</span></code>, and <code class="docutils literal notranslate"><span class="pre">spam/egg</span></code> selects all
|
||
grandchildren named <code class="docutils literal notranslate"><span class="pre">egg</span></code> in all children named
|
||
<code class="docutils literal notranslate"><span class="pre">spam</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">*</span></code></p></td>
|
||
<td><p>Selects all child elements. For example, <code class="docutils literal notranslate"><span class="pre">*/egg</span></code>
|
||
selects all grandchildren named <code class="docutils literal notranslate"><span class="pre">egg</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">.</span></code></p></td>
|
||
<td><p>Selects the current node. This is mostly useful
|
||
at the beginning of the path, to indicate that it’s
|
||
a relative path.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">//</span></code></p></td>
|
||
<td><p>Selects all subelements, on all levels beneath the
|
||
current element. For example, <code class="docutils literal notranslate"><span class="pre">.//egg</span></code> selects
|
||
all <code class="docutils literal notranslate"><span class="pre">egg</span></code> elements in the entire tree.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">..</span></code></p></td>
|
||
<td><p>Selects the parent element. Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if the
|
||
path attempts to reach the ancestors of the start
|
||
element (the element <code class="docutils literal notranslate"><span class="pre">find</span></code> was called on).</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[@attrib]</span></code></p></td>
|
||
<td><p>Selects all elements that have the given attribute.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[@attrib='value']</span></code></p></td>
|
||
<td><p>Selects all elements for which the given attribute
|
||
has the given value. The value cannot contain
|
||
quotes.</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[tag]</span></code></p></td>
|
||
<td><p>Selects all elements that have a child named
|
||
<code class="docutils literal notranslate"><span class="pre">tag</span></code>. Only immediate children are supported.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[.='text']</span></code></p></td>
|
||
<td><p>Selects all elements whose complete text content,
|
||
including descendants, equals the given <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[tag='text']</span></code></p></td>
|
||
<td><p>Selects all elements that have a child named
|
||
<code class="docutils literal notranslate"><span class="pre">tag</span></code> whose complete text content, including
|
||
descendants, equals the given <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[position]</span></code></p></td>
|
||
<td><p>Selects all elements that are located at the given
|
||
position. The position can be either an integer
|
||
(1 is the first position), the expression <code class="docutils literal notranslate"><span class="pre">last()</span></code>
|
||
(for the last position), or a position relative to
|
||
the last position (e.g. <code class="docutils literal notranslate"><span class="pre">last()-1</span></code>).</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Predicates (expressions within square brackets) must be preceded by a tag
|
||
name, an asterisk, or another predicate. <code class="docutils literal notranslate"><span class="pre">position</span></code> predicates must be
|
||
preceded by a tag name.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="reference">
|
||
<h2>Reference<a class="headerlink" href="#reference" title="Permalink to this headline">¶</a></h2>
|
||
<div class="section" id="functions">
|
||
<span id="elementtree-functions"></span><h3>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.Comment">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">Comment</code><span class="sig-paren">(</span><em>text=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Comment" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Comment element factory. This factory function creates a special element
|
||
that will be serialized as an XML comment by the standard serializer. The
|
||
comment string can be either a bytestring or a Unicode string. <em>text</em> is a
|
||
string containing the comment string. Returns an element instance
|
||
representing a comment.</p>
|
||
<p>Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> skips over comments in the input
|
||
instead of creating comment objects for them. An <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> will
|
||
only contain comment nodes if they have been inserted into to
|
||
the tree using one of the <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> methods.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.dump">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">dump</code><span class="sig-paren">(</span><em>elem</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.dump" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Writes an element tree or element structure to sys.stdout. This function
|
||
should be used for debugging only.</p>
|
||
<p>The exact output format is implementation dependent. In this version, it’s
|
||
written as an ordinary XML file.</p>
|
||
<p><em>elem</em> is an element tree or an individual element.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.fromstring">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">fromstring</code><span class="sig-paren">(</span><em>text</em>, <em>parser=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.fromstring" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parses an XML section from a string constant. Same as <a class="reference internal" href="#xml.etree.ElementTree.XML" title="xml.etree.ElementTree.XML"><code class="xref py py-func docutils literal notranslate"><span class="pre">XML()</span></code></a>. <em>text</em>
|
||
is a string containing XML data. <em>parser</em> is an optional parser instance.
|
||
If not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.
|
||
Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.fromstringlist">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">fromstringlist</code><span class="sig-paren">(</span><em>sequence</em>, <em>parser=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.fromstringlist" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parses an XML document from a sequence of string fragments. <em>sequence</em> is a
|
||
list or other sequence containing XML data fragments. <em>parser</em> is an
|
||
optional parser instance. If not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a>
|
||
parser is used. Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.iselement">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">iselement</code><span class="sig-paren">(</span><em>element</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.iselement" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Checks if an object appears to be a valid element object. <em>element</em> is an
|
||
element instance. Returns a true value if this is an element object.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.iterparse">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">iterparse</code><span class="sig-paren">(</span><em>source</em>, <em>events=None</em>, <em>parser=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.iterparse" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parses an XML section into an element tree incrementally, and reports what’s
|
||
going on to the user. <em>source</em> is a filename or <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>
|
||
containing XML data. <em>events</em> is a sequence of events to report back. The
|
||
supported events are the strings <code class="docutils literal notranslate"><span class="pre">"start"</span></code>, <code class="docutils literal notranslate"><span class="pre">"end"</span></code>, <code class="docutils literal notranslate"><span class="pre">"start-ns"</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">"end-ns"</span></code> (the “ns” events are used to get detailed namespace
|
||
information). If <em>events</em> is omitted, only <code class="docutils literal notranslate"><span class="pre">"end"</span></code> events are reported.
|
||
<em>parser</em> is an optional parser instance. If not given, the standard
|
||
<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used. <em>parser</em> must be a subclass of
|
||
<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> and can only use the default <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> as a
|
||
target. Returns an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> providing <code class="docutils literal notranslate"><span class="pre">(event,</span> <span class="pre">elem)</span></code> pairs.</p>
|
||
<p>Note that while <a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code></a> builds the tree incrementally, it issues
|
||
blocking reads on <em>source</em> (or the file it names). As such, it’s unsuitable
|
||
for applications where blocking reads can’t be made. For fully non-blocking
|
||
parsing, see <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p><a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code></a> only guarantees that it has seen the “>” character of a
|
||
starting tag when it emits a “start” event, so the attributes are defined,
|
||
but the contents of the text and tail attributes are undefined at that
|
||
point. The same applies to the element children; they may or may not be
|
||
present.</p>
|
||
<p>If you need a fully populated element, look for “end” events instead.</p>
|
||
</div>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.4: </span>The <em>parser</em> argument.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.parse">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">parse</code><span class="sig-paren">(</span><em>source</em>, <em>parser=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.parse" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parses an XML section into an element tree. <em>source</em> is a filename or file
|
||
object containing XML data. <em>parser</em> is an optional parser instance. If
|
||
not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used. Returns an
|
||
<a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.ProcessingInstruction">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">ProcessingInstruction</code><span class="sig-paren">(</span><em>target</em>, <em>text=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ProcessingInstruction" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>PI element factory. This factory function creates a special element that
|
||
will be serialized as an XML processing instruction. <em>target</em> is a string
|
||
containing the PI target. <em>text</em> is a string containing the PI contents, if
|
||
given. Returns an element instance, representing a processing instruction.</p>
|
||
<p>Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> skips over processing instructions
|
||
in the input instead of creating comment objects for them. An
|
||
<a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> will only contain processing instruction nodes if
|
||
they have been inserted into to the tree using one of the
|
||
<a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> methods.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.register_namespace">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">register_namespace</code><span class="sig-paren">(</span><em>prefix</em>, <em>uri</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.register_namespace" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Registers a namespace prefix. The registry is global, and any existing
|
||
mapping for either the given prefix or the namespace URI will be removed.
|
||
<em>prefix</em> is a namespace prefix. <em>uri</em> is a namespace uri. Tags and
|
||
attributes in this namespace will be serialized with the given prefix, if at
|
||
all possible.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.SubElement">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">SubElement</code><span class="sig-paren">(</span><em>parent</em>, <em>tag</em>, <em>attrib={}</em>, <em>**extra</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.SubElement" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Subelement factory. This function creates an element instance, and appends
|
||
it to an existing element.</p>
|
||
<p>The element name, attribute names, and attribute values can be either
|
||
bytestrings or Unicode strings. <em>parent</em> is the parent element. <em>tag</em> is
|
||
the subelement name. <em>attrib</em> is an optional dictionary, containing element
|
||
attributes. <em>extra</em> contains additional attributes, given as keyword
|
||
arguments. Returns an element instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.tostring">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">tostring</code><span class="sig-paren">(</span><em>element</em>, <em>encoding="us-ascii"</em>, <em>method="xml"</em>, <em>*</em>, <em>short_empty_elements=True</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.tostring" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Generates a string representation of an XML element, including all
|
||
subelements. <em>element</em> is an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance. <em>encoding</em> <a class="footnote-reference brackets" href="#id5" id="id1">1</a> is
|
||
the output encoding (default is US-ASCII). Use <code class="docutils literal notranslate"><span class="pre">encoding="unicode"</span></code> to
|
||
generate a Unicode string (otherwise, a bytestring is generated). <em>method</em>
|
||
is either <code class="docutils literal notranslate"><span class="pre">"xml"</span></code>, <code class="docutils literal notranslate"><span class="pre">"html"</span></code> or <code class="docutils literal notranslate"><span class="pre">"text"</span></code> (default is <code class="docutils literal notranslate"><span class="pre">"xml"</span></code>).
|
||
<em>short_empty_elements</em> has the same meaning as in <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a>.
|
||
Returns an (optionally) encoded string containing the XML data.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.4: </span>The <em>short_empty_elements</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.tostringlist">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">tostringlist</code><span class="sig-paren">(</span><em>element</em>, <em>encoding="us-ascii"</em>, <em>method="xml"</em>, <em>*</em>, <em>short_empty_elements=True</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.tostringlist" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Generates a string representation of an XML element, including all
|
||
subelements. <em>element</em> is an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance. <em>encoding</em> <a class="footnote-reference brackets" href="#id5" id="id2">1</a> is
|
||
the output encoding (default is US-ASCII). Use <code class="docutils literal notranslate"><span class="pre">encoding="unicode"</span></code> to
|
||
generate a Unicode string (otherwise, a bytestring is generated). <em>method</em>
|
||
is either <code class="docutils literal notranslate"><span class="pre">"xml"</span></code>, <code class="docutils literal notranslate"><span class="pre">"html"</span></code> or <code class="docutils literal notranslate"><span class="pre">"text"</span></code> (default is <code class="docutils literal notranslate"><span class="pre">"xml"</span></code>).
|
||
<em>short_empty_elements</em> has the same meaning as in <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a>.
|
||
Returns a list of (optionally) encoded strings containing the XML data.
|
||
It does not guarantee any specific sequence, except that
|
||
<code class="docutils literal notranslate"><span class="pre">b"".join(tostringlist(element))</span> <span class="pre">==</span> <span class="pre">tostring(element)</span></code>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.4: </span>The <em>short_empty_elements</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.XML">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">XML</code><span class="sig-paren">(</span><em>text</em>, <em>parser=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XML" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parses an XML section from a string constant. This function can be used to
|
||
embed “XML literals” in Python code. <em>text</em> is a string containing XML
|
||
data. <em>parser</em> is an optional parser instance. If not given, the standard
|
||
<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used. Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="xml.etree.ElementTree.XMLID">
|
||
<code class="descclassname">xml.etree.ElementTree.</code><code class="descname">XMLID</code><span class="sig-paren">(</span><em>text</em>, <em>parser=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLID" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parses an XML section from a string constant, and also returns a dictionary
|
||
which maps from element id:s to elements. <em>text</em> is a string containing XML
|
||
data. <em>parser</em> is an optional parser instance. If not given, the standard
|
||
<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used. Returns a tuple containing an
|
||
<a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance and a dictionary.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="element-objects">
|
||
<span id="elementtree-element-objects"></span><h3>Element Objects<a class="headerlink" href="#element-objects" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="xml.etree.ElementTree.Element">
|
||
<em class="property">class </em><code class="descclassname">xml.etree.ElementTree.</code><code class="descname">Element</code><span class="sig-paren">(</span><em>tag</em>, <em>attrib={}</em>, <em>**extra</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Element class. This class defines the Element interface, and provides a
|
||
reference implementation of this interface.</p>
|
||
<p>The element name, attribute names, and attribute values can be either
|
||
bytestrings or Unicode strings. <em>tag</em> is the element name. <em>attrib</em> is
|
||
an optional dictionary, containing element attributes. <em>extra</em> contains
|
||
additional attributes, given as keyword arguments.</p>
|
||
<dl class="attribute">
|
||
<dt id="xml.etree.ElementTree.Element.tag">
|
||
<code class="descname">tag</code><a class="headerlink" href="#xml.etree.ElementTree.Element.tag" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A string identifying what kind of data this element represents (the
|
||
element type, in other words).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="xml.etree.ElementTree.Element.text">
|
||
<code class="descname">text</code><a class="headerlink" href="#xml.etree.ElementTree.Element.text" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="xml.etree.ElementTree.Element.tail">
|
||
<code class="descname">tail</code><a class="headerlink" href="#xml.etree.ElementTree.Element.tail" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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 <em>text</em> attribute holds either the text between
|
||
the element’s start tag and its first child or end tag, or <code class="docutils literal notranslate"><span class="pre">None</span></code>, and
|
||
the <em>tail</em> attribute holds either the text between the element’s
|
||
end tag and the next tag, or <code class="docutils literal notranslate"><span class="pre">None</span></code>. For the XML data</p>
|
||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><a><b></span>1<span class="nt"><c></span>2<span class="nt"><d/></span>3<span class="nt"></c></b></span>4<span class="nt"></a></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>the <em>a</em> element has <code class="docutils literal notranslate"><span class="pre">None</span></code> for both <em>text</em> and <em>tail</em> attributes,
|
||
the <em>b</em> element has <em>text</em> <code class="docutils literal notranslate"><span class="pre">"1"</span></code> and <em>tail</em> <code class="docutils literal notranslate"><span class="pre">"4"</span></code>,
|
||
the <em>c</em> element has <em>text</em> <code class="docutils literal notranslate"><span class="pre">"2"</span></code> and <em>tail</em> <code class="docutils literal notranslate"><span class="pre">None</span></code>,
|
||
and the <em>d</em> element has <em>text</em> <code class="docutils literal notranslate"><span class="pre">None</span></code> and <em>tail</em> <code class="docutils literal notranslate"><span class="pre">"3"</span></code>.</p>
|
||
<p>To collect the inner text of an element, see <a class="reference internal" href="#xml.etree.ElementTree.Element.itertext" title="xml.etree.ElementTree.Element.itertext"><code class="xref py py-meth docutils literal notranslate"><span class="pre">itertext()</span></code></a>, for
|
||
example <code class="docutils literal notranslate"><span class="pre">"".join(element.itertext())</span></code>.</p>
|
||
<p>Applications may store arbitrary objects in these attributes.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="xml.etree.ElementTree.Element.attrib">
|
||
<code class="descname">attrib</code><a class="headerlink" href="#xml.etree.ElementTree.Element.attrib" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A dictionary containing the element’s attributes. Note that while the
|
||
<em>attrib</em> 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.</p>
|
||
</dd></dl>
|
||
|
||
<p>The following dictionary-like methods work on the element attributes.</p>
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.clear">
|
||
<code class="descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.clear" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Resets an element. This function removes all subelements, clears all
|
||
attributes, and sets the text and tail attributes to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.get">
|
||
<code class="descname">get</code><span class="sig-paren">(</span><em>key</em>, <em>default=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.get" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Gets the element attribute named <em>key</em>.</p>
|
||
<p>Returns the attribute value, or <em>default</em> if the attribute was not found.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.items">
|
||
<code class="descname">items</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.items" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the element attributes as a sequence of (name, value) pairs. The
|
||
attributes are returned in an arbitrary order.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.keys">
|
||
<code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.keys" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the elements attribute names as a list. The names are returned
|
||
in an arbitrary order.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.set">
|
||
<code class="descname">set</code><span class="sig-paren">(</span><em>key</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.set" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the attribute <em>key</em> on the element to <em>value</em>.</p>
|
||
</dd></dl>
|
||
|
||
<p>The following methods work on the element’s children (subelements).</p>
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.append">
|
||
<code class="descname">append</code><span class="sig-paren">(</span><em>subelement</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.append" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Adds the element <em>subelement</em> to the end of this element’s internal list
|
||
of subelements. Raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <em>subelement</em> is not an
|
||
<a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.extend">
|
||
<code class="descname">extend</code><span class="sig-paren">(</span><em>subelements</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.extend" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Appends <em>subelements</em> from a sequence object with zero or more elements.
|
||
Raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if a subelement is not an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.find">
|
||
<code class="descname">find</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.find" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Finds the first subelement matching <em>match</em>. <em>match</em> may be a tag name
|
||
or a <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">path</span></a>. Returns an element instance
|
||
or <code class="docutils literal notranslate"><span class="pre">None</span></code>. <em>namespaces</em> is an optional mapping from namespace prefix
|
||
to full name.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.findall">
|
||
<code class="descname">findall</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.findall" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Finds all matching subelements, by tag name or
|
||
<a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">path</span></a>. Returns a list containing all matching
|
||
elements in document order. <em>namespaces</em> is an optional mapping from
|
||
namespace prefix to full name.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.findtext">
|
||
<code class="descname">findtext</code><span class="sig-paren">(</span><em>match</em>, <em>default=None</em>, <em>namespaces=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.findtext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Finds text for the first subelement matching <em>match</em>. <em>match</em> may be
|
||
a tag name or a <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">path</span></a>. Returns the text content
|
||
of the first matching element, or <em>default</em> if no element was found.
|
||
Note that if the matching element has no text content an empty string
|
||
is returned. <em>namespaces</em> is an optional mapping from namespace prefix
|
||
to full name.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.getchildren">
|
||
<code class="descname">getchildren</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.getchildren" title="Permalink to this definition">¶</a></dt>
|
||
<dd><div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.2: </span>Use <code class="docutils literal notranslate"><span class="pre">list(elem)</span></code> or iteration.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.getiterator">
|
||
<code class="descname">getiterator</code><span class="sig-paren">(</span><em>tag=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.getiterator" title="Permalink to this definition">¶</a></dt>
|
||
<dd><div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.2: </span>Use method <a class="reference internal" href="#xml.etree.ElementTree.Element.iter" title="xml.etree.ElementTree.Element.iter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.iter()</span></code></a> instead.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.insert">
|
||
<code class="descname">insert</code><span class="sig-paren">(</span><em>index</em>, <em>subelement</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.insert" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Inserts <em>subelement</em> at the given position in this element. Raises
|
||
<a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <em>subelement</em> is not an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.iter">
|
||
<code class="descname">iter</code><span class="sig-paren">(</span><em>tag=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.iter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creates a tree <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> with the current element as the root.
|
||
The iterator iterates over this element and all elements below it, in
|
||
document (depth first) order. If <em>tag</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code> or <code class="docutils literal notranslate"><span class="pre">'*'</span></code>, only
|
||
elements whose tag equals <em>tag</em> are returned from the iterator. If the
|
||
tree structure is modified during iteration, the result is undefined.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.iterfind">
|
||
<code class="descname">iterfind</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.iterfind" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Finds all matching subelements, by tag name or
|
||
<a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">path</span></a>. Returns an iterable yielding all
|
||
matching elements in document order. <em>namespaces</em> is an optional mapping
|
||
from namespace prefix to full name.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.itertext">
|
||
<code class="descname">itertext</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.itertext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creates a text iterator. The iterator loops over this element and all
|
||
subelements, in document order, and returns all inner text.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.makeelement">
|
||
<code class="descname">makeelement</code><span class="sig-paren">(</span><em>tag</em>, <em>attrib</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.makeelement" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creates a new element object of the same type as this element. Do not
|
||
call this method, use the <a class="reference internal" href="#xml.etree.ElementTree.SubElement" title="xml.etree.ElementTree.SubElement"><code class="xref py py-func docutils literal notranslate"><span class="pre">SubElement()</span></code></a> factory function instead.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.Element.remove">
|
||
<code class="descname">remove</code><span class="sig-paren">(</span><em>subelement</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.remove" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Removes <em>subelement</em> from the element. Unlike the find* methods this
|
||
method compares elements based on the instance identity, not on tag value
|
||
or contents.</p>
|
||
</dd></dl>
|
||
|
||
<p><a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> objects also support the following sequence type methods
|
||
for working with subelements: <a class="reference internal" href="../reference/datamodel.html#object.__delitem__" title="object.__delitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delitem__()</span></code></a>,
|
||
<a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a>,
|
||
<a class="reference internal" href="../reference/datamodel.html#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code></a>.</p>
|
||
<p>Caution: Elements with no subelements will test as <code class="docutils literal notranslate"><span class="pre">False</span></code>. This behavior
|
||
will change in future versions. Use specific <code class="docutils literal notranslate"><span class="pre">len(elem)</span></code> or <code class="docutils literal notranslate"><span class="pre">elem</span> <span class="pre">is</span>
|
||
<span class="pre">None</span></code> test instead.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">element</span> <span class="o">=</span> <span class="n">root</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span>
|
||
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">element</span><span class="p">:</span> <span class="c1"># careful!</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"element not found, or element has no subelements"</span><span class="p">)</span>
|
||
|
||
<span class="k">if</span> <span class="n">element</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"element not found"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="elementtree-objects">
|
||
<span id="elementtree-elementtree-objects"></span><h3>ElementTree Objects<a class="headerlink" href="#elementtree-objects" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="xml.etree.ElementTree.ElementTree">
|
||
<em class="property">class </em><code class="descclassname">xml.etree.ElementTree.</code><code class="descname">ElementTree</code><span class="sig-paren">(</span><em>element=None</em>, <em>file=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>ElementTree wrapper class. This class represents an entire element
|
||
hierarchy, and adds some extra support for serialization to and from
|
||
standard XML.</p>
|
||
<p><em>element</em> is the root element. The tree is initialized with the contents
|
||
of the XML <em>file</em> if given.</p>
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree._setroot">
|
||
<code class="descname">_setroot</code><span class="sig-paren">(</span><em>element</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree._setroot" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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. <em>element</em> is an element instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.find">
|
||
<code class="descname">find</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.find" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Same as <a class="reference internal" href="#xml.etree.ElementTree.Element.find" title="xml.etree.ElementTree.Element.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.find()</span></code></a>, starting at the root of the tree.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.findall">
|
||
<code class="descname">findall</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.findall" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Same as <a class="reference internal" href="#xml.etree.ElementTree.Element.findall" title="xml.etree.ElementTree.Element.findall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.findall()</span></code></a>, starting at the root of the tree.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.findtext">
|
||
<code class="descname">findtext</code><span class="sig-paren">(</span><em>match</em>, <em>default=None</em>, <em>namespaces=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.findtext" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Same as <a class="reference internal" href="#xml.etree.ElementTree.Element.findtext" title="xml.etree.ElementTree.Element.findtext"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.findtext()</span></code></a>, starting at the root of the tree.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.getiterator">
|
||
<code class="descname">getiterator</code><span class="sig-paren">(</span><em>tag=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.getiterator" title="Permalink to this definition">¶</a></dt>
|
||
<dd><div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.2: </span>Use method <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.iter" title="xml.etree.ElementTree.ElementTree.iter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.iter()</span></code></a> instead.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.getroot">
|
||
<code class="descname">getroot</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.getroot" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the root element for this tree.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.iter">
|
||
<code class="descname">iter</code><span class="sig-paren">(</span><em>tag=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.iter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creates and returns a tree iterator for the root element. The iterator
|
||
loops over all elements in this tree, in section order. <em>tag</em> is the tag
|
||
to look for (default is to return all elements).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.iterfind">
|
||
<code class="descname">iterfind</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.iterfind" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Same as <a class="reference internal" href="#xml.etree.ElementTree.Element.iterfind" title="xml.etree.ElementTree.Element.iterfind"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.iterfind()</span></code></a>, starting at the root of the tree.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.parse">
|
||
<code class="descname">parse</code><span class="sig-paren">(</span><em>source</em>, <em>parser=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.parse" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Loads an external XML section into this element tree. <em>source</em> is a file
|
||
name or <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>. <em>parser</em> is an optional parser instance.
|
||
If not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used. Returns the
|
||
section root element.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.ElementTree.write">
|
||
<code class="descname">write</code><span class="sig-paren">(</span><em>file</em>, <em>encoding="us-ascii"</em>, <em>xml_declaration=None</em>, <em>default_namespace=None</em>, <em>method="xml"</em>, <em>*</em>, <em>short_empty_elements=True</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Writes the element tree to a file, as XML. <em>file</em> is a file name, or a
|
||
<a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> opened for writing. <em>encoding</em> <a class="footnote-reference brackets" href="#id5" id="id3">1</a> is the output
|
||
encoding (default is US-ASCII).
|
||
<em>xml_declaration</em> controls if an XML declaration should be added to the
|
||
file. Use <code class="docutils literal notranslate"><span class="pre">False</span></code> for never, <code class="docutils literal notranslate"><span class="pre">True</span></code> for always, <code class="docutils literal notranslate"><span class="pre">None</span></code>
|
||
for only if not US-ASCII or UTF-8 or Unicode (default is <code class="docutils literal notranslate"><span class="pre">None</span></code>).
|
||
<em>default_namespace</em> sets the default XML namespace (for “xmlns”).
|
||
<em>method</em> is either <code class="docutils literal notranslate"><span class="pre">"xml"</span></code>, <code class="docutils literal notranslate"><span class="pre">"html"</span></code> or <code class="docutils literal notranslate"><span class="pre">"text"</span></code> (default is
|
||
<code class="docutils literal notranslate"><span class="pre">"xml"</span></code>).
|
||
The keyword-only <em>short_empty_elements</em> parameter controls the formatting
|
||
of elements that contain no content. If <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), they are
|
||
emitted as a single self-closed tag, otherwise they are emitted as a pair
|
||
of start/end tags.</p>
|
||
<p>The output is either a string (<a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) or binary (<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>).
|
||
This is controlled by the <em>encoding</em> argument. If <em>encoding</em> is
|
||
<code class="docutils literal notranslate"><span class="pre">"unicode"</span></code>, the output is a string; otherwise, it’s binary. Note that
|
||
this may conflict with the type of <em>file</em> if it’s an open
|
||
<a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>; make sure you do not try to write a string to a
|
||
binary stream and vice versa.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.4: </span>The <em>short_empty_elements</em> parameter.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<p>This is the XML file that is going to be manipulated:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">html</span><span class="o">></span>
|
||
<span class="o"><</span><span class="n">head</span><span class="o">></span>
|
||
<span class="o"><</span><span class="n">title</span><span class="o">></span><span class="n">Example</span> <span class="n">page</span><span class="o"></</span><span class="n">title</span><span class="o">></span>
|
||
<span class="o"></</span><span class="n">head</span><span class="o">></span>
|
||
<span class="o"><</span><span class="n">body</span><span class="o">></span>
|
||
<span class="o"><</span><span class="n">p</span><span class="o">></span><span class="n">Moved</span> <span class="n">to</span> <span class="o"><</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">"http://example.org/"</span><span class="o">></span><span class="n">example</span><span class="o">.</span><span class="n">org</span><span class="o"></</span><span class="n">a</span><span class="o">></span>
|
||
<span class="ow">or</span> <span class="o"><</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">"http://example.com/"</span><span class="o">></span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o"></</span><span class="n">a</span><span class="o">>.</</span><span class="n">p</span><span class="o">></span>
|
||
<span class="o"></</span><span class="n">body</span><span class="o">></span>
|
||
<span class="o"></</span><span class="n">html</span><span class="o">></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Example of changing the attribute “target” of every link in first paragraph:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">xml.etree.ElementTree</span> <span class="k">import</span> <span class="n">ElementTree</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span> <span class="o">=</span> <span class="n">ElementTree</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">"index.xhtml"</span><span class="p">)</span>
|
||
<span class="go"><Element 'html' at 0xb77e6fac></span>
|
||
<span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">tree</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s2">"body/p"</span><span class="p">)</span> <span class="c1"># Finds first occurrence of tag p in body</span>
|
||
<span class="gp">>>> </span><span class="n">p</span>
|
||
<span class="go"><Element 'p' at 0xb77ec26c></span>
|
||
<span class="gp">>>> </span><span class="n">links</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">iter</span><span class="p">(</span><span class="s2">"a"</span><span class="p">))</span> <span class="c1"># Returns list of all links</span>
|
||
<span class="gp">>>> </span><span class="n">links</span>
|
||
<span class="go">[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">links</span><span class="p">:</span> <span class="c1"># Iterates through all found links</span>
|
||
<span class="gp">... </span> <span class="n">i</span><span class="o">.</span><span class="n">attrib</span><span class="p">[</span><span class="s2">"target"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"blank"</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">"output.xhtml"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="qname-objects">
|
||
<span id="elementtree-qname-objects"></span><h3>QName Objects<a class="headerlink" href="#qname-objects" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="xml.etree.ElementTree.QName">
|
||
<em class="property">class </em><code class="descclassname">xml.etree.ElementTree.</code><code class="descname">QName</code><span class="sig-paren">(</span><em>text_or_uri</em>, <em>tag=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.QName" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>QName wrapper. This can be used to wrap a QName attribute value, in order
|
||
to get proper namespace handling on output. <em>text_or_uri</em> is a string
|
||
containing the QName value, in the form {uri}local, or, if the tag argument
|
||
is given, the URI part of a QName. If <em>tag</em> is given, the first argument is
|
||
interpreted as a URI, and this argument is interpreted as a local name.
|
||
<a class="reference internal" href="#xml.etree.ElementTree.QName" title="xml.etree.ElementTree.QName"><code class="xref py py-class docutils literal notranslate"><span class="pre">QName</span></code></a> instances are opaque.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="treebuilder-objects">
|
||
<span id="elementtree-treebuilder-objects"></span><h3>TreeBuilder Objects<a class="headerlink" href="#treebuilder-objects" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="xml.etree.ElementTree.TreeBuilder">
|
||
<em class="property">class </em><code class="descclassname">xml.etree.ElementTree.</code><code class="descname">TreeBuilder</code><span class="sig-paren">(</span><em>element_factory=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Generic element structure builder. This builder converts a sequence of
|
||
start, data, and end method calls to a well-formed element structure. You
|
||
can use this class to build an element structure using a custom XML parser,
|
||
or a parser for some other XML-like format. <em>element_factory</em>, when given,
|
||
must be a callable accepting two positional arguments: a tag and
|
||
a dict of attributes. It is expected to return a new element instance.</p>
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.TreeBuilder.close">
|
||
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Flushes the builder buffers, and returns the toplevel document
|
||
element. Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.TreeBuilder.data">
|
||
<code class="descname">data</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.data" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Adds text to the current element. <em>data</em> is a string. This should be
|
||
either a bytestring, or a Unicode string.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.TreeBuilder.end">
|
||
<code class="descname">end</code><span class="sig-paren">(</span><em>tag</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.end" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Closes the current element. <em>tag</em> is the element name. Returns the
|
||
closed element.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.TreeBuilder.start">
|
||
<code class="descname">start</code><span class="sig-paren">(</span><em>tag</em>, <em>attrs</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.start" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Opens a new element. <em>tag</em> is the element name. <em>attrs</em> is a dictionary
|
||
containing element attributes. Returns the opened element.</p>
|
||
</dd></dl>
|
||
|
||
<p>In addition, a custom <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> object can provide the
|
||
following method:</p>
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.TreeBuilder.doctype">
|
||
<code class="descname">doctype</code><span class="sig-paren">(</span><em>name</em>, <em>pubid</em>, <em>system</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.doctype" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Handles a doctype declaration. <em>name</em> is the doctype name. <em>pubid</em> is
|
||
the public identifier. <em>system</em> is the system identifier. This method
|
||
does not exist on the default <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> class.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="xmlparser-objects">
|
||
<span id="elementtree-xmlparser-objects"></span><h3>XMLParser Objects<a class="headerlink" href="#xmlparser-objects" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="xml.etree.ElementTree.XMLParser">
|
||
<em class="property">class </em><code class="descclassname">xml.etree.ElementTree.</code><code class="descname">XMLParser</code><span class="sig-paren">(</span><em>html=0</em>, <em>target=None</em>, <em>encoding=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLParser" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This class is the low-level building block of the module. It uses
|
||
<a class="reference internal" href="pyexpat.html#module-xml.parsers.expat" title="xml.parsers.expat: An interface to the Expat non-validating XML parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.parsers.expat</span></code></a> for efficient, event-based parsing of XML. It can
|
||
be fed XML data incrementally with the <a class="reference internal" href="#xml.etree.ElementTree.XMLParser.feed" title="xml.etree.ElementTree.XMLParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">feed()</span></code></a> method, and parsing
|
||
events are translated to a push API - by invoking callbacks on the <em>target</em>
|
||
object. If <em>target</em> is omitted, the standard <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> is used.
|
||
The <em>html</em> argument was historically used for backwards compatibility and is
|
||
now deprecated. If <em>encoding</em> <a class="footnote-reference brackets" href="#id5" id="id4">1</a> is given, the value overrides the
|
||
encoding specified in the XML file.</p>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.4: </span>The <em>html</em> argument. The remaining arguments should be passed via
|
||
keyword to prepare for the removal of the <em>html</em> argument.</p>
|
||
</div>
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.XMLParser.close">
|
||
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLParser.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Finishes feeding data to the parser. Returns the result of calling the
|
||
<code class="docutils literal notranslate"><span class="pre">close()</span></code> method of the <em>target</em> passed during construction; by default,
|
||
this is the toplevel document element.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.XMLParser.doctype">
|
||
<code class="descname">doctype</code><span class="sig-paren">(</span><em>name</em>, <em>pubid</em>, <em>system</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLParser.doctype" title="Permalink to this definition">¶</a></dt>
|
||
<dd><div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.2: </span>Define the <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder.doctype" title="xml.etree.ElementTree.TreeBuilder.doctype"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TreeBuilder.doctype()</span></code></a> method on a custom TreeBuilder
|
||
target.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.XMLParser.feed">
|
||
<code class="descname">feed</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLParser.feed" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Feeds data to the parser. <em>data</em> is encoded data.</p>
|
||
</dd></dl>
|
||
|
||
<p><a class="reference internal" href="#xml.etree.ElementTree.XMLParser.feed" title="xml.etree.ElementTree.XMLParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLParser.feed()</span></code></a> calls <em>target</em>’s <code class="docutils literal notranslate"><span class="pre">start(tag,</span> <span class="pre">attrs_dict)</span></code> method
|
||
for each opening tag, its <code class="docutils literal notranslate"><span class="pre">end(tag)</span></code> method for each closing tag, and data
|
||
is processed by method <code class="docutils literal notranslate"><span class="pre">data(data)</span></code>. <a class="reference internal" href="#xml.etree.ElementTree.XMLParser.close" title="xml.etree.ElementTree.XMLParser.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLParser.close()</span></code></a> calls
|
||
<em>target</em>’s method <code class="docutils literal notranslate"><span class="pre">close()</span></code>. <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> can be used not only for
|
||
building a tree structure. This is an example of counting the maximum depth
|
||
of an XML file:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">xml.etree.ElementTree</span> <span class="k">import</span> <span class="n">XMLParser</span>
|
||
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">MaxDepth</span><span class="p">:</span> <span class="c1"># The target object of the parser</span>
|
||
<span class="gp">... </span> <span class="n">maxDepth</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="gp">... </span> <span class="n">depth</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="gp">... </span> <span class="k">def</span> <span class="nf">start</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tag</span><span class="p">,</span> <span class="n">attrib</span><span class="p">):</span> <span class="c1"># Called for each opening tag.</span>
|
||
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="gp">... </span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">></span> <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span>
|
||
<span class="gp">... </span> <span class="k">def</span> <span class="nf">end</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tag</span><span class="p">):</span> <span class="c1"># Called for each closing tag.</span>
|
||
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">-=</span> <span class="mi">1</span>
|
||
<span class="gp">... </span> <span class="k">def</span> <span class="nf">data</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">pass</span> <span class="c1"># We do not need to do anything with data.</span>
|
||
<span class="gp">... </span> <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="c1"># Called when all data has been parsed.</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">target</span> <span class="o">=</span> <span class="n">MaxDepth</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">XMLParser</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">target</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">exampleXml</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2"><a></span>
|
||
<span class="gp">... </span><span class="s2"> <b></span>
|
||
<span class="gp">... </span><span class="s2"> </b></span>
|
||
<span class="gp">... </span><span class="s2"> <b></span>
|
||
<span class="gp">... </span><span class="s2"> <c></span>
|
||
<span class="gp">... </span><span class="s2"> <d></span>
|
||
<span class="gp">... </span><span class="s2"> </d></span>
|
||
<span class="gp">... </span><span class="s2"> </c></span>
|
||
<span class="gp">... </span><span class="s2"> </b></span>
|
||
<span class="gp">... </span><span class="s2"></a>"""</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="n">exampleXml</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
<span class="go">4</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="xmlpullparser-objects">
|
||
<span id="elementtree-xmlpullparser-objects"></span><h3>XMLPullParser Objects<a class="headerlink" href="#xmlpullparser-objects" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="xml.etree.ElementTree.XMLPullParser">
|
||
<em class="property">class </em><code class="descclassname">xml.etree.ElementTree.</code><code class="descname">XMLPullParser</code><span class="sig-paren">(</span><em>events=None</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A pull parser suitable for non-blocking applications. Its input-side API is
|
||
similar to that of <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a>, but instead of pushing calls to a
|
||
callback target, <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a> collects an internal list of parsing
|
||
events and lets the user read from it. <em>events</em> is a sequence of events to
|
||
report back. The supported events are the strings <code class="docutils literal notranslate"><span class="pre">"start"</span></code>, <code class="docutils literal notranslate"><span class="pre">"end"</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">"start-ns"</span></code> and <code class="docutils literal notranslate"><span class="pre">"end-ns"</span></code> (the “ns” events are used to get detailed
|
||
namespace information). If <em>events</em> is omitted, only <code class="docutils literal notranslate"><span class="pre">"end"</span></code> events are
|
||
reported.</p>
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.XMLPullParser.feed">
|
||
<code class="descname">feed</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser.feed" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Feed the given bytes data to the parser.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.XMLPullParser.close">
|
||
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Signal the parser that the data stream is terminated. Unlike
|
||
<a class="reference internal" href="#xml.etree.ElementTree.XMLParser.close" title="xml.etree.ElementTree.XMLParser.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLParser.close()</span></code></a>, this method always returns <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.
|
||
Any events not yet retrieved when the parser is closed can still be
|
||
read with <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_events()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="xml.etree.ElementTree.XMLPullParser.read_events">
|
||
<code class="descname">read_events</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return an iterator over the events which have been encountered in the
|
||
data fed to the
|
||
parser. The iterator yields <code class="docutils literal notranslate"><span class="pre">(event,</span> <span class="pre">elem)</span></code> pairs, where <em>event</em> is a
|
||
string representing the type of event (e.g. <code class="docutils literal notranslate"><span class="pre">"end"</span></code>) and <em>elem</em> is the
|
||
encountered <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> object.</p>
|
||
<p>Events provided in a previous call to <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_events()</span></code></a> will not be
|
||
yielded again. Events are consumed from the internal queue only when
|
||
they are retrieved from the iterator, so multiple readers iterating in
|
||
parallel over iterators obtained from <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_events()</span></code></a> will have
|
||
unpredictable results.</p>
|
||
</dd></dl>
|
||
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p><a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a> only guarantees that it has seen the “>”
|
||
character of a starting tag when it emits a “start” event, so the
|
||
attributes are defined, but the contents of the text and tail attributes
|
||
are undefined at that point. The same applies to the element children;
|
||
they may or may not be present.</p>
|
||
<p>If you need a fully populated element, look for “end” events instead.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="exceptions">
|
||
<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="xml.etree.ElementTree.ParseError">
|
||
<em class="property">class </em><code class="descclassname">xml.etree.ElementTree.</code><code class="descname">ParseError</code><a class="headerlink" href="#xml.etree.ElementTree.ParseError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>XML parse error, raised by the various parsing methods in this module when
|
||
parsing fails. The string representation of an instance of this exception
|
||
will contain a user-friendly error message. In addition, it will have
|
||
the following attributes available:</p>
|
||
<dl class="attribute">
|
||
<dt id="xml.etree.ElementTree.ParseError.code">
|
||
<code class="descname">code</code><a class="headerlink" href="#xml.etree.ElementTree.ParseError.code" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A numeric error code from the expat parser. See the documentation of
|
||
<a class="reference internal" href="pyexpat.html#module-xml.parsers.expat" title="xml.parsers.expat: An interface to the Expat non-validating XML parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.parsers.expat</span></code></a> for the list of error codes and their meanings.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="xml.etree.ElementTree.ParseError.position">
|
||
<code class="descname">position</code><a class="headerlink" href="#xml.etree.ElementTree.ParseError.position" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A tuple of <em>line</em>, <em>column</em> numbers, specifying where the error occurred.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<p class="rubric">Footnotes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="id5"><span class="brackets">1</span><span class="fn-backref">(<a href="#id1">1</a>,<a href="#id2">2</a>,<a href="#id3">3</a>,<a href="#id4">4</a>)</span></dt>
|
||
<dd><p>The encoding string included in XML output should conform to the
|
||
appropriate standards. For example, “UTF-8” is valid, but “UTF8” is
|
||
not. See <a class="reference external" href="https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl">https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl</a>
|
||
and <a class="reference external" href="https://www.iana.org/assignments/character-sets/character-sets.xhtml">https://www.iana.org/assignments/character-sets/character-sets.xhtml</a>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code> — The ElementTree XML API</a><ul>
|
||
<li><a class="reference internal" href="#tutorial">Tutorial</a><ul>
|
||
<li><a class="reference internal" href="#xml-tree-and-elements">XML tree and elements</a></li>
|
||
<li><a class="reference internal" href="#parsing-xml">Parsing XML</a></li>
|
||
<li><a class="reference internal" href="#pull-api-for-non-blocking-parsing">Pull API for non-blocking parsing</a></li>
|
||
<li><a class="reference internal" href="#finding-interesting-elements">Finding interesting elements</a></li>
|
||
<li><a class="reference internal" href="#modifying-an-xml-file">Modifying an XML File</a></li>
|
||
<li><a class="reference internal" href="#building-xml-documents">Building XML documents</a></li>
|
||
<li><a class="reference internal" href="#parsing-xml-with-namespaces">Parsing XML with Namespaces</a></li>
|
||
<li><a class="reference internal" href="#additional-resources">Additional resources</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#xpath-support">XPath support</a><ul>
|
||
<li><a class="reference internal" href="#example">Example</a></li>
|
||
<li><a class="reference internal" href="#supported-xpath-syntax">Supported XPath syntax</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#reference">Reference</a><ul>
|
||
<li><a class="reference internal" href="#functions">Functions</a></li>
|
||
<li><a class="reference internal" href="#element-objects">Element Objects</a></li>
|
||
<li><a class="reference internal" href="#elementtree-objects">ElementTree Objects</a></li>
|
||
<li><a class="reference internal" href="#qname-objects">QName Objects</a></li>
|
||
<li><a class="reference internal" href="#treebuilder-objects">TreeBuilder Objects</a></li>
|
||
<li><a class="reference internal" href="#xmlparser-objects">XMLParser Objects</a></li>
|
||
<li><a class="reference internal" href="#xmlpullparser-objects">XMLPullParser Objects</a></li>
|
||
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="xml.html"
|
||
title="previous chapter">XML Processing Modules</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="xml.dom.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.dom</span></code> — The Document Object Model API</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/xml.etree.elementtree.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="xml.dom.html" title="xml.dom — The Document Object Model API"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="xml.html" title="XML Processing Modules"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="markup.html" >Structured Markup Processing Tools</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |