1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
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 }
13 <title>Python and bindings</title>
15 <body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
16 <table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
18 <a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 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>
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>
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">
30 <form action="search.php" enctype="application/x-www-form-urlencoded" method="GET">
31 <input name="query" type="TEXT" size="20" value=""><input name="submit" type="submit" value="Search ...">
34 <li><a href="index.html">Home</a></li>
35 <li><a href="intro.html">Introduction</a></li>
36 <li><a href="docs.html">Documentation</a></li>
37 <li><a href="bugs.html">Reporting bugs and getting help</a></li>
38 <li><a href="help.html">How to help</a></li>
39 <li><a href="downloads.html">Downloads</a></li>
40 <li><a href="FAQ.html">FAQ</a></li>
41 <li><a href="news.html">News</a></li>
42 <li><a href="xsltproc2.html">The xsltproc tool</a></li>
43 <li><a href="docbook.html">DocBook</a></li>
44 <li><a href="API.html">The programming API</a></li>
45 <li><a href="python.html">Python and bindings</a></li>
46 <li><a href="internals.html">Library internals</a></li>
47 <li><a href="extensions.html">Writing extensions</a></li>
48 <li><a href="contribs.html">Contributions</a></li>
50 <a href="xslt.html">flat page</a>, <a href="site.xsl">stylesheet</a>
55 <table width="100%" border="0" cellspacing="1" cellpadding="3">
56 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
57 <tr><td bgcolor="#fffacd"><ul>
58 <li><a href="tutorial/libxslttutorial.html">Tutorial</a></li>
59 <li><a href="xsltproc.html">Man page for xsltproc</a></li>
60 <li><a href="http://mail.gnome.org/archives/xslt/">Mail archive</a></li>
61 <li><a href="http://xmlsoft.org/">XML libxml</a></li>
62 <li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
63 <li><a href="ftp://xmlsoft.org/">FTP</a></li>
64 <li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li>
65 <li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
66 <li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li>
67 <li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li>
68 <li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">Bug Tracker</a></li>
69 <li><a href="http://xsldbg.sourceforge.net/">Xsldbg Debugger</a></li>
70 <li><a href="http://www.mod-xslt.com/mod-xslt/">Apache module</a></li>
73 <table width="100%" border="0" cellspacing="1" cellpadding="3">
74 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr>
75 <tr><td bgcolor="#fffacd"><ul>
76 <li><a href="APIchunk0.html">Alphabetic</a></li>
77 <li><a href="APIconstructors.html">Constructors</a></li>
78 <li><a href="APIfunctions.html">Functions/Types</a></li>
79 <li><a href="APIfiles.html">Modules</a></li>
80 <li><a href="APIsymbols.html">Symbols</a></li>
83 </td></tr></table></td>
84 <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">
85 <p>There is a number of language bindings and wrappers available for libxml2,
86 the list below is not exhaustive. Please contact the <a href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>
87 (<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) in
88 order to get updates to this list or to discuss the specific topic of libxml2
89 or libxslt wrappers or bindings:</p>
92 <a href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
93 Sergeant</a> developped <a href="http://axkit.org/download/">XML::LibXML
94 and XML::LibXSLT</a>, Perl wrappers for libxml2/libxslt as part of the
95 <a href="http://axkit.com/">AxKit XML application server</a>
98 <a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides and
99 earlier version of the libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for Python</a>
101 <li>Petr Kozelka provides <a href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
102 libxml2</a> with Kylix, Delphi and other Pascal compilers</li>
103 <li>Wai-Sun "Squidster" Chia provides <a href="http://www.rubycolor.org/arc/redist/">bindings for Ruby</a> and
104 libxml2 bindings are also available in Ruby through the <a href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a> module
105 maintained by Tobias Peters.</li>
106 <li>Steve Ball and contributors maintains <a href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
110 <a href="mailto:xmlwrapp@pmade.org">Peter Jones</a> maintains C++
111 bindings for libxslt within <a href="http://pmade.org/pjones/software/xmlwrapp/">xmlwrapp</a>
114 <a href="phillim2@comcast.net">Mike Phillips</a> provides a module
115 using <a href="http://siasl.dyndns.org/projects/projects.html">libxslt
118 <a href="http://savannah.gnu.org/projects/classpathx/">LibxmlJ</a> is
119 an effort to create a 100% JAXP-compatible Java wrapper for
120 libxml2 and libxslt as part of GNU ClasspathX project.
123 <p>The libxslt Python module depends on the <a href="http://xmlsoft.org/python.html">libxml2 Python</a> module.</p>
124 <p>The distribution includes a set of Python bindings, which are garanteed to
125 be maintained as part of the library in the future, though the Python
126 interface have not yet reached the completeness of the C API.</p>
128 <a href="mailto:stephane.bidoul@softwareag.com">Stéphane Bidoul</a>
129 maintains <a href="http://users.skynet.be/sbi/libxml-python/">a Windows port
130 of the Python bindings</a>.</p>
131 <p>Note to people interested in building bindings, the API is formalized as
132 <a href="libxslt-api.xml">an XML API description file</a> which allows to
133 automate a large part of the Python bindings, this includes function
134 descriptions, enums, structures, typedefs, etc... The Python script used to
135 build the bindings is python/generator.py in the source distribution.</p>
136 <p>To install the Python bindings there are 2 options:</p>
138 <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
139 RPM</a> and the <a href="http://rpmfind.net/linux/rpm2html/search.php?query=libxslt-python">libxslt-python
141 <li>Otherwise use the <a href="ftp://xmlsoft.org/python/">libxml2-python
142 module distribution</a> corresponding to your installed version of
143 libxml2 and libxslt. Note that to install it you will need both libxml2
144 and libxslt installed and run "python setup.py build install" in the
147 <p>The distribution includes a set of examples and regression tests for the
148 python bindings in the <code>python/tests</code> directory. Here are some
149 excepts from those tests:</p>
151 <p>This is a basic test of XSLT interfaces: loading a stylesheet and a
152 document, transforming the document and saving the result.</p>
156 styledoc = libxml2.parseFile("test.xsl")
157 style = libxslt.parseStylesheetDoc(styledoc)
158 doc = libxml2.parseFile("test.xml")
159 result = style.applyStylesheet(doc, None)
160 style.saveResultToFilename("foo", result, 0)
161 style.freeStylesheet()
163 result.freeDoc()</pre>
164 <p>The Python module is called libxslt, you will also need the libxml2 module
165 for the operations on XML trees. Let's have a look at the objects manipulated
166 in that example and how is the processing done:</p>
169 <code>styledoc</code> : is a libxml2 document tree. It is obtained by
170 parsing the XML file "test.xsl" containing the stylesheet.</li>
172 <code>style</code> : this is a precompiled stylesheet ready to be used
173 by the following transformations (note the plural form, multiple
174 transformations can resuse the same stylesheet).</li>
176 <code>doc</code> : this is the document to apply the transformation to.
177 In this case it is simply generated by parsing it from a file but any
178 other processing is possible as long as one get a libxml2 Doc. Note that
179 HTML tree are suitable for XSLT processing in libxslt. This is actually
180 how this page is generated !</li>
182 <code>result</code> : this is a document generated by applying the
183 stylesheet to the document. Note that some of the stylesheet informations
184 may be related to the serialization of that document and as in this
185 example a specific saveResultToFilename() method of the stylesheet should
186 be used to save it to a file (in that case to "foo").</li>
188 <p>Also note the need to explicitely deallocate documents with freeDoc()
189 except for the stylesheet document which is freed when its compiled form is
190 garbage collected.</p>
192 <p>This one is a far more complex test. It shows how to modify the behaviour
193 of an XSLT transformation by passing parameters and how to extend the XSLT
194 engine with functions defined in python:</p>
204 # Small check to verify the context is correcly accessed
207 pctxt = libxslt.xpathParserContext(_obj=ctx)
208 ctxt = pctxt.context()
209 tctxt = ctxt.transformContext()
210 nodeName = tctxt.insertNode().name
214 return string.upper(str)
216 libxslt.registerExtModuleFunction("foo", "http://example.com/foo", f)</pre>
217 <p>This code defines and register an extension function. Note that the
218 function can be bound to any name (foo) and how the binding is also
219 associated to a namespace name "http://example.com/foo". From an XSLT point
220 of view the function just returns an upper case version of the string passed
221 as a parameter. But the first part of the function also read some contextual
222 information from the current XSLT processing environement, in that case it
223 looks for the current insertion node in the resulting output (either the
224 resulting document or the Result Value Tree being generated), and saves it to
225 a global variable for checking that the access actually worked.</p>
226 <p>For more informations on the xpathParserContext and transformContext
227 objects check the <a href="internals.html">libray internals description</a>.
228 The pctxt is actually an object from a class derived from the
229 libxml2.xpathParserContext() with just a couple more properties including the
230 possibility to look up the XSLT transformation context from the XPath
232 <pre>styledoc = libxml2.parseDoc("""
233 <xsl:stylesheet version='1.0'
234 xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
235 xmlns:foo='http://example.com/foo'
236 xsl:exclude-result-prefixes='foo'>
238 <xsl:param name='bar'>failure</xsl:param>
239 <xsl:template match='/'>
240 <article><xsl:value-of select='foo:foo($bar)'/></article>
241 </xsl:template>
242 </xsl:stylesheet>
243 """)</pre>
244 <p>Here is a simple example of how to read an XML document from a python
245 string with libxml2. Note how this stylesheet:</p>
247 <li>Uses a global parameter <code>bar</code>
249 <li>Reference the extension function f</li>
250 <li>how the Namespace name "http://example.com/foo" has to be bound to a
252 <li>how that prefix is excluded from the output</li>
253 <li>how the function is called from the select</li>
255 <pre>style = libxslt.parseStylesheetDoc(styledoc)
256 doc = libxml2.parseDoc("<doc/>")
257 result = style.applyStylesheet(doc, { "bar": "'success'" })
258 style.freeStylesheet()
260 <p>that part is identical, to the basic example except that the
261 transformation is passed a dictionnary of parameters. Note that the string
262 passed "success" had to be quoted, otherwise it is interpreted as an XPath
263 query for the childs of root named "success".</p>
264 <pre>root = result.children
265 if root.name != "article":
266 print "Unexpected root node name"
268 if root.content != "SUCCESS":
269 print "Unexpected root node content, extension function failed"
271 if nodeName != 'article':
272 print "The function callback failed to access its context"
275 result.freeDoc()</pre>
276 <p>That part just verifies that the transformation worked, that the parameter
277 got properly passed to the engine, that the function f() got called and that
278 it properly accessed the context to find the name of the insertion node.</p>
279 <h3>pyxsltproc.py:</h3>
280 <p>this module is a bit too long to be described there but it is basically a
281 rewrite of the xsltproc command line interface of libxslt in Python. It
282 provides nearly all the functionalities of xsltproc and can be used as a base
283 module to write Python customized XSLT processors. One of the thing to notice
285 <pre>libxml2.lineNumbersDefault(1)
286 libxml2.substituteEntitiesDefault(1)</pre>
287 <p>those two calls in the main() function are needed to force the libxml2
288 processor to generate DOM trees compliant with the XPath data model.</p>
289 <p><a href="bugs.html">Daniel Veillard</a></p>
290 </td></tr></table></td></tr></table></td></tr></table></td>
291 </tr></table></td></tr></table>