~ubuntu-branches/ubuntu/oneiric/lxml/oneiric

<div class="sidemenu"><ul id="lxml-section"><li>lxml<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>Developing with lxml<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 foreign" 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>Extending lxml<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>Developing lxml<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 5-menu"><li class="menu title"><a href="changes-2.1.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></ul></div><h1 class="title">Using custom Element classes in lxml</h1>

lxml has very sophisticated support for custom Element classes. You can

provide your own classes for Elements and have lxml use them by default, for

all elements generated by a specific parser, for a specific tag name in a

specific namespace or for an exact element at a specific position in the tree.

<div class="sidemenu"><ul id="lxml-section"><li>lxml<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>Developing with lxml<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 foreign" 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><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>Extending lxml<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#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#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>Developing lxml<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#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 2 2-menu"><li class="menu title"><a href="changes-2.2.2.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">Using custom Element classes in lxml</h1>

lxml has very sophisticated support for custom Element classes. You

can provide your own classes for Elements and have lxml use them by

default for all elements generated by a specific parser, only for a

specific tag name in a specific namespace or even for an exact element

at a specific position in the tree.

Custom Elements must inherit from the <tt class="docutils literal">lxml.etree.ElementBase</tt> class, which

provides the Element interface for subclasses:

<div class="syntax"><pre>>>> from lxml import etree

>>> class HonkElement(etree.ElementBase):

>>> class honk(etree.ElementBase):

... def honking(self):

... return self.get('honking') == 'true'

... honking = property(honking)

</pre></div>

This defines a new Element class <tt class="docutils literal">HonkElement</tt> with a property <tt class="docutils literal">honking</tt>.

Note that you cannot (or rather must not) instantiate this class

yourself. lxml.etree will do that for you through its normal

ElementTree API. All you have to do is tell lxml which class to use

for which kind of Element. This is done through a class lookup

scheme, as described below.

<a id="contents" name="contents">Contents</a>

This defines a new Element class <tt class="docutils literal">honk</tt> with a property <tt class="docutils literal">honking</tt>.

The following document describes how you can make lxml.etree use these

custom Element classes.

Contents

<li><a class="reference" href="#element-initialization" id="id2" name="id2">Element initialization</a></li>

<li><a class="reference" href="#setting-up-a-class-lookup-scheme" id="id3" name="id3">Setting up a class lookup scheme</a><ul>

<li><a class="reference" href="#default-class-lookup" id="id4" name="id4">Default class lookup</a></li>

<li><a class="reference" href="#namespace-class-lookup" id="id5" name="id5">Namespace class lookup</a></li>

<li><a class="reference" href="#attribute-based-lookup" id="id6" name="id6">Attribute based lookup</a></li>

<li><a class="reference" href="#custom-element-class-lookup" id="id7" name="id7">Custom element class lookup</a></li>

<li><a class="reference" href="#tree-based-element-class-lookup-in-python" id="id8" name="id8">Tree based element class lookup in Python</a></li>

<li><a class="reference internal" href="#background-on-element-proxies" id="id2">Background on Element proxies</a></li>

<li><a class="reference internal" href="#element-initialization" id="id3">Element initialization</a></li>

<li><a class="reference internal" href="#setting-up-a-class-lookup-scheme" id="id4">Setting up a class lookup scheme</a><ul>

<li><a class="reference internal" href="#default-class-lookup" id="id5">Default class lookup</a></li>

<li><a class="reference internal" href="#namespace-class-lookup" id="id6">Namespace class lookup</a></li>

<li><a class="reference internal" href="#attribute-based-lookup" id="id7">Attribute based lookup</a></li>

<li><a class="reference internal" href="#custom-element-class-lookup" id="id8">Custom element class lookup</a></li>

<li><a class="reference internal" href="#tree-based-element-class-lookup-in-python" id="id9">Tree based element class lookup in Python</a></li>

</ul>

</li>

<li><a class="reference" href="#id1" id="id9" name="id9">Implementing namespaces</a></li>

<li><a class="reference internal" href="#generating-xml-with-custom-classes" id="id10">Generating XML with custom classes</a></li>

<li><a class="reference internal" href="#id1" id="id11">Implementing namespaces</a></li>

</ul>

</div>

<h1><a id="element-initialization" name="element-initialization">Element initialization</a></h1>

There is one thing to know up front. Element classes must not have a

constructor, neither must there be any internal state (except for the data

stored in the underlying XML tree). Element instances are created and garbage

collected at need, so there is no way to predict when and how often a

constructor would be called. Even worse, when the <tt class="docutils literal">__init__</tt> method is

called, the object may not even be initialized yet to represent the XML tag,

so there is not much use in providing an <tt class="docutils literal">__init__</tt> method in subclasses.

<h1>Background on Element proxies</h1>

Being based on libxml2, lxml.etree holds the entire XML tree in a C

structure. To communicate with Python code, it creates Python proxy

objects for the XML elements on demand.

</blockquote>

The mapping between C elements and Python Element classes is

completely configurable. When you ask lxml.etree for an Element by

using its API, it will instantiate your classes for you. All you have

to do is tell lxml which class to use for which kind of Element. This

is done through a class lookup scheme, as described in the sections

below.

</div>

<h1>Element initialization</h1>

There is one thing to know up front. Element classes must not have

an <tt class="docutils literal">__init___</tt> or <tt class="docutils literal">__new__</tt> method. There should not be any

internal state either, except for the data stored in the underlying

XML tree. Element instances are created and garbage collected at

need, so there is no way to predict when and how often a proxy is

created for them. Even worse, when the <tt class="docutils literal">__init__</tt> method is called,

the object is not even initialized yet to represent the XML tag, so

there is not much use in providing an <tt class="docutils literal">__init__</tt> method in

subclasses.

Most use cases will not require any class initialisation, so you can content

yourself with skipping to the next section for now. However, if you really

need to set up your element class on instantiation, there is one possible way

children or verify and update attributes.

The semantics of <tt class="docutils literal">_init()</tt> are as follows:

<li>It is called at least once on element instantiation time. That is, when a

Python representation of the element is created by lxml. At that time, the

element object is completely initialized to represent a specific XML element

within the tree.</li>

<li>It is called once on Element class instantiation time. That is,

when a Python representation of the element is created by lxml. At

that time, the element object is completely initialized to represent

a specific XML element within the tree.</li>

<li>The method has complete access to the XML tree. Modifications can be done

in exactly the same way as anywhere else in the program.</li>

<li>Python representations of elements may be created multiple times during the

lifetime of an XML element in the underlying tree. The <tt class="docutils literal">_init()</tt> code

lifetime of an XML element in the underlying C tree. The <tt class="docutils literal">_init()</tt> code

provided by subclasses must take special care by itself that multiple

executions either are harmless or that they are prevented by some kind of

flag in the XML tree. The latter can be achieved by modifying an attribute

you write here as its exceptions may turn up in various unexpected places.</li>

</ul>

</div>

<h1><a id="setting-up-a-class-lookup-scheme" name="setting-up-a-class-lookup-scheme">Setting up a class lookup scheme</a></h1>

100

<h1>Setting up a class lookup scheme</h1>

101

The first thing to do when deploying custom element classes is to register a

102

class lookup scheme on a parser. lxml.etree provides quite a number of

different schemes, that also support class lookup based on namespaces or

103

different schemes that also support class lookup based on namespaces or

104

attribute values. Most lookups support fallback chaining, which allows the

105

next lookup mechanism to take over when the previous one fails to find a

106

class.

For example, setting a different default element class for a parser works as

follows:

<div class="syntax"><pre>>>> parser_lookup = etree.ElementDefaultClassLookup(element=HonkElement)

107

For example, setting the <tt class="docutils literal">honk</tt> Element as a default element class

108

for a parser works as follows:

109

110

>>> parser = etree.XMLParser()

111

>>> parser.set_element_class_lookup(parser_lookup)

112

</pre></div>

114

does not know about your specialised parser and creates a new document that

115

deploys the default parser:

116

<div class="syntax"><pre>>>> el = etree.Element("root")

>>> print(isinstance(el, HonkElement))

117

118

False

100

119

</pre></div>

101

You should therefore avoid using this function in code that uses custom

102

classes. The <tt class="docutils literal">makeelement()</tt> method of parsers provides a simple

103

replacement:

120

You should therefore avoid using this factory function in code that

121

uses custom classes. The <tt class="docutils literal">makeelement()</tt> method of parsers provides

122

a simple replacement:

104

123

<div class="syntax"><pre>>>> el = parser.makeelement("root")

105

124

106

125

True

107

126

</pre></div>

108

127

If you use a parser at the module level, you can easily redirect a module

109

128

level <tt class="docutils literal">Element()</tt> factory to the parser method by adding code like this:

110

<div class="syntax"><pre>>>> MODULE_PARSER = etree.XMLParser()

111

>>> Element = MODULE_PARSER.makeelement

129

<div class="syntax"><pre>>>> module_level_parser = etree.XMLParser()

130

>>> Element = module_level_parser.makeelement

112

131

</pre></div>

113

132

While the <tt class="docutils literal">XML()</tt> and <tt class="docutils literal">HTML()</tt> factories also depend on the default

114

133

parser, you can pass them a different parser as second argument:

115

134

<div class="syntax"><pre>>>> element = etree.XML("<test/>")

116

>>> print(isinstance(element, HonkElement))

135

117

136

False

118

137

119

138

>>> element = etree.XML("<test/>", parser)

120

139

121

140

True

122

141

</pre></div>

123

142

Whenever you create a document with a parser, it will inherit the lookup

124

143

scheme and all subsequent element instantiations for this document will use

125

144

it:

126

145

<div class="syntax"><pre>>>> element = etree.fromstring("<test/>", parser)

127

146

128

147

True

129

148

>>> el = etree.SubElement(element, "subel")

130

149

131

150

True

132

151

</pre></div>

133

For small projects, you may also consider setting a lookup scheme on the

134

default parser. To avoid interfering with other modules, however, it is

135

usually a better idea to use a dedicated parser for each module (or a parser

136

pool when using threads) and then register the required lookup scheme only for

152

For testing code in the Python interpreter and for small projects, you

153

may also consider setting a lookup scheme on the default parser. To

154

avoid interfering with other modules, however, it is usually a better

155

idea to use a dedicated parser for each module (or a parser pool when

156

using threads) and then register the required lookup scheme only for

137

157

this parser.

138

139

<h2><a id="default-class-lookup" name="default-class-lookup">Default class lookup</a></h2>

158

159

<h2>Default class lookup</h2>

140

160

This is the most simple lookup mechanism. It always returns the default

141

161

element class. Consequently, no further fallbacks are supported, but this

142

scheme is a good fallback for other custom lookup mechanisms.

162

scheme is a nice fallback for other custom lookup mechanisms.

143

163

Usage:

144

164

<div class="syntax"><pre>>>> lookup = etree.ElementDefaultClassLookup()

145

165

>>> parser = etree.XMLParser()

151

171

the constructor. While it accepts classes for <tt class="docutils literal">element</tt>, <tt class="docutils literal">comment</tt> and

152

172

<tt class="docutils literal">pi</tt> nodes, most use cases will only override the element class:

153

173

154

174

155

175

False

156

176

157

>>> lookup = etree.ElementDefaultClassLookup(element=HonkElement)

177

158

178

159

179

160

180

>>> el = parser.makeelement("myelement")

161

181

162

182

True

163

183

>>> el.honking

164

184

False

169

189

True

170

190

</pre></div>

171

191

</div>

172

173

<h2><a id="namespace-class-lookup" name="namespace-class-lookup">Namespace class lookup</a></h2>

192

193

<h2>Namespace class lookup</h2>

174

194

This is an advanced lookup mechanism that supports namespace/tag-name specific

175

195

element classes. You can select it by calling:

176

196

177

197

>>> parser = etree.XMLParser()

178

198

179

199

</pre></div>

180

See the separate section on <a class="reference" href="#implementing-namespaces">implementing namespaces</a> below to learn how to

200

See the separate section on <a class="reference external" href="#implementing-namespaces">implementing namespaces</a> below to learn how to

181

201

make use of it.

182

202

This scheme supports a fallback mechanism that is used in the case where the

183

203

namespace is not found or no class was registered for the element name.

184

204

Normally, the default class lookup is used here. To change it, pass the

185

205

desired fallback lookup scheme to the constructor:

186

<div class="syntax"><pre>>>> fallback = etree.ElementDefaultClassLookup(element=HonkElement)

206

187

207

>>> lookup = etree.ElementNamespaceClassLookup(fallback)

188

208

189

209

</pre></div>

190

210

</div>

191

192

<h2><a id="attribute-based-lookup" name="attribute-based-lookup">Attribute based lookup</a></h2>

211

212

<h2>Attribute based lookup</h2>

193

213

This scheme uses a mapping from attribute values to classes. An attribute

194

214

name is set at initialisation time and is then used to find the corresponding

195

value. It is set up as follows:

196

<div class="syntax"><pre>>>> id_class_mapping = {} # maps attribute values to element classes

215

value in a dictionary. It is set up as follows:

216

<div class="syntax"><pre>>>> id_class_mapping = {'1234' : honk} # maps attribute values to classes

217

197

218

>>> lookup = etree.AttributeBasedElementClassLookup(

198

219

... 'id', id_class_mapping)

199

220

>>> parser = etree.XMLParser()

200

221

201

222

</pre></div>

202

Instead of a global setup of this scheme, you should consider using a

203

per-parser setup.

204

223

This class uses its fallback if the attribute is not found or its value is not

205

224

in the mapping. Normally, the default class lookup is used here. If you want

206

225

to use the namespace lookup, for example, you can use this code:

211

230

212

231

</pre></div>

213

232

</div>

214

215

<h2><a id="custom-element-class-lookup" name="custom-element-class-lookup">Custom element class lookup</a></h2>

233

234

<h2>Custom element class lookup</h2>

216

235

This is the most customisable way of finding element classes on a per-element

217

236

basis. It allows you to implement a custom lookup scheme in a subclass:

218

237

<div class="syntax"><pre>>>> class MyLookup(etree.CustomElementClassLookup):

219

238

... def lookup(self, node_type, document, namespace, name):

220

... return MyElementClass # defined elsewhere

239

... return honk # be a bit more selective here ...

221

240

222

241

>>> parser = etree.XMLParser()

223

242

224

243

</pre></div>

225

The <tt class="docutils literal">lookup()</tt> method must either return None (which triggers the fallback

226

mechanism) or a subclass of <tt class="docutils literal">lxml.etree.ElementBase</tt>. It can take any

227

decision it wants based on the node type (one of "element", "comment", "PI"),

228

the XML document of the element, or its namespace or tag name.

229

Instead of a global setup of this scheme, you should consider using a

230

per-parser setup.

244

The <tt class="docutils literal">.lookup()</tt> method must return either None (which triggers the

245

fallback mechanism) or a subclass of <tt class="docutils literal">lxml.etree.ElementBase</tt>. It

246

can take any decision it wants based on the node type (one of

247

"element", "comment", "PI", "entity"), the XML document of the

248

element, or its namespace or tag name.

231

249

</div>

232

233

<h2><a id="tree-based-element-class-lookup-in-python" name="tree-based-element-class-lookup-in-python">Tree based element class lookup in Python</a></h2>

234

Taking more elaborate decisions than allowed by the custom scheme is difficult

235

to achieve in pure Python. It would require access to the tree - before the

236

elements in the tree have been instantiated as Python Element objects.

250

251

<h2>Tree based element class lookup in Python</h2>

252

Taking more elaborate decisions than allowed by the custom scheme is

253

difficult to achieve in pure Python, as it results in a

254

chicken-and-egg problem. It would require access to the tree - before

255

the elements in the tree have been instantiated as Python Element

256

proxies.

237

257

Luckily, there is a way to do this. The <tt class="docutils literal">PythonElementClassLookup</tt>

238

258

works similar to the custom lookup scheme:

239

259

<div class="syntax"><pre>>>> class MyLookup(etree.PythonElementClassLookup):

260

280

provide. Once you have taken the decision which class to use for this

261

281

element, you can simply return it and have lxml take care of cleaning up the

262

282

instantiated proxy classes.

263

Note: this lookup scheme originally lived in a separate module called

283

Sidenote: this lookup scheme originally lived in a separate module called

264

284

<tt class="docutils literal">lxml.pyclasslookup</tt>.

265

285

</div>

266

286

</div>

267

268

<h1><a id="id1" name="id1">Implementing namespaces</a></h1>

287

288

<h1>Generating XML with custom classes</h1>

289

Up to lxml 2.1, you could not instantiate proxy classes yourself.

290

Only lxml.etree could do that when creating an object representation

291

of an existing XML element. Since lxml 2.2, however, instantiating

292

this class will simply create a new Element:

293

<div class="syntax"><pre>>>> el = honk(honking = 'true')

294

>>> el.tag

295

'honk'

296

>>> el.honking

297

True

298

</pre></div>

299

Note, however, that the proxy you create here will be garbage

300

collected just like any other proxy. You can therefore not count on

301

lxml.etree using the same class that you instantiated when you access

302

this Element a second time after letting its reference go. You should

303

therefore always use a corresponding class lookup scheme that returns

304

your Element proxy classes for the elements that they create. The

305

<tt class="docutils literal">ElementNamespaceClassLookup</tt> is generally a good match.

306

You can use custom Element classes to quickly create XML fragments:

307

<div class="syntax"><pre>>>> class hale(etree.ElementBase): pass

308

>>> class bopp(etree.ElementBase): pass

309

310

>>> el = hale( "some ", honk(honking = 'true'), bopp, " text" )

311

312

>>> print(etree.tostring(el, encoding=unicode))

313

314

</pre></div>

315

</div>

316

317

<h1>Implementing namespaces</h1>

269

318

lxml allows you to implement namespaces, in a rather literal sense. After

270

319

setting up the namespace class lookup mechanism as described above, you can

271

320

build a new element namespace (or retrieve an existing one) by calling the

278

327

</pre></div>

279

328

and then register the new element type with that namespace, say, under the tag

280

329

name <tt class="docutils literal">honk</tt>:

281

<div class="syntax"><pre>>>> namespace['honk'] = HonkElement

330

282

331

</pre></div>

332

If you have many Element classes declared in one module, and they are

333

all named like the elements they create, you can simply use

334

<tt class="docutils literal">namespace.update(vars())</tt> at the end of your module to declare them

335

automatically. The implementation is smart enough to ignore

336

everything that is not an Element class.

283

337

After this, you create and use your XML elements through the normal API of

284

338

lxml:

285

339

<div class="syntax"><pre>>>> xml = '<honk xmlns="http://hui.de/honk" honking="true"/>'

293

347

>>> print(honk_element.honking)

294

348

True

295

349

</pre></div>

296

Essentially, what this allows you to do, is to give elements a custom API

350

Essentially, what this allows you to do, is to give Elements a custom API

297

351

based on their namespace and tag name.

298

A somewhat related topic are <a class="reference" href="extensions.html">extension functions</a> which use a similar

352

A somewhat related topic are <a class="reference external" href="extensions.html">extension functions</a> which use a similar

299

353

mechanism for registering extension functions in XPath and XSLT.

300

In the setup example above, we associated the HonkElement class only with the

301

'honk' element. If an XML tree contains different elements in the same

302

namespace, they do not pick up the same implementation:

354

In the setup example above, we associated the <tt class="docutils literal">honk</tt> Element class

355

only with the 'honk' element. If an XML tree contains different

356

elements in the same namespace, they do not pick up the same

357

implementation:

303

358

<div class="syntax"><pre>>>> xml = '<honk xmlns="http://hui.de/honk" honking="true"><bla/></honk>'

304

359

>>> honk_element = etree.XML(xml, parser)

305

360

>>> print(honk_element.honking)

321

376

<div class="syntax"><pre>>>> class HonkNSElement(etree.ElementBase):

322

377

... def honk(self):

323

378

... return "HONK"

324

>>> namespace[None] = HonkNSElement

379

>>> namespace[None] = HonkNSElement # default Element for namespace

325

380

326

381

>>> class HonkElement(HonkNSElement):

327

382

... def honking(self):

328

383

329

384

... honking = property(honking)

330

>>> namespace['honk'] = HonkElement

385

>>> namespace['honk'] = HonkElement # Element for specific tag

331

386

</pre></div>

332

387

Now you can rely on lxml to always return objects of type HonkNSElement or its

333

388

subclasses for elements of this namespace:

343

398

True

344

399

>>> print(honk_element.honk())

345

400

HONK

401

346

402

>>> print(honk_element[0].honk())

347

403

HONK

348

404

353

409

</div>

354

410

355

411

356

Generated on: 2009-01-06.

412

Generated on: 2009-06-21.

357

413

358

414

</div>

359

415

</body>

Older »