Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
xml.etree.elementtree.html2010 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="xml.etree.ElementTree — The ElementTree XML API" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/xml.etree.elementtree.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/xml/etree/ElementTree.py The xml.etree.ElementTree module implements a simple and efficient API for parsing and creating XML data. Tutorial: This is a short tutorial for using xml...." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_xml.etree.elementtree_9e075cad.png" />15<meta property="og:image:alt" content="Source code: Lib/xml/etree/ElementTree.py The xml.etree.ElementTree module implements a simple and efficient API for parsing and creating XML data. Tutorial: This is a short tutorial for using xml...." />16<meta name="description" content="Source code: Lib/xml/etree/ElementTree.py The xml.etree.ElementTree module implements a simple and efficient API for parsing and creating XML data. Tutorial: This is a short tutorial for using xml...." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>xml.etree.ElementTree — The ElementTree XML API &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="xml.dom — The Document Object Model API" href="xml.dom.html" />43    <link rel="prev" title="XML Processing Modules" href="xml.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/xml.etree.elementtree.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code> — The ElementTree XML API</a><ul>108<li><a class="reference internal" href="#tutorial">Tutorial</a><ul>109<li><a class="reference internal" href="#xml-tree-and-elements">XML tree and elements</a></li>110<li><a class="reference internal" href="#parsing-xml">Parsing XML</a></li>111<li><a class="reference internal" href="#pull-api-for-non-blocking-parsing">Pull API for non-blocking parsing</a></li>112<li><a class="reference internal" href="#finding-interesting-elements">Finding interesting elements</a></li>113<li><a class="reference internal" href="#modifying-an-xml-file">Modifying an XML File</a></li>114<li><a class="reference internal" href="#building-xml-documents">Building XML documents</a></li>115<li><a class="reference internal" href="#parsing-xml-with-namespaces">Parsing XML with Namespaces</a></li>116</ul>117</li>118<li><a class="reference internal" href="#xpath-support">XPath support</a><ul>119<li><a class="reference internal" href="#example">Example</a></li>120<li><a class="reference internal" href="#supported-xpath-syntax">Supported XPath syntax</a></li>121</ul>122</li>123<li><a class="reference internal" href="#reference">Reference</a><ul>124<li><a class="reference internal" href="#functions">Functions</a></li>125</ul>126</li>127<li><a class="reference internal" href="#xinclude-support">XInclude support</a><ul>128<li><a class="reference internal" href="#id3">Example</a></li>129</ul>130</li>131<li><a class="reference internal" href="#id4">Reference</a><ul>132<li><a class="reference internal" href="#elementinclude-functions">Functions</a></li>133<li><a class="reference internal" href="#element-objects">Element Objects</a></li>134<li><a class="reference internal" href="#elementtree-objects">ElementTree Objects</a></li>135<li><a class="reference internal" href="#qname-objects">QName Objects</a></li>136<li><a class="reference internal" href="#treebuilder-objects">TreeBuilder Objects</a></li>137<li><a class="reference internal" href="#xmlparser-objects">XMLParser Objects</a></li>138<li><a class="reference internal" href="#xmlpullparser-objects">XMLPullParser Objects</a></li>139<li><a class="reference internal" href="#exceptions">Exceptions</a></li>140</ul>141</li>142</ul>143</li>144</ul>145 146  </div>147  <div>148    <h4>Previous topic</h4>149    <p class="topless"><a href="xml.html"150                          title="previous chapter">XML Processing Modules</a></p>151  </div>152  <div>153    <h4>Next topic</h4>154    <p class="topless"><a href="xml.dom.html"155                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.dom</span></code> — The Document Object Model API</a></p>156  </div>157  <script>158    document.addEventListener('DOMContentLoaded', () => {159        const title = document.querySelector('meta[property="og:title"]').content;160        const elements = document.querySelectorAll('.improvepage');161        const pageurl = window.location.href.split('?')[0];162        elements.forEach(element => {163            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));164            url.searchParams.set('pagetitle', title);165            url.searchParams.set('pageurl', pageurl);166            url.searchParams.set('pagesource', "library/xml.etree.elementtree.rst");167            element.href = url.toString();168        });169    });170  </script>171  <div role="note" aria-label="source link">172    <h3>This page</h3>173    <ul class="this-page-menu">174      <li><a href="../bugs.html">Report a bug</a></li>175      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>176      <li>177        <a href="https://github.com/python/cpython/blob/main/Doc/library/xml.etree.elementtree.rst?plain=1"178            rel="nofollow">Show source179        </a>180      </li>181      182    </ul>183  </div>184        </nav>185    </div>186</div>187 188  189    <div class="related" role="navigation" aria-label="Related">190      <h3>Navigation</h3>191      <ul>192        <li class="right" style="margin-right: 10px">193          <a href="../genindex.html" title="General Index"194             accesskey="I">index</a></li>195        <li class="right" >196          <a href="../py-modindex.html" title="Python Module Index"197             >modules</a> |</li>198        <li class="right" >199          <a href="xml.dom.html" title="xml.dom — The Document Object Model API"200             accesskey="N">next</a> |</li>201        <li class="right" >202          <a href="xml.html" title="XML Processing Modules"203             accesskey="P">previous</a> |</li>204 205          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>206          <li><a href="https://www.python.org/">Python</a> &#187;</li>207          <li class="switchers">208            <div class="language_switcher_placeholder"></div>209            <div class="version_switcher_placeholder"></div>210          </li>211          <li>212              213          </li>214    <li id="cpython-language-and-version">215      <a href="../index.html">3.15.0a6 Documentation</a> &#187;216    </li>217 218          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>219          <li class="nav-item nav-item-2"><a href="markup.html" accesskey="U">Structured Markup Processing Tools</a> &#187;</li>220        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code> — The ElementTree XML API</a></li>221                <li class="right">222                    223 224    <div class="inline-search" role="search">225        <form class="inline-search" action="../search.html" method="get">226          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">227          <input type="submit" value="Go">228        </form>229    </div>230                     |231                </li>232            <li class="right">233<label class="theme-selector-label">234    Theme235    <select class="theme-selector" oninput="activateTheme(this.value)">236        <option value="auto" selected>Auto</option>237        <option value="light">Light</option>238        <option value="dark">Dark</option>239    </select>240</label> |</li>241            242      </ul>243    </div>    244 245    <div class="document">246      <div class="documentwrapper">247        <div class="bodywrapper">248          <div class="body" role="main">249            250  <section id="module-xml.etree.ElementTree">251<span id="xml-etree-elementtree-the-elementtree-xml-api"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code> — The ElementTree XML API<a class="headerlink" href="#module-xml.etree.ElementTree" title="Link to this heading">¶</a></h1>252<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/xml/etree/ElementTree.py">Lib/xml/etree/ElementTree.py</a></p>253<hr class="docutils" />254<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code> module implements a simple and efficient API255for parsing and creating XML data.</p>256<div class="versionchanged">257<p><span class="versionmodified changed">Changed in version 3.3: </span>This module will use a fast implementation whenever available.</p>258</div>259<div class="deprecated">260<p><span class="versionmodified deprecated">Deprecated since version 3.3: </span>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.cElementTree</span></code> module is deprecated.</p>261</div>262<div class="admonition note">263<p class="admonition-title">Note</p>264<p>If you need to parse untrusted or unauthenticated data, see265<a class="reference internal" href="xml.html#xml-security"><span class="std std-ref">XML security</span></a>.</p>266</div>267<section id="tutorial">268<h2>Tutorial<a class="headerlink" href="#tutorial" title="Link to this heading">¶</a></h2>269<p>This is a short tutorial for using <code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code> (<code class="docutils literal notranslate"><span class="pre">ET</span></code> in270short).  The goal is to demonstrate some of the building blocks and basic271concepts of the module.</p>272<section id="xml-tree-and-elements">273<h3>XML tree and elements<a class="headerlink" href="#xml-tree-and-elements" title="Link to this heading">¶</a></h3>274<p>XML is an inherently hierarchical data format, and the most natural way to275represent it is with a tree.  <code class="docutils literal notranslate"><span class="pre">ET</span></code> has two classes for this purpose -276<a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> represents the whole XML document as a tree, and277<a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> represents a single node in this tree.  Interactions with278the whole document (reading and writing to/from files) are usually done279on the <code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code> level.  Interactions with a single XML element280and its sub-elements are done on the <code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code> level.</p>281</section>282<section id="parsing-xml">283<span id="elementtree-parsing-xml"></span><h3>Parsing XML<a class="headerlink" href="#parsing-xml" title="Link to this heading">¶</a></h3>284<p>We’ll be using the fictive <code class="file docutils literal notranslate"><span class="pre">country_data.xml</span></code> XML document as the sample data for this section:</p>285<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>286<span class="nt">&lt;data&gt;</span>287<span class="w">    </span><span class="nt">&lt;country</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Liechtenstein&quot;</span><span class="nt">&gt;</span>288<span class="w">        </span><span class="nt">&lt;rank&gt;</span>1<span class="nt">&lt;/rank&gt;</span>289<span class="w">        </span><span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>290<span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>291<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Austria&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;E&quot;</span><span class="nt">/&gt;</span>292<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Switzerland&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;W&quot;</span><span class="nt">/&gt;</span>293<span class="w">    </span><span class="nt">&lt;/country&gt;</span>294<span class="w">    </span><span class="nt">&lt;country</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Singapore&quot;</span><span class="nt">&gt;</span>295<span class="w">        </span><span class="nt">&lt;rank&gt;</span>4<span class="nt">&lt;/rank&gt;</span>296<span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>297<span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>298<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Malaysia&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;N&quot;</span><span class="nt">/&gt;</span>299<span class="w">    </span><span class="nt">&lt;/country&gt;</span>300<span class="w">    </span><span class="nt">&lt;country</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Panama&quot;</span><span class="nt">&gt;</span>301<span class="w">        </span><span class="nt">&lt;rank&gt;</span>68<span class="nt">&lt;/rank&gt;</span>302<span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>303<span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>13600<span class="nt">&lt;/gdppc&gt;</span>304<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Costa Rica&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;W&quot;</span><span class="nt">/&gt;</span>305<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Colombia&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;E&quot;</span><span class="nt">/&gt;</span>306<span class="w">    </span><span class="nt">&lt;/country&gt;</span>307<span class="nt">&lt;/data&gt;</span>308</pre></div>309</div>310<p>We can import this data by reading from a file:</p>311<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">xml.etree.ElementTree</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">ET</span>312<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">&#39;country_data.xml&#39;</span><span class="p">)</span>313<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>314</pre></div>315</div>316<p>Or directly from a string:</p>317<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">root</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="n">country_data_as_string</span><span class="p">)</span>318</pre></div>319</div>320<p><a class="reference internal" href="#xml.etree.ElementTree.fromstring" title="xml.etree.ElementTree.fromstring"><code class="xref py py-func docutils literal notranslate"><span class="pre">fromstring()</span></code></a> parses XML from a string directly into an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>,321which is the root element of the parsed tree.  Other parsing functions may322create an <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a>.  Check the documentation to be sure.</p>323<p>As an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>, <code class="docutils literal notranslate"><span class="pre">root</span></code> has a tag and a dictionary of attributes:</p>324<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">tag</span>325<span class="go">&#39;data&#39;</span>326<span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">attrib</span>327<span class="go">{}</span>328</pre></div>329</div>330<p>It also has children nodes over which we can iterate:</p>331<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">child</span> <span class="ow">in</span> <span class="n">root</span><span class="p">:</span>332<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>333<span class="gp">...</span>334<span class="go">country {&#39;name&#39;: &#39;Liechtenstein&#39;}</span>335<span class="go">country {&#39;name&#39;: &#39;Singapore&#39;}</span>336<span class="go">country {&#39;name&#39;: &#39;Panama&#39;}</span>337</pre></div>338</div>339<p>Children are nested, and we can access specific child nodes by index:</p>340<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">text</span>341<span class="go">&#39;2008&#39;</span>342</pre></div>343</div>344<div class="admonition note">345<p class="admonition-title">Note</p>346<p>Not all elements of the XML input will end up as elements of the347parsed tree. Currently, this module skips over any XML comments,348processing instructions, and document type declarations in the349input. Nevertheless, trees built using this module’s API rather350than parsing from XML text can have comments and processing351instructions in them; they will be included when generating XML352output. A document type declaration may be accessed by passing a353custom <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> instance to the <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a>354constructor.</p>355</div>356</section>357<section id="pull-api-for-non-blocking-parsing">358<span id="elementtree-pull-parsing"></span><h3>Pull API for non-blocking parsing<a class="headerlink" href="#pull-api-for-non-blocking-parsing" title="Link to this heading">¶</a></h3>359<p>Most parsing functions provided by this module require the whole document360to be read at once before returning any result.  It is possible to use an361<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> and feed data into it incrementally, but it is a push API that362calls methods on a callback target, which is too low-level and inconvenient for363most needs.  Sometimes what the user really wants is to be able to parse XML364incrementally, without blocking operations, while enjoying the convenience of365fully constructed <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> objects.</p>366<p>The most powerful tool for doing this is <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a>.  It does not367require a blocking read to obtain the XML data, and is instead fed with data368incrementally with <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.feed" title="xml.etree.ElementTree.XMLPullParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLPullParser.feed()</span></code></a> calls.  To get the parsed XML369elements, call <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLPullParser.read_events()</span></code></a>.  Here is an example:</p>370<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">XMLPullParser</span><span class="p">([</span><span class="s1">&#39;start&#39;</span><span class="p">,</span> <span class="s1">&#39;end&#39;</span><span class="p">])</span>371<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="s1">&#39;&lt;mytag&gt;sometext&#39;</span><span class="p">)</span>372<span class="gp">&gt;&gt;&gt; </span><span class="nb">list</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">read_events</span><span class="p">())</span>373<span class="go">[(&#39;start&#39;, &lt;Element &#39;mytag&#39; at 0x7fa66db2be58&gt;)]</span>374<span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="s1">&#39; more text&lt;/mytag&gt;&#39;</span><span class="p">)</span>375<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">event</span><span class="p">,</span> <span class="n">elem</span> <span class="ow">in</span> <span class="n">parser</span><span class="o">.</span><span class="n">read_events</span><span class="p">():</span>376<span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>377<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">&#39;text=&#39;</span><span class="p">,</span> <span class="n">elem</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>378<span class="gp">...</span>379<span class="go">end</span>380<span class="go">mytag text= sometext more text</span>381</pre></div>382</div>383<p>The obvious use case is applications that operate in a non-blocking fashion384where the XML data is being received from a socket or read incrementally from385some storage device.  In such cases, blocking reads are unacceptable.</p>386<p>Because it’s so flexible, <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a> can be inconvenient to use for387simpler use-cases.  If you don’t mind your application blocking on reading XML388data but would still like to have incremental parsing capabilities, take a look389at <a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code></a>.  It can be useful when you’re reading a large XML document390and don’t want to hold it wholly in memory.</p>391<p>Where <em>immediate</em> feedback through events is wanted, calling method392<a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.flush" title="xml.etree.ElementTree.XMLPullParser.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLPullParser.flush()</span></code></a> can help reduce delay;393please make sure to study the related security notes.</p>394</section>395<section id="finding-interesting-elements">396<h3>Finding interesting elements<a class="headerlink" href="#finding-interesting-elements" title="Link to this heading">¶</a></h3>397<p><a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> has some useful methods that help iterate recursively over all398the sub-tree below it (its children, their children, and so on).  For example,399<a class="reference internal" href="#xml.etree.ElementTree.Element.iter" title="xml.etree.ElementTree.Element.iter"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.iter()</span></code></a>:</p>400<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">neighbor</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iter</span><span class="p">(</span><span class="s1">&#39;neighbor&#39;</span><span class="p">):</span>401<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>402<span class="gp">...</span>403<span class="go">{&#39;name&#39;: &#39;Austria&#39;, &#39;direction&#39;: &#39;E&#39;}</span>404<span class="go">{&#39;name&#39;: &#39;Switzerland&#39;, &#39;direction&#39;: &#39;W&#39;}</span>405<span class="go">{&#39;name&#39;: &#39;Malaysia&#39;, &#39;direction&#39;: &#39;N&#39;}</span>406<span class="go">{&#39;name&#39;: &#39;Costa Rica&#39;, &#39;direction&#39;: &#39;W&#39;}</span>407<span class="go">{&#39;name&#39;: &#39;Colombia&#39;, &#39;direction&#39;: &#39;E&#39;}</span>408</pre></div>409</div>410<p><a class="reference internal" href="#xml.etree.ElementTree.Element.findall" title="xml.etree.ElementTree.Element.findall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.findall()</span></code></a> finds only elements with a tag which are direct411children of the current element.  <a class="reference internal" href="#xml.etree.ElementTree.Element.find" title="xml.etree.ElementTree.Element.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.find()</span></code></a> finds the <em>first</em> child412with a particular tag, and <a class="reference internal" href="#xml.etree.ElementTree.Element.text" title="xml.etree.ElementTree.Element.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Element.text</span></code></a> accesses the element’s text413content.  <a class="reference internal" href="#xml.etree.ElementTree.Element.get" title="xml.etree.ElementTree.Element.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.get()</span></code></a> accesses the element’s attributes:</p>414<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">country</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">&#39;country&#39;</span><span class="p">):</span>415<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">&#39;rank&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">text</span>416<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">&#39;name&#39;</span><span class="p">)</span>417<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>418<span class="gp">...</span>419<span class="go">Liechtenstein 1</span>420<span class="go">Singapore 4</span>421<span class="go">Panama 68</span>422</pre></div>423</div>424<p>More sophisticated specification of which elements to look for is possible by425using <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">XPath</span></a>.</p>426</section>427<section id="modifying-an-xml-file">428<h3>Modifying an XML File<a class="headerlink" href="#modifying-an-xml-file" title="Link to this heading">¶</a></h3>429<p><a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> provides a simple way to build XML documents and write them to files.430The <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a> method serves this purpose.</p>431<p>Once created, an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> object may be manipulated by directly changing432its fields (such as <a class="reference internal" href="#xml.etree.ElementTree.Element.text" title="xml.etree.ElementTree.Element.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Element.text</span></code></a>), adding and modifying attributes433(<a class="reference internal" href="#xml.etree.ElementTree.Element.set" title="xml.etree.ElementTree.Element.set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.set()</span></code></a> method), as well as adding new children (for example434with <a class="reference internal" href="#xml.etree.ElementTree.Element.append" title="xml.etree.ElementTree.Element.append"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.append()</span></code></a>).</p>435<p>Let’s say we want to add one to each country’s rank, and add an <code class="docutils literal notranslate"><span class="pre">updated</span></code>436attribute to the rank element:</p>437<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">rank</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iter</span><span class="p">(</span><span class="s1">&#39;rank&#39;</span><span class="p">):</span>438<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>439<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>440<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">&#39;updated&#39;</span><span class="p">,</span> <span class="s1">&#39;yes&#39;</span><span class="p">)</span>441<span class="gp">...</span>442<span class="gp">&gt;&gt;&gt; </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;output.xml&#39;</span><span class="p">)</span>443</pre></div>444</div>445<p>Our XML now looks like this:</p>446<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>447<span class="nt">&lt;data&gt;</span>448<span class="w">    </span><span class="nt">&lt;country</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Liechtenstein&quot;</span><span class="nt">&gt;</span>449<span class="w">        </span><span class="nt">&lt;rank</span><span class="w"> </span><span class="na">updated=</span><span class="s">&quot;yes&quot;</span><span class="nt">&gt;</span>2<span class="nt">&lt;/rank&gt;</span>450<span class="w">        </span><span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>451<span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>452<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Austria&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;E&quot;</span><span class="nt">/&gt;</span>453<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Switzerland&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;W&quot;</span><span class="nt">/&gt;</span>454<span class="w">    </span><span class="nt">&lt;/country&gt;</span>455<span class="w">    </span><span class="nt">&lt;country</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Singapore&quot;</span><span class="nt">&gt;</span>456<span class="w">        </span><span class="nt">&lt;rank</span><span class="w"> </span><span class="na">updated=</span><span class="s">&quot;yes&quot;</span><span class="nt">&gt;</span>5<span class="nt">&lt;/rank&gt;</span>457<span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>458<span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>459<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Malaysia&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;N&quot;</span><span class="nt">/&gt;</span>460<span class="w">    </span><span class="nt">&lt;/country&gt;</span>461<span class="w">    </span><span class="nt">&lt;country</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Panama&quot;</span><span class="nt">&gt;</span>462<span class="w">        </span><span class="nt">&lt;rank</span><span class="w"> </span><span class="na">updated=</span><span class="s">&quot;yes&quot;</span><span class="nt">&gt;</span>69<span class="nt">&lt;/rank&gt;</span>463<span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>464<span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>13600<span class="nt">&lt;/gdppc&gt;</span>465<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Costa Rica&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;W&quot;</span><span class="nt">/&gt;</span>466<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Colombia&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;E&quot;</span><span class="nt">/&gt;</span>467<span class="w">    </span><span class="nt">&lt;/country&gt;</span>468<span class="nt">&lt;/data&gt;</span>469</pre></div>470</div>471<p>We can remove elements using <a class="reference internal" href="#xml.etree.ElementTree.Element.remove" title="xml.etree.ElementTree.Element.remove"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.remove()</span></code></a>.  Let’s say we want to472remove all countries with a rank higher than 50:</p>473<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">country</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s1">&#39;country&#39;</span><span class="p">):</span>474<span class="gp">... </span>    <span class="c1"># using root.findall() to avoid removal during traversal</span>475<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">&#39;rank&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>476<span class="gp">... </span>    <span class="k">if</span> <span class="n">rank</span> <span class="o">&gt;</span> <span class="mi">50</span><span class="p">:</span>477<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>478<span class="gp">...</span>479<span class="gp">&gt;&gt;&gt; </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;output.xml&#39;</span><span class="p">)</span>480</pre></div>481</div>482<p>Note that concurrent modification while iterating can lead to problems,483just like when iterating and modifying Python lists or dicts.484Therefore, the example first collects all matching elements with485<code class="docutils literal notranslate"><span class="pre">root.findall()</span></code>, and only then iterates over the list of matches.</p>486<p>Our XML now looks like this:</p>487<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>488<span class="nt">&lt;data&gt;</span>489<span class="w">    </span><span class="nt">&lt;country</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Liechtenstein&quot;</span><span class="nt">&gt;</span>490<span class="w">        </span><span class="nt">&lt;rank</span><span class="w"> </span><span class="na">updated=</span><span class="s">&quot;yes&quot;</span><span class="nt">&gt;</span>2<span class="nt">&lt;/rank&gt;</span>491<span class="w">        </span><span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>492<span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>493<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Austria&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;E&quot;</span><span class="nt">/&gt;</span>494<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Switzerland&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;W&quot;</span><span class="nt">/&gt;</span>495<span class="w">    </span><span class="nt">&lt;/country&gt;</span>496<span class="w">    </span><span class="nt">&lt;country</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Singapore&quot;</span><span class="nt">&gt;</span>497<span class="w">        </span><span class="nt">&lt;rank</span><span class="w"> </span><span class="na">updated=</span><span class="s">&quot;yes&quot;</span><span class="nt">&gt;</span>5<span class="nt">&lt;/rank&gt;</span>498<span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>499<span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>500<span class="w">        </span><span class="nt">&lt;neighbor</span><span class="w"> </span><span class="na">name=</span><span class="s">&quot;Malaysia&quot;</span><span class="w"> </span><span class="na">direction=</span><span class="s">&quot;N&quot;</span><span class="nt">/&gt;</span>501<span class="w">    </span><span class="nt">&lt;/country&gt;</span>502<span class="nt">&lt;/data&gt;</span>503</pre></div>504</div>505</section>506<section id="building-xml-documents">507<h3>Building XML documents<a class="headerlink" href="#building-xml-documents" title="Link to this heading">¶</a></h3>508<p>The <a class="reference internal" href="#xml.etree.ElementTree.SubElement" title="xml.etree.ElementTree.SubElement"><code class="xref py py-func docutils literal notranslate"><span class="pre">SubElement()</span></code></a> function also provides a convenient way to create new509sub-elements for a given element:</p>510<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s1">&#39;a&#39;</span><span class="p">)</span>511<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">)</span>512<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="s1">&#39;c&#39;</span><span class="p">)</span>513<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="n">ET</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="s1">&#39;d&#39;</span><span class="p">)</span>514<span class="gp">&gt;&gt;&gt; </span><span class="n">ET</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>515<span class="go">&lt;a&gt;&lt;b /&gt;&lt;c&gt;&lt;d /&gt;&lt;/c&gt;&lt;/a&gt;</span>516</pre></div>517</div>518</section>519<section id="parsing-xml-with-namespaces">520<h3>Parsing XML with Namespaces<a class="headerlink" href="#parsing-xml-with-namespaces" title="Link to this heading">¶</a></h3>521<p>If the XML input has <a class="reference external" href="https://en.wikipedia.org/wiki/XML_namespace">namespaces</a>, tags and attributes522with prefixes in the form <code class="docutils literal notranslate"><span class="pre">prefix:sometag</span></code> get expanded to523<code class="docutils literal notranslate"><span class="pre">{uri}sometag</span></code> where the <em>prefix</em> is replaced by the full <em>URI</em>.524Also, if there is a <a class="reference external" href="https://www.w3.org/TR/xml-names/#defaulting">default namespace</a>,525that full URI gets prepended to all of the non-prefixed tags.</p>526<p>Here is an XML example that incorporates two namespaces, one with the527prefix “fictional” and the other serving as the default namespace:</p>528<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>529<span class="nt">&lt;actors</span><span class="w"> </span><span class="na">xmlns:fictional=</span><span class="s">&quot;http://characters.example.com&quot;</span>530<span class="w">        </span><span class="na">xmlns=</span><span class="s">&quot;http://people.example.com&quot;</span><span class="nt">&gt;</span>531<span class="w">    </span><span class="nt">&lt;actor&gt;</span>532<span class="w">        </span><span class="nt">&lt;name&gt;</span>John<span class="w"> </span>Cleese<span class="nt">&lt;/name&gt;</span>533<span class="w">        </span><span class="nt">&lt;fictional:character&gt;</span>Lancelot<span class="nt">&lt;/fictional:character&gt;</span>534<span class="w">        </span><span class="nt">&lt;fictional:character&gt;</span>Archie<span class="w"> </span>Leach<span class="nt">&lt;/fictional:character&gt;</span>535<span class="w">    </span><span class="nt">&lt;/actor&gt;</span>536<span class="w">    </span><span class="nt">&lt;actor&gt;</span>537<span class="w">        </span><span class="nt">&lt;name&gt;</span>Eric<span class="w"> </span>Idle<span class="nt">&lt;/name&gt;</span>538<span class="w">        </span><span class="nt">&lt;fictional:character&gt;</span>Sir<span class="w"> </span>Robin<span class="nt">&lt;/fictional:character&gt;</span>539<span class="w">        </span><span class="nt">&lt;fictional:character&gt;</span>Gunther<span class="nt">&lt;/fictional:character&gt;</span>540<span class="w">        </span><span class="nt">&lt;fictional:character&gt;</span>Commander<span class="w"> </span>Clement<span class="nt">&lt;/fictional:character&gt;</span>541<span class="w">    </span><span class="nt">&lt;/actor&gt;</span>542<span class="nt">&lt;/actors&gt;</span>543</pre></div>544</div>545<p>One way to search and explore this XML example is to manually add the546URI to every tag or attribute in the xpath of a547<a class="reference internal" href="#xml.etree.ElementTree.Element.find" title="xml.etree.ElementTree.Element.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">find()</span></code></a> or <a class="reference internal" href="#xml.etree.ElementTree.Element.findall" title="xml.etree.ElementTree.Element.findall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">findall()</span></code></a>:</p>548<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">root</span> <span class="o">=</span> <span class="n">fromstring</span><span class="p">(</span><span class="n">xml_text</span><span class="p">)</span>549<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">&#39;{http://people.example.com}actor&#39;</span><span class="p">):</span>550    <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">&#39;{http://people.example.com}name&#39;</span><span class="p">)</span>551    <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>552    <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">&#39;{http://characters.example.com}character&#39;</span><span class="p">):</span>553        <span class="nb">print</span><span class="p">(</span><span class="s1">&#39; |--&gt;&#39;</span><span class="p">,</span> <span class="n">char</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>554</pre></div>555</div>556<p>A better way to search the namespaced XML example is to create a557dictionary with your own prefixes and use those in the search functions:</p>558<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">ns</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;real_person&#39;</span><span class="p">:</span> <span class="s1">&#39;http://people.example.com&#39;</span><span class="p">,</span>559      <span class="s1">&#39;role&#39;</span><span class="p">:</span> <span class="s1">&#39;http://characters.example.com&#39;</span><span class="p">}</span>560 561<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">&#39;real_person:actor&#39;</span><span class="p">,</span> <span class="n">ns</span><span class="p">):</span>562    <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">&#39;real_person:name&#39;</span><span class="p">,</span> <span class="n">ns</span><span class="p">)</span>563    <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>564    <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">&#39;role:character&#39;</span><span class="p">,</span> <span class="n">ns</span><span class="p">):</span>565        <span class="nb">print</span><span class="p">(</span><span class="s1">&#39; |--&gt;&#39;</span><span class="p">,</span> <span class="n">char</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>566</pre></div>567</div>568<p>These two approaches both output:</p>569<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">John</span> <span class="n">Cleese</span>570 <span class="o">|--&gt;</span> <span class="n">Lancelot</span>571 <span class="o">|--&gt;</span> <span class="n">Archie</span> <span class="n">Leach</span>572<span class="n">Eric</span> <span class="n">Idle</span>573 <span class="o">|--&gt;</span> <span class="n">Sir</span> <span class="n">Robin</span>574 <span class="o">|--&gt;</span> <span class="n">Gunther</span>575 <span class="o">|--&gt;</span> <span class="n">Commander</span> <span class="n">Clement</span>576</pre></div>577</div>578</section>579</section>580<section id="xpath-support">581<span id="elementtree-xpath"></span><h2>XPath support<a class="headerlink" href="#xpath-support" title="Link to this heading">¶</a></h2>582<p>This module provides limited support for583<a class="reference external" href="https://www.w3.org/TR/xpath">XPath expressions</a> for locating elements in a584tree.  The goal is to support a small subset of the abbreviated syntax; a full585XPath engine is outside the scope of the module.</p>586<section id="example">587<h3>Example<a class="headerlink" href="#example" title="Link to this heading">¶</a></h3>588<p>Here’s an example that demonstrates some of the XPath capabilities of the589module.  We’ll be using the <code class="docutils literal notranslate"><span class="pre">countrydata</span></code> XML document from the590<a class="reference internal" href="#elementtree-parsing-xml"><span class="std std-ref">Parsing XML</span></a> section:</p>591<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">xml.etree.ElementTree</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">ET</span>592 593<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>594 595<span class="c1"># Top-level elements</span>596<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">&quot;.&quot;</span><span class="p">)</span>597 598<span class="c1"># All &#39;neighbor&#39; grand-children of &#39;country&#39; children of the top-level</span>599<span class="c1"># elements</span>600<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">&quot;./country/neighbor&quot;</span><span class="p">)</span>601 602<span class="c1"># Nodes with name=&#39;Singapore&#39; that have a &#39;year&#39; child</span>603<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">&quot;.//year/..[@name=&#39;Singapore&#39;]&quot;</span><span class="p">)</span>604 605<span class="c1"># &#39;year&#39; nodes that are children of nodes with name=&#39;Singapore&#39;</span>606<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">&quot;.//*[@name=&#39;Singapore&#39;]/year&quot;</span><span class="p">)</span>607 608<span class="c1"># All &#39;neighbor&#39; nodes that are the second child of their parent</span>609<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">&quot;.//neighbor[2]&quot;</span><span class="p">)</span>610</pre></div>611</div>612<p>For XML with namespaces, use the usual qualified <code class="docutils literal notranslate"><span class="pre">{namespace}tag</span></code> notation:</p>613<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># All dublin-core &quot;title&quot; tags in the document</span>614<span class="n">root</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s2">&quot;.//{http://purl.org/dc/elements/1.1/}title&quot;</span><span class="p">)</span>615</pre></div>616</div>617</section>618<section id="supported-xpath-syntax">619<h3>Supported XPath syntax<a class="headerlink" href="#supported-xpath-syntax" title="Link to this heading">¶</a></h3>620<table class="docutils align-default">621<thead>622<tr class="row-odd"><th class="head"><p>Syntax</p></th>623<th class="head"><p>Meaning</p></th>624</tr>625</thead>626<tbody>627<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">tag</span></code></p></td>628<td><p>Selects all child elements with the given tag.629For example, <code class="docutils literal notranslate"><span class="pre">spam</span></code> selects all child elements630named <code class="docutils literal notranslate"><span class="pre">spam</span></code>, and <code class="docutils literal notranslate"><span class="pre">spam/egg</span></code> selects all631grandchildren named <code class="docutils literal notranslate"><span class="pre">egg</span></code> in all children named632<code class="docutils literal notranslate"><span class="pre">spam</span></code>.  <code class="docutils literal notranslate"><span class="pre">{namespace}*</span></code> selects all tags in the633given namespace, <code class="docutils literal notranslate"><span class="pre">{*}spam</span></code> selects tags named634<code class="docutils literal notranslate"><span class="pre">spam</span></code> in any (or no) namespace, and <code class="docutils literal notranslate"><span class="pre">{}*</span></code>635only selects tags that are not in a namespace.</p>636<div class="versionchanged">637<p><span class="versionmodified changed">Changed in version 3.8: </span>Support for star-wildcards was added.</p>638</div>639</td>640</tr>641<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">*</span></code></p></td>642<td><p>Selects all child elements, including comments and643processing instructions.  For example, <code class="docutils literal notranslate"><span class="pre">*/egg</span></code>644selects all grandchildren named <code class="docutils literal notranslate"><span class="pre">egg</span></code>.</p></td>645</tr>646<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">.</span></code></p></td>647<td><p>Selects the current node.  This is mostly useful648at the beginning of the path, to indicate that it’s649a relative path.</p></td>650</tr>651<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">//</span></code></p></td>652<td><p>Selects all subelements, on all levels beneath the653current  element.  For example, <code class="docutils literal notranslate"><span class="pre">.//egg</span></code> selects654all <code class="docutils literal notranslate"><span class="pre">egg</span></code> elements in the entire tree.</p></td>655</tr>656<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">..</span></code></p></td>657<td><p>Selects the parent element.  Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if the658path attempts to reach the ancestors of the start659element (the element <code class="docutils literal notranslate"><span class="pre">find</span></code> was called on).</p></td>660</tr>661<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[&#64;attrib]</span></code></p></td>662<td><p>Selects all elements that have the given attribute.</p></td>663</tr>664<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[&#64;attrib='value']</span></code></p></td>665<td><p>Selects all elements for which the given attribute666has the given value.  The value cannot contain667quotes.</p></td>668</tr>669<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[&#64;attrib!='value']</span></code></p></td>670<td><p>Selects all elements for which the given attribute671does not have the given value. The value cannot672contain quotes.</p>673<div class="versionadded">674<p><span class="versionmodified added">Added in version 3.10.</span></p>675</div>676</td>677</tr>678<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[tag]</span></code></p></td>679<td><p>Selects all elements that have a child named680<code class="docutils literal notranslate"><span class="pre">tag</span></code>.  Only immediate children are supported.</p></td>681</tr>682<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[.='text']</span></code></p></td>683<td><p>Selects all elements whose complete text content,684including descendants, equals the given <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p>685<div class="versionadded">686<p><span class="versionmodified added">Added in version 3.7.</span></p>687</div>688</td>689</tr>690<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[.!='text']</span></code></p></td>691<td><p>Selects all elements whose complete text content,692including descendants, does not equal the given693<code class="docutils literal notranslate"><span class="pre">text</span></code>.</p>694<div class="versionadded">695<p><span class="versionmodified added">Added in version 3.10.</span></p>696</div>697</td>698</tr>699<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[tag='text']</span></code></p></td>700<td><p>Selects all elements that have a child named701<code class="docutils literal notranslate"><span class="pre">tag</span></code> whose complete text content, including702descendants, equals the given <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p></td>703</tr>704<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[tag!='text']</span></code></p></td>705<td><p>Selects all elements that have a child named706<code class="docutils literal notranslate"><span class="pre">tag</span></code> whose complete text content, including707descendants, does not equal the given <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p>708<div class="versionadded">709<p><span class="versionmodified added">Added in version 3.10.</span></p>710</div>711</td>712</tr>713<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[position]</span></code></p></td>714<td><p>Selects all elements that are located at the given715position.  The position can be either an integer716(1 is the first position), the expression <code class="docutils literal notranslate"><span class="pre">last()</span></code>717(for the last position), or a position relative to718the last position (e.g. <code class="docutils literal notranslate"><span class="pre">last()-1</span></code>).</p></td>719</tr>720</tbody>721</table>722<p>Predicates (expressions within square brackets) must be preceded by a tag723name, an asterisk, or another predicate.  <code class="docutils literal notranslate"><span class="pre">position</span></code> predicates must be724preceded by a tag name.</p>725</section>726</section>727<section id="reference">728<h2>Reference<a class="headerlink" href="#reference" title="Link to this heading">¶</a></h2>729<section id="functions">730<span id="elementtree-functions"></span><h3>Functions<a class="headerlink" href="#functions" title="Link to this heading">¶</a></h3>731<dl class="py function">732<dt class="sig sig-object py" id="xml.etree.ElementTree.canonicalize">733<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">canonicalize</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">xml_data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">from_file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">options</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.canonicalize" title="Link to this definition">¶</a></dt>734<dd><p><a class="reference external" href="https://www.w3.org/TR/xml-c14n2/">C14N 2.0</a> transformation function.</p>735<p>Canonicalization is a way to normalise XML output in a way that allows736byte-by-byte comparisons and digital signatures.  It reduces the freedom737that XML serializers have and instead generates a more constrained XML738representation.  The main restrictions regard the placement of namespace739declarations, the ordering of attributes, and ignorable whitespace.</p>740<p>This function takes an XML data string (<em>xml_data</em>) or a file path or741file-like object (<em>from_file</em>) as input, converts it to the canonical742form, and writes it out using the <em>out</em> file(-like) object, if provided,743or returns it as a text string if not.  The output file receives text,744not bytes.  It should therefore be opened in text mode with <code class="docutils literal notranslate"><span class="pre">utf-8</span></code>745encoding.</p>746<p>Typical uses:</p>747<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">xml_data</span> <span class="o">=</span> <span class="s2">&quot;&lt;root&gt;...&lt;/root&gt;&quot;</span>748<span class="nb">print</span><span class="p">(</span><span class="n">canonicalize</span><span class="p">(</span><span class="n">xml_data</span><span class="p">))</span>749 750<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">&quot;c14n_output.xml&quot;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;utf-8&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">out_file</span><span class="p">:</span>751    <span class="n">canonicalize</span><span class="p">(</span><span class="n">xml_data</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="n">out_file</span><span class="p">)</span>752 753<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">&quot;c14n_output.xml&quot;</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;utf-8&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">out_file</span><span class="p">:</span>754    <span class="n">canonicalize</span><span class="p">(</span><span class="n">from_file</span><span class="o">=</span><span class="s2">&quot;inputfile.xml&quot;</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="n">out_file</span><span class="p">)</span>755</pre></div>756</div>757<p>The configuration <em>options</em> are as follows:</p>758<ul class="simple">759<li><p><em>with_comments</em>: set to true to include comments (default: false)</p></li>760<li><dl class="simple">761<dt><em>strip_text</em>: set to true to strip whitespace before and after text content</dt><dd><p>(default: false)</p>762</dd>763</dl>764</li>765<li><dl class="simple">766<dt><em>rewrite_prefixes</em>: set to true to replace namespace prefixes by “n{number}”</dt><dd><p>(default: false)</p>767</dd>768</dl>769</li>770<li><dl class="simple">771<dt><em>qname_aware_tags</em>: a set of qname aware tag names in which prefixes</dt><dd><p>should be replaced in text content (default: empty)</p>772</dd>773</dl>774</li>775<li><dl class="simple">776<dt><em>qname_aware_attrs</em>: a set of qname aware attribute names in which prefixes</dt><dd><p>should be replaced in text content (default: empty)</p>777</dd>778</dl>779</li>780<li><p><em>exclude_attrs</em>: a set of attribute names that should not be serialised</p></li>781<li><p><em>exclude_tags</em>: a set of tag names that should not be serialised</p></li>782</ul>783<p>In the option list above, “a set” refers to any collection or iterable of784strings, no ordering is expected.</p>785<div class="versionadded">786<p><span class="versionmodified added">Added in version 3.8.</span></p>787</div>788</dd></dl>789 790<dl class="py function">791<dt class="sig sig-object py" id="xml.etree.ElementTree.Comment">792<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">Comment</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">text</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Comment" title="Link to this definition">¶</a></dt>793<dd><p>Comment element factory.  This factory function creates a special element794that will be serialized as an XML comment by the standard serializer.  The795comment string can be either a bytestring or a Unicode string.  <em>text</em> is a796string containing the comment string.  Returns an element instance797representing a comment.</p>798<p>Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> skips over comments in the input799instead of creating comment objects for them. An <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> will800only contain comment nodes if they have been inserted into to801the tree using one of the <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> methods.</p>802</dd></dl>803 804<dl class="py function">805<dt class="sig sig-object py" id="xml.etree.ElementTree.dump">806<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">dump</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">elem</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.dump" title="Link to this definition">¶</a></dt>807<dd><p>Writes an element tree or element structure to sys.stdout.  This function808should be used for debugging only.</p>809<p>The exact output format is implementation dependent.  In this version, it’s810written as an ordinary XML file.</p>811<p><em>elem</em> is an element tree or an individual element.</p>812<div class="versionchanged">813<p><span class="versionmodified changed">Changed in version 3.8: </span>The <code class="xref py py-func docutils literal notranslate"><span class="pre">dump()</span></code> function now preserves the attribute order specified814by the user.</p>815</div>816</dd></dl>817 818<dl class="py function">819<dt class="sig sig-object py" id="xml.etree.ElementTree.fromstring">820<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">fromstring</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">text</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.fromstring" title="Link to this definition">¶</a></dt>821<dd><p>Parses an XML section from a string constant.  Same as <a class="reference internal" href="#xml.etree.ElementTree.XML" title="xml.etree.ElementTree.XML"><code class="xref py py-func docutils literal notranslate"><span class="pre">XML()</span></code></a>.  <em>text</em>822is a string containing XML data.  <em>parser</em> is an optional parser instance.823If not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.824Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.</p>825</dd></dl>826 827<dl class="py function">828<dt class="sig sig-object py" id="xml.etree.ElementTree.fromstringlist">829<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">fromstringlist</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sequence</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.fromstringlist" title="Link to this definition">¶</a></dt>830<dd><p>Parses an XML document from a sequence of string fragments.  <em>sequence</em> is a831list or other sequence containing XML data fragments.  <em>parser</em> is an832optional parser instance.  If not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a>833parser is used.  Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.</p>834<div class="versionadded">835<p><span class="versionmodified added">Added in version 3.2.</span></p>836</div>837</dd></dl>838 839<dl class="py function">840<dt class="sig sig-object py" id="xml.etree.ElementTree.indent">841<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">indent</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tree</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">space</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'</span>&#160; <span class="pre">'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.indent" title="Link to this definition">¶</a></dt>842<dd><p>Appends whitespace to the subtree to indent the tree visually.843This can be used to generate pretty-printed XML output.844<em>tree</em> can be an Element or ElementTree.  <em>space</em> is the whitespace845string that will be inserted for each indentation level, two space846characters by default.  For indenting partial subtrees inside of an847already indented tree, pass the initial indentation level as <em>level</em>.</p>848<div class="versionadded">849<p><span class="versionmodified added">Added in version 3.9.</span></p>850</div>851</dd></dl>852 853<dl class="py function">854<dt class="sig sig-object py" id="xml.etree.ElementTree.iselement">855<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">iselement</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">element</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.iselement" title="Link to this definition">¶</a></dt>856<dd><p>Check if an object appears to be a valid element object.  <em>element</em> is an857element instance.  Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if this is an element object.</p>858</dd></dl>859 860<dl class="py function">861<dt class="sig sig-object py" id="xml.etree.ElementTree.iterparse">862<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">iterparse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">source</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">events</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.iterparse" title="Link to this definition">¶</a></dt>863<dd><p>Parses an XML section into an element tree incrementally, and reports what’s864going on to the user.  <em>source</em> is a filename or <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>865containing XML data.  <em>events</em> is a sequence of events to report back.  The866supported events are the strings <code class="docutils literal notranslate"><span class="pre">&quot;start&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;end&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;comment&quot;</span></code>,867<code class="docutils literal notranslate"><span class="pre">&quot;pi&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;start-ns&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;end-ns&quot;</span></code>868(the “ns” events are used to get detailed namespace869information).  If <em>events</em> is omitted, only <code class="docutils literal notranslate"><span class="pre">&quot;end&quot;</span></code> events are reported.870<em>parser</em> is an optional parser instance.  If not given, the standard871<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.  <em>parser</em> must be a subclass of872<code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code> and can only use the default <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> as a873target. Returns an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> providing <code class="docutils literal notranslate"><span class="pre">(event,</span> <span class="pre">elem)</span></code> pairs;874it has a <code class="docutils literal notranslate"><span class="pre">root</span></code> attribute that references the root element of the875resulting XML tree once <em>source</em> is fully read.876The iterator has the <code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code> method that closes the internal877file object if <em>source</em> is a filename.</p>878<p>Note that while <code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code> builds the tree incrementally, it issues879blocking reads on <em>source</em> (or the file it names).  As such, it’s unsuitable880for applications where blocking reads can’t be made.  For fully non-blocking881parsing, see <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a>.</p>882<div class="admonition note">883<p class="admonition-title">Note</p>884<p><code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code> only guarantees that it has seen the “&gt;” character of a885starting tag when it emits a “start” event, so the attributes are defined,886but the contents of the text and tail attributes are undefined at that887point.  The same applies to the element children; they may or may not be888present.</p>889<p>If you need a fully populated element, look for “end” events instead.</p>890</div>891<div class="deprecated">892<p><span class="versionmodified deprecated">Deprecated since version 3.4: </span>The <em>parser</em> argument.</p>893</div>894<div class="versionchanged">895<p><span class="versionmodified changed">Changed in version 3.8: </span>The <code class="docutils literal notranslate"><span class="pre">comment</span></code> and <code class="docutils literal notranslate"><span class="pre">pi</span></code> events were added.</p>896</div>897<div class="versionchanged">898<p><span class="versionmodified changed">Changed in version 3.13: </span>Added the <code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code> method.</p>899</div>900<div class="versionchanged">901<p><span class="versionmodified changed">Changed in version 3.15: </span>A <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> is now emitted if the iterator opened a file902and is not explicitly closed.</p>903</div>904</dd></dl>905 906<dl class="py function">907<dt class="sig sig-object py" id="xml.etree.ElementTree.parse">908<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">source</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.parse" title="Link to this definition">¶</a></dt>909<dd><p>Parses an XML section into an element tree.  <em>source</em> is a filename or file910object containing XML data.  <em>parser</em> is an optional parser instance.  If911not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.  Returns an912<a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> instance.</p>913</dd></dl>914 915<dl class="py function">916<dt class="sig sig-object py" id="xml.etree.ElementTree.ProcessingInstruction">917<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">ProcessingInstruction</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">target</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">text</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ProcessingInstruction" title="Link to this definition">¶</a></dt>918<dd><p>PI element factory.  This factory function creates a special element that919will be serialized as an XML processing instruction.  <em>target</em> is a string920containing the PI target.  <em>text</em> is a string containing the PI contents, if921given.  Returns an element instance, representing a processing instruction.</p>922<p>Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> skips over processing instructions923in the input instead of creating PI objects for them. An924<a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> will only contain processing instruction nodes if925they have been inserted into to the tree using one of the926<a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> methods.</p>927</dd></dl>928 929<dl class="py function">930<dt class="sig sig-object py" id="xml.etree.ElementTree.register_namespace">931<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">register_namespace</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prefix</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">uri</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.register_namespace" title="Link to this definition">¶</a></dt>932<dd><p>Registers a namespace prefix.  The registry is global, and any existing933mapping for either the given prefix or the namespace URI will be removed.934<em>prefix</em> is a namespace prefix.  <em>uri</em> is a namespace uri.  Tags and935attributes in this namespace will be serialized with the given prefix, if at936all possible.</p>937<div class="versionadded">938<p><span class="versionmodified added">Added in version 3.2.</span></p>939</div>940</dd></dl>941 942<dl class="py function">943<dt class="sig sig-object py" id="xml.etree.ElementTree.SubElement">944<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">SubElement</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">parent</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tag</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attrib</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">{}</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">extra</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.SubElement" title="Link to this definition">¶</a></dt>945<dd><p>Subelement factory.  This function creates an element instance, and appends946it to an existing element.</p>947<p>The element name, attribute names, and attribute values can be either948bytestrings or Unicode strings.  <em>parent</em> is the parent element.  <em>tag</em> is949the subelement name.  <em>attrib</em> is an optional dictionary, containing element950attributes.  <em>extra</em> contains additional attributes, given as keyword951arguments.  Returns an element instance.</p>952<div class="versionchanged">953<p><span class="versionmodified changed">Changed in version 3.15.0a6 (unreleased): </span><em>attrib</em> can now be a <a class="reference internal" href="stdtypes.html#frozendict" title="frozendict"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a>.</p>954</div>955</dd></dl>956 957<dl class="py function">958<dt class="sig sig-object py" id="xml.etree.ElementTree.tostring">959<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">tostring</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">element</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'us-ascii'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">method</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'xml'</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">xml_declaration</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default_namespace</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">short_empty_elements</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.tostring" title="Link to this definition">¶</a></dt>960<dd><p>Generates a string representation of an XML element, including all961subelements.  <em>element</em> is an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.  <em>encoding</em> <a class="footnote-reference brackets" href="#id9" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> is962the output encoding (default is US-ASCII).  Use <code class="docutils literal notranslate"><span class="pre">encoding=&quot;unicode&quot;</span></code> to963generate a Unicode string (otherwise, a bytestring is generated).  <em>method</em>964is either <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;html&quot;</span></code> or <code class="docutils literal notranslate"><span class="pre">&quot;text&quot;</span></code> (default is <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>).965<em>xml_declaration</em>, <em>default_namespace</em> and <em>short_empty_elements</em> has the same966meaning as in <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a>. Returns an (optionally) encoded string967containing the XML data.</p>968<div class="versionchanged">969<p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>short_empty_elements</em> parameter.</p>970</div>971<div class="versionchanged">972<p><span class="versionmodified changed">Changed in version 3.8: </span>Added the <em>xml_declaration</em> and <em>default_namespace</em> parameters.</p>973</div>974<div class="versionchanged">975<p><span class="versionmodified changed">Changed in version 3.8: </span>The <code class="xref py py-func docutils literal notranslate"><span class="pre">tostring()</span></code> function now preserves the attribute order976specified by the user.</p>977</div>978</dd></dl>979 980<dl class="py function">981<dt class="sig sig-object py" id="xml.etree.ElementTree.tostringlist">982<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">tostringlist</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">element</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'us-ascii'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">method</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'xml'</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">xml_declaration</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default_namespace</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">short_empty_elements</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.tostringlist" title="Link to this definition">¶</a></dt>983<dd><p>Generates a string representation of an XML element, including all984subelements.  <em>element</em> is an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.  <em>encoding</em> <a class="footnote-reference brackets" href="#id9" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> is985the output encoding (default is US-ASCII).  Use <code class="docutils literal notranslate"><span class="pre">encoding=&quot;unicode&quot;</span></code> to986generate a Unicode string (otherwise, a bytestring is generated).  <em>method</em>987is either <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;html&quot;</span></code> or <code class="docutils literal notranslate"><span class="pre">&quot;text&quot;</span></code> (default is <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>).988<em>xml_declaration</em>, <em>default_namespace</em> and <em>short_empty_elements</em> has the same989meaning as in <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a>. Returns a list of (optionally) encoded990strings containing the XML data. It does not guarantee any specific sequence,991except that <code class="docutils literal notranslate"><span class="pre">b&quot;&quot;.join(tostringlist(element))</span> <span class="pre">==</span> <span class="pre">tostring(element)</span></code>.</p>992<div class="versionadded">993<p><span class="versionmodified added">Added in version 3.2.</span></p>994</div>995<div class="versionchanged">996<p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>short_empty_elements</em> parameter.</p>997</div>998<div class="versionchanged">999<p><span class="versionmodified changed">Changed in version 3.8: </span>Added the <em>xml_declaration</em> and <em>default_namespace</em> parameters.</p>1000</div>1001<div class="versionchanged">1002<p><span class="versionmodified changed">Changed in version 3.8: </span>The <code class="xref py py-func docutils literal notranslate"><span class="pre">tostringlist()</span></code> function now preserves the attribute order1003specified by the user.</p>1004</div>1005</dd></dl>1006 1007<dl class="py function">1008<dt class="sig sig-object py" id="xml.etree.ElementTree.XML">1009<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">XML</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">text</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XML" title="Link to this definition">¶</a></dt>1010<dd><p>Parses an XML section from a string constant.  This function can be used to1011embed “XML literals” in Python code.  <em>text</em> is a string containing XML1012data.  <em>parser</em> is an optional parser instance.  If not given, the standard1013<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.  Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.</p>1014</dd></dl>1015 1016<dl class="py function">1017<dt class="sig sig-object py" id="xml.etree.ElementTree.XMLID">1018<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">XMLID</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">text</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLID" title="Link to this definition">¶</a></dt>1019<dd><p>Parses an XML section from a string constant, and also returns a dictionary1020which maps from element id:s to elements.  <em>text</em> is a string containing XML1021data.  <em>parser</em> is an optional parser instance.  If not given, the standard1022<a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.  Returns a tuple containing an1023<a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance and a dictionary.</p>1024</dd></dl>1025 1026</section>1027</section>1028<section id="xinclude-support">1029<span id="elementtree-xinclude"></span><h2>XInclude support<a class="headerlink" href="#xinclude-support" title="Link to this heading">¶</a></h2>1030<p>This module provides limited support for1031<a class="reference external" href="https://www.w3.org/TR/xinclude/">XInclude directives</a>, via the <a class="reference internal" href="#module-xml.etree.ElementInclude" title="xml.etree.ElementInclude"><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementInclude</span></code></a> helper module.  This module can be used to insert subtrees and text strings into element trees, based on information in the tree.</p>1032<section id="id3">1033<h3>Example<a class="headerlink" href="#id3" title="Link to this heading">¶</a></h3>1034<p>Here’s an example that demonstrates use of the XInclude module. To include an XML document in the current document, use the <code class="docutils literal notranslate"><span class="pre">{http://www.w3.org/2001/XInclude}include</span></code> element and set the <strong>parse</strong> attribute to <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>, and use the <strong>href</strong> attribute to specify the document to include.</p>1035<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>1036<span class="nt">&lt;document</span><span class="w"> </span><span class="na">xmlns:xi=</span><span class="s">&quot;http://www.w3.org/2001/XInclude&quot;</span><span class="nt">&gt;</span>1037<span class="w">  </span><span class="nt">&lt;xi:include</span><span class="w"> </span><span class="na">href=</span><span class="s">&quot;source.xml&quot;</span><span class="w"> </span><span class="na">parse=</span><span class="s">&quot;xml&quot;</span><span class="w"> </span><span class="nt">/&gt;</span>1038<span class="nt">&lt;/document&gt;</span>1039</pre></div>1040</div>1041<p>By default, the <strong>href</strong> attribute is treated as a file name. You can use custom loaders to override this behaviour. Also note that the standard helper does not support XPointer syntax.</p>1042<p>To process this file, load it as usual, and pass the root element to the <code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code> module:</p>1043<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">xml.etree</span><span class="w"> </span><span class="kn">import</span> <span class="n">ElementTree</span><span class="p">,</span> <span class="n">ElementInclude</span>1044 1045<span class="n">tree</span> <span class="o">=</span> <span class="n">ElementTree</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">&quot;document.xml&quot;</span><span class="p">)</span>1046<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>1047 1048<span class="n">ElementInclude</span><span class="o">.</span><span class="n">include</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>1049</pre></div>1050</div>1051<p>The ElementInclude module replaces the <code class="docutils literal notranslate"><span class="pre">{http://www.w3.org/2001/XInclude}include</span></code> element with the root element from the <strong>source.xml</strong> document. The result might look something like this:</p>1052<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;document</span><span class="w"> </span><span class="na">xmlns:xi=</span><span class="s">&quot;http://www.w3.org/2001/XInclude&quot;</span><span class="nt">&gt;</span>1053<span class="w">  </span><span class="nt">&lt;para&gt;</span>This<span class="w"> </span>is<span class="w"> </span>a<span class="w"> </span>paragraph.<span class="nt">&lt;/para&gt;</span>1054<span class="nt">&lt;/document&gt;</span>1055</pre></div>1056</div>1057<p>If the <strong>parse</strong> attribute is omitted, it defaults to “xml”. The href attribute is required.</p>1058<p>To include a text document, use the <code class="docutils literal notranslate"><span class="pre">{http://www.w3.org/2001/XInclude}include</span></code> element, and set the <strong>parse</strong> attribute to “text”:</p>1059<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>1060<span class="nt">&lt;document</span><span class="w"> </span><span class="na">xmlns:xi=</span><span class="s">&quot;http://www.w3.org/2001/XInclude&quot;</span><span class="nt">&gt;</span>1061<span class="w">  </span>Copyright<span class="w"> </span>(c)<span class="w"> </span><span class="nt">&lt;xi:include</span><span class="w"> </span><span class="na">href=</span><span class="s">&quot;year.txt&quot;</span><span class="w"> </span><span class="na">parse=</span><span class="s">&quot;text&quot;</span><span class="w"> </span><span class="nt">/&gt;</span>.1062<span class="nt">&lt;/document&gt;</span>1063</pre></div>1064</div>1065<p>The result might look something like:</p>1066<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;document</span><span class="w"> </span><span class="na">xmlns:xi=</span><span class="s">&quot;http://www.w3.org/2001/XInclude&quot;</span><span class="nt">&gt;</span>1067<span class="w">  </span>Copyright<span class="w"> </span>(c)<span class="w"> </span>2003.1068<span class="nt">&lt;/document&gt;</span>1069</pre></div>1070</div>1071</section>1072</section>1073<section id="id4">1074<h2>Reference<a class="headerlink" href="#id4" title="Link to this heading">¶</a></h2>1075<section id="elementinclude-functions">1076<span id="id5"></span><h3>Functions<a class="headerlink" href="#elementinclude-functions" title="Link to this heading">¶</a></h3>1077<dl class="py function" id="module-xml.etree.ElementInclude">1078<dt class="sig sig-object py" id="xml.etree.ElementInclude.default_loader">1079<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementInclude.</span></span><span class="sig-name descname"><span class="pre">default_loader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">href</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parse</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementInclude.default_loader" title="Link to this definition">¶</a></dt>1080<dd><p>Default loader. This default loader reads an included resource from disk.1081<em>href</em> is a URL.  <em>parse</em> is for parse mode either “xml” or “text”.1082<em>encoding</em> is an optional text encoding.  If not given, encoding is <code class="docutils literal notranslate"><span class="pre">utf-8</span></code>.1083Returns the expanded resource.1084If the parse mode is <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>, this is an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.1085If the parse mode is <code class="docutils literal notranslate"><span class="pre">&quot;text&quot;</span></code>, this is a string.1086If the loader fails, it can return <code class="docutils literal notranslate"><span class="pre">None</span></code> or raise an exception.</p>1087</dd></dl>1088 1089<dl class="py function">1090<dt class="sig sig-object py" id="xml.etree.ElementInclude.include">1091<span class="sig-prename descclassname"><span class="pre">xml.etree.ElementInclude.</span></span><span class="sig-name descname"><span class="pre">include</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">elem</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loader</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">base_url</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_depth</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">6</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementInclude.include" title="Link to this definition">¶</a></dt>1092<dd><p>This function expands XInclude directives in-place in tree pointed by <em>elem</em>.1093<em>elem</em> is either the root <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> or an1094<a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> instance to find such element.1095<em>loader</em> is an optional resource loader.  If omitted, it defaults to <a class="reference internal" href="#xml.etree.ElementInclude.default_loader" title="xml.etree.ElementInclude.default_loader"><code class="xref py py-func docutils literal notranslate"><span class="pre">default_loader()</span></code></a>.1096If given, it should be a callable that implements the same interface as1097<code class="xref py py-func docutils literal notranslate"><span class="pre">default_loader()</span></code>.  <em>base_url</em> is base URL of the original file, to resolve1098relative include file references.  <em>max_depth</em> is the maximum number of recursive1099inclusions.  Limited to reduce the risk of malicious content explosion.1100Pass <code class="docutils literal notranslate"><span class="pre">None</span></code> to disable the limitation.</p>1101<div class="versionchanged">1102<p><span class="versionmodified changed">Changed in version 3.9: </span>Added the <em>base_url</em> and <em>max_depth</em> parameters.</p>1103</div>1104</dd></dl>1105 1106</section>1107<section id="element-objects">1108<span id="elementtree-element-objects"></span><h3>Element Objects<a class="headerlink" href="#element-objects" title="Link to this heading">¶</a></h3>1109<dl class="py class">1110<dt class="sig sig-object py" id="xml.etree.ElementTree.Element">1111<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">xml.etree.ElementTree.</span></span><span class="sig-name descname"><span class="pre">Element</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tag</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attrib</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">{}</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">extra</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element" title="Link to this definition">¶</a></dt>1112<dd><p>Element class.  This class defines the Element interface, and provides a1113reference implementation of this interface.</p>1114<p>The element name, attribute names, and attribute values can be either1115bytestrings or Unicode strings.  <em>tag</em> is the element name.  <em>attrib</em> is1116an optional dictionary, containing element attributes.  <em>extra</em> contains1117additional attributes, given as keyword arguments.</p>1118<div class="versionchanged">1119<p><span class="versionmodified changed">Changed in version 3.15.0a6 (unreleased): </span><em>attrib</em> can now be a <a class="reference internal" href="stdtypes.html#frozendict" title="frozendict"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozendict</span></code></a>.</p>1120</div>1121<dl class="py attribute">1122<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.tag">1123<span class="sig-name descname"><span class="pre">tag</span></span><a class="headerlink" href="#xml.etree.ElementTree.Element.tag" title="Link to this definition">¶</a></dt>1124<dd><p>A string identifying what kind of data this element represents (the1125element type, in other words).</p>1126</dd></dl>1127 1128<dl class="py attribute">1129<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.text">1130<span class="sig-name descname"><span class="pre">text</span></span><a class="headerlink" href="#xml.etree.ElementTree.Element.text" title="Link to this definition">¶</a></dt>1131<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.tail">1132<span class="sig-name descname"><span class="pre">tail</span></span><a class="headerlink" href="#xml.etree.ElementTree.Element.tail" title="Link to this definition">¶</a></dt>1133<dd><p>These attributes can be used to hold additional data associated with1134the element.  Their values are usually strings but may be any1135application-specific object.  If the element is created from1136an XML file, the <em>text</em> attribute holds either the text between1137the element’s start tag and its first child or end tag, or <code class="docutils literal notranslate"><span class="pre">None</span></code>, and1138the <em>tail</em> attribute holds either the text between the element’s1139end tag and the next tag, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.  For the XML data</p>1140<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt">&lt;a&gt;&lt;b&gt;</span>1<span class="nt">&lt;c&gt;</span>2<span class="nt">&lt;d/&gt;</span>3<span class="nt">&lt;/c&gt;&lt;/b&gt;</span>4<span class="nt">&lt;/a&gt;</span>1141</pre></div>1142</div>1143<p>the <em>a</em> element has <code class="docutils literal notranslate"><span class="pre">None</span></code> for both <em>text</em> and <em>tail</em> attributes,1144the <em>b</em> element has <em>text</em> <code class="docutils literal notranslate"><span class="pre">&quot;1&quot;</span></code> and <em>tail</em> <code class="docutils literal notranslate"><span class="pre">&quot;4&quot;</span></code>,1145the <em>c</em> element has <em>text</em> <code class="docutils literal notranslate"><span class="pre">&quot;2&quot;</span></code> and <em>tail</em> <code class="docutils literal notranslate"><span class="pre">None</span></code>,1146and the <em>d</em> element has <em>text</em> <code class="docutils literal notranslate"><span class="pre">None</span></code> and <em>tail</em> <code class="docutils literal notranslate"><span class="pre">&quot;3&quot;</span></code>.</p>1147<p>To collect the inner text of an element, see <a class="reference internal" href="#xml.etree.ElementTree.Element.itertext" title="xml.etree.ElementTree.Element.itertext"><code class="xref py py-meth docutils literal notranslate"><span class="pre">itertext()</span></code></a>, for1148example <code class="docutils literal notranslate"><span class="pre">&quot;&quot;.join(element.itertext())</span></code>.</p>1149<p>Applications may store arbitrary objects in these attributes.</p>1150</dd></dl>1151 1152<dl class="py attribute">1153<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.attrib">1154<span class="sig-name descname"><span class="pre">attrib</span></span><a class="headerlink" href="#xml.etree.ElementTree.Element.attrib" title="Link to this definition">¶</a></dt>1155<dd><p>A dictionary containing the element’s attributes.  Note that while the1156<em>attrib</em> value is always a real mutable Python dictionary, an ElementTree1157implementation may choose to use another internal representation, and1158create the dictionary only if someone asks for it.  To take advantage of1159such implementations, use the dictionary methods below whenever possible.</p>1160</dd></dl>1161 1162<p>The following dictionary-like methods work on the element attributes.</p>1163<dl class="py method">1164<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.clear">1165<span class="sig-name descname"><span class="pre">clear</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.clear" title="Link to this definition">¶</a></dt>1166<dd><p>Resets an element.  This function removes all subelements, clears all1167attributes, and sets the text and tail attributes to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>1168</dd></dl>1169 1170<dl class="py method">1171<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.get">1172<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.get" title="Link to this definition">¶</a></dt>1173<dd><p>Gets the element attribute named <em>key</em>.</p>1174<p>Returns the attribute value, or <em>default</em> if the attribute was not found.</p>1175</dd></dl>1176 1177<dl class="py method">1178<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.items">1179<span class="sig-name descname"><span class="pre">items</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.items" title="Link to this definition">¶</a></dt>1180<dd><p>Returns the element attributes as a sequence of (name, value) pairs.  The1181attributes are returned in an arbitrary order.</p>1182</dd></dl>1183 1184<dl class="py method">1185<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.keys">1186<span class="sig-name descname"><span class="pre">keys</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.keys" title="Link to this definition">¶</a></dt>1187<dd><p>Returns the elements attribute names as a list.  The names are returned1188in an arbitrary order.</p>1189</dd></dl>1190 1191<dl class="py method">1192<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.set">1193<span class="sig-name descname"><span class="pre">set</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.set" title="Link to this definition">¶</a></dt>1194<dd><p>Set the attribute <em>key</em> on the element to <em>value</em>.</p>1195</dd></dl>1196 1197<p>The following methods work on the element’s children (subelements).</p>1198<dl class="py method">1199<dt class="sig sig-object py" id="xml.etree.ElementTree.Element.append">1200<span class="sig-name descname"><span class="pre">append</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">subelement</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.append" title="Link to this definition">¶</a></dt>

Showing the first 1,200 of 2010 lines. Download the file for the rest.