doc/capi.txt

   1 ==============================
   2 The public C-API of lxml.etree
   3 ==============================
   4
   5 As of version 1.1, lxml.etree provides a public C-API.  This allows external
   6 C extensions to efficiently access public functions and classes of lxml,
   7 without going through the Python API.
   8
   9 The API is described in the file `etreepublic.pxd`_, which is directly
  10 c-importable by extension modules implemented in Pyrex_ or Cython_.
  11
  12 .. _`etreepublic.pxd`: http://codespeak.net/svn/lxml/trunk/src/lxml/etreepublic.pxd
  13 .. _Cython: http://www.cython.org
  14 .. _Pyrex: http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/
  15
  16 .. contents::
  17 ..
  18    1  Writing external modules in Cython
  19    2  Writing external modules in C
  20
  21
  22 Writing external modules in Cython
  23 ----------------------------------
  24
  25 This is the easiest way of extending lxml at the C level.  A Cython_
  26 (or Pyrex_) module should start like this::
  27
  28     # My Cython extension
  29
  30     # import the public functions and classes of lxml.etree
  31     cimport etreepublic as cetree
  32
  33     # import the lxml.etree module in Python
  34     cdef object etree
  35     from lxml import etree
  36
  37     # initialize the access to the C-API of lxml.etree
  38     cetree.import_lxml__etree()
  39
  40 From this line on, you can access all public functions of lxml.etree
  41 from the ``cetree`` namespace like this::
  42
  43     # build a tag name from namespace and element name
  44     py_tag = cetree.namespacedNameFromNsName("http://some/url", "myelement")
  45
  46 Public lxml classes are easily subclassed.  For example, to implement
  47 and set a new default element class, you can write Cython code like
  48 the following::
  49
  50     from etreepublic cimport ElementBase
  51     cdef class NewElementClass(ElementBase):
  52          def set_value(self, myval):
  53              self.set("my_attribute", myval)
  54
  55     etree.set_element_class_lookup(
  56          etree.DefaultElementClassLookup(element=NewElementClass))
  57
  58
  59 Writing external modules in C
  60 -----------------------------
  61
  62 If you really feel like it, you can also interface with lxml.etree straight
  63 from C code.  All you have to do is include the header file for the public
  64 API, import the ``lxml.etree`` module and then call the import function:
  65
  66 .. sourcecode:: c
  67
  68     /* My C extension */
  69
  70     /* common includes */
  71     #include "Python.h"
  72     #include "stdio.h"
  73     #include "string.h"
  74     #include "stdarg.h"
  75     #include "libxml/xmlversion.h"
  76     #include "libxml/encoding.h"
  77     #include "libxml/hash.h"
  78     #include "libxml/tree.h"
  79     #include "libxml/xmlIO.h"
  80     #include "libxml/xmlsave.h"
  81     #include "libxml/globals.h"
  82     #include "libxml/xmlstring.h"
  83
  84     /* lxml.etree specific includes */
  85     #include "lxml-version.h"
  86     #include "etree_defs.h"
  87     #include "etree.h"
  88
  89     /* setup code */
  90     import_lxml__etree()
  91
  92 Note that including ``etree.h`` does not automatically include the
  93 header files it requires.  Note also that the above list of common
  94 includes may not be sufficient.