source: trunk/third/libxslt/doc/python.html @ 21535

Revision 21535, 15.1 KB checked in by ghudson, 20 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r21534, which included commits to RCS files with non-trunk default branches.
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><style type="text/css">
4TD {font-family: Verdana,Arial,Helvetica}
5BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
6H1 {font-family: Verdana,Arial,Helvetica}
7H2 {font-family: Verdana,Arial,Helvetica}
8H3 {font-family: Verdana,Arial,Helvetica}
9A:link, A:visited, A:active { text-decoration: underline }
10    </style><title>Python and bindings</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C 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></td><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"><h1>The XSLT C library for Gnome</h1><h2>Python and bindings</h2></td></tr></table></td></tr></table></td></tr></table><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><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="intro.html">Introduction</a></li><li><a href="docs.html">Documentation</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="news.html">News</a></li><li><a href="xsltproc2.html">The xsltproc tool</a></li><li><a href="docbook.html">DocBook</a></li><li><a href="API.html">The programming API</a></li><li><a href="python.html">Python and bindings</a></li><li><a href="internals.html">Library internals</a></li><li><a href="extensions.html">Writing extensions</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="EXSLT/index.html" style="font-weight:bold">libexslt</a></li><li><a href="xslt.html">flat page</a>, <a href="site.xsl">stylesheet</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="ChangeLog.html">ChangeLog</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="tutorial/libxslttutorial.html">Tutorial</a>,
11          <a href="tutorial2/libxslt_pipes.html">Tutorial2</a></li><li><a href="xsltproc.html">Man page for xsltproc</a></li><li><a href="http://mail.gnome.org/archives/xslt/">Mail archive</a></li><li><a href="http://xmlsoft.org/">XML libxml2</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li><li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxslt">Bug Tracker</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading17">XSLT with PHP</a></li><li><a href="http://www.mod-xslt2.com/">Apache module</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://xsldbg.sourceforge.net/">Xsldbg Debugger</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="APIchunk0.html">Alphabetic</a></li><li><a href="APIconstructors.html">Constructors</a></li><li><a href="APIfunctions.html">Functions/Types</a></li><li><a href="APIfiles.html">Modules</a></li><li><a href="APIsymbols.html">Symbols</a></li></ul></td></tr></table></td></tr></table></td><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"><p>There is a number of language bindings and wrappers available for libxml2,
12the list below is not exhaustive. Please contact the <a href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>
13(<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) in
14order to get updates to this list or to discuss the specific topic of libxml2
15or libxslt wrappers or bindings:</p><ul><li><a href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">Matt
16    Sergeant</a> developped <a href="http://axkit.org/download/">XML::LibXML
17    and XML::LibXSLT</a>, Perl wrappers for libxml2/libxslt as part of the <a href="http://axkit.com/">AxKit XML application server</a></li>
18  <li><a href="mailto:dkuhlman@cutter.rexx.com">Dave Kuhlman</a> provides and
19    earlier version of the libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for Python</a></li>
20  <li>Petr Kozelka provides <a href="http://sourceforge.net/projects/libxml2-pas">Pascal units to glue
21    libxml2</a> with Kylix, Delphi and other Pascal compilers</li>
22  <li>Wai-Sun "Squidster" Chia provides <a href="http://www.rubycolor.org/arc/redist/">bindings for Ruby</a>  and
23    libxml2 bindings are also available in Ruby through the <a href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a> module
24    maintained by Tobias Peters.</li>
25  <li>Steve Ball and contributors maintains <a href="http://tclxml.sourceforge.net/">libxml2 and libxslt bindings for
26    Tcl</a></li>
27  <li><a href="mailto:xmlwrapp@pmade.org">Peter Jones</a> maintains C++
28    bindings for libxslt within <a href="http://pmade.org/pjones/software/xmlwrapp/">xmlwrapp</a></li>
29  <li><a href="phillim2@comcast.net">Mike Phillips</a> provides a module
30    using <a href="http://siasl.dyndns.org/projects/projects.html">libxslt
31    for PHP</a>.</li>
32  <li><a href="http://savannah.gnu.org/projects/classpathx/">LibxmlJ</a> is
33    an effort to create a 100% JAXP-compatible Java wrapper for libxml2 and
34    libxslt as part of GNU ClasspathX project.</li>
35  <li>Patrick McPhee provides Rexx bindings fof libxml2 and libxslt, look for
36    <a href="http://www.interlog.com/~ptjm/software.html">RexxXML</a>.</li>
37</ul><p>The libxslt Python module depends on the <a href="http://xmlsoft.org/python.html">libxml2 Python</a> module.</p><p>The distribution includes a set of Python bindings, which are garanteed to
38be maintained as part of the library in the future, though the Python
39interface have not yet reached the completeness of the C API.</p><p><a href="mailto:stephane.bidoul@softwareag.com">Stéphane Bidoul</a>
40maintains <a href="http://users.skynet.be/sbi/libxml-python/">a Windows port
41of the Python bindings</a>.</p><p>Note to people interested in building bindings, the API is formalized as
42<a href="libxslt-api.xml">an XML API description file</a> which allows to
43automate a large part of the Python bindings, this includes function
44descriptions, enums, structures, typedefs, etc... The Python script used to
45build the bindings is python/generator.py in the source distribution.</p><p>To install the Python bindings there are 2 options:</p><ul><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
46    RPM</a> and the <a href="http://rpmfind.net/linux/rpm2html/search.php?query=libxslt-python">libxslt-python
47    RPM</a>.</li>
48  <li>Otherwise use the <a href="ftp://xmlsoft.org/python/">libxml2-python
49    module distribution</a> corresponding to your installed version of
50    libxml2 and libxslt. Note that to install it you will need both libxml2
51    and libxslt installed and run "python setup.py build install" in the
52    module tree.</li>
53</ul><p>The distribution includes a set of examples and regression tests for the
54python bindings in the <code>python/tests</code> directory. Here are some
55excepts from those tests:</p><h3>basic.py:</h3><p>This is a basic test of XSLT interfaces: loading a stylesheet and a
56document, transforming the document and saving the result.</p><pre>import libxml2
57import libxslt
58
59styledoc = libxml2.parseFile("test.xsl")
60style = libxslt.parseStylesheetDoc(styledoc)
61doc = libxml2.parseFile("test.xml")
62result = style.applyStylesheet(doc, None)
63style.saveResultToFilename("foo", result, 0)
64style.freeStylesheet()
65doc.freeDoc()
66result.freeDoc()</pre><p>The Python module is called libxslt, you will also need the libxml2 module
67for the operations on XML trees. Let's have a look at the objects manipulated
68in that example and how is the processing done:</p><ul><li><code>styledoc</code> : is a libxml2 document tree. It is obtained by
69    parsing the XML file "test.xsl" containing the stylesheet.</li>
70  <li><code>style</code> : this is a precompiled stylesheet ready to be used
71    by the following transformations (note the plural form, multiple
72    transformations can resuse the same stylesheet).</li>
73  <li><code>doc</code> : this is the document to apply the transformation to.
74    In this case it is simply generated by parsing it from a file but any
75    other processing is possible as long as one get a libxml2 Doc. Note that
76    HTML tree are suitable for XSLT processing in libxslt. This is actually
77    how this page is generated !</li>
78  <li><code>result</code> : this is a document generated by applying the
79    stylesheet to the document. Note that some of the stylesheet informations
80    may be related to the serialization of that document and as in this
81    example a specific saveResultToFilename() method of the stylesheet should
82    be used to save it to a file (in that case to "foo").</li>
83</ul><p>Also note the need to explicitely deallocate documents with freeDoc()
84except for the stylesheet document which is freed when its compiled form is
85garbage collected.</p><h3>extfunc.py:</h3><p>This one is a far more complex test. It shows how to modify the behaviour
86of an XSLT transformation by passing parameters and how to extend the XSLT
87engine with functions defined in python:</p><pre>import libxml2
88import libxslt
89import string
90
91nodeName = None
92def f(ctx, str):
93    global nodeName
94
95    #
96    # Small check to verify the context is correcly accessed
97    #
98    try:
99        pctxt = libxslt.xpathParserContext(_obj=ctx)
100        ctxt = pctxt.context()
101        tctxt = ctxt.transformContext()
102        nodeName = tctxt.insertNode().name
103    except:
104        pass
105
106    return string.upper(str)
107
108libxslt.registerExtModuleFunction("foo", "http://example.com/foo", f)</pre><p>This code defines and register an extension function. Note that the
109function can be bound to any name (foo) and how the binding is also
110associated to a namespace name "http://example.com/foo". From an XSLT point
111of view the function just returns an upper case version of the string passed
112as a parameter. But the first part of the function also read some contextual
113information from the current XSLT processing environement, in that case it
114looks for the current insertion node in the resulting output (either the
115resulting document or the Result Value Tree being generated), and saves it to
116a global variable for checking that the access actually worked.</p><p>For more informations on the xpathParserContext and transformContext
117objects check the <a href="internals.html">libray internals description</a>.
118The pctxt is actually an object from a class derived from the
119libxml2.xpathParserContext() with just a couple more properties including the
120possibility to look up the XSLT transformation context from the XPath
121context.</p><pre>styledoc = libxml2.parseDoc("""
122&lt;xsl:stylesheet version='1.0'
123  xmlns:xsl='http://www.w3.org/1999/XSL/Transform'
124  xmlns:foo='http://example.com/foo'
125  xsl:exclude-result-prefixes='foo'&gt;
126
127  &lt;xsl:param name='bar'&gt;failure&lt;/xsl:param&gt;
128  &lt;xsl:template match='/'&gt;
129    &lt;article&gt;&lt;xsl:value-of select='foo:foo($bar)'/&gt;&lt;/article&gt;
130  &lt;/xsl:template&gt;
131&lt;/xsl:stylesheet&gt;
132""")</pre><p>Here is a simple example of how to read an XML document from a python
133string with libxml2. Note how this stylesheet:</p><ul><li>Uses a global parameter <code>bar</code></li>
134  <li>Reference the extension function f</li>
135  <li>how the Namespace name "http://example.com/foo" has to be bound to a
136    prefix</li>
137  <li>how that prefix is excluded from the output</li>
138  <li>how the function is called from the select</li>
139</ul><pre>style = libxslt.parseStylesheetDoc(styledoc)
140doc = libxml2.parseDoc("&lt;doc/&gt;")
141result = style.applyStylesheet(doc, { "bar": "'success'" })
142style.freeStylesheet()
143doc.freeDoc()</pre><p>that part is identical, to the basic example except that the
144transformation is passed a dictionnary of parameters. Note that the string
145passed "success" had to be quoted, otherwise it is interpreted as an XPath
146query for the childs of root named "success".</p><pre>root = result.children
147if root.name != "article":
148    print "Unexpected root node name"
149    sys.exit(1)
150if root.content != "SUCCESS":
151    print "Unexpected root node content, extension function failed"
152    sys.exit(1)
153if nodeName != 'article':
154    print "The function callback failed to access its context"
155    sys.exit(1)
156
157result.freeDoc()</pre><p>That part just verifies that the transformation worked, that the parameter
158got properly passed to the engine, that the function f() got called and that
159it properly accessed the context to find the name of the insertion node.</p><h3>pyxsltproc.py:</h3><p>this module is a bit too long to be described there but it is basically a
160rewrite of the xsltproc command line interface of libxslt in Python. It
161provides nearly all the functionalities of xsltproc and can be used as a base
162module to write Python customized XSLT processors. One of the thing to notice
163are:</p><pre>libxml2.lineNumbersDefault(1)
164libxml2.substituteEntitiesDefault(1)</pre><p>those two calls in the main() function are needed to force the libxml2
165processor to generate DOM trees compliant with the XPath data model.</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.