1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5 <meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
6 <title>lxml.objectify</title>
7 <meta name="authors" content="Stefan Behnel Holger Joukl" />
8 <link rel="stylesheet" href="style.css" type="text/css" />
9 <script type="text/javascript">
10 function trigger_menu(event) {
11 var sidemenu = document.getElementById("sidemenu");
12 var classes = sidemenu.getAttribute("class");
13 classes = (classes.indexOf(" visible") === -1) ? classes + " visible" : classes.replace(" visible", "");
14 sidemenu.setAttribute("class", classes);
15 event.preventDefault();
16 event.stopPropagation();
18 function hide_menu() {
19 var sidemenu = document.getElementById("sidemenu");
20 var classes = sidemenu.getAttribute("class");
21 if (classes.indexOf(" visible") !== -1) {
22 sidemenu.setAttribute("class", classes.replace(" visible", ""));
25 </script><meta content="width=device-width, initial-scale=1" name="viewport" /></head>
26 <body onclick="hide_menu()">
27 <div class="document" id="lxml-objectify">
28 <div class="sidemenu" id="sidemenu"><div class="menutrigger" onclick="trigger_menu(event)">Menu</div><div class="menu"><ul id="lxml-section"><li><span class="section title">lxml</span><ul class="menu foreign" id="index-menu"><li class="menu title"><a href="index.html">lxml</a><ul class="submenu"><li class="menu item"><a href="index.html#introduction">Introduction</a></li><li class="menu item"><a href="index.html#support-the-project">Support the project</a></li><li class="menu item"><a href="index.html#documentation">Documentation</a></li><li class="menu item"><a href="index.html#download">Download</a></li><li class="menu item"><a href="index.html#mailing-list">Mailing list</a></li><li class="menu item"><a href="index.html#bug-tracker">Bug tracker</a></li><li class="menu item"><a href="index.html#license">License</a></li><li class="menu item"><a href="index.html#old-versions">Old Versions</a></li><li class="menu item"><a href="index.html#legal-notice-for-donations">Legal Notice for Donations</a></li></ul></li></ul><ul class="menu foreign" id="intro-menu"><li class="menu title"><a href="intro.html">Why lxml?</a><ul class="submenu"><li class="menu item"><a href="intro.html#motto">Motto</a></li><li class="menu item"><a href="intro.html#aims">Aims</a></li></ul></li></ul><ul class="menu foreign" id="installation-menu"><li class="menu title"><a href="installation.html">Installing lxml</a><ul class="submenu"><li class="menu item"><a href="installation.html#where-to-get-it">Where to get it</a></li><li class="menu item"><a href="installation.html#requirements">Requirements</a></li><li class="menu item"><a href="installation.html#installation">Installation</a></li><li class="menu item"><a href="installation.html#building-lxml-from-dev-sources">Building lxml from dev sources</a></li><li class="menu item"><a href="installation.html#using-lxml-with-python-libxml2">Using lxml with python-libxml2</a></li><li class="menu item"><a href="installation.html#source-builds-on-ms-windows">Source builds on MS Windows</a></li><li class="menu item"><a href="installation.html#source-builds-on-macos-x">Source builds on MacOS-X</a></li></ul></li></ul><ul class="menu foreign" id="performance-menu"><li class="menu title"><a href="performance.html">Benchmarks and Speed</a><ul class="submenu"><li class="menu item"><a href="performance.html#general-notes">General notes</a></li><li class="menu item"><a href="performance.html#how-to-read-the-timings">How to read the timings</a></li><li class="menu item"><a href="performance.html#parsing-and-serialising">Parsing and Serialising</a></li><li class="menu item"><a href="performance.html#the-elementtree-api">The ElementTree API</a></li><li class="menu item"><a href="performance.html#xpath">XPath</a></li><li class="menu item"><a href="performance.html#a-longer-example">A longer example</a></li><li class="menu item"><a href="performance.html#lxml-objectify">lxml.objectify</a></li></ul></li></ul><ul class="menu foreign" id="compatibility-menu"><li class="menu title"><a href="compatibility.html">ElementTree compatibility of lxml.etree</a></li></ul><ul class="menu foreign" id="FAQ-menu"><li class="menu title"><a href="FAQ.html">lxml FAQ - Frequently Asked Questions</a><ul class="submenu"><li class="menu item"><a href="FAQ.html#general-questions">General Questions</a></li><li class="menu item"><a href="FAQ.html#installation">Installation</a></li><li class="menu item"><a href="FAQ.html#contributing">Contributing</a></li><li class="menu item"><a href="FAQ.html#bugs">Bugs</a></li><li class="menu item"><a href="FAQ.html#id1">Threading</a></li><li class="menu item"><a href="FAQ.html#parsing-and-serialisation">Parsing and Serialisation</a></li><li class="menu item"><a href="FAQ.html#xpath-and-document-traversal">XPath and Document Traversal</a></li></ul></li></ul></li></ul><ul id="Developing with lxml-section"><li><span class="section title">Developing with lxml</span><ul class="menu foreign" id="tutorial-menu"><li class="menu title"><a href="tutorial.html">The lxml.etree Tutorial</a><ul class="submenu"><li class="menu item"><a href="tutorial.html#the-element-class">The Element class</a></li><li class="menu item"><a href="tutorial.html#the-elementtree-class">The ElementTree class</a></li><li class="menu item"><a href="tutorial.html#parsing-from-strings-and-files">Parsing from strings and files</a></li><li class="menu item"><a href="tutorial.html#namespaces">Namespaces</a></li><li class="menu item"><a href="tutorial.html#the-e-factory">The E-factory</a></li><li class="menu item"><a href="tutorial.html#elementpath">ElementPath</a></li></ul></li></ul><ul class="menu foreign" id="api index-menu"><li class="menu title"><a href="api/index.html">API reference</a></li></ul><ul class="menu foreign" id="api-menu"><li class="menu title"><a href="api.html">APIs specific to lxml.etree</a><ul class="submenu"><li class="menu item"><a href="api.html#lxml-etree">lxml.etree</a></li><li class="menu item"><a href="api.html#other-element-apis">Other Element APIs</a></li><li class="menu item"><a href="api.html#trees-and-documents">Trees and Documents</a></li><li class="menu item"><a href="api.html#iteration">Iteration</a></li><li class="menu item"><a href="api.html#error-handling-on-exceptions">Error handling on exceptions</a></li><li class="menu item"><a href="api.html#error-logging">Error logging</a></li><li class="menu item"><a href="api.html#serialisation">Serialisation</a></li><li class="menu item"><a href="api.html#incremental-xml-generation">Incremental XML generation</a></li><li class="menu item"><a href="api.html#cdata">CDATA</a></li><li class="menu item"><a href="api.html#xinclude-and-elementinclude">XInclude and ElementInclude</a></li></ul></li></ul><ul class="menu foreign" id="parsing-menu"><li class="menu title"><a href="parsing.html">Parsing XML and HTML with lxml</a><ul class="submenu"><li class="menu item"><a href="parsing.html#parsers">Parsers</a></li><li class="menu item"><a href="parsing.html#the-target-parser-interface">The target parser interface</a></li><li class="menu item"><a href="parsing.html#the-feed-parser-interface">The feed parser interface</a></li><li class="menu item"><a href="parsing.html#incremental-event-parsing">Incremental event parsing</a></li><li class="menu item"><a href="parsing.html#iterparse-and-iterwalk">iterparse and iterwalk</a></li><li class="menu item"><a href="parsing.html#python-unicode-strings">Python unicode strings</a></li></ul></li></ul><ul class="menu foreign" id="validation-menu"><li class="menu title"><a href="validation.html">Validation with lxml</a><ul class="submenu"><li class="menu item"><a href="validation.html#validation-at-parse-time">Validation at parse time</a></li><li class="menu item"><a href="validation.html#id1">DTD</a></li><li class="menu item"><a href="validation.html#relaxng">RelaxNG</a></li><li class="menu item"><a href="validation.html#xmlschema">XMLSchema</a></li><li class="menu item"><a href="validation.html#id2">Schematron</a></li><li class="menu item"><a href="validation.html#id3">(Pre-ISO-Schematron)</a></li></ul></li></ul><ul class="menu foreign" id="xpathxslt-menu"><li class="menu title"><a href="xpathxslt.html">XPath and XSLT with lxml</a><ul class="submenu"><li class="menu item"><a href="xpathxslt.html#xpath">XPath</a></li><li class="menu item"><a href="xpathxslt.html#xslt">XSLT</a></li></ul></li></ul><ul class="menu current" id="objectify-menu"><li class="menu title"><a href="objectify.html">lxml.objectify</a><ul class="submenu"><li class="menu item"><a href="objectify.html#the-lxml-objectify-api">The lxml.objectify API</a></li><li class="menu item"><a href="objectify.html#asserting-a-schema">Asserting a Schema</a></li><li class="menu item"><a href="objectify.html#objectpath">ObjectPath</a></li><li class="menu item"><a href="objectify.html#python-data-types">Python data types</a></li><li class="menu item"><a href="objectify.html#how-data-types-are-matched">How data types are matched</a></li><li class="menu item"><a href="objectify.html#what-is-different-from-lxml-etree">What is different from lxml.etree?</a></li></ul></li></ul><ul class="menu foreign" id="lxmlhtml-menu"><li class="menu title"><a href="lxmlhtml.html">lxml.html</a><ul class="submenu"><li class="menu item"><a href="lxmlhtml.html#parsing-html">Parsing HTML</a></li><li class="menu item"><a href="lxmlhtml.html#html-element-methods">HTML Element Methods</a></li><li class="menu item"><a href="lxmlhtml.html#running-html-doctests">Running HTML doctests</a></li><li class="menu item"><a href="lxmlhtml.html#creating-html-with-the-e-factory">Creating HTML with the E-factory</a></li><li class="menu item"><a href="lxmlhtml.html#working-with-links">Working with links</a></li><li class="menu item"><a href="lxmlhtml.html#forms">Forms</a></li><li class="menu item"><a href="lxmlhtml.html#cleaning-up-html">Cleaning up HTML</a></li><li class="menu item"><a href="lxmlhtml.html#html-diff">HTML Diff</a></li><li class="menu item"><a href="lxmlhtml.html#examples">Examples</a></li></ul></li></ul><ul class="menu foreign" id="cssselect-menu"><li class="menu title"><a href="cssselect.html">lxml.cssselect</a><ul class="submenu"><li class="menu item"><a href="cssselect.html#the-cssselector-class">The CSSSelector class</a></li><li class="menu item"><a href="cssselect.html#the-cssselect-method">The cssselect method</a></li><li class="menu item"><a href="cssselect.html#supported-selectors">Supported Selectors</a></li><li class="menu item"><a href="cssselect.html#namespaces">Namespaces</a></li></ul></li></ul><ul class="menu foreign" id="elementsoup-menu"><li class="menu title"><a href="elementsoup.html">BeautifulSoup Parser</a><ul class="submenu"><li class="menu item"><a href="elementsoup.html#parsing-with-the-soupparser">Parsing with the soupparser</a></li><li class="menu item"><a href="elementsoup.html#entity-handling">Entity handling</a></li><li class="menu item"><a href="elementsoup.html#using-soupparser-as-a-fallback">Using soupparser as a fallback</a></li><li class="menu item"><a href="elementsoup.html#using-only-the-encoding-detection">Using only the encoding detection</a></li></ul></li></ul><ul class="menu foreign" id="html5parser-menu"><li class="menu title"><a href="html5parser.html">html5lib Parser</a><ul class="submenu"><li class="menu item"><a href="html5parser.html#differences-to-regular-html-parsing">Differences to regular HTML parsing</a></li><li class="menu item"><a href="html5parser.html#function-reference">Function Reference</a></li></ul></li></ul></li></ul><ul id="Extending lxml-section"><li><span class="section title">Extending lxml</span><ul class="menu foreign" id="resolvers-menu"><li class="menu title"><a href="resolvers.html">Document loading and URL resolving</a><ul class="submenu"><li class="menu item"><a href="resolvers.html#xml-catalogs">XML Catalogs</a></li><li class="menu item"><a href="resolvers.html#uri-resolvers">URI Resolvers</a></li><li class="menu item"><a href="resolvers.html#document-loading-in-context">Document loading in context</a></li><li class="menu item"><a href="resolvers.html#i-o-access-control-in-xslt">I/O access control in XSLT</a></li></ul></li></ul><ul class="menu foreign" id="extensions-menu"><li class="menu title"><a href="extensions.html">Python extensions for XPath and XSLT</a><ul class="submenu"><li class="menu item"><a href="extensions.html#xpath-extension-functions">XPath Extension functions</a></li><li class="menu item"><a href="extensions.html#xslt-extension-elements">XSLT extension elements</a></li></ul></li></ul><ul class="menu foreign" id="element classes-menu"><li class="menu title"><a href="element_classes.html">Using custom Element classes in lxml</a><ul class="submenu"><li class="menu item"><a href="element_classes.html#background-on-element-proxies">Background on Element proxies</a></li><li class="menu item"><a href="element_classes.html#element-initialization">Element initialization</a></li><li class="menu item"><a href="element_classes.html#setting-up-a-class-lookup-scheme">Setting up a class lookup scheme</a></li><li class="menu item"><a href="element_classes.html#generating-xml-with-custom-classes">Generating XML with custom classes</a></li><li class="menu item"><a href="element_classes.html#id1">Implementing namespaces</a></li></ul></li></ul><ul class="menu foreign" id="sax-menu"><li class="menu title"><a href="sax.html">Sax support</a><ul class="submenu"><li class="menu item"><a href="sax.html#building-a-tree-from-sax-events">Building a tree from SAX events</a></li><li class="menu item"><a href="sax.html#producing-sax-events-from-an-elementtree-or-element">Producing SAX events from an ElementTree or Element</a></li><li class="menu item"><a href="sax.html#interfacing-with-pulldom-minidom">Interfacing with pulldom/minidom</a></li></ul></li></ul><ul class="menu foreign" id="capi-menu"><li class="menu title"><a href="capi.html">The public C-API of lxml.etree</a><ul class="submenu"><li class="menu item"><a href="capi.html#passing-generated-trees-through-python">Passing generated trees through Python</a></li><li class="menu item"><a href="capi.html#writing-external-modules-in-cython">Writing external modules in Cython</a></li><li class="menu item"><a href="capi.html#writing-external-modules-in-c">Writing external modules in C</a></li></ul></li></ul></li></ul><ul id="Developing lxml-section"><li><span class="section title">Developing lxml</span><ul class="menu foreign" id="build-menu"><li class="menu title"><a href="build.html">How to build lxml from source</a><ul class="submenu"><li class="menu item"><a href="build.html#cython">Cython</a></li><li class="menu item"><a href="build.html#github-git-and-hg">Github, git and hg</a></li><li class="menu item"><a href="build.html#building-the-sources">Building the sources</a></li><li class="menu item"><a href="build.html#running-the-tests-and-reporting-errors">Running the tests and reporting errors</a></li><li class="menu item"><a href="build.html#building-an-egg-or-wheel">Building an egg or wheel</a></li><li class="menu item"><a href="build.html#building-lxml-on-macos-x">Building lxml on MacOS-X</a></li><li class="menu item"><a href="build.html#static-linking-on-windows">Static linking on Windows</a></li><li class="menu item"><a href="build.html#building-debian-packages-from-svn-sources">Building Debian packages from SVN sources</a></li></ul></li></ul><ul class="menu foreign" id="lxml source howto-menu"><li class="menu title"><a href="lxml-source-howto.html">How to read the source of lxml</a><ul class="submenu"><li class="menu item"><a href="lxml-source-howto.html#what-is-cython">What is Cython?</a></li><li class="menu item"><a href="lxml-source-howto.html#where-to-start">Where to start?</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-etree">lxml.etree</a></li><li class="menu item"><a href="lxml-source-howto.html#python-modules">Python modules</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-objectify">lxml.objectify</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-html">lxml.html</a></li></ul></li></ul><ul class="menu foreign" id="changes 4 4 3-menu"><li class="menu title"><a href="changes-4.4.3.html">Release Changelog</a></li></ul><ul class="menu foreign" id="credits-menu"><li class="menu title"><a href="credits.html">Credits</a><ul class="submenu"><li class="menu item"><a href="credits.html#main-contributors">Main contributors</a></li><li class="menu item"><a href="credits.html#special-thanks-goes-to">Special thanks goes to:</a></li></ul></li></ul></li><li><a href="/sitemap.html">Sitemap</a></li></ul></div></div><h1 class="title">lxml.objectify</h1>
29 <table class="docinfo" frame="void" rules="none">
30 <col class="docinfo-name" />
31 <col class="docinfo-content" />
33 <tr><th class="docinfo-name">Authors:</th>
35 <br />Holger Joukl</td></tr>
38 <p>lxml supports an alternative API similar to the <a class="reference external" href="http://uche.ogbuji.net/tech/4suite/amara/">Amara</a> bindery or
39 <a class="reference external" href="http://gnosis.cx/download/">gnosis.xml.objectify</a> through a <a class="reference external" href="element_classes.html">custom Element implementation</a>. The main idea
40 is to hide the usage of XML behind normal Python objects, sometimes referred
41 to as data-binding. It allows you to use XML as if you were dealing with a
42 normal Python object hierarchy.</p>
43 <p>Accessing the children of an XML element deploys object attribute access. If
44 there are multiple children with the same name, slicing and indexing can be
45 used. Python data types are extracted from XML content automatically and made
46 available to the normal Python operators.</p>
47 <div class="contents topic" id="contents">
48 <p class="topic-title first">Contents</p>
50 <li><a class="reference internal" href="#the-lxml-objectify-api" id="id1">The lxml.objectify API</a><ul>
51 <li><a class="reference internal" href="#element-access-through-object-attributes" id="id2">Element access through object attributes</a></li>
52 <li><a class="reference internal" href="#creating-objectify-trees" id="id3">Creating objectify trees</a></li>
53 <li><a class="reference internal" href="#tree-generation-with-the-e-factory" id="id4">Tree generation with the E-factory</a></li>
54 <li><a class="reference internal" href="#namespace-handling" id="id5">Namespace handling</a></li>
57 <li><a class="reference internal" href="#asserting-a-schema" id="id6">Asserting a Schema</a></li>
58 <li><a class="reference internal" href="#objectpath" id="id7">ObjectPath</a></li>
59 <li><a class="reference internal" href="#python-data-types" id="id8">Python data types</a><ul>
60 <li><a class="reference internal" href="#recursive-tree-dump" id="id9">Recursive tree dump</a></li>
61 <li><a class="reference internal" href="#recursive-string-representation-of-elements" id="id10">Recursive string representation of elements</a></li>
64 <li><a class="reference internal" href="#how-data-types-are-matched" id="id11">How data types are matched</a><ul>
65 <li><a class="reference internal" href="#type-annotations" id="id12">Type annotations</a></li>
66 <li><a class="reference internal" href="#xml-schema-datatype-annotation" id="id13">XML Schema datatype annotation</a></li>
67 <li><a class="reference internal" href="#the-dataelement-factory" id="id14">The DataElement factory</a></li>
68 <li><a class="reference internal" href="#defining-additional-data-classes" id="id15">Defining additional data classes</a></li>
69 <li><a class="reference internal" href="#advanced-element-class-lookup" id="id16">Advanced element class lookup</a></li>
72 <li><a class="reference internal" href="#what-is-different-from-lxml-etree" id="id17">What is different from lxml.etree?</a></li>
75 <p>To set up and use <tt class="docutils literal">objectify</tt>, you need both the <tt class="docutils literal">lxml.etree</tt>
76 module and <tt class="docutils literal">lxml.objectify</tt>:</p>
77 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">lxml</span> <span class="kn">import</span> <span class="n">etree</span>
78 <span class="gp">>>> </span><span class="kn">from</span> <span class="nn">lxml</span> <span class="kn">import</span> <span class="n">objectify</span>
80 <p>The objectify API is very different from the ElementTree API. If it
81 is used, it should not be mixed with other element implementations
82 (such as trees parsed with <tt class="docutils literal">lxml.etree</tt>), to avoid non-obvious
84 <p>The <a class="reference external" href="performance.html#lxml-objectify">benchmark page</a> has some hints on performance optimisation of
85 code using lxml.objectify.</p>
86 <p>To make the doctests in this document look a little nicer, we also use
88 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">lxml.usedoctest</span>
90 <p>Imported from within a doctest, this relieves us from caring about the exact
91 formatting of XML output.</p>
92 <div class="section" id="the-lxml-objectify-api">
93 <h1>The lxml.objectify API</h1>
94 <p>In <tt class="docutils literal">lxml.objectify</tt>, element trees provide an API that models the behaviour
95 of normal Python object trees as closely as possible.</p>
96 <div class="section" id="element-access-through-object-attributes">
97 <h2>Element access through object attributes</h2>
98 <p>The main idea behind the <tt class="docutils literal">objectify</tt> API is to hide XML element access
99 behind the usual object attribute access pattern. Asking an element for an
100 attribute will return the sequence of children with corresponding tag names:</p>
101 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"root"</span><span class="p">)</span>
102 <span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"b"</span><span class="p">)</span>
103 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
104 <span class="go">b</span>
105 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
106 <span class="go">0</span>
107 <span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"b"</span><span class="p">)</span>
108 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
109 <span class="go">b</span>
110 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
111 <span class="go">b</span>
112 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
113 <span class="go">1</span>
115 <p>For convenience, you can omit the index '0' to access the first child:</p>
116 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
117 <span class="go">b</span>
118 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">)</span>
119 <span class="go">0</span>
120 <span class="gp">>>> </span><span class="k">del</span> <span class="n">root</span><span class="o">.</span><span class="n">b</span>
122 <p>Iteration and slicing also obey the requested tag:</p>
123 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">x1</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"x"</span><span class="p">)</span>
124 <span class="gp">>>> </span><span class="n">x2</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"x"</span><span class="p">)</span>
125 <span class="gp">>>> </span><span class="n">x3</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"x"</span><span class="p">)</span>
127 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">x</span> <span class="p">]</span>
128 <span class="go">['x', 'x', 'x']</span>
130 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">x</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">3</span><span class="p">]</span> <span class="p">]</span>
131 <span class="go">['x', 'x']</span>
133 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">x</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">:]</span> <span class="p">]</span>
134 <span class="go">['x']</span>
136 <span class="gp">>>> </span><span class="k">del</span> <span class="n">root</span><span class="o">.</span><span class="n">x</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span>
137 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">x</span> <span class="p">]</span>
138 <span class="go">['x', 'x']</span>
140 <p>If you want to iterate over all children or need to provide a specific
141 namespace for the tag, use the <tt class="docutils literal">iterchildren()</tt> method. Like the other
142 methods for iteration, it supports an optional tag keyword argument:</p>
143 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">iterchildren</span><span class="p">()</span> <span class="p">]</span>
144 <span class="go">['b', 'x', 'x']</span>
146 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">iterchildren</span><span class="p">(</span><span class="n">tag</span><span class="o">=</span><span class="s1">'b'</span><span class="p">)</span> <span class="p">]</span>
147 <span class="go">['b']</span>
149 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">b</span> <span class="p">]</span>
150 <span class="go">['b']</span>
152 <p>XML attributes are accessed as in the normal ElementTree API:</p>
153 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"c"</span><span class="p">,</span> <span class="n">myattr</span><span class="o">=</span><span class="s2">"someval"</span><span class="p">)</span>
154 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"myattr"</span><span class="p">))</span>
155 <span class="go">someval</span>
157 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s2">"c"</span><span class="p">,</span> <span class="s2">"oh-oh"</span><span class="p">)</span>
158 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"c"</span><span class="p">))</span>
159 <span class="go">oh-oh</span>
161 <p>In addition to the normal ElementTree API for appending elements to trees,
162 subtrees can also be added by assigning them to object attributes. In this
163 case, the subtree is automatically deep copied and the tag name of its root is
164 updated to match the attribute name:</p>
165 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"yet_another_child"</span><span class="p">)</span>
166 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">new_child</span> <span class="o">=</span> <span class="n">el</span>
167 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">new_child</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
168 <span class="go">new_child</span>
169 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
170 <span class="go">yet_another_child</span>
172 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="p">[</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"y"</span><span class="p">),</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"y"</span><span class="p">)</span> <span class="p">]</span>
173 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">y</span> <span class="p">]</span>
174 <span class="go">['y', 'y']</span>
176 <p>The latter is a short form for operations on the full slice:</p>
177 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">y</span><span class="p">[:]</span> <span class="o">=</span> <span class="p">[</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"y"</span><span class="p">)</span> <span class="p">]</span>
178 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <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">y</span> <span class="p">]</span>
179 <span class="go">['y']</span>
181 <p>You can also replace children that way:</p>
182 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">child1</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"child"</span><span class="p">)</span>
183 <span class="gp">>>> </span><span class="n">child2</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"child"</span><span class="p">)</span>
184 <span class="gp">>>> </span><span class="n">child3</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"child"</span><span class="p">)</span>
186 <span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"new_child"</span><span class="p">)</span>
187 <span class="gp">>>> </span><span class="n">subel</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">el</span><span class="p">,</span> <span class="s2">"sub"</span><span class="p">)</span>
189 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">child</span> <span class="o">=</span> <span class="n">el</span>
190 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">child</span><span class="o">.</span><span class="n">sub</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
191 <span class="go">sub</span>
193 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">child</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="n">el</span>
194 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">child</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">.</span><span class="n">sub</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
195 <span class="go">sub</span>
197 <p>Note that special care must be taken when changing the tag name of an element:</p>
198 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
199 <span class="go">b</span>
200 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span> <span class="o">=</span> <span class="s2">"notB"</span>
201 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span>
202 <span class="gt">Traceback (most recent call last):</span>
203 <span class="c">...</span>
204 <span class="gr">AttributeError</span>: <span class="n">no such child: b</span>
205 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">notB</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
206 <span class="go">notB</span>
209 <div class="section" id="creating-objectify-trees">
210 <h2>Creating objectify trees</h2>
211 <p>As with <tt class="docutils literal">lxml.etree</tt>, you can either create an <tt class="docutils literal">objectify</tt> tree by
212 parsing an XML document or by building one from scratch. To parse a
213 document, just use the <tt class="docutils literal">parse()</tt> or <tt class="docutils literal">fromstring()</tt> functions of
215 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">fileobject</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">(</span><span class="s1">'<test/>'</span><span class="p">)</span>
217 <span class="gp">>>> </span><span class="n">tree</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">fileobject</span><span class="p">)</span>
218 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">getroot</span><span class="p">(),</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
219 <span class="go">True</span>
221 <span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s1">'<test/>'</span><span class="p">)</span>
222 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
223 <span class="go">True</span>
225 <p>To build a new tree in memory, <tt class="docutils literal">objectify</tt> replicates the standard
226 factory function <tt class="docutils literal">Element()</tt> from <tt class="docutils literal">lxml.etree</tt>:</p>
227 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">obj_el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"new"</span><span class="p">)</span>
228 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">obj_el</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
229 <span class="go">True</span>
231 <p>After creating such an Element, you can use the <a class="reference external" href="tutorial.html#the-element-class">usual API</a> of
232 lxml.etree to add SubElements to the tree:</p>
233 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">child</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">obj_el</span><span class="p">,</span> <span class="s2">"newchild"</span><span class="p">,</span> <span class="n">attr</span><span class="o">=</span><span class="s2">"value"</span><span class="p">)</span>
235 <p>New subelements will automatically inherit the objectify behaviour
236 from their tree. However, all independent elements that you create
237 through the <tt class="docutils literal">Element()</tt> factory of lxml.etree (instead of objectify)
238 will not support the <tt class="docutils literal">objectify</tt> API by themselves:</p>
239 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">subel</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">obj_el</span><span class="p">,</span> <span class="s2">"sub"</span><span class="p">)</span>
240 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">subel</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
241 <span class="go">True</span>
243 <span class="gp">>>> </span><span class="n">independent_el</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"new"</span><span class="p">)</span>
244 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">independent_el</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
245 <span class="go">False</span>
248 <div class="section" id="tree-generation-with-the-e-factory">
249 <h2>Tree generation with the E-factory</h2>
250 <p>To simplify the generation of trees even further, you can use the E-factory:</p>
251 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">E</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">E</span>
252 <span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">E</span><span class="o">.</span><span class="n">root</span><span class="p">(</span>
253 <span class="gp">... </span> <span class="n">E</span><span class="o">.</span><span class="n">a</span><span class="p">(</span><span class="mi">5</span><span class="p">),</span>
254 <span class="gp">... </span> <span class="n">E</span><span class="o">.</span><span class="n">b</span><span class="p">(</span><span class="mf">6.21</span><span class="p">),</span>
255 <span class="gp">... </span> <span class="n">E</span><span class="o">.</span><span class="n">c</span><span class="p">(</span><span class="bp">True</span><span class="p">),</span>
256 <span class="gp">... </span> <span class="n">E</span><span class="o">.</span><span class="n">d</span><span class="p">(</span><span class="s2">"how"</span><span class="p">,</span> <span class="n">tell</span><span class="o">=</span><span class="s2">"me"</span><span class="p">)</span>
257 <span class="gp">... </span><span class="p">)</span>
259 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
260 <span class="go"><root xmlns:py="http://codespeak.net/lxml/objectify/pytype"></span>
261 <span class="go"> <a py:pytype="int">5</a></span>
262 <span class="go"> <b py:pytype="float">6.21</b></span>
263 <span class="go"> <c py:pytype="bool">true</c></span>
264 <span class="go"> <d py:pytype="str" tell="me">how</d></span>
265 <span class="go"></root></span>
267 <p>This allows you to write up a specific language in tags:</p>
268 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">ROOT</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">E</span><span class="o">.</span><span class="n">root</span>
269 <span class="gp">>>> </span><span class="n">TITLE</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">E</span><span class="o">.</span><span class="n">title</span>
270 <span class="gp">>>> </span><span class="n">HOWMANY</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">E</span><span class="p">,</span> <span class="s2">"how-many"</span><span class="p">)</span>
272 <span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">ROOT</span><span class="p">(</span>
273 <span class="gp">... </span> <span class="n">TITLE</span><span class="p">(</span><span class="s2">"The title"</span><span class="p">),</span>
274 <span class="gp">... </span> <span class="n">HOWMANY</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
275 <span class="gp">... </span><span class="p">)</span>
277 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
278 <span class="go"><root xmlns:py="http://codespeak.net/lxml/objectify/pytype"></span>
279 <span class="go"> <title py:pytype="str">The title</title></span>
280 <span class="go"> <how-many py:pytype="int">5</how-many></span>
281 <span class="go"></root></span>
283 <p><tt class="docutils literal">objectify.E</tt> is an instance of <tt class="docutils literal">objectify.ElementMaker</tt>. By default, it
284 creates pytype annotated Elements without a namespace. You can switch off the
285 pytype annotation by passing False to the <tt class="docutils literal">annotate</tt> keyword argument of the
286 constructor. You can also pass a default namespace and an <tt class="docutils literal">nsmap</tt>:</p>
287 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">myE</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ElementMaker</span><span class="p">(</span><span class="n">annotate</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
288 <span class="gp">... </span> <span class="n">namespace</span><span class="o">=</span><span class="s2">"http://my/ns"</span><span class="p">,</span> <span class="n">nsmap</span><span class="o">=</span><span class="p">{</span><span class="bp">None</span> <span class="p">:</span> <span class="s2">"http://my/ns"</span><span class="p">})</span>
290 <span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">myE</span><span class="o">.</span><span class="n">root</span><span class="p">(</span> <span class="n">myE</span><span class="o">.</span><span class="n">someint</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="p">)</span>
292 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
293 <span class="go"><root xmlns="http://my/ns"></span>
294 <span class="go"> <someint>2</someint></span>
295 <span class="go"></root></span>
298 <div class="section" id="namespace-handling">
299 <h2>Namespace handling</h2>
300 <p>During tag lookups, namespaces are handled mostly behind the scenes.
301 If you access a child of an Element without specifying a namespace,
302 the lookup will use the namespace of the parent:</p>
303 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"{http://ns/}root"</span><span class="p">)</span>
304 <span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"{http://ns/}b"</span><span class="p">)</span>
305 <span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"{http://other/}c"</span><span class="p">)</span>
307 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
308 <span class="go">{http://ns/}b</span>
310 <p>Note that the <tt class="docutils literal">SubElement()</tt> factory of <tt class="docutils literal">lxml.etree</tt> does not
311 inherit any namespaces when creating a new subelement. Element
312 creation must be explicit about the namespace, and is simplified
313 through the E-factory as described above.</p>
314 <p>Lookups, however, inherit namespaces implicitly:</p>
315 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
316 <span class="go">{http://ns/}b</span>
318 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="p">)</span>
319 <span class="gt">Traceback (most recent call last):</span>
320 <span class="o">...</span>
321 <span class="gr">AttributeError</span>: <span class="n">no such child: {http://ns/}c</span>
323 <p>To access an element in a different namespace than its parent, you can
324 use <tt class="docutils literal">getattr()</tt>:</p>
325 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"{http://other/}c"</span><span class="p">)</span>
326 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
327 <span class="go">{http://other/}c</span>
329 <p>For convenience, there is also a quick way through item access:</p>
330 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">root</span><span class="p">[</span><span class="s2">"{http://other/}c"</span><span class="p">]</span>
331 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
332 <span class="go">{http://other/}c</span>
334 <p>The same approach must be used to access children with tag names that are not
335 valid Python identifiers:</p>
336 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"{http://ns/}tag-name"</span><span class="p">)</span>
337 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s2">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
338 <span class="go">{http://ns/}tag-name</span>
340 <span class="gp">>>> </span><span class="n">new_el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"{http://ns/}new-element"</span><span class="p">)</span>
341 <span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">new_el</span><span class="p">,</span> <span class="s2">"{http://ns/}child"</span><span class="p">)</span>
342 <span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">new_el</span><span class="p">,</span> <span class="s2">"{http://ns/}child"</span><span class="p">)</span>
343 <span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">new_el</span><span class="p">,</span> <span class="s2">"{http://ns/}child"</span><span class="p">)</span>
345 <span class="gp">>>> </span><span class="n">root</span><span class="p">[</span><span class="s2">"tag-name"</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span> <span class="n">new_el</span><span class="p">,</span> <span class="n">new_el</span> <span class="p">]</span>
346 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s2">"tag-name"</span><span class="p">]))</span>
347 <span class="go">2</span>
348 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s2">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
349 <span class="go">{http://ns/}tag-name</span>
351 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s2">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">child</span><span class="p">))</span>
352 <span class="go">3</span>
353 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s2">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">child</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
354 <span class="go">{http://ns/}child</span>
355 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s2">"tag-name"</span><span class="p">][</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">child</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
356 <span class="go">{http://ns/}child</span>
358 <p>or for names that have a special meaning in lxml.objectify:</p>
359 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">XML</span><span class="p">(</span><span class="s2">"<root><text>TEXT</text></root>"</span><span class="p">)</span>
361 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">text</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
362 <span class="gt">Traceback (most recent call last):</span>
363 <span class="c">...</span>
364 <span class="gr">AttributeError</span>: <span class="n">'NoneType' object has no attribute 'text'</span>
366 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s2">"text"</span><span class="p">]</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
367 <span class="go">TEXT</span>
371 <div class="section" id="asserting-a-schema">
372 <h1>Asserting a Schema</h1>
373 <p>When dealing with XML documents from different sources, you will often
374 require them to follow a common schema. In lxml.objectify, this
375 directly translates to enforcing a specific object tree, i.e. expected
376 object attributes are ensured to be there and to have the expected
377 type. This can easily be achieved through XML Schema validation at
378 parse time. Also see the <a class="reference external" href="validation.html">documentation on validation</a> on this
380 <p>First of all, we need a parser that knows our schema, so let's say we
381 parse the schema from a file-like object (or file or filename):</p>
382 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">(</span><span class="s1">'''</span><span class="se">\</span>
383 <span class="gp">... </span><span class="s1"> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"></span>
384 <span class="gp">... </span><span class="s1"> <xsd:element name="a" type="AType"/></span>
385 <span class="gp">... </span><span class="s1"> <xsd:complexType name="AType"></span>
386 <span class="gp">... </span><span class="s1"> <xsd:sequence></span>
387 <span class="gp">... </span><span class="s1"> <xsd:element name="b" type="xsd:string" /></span>
388 <span class="gp">... </span><span class="s1"> </xsd:sequence></span>
389 <span class="gp">... </span><span class="s1"> </xsd:complexType></span>
390 <span class="gp">... </span><span class="s1"> </xsd:schema></span>
391 <span class="gp">... </span><span class="s1">'''</span><span class="p">)</span>
392 <span class="gp">>>> </span><span class="n">schema</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">XMLSchema</span><span class="p">(</span><span class="nb">file</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>
394 <p>When creating the validating parser, we must make sure it <a class="reference external" href="#advance-element-class-lookup">returns
395 objectify trees</a>. This is best done with the <tt class="docutils literal">makeparser()</tt>
397 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">makeparser</span><span class="p">(</span><span class="n">schema</span> <span class="o">=</span> <span class="n">schema</span><span class="p">)</span>
399 <p>Now we can use it to parse a valid document:</p>
400 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">xml</span> <span class="o">=</span> <span class="s2">"<a><b>test</b></a>"</span>
401 <span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="n">xml</span><span class="p">,</span> <span class="n">parser</span><span class="p">)</span>
403 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">b</span><span class="p">)</span>
404 <span class="go">test</span>
406 <p>Or an invalid document:</p>
407 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">xml</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">"<a><b>test</b><c/></a>"</span>
408 <span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="n">xml</span><span class="p">,</span> <span class="n">parser</span><span class="p">)</span> <span class="c1"># doctest: +ELLIPSIS</span>
409 <span class="gt">Traceback (most recent call last):</span>
410 <span class="gr">lxml.etree.XMLSyntaxError</span>: <span class="n">Element 'c': This element is not expected...</span>
412 <p>Note that the same works for parse-time DTD validation, except that
413 DTDs do not support any data types by design.</p>
415 <div class="section" id="objectpath">
417 <p>For both convenience and speed, objectify supports its own path language,
418 represented by the <tt class="docutils literal">ObjectPath</tt> class:</p>
419 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"{http://ns/}root"</span><span class="p">)</span>
420 <span class="gp">>>> </span><span class="n">b1</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"{http://ns/}b"</span><span class="p">)</span>
421 <span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">b1</span><span class="p">,</span> <span class="s2">"{http://ns/}c"</span><span class="p">)</span>
422 <span class="gp">>>> </span><span class="n">b2</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"{http://ns/}b"</span><span class="p">)</span>
423 <span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"{http://other/}d"</span><span class="p">)</span>
425 <span class="gp">>>> </span><span class="n">path</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">"root.b.c"</span><span class="p">)</span>
426 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
427 <span class="go">root.b.c</span>
428 <span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">hasattr</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
429 <span class="go">True</span>
430 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
431 <span class="go">{http://ns/}c</span>
433 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">"root.b.c"</span><span class="p">)</span>
434 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
435 <span class="go">{http://ns/}c</span>
437 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">"root.{http://other/}d"</span><span class="p">)</span>
438 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
439 <span class="go">{http://other/}d</span>
441 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">"root.{not}there"</span><span class="p">)</span>
442 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
443 <span class="gt">Traceback (most recent call last):</span>
444 <span class="c">...</span>
445 <span class="gr">AttributeError</span>: <span class="n">no such child: {not}there</span>
447 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">"{not}there"</span><span class="p">)</span>
448 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
449 <span class="gt">Traceback (most recent call last):</span>
450 <span class="c">...</span>
451 <span class="gr">ValueError</span>: <span class="n">root element does not match: need {not}there, got {http://ns/}root</span>
453 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">"root.b[1]"</span><span class="p">)</span>
454 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
455 <span class="go">{http://ns/}b</span>
457 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">"root.{http://ns/}b[1]"</span><span class="p">)</span>
458 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
459 <span class="go">{http://ns/}b</span>
461 <p>Apart from strings, ObjectPath also accepts lists of path segments:</p>
462 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">([</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">,</span> <span class="s1">'c'</span><span class="p">])</span>
463 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
464 <span class="go">{http://ns/}c</span>
466 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">([</span><span class="s1">'root'</span><span class="p">,</span> <span class="s1">'{http://ns/}b[1]'</span><span class="p">])</span>
467 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
468 <span class="go">{http://ns/}b</span>
470 <p>You can also use relative paths starting with a '.' to ignore the actual root
471 element and only inherit its namespace:</p>
472 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">".b[1]"</span><span class="p">)</span>
473 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
474 <span class="go">{http://ns/}b</span>
476 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">([</span><span class="s1">''</span><span class="p">,</span> <span class="s1">'b[1]'</span><span class="p">])</span>
477 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
478 <span class="go">{http://ns/}b</span>
480 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">".unknown[1]"</span><span class="p">)</span>
481 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
482 <span class="gt">Traceback (most recent call last):</span>
483 <span class="c">...</span>
484 <span class="gr">AttributeError</span>: <span class="n">no such child: {http://ns/}unknown</span>
486 <span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">".{http://other/}unknown[1]"</span><span class="p">)</span>
487 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
488 <span class="gt">Traceback (most recent call last):</span>
489 <span class="c">...</span>
490 <span class="gr">AttributeError</span>: <span class="n">no such child: {http://other/}unknown</span>
492 <p>For convenience, a single dot represents the empty ObjectPath (identity):</p>
493 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">"."</span><span class="p">)</span>
494 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
495 <span class="go">{http://ns/}root</span>
497 <p>ObjectPath objects can be used to manipulate trees:</p>
498 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"{http://ns/}root"</span><span class="p">)</span>
500 <span class="gp">>>> </span><span class="n">path</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">".some.child.{http://other/}unknown"</span><span class="p">)</span>
501 <span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">hasattr</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
502 <span class="go">False</span>
503 <span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
504 <span class="gt">Traceback (most recent call last):</span>
505 <span class="c">...</span>
506 <span class="gr">AttributeError</span>: <span class="n">no such child: {http://ns/}some</span>
508 <span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">setattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"my value"</span><span class="p">)</span> <span class="c1"># creates children as necessary</span>
509 <span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">hasattr</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
510 <span class="go">True</span>
511 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
512 <span class="go">my value</span>
513 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">some</span><span class="o">.</span><span class="n">child</span><span class="p">[</span><span class="s2">"{http://other/}unknown"</span><span class="p">]</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
514 <span class="go">my value</span>
516 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span> <span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span> <span class="p">))</span>
517 <span class="go">1</span>
518 <span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">addattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"my new value"</span><span class="p">)</span>
519 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span> <span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span> <span class="p">))</span>
520 <span class="go">2</span>
521 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">text</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span> <span class="p">]</span>
522 <span class="go">['my value', 'my new value']</span>
524 <p>As with attribute assignment, <tt class="docutils literal">setattr()</tt> accepts lists:</p>
525 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">setattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="p">[</span><span class="s2">"v1"</span><span class="p">,</span> <span class="s2">"v2"</span><span class="p">,</span> <span class="s2">"v3"</span><span class="p">])</span>
526 <span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">text</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span> <span class="p">]</span>
527 <span class="go">['v1', 'v2', 'v3']</span>
529 <p>Note, however, that indexing is only supported in this context if the children
530 exist. Indexing of non existing children will not extend or create a list of
531 such children but raise an exception:</p>
532 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">path</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s2">".{non}existing[1]"</span><span class="p">)</span>
533 <span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">setattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"my value"</span><span class="p">)</span>
534 <span class="gt">Traceback (most recent call last):</span>
535 <span class="c">...</span>
536 <span class="gr">TypeError</span>: <span class="n">creating indexed path attributes is not supported</span>
538 <p>It is worth noting that ObjectPath does not depend on the <tt class="docutils literal">objectify</tt> module
539 or the ObjectifiedElement implementation. It can also be used in combination
540 with Elements from the normal lxml.etree API.</p>
542 <div class="section" id="python-data-types">
543 <h1>Python data types</h1>
544 <p>The objectify module knows about Python data types and tries its best to let
545 element content behave like them. For example, they support the normal math
547 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span>
548 <span class="gp">... </span> <span class="s2">"<root><a>5</a><b>11</b><c>true</c><d>hoi</d></root>"</span><span class="p">)</span>
549 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="n">root</span><span class="o">.</span><span class="n">b</span>
550 <span class="go">16</span>
551 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+=</span> <span class="n">root</span><span class="o">.</span><span class="n">b</span>
552 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
553 <span class="go">16</span>
555 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">2</span>
556 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="mi">2</span><span class="p">)</span>
557 <span class="go">4</span>
558 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
559 <span class="go">3</span>
561 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="p">)</span>
562 <span class="go">True</span>
563 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">c</span> <span class="o">=</span> <span class="bp">False</span>
564 <span class="gp">>>> </span><span class="k">if</span> <span class="ow">not</span> <span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="p">:</span>
565 <span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s2">"false!"</span><span class="p">)</span>
566 <span class="go">false!</span>
568 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">d</span> <span class="o">+</span> <span class="s2">" test !"</span><span class="p">)</span>
569 <span class="go">hoi test !</span>
570 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">d</span> <span class="o">=</span> <span class="s2">"</span><span class="si">%s</span><span class="s2"> - </span><span class="si">%s</span><span class="s2">"</span>
571 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">d</span> <span class="o">%</span> <span class="p">(</span><span class="mi">1234</span><span class="p">,</span> <span class="mi">12345</span><span class="p">))</span>
572 <span class="go">1234 - 12345</span>
574 <p>However, data elements continue to provide the objectify API. This means that
575 sequence operations such as <tt class="docutils literal">len()</tt>, slicing and indexing (e.g. of strings)
576 cannot behave as the Python types. Like all other tree elements, they show
577 the normal slicing behaviour of objectify elements:</p>
578 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s2">"<root><a>test</a><b>toast</b></root>"</span><span class="p">)</span>
579 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="s1">' me'</span><span class="p">)</span> <span class="c1"># behaves like a string, right?</span>
580 <span class="go">test me</span>
581 <span class="gp">>>> </span><span class="nb">len</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span> <span class="c1"># but there's only one 'a' element!</span>
582 <span class="go">1</span>
583 <span class="gp">>>> </span><span class="p">[</span> <span class="n">a</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="p">]</span>
584 <span class="go">['a']</span>
585 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
586 <span class="go">a</span>
588 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
589 <span class="go">test</span>
590 <span class="gp">>>> </span><span class="p">[</span> <span class="nb">str</span><span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">[:</span><span class="mi">1</span><span class="p">]</span> <span class="p">]</span>
591 <span class="go">['test']</span>
593 <p>If you need to run sequence operations on data types, you must ask the API for
594 the <em>real</em> Python value. The string value is always available through the
595 normal ElementTree <tt class="docutils literal">.text</tt> attribute. Additionally, all data classes
596 provide a <tt class="docutils literal">.pyval</tt> attribute that returns the value as plain Python type:</p>
597 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s2">"<root><a>test</a><b>5</b></root>"</span><span class="p">)</span>
598 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">text</span>
599 <span class="go">'test'</span>
600 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">pyval</span>
601 <span class="go">'test'</span>
603 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">text</span>
604 <span class="go">'5'</span>
605 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">pyval</span>
606 <span class="go">5</span>
608 <p>Note, however, that both attributes are read-only in objectify. If you want
609 to change values, just assign them directly to the attribute:</p>
610 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="s2">"25"</span>
611 <span class="gt">Traceback (most recent call last):</span>
612 <span class="c">...</span>
613 <span class="gr">TypeError</span>: <span class="n">attribute 'text' of 'StringElement' objects is not writable</span>
615 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">pyval</span> <span class="o">=</span> <span class="mi">25</span>
616 <span class="gt">Traceback (most recent call last):</span>
617 <span class="c">...</span>
618 <span class="gr">TypeError</span>: <span class="n">attribute 'pyval' of 'StringElement' objects is not writable</span>
620 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">25</span>
621 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
622 <span class="go">25</span>
623 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">pyval</span><span class="p">)</span>
624 <span class="go">25</span>
626 <p>In other words, <tt class="docutils literal">objectify</tt> data elements behave like immutable Python
627 types. You can replace them, but not modify them.</p>
628 <div class="section" id="recursive-tree-dump">
629 <h2>Recursive tree dump</h2>
630 <p>To see the data types that are currently used, you can call the module level
631 <tt class="docutils literal">dump()</tt> function that returns a recursive string representation for
633 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s2">"""</span>
634 <span class="gp">... </span><span class="s2"><root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></span>
635 <span class="gp">... </span><span class="s2"> <a attr1="foo" attr2="bar">1</a></span>
636 <span class="gp">... </span><span class="s2"> <a>1.2</a></span>
637 <span class="gp">... </span><span class="s2"> <b>1</b></span>
638 <span class="gp">... </span><span class="s2"> <b>true</b></span>
639 <span class="gp">... </span><span class="s2"> <c>what?</c></span>
640 <span class="gp">... </span><span class="s2"> <d xsi:nil="true"/></span>
641 <span class="gp">... </span><span class="s2"></root></span>
642 <span class="gp">... </span><span class="s2">"""</span><span class="p">)</span>
644 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
645 <span class="go">root = None [ObjectifiedElement]</span>
646 <span class="go"> a = 1 [IntElement]</span>
647 <span class="go"> * attr1 = 'foo'</span>
648 <span class="go"> * attr2 = 'bar'</span>
649 <span class="go"> a = 1.2 [FloatElement]</span>
650 <span class="go"> b = 1 [IntElement]</span>
651 <span class="go"> b = True [BoolElement]</span>
652 <span class="go"> c = 'what?' [StringElement]</span>
653 <span class="go"> d = None [NoneElement]</span>
654 <span class="go"> * xsi:nil = 'true'</span>
656 <p>You can freely switch between different types for the same child:</p>
657 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s2">"<root><a>5</a></root>"</span><span class="p">)</span>
658 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
659 <span class="go">root = None [ObjectifiedElement]</span>
660 <span class="go"> a = 5 [IntElement]</span>
662 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="s1">'nice string!'</span>
663 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
664 <span class="go">root = None [ObjectifiedElement]</span>
665 <span class="go"> a = 'nice string!' [StringElement]</span>
666 <span class="go"> * py:pytype = 'str'</span>
668 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="bp">True</span>
669 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
670 <span class="go">root = None [ObjectifiedElement]</span>
671 <span class="go"> a = True [BoolElement]</span>
672 <span class="go"> * py:pytype = 'bool'</span>
674 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>
675 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
676 <span class="go">root = None [ObjectifiedElement]</span>
677 <span class="go"> a = 1 [IntElement]</span>
678 <span class="go"> * py:pytype = 'int'</span>
679 <span class="go"> a = 2 [IntElement]</span>
680 <span class="go"> * py:pytype = 'int'</span>
681 <span class="go"> a = 3 [IntElement]</span>
682 <span class="go"> * py:pytype = 'int'</span>
684 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
685 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
686 <span class="go">root = None [ObjectifiedElement]</span>
687 <span class="go"> a = 1 [IntElement]</span>
688 <span class="go"> * py:pytype = 'int'</span>
689 <span class="go"> a = 2 [IntElement]</span>
690 <span class="go"> * py:pytype = 'int'</span>
691 <span class="go"> a = 3 [IntElement]</span>
692 <span class="go"> * py:pytype = 'int'</span>
695 <div class="section" id="recursive-string-representation-of-elements">
696 <h2>Recursive string representation of elements</h2>
697 <p>Normally, elements use the standard string representation for str() that is
698 provided by lxml.etree. You can enable a pretty-print representation for
699 objectify elements like this:</p>
700 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">enable_recursive_str</span><span class="p">()</span>
702 <span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s2">"""</span>
703 <span class="gp">... </span><span class="s2"><root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></span>
704 <span class="gp">... </span><span class="s2"> <a attr1="foo" attr2="bar">1</a></span>
705 <span class="gp">... </span><span class="s2"> <a>1.2</a></span>
706 <span class="gp">... </span><span class="s2"> <b>1</b></span>
707 <span class="gp">... </span><span class="s2"> <b>true</b></span>
708 <span class="gp">... </span><span class="s2"> <c>what?</c></span>
709 <span class="gp">... </span><span class="s2"> <d xsi:nil="true"/></span>
710 <span class="gp">... </span><span class="s2"></root></span>
711 <span class="gp">... </span><span class="s2">"""</span><span class="p">)</span>
713 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
714 <span class="go">root = None [ObjectifiedElement]</span>
715 <span class="go"> a = 1 [IntElement]</span>
716 <span class="go"> * attr1 = 'foo'</span>
717 <span class="go"> * attr2 = 'bar'</span>
718 <span class="go"> a = 1.2 [FloatElement]</span>
719 <span class="go"> b = 1 [IntElement]</span>
720 <span class="go"> b = True [BoolElement]</span>
721 <span class="go"> c = 'what?' [StringElement]</span>
722 <span class="go"> d = None [NoneElement]</span>
723 <span class="go"> * xsi:nil = 'true'</span>
725 <p>This behaviour can be switched off in the same way:</p>
726 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">enable_recursive_str</span><span class="p">(</span><span class="bp">False</span><span class="p">)</span>
730 <div class="section" id="how-data-types-are-matched">
731 <h1>How data types are matched</h1>
732 <p>Objectify uses two different types of Elements. Structural Elements (or tree
733 Elements) represent the object tree structure. Data Elements represent the
734 data containers at the leafs. You can explicitly create tree Elements with
735 the <tt class="docutils literal">objectify.Element()</tt> factory and data Elements with the
736 <tt class="docutils literal">objectify.DataElement()</tt> factory.</p>
737 <p>When Element objects are created, lxml.objectify must determine which
738 implementation class to use for them. This is relatively easy for tree
739 Elements and less so for data Elements. The algorithm is as follows:</p>
740 <ol class="arabic simple">
741 <li>If an element has children, use the default tree class.</li>
742 <li>If an element is defined as xsi:nil, use the NoneElement class.</li>
743 <li>If a "Python type hint" attribute is given, use this to determine the element
744 class, see below.</li>
745 <li>If an XML Schema xsi:type hint is given, use this to determine the element
746 class, see below.</li>
747 <li>Try to determine the element class from the text content type by trial and
749 <li>If the element is a root node then use the default tree class.</li>
750 <li>Otherwise, use the default class for empty data classes.</li>
752 <p>You can change the default classes for tree Elements and empty data Elements
753 at setup time. The <tt class="docutils literal">ObjectifyElementClassLookup()</tt> call accepts two keyword
754 arguments, <tt class="docutils literal">tree_class</tt> and <tt class="docutils literal">empty_data_class</tt>, that determine the Element
755 classes used in these cases. By default, <tt class="docutils literal">tree_class</tt> is a class called
756 <tt class="docutils literal">ObjectifiedElement</tt> and <tt class="docutils literal">empty_data_class</tt> is a <tt class="docutils literal">StringElement</tt>.</p>
757 <div class="section" id="type-annotations">
758 <h2>Type annotations</h2>
759 <p>The "type hint" mechanism deploys an XML attribute defined as
760 <tt class="docutils literal">lxml.objectify.PYTYPE_ATTRIBUTE</tt>. It may contain any of the following
761 string values: int, long, float, str, unicode, NoneType:</p>
762 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">PYTYPE_ATTRIBUTE</span><span class="p">)</span>
763 <span class="go">{http://codespeak.net/lxml/objectify/pytype}pytype</span>
764 <span class="gp">>>> </span><span class="n">ns</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">PYTYPE_ATTRIBUTE</span><span class="p">[</span><span class="mi">1</span><span class="p">:]</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">'}'</span><span class="p">)</span>
766 <span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s2">"""</span><span class="se">\</span>
767 <span class="gp">... </span><span class="s2"><root xmlns:py='</span><span class="si">%s</span><span class="s2">'></span>
768 <span class="gp">... </span><span class="s2"> <a py:pytype='str'>5</a></span>
769 <span class="gp">... </span><span class="s2"> <b py:pytype='int'>5</b></span>
770 <span class="gp">... </span><span class="s2"> <c py:pytype='NoneType' /></span>
771 <span class="gp">... </span><span class="s2"></root></span>
772 <span class="gp">... </span><span class="s2">"""</span> <span class="o">%</span> <span class="n">ns</span><span class="p">)</span>
774 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="mi">10</span><span class="p">)</span>
775 <span class="go">510</span>
776 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span> <span class="o">+</span> <span class="mi">10</span><span class="p">)</span>
777 <span class="go">15</span>
778 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="p">)</span>
779 <span class="go">None</span>
781 <p>Note that you can change the name and namespace used for this
782 attribute through the <tt class="docutils literal">set_pytype_attribute_tag(tag)</tt> module
783 function, in case your application ever needs to. There is also a
784 utility function <tt class="docutils literal">annotate()</tt> that recursively generates this
785 attribute for the elements of a tree:</p>
786 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s2">"<root><a>test</a><b>5</b></root>"</span><span class="p">)</span>
787 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
788 <span class="go">root = None [ObjectifiedElement]</span>
789 <span class="go"> a = 'test' [StringElement]</span>
790 <span class="go"> b = 5 [IntElement]</span>
792 <span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
794 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
795 <span class="go">root = None [ObjectifiedElement]</span>
796 <span class="go"> a = 'test' [StringElement]</span>
797 <span class="go"> * py:pytype = 'str'</span>
798 <span class="go"> b = 5 [IntElement]</span>
799 <span class="go"> * py:pytype = 'int'</span>
802 <div class="section" id="xml-schema-datatype-annotation">
803 <h2>XML Schema datatype annotation</h2>
804 <p>A second way of specifying data type information uses XML Schema types as
805 element annotations. Objectify knows those that can be mapped to normal
807 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s1">'''</span><span class="se">\</span>
808 <span class="gp">... </span><span class="s1"> <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
809 <span class="gp">... </span><span class="s1"> xmlns:xsd="http://www.w3.org/2001/XMLSchema"></span>
810 <span class="gp">... </span><span class="s1"> <d xsi:type="xsd:double">5</d></span>
811 <span class="gp">... </span><span class="s1"> <i xsi:type="xsd:int" >5</i></span>
812 <span class="gp">... </span><span class="s1"> <s xsi:type="xsd:string">5</s></span>
813 <span class="gp">... </span><span class="s1"> </root></span>
814 <span class="gp">... </span><span class="s1"> '''</span><span class="p">)</span>
815 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
816 <span class="go">root = None [ObjectifiedElement]</span>
817 <span class="go"> d = 5.0 [FloatElement]</span>
818 <span class="go"> * xsi:type = 'xsd:double'</span>
819 <span class="go"> i = 5 [IntElement]</span>
820 <span class="go"> * xsi:type = 'xsd:int'</span>
821 <span class="go"> s = '5' [StringElement]</span>
822 <span class="go"> * xsi:type = 'xsd:string'</span>
824 <p>Again, there is a utility function <tt class="docutils literal">xsiannotate()</tt> that recursively
825 generates the "xsi:type" attribute for the elements of a tree:</p>
826 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s1">'''</span><span class="se">\</span>
827 <span class="gp">... </span><span class="s1"> <root><a>test</a><b>5</b><c>true</c></root></span>
828 <span class="gp">... </span><span class="s1"> '''</span><span class="p">)</span>
829 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
830 <span class="go">root = None [ObjectifiedElement]</span>
831 <span class="go"> a = 'test' [StringElement]</span>
832 <span class="go"> b = 5 [IntElement]</span>
833 <span class="go"> c = True [BoolElement]</span>
835 <span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">xsiannotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
837 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
838 <span class="go">root = None [ObjectifiedElement]</span>
839 <span class="go"> a = 'test' [StringElement]</span>
840 <span class="go"> * xsi:type = 'xsd:string'</span>
841 <span class="go"> b = 5 [IntElement]</span>
842 <span class="go"> * xsi:type = 'xsd:integer'</span>
843 <span class="go"> c = True [BoolElement]</span>
844 <span class="go"> * xsi:type = 'xsd:boolean'</span>
846 <p>Note, however, that <tt class="docutils literal">xsiannotate()</tt> will always use the first XML Schema
847 datatype that is defined for any given Python type, see also
848 <a class="reference internal" href="#defining-additional-data-classes">Defining additional data classes</a>.</p>
849 <p>The utility function <tt class="docutils literal">deannotate()</tt> can be used to get rid of 'py:pytype'
850 and/or 'xsi:type' information:</p>
851 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s1">'''</span><span class="se">\</span>
852 <span class="gp">... </span><span class="s1"><root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
853 <span class="gp">... </span><span class="s1"> xmlns:xsd="http://www.w3.org/2001/XMLSchema"></span>
854 <span class="gp">... </span><span class="s1"> <d xsi:type="xsd:double">5</d></span>
855 <span class="gp">... </span><span class="s1"> <i xsi:type="xsd:int" >5</i></span>
856 <span class="gp">... </span><span class="s1"> <s xsi:type="xsd:string">5</s></span>
857 <span class="gp">... </span><span class="s1"></root>'''</span><span class="p">)</span>
858 <span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
859 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
860 <span class="go">root = None [ObjectifiedElement]</span>
861 <span class="go"> d = 5.0 [FloatElement]</span>
862 <span class="go"> * py:pytype = 'float'</span>
863 <span class="go"> * xsi:type = 'xsd:double'</span>
864 <span class="go"> i = 5 [IntElement]</span>
865 <span class="go"> * py:pytype = 'int'</span>
866 <span class="go"> * xsi:type = 'xsd:int'</span>
867 <span class="go"> s = '5' [StringElement]</span>
868 <span class="go"> * py:pytype = 'str'</span>
869 <span class="go"> * xsi:type = 'xsd:string'</span>
870 <span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">deannotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
871 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
872 <span class="go">root = None [ObjectifiedElement]</span>
873 <span class="go"> d = 5 [IntElement]</span>
874 <span class="go"> i = 5 [IntElement]</span>
875 <span class="go"> s = 5 [IntElement]</span>
877 <p>You can control which type attributes should be de-annotated with the keyword
878 arguments 'pytype' (default: True) and 'xsi' (default: True).
879 <tt class="docutils literal">deannotate()</tt> can also remove 'xsi:nil' attributes by setting 'xsi_nil=True'
880 (default: False):</p>
881 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s1">'''</span><span class="se">\</span>
882 <span class="gp">... </span><span class="s1"><root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
883 <span class="gp">... </span><span class="s1"> xmlns:xsd="http://www.w3.org/2001/XMLSchema"></span>
884 <span class="gp">... </span><span class="s1"> <d xsi:type="xsd:double">5</d></span>
885 <span class="gp">... </span><span class="s1"> <i xsi:type="xsd:int" >5</i></span>
886 <span class="gp">... </span><span class="s1"> <s xsi:type="xsd:string">5</s></span>
887 <span class="gp">... </span><span class="s1"> <n xsi:nil="true"/></span>
888 <span class="gp">... </span><span class="s1"></root>'''</span><span class="p">)</span>
889 <span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
890 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
891 <span class="go">root = None [ObjectifiedElement]</span>
892 <span class="go"> d = 5.0 [FloatElement]</span>
893 <span class="go"> * py:pytype = 'float'</span>
894 <span class="go"> * xsi:type = 'xsd:double'</span>
895 <span class="go"> i = 5 [IntElement]</span>
896 <span class="go"> * py:pytype = 'int'</span>
897 <span class="go"> * xsi:type = 'xsd:int'</span>
898 <span class="go"> s = '5' [StringElement]</span>
899 <span class="go"> * py:pytype = 'str'</span>
900 <span class="go"> * xsi:type = 'xsd:string'</span>
901 <span class="go"> n = None [NoneElement]</span>
902 <span class="go"> * py:pytype = 'NoneType'</span>
903 <span class="go"> * xsi:nil = 'true'</span>
904 <span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">deannotate</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">xsi_nil</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
905 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
906 <span class="go">root = None [ObjectifiedElement]</span>
907 <span class="go"> d = 5 [IntElement]</span>
908 <span class="go"> i = 5 [IntElement]</span>
909 <span class="go"> s = 5 [IntElement]</span>
910 <span class="go"> n = u'' [StringElement]</span>
912 <p>Note that <tt class="docutils literal">deannotate()</tt> does not remove the namespace declarations
913 of the <tt class="docutils literal">pytype</tt> namespace by default. To remove them as well, and
914 to generally clean up the namespace declarations in the document
915 (usually when done with the whole processing), pass the option
916 <tt class="docutils literal">cleanup_namespaces=True</tt>. This option is new in lxml 2.3.2. In
917 older versions, use the function <tt class="docutils literal">lxml.etree.cleanup_namespaces()</tt>
920 <div class="section" id="the-dataelement-factory">
921 <h2>The DataElement factory</h2>
922 <p>For convenience, the <tt class="docutils literal">DataElement()</tt> factory creates an Element with a
923 Python value in one step. You can pass the required Python type name or the
925 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"root"</span><span class="p">)</span>
926 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">_pytype</span><span class="o">=</span><span class="s2">"int"</span><span class="p">)</span>
927 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
928 <span class="go">root = None [ObjectifiedElement]</span>
929 <span class="go"> x = 5 [IntElement]</span>
930 <span class="go"> * py:pytype = 'int'</span>
932 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">_pytype</span><span class="o">=</span><span class="s2">"str"</span><span class="p">,</span> <span class="n">myattr</span><span class="o">=</span><span class="s2">"someval"</span><span class="p">)</span>
933 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
934 <span class="go">root = None [ObjectifiedElement]</span>
935 <span class="go"> x = '5' [StringElement]</span>
936 <span class="go"> * myattr = 'someval'</span>
937 <span class="go"> * py:pytype = 'str'</span>
939 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s2">"integer"</span><span class="p">)</span>
940 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
941 <span class="go">root = None [ObjectifiedElement]</span>
942 <span class="go"> x = 5 [IntElement]</span>
943 <span class="go"> * py:pytype = 'int'</span>
944 <span class="go"> * xsi:type = 'xsd:integer'</span>
946 <p>XML Schema types reside in the XML schema namespace thus <tt class="docutils literal">DataElement()</tt>
947 tries to correctly prefix the xsi:type attribute value for you:</p>
948 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s2">"root"</span><span class="p">)</span>
949 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">s</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s2">"string"</span><span class="p">)</span>
951 <span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">deannotate</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">xsi</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
952 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
953 <span class="go"><root xmlns:py="http://codespeak.net/lxml/objectify/pytype" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></span>
954 <span class="go"> <s xsi:type="xsd:string">5</s></span>
955 <span class="go"></root></span>
957 <p><tt class="docutils literal">DataElement()</tt> uses a default nsmap to set these prefixes:</p>
958 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="s1">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s1">'string'</span><span class="p">)</span>
959 <span class="gp">>>> </span><span class="n">namespaces</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">nsmap</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>
960 <span class="gp">>>> </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
961 <span class="gp">>>> </span><span class="k">for</span> <span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span> <span class="ow">in</span> <span class="n">namespaces</span><span class="p">:</span>
962 <span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s2">"</span><span class="si">%s</span><span class="s2"> - </span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span><span class="p">))</span>
963 <span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
964 <span class="go">xsd - http://www.w3.org/2001/XMLSchema</span>
965 <span class="go">xsi - http://www.w3.org/2001/XMLSchema-instance</span>
967 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
968 <span class="go">xsd:string</span>
970 <p>While you can set custom namespace prefixes, it is necessary to provide valid
971 namespace information if you choose to do so:</p>
972 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="s1">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s1">'foo:string'</span><span class="p">,</span>
973 <span class="gp">... </span> <span class="n">nsmap</span><span class="o">=</span><span class="p">{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'http://www.w3.org/2001/XMLSchema'</span><span class="p">})</span>
974 <span class="gp">>>> </span><span class="n">namespaces</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">nsmap</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>
975 <span class="gp">>>> </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
976 <span class="gp">>>> </span><span class="k">for</span> <span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span> <span class="ow">in</span> <span class="n">namespaces</span><span class="p">:</span>
977 <span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s2">"</span><span class="si">%s</span><span class="s2"> - </span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span><span class="p">))</span>
978 <span class="go">foo - http://www.w3.org/2001/XMLSchema</span>
979 <span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
980 <span class="go">xsi - http://www.w3.org/2001/XMLSchema-instance</span>
982 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
983 <span class="go">foo:string</span>
985 <p>Note how lxml chose a default prefix for the XML Schema Instance
986 namespace. We can override it as in the following example:</p>
987 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="s1">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s1">'foo:string'</span><span class="p">,</span>
988 <span class="gp">... </span> <span class="n">nsmap</span><span class="o">=</span><span class="p">{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'http://www.w3.org/2001/XMLSchema'</span><span class="p">,</span>
989 <span class="gp">... </span> <span class="s1">'myxsi'</span><span class="p">:</span> <span class="s1">'http://www.w3.org/2001/XMLSchema-instance'</span><span class="p">})</span>
990 <span class="gp">>>> </span><span class="n">namespaces</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">nsmap</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>
991 <span class="gp">>>> </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
992 <span class="gp">>>> </span><span class="k">for</span> <span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span> <span class="ow">in</span> <span class="n">namespaces</span><span class="p">:</span>
993 <span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s2">"</span><span class="si">%s</span><span class="s2"> - </span><span class="si">%s</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span><span class="p">))</span>
994 <span class="go">foo - http://www.w3.org/2001/XMLSchema</span>
995 <span class="go">myxsi - http://www.w3.org/2001/XMLSchema-instance</span>
996 <span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
998 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
999 <span class="go">foo:string</span>
1001 <p>Care must be taken if different namespace prefixes have been used for the same
1002 namespace. Namespace information gets merged to avoid duplicate definitions
1003 when adding a new sub-element to a tree, but this mechanism does not adapt the
1004 prefixes of attribute values:</p>
1005 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s2">"""<root xmlns:schema="http://www.w3.org/2001/XMLSchema"/>"""</span><span class="p">)</span>
1006 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
1007 <span class="go"><root xmlns:schema="http://www.w3.org/2001/XMLSchema"/></span>
1009 <span class="gp">>>> </span><span class="n">s</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="s2">"17"</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s2">"string"</span><span class="p">)</span>
1010 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
1011 <span class="go"><value xmlns:py="http://codespeak.net/lxml/objectify/pytype" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" py:pytype="str" xsi:type="xsd:string">17</value></span>
1013 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">s</span> <span class="o">=</span> <span class="n">s</span>
1014 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
1015 <span class="go"><root xmlns:schema="http://www.w3.org/2001/XMLSchema"></span>
1016 <span class="go"> <s xmlns:py="http://codespeak.net/lxml/objectify/pytype" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" py:pytype="str" xsi:type="xsd:string">17</s></span>
1017 <span class="go"></root></span>
1019 <p>It is your responsibility to fix the prefixes of attribute values if you
1020 choose to deviate from the standard prefixes. A convenient way to do this for
1021 xsi:type attributes is to use the <tt class="docutils literal">xsiannotate()</tt> utility:</p>
1022 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">xsiannotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
1023 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
1024 <span class="go"><root xmlns:schema="http://www.w3.org/2001/XMLSchema"></span>
1025 <span class="go"> <s xmlns:py="http://codespeak.net/lxml/objectify/pytype" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" py:pytype="str" xsi:type="schema:string">17</s></span>
1026 <span class="go"></root></span>
1028 <p>Of course, it is discouraged to use different prefixes for one and the same
1029 namespace when building up an objectify tree.</p>
1031 <div class="section" id="defining-additional-data-classes">
1032 <h2>Defining additional data classes</h2>
1033 <p>You can plug additional data classes into objectify that will be used in
1034 exactly the same way as the predefined types. Data classes can either inherit
1035 from <tt class="docutils literal">ObjectifiedDataElement</tt> directly or from one of the specialised
1036 classes like <tt class="docutils literal">NumberElement</tt> or <tt class="docutils literal">BoolElement</tt>. The numeric types require
1037 an initial call to the NumberElement method <tt class="docutils literal">self._setValueParser(function)</tt>
1038 to set their type conversion function (string -> numeric Python type). This
1039 call should be placed into the element <tt class="docutils literal">_init()</tt> method.</p>
1040 <p>The registration of data classes uses the <tt class="docutils literal">PyType</tt> class:</p>
1041 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="k">class</span> <span class="nc">ChristmasDate</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedDataElement</span><span class="p">):</span>
1042 <span class="gp">... </span> <span class="k">def</span> <span class="nf">call_santa</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1043 <span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s2">"Ho ho ho!"</span><span class="p">)</span>
1045 <span class="gp">>>> </span><span class="k">def</span> <span class="nf">checkChristmasDate</span><span class="p">(</span><span class="n">date_string</span><span class="p">):</span>
1046 <span class="gp">... </span> <span class="k">if</span> <span class="ow">not</span> <span class="n">date_string</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s1">'24.12.'</span><span class="p">):</span>
1047 <span class="gp">... </span> <span class="k">raise</span> <span class="ne">ValueError</span> <span class="c1"># or TypeError</span>
1049 <span class="gp">>>> </span><span class="n">xmas_type</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">PyType</span><span class="p">(</span><span class="s1">'date'</span><span class="p">,</span> <span class="n">checkChristmasDate</span><span class="p">,</span> <span class="n">ChristmasDate</span><span class="p">)</span>
1051 <p>The PyType constructor takes a string type name, an (optional) callable type
1052 check and the custom data class. If a type check is provided it must accept a
1053 string as argument and raise ValueError or TypeError if it cannot handle the
1055 <p>PyTypes are used if an element carries a <tt class="docutils literal">py:pytype</tt> attribute denoting its
1056 data type or, in absence of such an attribute, if the given type check callable
1057 does not raise a ValueError/TypeError exception when applied to the element
1059 <p>If you want, you can also register this type under an XML Schema type name:</p>
1060 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">xmas_type</span><span class="o">.</span><span class="n">xmlSchemaTypes</span> <span class="o">=</span> <span class="p">(</span><span class="s2">"date"</span><span class="p">,)</span>
1062 <p>XML Schema types will be considered if the element has an <tt class="docutils literal">xsi:type</tt>
1063 attribute that specifies its data type. The line above binds the XSD type
1064 <tt class="docutils literal">date</tt> to the newly defined Python type. Note that this must be done before
1065 the next step, which is to register the type. Then you can use it:</p>
1066 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">xmas_type</span><span class="o">.</span><span class="n">register</span><span class="p">()</span>
1068 <span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span>
1069 <span class="gp">... </span> <span class="s2">"<root><a>24.12.2000</a><b>12.24.2000</b></root>"</span><span class="p">)</span>
1070 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
1071 <span class="go">Ho ho ho!</span>
1072 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
1073 <span class="gt">Traceback (most recent call last):</span>
1074 <span class="c">...</span>
1075 <span class="gr">AttributeError</span>: <span class="n">no such child: call_santa</span>
1077 <p>If you need to specify dependencies between the type check functions, you can
1078 pass a sequence of type names through the <tt class="docutils literal">before</tt> and <tt class="docutils literal">after</tt> keyword
1079 arguments of the <tt class="docutils literal">register()</tt> method. The PyType will then try to register
1080 itself before or after the respective types, as long as they are currently
1081 registered. Note that this only impacts the currently registered types at the
1082 time of registration. Types that are registered later on will not care about
1083 the dependencies of already registered types.</p>
1084 <p>If you provide XML Schema type information, this will override the type check
1085 function defined above:</p>
1086 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s1">'''</span><span class="se">\</span>
1087 <span class="gp">... </span><span class="s1"> <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></span>
1088 <span class="gp">... </span><span class="s1"> <a xsi:type="date">12.24.2000</a></span>
1089 <span class="gp">... </span><span class="s1"> </root></span>
1090 <span class="gp">... </span><span class="s1"> '''</span><span class="p">)</span>
1091 <span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
1092 <span class="go">12.24.2000</span>
1093 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
1094 <span class="go">Ho ho ho!</span>
1096 <p>To unregister a type, call its <tt class="docutils literal">unregister()</tt> method:</p>
1097 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
1098 <span class="go">Ho ho ho!</span>
1099 <span class="gp">>>> </span><span class="n">xmas_type</span><span class="o">.</span><span class="n">unregister</span><span class="p">()</span>
1100 <span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
1101 <span class="gt">Traceback (most recent call last):</span>
1102 <span class="c">...</span>
1103 <span class="gr">AttributeError</span>: <span class="n">no such child: call_santa</span>
1105 <p>Be aware, though, that this does not immediately apply to elements to which
1106 there already is a Python reference. Their Python class will only be changed
1107 after all references are gone and the Python object is garbage collected.</p>
1109 <div class="section" id="advanced-element-class-lookup">
1110 <h2>Advanced element class lookup</h2>
1111 <p>In some cases, the normal data class setup is not enough. Being based
1112 on <tt class="docutils literal">lxml.etree</tt>, however, <tt class="docutils literal">lxml.objectify</tt> supports very
1113 fine-grained control over the Element classes used in a tree. All you
1114 have to do is configure a different <a class="reference external" href="element_classes.html">class lookup</a> mechanism (or
1115 write one yourself).</p>
1116 <p>The first step for the setup is to create a new parser that builds
1117 objectify documents. The objectify API is meant for data-centric XML
1118 (as opposed to document XML with mixed content). Therefore, we
1119 configure the parser to let it remove whitespace-only text from the
1120 parsed document if it is not enclosed by an XML element. Note that
1121 this alters the document infoset, so if you consider the removed
1122 spaces as data in your specific use case, you should go with a normal
1123 parser and just set the element class lookup. Most applications,
1124 however, will work fine with the following setup:</p>
1125 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">makeparser</span><span class="p">(</span><span class="n">remove_blank_text</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
1127 <p>What this does internally, is:</p>
1128 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">XMLParser</span><span class="p">(</span><span class="n">remove_blank_text</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
1130 <span class="gp">>>> </span><span class="n">lookup</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifyElementClassLookup</span><span class="p">()</span>
1131 <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">set_element_class_lookup</span><span class="p">(</span><span class="n">lookup</span><span class="p">)</span>
1133 <p>If you want to change the lookup scheme, say, to get additional
1134 support for <a class="reference external" href="element_classes.html#namespace-class-lookup">namespace specific classes</a>, you can register the
1135 objectify lookup as a fallback of the namespace lookup. In this case,
1136 however, you have to take care that the namespace classes inherit from
1137 <tt class="docutils literal">objectify.ObjectifiedElement</tt>, not only from the normal
1138 <tt class="docutils literal">lxml.etree.ElementBase</tt>, so that they support the <tt class="docutils literal">objectify</tt>
1139 API. The above setup code then becomes:</p>
1140 <div class="syntax"><pre><span></span><span class="gp">>>> </span><span class="n">lookup</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">ElementNamespaceClassLookup</span><span class="p">(</span>
1141 <span class="gp">... </span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifyElementClassLookup</span><span class="p">()</span> <span class="p">)</span>
1142 <span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">set_element_class_lookup</span><span class="p">(</span><span class="n">lookup</span><span class="p">)</span>
1144 <p>See the documentation on <a class="reference external" href="element_classes.html">class lookup</a> schemes for more information.</p>
1147 <div class="section" id="what-is-different-from-lxml-etree">
1148 <h1>What is different from lxml.etree?</h1>
1149 <p>Such a different Element API obviously implies some side effects to the normal
1150 behaviour of the rest of the API.</p>
1152 <li>len(<element>) returns the sibling count, not the number of children of
1153 <element>. You can retrieve the number of children with the
1154 <tt class="docutils literal">countchildren()</tt> method.</li>
1155 <li>Iteration over elements does not yield the children, but the siblings. You
1156 can access all children with the <tt class="docutils literal">iterchildren()</tt> method on elements or
1157 retrieve a list by calling the <tt class="docutils literal">getchildren()</tt> method.</li>
1158 <li>The find, findall and findtext methods require a different implementation
1159 based on ETXPath. In <tt class="docutils literal">lxml.etree</tt>, they use a Python implementation based
1160 on the original iteration scheme. This has the disadvantage that they may
1161 not be 100% backwards compatible, and the additional advantage that they now
1162 support any XPath expression.</li>
1166 <div class="footer">
1167 <hr class="footer" />
1168 Generated on: 2020-01-29.
projects / platform / upstream / python-lxml.git / blob