doc/html/FAQ.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5 <meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
   6 <title>lxml FAQ - Frequently Asked Questions</title>
   7 <meta content="Frequently Asked Questions about lxml (FAQ)" name="description" />
   8 <meta content="lxml, lxml.etree, FAQ, frequently asked questions" name="keywords" />
   9 <link rel="stylesheet" href="style.css" type="text/css" />
  10 </head>
  11 <body>
  12 <div class="document" id="lxml-faq-frequently-asked-questions">
  13 <div class="sidemenu"><ul id="lxml-section"><li><span class="section title">lxml</span><ul class="menu foreign" id="index-menu"><li class="menu title"><a href="index.html">lxml</a><ul class="submenu"><li class="menu item"><a href="index.html#introduction">Introduction</a></li><li class="menu item"><a href="index.html#support-the-project">Support the project</a></li><li class="menu item"><a href="index.html#documentation">Documentation</a></li><li class="menu item"><a href="index.html#download">Download</a></li><li class="menu item"><a href="index.html#mailing-list">Mailing list</a></li><li class="menu item"><a href="index.html#bug-tracker">Bug tracker</a></li><li class="menu item"><a href="index.html#license">License</a></li><li class="menu item"><a href="index.html#old-versions">Old Versions</a></li><li class="menu item"><a href="index.html#legal-notice-for-donations">Legal Notice for Donations</a></li></ul></li></ul><ul class="menu foreign" id="intro-menu"><li class="menu title"><a href="intro.html">Why lxml?</a><ul class="submenu"><li class="menu item"><a href="intro.html#motto">Motto</a></li><li class="menu item"><a href="intro.html#aims">Aims</a></li></ul></li></ul><ul class="menu foreign" id="installation-menu"><li class="menu title"><a href="installation.html">Installing lxml</a><ul class="submenu"><li class="menu item"><a href="installation.html#requirements">Requirements</a></li><li class="menu item"><a href="installation.html#installation">Installation</a></li><li class="menu item"><a href="installation.html#building-lxml-from-sources">Building lxml from sources</a></li><li class="menu item"><a href="installation.html#using-lxml-with-python-libxml2">Using lxml with python-libxml2</a></li><li class="menu item"><a href="installation.html#ms-windows">MS Windows</a></li><li class="menu item"><a href="installation.html#macos-x">MacOS-X</a></li></ul></li></ul><ul class="menu foreign" id="performance-menu"><li class="menu title"><a href="performance.html">Benchmarks and Speed</a><ul class="submenu"><li class="menu item"><a href="performance.html#general-notes">General notes</a></li><li class="menu item"><a href="performance.html#how-to-read-the-timings">How to read the timings</a></li><li class="menu item"><a href="performance.html#parsing-and-serialising">Parsing and Serialising</a></li><li class="menu item"><a href="performance.html#the-elementtree-api">The ElementTree API</a></li><li class="menu item"><a href="performance.html#xpath">XPath</a></li><li class="menu item"><a href="performance.html#a-longer-example">A longer example</a></li><li class="menu item"><a href="performance.html#lxml-objectify">lxml.objectify</a></li></ul></li></ul><ul class="menu foreign" id="compatibility-menu"><li class="menu title"><a href="compatibility.html">ElementTree compatibility of lxml.etree</a></li></ul><ul class="menu current" id="FAQ-menu"><li class="menu title"><a href="FAQ.html">lxml FAQ - Frequently Asked Questions</a><ul class="submenu"><li class="menu item"><a href="FAQ.html#general-questions">General Questions</a></li><li class="menu item"><a href="FAQ.html#installation">Installation</a></li><li class="menu item"><a href="FAQ.html#contributing">Contributing</a></li><li class="menu item"><a href="FAQ.html#bugs">Bugs</a></li><li class="menu item"><a href="FAQ.html#id1">Threading</a></li><li class="menu item"><a href="FAQ.html#parsing-and-serialisation">Parsing and Serialisation</a></li><li class="menu item"><a href="FAQ.html#xpath-and-document-traversal">XPath and Document Traversal</a></li></ul></li></ul></li></ul><ul id="Developing with lxml-section"><li><span class="section title">Developing with lxml</span><ul class="menu foreign" id="tutorial-menu"><li class="menu title"><a href="tutorial.html">The lxml.etree Tutorial</a><ul class="submenu"><li class="menu item"><a href="tutorial.html#the-element-class">The Element class</a></li><li class="menu item"><a href="tutorial.html#the-elementtree-class">The ElementTree class</a></li><li class="menu item"><a href="tutorial.html#parsing-from-strings-and-files">Parsing from strings and files</a></li><li class="menu item"><a href="tutorial.html#namespaces">Namespaces</a></li><li class="menu item"><a href="tutorial.html#the-e-factory">The E-factory</a></li><li class="menu item"><a href="tutorial.html#elementpath">ElementPath</a></li></ul></li></ul><ul class="menu foreign" id="api index-menu"><li class="menu title"><a href="api/index.html">API reference</a></li></ul><ul class="menu foreign" id="api-menu"><li class="menu title"><a href="api.html">APIs specific to lxml.etree</a><ul class="submenu"><li class="menu item"><a href="api.html#lxml-etree">lxml.etree</a></li><li class="menu item"><a href="api.html#other-element-apis">Other Element APIs</a></li><li class="menu item"><a href="api.html#trees-and-documents">Trees and Documents</a></li><li class="menu item"><a href="api.html#iteration">Iteration</a></li><li class="menu item"><a href="api.html#error-handling-on-exceptions">Error handling on exceptions</a></li><li class="menu item"><a href="api.html#error-logging">Error logging</a></li><li class="menu item"><a href="api.html#serialisation">Serialisation</a></li><li class="menu item"><a href="api.html#cdata">CDATA</a></li><li class="menu item"><a href="api.html#xinclude-and-elementinclude">XInclude and ElementInclude</a></li><li class="menu item"><a href="api.html#write-c14n-on-elementtree">write_c14n on ElementTree</a></li></ul></li></ul><ul class="menu foreign" id="parsing-menu"><li class="menu title"><a href="parsing.html">Parsing XML and HTML with lxml</a><ul class="submenu"><li class="menu item"><a href="parsing.html#parsers">Parsers</a></li><li class="menu item"><a href="parsing.html#the-target-parser-interface">The target parser interface</a></li><li class="menu item"><a href="parsing.html#the-feed-parser-interface">The feed parser interface</a></li><li class="menu item"><a href="parsing.html#iterparse-and-iterwalk">iterparse and iterwalk</a></li><li class="menu item"><a href="parsing.html#python-unicode-strings">Python unicode strings</a></li></ul></li></ul><ul class="menu foreign" id="validation-menu"><li class="menu title"><a href="validation.html">Validation with lxml</a><ul class="submenu"><li class="menu item"><a href="validation.html#validation-at-parse-time">Validation at parse time</a></li><li class="menu item"><a href="validation.html#id1">DTD</a></li><li class="menu item"><a href="validation.html#relaxng">RelaxNG</a></li><li class="menu item"><a href="validation.html#xmlschema">XMLSchema</a></li><li class="menu item"><a href="validation.html#id2">Schematron</a></li><li class="menu item"><a href="validation.html#id3">(Pre-ISO-Schematron)</a></li></ul></li></ul><ul class="menu foreign" id="xpathxslt-menu"><li class="menu title"><a href="xpathxslt.html">XPath and XSLT with lxml</a><ul class="submenu"><li class="menu item"><a href="xpathxslt.html#xpath">XPath</a></li><li class="menu item"><a href="xpathxslt.html#xslt">XSLT</a></li></ul></li></ul><ul class="menu 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><li class="menu item"><a href="elementsoup.html#using-only-the-encoding-detection">Using only the encoding detection</a></li></ul></li></ul><ul class="menu foreign" id="html5parser-menu"><li class="menu title"><a href="html5parser.html">html5lib Parser</a><ul class="submenu"><li class="menu item"><a href="html5parser.html#differences-to-regular-html-parsing">Differences to regular HTML parsing</a></li><li class="menu item"><a href="html5parser.html#function-reference">Function Reference</a></li></ul></li></ul></li></ul><ul id="Extending lxml-section"><li><span class="section title">Extending lxml</span><ul class="menu foreign" id="resolvers-menu"><li class="menu title"><a href="resolvers.html">Document loading and URL resolving</a><ul class="submenu"><li class="menu item"><a href="resolvers.html#xml-catalogs">XML Catalogs</a></li><li class="menu item"><a href="resolvers.html#uri-resolvers">URI Resolvers</a></li><li class="menu item"><a href="resolvers.html#document-loading-in-context">Document loading in context</a></li><li class="menu item"><a href="resolvers.html#i-o-access-control-in-xslt">I/O access control in XSLT</a></li></ul></li></ul><ul class="menu foreign" id="extensions-menu"><li class="menu title"><a href="extensions.html">Python extensions for XPath and XSLT</a><ul class="submenu"><li class="menu item"><a href="extensions.html#xpath-extension-functions">XPath Extension functions</a></li><li class="menu item"><a href="extensions.html#xslt-extension-elements">XSLT extension elements</a></li></ul></li></ul><ul class="menu foreign" id="element classes-menu"><li class="menu title"><a href="element_classes.html">Using custom Element classes in lxml</a><ul class="submenu"><li class="menu item"><a href="element_classes.html#background-on-element-proxies">Background on Element proxies</a></li><li class="menu item"><a href="element_classes.html#element-initialization">Element initialization</a></li><li class="menu item"><a href="element_classes.html#setting-up-a-class-lookup-scheme">Setting up a class lookup scheme</a></li><li class="menu item"><a href="element_classes.html#generating-xml-with-custom-classes">Generating XML with custom classes</a></li><li class="menu item"><a href="element_classes.html#id1">Implementing namespaces</a></li></ul></li></ul><ul class="menu foreign" id="sax-menu"><li class="menu title"><a href="sax.html">Sax support</a><ul class="submenu"><li class="menu item"><a href="sax.html#building-a-tree-from-sax-events">Building a tree from SAX events</a></li><li class="menu item"><a href="sax.html#producing-sax-events-from-an-elementtree-or-element">Producing SAX events from an ElementTree or Element</a></li><li class="menu item"><a href="sax.html#interfacing-with-pulldom-minidom">Interfacing with pulldom/minidom</a></li></ul></li></ul><ul class="menu foreign" id="capi-menu"><li class="menu title"><a href="capi.html">The public C-API of lxml.etree</a><ul class="submenu"><li class="menu item"><a href="capi.html#writing-external-modules-in-cython">Writing external modules in Cython</a></li><li class="menu item"><a href="capi.html#writing-external-modules-in-c">Writing external modules in C</a></li></ul></li></ul></li></ul><ul id="Developing lxml-section"><li><span class="section title">Developing lxml</span><ul class="menu foreign" id="build-menu"><li class="menu title"><a href="build.html">How to build lxml from source</a><ul class="submenu"><li class="menu item"><a href="build.html#cython">Cython</a></li><li class="menu item"><a href="build.html#github-git-and-hg">Github, git and hg</a></li><li class="menu item"><a href="build.html#id2">Setuptools</a></li><li class="menu item"><a href="build.html#running-the-tests-and-reporting-errors">Running the tests and reporting errors</a></li><li class="menu item"><a href="build.html#building-an-egg">Building an egg</a></li><li class="menu item"><a href="build.html#building-lxml-on-macos-x">Building lxml on MacOS-X</a></li><li class="menu item"><a href="build.html#static-linking-on-windows">Static linking on Windows</a></li><li class="menu item"><a href="build.html#building-debian-packages-from-svn-sources">Building Debian packages from SVN sources</a></li></ul></li></ul><ul class="menu foreign" id="lxml source howto-menu"><li class="menu title"><a href="lxml-source-howto.html">How to read the source of lxml</a><ul class="submenu"><li class="menu item"><a href="lxml-source-howto.html#what-is-cython">What is Cython?</a></li><li class="menu item"><a href="lxml-source-howto.html#where-to-start">Where to start?</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-etree">lxml.etree</a></li><li class="menu item"><a href="lxml-source-howto.html#python-modules">Python modules</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-objectify">lxml.objectify</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-html">lxml.html</a></li></ul></li></ul><ul class="menu foreign" id="changes 2 3 5-menu"><li class="menu title"><a href="changes-2.3.5.html">Release Changelog</a></li></ul><ul class="menu foreign" id="credits-menu"><li class="menu title"><a href="credits.html">Credits</a><ul class="submenu"><li class="menu item"><a href="credits.html#main-contributors">Main contributors</a></li><li class="menu item"><a href="credits.html#special-thanks-goes-to">Special thanks goes to:</a></li></ul></li></ul></li><li><a href="http://lxml.de/sitemap.html">Sitemap</a></li></ul></div><h1 class="title">lxml FAQ - Frequently Asked Questions</h1>
  14
  15 <p>Frequently asked questions on lxml.  See also the notes on <a class="reference external" href="compatibility.html">compatibility</a> to
  16 <a class="reference external" href="http://effbot.org/zone/element-index.htm">ElementTree</a>.</p>
  17 <div class="contents topic" id="contents">
  18 <p class="topic-title first">Contents</p>
  19 <ul class="simple">
  20 <li><a class="reference internal" href="#general-questions" id="id2">General Questions</a><ul>
  21 <li><a class="reference internal" href="#is-there-a-tutorial" id="id3">Is there a tutorial?</a></li>
  22 <li><a class="reference internal" href="#where-can-i-find-more-documentation-about-lxml" id="id4">Where can I find more documentation about lxml?</a></li>
  23 <li><a class="reference internal" href="#what-standards-does-lxml-implement" id="id5">What standards does lxml implement?</a></li>
  24 <li><a class="reference internal" href="#who-uses-lxml" id="id6">Who uses lxml?</a></li>
  25 <li><a class="reference internal" href="#what-is-the-difference-between-lxml-etree-and-lxml-objectify" id="id7">What is the difference between lxml.etree and lxml.objectify?</a></li>
  26 <li><a class="reference internal" href="#how-can-i-make-my-application-run-faster" id="id8">How can I make my application run faster?</a></li>
  27 <li><a class="reference internal" href="#what-about-that-trailing-text-on-serialised-elements" id="id9">What about that trailing text on serialised Elements?</a></li>
  28 <li><a class="reference internal" href="#how-can-i-find-out-if-an-element-is-a-comment-or-pi" id="id10">How can I find out if an Element is a comment or PI?</a></li>
  29 <li><a class="reference internal" href="#how-can-i-map-an-xml-tree-into-a-dict-of-dicts" id="id11">How can I map an XML tree into a dict of dicts?</a></li>
  30 </ul>
  31 </li>
  32 <li><a class="reference internal" href="#installation" id="id12">Installation</a><ul>
  33 <li><a class="reference internal" href="#which-version-of-libxml2-and-libxslt-should-i-use-or-require" id="id13">Which version of libxml2 and libxslt should I use or require?</a></li>
  34 <li><a class="reference internal" href="#where-are-the-binary-builds" id="id14">Where are the binary builds?</a></li>
  35 <li><a class="reference internal" href="#why-do-i-get-errors-about-missing-ucs4-symbols-when-installing-lxml" id="id15">Why do I get errors about missing UCS4 symbols when installing lxml?</a></li>
  36 </ul>
  37 </li>
  38 <li><a class="reference internal" href="#contributing" id="id16">Contributing</a><ul>
  39 <li><a class="reference internal" href="#why-is-lxml-not-written-in-python" id="id17">Why is lxml not written in Python?</a></li>
  40 <li><a class="reference internal" href="#how-can-i-contribute" id="id18">How can I contribute?</a></li>
  41 </ul>
  42 </li>
  43 <li><a class="reference internal" href="#bugs" id="id19">Bugs</a><ul>
  44 <li><a class="reference internal" href="#my-application-crashes" id="id20">My application crashes!</a></li>
  45 <li><a class="reference internal" href="#my-application-crashes-on-macos-x" id="id21">My application crashes on MacOS-X!</a></li>
  46 <li><a class="reference internal" href="#i-think-i-have-found-a-bug-in-lxml-what-should-i-do" id="id22">I think I have found a bug in lxml. What should I do?</a></li>
  47 <li><a class="reference internal" href="#how-do-i-know-a-bug-is-really-in-lxml-and-not-in-libxml2" id="id23">How do I know a bug is really in lxml and not in libxml2?</a></li>
  48 </ul>
  49 </li>
  50 <li><a class="reference internal" href="#id1" id="id24">Threading</a><ul>
  51 <li><a class="reference internal" href="#can-i-use-threads-to-concurrently-access-the-lxml-api" id="id25">Can I use threads to concurrently access the lxml API?</a></li>
  52 <li><a class="reference internal" href="#does-my-program-run-faster-if-i-use-threads" id="id26">Does my program run faster if I use threads?</a></li>
  53 <li><a class="reference internal" href="#would-my-single-threaded-program-run-faster-if-i-turned-off-threading" id="id27">Would my single-threaded program run faster if I turned off threading?</a></li>
  54 <li><a class="reference internal" href="#why-can-t-i-reuse-xslt-stylesheets-in-other-threads" id="id28">Why can't I reuse XSLT stylesheets in other threads?</a></li>
  55 <li><a class="reference internal" href="#my-program-crashes-when-run-with-mod-python-pyro-zope-plone" id="id29">My program crashes when run with mod_python/Pyro/Zope/Plone/...</a></li>
  56 </ul>
  57 </li>
  58 <li><a class="reference internal" href="#parsing-and-serialisation" id="id30">Parsing and Serialisation</a><ul>
  59 <li><a class="reference internal" href="#why-doesn-t-the-pretty-print-option-reformat-my-xml-output" id="id31">Why doesn't the <tt class="docutils literal">pretty_print</tt> option reformat my XML output?</a></li>
  60 <li><a class="reference internal" href="#why-can-t-lxml-parse-my-xml-from-unicode-strings" id="id32">Why can't lxml parse my XML from unicode strings?</a></li>
  61 <li><a class="reference internal" href="#what-is-the-difference-between-str-xslt-doc-and-xslt-doc-write" id="id33">What is the difference between str(xslt(doc)) and xslt(doc).write() ?</a></li>
  62 <li><a class="reference internal" href="#why-can-t-i-just-delete-parents-or-clear-the-root-node-in-iterparse" id="id34">Why can't I just delete parents or clear the root node in iterparse()?</a></li>
  63 <li><a class="reference internal" href="#how-do-i-output-null-characters-in-xml-text" id="id35">How do I output null characters in XML text?</a></li>
  64 <li><a class="reference internal" href="#is-lxml-vulnerable-to-xml-bombs" id="id36">Is lxml vulnerable to XML bombs?</a></li>
  65 <li><a class="reference internal" href="#can-lxml-parse-from-file-objects-opened-in-unicode-text-mode" id="id37">Can lxml parse from file objects opened in unicode/text mode?</a></li>
  66 </ul>
  67 </li>
  68 <li><a class="reference internal" href="#xpath-and-document-traversal" id="id38">XPath and Document Traversal</a><ul>
  69 <li><a class="reference internal" href="#what-are-the-findall-and-xpath-methods-on-element-tree" id="id39">What are the <tt class="docutils literal">findall()</tt> and <tt class="docutils literal">xpath()</tt> methods on Element(Tree)?</a></li>
  70 <li><a class="reference internal" href="#why-doesn-t-findall-support-full-xpath-expressions" id="id40">Why doesn't <tt class="docutils literal">findall()</tt> support full XPath expressions?</a></li>
  71 <li><a class="reference internal" href="#how-can-i-find-out-which-namespace-prefixes-are-used-in-a-document" id="id41">How can I find out which namespace prefixes are used in a document?</a></li>
  72 <li><a class="reference internal" href="#how-can-i-specify-a-default-namespace-for-xpath-expressions" id="id42">How can I specify a default namespace for XPath expressions?</a></li>
  73 </ul>
  74 </li>
  75 </ul>
  76 </div>
  77 <div class="section" id="general-questions">
  78 <h1>General Questions</h1>
  79 <div class="section" id="is-there-a-tutorial">
  80 <h2>Is there a tutorial?</h2>
  81 <p>Read the <a class="reference external" href="tutorial.html">lxml.etree Tutorial</a>.  While this is still work in progress
  82 (just as any good documentation), it provides an overview of the most
  83 important concepts in <tt class="docutils literal">lxml.etree</tt>.  If you want to help out,
  84 improving the tutorial is a very good place to start.</p>
  85 <p>There is also a <a class="reference external" href="http://effbot.org/zone/element.htm">tutorial for ElementTree</a> which works for
  86 <tt class="docutils literal">lxml.etree</tt>.  The documentation of the <a class="reference external" href="api.html">extended etree API</a> also
  87 contains many examples for <tt class="docutils literal">lxml.etree</tt>.  Fredrik Lundh's <a class="reference external" href="http://effbot.org/zone/element-lib.htm">element
  88 library</a> contains a lot of nice recipes that show how to solve common
  89 tasks in ElementTree and lxml.etree.  To learn using
  90 <tt class="docutils literal">lxml.objectify</tt>, read the <a class="reference external" href="objectify.html">objectify documentation</a>.</p>
  91 <p>John Shipman has written another tutorial called <a class="reference external" href="http://www.nmt.edu/tcc/help/pubs/pylxml/">Python XML
  92 processing with lxml</a> that contains lots of examples.  Liza Daly
  93 wrote a nice article about high-performance aspects when <a class="reference external" href="http://www.ibm.com/developerworks/xml/library/x-hiperfparse/">parsing
  94 large files with lxml</a>.</p>
  95 </div>
  96 <div class="section" id="where-can-i-find-more-documentation-about-lxml">
  97 <h2>Where can I find more documentation about lxml?</h2>
  98 <p>There is a lot of documentation on the web and also in the Python
  99 standard library documentation, as lxml implements the well-known
 100 <a class="reference external" href="http://effbot.org/zone/element-index.htm">ElementTree API</a> and tries to follow its documentation as closely as
 101 possible.  The recipes in Fredrik Lundh's <a class="reference external" href="http://effbot.org/zone/element-lib.htm">element library</a> are
 102 generally worth taking a look at.  There are a couple of issues where
 103 lxml cannot keep up compatibility.  They are described in the
 104 <a class="reference external" href="compatibility.html">compatibility</a> documentation.</p>
 105 <p>The lxml specific extensions to the API are described by individual
 106 files in the <tt class="docutils literal">doc</tt> directory of the source distribution and on <a class="reference external" href="http://lxml.de/#documentation">the
 107 web page</a>.</p>
 108 <p>The <a class="reference external" href="api/index.html">generated API documentation</a> is a comprehensive API reference
 109 for the lxml package.</p>
 110 </div>
 111 <div class="section" id="what-standards-does-lxml-implement">
 112 <h2>What standards does lxml implement?</h2>
 113 <p>The compliance to XML Standards depends on the support in libxml2 and libxslt.
 114 Here is a quote from <a class="reference external" href="http://xmlsoft.org/">http://xmlsoft.org/</a>:</p>
 115 <blockquote>
 116 In most cases libxml2 tries to implement the specifications in a relatively
 117 strictly compliant way. As of release 2.4.16, libxml2 passed all 1800+ tests
 118 from the OASIS XML Tests Suite.</blockquote>
 119 <p>lxml currently supports libxml2 2.6.20 or later, which has even better
 120 support for various XML standards.  The important ones are:</p>
 121 <ul class="simple">
 122 <li>XML 1.0</li>
 123 <li>HTML 4</li>
 124 <li>XML namespaces</li>
 125 <li>XML Schema 1.0</li>
 126 <li>XPath 1.0</li>
 127 <li>XInclude 1.0</li>
 128 <li>XSLT 1.0</li>
 129 <li>EXSLT</li>
 130 <li>XML catalogs</li>
 131 <li>canonical XML</li>
 132 <li>RelaxNG</li>
 133 <li>xml:id</li>
 134 <li>xml:base</li>
 135 </ul>
 136 <p>Support for XML Schema is currently not 100% complete in libxml2, but
 137 is definitely very close to compliance.  Schematron is supported in
 138 two ways, the best being the original ISO Schematron reference
 139 implementation via XSLT.  libxml2 also supports loading documents
 140 through HTTP and FTP.</p>
 141 </div>
 142 <div class="section" id="who-uses-lxml">
 143 <h2>Who uses lxml?</h2>
 144 <p>As an XML library, lxml is often used under the hood of in-house
 145 server applications, such as web servers or applications that
 146 facilitate some kind of content management.  Many people who deploy
 147 <a class="reference external" href="http://www.zope.org/">Zope</a>, <a class="reference external" href="http://www.plone.org/">Plone</a> or <a class="reference external" href="https://www.djangoproject.com/">Django</a> use it together with lxml in the background,
 148 without speaking publicly about it.  Therefore, it is hard to get an
 149 idea of who uses it, and the following list of 'users and projects we
 150 know of' is very far from a complete list of lxml's users.</p>
 151 <p>Also note that the compatibility to the ElementTree library does not
 152 require projects to set a hard dependency on lxml - as long as they do
 153 not take advantage of lxml's enhanced feature set.</p>
 154 <ul class="simple">
 155 <li><a class="reference external" 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">lxml.cssselect</tt></li>
 156 <li><a class="reference external" href="http://www.openplans.org/projects/deliverance/project-home">Deliverance</a>, a content theming tool</li>
 157 <li><a class="reference external" href="http://www.enfoldsystems.com/Products/Proxy/4">Enfold Proxy 4</a>, a web server accelerator with on-the-fly XSLT processing</li>
 158 <li><a class="reference external" href="http://lists.wald.intevation.org/pipermail/inteproxy-devel/2007-February/000000.html">Inteproxy</a>, a secure HTTP proxy</li>
 159 <li><a class="reference external" href="http://pypi.python.org/pypi/lwebstring">lwebstring</a>, an XML template engine</li>
 160 <li><a class="reference external" href="http://permalink.gmane.org/gmane.comp.python.lxml.devel/3250">OpenXMLlib</a>, a library for handling OpenXML document meta data</li>
 161 <li><a class="reference external" href="http://www.psychopy.org/">PsychoPy</a>, psychology software in Python</li>
 162 <li><a class="reference external" href="http://pypi.python.org/pypi/pycoon">Pycoon</a>, a WSGI web development framework based on XML pipelines</li>
 163 <li><a class="reference external" href="http://pypi.python.org/pypi/pyquery">PyQuery</a>, a query framework for XML/HTML, similar to jQuery for JavaScript</li>
 164 <li><a class="reference external" href="http://github.com/mikemaccana/python-docx">python-docx</a>, a package for handling Microsoft's Word OpenXML format</li>
 165 <li><a class="reference external" href="http://beta.rambler.ru/srch?query=python+lxml&amp;searchtype=web">Rambler</a>, a meta search engine that aggregates different data sources</li>
 166 <li><a class="reference external" href="http://pypi.python.org/pypi/rdfadict">rdfadict</a>, an RDFa parser with a simple dictionary-like interface.</li>
 167 <li><a class="reference external" href="http://pypi.python.org/pypi/xupdate-processor">xupdate-processor</a>, an XUpdate implementation for lxml.etree</li>
 168 </ul>
 169 <p>Zope3 and some of its extensions have good support for lxml:</p>
 170 <ul class="simple">
 171 <li><a class="reference external" href="http://pypi.python.org/pypi/gocept.lxml">gocept.lxml</a>, Zope3 interface bindings for lxml</li>
 172 <li><a class="reference external" href="http://pypi.python.org/pypi/z3c.rml">z3c.rml</a>, an implementation of ReportLab's RML format</li>
 173 <li><a class="reference external" href="http://pypi.python.org/pypi/zif.sedna">zif.sedna</a>, an XQuery based interface to the Sedna OpenSource XML database</li>
 174 </ul>
 175 <p>And don't miss the quotes by our generally <a class="reference external" href="http://thread.gmane.org/gmane.comp.python.lxml.devel/3244/focus=3244">happy</a> <a class="reference external" href="http://article.gmane.org/gmane.comp.python.lxml.devel/3246">users</a>, and other
 176 <a class="reference external" href="http://www.google.com/search?as_lq=http:%2F%2Flxml.de%2F">sites that link to lxml</a>.   As <a class="reference external" href="http://www.ibm.com/developerworks/xml/library/x-hiperfparse/">Liza Daly</a> puts it: "Many software
 177 products come with the pick-two caveat, meaning that you must choose
 178 only two: speed, flexibility, or readability.  When used carefully,
 179 lxml can provide all three."</p>
 180 </div>
 181 <div class="section" id="what-is-the-difference-between-lxml-etree-and-lxml-objectify">
 182 <h2>What is the difference between lxml.etree and lxml.objectify?</h2>
 183 <p>The two modules provide different ways of handling XML.  However, objectify
 184 builds on top of lxml.etree and therefore inherits most of its capabilities
 185 and a large portion of its API.</p>
 186 <ul>
 187 <li><p class="first">lxml.etree is a generic API for XML and HTML handling.  It aims for
 188 ElementTree <a class="reference external" href="compatibility.html">compatibility</a> and supports the entire XML infoset.  It is well
 189 suited for both mixed content and data centric XML.  Its generality makes it
 190 the best choice for most applications.</p>
 191 </li>
 192 <li><p class="first">lxml.objectify is a specialized API for XML data handling in a Python object
 193 syntax.  It provides a very natural way to deal with data fields stored in a
 194 structurally well defined XML format.  Data is automatically converted to
 195 Python data types and can be manipulated with normal Python operators.  Look
 196 at the examples in the <a class="reference external" href="objectify.html">objectify documentation</a> to see what it feels like
 197 to use it.</p>
 198 <p>Objectify is not well suited for mixed contents or HTML documents.  As it is
 199 built on top of lxml.etree, however, it inherits the normal support for
 200 XPath, XSLT or validation.</p>
 201 </li>
 202 </ul>
 203 </div>
 204 <div class="section" id="how-can-i-make-my-application-run-faster">
 205 <h2>How can I make my application run faster?</h2>
 206 <p>lxml.etree is a very fast library for processing XML.  There are, however, <a class="reference external" href="performance.html#the-elementtree-api">a
 207 few caveats</a> involved in the mapping of the powerful libxml2 library to the
 208 simple and convenient ElementTree API.  Not all operations are as fast as the
 209 simplicity of the API might suggest, while some use cases can heavily benefit
 210 from finding the right way of doing them.  The <a class="reference external" href="performance.html">benchmark page</a> has a
 211 comparison to other ElementTree implementations and a number of tips for
 212 performance tweaking.  As with any Python application, the rule of thumb is:
 213 the more of your processing runs in C, the faster your application gets.  See
 214 also the section on <a class="reference external" href="#threading">threading</a>.</p>
 215 </div>
 216 <div class="section" id="what-about-that-trailing-text-on-serialised-elements">
 217 <h2>What about that trailing text on serialised Elements?</h2>
 218 <p>The ElementTree tree model defines an Element as a container with a tag name,
 219 contained text, child Elements and a tail text.  This means that whenever you
 220 serialise an Element, you will get all parts of that Element:</p>
 221 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">root</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">XML</span><span class="p">(</span><span class="s">"&lt;root&gt;&lt;tag&gt;text&lt;child/&gt;&lt;/tag&gt;tail&lt;/root&gt;"</span><span class="p">)</span>
 222 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="mi">0</span><span class="p">]))</span>
 223 <span class="go">&lt;tag&gt;text&lt;child/&gt;&lt;/tag&gt;tail</span>
 224 </pre></div>
 225 <p>Here is an example that shows why not serialising the tail would be
 226 even more surprising from an object point of view:</p>
 227 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">root</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"test"</span><span class="p">)</span>
 228
 229 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="s">"TEXT"</span>
 230 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
 231 <span class="go">&lt;test&gt;TEXT&lt;/test&gt;</span>
 232
 233 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">tail</span> <span class="o">=</span> <span class="s">"TAIL"</span>
 234 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
 235 <span class="go">&lt;test&gt;TEXT&lt;/test&gt;TAIL</span>
 236
 237 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">tail</span> <span class="o">=</span> <span class="bp">None</span>
 238 <span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
 239 <span class="go">&lt;test&gt;TEXT&lt;/test&gt;</span>
 240 </pre></div>
 241 <p>Just imagine a Python list where you append an item and it doesn't
 242 show up when you look at the list.</p>
 243 <p>The <tt class="docutils literal">.tail</tt> property is a huge simplification for the tree model as
 244 it avoids text nodes to appear in the list of children and makes
 245 access to them quick and simple.  So this is a benefit in most
 246 applications and simplifies many, many XML tree algorithms.</p>
 247 <p>However, in document-like XML (and especially HTML), the above result can be
 248 unexpected to new users and can sometimes require a bit more overhead.  A good
 249 way to deal with this is to use helper functions that copy the Element without
 250 its tail.  The <tt class="docutils literal">lxml.html</tt> package also deals with this in a couple of
 251 places, as most HTML algorithms benefit from a tail-free behaviour.</p>
 252 </div>
 253 <div class="section" id="how-can-i-find-out-if-an-element-is-a-comment-or-pi">
 254 <h2>How can I find out if an Element is a comment or PI?</h2>
 255 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">root</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">XML</span><span class="p">(</span><span class="s">"&lt;?my PI?&gt;&lt;root&gt;&lt;!-- empty --&gt;&lt;/root&gt;"</span><span class="p">)</span>
 256
 257 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">tag</span>
 258 <span class="go">'root'</span>
 259 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="o">.</span><span class="n">getprevious</span><span class="p">()</span><span class="o">.</span><span class="n">tag</span> <span class="ow">is</span> <span class="n">etree</span><span class="o">.</span><span class="n">PI</span>
 260 <span class="go">True</span>
 261 <span class="gp">&gt;&gt;&gt; </span><span class="n">root</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span> <span class="ow">is</span> <span class="n">etree</span><span class="o">.</span><span class="n">Comment</span>
 262 <span class="go">True</span>
 263 </pre></div>
 264 </div>
 265 <div class="section" id="how-can-i-map-an-xml-tree-into-a-dict-of-dicts">
 266 <h2>How can I map an XML tree into a dict of dicts?</h2>
 267 <p>I'm glad you asked.</p>
 268 <div class="syntax"><pre><span class="k">def</span> <span class="nf">recursive_dict</span><span class="p">(</span><span class="n">element</span><span class="p">):</span>
 269      <span class="k">return</span> <span class="n">element</span><span class="o">.</span><span class="n">tag</span><span class="p">,</span> \
 270             <span class="nb">dict</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">recursive_dict</span><span class="p">,</span> <span class="n">element</span><span class="p">))</span> <span class="ow">or</span> <span class="n">element</span><span class="o">.</span><span class="n">text</span>
 271 </pre></div>
 272 </div>
 273 </div>
 274 <div class="section" id="installation">
 275 <h1>Installation</h1>
 276 <div class="section" id="which-version-of-libxml2-and-libxslt-should-i-use-or-require">
 277 <h2>Which version of libxml2 and libxslt should I use or require?</h2>
 278 <p>It really depends on your application, but the rule of thumb is: more recent
 279 versions contain less bugs and provide more features.</p>
 280 <ul class="simple">
 281 <li>Do not use libxml2 2.6.27 if you want to use XPath (including XSLT).  You
 282 will get crashes when XPath errors occur during the evaluation (e.g. for
 283 unknown functions).  This happens inside the evaluation call to libxml2, so
 284 there is nothing that lxml can do about it.</li>
 285 <li>Try to use versions of both libraries that were released together.  At least
 286 the libxml2 version should not be older than the libxslt version.</li>
 287 <li>If you use XML Schema or Schematron which are still under development, the
 288 most recent version of libxml2 is usually a good bet.</li>
 289 <li>The same applies to XPath, where a substantial number of bugs and memory
 290 leaks were fixed over time.  If you encounter crashes or memory leaks in
 291 XPath applications, try a more recent version of libxml2.</li>
 292 <li>For parsing and fixing broken HTML, lxml requires at least libxml2 2.6.21.</li>
 293 <li>For the normal tree handling, however, any libxml2 version starting with
 294 2.6.20 should do.</li>
 295 </ul>
 296 <p>Read the <a class="reference external" href="http://xmlsoft.org/news.html">release notes of libxml2</a> and the <a class="reference external" href="http://xmlsoft.org/XSLT/news.html">release notes of libxslt</a> to
 297 see when (or if) a specific bug has been fixed.</p>
 298 </div>
 299 <div class="section" id="where-are-the-binary-builds">
 300 <h2>Where are the binary builds?</h2>
 301 <p>Binary builds are often requested by users of Microsoft Windows.  Two
 302 of the major design issues of this operating system make it
 303 non-trivial for users to build lxml: the lack of a pre-installed
 304 standard compiler and the missing package management.</p>
 305 <p>We previously provided Windows binaries for new releases, but
 306 currently lack a maintainer with a suitable build system.  If there is
 307 not currently a binary distribution of the most recent lxml release
 308 for this platform available from the Python Package Index (PyPI),
 309 please look through the older versions to see if they provide a binary
 310 build.  This is done by appending the version number to the PyPI URL,
 311 e.g.:</p>
 312 <pre class="literal-block">
 313 http://pypi.python.org/pypi/lxml/2.2.8
 314 </pre>
 315 <p>Christoph Gohlke also provides <a class="reference external" href="http://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml">unofficial lxml binary builds for
 316 Windows</a> that are
 317 usually very up to date.</p>
 318 <p>Apart from that, we generally do not provide binary builds of lxml, as
 319 most of the other operating systems out there can build lxml without
 320 problems (with <a class="reference external" href="build.html#building-lxml-on-macos-x">MacOS-X</a> being sometimes an exception), and the sheer
 321 mass of variations between platforms makes it futile to provide builds
 322 for everyone.</p>
 323 </div>
 324 <div class="section" id="why-do-i-get-errors-about-missing-ucs4-symbols-when-installing-lxml">
 325 <h2>Why do I get errors about missing UCS4 symbols when installing lxml?</h2>
 326 <p>Most likely, you use a Python installation that was configured for internal
 327 use of UCS2 unicode, meaning 16-bit unicode.  The lxml egg distributions are
 328 generally compiled on platforms that use UCS4, a 32-bit unicode encoding, as
 329 this is used on the majority of platforms.  Sadly, both are not compatible, so
 330 the eggs can only support the one they were compiled with.</p>
 331 <p>This means that you have to compile lxml from sources for your system.  Note
 332 that you do not need Cython for this, the lxml source distribution is directly
 333 compilable on both platform types.  See the <a class="reference external" href="build.html">build instructions</a> on how to do
 334 this.</p>
 335 </div>
 336 </div>
 337 <div class="section" id="contributing">
 338 <h1>Contributing</h1>
 339 <div class="section" id="why-is-lxml-not-written-in-python">
 340 <h2>Why is lxml not written in Python?</h2>
 341 <p>It <em>almost</em> is.</p>
 342 <p>lxml is not written in plain Python, because it interfaces with two C
 343 libraries: libxml2 and libxslt.  Accessing them at the C-level is
 344 required for performance reasons.</p>
 345 <p>However, to avoid writing plain C-code and caring too much about the
 346 details of built-in types and reference counting, lxml is written in
 347 <a class="reference external" href="http://www.cython.org/">Cython</a>, a Python-like language that is translated into C-code.
 348 Chances are that if you know Python, you can write <a class="reference external" href="http://docs.cython.org/docs/tutorial.html">code that Cython
 349 accepts</a>.  Again, the C-ish style used in the lxml code is just for
 350 performance optimisations.  If you want to contribute, don't bother
 351 with the details, a Python implementation of your contribution is
 352 better than none.  And keep in mind that lxml's flexible API often
 353 favours an implementation of features in pure Python, without
 354 bothering with C-code at all.  For example, the <tt class="docutils literal">lxml.html</tt> package
 355 is entirely written in Python.</p>
 356 <p>Please contact the <a class="reference external" href="http://lxml.de/mailinglist/">mailing list</a> if you need any help.</p>
 357 </div>
 358 <div class="section" id="how-can-i-contribute">
 359 <h2>How can I contribute?</h2>
 360 <p>If you find something that you would like lxml to do (or do better),
 361 then please tell us about it on the <a class="reference external" href="http://lxml.de/mailinglist/">mailing list</a>.  Patches are
 362 always appreciated, especially when accompanied by unit tests and
 363 documentation (doctests would be great).  See the <tt class="docutils literal">tests</tt>
 364 subdirectories in the lxml source tree (below the <tt class="docutils literal">src</tt> directory)
 365 and the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> <a class="reference external" href="https://github.com/lxml/lxml/tree/master/doc">text files</a> in the <tt class="docutils literal">doc</tt> directory.</p>
 366 <p>We also have a <a class="reference external" href="https://github.com/lxml/lxml/blob/master/IDEAS.txt">list of missing features</a> that we would like to
 367 implement but didn't due to lack if time.  If <em>you</em> find the time,
 368 patches are very welcome.</p>
 369 <p>Besides enhancing the code, there are a lot of places where you can help the
 370 project and its user base.  You can</p>
 371 <ul class="simple">
 372 <li>spread the word and write about lxml.  Many users (especially new Python
 373 users) have not yet heared about lxml, although our user base is constantly
 374 growing.  If you write your own blog and feel like saying something about
 375 lxml, go ahead and do so.  If we think your contribution or criticism is
 376 valuable to other users, we may even put a link or a quote on the project
 377 page.</li>
 378 <li>provide code examples for the general usage of lxml or specific problems
 379 solved with lxml.  Readable code is a very good way of showing how a library
 380 can be used and what great things you can do with it.  Again, if we hear
 381 about it, we can set a link on the project page.</li>
 382 <li>work on the documentation.  The web page is generated from a set of <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a>
 383 <a class="reference external" href="https://github.com/lxml/lxml/tree/master/doc">text files</a>.  It is meant both as a representative project page for lxml
 384 and as a site for documenting lxml's API and usage.  If you have questions
 385 or an idea how to make it more readable and accessible while you are reading
 386 it, please send a comment to the <a class="reference external" href="http://lxml.de/mailinglist/">mailing list</a>.</li>
 387 <li>enhance the web site. We put some work into making the web site
 388 usable, understandable and also easy to find, but there's always
 389 things that can be done better.  You may notice that we are not
 390 top-ranked when searching the web for "Python and XML", so maybe you
 391 have an idea how to improve that.</li>
 392 <li>help with the tutorial.  A tutorial is the most important stating point for
 393 new users, so it is important for us to provide an easy to understand guide
 394 into lxml.  As allo documentation, the tutorial is work in progress, so we
 395 appreciate every helping hand.</li>
 396 <li>improve the docstrings.  lxml uses docstrings to support Python's integrated
 397 online <tt class="docutils literal">help()</tt> function.  However, sometimes these are not sufficient to
 398 grasp the details of the function in question.  If you find such a place,
 399 you can try to write up a better description and send it to the <a class="reference external" href="http://lxml.de/mailinglist/">mailing
 400 list</a>.</li>
 401 </ul>
 402 </div>
 403 </div>
 404 <div class="section" id="bugs">
 405 <h1>Bugs</h1>
 406 <div class="section" id="my-application-crashes">
 407 <h2>My application crashes!</h2>
 408 <p>One of the goals of lxml is "no segfaults", so if there is no clear
 409 warning in the documentation that you were doing something potentially
 410 harmful, you have found a bug and we would like to hear about it.
 411 Please report this bug to the <a class="reference external" href="http://lxml.de/mailinglist/">mailing list</a>.  See the section on bug
 412 reporting to learn how to do that.</p>
 413 <p>If your application (or e.g. your web container) uses threads, please
 414 see the FAQ section on <a class="reference external" href="#threading">threading</a> to check if you touch on one of the
 415 potential pitfalls.</p>
 416 <p>In any case, try to reproduce the problem with the latest versions of
 417 libxml2 and libxslt.  From time to time, bugs and race conditions are found
 418 in these libraries, so a more recent version might already contain a fix for
 419 your problem.</p>
 420 <p>Remember: even if you see lxml appear in a crash stack trace, it is
 421 not necessarily lxml that <em>caused</em> the crash.</p>
 422 </div>
 423 <div class="section" id="my-application-crashes-on-macos-x">
 424 <h2>My application crashes on MacOS-X!</h2>
 425 <p>This was a common problem up to lxml 2.1.x.  Since lxml 2.2, the only
 426 officially supported way to use it on this platform is through a
 427 static build against freshly downloaded versions of libxml2 and
 428 libxslt.  See the build instructions for <a class="reference external" href="build.html#building-lxml-on-macos-x">MacOS-X</a>.</p>
 429 </div>
 430 <div class="section" id="i-think-i-have-found-a-bug-in-lxml-what-should-i-do">
 431 <h2>I think I have found a bug in lxml. What should I do?</h2>
 432 <p>First, you should look at the <a class="reference external" href="https://github.com/lxml/lxml/blob/master/CHANGES.txt">current developer changelog</a> to see if this
 433 is a known problem that has already been fixed in the SVN trunk since the
 434 release you are using.</p>
 435 <p>Also, the 'crash' section above has a few good advices what to try to see if
 436 the problem is really in lxml - and not in your setup.  Believe it or not,
 437 that happens more often than you might think, especially when old libraries
 438 or even multiple library versions are installed.</p>
 439 <p>You should always try to reproduce the problem with the latest
 440 versions of libxml2 and libxslt - and make sure they are used.
 441 <tt class="docutils literal">lxml.etree</tt> can tell you what it runs with:</p>
 442 <div class="syntax"><pre><span class="kn">import</span> <span class="nn">sys</span>
 443 <span class="kn">from</span> <span class="nn">lxml</span> <span class="kn">import</span> <span class="n">etree</span>
 444
 445 <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%-20s</span><span class="s">: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="s">'Python'</span><span class="p">,</span>           <span class="n">sys</span><span class="o">.</span><span class="n">version_info</span><span class="p">))</span>
 446 <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%-20s</span><span class="s">: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="s">'lxml.etree'</span><span class="p">,</span>       <span class="n">etree</span><span class="o">.</span><span class="n">LXML_VERSION</span><span class="p">))</span>
 447 <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%-20s</span><span class="s">: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="s">'libxml used'</span><span class="p">,</span>      <span class="n">etree</span><span class="o">.</span><span class="n">LIBXML_VERSION</span><span class="p">))</span>
 448 <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%-20s</span><span class="s">: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="s">'libxml compiled'</span><span class="p">,</span>  <span class="n">etree</span><span class="o">.</span><span class="n">LIBXML_COMPILED_VERSION</span><span class="p">))</span>
 449 <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%-20s</span><span class="s">: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="s">'libxslt used'</span><span class="p">,</span>     <span class="n">etree</span><span class="o">.</span><span class="n">LIBXSLT_VERSION</span><span class="p">))</span>
 450 <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%-20s</span><span class="s">: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="s">'libxslt compiled'</span><span class="p">,</span> <span class="n">etree</span><span class="o">.</span><span class="n">LIBXSLT_COMPILED_VERSION</span><span class="p">))</span>
 451 </pre></div>
 452 <p>If you can figure that the problem is not in lxml but in the
 453 underlying libxml2 or libxslt, you can ask right on the respective
 454 mailing lists, which may considerably reduce the time to find a fix or
 455 work-around.  See the next question for some hints on how to do that.</p>
 456 <p>Otherwise, we would really like to hear about it.  Please report it to
 457 the <a class="reference external" href="http://lxml.de/mailinglist/">mailing list</a> so that we can fix it.  It is very helpful in this
 458 case if you can come up with a short code snippet that demonstrates
 459 your problem.  If others can reproduce and see the problem, it is much
 460 easier for them to fix it - and maybe even easier for you to describe
 461 it and get people convinced that it really is a problem to fix.</p>
 462 <p>It is important that you always report the version of lxml, libxml2
 463 and libxslt that you get from the code snippet above.  If we do not
 464 know the library versions you are using, we will ask back, so it will
 465 take longer for you to get a helpful answer.</p>
 466 <p>Since as a user of lxml you are likely a programmer, you might find
 467 <a class="reference external" href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">this article on bug reports</a> an interesting read.</p>
 468 </div>
 469 <div class="section" id="how-do-i-know-a-bug-is-really-in-lxml-and-not-in-libxml2">
 470 <h2>How do I know a bug is really in lxml and not in libxml2?</h2>
 471 <p>A large part of lxml's functionality is implemented by libxml2 and
 472 libxslt, so problems that you encounter may be in one or the other.
 473 Knowing the right place to ask will reduce the time it takes to fix
 474 the problem, or to find a work-around.</p>
 475 <p>Both libxml2 and libxslt come with their own command line frontends,
 476 namely <tt class="docutils literal">xmllint</tt> and <tt class="docutils literal">xsltproc</tt>.  If you encounter problems with
 477 XSLT processing for specific stylesheets or with validation for
 478 specific schemas, try to run the XSLT with <tt class="docutils literal">xsltproc</tt> or the
 479 validation with <tt class="docutils literal">xmllint</tt> respectively to find out if it fails there
 480 as well.  If it does, please report directly to the mailing lists of
 481 the respective project, namely:</p>
 482 <ul class="simple">
 483 <li><a class="reference external" href="http://mail.gnome.org/mailman/listinfo/xml">libxml2 mailing list</a></li>
 484 <li><a class="reference external" href="http://mail.gnome.org/mailman/listinfo/xslt">libxslt mailing list</a></li>
 485 </ul>
 486 <p>On the other hand, everything that seems to be related to Python code,
 487 including custom resolvers, custom XPath functions, etc. is likely
 488 outside of the scope of libxml2/libxslt.  If you encounter problems
 489 here or you are not sure where there the problem may come from, please
 490 ask on the lxml mailing list first.</p>
 491 <p>In any case, a good explanation of the problem including some simple
 492 test code and some input data will help us (or the libxml2 developers)
 493 see and understand the problem, which largely increases your chance of
 494 getting help.  See the question above for a few hints on what is
 495 helpful here.</p>
 496 </div>
 497 </div>
 498 <div class="section" id="id1">
 499 <h1>Threading</h1>
 500 <div class="section" id="can-i-use-threads-to-concurrently-access-the-lxml-api">
 501 <h2>Can I use threads to concurrently access the lxml API?</h2>
 502 <p>Short answer: yes, if you use lxml 2.2 and later.</p>
 503 <p>Since version 1.1, lxml frees the GIL (Python's global interpreter
 504 lock) internally when parsing from disk and memory, as long as you use
 505 either the default parser (which is replicated for each thread) or
 506 create a parser for each thread yourself.  lxml also allows
 507 concurrency during validation (RelaxNG and XMLSchema) and XSL
 508 transformation.  You can share RelaxNG, XMLSchema and XSLT objects
 509 between threads.</p>
 510 <p>While you can also share parsers between threads, this will serialize
 511 the access to each of them, so it is better to <tt class="docutils literal">.copy()</tt> parsers or
 512 to just use the default parser if you do not need any special
 513 configuration.  The same applies to the XPath evaluators, which use an
 514 internal lock to protect their prepared evaluation contexts.  It is
 515 therefore best to use separate evaluator instances in threads.</p>
 516 <p>Warning: Before lxml 2.2, and especially before 2.1, there were
 517 various issues when moving subtrees between different threads, or when
 518 applying XSLT objects from one thread to trees parsed or modified in
 519 another.  If you need code to run with older versions, you should
 520 generally avoid modifying trees in other threads than the one it was
 521 generated in.  Although this should work in many cases, there are
 522 certain scenarios where the termination of a thread that parsed a tree
 523 can crash the application if subtrees of this tree were moved to other
 524 documents.  You should be on the safe side when passing trees between
 525 threads if you either</p>
 526 <ul class="simple">
 527 <li>do not modify these trees and do not move their elements to other
 528 trees, or</li>
 529 <li>do not terminate threads while the trees they parsed are still in
 530 use (e.g. by using a fixed size thread-pool or long-running threads
 531 in processing chains)</li>
 532 </ul>
 533 <p>Since lxml 2.2, even multi-thread pipelines are supported. However,
 534 note that it is more efficient to do all tree work inside one thread,
 535 than to let multiple threads work on a tree one after the other. This
 536 is because trees inherit state from the thread that created them,
 537 which must be maintained when the tree is modified inside another
 538 thread.</p>
 539 </div>
 540 <div class="section" id="does-my-program-run-faster-if-i-use-threads">
 541 <h2>Does my program run faster if I use threads?</h2>
 542 <p>Depends.  The best way to answer this is timing and profiling.</p>
 543 <p>The global interpreter lock (GIL) in Python serializes access to the
 544 interpreter, so if the majority of your processing is done in Python
 545 code (walking trees, modifying elements, etc.), your gain will be
 546 close to zero.  The more of your XML processing moves into lxml,
 547 however, the higher your gain.  If your application is bound by XML
 548 parsing and serialisation, or by very selective XPath expressions and
 549 complex XSLTs, your speedup on multi-processor machines can be
 550 substantial.</p>
 551 <p>See the question above to learn which operations free the GIL to support
 552 multi-threading.</p>
 553 </div>
 554 <div class="section" id="would-my-single-threaded-program-run-faster-if-i-turned-off-threading">
 555 <h2>Would my single-threaded program run faster if I turned off threading?</h2>
 556 <p>Possibly, yes.  You can see for yourself by compiling lxml entirely
 557 without threading support.  Pass the <tt class="docutils literal"><span class="pre">--without-threading</span></tt> option to
 558 setup.py when building lxml from source.  You can also build libxml2
 559 without pthread support (<tt class="docutils literal"><span class="pre">--without-pthreads</span></tt> option), which may add
 560 another bit of performance.  Note that this will leave internal data
 561 structures entirely without thread protection, so make sure you really
 562 do not use lxml outside of the main application thread in this case.</p>
 563 </div>
 564 <div class="section" id="why-can-t-i-reuse-xslt-stylesheets-in-other-threads">
 565 <h2>Why can't I reuse XSLT stylesheets in other threads?</h2>
 566 <p>Since later lxml 2.0 versions, you can do this.  There is some
 567 overhead involved as the result document needs an additional cleanup
 568 traversal when the input document and/or the stylesheet were created
 569 in other threads.  However, on a multi-processor machine, the gain of
 570 freeing the GIL easily covers this drawback.</p>
 571 <p>If you need even the last bit of performance, consider keeping (a copy
 572 of) the stylesheet in thread-local storage, and try creating the input
 573 document(s) in the same thread.  And do not forget to benchmark your
 574 code to see if the increased code complexity is really worth it.</p>
 575 </div>
 576 <div class="section" id="my-program-crashes-when-run-with-mod-python-pyro-zope-plone">
 577 <h2>My program crashes when run with mod_python/Pyro/Zope/Plone/...</h2>
 578 <p>These environments can use threads in a way that may not make it obvious when
 579 threads are created and what happens in which thread.  This makes it hard to
 580 ensure lxml's threading support is used in a reliable way.  Sadly, if problems
 581 arise, they are as diverse as the applications, so it is difficult to provide
 582 any generally applicable solution.  Also, these environments are so complex
 583 that problems become hard to debug and even harder to reproduce in a
 584 predictable way.  If you encounter crashes in one of these systems, but your
 585 code runs perfectly when started by hand, the following gives you a few hints
 586 for possible approaches to solve your specific problem:</p>
 587 <ul>
 588 <li><p class="first">make sure you use recent versions of libxml2, libxslt and lxml.  The
 589 libxml2 developers keep fixing bugs in each release, and lxml also
 590 tries to become more robust against possible pitfalls.  So newer
 591 versions might already fix your problem in a reliable way.  Version
 592 2.2 of lxml contains many improvements.</p>
 593 </li>
 594 <li><p class="first">make sure the library versions you installed are really used.  Do
 595 not rely on what your operating system tells you!  Print the version
 596 constants in <tt class="docutils literal">lxml.etree</tt> from within your runtime environment to
 597 make sure it is the case.  This is especially a problem under
 598 MacOS-X when newer library versions were installed in addition to
 599 the outdated system libraries.  Please read the bugs section
 600 regarding MacOS-X in this FAQ.</p>
 601 </li>
 602 <li><p class="first">if you use <tt class="docutils literal">mod_python</tt>, try setting this option:</p>
 603 <blockquote>
 604 <p>PythonInterpreter main_interpreter</p>
 605 </blockquote>
 606 <p>There was a discussion on the mailing list about this problem:</p>
 607 <blockquote>
 608 <p><a class="reference external" href="http://comments.gmane.org/gmane.comp.python.lxml.devel/2942">http://comments.gmane.org/gmane.comp.python.lxml.devel/2942</a></p>
 609 </blockquote>
 610 </li>
 611 <li><p class="first">compile lxml without threading support by running <tt class="docutils literal">setup.py</tt> with the
 612 <tt class="docutils literal"><span class="pre">--without-threading</span></tt> option.  While this might be slower in certain
 613 scenarios on multi-processor systems, it <em>might</em> also keep your application
 614 from crashing, which should be worth more to you than peek performance.
 615 Remember that lxml is fast anyway, so concurrency may not even be worth it.</p>
 616 </li>
 617 <li><p class="first">look out for fancy XSLT stuff like foreign document access or
 618 passing in subtrees trough XSLT variables.  This might or might not
 619 work, depending on your specific usage.  Again, later versions of
 620 lxml and libxslt provide safer support here.</p>
 621 </li>
 622 <li><p class="first">try copying trees at suspicious places in your code and working with
 623 those instead of a tree shared between threads.  Note that the
 624 copying must happen inside the target thread to be effective, not in
 625 the thread that created the tree.  Serialising in one thread and
 626 parsing in another is also a simple (and fast) way of separating
 627 thread contexts.</p>
 628 </li>
 629 <li><p class="first">try keeping thread-local copies of XSLT stylesheets, i.e. one per thread,
 630 instead of sharing one.  Also see the question above.</p>
 631 </li>
 632 <li><p class="first">you can try to serialise suspicious parts of your code with explicit thread
 633 locks, thus disabling the concurrency of the runtime system.</p>
 634 </li>
 635 <li><p class="first">report back on the mailing list to see if there are other ways to work
 636 around your specific problems.  Do not forget to report the version numbers
 637 of lxml, libxml2 and libxslt you are using (see the question on reporting
 638 a bug).</p>
 639 </li>
 640 </ul>
 641 <p>Note that most of these options will degrade performance and/or your
 642 code quality.  If you are unsure what to do, please ask on the mailing
 643 list.</p>
 644 </div>
 645 </div>
 646 <div class="section" id="parsing-and-serialisation">
 647 <h1>Parsing and Serialisation</h1>
 648 <div class="section" id="why-doesn-t-the-pretty-print-option-reformat-my-xml-output">
 649 <h2>Why doesn't the <tt class="docutils literal">pretty_print</tt> option reformat my XML output?</h2>
 650 <p>Pretty printing (or formatting) an XML document means adding white space to
 651 the content.  These modifications are harmless if they only impact elements in
 652 the document that do not carry (text) data.  They corrupt your data if they
 653 impact elements that contain data.  If lxml cannot distinguish between
 654 whitespace and data, it will not alter your data.  Whitespace is therefore
 655 only added between nodes that do not contain data.  This is always the case
 656 for trees constructed element-by-element, so no problems should be expected
 657 here.  For parsed trees, a good way to assure that no conflicting whitespace
 658 is left in the tree is the <tt class="docutils literal">remove_blank_text</tt> option:</p>
 659 <div class="syntax"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">parser</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">XMLParser</span><span class="p">(</span><span class="n">remove_blank_text</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
 660 <span class="gp">&gt;&gt;&gt; </span><span class="n">tree</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">parser</span><span class="p">)</span>
 661 </pre></div>
 662 <p>This will allow the parser to drop blank text nodes when constructing the
 663 tree.  If you now call a serialization function to pretty print this tree,
 664 lxml can add fresh whitespace to the XML tree to indent it.</p>
 665 <p>Note that the <tt class="docutils literal">remove_blank_text</tt> option also uses a heuristic if it
 666 has no definite knowledge about the document's ignorable whitespace.
 667 It will keep blank text nodes that appear after non-blank text nodes
 668 at the same level.  This is to prevent document-style XML from
 669 breaking.</p>
 670 <p>If you want to be sure all blank text is removed, you have to use
 671 either a DTD to tell the parser which whitespace it can safely ignore,
 672 or remove the ignorable whitespace manually after parsing, e.g. by
 673 setting all tail text to None:</p>
 674 <div class="syntax"><pre><span class="k">for</span> <span class="n">element</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iter</span><span class="p">():</span>
 675     <span class="n">element</span><span class="o">.</span><span class="n">tail</span> <span class="o">=</span> <span class="bp">None</span>
 676 </pre></div>
 677 <p>Fredrik Lundh also has a Python-level function for indenting XML by
 678 appending whitespace to tags.  It can be found on his <a class="reference external" href="http://effbot.org/zone/element-lib.htm">element
 679 library</a> recipe page.</p>
 680 </div>
 681 <div class="section" id="why-can-t-lxml-parse-my-xml-from-unicode-strings">
 682 <h2>Why can't lxml parse my XML from unicode strings?</h2>
 683 <p>lxml can read Python unicode strings and even tries to support them if libxml2
 684 does not.  However, if the unicode string declares an XML encoding internally
 685 (<tt class="docutils literal"><span class="pre">&lt;?xml</span> <span class="pre">encoding="..."?&gt;</span></tt>), parsing is bound to fail, as this encoding is
 686 most likely not the real encoding used in Python unicode.  The same is true
 687 for HTML unicode strings that contain charset meta tags, although the problems
 688 may be more subtle here.  The libxml2 HTML parser may not be able to parse the
 689 meta tags in broken HTML and may end up ignoring them, so even if parsing
 690 succeeds, later handling may still fail with character encoding errors.</p>
 691 <p>Note that Python uses different encodings for unicode on different platforms,
 692 so even specifying the real internal unicode encoding is not portable between
 693 Python interpreters.  Don't do it.</p>
 694 <p>Python unicode strings with XML data or HTML data that carry encoding
 695 information are broken.  lxml will not parse them.  You must provide parsable
 696 data in a valid encoding.</p>
 697 </div>
 698 <div class="section" id="what-is-the-difference-between-str-xslt-doc-and-xslt-doc-write">
 699 <h2>What is the difference between str(xslt(doc)) and xslt(doc).write() ?</h2>
 700 <p>The str() implementation of the XSLTResultTree class (a subclass of the
 701 ElementTree class) knows about the output method chosen in the stylesheet
 702 (xsl:output), write() doesn't.  If you call write(), the result will be a
 703 normal XML tree serialization in the requested encoding.  Calling this method
 704 may also fail for XSLT results that are not XML trees (e.g. string results).</p>
 705 <p>If you call str(), it will return the serialized result as specified by the
 706 XSL transform.  This correctly serializes string results to encoded Python
 707 strings and honours <tt class="docutils literal">xsl:output</tt> options like <tt class="docutils literal">indent</tt>.  This almost
 708 certainly does what you want, so you should only use <tt class="docutils literal">write()</tt> if you are
 709 sure that the XSLT result is an XML tree and you want to override the encoding
 710 and indentation options requested by the stylesheet.</p>
 711 </div>
 712 <div class="section" id="why-can-t-i-just-delete-parents-or-clear-the-root-node-in-iterparse">
 713 <h2>Why can't I just delete parents or clear the root node in iterparse()?</h2>
 714 <p>The <tt class="docutils literal">iterparse()</tt> implementation is based on the libxml2 parser.  It
 715 requires the tree to be intact to finish parsing.  If you delete or modify
 716 parents of the current node, chances are you modify the structure in a way
 717 that breaks the parser.  Normally, this will result in a segfault.  Please
 718 refer to the <a class="reference external" href="parsing.html#iterparse-and-iterwalk">iterparse section</a> of the lxml API documentation to find out
 719 what you can do and what you can't do.</p>
 720 </div>
 721 <div class="section" id="how-do-i-output-null-characters-in-xml-text">
 722 <h2>How do I output null characters in XML text?</h2>
 723 <p>Don't.  What you would produce is not well-formed XML.  XML parsers
 724 will refuse to parse a document that contains null characters.  The
 725 right way to embed binary data in XML is using a text encoding such as
 726 uuencode or base64.</p>
 727 </div>
 728 <div class="section" id="is-lxml-vulnerable-to-xml-bombs">
 729 <h2>Is lxml vulnerable to XML bombs?</h2>
 730 <p>This has nothing to do with lxml itself, only with the parser of
 731 libxml2.  Since libxml2 version 2.7, the parser imposes hard security
 732 limits on input documents to prevent DoS attacks with forged input
 733 data.  Since lxml 2.2.1, you can disable these limits with the
 734 <tt class="docutils literal">huge_tree</tt> parser option if you need to parse <em>really</em> large,
 735 trusted documents.  All lxml versions will leave these restrictions
 736 enabled by default.</p>
 737 <p>Note that libxml2 versions of the 2.6 series do not restrict their
 738 parser and are therefore vulnerable to DoS attacks.</p>
 739 </div>
 740 <div class="section" id="can-lxml-parse-from-file-objects-opened-in-unicode-text-mode">
 741 <h2>Can lxml parse from file objects opened in unicode/text mode?</h2>
 742 <p>Technically, yes. However, you likely do not want to do that, because
 743 it is extremely inefficient. The text encoding that libxml2 uses
 744 internally is UTF-8, so parsing from a Unicode file means that Python
 745 first reads a chunk of data from the file, then decodes it into a new
 746 buffer, and then copies it into a new unicode string object, just to
 747 let libxml2 make yet another copy while encoding it down into UTF-8
 748 in order to parse it. It's clear that this involves a lot more
 749 recoding and copying than when parsing straight from the bytes that
 750 the file contains.</p>
 751 <p>If you really know the encoding better than the parser (e.g. when
 752 parsing HTML that lacks a content declaration), then instead of passing
 753 an encoding parameter into the file object when opening it, create a
 754 new instance of an XMLParser or HTMLParser and pass the encoding into
 755 its constructor. Afterwards, use that parser for parsing, e.g. by
 756 passing it into the <tt class="docutils literal">etree.parse(file, parser)</tt> function.</p>
 757 </div>
 758 </div>
 759 <div class="section" id="xpath-and-document-traversal">
 760 <h1>XPath and Document Traversal</h1>
 761 <div class="section" id="what-are-the-findall-and-xpath-methods-on-element-tree">
 762 <h2>What are the <tt class="docutils literal">findall()</tt> and <tt class="docutils literal">xpath()</tt> methods on Element(Tree)?</h2>
 763 <p><tt class="docutils literal">findall()</tt> is part of the original <a class="reference external" href="http://effbot.org/zone/element-index.htm">ElementTree API</a>.  It supports a
 764 <a class="reference external" href="http://effbot.org/zone/element-xpath.htm">simple subset of the XPath language</a>, without predicates, conditions and
 765 other advanced features.  It is very handy for finding specific tags in a
 766 tree.  Another important difference is namespace handling, which uses the
 767 <tt class="docutils literal">{namespace}tagname</tt> notation.  This is not supported by XPath.  The
 768 findall, find and findtext methods are compatible with other ElementTree
 769 implementations and allow writing portable code that runs on ElementTree,
 770 cElementTree and lxml.etree.</p>
 771 <p><tt class="docutils literal">xpath()</tt>, on the other hand, supports the complete power of the XPath
 772 language, including predicates, XPath functions and Python extension
 773 functions.  The syntax is defined by the <a class="reference external" href="http://www.w3.org/TR/xpath">XPath specification</a>.  If you need
 774 the expressiveness and selectivity of XPath, the <tt class="docutils literal">xpath()</tt> method, the
 775 <tt class="docutils literal">XPath</tt> class and the <tt class="docutils literal">XPathEvaluator</tt> are the best <a class="reference external" href="performance.html#xpath">choice</a>.</p>
 776 </div>
 777 <div class="section" id="why-doesn-t-findall-support-full-xpath-expressions">
 778 <h2>Why doesn't <tt class="docutils literal">findall()</tt> support full XPath expressions?</h2>
 779 <p>It was decided that it is more important to keep compatibility with
 780 <a class="reference external" href="http://effbot.org/zone/element-index.htm">ElementTree</a> to simplify code migration between the libraries.  The main
 781 difference compared to XPath is the <tt class="docutils literal">{namespace}tagname</tt> notation used in
 782 <tt class="docutils literal">findall()</tt>, which is not valid XPath.</p>
 783 <p>ElementTree and lxml.etree use the same implementation, which assures 100%
 784 compatibility.  Note that <tt class="docutils literal">findall()</tt> is <a class="reference external" href="performance.html#tree-traversal">so fast</a> in lxml that a native
 785 implementation would not bring any performance benefits.</p>
 786 </div>
 787 <div class="section" id="how-can-i-find-out-which-namespace-prefixes-are-used-in-a-document">
 788 <h2>How can I find out which namespace prefixes are used in a document?</h2>
 789 <p>You can traverse the document (<tt class="docutils literal">root.iter()</tt>) and collect the prefix
 790 attributes from all Elements into a set.  However, it is unlikely that you
 791 really want to do that.  You do not need these prefixes, honestly.  You only
 792 need the namespace URIs.  All namespace comparisons use these, so feel free to
 793 make up your own prefixes when you use XPath expressions or extension
 794 functions.</p>
 795 <p>The only place where you might consider specifying prefixes is the
 796 serialization of Elements that were created through the API.  Here, you can
 797 specify a prefix mapping through the <tt class="docutils literal">nsmap</tt> argument when creating the root
 798 Element.  Its children will then inherit this prefix for serialization.</p>
 799 </div>
 800 <div class="section" id="how-can-i-specify-a-default-namespace-for-xpath-expressions">
 801 <h2>How can I specify a default namespace for XPath expressions?</h2>
 802 <p>You can't.  In XPath, there is no such thing as a default namespace.  Just use
 803 an arbitrary prefix and let the namespace dictionary of the XPath evaluators
 804 map it to your namespace.  See also the question above.</p>
 805 </div>
 806 </div>
 807 </div>
 808 <div class="footer">
 809 <hr class="footer" />
 810 Generated on: 2012-07-31.
 811
 812 </div>
 813 </body>
 814 </html>