Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
關注 1
收藏 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
分支: master
分支列表 標籤
${ item.name }
建立分支 ${ searchTerm }
從 'master'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/xml.etree.elementtree.html

1961 line
198KB
原始文件 永久連結 Blame 歷史記錄 

  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" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <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...." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>xml.etree.ElementTree — The ElementTree XML API &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="xml.dom — The Document Object Model API" href="xml.dom.html" />

  39.     <link rel="prev" title="XML Processing Modules" href="xml.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/xml.etree.elementtree.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <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>

  99. <li><a class="reference internal" href="#tutorial">Tutorial</a><ul>

  100. <li><a class="reference internal" href="#xml-tree-and-elements">XML tree and elements</a></li>

  101. <li><a class="reference internal" href="#parsing-xml">Parsing XML</a></li>

  102. <li><a class="reference internal" href="#pull-api-for-non-blocking-parsing">Pull API for non-blocking parsing</a></li>

  103. <li><a class="reference internal" href="#finding-interesting-elements">Finding interesting elements</a></li>

  104. <li><a class="reference internal" href="#modifying-an-xml-file">Modifying an XML File</a></li>

  105. <li><a class="reference internal" href="#building-xml-documents">Building XML documents</a></li>

  106. <li><a class="reference internal" href="#parsing-xml-with-namespaces">Parsing XML with Namespaces</a></li>

  107. </ul>

  108. </li>

  109. <li><a class="reference internal" href="#xpath-support">XPath support</a><ul>

  110. <li><a class="reference internal" href="#example">Example</a></li>

  111. <li><a class="reference internal" href="#supported-xpath-syntax">Supported XPath syntax</a></li>

  112. </ul>

  113. </li>

  114. <li><a class="reference internal" href="#reference">Reference</a><ul>

  115. <li><a class="reference internal" href="#functions">Functions</a></li>

  116. </ul>

  117. </li>

  118. <li><a class="reference internal" href="#xinclude-support">XInclude support</a><ul>

  119. <li><a class="reference internal" href="#id3">Example</a></li>

  120. </ul>

  121. </li>

  122. <li><a class="reference internal" href="#id4">Reference</a><ul>

  123. <li><a class="reference internal" href="#elementinclude-functions">Functions</a></li>

  124. <li><a class="reference internal" href="#element-objects">Element Objects</a></li>

  125. <li><a class="reference internal" href="#elementtree-objects">ElementTree Objects</a></li>

  126. <li><a class="reference internal" href="#qname-objects">QName Objects</a></li>

  127. <li><a class="reference internal" href="#treebuilder-objects">TreeBuilder Objects</a></li>

  128. <li><a class="reference internal" href="#xmlparser-objects">XMLParser Objects</a></li>

  129. <li><a class="reference internal" href="#xmlpullparser-objects">XMLPullParser Objects</a></li>

  130. <li><a class="reference internal" href="#exceptions">Exceptions</a></li>

  131. </ul>

  132. </li>

  133. </ul>

  134. </li>

  135. </ul>

  136. 

  137.   </div>

  138.   <div>

  139.     <h4>Previous topic</h4>

  140.     <p class="topless"><a href="xml.html"

  141.                           title="previous chapter">XML Processing Modules</a></p>

  142.   </div>

  143.   <div>

  144.     <h4>Next topic</h4>

  145.     <p class="topless"><a href="xml.dom.html"

  146.                           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>

  147.   </div>

  148.   <div role="note" aria-label="source link">

  149.     <h3>This Page</h3>

  150.     <ul class="this-page-menu">

  151.       <li><a href="../bugs.html">Report a Bug</a></li>

  152.       <li>

  153.         <a href="https://github.com/python/cpython/blob/main/Doc/library/xml.etree.elementtree.rst"

  154.             rel="nofollow">Show Source

  155.         </a>

  156.       </li>

  157.     </ul>

  158.   </div>

  159.         </nav>

  160.     </div>

  161. </div>

  162. 

  163.   

  164.     <div class="related" role="navigation" aria-label="related navigation">

  165.       <h3>Navigation</h3>

  166.       <ul>

  167.         <li class="right" style="margin-right: 10px">

  168.           <a href="../genindex.html" title="General Index"

  169.              accesskey="I">index</a></li>

  170.         <li class="right" >

  171.           <a href="../py-modindex.html" title="Python Module Index"

  172.              >modules</a> |</li>

  173.         <li class="right" >

  174.           <a href="xml.dom.html" title="xml.dom — The Document Object Model API"

  175.              accesskey="N">next</a> |</li>

  176.         <li class="right" >

  177.           <a href="xml.html" title="XML Processing Modules"

  178.              accesskey="P">previous</a> |</li>

  179. 

  180.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  181.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  182.           <li class="switchers">

  183.             <div class="language_switcher_placeholder"></div>

  184.             <div class="version_switcher_placeholder"></div>

  185.           </li>

  186.           <li>

  187.               

  188.           </li>

  189.     <li id="cpython-language-and-version">

  190.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  191.     </li>

  192. 

  193.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  194.           <li class="nav-item nav-item-2"><a href="markup.html" accesskey="U">Structured Markup Processing Tools</a> &#187;</li>

  195.         <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>

  196.                 <li class="right">

  197.                     

  198. 

  199.     <div class="inline-search" role="search">

  200.         <form class="inline-search" action="../search.html" method="get">

  201.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  202.           <input type="submit" value="Go" />

  203.         </form>

  204.     </div>

  205.                      |

  206.                 </li>

  207.             <li class="right">

  208. <label class="theme-selector-label">

  209.     Theme

  210.     <select class="theme-selector" oninput="activateTheme(this.value)">

  211.         <option value="auto" selected>Auto</option>

  212.         <option value="light">Light</option>

  213.         <option value="dark">Dark</option>

  214.     </select>

  215. </label> |</li>

  216.             

  217.       </ul>

  218.     </div>    

  219. 

  220.     <div class="document">

  221.       <div class="documentwrapper">

  222.         <div class="bodywrapper">

  223.           <div class="body" role="main">

  224.             

  225.   <section id="module-xml.etree.ElementTree">

  226. <span id="xml-etree-elementtree-the-elementtree-xml-api"></span><h1><a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> — The ElementTree XML API<a class="headerlink" href="#module-xml.etree.ElementTree" title="Link to this heading">¶</a></h1>

  227. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/xml/etree/ElementTree.py">Lib/xml/etree/ElementTree.py</a></p>

  228. <hr class="docutils" />

  229. <p>The <a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> module implements a simple and efficient API

  230. for parsing and creating XML data.</p>

  231. <div class="versionchanged">

  232. <p><span class="versionmodified changed">Changed in version 3.3: </span>This module will use a fast implementation whenever available.</p>

  233. </div>

  234. <div class="deprecated">

  235. <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>

  236. </div>

  237. <div class="admonition warning">

  238. <p class="admonition-title">Warning</p>

  239. <p>The <a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> module is not secure against

  240. maliciously constructed data.  If you need to parse untrusted or

  241. unauthenticated data see <a class="reference internal" href="xml.html#xml-vulnerabilities"><span class="std std-ref">XML vulnerabilities</span></a>.</p>

  242. </div>

  243. <section id="tutorial">

  244. <h2>Tutorial<a class="headerlink" href="#tutorial" title="Link to this heading">¶</a></h2>

  245. <p>This is a short tutorial for using <a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> (<code class="docutils literal notranslate"><span class="pre">ET</span></code> in

  246. short).  The goal is to demonstrate some of the building blocks and basic

  247. concepts of the module.</p>

  248. <section id="xml-tree-and-elements">

  249. <h3>XML tree and elements<a class="headerlink" href="#xml-tree-and-elements" title="Link to this heading">¶</a></h3>

  250. <p>XML is an inherently hierarchical data format, and the most natural way to

  251. represent it is with a tree.  <code class="docutils literal notranslate"><span class="pre">ET</span></code> has two classes for this purpose -

  252. <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> represents the whole XML document as a tree, and

  253. <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> represents a single node in this tree.  Interactions with

  254. the whole document (reading and writing to/from files) are usually done

  255. on the <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> level.  Interactions with a single XML element

  256. and its sub-elements are done on the <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> level.</p>

  257. </section>

  258. <section id="parsing-xml">

  259. <span id="elementtree-parsing-xml"></span><h3>Parsing XML<a class="headerlink" href="#parsing-xml" title="Link to this heading">¶</a></h3>

  260. <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>

  261. <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>

  262. <span class="nt">&lt;data&gt;</span>

  263. <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>

  264. <span class="w">        </span><span class="nt">&lt;rank&gt;</span>1<span class="nt">&lt;/rank&gt;</span>

  265. <span class="w">        </span><span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>

  266. <span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>

  267. <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>

  268. <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>

  269. <span class="w">    </span><span class="nt">&lt;/country&gt;</span>

  270. <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>

  271. <span class="w">        </span><span class="nt">&lt;rank&gt;</span>4<span class="nt">&lt;/rank&gt;</span>

  272. <span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>

  273. <span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>

  274. <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>

  275. <span class="w">    </span><span class="nt">&lt;/country&gt;</span>

  276. <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>

  277. <span class="w">        </span><span class="nt">&lt;rank&gt;</span>68<span class="nt">&lt;/rank&gt;</span>

  278. <span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>

  279. <span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>13600<span class="nt">&lt;/gdppc&gt;</span>

  280. <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>

  281. <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>

  282. <span class="w">    </span><span class="nt">&lt;/country&gt;</span>

  283. <span class="nt">&lt;/data&gt;</span>

  284. </pre></div>

  285. </div>

  286. <p>We can import this data by reading from a file:</p>

  287. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">xml.etree.ElementTree</span> <span class="k">as</span> <span class="nn">ET</span>

  288. <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>

  289. <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>

  290. </pre></div>

  291. </div>

  292. <p>Or directly from a string:</p>

  293. <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>

  294. </pre></div>

  295. </div>

  296. <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>,

  297. which is the root element of the parsed tree.  Other parsing functions may

  298. create an <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a>.  Check the documentation to be sure.</p>

  299. <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>

  300. <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>

  301. <span class="go">&#39;data&#39;</span>

  302. <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">attrib</span>

  303. <span class="go">{}</span>

  304. </pre></div>

  305. </div>

  306. <p>It also has children nodes over which we can iterate:</p>

  307. <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>

  308. <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>

  309. <span class="gp">...</span>

  310. <span class="go">country {&#39;name&#39;: &#39;Liechtenstein&#39;}</span>

  311. <span class="go">country {&#39;name&#39;: &#39;Singapore&#39;}</span>

  312. <span class="go">country {&#39;name&#39;: &#39;Panama&#39;}</span>

  313. </pre></div>

  314. </div>

  315. <p>Children are nested, and we can access specific child nodes by index:</p>

  316. <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>

  317. <span class="go">&#39;2008&#39;</span>

  318. </pre></div>

  319. </div>

  320. <div class="admonition note">

  321. <p class="admonition-title">Note</p>

  322. <p>Not all elements of the XML input will end up as elements of the

  323. parsed tree. Currently, this module skips over any XML comments,

  324. processing instructions, and document type declarations in the

  325. input. Nevertheless, trees built using this module’s API rather

  326. than parsing from XML text can have comments and processing

  327. instructions in them; they will be included when generating XML

  328. output. A document type declaration may be accessed by passing a

  329. custom <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> instance to the <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a>

  330. constructor.</p>

  331. </div>

  332. </section>

  333. <section id="pull-api-for-non-blocking-parsing">

  334. <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>

  335. <p>Most parsing functions provided by this module require the whole document

  336. to be read at once before returning any result.  It is possible to use an

  337. <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> and feed data into it incrementally, but it is a push API that

  338. calls methods on a callback target, which is too low-level and inconvenient for

  339. most needs.  Sometimes what the user really wants is to be able to parse XML

  340. incrementally, without blocking operations, while enjoying the convenience of

  341. fully constructed <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> objects.</p>

  342. <p>The most powerful tool for doing this is <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a>.  It does not

  343. require a blocking read to obtain the XML data, and is instead fed with data

  344. incrementally with <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.feed" title="xml.etree.ElementTree.XMLPullParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLPullParser.feed()</span></code></a> calls.  To get the parsed XML

  345. elements, call <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLPullParser.read_events()</span></code></a>.  Here is an example:</p>

  346. <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>

  347. <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>

  348. <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>

  349. <span class="go">[(&#39;start&#39;, &lt;Element &#39;mytag&#39; at 0x7fa66db2be58&gt;)]</span>

  350. <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>

  351. <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>

  352. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>

  353. <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>

  354. <span class="gp">...</span>

  355. <span class="go">end</span>

  356. <span class="go">mytag text= sometext more text</span>

  357. </pre></div>

  358. </div>

  359. <p>The obvious use case is applications that operate in a non-blocking fashion

  360. where the XML data is being received from a socket or read incrementally from

  361. some storage device.  In such cases, blocking reads are unacceptable.</p>

  362. <p>Because it’s so flexible, <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a> can be inconvenient to use for

  363. simpler use-cases.  If you don’t mind your application blocking on reading XML

  364. data but would still like to have incremental parsing capabilities, take a look

  365. at <a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code></a>.  It can be useful when you’re reading a large XML document

  366. and don’t want to hold it wholly in memory.</p>

  367. <p>Where <em>immediate</em> feedback through events is wanted, calling method

  368. <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;

  369. please make sure to study the related security notes.</p>

  370. </section>

  371. <section id="finding-interesting-elements">

  372. <h3>Finding interesting elements<a class="headerlink" href="#finding-interesting-elements" title="Link to this heading">¶</a></h3>

  373. <p><a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> has some useful methods that help iterate recursively over all

  374. the sub-tree below it (its children, their children, and so on).  For example,

  375. <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>

  376. <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>

  377. <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>

  378. <span class="gp">...</span>

  379. <span class="go">{&#39;name&#39;: &#39;Austria&#39;, &#39;direction&#39;: &#39;E&#39;}</span>

  380. <span class="go">{&#39;name&#39;: &#39;Switzerland&#39;, &#39;direction&#39;: &#39;W&#39;}</span>

  381. <span class="go">{&#39;name&#39;: &#39;Malaysia&#39;, &#39;direction&#39;: &#39;N&#39;}</span>

  382. <span class="go">{&#39;name&#39;: &#39;Costa Rica&#39;, &#39;direction&#39;: &#39;W&#39;}</span>

  383. <span class="go">{&#39;name&#39;: &#39;Colombia&#39;, &#39;direction&#39;: &#39;E&#39;}</span>

  384. </pre></div>

  385. </div>

  386. <p><a class="reference internal" href="#xml.etree.ElementTree.Element.findall" title="xml.etree.ElementTree.Element.findall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.findall()</span></code></a> finds only elements with a tag which are direct

  387. children of the current element.  <a class="reference internal" href="#xml.etree.ElementTree.Element.find" title="xml.etree.ElementTree.Element.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.find()</span></code></a> finds the <em>first</em> child

  388. with a particular tag, and <a class="reference internal" href="#xml.etree.ElementTree.Element.text" title="xml.etree.ElementTree.Element.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Element.text</span></code></a> accesses the element’s text

  389. content.  <a class="reference internal" href="#xml.etree.ElementTree.Element.get" title="xml.etree.ElementTree.Element.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.get()</span></code></a> accesses the element’s attributes:</p>

  390. <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>

  391. <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>

  392. <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>

  393. <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>

  394. <span class="gp">...</span>

  395. <span class="go">Liechtenstein 1</span>

  396. <span class="go">Singapore 4</span>

  397. <span class="go">Panama 68</span>

  398. </pre></div>

  399. </div>

  400. <p>More sophisticated specification of which elements to look for is possible by

  401. using <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">XPath</span></a>.</p>

  402. </section>

  403. <section id="modifying-an-xml-file">

  404. <h3>Modifying an XML File<a class="headerlink" href="#modifying-an-xml-file" title="Link to this heading">¶</a></h3>

  405. <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.

  406. The <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a> method serves this purpose.</p>

  407. <p>Once created, an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> object may be manipulated by directly changing

  408. its fields (such as <a class="reference internal" href="#xml.etree.ElementTree.Element.text" title="xml.etree.ElementTree.Element.text"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Element.text</span></code></a>), adding and modifying attributes

  409. (<a class="reference internal" href="#xml.etree.ElementTree.Element.set" title="xml.etree.ElementTree.Element.set"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.set()</span></code></a> method), as well as adding new children (for example

  410. with <a class="reference internal" href="#xml.etree.ElementTree.Element.append" title="xml.etree.ElementTree.Element.append"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.append()</span></code></a>).</p>

  411. <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>

  412. attribute to the rank element:</p>

  413. <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>

  414. <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>

  415. <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>

  416. <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>

  417. <span class="gp">...</span>

  418. <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>

  419. </pre></div>

  420. </div>

  421. <p>Our XML now looks like this:</p>

  422. <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>

  423. <span class="nt">&lt;data&gt;</span>

  424. <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>

  425. <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>

  426. <span class="w">        </span><span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>

  427. <span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>

  428. <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>

  429. <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>

  430. <span class="w">    </span><span class="nt">&lt;/country&gt;</span>

  431. <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>

  432. <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>

  433. <span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>

  434. <span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>

  435. <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>

  436. <span class="w">    </span><span class="nt">&lt;/country&gt;</span>

  437. <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>

  438. <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>

  439. <span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>

  440. <span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>13600<span class="nt">&lt;/gdppc&gt;</span>

  441. <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>

  442. <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>

  443. <span class="w">    </span><span class="nt">&lt;/country&gt;</span>

  444. <span class="nt">&lt;/data&gt;</span>

  445. </pre></div>

  446. </div>

  447. <p>We can remove elements using <a class="reference internal" href="#xml.etree.ElementTree.Element.remove" title="xml.etree.ElementTree.Element.remove"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.remove()</span></code></a>.  Let’s say we want to

  448. remove all countries with a rank higher than 50:</p>

  449. <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>

  450. <span class="gp">... </span>    <span class="c1"># using root.findall() to avoid removal during traversal</span>

  451. <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>

  452. <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>

  453. <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>

  454. <span class="gp">...</span>

  455. <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>

  456. </pre></div>

  457. </div>

  458. <p>Note that concurrent modification while iterating can lead to problems,

  459. just like when iterating and modifying Python lists or dicts.

  460. Therefore, the example first collects all matching elements with

  461. <code class="docutils literal notranslate"><span class="pre">root.findall()</span></code>, and only then iterates over the list of matches.</p>

  462. <p>Our XML now looks like this:</p>

  463. <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>

  464. <span class="nt">&lt;data&gt;</span>

  465. <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>

  466. <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>

  467. <span class="w">        </span><span class="nt">&lt;year&gt;</span>2008<span class="nt">&lt;/year&gt;</span>

  468. <span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>141100<span class="nt">&lt;/gdppc&gt;</span>

  469. <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>

  470. <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>

  471. <span class="w">    </span><span class="nt">&lt;/country&gt;</span>

  472. <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>

  473. <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>

  474. <span class="w">        </span><span class="nt">&lt;year&gt;</span>2011<span class="nt">&lt;/year&gt;</span>

  475. <span class="w">        </span><span class="nt">&lt;gdppc&gt;</span>59900<span class="nt">&lt;/gdppc&gt;</span>

  476. <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>

  477. <span class="w">    </span><span class="nt">&lt;/country&gt;</span>

  478. <span class="nt">&lt;/data&gt;</span>

  479. </pre></div>

  480. </div>

  481. </section>

  482. <section id="building-xml-documents">

  483. <h3>Building XML documents<a class="headerlink" href="#building-xml-documents" title="Link to this heading">¶</a></h3>

  484. <p>The <a class="reference internal" href="#xml.etree.ElementTree.SubElement" title="xml.etree.ElementTree.SubElement"><code class="xref py py-func docutils literal notranslate"><span class="pre">SubElement()</span></code></a> function also provides a convenient way to create new

  485. sub-elements for a given element:</p>

  486. <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>

  487. <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>

  488. <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>

  489. <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>

  490. <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>

  491. <span class="go">&lt;a&gt;&lt;b /&gt;&lt;c&gt;&lt;d /&gt;&lt;/c&gt;&lt;/a&gt;</span>

  492. </pre></div>

  493. </div>

  494. </section>

  495. <section id="parsing-xml-with-namespaces">

  496. <h3>Parsing XML with Namespaces<a class="headerlink" href="#parsing-xml-with-namespaces" title="Link to this heading">¶</a></h3>

  497. <p>If the XML input has <a class="reference external" href="https://en.wikipedia.org/wiki/XML_namespace">namespaces</a>, tags and attributes

  498. with prefixes in the form <code class="docutils literal notranslate"><span class="pre">prefix:sometag</span></code> get expanded to

  499. <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>.

  500. Also, if there is a <a class="reference external" href="https://www.w3.org/TR/xml-names/#defaulting">default namespace</a>,

  501. that full URI gets prepended to all of the non-prefixed tags.</p>

  502. <p>Here is an XML example that incorporates two namespaces, one with the

  503. prefix “fictional” and the other serving as the default namespace:</p>

  504. <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>

  505. <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>

  506. <span class="w">        </span><span class="na">xmlns=</span><span class="s">&quot;http://people.example.com&quot;</span><span class="nt">&gt;</span>

  507. <span class="w">    </span><span class="nt">&lt;actor&gt;</span>

  508. <span class="w">        </span><span class="nt">&lt;name&gt;</span>John<span class="w"> </span>Cleese<span class="nt">&lt;/name&gt;</span>

  509. <span class="w">        </span><span class="nt">&lt;fictional:character&gt;</span>Lancelot<span class="nt">&lt;/fictional:character&gt;</span>

  510. <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>

  511. <span class="w">    </span><span class="nt">&lt;/actor&gt;</span>

  512. <span class="w">    </span><span class="nt">&lt;actor&gt;</span>

  513. <span class="w">        </span><span class="nt">&lt;name&gt;</span>Eric<span class="w"> </span>Idle<span class="nt">&lt;/name&gt;</span>

  514. <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>

  515. <span class="w">        </span><span class="nt">&lt;fictional:character&gt;</span>Gunther<span class="nt">&lt;/fictional:character&gt;</span>

  516. <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>

  517. <span class="w">    </span><span class="nt">&lt;/actor&gt;</span>

  518. <span class="nt">&lt;/actors&gt;</span>

  519. </pre></div>

  520. </div>

  521. <p>One way to search and explore this XML example is to manually add the

  522. URI to every tag or attribute in the xpath of a

  523. <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>

  524. <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>

  525. <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>

  526.     <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>

  527.     <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>

  528.     <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>

  529.         <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>

  530. </pre></div>

  531. </div>

  532. <p>A better way to search the namespaced XML example is to create a

  533. dictionary with your own prefixes and use those in the search functions:</p>

  534. <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>

  535.       <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>

  536. 

  537. <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>

  538.     <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>

  539.     <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>

  540.     <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>

  541.         <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>

  542. </pre></div>

  543. </div>

  544. <p>These two approaches both output:</p>

  545. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">John</span> <span class="n">Cleese</span>

  546.  <span class="o">|--&gt;</span> <span class="n">Lancelot</span>

  547.  <span class="o">|--&gt;</span> <span class="n">Archie</span> <span class="n">Leach</span>

  548. <span class="n">Eric</span> <span class="n">Idle</span>

  549.  <span class="o">|--&gt;</span> <span class="n">Sir</span> <span class="n">Robin</span>

  550.  <span class="o">|--&gt;</span> <span class="n">Gunther</span>

  551.  <span class="o">|--&gt;</span> <span class="n">Commander</span> <span class="n">Clement</span>

  552. </pre></div>

  553. </div>

  554. </section>

  555. </section>

  556. <section id="xpath-support">

  557. <span id="elementtree-xpath"></span><h2>XPath support<a class="headerlink" href="#xpath-support" title="Link to this heading">¶</a></h2>

  558. <p>This module provides limited support for

  559. <a class="reference external" href="https://www.w3.org/TR/xpath">XPath expressions</a> for locating elements in a

  560. tree.  The goal is to support a small subset of the abbreviated syntax; a full

  561. XPath engine is outside the scope of the module.</p>

  562. <section id="example">

  563. <h3>Example<a class="headerlink" href="#example" title="Link to this heading">¶</a></h3>

  564. <p>Here’s an example that demonstrates some of the XPath capabilities of the

  565. module.  We’ll be using the <code class="docutils literal notranslate"><span class="pre">countrydata</span></code> XML document from the

  566. <a class="reference internal" href="#elementtree-parsing-xml"><span class="std std-ref">Parsing XML</span></a> section:</p>

  567. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">xml.etree.ElementTree</span> <span class="k">as</span> <span class="nn">ET</span>

  568. 

  569. <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>

  570. 

  571. <span class="c1"># Top-level elements</span>

  572. <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>

  573. 

  574. <span class="c1"># All &#39;neighbor&#39; grand-children of &#39;country&#39; children of the top-level</span>

  575. <span class="c1"># elements</span>

  576. <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>

  577. 

  578. <span class="c1"># Nodes with name=&#39;Singapore&#39; that have a &#39;year&#39; child</span>

  579. <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>

  580. 

  581. <span class="c1"># &#39;year&#39; nodes that are children of nodes with name=&#39;Singapore&#39;</span>

  582. <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>

  583. 

  584. <span class="c1"># All &#39;neighbor&#39; nodes that are the second child of their parent</span>

  585. <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>

  586. </pre></div>

  587. </div>

  588. <p>For XML with namespaces, use the usual qualified <code class="docutils literal notranslate"><span class="pre">{namespace}tag</span></code> notation:</p>

  589. <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>

  590. <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>

  591. </pre></div>

  592. </div>

  593. </section>

  594. <section id="supported-xpath-syntax">

  595. <h3>Supported XPath syntax<a class="headerlink" href="#supported-xpath-syntax" title="Link to this heading">¶</a></h3>

  596. <table class="docutils align-default">

  597. <thead>

  598. <tr class="row-odd"><th class="head"><p>Syntax</p></th>

  599. <th class="head"><p>Meaning</p></th>

  600. </tr>

  601. </thead>

  602. <tbody>

  603. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">tag</span></code></p></td>

  604. <td><p>Selects all child elements with the given tag.

  605. For example, <code class="docutils literal notranslate"><span class="pre">spam</span></code> selects all child elements

  606. named <code class="docutils literal notranslate"><span class="pre">spam</span></code>, and <code class="docutils literal notranslate"><span class="pre">spam/egg</span></code> selects all

  607. grandchildren named <code class="docutils literal notranslate"><span class="pre">egg</span></code> in all children named

  608. <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 the

  609. given namespace, <code class="docutils literal notranslate"><span class="pre">{*}spam</span></code> selects tags named

  610. <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>

  611. only selects tags that are not in a namespace.</p>

  612. <div class="versionchanged">

  613. <p><span class="versionmodified changed">Changed in version 3.8: </span>Support for star-wildcards was added.</p>

  614. </div>

  615. </td>

  616. </tr>

  617. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">*</span></code></p></td>

  618. <td><p>Selects all child elements, including comments and

  619. processing instructions.  For example, <code class="docutils literal notranslate"><span class="pre">*/egg</span></code>

  620. selects all grandchildren named <code class="docutils literal notranslate"><span class="pre">egg</span></code>.</p></td>

  621. </tr>

  622. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">.</span></code></p></td>

  623. <td><p>Selects the current node.  This is mostly useful

  624. at the beginning of the path, to indicate that it’s

  625. a relative path.</p></td>

  626. </tr>

  627. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">//</span></code></p></td>

  628. <td><p>Selects all subelements, on all levels beneath the

  629. current  element.  For example, <code class="docutils literal notranslate"><span class="pre">.//egg</span></code> selects

  630. all <code class="docutils literal notranslate"><span class="pre">egg</span></code> elements in the entire tree.</p></td>

  631. </tr>

  632. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">..</span></code></p></td>

  633. <td><p>Selects the parent element.  Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if the

  634. path attempts to reach the ancestors of the start

  635. element (the element <code class="docutils literal notranslate"><span class="pre">find</span></code> was called on).</p></td>

  636. </tr>

  637. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[&#64;attrib]</span></code></p></td>

  638. <td><p>Selects all elements that have the given attribute.</p></td>

  639. </tr>

  640. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[&#64;attrib='value']</span></code></p></td>

  641. <td><p>Selects all elements for which the given attribute

  642. has the given value.  The value cannot contain

  643. quotes.</p></td>

  644. </tr>

  645. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[&#64;attrib!='value']</span></code></p></td>

  646. <td><p>Selects all elements for which the given attribute

  647. does not have the given value. The value cannot

  648. contain quotes.</p>

  649. <div class="versionadded">

  650. <p><span class="versionmodified added">New in version 3.10.</span></p>

  651. </div>

  652. </td>

  653. </tr>

  654. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[tag]</span></code></p></td>

  655. <td><p>Selects all elements that have a child named

  656. <code class="docutils literal notranslate"><span class="pre">tag</span></code>.  Only immediate children are supported.</p></td>

  657. </tr>

  658. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[.='text']</span></code></p></td>

  659. <td><p>Selects all elements whose complete text content,

  660. including descendants, equals the given <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p>

  661. <div class="versionadded">

  662. <p><span class="versionmodified added">New in version 3.7.</span></p>

  663. </div>

  664. </td>

  665. </tr>

  666. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[.!='text']</span></code></p></td>

  667. <td><p>Selects all elements whose complete text content,

  668. including descendants, does not equal the given

  669. <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p>

  670. <div class="versionadded">

  671. <p><span class="versionmodified added">New in version 3.10.</span></p>

  672. </div>

  673. </td>

  674. </tr>

  675. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[tag='text']</span></code></p></td>

  676. <td><p>Selects all elements that have a child named

  677. <code class="docutils literal notranslate"><span class="pre">tag</span></code> whose complete text content, including

  678. descendants, equals the given <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p></td>

  679. </tr>

  680. <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">[tag!='text']</span></code></p></td>

  681. <td><p>Selects all elements that have a child named

  682. <code class="docutils literal notranslate"><span class="pre">tag</span></code> whose complete text content, including

  683. descendants, does not equal the given <code class="docutils literal notranslate"><span class="pre">text</span></code>.</p>

  684. <div class="versionadded">

  685. <p><span class="versionmodified added">New in version 3.10.</span></p>

  686. </div>

  687. </td>

  688. </tr>

  689. <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">[position]</span></code></p></td>

  690. <td><p>Selects all elements that are located at the given

  691. position.  The position can be either an integer

  692. (1 is the first position), the expression <code class="docutils literal notranslate"><span class="pre">last()</span></code>

  693. (for the last position), or a position relative to

  694. the last position (e.g. <code class="docutils literal notranslate"><span class="pre">last()-1</span></code>).</p></td>

  695. </tr>

  696. </tbody>

  697. </table>

  698. <p>Predicates (expressions within square brackets) must be preceded by a tag

  699. name, an asterisk, or another predicate.  <code class="docutils literal notranslate"><span class="pre">position</span></code> predicates must be

  700. preceded by a tag name.</p>

  701. </section>

  702. </section>

  703. <section id="reference">

  704. <h2>Reference<a class="headerlink" href="#reference" title="Link to this heading">¶</a></h2>

  705. <section id="functions">

  706. <span id="elementtree-functions"></span><h3>Functions<a class="headerlink" href="#functions" title="Link to this heading">¶</a></h3>

  707. <dl class="py function">

  708. <dt class="sig sig-object py" id="xml.etree.ElementTree.canonicalize">

  709. <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="o"><span class="pre">*</span></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>

  710. <dd><p><a class="reference external" href="https://www.w3.org/TR/xml-c14n2/">C14N 2.0</a> transformation function.</p>

  711. <p>Canonicalization is a way to normalise XML output in a way that allows

  712. byte-by-byte comparisons and digital signatures.  It reduced the freedom

  713. that XML serializers have and instead generates a more constrained XML

  714. representation.  The main restrictions regard the placement of namespace

  715. declarations, the ordering of attributes, and ignorable whitespace.</p>

  716. <p>This function takes an XML data string (<em>xml_data</em>) or a file path or

  717. file-like object (<em>from_file</em>) as input, converts it to the canonical

  718. form, and writes it out using the <em>out</em> file(-like) object, if provided,

  719. or returns it as a text string if not.  The output file receives text,

  720. not bytes.  It should therefore be opened in text mode with <code class="docutils literal notranslate"><span class="pre">utf-8</span></code>

  721. encoding.</p>

  722. <p>Typical uses:</p>

  723. <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>

  724. <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>

  725. 

  726. <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>

  727.     <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>

  728. 

  729. <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>

  730.     <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>

  731. </pre></div>

  732. </div>

  733. <p>The configuration <em>options</em> are as follows:</p>

  734. <ul class="simple">

  735. <li><p><em>with_comments</em>: set to true to include comments (default: false)</p></li>

  736. <li><dl class="simple">

  737. <dt><em>strip_text</em>: set to true to strip whitespace before and after text content</dt><dd><p>(default: false)</p>

  738. </dd>

  739. </dl>

  740. </li>

  741. <li><dl class="simple">

  742. <dt><em>rewrite_prefixes</em>: set to true to replace namespace prefixes by “n{number}”</dt><dd><p>(default: false)</p>

  743. </dd>

  744. </dl>

  745. </li>

  746. <li><dl class="simple">

  747. <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>

  748. </dd>

  749. </dl>

  750. </li>

  751. <li><dl class="simple">

  752. <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>

  753. </dd>

  754. </dl>

  755. </li>

  756. <li><p><em>exclude_attrs</em>: a set of attribute names that should not be serialised</p></li>

  757. <li><p><em>exclude_tags</em>: a set of tag names that should not be serialised</p></li>

  758. </ul>

  759. <p>In the option list above, “a set” refers to any collection or iterable of

  760. strings, no ordering is expected.</p>

  761. <div class="versionadded">

  762. <p><span class="versionmodified added">New in version 3.8.</span></p>

  763. </div>

  764. </dd></dl>

  765. 

  766. <dl class="py function">

  767. <dt class="sig sig-object py" id="xml.etree.ElementTree.Comment">

  768. <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>

  769. <dd><p>Comment element factory.  This factory function creates a special element

  770. that will be serialized as an XML comment by the standard serializer.  The

  771. comment string can be either a bytestring or a Unicode string.  <em>text</em> is a

  772. string containing the comment string.  Returns an element instance

  773. representing a comment.</p>

  774. <p>Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> skips over comments in the input

  775. instead of creating comment objects for them. An <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> will

  776. only contain comment nodes if they have been inserted into to

  777. the tree using one of the <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> methods.</p>

  778. </dd></dl>

  779. 

  780. <dl class="py function">

  781. <dt class="sig sig-object py" id="xml.etree.ElementTree.dump">

  782. <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>

  783. <dd><p>Writes an element tree or element structure to sys.stdout.  This function

  784. should be used for debugging only.</p>

  785. <p>The exact output format is implementation dependent.  In this version, it’s

  786. written as an ordinary XML file.</p>

  787. <p><em>elem</em> is an element tree or an individual element.</p>

  788. <div class="versionchanged">

  789. <p><span class="versionmodified changed">Changed in version 3.8: </span>The <a class="reference internal" href="#xml.etree.ElementTree.dump" title="xml.etree.ElementTree.dump"><code class="xref py py-func docutils literal notranslate"><span class="pre">dump()</span></code></a> function now preserves the attribute order specified

  790. by the user.</p>

  791. </div>

  792. </dd></dl>

  793. 

  794. <dl class="py function">

  795. <dt class="sig sig-object py" id="xml.etree.ElementTree.fromstring">

  796. <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>

  797. <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>

  798. is a string containing XML data.  <em>parser</em> is an optional parser instance.

  799. If not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.

  800. 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>

  801. </dd></dl>

  802. 

  803. <dl class="py function">

  804. <dt class="sig sig-object py" id="xml.etree.ElementTree.fromstringlist">

  805. <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>

  806. <dd><p>Parses an XML document from a sequence of string fragments.  <em>sequence</em> is a

  807. list or other sequence containing XML data fragments.  <em>parser</em> is an

  808. optional parser instance.  If not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a>

  809. 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>

  810. <div class="versionadded">

  811. <p><span class="versionmodified added">New in version 3.2.</span></p>

  812. </div>

  813. </dd></dl>

  814. 

  815. <dl class="py function">

  816. <dt class="sig sig-object py" id="xml.etree.ElementTree.indent">

  817. <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>

  818. <dd><p>Appends whitespace to the subtree to indent the tree visually.

  819. This can be used to generate pretty-printed XML output.

  820. <em>tree</em> can be an Element or ElementTree.  <em>space</em> is the whitespace

  821. string that will be inserted for each indentation level, two space

  822. characters by default.  For indenting partial subtrees inside of an

  823. already indented tree, pass the initial indentation level as <em>level</em>.</p>

  824. <div class="versionadded">

  825. <p><span class="versionmodified added">New in version 3.9.</span></p>

  826. </div>

  827. </dd></dl>

  828. 

  829. <dl class="py function">

  830. <dt class="sig sig-object py" id="xml.etree.ElementTree.iselement">

  831. <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>

  832. <dd><p>Check if an object appears to be a valid element object.  <em>element</em> is an

  833. element instance.  Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if this is an element object.</p>

  834. </dd></dl>

  835. 

  836. <dl class="py function">

  837. <dt class="sig sig-object py" id="xml.etree.ElementTree.iterparse">

  838. <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>

  839. <dd><p>Parses an XML section into an element tree incrementally, and reports what’s

  840. going on to the user.  <em>source</em> is a filename or <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>

  841. containing XML data.  <em>events</em> is a sequence of events to report back.  The

  842. supported 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>,

  843. <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>

  844. (the “ns” events are used to get detailed namespace

  845. information).  If <em>events</em> is omitted, only <code class="docutils literal notranslate"><span class="pre">&quot;end&quot;</span></code> events are reported.

  846. <em>parser</em> is an optional parser instance.  If not given, the standard

  847. <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.  <em>parser</em> must be a subclass of

  848. <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> and can only use the default <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> as a

  849. target. Returns an <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> providing <code class="docutils literal notranslate"><span class="pre">(event,</span> <span class="pre">elem)</span></code> pairs;

  850. it has a <code class="docutils literal notranslate"><span class="pre">root</span></code> attribute that references the root element of the

  851. resulting XML tree once <em>source</em> is fully read.</p>

  852. <p>Note that while <a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code></a> builds the tree incrementally, it issues

  853. blocking reads on <em>source</em> (or the file it names).  As such, it’s unsuitable

  854. for applications where blocking reads can’t be made.  For fully non-blocking

  855. parsing, see <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a>.</p>

  856. <div class="admonition note">

  857. <p class="admonition-title">Note</p>

  858. <p><a class="reference internal" href="#xml.etree.ElementTree.iterparse" title="xml.etree.ElementTree.iterparse"><code class="xref py py-func docutils literal notranslate"><span class="pre">iterparse()</span></code></a> only guarantees that it has seen the “&gt;” character of a

  859. starting tag when it emits a “start” event, so the attributes are defined,

  860. but the contents of the text and tail attributes are undefined at that

  861. point.  The same applies to the element children; they may or may not be

  862. present.</p>

  863. <p>If you need a fully populated element, look for “end” events instead.</p>

  864. </div>

  865. <div class="deprecated">

  866. <p><span class="versionmodified deprecated">Deprecated since version 3.4: </span>The <em>parser</em> argument.</p>

  867. </div>

  868. <div class="versionchanged">

  869. <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>

  870. </div>

  871. </dd></dl>

  872. 

  873. <dl class="py function">

  874. <dt class="sig sig-object py" id="xml.etree.ElementTree.parse">

  875. <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>

  876. <dd><p>Parses an XML section into an element tree.  <em>source</em> is a filename or file

  877. object containing XML data.  <em>parser</em> is an optional parser instance.  If

  878. not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.  Returns an

  879. <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>

  880. </dd></dl>

  881. 

  882. <dl class="py function">

  883. <dt class="sig sig-object py" id="xml.etree.ElementTree.ProcessingInstruction">

  884. <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>

  885. <dd><p>PI element factory.  This factory function creates a special element that

  886. will be serialized as an XML processing instruction.  <em>target</em> is a string

  887. containing the PI target.  <em>text</em> is a string containing the PI contents, if

  888. given.  Returns an element instance, representing a processing instruction.</p>

  889. <p>Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> skips over processing instructions

  890. in the input instead of creating PI objects for them. An

  891. <a class="reference internal" href="#xml.etree.ElementTree.ElementTree" title="xml.etree.ElementTree.ElementTree"><code class="xref py py-class docutils literal notranslate"><span class="pre">ElementTree</span></code></a> will only contain processing instruction nodes if

  892. they have been inserted into to the tree using one of the

  893. <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>

  894. </dd></dl>

  895. 

  896. <dl class="py function">

  897. <dt class="sig sig-object py" id="xml.etree.ElementTree.register_namespace">

  898. <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>

  899. <dd><p>Registers a namespace prefix.  The registry is global, and any existing

  900. mapping for either the given prefix or the namespace URI will be removed.

  901. <em>prefix</em> is a namespace prefix.  <em>uri</em> is a namespace uri.  Tags and

  902. attributes in this namespace will be serialized with the given prefix, if at

  903. all possible.</p>

  904. <div class="versionadded">

  905. <p><span class="versionmodified added">New in version 3.2.</span></p>

  906. </div>

  907. </dd></dl>

  908. 

  909. <dl class="py function">

  910. <dt class="sig sig-object py" id="xml.etree.ElementTree.SubElement">

  911. <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>

  912. <dd><p>Subelement factory.  This function creates an element instance, and appends

  913. it to an existing element.</p>

  914. <p>The element name, attribute names, and attribute values can be either

  915. bytestrings or Unicode strings.  <em>parent</em> is the parent element.  <em>tag</em> is

  916. the subelement name.  <em>attrib</em> is an optional dictionary, containing element

  917. attributes.  <em>extra</em> contains additional attributes, given as keyword

  918. arguments.  Returns an element instance.</p>

  919. </dd></dl>

  920. 

  921. <dl class="py function">

  922. <dt class="sig sig-object py" id="xml.etree.ElementTree.tostring">

  923. <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="o"><span class="pre">*</span></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>

  924. <dd><p>Generates a string representation of an XML element, including all

  925. subelements.  <em>element</em> is an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.  <em>encoding</em> <a class="footnote-reference brackets" href="#id9" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> is

  926. the output encoding (default is US-ASCII).  Use <code class="docutils literal notranslate"><span class="pre">encoding=&quot;unicode&quot;</span></code> to

  927. generate a Unicode string (otherwise, a bytestring is generated).  <em>method</em>

  928. is 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>).

  929. <em>xml_declaration</em>, <em>default_namespace</em> and <em>short_empty_elements</em> has the same

  930. meaning as in <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a>. Returns an (optionally) encoded string

  931. containing the XML data.</p>

  932. <div class="versionchanged">

  933. <p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>short_empty_elements</em> parameter.</p>

  934. </div>

  935. <div class="versionchanged">

  936. <p><span class="versionmodified changed">Changed in version 3.8: </span>Added the <em>xml_declaration</em> and <em>default_namespace</em> parameters.</p>

  937. </div>

  938. <div class="versionchanged">

  939. <p><span class="versionmodified changed">Changed in version 3.8: </span>The <a class="reference internal" href="#xml.etree.ElementTree.tostring" title="xml.etree.ElementTree.tostring"><code class="xref py py-func docutils literal notranslate"><span class="pre">tostring()</span></code></a> function now preserves the attribute order

  940. specified by the user.</p>

  941. </div>

  942. </dd></dl>

  943. 

  944. <dl class="py function">

  945. <dt class="sig sig-object py" id="xml.etree.ElementTree.tostringlist">

  946. <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="o"><span class="pre">*</span></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>

  947. <dd><p>Generates a string representation of an XML element, including all

  948. subelements.  <em>element</em> is an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.  <em>encoding</em> <a class="footnote-reference brackets" href="#id9" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> is

  949. the output encoding (default is US-ASCII).  Use <code class="docutils literal notranslate"><span class="pre">encoding=&quot;unicode&quot;</span></code> to

  950. generate a Unicode string (otherwise, a bytestring is generated).  <em>method</em>

  951. is 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>).

  952. <em>xml_declaration</em>, <em>default_namespace</em> and <em>short_empty_elements</em> has the same

  953. meaning as in <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ElementTree.write()</span></code></a>. Returns a list of (optionally) encoded

  954. strings containing the XML data. It does not guarantee any specific sequence,

  955. except 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>

  956. <div class="versionadded">

  957. <p><span class="versionmodified added">New in version 3.2.</span></p>

  958. </div>

  959. <div class="versionchanged">

  960. <p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>short_empty_elements</em> parameter.</p>

  961. </div>

  962. <div class="versionchanged">

  963. <p><span class="versionmodified changed">Changed in version 3.8: </span>Added the <em>xml_declaration</em> and <em>default_namespace</em> parameters.</p>

  964. </div>

  965. <div class="versionchanged">

  966. <p><span class="versionmodified changed">Changed in version 3.8: </span>The <a class="reference internal" href="#xml.etree.ElementTree.tostringlist" title="xml.etree.ElementTree.tostringlist"><code class="xref py py-func docutils literal notranslate"><span class="pre">tostringlist()</span></code></a> function now preserves the attribute order

  967. specified by the user.</p>

  968. </div>

  969. </dd></dl>

  970. 

  971. <dl class="py function">

  972. <dt class="sig sig-object py" id="xml.etree.ElementTree.XML">

  973. <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>

  974. <dd><p>Parses an XML section from a string constant.  This function can be used to

  975. embed “XML literals” in Python code.  <em>text</em> is a string containing XML

  976. data.  <em>parser</em> is an optional parser instance.  If not given, the standard

  977. <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>

  978. </dd></dl>

  979. 

  980. <dl class="py function">

  981. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLID">

  982. <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>

  983. <dd><p>Parses an XML section from a string constant, and also returns a dictionary

  984. which maps from element id:s to elements.  <em>text</em> is a string containing XML

  985. data.  <em>parser</em> is an optional parser instance.  If not given, the standard

  986. <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.  Returns a tuple containing an

  987. <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>

  988. </dd></dl>

  989. 

  990. </section>

  991. </section>

  992. <section id="xinclude-support">

  993. <span id="elementtree-xinclude"></span><h2>XInclude support<a class="headerlink" href="#xinclude-support" title="Link to this heading">¶</a></h2>

  994. <p>This module provides limited support for

  995. <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>

  996. <section id="id3">

  997. <h3>Example<a class="headerlink" href="#id3" title="Link to this heading">¶</a></h3>

  998. <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>

  999. <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>

  1000. <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>

  1001. <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>

  1002. <span class="nt">&lt;/document&gt;</span>

  1003. </pre></div>

  1004. </div>

  1005. <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>

  1006. <p>To process this file, load it as usual, and pass the root element to the <a class="reference internal" href="#module-xml.etree.ElementTree" title="xml.etree.ElementTree: Implementation of the ElementTree API."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.etree.ElementTree</span></code></a> module:</p>

  1007. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">xml.etree</span> <span class="kn">import</span> <span class="n">ElementTree</span><span class="p">,</span> <span class="n">ElementInclude</span>

  1008. 

  1009. <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>

  1010. <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>

  1011. 

  1012. <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>

  1013. </pre></div>

  1014. </div>

  1015. <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>

  1016. <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>

  1017. <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>

  1018. <span class="nt">&lt;/document&gt;</span>

  1019. </pre></div>

  1020. </div>

  1021. <p>If the <strong>parse</strong> attribute is omitted, it defaults to “xml”. The href attribute is required.</p>

  1022. <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>

  1023. <div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>

  1024. <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>

  1025. <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>.

  1026. <span class="nt">&lt;/document&gt;</span>

  1027. </pre></div>

  1028. </div>

  1029. <p>The result might look something like:</p>

  1030. <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>

  1031. <span class="w">  </span>Copyright<span class="w"> </span>(c)<span class="w"> </span>2003.

  1032. <span class="nt">&lt;/document&gt;</span>

  1033. </pre></div>

  1034. </div>

  1035. </section>

  1036. </section>

  1037. <section id="id4">

  1038. <h2>Reference<a class="headerlink" href="#id4" title="Link to this heading">¶</a></h2>

  1039. <section id="elementinclude-functions">

  1040. <span id="id5"></span><h3>Functions<a class="headerlink" href="#elementinclude-functions" title="Link to this heading">¶</a></h3>

  1041. <dl class="py function" id="module-xml.etree.ElementInclude">

  1042. <dt class="sig sig-object py" id="xml.etree.ElementInclude.default_loader">

  1043. <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>

  1044. <dd><p>Default loader. This default loader reads an included resource from disk.  <em>href</em> is a URL.

  1045. <em>parse</em> is for parse mode either “xml” or “text”.  <em>encoding</em>

  1046. is an optional text encoding.  If not given, encoding is <code class="docutils literal notranslate"><span class="pre">utf-8</span></code>.  Returns the

  1047. expanded resource.  If the parse mode is <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>, this is an ElementTree

  1048. instance.  If the parse mode is “text”, this is a Unicode string.  If the

  1049. loader fails, it can return None or raise an exception.</p>

  1050. </dd></dl>

  1051. 

  1052. <dl class="py function">

  1053. <dt class="sig sig-object py" id="xml.etree.ElementInclude.include">

  1054. <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>

  1055. <dd><p>This function expands XInclude directives.  <em>elem</em> is the root element.  <em>loader</em> is

  1056. 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>.

  1057. If given, it should be a callable that implements the same interface as

  1058. <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>.  <em>base_url</em> is base URL of the original file, to resolve

  1059. relative include file references.  <em>max_depth</em> is the maximum number of recursive

  1060. inclusions.  Limited to reduce the risk of malicious content explosion. Pass a

  1061. negative value to disable the limitation.</p>

  1062. <p>Returns the expanded resource.  If the parse mode is

  1063. <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>, this is an ElementTree instance.  If the parse mode is “text”,

  1064. this is a Unicode string.  If the loader fails, it can return None or

  1065. raise an exception.</p>

  1066. <div class="versionchanged">

  1067. <p><span class="versionmodified changed">Changed in version 3.9: </span>Added the <em>base_url</em> and <em>max_depth</em> parameters.</p>

  1068. </div>

  1069. </dd></dl>

  1070. 

  1071. </section>

  1072. <section id="element-objects">

  1073. <span id="elementtree-element-objects"></span><h3>Element Objects<a class="headerlink" href="#element-objects" title="Link to this heading">¶</a></h3>

  1074. <dl class="py class">

  1075. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element">

  1076. <em class="property"><span class="pre">class</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>

  1077. <dd><p>Element class.  This class defines the Element interface, and provides a

  1078. reference implementation of this interface.</p>

  1079. <p>The element name, attribute names, and attribute values can be either

  1080. bytestrings or Unicode strings.  <em>tag</em> is the element name.  <em>attrib</em> is

  1081. an optional dictionary, containing element attributes.  <em>extra</em> contains

  1082. additional attributes, given as keyword arguments.</p>

  1083. <dl class="py attribute">

  1084. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.tag">

  1085. <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>

  1086. <dd><p>A string identifying what kind of data this element represents (the

  1087. element type, in other words).</p>

  1088. </dd></dl>

  1089. 

  1090. <dl class="py attribute">

  1091. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.text">

  1092. <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>

  1093. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.tail">

  1094. <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>

  1095. <dd><p>These attributes can be used to hold additional data associated with

  1096. the element.  Their values are usually strings but may be any

  1097. application-specific object.  If the element is created from

  1098. an XML file, the <em>text</em> attribute holds either the text between

  1099. the element’s start tag and its first child or end tag, or <code class="docutils literal notranslate"><span class="pre">None</span></code>, and

  1100. the <em>tail</em> attribute holds either the text between the element’s

  1101. end tag and the next tag, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.  For the XML data</p>

  1102. <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>

  1103. </pre></div>

  1104. </div>

  1105. <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,

  1106. the <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>,

  1107. the <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>,

  1108. and the <em>d</em> element has <em>text</em> <code class="docutils literal notranslate"><span class="pre">None</span></code> and <em>tail</em> <code class="docutils literal notranslate"><span class="pre">&quot;3&quot;</span></code>.</p>

  1109. <p>To collect the inner text of an element, see <a class="reference internal" href="#xml.etree.ElementTree.Element.itertext" title="xml.etree.ElementTree.Element.itertext"><code class="xref py py-meth docutils literal notranslate"><span class="pre">itertext()</span></code></a>, for

  1110. example <code class="docutils literal notranslate"><span class="pre">&quot;&quot;.join(element.itertext())</span></code>.</p>

  1111. <p>Applications may store arbitrary objects in these attributes.</p>

  1112. </dd></dl>

  1113. 

  1114. <dl class="py attribute">

  1115. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.attrib">

  1116. <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>

  1117. <dd><p>A dictionary containing the element’s attributes.  Note that while the

  1118. <em>attrib</em> value is always a real mutable Python dictionary, an ElementTree

  1119. implementation may choose to use another internal representation, and

  1120. create the dictionary only if someone asks for it.  To take advantage of

  1121. such implementations, use the dictionary methods below whenever possible.</p>

  1122. </dd></dl>

  1123. 

  1124. <p>The following dictionary-like methods work on the element attributes.</p>

  1125. <dl class="py method">

  1126. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.clear">

  1127. <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>

  1128. <dd><p>Resets an element.  This function removes all subelements, clears all

  1129. attributes, and sets the text and tail attributes to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>

  1130. </dd></dl>

  1131. 

  1132. <dl class="py method">

  1133. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.get">

  1134. <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>

  1135. <dd><p>Gets the element attribute named <em>key</em>.</p>

  1136. <p>Returns the attribute value, or <em>default</em> if the attribute was not found.</p>

  1137. </dd></dl>

  1138. 

  1139. <dl class="py method">

  1140. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.items">

  1141. <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>

  1142. <dd><p>Returns the element attributes as a sequence of (name, value) pairs.  The

  1143. attributes are returned in an arbitrary order.</p>

  1144. </dd></dl>

  1145. 

  1146. <dl class="py method">

  1147. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.keys">

  1148. <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>

  1149. <dd><p>Returns the elements attribute names as a list.  The names are returned

  1150. in an arbitrary order.</p>

  1151. </dd></dl>

  1152. 

  1153. <dl class="py method">

  1154. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.set">

  1155. <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>

  1156. <dd><p>Set the attribute <em>key</em> on the element to <em>value</em>.</p>

  1157. </dd></dl>

  1158. 

  1159. <p>The following methods work on the element’s children (subelements).</p>

  1160. <dl class="py method">

  1161. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.append">

  1162. <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>

  1163. <dd><p>Adds the element <em>subelement</em> to the end of this element’s internal list

  1164. of subelements.  Raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <em>subelement</em> is not an

  1165. <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>.</p>

  1166. </dd></dl>

  1167. 

  1168. <dl class="py method">

  1169. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.extend">

  1170. <span class="sig-name descname"><span class="pre">extend</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">subelements</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.extend" title="Link to this definition">¶</a></dt>

  1171. <dd><p>Appends <em>subelements</em> from a sequence object with zero or more elements.

  1172. Raises <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if a subelement is not an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>.</p>

  1173. <div class="versionadded">

  1174. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1175. </div>

  1176. </dd></dl>

  1177. 

  1178. <dl class="py method">

  1179. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.find">

  1180. <span class="sig-name descname"><span class="pre">find</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">match</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespaces</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.find" title="Link to this definition">¶</a></dt>

  1181. <dd><p>Finds the first subelement matching <em>match</em>.  <em>match</em> may be a tag name

  1182. or a <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">path</span></a>.  Returns an element instance

  1183. or <code class="docutils literal notranslate"><span class="pre">None</span></code>.  <em>namespaces</em> is an optional mapping from namespace prefix

  1184. to full name.  Pass <code class="docutils literal notranslate"><span class="pre">''</span></code> as prefix to move all unprefixed tag names

  1185. in the expression into the given namespace.</p>

  1186. </dd></dl>

  1187. 

  1188. <dl class="py method">

  1189. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.findall">

  1190. <span class="sig-name descname"><span class="pre">findall</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">match</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespaces</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.findall" title="Link to this definition">¶</a></dt>

  1191. <dd><p>Finds all matching subelements, by tag name or

  1192. <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">path</span></a>.  Returns a list containing all matching

  1193. elements in document order.  <em>namespaces</em> is an optional mapping from

  1194. namespace prefix to full name.  Pass <code class="docutils literal notranslate"><span class="pre">''</span></code> as prefix to move all

  1195. unprefixed tag names in the expression into the given namespace.</p>

  1196. </dd></dl>

  1197. 

  1198. <dl class="py method">

  1199. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.findtext">

  1200. <span class="sig-name descname"><span class="pre">findtext</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">match</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>, <em class="sig-param"><span class="n"><span class="pre">namespaces</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.findtext" title="Link to this definition">¶</a></dt>

  1201. <dd><p>Finds text for the first subelement matching <em>match</em>.  <em>match</em> may be

  1202. a tag name or a <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">path</span></a>.  Returns the text content

  1203. of the first matching element, or <em>default</em> if no element was found.

  1204. Note that if the matching element has no text content an empty string

  1205. is returned. <em>namespaces</em> is an optional mapping from namespace prefix

  1206. to full name.  Pass <code class="docutils literal notranslate"><span class="pre">''</span></code> as prefix to move all unprefixed tag names

  1207. in the expression into the given namespace.</p>

  1208. </dd></dl>

  1209. 

  1210. <dl class="py method">

  1211. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.insert">

  1212. <span class="sig-name descname"><span class="pre">insert</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">index</span></span></em>, <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.insert" title="Link to this definition">¶</a></dt>

  1213. <dd><p>Inserts <em>subelement</em> at the given position in this element.  Raises

  1214. <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <em>subelement</em> is not an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a>.</p>

  1215. </dd></dl>

  1216. 

  1217. <dl class="py method">

  1218. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.iter">

  1219. <span class="sig-name descname"><span class="pre">iter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tag</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.iter" title="Link to this definition">¶</a></dt>

  1220. <dd><p>Creates a tree <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> with the current element as the root.

  1221. The iterator iterates over this element and all elements below it, in

  1222. document (depth first) order.  If <em>tag</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code> or <code class="docutils literal notranslate"><span class="pre">'*'</span></code>, only

  1223. elements whose tag equals <em>tag</em> are returned from the iterator.  If the

  1224. tree structure is modified during iteration, the result is undefined.</p>

  1225. <div class="versionadded">

  1226. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1227. </div>

  1228. </dd></dl>

  1229. 

  1230. <dl class="py method">

  1231. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.iterfind">

  1232. <span class="sig-name descname"><span class="pre">iterfind</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">match</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespaces</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.iterfind" title="Link to this definition">¶</a></dt>

  1233. <dd><p>Finds all matching subelements, by tag name or

  1234. <a class="reference internal" href="#elementtree-xpath"><span class="std std-ref">path</span></a>.  Returns an iterable yielding all

  1235. matching elements in document order. <em>namespaces</em> is an optional mapping

  1236. from namespace prefix to full name.</p>

  1237. <div class="versionadded">

  1238. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1239. </div>

  1240. </dd></dl>

  1241. 

  1242. <dl class="py method">

  1243. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.itertext">

  1244. <span class="sig-name descname"><span class="pre">itertext</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.itertext" title="Link to this definition">¶</a></dt>

  1245. <dd><p>Creates a text iterator.  The iterator loops over this element and all

  1246. subelements, in document order, and returns all inner text.</p>

  1247. <div class="versionadded">

  1248. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1249. </div>

  1250. </dd></dl>

  1251. 

  1252. <dl class="py method">

  1253. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.makeelement">

  1254. <span class="sig-name descname"><span class="pre">makeelement</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></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.Element.makeelement" title="Link to this definition">¶</a></dt>

  1255. <dd><p>Creates a new element object of the same type as this element.  Do not

  1256. call this method, use the <a class="reference internal" href="#xml.etree.ElementTree.SubElement" title="xml.etree.ElementTree.SubElement"><code class="xref py py-func docutils literal notranslate"><span class="pre">SubElement()</span></code></a> factory function instead.</p>

  1257. </dd></dl>

  1258. 

  1259. <dl class="py method">

  1260. <dt class="sig sig-object py" id="xml.etree.ElementTree.Element.remove">

  1261. <span class="sig-name descname"><span class="pre">remove</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.remove" title="Link to this definition">¶</a></dt>

  1262. <dd><p>Removes <em>subelement</em> from the element.  Unlike the find* methods this

  1263. method compares elements based on the instance identity, not on tag value

  1264. or contents.</p>

  1265. </dd></dl>

  1266. 

  1267. <p><a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> objects also support the following sequence type methods

  1268. for working with subelements: <a class="reference internal" href="../reference/datamodel.html#object.__delitem__" title="object.__delitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__delitem__()</span></code></a>,

  1269. <a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a>,

  1270. <a class="reference internal" href="../reference/datamodel.html#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__len__()</span></code></a>.</p>

  1271. <p>Caution: Elements with no subelements will test as <code class="docutils literal notranslate"><span class="pre">False</span></code>.  Testing the

  1272. truth value of an Element is deprecated and will raise an exception in

  1273. Python 3.14.  Use specific <code class="docutils literal notranslate"><span class="pre">len(elem)</span></code> or <code class="docutils literal notranslate"><span class="pre">elem</span> <span class="pre">is</span> <span class="pre">None</span></code> test instead.:</p>

  1274. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">element</span> <span class="o">=</span> <span class="n">root</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">)</span>

  1275. 

  1276. <span class="k">if</span> <span class="ow">not</span> <span class="n">element</span><span class="p">:</span>  <span class="c1"># careful!</span>

  1277.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;element not found, or element has no subelements&quot;</span><span class="p">)</span>

  1278. 

  1279. <span class="k">if</span> <span class="n">element</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>

  1280.     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;element not found&quot;</span><span class="p">)</span>

  1281. </pre></div>

  1282. </div>

  1283. <div class="versionchanged">

  1284. <p><span class="versionmodified changed">Changed in version 3.12: </span>Testing the truth value of an Element emits <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a>.</p>

  1285. </div>

  1286. <p>Prior to Python 3.8, the serialisation order of the XML attributes of

  1287. elements was artificially made predictable by sorting the attributes by

  1288. their name. Based on the now guaranteed ordering of dicts, this arbitrary

  1289. reordering was removed in Python 3.8 to preserve the order in which

  1290. attributes were originally parsed or created by user code.</p>

  1291. <p>In general, user code should try not to depend on a specific ordering of

  1292. attributes, given that the <a class="reference external" href="https://www.w3.org/TR/xml-infoset/">XML Information Set</a> explicitly excludes the attribute

  1293. order from conveying information. Code should be prepared to deal with

  1294. any ordering on input. In cases where deterministic XML output is required,

  1295. e.g. for cryptographic signing or test data sets, canonical serialisation

  1296. is available with the <a class="reference internal" href="#xml.etree.ElementTree.canonicalize" title="xml.etree.ElementTree.canonicalize"><code class="xref py py-func docutils literal notranslate"><span class="pre">canonicalize()</span></code></a> function.</p>

  1297. <p>In cases where canonical output is not applicable but a specific attribute

  1298. order is still desirable on output, code should aim for creating the

  1299. attributes directly in the desired order, to avoid perceptual mismatches

  1300. for readers of the code. In cases where this is difficult to achieve, a

  1301. recipe like the following can be applied prior to serialisation to enforce

  1302. an order independently from the Element creation:</p>

  1303. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">reorder_attributes</span><span class="p">(</span><span class="n">root</span><span class="p">):</span>

  1304.     <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iter</span><span class="p">():</span>

  1305.         <span class="n">attrib</span> <span class="o">=</span> <span class="n">el</span><span class="o">.</span><span class="n">attrib</span>

  1306.         <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">attrib</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>

  1307.             <span class="c1"># adjust attribute order, e.g. by sorting</span>

  1308.             <span class="n">attribs</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">attrib</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>

  1309.             <span class="n">attrib</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span>

  1310.             <span class="n">attrib</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">attribs</span><span class="p">)</span>

  1311. </pre></div>

  1312. </div>

  1313. </dd></dl>

  1314. 

  1315. </section>

  1316. <section id="elementtree-objects">

  1317. <span id="elementtree-elementtree-objects"></span><h3>ElementTree Objects<a class="headerlink" href="#elementtree-objects" title="Link to this heading">¶</a></h3>

  1318. <dl class="py class">

  1319. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree">

  1320. <em class="property"><span class="pre">class</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">ElementTree</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">element</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">file</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.ElementTree" title="Link to this definition">¶</a></dt>

  1321. <dd><p>ElementTree wrapper class.  This class represents an entire element

  1322. hierarchy, and adds some extra support for serialization to and from

  1323. standard XML.</p>

  1324. <p><em>element</em> is the root element.  The tree is initialized with the contents

  1325. of the XML <em>file</em> if given.</p>

  1326. <dl class="py method">

  1327. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree._setroot">

  1328. <span class="sig-name descname"><span class="pre">_setroot</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.ElementTree._setroot" title="Link to this definition">¶</a></dt>

  1329. <dd><p>Replaces the root element for this tree.  This discards the current

  1330. contents of the tree, and replaces it with the given element.  Use with

  1331. care.  <em>element</em> is an element instance.</p>

  1332. </dd></dl>

  1333. 

  1334. <dl class="py method">

  1335. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree.find">

  1336. <span class="sig-name descname"><span class="pre">find</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">match</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespaces</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.ElementTree.find" title="Link to this definition">¶</a></dt>

  1337. <dd><p>Same as <a class="reference internal" href="#xml.etree.ElementTree.Element.find" title="xml.etree.ElementTree.Element.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.find()</span></code></a>, starting at the root of the tree.</p>

  1338. </dd></dl>

  1339. 

  1340. <dl class="py method">

  1341. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree.findall">

  1342. <span class="sig-name descname"><span class="pre">findall</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">match</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespaces</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.ElementTree.findall" title="Link to this definition">¶</a></dt>

  1343. <dd><p>Same as <a class="reference internal" href="#xml.etree.ElementTree.Element.findall" title="xml.etree.ElementTree.Element.findall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.findall()</span></code></a>, starting at the root of the tree.</p>

  1344. </dd></dl>

  1345. 

  1346. <dl class="py method">

  1347. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree.findtext">

  1348. <span class="sig-name descname"><span class="pre">findtext</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">match</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>, <em class="sig-param"><span class="n"><span class="pre">namespaces</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.ElementTree.findtext" title="Link to this definition">¶</a></dt>

  1349. <dd><p>Same as <a class="reference internal" href="#xml.etree.ElementTree.Element.findtext" title="xml.etree.ElementTree.Element.findtext"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.findtext()</span></code></a>, starting at the root of the tree.</p>

  1350. </dd></dl>

  1351. 

  1352. <dl class="py method">

  1353. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree.getroot">

  1354. <span class="sig-name descname"><span class="pre">getroot</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.ElementTree.getroot" title="Link to this definition">¶</a></dt>

  1355. <dd><p>Returns the root element for this tree.</p>

  1356. </dd></dl>

  1357. 

  1358. <dl class="py method">

  1359. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree.iter">

  1360. <span class="sig-name descname"><span class="pre">iter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tag</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.ElementTree.iter" title="Link to this definition">¶</a></dt>

  1361. <dd><p>Creates and returns a tree iterator for the root element.  The iterator

  1362. loops over all elements in this tree, in section order.  <em>tag</em> is the tag

  1363. to look for (default is to return all elements).</p>

  1364. </dd></dl>

  1365. 

  1366. <dl class="py method">

  1367. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree.iterfind">

  1368. <span class="sig-name descname"><span class="pre">iterfind</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">match</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">namespaces</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.ElementTree.iterfind" title="Link to this definition">¶</a></dt>

  1369. <dd><p>Same as <a class="reference internal" href="#xml.etree.ElementTree.Element.iterfind" title="xml.etree.ElementTree.Element.iterfind"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Element.iterfind()</span></code></a>, starting at the root of the tree.</p>

  1370. <div class="versionadded">

  1371. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1372. </div>

  1373. </dd></dl>

  1374. 

  1375. <dl class="py method">

  1376. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree.parse">

  1377. <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.ElementTree.parse" title="Link to this definition">¶</a></dt>

  1378. <dd><p>Loads an external XML section into this element tree.  <em>source</em> is a file

  1379. name or <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>.  <em>parser</em> is an optional parser instance.

  1380. If not given, the standard <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> parser is used.  Returns the

  1381. section root element.</p>

  1382. </dd></dl>

  1383. 

  1384. <dl class="py method">

  1385. <dt class="sig sig-object py" id="xml.etree.ElementTree.ElementTree.write">

  1386. <span class="sig-name descname"><span class="pre">write</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</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">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">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="o"><span class="pre">*</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.ElementTree.write" title="Link to this definition">¶</a></dt>

  1387. <dd><p>Writes the element tree to a file, as XML.  <em>file</em> is a file name, or a

  1388. <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> opened for writing.  <em>encoding</em> <a class="footnote-reference brackets" href="#id9" id="id6" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> is the output

  1389. encoding (default is US-ASCII).

  1390. <em>xml_declaration</em> controls if an XML declaration should be added to the

  1391. file.  Use <code class="docutils literal notranslate"><span class="pre">False</span></code> for never, <code class="docutils literal notranslate"><span class="pre">True</span></code> for always, <code class="docutils literal notranslate"><span class="pre">None</span></code>

  1392. for only if not US-ASCII or UTF-8 or Unicode (default is <code class="docutils literal notranslate"><span class="pre">None</span></code>).

  1393. <em>default_namespace</em> sets the default XML namespace (for “xmlns”).

  1394. <em>method</em> is 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

  1395. <code class="docutils literal notranslate"><span class="pre">&quot;xml&quot;</span></code>).

  1396. The keyword-only <em>short_empty_elements</em> parameter controls the formatting

  1397. of elements that contain no content.  If <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), they are

  1398. emitted as a single self-closed tag, otherwise they are emitted as a pair

  1399. of start/end tags.</p>

  1400. <p>The output is either a string (<a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>) or binary (<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>).

  1401. This is controlled by the <em>encoding</em> argument.  If <em>encoding</em> is

  1402. <code class="docutils literal notranslate"><span class="pre">&quot;unicode&quot;</span></code>, the output is a string; otherwise, it’s binary.  Note that

  1403. this may conflict with the type of <em>file</em> if it’s an open

  1404. <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>; make sure you do not try to write a string to a

  1405. binary stream and vice versa.</p>

  1406. <div class="versionchanged">

  1407. <p><span class="versionmodified changed">Changed in version 3.4: </span>Added the <em>short_empty_elements</em> parameter.</p>

  1408. </div>

  1409. <div class="versionchanged">

  1410. <p><span class="versionmodified changed">Changed in version 3.8: </span>The <a class="reference internal" href="#xml.etree.ElementTree.ElementTree.write" title="xml.etree.ElementTree.ElementTree.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> method now preserves the attribute order specified

  1411. by the user.</p>

  1412. </div>

  1413. </dd></dl>

  1414. 

  1415. </dd></dl>

  1416. 

  1417. <p>This is the XML file that is going to be manipulated:</p>

  1418. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">&lt;</span><span class="n">html</span><span class="o">&gt;</span>

  1419.     <span class="o">&lt;</span><span class="n">head</span><span class="o">&gt;</span>

  1420.         <span class="o">&lt;</span><span class="n">title</span><span class="o">&gt;</span><span class="n">Example</span> <span class="n">page</span><span class="o">&lt;/</span><span class="n">title</span><span class="o">&gt;</span>

  1421.     <span class="o">&lt;/</span><span class="n">head</span><span class="o">&gt;</span>

  1422.     <span class="o">&lt;</span><span class="n">body</span><span class="o">&gt;</span>

  1423.         <span class="o">&lt;</span><span class="n">p</span><span class="o">&gt;</span><span class="n">Moved</span> <span class="n">to</span> <span class="o">&lt;</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">&quot;http://example.org/&quot;</span><span class="o">&gt;</span><span class="n">example</span><span class="o">.</span><span class="n">org</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;</span>

  1424.         <span class="ow">or</span> <span class="o">&lt;</span><span class="n">a</span> <span class="n">href</span><span class="o">=</span><span class="s2">&quot;http://example.com/&quot;</span><span class="o">&gt;</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">&lt;/</span><span class="n">a</span><span class="o">&gt;.&lt;/</span><span class="n">p</span><span class="o">&gt;</span>

  1425.     <span class="o">&lt;/</span><span class="n">body</span><span class="o">&gt;</span>

  1426. <span class="o">&lt;/</span><span class="n">html</span><span class="o">&gt;</span>

  1427. </pre></div>

  1428. </div>

  1429. <p>Example of changing the attribute “target” of every link in first paragraph:</p>

  1430. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">xml.etree.ElementTree</span> <span class="kn">import</span> <span class="n">ElementTree</span>

  1431. <span class="gp">&gt;&gt;&gt; </span><span class="n">tree</span> <span class="o">=</span> <span class="n">ElementTree</span><span class="p">()</span>

  1432. <span class="gp">&gt;&gt;&gt; </span><span class="n">tree</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">&quot;index.xhtml&quot;</span><span class="p">)</span>

  1433. <span class="go">&lt;Element &#39;html&#39; at 0xb77e6fac&gt;</span>

  1434. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">tree</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s2">&quot;body/p&quot;</span><span class="p">)</span>     <span class="c1"># Finds first occurrence of tag p in body</span>

  1435. <span class="gp">&gt;&gt;&gt; </span><span class="n">p</span>

  1436. <span class="go">&lt;Element &#39;p&#39; at 0xb77ec26c&gt;</span>

  1437. <span class="gp">&gt;&gt;&gt; </span><span class="n">links</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">p</span><span class="o">.</span><span class="n">iter</span><span class="p">(</span><span class="s2">&quot;a&quot;</span><span class="p">))</span>   <span class="c1"># Returns list of all links</span>

  1438. <span class="gp">&gt;&gt;&gt; </span><span class="n">links</span>

  1439. <span class="go">[&lt;Element &#39;a&#39; at 0xb77ec2ac&gt;, &lt;Element &#39;a&#39; at 0xb77ec1cc&gt;]</span>

  1440. <span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">links</span><span class="p">:</span>             <span class="c1"># Iterates through all found links</span>

  1441. <span class="gp">... </span>    <span class="n">i</span><span class="o">.</span><span class="n">attrib</span><span class="p">[</span><span class="s2">&quot;target&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;blank&quot;</span>

  1442. <span class="gp">...</span>

  1443. <span class="gp">&gt;&gt;&gt; </span><span class="n">tree</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">&quot;output.xhtml&quot;</span><span class="p">)</span>

  1444. </pre></div>

  1445. </div>

  1446. </section>

  1447. <section id="qname-objects">

  1448. <span id="elementtree-qname-objects"></span><h3>QName Objects<a class="headerlink" href="#qname-objects" title="Link to this heading">¶</a></h3>

  1449. <dl class="py class">

  1450. <dt class="sig sig-object py" id="xml.etree.ElementTree.QName">

  1451. <em class="property"><span class="pre">class</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">QName</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">text_or_uri</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tag</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.QName" title="Link to this definition">¶</a></dt>

  1452. <dd><p>QName wrapper.  This can be used to wrap a QName attribute value, in order

  1453. to get proper namespace handling on output.  <em>text_or_uri</em> is a string

  1454. containing the QName value, in the form {uri}local, or, if the tag argument

  1455. is given, the URI part of a QName.  If <em>tag</em> is given, the first argument is

  1456. interpreted as a URI, and this argument is interpreted as a local name.

  1457. <a class="reference internal" href="#xml.etree.ElementTree.QName" title="xml.etree.ElementTree.QName"><code class="xref py py-class docutils literal notranslate"><span class="pre">QName</span></code></a> instances are opaque.</p>

  1458. </dd></dl>

  1459. 

  1460. </section>

  1461. <section id="treebuilder-objects">

  1462. <span id="elementtree-treebuilder-objects"></span><h3>TreeBuilder Objects<a class="headerlink" href="#treebuilder-objects" title="Link to this heading">¶</a></h3>

  1463. <dl class="py class">

  1464. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder">

  1465. <em class="property"><span class="pre">class</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">TreeBuilder</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">element_factory</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></em>, <em class="sig-param"><span class="n"><span class="pre">comment_factory</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">pi_factory</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">insert_comments</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">insert_pis</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder" title="Link to this definition">¶</a></dt>

  1466. <dd><p>Generic element structure builder.  This builder converts a sequence of

  1467. start, data, end, comment and pi method calls to a well-formed element

  1468. structure.  You can use this class to build an element structure using

  1469. a custom XML parser, or a parser for some other XML-like format.</p>

  1470. <p><em>element_factory</em>, when given, must be a callable accepting two positional

  1471. arguments: a tag and a dict of attributes.  It is expected to return a new

  1472. element instance.</p>

  1473. <p>The <em>comment_factory</em> and <em>pi_factory</em> functions, when given, should behave

  1474. like the <a class="reference internal" href="#xml.etree.ElementTree.Comment" title="xml.etree.ElementTree.Comment"><code class="xref py py-func docutils literal notranslate"><span class="pre">Comment()</span></code></a> and <a class="reference internal" href="#xml.etree.ElementTree.ProcessingInstruction" title="xml.etree.ElementTree.ProcessingInstruction"><code class="xref py py-func docutils literal notranslate"><span class="pre">ProcessingInstruction()</span></code></a> functions to

  1475. create comments and processing instructions.  When not given, the default

  1476. factories will be used.  When <em>insert_comments</em> and/or <em>insert_pis</em> is true,

  1477. comments/pis will be inserted into the tree if they appear within the root

  1478. element (but not outside of it).</p>

  1479. <dl class="py method">

  1480. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.close">

  1481. <span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.close" title="Link to this definition">¶</a></dt>

  1482. <dd><p>Flushes the builder buffers, and returns the toplevel document

  1483. element.  Returns an <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> instance.</p>

  1484. </dd></dl>

  1485. 

  1486. <dl class="py method">

  1487. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.data">

  1488. <span class="sig-name descname"><span class="pre">data</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.data" title="Link to this definition">¶</a></dt>

  1489. <dd><p>Adds text to the current element.  <em>data</em> is a string.  This should be

  1490. either a bytestring, or a Unicode string.</p>

  1491. </dd></dl>

  1492. 

  1493. <dl class="py method">

  1494. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.end">

  1495. <span class="sig-name descname"><span class="pre">end</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tag</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.end" title="Link to this definition">¶</a></dt>

  1496. <dd><p>Closes the current element.  <em>tag</em> is the element name.  Returns the

  1497. closed element.</p>

  1498. </dd></dl>

  1499. 

  1500. <dl class="py method">

  1501. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.start">

  1502. <span class="sig-name descname"><span class="pre">start</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">attrs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.start" title="Link to this definition">¶</a></dt>

  1503. <dd><p>Opens a new element.  <em>tag</em> is the element name.  <em>attrs</em> is a dictionary

  1504. containing element attributes.  Returns the opened element.</p>

  1505. </dd></dl>

  1506. 

  1507. <dl class="py method">

  1508. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.comment">

  1509. <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></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.comment" title="Link to this definition">¶</a></dt>

  1510. <dd><p>Creates a comment with the given <em>text</em>.  If <code class="docutils literal notranslate"><span class="pre">insert_comments</span></code> is true,

  1511. this will also add it to the tree.</p>

  1512. <div class="versionadded">

  1513. <p><span class="versionmodified added">New in version 3.8.</span></p>

  1514. </div>

  1515. </dd></dl>

  1516. 

  1517. <dl class="py method">

  1518. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.pi">

  1519. <span class="sig-name descname"><span class="pre">pi</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></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.pi" title="Link to this definition">¶</a></dt>

  1520. <dd><p>Creates a process instruction with the given <em>target</em> name and <em>text</em>.

  1521. If <code class="docutils literal notranslate"><span class="pre">insert_pis</span></code> is true, this will also add it to the tree.</p>

  1522. <div class="versionadded">

  1523. <p><span class="versionmodified added">New in version 3.8.</span></p>

  1524. </div>

  1525. </dd></dl>

  1526. 

  1527. <p>In addition, a custom <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> object can provide the

  1528. following methods:</p>

  1529. <dl class="py method">

  1530. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.doctype">

  1531. <span class="sig-name descname"><span class="pre">doctype</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pubid</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">system</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.doctype" title="Link to this definition">¶</a></dt>

  1532. <dd><p>Handles a doctype declaration.  <em>name</em> is the doctype name.  <em>pubid</em> is

  1533. the public identifier.  <em>system</em> is the system identifier.  This method

  1534. does not exist on the default <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> class.</p>

  1535. <div class="versionadded">

  1536. <p><span class="versionmodified added">New in version 3.2.</span></p>

  1537. </div>

  1538. </dd></dl>

  1539. 

  1540. <dl class="py method">

  1541. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.start_ns">

  1542. <span class="sig-name descname"><span class="pre">start_ns</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.TreeBuilder.start_ns" title="Link to this definition">¶</a></dt>

  1543. <dd><p>Is called whenever the parser encounters a new namespace declaration,

  1544. before the <code class="docutils literal notranslate"><span class="pre">start()</span></code> callback for the opening element that defines it.

  1545. <em>prefix</em> is <code class="docutils literal notranslate"><span class="pre">''</span></code> for the default namespace and the declared

  1546. namespace prefix name otherwise.  <em>uri</em> is the namespace URI.</p>

  1547. <div class="versionadded">

  1548. <p><span class="versionmodified added">New in version 3.8.</span></p>

  1549. </div>

  1550. </dd></dl>

  1551. 

  1552. <dl class="py method">

  1553. <dt class="sig sig-object py" id="xml.etree.ElementTree.TreeBuilder.end_ns">

  1554. <span class="sig-name descname"><span class="pre">end_ns</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">prefix</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.TreeBuilder.end_ns" title="Link to this definition">¶</a></dt>

  1555. <dd><p>Is called after the <code class="docutils literal notranslate"><span class="pre">end()</span></code> callback of an element that declared

  1556. a namespace prefix mapping, with the name of the <em>prefix</em> that went

  1557. out of scope.</p>

  1558. <div class="versionadded">

  1559. <p><span class="versionmodified added">New in version 3.8.</span></p>

  1560. </div>

  1561. </dd></dl>

  1562. 

  1563. </dd></dl>

  1564. 

  1565. <dl class="py class">

  1566. <dt class="sig sig-object py" id="xml.etree.ElementTree.C14NWriterTarget">

  1567. <em class="property"><span class="pre">class</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">C14NWriterTarget</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">write</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">with_comments</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strip_text</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rewrite_prefixes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">qname_aware_tags</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">qname_aware_attrs</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">exclude_attrs</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">exclude_tags</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.C14NWriterTarget" title="Link to this definition">¶</a></dt>

  1568. <dd><p>A <a class="reference external" href="https://www.w3.org/TR/xml-c14n2/">C14N 2.0</a> writer.  Arguments are the

  1569. same as for the <a class="reference internal" href="#xml.etree.ElementTree.canonicalize" title="xml.etree.ElementTree.canonicalize"><code class="xref py py-func docutils literal notranslate"><span class="pre">canonicalize()</span></code></a> function.  This class does not build a

  1570. tree but translates the callback events directly into a serialised form

  1571. using the <em>write</em> function.</p>

  1572. <div class="versionadded">

  1573. <p><span class="versionmodified added">New in version 3.8.</span></p>

  1574. </div>

  1575. </dd></dl>

  1576. 

  1577. </section>

  1578. <section id="xmlparser-objects">

  1579. <span id="elementtree-xmlparser-objects"></span><h3>XMLParser Objects<a class="headerlink" href="#xmlparser-objects" title="Link to this heading">¶</a></h3>

  1580. <dl class="py class">

  1581. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLParser">

  1582. <em class="property"><span class="pre">class</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">XMLParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">target</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">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.ElementTree.XMLParser" title="Link to this definition">¶</a></dt>

  1583. <dd><p>This class is the low-level building block of the module.  It uses

  1584. <a class="reference internal" href="pyexpat.html#module-xml.parsers.expat" title="xml.parsers.expat: An interface to the Expat non-validating XML parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.parsers.expat</span></code></a> for efficient, event-based parsing of XML.  It can

  1585. be fed XML data incrementally with the <a class="reference internal" href="#xml.etree.ElementTree.XMLParser.feed" title="xml.etree.ElementTree.XMLParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">feed()</span></code></a> method, and parsing

  1586. events are translated to a push API - by invoking callbacks on the <em>target</em>

  1587. object.  If <em>target</em> is omitted, the standard <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> is used.

  1588. If <em>encoding</em> <a class="footnote-reference brackets" href="#id9" id="id8" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> is given, the value overrides the

  1589. encoding specified in the XML file.</p>

  1590. <div class="versionchanged">

  1591. <p><span class="versionmodified changed">Changed in version 3.8: </span>Parameters are now <a class="reference internal" href="../glossary.html#keyword-only-parameter"><span class="std std-ref">keyword-only</span></a>.

  1592. The <em>html</em> argument no longer supported.</p>

  1593. </div>

  1594. <dl class="py method">

  1595. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLParser.close">

  1596. <span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLParser.close" title="Link to this definition">¶</a></dt>

  1597. <dd><p>Finishes feeding data to the parser.  Returns the result of calling the

  1598. <code class="docutils literal notranslate"><span class="pre">close()</span></code> method of the <em>target</em> passed during construction; by default,

  1599. this is the toplevel document element.</p>

  1600. </dd></dl>

  1601. 

  1602. <dl class="py method">

  1603. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLParser.feed">

  1604. <span class="sig-name descname"><span class="pre">feed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLParser.feed" title="Link to this definition">¶</a></dt>

  1605. <dd><p>Feeds data to the parser.  <em>data</em> is encoded data.</p>

  1606. </dd></dl>

  1607. 

  1608. <dl class="py method">

  1609. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLParser.flush">

  1610. <span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLParser.flush" title="Link to this definition">¶</a></dt>

  1611. <dd><p>Triggers parsing of any previously fed unparsed data, which can be

  1612. used to ensure more immediate feedback, in particular with Expat &gt;=2.6.0.

  1613. The implementation of <a class="reference internal" href="#xml.etree.ElementTree.XMLParser.flush" title="xml.etree.ElementTree.XMLParser.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a> temporarily disables reparse deferral

  1614. with Expat (if currently enabled) and triggers a reparse.

  1615. Disabling reparse deferral has security consequences; please see

  1616. <a class="reference internal" href="pyexpat.html#xml.parsers.expat.xmlparser.SetReparseDeferralEnabled" title="xml.parsers.expat.xmlparser.SetReparseDeferralEnabled"><code class="xref py py-meth docutils literal notranslate"><span class="pre">xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()</span></code></a> for details.</p>

  1617. <p>Note that <a class="reference internal" href="#xml.etree.ElementTree.XMLParser.flush" title="xml.etree.ElementTree.XMLParser.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a> has been backported to some prior releases of

  1618. CPython as a security fix.  Check for availability of <a class="reference internal" href="#xml.etree.ElementTree.XMLParser.flush" title="xml.etree.ElementTree.XMLParser.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a>

  1619. using <a class="reference internal" href="functions.html#hasattr" title="hasattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">hasattr()</span></code></a> if used in code running across a variety of Python

  1620. versions.</p>

  1621. <div class="versionadded">

  1622. <p><span class="versionmodified added">New in version 3.12.3.</span></p>

  1623. </div>

  1624. </dd></dl>

  1625. 

  1626. <p><a class="reference internal" href="#xml.etree.ElementTree.XMLParser.feed" title="xml.etree.ElementTree.XMLParser.feed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLParser.feed()</span></code></a> calls <em>target</em>'s <code class="docutils literal notranslate"><span class="pre">start(tag,</span> <span class="pre">attrs_dict)</span></code> method

  1627. for each opening tag, its <code class="docutils literal notranslate"><span class="pre">end(tag)</span></code> method for each closing tag, and data

  1628. is processed by method <code class="docutils literal notranslate"><span class="pre">data(data)</span></code>.  For further supported callback

  1629. methods, see the <a class="reference internal" href="#xml.etree.ElementTree.TreeBuilder" title="xml.etree.ElementTree.TreeBuilder"><code class="xref py py-class docutils literal notranslate"><span class="pre">TreeBuilder</span></code></a> class.  <a class="reference internal" href="#xml.etree.ElementTree.XMLParser.close" title="xml.etree.ElementTree.XMLParser.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLParser.close()</span></code></a> calls

  1630. <em>target</em>'s method <code class="docutils literal notranslate"><span class="pre">close()</span></code>. <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a> can be used not only for

  1631. building a tree structure. This is an example of counting the maximum depth

  1632. of an XML file:</p>

  1633. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">xml.etree.ElementTree</span> <span class="kn">import</span> <span class="n">XMLParser</span>

  1634. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MaxDepth</span><span class="p">:</span>                     <span class="c1"># The target object of the parser</span>

  1635. <span class="gp">... </span>    <span class="n">maxDepth</span> <span class="o">=</span> <span class="mi">0</span>

  1636. <span class="gp">... </span>    <span class="n">depth</span> <span class="o">=</span> <span class="mi">0</span>

  1637. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">start</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tag</span><span class="p">,</span> <span class="n">attrib</span><span class="p">):</span>   <span class="c1"># Called for each opening tag.</span>

  1638. <span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">+=</span> <span class="mi">1</span>

  1639. <span class="gp">... </span>        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">&gt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span><span class="p">:</span>

  1640. <span class="gp">... </span>            <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">depth</span>

  1641. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">end</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tag</span><span class="p">):</span>             <span class="c1"># Called for each closing tag.</span>

  1642. <span class="gp">... </span>        <span class="bp">self</span><span class="o">.</span><span class="n">depth</span> <span class="o">-=</span> <span class="mi">1</span>

  1643. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">data</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>

  1644. <span class="gp">... </span>        <span class="k">pass</span>            <span class="c1"># We do not need to do anything with data.</span>

  1645. <span class="gp">... </span>    <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>    <span class="c1"># Called when all data has been parsed.</span>

  1646. <span class="gp">... </span>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">maxDepth</span>

  1647. <span class="gp">...</span>

  1648. <span class="gp">&gt;&gt;&gt; </span><span class="n">target</span> <span class="o">=</span> <span class="n">MaxDepth</span><span class="p">()</span>

  1649. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span> <span class="o">=</span> <span class="n">XMLParser</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">target</span><span class="p">)</span>

  1650. <span class="gp">&gt;&gt;&gt; </span><span class="n">exampleXml</span> <span class="o">=</span> <span class="s2">&quot;&quot;&quot;</span>

  1651. <span class="gp">... </span><span class="s2">&lt;a&gt;</span>

  1652. <span class="gp">... </span><span class="s2">  &lt;b&gt;</span>

  1653. <span class="gp">... </span><span class="s2">  &lt;/b&gt;</span>

  1654. <span class="gp">... </span><span class="s2">  &lt;b&gt;</span>

  1655. <span class="gp">... </span><span class="s2">    &lt;c&gt;</span>

  1656. <span class="gp">... </span><span class="s2">      &lt;d&gt;</span>

  1657. <span class="gp">... </span><span class="s2">      &lt;/d&gt;</span>

  1658. <span class="gp">... </span><span class="s2">    &lt;/c&gt;</span>

  1659. <span class="gp">... </span><span class="s2">  &lt;/b&gt;</span>

  1660. <span class="gp">... </span><span class="s2">&lt;/a&gt;&quot;&quot;&quot;</span>

  1661. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">feed</span><span class="p">(</span><span class="n">exampleXml</span><span class="p">)</span>

  1662. <span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>

  1663. <span class="go">4</span>

  1664. </pre></div>

  1665. </div>

  1666. </dd></dl>

  1667. 

  1668. </section>

  1669. <section id="xmlpullparser-objects">

  1670. <span id="elementtree-xmlpullparser-objects"></span><h3>XMLPullParser Objects<a class="headerlink" href="#xmlpullparser-objects" title="Link to this heading">¶</a></h3>

  1671. <dl class="py class">

  1672. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLPullParser">

  1673. <em class="property"><span class="pre">class</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">XMLPullParser</span></span><span class="sig-paren">(</span><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><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser" title="Link to this definition">¶</a></dt>

  1674. <dd><p>A pull parser suitable for non-blocking applications.  Its input-side API is

  1675. similar to that of <a class="reference internal" href="#xml.etree.ElementTree.XMLParser" title="xml.etree.ElementTree.XMLParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLParser</span></code></a>, but instead of pushing calls to a

  1676. callback target, <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a> collects an internal list of parsing

  1677. events and lets the user read from it. <em>events</em> is a sequence of events to

  1678. report back.  The supported 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>,

  1679. <code class="docutils literal notranslate"><span class="pre">&quot;comment&quot;</span></code>, <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> (the “ns” events

  1680. are used to get detailed namespace information).  If <em>events</em> is omitted,

  1681. only <code class="docutils literal notranslate"><span class="pre">&quot;end&quot;</span></code> events are reported.</p>

  1682. <dl class="py method">

  1683. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLPullParser.feed">

  1684. <span class="sig-name descname"><span class="pre">feed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser.feed" title="Link to this definition">¶</a></dt>

  1685. <dd><p>Feed the given bytes data to the parser.</p>

  1686. </dd></dl>

  1687. 

  1688. <dl class="py method">

  1689. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLPullParser.flush">

  1690. <span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser.flush" title="Link to this definition">¶</a></dt>

  1691. <dd><p>Triggers parsing of any previously fed unparsed data, which can be

  1692. used to ensure more immediate feedback, in particular with Expat &gt;=2.6.0.

  1693. The implementation of <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">flush()</span></code></a> temporarily disables reparse deferral

  1694. with Expat (if currently enabled) and triggers a reparse.

  1695. Disabling reparse deferral has security consequences; please see

  1696. <a class="reference internal" href="pyexpat.html#xml.parsers.expat.xmlparser.SetReparseDeferralEnabled" title="xml.parsers.expat.xmlparser.SetReparseDeferralEnabled"><code class="xref py py-meth docutils literal notranslate"><span class="pre">xml.parsers.expat.xmlparser.SetReparseDeferralEnabled()</span></code></a> for details.</p>

  1697. <p>Note that <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">flush()</span></code></a> has been backported to some prior releases of

  1698. CPython as a security fix.  Check for availability of <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">flush()</span></code></a>

  1699. using <a class="reference internal" href="functions.html#hasattr" title="hasattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">hasattr()</span></code></a> if used in code running across a variety of Python

  1700. versions.</p>

  1701. <div class="versionadded">

  1702. <p><span class="versionmodified added">New in version 3.12.3.</span></p>

  1703. </div>

  1704. </dd></dl>

  1705. 

  1706. <dl class="py method">

  1707. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLPullParser.close">

  1708. <span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser.close" title="Link to this definition">¶</a></dt>

  1709. <dd><p>Signal the parser that the data stream is terminated. Unlike

  1710. <a class="reference internal" href="#xml.etree.ElementTree.XMLParser.close" title="xml.etree.ElementTree.XMLParser.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">XMLParser.close()</span></code></a>, this method always returns <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.

  1711. Any events not yet retrieved when the parser is closed can still be

  1712. read with <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_events()</span></code></a>.</p>

  1713. </dd></dl>

  1714. 

  1715. <dl class="py method">

  1716. <dt class="sig sig-object py" id="xml.etree.ElementTree.XMLPullParser.read_events">

  1717. <span class="sig-name descname"><span class="pre">read_events</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="Link to this definition">¶</a></dt>

  1718. <dd><p>Return an iterator over the events which have been encountered in the

  1719. data fed to the

  1720. parser.  The iterator yields <code class="docutils literal notranslate"><span class="pre">(event,</span> <span class="pre">elem)</span></code> pairs, where <em>event</em> is a

  1721. string representing the type of event (e.g. <code class="docutils literal notranslate"><span class="pre">&quot;end&quot;</span></code>) and <em>elem</em> is the

  1722. encountered <a class="reference internal" href="#xml.etree.ElementTree.Element" title="xml.etree.ElementTree.Element"><code class="xref py py-class docutils literal notranslate"><span class="pre">Element</span></code></a> object, or other context value as follows.</p>

  1723. <ul class="simple">

  1724. <li><p><code class="docutils literal notranslate"><span class="pre">start</span></code>, <code class="docutils literal notranslate"><span class="pre">end</span></code>: the current Element.</p></li>

  1725. <li><p><code class="docutils literal notranslate"><span class="pre">comment</span></code>, <code class="docutils literal notranslate"><span class="pre">pi</span></code>: the current comment / processing instruction</p></li>

  1726. <li><p><code class="docutils literal notranslate"><span class="pre">start-ns</span></code>: a tuple <code class="docutils literal notranslate"><span class="pre">(prefix,</span> <span class="pre">uri)</span></code> naming the declared namespace

  1727. mapping.</p></li>

  1728. <li><p><code class="docutils literal notranslate"><span class="pre">end-ns</span></code>: <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> (this may change in a future version)</p></li>

  1729. </ul>

  1730. <p>Events provided in a previous call to <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_events()</span></code></a> will not be

  1731. yielded again.  Events are consumed from the internal queue only when

  1732. they are retrieved from the iterator, so multiple readers iterating in

  1733. parallel over iterators obtained from <a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser.read_events" title="xml.etree.ElementTree.XMLPullParser.read_events"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_events()</span></code></a> will have

  1734. unpredictable results.</p>

  1735. </dd></dl>

  1736. 

  1737. <div class="admonition note">

  1738. <p class="admonition-title">Note</p>

  1739. <p><a class="reference internal" href="#xml.etree.ElementTree.XMLPullParser" title="xml.etree.ElementTree.XMLPullParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">XMLPullParser</span></code></a> only guarantees that it has seen the “&gt;”

  1740. character of a starting tag when it emits a “start” event, so the

  1741. attributes are defined, but the contents of the text and tail attributes

  1742. are undefined at that point.  The same applies to the element children;

  1743. they may or may not be present.</p>

  1744. <p>If you need a fully populated element, look for “end” events instead.</p>

  1745. </div>

  1746. <div class="versionadded">

  1747. <p><span class="versionmodified added">New in version 3.4.</span></p>

  1748. </div>

  1749. <div class="versionchanged">

  1750. <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>

  1751. </div>

  1752. </dd></dl>

  1753. 

  1754. </section>

  1755. <section id="exceptions">

  1756. <h3>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h3>

  1757. <dl class="py class">

  1758. <dt class="sig sig-object py" id="xml.etree.ElementTree.ParseError">

  1759. <em class="property"><span class="pre">class</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">ParseError</span></span><a class="headerlink" href="#xml.etree.ElementTree.ParseError" title="Link to this definition">¶</a></dt>

  1760. <dd><p>XML parse error, raised by the various parsing methods in this module when

  1761. parsing fails.  The string representation of an instance of this exception

  1762. will contain a user-friendly error message.  In addition, it will have

  1763. the following attributes available:</p>

  1764. <dl class="py attribute">

  1765. <dt class="sig sig-object py" id="xml.etree.ElementTree.ParseError.code">

  1766. <span class="sig-name descname"><span class="pre">code</span></span><a class="headerlink" href="#xml.etree.ElementTree.ParseError.code" title="Link to this definition">¶</a></dt>

  1767. <dd><p>A numeric error code from the expat parser. See the documentation of

  1768. <a class="reference internal" href="pyexpat.html#module-xml.parsers.expat" title="xml.parsers.expat: An interface to the Expat non-validating XML parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xml.parsers.expat</span></code></a> for the list of error codes and their meanings.</p>

  1769. </dd></dl>

  1770. 

  1771. <dl class="py attribute">

  1772. <dt class="sig sig-object py" id="xml.etree.ElementTree.ParseError.position">

  1773. <span class="sig-name descname"><span class="pre">position</span></span><a class="headerlink" href="#xml.etree.ElementTree.ParseError.position" title="Link to this definition">¶</a></dt>

  1774. <dd><p>A tuple of <em>line</em>, <em>column</em> numbers, specifying where the error occurred.</p>

  1775. </dd></dl>

  1776. 

  1777. </dd></dl>

  1778. 

  1779. <p class="rubric">Footnotes</p>

  1780. <aside class="footnote-list brackets">

  1781. <aside class="footnote brackets" id="id9" role="doc-footnote">

  1782. <span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>

  1783. <span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>,<a role="doc-backlink" href="#id6">3</a>,<a role="doc-backlink" href="#id8">4</a>)</span>

  1784. <p>The encoding string included in XML output should conform to the

  1785. appropriate standards.  For example, “UTF-8” is valid, but “UTF8” is

  1786. not.  See <a class="reference external" href="https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl">https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl</a>

  1787. and <a class="reference external" href="https://www.iana.org/assignments/character-sets/character-sets.xhtml">https://www.iana.org/assignments/character-sets/character-sets.xhtml</a>.</p>

  1788. </aside>

  1789. </aside>

  1790. </section>

  1791. </section>

  1792. </section>

  1793. 

  1794. 

  1795.             <div class="clearer"></div>

  1796.           </div>

  1797.         </div>

  1798.       </div>

  1799.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  1800.         <div class="sphinxsidebarwrapper">

  1801.   <div>

  1802.     <h3><a href="../contents.html">Table of Contents</a></h3>

  1803.     <ul>

  1804. <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>

  1805. <li><a class="reference internal" href="#tutorial">Tutorial</a><ul>

  1806. <li><a class="reference internal" href="#xml-tree-and-elements">XML tree and elements</a></li>

  1807. <li><a class="reference internal" href="#parsing-xml">Parsing XML</a></li>

  1808. <li><a class="reference internal" href="#pull-api-for-non-blocking-parsing">Pull API for non-blocking parsing</a></li>

  1809. <li><a class="reference internal" href="#finding-interesting-elements">Finding interesting elements</a></li>

  1810. <li><a class="reference internal" href="#modifying-an-xml-file">Modifying an XML File</a></li>

  1811. <li><a class="reference internal" href="#building-xml-documents">Building XML documents</a></li>

  1812. <li><a class="reference internal" href="#parsing-xml-with-namespaces">Parsing XML with Namespaces</a></li>

  1813. </ul>

  1814. </li>

  1815. <li><a class="reference internal" href="#xpath-support">XPath support</a><ul>

  1816. <li><a class="reference internal" href="#example">Example</a></li>

  1817. <li><a class="reference internal" href="#supported-xpath-syntax">Supported XPath syntax</a></li>

  1818. </ul>

  1819. </li>

  1820. <li><a class="reference internal" href="#reference">Reference</a><ul>

  1821. <li><a class="reference internal" href="#functions">Functions</a></li>

  1822. </ul>

  1823. </li>

  1824. <li><a class="reference internal" href="#xinclude-support">XInclude support</a><ul>

  1825. <li><a class="reference internal" href="#id3">Example</a></li>

  1826. </ul>

  1827. </li>

  1828. <li><a class="reference internal" href="#id4">Reference</a><ul>

  1829. <li><a class="reference internal" href="#elementinclude-functions">Functions</a></li>

  1830. <li><a class="reference internal" href="#element-objects">Element Objects</a></li>

  1831. <li><a class="reference internal" href="#elementtree-objects">ElementTree Objects</a></li>

  1832. <li><a class="reference internal" href="#qname-objects">QName Objects</a></li>

  1833. <li><a class="reference internal" href="#treebuilder-objects">TreeBuilder Objects</a></li>

  1834. <li><a class="reference internal" href="#xmlparser-objects">XMLParser Objects</a></li>

  1835. <li><a class="reference internal" href="#xmlpullparser-objects">XMLPullParser Objects</a></li>

  1836. <li><a class="reference internal" href="#exceptions">Exceptions</a></li>

  1837. </ul>

  1838. </li>

  1839. </ul>

  1840. </li>

  1841. </ul>

  1842. 

  1843.   </div>

  1844.   <div>

  1845.     <h4>Previous topic</h4>

  1846.     <p class="topless"><a href="xml.html"

  1847.                           title="previous chapter">XML Processing Modules</a></p>

  1848.   </div>

  1849.   <div>

  1850.     <h4>Next topic</h4>

  1851.     <p class="topless"><a href="xml.dom.html"

  1852.                           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>

  1853.   </div>

  1854.   <div role="note" aria-label="source link">

  1855.     <h3>This Page</h3>

  1856.     <ul class="this-page-menu">

  1857.       <li><a href="../bugs.html">Report a Bug</a></li>

  1858.       <li>

  1859.         <a href="https://github.com/python/cpython/blob/main/Doc/library/xml.etree.elementtree.rst"

  1860.             rel="nofollow">Show Source

  1861.         </a>

  1862.       </li>

  1863.     </ul>

  1864.   </div>

  1865.         </div>

  1866. <div id="sidebarbutton" title="Collapse sidebar">

  1867. <span>«</span>

  1868. </div>

  1869. 

  1870.       </div>

  1871.       <div class="clearer"></div>

  1872.     </div>  

  1873.     <div class="related" role="navigation" aria-label="related navigation">

  1874.       <h3>Navigation</h3>

  1875.       <ul>

  1876.         <li class="right" style="margin-right: 10px">

  1877.           <a href="../genindex.html" title="General Index"

  1878.              >index</a></li>

  1879.         <li class="right" >

  1880.           <a href="../py-modindex.html" title="Python Module Index"

  1881.              >modules</a> |</li>

  1882.         <li class="right" >

  1883.           <a href="xml.dom.html" title="xml.dom — The Document Object Model API"

  1884.              >next</a> |</li>

  1885.         <li class="right" >

  1886.           <a href="xml.html" title="XML Processing Modules"

  1887.              >previous</a> |</li>

  1888. 

  1889.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  1890.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  1891.           <li class="switchers">

  1892.             <div class="language_switcher_placeholder"></div>

  1893.             <div class="version_switcher_placeholder"></div>

  1894.           </li>

  1895.           <li>

  1896.               

  1897.           </li>

  1898.     <li id="cpython-language-and-version">

  1899.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  1900.     </li>

  1901. 

  1902.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  1903.           <li class="nav-item nav-item-2"><a href="markup.html" >Structured Markup Processing Tools</a> &#187;</li>

  1904.         <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>

  1905.                 <li class="right">

  1906.                     

  1907. 

  1908.     <div class="inline-search" role="search">

  1909.         <form class="inline-search" action="../search.html" method="get">

  1910.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  1911.           <input type="submit" value="Go" />

  1912.         </form>

  1913.     </div>

  1914.                      |

  1915.                 </li>

  1916.             <li class="right">

  1917. <label class="theme-selector-label">

  1918.     Theme

  1919.     <select class="theme-selector" oninput="activateTheme(this.value)">

  1920.         <option value="auto" selected>Auto</option>

  1921.         <option value="light">Light</option>

  1922.         <option value="dark">Dark</option>

  1923.     </select>

  1924. </label> |</li>

  1925.             

  1926.       </ul>

  1927.     </div>  

  1928.     <div class="footer">

  1929.     &copy; 

  1930.       <a href="../copyright.html">

  1931.     

  1932.     Copyright

  1933.     

  1934.       </a>

  1935.      2001-2024, Python Software Foundation.

  1936.     <br />

  1937.     This page is licensed under the Python Software Foundation License Version 2.

  1938.     <br />

  1939.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  1940.     <br />

  1941.     

  1942.       See <a href="/license.html">History and License</a> for more information.<br />

  1943.     

  1944.     

  1945.     <br />

  1946. 

  1947.     The Python Software Foundation is a non-profit corporation.

  1948. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  1949. <br />

  1950.     <br />

  1951.       Last updated on Apr 09, 2024 (13:47 UTC).

  1952.     

  1953.       <a href="/bugs.html">Found a bug</a>?

  1954.     

  1955.     <br />

  1956. 

  1957.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  1958.     </div>

  1959. 

  1960.   </body>

  1961. </html>
上海开阖软件有限公司 沪ICP备12045867号-1