2
2
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
4
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
5
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
6
6
<title>lxml.objectify</title>
7
7
<meta name="authors" content="Stefan Behnel Holger Joukl" />
8
8
<link rel="stylesheet" href="style.css" type="text/css" />
11
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#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></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#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="lxml2-menu"><li class="menu title"><a href="lxml2.html">What's new in lxml 2.0?</a><ul class="submenu"><li class="menu item"><a href="lxml2.html#changes-in-etree-and-objectify">Changes in etree and objectify</a></li><li class="menu item"><a href="lxml2.html#new-modules">New modules</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#threading">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#dtd">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#schematron">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></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#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#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#implementing-namespaces">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#subversion">Subversion</a></li><li class="menu item"><a href="build.html#setuptools">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#contributing-an-egg">Contributing an egg</a></li><li class="menu item"><a href="build.html#providing-newer-library-versions-on-mac-os-x">Providing newer library versions on Mac-OS 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 1-menu"><li class="menu title"><a href="changes-2.1.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></ul></div><h1 class="title">lxml.objectify</h1>
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#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></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#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="lxml2-menu"><li class="menu title"><a href="lxml2.html">What's new in lxml 2.0?</a><ul class="submenu"><li class="menu item"><a href="lxml2.html#changes-in-etree-and-objectify">Changes in etree and objectify</a></li><li class="menu item"><a href="lxml2.html#new-modules">New modules</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#threading">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#dtd">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#schematron">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></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#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#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#implementing-namespaces">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#subversion">Subversion</a></li><li class="menu item"><a href="build.html#setuptools">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#contributing-an-egg">Contributing an egg</a></li><li class="menu item"><a href="build.html#providing-newer-library-versions-on-mac-os-x">Providing newer library versions on Mac-OS 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 1 1-menu"><li class="menu title"><a href="changes-2.1.1.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></ul></div><h1 class="title">lxml.objectify</h1>
13
13
<table class="docinfo" frame="void" rules="none">
14
14
<col class="docinfo-name" />
15
15
<col class="docinfo-content" />
19
19
<br />Holger Joukl</td></tr>
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 custom Element implementation. The main idea
22
<p>lxml supports an alternative API similar to the <a class="reference" href="http://uche.ogbuji.net/tech/4suite/amara/">Amara</a> bindery or
23
<a class="reference" href="http://gnosis.cx/download/">gnosis.xml.objectify</a> through a custom Element implementation. The main idea
24
24
is to hide the usage of XML behind normal Python objects, sometimes referred
25
25
to as data-binding. It allows you to use XML as if you were dealing with a
26
26
normal Python object hierarchy.</p>
28
28
there are multiple children with the same name, slicing and indexing can be
29
29
used. Python data types are extracted from XML content automatically and made
30
30
available to the normal Python operators.</p>
31
<div class="contents topic" id="contents">
32
<p class="topic-title first">Contents</p>
31
<div class="contents topic">
32
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
33
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="#creating-objectify-trees" id="id2">Creating objectify trees</a></li>
36
<li><a class="reference internal" href="#element-access-through-object-attributes" id="id3">Element access through object attributes</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>
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>
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>
56
<li><a class="reference internal" href="#what-is-different-from-lxml-etree" id="id17">What is different from lxml.etree?</a></li>
34
<li><a class="reference" href="#the-lxml-objectify-api" id="id1" name="id1">The lxml.objectify API</a><ul>
35
<li><a class="reference" href="#creating-objectify-trees" id="id2" name="id2">Creating objectify trees</a></li>
36
<li><a class="reference" href="#element-access-through-object-attributes" id="id3" name="id3">Element access through object attributes</a></li>
37
<li><a class="reference" href="#tree-generation-with-the-e-factory" id="id4" name="id4">Tree generation with the E-factory</a></li>
38
<li><a class="reference" href="#namespace-handling" id="id5" name="id5">Namespace handling</a></li>
41
<li><a class="reference" href="#asserting-a-schema" id="id6" name="id6">Asserting a Schema</a></li>
42
<li><a class="reference" href="#objectpath" id="id7" name="id7">ObjectPath</a></li>
43
<li><a class="reference" href="#python-data-types" id="id8" name="id8">Python data types</a><ul>
44
<li><a class="reference" href="#recursive-tree-dump" id="id9" name="id9">Recursive tree dump</a></li>
45
<li><a class="reference" href="#recursive-string-representation-of-elements" id="id10" name="id10">Recursive string representation of elements</a></li>
48
<li><a class="reference" href="#how-data-types-are-matched" id="id11" name="id11">How data types are matched</a><ul>
49
<li><a class="reference" href="#type-annotations" id="id12" name="id12">Type annotations</a></li>
50
<li><a class="reference" href="#xml-schema-datatype-annotation" id="id13" name="id13">XML Schema datatype annotation</a></li>
51
<li><a class="reference" href="#the-dataelement-factory" id="id14" name="id14">The DataElement factory</a></li>
52
<li><a class="reference" href="#defining-additional-data-classes" id="id15" name="id15">Defining additional data classes</a></li>
53
<li><a class="reference" href="#advanced-element-class-lookup" id="id16" name="id16">Advanced element class lookup</a></li>
56
<li><a class="reference" href="#what-is-different-from-lxml-etree" id="id17" name="id17">What is different from lxml.etree?</a></li>
59
59
<p>To set up and use <tt class="docutils literal"><span class="pre">objectify</span></tt>, you need both the <tt class="docutils literal"><span class="pre">lxml.etree</span></tt>
65
65
is used, it should not be mixed with other element implementations
66
66
(such as trees parsed with <tt class="docutils literal"><span class="pre">lxml.etree</span></tt>), to avoid non-obvious
68
<p>The <a class="reference external" href="performance.html#lxml-objectify">benchmark page</a> has some hints on performance optimisation of
68
<p>The <a class="reference" href="performance.html#lxml-objectify">benchmark page</a> has some hints on performance optimisation of
69
69
code using lxml.objectify.</p>
70
70
<p>To make the doctests in this document look a little nicer, we also use
74
74
<p>Imported from within a doctest, this relieves us from caring about the exact
75
75
formatting of XML output.</p>
76
<div class="section" id="the-lxml-objectify-api">
77
<h1>The lxml.objectify API</h1>
77
<h1><a id="the-lxml-objectify-api" name="the-lxml-objectify-api">The lxml.objectify API</a></h1>
78
78
<p>In <tt class="docutils literal"><span class="pre">lxml.objectify</span></tt>, element trees provide an API that models the behaviour
79
79
of normal Python object trees as closely as possible.</p>
80
<div class="section" id="creating-objectify-trees">
81
<h2>Creating objectify trees</h2>
81
<h2><a id="creating-objectify-trees" name="creating-objectify-trees">Creating objectify trees</a></h2>
82
82
<p>As with <tt class="docutils literal"><span class="pre">lxml.etree</span></tt>, you can either create an <tt class="docutils literal"><span class="pre">objectify</span></tt> tree by
83
83
parsing an XML document or by building one from scratch. To parse a
84
84
document, just use the <tt class="docutils literal"><span class="pre">parse()</span></tt> or <tt class="docutils literal"><span class="pre">fromstring()</span></tt> functions of
99
99
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">obj_el</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
100
100
<span class="go">True</span>
102
<p>After creating such an Element, you can use the <a class="reference external" href="tutorial.html#the-element-class">usual API</a> of
102
<p>After creating such an Element, you can use the <a class="reference" href="tutorial.html#the-element-class">usual API</a> of
103
103
lxml.etree to add SubElements to the tree:</p>
104
104
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">child</span> <span class="o">=</span> <span class="n">etree</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>
116
116
<span class="go">False</span>
119
<div class="section" id="element-access-through-object-attributes">
120
<h2>Element access through object attributes</h2>
119
<div class="section">
120
<h2><a id="element-access-through-object-attributes" name="element-access-through-object-attributes">Element access through object attributes</a></h2>
121
121
<p>The main idea behind the <tt class="docutils literal"><span class="pre">objectify</span></tt> API is to hide XML element access
122
122
behind the usual object attribute access pattern. Asking an element for an
123
123
attribute will return the sequence of children with corresponding tag names:</p>
229
229
<span class="go">notB</span>
232
<div class="section" id="tree-generation-with-the-e-factory">
233
<h2>Tree generation with the E-factory</h2>
232
<div class="section">
233
<h2><a id="tree-generation-with-the-e-factory" name="tree-generation-with-the-e-factory">Tree generation with the E-factory</a></h2>
234
234
<p>To simplify the generation of trees even further, you can use the E-factory:</p>
235
235
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">E</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">E</span>
236
236
<span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">E</span><span class="o">.</span><span class="n">root</span><span class="p">(</span>
343
<div class="section" id="asserting-a-schema">
344
<h1>Asserting a Schema</h1>
343
<div class="section">
344
<h1><a id="asserting-a-schema" name="asserting-a-schema">Asserting a Schema</a></h1>
345
345
<p>When dealing with XML documents from different sources, you will often
346
346
require them to follow a common schema. In lxml.objectify, this
347
347
directly translates to enforcing a specific object tree, i.e. expected
348
348
object attributes are ensured to be there and to have the expected
349
349
type. This can easily be achieved through XML Schema validation at
350
parse time. Also see the <a class="reference external" href="validation.html">documentation on validation</a> on this
350
parse time. Also see the <a class="reference" href="validation.html">documentation on validation</a> on this
352
352
<p>First of all, we need a parser that knows our schema, so let's say we
353
353
parse the schema from a file-like object (or file or filename):</p>
363
363
<span class="gp">... </span><span class="s">'''</span><span class="p">)</span>
364
364
<span class="gp">>>> </span><span class="n">schema</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">XMLSchema</span><span class="p">(</span><span class="nb">file</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>
366
<p>When creating the validating parser, we must make sure it <a class="reference external" href="#advance-element-class-lookup">returns
366
<p>When creating the validating parser, we must make sure it <a class="reference" href="#advance-element-class-lookup">returns
367
367
objectify trees</a>. This is best done with the <tt class="docutils literal"><span class="pre">makeparser()</span></tt>
369
369
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">makeparser</span><span class="p">(</span><span class="n">schema</span> <span class="o">=</span> <span class="n">schema</span><span class="p">)</span>
384
384
<p>Note that the same works for parse-time DTD validation, except that
385
385
DTDs do not support any data types by design.</p>
387
<div class="section" id="objectpath">
387
<div class="section">
388
<h1><a id="objectpath" name="objectpath">ObjectPath</a></h1>
389
389
<p>For both convenience and speed, objectify supports its own path language,
390
390
represented by the <tt class="docutils literal"><span class="pre">ObjectPath</span></tt> class:</p>
391
391
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"{ns}root"</span><span class="p">)</span>
511
511
or the ObjectifiedElement implementation. It can also be used in combination
512
512
with Elements from the normal lxml.etree API.</p>
514
<div class="section" id="python-data-types">
515
<h1>Python data types</h1>
514
<div class="section">
515
<h1><a id="python-data-types" name="python-data-types">Python data types</a></h1>
516
516
<p>The objectify module knows about Python data types and tries its best to let
517
517
element content behave like them. For example, they support the normal math
598
598
<p>In other words, <tt class="docutils literal"><span class="pre">objectify</span></tt> data elements behave like immutable Python
599
599
types. You can replace them, but not modify them.</p>
600
<div class="section" id="recursive-tree-dump">
601
<h2>Recursive tree dump</h2>
600
<div class="section">
601
<h2><a id="recursive-tree-dump" name="recursive-tree-dump">Recursive tree dump</a></h2>
602
602
<p>To see the data types that are currently used, you can call the module level
603
603
<tt class="docutils literal"><span class="pre">dump()</span></tt> function that returns a recursive string representation for
664
664
<span class="go"> * py:pytype = 'int'</span>
667
<div class="section" id="recursive-string-representation-of-elements">
668
<h2>Recursive string representation of elements</h2>
667
<div class="section">
668
<h2><a id="recursive-string-representation-of-elements" name="recursive-string-representation-of-elements">Recursive string representation of elements</a></h2>
669
669
<p>Normally, elements use the standard string representation for str() that is
670
670
provided by lxml.etree. You can enable a pretty-print representation for
671
671
objectify elements like this:</p>
726
726
arguments, <tt class="docutils literal"><span class="pre">tree_class</span></tt> and <tt class="docutils literal"><span class="pre">empty_data_class</span></tt>, that determine the Element
727
727
classes used in these cases. By default, <tt class="docutils literal"><span class="pre">tree_class</span></tt> is a class called
728
728
<tt class="docutils literal"><span class="pre">ObjectifiedElement</span></tt> and <tt class="docutils literal"><span class="pre">empty_data_class</span></tt> is a <tt class="docutils literal"><span class="pre">StringElement</span></tt>.</p>
729
<div class="section" id="type-annotations">
730
<h2>Type annotations</h2>
729
<div class="section">
730
<h2><a id="type-annotations" name="type-annotations">Type annotations</a></h2>
731
731
<p>The "type hint" mechanism deploys an XML attribute defined as
732
732
<tt class="docutils literal"><span class="pre">lxml.objectify.PYTYPE_ATTRIBUTE</span></tt>. It may contain any of the following
733
733
string values: int, long, float, str, unicode, NoneType:</p>
818
818
<p>Note, however, that <tt class="docutils literal"><span class="pre">xsiannotate()</span></tt> will always use the first XML Schema
819
819
datatype that is defined for any given Python type, see also
820
<a class="reference internal" href="#defining-additional-data-classes">Defining additional data classes</a>.</p>
820
<a class="reference" href="#defining-additional-data-classes">Defining additional data classes</a>.</p>
821
821
<p>The utility function <tt class="docutils literal"><span class="pre">deannotate()</span></tt> can be used to get rid of 'py:pytype'
822
822
and/or 'xsi:type' information:</p>
823
823
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
958
958
<p>Of course, it is discouraged to use different prefixes for one and the same
959
959
namespace when building up an objectify tree.</p>
961
<div class="section" id="defining-additional-data-classes">
962
<h2>Defining additional data classes</h2>
961
<div class="section">
962
<h2><a id="defining-additional-data-classes" name="defining-additional-data-classes">Defining additional data classes</a></h2>
963
963
<p>You can plug additional data classes into objectify that will be used in
964
964
exactly the same way as the predefined types. Data classes can either inherit
965
965
from <tt class="docutils literal"><span class="pre">ObjectifiedDataElement</span></tt> directly or from one of the specialised
1036
1036
there already is a Python reference. Their Python class will only be changed
1037
1037
after all references are gone and the Python object is garbage collected.</p>
1039
<div class="section" id="advanced-element-class-lookup">
1040
<h2>Advanced element class lookup</h2>
1039
<div class="section">
1040
<h2><a id="advanced-element-class-lookup" name="advanced-element-class-lookup">Advanced element class lookup</a></h2>
1041
1041
<p>In some cases, the normal data class setup is not enough. Being based
1042
1042
on <tt class="docutils literal"><span class="pre">lxml.etree</span></tt>, however, <tt class="docutils literal"><span class="pre">lxml.objectify</span></tt> supports very
1043
1043
fine-grained control over the Element classes used in a tree. All you
1044
have to do is configure a different <a class="reference external" href="element_classes.html">class lookup</a> mechanism (or
1044
have to do is configure a different <a class="reference" href="element_classes.html">class lookup</a> mechanism (or
1045
1045
write one yourself).</p>
1046
1046
<p>The first step for the setup is to create a new parser that builds
1047
1047
objectify documents. The objectify API is meant for data-centric XML
1061
1061
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">set_element_class_lookup</span><span class="p">(</span><span class="n">lookup</span><span class="p">)</span>
1063
1063
<p>If you want to change the lookup scheme, say, to get additional
1064
support for <a class="reference external" href="element_classes.html#namespace-class-lookup">namespace specific classes</a>, you can register the
1064
support for <a class="reference" href="element_classes.html#namespace-class-lookup">namespace specific classes</a>, you can register the
1065
1065
objectify lookup as a fallback of the namespace lookup. In this case,
1066
1066
however, you have to take care that the namespace classes inherit from
1067
1067
<tt class="docutils literal"><span class="pre">objectify.ObjectifiedElement</span></tt>, not only from the normal
1071
1071
<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>
1072
1072
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">set_element_class_lookup</span><span class="p">(</span><span class="n">lookup</span><span class="p">)</span>
1074
<p>See the documentation on <a class="reference external" href="element_classes.html">class lookup</a> schemes for more information.</p>
1077
<div class="section" id="what-is-different-from-lxml-etree">
1078
<h1>What is different from lxml.etree?</h1>
1074
<p>See the documentation on <a class="reference" href="element_classes.html">class lookup</a> schemes for more information.</p>
1077
<div class="section">
1078
<h1><a id="what-is-different-from-lxml-etree" name="what-is-different-from-lxml-etree">What is different from lxml.etree?</a></h1>
1079
1079
<p>Such a different Element API obviously implies some side effects to the normal
1080
1080
behaviour of the rest of the API.</p>
1081
1081
<ul class="simple">
added
removed
doc/html/objectify.html
