uTools-Manuals/docs/python/xml.etree.elementtree.html

239 lines
128 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div class="body" role="main"><div class="section" id="module-xml.etree.ElementTree"><h1><span class="yiyi-st" id="yiyi-10">20.5. <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"><span class="pre">xml.etree.ElementTree</span></code></a> — The ElementTree XML API</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>Source code:</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/xml/etree/ElementTree.py">Lib/xml/etree/ElementTree.py</a></span></p><p><span class="yiyi-st" id="yiyi-12">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"><span class="pre">xml.etree.ElementTree</span></code></a> module implements a simple and efficient API for parsing and creating XML data.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-13"><span class="versionmodified">Changed in version 3.3: </span>This module will use a fast implementation whenever available. </span><span class="yiyi-st" id="yiyi-14">The <code class="xref py py-mod docutils literal"><span class="pre">xml.etree.cElementTree</span></code> module is deprecated.</span></p></div><div class="admonition warning"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-15">Warning</span></p><p class="last"><span class="yiyi-st" id="yiyi-16">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"><span class="pre">xml.etree.ElementTree</span></code></a> module is not secure against maliciously constructed data. </span><span class="yiyi-st" id="yiyi-17">If you need to parse untrusted or unauthenticated data see <a class="reference internal" href="xml.html#xml-vulnerabilities"><span>XML vulnerabilities</span></a>.</span></p></div><div class="section" id="tutorial"><h2><span class="yiyi-st" id="yiyi-18">20.5.1. </span><span class="yiyi-st" id="yiyi-19">Tutorial</span></h2><p><span class="yiyi-st" id="yiyi-20">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"><span class="pre">xml.etree.ElementTree</span></code></a> (<code class="docutils literal"><span class="pre">ET</span></code> in short). </span><span class="yiyi-st" id="yiyi-21">The goal is to demonstrate some of the building blocks and basic concepts of the module.</span></p><div class="section" id="xml-tree-and-elements"><h3><span class="yiyi-st" id="yiyi-22">20.5.1.1. </span><span class="yiyi-st" id="yiyi-23">XML tree and elements</span></h3><p><span class="yiyi-st" id="yiyi-24">XML is an inherently hierarchical data format, and the most natural way to represent it is with a tree. </span><span class="yiyi-st" id="yiyi-25"><code class="docutils literal"><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"><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"><span class="pre">Element</span></code></a> represents a single node in this tree. </span><span class="yiyi-st" id="yiyi-26">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"><span class="pre">ElementTree</span></code></a> level. </span><span class="yiyi-st" id="yiyi-27">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"><span class="pre">Element</span></code></a> level.</span></p></div><div class="section" id="parsing-xml"><h3><span class="yiyi-st" id="yiyi-28">20.5.1.2. </span><span class="yiyi-st" id="yiyi-29">Parsing XML</span></h3><p><span class="yiyi-st" id="yiyi-30">Well be using the following XML document as the sample data for this section:</span></p><div class="highlight-xml"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version="1.0"?&gt;</span>
<span class="nt">&lt;data&gt;</span>
<span class="nt">&lt;country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">&gt;</span>
<span class="nt">&lt;rank&gt;</span>1<span class="nt">&lt;/rank&gt;</span>
<span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>
<span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/country&gt;</span>
<span class="nt">&lt;country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">&gt;</span>
<span class="nt">&lt;rank&gt;</span>4<span class="nt">&lt;/rank&gt;</span>
<span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>
<span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/country&gt;</span>
<span class="nt">&lt;country</span> <span class="na">name=</span><span class="s">"Panama"</span><span class="nt">&gt;</span>
<span class="nt">&lt;rank&gt;</span>68<span class="nt">&lt;/rank&gt;</span>
<span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>
<span class="nt">&lt;gdppc&gt;</span>13600<span class="nt">&lt;/gdppc&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/country&gt;</span>
<span class="nt">&lt;/data&gt;</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-31">We can import this data by reading from a file:</span></p><pre><code class="language-python"><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>
</code></pre><p><span class="yiyi-st" id="yiyi-32">Or directly from a string:</span></p><pre><code class="language-python"><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>
</code></pre><p><span class="yiyi-st" id="yiyi-33"><a class="reference internal" href="#xml.etree.ElementTree.fromstring" title="xml.etree.ElementTree.fromstring"><code class="xref py py-func docutils literal"><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"><span class="pre">Element</span></code></a>, which is the root element of the parsed tree. </span><span class="yiyi-st" id="yiyi-34">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"><span class="pre">ElementTree</span></code></a>. </span><span class="yiyi-st" id="yiyi-35">Check the documentation to be sure.</span></p><p><span class="yiyi-st" id="yiyi-36">As an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal"><span class="pre">Element</span></code></a>, <code class="docutils literal"><span class="pre">root</span></code> has a tag and a dictionary of attributes:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">tag</span>
<span class="go">'data'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">attrib</span>
<span class="go">{}</span>
</code></pre><p><span class="yiyi-st" id="yiyi-37">它也有子节点,我们可以迭代:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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>
</code></pre><p><span class="yiyi-st" id="yiyi-38">Children are nested, and we can access specific child nodes by index:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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>
</code></pre><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-39">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-40">Not all elements of the XML input will end up as elements of the parsed tree. </span><span class="yiyi-st" id="yiyi-41">Currently, this module skips over any XML comments, processing instructions, and document type declarations in the input. </span><span class="yiyi-st" id="yiyi-42">Nevertheless, trees built using this modules API rather than parsing from XML text can have comments and processing instructions in them; they will be included when generating XML output. </span><span class="yiyi-st" id="yiyi-43">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"><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"><span class="pre">XMLParser</span></code></a> constructor.</span></p></div></div><div class="section" id="pull-api-for-non-blocking-parsing"><h3><span class="yiyi-st" id="yiyi-44">20.5.1.3. </span><span class="yiyi-st" id="yiyi-45">Pull API for non-blocking parsing</span></h3><p><span class="yiyi-st" id="yiyi-46">Most parsing functions provided by this module require the whole document to be read at once before returning any result. </span><span class="yiyi-st" id="yiyi-47">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"><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. </span><span class="yiyi-st" id="yiyi-48">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"><span class="pre">Element</span></code></a> objects.</span></p><p><span class="yiyi-st" id="yiyi-49">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"><span class="pre">XMLPullParser</span></code></a>. </span><span class="yiyi-st" id="yiyi-50">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"><span class="pre">XMLPullParser.feed()</span></code></a> calls. </span><span class="yiyi-st" id="yiyi-51">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"><span class="pre">XMLPullParser.read_events()</span></code></a>. </span><span class="yiyi-st" id="yiyi-52">Here is an example:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="s1">'&lt;mytag&gt;sometext'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </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', &lt;Element 'mytag' at 0x7fa66db2be58&gt;)]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="s1">' more text&lt;/mytag&gt;'</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </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>
</code></pre><p><span class="yiyi-st" id="yiyi-53">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. </span><span class="yiyi-st" id="yiyi-54">In such cases, blocking reads are unacceptable.</span></p><p><span class="yiyi-st" id="yiyi-55">Because its so flexible, <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal"><span class="pre">XMLPullParser</span></code></a> can be inconvenient to use for simpler use-cases. </span><span class="yiyi-st" id="yiyi-56">If you dont 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"><span class="pre">iterparse()</span></code></a>. </span><span class="yiyi-st" id="yiyi-57">It can be useful when youre reading a large XML document and dont want to hold it wholly in memory.</span></p></div><div class="section" id="finding-interesting-elements"><h3><span class="yiyi-st" id="yiyi-58">20.5.1.4. </span><span class="yiyi-st" id="yiyi-59">Finding interesting elements</span></h3><p><span class="yiyi-st" id="yiyi-60"><a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal"><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). </span><span class="yiyi-st" id="yiyi-61">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"><span class="pre">Element.iter()</span></code></a>:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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>
</code></pre><p><span class="yiyi-st" id="yiyi-62"><a class="reference internal" href="#xml.etree.ElementTree.Element.findall" title="xml.etree.ElementTree.Element.findall"><code class="xref py py-meth docutils literal"><span class="pre">Element.findall()</span></code></a> finds only elements with a tag which are direct children of the current element. </span><span class="yiyi-st" id="yiyi-63"><a class="reference internal" href="#xml.etree.ElementTree.Element.find" title="xml.etree.ElementTree.Element.find"><code class="xref py py-meth docutils literal"><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"><span class="pre">Element.text</span></code></a> accesses the elements text content. </span><span class="yiyi-st" id="yiyi-64"><a class="reference internal" href="#xml.etree.ElementTree.Element.get" title="xml.etree.ElementTree.Element.get"><code class="xref py py-meth docutils literal"><span class="pre">Element.get()</span></code></a> accesses the elements attributes:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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>
</code></pre><p><span class="yiyi-st" id="yiyi-65">More sophisticated specification of which elements to look for is possible by using <a class="reference internal" href="#elementtree-xpath"><span>XPath</span></a>.</span></p></div><div class="section" id="modifying-an-xml-file"><h3><span class="yiyi-st" id="yiyi-66">20.5.1.5. </span><span class="yiyi-st" id="yiyi-67">Modifying an XML File</span></h3><p><span class="yiyi-st" id="yiyi-68"><a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal"><span class="pre">ElementTree</span></code></a> provides a simple way to build XML documents and write them to files. </span><span class="yiyi-st" id="yiyi-69">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"><span class="pre">ElementTree.write()</span></code></a> method serves this purpose.</span></p><p><span class="yiyi-st" id="yiyi-70">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"><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"><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"><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"><span class="pre">Element.append()</span></code></a>).</span></p><p><span class="yiyi-st" id="yiyi-71">Lets say we want to add one to each countrys rank, and add an <code class="docutils literal"><span class="pre">updated</span></code> attribute to the rank element:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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>
</code></pre><p><span class="yiyi-st" id="yiyi-72">Our XML now looks like this:</span></p><div class="highlight-xml"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version="1.0"?&gt;</span>
<span class="nt">&lt;data&gt;</span>
<span class="nt">&lt;country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">&gt;</span>
<span class="nt">&lt;rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">&gt;</span>2<span class="nt">&lt;/rank&gt;</span>
<span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>
<span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/country&gt;</span>
<span class="nt">&lt;country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">&gt;</span>
<span class="nt">&lt;rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">&gt;</span>5<span class="nt">&lt;/rank&gt;</span>
<span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>
<span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/country&gt;</span>
<span class="nt">&lt;country</span> <span class="na">name=</span><span class="s">"Panama"</span><span class="nt">&gt;</span>
<span class="nt">&lt;rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">&gt;</span>69<span class="nt">&lt;/rank&gt;</span>
<span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>
<span class="nt">&lt;gdppc&gt;</span>13600<span class="nt">&lt;/gdppc&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/country&gt;</span>
<span class="nt">&lt;/data&gt;</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-73">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"><span class="pre">Element.remove()</span></code></a>. </span><span class="yiyi-st" id="yiyi-74">Lets say we want to remove all countries with a rank higher than 50:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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">&gt;</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">&gt;&gt;&gt; </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>
</code></pre><p><span class="yiyi-st" id="yiyi-75">Our XML now looks like this:</span></p><div class="highlight-xml"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version="1.0"?&gt;</span>
<span class="nt">&lt;data&gt;</span>
<span class="nt">&lt;country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">&gt;</span>
<span class="nt">&lt;rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">&gt;</span>2<span class="nt">&lt;/rank&gt;</span>
<span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>
<span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/country&gt;</span>
<span class="nt">&lt;country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">&gt;</span>
<span class="nt">&lt;rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">&gt;</span>5<span class="nt">&lt;/rank&gt;</span>
<span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>
<span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/country&gt;</span>
<span class="nt">&lt;/data&gt;</span>
</pre></div></div></div><div class="section" id="building-xml-documents"><h3><span class="yiyi-st" id="yiyi-76">20.5.1.6. </span><span class="yiyi-st" id="yiyi-77">Building XML documents</span></h3><p><span class="yiyi-st" id="yiyi-78">The <a class="reference internal" href="#xml.etree.ElementTree.SubElement" title="xml.etree.ElementTree.SubElement"><code class="xref py py-func docutils literal"><span class="pre">SubElement()</span></code></a> function also provides a convenient way to create new sub-elements for a given element:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&lt;a&gt;&lt;b /&gt;&lt;c&gt;&lt;d /&gt;&lt;/c&gt;&lt;/a&gt;</span>
</code></pre></div><div class="section" id="parsing-xml-with-namespaces"><h3><span class="yiyi-st" id="yiyi-79">20.5.1.7. </span><span class="yiyi-st" id="yiyi-80">Parsing XML with Namespaces</span></h3><p><span class="yiyi-st" id="yiyi-81">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"><span class="pre">prefix:sometag</span></code> get expanded to <code class="docutils literal"><span class="pre">{uri}sometag</span></code> where the <em>prefix</em> is replaced by the full <em>URI</em>. </span><span class="yiyi-st" id="yiyi-82">Also, if there is a <a class="reference external" href="https://www.w3.org/TR/2006/REC-xml-names-20060816/#defaulting">default namespace</a>, that full URI gets prepended to all of the non-prefixed tags.</span></p><p><span class="yiyi-st" id="yiyi-83">Here is an XML example that incorporates two namespaces, one with the prefix “fictional” and the other serving as the default namespace:</span></p><div class="highlight-xml"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version="1.0"?&gt;</span>
<span class="nt">&lt;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">&gt;</span>
<span class="nt">&lt;actor&gt;</span>
<span class="nt">&lt;name&gt;</span>John Cleese<span class="nt">&lt;/name&gt;</span>
<span class="nt">&lt;fictional:character&gt;</span>Lancelot<span class="nt">&lt;/fictional:character&gt;</span>
<span class="nt">&lt;fictional:character&gt;</span>Archie Leach<span class="nt">&lt;/fictional:character&gt;</span>
<span class="nt">&lt;/actor&gt;</span>
<span class="nt">&lt;actor&gt;</span>
<span class="nt">&lt;name&gt;</span>Eric Idle<span class="nt">&lt;/name&gt;</span>
<span class="nt">&lt;fictional:character&gt;</span>Sir Robin<span class="nt">&lt;/fictional:character&gt;</span>
<span class="nt">&lt;fictional:character&gt;</span>Gunther<span class="nt">&lt;/fictional:character&gt;</span>
<span class="nt">&lt;fictional:character&gt;</span>Commander Clement<span class="nt">&lt;/fictional:character&gt;</span>
<span class="nt">&lt;/actor&gt;</span>
<span class="nt">&lt;/actors&gt;</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-84">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"><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"><span class="pre">findall()</span></code></a>:</span></p><pre><code class="language-python"><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">' |--&gt;'</span><span class="p">,</span> <span class="n">char</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-85">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:</span></p><pre><code class="language-python"><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">' |--&gt;'</span><span class="p">,</span> <span class="n">char</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-86">These two approaches both output:</span></p><pre><code class="language-python"><span></span><span class="n">John</span> <span class="n">Cleese</span>
<span class="o">|--&gt;</span> <span class="n">Lancelot</span>
<span class="o">|--&gt;</span> <span class="n">Archie</span> <span class="n">Leach</span>
<span class="n">Eric</span> <span class="n">Idle</span>
<span class="o">|--&gt;</span> <span class="n">Sir</span> <span class="n">Robin</span>
<span class="o">|--&gt;</span> <span class="n">Gunther</span>
<span class="o">|--&gt;</span> <span class="n">Commander</span> <span class="n">Clement</span>
</code></pre></div><div class="section" id="additional-resources"><h3><span class="yiyi-st" id="yiyi-87">20.5.1.8. </span><span class="yiyi-st" id="yiyi-88">Additional resources</span></h3><p><span class="yiyi-st" id="yiyi-89">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.</span></p></div></div><div class="section" id="xpath-support"><h2><span class="yiyi-st" id="yiyi-90">20.5.2. </span><span class="yiyi-st" id="yiyi-91">XPath support</span></h2><p><span class="yiyi-st" id="yiyi-92">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. </span><span class="yiyi-st" id="yiyi-93">The goal is to support a small subset of the abbreviated syntax; a full XPath engine is outside the scope of the module.</span></p><div class="section" id="example"><h3><span class="yiyi-st" id="yiyi-94">20.5.2.1. </span><span class="yiyi-st" id="yiyi-95">Example</span></h3><p><span class="yiyi-st" id="yiyi-96">Heres an example that demonstrates some of the XPath capabilities of the module. </span><span class="yiyi-st" id="yiyi-97">Well be using the <code class="docutils literal"><span class="pre">countrydata</span></code> XML document from the <a class="reference internal" href="#elementtree-parsing-xml"><span>Parsing XML</span></a> section:</span></p><pre><code class="language-python"><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>
</code></pre></div><div class="section" id="supported-xpath-syntax"><h3><span class="yiyi-st" id="yiyi-98">20.5.2.2. </span><span class="yiyi-st" id="yiyi-99">Supported XPath syntax</span></h3><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-100">Syntax</span></th><th class="head"><span class="yiyi-st" id="yiyi-101">Meaning</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-102"><code class="docutils literal"><span class="pre">tag</span></code></span></td><td><span class="yiyi-st" id="yiyi-103">Selects all child elements with the given tag. </span><span class="yiyi-st" id="yiyi-104">For example, <code class="docutils literal"><span class="pre">spam</span></code> selects all child elements named <code class="docutils literal"><span class="pre">spam</span></code>, and <code class="docutils literal"><span class="pre">spam/egg</span></code> selects all grandchildren named <code class="docutils literal"><span class="pre">egg</span></code> in all children named <code class="docutils literal"><span class="pre">spam</span></code>.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-105"><code class="docutils literal"><span class="pre">*</span></code></span></td><td><span class="yiyi-st" id="yiyi-106">Selects all child elements. </span><span class="yiyi-st" id="yiyi-107">For example, <code class="docutils literal"><span class="pre">*/egg</span></code> selects all grandchildren named <code class="docutils literal"><span class="pre">egg</span></code>.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-108"><code class="docutils literal"><span class="pre">.</span></code></span></td><td><span class="yiyi-st" id="yiyi-109">Selects the current node. </span><span class="yiyi-st" id="yiyi-110">This is mostly useful at the beginning of the path, to indicate that its a relative path.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-111"><code class="docutils literal"><span class="pre">//</span></code></span></td><td><span class="yiyi-st" id="yiyi-112">Selects all subelements, on all levels beneath the current element. </span><span class="yiyi-st" id="yiyi-113">For example, <code class="docutils literal"><span class="pre">.//egg</span></code> selects all <code class="docutils literal"><span class="pre">egg</span></code> elements in the entire tree.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-114"><code class="docutils literal"><span class="pre">..</span></code></span></td><td><span class="yiyi-st" id="yiyi-115">Selects the parent element. </span><span class="yiyi-st" id="yiyi-116">Returns <code class="docutils literal"><span class="pre">None</span></code> if the path attempts to reach the ancestors of the start element (the element <code class="docutils literal"><span class="pre">find</span></code> was called on).</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-117"><code class="docutils literal"><span class="pre">[@attrib]</span></code></span></td><td><span class="yiyi-st" id="yiyi-118">Selects all elements that have the given attribute.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-119"><code class="docutils literal"><span class="pre">[@attrib='value']</span></code></span></td><td><span class="yiyi-st" id="yiyi-120">Selects all elements for which the given attribute has the given value. </span><span class="yiyi-st" id="yiyi-121">The value cannot contain quotes.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-122"><code class="docutils literal"><span class="pre">[tag]</span></code></span></td><td><span class="yiyi-st" id="yiyi-123">Selects all elements that have a child named <code class="docutils literal"><span class="pre">tag</span></code>. </span><span class="yiyi-st" id="yiyi-124">Only immediate children are supported.</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-125"><code class="docutils literal"><span class="pre">[tag='text']</span></code></span></td><td><span class="yiyi-st" id="yiyi-126">Selects all elements that have a child named <code class="docutils literal"><span class="pre">tag</span></code> whose complete text content, including descendants, equals the given <code class="docutils literal"><span class="pre">text</span></code>.</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-127"><code class="docutils literal"><span class="pre">[position]</span></code></span></td><td><span class="yiyi-st" id="yiyi-128">Selects all elements that are located at the given position. </span><span class="yiyi-st" id="yiyi-129">The position can be either an integer (1 is the first position), the expression <code class="docutils literal"><span class="pre">last()</span></code> (for the last position), or a position relative to the last position (e.g. </span><span class="yiyi-st" id="yiyi-130"><code class="docutils literal"><span class="pre">last()-1</span></code>).</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-131">Predicates (expressions within square brackets) must be preceded by a tag name, an asterisk, or another predicate. </span><span class="yiyi-st" id="yiyi-132"><code class="docutils literal"><span class="pre">position</span></code> predicates must be preceded by a tag name.</span></p></div></div><div class="section" id="reference"><h2><span class="yiyi-st" id="yiyi-133">20.5.3. </span><span class="yiyi-st" id="yiyi-134">Reference</span></h2><div class="section" id="functions"><h3><span class="yiyi-st" id="yiyi-135">20.5.3.1. </span><span class="yiyi-st" id="yiyi-136">Functions</span></h3><dl class="function"><dt id="xml.etree.ElementTree.Comment"><span class="yiyi-st" id="yiyi-137"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-138">Comment element factory. </span><span class="yiyi-st" id="yiyi-139">This factory function creates a special element that will be serialized as an XML comment by the standard serializer. </span><span class="yiyi-st" id="yiyi-140">The comment string can be either a bytestring or a Unicode string. </span><span class="yiyi-st" id="yiyi-141"><em>text</em> is a string containing the comment string. </span><span class="yiyi-st" id="yiyi-142">Returns an element instance representing a comment.</span></p><p><span class="yiyi-st" id="yiyi-143">Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal"><span class="pre">XMLParser</span></code></a> skips over comments in the input instead of creating comment objects for them. </span><span class="yiyi-st" id="yiyi-144">An <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal"><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"><span class="pre">Element</span></code></a> methods.</span></p></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.dump"><span class="yiyi-st" id="yiyi-145"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-146">Writes an element tree or element structure to sys.stdout. </span><span class="yiyi-st" id="yiyi-147">This function should be used for debugging only.</span></p><p><span class="yiyi-st" id="yiyi-148">The exact output format is implementation dependent. </span><span class="yiyi-st" id="yiyi-149">In this version, its written as an ordinary XML file.</span></p><p><span class="yiyi-st" id="yiyi-150"><em>elem</em> is an element tree or an individual element.</span></p></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.fromstring"><span class="yiyi-st" id="yiyi-151"> <code class="descclassname">xml.etree.ElementTree.</code><code class="descname">fromstring</code><span class="sig-paren">(</span><em>text</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-152">Parses an XML section from a string constant. </span><span class="yiyi-st" id="yiyi-153">Same as <a class="reference internal" href="#xml.etree.ElementTree.XML" title="xml.etree.ElementTree.XML"><code class="xref py py-func docutils literal"><span class="pre">XML()</span></code></a>. </span><span class="yiyi-st" id="yiyi-154"><em>text</em> is a string containing XML data. </span><span class="yiyi-st" id="yiyi-155">Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal"><span class="pre">Element</span></code></a> instance.</span></p></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.fromstringlist"><span class="yiyi-st" id="yiyi-156"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-157">Parses an XML document from a sequence of string fragments. </span><span class="yiyi-st" id="yiyi-158"><em>sequence</em> is a list or other sequence containing XML data fragments. </span><span class="yiyi-st" id="yiyi-159"><em>parser</em> is an optional parser instance. </span><span class="yiyi-st" id="yiyi-160">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"><span class="pre">XMLParser</span></code></a> parser is used. </span><span class="yiyi-st" id="yiyi-161">Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal"><span class="pre">Element</span></code></a> instance.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-162"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.iselement"><span class="yiyi-st" id="yiyi-163"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-164">Checks if an object appears to be a valid element object. </span><span class="yiyi-st" id="yiyi-165"><em>element</em> is an element instance. </span><span class="yiyi-st" id="yiyi-166">Returns a true value if this is an element object.</span></p></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.iterparse"><span class="yiyi-st" id="yiyi-167"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-168">Parses an XML section into an element tree incrementally, and reports whats going on to the user. </span><span class="yiyi-st" id="yiyi-169"><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. </span><span class="yiyi-st" id="yiyi-170"><em>events</em> is a sequence of events to report back. </span><span class="yiyi-st" id="yiyi-171">The supported events are the strings <code class="docutils literal"><span class="pre">"start"</span></code>, <code class="docutils literal"><span class="pre">"end"</span></code>, <code class="docutils literal"><span class="pre">"start-ns"</span></code> and <code class="docutils literal"><span class="pre">"end-ns"</span></code> (the “ns” events are used to get detailed namespace information). </span><span class="yiyi-st" id="yiyi-172">If <em>events</em> is omitted, only <code class="docutils literal"><span class="pre">"end"</span></code> events are reported. </span><span class="yiyi-st" id="yiyi-173"><em>parser</em> is an optional parser instance. </span><span class="yiyi-st" id="yiyi-174">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"><span class="pre">XMLParser</span></code></a> parser is used. </span><span class="yiyi-st" id="yiyi-175"><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"><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"><span class="pre">TreeBuilder</span></code></a> as a target. </span><span class="yiyi-st" id="yiyi-176">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"><span class="pre">(event,</span> <span class="pre">elem)</span></code> pairs.</span></p><p><span class="yiyi-st" id="yiyi-177">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"><span class="pre">iterparse()</span></code></a> builds the tree incrementally, it issues blocking reads on <em>source</em> (or the file it names). </span><span class="yiyi-st" id="yiyi-178">As such, its unsuitable for applications where blocking reads cant be made. </span><span class="yiyi-st" id="yiyi-179">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"><span class="pre">XMLPullParser</span></code></a>.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-180">Note</span></p><p><span class="yiyi-st" id="yiyi-181"><a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal"><span class="pre">iterparse()</span></code></a> only guarantees that it has seen the “&gt;” 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. </span><span class="yiyi-st" id="yiyi-182">The same applies to the element children; they may or may not be present.</span></p><p class="last"><span class="yiyi-st" id="yiyi-183">If you need a fully populated element, look for “end” events instead.</span></p></div><div class="deprecated"><p><span class="yiyi-st" id="yiyi-184"><span class="versionmodified">Deprecated since version 3.4: </span>The <em>parser</em> argument.</span></p></div></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.parse"><span class="yiyi-st" id="yiyi-185"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-186">Parses an XML section into an element tree. </span><span class="yiyi-st" id="yiyi-187"><em>source</em> is a filename or file object containing XML data. </span><span class="yiyi-st" id="yiyi-188"><em>parser</em> is an optional parser instance. </span><span class="yiyi-st" id="yiyi-189">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"><span class="pre">XMLParser</span></code></a> parser is used. </span><span class="yiyi-st" id="yiyi-190">Returns an <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal"><span class="pre">ElementTree</span></code></a> instance.</span></p></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.ProcessingInstruction"><span class="yiyi-st" id="yiyi-191"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-192">PI element factory. </span><span class="yiyi-st" id="yiyi-193">This factory function creates a special element that will be serialized as an XML processing instruction. </span><span class="yiyi-st" id="yiyi-194"><em>target</em> is a string containing the PI target. </span><span class="yiyi-st" id="yiyi-195"><em>text</em> is a string containing the PI contents, if given. </span><span class="yiyi-st" id="yiyi-196">Returns an element instance, representing a processing instruction.</span></p><p><span class="yiyi-st" id="yiyi-197">Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal"><span class="pre">XMLParser</span></code></a> skips over processing instructions in the input instead of creating comment objects for them. </span><span class="yiyi-st" id="yiyi-198">An <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal"><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"><span class="pre">Element</span></code></a> methods.</span></p></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.register_namespace"><span class="yiyi-st" id="yiyi-199"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-200">Registers a namespace prefix. </span><span class="yiyi-st" id="yiyi-201">The registry is global, and any existing mapping for either the given prefix or the namespace URI will be removed. </span><span class="yiyi-st" id="yiyi-202"><em>prefix</em> is a namespace prefix. </span><span class="yiyi-st" id="yiyi-203"><em>uri</em> is a namespace uri. </span><span class="yiyi-st" id="yiyi-204">Tags and attributes in this namespace will be serialized with the given prefix, if at all possible.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-205"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.SubElement"><span class="yiyi-st" id="yiyi-206"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-207">Subelement factory. </span><span class="yiyi-st" id="yiyi-208">This function creates an element instance, and appends it to an existing element.</span></p><p><span class="yiyi-st" id="yiyi-209">The element name, attribute names, and attribute values can be either bytestrings or Unicode strings. </span><span class="yiyi-st" id="yiyi-210"><em>parent</em> is the parent element. </span><span class="yiyi-st" id="yiyi-211"><em>tag</em> is the subelement name. </span><span class="yiyi-st" id="yiyi-212"><em>attrib</em> is an optional dictionary, containing element attributes. </span><span class="yiyi-st" id="yiyi-213"><em>extra</em> contains additional attributes, given as keyword arguments. </span><span class="yiyi-st" id="yiyi-214">Returns an element instance.</span></p></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.tostring"><span class="yiyi-st" id="yiyi-215"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-216">Generates a string representation of an XML element, including all subelements. </span><span class="yiyi-st" id="yiyi-217"><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"><span class="pre">Element</span></code></a> instance. </span><span class="yiyi-st" id="yiyi-218"><em>encoding</em> <a class="footnote-reference" href="#id5" id="id1">[1]</a> is the output encoding (default is US-ASCII). </span><span class="yiyi-st" id="yiyi-219">Use <code class="docutils literal"><span class="pre">encoding="unicode"</span></code> to generate a Unicode string (otherwise, a bytestring is generated). </span><span class="yiyi-st" id="yiyi-220"><em>method</em> is either <code class="docutils literal"><span class="pre">"xml"</span></code>, <code class="docutils literal"><span class="pre">"html"</span></code> or <code class="docutils literal"><span class="pre">"text"</span></code> (default is <code class="docutils literal"><span class="pre">"xml"</span></code>). </span><span class="yiyi-st" id="yiyi-221"><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"><span class="pre">ElementTree.write()</span></code></a>. </span><span class="yiyi-st" id="yiyi-222">Returns an (optionally) encoded string containing the XML data.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-223"><span class="versionmodified">New in version 3.4: </span>The <em>short_empty_elements</em> parameter.</span></p></div></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.tostringlist"><span class="yiyi-st" id="yiyi-224"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-225">Generates a string representation of an XML element, including all subelements. </span><span class="yiyi-st" id="yiyi-226"><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"><span class="pre">Element</span></code></a> instance. </span><span class="yiyi-st" id="yiyi-227"><em>encoding</em> <a class="footnote-reference" href="#id5" id="id2">[1]</a> is the output encoding (default is US-ASCII). </span><span class="yiyi-st" id="yiyi-228">Use <code class="docutils literal"><span class="pre">encoding="unicode"</span></code> to generate a Unicode string (otherwise, a bytestring is generated). </span><span class="yiyi-st" id="yiyi-229"><em>method</em> is either <code class="docutils literal"><span class="pre">"xml"</span></code>, <code class="docutils literal"><span class="pre">"html"</span></code> or <code class="docutils literal"><span class="pre">"text"</span></code> (default is <code class="docutils literal"><span class="pre">"xml"</span></code>). </span><span class="yiyi-st" id="yiyi-230"><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"><span class="pre">ElementTree.write()</span></code></a>. </span><span class="yiyi-st" id="yiyi-231">Returns a list of (optionally) encoded strings containing the XML data. </span><span class="yiyi-st" id="yiyi-232">It does not guarantee any specific sequence, except that <code class="docutils literal"><span class="pre">b"".join(tostringlist(element))</span> <span class="pre">==</span> <span class="pre">tostring(element)</span></code>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-233"><span class="versionmodified">New in version 3.2.</span></span></p></div><div class="versionadded"><p><span class="yiyi-st" id="yiyi-234"><span class="versionmodified">New in version 3.4: </span>The <em>short_empty_elements</em> parameter.</span></p></div></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.XML"><span class="yiyi-st" id="yiyi-235"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-236">Parses an XML section from a string constant. </span><span class="yiyi-st" id="yiyi-237">This function can be used to embed “XML literals” in Python code. </span><span class="yiyi-st" id="yiyi-238"><em>text</em> is a string containing XML data. </span><span class="yiyi-st" id="yiyi-239"><em>parser</em> is an optional parser instance. </span><span class="yiyi-st" id="yiyi-240">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"><span class="pre">XMLParser</span></code></a> parser is used. </span><span class="yiyi-st" id="yiyi-241">Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal"><span class="pre">Element</span></code></a> instance.</span></p></dd></dl><dl class="function"><dt id="xml.etree.ElementTree.XMLID"><span class="yiyi-st" id="yiyi-242"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-243">Parses an XML section from a string constant, and also returns a dictionary which maps from element id:s to elements. </span><span class="yiyi-st" id="yiyi-244"><em>text</em> is a string containing XML data. </span><span class="yiyi-st" id="yiyi-245"><em>parser</em> is an optional parser instance. </span><span class="yiyi-st" id="yiyi-246">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"><span class="pre">XMLParser</span></code></a> parser is used. </span><span class="yiyi-st" id="yiyi-247">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"><span class="pre">Element</span></code></a> instance and a dictionary.</span></p></dd></dl></div><div class="section" id="element-objects"><h3><span class="yiyi-st" id="yiyi-248">20.5.3.2. </span><span class="yiyi-st" id="yiyi-249">Element Objects</span></h3><dl class="class"><dt id="xml.etree.ElementTree.Element"><span class="yiyi-st" id="yiyi-250"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-251">Element class. </span><span class="yiyi-st" id="yiyi-252">This class defines the Element interface, and provides a reference implementation of this interface.</span></p><p><span class="yiyi-st" id="yiyi-253">The element name, attribute names, and attribute values can be either bytestrings or Unicode strings. </span><span class="yiyi-st" id="yiyi-254"><em>tag</em> is the element name. </span><span class="yiyi-st" id="yiyi-255"><em>attrib</em> is an optional dictionary, containing element attributes. </span><span class="yiyi-st" id="yiyi-256"><em>extra</em> contains additional attributes, given as keyword arguments.</span></p><dl class="attribute"><dt id="xml.etree.ElementTree.Element.tag"><span class="yiyi-st" id="yiyi-257"> <code class="descname">tag</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-258">A string identifying what kind of data this element represents (the element type, in other words).</span></p></dd></dl><dl class="attribute"><dt id="xml.etree.ElementTree.Element.text"><span class="yiyi-st" id="yiyi-259"> <code class="descname">text</code></span></dt><dt id="xml.etree.ElementTree.Element.tail"><span class="yiyi-st" id="yiyi-260"> <code class="descname">tail</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-261">These attributes can be used to hold additional data associated with the element. </span><span class="yiyi-st" id="yiyi-262">Their values are usually strings but may be any application-specific object. </span><span class="yiyi-st" id="yiyi-263">If the element is created from an XML file, the <em>text</em> attribute holds either the text between the elements start tag and its first child or end tag, or <code class="docutils literal"><span class="pre">None</span></code>, and the <em>tail</em> attribute holds either the text between the elements end tag and the next tag, or <code class="docutils literal"><span class="pre">None</span></code>. </span><span class="yiyi-st" id="yiyi-264">For the XML data</span></p><div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;a&gt;&lt;b&gt;</span>1<span class="nt">&lt;c&gt;</span>2<span class="nt">&lt;d/&gt;</span>3<span class="nt">&lt;/c&gt;&lt;/b&gt;</span>4<span class="nt">&lt;/a&gt;</span>
</pre></div></div><p><span class="yiyi-st" id="yiyi-265">the <em>a</em> element has <code class="docutils literal"><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"><span class="pre">"1"</span></code> and <em>tail</em> <code class="docutils literal"><span class="pre">"4"</span></code>, the <em>c</em> element has <em>text</em> <code class="docutils literal"><span class="pre">"2"</span></code> and <em>tail</em> <code class="docutils literal"><span class="pre">None</span></code>, and the <em>d</em> element has <em>text</em> <code class="docutils literal"><span class="pre">None</span></code> and <em>tail</em> <code class="docutils literal"><span class="pre">"3"</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-266">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"><span class="pre">itertext()</span></code></a>, for example <code class="docutils literal"><span class="pre">"".join(element.itertext())</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-267">Applications may store arbitrary objects in these attributes.</span></p></dd></dl><dl class="attribute"><dt id="xml.etree.ElementTree.Element.attrib"><span class="yiyi-st" id="yiyi-268"> <code class="descname">attrib</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-269">A dictionary containing the elements attributes. </span><span class="yiyi-st" id="yiyi-270">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. </span><span class="yiyi-st" id="yiyi-271">To take advantage of such implementations, use the dictionary methods below whenever possible.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-272">The following dictionary-like methods work on the element attributes.</span></p><dl class="method"><dt id="xml.etree.ElementTree.Element.clear"><span class="yiyi-st" id="yiyi-273"> <code class="descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-274">Resets an element. </span><span class="yiyi-st" id="yiyi-275">This function removes all subelements, clears all attributes, and sets the text and tail attributes to <code class="docutils literal"><span class="pre">None</span></code>.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.get"><span class="yiyi-st" id="yiyi-276"> <code class="descname">get</code><span class="sig-paren">(</span><em>key</em>, <em>default=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-277">Gets the element attribute named <em>key</em>.</span></p><p><span class="yiyi-st" id="yiyi-278">Returns the attribute value, or <em>default</em> if the attribute was not found.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.items"><span class="yiyi-st" id="yiyi-279"> <code class="descname">items</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-280">Returns the element attributes as a sequence of (name, value) pairs. </span><span class="yiyi-st" id="yiyi-281">The attributes are returned in an arbitrary order.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.keys"><span class="yiyi-st" id="yiyi-282"> <code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-283">Returns the elements attribute names as a list. </span><span class="yiyi-st" id="yiyi-284">The names are returned in an arbitrary order.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.set"><span class="yiyi-st" id="yiyi-285"> <code class="descname">set</code><span class="sig-paren">(</span><em>key</em>, <em>value</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-286">Set the attribute <em>key</em> on the element to <em>value</em>.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-287">The following methods work on the elements children (subelements).</span></p><dl class="method"><dt id="xml.etree.ElementTree.Element.append"><span class="yiyi-st" id="yiyi-288"> <code class="descname">append</code><span class="sig-paren">(</span><em>subelement</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-289">Adds the element <em>subelement</em> to the end of this elements internal list of subelements. </span><span class="yiyi-st" id="yiyi-290">Raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal"><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"><span class="pre">Element</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.extend"><span class="yiyi-st" id="yiyi-291"> <code class="descname">extend</code><span class="sig-paren">(</span><em>subelements</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-292">Appends <em>subelements</em> from a sequence object with zero or more elements. </span><span class="yiyi-st" id="yiyi-293">Raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal"><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"><span class="pre">Element</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-294"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.find"><span class="yiyi-st" id="yiyi-295"> <code class="descname">find</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-296">Finds the first subelement matching <em>match</em>. </span><span class="yiyi-st" id="yiyi-297"><em>match</em> may be a tag name or a <a class="reference internal" href="#elementtree-xpath"><span>path</span></a>. </span><span class="yiyi-st" id="yiyi-298">Returns an element instance or <code class="docutils literal"><span class="pre">None</span></code>. </span><span class="yiyi-st" id="yiyi-299"><em>namespaces</em> is an optional mapping from namespace prefix to full name.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.findall"><span class="yiyi-st" id="yiyi-300"> <code class="descname">findall</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-301">Finds all matching subelements, by tag name or <a class="reference internal" href="#elementtree-xpath"><span>path</span></a>. </span><span class="yiyi-st" id="yiyi-302">Returns a list containing all matching elements in document order. </span><span class="yiyi-st" id="yiyi-303"><em>namespaces</em> is an optional mapping from namespace prefix to full name.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.findtext"><span class="yiyi-st" id="yiyi-304"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-305">Finds text for the first subelement matching <em>match</em>. </span><span class="yiyi-st" id="yiyi-306"><em>match</em> may be a tag name or a <a class="reference internal" href="#elementtree-xpath"><span>path</span></a>. </span><span class="yiyi-st" id="yiyi-307">Returns the text content of the first matching element, or <em>default</em> if no element was found. </span><span class="yiyi-st" id="yiyi-308">Note that if the matching element has no text content an empty string is returned. </span><span class="yiyi-st" id="yiyi-309"><em>namespaces</em> is an optional mapping from namespace prefix to full name.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.getchildren"><span class="yiyi-st" id="yiyi-310"> <code class="descname">getchildren</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><div class="deprecated"><p><span class="yiyi-st" id="yiyi-311"><span class="versionmodified">Deprecated since version 3.2: </span>Use <code class="docutils literal"><span class="pre">list(elem)</span></code> or iteration.</span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.getiterator"><span class="yiyi-st" id="yiyi-312"> <code class="descname">getiterator</code><span class="sig-paren">(</span><em>tag=None</em><span class="sig-paren">)</span></span></dt><dd><div class="deprecated"><p><span class="yiyi-st" id="yiyi-313"><span class="versionmodified">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"><span class="pre">Element.iter()</span></code></a> instead.</span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.insert"><span class="yiyi-st" id="yiyi-314"> <code class="descname">insert</code><span class="sig-paren">(</span><em>index</em>, <em>subelement</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-315">Inserts <em>subelement</em> at the given position in this element. </span><span class="yiyi-st" id="yiyi-316">Raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal"><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"><span class="pre">Element</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.iter"><span class="yiyi-st" id="yiyi-317"> <code class="descname">iter</code><span class="sig-paren">(</span><em>tag=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-318">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. </span><span class="yiyi-st" id="yiyi-319">The iterator iterates over this element and all elements below it, in document (depth first) order. </span><span class="yiyi-st" id="yiyi-320">If <em>tag</em> is not <code class="docutils literal"><span class="pre">None</span></code> or <code class="docutils literal"><span class="pre">'*'</span></code>, only elements whose tag equals <em>tag</em> are returned from the iterator. </span><span class="yiyi-st" id="yiyi-321">If the tree structure is modified during iteration, the result is undefined.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-322"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.iterfind"><span class="yiyi-st" id="yiyi-323"> <code class="descname">iterfind</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-324">Finds all matching subelements, by tag name or <a class="reference internal" href="#elementtree-xpath"><span>path</span></a>. </span><span class="yiyi-st" id="yiyi-325">Returns an iterable yielding all matching elements in document order. </span><span class="yiyi-st" id="yiyi-326"><em>namespaces</em> is an optional mapping from namespace prefix to full name.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-327"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.itertext"><span class="yiyi-st" id="yiyi-328"> <code class="descname">itertext</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-329">Creates a text iterator. </span><span class="yiyi-st" id="yiyi-330">The iterator loops over this element and all subelements, in document order, and returns all inner text.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-331"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.makeelement"><span class="yiyi-st" id="yiyi-332"> <code class="descname">makeelement</code><span class="sig-paren">(</span><em>tag</em>, <em>attrib</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-333">Creates a new element object of the same type as this element. </span><span class="yiyi-st" id="yiyi-334">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"><span class="pre">SubElement()</span></code></a> factory function instead.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.Element.remove"><span class="yiyi-st" id="yiyi-335"> <code class="descname">remove</code><span class="sig-paren">(</span><em>subelement</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-336">Removes <em>subelement</em> from the element. </span><span class="yiyi-st" id="yiyi-337">Unlike the find* methods this method compares elements based on the instance identity, not on tag value or contents.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-338"><a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal"><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"><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"><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"><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"><span class="pre">__len__()</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-339">Caution: Elements with no subelements will test as <code class="docutils literal"><span class="pre">False</span></code>. </span><span class="yiyi-st" id="yiyi-340">This behavior will change in future versions. </span><span class="yiyi-st" id="yiyi-341">Use specific <code class="docutils literal"><span class="pre">len(elem)</span></code> or <code class="docutils literal"><span class="pre">elem</span> <span class="pre">is</span> <span class="pre">None</span></code> test instead.</span></p><pre><code class="language-python"><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>
</code></pre></dd></dl></div><div class="section" id="elementtree-objects"><h3><span class="yiyi-st" id="yiyi-342">20.5.3.3. </span><span class="yiyi-st" id="yiyi-343">ElementTree Objects</span></h3><dl class="class"><dt id="xml.etree.ElementTree.ElementTree"><span class="yiyi-st" id="yiyi-344"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-345">ElementTree wrapper class. </span><span class="yiyi-st" id="yiyi-346">This class represents an entire element hierarchy, and adds some extra support for serialization to and from standard XML.</span></p><p><span class="yiyi-st" id="yiyi-347"><em>element</em> is the root element. </span><span class="yiyi-st" id="yiyi-348">The tree is initialized with the contents of the XML <em>file</em> if given.</span></p><dl class="method"><dt id="xml.etree.ElementTree.ElementTree._setroot"><span class="yiyi-st" id="yiyi-349"> <code class="descname">_setroot</code><span class="sig-paren">(</span><em>element</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-350">Replaces the root element for this tree. </span><span class="yiyi-st" id="yiyi-351">This discards the current contents of the tree, and replaces it with the given element. </span><span class="yiyi-st" id="yiyi-352">Use with care. </span><span class="yiyi-st" id="yiyi-353"><em>element</em> is an element instance.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.find"><span class="yiyi-st" id="yiyi-354"> <code class="descname">find</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-355">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"><span class="pre">Element.find()</span></code></a>, starting at the root of the tree.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.findall"><span class="yiyi-st" id="yiyi-356"> <code class="descname">findall</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-357">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"><span class="pre">Element.findall()</span></code></a>, starting at the root of the tree.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.findtext"><span class="yiyi-st" id="yiyi-358"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-359">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"><span class="pre">Element.findtext()</span></code></a>, starting at the root of the tree.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.getiterator"><span class="yiyi-st" id="yiyi-360"> <code class="descname">getiterator</code><span class="sig-paren">(</span><em>tag=None</em><span class="sig-paren">)</span></span></dt><dd><div class="deprecated"><p><span class="yiyi-st" id="yiyi-361"><span class="versionmodified">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"><span class="pre">ElementTree.iter()</span></code></a> instead.</span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.getroot"><span class="yiyi-st" id="yiyi-362"> <code class="descname">getroot</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-363">Returns the root element for this tree.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.iter"><span class="yiyi-st" id="yiyi-364"> <code class="descname">iter</code><span class="sig-paren">(</span><em>tag=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-365">Creates and returns a tree iterator for the root element. </span><span class="yiyi-st" id="yiyi-366">The iterator loops over all elements in this tree, in section order. </span><span class="yiyi-st" id="yiyi-367"><em>tag</em> is the tag to look for (default is to return all elements).</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.iterfind"><span class="yiyi-st" id="yiyi-368"> <code class="descname">iterfind</code><span class="sig-paren">(</span><em>match</em>, <em>namespaces=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-369">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"><span class="pre">Element.iterfind()</span></code></a>, starting at the root of the tree.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-370"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.parse"><span class="yiyi-st" id="yiyi-371"> <code class="descname">parse</code><span class="sig-paren">(</span><em>source</em>, <em>parser=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-372">Loads an external XML section into this element tree. </span><span class="yiyi-st" id="yiyi-373"><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>. </span><span class="yiyi-st" id="yiyi-374"><em>parser</em> is an optional parser instance. </span><span class="yiyi-st" id="yiyi-375">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"><span class="pre">XMLParser</span></code></a> parser is used. </span><span class="yiyi-st" id="yiyi-376">Returns the section root element.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.ElementTree.write"><span class="yiyi-st" id="yiyi-377"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-378">Writes the element tree to a file, as XML. </span><span class="yiyi-st" id="yiyi-379"><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. </span><span class="yiyi-st" id="yiyi-380"><em>encoding</em> <a class="footnote-reference" href="#id5" id="id3">[1]</a> is the output encoding (default is US-ASCII). </span><span class="yiyi-st" id="yiyi-381"><em>xml_declaration</em> controls if an XML declaration should be added to the file. </span><span class="yiyi-st" id="yiyi-382">Use <code class="docutils literal"><span class="pre">False</span></code> for never, <code class="docutils literal"><span class="pre">True</span></code> for always, <code class="docutils literal"><span class="pre">None</span></code> for only if not US-ASCII or UTF-8 or Unicode (default is <code class="docutils literal"><span class="pre">None</span></code>). </span><span class="yiyi-st" id="yiyi-383"><em>default_namespace</em> sets the default XML namespace (for “xmlns”). </span><span class="yiyi-st" id="yiyi-384"><em>method</em> is either <code class="docutils literal"><span class="pre">"xml"</span></code>, <code class="docutils literal"><span class="pre">"html"</span></code> or <code class="docutils literal"><span class="pre">"text"</span></code> (default is <code class="docutils literal"><span class="pre">"xml"</span></code>). </span><span class="yiyi-st" id="yiyi-385">The keyword-only <em>short_empty_elements</em> parameter controls the formatting of elements that contain no content. </span><span class="yiyi-st" id="yiyi-386">If <em>True</em> (the default), they are emitted as a single self-closed tag, otherwise they are emitted as a pair of start/end tags.</span></p><p><span class="yiyi-st" id="yiyi-387">The output is either a string (<a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a>) or binary (<a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal"><span class="pre">bytes</span></code></a>). </span><span class="yiyi-st" id="yiyi-388">This is controlled by the <em>encoding</em> argument. </span><span class="yiyi-st" id="yiyi-389">If <em>encoding</em> is <code class="docutils literal"><span class="pre">"unicode"</span></code>, the output is a string; otherwise, its binary. </span><span class="yiyi-st" id="yiyi-390">Note that this may conflict with the type of <em>file</em> if its 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.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-391"><span class="versionmodified">New in version 3.4: </span>The <em>short_empty_elements</em> parameter.</span></p></div></dd></dl></dd></dl><p><span class="yiyi-st" id="yiyi-392">This is the XML file that is going to be manipulated:</span></p><pre><code class="language-python"><span></span><span class="o">&lt;</span><span class="n">html</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="n">head</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="n">title</span><span class="o">&gt;</span><span class="n">Example</span> <span class="n">page</span><span class="o">&lt;/</span><span class="n">title</span><span class="o">&gt;</span>
<span class="o">&lt;/</span><span class="n">head</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="n">body</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="n">p</span><span class="o">&gt;</span><span class="n">Moved</span> <span class="n">to</span> <span class="o">&lt;</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">&gt;</span><span class="n">example</span><span class="o">.</span><span class="n">org</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;</span>
<span class="ow">or</span> <span class="o">&lt;</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">&gt;</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;.&lt;/</span><span class="n">p</span><span class="o">&gt;</span>
<span class="o">&lt;/</span><span class="n">body</span><span class="o">&gt;</span>
<span class="o">&lt;/</span><span class="n">html</span><span class="o">&gt;</span>
</code></pre><p><span class="yiyi-st" id="yiyi-393">Example of changing the attribute “target” of every link in first paragraph:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">tree</span> <span class="o">=</span> <span class="n">ElementTree</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </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">&lt;Element 'html' at 0xb77e6fac&gt;</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">p</span>
<span class="go">&lt;Element 'p' at 0xb77ec26c&gt;</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">links</span>
<span class="go">[&lt;Element 'a' at 0xb77ec2ac&gt;, &lt;Element 'a' at 0xb77ec1cc&gt;]</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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>
</code></pre></div><div class="section" id="qname-objects"><h3><span class="yiyi-st" id="yiyi-394">20.5.3.4. </span><span class="yiyi-st" id="yiyi-395">QName Objects</span></h3><dl class="class"><dt id="xml.etree.ElementTree.QName"><span class="yiyi-st" id="yiyi-396"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-397">QName wrapper. </span><span class="yiyi-st" id="yiyi-398">This can be used to wrap a QName attribute value, in order to get proper namespace handling on output. </span><span class="yiyi-st" id="yiyi-399"><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. </span><span class="yiyi-st" id="yiyi-400">If <em>tag</em> is given, the first argument is interpreted as a URI, and this argument is interpreted as a local name. </span><span class="yiyi-st" id="yiyi-401"><a class="reference internal" href="#xml.etree.ElementTree.QName" title="xml.etree.ElementTree.QName"><code class="xref py py-class docutils literal"><span class="pre">QName</span></code></a> instances are opaque.</span></p></dd></dl></div><div class="section" id="treebuilder-objects"><h3><span class="yiyi-st" id="yiyi-402">20.5.3.5. </span><span class="yiyi-st" id="yiyi-403">TreeBuilder Objects</span></h3><dl class="class"><dt id="xml.etree.ElementTree.TreeBuilder"><span class="yiyi-st" id="yiyi-404"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-405">Generic element structure builder. </span><span class="yiyi-st" id="yiyi-406">This builder converts a sequence of start, data, and end method calls to a well-formed element structure. </span><span class="yiyi-st" id="yiyi-407">You can use this class to build an element structure using a custom XML parser, or a parser for some other XML-like format. </span><span class="yiyi-st" id="yiyi-408"><em>element_factory</em>, when given, must be a callable accepting two positional arguments: a tag and a dict of attributes. </span><span class="yiyi-st" id="yiyi-409">It is expected to return a new element instance.</span></p><dl class="method"><dt id="xml.etree.ElementTree.TreeBuilder.close"><span class="yiyi-st" id="yiyi-410"> <code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-411">Flushes the builder buffers, and returns the toplevel document element. </span><span class="yiyi-st" id="yiyi-412">Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal"><span class="pre">Element</span></code></a> instance.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.TreeBuilder.data"><span class="yiyi-st" id="yiyi-413"> <code class="descname">data</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-414">Adds text to the current element. </span><span class="yiyi-st" id="yiyi-415"><em>data</em> is a string. </span><span class="yiyi-st" id="yiyi-416">This should be either a bytestring, or a Unicode string.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.TreeBuilder.end"><span class="yiyi-st" id="yiyi-417"> <code class="descname">end</code><span class="sig-paren">(</span><em>tag</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-418">Closes the current element. </span><span class="yiyi-st" id="yiyi-419"><em>tag</em> is the element name. </span><span class="yiyi-st" id="yiyi-420">Returns the closed element.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.TreeBuilder.start"><span class="yiyi-st" id="yiyi-421"> <code class="descname">start</code><span class="sig-paren">(</span><em>tag</em>, <em>attrs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-422">Opens a new element. </span><span class="yiyi-st" id="yiyi-423"><em>tag</em> is the element name. </span><span class="yiyi-st" id="yiyi-424"><em>attrs</em> is a dictionary containing element attributes. </span><span class="yiyi-st" id="yiyi-425">Returns the opened element.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-426">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"><span class="pre">TreeBuilder</span></code></a> object can provide the following method:</span></p><dl class="method"><dt id="xml.etree.ElementTree.TreeBuilder.doctype"><span class="yiyi-st" id="yiyi-427"> <code class="descname">doctype</code><span class="sig-paren">(</span><em>name</em>, <em>pubid</em>, <em>system</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-428">Handles a doctype declaration. </span><span class="yiyi-st" id="yiyi-429"><em>name</em> is the doctype name. </span><span class="yiyi-st" id="yiyi-430"><em>pubid</em> is the public identifier. </span><span class="yiyi-st" id="yiyi-431"><em>system</em> is the system identifier. </span><span class="yiyi-st" id="yiyi-432">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"><span class="pre">TreeBuilder</span></code></a> class.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-433"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl></dd></dl></div><div class="section" id="xmlparser-objects"><h3><span class="yiyi-st" id="yiyi-434">20.5.3.6. </span><span class="yiyi-st" id="yiyi-435">XMLParser Objects</span></h3><dl class="class"><dt id="xml.etree.ElementTree.XMLParser"><span class="yiyi-st" id="yiyi-436"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-437">This class is the low-level building block of the module. </span><span class="yiyi-st" id="yiyi-438">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"><span class="pre">xml.parsers.expat</span></code></a> for efficient, event-based parsing of XML. </span><span class="yiyi-st" id="yiyi-439">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"><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. </span><span class="yiyi-st" id="yiyi-440">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"><span class="pre">TreeBuilder</span></code></a> is used. </span><span class="yiyi-st" id="yiyi-441">The <em>html</em> argument was historically used for backwards compatibility and is now deprecated. </span><span class="yiyi-st" id="yiyi-442">If <em>encoding</em> <a class="footnote-reference" href="#id5" id="id4">[1]</a> is given, the value overrides the encoding specified in the XML file.</span></p><div class="deprecated"><p><span class="yiyi-st" id="yiyi-443"><span class="versionmodified">Deprecated since version 3.4: </span>The <em>html</em> argument. </span><span class="yiyi-st" id="yiyi-444">The remaining arguments should be passed via keyword to prepare for the removal of the <em>html</em> argument.</span></p></div><dl class="method"><dt id="xml.etree.ElementTree.XMLParser.close"><span class="yiyi-st" id="yiyi-445"> <code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-446">Finishes feeding data to the parser. </span><span class="yiyi-st" id="yiyi-447">Returns the result of calling the <code class="docutils literal"><span class="pre">close()</span></code> method of the <em>target</em> passed during construction; by default, this is the toplevel document element.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.XMLParser.doctype"><span class="yiyi-st" id="yiyi-448"> <code class="descname">doctype</code><span class="sig-paren">(</span><em>name</em>, <em>pubid</em>, <em>system</em><span class="sig-paren">)</span></span></dt><dd><div class="deprecated"><p><span class="yiyi-st" id="yiyi-449"><span class="versionmodified">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"><span class="pre">TreeBuilder.doctype()</span></code></a> method on a custom TreeBuilder target.</span></p></div></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.XMLParser.feed"><span class="yiyi-st" id="yiyi-450"> <code class="descname">feed</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-451">Feeds data to the parser. </span><span class="yiyi-st" id="yiyi-452"><em>data</em> is encoded data.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-453"><a class="reference internal" href="#xml.etree.ElementTree.XMLParser.feed" title="xml.etree.ElementTree.XMLParser.feed"><code class="xref py py-meth docutils literal"><span class="pre">XMLParser.feed()</span></code></a> calls <em>target</em>s <code class="docutils literal"><span class="pre">start(tag,</span> <span class="pre">attrs_dict)</span></code> method for each opening tag, its <code class="docutils literal"><span class="pre">end(tag)</span></code> method for each closing tag, and data is processed by method <code class="docutils literal"><span class="pre">data(data)</span></code>. </span><span class="yiyi-st" id="yiyi-454"><a class="reference internal" href="#xml.etree.ElementTree.XMLParser.close" title="xml.etree.ElementTree.XMLParser.close"><code class="xref py py-meth docutils literal"><span class="pre">XMLParser.close()</span></code></a> calls <em>target</em>s method <code class="docutils literal"><span class="pre">close()</span></code>. </span><span class="yiyi-st" id="yiyi-455"><a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal"><span class="pre">XMLParser</span></code></a> can be used not only for building a tree structure. </span><span class="yiyi-st" id="yiyi-456">This is an example of counting the maximum depth of an XML file:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </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">&gt;</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">&gt;&gt;&gt; </span><span class="n">target</span> <span class="o">=</span> <span class="n">MaxDepth</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">exampleXml</span> <span class="o">=</span> <span class="s2">"""</span>
<span class="gp">... </span><span class="s2">&lt;a&gt;</span>
<span class="gp">... </span><span class="s2"> &lt;b&gt;</span>
<span class="gp">... </span><span class="s2"> &lt;/b&gt;</span>
<span class="gp">... </span><span class="s2"> &lt;b&gt;</span>
<span class="gp">... </span><span class="s2"> &lt;c&gt;</span>
<span class="gp">... </span><span class="s2"> &lt;d&gt;</span>
<span class="gp">... </span><span class="s2"> &lt;/d&gt;</span>
<span class="gp">... </span><span class="s2"> &lt;/c&gt;</span>
<span class="gp">... </span><span class="s2"> &lt;/b&gt;</span>
<span class="gp">... </span><span class="s2">&lt;/a&gt;"""</span>
<span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
<span class="go">4</span>
</code></pre></dd></dl></div><div class="section" id="xmlpullparser-objects"><h3><span class="yiyi-st" id="yiyi-457">20.5.3.7. </span><span class="yiyi-st" id="yiyi-458">XMLPullParser Objects</span></h3><dl class="class"><dt id="xml.etree.ElementTree.XMLPullParser"><span class="yiyi-st" id="yiyi-459"> <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></span></dt><dd><p><span class="yiyi-st" id="yiyi-460">A pull parser suitable for non-blocking applications. </span><span class="yiyi-st" id="yiyi-461">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"><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"><span class="pre">XMLPullParser</span></code></a> collects an internal list of parsing events and lets the user read from it. </span><span class="yiyi-st" id="yiyi-462"><em>events</em> is a sequence of events to report back. </span><span class="yiyi-st" id="yiyi-463">The supported events are the strings <code class="docutils literal"><span class="pre">"start"</span></code>, <code class="docutils literal"><span class="pre">"end"</span></code>, <code class="docutils literal"><span class="pre">"start-ns"</span></code> and <code class="docutils literal"><span class="pre">"end-ns"</span></code> (the “ns” events are used to get detailed namespace information). </span><span class="yiyi-st" id="yiyi-464">If <em>events</em> is omitted, only <code class="docutils literal"><span class="pre">"end"</span></code> events are reported.</span></p><dl class="method"><dt id="xml.etree.ElementTree.XMLPullParser.feed"><span class="yiyi-st" id="yiyi-465"> <code class="descname">feed</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-466">Feed the given bytes data to the parser.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.XMLPullParser.close"><span class="yiyi-st" id="yiyi-467"> <code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-468">Signal the parser that the data stream is terminated. </span><span class="yiyi-st" id="yiyi-469">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"><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"><span class="pre">None</span></code></a>. </span><span class="yiyi-st" id="yiyi-470">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"><span class="pre">read_events()</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="xml.etree.ElementTree.XMLPullParser.read_events"><span class="yiyi-st" id="yiyi-471"> <code class="descname">read_events</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-472">Return an iterator over the events which have been encountered in the data fed to the parser. </span><span class="yiyi-st" id="yiyi-473">The iterator yields <code class="docutils literal"><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. </span><span class="yiyi-st" id="yiyi-474"><code class="docutils literal"><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"><span class="pre">Element</span></code></a> object.</span></p><p><span class="yiyi-st" id="yiyi-475">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"><span class="pre">read_events()</span></code></a> will not be yielded again. </span><span class="yiyi-st" id="yiyi-476">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"><span class="pre">read_events()</span></code></a> will have unpredictable results.</span></p></dd></dl><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-477">Note</span></p><p><span class="yiyi-st" id="yiyi-478"><a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal"><span class="pre">XMLPullParser</span></code></a> only guarantees that it has seen the “&gt;” 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. </span><span class="yiyi-st" id="yiyi-479">The same applies to the element children; they may or may not be present.</span></p><p class="last"><span class="yiyi-st" id="yiyi-480">If you need a fully populated element, look for “end” events instead.</span></p></div><div class="versionadded"><p><span class="yiyi-st" id="yiyi-481"><span class="versionmodified">New in version 3.4.</span></span></p></div></dd></dl></div><div class="section" id="exceptions"><h3><span class="yiyi-st" id="yiyi-482">20.5.3.8. </span><span class="yiyi-st" id="yiyi-483">Exceptions</span></h3><dl class="class"><dt id="xml.etree.ElementTree.ParseError"><span class="yiyi-st" id="yiyi-484"> <em class="property">class </em><code class="descclassname">xml.etree.ElementTree.</code><code class="descname">ParseError</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-485">XML parse error, raised by the various parsing methods in this module when parsing fails. </span><span class="yiyi-st" id="yiyi-486">The string representation of an instance of this exception will contain a user-friendly error message. </span><span class="yiyi-st" id="yiyi-487">In addition, it will have the following attributes available:</span></p><dl class="attribute"><dt id="xml.etree.ElementTree.ParseError.code"><span class="yiyi-st" id="yiyi-488"> <code class="descname">code</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-489">A numeric error code from the expat parser. </span><span class="yiyi-st" id="yiyi-490">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"><span class="pre">xml.parsers.expat</span></code></a> for the list of error codes and their meanings.</span></p></dd></dl><dl class="attribute"><dt id="xml.etree.ElementTree.ParseError.position"><span class="yiyi-st" id="yiyi-491"> <code class="descname">position</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-492">A tuple of <em>line</em>, <em>column</em> numbers, specifying where the error occurred.</span></p></dd></dl></dd></dl><p class="rubric"><span class="yiyi-st" id="yiyi-493">Footnotes</span></p><table class="docutils footnote" frame="void" id="id5" rules="none"><tbody valign="top"><tr><td class="label"><span class="yiyi-st" id="yiyi-494">[1]</span></td><td><span class="yiyi-st" id="yiyi-495">The encoding string included in XML output should conform to the appropriate standards. </span><span class="yiyi-st" id="yiyi-496">For example, “UTF-8” is valid, but “UTF8” is not. </span><span class="yiyi-st" id="yiyi-497">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>.</span></td></tr></tbody></table></div></div></div></div>