Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libxml2 / fabafd54c7d7aed4f68be56d196b2f965eab7a9d / . / doc / python.html
blob: adb3d36d96f51a99cd2378087035287bc71635b8 [file] [log] [blame]
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]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" /><link rel="SHORTCUT ICON" href="/favicon.ico" /><style type="text/css">
Daniel Veillard373a4752002-02-21 14:46:29 +0000[diff] [blame]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}
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]9A:link, A:visited, A:active { text-decoration: underline }
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]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/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 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 XML C parser and toolkit of 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>Developer 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" style="font-weight:bold">Main Menu</a></li><li><a href="html/index.html" style="font-weight:bold">Reference Manual</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="tutorial/index.html">Tutorial</a></li><li><a href="xmlreader.html">The Reader Interface</a></li><li><a href="ChangeLog.html">ChangeLog</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="python.html">Python and bindings</a></li><li><a href="architecture.html">libxml2 architecture</a></li><li><a href="tree.html">The tree output</a></li><li><a href="interface.html">The SAX interface</a></li><li><a href="xmlmem.html">Memory Management</a></li><li><a href="xmlio.html">I/O Interfaces</a></li><li><a href="library.html">The parser interfaces</a></li><li><a href="entities.html">Entities or no entities</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="upgrade.html">Upgrading 1.x code</a></li><li><a href="threads.html">Thread safety</a></li><li><a href="DOM.html">DOM Principles</a></li><li><a href="example.html">A real example</a></li><li><a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</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><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="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</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://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</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 are a number of language bindings and wrappers available
11forlibxml2,the list below is not exhaustive. Please contact the <a href="http://mail.gnome.org/mailman/listinfo/xml-bindings">xml-bindings@gnome.org</a>(<a href="http://mail.gnome.org/archives/xml-bindings/">archives</a>) inorder
12toget updates to this list or to discuss the specific topic of
13libxml2orlibxslt wrappers or bindings:</p><ul><li><a href="http://libxmlplusplus.sourceforge.net/">Libxml++</a>seemsthemost
14 up-to-date C++ bindings for libxml2, check the <a href="http://libxmlplusplus.sourceforge.net/reference/html/hierarchy.html">documentation</a>andthe
15 <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/libxmlplusplus/libxml%2b%2b/examples/">examples</a>.</li>
16 <li>There is another <a href="http://libgdome-cpp.berlios.de/">C++wrapperbased on the gdome2
17 bindings</a>maintained by Tobias Peters.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]18 <li>and a third C++ wrapper by Peter Jones &lt;pjones@pmade.org&gt;
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]19 <p>Website: <a href="http://pmade.org/pjones/software/xmlwrapp/">http://pmade.org/pjones/software/xmlwrapp/</a></p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]20 </li>
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]21 <li><a href="http://mail.gnome.org/archives/xml/2001-March/msg00014.html">MattSergeant</a>developed<a href="http://axkit.org/download/">XML::LibXSLT</a>, a Perl
22 wrapperforlibxml2/libxslt as part of the <a href="http://axkit.com/">AxKitXMLapplication server</a>.</li>
23 <li>If you're interested into scripting XML processing, have a look at <a href="http://xsh.sourceforge.net/">XSH</a>an XML editing shell
24 basedonLibxml2 Perl bindings.</li>
25 <li><a href="mailto:dkuhlman@cutter.rexx.com">Dave
26 Kuhlman</a>providesanearlier version of the libxml/libxslt <a href="http://www.rexx.com/~dkuhlman">wrappers for Python</a>.</li>
27 <li>Gopal.V and Peter Minten develop <a href="http://savannah.gnu.org/projects/libxmlsharp">libxml#</a>, a
28 setofC# libxml2 bindings.</li>
29 <li>Petr Kozelka provides <a href="http://sourceforge.net/projects/libxml2-pas">Pascal units
30 togluelibxml2</a>with Kylix, Delphi and other Pascal compilers.</li>
31 <li>Uwe Fechner also provides <a href="http://sourceforge.net/projects/idom2-pas/">idom2</a>,
32 aDOM2implementation for Kylix2/D5/D6 from Borland.</li>
33 <li>There is <a href="http://libxml.rubyforge.org/">bindings forRuby</a>and
34 libxml2 bindings are also available in Ruby through the <a href="http://libgdome-ruby.berlios.de/">libgdome-ruby</a>modulemaintainedby
35 Tobias Peters.</li>
36 <li>Steve Ball and contributors maintains <a href="http://tclxml.sourceforge.net/">libxml2 and libxslt
37 bindingsforTcl</a>.</li>
Daniel Veillard142fb212005-04-07 12:48:10 +0000[diff] [blame]38 <li>libxml2 and libxslt is the default XML library for PHP5.</li>
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]39 <li><a href="http://savannah.gnu.org/projects/classpathx/">LibxmlJ</a>isaneffort
40 to create a 100% JAXP-compatible Java wrapper for libxml2andlibxslt as
41 part of GNU ClasspathX project.</li>
42 <li>Patrick McPhee provides Rexx bindings fof libxml2 and libxslt,
43 lookfor<a href="http://www.interlog.com/~ptjm/software.html">RexxXML</a>.</li>
44 <li><a href="http://www.satimage.fr/software/en/xml_suite.html">Satimage</a>provides<a href="http://www.satimage.fr/software/en/downloads_osaxen.html">XMLLibosax</a>.This
45 is an osax for Mac OS X with a set of commands toimplement inAppleScript
46 the XML DOM, XPATH and XSLT. Also includescommands forProperty-lists
47 (Apple's fast lookup table XML format.)</li>
48 <li>Francesco Montorsi developped <a href="https://sourceforge.net/project/showfiles.php?group_id=51305&amp;package_id=45182">wxXml2</a>wrappersthat
49 interface libxml2, allowing wxWidgets applications toload/save/editXML
50 instances.</li>
51</ul><p>The distribution includes a set of Python bindings, which are
52guaranteedtobe maintained as part of the library in the future, though
53thePythoninterface have not yet reached the completeness of the C API.</p><p>Note that some of the Python purist dislike the default set
54ofPythonbindings, rather than complaining I suggest they have a look at <a href="http://codespeak.net/lxml/">lxml the more pythonic bindings
55forlibxml2and libxslt</a>and <a href="http://codespeak.net/mailman/listinfo/lxml-dev">helpMartijnFaassen</a>complete
56those.</p><p><a href="mailto:stephane.bidoul@softwareag.com">StéphaneBidoul</a>maintains <a href="http://users.skynet.be/sbi/libxml-python/">aWindows portof the Python
57bindings</a>.</p><p>Note to people interested in building bindings, the API is formalized as<a href="libxml2-api.xml">an XML API description file</a>which allows
58toautomatea large part of the Python bindings, this includes
59functiondescriptions,enums, structures, typedefs, etc... The Python script
60used tobuild thebindings is python/generator.py in the source
61distribution.</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-pythonRPM</a>(andif
62 needed the <a href="http://rpmfind.net/linux/rpm2html/search.php?query=libxslt-python">libxslt-pythonRPM</a>).</li>
63 <li>Otherwise use the <a href="ftp://xmlsoft.org/libxml2/python/">libxml2-pythonmoduledistribution</a>corresponding
64 to your installed version oflibxml2 andlibxslt. Note that to install it
65 you will need both libxml2and libxsltinstalled and run "python setup.py
66 build install" in themodule tree.</li>
67</ul><p>The distribution includes a set of examples and regression tests
68forthepython bindings in the <code>python/tests</code>directory. Here
69aresomeexcerpts from those tests:</p><h3>tst.py:</h3><p>This is a basic test of the file interface and DOM navigation:</p><pre>import libxml2, sys
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]70
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]71doc = libxml2.parseFile("tst.xml")
72if doc.name != "tst.xml":
73 print "doc.name failed"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]74 sys.exit(1)
75root = doc.children
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]76if root.name != "doc":
77 print "root.name failed"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]78 sys.exit(1)
79child = root.children
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]80if child.name != "foo":
81 print "child.name failed"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]82 sys.exit(1)
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]83doc.freeDoc()</pre><p>The Python module is called libxml2; parseFile is the
84equivalentofxmlParseFile (most of the bindings are automatically generated,
85and thexmlprefix is removed and the casing convention are kept). All node
86seen atthebinding level share the same subset of accessors:</p><ul><li><code>name</code>: returns the node name</li>
Daniel Veillard69839ba2006-06-06 13:27:03 +0000[diff] [blame]87 <li><code>type</code>: returns a string indicating the node type</li>
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]88 <li><code>content</code>: returns the content of the node, it is
89 basedonxmlNodeGetContent() and hence is recursive.</li>
90 <li><code>parent</code>,
91 <code>children</code>,<code>last</code>,<code>next</code>,
92 <code>prev</code>,<code>doc</code>,<code>properties</code>: pointing to
93 the associatedelement in the tree,those may return None in case no such
94 linkexists.</li>
95</ul><p>Also note the need to explicitly deallocate documents with
96freeDoc().Reference counting for libxml2 trees would need quite a lot of
97worktofunction properly, and rather than risk memory leaks if
98notimplementedcorrectly it sounds safer to have an explicit function to free
99atree. Thewrapper python objects like doc, root or child are
100themautomatically garbagecollected.</p><h3>validate.py:</h3><p>This test check the validation interfaces and redirection
101oferrormessages:</p><pre>import libxml2
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]102
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]103#deactivate error messages from the validation
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]104def noerr(ctx, str):
105 pass
106
107libxml2.registerErrorHandler(noerr, None)
108
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]109ctxt = libxml2.createFileParserCtxt("invalid.xml")
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]110ctxt.validate(1)
111ctxt.parseDocument()
112doc = ctxt.doc()
113valid = ctxt.isValid()
114doc.freeDoc()
115if valid != 0:
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]116 print "validity check failed"</pre><p>The first thing to notice is the call to registerErrorHandler(),
117itdefinesa new error handler global to the library. It is used to avoid
118seeingtheerror messages when trying to validate the invalid document.</p><p>The main interest of that test is the creation of a parser
119contextwithcreateFileParserCtxt() and how the behaviour can be changed
120beforecallingparseDocument() . Similarly the informations resulting from
121theparsing phaseare also available using context methods.</p><p>Contexts like nodes are defined as class and the libxml2 wrappers mapstheC
122function interfaces in terms of objects method as much as possible.Thebest to
123get a complete view of what methods are supported is to look atthelibxml2.py
124module containing all the wrappers.</p><h3>push.py:</h3><p>This test show how to activate the push parser interface:</p><pre>import libxml2
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]125
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]126ctxt = libxml2.createPushParser(None, "&lt;foo", 4, "test.xml")
127ctxt.parseChunk("/&gt;", 2, 1)
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]128doc = ctxt.doc()
129
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]130doc.freeDoc()</pre><p>The context is created with a special call based
131onthexmlCreatePushParser() from the C library. The first argument is
132anoptionalSAX callback object, then the initial set of data, the length and
133thename ofthe resource in case URI-References need to be computed by
134theparser.</p><p>Then the data are pushed using the parseChunk() method, the
135lastcallsetting the third argument terminate to 1.</p><h3>pushSAX.py:</h3><p>this test show the use of the event based parsing interfaces. In
136thiscasethe parser does not build a document, but provides callback
137informationasthe parser makes progresses analyzing the data being
138provided:</p><pre>import libxml2
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]139log = ""
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]140
141class callback:
142 def startDocument(self):
143 global log
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]144 log = log + "startDocument:"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]145
146 def endDocument(self):
147 global log
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]148 log = log + "endDocument:"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]149
150 def startElement(self, tag, attrs):
151 global log
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]152 log = log + "startElement %s %s:" % (tag, attrs)
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]153
154 def endElement(self, tag):
155 global log
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]156 log = log + "endElement %s:" % (tag)
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]157
158 def characters(self, data):
159 global log
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]160 log = log + "characters: %s:" % (data)
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]161
162 def warning(self, msg):
163 global log
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]164 log = log + "warning: %s:" % (msg)
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]165
166 def error(self, msg):
167 global log
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]168 log = log + "error: %s:" % (msg)
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]169
170 def fatalError(self, msg):
171 global log
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]172 log = log + "fatalError: %s:" % (msg)
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]173
174handler = callback()
175
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]176ctxt = libxml2.createPushParser(handler, "&lt;foo", 4, "test.xml")
177chunk = " url='tst'&gt;b"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]178ctxt.parseChunk(chunk, len(chunk), 0)
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]179chunk = "ar&lt;/foo&gt;"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]180ctxt.parseChunk(chunk, len(chunk), 1)
181
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]182reference = "startDocument:startElement foo {'url': 'tst'}:" + \
183 "characters: bar:endElement foo:endDocument:"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]184if log != reference:
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]185 print "Error got: %s" % log
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]186 print "Expected: %s" % reference</pre><p>The key object in that test is the handler, it provides a number
187ofentrypoints which can be called by the parser as it makes progresses
188toindicatethe information set obtained. The full set of callback is larger
189thanwhatthe callback class in that specific example implements (see
190theSAXdefinition for a complete list). The wrapper will only call those
191suppliedbythe object when activated. The startElement receives the names of
192theelementand a dictionary containing the attributes carried by this
193element.</p><p>Also note that the reference string generated from the callback
194showsasingle character call even though the string "bar" is passed to
195theparserfrom 2 different call to parseChunk()</p><h3>xpath.py:</h3><p>This is a basic test of XPath wrappers support</p><pre>import libxml2
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]196
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]197doc = libxml2.parseFile("tst.xml")
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]198ctxt = doc.xpathNewContext()
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]199res = ctxt.xpathEval("//*")
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]200if len(res) != 2:
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]201 print "xpath query: wrong node set size"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]202 sys.exit(1)
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]203if res[0].name != "doc" or res[1].name != "foo":
204 print "xpath query: wrong node set value"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]205 sys.exit(1)
206doc.freeDoc()
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]207ctxt.xpathFreeContext()</pre><p>This test parses a file, then create an XPath context to
208evaluateXPathexpression on it. The xpathEval() method execute an XPath query
209andreturnsthe result mapped in a Python way. String and numbers are
210nativelyconverted,and node sets are returned as a tuple of libxml2 Python
211nodeswrappers. Likethe document, the XPath context need to be freed
212explicitly,also not thatthe result of the XPath query may point back to the
213documenttree and hencethe document must be freed after the result of the
214query isused.</p><h3>xpathext.py:</h3><p>This test shows how to extend the XPath engine with functions
215writteninpython:</p><pre>import libxml2
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]216
217def foo(ctx, x):
218 return x + 1
219
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]220doc = libxml2.parseFile("tst.xml")
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]221ctxt = doc.xpathNewContext()
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]222libxml2.registerXPathFunction(ctxt._o, "foo", None, foo)
223res = ctxt.xpathEval("foo(1)")
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]224if res != 2:
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]225 print "xpath extension failure"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]226doc.freeDoc()
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]227ctxt.xpathFreeContext()</pre><p>Note how the extension function is registered with the context
228(butthatpart is not yet finalized, this may change slightly in the
229future).</p><h3>tstxpath.py:</h3><p>This test is similar to the previous one but shows how
230theextensionfunction can access the XPath evaluation context:</p><pre>def foo(ctx, x):
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]231 global called
232
233 #
234 # test that access to the XPath evaluation contexts
235 #
236 pctxt = libxml2.xpathParserContext(_obj=ctx)
237 ctxt = pctxt.context()
238 called = ctxt.function()
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]239 return x + 1</pre><p>All the interfaces around the XPath parser(or rather evaluation)contextare
240not finalized, but it should be sufficient to do contextual workat
241theevaluation point.</p><h3>Memory debugging:</h3><p>last but not least, all tests starts with the following prologue:</p><pre>#memory debug specific
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]242libxml2.debugMemory(1)</pre><p>and ends with the following epilogue:</p><pre>#memory debug specific
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]243libxml2.cleanupParser()
244if libxml2.debugMemory(1) == 0:
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]245 print "OK"
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]246else:
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]247 print "Memory leak %d bytes" % (libxml2.debugMemory(1))
Daniel Veillardfabafd52006-06-08 08:16:33 +0000[diff] [blame^]248 libxml2.dumpMemory()</pre><p>Those activate the memory debugging interface of libxml2 whereallallocated
249block in the library are tracked. The prologue then cleans upthelibrary state
250and checks that all allocated memory has been freed. If notitcalls
251dumpMemory() which saves that list in a <code>.memdump</code>file.</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>