doc/main.txt

   1 lxml
   2 ====
   3
   4 .. meta::
   5   :description: lxml - the most feature-rich and easy-to-use library for working with XML and HTML in the Python language
   6   :keywords: Python, XML, HTML, lxml, simple, ElementTree, etree, objectify, parsing, validation, XPath, XSLT
   7
   8 .. class:: pagequote
   9
  10 | `» lxml takes all the pain out of XML. « <http://thread.gmane.org/gmane.comp.python.lxml.devel/3252/focus=3258>`_
  11 | Stephan Richter
  12
  13 .. class:: eyecatcher
  14
  15      lxml is the most feature-rich
  16      and easy-to-use library
  17      for working with XML and HTML
  18      in the Python language.
  19
  20 ..
  21    1  Introduction
  22    2  Documentation
  23    3  Download
  24    4  Mailing list
  25    5  Bug tracker
  26    6  License
  27    7  Old Versions
  28
  29
  30 Introduction
  31 ------------
  32
  33 lxml is a Pythonic binding for the libxml2_ and libxslt_ libraries.  It is
  34 unique in that it combines the speed and feature completeness of these
  35 libraries with the simplicity of a native Python API, mostly compatible but
  36 superior to the well-known ElementTree_ API.  See the introduction_ for more
  37 information about background and goals.  Some common questions are answered in
  38 the FAQ_.
  39
  40 .. _libxml2: http://xmlsoft.org
  41 .. _libxslt: http://xmlsoft.org/XSLT
  42
  43 .. _introduction: intro.html
  44 .. _FAQ:          FAQ.html
  45
  46
  47 Documentation
  48 -------------
  49
  50 The complete lxml documentation is available for download as `PDF
  51 documentation`_.  The HTML documentation from this web site is part of
  52 the normal `source download <#download>`_.
  53
  54 * ElementTree:
  55
  56   * `ElementTree API`_
  57
  58   * compatibility_ and differences of lxml.etree
  59
  60   * `benchmark results`_
  61
  62 * lxml.etree:
  63
  64   * the `lxml.etree Tutorial`_
  65
  66   * `lxml.etree specific API`_ documentation
  67
  68   * the `generated API documentation`_ as a reference
  69
  70   * parsing_ and validating_ XML
  71
  72   * `XPath and XSLT`_ support
  73
  74   * Python `extension functions`_ for XPath and XSLT
  75
  76   * `custom element classes`_ for custom XML APIs (see `EuroPython 2008 talk`_)
  77
  78   * a `SAX compliant API`_ for interfacing with other XML tools
  79
  80   * a `C-level API`_ for interfacing with external C/Pyrex modules
  81
  82 * lxml.objectify:
  83
  84   * `lxml.objectify`_ API documentation
  85
  86   * a brief comparison of `objectify and etree`_
  87
  88 lxml.etree follows the ElementTree_ API as much as possible, building it on
  89 top of the native libxml2 tree.  If you are new to ElementTree, start with the
  90 `lxml.etree Tutorial`_.  See also the ElementTree compatibility_ overview and
  91 the `benchmark results`_ comparing lxml to the original ElementTree_ and
  92 cElementTree_ implementations.
  93
  94 Right after the `lxml.etree Tutorial`_ and the ElementTree_ documentation, the
  95 most important place to look is the `lxml.etree specific API`_ documentation.
  96 It describes how lxml extends the ElementTree API to expose libxml2 and
  97 libxslt specific functionality, such as XPath_, `Relax NG`_, `XML Schema`_,
  98 `XSLT`_, and `c14n`_.  Python code can be called from XPath expressions and
  99 XSLT stylesheets through the use of `extension functions`_.  lxml also offers
 100 a `SAX compliant API`_, that works with the SAX support in the standard
 101 library.
 102
 103 There is a separate module `lxml.objectify`_ that implements a data-binding
 104 API on top of lxml.etree.  See the `objectify and etree`_ FAQ entry for a
 105 comparison.
 106
 107 In addition to the ElementTree API, lxml also features a sophisticated API for
 108 `custom element classes`_.  This is a simple way to write arbitrary XML driven
 109 APIs on top of lxml.  As of version 1.1, lxml.etree has a new `C-level API`_
 110 that can be used to efficiently extend lxml.etree in external C modules,
 111 including custom element class support.
 112
 113 .. _ElementTree:  http://effbot.org/zone/element-index.htm
 114 .. _`ElementTree API`:  http://effbot.org/zone/element-index.htm#documentation
 115 .. _cElementTree: http://effbot.org/zone/celementtree.htm
 116
 117 .. _`lxml.etree Tutorial`: tutorial.html
 118 .. _`generated API documentation`:   api/index.html
 119 .. _`benchmark results`: performance.html
 120 .. _`compatibility`: compatibility.html
 121 .. _`lxml.etree specific API`: api.html
 122 .. _`parsing`: parsing.html
 123 .. _`validating`: validation.html
 124 .. _`XPath and XSLT`: xpathxslt.html
 125 .. _`extension functions`: extensions.html
 126 .. _`custom element classes`: element_classes.html
 127 .. _`SAX compliant API`: sax.html
 128 .. _`C-level API`: capi.html
 129 .. _`lxml.objectify`: objectify.html
 130 .. _`objectify and etree`: FAQ.html#what-is-the-difference-between-lxml-etree-and-lxml-objectify
 131 .. _`EuroPython 2008 talk`: s5/lxml-ep2008.html
 132
 133 .. _XPath: http://www.w3.org/TR/xpath
 134 .. _`Relax NG`: http://www.relaxng.org/
 135 .. _`XML Schema`: http://www.w3.org/XML/Schema
 136 .. _`XSLT`: http://www.w3.org/TR/xslt
 137 .. _`c14n`: http://www.w3.org/TR/xml-c14n
 138
 139
 140 Download
 141 --------
 142
 143 The best way to download lxml is to visit `lxml at the Python Package
 144 Index`_ (PyPI).  It has the source that compiles on various platforms.
 145 The source distribution is signed with `this key`_.  Binary builds for
 146 MS Windows usually become available through PyPI a few days after a
 147 source release.  If you can't wait, consider trying a less recent
 148 release version first.
 149
 150 The latest version is `lxml 2.2.3`_, released 2009-10-30
 151 (`changes for 2.2.3`_).  `Older versions`_ are listed below.
 152
 153 Please take a look at the `installation instructions`_!
 154
 155 This complete web site (including the generated API documentation) is
 156 part of the source distribution, so if you want to download the
 157 documentation for offline use, take the source archive and copy the
 158 ``doc/html`` directory out of the source tree.
 159
 160 It's also possible to check out the latest development version of lxml
 161 from svn directly, using a command like this::
 162
 163   svn co http://codespeak.net/svn/lxml/trunk lxml
 164
 165 You can also browse the `Subversion repository`_ through the web, or
 166 take a look at the `Subversion history`_.  Please read `how to build lxml
 167 from source`_ first.  The `latest CHANGES`_ of the developer version
 168 are also accessible.  You can check there if a bug you found has been
 169 fixed or a feature you want has been implemented in the latest trunk
 170 version.
 171
 172 .. _`lxml at the Python Package Index`: http://pypi.python.org/pypi/lxml/
 173 .. _`this key`: pubkey.asc
 174 .. _`Older versions`: #old-versions
 175 .. _`installation instructions`: installation.html
 176 .. _`how to build lxml from source`: build.html
 177 .. _`Subversion repository`: http://codespeak.net/svn/lxml/
 178 .. _`Subversion history`: https://codespeak.net/viewvc/lxml/
 179 .. _`latest CHANGES`: http://codespeak.net/svn/lxml/trunk/CHANGES.txt
 180
 181
 182 Mailing list
 183 ------------
 184
 185 Questions? Suggestions? Code to contribute? We have a `mailing list`_.
 186
 187 You can search the archive with Gmane_ or Google_.
 188
 189 .. _`mailing list`: http://codespeak.net/mailman/listinfo/lxml-dev
 190 .. _Gmane: http://blog.gmane.org/gmane.comp.python.lxml.devel
 191 .. _Google: http://www.google.com/webhp?q=site:codespeak.net%2Fmailman%2Flistinfo%2Flxml-dev+
 192
 193
 194 Bug tracker
 195 -----------
 196
 197 lxml uses the `launchpad bug tracker`_.  If you are sure you found a bug in
 198 lxml, please file a bug report there.  If you are not sure whether some
 199 unexpected behaviour of lxml is a bug or not, please ask on the `mailing
 200 list`_ first.  Do not forget to search the archive (e.g. with Gmane_)!
 201
 202 .. _`launchpad bug tracker`: https://launchpad.net/lxml/
 203
 204
 205 License
 206 -------
 207
 208 The lxml library is shipped under a `BSD license`_. libxml2 and libxslt2
 209 itself are shipped under the `MIT license`_. There should therefore be no
 210 obstacle to using lxml in your codebase.
 211
 212 .. _`BSD license`: http://codespeak.net/svn/lxml/trunk/doc/licenses/BSD.txt
 213 .. _`MIT license`: http://www.opensource.org/licenses/mit-license.html
 214
 215
 216 Old Versions
 217 ------------
 218
 219 See the web sites of lxml `1.3 <http://codespeak.net/lxml/1.3/>`_,
 220 `2.0 <http://codespeak.net/lxml/2.0/>`_, `2.1
 221 <http://codespeak.net/lxml/2.1/>`_ and the `current in-development
 222 version <http://codespeak.net/lxml/dev/>`_.
 223
 224 .. _`PDF documentation`: lxmldoc-2.2.3.pdf
 225
 226 * `lxml 2.2.2`_, released 2009-06-21 (`changes for 2.2.2`_)
 227
 228 * `lxml 2.2.1`_, released 2009-06-02 (`changes for 2.2.1`_)
 229
 230 * `lxml 2.2`_, released 2009-03-21 (`changes for 2.2`_)
 231
 232 * `lxml 2.2beta4`_, released 2009-02-27 (`changes for 2.2beta4`_)
 233
 234 * `lxml 2.2beta3`_, released 2009-02-17 (`changes for 2.2beta3`_)
 235
 236 * `lxml 2.2beta2`_, released 2009-01-25 (`changes for 2.2beta2`_)
 237
 238 * `lxml 2.2beta1`_, released 2008-12-12 (`changes for 2.2beta1`_)
 239
 240 * `lxml 2.2alpha1`_, released 2008-11-23 (`changes for 2.2alpha1`_)
 241
 242 * `lxml 2.1.5`_, released 2009-01-06 (`changes for 2.1.5`_)
 243
 244 * `lxml 2.1.4`_, released 2008-12-12 (`changes for 2.1.4`_)
 245
 246 * `lxml 2.1.3`_, released 2008-11-17 (`changes for 2.1.3`_)
 247
 248 * `lxml 2.1.2`_, released 2008-09-05 (`changes for 2.1.2`_)
 249
 250 * `lxml 2.1.1`_, released 2008-07-24 (`changes for 2.1.1`_)
 251
 252 * `lxml 2.1`_, released 2008-07-09 (`changes for 2.1`_)
 253
 254 * `lxml 2.0.11`_, released 2008-12-12 (`changes for 2.0.11`_)
 255
 256 * `lxml 2.0.10`_, released 2008-11-17 (`changes for 2.0.10`_)
 257
 258 * `lxml 2.0.9`_, released 2008-09-05 (`changes for 2.0.9`_)
 259
 260 * `lxml 2.0.8`_, released 2008-07-24 (`changes for 2.0.8`_)
 261
 262 * `lxml 2.0.7`_, released 2008-06-20 (`changes for 2.0.7`_)
 263
 264 * `lxml 2.0.6`_, released 2008-05-31 (`changes for 2.0.6`_)
 265
 266 * `lxml 2.0.5`_, released 2008-05-01 (`changes for 2.0.5`_)
 267
 268 * `lxml 2.0.4`_, released 2008-04-14 (`changes for 2.0.4`_)
 269
 270 * `lxml 2.0.3`_, released 2008-03-26 (`changes for 2.0.3`_)
 271
 272 * `lxml 2.0.2`_, released 2008-02-22 (`changes for 2.0.2`_)
 273
 274 * `lxml 2.0.1`_, released 2008-02-13 (`changes for 2.0.1`_)
 275
 276 * `lxml 2.0`_, released 2008-02-01 (`changes for 2.0`_)
 277
 278 * `lxml 1.3.6`_, released 2007-10-29 (`changes for 1.3.6`_)
 279
 280 * `lxml 1.3.5`_, released 2007-10-22 (`changes for 1.3.5`_)
 281
 282 * `lxml 1.3.4`_, released 2007-08-30 (`changes for 1.3.4`_)
 283
 284 * `lxml 1.3.3`_, released 2007-07-26 (`changes for 1.3.3`_)
 285
 286 * `lxml 1.3.2`_, released 2007-07-03 (`changes for 1.3.2`_)
 287
 288 * lxml 1.3.1, released 2007-07-02 (`changes for 1.3.1`_)
 289
 290 * `lxml 1.3`_, released 2007-06-24 (`changes for 1.3`_)
 291
 292 * `lxml 1.2.1`_, released 2007-02-27 (`changes for 1.2.1`_)
 293
 294 * `lxml 1.2`_, released 2007-02-20 (`changes for 1.2`_)
 295
 296 * `lxml 1.1.2`_, released 2006-10-30 (`changes for 1.1.2`_)
 297
 298 * `lxml 1.1.1`_, released 2006-09-21 (`changes for 1.1.1`_)
 299
 300 * `lxml 1.1`_, released 2006-09-13 (`changes for 1.1`_)
 301
 302 * `lxml 1.0.4`_, released 2006-09-09 (`changes for 1.0.4`_)
 303
 304 * `lxml 1.0.3`_, released 2006-08-08 (`changes for 1.0.3`_)
 305
 306 * `lxml 1.0.2`_, released 2006-06-27 (`changes for 1.0.2`_)
 307
 308 * `lxml 1.0.1`_, released 2006-06-09 (`changes for 1.0.1`_)
 309
 310 * `lxml 1.0`_, released 2006-06-01 (`changes for 1.0`_)
 311
 312 * `lxml 0.9.2`_, released 2006-05-10 (`changes for 0.9.2`_)
 313
 314 * `lxml 0.9.1`_, released 2006-03-30 (`changes for 0.9.1`_)
 315
 316 * `lxml 0.9`_,   released 2006-03-20 (`changes for 0.9`_)
 317
 318 * `lxml 0.8`_,   released 2005-11-03 (`changes for 0.8`_)
 319
 320 * `lxml 0.7`_,   released 2005-06-15 (`changes for 0.7`_)
 321
 322 * `lxml 0.6`_,   released 2005-05-14 (`changes for 0.6`_)
 323
 324 * `lxml 0.5.1`_, released 2005-04-09 (`changes for 0.5.1`_)
 325
 326 * `lxml 0.5`_,   released 2005-04-08
 327
 328 .. _`lxml 2.2.3`: lxml-2.2.3.tgz
 329 .. _`lxml 2.2.2`: lxml-2.2.2.tgz
 330 .. _`lxml 2.2.1`: lxml-2.2.1.tgz
 331 .. _`lxml 2.2`: lxml-2.2.tgz
 332 .. _`lxml 2.2beta4`: lxml-2.2beta4.tgz
 333 .. _`lxml 2.2beta3`: lxml-2.2beta3.tgz
 334 .. _`lxml 2.2beta2`: lxml-2.2beta2.tgz
 335 .. _`lxml 2.2beta1`: lxml-2.2beta1.tgz
 336 .. _`lxml 2.2alpha1`: lxml-2.2alpha1.tgz
 337 .. _`lxml 2.1.5`: lxml-2.1.5.tgz
 338 .. _`lxml 2.1.4`: lxml-2.1.4.tgz
 339 .. _`lxml 2.1.3`: lxml-2.1.3.tgz
 340 .. _`lxml 2.1.2`: lxml-2.1.2.tgz
 341 .. _`lxml 2.1.1`: lxml-2.1.1.tgz
 342 .. _`lxml 2.1`: lxml-2.1.tgz
 343 .. _`lxml 2.0.11`: lxml-2.0.11.tgz
 344 .. _`lxml 2.0.10`: lxml-2.0.10.tgz
 345 .. _`lxml 2.0.9`: lxml-2.0.9.tgz
 346 .. _`lxml 2.0.8`: lxml-2.0.8.tgz
 347 .. _`lxml 2.0.7`: lxml-2.0.7.tgz
 348 .. _`lxml 2.0.6`: lxml-2.0.6.tgz
 349 .. _`lxml 2.0.5`: lxml-2.0.5.tgz
 350 .. _`lxml 2.0.4`: lxml-2.0.4.tgz
 351 .. _`lxml 2.0.3`: lxml-2.0.3.tgz
 352 .. _`lxml 2.0.2`: lxml-2.0.2.tgz
 353 .. _`lxml 2.0.1`: lxml-2.0.1.tgz
 354 .. _`lxml 2.0`: lxml-2.0.tgz
 355 .. _`lxml 1.3.6`: lxml-1.3.6.tgz
 356 .. _`lxml 1.3.5`: lxml-1.3.5.tgz
 357 .. _`lxml 1.3.4`: lxml-1.3.4.tgz
 358 .. _`lxml 1.3.3`: lxml-1.3.3.tgz
 359 .. _`lxml 1.3.2`: lxml-1.3.2.tgz
 360 .. _`lxml 1.3`: lxml-1.3.tgz
 361 .. _`lxml 1.2.1`: lxml-1.2.1.tgz
 362 .. _`lxml 1.2`: lxml-1.2.tgz
 363 .. _`lxml 1.1.2`: lxml-1.1.2.tgz
 364 .. _`lxml 1.1.1`: lxml-1.1.1.tgz
 365 .. _`lxml 1.1`: lxml-1.1.tgz
 366 .. _`lxml 1.0.4`: lxml-1.0.4.tgz
 367 .. _`lxml 1.0.3`: lxml-1.0.3.tgz
 368 .. _`lxml 1.0.2`: lxml-1.0.2.tgz
 369 .. _`lxml 1.0.1`: lxml-1.0.1.tgz
 370 .. _`lxml 1.0`: lxml-1.0.tgz
 371 .. _`lxml 0.9.2`: lxml-0.9.2.tgz
 372 .. _`lxml 0.9.1`: lxml-0.9.1.tgz
 373 .. _`lxml 0.9`: lxml-0.9.tgz
 374 .. _`lxml 0.8`: lxml-0.8.tgz
 375 .. _`lxml 0.7`: lxml-0.7.tgz
 376 .. _`lxml 0.6`: lxml-0.6.tgz
 377 .. _`lxml 0.5.1`: lxml-0.5.1.tgz
 378 .. _`lxml 0.5`: lxml-0.5.tgz
 379
 380 .. _`changes for 2.2.3`: changes-2.2.3.html
 381 .. _`changes for 2.2.2`: changes-2.2.2.html
 382 .. _`changes for 2.2.1`: changes-2.2.1.html
 383 .. _`changes for 2.2`: changes-2.2.html
 384 .. _`changes for 2.2beta4`: changes-2.2beta4.html
 385 .. _`changes for 2.2beta3`: changes-2.2beta3.html
 386 .. _`changes for 2.2beta2`: changes-2.2beta2.html
 387 .. _`changes for 2.2beta1`: changes-2.2beta1.html
 388 .. _`changes for 2.2alpha1`: changes-2.2alpha1.html
 389 .. _`changes for 2.1.5`: changes-2.1.5.html
 390 .. _`changes for 2.1.4`: changes-2.1.4.html
 391 .. _`changes for 2.1.3`: changes-2.1.3.html
 392 .. _`changes for 2.1.2`: changes-2.1.2.html
 393 .. _`changes for 2.1.1`: changes-2.1.1.html
 394 .. _`changes for 2.1`: changes-2.1.html
 395 .. _`changes for 2.0.11`: changes-2.0.11.html
 396 .. _`changes for 2.0.10`: changes-2.0.10.html
 397 .. _`changes for 2.0.9`: changes-2.0.9.html
 398 .. _`changes for 2.0.8`: changes-2.0.8.html
 399 .. _`changes for 2.0.7`: changes-2.0.7.html
 400 .. _`changes for 2.0.6`: changes-2.0.6.html
 401 .. _`changes for 2.0.5`: changes-2.0.5.html
 402 .. _`changes for 2.0.4`: changes-2.0.4.html
 403 .. _`changes for 2.0.3`: changes-2.0.3.html
 404 .. _`changes for 2.0.2`: changes-2.0.2.html
 405 .. _`changes for 2.0.1`: changes-2.0.1.html
 406 .. _`changes for 2.0`: changes-2.0.html
 407 .. _`changes for 1.3.6`: changes-1.3.6.html
 408 .. _`changes for 1.3.5`: changes-1.3.5.html
 409 .. _`changes for 1.3.4`: changes-1.3.4.html
 410 .. _`changes for 1.3.3`: changes-1.3.3.html
 411 .. _`changes for 1.3.2`: changes-1.3.2.html
 412 .. _`changes for 1.3.1`: changes-1.3.1.html
 413 .. _`changes for 1.3`: changes-1.3.html
 414 .. _`changes for 1.2.1`: changes-1.2.1.html
 415 .. _`changes for 1.2`: changes-1.2.html
 416 .. _`changes for 1.1.2`: changes-1.1.2.html
 417 .. _`changes for 1.1.1`: changes-1.1.1.html
 418 .. _`changes for 1.1`: changes-1.1.html
 419 .. _`changes for 1.0.4`: changes-1.0.4.html
 420 .. _`changes for 1.0.3`: changes-1.0.3.html
 421 .. _`changes for 1.0.2`: changes-1.0.2.html
 422 .. _`changes for 1.0.1`: changes-1.0.1.html
 423 .. _`changes for 1.0`: changes-1.0.html
 424 .. _`changes for 0.9.2`: changes-0.9.2.html
 425 .. _`changes for 0.9.1`: changes-0.9.1.html
 426 .. _`changes for 0.9`: changes-0.9.html
 427 .. _`changes for 0.8`: changes-0.8.html
 428 .. _`changes for 0.7`: changes-0.7.html
 429 .. _`changes for 0.6`: changes-0.6.html
 430 .. _`changes for 0.5.1`: changes-0.5.1.html