doc/python.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   5 <style type="text/css"><!--
   6 TD {font-family: Verdana,Arial,Helvetica}
   7 BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
   8 H1 {font-family: Verdana,Arial,Helvetica}
   9 H2 {font-family: Verdana,Arial,Helvetica}
  10 H3 {font-family: Verdana,Arial,Helvetica}
  11 A:link, A:visited, A:active { text-decoration: underline }
  12 --></style>
  13 <title>Python and bindings</title>
  14 </head>
  15 <body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
  16 <table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
  17 <td width="100">
  18 <a href="http://www.gnome.org/"><img src="smallfootonly.gif" alt="Gnome Logo"></a><a href="http://www.redhat.com"><img src="redhat.gif" alt="Red Hat Logo"></a><div align="left"><a href="http://xmlsoft.org/XSLT/"><img src="Libxslt-Logo-180x168.gif" alt="Made with Libxslt Logo"></a></div>
  19 </td>
  20 <td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center">
  21 <h1>The XSLT C library for Gnome</h1>
  22 <h2>Python and bindings</h2>
  23 </td></tr></table></td></tr></table></td>
  24 </tr></table>
  25 <table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr>
  26 <td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td>
  27 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  28 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr>
  29 <tr><td bgcolor="#fffacd"><ul>
  30 <li><a href="index.html">Home</a></li>
  31 <li><a href="intro.html">Introduction</a></li>
  32 <li><a href="docs.html">Documentation</a></li>
  33 <li><a href="bugs.html">Reporting bugs and getting help</a></li>
  34 <li><a href="help.html">How to help</a></li>
  35 <li><a href="downloads.html">Downloads</a></li>
  36 <li><a href="FAQ.html">FAQ</a></li>
  37 <li><a href="news.html">News</a></li>
  38 <li><a href="xsltproc2.html">The xsltproc tool</a></li>
  39 <li><a href="docbook.html">DocBook</a></li>
  40 <li><a href="API.html">The programming API</a></li>
  41 <li><a href="python.html">Python and bindings</a></li>
  42 <li><a href="internals.html">Library internals</a></li>
  43 <li><a href="extensions.html">Writing extensions</a></li>
  44 <li><a href="contribs.html">Contributions</a></li>
  45 <li>
  46 <a href="xslt.html">flat page</a>, <a href="site.xsl">stylesheet</a>
  47 </li>
  48 </ul></td></tr>
  49 </table>
  50 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  51 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr>
  52 <tr><td bgcolor="#fffacd"><ul>
  53 <li><a href="APIchunk0.html">Alphabetic</a></li>
  54 <li><a href="APIconstructors.html">Constructors</a></li>
  55 <li><a href="APIfunctions.html">Functions/Types</a></li>
  56 <li><a href="APIfiles.html">Modules</a></li>
  57 <li><a href="APIsymbols.html">Symbols</a></li>
  58 </ul></td></tr>
  59 </table>
  60 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  61 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
  62 <tr><td bgcolor="#fffacd"><ul>
  63 <li><a href="tutorial/libxslttutorial.html">Tutorial</a></li>
  64 <li><a href="xsltproc.html">Man page for xsltproc</a></li>
  65 <li><a href="http://mail.gnome.org/archives/xslt/">Mail archive</a></li>
  66 <li><a href="http://xmlsoft.org/">XML libxml</a></li>
  67 <li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
  68 <li><a href="ftp://xmlsoft.org/">FTP</a></li>
  69 <li><a href="http://www.fh-frankfurt.de/~igor/projects/libxml/">Windows binaries</a></li>
  70 <li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
  71 <li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li>
  72 <li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">Bug Tracker</a></li>
  73 <li><a href="http://xsldbg.sourceforge.net/">Xsldbg Debugger</a></li>
  74 </ul></td></tr>
  75 </table>
  76 </td></tr></table></td>
  77 <td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd">
  78 <p>There is a number of language bindings and wrappers available for libxml2,
  79 the list below is not exhaustive. Please contact the <a href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>
  80 (<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) in
  81 order to get updates to this list or to discuss the specific topic of libxml2
  82 or libxslt wrappers or bindings:</p>
  83 <ul>
  84 <li>
  85 <a href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
  86     Sergeant</a> developped <a href="http://axkit.org/download/">XML::LibXML
  87     and XML::LibXSLT</a>, a perl wrapper for libxml2/libxslt as part of the
  88     <a href="http://axkit.com/">AxKit XML application server</a>
  89 </li>
  90   <li>
  91 <a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides and
  92     earlier version of the libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for Python</a>
  93 </li>
  94   <li>Petr Kozelka provides <a href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
  95     libxml2</a> with Kylix, Delphi and other Pascal compilers</li>
  96   <li>Wai-Sun &quot;Squidster&quot; Chia provides <a href="http://www.rubycolor.org/arc/redist/">bindings for Ruby</a>  and
  97     libxml2 bindings are also available in Ruby through the <a href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a> module
  98     maintained by Tobias Peters.</li>
  99   <li>Steve Ball and contributors maintains <a href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
 100     Tcl</a>
 101 </li>
 102 </ul>
 103 <p>The libxslt Python module depends on the <a href="http://xmlsoft.org/python.html">libxml2 Python</a> module.</p>
 104 <p>The distribution includes a set of Python bindings, which are garanteed to
 105 be maintained as part of the library in the future, though the Python
 106 interface have not yet reached the maturity of the C API.</p>
 107 <p>To install the Python bindings there are 2 options:</p>
 108 <ul>
 109 <li>If you use an RPM based distribution, simply install the <a href="http://rpmfind.net/linux/rpm2html/search.php?query=libxml2-python">libxml2-python
 110     RPM</a> and the <a href="http://rpmfind.net/linux/rpm2html/search.php?query=libxslt-python">libxslt-python
 111     RPM</a>.</li>
 112   <li>Otherwise use the <a href="ftp://xmlsoft.org/python/">libxml2-python
 113     module distribution</a> corresponding to your installed version of
 114     libxml2 and libxslt. Note that to install it you will need both libxml2
 115     and libxslt installed and run &quot;python setup.py build install&quot; in the
 116     module tree.</li>
 117 </ul>
 118 <p>The distribution includes a set of examples and regression tests for the
 119 python bindings in the <code>python/tests</code> directory. Here are some
 120 excepts from those tests:</p>
 121 <h3>basic.py:</h3>
 122 <p>This is a basic test of XSLT interfaces: loading a stylesheet and a
 123 document, transforming the document and saving the result.</p>
 124 <pre>import libxml2
 125 import libxslt
 126
 127 styledoc = libxml2.parseFile(&quot;test.xsl&quot;)
 128 style = libxslt.parseStylesheetDoc(styledoc)
 129 doc = libxml2.parseFile(&quot;test.xml&quot;)
 130 result = style.applyStylesheet(doc, None)
 131 style.saveResultToFilename(&quot;foo&quot;, result, 0)
 132 style.freeStylesheet()
 133 doc.freeDoc()
 134 result.freeDoc()</pre>
 135 <p>The Python module is called libxslt, you will also need the libxml2 module
 136 for the operations on XML trees. Let's have a look at the objects manipulated
 137 in that example and how is the processing done:</p>
 138 <ul>
 139 <li>
 140 <code>styledoc</code> : is a libxml2 document tree. It is obtained by
 141     parsing the XML file &quot;test.xsl&quot; containing the stylesheet.</li>
 142   <li>
 143 <code>style</code> : this is a precompiled stylesheet ready to be used
 144     by the following transformations (note the plural form, multiple
 145     transformations can resuse the same stylesheet).</li>
 146   <li>
 147 <code>doc</code> : this is the document to apply the transformation to.
 148     In this case it is simply generated by parsing it from a file but any
 149     other processing is possible as long as one get a libxml2 Doc. Note that
 150     HTML tree are suitable for XSLT processing in libxslt. This is actually
 151     how this page is generated !</li>
 152   <li>
 153 <code>result</code> : this is a document generated by applying the
 154     stylesheet to the document. Note that some of the stylesheet informations
 155     may be related to the serialization of that document and as in this
 156     example a specific saveResultToFilename() method of the stylesheet should
 157     be used to save it to a file (in that case to &quot;foo&quot;).</li>
 158 </ul>
 159 <p>Also note the need to explicitely deallocate documents with freeDoc()
 160 except for the stylesheet document which is freed when its compiled form is
 161 garbage collected.</p>
 162 <h3>extfunc.py:</h3>
 163 <p>This one is a far more complex test. It shows how to modify the behaviour
 164 of an XSLT transformation by passing parameters and how to extend the XSLT
 165 engine with functions defined in python:</p>
 166 <pre>import libxml2
 167 import libxslt
 168 import string
 169
 170 nodeName = None
 171 def f(ctx, str):
 172     global nodeName
 173
 174     #
 175     # Small check to verify the context is correcly accessed
 176     #
 177     try:
 178         pctxt = libxslt.xpathParserContext(_obj=ctx)
 179         ctxt = pctxt.context()
 180         tctxt = ctxt.transformContext()
 181         nodeName = tctxt.insertNode().name
 182     except:
 183         pass
 184
 185     return string.upper(str)
 186
 187 libxslt.registerExtModuleFunction(&quot;foo&quot;, &quot;http://example.com/foo&quot;, f)</pre>
 188 <p>This code defines and register an extension function. Note that the
 189 function can be bound to any name (foo) and how the binding is also
 190 associated to a namespace name &quot;http://example.com/foo&quot;. From an XSLT point
 191 of view the function just returns an upper case version of the string passed
 192 as a parameter. But the first part of the function also read some contextual
 193 information from the current XSLT processing environement, in that case it
 194 looks for the current insertion node in the resulting output (either the
 195 resulting document or the Result Value Tree being generated), and saves it to
 196 a global variable for checking that the access actually worked.</p>
 197 <p>For more informations on the xpathParserContext and transformContext
 198 objects check the <a href="internals.html">libray internals description</a>.
 199 The pctxt is actually an object from a class derived from the
 200 libxml2.xpathParserContext() with just a couple more properties including the
 201 possibility to look up the XSLT transformation context from the XPath
 202 context.</p>
 203 <pre>styledoc = libxml2.parseDoc(&quot;&quot;&quot;
 204 &lt;xsl:stylesheet version='1.0'
 205   xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
 206   xmlns:foo='http://example.com/foo'
 207   xsl:exclude-result-prefixes='foo'&gt;
 208
 209   &lt;xsl:param name='bar'&gt;failure&lt;/xsl:param&gt;
 210   &lt;xsl:template match='/'&gt;
 211     &lt;article&gt;&lt;xsl:value-of select='foo:foo($bar)'/&gt;&lt;/article&gt;
 212   &lt;/xsl:template&gt;
 213 &lt;/xsl:stylesheet&gt;
 214 &quot;&quot;&quot;)</pre>
 215 <p>Here is a simple example of how to read an XML document from a python
 216 string with libxml2. Note how this stylesheet:</p>
 217 <ul>
 218 <li>Uses a global parameter <code>bar</code>
 219 </li>
 220   <li>Reference the extension function f</li>
 221   <li>how the Namespace name &quot;http://example.com/foo&quot; has to be bound to a
 222     prefix</li>
 223   <li>how that prefix is excluded from the output</li>
 224   <li>how the function is called from the select</li>
 225 </ul>
 226 <pre>style = libxslt.parseStylesheetDoc(styledoc)
 227 doc = libxml2.parseDoc(&quot;&lt;doc/&gt;&quot;)
 228 result = style.applyStylesheet(doc, { &quot;bar&quot;: &quot;'success'&quot; })
 229 style.freeStylesheet()
 230 doc.freeDoc()</pre>
 231 <p>that part is identical, to the basic example except that the
 232 transformation is passed a dictionnary of parameters. Note that the string
 233 passed &quot;success&quot; had to be quoted, otherwise it is interpreted as an XPath
 234 query for the childs of root named &quot;success&quot;.</p>
 235 <pre>root = result.children
 236 if root.name != &quot;article&quot;:
 237     print &quot;Unexpected root node name&quot;
 238     sys.exit(1)
 239 if root.content != &quot;SUCCESS&quot;:
 240     print &quot;Unexpected root node content, extension function failed&quot;
 241     sys.exit(1)
 242 if nodeName != 'article':
 243     print &quot;The function callback failed to access its context&quot;
 244     sys.exit(1)
 245
 246 result.freeDoc()</pre>
 247 <p>That part just verifies that the transformation worked, that the parameter
 248 got properly passed to the engine, that the function f() got called and that
 249 it properly accessed the context to find the name of the insertion node.</p>
 250 <h3>pyxsltproc.py:</h3>
 251 <p>this module is a bit too long to be described there but it is basically a
 252 rewrite of the xsltproc command line interface of libxslt in Python. It
 253 provides nearly all the functionalities of xsltproc and can be used as a base
 254 module to write Python customized XSLT processors. One of the thing to notice
 255 are:</p>
 256 <pre>libxml2.lineNumbersDefault(1)
 257 libxml2.substituteEntitiesDefault(1)</pre>
 258 <p>those two calls in the main() function are needed to force the libxml2
 259 processor to generate DOM trees compliant with the XPath data model.</p>
 260 <p><a href="bugs.html">Daniel Veillard</a></p>
 261 </td></tr></table></td></tr></table></td></tr></table></td>
 262 </tr></table></td></tr></table>
 263 </body>
 264 </html>