mirror of
https://github.com/fofolee/uTools-Manuals.git
synced 2025-06-29 13:04:32 +08:00
239 lines
128 KiB
HTML
239 lines
128 KiB
HTML
<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">We’ll 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"><?xml version="1.0"?></span>
|
||
<span class="nt"><data></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">></span>
|
||
<span class="nt"><rank></span>1<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2008<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>141100<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Austria"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Switzerland"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">></span>
|
||
<span class="nt"><rank></span>4<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>59900<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Malaysia"</span> <span class="na">direction=</span><span class="s">"N"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Panama"</span><span class="nt">></span>
|
||
<span class="nt"><rank></span>68<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>13600<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Costa Rica"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Colombia"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"></data></span>
|
||
</pre></div></div><p><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">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">tag</span>
|
||
<span class="go">'data'</span>
|
||
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">attrib</span>
|
||
<span class="go">{}</span>
|
||
</code></pre><p><span class="yiyi-st" id="yiyi-37">它也有子节点，我们可以迭代：</span></p><pre><code class="language-python"><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">root</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">child</span><span class="o">.</span><span class="n">tag</span><span class="p">,</span> <span class="n">child</span><span class="o">.</span><span class="n">attrib</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">country {'name': 'Liechtenstein'}</span>
|
||
<span class="go">country {'name': 'Singapore'}</span>
|
||
<span class="go">country {'name': 'Panama'}</span>
|
||
</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">>>> </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 module’s API rather than parsing from XML text can have comments and processing instructions in them; they will be included when generating XML output. </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">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">XMLPullParser</span><span class="p">([</span><span class="s1">'start'</span><span class="p">,</span> <span class="s1">'end'</span><span class="p">])</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="s1">'<mytag>sometext'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">read_events</span><span class="p">())</span>
|
||
<span class="go">[('start', <Element 'mytag' at 0x7fa66db2be58>)]</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="s1">' more text</mytag>'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">event</span><span class="p">,</span> <span class="n">elem</span> <span class="ow">in</span> <span class="n">parser</span><span class="o">.</span><span class="n">read_events</span><span class="p">():</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">elem</span><span class="o">.</span><span class="n">tag</span><span class="p">,</span> <span class="s1">'text='</span><span class="p">,</span> <span class="n">elem</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">end</span>
|
||
</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 it’s so flexible, <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal"><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 don’t mind your application blocking on reading XML data but would still like to have incremental parsing capabilities, take a look at <a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal"><span class="pre">iterparse()</span></code></a>. </span><span class="yiyi-st" id="yiyi-57">It can be useful when you’re reading a large XML document and don’t 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">>>> </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 element’s 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 element’s attributes:</span></p><pre><code class="language-python"><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">country</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">'country'</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">rank</span> <span class="o">=</span> <span class="n">country</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s1">'rank'</span><span class="p">)</span><span class="o">.</span><span class="n">text</span>
|
||
<span class="gp">... </span> <span class="n">name</span> <span class="o">=</span> <span class="n">country</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'name'</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">rank</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">Liechtenstein 1</span>
|
||
<span class="go">Singapore 4</span>
|
||
<span class="go">Panama 68</span>
|
||
</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">Let’s say we want to add one to each country’s 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">>>> </span><span class="k">for</span> <span class="n">rank</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iter</span><span class="p">(</span><span class="s1">'rank'</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">new_rank</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">rank</span><span class="o">.</span><span class="n">text</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span>
|
||
<span class="gp">... </span> <span class="n">rank</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">new_rank</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="n">rank</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'updated'</span><span class="p">,</span> <span class="s1">'yes'</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'output.xml'</span><span class="p">)</span>
|
||
</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"><?xml version="1.0"?></span>
|
||
<span class="nt"><data></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>2<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2008<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>141100<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Austria"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Switzerland"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>5<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>59900<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Malaysia"</span> <span class="na">direction=</span><span class="s">"N"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Panama"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>69<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>13600<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Costa Rica"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Colombia"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"></data></span>
|
||
</pre></div></div><p><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">Let’s 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">>>> </span><span class="k">for</span> <span class="n">country</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">'country'</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="n">rank</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">country</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s1">'rank'</span><span class="p">)</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">if</span> <span class="n">rank</span> <span class="o">></span> <span class="mi">50</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">root</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">country</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'output.xml'</span><span class="p">)</span>
|
||
</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"><?xml version="1.0"?></span>
|
||
<span class="nt"><data></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Liechtenstein"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>2<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2008<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>141100<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Austria"</span> <span class="na">direction=</span><span class="s">"E"</span><span class="nt">/></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Switzerland"</span> <span class="na">direction=</span><span class="s">"W"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"><country</span> <span class="na">name=</span><span class="s">"Singapore"</span><span class="nt">></span>
|
||
<span class="nt"><rank</span> <span class="na">updated=</span><span class="s">"yes"</span><span class="nt">></span>5<span class="nt"></rank></span>
|
||
<span class="nt"><year></span>2011<span class="nt"></year></span>
|
||
<span class="nt"><gdppc></span>59900<span class="nt"></gdppc></span>
|
||
<span class="nt"><neighbor</span> <span class="na">name=</span><span class="s">"Malaysia"</span> <span class="na">direction=</span><span class="s">"N"</span><span class="nt">/></span>
|
||
<span class="nt"></country></span>
|
||
<span class="nt"></data></span>
|
||
</pre></div></div></div><div class="section" id="building-xml-documents"><h3><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">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s1">'a'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="s1">'c'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="s1">'d'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">ET</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
|
||
<span class="go"><a><b /><c><d /></c></a></span>
|
||
</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"><?xml version="1.0"?></span>
|
||
<span class="nt"><actors</span> <span class="na">xmlns:fictional=</span><span class="s">"http://characters.example.com"</span>
|
||
<span class="na">xmlns=</span><span class="s">"http://people.example.com"</span><span class="nt">></span>
|
||
<span class="nt"><actor></span>
|
||
<span class="nt"><name></span>John Cleese<span class="nt"></name></span>
|
||
<span class="nt"><fictional:character></span>Lancelot<span class="nt"></fictional:character></span>
|
||
<span class="nt"><fictional:character></span>Archie Leach<span class="nt"></fictional:character></span>
|
||
<span class="nt"></actor></span>
|
||
<span class="nt"><actor></span>
|
||
<span class="nt"><name></span>Eric Idle<span class="nt"></name></span>
|
||
<span class="nt"><fictional:character></span>Sir Robin<span class="nt"></fictional:character></span>
|
||
<span class="nt"><fictional:character></span>Gunther<span class="nt"></fictional:character></span>
|
||
<span class="nt"><fictional:character></span>Commander Clement<span class="nt"></fictional:character></span>
|
||
<span class="nt"></actor></span>
|
||
<span class="nt"></actors></span>
|
||
</pre></div></div><p><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">' |-->'</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">' |-->'</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">|--></span> <span class="n">Lancelot</span>
|
||
<span class="o">|--></span> <span class="n">Archie</span> <span class="n">Leach</span>
|
||
<span class="n">Eric</span> <span class="n">Idle</span>
|
||
<span class="o">|--></span> <span class="n">Sir</span> <span class="n">Robin</span>
|
||
<span class="o">|--></span> <span class="n">Gunther</span>
|
||
<span class="o">|--></span> <span class="n">Commander</span> <span class="n">Clement</span>
|
||
</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">Here’s an example that demonstrates some of the XPath capabilities of the module. </span><span class="yiyi-st" id="yiyi-97">We’ll 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 it’s 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, it’s 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 what’s 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, it’s unsuitable for applications where blocking reads can’t 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 “>” 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 element’s 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 element’s 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"><a><b></span>1<span class="nt"><c></span>2<span class="nt"><d/></span>3<span class="nt"></c></b></span>4<span class="nt"></a></span>
|
||
</pre></div></div><p><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 element’s 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 element’s 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 element’s 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, it’s binary. </span><span class="yiyi-st" id="yiyi-390">Note that this may conflict with the type of <em>file</em> if it’s an open <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>; make sure you do not try to write a string to a binary stream and vice versa.</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"><</span><span class="n">html</span><span class="o">></span>
|
||
<span class="o"><</span><span class="n">head</span><span class="o">></span>
|
||
<span class="o"><</span><span class="n">title</span><span class="o">></span><span class="n">Example</span> <span class="n">page</span><span class="o"></</span><span class="n">title</span><span class="o">></span>
|
||
<span class="o"></</span><span class="n">head</span><span class="o">></span>
|
||
<span class="o"><</span><span class="n">body</span><span class="o">></span>
|
||
<span class="o"><</span><span class="n">p</span><span class="o">></span><span class="n">Moved</span> <span class="n">to</span> <span class="o"><</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">"http://example.org/"</span><span class="o">></span><span class="n">example</span><span class="o">.</span><span class="n">org</span><span class="o"></</span><span class="n">a</span><span class="o">></span>
|
||
<span class="ow">or</span> <span class="o"><</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">"http://example.com/"</span><span class="o">></span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o"></</span><span class="n">a</span><span class="o">>.</</span><span class="n">p</span><span class="o">></span>
|
||
<span class="o"></</span><span class="n">body</span><span class="o">></span>
|
||
<span class="o"></</span><span class="n">html</span><span class="o">></span>
|
||
</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">>>> </span><span class="kn">from</span> <span class="nn">xml.etree.ElementTree</span> <span class="k">import</span> <span class="n">ElementTree</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span> <span class="o">=</span> <span class="n">ElementTree</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">"index.xhtml"</span><span class="p">)</span>
|
||
<span class="go"><Element 'html' at 0xb77e6fac></span>
|
||
<span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">tree</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s2">"body/p"</span><span class="p">)</span> <span class="c1"># Finds first occurrence of tag p in body</span>
|
||
<span class="gp">>>> </span><span class="n">p</span>
|
||
<span class="go"><Element 'p' at 0xb77ec26c></span>
|
||
<span class="gp">>>> </span><span class="n">links</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">iter</span><span class="p">(</span><span class="s2">"a"</span><span class="p">))</span> <span class="c1"># Returns list of all links</span>
|
||
<span class="gp">>>> </span><span class="n">links</span>
|
||
<span class="go">[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">links</span><span class="p">:</span> <span class="c1"># Iterates through all found links</span>
|
||
<span class="gp">... </span> <span class="n">i</span><span class="o">.</span><span class="n">attrib</span><span class="p">[</span><span class="s2">"target"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"blank"</span>
|
||
<span class="gp">>>> </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">"output.xhtml"</span><span class="p">)</span>
|
||
</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">>>> </span><span class="kn">from</span> <span class="nn">xml.etree.ElementTree</span> <span class="k">import</span> <span class="n">XMLParser</span>
|
||
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">MaxDepth</span><span class="p">:</span> <span class="c1"># The target object of the parser</span>
|
||
<span class="gp">... </span> <span class="n">maxDepth</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="gp">... </span> <span class="n">depth</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="gp">... </span> <span class="k">def</span> <span class="nf">start</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tag</span><span class="p">,</span> <span class="n">attrib</span><span class="p">):</span> <span class="c1"># Called for each opening tag.</span>
|
||
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="gp">... </span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">></span> <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span>
|
||
<span class="gp">... </span> <span class="k">def</span> <span class="nf">end</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tag</span><span class="p">):</span> <span class="c1"># Called for each closing tag.</span>
|
||
<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">-=</span> <span class="mi">1</span>
|
||
<span class="gp">... </span> <span class="k">def</span> <span class="nf">data</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
|
||
<span class="gp">... </span> <span class="k">pass</span> <span class="c1"># We do not need to do anything with data.</span>
|
||
<span class="gp">... </span> <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="c1"># Called when all data has been parsed.</span>
|
||
<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">target</span> <span class="o">=</span> <span class="n">MaxDepth</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">XMLParser</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">target</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">exampleXml</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2"><a></span>
|
||
<span class="gp">... </span><span class="s2"> <b></span>
|
||
<span class="gp">... </span><span class="s2"> </b></span>
|
||
<span class="gp">... </span><span class="s2"> <b></span>
|
||
<span class="gp">... </span><span class="s2"> <c></span>
|
||
<span class="gp">... </span><span class="s2"> <d></span>
|
||
<span class="gp">... </span><span class="s2"> </d></span>
|
||
<span class="gp">... </span><span class="s2"> </c></span>
|
||
<span class="gp">... </span><span class="s2"> </b></span>
|
||
<span class="gp">... </span><span class="s2"></a>"""</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="n">exampleXml</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
<span class="go">4</span>
|
||
</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 “>” 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> |