<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>ElementTree compatibility of lxml.etree</title>
<link rel="stylesheet" href="style.css" type="text/css" />
</head>
<body>
<div class="document" id="elementtree-compatibility-of-lxml-etree">
<div class="sidemenu"><ul id="lxml"><li><span class="section title">lxml</span><ul class="menu foreign" id="index"><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"><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"><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"><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"><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 current" id="compatibility"><li class="menu title"><a href="compatibility.html">ElementTree compatibility of lxml.etree</a></li></ul><ul class="menu foreign" id="FAQ"><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"><li><span class="section title">Developing with lxml</span><ul class="menu foreign" id="tutorial"><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"><li class="menu title"><a href="api/index.html">API reference</a></li></ul><ul class="menu foreign" id="api"><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#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"><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"><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"><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"><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"><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"><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#limitations">Limitations</a></li></ul></li></ul><ul class="menu foreign" id="elementsoup"><li class="menu title"><a href="elementsoup.html">BeautifulSoup Parser</a><ul class="submenu"><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"><li><span class="section title">Extending lxml</span><ul class="menu foreign" id="resolvers"><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#resolvers">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"><li class="menu title"><a href="extensions.html">Extension functions for XPath and XSLT</a><ul class="submenu"><li class="menu item"><a href="extensions.html#the-functionnamespace">The FunctionNamespace</a></li><li class="menu item"><a href="extensions.html#global-prefix-assignment">Global prefix assignment</a></li><li class="menu item"><a href="extensions.html#the-xpath-context">The XPath context</a></li><li class="menu item"><a href="extensions.html#evaluators-and-xslt">Evaluators and XSLT</a></li><li class="menu item"><a href="extensions.html#evaluator-local-extensions">Evaluator-local extensions</a></li><li class="menu item"><a href="extensions.html#what-to-return-from-a-function">What to return from a function</a></li></ul></li></ul><ul class="menu foreign" id="element classes"><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"><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"><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"><li><span class="section title">Developing lxml</span><ul class="menu foreign" id="build"><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"><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-pyclasslookup">lxml.pyclasslookup</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 0 11"><li class="menu title"><a href="changes-2.0.11.html">Release Changelog</a></li></ul><ul class="menu foreign" id="credits"><li class="menu title"><a href="credits.html">Credits</a><ul class="submenu"><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">ElementTree compatibility of lxml.etree</h1>
<p>A lot of care has been taken to ensure compatibility between etree and
ElementTree. Nonetheless, some differences and incompatibilities exist:</p>
<ul>
<li><p class="first">Importing etree is obviously different; etree uses a lower-case
package name, while ElementTree uses a combination of upper-case and
lower case in imports:</p>
<pre class="literal-block">
# etree
from lxml.etree import Element
# ElementTree
from elementtree.ElementTree import Element
# ElementTree in the Python 2.5 standard library
from xml.etree.ElementTree import Element
</pre>
<p>When switching over code from ElementTree to lxml.etree, and you're using
the package name prefix 'ElementTree', you can do the following:</p>
<pre class="literal-block">
# instead of
from elementtree import ElementTree
# use
from lxml import etree as ElementTree
</pre>
</li>
<li><p class="first">lxml.etree offers a lot more functionality, such as XPath, XSLT, Relax NG,
and XML Schema support, which (c)ElementTree does not offer.</p>
</li>
<li><p class="first">etree has a different idea about Python unicode strings than ElementTree.
In most parts of the API, ElementTree uses plain strings and unicode strings
as what they are. This includes Element.text, Element.tail and many other
places. However, the ElementTree parsers assume by default that any string
(<cite>str</cite> or <cite>unicode</cite>) contains ASCII data. They raise an exception if
strings do not match the expected encoding.</p>
<p>etree has the same idea about plain strings (<cite>str</cite>) as ElementTree. For
unicode strings, however, etree assumes throughout the API that they are
Python unicode encoded strings rather than byte data. This includes the
parsers. It is therefore perfectly correct to pass XML unicode data into
the etree parsers in form of Python unicode strings. It is an error, on the
other hand, if unicode strings specify an encoding in their XML declaration,
as this conflicts with the characteristic encoding of Python unicode
strings.</p>
</li>
<li><p class="first">ElementTree allows you to place an Element in two different trees at the
same time. Thus, this:</p>
<pre class="literal-block">
a = Element('a')
b = SubElement(a, 'b')
c = Element('c')
c.append(b)
</pre>
<p>will result in the following tree a:</p>
<pre class="literal-block">
<a><b /></a>
</pre>
<p>and the following tree c:</p>
<pre class="literal-block">
<c><b /></c>
</pre>
<p>In lxml, this behavior is different, because lxml is built on top of a tree
that maintains parent relationships for elements (like W3C DOM). This means
an element can only exist in a single tree at the same time. Adding an
element in some tree to another tree will cause this element to be moved.</p>
<p>So, for tree a we will get:</p>
<pre class="literal-block">
<a></a>
</pre>
<p>and for tree c we will get:</p>
<pre class="literal-block">
<c><b/></c>
</pre>
<p>Unfortunately this is a rather fundamental difference in behavior, which is
hard to change. It won't affect some applications, but if you want to port
code you must unfortunately make sure that it doesn't affect yours.</p>
</li>
<li><p class="first">etree allows navigation to the parent of a node by the <tt class="docutils literal"><span class="pre">getparent()</span></tt>
method and to the siblings by calling <tt class="docutils literal"><span class="pre">getnext()</span></tt> and <tt class="docutils literal"><span class="pre">getprevious()</span></tt>.
This is not possible in ElementTree as the underlying tree model does not
have this information.</p>
</li>
<li><p class="first">When trying to set a subelement using __setitem__ that is in fact not an
Element but some other object, etree raises a TypeError, and ElementTree
raises an AssertionError. This also applies to some other places of the
API. In general, etree tries to avoid AssertionErrors in favour of being
more specific about the reason for the exception.</p>
</li>
<li><p class="first">When parsing fails in <tt class="docutils literal"><span class="pre">iterparse()</span></tt>, ElementTree up to version
1.2.x raises a low-level <tt class="docutils literal"><span class="pre">ExpatError</span></tt> instead of a <tt class="docutils literal"><span class="pre">SyntaxError</span></tt>
as the other parsers. Both lxml and ElementTree 1.3 raise a
<tt class="docutils literal"><span class="pre">ParseError</span></tt> for parser errors.</p>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">iterparse()</span></tt> function in lxml is implemented based on the libxml2
parser and tree generator. This means that modifications of the document
root or the ancestors of the current element during parsing can irritate the
parser and even segfault. While this is not a problem in the Python object
structure used by ElementTree, the C tree underlying lxml suffers from it.
The golden rule for <tt class="docutils literal"><span class="pre">iterparse()</span></tt> on lxml therefore is: do not touch
anything that will have to be touched again by the parser later on. See the
lxml parser documentation on this.</p>
</li>
<li><p class="first">ElementTree ignores comments and processing instructions when parsing XML,
while etree will read them in and treat them as Comment or
ProcessingInstruction elements respectively. This is especially visible
where comments are found inside text content, which is then split by the
Comment element.</p>
<p>You can disable this behaviour by passing the boolean <tt class="docutils literal"><span class="pre">remove_comments</span></tt>
and/or <tt class="docutils literal"><span class="pre">remove_pis</span></tt> keyword arguments to the parser you use. For
convenience and to support portable code, you can also use the
<tt class="docutils literal"><span class="pre">etree.ETCompatXMLParser</span></tt> instead of the default <tt class="docutils literal"><span class="pre">etree.XMLParser</span></tt>. It
tries to provide a default setup that is as close to the ElementTree parser
as possible.</p>
</li>
<li><p class="first">The <tt class="docutils literal"><span class="pre">TreeBuilder</span></tt> class of <tt class="docutils literal"><span class="pre">lxml.etree</span></tt> uses a different
signature for the <tt class="docutils literal"><span class="pre">start()</span></tt> method. It accepts an additional
argument <tt class="docutils literal"><span class="pre">nsmap</span></tt> to propagate the namespace declarations of an
element in addition to its own namespace. To assure compatibility
with ElementTree (which does not support this argument), lxml checks
if the method accepts 3 arguments before calling it, and otherwise
drops the namespace mapping. This should work with most existing
ElementTree code, although there may still be conflicting cases.</p>
</li>
<li><p class="first">ElementTree 1.2 has a bug when serializing an empty Comment (no text
argument given) to XML, etree serializes this successfully.</p>
</li>
<li><p class="first">ElementTree adds whitespace around comments on serialization, lxml does
not. This means that a comment text "text" that ElementTree serializes as
"<!-- text -->" will become "<!--text-->" in lxml.</p>
</li>
<li><p class="first">When the string '*' is used as tag filter in the <tt class="docutils literal"><span class="pre">Element.getiterator()</span></tt>
method, ElementTree returns all elements in the tree, including comments and
processing instructions. lxml.etree only returns real Elements, i.e. tree
nodes that have a string tag name. Without a filter, both libraries iterate
over all nodes.</p>
<p>Note that currently only lxml.etree supports passing the <tt class="docutils literal"><span class="pre">Element</span></tt> factory
function as filter to select only Elements. Both libraries support passing
the <tt class="docutils literal"><span class="pre">Comment</span></tt> and <tt class="docutils literal"><span class="pre">ProcessingInstruction</span></tt> factories to select the
respective tree nodes.</p>
</li>
<li><p class="first">ElementTree merges the target of a processing instruction into <tt class="docutils literal"><span class="pre">PI.text</span></tt>,
while lxml.etree puts it into the <tt class="docutils literal"><span class="pre">.target</span></tt> property and leaves it out of
the <tt class="docutils literal"><span class="pre">.text</span></tt> property. The <tt class="docutils literal"><span class="pre">pi.text</span></tt> in ElementTree therefore
correspondents to <tt class="docutils literal"><span class="pre">pi.target</span> <span class="pre">+</span> <span class="pre">"</span> <span class="pre">"</span> <span class="pre">+</span> <span class="pre">pi.text</span></tt> in lxml.etree.</p>
</li>
<li><p class="first">Because etree is built on top of libxml2, which is namespace prefix aware,
etree preserves namespaces declarations and prefixes while ElementTree tends
to come up with its own prefixes (ns0, ns1, etc). When no namespace prefix
is given, however, etree creates ElementTree style prefixes as well.</p>
</li>
<li><p class="first">etree has a 'prefix' attribute (read-only) on elements giving the Element's
prefix, if this is known, and None otherwise (in case of no namespace at
all, or default namespace).</p>
</li>
<li><p class="first">etree further allows passing an 'nsmap' dictionary to the Element and
SubElement element factories to explicitly map namespace prefixes to
namespace URIs. These will be translated into namespace declarations on
that element. This means that in the probably rare case that you need to
construct an attribute called 'nsmap', you need to be aware that unlike in
ElementTree, you cannot pass it as a keyword argument to the Element and
SubElement factories directly.</p>
</li>
<li><p class="first">ElementTree allows QName objects as attribute values and resolves their
prefix on serialisation (e.g. an attribute value <tt class="docutils literal"><span class="pre">QName("{myns}myname")</span></tt>
becomes "p:myname" if "p" is the namespace prefix of "myns"). lxml.etree
also allows you to set attribute values from QName instances (and also .text
values), but it resolves their prefix immediately and stores the plain text
value. So, if prefixes are modified later on, e.g. by moving a subtree to a
different tree (which reassigns the prefix mappings), the text values will
not be updated and you might end up with an undefined prefix.</p>
</li>
<li><p class="first">etree elements can be copied using <tt class="docutils literal"><span class="pre">copy.deepcopy()</span></tt> and <tt class="docutils literal"><span class="pre">copy.copy()</span></tt>,
just like ElementTree's. However, <tt class="docutils literal"><span class="pre">copy.copy()</span></tt> does <em>not</em> create a
shallow copy where elements are shared between trees, as this makes no sense
in the context of libxml2 trees. Note that lxml can deep-copy trees
considerably faster than ElementTree, so a deep copy might still be fast
enough to replace a shallow copy in your case.</p>
</li>
</ul>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2008-12-12.
</div>
</body>
</html>
