capi.txt 2.8 KB

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