Tryag File Manager
Home
-
Turbo Force
Current Path :
/
proc
/
self
/
root
/
usr
/
share
/
doc
/
python-lxml-2.0.11
/
doc
/
html
/
Upload File :
New :
File
Dir
//proc/self/root/usr/share/doc/python-lxml-2.0.11/doc/html/FAQ.html
<!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>lxml FAQ - Frequently Asked Questions</title> <meta content="Frequently Asked Questions about lxml (FAQ)" name="description" /> <meta content="lxml, lxml.etree, FAQ, frequently asked questions" name="keywords" /> <link rel="stylesheet" href="style.css" type="text/css" /> </head> <body> <div class="document" id="lxml-faq-frequently-asked-questions"> <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 foreign" id="compatibility"><li class="menu title"><a href="compatibility.html">ElementTree compatibility of lxml.etree</a></li></ul><ul class="menu current" 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">lxml FAQ - Frequently Asked Questions</h1> <p>Frequently asked questions on lxml. See also the notes on <a class="reference" href="compatibility.html">compatibility</a> to <a class="reference" href="http://effbot.org/zone/element-index.htm">ElementTree</a>.</p> <div class="contents topic"> <p class="topic-title first"><a id="contents" name="contents">Contents</a></p> <ul class="simple"> <li><a class="reference" href="#general-questions" id="id2" name="id2">General Questions</a><ul> <li><a class="reference" href="#is-there-a-tutorial" id="id3" name="id3">Is there a tutorial?</a></li> <li><a class="reference" href="#where-can-i-find-more-documentation-about-lxml" id="id4" name="id4">Where can I find more documentation about lxml?</a></li> <li><a class="reference" href="#what-standards-does-lxml-implement" id="id5" name="id5">What standards does lxml implement?</a></li> <li><a class="reference" href="#who-uses-lxml" id="id6" name="id6">Who uses lxml?</a></li> <li><a class="reference" href="#what-is-the-difference-between-lxml-etree-and-lxml-objectify" id="id7" name="id7">What is the difference between lxml.etree and lxml.objectify?</a></li> <li><a class="reference" href="#how-can-i-make-my-application-run-faster" id="id8" name="id8">How can I make my application run faster?</a></li> <li><a class="reference" href="#what-about-that-trailing-text-on-serialised-elements" id="id9" name="id9">What about that trailing text on serialised Elements?</a></li> </ul> </li> <li><a class="reference" href="#installation" id="id10" name="id10">Installation</a><ul> <li><a class="reference" href="#which-version-of-libxml2-and-libxslt-should-i-use-or-require" id="id11" name="id11">Which version of libxml2 and libxslt should I use or require?</a></li> <li><a class="reference" href="#where-are-the-windows-binaries" id="id12" name="id12">Where are the Windows binaries?</a></li> <li><a class="reference" href="#why-do-i-get-errors-about-missing-ucs4-symbols-when-installing-lxml" id="id13" name="id13">Why do I get errors about missing UCS4 symbols when installing lxml?</a></li> </ul> </li> <li><a class="reference" href="#contributing" id="id14" name="id14">Contributing</a><ul> <li><a class="reference" href="#why-is-lxml-not-written-in-python" id="id15" name="id15">Why is lxml not written in Python?</a></li> <li><a class="reference" href="#how-can-i-contribute" id="id16" name="id16">How can I contribute?</a></li> </ul> </li> <li><a class="reference" href="#bugs" id="id17" name="id17">Bugs</a><ul> <li><a class="reference" href="#my-application-crashes" id="id18" name="id18">My application crashes!</a></li> <li><a class="reference" href="#i-think-i-have-found-a-bug-in-lxml-what-should-i-do" id="id19" name="id19">I think I have found a bug in lxml. What should I do?</a></li> </ul> </li> <li><a class="reference" href="#id1" id="id20" name="id20">Threading</a><ul> <li><a class="reference" href="#can-i-use-threads-to-concurrently-access-the-lxml-api" id="id21" name="id21">Can I use threads to concurrently access the lxml API?</a></li> <li><a class="reference" href="#does-my-program-run-faster-if-i-use-threads" id="id22" name="id22">Does my program run faster if I use threads?</a></li> <li><a class="reference" href="#would-my-single-threaded-program-run-faster-if-i-turned-off-threading" id="id23" name="id23">Would my single-threaded program run faster if I turned off threading?</a></li> <li><a class="reference" href="#why-can-t-i-reuse-xslt-stylesheets-in-other-threads" id="id24" name="id24">Why can't I reuse XSLT stylesheets in other threads?</a></li> <li><a class="reference" href="#my-program-crashes-when-run-with-mod-python-pyro-zope-plone" id="id25" name="id25">My program crashes when run with mod_python/Pyro/Zope/Plone/...</a></li> </ul> </li> <li><a class="reference" href="#parsing-and-serialisation" id="id26" name="id26">Parsing and Serialisation</a><ul> <li><a class="reference" href="#why-doesn-t-the-pretty-print-option-reformat-my-xml-output" id="id27" name="id27">Why doesn't the <tt class="docutils literal"><span class="pre">pretty_print</span></tt> option reformat my XML output?</a></li> <li><a class="reference" href="#why-can-t-lxml-parse-my-xml-from-unicode-strings" id="id28" name="id28">Why can't lxml parse my XML from unicode strings?</a></li> <li><a class="reference" href="#what-is-the-difference-between-str-xslt-doc-and-xslt-doc-write" id="id29" name="id29">What is the difference between str(xslt(doc)) and xslt(doc).write() ?</a></li> <li><a class="reference" href="#why-can-t-i-just-delete-parents-or-clear-the-root-node-in-iterparse" id="id30" name="id30">Why can't I just delete parents or clear the root node in iterparse()?</a></li> <li><a class="reference" href="#how-do-i-output-null-characters-in-xml-text" id="id31" name="id31">How do I output null characters in XML text?</a></li> </ul> </li> <li><a class="reference" href="#xpath-and-document-traversal" id="id32" name="id32">XPath and Document Traversal</a><ul> <li><a class="reference" href="#what-are-the-findall-and-xpath-methods-on-element-tree" id="id33" name="id33">What are the <tt class="docutils literal"><span class="pre">findall()</span></tt> and <tt class="docutils literal"><span class="pre">xpath()</span></tt> methods on Element(Tree)?</a></li> <li><a class="reference" href="#why-doesn-t-findall-support-full-xpath-expressions" id="id34" name="id34">Why doesn't <tt class="docutils literal"><span class="pre">findall()</span></tt> support full XPath expressions?</a></li> <li><a class="reference" href="#how-can-i-find-out-which-namespace-prefixes-are-used-in-a-document" id="id35" name="id35">How can I find out which namespace prefixes are used in a document?</a></li> <li><a class="reference" href="#how-can-i-specify-a-default-namespace-for-xpath-expressions" id="id36" name="id36">How can I specify a default namespace for XPath expressions?</a></li> </ul> </li> </ul> </div> <div class="section"> <h1><a id="general-questions" name="general-questions">General Questions</a></h1> <div class="section"> <h2><a id="is-there-a-tutorial" name="is-there-a-tutorial">Is there a tutorial?</a></h2> <p>Read the <a class="reference" href="tutorial.html">lxml.etree Tutorial</a>. While this is still work in progress (just as any good documentation), it provides an overview of the most important concepts in <tt class="docutils literal"><span class="pre">lxml.etree</span></tt>. If you want to help out, improving the tutorial is a very good place to start.</p> <p>There is also a <a class="reference" href="http://effbot.org/zone/element.htm">tutorial for ElementTree</a> which works for <tt class="docutils literal"><span class="pre">lxml.etree</span></tt>. The <a class="reference" href="api.html">API documentation</a> also contains many examples for <tt class="docutils literal"><span class="pre">lxml.etree</span></tt>. To learn using <tt class="docutils literal"><span class="pre">lxml.objectify</span></tt>, read the <a class="reference" href="objectify.html">objectify documentation</a>.</p> <p>John Shipman has written another tutorial called <a class="reference" href="http://www.nmt.edu/tcc/help/pubs/pylxml/">Python XML processing with lxml</a> that contains lots of examples.</p> </div> <div class="section"> <h2><a id="where-can-i-find-more-documentation-about-lxml" name="where-can-i-find-more-documentation-about-lxml">Where can I find more documentation about lxml?</a></h2> <p>There is a lot of documentation as lxml implements the well-known <a class="reference" href="http://effbot.org/zone/element-index.htm">ElementTree API</a> and tries to follow its documentation as closely as possible. There are a couple of issues where lxml cannot keep up compatibility. They are described in the <a class="reference" href="compatibility.html">compatibility</a> documentation. The lxml specific extensions to the API are described by individual files in the <tt class="docutils literal"><span class="pre">doc</span></tt> directory of the distribution and on <a class="reference" href="http://codespeak.net/lxml/#documentation">the web page</a>.</p> </div> <div class="section"> <h2><a id="what-standards-does-lxml-implement" name="what-standards-does-lxml-implement">What standards does lxml implement?</a></h2> <p>The compliance to XML Standards depends on the support in libxml2 and libxslt. Here is a quote from <cite>http://xmlsoft.org/</cite>:</p> <blockquote> In most cases libxml2 tries to implement the specifications in a relatively strictly compliant way. As of release 2.4.16, libxml2 passed all 1800+ tests from the OASIS XML Tests Suite.</blockquote> <p>lxml currently supports libxml2 2.6.20 or later, which has even better support for various XML standards. Some of the more important ones are: HTML, XML namespaces, XPath, XInclude, XSLT, XML catalogs, canonical XML, RelaxNG, XML:ID. Support for XML Schema and especially Schematron is currently incomplete in libxml2, but is definitely usable and actively being worked on. libxml2 also supports loading documents through HTTP and FTP.</p> </div> <div class="section"> <h2><a id="who-uses-lxml" name="who-uses-lxml">Who uses lxml?</a></h2> <p>As an XML library, lxml is often used under the hood of in-house server applications, such as web servers or applications that facilitate some kind of document management. Therefore, it is hard to get an idea of who uses it, and the following list of 'users and projects we know of' is definitely not a complete list of lxml's users.</p> <p>Also note that the compatibility to the ElementTree library does not require projects to set a hard dependency on lxml - as long as they do not take advantage of lxml's enhanced feature set.</p> <ul class="simple"> <li><a class="reference" href="http://code.google.com/p/cssutils/source/browse/trunk/examples/style.py?r=917">cssutils</a>, a CSS parser and toolkit, can be used with <tt class="docutils literal"><span class="pre">lxml.cssselect</span></tt></li> <li><a class="reference" href="http://www.openplans.org/projects/deliverance/project-home">Deliverance</a>, a content theming tool</li> <li><a class="reference" href="http://www.enfoldsystems.com/Products/Proxy/4">Enfold Proxy 4</a>, a web server accelerator with on-the-fly XSLT processing</li> <li><a class="reference" href="http://lists.wald.intevation.org/pipermail/inteproxy-devel/2007-February/000000.html">Inteproxy</a>, a secure HTTP proxy</li> <li><a class="reference" href="http://pypi.python.org/pypi/lwebstring">lwebstring</a>, an XML template engine</li> <li><a class="reference" href="http://permalink.gmane.org/gmane.comp.python.lxml.devel/3250">OpenXMLlib</a>, a library for handling OpenXML document meta data</li> <li><a class="reference" href="http://pypi.python.org/pypi/pycoon">Pycoon</a>, a WSGI web development framework based on XML pipelines</li> <li><a class="reference" href="http://pypi.python.org/pypi/rdfadict">rfadict</a>, an RDFa parser with a simple dictionary-like interface.</li> </ul> <p>Zope3 and some of its extensions have good support for lxml:</p> <ul class="simple"> <li><a class="reference" href="http://pypi.python.org/pypi/gocept.lxml">gocept.lxml</a>, Zope3 interface bindings for lxml</li> <li><a class="reference" href="http://pypi.python.org/pypi/z3c.rml">z3c.rml</a>, an implementation of ReportLab's RML format</li> </ul> <p>And don't miss the quotes by our generally <a class="reference" href="http://thread.gmane.org/gmane.comp.python.lxml.devel/3244/focus=3244">happy</a> <a class="reference" href="http://article.gmane.org/gmane.comp.python.lxml.devel/3246">users</a>, and other <a class="reference" href="http://www.google.com/search?as_lq=http%3A%2F%2Fcodespeak.net%2Flxml">sites that link to lxml</a>.</p> </div> <div class="section"> <h2><a id="what-is-the-difference-between-lxml-etree-and-lxml-objectify" name="what-is-the-difference-between-lxml-etree-and-lxml-objectify">What is the difference between lxml.etree and lxml.objectify?</a></h2> <p>The two modules provide different ways of handling XML. However, objectify builds on top of lxml.etree and therefore inherits most of its capabilities and a large portion of its API.</p> <ul> <li><p class="first">lxml.etree is a generic API for XML and HTML handling. It aims for ElementTree <a class="reference" href="compatibility.html">compatibility</a> and supports the entire XML infoset. It is well suited for both mixed content and data centric XML. Its generality makes it the best choice for most applications.</p> </li> <li><p class="first">lxml.objectify is a specialized API for XML data handling in a Python object syntax. It provides a very natural way to deal with data fields stored in a structurally well defined XML format. Data is automatically converted to Python data types and can be manipulated with normal Python operators. Look at the examples in the <a class="reference" href="objectify.html">objectify documentation</a> to see what it feels like to use it.</p> <p>Objectify is not well suited for mixed contents or HTML documents. As it is built on top of lxml.etree, however, it inherits the normal support for XPath, XSLT or validation.</p> </li> </ul> </div> <div class="section"> <h2><a id="how-can-i-make-my-application-run-faster" name="how-can-i-make-my-application-run-faster">How can I make my application run faster?</a></h2> <p>lxml.etree is a very fast library for processing XML. There are, however, <a class="reference" href="performance.html#the-elementtree-api">a few caveats</a> involved in the mapping of the powerful libxml2 library to the simple and convenient ElementTree API. Not all operations are as fast as the simplicity of the API might suggest, while some use cases can heavily benefit from finding the right way of doing them. The <a class="reference" href="performance.html">benchmark page</a> has a comparison to other ElementTree implementations and a number of tips for performance tweaking. As with any Python application, the rule of thumb is: the more of your processing runs in C, the faster your application gets. See also the section on <a class="reference" href="#threading">threading</a>.</p> </div> <div class="section"> <h2><a id="what-about-that-trailing-text-on-serialised-elements" name="what-about-that-trailing-text-on-serialised-elements">What about that trailing text on serialised Elements?</a></h2> <p>The ElementTree tree model defines an Element as a container with a tag name, contained text, child Elements and a tail text. This means that whenever you serialise an Element, you will get all parts of that Element:</p> <pre class="literal-block"> >>> from lxml import etree >>> root = etree.XML("<root><tag>text<child/></tag>tail</root>") >>> print etree.tostring(root[0]) <tag>text<child/></tag>tail </pre> <p>Here is an example that shows why not serialising the tail would be even more surprising from an object point of view:</p> <pre class="literal-block"> >>> root = etree.Element("test") >>> root.text = "TEXT" >>> etree.tostring(root) <test>TEXT</test> >>> etree.tail = "TAIL" >>> etree.tostring(root) <test>TEXT</test>TAIL >>> etree.tail = None >>> etree.tostring(root) <test>TEXT</test> </pre> <p>Just imagine a Python list where you append an item and it doesn't show up when you look at the list.</p> <p>The <tt class="docutils literal"><span class="pre">.tail</span></tt> property is a huge simplification for the tree model as it avoids text nodes to appear in the list of children and makes access to them quick and simple. So this is a benefit in most applications and simplifies many, many XML tree algorithms.</p> <p>However, in document-like XML (and especially HTML), the above result can be unexpected to new users and can sometimes require a bit more overhead. A good way to deal with this is to use helper functions that copy the Element without its tail. The <tt class="docutils literal"><span class="pre">lxml.html</span></tt> package also deals with this in a couple of places, as most HTML algorithms benefit from a tail-free behaviour.</p> </div> </div> <div class="section"> <h1><a id="installation" name="installation">Installation</a></h1> <div class="section"> <h2><a id="which-version-of-libxml2-and-libxslt-should-i-use-or-require" name="which-version-of-libxml2-and-libxslt-should-i-use-or-require">Which version of libxml2 and libxslt should I use or require?</a></h2> <p>It really depends on your application, but the rule of thumb is: more recent versions contain less bugs and provide more features.</p> <ul class="simple"> <li>Do not use libxml2 2.6.27 if you want to use XPath (including XSLT). You will get crashes when XPath errors occur during the evaluation (e.g. for unknown functions). This happens inside the evaluation call to libxml2, so there is nothing that lxml can do about it.</li> <li>Try to use versions of both libraries that were released together. At least the libxml2 version should not be older than the libxslt version.</li> <li>If you use XML Schema or Schematron which are still under development, the most recent version of libxml2 is usually a good bet.</li> <li>The same applies to XPath, where a substantial number of bugs and memory leaks were fixed over time. If you encounter crashes or memory leaks in XPath applications, try a more recent version of libxml2.</li> <li>For parsing and fixing broken HTML, lxml requires at least libxml2 2.6.21.</li> <li>For the normal tree handling, however, any libxml2 version starting with 2.6.20 should do.</li> </ul> <p>Read the <a class="reference" href="http://xmlsoft.org/news.html">release notes of libxml2</a> and the <a class="reference" href="http://xmlsoft.org/XSLT/news.html">release notes of libxslt</a> to see when (or if) a specific bug has been fixed.</p> </div> <div class="section"> <h2><a id="where-are-the-windows-binaries" name="where-are-the-windows-binaries">Where are the Windows binaries?</a></h2> <p>Short answer: If you want to contribute a binary build, we are happy to put it up on the Cheeseshop.</p> <p>Long answer: Two of the bigger problems with the Windows system are the lack of a pre-installed standard compiler and the missing package management. Both make it non-trivial to build lxml on this platform. We are trying hard to make lxml as platform-independent as possible and it is regularly tested on Windows systems. However, we currently cannot provide Windows binary distributions ourselves.</p> <p>From time to time, users of different environments kindly contribute binary builds of lxml, most frequently for Windows or Mac-OS X. We put these on the Cheeseshop to make it as easy as possible for others to use lxml on their platform.</p> <p>If there is not currently a binary distribution of the most recent lxml release for your platform available from the Cheeseshop, please look through the older versions to see if they provide a binary build. This is done by appending the version number to the cheeseshop URL, e.g.:</p> <blockquote> <a class="reference" href="http://cheeseshop.python.org/pypi/lxml/1.1.2">http://cheeseshop.python.org/pypi/lxml/1.1.2</a></blockquote> </div> <div class="section"> <h2><a id="why-do-i-get-errors-about-missing-ucs4-symbols-when-installing-lxml" name="why-do-i-get-errors-about-missing-ucs4-symbols-when-installing-lxml">Why do I get errors about missing UCS4 symbols when installing lxml?</a></h2> <p>Most likely, you use a Python installation that was configured for internal use of UCS2 unicode, meaning 16-bit unicode. The lxml egg distributions are generally compiled on platforms that use UCS4, a 32-bit unicode encoding, as this is used on the majority of platforms. Sadly, both are not compatible, so the eggs can only support the one they were compiled with.</p> <p>This means that you have to compile lxml from sources for your system. Note that you do not need Cython for this, the lxml source distribution is directly compilable on both platform types. See the <a class="reference" href="build.html">build instructions</a> on how to do this.</p> </div> </div> <div class="section"> <h1><a id="contributing" name="contributing">Contributing</a></h1> <div class="section"> <h2><a id="why-is-lxml-not-written-in-python" name="why-is-lxml-not-written-in-python">Why is lxml not written in Python?</a></h2> <p>It <em>almost</em> is.</p> <p>lxml is not written in plain Python, because it interfaces with two C libraries: libxml2 and libxslt. Accessing them at the C-level is required for performance reasons.</p> <p>However, to avoid writing plain C-code and caring too much about the details of built-in types and reference counting, lxml is written in <a class="reference" href="http://www.cython.org/">Cython</a>, a Python-like language that is translated into C-code. Chances are that if you know Python, you can write <a class="reference" href="http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/version/Doc/overview.html">code that Cython accepts</a>. Again, the C-ish style used in the lxml code is just for performance optimisations. If you want to contribute, don't bother with the details, a Python implementation of your contribution is better than none. And keep in mind that lxml's flexible API often favours an implementation of features in pure Python, without bothering with C-code at all. For example, the <tt class="docutils literal"><span class="pre">lxml.html</span></tt> package is entirely written in Python.</p> <p>Please contact the <a class="reference" href="http://codespeak.net/mailman/listinfo/lxml-dev">mailing list</a> if you need any help.</p> </div> <div class="section"> <h2><a id="how-can-i-contribute" name="how-can-i-contribute">How can I contribute?</a></h2> <p>Besides enhancing the code, there are a lot of places where you can help the project and its user base. You can</p> <ul class="simple"> <li>spread the word and write about lxml. Many users (especially new Python users) have not yet heared about lxml, although our user base is constantly growing. If you write your own blog and feel like saying something about lxml, go ahead and do so. If we think your contribution or criticism is valuable to other users, we may even put a link or a quote on the project page.</li> <li>provide code examples for the general usage of lxml or specific problems solved with lxml. Readable code is a very good way of showing how a library can be used and what great things you can do with it. Again, if we hear about it, we can set a link on the project page.</li> <li>work on the documentation. The web page is generated from a set of <a class="reference" href="http://docutils.sourceforge.net/rst.html">ReST</a> <a class="reference" href="http://codespeak.net/svn/lxml/trunk/doc/">text files</a>. It is meant both as a representative project page for lxml and as a site for documenting lxml's API and usage. If you have questions or an idea how to make it more readable and accessible while you are reading it, please send a comment to the <a class="reference" href="http://codespeak.net/mailman/listinfo/lxml-dev">mailing list</a>.</li> </ul> <ul class="simple"> <li>help with the tutorial. A tutorial is the most important stating point for new users, so it is important for us to provide an easy to understand guide into lxml. As allo documentation, the tutorial is work in progress, so we appreciate every helping hand.</li> <li>improve the docstrings. lxml uses docstrings to support Python's integrated online <tt class="docutils literal"><span class="pre">help()</span></tt> function. However, sometimes these are not sufficient to grasp the details of the function in question. If you find such a place, you can try to write up a better description and send it to the <a class="reference" href="http://codespeak.net/mailman/listinfo/lxml-dev">mailing list</a>.</li> </ul> </div> </div> <div class="section"> <h1><a id="bugs" name="bugs">Bugs</a></h1> <div class="section"> <h2><a id="my-application-crashes" name="my-application-crashes">My application crashes!</a></h2> <p>One of the goals of lxml is "no segfaults", so if there is no clear warning in the documentation that you were doing something potentially harmful, you have found a bug and we would like to hear about it. Please report this bug to the <a class="reference" href="http://codespeak.net/mailman/listinfo/lxml-dev">mailing list</a>. See the next section on how to do that.</p> <p>However, there are a few things to try first, to make sure the problem is really within lxml (or libxml2 or libxslt):</p> <ol class="loweralpha simple"> <li>If your application (or e.g. your web container) uses threads, please see the FAQ section on <a class="reference" href="#threading">threading</a> to check if you touch on one of the potential pitfalls.</li> <li>If you are on Mac-OS X, make sure lxml uses the correct libraries. If you have updated the old system libraries (e.g. through fink), this is best achieved by building lxml statically to prevent the different library versions from interfering. If you choose to use a dynamically linked version, make sure the <tt class="docutils literal"><span class="pre">DYLD_LIBRARY_PATH</span></tt> environment variable contains the directory where you installed the libraries. To make sure the correct libraries are used, print the module level version numbers that <tt class="docutils literal"><span class="pre">lxml.etree</span></tt> provides from <em>within</em> your application rather than relying on what your operating system tells you.</li> </ol> <p>In any case, try to reproduce the problem with the latest versions of libxml2 and libxslt. From time to time, bugs and race conditions are found in these libraries, so a more recent version might already contain a fix for your problem.</p> </div> <div class="section"> <h2><a id="i-think-i-have-found-a-bug-in-lxml-what-should-i-do" name="i-think-i-have-found-a-bug-in-lxml-what-should-i-do">I think I have found a bug in lxml. What should I do?</a></h2> <p>First, you should look at the <a class="reference" href="http://codespeak.net/svn/lxml/trunk/CHANGES.txt">current developer changelog</a> to see if this is a known problem that has already been fixed in the SVN trunk since the release you are using.</p> <p>Also, the 'crash' section above has a few good advices what to try to see if the problem is really in lxml - and not in your setup. Believe it or not, that happens more often than you might think, especially when old libraries or even multiple library versions are installed.</p> <p>You should always try to reproduce the problem with the latest versions of libxml2 and libxslt - and make sure they are used (<tt class="docutils literal"><span class="pre">lxml.etree</span></tt> can tell you what it runs with, see below).</p> <p>Otherwise, we would really like to hear about it. Please report it to the <a class="reference" href="http://codespeak.net/mailman/listinfo/lxml-dev">mailing list</a> so that we can fix it. It is very helpful in this case if you can come up with a short code snippet that demonstrates your problem. If others can reproduce and see the problem, it is much easier for them to fix it - and maybe even easier for you to describe it and get people convinced that it really is a problem to fix. Please also report the version of lxml, libxml2 and libxslt that you are using by calling this:</p> <pre class="literal-block"> from lxml import etree print "lxml.etree: ", etree.LXML_VERSION print "libxml used: ", etree.LIBXML_VERSION print "libxml compiled: ", etree.LIBXML_COMPILED_VERSION print "libxslt used: ", etree.LIBXSLT_VERSION print "libxslt compiled: ", etree.LIBXSLT_COMPILED_VERSION </pre> <p>Since as a user of lxml you are likely a programmer, you might find <a class="reference" href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">this article on bug reports</a> an interesting read.</p> </div> </div> <div class="section"> <h1><a id="id1" name="id1">Threading</a></h1> <div class="section"> <h2><a id="can-i-use-threads-to-concurrently-access-the-lxml-api" name="can-i-use-threads-to-concurrently-access-the-lxml-api">Can I use threads to concurrently access the lxml API?</a></h2> <p>Yes, although not carelessly.</p> <p>lxml frees the GIL (Python's global interpreter lock) internally when parsing from disk and memory, as long as you use either the default parser (which is replicated for each thread) or create a parser for each thread yourself. lxml also allows concurrency during validation (RelaxNG and XMLSchema) and XSL transformation. You can share RelaxNG, XMLSchema and (with restrictions) XSLT objects between threads. While you can also share parsers between threads, this will serialize the access to each of them, so it is better to <tt class="docutils literal"><span class="pre">copy()</span></tt> parsers or to just use the default parser (which is automatically copied for each thread).</p> <p>Due to the way libxslt handles threading, concurrent access to stylesheets is currently only possible if it was parsed in the main thread. Parsing and applying a stylesheet inside one thread also works.</p> <p>Warning: You should generally avoid modifying trees in other threads than the one it was generated in. Although this should work in many cases, there are certain scenarios where the termination of a thread that parsed a tree can crash the application if subtrees of this tree were moved to other documents. You should be on the safe side when passing trees between threads if you either</p> <ol class="loweralpha simple"> <li>do not modify these trees and do not move their elements to other trees, or</li> <li>do not terminate threads while the trees they parsed are still in use (e.g. by using a fixed size thread-pool or long-running threads in processing chains)</li> </ol> </div> <div class="section"> <h2><a id="does-my-program-run-faster-if-i-use-threads" name="does-my-program-run-faster-if-i-use-threads">Does my program run faster if I use threads?</a></h2> <p>Depends. The best way to answer this is timing and profiling.</p> <p>The global interpreter lock (GIL) in Python serializes access to the interpreter, so if the majority of your processing is done in Python code (walking trees, modifying elements, etc.), your gain will be close to 0. The more of your XML processing moves into lxml, however, the higher your gain. If your application is bound by XML parsing and serialisation, or by complex XSLTs, your speedup on multi-processor machines can be substantial.</p> <p>See the question above to learn which operations free the GIL to support multi-threading.</p> </div> <div class="section"> <h2><a id="would-my-single-threaded-program-run-faster-if-i-turned-off-threading" name="would-my-single-threaded-program-run-faster-if-i-turned-off-threading">Would my single-threaded program run faster if I turned off threading?</a></h2> <p>Can be. You can see for yourself by compiling lxml entirely without threading support. Pass the <tt class="docutils literal"><span class="pre">--without-threading</span></tt> option to setup.py when building lxml from source.</p> </div> <div class="section"> <h2><a id="why-can-t-i-reuse-xslt-stylesheets-in-other-threads" name="why-can-t-i-reuse-xslt-stylesheets-in-other-threads">Why can't I reuse XSLT stylesheets in other threads?</a></h2> <p>lxml currently has the restriction that an XSLT object can only be used in a thread if it was created either in the thread itself or in the main thread. This is due to some interfering optimisations in libxslt and lxml.etree. To work around this, you can do a couple of things:</p> <ul class="simple"> <li>create all XSLT objects in the main program and reuse them wherever you want.</li> <li>create them in the thread where you use them and maybe cache them in thread local storage (see the threading module).</li> </ul> <p>If your stylesheets are diverse and status specific, you can still prepare them in advance if you:</p> <ul class="simple"> <li>use XSLT parameters that you pass at call time to configure the stylesheets</li> <li>create the stylesheets (partially) programmatically in the main program, e.g. by adding <tt class="docutils literal"><span class="pre">xsl:output</span></tt> tags, <tt class="docutils literal"><span class="pre">xsl:include</span></tt> tags or templates (be careful with the order here) to the XSL tree, and then create the <tt class="docutils literal"><span class="pre">XSLT</span></tt> objects and store them in a read-only dictionary. That way, you can access and use them in any thread.</li> </ul> <p>Note that passing the same XSL tree into multiple <tt class="docutils literal"><span class="pre">XSLT()</span></tt> instances will create independent stylesheets, so later modifications of the tree will not be reflected in the already created stylesheets. Also, since lxml 2.0, you can deep copy XSLT objects using the <tt class="docutils literal"><span class="pre">copy</span></tt> module from the standard library.</p> </div> <div class="section"> <h2><a id="my-program-crashes-when-run-with-mod-python-pyro-zope-plone" name="my-program-crashes-when-run-with-mod-python-pyro-zope-plone">My program crashes when run with mod_python/Pyro/Zope/Plone/...</a></h2> <p>These environments can use threads in a way that may not make it obvious when threads are created and what happens in which thread. This makes it hard to ensure lxml's threading support is used in a reliable way. Sadly, if problems arise, they are as diverse as the applications, so it is difficult to provide any generally applicable solution. Also, these environments are so complex that problems become hard to debug and even harder to reproduce in a predictable way. If you encounter crashes in one of these systems, but your code runs perfectly when started by hand, the following gives you a few hints for possible approaches to solve your specific problem:</p> <ul> <li><p class="first">make sure you use recent versions of libxml2, libxslt and lxml. The libxml2 developers keep fixing bugs in each release, and lxml also tries to become more robust against possible pitfalls. So newer versions might already fix your problem in a reliable way.</p> </li> <li><p class="first">make sure the library versions you installed are really used. Do not rely on what your operating system tells you! Print the version constants in <tt class="docutils literal"><span class="pre">lxml.etree</span></tt> from within your runtime environment to make sure it is the case. This is especially a problem under MacOS-X when newer library versions were installed in addition to the outdated system libraries.</p> </li> <li><p class="first">if you use <tt class="docutils literal"><span class="pre">mod_python</span></tt>, try setting this option:</p> <blockquote> <p>PythonInterpreter main_interpreter</p> </blockquote> <p>There was a discussion on the mailing list about this problem:</p> <blockquote> <p><a class="reference" href="http://comments.gmane.org/gmane.comp.python.lxml.devel/2942">http://comments.gmane.org/gmane.comp.python.lxml.devel/2942</a></p> </blockquote> </li> <li><p class="first">compile lxml without threading support by running <tt class="docutils literal"><span class="pre">setup.py</span></tt> with the <tt class="docutils literal"><span class="pre">--without-threading</span></tt> option. While this might be slower in certain scenarios on multi-processor systems, it <em>might</em> also keep your application from crashing, which should be worth more to you than peek performance. Remember that lxml is fast anyway, so concurrency may not even be worth it.</p> </li> <li><p class="first">avoid doing fancy XSLT stuff like foreign document access or passing in subtrees trough XSLT variables. This might or might not work, depending on your specific usage.</p> </li> <li><p class="first">try copying trees at suspicious places and working with those instead of a tree shared between threads. A good candidate might be the result of an XSLT or the stylesheet itself.</p> </li> <li><p class="first">try keeping thread-local copies of XSLT stylesheets, i.e. one per thread, instead of sharing one. Also see the question above.</p> </li> <li><p class="first">you can try to serialise suspicious parts of your code with explicit thread locks, thus disabling the concurrency of the runtime system.</p> </li> <li><p class="first">report back on the mailing list to see if there are other ways to work around your specific problems. Do not forget to report the version numbers of lxml, libxml2 and libxslt you are using (see the question on reporting a bug).</p> </li> </ul> </div> </div> <div class="section"> <h1><a id="parsing-and-serialisation" name="parsing-and-serialisation">Parsing and Serialisation</a></h1> <div class="section"> <h2><a id="why-doesn-t-the-pretty-print-option-reformat-my-xml-output" name="why-doesn-t-the-pretty-print-option-reformat-my-xml-output">Why doesn't the <tt class="docutils literal"><span class="pre">pretty_print</span></tt> option reformat my XML output?</a></h2> <p>Pretty printing (or formatting) an XML document means adding white space to the content. These modifications are harmless if they only impact elements in the document that do not carry (text) data. They corrupt your data if they impact elements that contain data. If lxml cannot distinguish between whitespace and data, it will not alter your data. Whitespace is therefore only added between nodes that do not contain data. This is always the case for trees constructed element-by-element, so no problems should be expected here. For parsed trees, a good way to assure that no conflicting whitespace is left in the tree is the <tt class="docutils literal"><span class="pre">remove_blank_text</span></tt> option:</p> <pre class="literal-block"> >>> parser = etree.XMLParser(remove_blank_text=True) >>> tree = etree.parse(file, parser) </pre> <p>This will allow the parser to drop blank text nodes when constructing the tree. If you now call a serialization function to pretty print this tree, lxml can add fresh whitespace to the XML tree to indent it.</p> </div> <div class="section"> <h2><a id="why-can-t-lxml-parse-my-xml-from-unicode-strings" name="why-can-t-lxml-parse-my-xml-from-unicode-strings">Why can't lxml parse my XML from unicode strings?</a></h2> <p>lxml can read Python unicode strings and even tries to support them if libxml2 does not. However, if the unicode string declares an XML encoding internally (<tt class="docutils literal"><span class="pre"><?xml</span> <span class="pre">encoding="..."?></span></tt>), parsing is bound to fail, as this encoding is most likely not the real encoding used in Python unicode. The same is true for HTML unicode strings that contain charset meta tags, although the problems may be more subtle here. The libxml2 HTML parser may not be able to parse the meta tags in broken HTML and may end up ignoring them, so even if parsing succeeds, later handling may still fail with character encoding errors.</p> <p>Note that Python uses different encodings for unicode on different platforms, so even specifying the real internal unicode encoding is not portable between Python interpreters. Don't do it.</p> <p>Python unicode strings with XML data or HTML data that carry encoding information are broken. lxml will not parse them. You must provide parsable data in a valid encoding.</p> </div> <div class="section"> <h2><a id="what-is-the-difference-between-str-xslt-doc-and-xslt-doc-write" name="what-is-the-difference-between-str-xslt-doc-and-xslt-doc-write">What is the difference between str(xslt(doc)) and xslt(doc).write() ?</a></h2> <p>The str() implementation of the XSLTResultTree class (a subclass of the ElementTree class) knows about the output method chosen in the stylesheet (xsl:output), write() doesn't. If you call write(), the result will be a normal XML tree serialization in the requested encoding. Calling this method may also fail for XSLT results that are not XML trees (e.g. string results).</p> <p>If you call str(), it will return the serialized result as specified by the XSL transform. This correctly serializes string results to encoded Python strings and honours <tt class="docutils literal"><span class="pre">xsl:output</span></tt> options like <tt class="docutils literal"><span class="pre">indent</span></tt>. This almost certainly does what you want, so you should only use <tt class="docutils literal"><span class="pre">write()</span></tt> if you are sure that the XSLT result is an XML tree and you want to override the encoding and indentation options requested by the stylesheet.</p> </div> <div class="section"> <h2><a id="why-can-t-i-just-delete-parents-or-clear-the-root-node-in-iterparse" name="why-can-t-i-just-delete-parents-or-clear-the-root-node-in-iterparse">Why can't I just delete parents or clear the root node in iterparse()?</a></h2> <p>The <tt class="docutils literal"><span class="pre">iterparse()</span></tt> implementation is based on the libxml2 parser. It requires the tree to be intact to finish parsing. If you delete or modify parents of the current node, chances are you modify the structure in a way that breaks the parser. Normally, this will result in a segfault. Please refer to the <a class="reference" href="api.html#iterparse-and-iterwalk">iterparse section</a> of the lxml API documentation to find out what you can do and what you can't do.</p> </div> <div class="section"> <h2><a id="how-do-i-output-null-characters-in-xml-text" name="how-do-i-output-null-characters-in-xml-text">How do I output null characters in XML text?</a></h2> <p>Don't. What you would produce is not well-formed XML. XML parsers will refuse to parse a document that contains null characters. The right way to embed binary data in XML is using a text encoding such as uuencode or base64.</p> </div> </div> <div class="section"> <h1><a id="xpath-and-document-traversal" name="xpath-and-document-traversal">XPath and Document Traversal</a></h1> <div class="section"> <h2><a id="what-are-the-findall-and-xpath-methods-on-element-tree" name="what-are-the-findall-and-xpath-methods-on-element-tree">What are the <tt class="docutils literal"><span class="pre">findall()</span></tt> and <tt class="docutils literal"><span class="pre">xpath()</span></tt> methods on Element(Tree)?</a></h2> <p><tt class="docutils literal"><span class="pre">findall()</span></tt> is part of the original <a class="reference" href="http://effbot.org/zone/element-index.htm">ElementTree API</a>. It supports a <a class="reference" href="http://effbot.org/zone/element-xpath.htm">simple subset of the XPath language</a>, without predicates, conditions and other advanced features. It is very handy for finding specific tags in a tree. Another important difference is namespace handling, which uses the <tt class="docutils literal"><span class="pre">{namespace}tagname</span></tt> notation. This is not supported by XPath. The findall, find and findtext methods are compatible with other ElementTree implementations and allow writing portable code that runs on ElementTree, cElementTree and lxml.etree.</p> <p><tt class="docutils literal"><span class="pre">xpath()</span></tt>, on the other hand, supports the complete power of the XPath language, including predicates, XPath functions and Python extension functions. The syntax is defined by the <a class="reference" href="http://www.w3.org/TR/xpath">XPath specification</a>. If you need the expressiveness and selectivity of XPath, the <tt class="docutils literal"><span class="pre">xpath()</span></tt> method, the <tt class="docutils literal"><span class="pre">XPath</span></tt> class and the <tt class="docutils literal"><span class="pre">XPathEvaluator</span></tt> are the best <a class="reference" href="performance.html#xpath">choice</a>.</p> </div> <div class="section"> <h2><a id="why-doesn-t-findall-support-full-xpath-expressions" name="why-doesn-t-findall-support-full-xpath-expressions">Why doesn't <tt class="docutils literal"><span class="pre">findall()</span></tt> support full XPath expressions?</a></h2> <p>It was decided that it is more important to keep compatibility with <a class="reference" href="http://effbot.org/zone/element-index.htm">ElementTree</a> to simplify code migration between the libraries. The main difference compared to XPath is the <tt class="docutils literal"><span class="pre">{namespace}tagname</span></tt> notation used in <tt class="docutils literal"><span class="pre">findall()</span></tt>, which is not valid XPath.</p> <p>ElementTree and lxml.etree use the same implementation, which assures 100% compatibility. Note that <tt class="docutils literal"><span class="pre">findall()</span></tt> is <a class="reference" href="performance.html#tree-traversal">so fast</a> in lxml that a native implementation would not bring any performance benefits.</p> </div> <div class="section"> <h2><a id="how-can-i-find-out-which-namespace-prefixes-are-used-in-a-document" name="how-can-i-find-out-which-namespace-prefixes-are-used-in-a-document">How can I find out which namespace prefixes are used in a document?</a></h2> <p>You can traverse the document (<tt class="docutils literal"><span class="pre">getiterator()</span></tt>) and collect the prefix attributes from all Elements into a set. However, it is unlikely that you really want to do that. You do not need these prefixes, honestly. You only need the namespace URIs. All namespace comparisons use these, so feel free to make up your own prefixes when you use XPath expressions or extension functions.</p> <p>The only place where you might consider specifying prefixes is the serialization of Elements that were created through the API. Here, you can specify a prefix mapping through the <tt class="docutils literal"><span class="pre">nsmap</span></tt> argument when creating the root Element. Its children will then inherit this prefix for serialization.</p> </div> <div class="section"> <h2><a id="how-can-i-specify-a-default-namespace-for-xpath-expressions" name="how-can-i-specify-a-default-namespace-for-xpath-expressions">How can I specify a default namespace for XPath expressions?</a></h2> <p>You can't. In XPath, there is no such thing as a default namespace. Just use an arbitrary prefix and let the namespace dictionary of the XPath evaluators map it to your namespace. See also the question above.</p> </div> </div> </div> <div class="footer"> <hr class="footer" /> Generated on: 2008-12-12. </div> </body> </html>