Imported Upstream version 2.3.5
[platform/upstream/python-lxml.git] / doc / html / objectify.html
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">
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5 <meta name="generator" content="Docutils 0.8.1: 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 </head>
10 <body>
11 <div class="document" id="lxml-objectify">
12 <div class="sidemenu"><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#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-sources">Building lxml from 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#ms-windows">MS Windows</a></li><li class="menu item"><a href="installation.html#macos-x">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#cdata">CDATA</a></li><li class="menu item"><a href="api.html#xinclude-and-elementinclude">XInclude and ElementInclude</a></li><li class="menu item"><a href="api.html#write-c14n-on-elementtree">write_c14n on ElementTree</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#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#css-selectors">CSS Selectors</a></li><li class="menu item"><a href="cssselect.html#namespaces">Namespaces</a></li><li class="menu item"><a href="cssselect.html#limitations">Limitations</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#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#id2">Setuptools</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">Building an egg</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 2 3 5-menu"><li class="menu title"><a href="changes-2.3.5.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="http://lxml.de/sitemap.html">Sitemap</a></li></ul></div><h1 class="title">lxml.objectify</h1>
13 <table class="docinfo" frame="void" rules="none">
14 <col class="docinfo-name" />
15 <col class="docinfo-content" />
16 <tbody valign="top">
17 <tr><th class="docinfo-name">Authors:</th>
18 <td>Stefan Behnel
19 <br />Holger Joukl</td></tr>
20 </tbody>
21 </table>
22 <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
23 <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
24 is to hide the usage of XML behind normal Python objects, sometimes referred
25 to as data-binding.  It allows you to use XML as if you were dealing with a
26 normal Python object hierarchy.</p>
27 <p>Accessing the children of an XML element deploys object attribute access.  If
28 there are multiple children with the same name, slicing and indexing can be
29 used.  Python data types are extracted from XML content automatically and made
30 available to the normal Python operators.</p>
31 <div class="contents topic" id="contents">
32 <p class="topic-title first">Contents</p>
33 <ul class="simple">
34 <li><a class="reference internal" href="#the-lxml-objectify-api" id="id1">The lxml.objectify API</a><ul>
35 <li><a class="reference internal" href="#element-access-through-object-attributes" id="id2">Element access through object attributes</a></li>
36 <li><a class="reference internal" href="#creating-objectify-trees" id="id3">Creating objectify trees</a></li>
37 <li><a class="reference internal" href="#tree-generation-with-the-e-factory" id="id4">Tree generation with the E-factory</a></li>
38 <li><a class="reference internal" href="#namespace-handling" id="id5">Namespace handling</a></li>
39 </ul>
40 </li>
41 <li><a class="reference internal" href="#asserting-a-schema" id="id6">Asserting a Schema</a></li>
42 <li><a class="reference internal" href="#objectpath" id="id7">ObjectPath</a></li>
43 <li><a class="reference internal" href="#python-data-types" id="id8">Python data types</a><ul>
44 <li><a class="reference internal" href="#recursive-tree-dump" id="id9">Recursive tree dump</a></li>
45 <li><a class="reference internal" href="#recursive-string-representation-of-elements" id="id10">Recursive string representation of elements</a></li>
46 </ul>
47 </li>
48 <li><a class="reference internal" href="#how-data-types-are-matched" id="id11">How data types are matched</a><ul>
49 <li><a class="reference internal" href="#type-annotations" id="id12">Type annotations</a></li>
50 <li><a class="reference internal" href="#xml-schema-datatype-annotation" id="id13">XML Schema datatype annotation</a></li>
51 <li><a class="reference internal" href="#the-dataelement-factory" id="id14">The DataElement factory</a></li>
52 <li><a class="reference internal" href="#defining-additional-data-classes" id="id15">Defining additional data classes</a></li>
53 <li><a class="reference internal" href="#advanced-element-class-lookup" id="id16">Advanced element class lookup</a></li>
54 </ul>
55 </li>
56 <li><a class="reference internal" href="#what-is-different-from-lxml-etree" id="id17">What is different from lxml.etree?</a></li>
57 </ul>
58 </div>
59 <p>To set up and use <tt class="docutils literal">objectify</tt>, you need both the <tt class="docutils literal">lxml.etree</tt>
60 module and <tt class="docutils literal">lxml.objectify</tt>:</p>
61 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">lxml</span> <span class="kn">import</span> <span class="n">etree</span>
62 <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">lxml</span> <span class="kn">import</span> <span class="n">objectify</span>
63 </pre></div>
64 <p>The objectify API is very different from the ElementTree API.  If it
65 is used, it should not be mixed with other element implementations
66 (such as trees parsed with <tt class="docutils literal">lxml.etree</tt>), to avoid non-obvious
67 behaviour.</p>
68 <p>The <a class="reference external" href="performance.html#lxml-objectify">benchmark page</a> has some hints on performance optimisation of
69 code using lxml.objectify.</p>
70 <p>To make the doctests in this document look a little nicer, we also use
71 this:</p>
72 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">lxml.usedoctest</span>
73 </pre></div>
74 <p>Imported from within a doctest, this relieves us from caring about the exact
75 formatting of XML output.</p>
76 <div class="section" id="the-lxml-objectify-api">
77 <h1>The lxml.objectify API</h1>
78 <p>In <tt class="docutils literal">lxml.objectify</tt>, element trees provide an API that models the behaviour
79 of normal Python object trees as closely as possible.</p>
80 <div class="section" id="element-access-through-object-attributes">
81 <h2>Element access through object attributes</h2>
82 <p>The main idea behind the <tt class="docutils literal">objectify</tt> API is to hide XML element access
83 behind the usual object attribute access pattern.  Asking an element for an
84 attribute will return the sequence of children with corresponding tag names:</p>
85 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"root"</span><span class="p">)</span>
86 <span class="gp">&gt;&gt;&gt; </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="s">"b"</span><span class="p">)</span>
87 <span class="gp">&gt;&gt;&gt; </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>
88 <span class="go">b</span>
89 <span class="gp">&gt;&gt;&gt; </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>
90 <span class="go">0</span>
91 <span class="gp">&gt;&gt;&gt; </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="s">"b"</span><span class="p">)</span>
92 <span class="gp">&gt;&gt;&gt; </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>
93 <span class="go">b</span>
94 <span class="gp">&gt;&gt;&gt; </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>
95 <span class="go">b</span>
96 <span class="gp">&gt;&gt;&gt; </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>
97 <span class="go">1</span>
98 </pre></div>
99 <p>For convenience, you can omit the index '0' to access the first child:</p>
100 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
101 <span class="go">b</span>
102 <span class="gp">&gt;&gt;&gt; </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>
103 <span class="go">0</span>
104 <span class="gp">&gt;&gt;&gt; </span><span class="k">del</span> <span class="n">root</span><span class="o">.</span><span class="n">b</span>
105 </pre></div>
106 <p>Iteration and slicing also obey the requested tag:</p>
107 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"x"</span><span class="p">)</span>
108 <span class="gp">&gt;&gt;&gt; </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="s">"x"</span><span class="p">)</span>
109 <span class="gp">&gt;&gt;&gt; </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="s">"x"</span><span class="p">)</span>
110
111 <span class="gp">&gt;&gt;&gt; </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>
112 <span class="go">['x', 'x', 'x']</span>
113
114 <span class="gp">&gt;&gt;&gt; </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>
115 <span class="go">['x', 'x']</span>
116
117 <span class="gp">&gt;&gt;&gt; </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>
118 <span class="go">['x']</span>
119
120 <span class="gp">&gt;&gt;&gt; </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>
121 <span class="gp">&gt;&gt;&gt; </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>
122 <span class="go">['x', 'x']</span>
123 </pre></div>
124 <p>If you want to iterate over all children or need to provide a specific
125 namespace for the tag, use the <tt class="docutils literal">iterchildren()</tt> method.  Like the other
126 methods for iteration, it supports an optional tag keyword argument:</p>
127 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
128 <span class="go">['b', 'x', 'x']</span>
129
130 <span class="gp">&gt;&gt;&gt; </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="s">'b'</span><span class="p">)</span> <span class="p">]</span>
131 <span class="go">['b']</span>
132
133 <span class="gp">&gt;&gt;&gt; </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>
134 <span class="go">['b']</span>
135 </pre></div>
136 <p>XML attributes are accessed as in the normal ElementTree API:</p>
137 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"c"</span><span class="p">,</span> <span class="n">myattr</span><span class="o">=</span><span class="s">"someval"</span><span class="p">)</span>
138 <span class="gp">&gt;&gt;&gt; </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="s">"myattr"</span><span class="p">))</span>
139 <span class="go">someval</span>
140
141 <span class="gp">&gt;&gt;&gt; </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="s">"c"</span><span class="p">,</span> <span class="s">"oh-oh"</span><span class="p">)</span>
142 <span class="gp">&gt;&gt;&gt; </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="s">"c"</span><span class="p">))</span>
143 <span class="go">oh-oh</span>
144 </pre></div>
145 <p>In addition to the normal ElementTree API for appending elements to trees,
146 subtrees can also be added by assigning them to object attributes.  In this
147 case, the subtree is automatically deep copied and the tag name of its root is
148 updated to match the attribute name:</p>
149 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"yet_another_child"</span><span class="p">)</span>
150 <span class="gp">&gt;&gt;&gt; </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>
151 <span class="gp">&gt;&gt;&gt; </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>
152 <span class="go">new_child</span>
153 <span class="gp">&gt;&gt;&gt; </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>
154 <span class="go">yet_another_child</span>
155
156 <span class="gp">&gt;&gt;&gt; </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="s">"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="s">"y"</span><span class="p">)</span> <span class="p">]</span>
157 <span class="gp">&gt;&gt;&gt; </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>
158 <span class="go">['y', 'y']</span>
159 </pre></div>
160 <p>The latter is a short form for operations on the full slice:</p>
161 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"y"</span><span class="p">)</span> <span class="p">]</span>
162 <span class="gp">&gt;&gt;&gt; </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>
163 <span class="go">['y']</span>
164 </pre></div>
165 <p>You can also replace children that way:</p>
166 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"child"</span><span class="p">)</span>
167 <span class="gp">&gt;&gt;&gt; </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="s">"child"</span><span class="p">)</span>
168 <span class="gp">&gt;&gt;&gt; </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="s">"child"</span><span class="p">)</span>
169
170 <span class="gp">&gt;&gt;&gt; </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="s">"new_child"</span><span class="p">)</span>
171 <span class="gp">&gt;&gt;&gt; </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="s">"sub"</span><span class="p">)</span>
172
173 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">child</span> <span class="o">=</span> <span class="n">el</span>
174 <span class="gp">&gt;&gt;&gt; </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>
175 <span class="go">sub</span>
176
177 <span class="gp">&gt;&gt;&gt; </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>
178 <span class="gp">&gt;&gt;&gt; </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>
179 <span class="go">sub</span>
180 </pre></div>
181 <p>Note that special care must be taken when changing the tag name of an element:</p>
182 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
183 <span class="go">b</span>
184 <span class="gp">&gt;&gt;&gt; </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="s">"notB"</span>
185 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">b</span>
186 <span class="gt">Traceback (most recent call last):</span>
187   <span class="c">...</span>
188 <span class="gr">AttributeError: no such child</span>: <span class="n">b</span>
189 <span class="gp">&gt;&gt;&gt; </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>
190 <span class="go">notB</span>
191 </pre></div>
192 </div>
193 <div class="section" id="creating-objectify-trees">
194 <h2>Creating objectify trees</h2>
195 <p>As with <tt class="docutils literal">lxml.etree</tt>, you can either create an <tt class="docutils literal">objectify</tt> tree by
196 parsing an XML document or by building one from scratch.  To parse a
197 document, just use the <tt class="docutils literal">parse()</tt> or <tt class="docutils literal">fromstring()</tt> functions of
198 the module:</p>
199 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">fileobject</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">(</span><span class="s">'&lt;test/&gt;'</span><span class="p">)</span>
200
201 <span class="gp">&gt;&gt;&gt; </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>
202 <span class="gp">&gt;&gt;&gt; </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>
203 <span class="go">True</span>
204
205 <span class="gp">&gt;&gt;&gt; </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="s">'&lt;test/&gt;'</span><span class="p">)</span>
206 <span class="gp">&gt;&gt;&gt; </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>
207 <span class="go">True</span>
208 </pre></div>
209 <p>To build a new tree in memory, <tt class="docutils literal">objectify</tt> replicates the standard
210 factory function <tt class="docutils literal">Element()</tt> from <tt class="docutils literal">lxml.etree</tt>:</p>
211 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"new"</span><span class="p">)</span>
212 <span class="gp">&gt;&gt;&gt; </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>
213 <span class="go">True</span>
214 </pre></div>
215 <p>After creating such an Element, you can use the <a class="reference external" href="tutorial.html#the-element-class">usual API</a> of
216 lxml.etree to add SubElements to the tree:</p>
217 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"newchild"</span><span class="p">,</span> <span class="n">attr</span><span class="o">=</span><span class="s">"value"</span><span class="p">)</span>
218 </pre></div>
219 <p>New subelements will automatically inherit the objectify behaviour
220 from their tree.  However, all independent elements that you create
221 through the <tt class="docutils literal">Element()</tt> factory of lxml.etree (instead of objectify)
222 will not support the <tt class="docutils literal">objectify</tt> API by themselves:</p>
223 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"sub"</span><span class="p">)</span>
224 <span class="gp">&gt;&gt;&gt; </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>
225 <span class="go">True</span>
226
227 <span class="gp">&gt;&gt;&gt; </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="s">"new"</span><span class="p">)</span>
228 <span class="gp">&gt;&gt;&gt; </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>
229 <span class="go">False</span>
230 </pre></div>
231 </div>
232 <div class="section" id="tree-generation-with-the-e-factory">
233 <h2>Tree generation with the E-factory</h2>
234 <p>To simplify the generation of trees even further, you can use the E-factory:</p>
235 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">E</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">E</span>
236 <span class="gp">&gt;&gt;&gt; </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>
237 <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>
238 <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.1</span><span class="p">),</span>
239 <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>
240 <span class="gp">... </span>  <span class="n">E</span><span class="o">.</span><span class="n">d</span><span class="p">(</span><span class="s">"how"</span><span class="p">,</span> <span class="n">tell</span><span class="o">=</span><span class="s">"me"</span><span class="p">)</span>
241 <span class="gp">... </span><span class="p">)</span>
242
243 <span class="gp">&gt;&gt;&gt; </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>
244 <span class="go">&lt;root xmlns:py="http://codespeak.net/lxml/objectify/pytype"&gt;</span>
245 <span class="go">  &lt;a py:pytype="int"&gt;5&lt;/a&gt;</span>
246 <span class="go">  &lt;b py:pytype="float"&gt;6.1&lt;/b&gt;</span>
247 <span class="go">  &lt;c py:pytype="bool"&gt;true&lt;/c&gt;</span>
248 <span class="go">  &lt;d py:pytype="str" tell="me"&gt;how&lt;/d&gt;</span>
249 <span class="go">&lt;/root&gt;</span>
250 </pre></div>
251 <p>This allows you to write up a specific language in tags:</p>
252 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
253 <span class="gp">&gt;&gt;&gt; </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>
254 <span class="gp">&gt;&gt;&gt; </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="s">"how-many"</span><span class="p">)</span>
255
256 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span> <span class="o">=</span> <span class="n">ROOT</span><span class="p">(</span>
257 <span class="gp">... </span>  <span class="n">TITLE</span><span class="p">(</span><span class="s">"The title"</span><span class="p">),</span>
258 <span class="gp">... </span>  <span class="n">HOWMANY</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
259 <span class="gp">... </span><span class="p">)</span>
260
261 <span class="gp">&gt;&gt;&gt; </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>
262 <span class="go">&lt;root xmlns:py="http://codespeak.net/lxml/objectify/pytype"&gt;</span>
263 <span class="go">  &lt;title py:pytype="str"&gt;The title&lt;/title&gt;</span>
264 <span class="go">  &lt;how-many py:pytype="int"&gt;5&lt;/how-many&gt;</span>
265 <span class="go">&lt;/root&gt;</span>
266 </pre></div>
267 <p><tt class="docutils literal">objectify.E</tt> is an instance of <tt class="docutils literal">objectify.ElementMaker</tt>.  By default, it
268 creates pytype annotated Elements without a namespace.  You can switch off the
269 pytype annotation by passing False to the <tt class="docutils literal">annotate</tt> keyword argument of the
270 constructor.  You can also pass a default namespace and an <tt class="docutils literal">nsmap</tt>:</p>
271 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
272 <span class="gp">... </span>          <span class="n">namespace</span><span class="o">=</span><span class="s">"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="s">"http://my/ns"</span><span class="p">})</span>
273
274 <span class="gp">&gt;&gt;&gt; </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>
275
276 <span class="gp">&gt;&gt;&gt; </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>
277 <span class="go">&lt;root xmlns="http://my/ns"&gt;</span>
278 <span class="go">  &lt;someint&gt;2&lt;/someint&gt;</span>
279 <span class="go">&lt;/root&gt;</span>
280 </pre></div>
281 </div>
282 <div class="section" id="namespace-handling">
283 <h2>Namespace handling</h2>
284 <p>During tag lookups, namespaces are handled mostly behind the scenes.
285 If you access a child of an Element without specifying a namespace,
286 the lookup will use the namespace of the parent:</p>
287 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}root"</span><span class="p">)</span>
288 <span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}b"</span><span class="p">)</span>
289 <span class="gp">&gt;&gt;&gt; </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="s">"{http://other/}c"</span><span class="p">)</span>
290
291 <span class="gp">&gt;&gt;&gt; </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>
292 <span class="go">{http://ns/}b</span>
293 </pre></div>
294 <p>Note that the <tt class="docutils literal">SubElement()</tt> factory of <tt class="docutils literal">lxml.etree</tt> does not
295 inherit any namespaces when creating a new subelement.  Element
296 creation must be explicit about the namespace, and is simplified
297 through the E-factory as described above.</p>
298 <p>Lookups, however, inherit namespaces implicitly:</p>
299 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
300 <span class="go">{http://ns/}b</span>
301
302 <span class="gp">&gt;&gt;&gt; </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>
303 <span class="gt">Traceback (most recent call last):</span>
304     <span class="o">...</span>
305 <span class="gr">AttributeError: no such child</span>: <span class="n">{http://ns/}c</span>
306 </pre></div>
307 <p>To access an element in a different namespace than its parent, you can
308 use <tt class="docutils literal">getattr()</tt>:</p>
309 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"{http://other/}c"</span><span class="p">)</span>
310 <span class="gp">&gt;&gt;&gt; </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>
311 <span class="go">{http://other/}c</span>
312 </pre></div>
313 <p>For convenience, there is also a quick way through item access:</p>
314 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">root</span><span class="p">[</span><span class="s">"{http://other/}c"</span><span class="p">]</span>
315 <span class="gp">&gt;&gt;&gt; </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>
316 <span class="go">{http://other/}c</span>
317 </pre></div>
318 <p>The same approach must be used to access children with tag names that are not
319 valid Python identifiers:</p>
320 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}tag-name"</span><span class="p">)</span>
321 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
322 <span class="go">{http://ns/}tag-name</span>
323
324 <span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}new-element"</span><span class="p">)</span>
325 <span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}child"</span><span class="p">)</span>
326 <span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}child"</span><span class="p">)</span>
327 <span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}child"</span><span class="p">)</span>
328
329 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="p">[</span><span class="s">"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>
330 <span class="gp">&gt;&gt;&gt; </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="s">"tag-name"</span><span class="p">]))</span>
331 <span class="go">2</span>
332 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
333 <span class="go">{http://ns/}tag-name</span>
334
335 <span class="gp">&gt;&gt;&gt; </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="s">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">child</span><span class="p">))</span>
336 <span class="go">3</span>
337 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"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>
338 <span class="go">{http://ns/}child</span>
339 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"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>
340 <span class="go">{http://ns/}child</span>
341 </pre></div>
342 <p>or for names that have a special meaning in lxml.objectify:</p>
343 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"&lt;root&gt;&lt;text&gt;TEXT&lt;/text&gt;&lt;/root&gt;"</span><span class="p">)</span>
344
345 <span class="gp">&gt;&gt;&gt; </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>
346 <span class="gt">Traceback (most recent call last):</span>
347   <span class="c">...</span>
348 <span class="gr">AttributeError</span>: <span class="n">'NoneType' object has no attribute 'text'</span>
349
350 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"text"</span><span class="p">]</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
351 <span class="go">TEXT</span>
352 </pre></div>
353 </div>
354 </div>
355 <div class="section" id="asserting-a-schema">
356 <h1>Asserting a Schema</h1>
357 <p>When dealing with XML documents from different sources, you will often
358 require them to follow a common schema.  In lxml.objectify, this
359 directly translates to enforcing a specific object tree, i.e. expected
360 object attributes are ensured to be there and to have the expected
361 type.  This can easily be achieved through XML Schema validation at
362 parse time.  Also see the <a class="reference external" href="validation.html">documentation on validation</a> on this
363 topic.</p>
364 <p>First of all, we need a parser that knows our schema, so let's say we
365 parse the schema from a file-like object (or file or filename):</p>
366 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
367 <span class="gp">... </span><span class="s">  &lt;xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"&gt;</span>
368 <span class="gp">... </span><span class="s">    &lt;xsd:element name="a" type="AType"/&gt;</span>
369 <span class="gp">... </span><span class="s">    &lt;xsd:complexType name="AType"&gt;</span>
370 <span class="gp">... </span><span class="s">      &lt;xsd:sequence&gt;</span>
371 <span class="gp">... </span><span class="s">        &lt;xsd:element name="b" type="xsd:string" /&gt;</span>
372 <span class="gp">... </span><span class="s">      &lt;/xsd:sequence&gt;</span>
373 <span class="gp">... </span><span class="s">    &lt;/xsd:complexType&gt;</span>
374 <span class="gp">... </span><span class="s">  &lt;/xsd:schema&gt;</span>
375 <span class="gp">... </span><span class="s">'''</span><span class="p">)</span>
376 <span class="gp">&gt;&gt;&gt; </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>
377 </pre></div>
378 <p>When creating the validating parser, we must make sure it <a class="reference external" href="#advance-element-class-lookup">returns
379 objectify trees</a>.  This is best done with the <tt class="docutils literal">makeparser()</tt>
380 function:</p>
381 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
382 </pre></div>
383 <p>Now we can use it to parse a valid document:</p>
384 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">xml</span> <span class="o">=</span> <span class="s">"&lt;a&gt;&lt;b&gt;test&lt;/b&gt;&lt;/a&gt;"</span>
385 <span class="gp">&gt;&gt;&gt; </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>
386
387 <span class="gp">&gt;&gt;&gt; </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>
388 <span class="go">test</span>
389 </pre></div>
390 <p>Or an invalid document:</p>
391 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">xml</span> <span class="o">=</span> <span class="s">"&lt;a&gt;&lt;b&gt;test&lt;/b&gt;&lt;c/&gt;&lt;/a&gt;"</span>
392 <span class="gp">&gt;&gt;&gt; </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>
393 <span class="gt">Traceback (most recent call last):</span>
394 <span class="gr">lxml.etree.XMLSyntaxError: Element 'c'</span>: <span class="n">This element is not expected.</span>
395 </pre></div>
396 <p>Note that the same works for parse-time DTD validation, except that
397 DTDs do not support any data types by design.</p>
398 </div>
399 <div class="section" id="objectpath">
400 <h1>ObjectPath</h1>
401 <p>For both convenience and speed, objectify supports its own path language,
402 represented by the <tt class="docutils literal">ObjectPath</tt> class:</p>
403 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}root"</span><span class="p">)</span>
404 <span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}b"</span><span class="p">)</span>
405 <span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}c"</span><span class="p">)</span>
406 <span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}b"</span><span class="p">)</span>
407 <span class="gp">&gt;&gt;&gt; </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="s">"{http://other/}d"</span><span class="p">)</span>
408
409 <span class="gp">&gt;&gt;&gt; </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="s">"root.b.c"</span><span class="p">)</span>
410 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
411 <span class="go">root.b.c</span>
412 <span class="gp">&gt;&gt;&gt; </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>
413 <span class="go">True</span>
414 <span class="gp">&gt;&gt;&gt; </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>
415 <span class="go">{http://ns/}c</span>
416
417 <span class="gp">&gt;&gt;&gt; </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="s">"root.b.c"</span><span class="p">)</span>
418 <span class="gp">&gt;&gt;&gt; </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>
419 <span class="go">{http://ns/}c</span>
420
421 <span class="gp">&gt;&gt;&gt; </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="s">"root.{http://other/}d"</span><span class="p">)</span>
422 <span class="gp">&gt;&gt;&gt; </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>
423 <span class="go">{http://other/}d</span>
424
425 <span class="gp">&gt;&gt;&gt; </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="s">"root.{not}there"</span><span class="p">)</span>
426 <span class="gp">&gt;&gt;&gt; </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>
427 <span class="gt">Traceback (most recent call last):</span>
428   <span class="c">...</span>
429 <span class="gr">AttributeError: no such child</span>: <span class="n">{not}there</span>
430
431 <span class="gp">&gt;&gt;&gt; </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="s">"{not}there"</span><span class="p">)</span>
432 <span class="gp">&gt;&gt;&gt; </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>
433 <span class="gt">Traceback (most recent call last):</span>
434   <span class="c">...</span>
435 <span class="gr">ValueError: root element does not match</span>: <span class="n">need {not}there, got {http://ns/}root</span>
436
437 <span class="gp">&gt;&gt;&gt; </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="s">"root.b[1]"</span><span class="p">)</span>
438 <span class="gp">&gt;&gt;&gt; </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://ns/}b</span>
440
441 <span class="gp">&gt;&gt;&gt; </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="s">"root.{http://ns/}b[1]"</span><span class="p">)</span>
442 <span class="gp">&gt;&gt;&gt; </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="go">{http://ns/}b</span>
444 </pre></div>
445 <p>Apart from strings, ObjectPath also accepts lists of path segments:</p>
446 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'root'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'c'</span><span class="p">])</span>
447 <span class="gp">&gt;&gt;&gt; </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>
448 <span class="go">{http://ns/}c</span>
449
450 <span class="gp">&gt;&gt;&gt; </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="s">'root'</span><span class="p">,</span> <span class="s">'{http://ns/}b[1]'</span><span class="p">])</span>
451 <span class="gp">&gt;&gt;&gt; </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>
452 <span class="go">{http://ns/}b</span>
453 </pre></div>
454 <p>You can also use relative paths starting with a '.' to ignore the actual root
455 element and only inherit its namespace:</p>
456 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">".b[1]"</span><span class="p">)</span>
457 <span class="gp">&gt;&gt;&gt; </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>
458 <span class="go">{http://ns/}b</span>
459
460 <span class="gp">&gt;&gt;&gt; </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="s">''</span><span class="p">,</span> <span class="s">'b[1]'</span><span class="p">])</span>
461 <span class="gp">&gt;&gt;&gt; </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>
462 <span class="go">{http://ns/}b</span>
463
464 <span class="gp">&gt;&gt;&gt; </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="s">".unknown[1]"</span><span class="p">)</span>
465 <span class="gp">&gt;&gt;&gt; </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>
466 <span class="gt">Traceback (most recent call last):</span>
467   <span class="c">...</span>
468 <span class="gr">AttributeError: no such child</span>: <span class="n">{http://ns/}unknown</span>
469
470 <span class="gp">&gt;&gt;&gt; </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="s">".{http://other/}unknown[1]"</span><span class="p">)</span>
471 <span class="gp">&gt;&gt;&gt; </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>
472 <span class="gt">Traceback (most recent call last):</span>
473   <span class="c">...</span>
474 <span class="gr">AttributeError: no such child</span>: <span class="n">{http://other/}unknown</span>
475 </pre></div>
476 <p>For convenience, a single dot represents the empty ObjectPath (identity):</p>
477 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"."</span><span class="p">)</span>
478 <span class="gp">&gt;&gt;&gt; </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>
479 <span class="go">{http://ns/}root</span>
480 </pre></div>
481 <p>ObjectPath objects can be used to manipulate trees:</p>
482 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"{http://ns/}root"</span><span class="p">)</span>
483
484 <span class="gp">&gt;&gt;&gt; </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="s">".some.child.{http://other/}unknown"</span><span class="p">)</span>
485 <span class="gp">&gt;&gt;&gt; </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>
486 <span class="go">False</span>
487 <span class="gp">&gt;&gt;&gt; </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>
488 <span class="gt">Traceback (most recent call last):</span>
489   <span class="c">...</span>
490 <span class="gr">AttributeError: no such child</span>: <span class="n">{http://ns/}some</span>
491
492 <span class="gp">&gt;&gt;&gt; </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="s">"my value"</span><span class="p">)</span> <span class="c"># creates children as necessary</span>
493 <span class="gp">&gt;&gt;&gt; </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>
494 <span class="go">True</span>
495 <span class="gp">&gt;&gt;&gt; </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>
496 <span class="go">my value</span>
497 <span class="gp">&gt;&gt;&gt; </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="s">"{http://other/}unknown"</span><span class="p">]</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
498 <span class="go">my value</span>
499
500 <span class="gp">&gt;&gt;&gt; </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>
501 <span class="go">1</span>
502 <span class="gp">&gt;&gt;&gt; </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="s">"my new value"</span><span class="p">)</span>
503 <span class="gp">&gt;&gt;&gt; </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>
504 <span class="go">2</span>
505 <span class="gp">&gt;&gt;&gt; </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>
506 <span class="go">['my value', 'my new value']</span>
507 </pre></div>
508 <p>As with attribute assignment, <tt class="docutils literal">setattr()</tt> accepts lists:</p>
509 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"v1"</span><span class="p">,</span> <span class="s">"v2"</span><span class="p">,</span> <span class="s">"v3"</span><span class="p">])</span>
510 <span class="gp">&gt;&gt;&gt; </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>
511 <span class="go">['v1', 'v2', 'v3']</span>
512 </pre></div>
513 <p>Note, however, that indexing is only supported in this context if the children
514 exist.  Indexing of non existing children will not extend or create a list of
515 such children but raise an exception:</p>
516 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">".{non}existing[1]"</span><span class="p">)</span>
517 <span class="gp">&gt;&gt;&gt; </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="s">"my value"</span><span class="p">)</span>
518 <span class="gt">Traceback (most recent call last):</span>
519   <span class="c">...</span>
520 <span class="gr">TypeError</span>: <span class="n">creating indexed path attributes is not supported</span>
521 </pre></div>
522 <p>It is worth noting that ObjectPath does not depend on the <tt class="docutils literal">objectify</tt> module
523 or the ObjectifiedElement implementation.  It can also be used in combination
524 with Elements from the normal lxml.etree API.</p>
525 </div>
526 <div class="section" id="python-data-types">
527 <h1>Python data types</h1>
528 <p>The objectify module knows about Python data types and tries its best to let
529 element content behave like them.  For example, they support the normal math
530 operators:</p>
531 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
532 <span class="gp">... </span>            <span class="s">"&lt;root&gt;&lt;a&gt;5&lt;/a&gt;&lt;b&gt;11&lt;/b&gt;&lt;c&gt;true&lt;/c&gt;&lt;d&gt;hoi&lt;/d&gt;&lt;/root&gt;"</span><span class="p">)</span>
533 <span class="gp">&gt;&gt;&gt; </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>
534 <span class="go">16</span>
535 <span class="gp">&gt;&gt;&gt; </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>
536 <span class="gp">&gt;&gt;&gt; </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>
537 <span class="go">16</span>
538
539 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">2</span>
540 <span class="gp">&gt;&gt;&gt; </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>
541 <span class="go">4</span>
542 <span class="gp">&gt;&gt;&gt; </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>
543 <span class="go">3</span>
544
545 <span class="gp">&gt;&gt;&gt; </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>
546 <span class="go">True</span>
547 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">c</span> <span class="o">=</span> <span class="bp">False</span>
548 <span class="gp">&gt;&gt;&gt; </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>
549 <span class="gp">... </span>    <span class="k">print</span><span class="p">(</span><span class="s">"false!"</span><span class="p">)</span>
550 <span class="go">false!</span>
551
552 <span class="gp">&gt;&gt;&gt; </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="s">" test !"</span><span class="p">)</span>
553 <span class="go">hoi test !</span>
554 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">d</span> <span class="o">=</span> <span class="s">"</span><span class="si">%s</span><span class="s"> - </span><span class="si">%s</span><span class="s">"</span>
555 <span class="gp">&gt;&gt;&gt; </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>
556 <span class="go">1234 - 12345</span>
557 </pre></div>
558 <p>However, data elements continue to provide the objectify API.  This means that
559 sequence operations such as <tt class="docutils literal">len()</tt>, slicing and indexing (e.g. of strings)
560 cannot behave as the Python types.  Like all other tree elements, they show
561 the normal slicing behaviour of objectify elements:</p>
562 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"&lt;root&gt;&lt;a&gt;test&lt;/a&gt;&lt;b&gt;toast&lt;/b&gt;&lt;/root&gt;"</span><span class="p">)</span>
563 <span class="gp">&gt;&gt;&gt; </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="s">' me'</span><span class="p">)</span> <span class="c"># behaves like a string, right?</span>
564 <span class="go">test me</span>
565 <span class="gp">&gt;&gt;&gt; </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="c"># but there's only one 'a' element!</span>
566 <span class="go">1</span>
567 <span class="gp">&gt;&gt;&gt; </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>
568 <span class="go">['a']</span>
569 <span class="gp">&gt;&gt;&gt; </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>
570 <span class="go">a</span>
571
572 <span class="gp">&gt;&gt;&gt; </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>
573 <span class="go">test</span>
574 <span class="gp">&gt;&gt;&gt; </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>
575 <span class="go">['test']</span>
576 </pre></div>
577 <p>If you need to run sequence operations on data types, you must ask the API for
578 the <em>real</em> Python value.  The string value is always available through the
579 normal ElementTree <tt class="docutils literal">.text</tt> attribute.  Additionally, all data classes
580 provide a <tt class="docutils literal">.pyval</tt> attribute that returns the value as plain Python type:</p>
581 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"&lt;root&gt;&lt;a&gt;test&lt;/a&gt;&lt;b&gt;5&lt;/b&gt;&lt;/root&gt;"</span><span class="p">)</span>
582 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">text</span>
583 <span class="go">'test'</span>
584 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">pyval</span>
585 <span class="go">'test'</span>
586
587 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">text</span>
588 <span class="go">'5'</span>
589 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">pyval</span>
590 <span class="go">5</span>
591 </pre></div>
592 <p>Note, however, that both attributes are read-only in objectify.  If you want
593 to change values, just assign them directly to the attribute:</p>
594 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"25"</span>
595 <span class="gt">Traceback (most recent call last):</span>
596   <span class="c">...</span>
597 <span class="gr">TypeError</span>: <span class="n">attribute 'text' of 'StringElement' objects is not writable</span>
598
599 <span class="gp">&gt;&gt;&gt; </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>
600 <span class="gt">Traceback (most recent call last):</span>
601   <span class="c">...</span>
602 <span class="gr">TypeError</span>: <span class="n">attribute 'pyval' of 'StringElement' objects is not writable</span>
603
604 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">25</span>
605 <span class="gp">&gt;&gt;&gt; </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>
606 <span class="go">25</span>
607 <span class="gp">&gt;&gt;&gt; </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>
608 <span class="go">25</span>
609 </pre></div>
610 <p>In other words, <tt class="docutils literal">objectify</tt> data elements behave like immutable Python
611 types.  You can replace them, but not modify them.</p>
612 <div class="section" id="recursive-tree-dump">
613 <h2>Recursive tree dump</h2>
614 <p>To see the data types that are currently used, you can call the module level
615 <tt class="docutils literal">dump()</tt> function that returns a recursive string representation for
616 elements:</p>
617 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"""</span>
618 <span class="gp">... </span><span class="s">&lt;root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;</span>
619 <span class="gp">... </span><span class="s">  &lt;a attr1="foo" attr2="bar"&gt;1&lt;/a&gt;</span>
620 <span class="gp">... </span><span class="s">  &lt;a&gt;1.2&lt;/a&gt;</span>
621 <span class="gp">... </span><span class="s">  &lt;b&gt;1&lt;/b&gt;</span>
622 <span class="gp">... </span><span class="s">  &lt;b&gt;true&lt;/b&gt;</span>
623 <span class="gp">... </span><span class="s">  &lt;c&gt;what?&lt;/c&gt;</span>
624 <span class="gp">... </span><span class="s">  &lt;d xsi:nil="true"/&gt;</span>
625 <span class="gp">... </span><span class="s">&lt;/root&gt;</span>
626 <span class="gp">... </span><span class="s">"""</span><span class="p">)</span>
627
628 <span class="gp">&gt;&gt;&gt; </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>
629 <span class="go">root = None [ObjectifiedElement]</span>
630 <span class="go">    a = 1 [IntElement]</span>
631 <span class="go">      * attr1 = 'foo'</span>
632 <span class="go">      * attr2 = 'bar'</span>
633 <span class="go">    a = 1.2 [FloatElement]</span>
634 <span class="go">    b = 1 [IntElement]</span>
635 <span class="go">    b = True [BoolElement]</span>
636 <span class="go">    c = 'what?' [StringElement]</span>
637 <span class="go">    d = None [NoneElement]</span>
638 <span class="go">      * xsi:nil = 'true'</span>
639 </pre></div>
640 <p>You can freely switch between different types for the same child:</p>
641 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"&lt;root&gt;&lt;a&gt;5&lt;/a&gt;&lt;/root&gt;"</span><span class="p">)</span>
642 <span class="gp">&gt;&gt;&gt; </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>
643 <span class="go">root = None [ObjectifiedElement]</span>
644 <span class="go">    a = 5 [IntElement]</span>
645
646 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="s">'nice string!'</span>
647 <span class="gp">&gt;&gt;&gt; </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>
648 <span class="go">root = None [ObjectifiedElement]</span>
649 <span class="go">    a = 'nice string!' [StringElement]</span>
650 <span class="go">      * py:pytype = 'str'</span>
651
652 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="bp">True</span>
653 <span class="gp">&gt;&gt;&gt; </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>
654 <span class="go">root = None [ObjectifiedElement]</span>
655 <span class="go">    a = True [BoolElement]</span>
656 <span class="go">      * py:pytype = 'bool'</span>
657
658 <span class="gp">&gt;&gt;&gt; </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>
659 <span class="gp">&gt;&gt;&gt; </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>
660 <span class="go">root = None [ObjectifiedElement]</span>
661 <span class="go">    a = 1 [IntElement]</span>
662 <span class="go">      * py:pytype = 'int'</span>
663 <span class="go">    a = 2 [IntElement]</span>
664 <span class="go">      * py:pytype = 'int'</span>
665 <span class="go">    a = 3 [IntElement]</span>
666 <span class="go">      * py:pytype = 'int'</span>
667
668 <span class="gp">&gt;&gt;&gt; </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>
669 <span class="gp">&gt;&gt;&gt; </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 = 1 [IntElement]</span>
672 <span class="go">      * py:pytype = 'int'</span>
673 <span class="go">    a = 2 [IntElement]</span>
674 <span class="go">      * py:pytype = 'int'</span>
675 <span class="go">    a = 3 [IntElement]</span>
676 <span class="go">      * py:pytype = 'int'</span>
677 </pre></div>
678 </div>
679 <div class="section" id="recursive-string-representation-of-elements">
680 <h2>Recursive string representation of elements</h2>
681 <p>Normally, elements use the standard string representation for str() that is
682 provided by lxml.etree.  You can enable a pretty-print representation for
683 objectify elements like this:</p>
684 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">objectify</span><span class="o">.</span><span class="n">enable_recursive_str</span><span class="p">()</span>
685
686 <span class="gp">&gt;&gt;&gt; </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="s">"""</span>
687 <span class="gp">... </span><span class="s">&lt;root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;</span>
688 <span class="gp">... </span><span class="s">  &lt;a attr1="foo" attr2="bar"&gt;1&lt;/a&gt;</span>
689 <span class="gp">... </span><span class="s">  &lt;a&gt;1.2&lt;/a&gt;</span>
690 <span class="gp">... </span><span class="s">  &lt;b&gt;1&lt;/b&gt;</span>
691 <span class="gp">... </span><span class="s">  &lt;b&gt;true&lt;/b&gt;</span>
692 <span class="gp">... </span><span class="s">  &lt;c&gt;what?&lt;/c&gt;</span>
693 <span class="gp">... </span><span class="s">  &lt;d xsi:nil="true"/&gt;</span>
694 <span class="gp">... </span><span class="s">&lt;/root&gt;</span>
695 <span class="gp">... </span><span class="s">"""</span><span class="p">)</span>
696
697 <span class="gp">&gt;&gt;&gt; </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>
698 <span class="go">root = None [ObjectifiedElement]</span>
699 <span class="go">    a = 1 [IntElement]</span>
700 <span class="go">      * attr1 = 'foo'</span>
701 <span class="go">      * attr2 = 'bar'</span>
702 <span class="go">    a = 1.2 [FloatElement]</span>
703 <span class="go">    b = 1 [IntElement]</span>
704 <span class="go">    b = True [BoolElement]</span>
705 <span class="go">    c = 'what?' [StringElement]</span>
706 <span class="go">    d = None [NoneElement]</span>
707 <span class="go">      * xsi:nil = 'true'</span>
708 </pre></div>
709 <p>This behaviour can be switched off in the same way:</p>
710 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
711 </pre></div>
712 </div>
713 </div>
714 <div class="section" id="how-data-types-are-matched">
715 <h1>How data types are matched</h1>
716 <p>Objectify uses two different types of Elements.  Structural Elements (or tree
717 Elements) represent the object tree structure.  Data Elements represent the
718 data containers at the leafs.  You can explicitly create tree Elements with
719 the <tt class="docutils literal">objectify.Element()</tt> factory and data Elements with the
720 <tt class="docutils literal">objectify.DataElement()</tt> factory.</p>
721 <p>When Element objects are created, lxml.objectify must determine which
722 implementation class to use for them.  This is relatively easy for tree
723 Elements and less so for data Elements.  The algorithm is as follows:</p>
724 <ol class="arabic simple">
725 <li>If an element has children, use the default tree class.</li>
726 <li>If an element is defined as xsi:nil, use the NoneElement class.</li>
727 <li>If a "Python type hint" attribute is given, use this to determine the element
728 class, see below.</li>
729 <li>If an XML Schema xsi:type hint is given, use this to determine the element
730 class, see below.</li>
731 <li>Try to determine the element class from the text content type by trial and
732 error.</li>
733 <li>If the element is a root node then use the default tree class.</li>
734 <li>Otherwise, use the default class for empty data classes.</li>
735 </ol>
736 <p>You can change the default classes for tree Elements and empty data Elements
737 at setup time.  The <tt class="docutils literal">ObjectifyElementClassLookup()</tt> call accepts two keyword
738 arguments, <tt class="docutils literal">tree_class</tt> and <tt class="docutils literal">empty_data_class</tt>, that determine the Element
739 classes used in these cases.  By default, <tt class="docutils literal">tree_class</tt> is a class called
740 <tt class="docutils literal">ObjectifiedElement</tt> and <tt class="docutils literal">empty_data_class</tt> is a <tt class="docutils literal">StringElement</tt>.</p>
741 <div class="section" id="type-annotations">
742 <h2>Type annotations</h2>
743 <p>The "type hint" mechanism deploys an XML attribute defined as
744 <tt class="docutils literal">lxml.objectify.PYTYPE_ATTRIBUTE</tt>.  It may contain any of the following
745 string values: int, long, float, str, unicode, NoneType:</p>
746 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
747 <span class="go">{http://codespeak.net/lxml/objectify/pytype}pytype</span>
748 <span class="gp">&gt;&gt;&gt; </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="s">'}'</span><span class="p">)</span>
749
750 <span class="gp">&gt;&gt;&gt; </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="s">"""</span><span class="se">\</span>
751 <span class="gp">... </span><span class="s">&lt;root xmlns:py='</span><span class="si">%s</span><span class="s">'&gt;</span>
752 <span class="gp">... </span><span class="s">  &lt;a py:pytype='str'&gt;5&lt;/a&gt;</span>
753 <span class="gp">... </span><span class="s">  &lt;b py:pytype='int'&gt;5&lt;/b&gt;</span>
754 <span class="gp">... </span><span class="s">  &lt;c py:pytype='NoneType' /&gt;</span>
755 <span class="gp">... </span><span class="s">&lt;/root&gt;</span>
756 <span class="gp">... </span><span class="s">"""</span> <span class="o">%</span> <span class="n">ns</span><span class="p">)</span>
757
758 <span class="gp">&gt;&gt;&gt; </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>
759 <span class="go">510</span>
760 <span class="gp">&gt;&gt;&gt; </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>
761 <span class="go">15</span>
762 <span class="gp">&gt;&gt;&gt; </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>
763 <span class="go">None</span>
764 </pre></div>
765 <p>Note that you can change the name and namespace used for this
766 attribute through the <tt class="docutils literal">set_pytype_attribute_tag(tag)</tt> module
767 function, in case your application ever needs to.  There is also a
768 utility function <tt class="docutils literal">annotate()</tt> that recursively generates this
769 attribute for the elements of a tree:</p>
770 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"&lt;root&gt;&lt;a&gt;test&lt;/a&gt;&lt;b&gt;5&lt;/b&gt;&lt;/root&gt;"</span><span class="p">)</span>
771 <span class="gp">&gt;&gt;&gt; </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>
772 <span class="go">root = None [ObjectifiedElement]</span>
773 <span class="go">    a = 'test' [StringElement]</span>
774 <span class="go">    b = 5 [IntElement]</span>
775
776 <span class="gp">&gt;&gt;&gt; </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>
777
778 <span class="gp">&gt;&gt;&gt; </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>
779 <span class="go">root = None [ObjectifiedElement]</span>
780 <span class="go">    a = 'test' [StringElement]</span>
781 <span class="go">      * py:pytype = 'str'</span>
782 <span class="go">    b = 5 [IntElement]</span>
783 <span class="go">      * py:pytype = 'int'</span>
784 </pre></div>
785 </div>
786 <div class="section" id="xml-schema-datatype-annotation">
787 <h2>XML Schema datatype annotation</h2>
788 <p>A second way of specifying data type information uses XML Schema types as
789 element annotations.  Objectify knows those that can be mapped to normal
790 Python types:</p>
791 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'''</span><span class="se">\</span>
792 <span class="gp">... </span><span class="s">   &lt;root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
793 <span class="gp">... </span><span class="s">         xmlns:xsd="http://www.w3.org/2001/XMLSchema"&gt;</span>
794 <span class="gp">... </span><span class="s">     &lt;d xsi:type="xsd:double"&gt;5&lt;/d&gt;</span>
795 <span class="gp">... </span><span class="s">     &lt;i xsi:type="xsd:int"   &gt;5&lt;/i&gt;</span>
796 <span class="gp">... </span><span class="s">     &lt;s xsi:type="xsd:string"&gt;5&lt;/s&gt;</span>
797 <span class="gp">... </span><span class="s">   &lt;/root&gt;</span>
798 <span class="gp">... </span><span class="s">   '''</span><span class="p">)</span>
799 <span class="gp">&gt;&gt;&gt; </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>
800 <span class="go">root = None [ObjectifiedElement]</span>
801 <span class="go">    d = 5.0 [FloatElement]</span>
802 <span class="go">      * xsi:type = 'xsd:double'</span>
803 <span class="go">    i = 5 [IntElement]</span>
804 <span class="go">      * xsi:type = 'xsd:int'</span>
805 <span class="go">    s = '5' [StringElement]</span>
806 <span class="go">      * xsi:type = 'xsd:string'</span>
807 </pre></div>
808 <p>Again, there is a utility function <tt class="docutils literal">xsiannotate()</tt> that recursively
809 generates the "xsi:type" attribute for the elements of a tree:</p>
810 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'''</span><span class="se">\</span>
811 <span class="gp">... </span><span class="s">   &lt;root&gt;&lt;a&gt;test&lt;/a&gt;&lt;b&gt;5&lt;/b&gt;&lt;c&gt;true&lt;/c&gt;&lt;/root&gt;</span>
812 <span class="gp">... </span><span class="s">   '''</span><span class="p">)</span>
813 <span class="gp">&gt;&gt;&gt; </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>
814 <span class="go">root = None [ObjectifiedElement]</span>
815 <span class="go">    a = 'test' [StringElement]</span>
816 <span class="go">    b = 5 [IntElement]</span>
817 <span class="go">    c = True [BoolElement]</span>
818
819 <span class="gp">&gt;&gt;&gt; </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>
820
821 <span class="gp">&gt;&gt;&gt; </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>
822 <span class="go">root = None [ObjectifiedElement]</span>
823 <span class="go">    a = 'test' [StringElement]</span>
824 <span class="go">      * xsi:type = 'xsd:string'</span>
825 <span class="go">    b = 5 [IntElement]</span>
826 <span class="go">      * xsi:type = 'xsd:integer'</span>
827 <span class="go">    c = True [BoolElement]</span>
828 <span class="go">      * xsi:type = 'xsd:boolean'</span>
829 </pre></div>
830 <p>Note, however, that <tt class="docutils literal">xsiannotate()</tt> will always use the first XML Schema
831 datatype that is defined for any given Python type, see also
832 <a class="reference internal" href="#defining-additional-data-classes">Defining additional data classes</a>.</p>
833 <p>The utility function <tt class="docutils literal">deannotate()</tt> can be used to get rid of 'py:pytype'
834 and/or 'xsi:type' information:</p>
835 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'''</span><span class="se">\</span>
836 <span class="gp">... </span><span class="s">&lt;root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
837 <span class="gp">... </span><span class="s">      xmlns:xsd="http://www.w3.org/2001/XMLSchema"&gt;</span>
838 <span class="gp">... </span><span class="s">  &lt;d xsi:type="xsd:double"&gt;5&lt;/d&gt;</span>
839 <span class="gp">... </span><span class="s">  &lt;i xsi:type="xsd:int"   &gt;5&lt;/i&gt;</span>
840 <span class="gp">... </span><span class="s">  &lt;s xsi:type="xsd:string"&gt;5&lt;/s&gt;</span>
841 <span class="gp">... </span><span class="s">&lt;/root&gt;'''</span><span class="p">)</span>
842 <span class="gp">&gt;&gt;&gt; </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>
843 <span class="gp">&gt;&gt;&gt; </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>
844 <span class="go">root = None [ObjectifiedElement]</span>
845 <span class="go">    d = 5.0 [FloatElement]</span>
846 <span class="go">      * xsi:type = 'xsd:double'</span>
847 <span class="go">      * py:pytype = 'float'</span>
848 <span class="go">    i = 5 [IntElement]</span>
849 <span class="go">      * xsi:type = 'xsd:int'</span>
850 <span class="go">      * py:pytype = 'int'</span>
851 <span class="go">    s = '5' [StringElement]</span>
852 <span class="go">      * xsi:type = 'xsd:string'</span>
853 <span class="go">      * py:pytype = 'str'</span>
854 <span class="gp">&gt;&gt;&gt; </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>
855 <span class="gp">&gt;&gt;&gt; </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>
856 <span class="go">root = None [ObjectifiedElement]</span>
857 <span class="go">    d = 5 [IntElement]</span>
858 <span class="go">    i = 5 [IntElement]</span>
859 <span class="go">    s = 5 [IntElement]</span>
860 </pre></div>
861 <p>You can control which type attributes should be de-annotated with the keyword
862 arguments 'pytype' (default: True) and 'xsi' (default: True).
863 <tt class="docutils literal">deannotate()</tt> can also remove 'xsi:nil' attributes by setting 'xsi_nil=True'
864 (default: False):</p>
865 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'''</span><span class="se">\</span>
866 <span class="gp">... </span><span class="s">&lt;root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
867 <span class="gp">... </span><span class="s">      xmlns:xsd="http://www.w3.org/2001/XMLSchema"&gt;</span>
868 <span class="gp">... </span><span class="s">  &lt;d xsi:type="xsd:double"&gt;5&lt;/d&gt;</span>
869 <span class="gp">... </span><span class="s">  &lt;i xsi:type="xsd:int"   &gt;5&lt;/i&gt;</span>
870 <span class="gp">... </span><span class="s">  &lt;s xsi:type="xsd:string"&gt;5&lt;/s&gt;</span>
871 <span class="gp">... </span><span class="s">  &lt;n xsi:nil="true"/&gt;</span>
872 <span class="gp">... </span><span class="s">&lt;/root&gt;'''</span><span class="p">)</span>
873 <span class="gp">&gt;&gt;&gt; </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>
874 <span class="gp">&gt;&gt;&gt; </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>
875 <span class="go">root = None [ObjectifiedElement]</span>
876 <span class="go">    d = 5.0 [FloatElement]</span>
877 <span class="go">      * xsi:type = 'xsd:double'</span>
878 <span class="go">      * py:pytype = 'float'</span>
879 <span class="go">    i = 5 [IntElement]</span>
880 <span class="go">      * xsi:type = 'xsd:int'</span>
881 <span class="go">      * py:pytype = 'int'</span>
882 <span class="go">    s = '5' [StringElement]</span>
883 <span class="go">      * xsi:type = 'xsd:string'</span>
884 <span class="go">      * py:pytype = 'str'</span>
885 <span class="go">    n = None [NoneElement]</span>
886 <span class="go">      * xsi:nil = 'true'</span>
887 <span class="go">      * py:pytype = 'NoneType'</span>
888 <span class="gp">&gt;&gt;&gt; </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>
889 <span class="gp">&gt;&gt;&gt; </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>
890 <span class="go">root = None [ObjectifiedElement]</span>
891 <span class="go">    d = 5 [IntElement]</span>
892 <span class="go">    i = 5 [IntElement]</span>
893 <span class="go">    s = 5 [IntElement]</span>
894 <span class="go">    n = u'' [StringElement]</span>
895 </pre></div>
896 <p>Note that <tt class="docutils literal">deannotate()</tt> does not remove the namespace declarations
897 of the <tt class="docutils literal">pytype</tt> namespace by default.  To remove them as well, and
898 to generally clean up the namespace declarations in the document
899 (usually when done with the whole processing), pass the option
900 <tt class="docutils literal">cleanup_namespaces=True</tt>.  This option is new in lxml 2.3.2.  In
901 older versions, use the function <tt class="docutils literal">lxml.etree.cleanup_namespaces()</tt>
902 instead.</p>
903 </div>
904 <div class="section" id="the-dataelement-factory">
905 <h2>The DataElement factory</h2>
906 <p>For convenience, the <tt class="docutils literal">DataElement()</tt> factory creates an Element with a
907 Python value in one step.  You can pass the required Python type name or the
908 XSI type name:</p>
909 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"root"</span><span class="p">)</span>
910 <span class="gp">&gt;&gt;&gt; </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="s">"int"</span><span class="p">)</span>
911 <span class="gp">&gt;&gt;&gt; </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>
912 <span class="go">root = None [ObjectifiedElement]</span>
913 <span class="go">    x = 5 [IntElement]</span>
914 <span class="go">      * py:pytype = 'int'</span>
915
916 <span class="gp">&gt;&gt;&gt; </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="s">"str"</span><span class="p">,</span> <span class="n">myattr</span><span class="o">=</span><span class="s">"someval"</span><span class="p">)</span>
917 <span class="gp">&gt;&gt;&gt; </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>
918 <span class="go">root = None [ObjectifiedElement]</span>
919 <span class="go">    x = '5' [StringElement]</span>
920 <span class="go">      * py:pytype = 'str'</span>
921 <span class="go">      * myattr = 'someval'</span>
922
923 <span class="gp">&gt;&gt;&gt; </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="s">"integer"</span><span class="p">)</span>
924 <span class="gp">&gt;&gt;&gt; </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>
925 <span class="go">root = None [ObjectifiedElement]</span>
926 <span class="go">    x = 5 [IntElement]</span>
927 <span class="go">      * py:pytype = 'int'</span>
928 <span class="go">      * xsi:type = 'xsd:integer'</span>
929 </pre></div>
930 <p>XML Schema types reside in the XML schema namespace thus <tt class="docutils literal">DataElement()</tt>
931 tries to correctly prefix the xsi:type attribute value for you:</p>
932 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"root"</span><span class="p">)</span>
933 <span class="gp">&gt;&gt;&gt; </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="s">"string"</span><span class="p">)</span>
934
935 <span class="gp">&gt;&gt;&gt; </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>
936 <span class="gp">&gt;&gt;&gt; </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>
937 <span class="go">&lt;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"&gt;</span>
938 <span class="go">  &lt;s xsi:type="xsd:string"&gt;5&lt;/s&gt;</span>
939 <span class="go">&lt;/root&gt;</span>
940 </pre></div>
941 <p><tt class="docutils literal">DataElement()</tt> uses a default nsmap to set these prefixes:</p>
942 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">'string'</span><span class="p">)</span>
943 <span class="gp">&gt;&gt;&gt; </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>
944 <span class="gp">&gt;&gt;&gt; </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
945 <span class="gp">&gt;&gt;&gt; </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>
946 <span class="gp">... </span>    <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%s</span><span class="s"> - </span><span class="si">%s</span><span class="s">"</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>
947 <span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
948 <span class="go">xsd - http://www.w3.org/2001/XMLSchema</span>
949 <span class="go">xsi - http://www.w3.org/2001/XMLSchema-instance</span>
950
951 <span class="gp">&gt;&gt;&gt; </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="s">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
952 <span class="go">xsd:string</span>
953 </pre></div>
954 <p>While you can set custom namespace prefixes, it is necessary to provide valid
955 namespace information if you choose to do so:</p>
956 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">'foo:string'</span><span class="p">,</span>
957 <span class="gp">... </span>         <span class="n">nsmap</span><span class="o">=</span><span class="p">{</span><span class="s">'foo'</span><span class="p">:</span> <span class="s">'http://www.w3.org/2001/XMLSchema'</span><span class="p">})</span>
958 <span class="gp">&gt;&gt;&gt; </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>
959 <span class="gp">&gt;&gt;&gt; </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
960 <span class="gp">&gt;&gt;&gt; </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>
961 <span class="gp">... </span>    <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%s</span><span class="s"> - </span><span class="si">%s</span><span class="s">"</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>
962 <span class="go">foo - http://www.w3.org/2001/XMLSchema</span>
963 <span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
964 <span class="go">xsi - http://www.w3.org/2001/XMLSchema-instance</span>
965
966 <span class="gp">&gt;&gt;&gt; </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="s">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
967 <span class="go">foo:string</span>
968 </pre></div>
969 <p>Note how lxml chose a default prefix for the XML Schema Instance
970 namespace.  We can override it as in the following example:</p>
971 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">'foo:string'</span><span class="p">,</span>
972 <span class="gp">... </span>         <span class="n">nsmap</span><span class="o">=</span><span class="p">{</span><span class="s">'foo'</span><span class="p">:</span> <span class="s">'http://www.w3.org/2001/XMLSchema'</span><span class="p">,</span>
973 <span class="gp">... </span>                <span class="s">'myxsi'</span><span class="p">:</span> <span class="s">'http://www.w3.org/2001/XMLSchema-instance'</span><span class="p">})</span>
974 <span class="gp">&gt;&gt;&gt; </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">&gt;&gt;&gt; </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
976 <span class="gp">&gt;&gt;&gt; </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="s">"</span><span class="si">%s</span><span class="s"> - </span><span class="si">%s</span><span class="s">"</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">myxsi - http://www.w3.org/2001/XMLSchema-instance</span>
980 <span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
981
982 <span class="gp">&gt;&gt;&gt; </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="s">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
983 <span class="go">foo:string</span>
984 </pre></div>
985 <p>Care must be taken if different namespace prefixes have been used for the same
986 namespace.  Namespace information gets merged to avoid duplicate definitions
987 when adding a new sub-element to a tree, but this mechanism does not adapt the
988 prefixes of attribute values:</p>
989 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"""&lt;root xmlns:schema="http://www.w3.org/2001/XMLSchema"/&gt;"""</span><span class="p">)</span>
990 <span class="gp">&gt;&gt;&gt; </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>
991 <span class="go">&lt;root xmlns:schema="http://www.w3.org/2001/XMLSchema"/&gt;</span>
992
993 <span class="gp">&gt;&gt;&gt; </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="s">"17"</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">"string"</span><span class="p">)</span>
994 <span class="gp">&gt;&gt;&gt; </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>
995 <span class="go">&lt;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"&gt;17&lt;/value&gt;</span>
996
997 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">s</span> <span class="o">=</span> <span class="n">s</span>
998 <span class="gp">&gt;&gt;&gt; </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>
999 <span class="go">&lt;root xmlns:schema="http://www.w3.org/2001/XMLSchema"&gt;</span>
1000 <span class="go">  &lt;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"&gt;17&lt;/s&gt;</span>
1001 <span class="go">&lt;/root&gt;</span>
1002 </pre></div>
1003 <p>It is your responsibility to fix the prefixes of attribute values if you
1004 choose to deviate from the standard prefixes.  A convenient way to do this for
1005 xsi:type attributes is to use the <tt class="docutils literal">xsiannotate()</tt> utility:</p>
1006 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
1007 <span class="gp">&gt;&gt;&gt; </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>
1008 <span class="go">&lt;root xmlns:schema="http://www.w3.org/2001/XMLSchema"&gt;</span>
1009 <span class="go">  &lt;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"&gt;17&lt;/s&gt;</span>
1010 <span class="go">&lt;/root&gt;</span>
1011 </pre></div>
1012 <p>Of course, it is discouraged to use different prefixes for one and the same
1013 namespace when building up an objectify tree.</p>
1014 </div>
1015 <div class="section" id="defining-additional-data-classes">
1016 <h2>Defining additional data classes</h2>
1017 <p>You can plug additional data classes into objectify that will be used in
1018 exactly the same way as the predefined types.  Data classes can either inherit
1019 from <tt class="docutils literal">ObjectifiedDataElement</tt> directly or from one of the specialised
1020 classes like <tt class="docutils literal">NumberElement</tt> or <tt class="docutils literal">BoolElement</tt>.  The numeric types require
1021 an initial call to the NumberElement method <tt class="docutils literal">self._setValueParser(function)</tt>
1022 to set their type conversion function (string -&gt; numeric Python type).  This
1023 call should be placed into the element <tt class="docutils literal">_init()</tt> method.</p>
1024 <p>The registration of data classes uses the <tt class="docutils literal">PyType</tt> class:</p>
1025 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
1026 <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>
1027 <span class="gp">... </span>        <span class="k">print</span><span class="p">(</span><span class="s">"Ho ho ho!"</span><span class="p">)</span>
1028
1029 <span class="gp">&gt;&gt;&gt; </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>
1030 <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="s">'24.12.'</span><span class="p">):</span>
1031 <span class="gp">... </span>        <span class="k">raise</span> <span class="ne">ValueError</span> <span class="c"># or TypeError</span>
1032
1033 <span class="gp">&gt;&gt;&gt; </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="s">'date'</span><span class="p">,</span> <span class="n">checkChristmasDate</span><span class="p">,</span> <span class="n">ChristmasDate</span><span class="p">)</span>
1034 </pre></div>
1035 <p>The PyType constructor takes a string type name, an (optional) callable type
1036 check and the custom data class.  If a type check is provided it must accept a
1037 string as argument and raise ValueError or TypeError if it cannot handle the
1038 string value.</p>
1039 <p>PyTypes are used if an element carries a <tt class="docutils literal">py:pytype</tt> attribute denoting its
1040 data type or, in absence of such an attribute, if the given type check callable
1041 does not raise a ValueError/TypeError exception when applied to the element
1042 text.</p>
1043 <p>If you want, you can also register this type under an XML Schema type name:</p>
1044 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">"date"</span><span class="p">,)</span>
1045 </pre></div>
1046 <p>XML Schema types will be considered if the element has an <tt class="docutils literal">xsi:type</tt>
1047 attribute that specifies its data type.  The line above binds the XSD type
1048 <tt class="docutils literal">date</tt> to the newly defined Python type.  Note that this must be done before
1049 the next step, which is to register the type.  Then you can use it:</p>
1050 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">xmas_type</span><span class="o">.</span><span class="n">register</span><span class="p">()</span>
1051
1052 <span class="gp">&gt;&gt;&gt; </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>
1053 <span class="gp">... </span>            <span class="s">"&lt;root&gt;&lt;a&gt;24.12.2000&lt;/a&gt;&lt;b&gt;12.24.2000&lt;/b&gt;&lt;/root&gt;"</span><span class="p">)</span>
1054 <span class="gp">&gt;&gt;&gt; </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>
1055 <span class="go">Ho ho ho!</span>
1056 <span class="gp">&gt;&gt;&gt; </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>
1057 <span class="gt">Traceback (most recent call last):</span>
1058   <span class="c">...</span>
1059 <span class="gr">AttributeError: no such child</span>: <span class="n">call_santa</span>
1060 </pre></div>
1061 <p>If you need to specify dependencies between the type check functions, you can
1062 pass a sequence of type names through the <tt class="docutils literal">before</tt> and <tt class="docutils literal">after</tt> keyword
1063 arguments of the <tt class="docutils literal">register()</tt> method.  The PyType will then try to register
1064 itself before or after the respective types, as long as they are currently
1065 registered.  Note that this only impacts the currently registered types at the
1066 time of registration.  Types that are registered later on will not care about
1067 the dependencies of already registered types.</p>
1068 <p>If you provide XML Schema type information, this will override the type check
1069 function defined above:</p>
1070 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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="s">'''</span><span class="se">\</span>
1071 <span class="gp">... </span><span class="s">   &lt;root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;</span>
1072 <span class="gp">... </span><span class="s">     &lt;a xsi:type="date"&gt;12.24.2000&lt;/a&gt;</span>
1073 <span class="gp">... </span><span class="s">   &lt;/root&gt;</span>
1074 <span class="gp">... </span><span class="s">   '''</span><span class="p">)</span>
1075 <span class="gp">&gt;&gt;&gt; </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>
1076 <span class="go">12.24.2000</span>
1077 <span class="gp">&gt;&gt;&gt; </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>
1078 <span class="go">Ho ho ho!</span>
1079 </pre></div>
1080 <p>To unregister a type, call its <tt class="docutils literal">unregister()</tt> method:</p>
1081 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
1082 <span class="go">Ho ho ho!</span>
1083 <span class="gp">&gt;&gt;&gt; </span><span class="n">xmas_type</span><span class="o">.</span><span class="n">unregister</span><span class="p">()</span>
1084 <span class="gp">&gt;&gt;&gt; </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>
1085 <span class="gt">Traceback (most recent call last):</span>
1086   <span class="c">...</span>
1087 <span class="gr">AttributeError: no such child</span>: <span class="n">call_santa</span>
1088 </pre></div>
1089 <p>Be aware, though, that this does not immediately apply to elements to which
1090 there already is a Python reference.  Their Python class will only be changed
1091 after all references are gone and the Python object is garbage collected.</p>
1092 </div>
1093 <div class="section" id="advanced-element-class-lookup">
1094 <h2>Advanced element class lookup</h2>
1095 <p>In some cases, the normal data class setup is not enough.  Being based
1096 on <tt class="docutils literal">lxml.etree</tt>, however, <tt class="docutils literal">lxml.objectify</tt> supports very
1097 fine-grained control over the Element classes used in a tree.  All you
1098 have to do is configure a different <a class="reference external" href="element_classes.html">class lookup</a> mechanism (or
1099 write one yourself).</p>
1100 <p>The first step for the setup is to create a new parser that builds
1101 objectify documents.  The objectify API is meant for data-centric XML
1102 (as opposed to document XML with mixed content).  Therefore, we
1103 configure the parser to let it remove whitespace-only text from the
1104 parsed document if it is not enclosed by an XML element.  Note that
1105 this alters the document infoset, so if you consider the removed
1106 spaces as data in your specific use case, you should go with a normal
1107 parser and just set the element class lookup.  Most applications,
1108 however, will work fine with the following setup:</p>
1109 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
1110 </pre></div>
1111 <p>What this does internally, is:</p>
1112 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
1113
1114 <span class="gp">&gt;&gt;&gt; </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>
1115 <span class="gp">&gt;&gt;&gt; </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>
1116 </pre></div>
1117 <p>If you want to change the lookup scheme, say, to get additional
1118 support for <a class="reference external" href="element_classes.html#namespace-class-lookup">namespace specific classes</a>, you can register the
1119 objectify lookup as a fallback of the namespace lookup.  In this case,
1120 however, you have to take care that the namespace classes inherit from
1121 <tt class="docutils literal">objectify.ObjectifiedElement</tt>, not only from the normal
1122 <tt class="docutils literal">lxml.etree.ElementBase</tt>, so that they support the <tt class="docutils literal">objectify</tt>
1123 API.  The above setup code then becomes:</p>
1124 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </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>
1125 <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>
1126 <span class="gp">&gt;&gt;&gt; </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>
1127 </pre></div>
1128 <p>See the documentation on <a class="reference external" href="element_classes.html">class lookup</a> schemes for more information.</p>
1129 </div>
1130 </div>
1131 <div class="section" id="what-is-different-from-lxml-etree">
1132 <h1>What is different from lxml.etree?</h1>
1133 <p>Such a different Element API obviously implies some side effects to the normal
1134 behaviour of the rest of the API.</p>
1135 <ul class="simple">
1136 <li>len(&lt;element&gt;) returns the sibling count, not the number of children of
1137 &lt;element&gt;. You can retrieve the number of children with the
1138 <tt class="docutils literal">countchildren()</tt> method.</li>
1139 <li>Iteration over elements does not yield the children, but the siblings.  You
1140 can access all children with the <tt class="docutils literal">iterchildren()</tt> method on elements or
1141 retrieve a list by calling the <tt class="docutils literal">getchildren()</tt> method.</li>
1142 <li>The find, findall and findtext methods require a different implementation
1143 based on ETXPath.  In <tt class="docutils literal">lxml.etree</tt>, they use a Python implementation based
1144 on the original iteration scheme.  This has the disadvantage that they may
1145 not be 100% backwards compatible, and the additional advantage that they now
1146 support any XPath expression.</li>
1147 </ul>
1148 </div>
1149 </div>
1150 <div class="footer">
1151 <hr class="footer" />
1152 Generated on: 2012-07-31.
1153
1154 </div>
1155 </body>
1156 </html>