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 content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
   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>
  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://bugzilla.gnome.org/buglist.cgi?product=libxslt">Bug Tracker</a></li>
  72 <li><a href="http://xsldbg.sourceforge.net/">Xsldbg Debugger</a></li>
  73 </ul></td></tr>
  74 </table>
  75 </td></tr></table></td>
  76 <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">
  77 <p>There is a number of language bindings and wrappers available for libxml2,
  78 the list below is not exhaustive. Please contact the <a href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>
  79 (<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) in
  80 order to get updates to this list or to discuss the specific topic of libxml2
  81 or libxslt wrappers or bindings:</p>
  82 <ul>
  83 <li>
  84 <a href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
  85     Sergeant</a>
  86      developped <a href="http://axkit.org/download/">XML::LibXML and
  87     XML::LibXSLT</a>, a perl wrapper for libxml2/libxslt as part of the <a href="http://axkit.com/">AxKit XML application server</a>
  88 </li>
  89 <li>
  90 <a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a>
  91      provides and earlier version of the libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for Python</a>
  92 </li>
  93 <li>Petr Kozelka provides <a href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
  94     libxml2</a> with Kylix, Delphi and other Pascal compilers</li>
  95 <li>Wai-Sun &quot;Squidster&quot; Chia provides <a href="http://www.rubycolor.org/arc/redist/">bindings for Ruby</a>  and
  96     libxml2 bindings are also available in Ruby through the <a href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a> module
  97     maintained by Tobias Peters.</li>
  98 <li>Steve Ball and contributors maintains <a href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
  99     Tcl</a>
 100 </li>
 101 </ul>
 102 <p>The libxslt Python module depends on the <a href="http://xmlsoft.org/python.html">libxml2 Python</a> module.</p>
 103 <p>The distribution includes a set of Python bindings, which are garanteed to
 104 be maintained as part of the library in the future, though the Python
 105 interface have not yet reached the maturity of the C API. The distribution
 106 includes a set of examples and regression tests for the python bindings in
 107 the <code>python/tests</code> directory. Here are some excepts from those
 108 tests:</p>
 109 <h3>basic.py:</h3>
 110 <p>This is a basic test of XSLT interfaces: loading a stylesheet and a
 111 document, transforming the document and saving the result.</p>
 112 <pre>import libxml2
 113 import libxslt
 114
 115 styledoc = libxml2.parseFile(&quot;test.xsl&quot;)
 116 style = libxslt.parseStylesheetDoc(styledoc)
 117 doc = libxml2.parseFile(&quot;test.xml&quot;)
 118 result = style.applyStylesheet(doc, None)
 119 style.saveResultToFilename(&quot;foo&quot;, result, 0)
 120 style.freeStylesheet()
 121 doc.freeDoc()
 122 result.freeDoc()</pre>
 123 <p>The Python module is called libxslt, you will also need the libxml2 module
 124 for the operations on XML trees. Let's have a look at the objects manipulated
 125 in that example and how is the processing done:</p>
 126 <ul>
 127 <li>
 128 <code>styledoc</code>
 129     : is a libxml2 document tree. It is obtained by parsing the XML file
 130     &quot;test.xsl&quot; containing the stylesheet.</li>
 131 <li>
 132 <code>style</code>
 133     : this is a precompiled stylesheet ready to be used by the following
 134     transformations (note the plural form, multiple transformations can
 135     resuse the same stylesheet).</li>
 136 <li>
 137 <code>doc</code>
 138     : this is the document to apply the transformation to. In this case it is
 139     simply generated by parsing it from a file but any other processing is
 140     possible as long as one get a libxml2 Doc. Note that HTML tree are
 141     suitable for XSLT processing in libxslt. This is actually how this page
 142     is generated !</li>
 143 <li>
 144 <code>result</code>
 145     : this is a document generated by applying the stylesheet to the
 146     document. Note that some of the stylesheet informations may be related to
 147     the serialization of that document and as in this example a specific
 148     saveResultToFilename() method of the stylesheet should be used to save it
 149     to a file (in that case to &quot;foo&quot;).</li>
 150 </ul>
 151 <p>Also note the need to explicitely deallocate documents with freeDoc()
 152 except for the stylesheet document which is freed when its compiled form is
 153 garbage collected.</p>
 154 <h3>extfunc.py:</h3>
 155 <p>This one is a far more complex test. It shows how to modify the behaviour
 156 of an XSLT transformation by passing parameters and how to extend the XSLT
 157 engine with functions defined in python:</p>
 158 <pre>import libxml2
 159 import libxslt
 160 import string
 161
 162 nodeName = None
 163 def f(ctx, str):
 164     global nodeName
 165
 166     #
 167     # Small check to verify the context is correcly accessed
 168     #
 169     try:
 170         pctxt = libxslt.xpathParserContext(_obj=ctx)
 171         ctxt = pctxt.context()
 172         tctxt = ctxt.transformContext()
 173         nodeName = tctxt.insertNode().name
 174     except:
 175         pass
 176
 177     return string.upper(str)
 178
 179 libxslt.registerExtModuleFunction(&quot;foo&quot;, &quot;http://example.com/foo&quot;, f)</pre>
 180 <p>This code defines and register an extension function. Note that the
 181 function can be bound to any name (foo) and how the binding is also
 182 associated to a namespace name &quot;http://example.com/foo&quot;. From an XSLT point
 183 of view the function just returns an upper case version of the string passed
 184 as a parameter. But the first part of the function also read some contextual
 185 information from the current XSLT processing environement, in that case it
 186 looks for the current insertion node in the resulting output (either the
 187 resulting document or the Result Value Tree being generated), and saves it to
 188 a global variable for checking that the access actually worked.</p>
 189 <p>For more informations on the xpathParserContext and transformContext
 190 objects check the <a href="internals.html">libray internals description</a>.
 191 The pctxt is actually an object from a class derived from the
 192 libxml2.xpathParserContext() with just a couple more properties including the
 193 possibility to look up the XSLT transformation context from the XPath
 194 context.</p>
 195 <pre>styledoc = libxml2.parseDoc(&quot;&quot;&quot;
 196 &lt;xsl:stylesheet version='1.0'
 197   xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
 198   xmlns:foo='http://example.com/foo'
 199   xsl:exclude-result-prefixes='foo'&gt;
 200
 201   &lt;xsl:param name='bar'&gt;failure&lt;/xsl:param&gt;
 202   &lt;xsl:template match='/'&gt;
 203     &lt;article&gt;&lt;xsl:value-of select='foo:foo($bar)'/&gt;&lt;/article&gt;
 204   &lt;/xsl:template&gt;
 205 &lt;/xsl:stylesheet&gt;
 206 &quot;&quot;&quot;)</pre>
 207 <p>Here is a simple example of how to read an XML document from a python
 208 string with libxml2. Note how this stylesheet:</p>
 209 <ul>
 210 <li>Uses a global parameter <code>bar</code>
 211 </li>
 212 <li>Reference the extension function f</li>
 213 <li>how the Namespace name &quot;http://example.com/foo&quot; has to be bound to a
 214     prefix</li>
 215 <li>how that prefix is excluded from the output</li>
 216 <li>how the function is called from the select</li>
 217 </ul>
 218 <pre>style = libxslt.parseStylesheetDoc(styledoc)
 219 doc = libxml2.parseDoc(&quot;&lt;doc/&gt;&quot;)
 220 result = style.applyStylesheet(doc, { &quot;bar&quot;: &quot;'success'&quot; })
 221 style.freeStylesheet()
 222 doc.freeDoc()</pre>
 223 <p>that part is identical, to the basic example except that the
 224 transformation is passed a dictionnary of parameters. Note that the string
 225 passed &quot;success&quot; had to be quoted, otherwise it is interpreted as an XPath
 226 query for the childs of root named &quot;success&quot;.</p>
 227 <pre>root = result.children
 228 if root.name != &quot;article&quot;:
 229     print &quot;Unexpected root node name&quot;
 230     sys.exit(1)
 231 if root.content != &quot;SUCCESS&quot;:
 232     print &quot;Unexpected root node content, extension function failed&quot;
 233     sys.exit(1)
 234 if nodeName != 'article':
 235     print &quot;The function callback failed to access its context&quot;
 236     sys.exit(1)
 237
 238 result.freeDoc()</pre>
 239 <p>That part just verifies that the transformation worked, that the parameter
 240 got properly passed to the engine, that the function f() got called and that
 241 it properly accessed the context to find the name of the insertion node.</p>
 242 <h3>pyxsltproc.py:</h3>
 243 <p>this module is a bit too long to be described there but it is basically a
 244 rewrite of the xsltproc command line interface of libxslt in Python. It
 245 provides nearly all the functionalities of xsltproc and can be used as a base
 246 module to write Python customized XSLT processors. One of the thing to notice
 247 are:</p>
 248 <pre>libxml2.lineNumbersDefault(1)
 249 libxml2.substituteEntitiesDefault(1)</pre>
 250 <p>those two calls in the main() function are needed to force the libxml2
 251 processor to generate DOM trees compliant with the XPath data model.</p>
 252 <p><a href="mailto:daniel@veillard.com">Daniel Veillard</a></p>
 253 </td></tr></table></td></tr></table></td></tr></table></td>
 254 </tr></table></td></tr></table>
 255 </body>
 256 </html>