From 6dbcaf8686cec01223029997a2d22054a2507e55 Mon Sep 17 00:00:00 2001 From: Daniel Veillard Date: Wed, 20 Feb 2002 14:37:47 +0000 Subject: [PATCH] added a Python and binding page describing the current state of the Python * doc/xml.html doc/python.html doc/*: added a Python and binding page describing the current state of the Python bindings and giving pointers to the other languages wrappers. Daniel --- ChangeLog | 6 + doc/DOM.html | 1 + doc/FAQ.html | 1 + doc/XMLinfo.html | 1 + doc/XSLT.html | 3 +- doc/architecture.html | 1 + doc/bugs.html | 1 + doc/catalog.html | 1 + doc/contribs.html | 1 + doc/docs.html | 1 + doc/downloads.html | 1 + doc/encoding.html | 1 + doc/entities.html | 1 + doc/example.html | 1 + doc/help.html | 1 + doc/index.html | 1 + doc/interface.html | 1 + doc/intro.html | 1 + doc/library.html | 1 + doc/namespaces.html | 1 + doc/news.html | 1 + doc/python.html | 352 ++++++++++++++++++++++++++++++++++++++++++ doc/site.xsl | 3 + doc/threads.html | 1 + doc/tree.html | 1 + doc/upgrade.html | 1 + doc/xml.html | 300 ++++++++++++++++++++++++++++++++++- doc/xmldtd.html | 1 + doc/xmlio.html | 4 + doc/xmlmem.html | 1 + 30 files changed, 690 insertions(+), 2 deletions(-) create mode 100644 doc/python.html diff --git a/ChangeLog b/ChangeLog index 4ae096b5..7a8a5d8e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +Wed Feb 20 15:36:03 CET 2002 Daniel Veillard + + * doc/xml.html doc/python.html doc/*: added a Python and binding + page describing the current state of the Python bindings and + giving pointers to the other languages wrappers. + Wed Feb 20 11:16:15 CET 2002 Daniel Veillard * configure.in include/libxml/xmlwin32version.h: preparing 2.4.16 diff --git a/doc/DOM.html b/doc/DOM.html index 9b11243c..7c74dc0e 100644 --- a/doc/DOM.html +++ b/doc/DOM.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/FAQ.html b/doc/FAQ.html index 7d2c48af..3b3731b4 100644 --- a/doc/FAQ.html +++ b/doc/FAQ.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/XMLinfo.html b/doc/XMLinfo.html index 5cd14426..d3e03b6c 100644 --- a/doc/XMLinfo.html +++ b/doc/XMLinfo.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/XSLT.html b/doc/XSLT.html index abd3840d..9abdd65a 100644 --- a/doc/XSLT.html +++ b/doc/XSLT.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • @@ -91,7 +92,7 @@ HTML/textual output).

    A separate library called libxslt is being built on top of libxml2. This module "libxslt" can be found in the Gnome CVS base too.

    You can check the features -supported and the progresses on the Changelog +supported and the progresses on the Changelog

    Daniel Veillard

    diff --git a/doc/architecture.html b/doc/architecture.html index 43a057aa..f66fe480 100644 --- a/doc/architecture.html +++ b/doc/architecture.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/bugs.html b/doc/bugs.html index 13d53762..b4b79108 100644 --- a/doc/bugs.html +++ b/doc/bugs.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/catalog.html b/doc/catalog.html index c125e0cc..93389a1b 100644 --- a/doc/catalog.html +++ b/doc/catalog.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/contribs.html b/doc/contribs.html index 1669a61b..da48ad3f 100644 --- a/doc/contribs.html +++ b/doc/contribs.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/docs.html b/doc/docs.html index 5eec3c49..571ca47b 100644 --- a/doc/docs.html +++ b/doc/docs.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/downloads.html b/doc/downloads.html index bf7603e6..e8519c31 100644 --- a/doc/downloads.html +++ b/doc/downloads.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/encoding.html b/doc/encoding.html index 29495608..16e05d51 100644 --- a/doc/encoding.html +++ b/doc/encoding.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/entities.html b/doc/entities.html index 8c603a46..fb9c8068 100644 --- a/doc/entities.html +++ b/doc/entities.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/example.html b/doc/example.html index 4f28a8e0..6c27f97c 100644 --- a/doc/example.html +++ b/doc/example.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/help.html b/doc/help.html index 8b4870ce..303c4f16 100644 --- a/doc/help.html +++ b/doc/help.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/index.html b/doc/index.html index cfcb0043..f6579e06 100644 --- a/doc/index.html +++ b/doc/index.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/interface.html b/doc/interface.html index f31dbfdd..27cce3b0 100644 --- a/doc/interface.html +++ b/doc/interface.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/intro.html b/doc/intro.html index 22068b9c..f256d6d6 100644 --- a/doc/intro.html +++ b/doc/intro.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/library.html b/doc/library.html index e0a70c11..21de9ed3 100644 --- a/doc/library.html +++ b/doc/library.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/namespaces.html b/doc/namespaces.html index 0dc20696..409d1436 100644 --- a/doc/namespaces.html +++ b/doc/namespaces.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/news.html b/doc/news.html index d6692444..c2c2be33 100644 --- a/doc/news.html +++ b/doc/news.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/python.html b/doc/python.html new file mode 100644 index 00000000..ae01b303 --- /dev/null +++ b/doc/python.html @@ -0,0 +1,352 @@ + + + + + +Python and bindings + + + + + +
    +Gnome LogoW3C LogoRed Hat Logo +
    +

    The XML C library for Gnome

    +

    Python and bindings

    +
    +
    + + +
    + + + +
    Main Menu
    + + + +
    API Indexes
    + + + +
    Related links
    +
    +

    There is a number of language bindings and wrappers available for libxml2, +the list below is not exhaustive. Please contact the xml-bindings@gnome.org +(archives) in +order to get updates to this list or to discuss the specific topic of libxml2 +or libxslt wrappers or bindings:

    + +

    The distribution includes a set of Python bindings, which are garanteed to +be maintained as part of the library in the future, though the Python +interface have not yet reached the maturity of the C API. The distribution +includes a set of examples and regression tests for the python bindings in +the python/tests directory. Here are some excepts from those +tests:

    +

    tst.py:

    +

    This is a basic test of the file interface and DOM navigation:

    +
    import libxml2
+
+doc = libxml2.parseFile("tst.xml")
+if doc.name != "tst.xml":
+    print "doc.name failed"
+    sys.exit(1)
+root = doc.children
+if root.name != "doc":
+    print "root.name failed"
+    sys.exit(1)
+child = root.children
+if child.name != "foo":
+    print "child.name failed"
+    sys.exit(1)
+doc.freeDoc()
    +

    The Python module is called libxml2, parseFile is the equivalent of +xmlParseFile (most of the bindings are automatically generated, and the xml +prefix is removed and the casing convention are kept). All node seen at the +binding level share the same subset of accesors:

    +
      +
    • +name + : returns the node name
      • +
    • +type + : returns a string indicating the node type +
      • +
    • +content + : returns the content of the node, it is based on xmlNodeGetContent() and + hence is recursive.
      • +
    • +parent + , children, last, next, + prev, doc, properties: pointing to + the associated element in the tree, those may return None in case no such + link exists.
      • +
    +

    Also note the need to explicitely deallocate documents with freeDoc() . +Reference counting for libxml2 trees would need quite a lot of work to +function properly, and rather than risk memory leaks if not implemented +correctly it sounds safer to have an explicit function to free a tree. The +wrapper python objects like doc, root or child are them automatically garbage +collected.

    +

    validate.py:

    +

    This test check the validation interfaces and redirection of error +messages:

    +
    import libxml2
+
+#desactivate error messages from the validation
+def noerr(ctx, str):
+    pass
+
+libxml2.registerErrorHandler(noerr, None)
+
+ctxt = libxml2.createFileParserCtxt("invalid.xml")
+ctxt.validate(1)
+ctxt.parseDocument()
+doc = ctxt.doc()
+valid = ctxt.isValid()
+doc.freeDoc()
+if valid != 0:
+    print "validity chec failed"
    +

    The first thing to notice is the call to registerErrorHandler(), it +defines a new error handler global to the library. It is used to avoid seeing +the error messages when trying to validate the invalid document.

    +

    The main interest of that test is the creation of a parser context with +createFileParserCtxt() and how the behaviour can be changed before calling +parseDocument() . Similary the informations resulting from the parsing phase +are also available using context methods.

    +

    Contexts like nodes are defined as class and the libxml2 wrappers maps the +C function interfaces in terms of objects method as much as possible. The +best to get a complete view of what methods are supported is to look at the +libxml2.py module containing all the wrappers.

    +

    push.py:

    +

    This test show how to activate the push parser interface:

    +
    import libxml2
+
+ctxt = libxml2.createPushParser(None, "<foo", 4, "test.xml")
+ctxt.parseChunk("/>", 2, 1)
+doc = ctxt.doc()
+
+doc.freeDoc()
    +

    The context is created with a speciall call based on the +xmlCreatePushParser() from the C library. The first argument is an optional +SAX callback object, then the initial set of data, the lenght and the name of +the resource in case URI-References need to be computed by the parser.

    +

    Then the data are pushed using the parseChunk() method, the last call +setting the thrird argument terminate to 1.

    +

    pushSAX.py:

    +

    this test show the use of the event based parsing interfaces. In this case +the parser does not build a document, but provides callback information as +the parser makes progresses analyzing the data being provided:

    +
    import libxml2
+log = ""
+
+class callback:
+    def startDocument(self):
+        global log
+        log = log + "startDocument:"
+
+    def endDocument(self):
+        global log
+        log = log + "endDocument:"
+
+    def startElement(self, tag, attrs):
+        global log
+        log = log + "startElement %s %s:" % (tag, attrs)
+
+    def endElement(self, tag):
+        global log
+        log = log + "endElement %s:" % (tag)
+
+    def characters(self, data):
+        global log
+        log = log + "characters: %s:" % (data)
+
+    def warning(self, msg):
+        global log
+        log = log + "warning: %s:" % (msg)
+
+    def error(self, msg):
+        global log
+        log = log + "error: %s:" % (msg)
+
+    def fatalError(self, msg):
+        global log
+        log = log + "fatalError: %s:" % (msg)
+
+handler = callback()
+
+ctxt = libxml2.createPushParser(handler, "<foo", 4, "test.xml")
+chunk = " url='tst'>b"
+ctxt.parseChunk(chunk, len(chunk), 0)
+chunk = "ar</foo>"
+ctxt.parseChunk(chunk, len(chunk), 1)
+
+reference = "startDocument:startElement foo {'url': 'tst'}:characters: bar:endElement foo:endDocument:"
+if log != reference:
+    print "Error got: %s" % log
+    print "Exprected: %s" % reference
    +

    The key object in that test is the handler, it provides a number of entry +points which can be called by the parser as it makes progresses to indicate +the information set obtained. The full set of callback is larger than what +the callback class in that specific example implements (see the SAX +definition for a complete list). The wrapper will only call those supplied by +the object when activated. The startElement receives the names of the element +and a dictionnary containing the attributes carried by this element.

    +

    Also note that the reference string generated from the callback shows a +single character call even though the string "bar" is passed to the parser +from 2 different call to parseChunk()

    +

    xpath.py:

    +

    This is a basic test of XPath warppers support

    +
    import libxml2
+
+doc = libxml2.parseFile("tst.xml")
+ctxt = doc.xpathNewContext()
+res = ctxt.xpathEval("//*")
+if len(res) != 2:
+    print "xpath query: wrong node set size"
+    sys.exit(1)
+if res[0].name != "doc" or res[1].name != "foo":
+    print "xpath query: wrong node set value"
+    sys.exit(1)
+doc.freeDoc()
+ctxt.xpathFreeContext()
    +

    This test parses a file, then create an XPath context to evaluate XPath +expression on it. The xpathEval() method execute an XPath query and returns +the result mapped in a Python way. String and numbers are natively converted, +and node sets are returned as a tuple of libxml2 Python nodes wrappers. Like +the document, the XPath context need to be freed explicitely, also not that +the result of the XPath query may point back to the document tree and hence +the document must be freed after the result of the query is used.

    +

    xpathext.py:

    +

    This test shows how to extend the XPath engine with functions written in +python:

    +
    import libxml2
+
+def foo(ctx, x):
+    return x + 1
+
+doc = libxml2.parseFile("tst.xml")
+ctxt = doc.xpathNewContext()
+libxml2.registerXPathFunction(ctxt._o, "foo", None, foo)
+res = ctxt.xpathEval("foo(1)")
+if res != 2:
+    print "xpath extension failure"
+doc.freeDoc()
+ctxt.xpathFreeContext()
    +

    Note how the extension function is registered with the context (but that +part is not yet finalized, ths may change slightly in the future).

    +

    tstxpath.py:

    +

    This test is similar to the previousone but shows how the extension +function can access the XPath evaluation context:

    +
    def foo(ctx, x):
+    global called
+
+    #
+    # test that access to the XPath evaluation contexts
+    #
+    pctxt = libxml2.xpathParserContext(_obj=ctx)
+    ctxt = pctxt.context()
+    called = ctxt.function()
+    return x + 1
    +

    All the interfaces around the XPath parser(or rather evaluation) context +are not finalized, but it should be sufficient to do contextual work at the +evaluation point.

    +

    Memory debugging:

    +

    last but not least, all tests starts with the following prologue:

    +
    #memory debug specific
+libxml2.debugMemory(1)
+
    +

    and ends with the following epilogue:

    +
    #memory debug specific
+libxml2.cleanupParser()
+if libxml2.debugMemory(1) == 0:
+    print "OK"
+else:
+    print "Memory leak %d bytes" % (libxml2.debugMemory(1))
+    libxml2.dumpMemory()
    +

    Those activate the memory debugging interface of libxml2 where all +alloacted block in the library are tracked. The prologue then cleans up the +library state and checks that all allocated memory has been freed. If not it +calls dumpMemory() which saves that list in a .memdump file.

    +

    Daniel Veillard

    +
    + + diff --git a/doc/site.xsl b/doc/site.xsl index 07033703..24495c6f 100644 --- a/doc/site.xsl +++ b/doc/site.xsl @@ -92,6 +92,9 @@ FAQ.html + + python.html + unknown.html diff --git a/doc/threads.html b/doc/threads.html index 8022ef6a..6201c727 100644 --- a/doc/threads.html +++ b/doc/threads.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/tree.html b/doc/tree.html index aa05c758..e32f4735 100644 --- a/doc/tree.html +++ b/doc/tree.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/upgrade.html b/doc/upgrade.html index 070297f5..5965662d 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/xml.html b/doc/xml.html index ca0e27e7..8cf3f690 100644 --- a/doc/xml.html +++ b/doc/xml.html @@ -1302,7 +1302,302 @@ module "libxslt" can be found in the Gnome CVS base too.

    You can check the features supported and the progresses on the Changelog

    +href="http://cvs.gnome.org/lxr/source/libxslt/ChangeLog" +name="Changelog">Changelog

    + +

    Python and bindings

    + +

    There is a number of language bindings and wrappers available for libxml2, +the list below is not exhaustive. Please contact the xml-bindings@gnome.org +(archives) in +order to get updates to this list or to discuss the specific topic of libxml2 +or libxslt wrappers or bindings:

    + + +

    The distribution includes a set of Python bindings, which are garanteed to +be maintained as part of the library in the future, though the Python +interface have not yet reached the maturity of the C API. The distribution +includes a set of examples and regression tests for the python bindings in +the python/tests directory. Here are some excepts from those +tests:

    + +

    tst.py:

    + +

    This is a basic test of the file interface and DOM navigation:

    +
    import libxml2
+
+doc = libxml2.parseFile("tst.xml")
+if doc.name != "tst.xml":
+    print "doc.name failed"
+    sys.exit(1)
+root = doc.children
+if root.name != "doc":
+    print "root.name failed"
+    sys.exit(1)
+child = root.children
+if child.name != "foo":
+    print "child.name failed"
+    sys.exit(1)
+doc.freeDoc()
    + +

    The Python module is called libxml2, parseFile is the equivalent of +xmlParseFile (most of the bindings are automatically generated, and the xml +prefix is removed and the casing convention are kept). All node seen at the +binding level share the same subset of accesors:

    +
      +
    • name + : returns the node name
      • +
    • type + : returns a string indicating the node type
      • +
    • content + : returns the content of the node, it is based on xmlNodeGetContent() and + hence is recursive.
      • +
    • parent + , children, last, next, + prev, doc, properties: pointing to + the associated element in the tree, those may return None in case no such + link exists.
      • +
    + +

    Also note the need to explicitely deallocate documents with freeDoc() . +Reference counting for libxml2 trees would need quite a lot of work to +function properly, and rather than risk memory leaks if not implemented +correctly it sounds safer to have an explicit function to free a tree. The +wrapper python objects like doc, root or child are them automatically garbage +collected.

    + +

    validate.py:

    + +

    This test check the validation interfaces and redirection of error +messages:

    +
    import libxml2
+
+#desactivate error messages from the validation
+def noerr(ctx, str):
+    pass
+
+libxml2.registerErrorHandler(noerr, None)
+
+ctxt = libxml2.createFileParserCtxt("invalid.xml")
+ctxt.validate(1)
+ctxt.parseDocument()
+doc = ctxt.doc()
+valid = ctxt.isValid()
+doc.freeDoc()
+if valid != 0:
+    print "validity chec failed"
    + +

    The first thing to notice is the call to registerErrorHandler(), it +defines a new error handler global to the library. It is used to avoid seeing +the error messages when trying to validate the invalid document.

    + +

    The main interest of that test is the creation of a parser context with +createFileParserCtxt() and how the behaviour can be changed before calling +parseDocument() . Similary the informations resulting from the parsing phase +are also available using context methods.

    + +

    Contexts like nodes are defined as class and the libxml2 wrappers maps the +C function interfaces in terms of objects method as much as possible. The +best to get a complete view of what methods are supported is to look at the +libxml2.py module containing all the wrappers.

    + +

    push.py:

    + +

    This test show how to activate the push parser interface:

    +
    import libxml2
+
+ctxt = libxml2.createPushParser(None, "<foo", 4, "test.xml")
+ctxt.parseChunk("/>", 2, 1)
+doc = ctxt.doc()
+
+doc.freeDoc()
    + +

    The context is created with a speciall call based on the +xmlCreatePushParser() from the C library. The first argument is an optional +SAX callback object, then the initial set of data, the lenght and the name of +the resource in case URI-References need to be computed by the parser.

    + +

    Then the data are pushed using the parseChunk() method, the last call +setting the thrird argument terminate to 1.

    + +

    pushSAX.py:

    + +

    this test show the use of the event based parsing interfaces. In this case +the parser does not build a document, but provides callback information as +the parser makes progresses analyzing the data being provided:

    +
    import libxml2
+log = ""
+
+class callback:
+    def startDocument(self):
+        global log
+        log = log + "startDocument:"
+
+    def endDocument(self):
+        global log
+        log = log + "endDocument:"
+
+    def startElement(self, tag, attrs):
+        global log
+        log = log + "startElement %s %s:" % (tag, attrs)
+
+    def endElement(self, tag):
+        global log
+        log = log + "endElement %s:" % (tag)
+
+    def characters(self, data):
+        global log
+        log = log + "characters: %s:" % (data)
+
+    def warning(self, msg):
+        global log
+        log = log + "warning: %s:" % (msg)
+
+    def error(self, msg):
+        global log
+        log = log + "error: %s:" % (msg)
+
+    def fatalError(self, msg):
+        global log
+        log = log + "fatalError: %s:" % (msg)
+
+handler = callback()
+
+ctxt = libxml2.createPushParser(handler, "<foo", 4, "test.xml")
+chunk = " url='tst'>b"
+ctxt.parseChunk(chunk, len(chunk), 0)
+chunk = "ar</foo>"
+ctxt.parseChunk(chunk, len(chunk), 1)
+
+reference = "startDocument:startElement foo {'url': 'tst'}:characters: bar:endElement foo:endDocument:"
+if log != reference:
+    print "Error got: %s" % log
+    print "Exprected: %s" % reference
    + +

    The key object in that test is the handler, it provides a number of entry +points which can be called by the parser as it makes progresses to indicate +the information set obtained. The full set of callback is larger than what +the callback class in that specific example implements (see the SAX +definition for a complete list). The wrapper will only call those supplied by +the object when activated. The startElement receives the names of the element +and a dictionnary containing the attributes carried by this element.

    + +

    Also note that the reference string generated from the callback shows a +single character call even though the string "bar" is passed to the parser +from 2 different call to parseChunk()

    + +

    xpath.py:

    + +

    This is a basic test of XPath warppers support

    +
    import libxml2
+
+doc = libxml2.parseFile("tst.xml")
+ctxt = doc.xpathNewContext()
+res = ctxt.xpathEval("//*")
+if len(res) != 2:
+    print "xpath query: wrong node set size"
+    sys.exit(1)
+if res[0].name != "doc" or res[1].name != "foo":
+    print "xpath query: wrong node set value"
+    sys.exit(1)
+doc.freeDoc()
+ctxt.xpathFreeContext()
    + +

    This test parses a file, then create an XPath context to evaluate XPath +expression on it. The xpathEval() method execute an XPath query and returns +the result mapped in a Python way. String and numbers are natively converted, +and node sets are returned as a tuple of libxml2 Python nodes wrappers. Like +the document, the XPath context need to be freed explicitely, also not that +the result of the XPath query may point back to the document tree and hence +the document must be freed after the result of the query is used.

    + +

    xpathext.py:

    + +

    This test shows how to extend the XPath engine with functions written in +python:

    +
    import libxml2
+
+def foo(ctx, x):
+    return x + 1
+
+doc = libxml2.parseFile("tst.xml")
+ctxt = doc.xpathNewContext()
+libxml2.registerXPathFunction(ctxt._o, "foo", None, foo)
+res = ctxt.xpathEval("foo(1)")
+if res != 2:
+    print "xpath extension failure"
+doc.freeDoc()
+ctxt.xpathFreeContext()
    + +

    Note how the extension function is registered with the context (but that +part is not yet finalized, ths may change slightly in the future).

    + +

    tstxpath.py:

    + +

    This test is similar to the previousone but shows how the extension +function can access the XPath evaluation context:

    +
    def foo(ctx, x):
+    global called
+
+    #
+    # test that access to the XPath evaluation contexts
+    #
+    pctxt = libxml2.xpathParserContext(_obj=ctx)
+    ctxt = pctxt.context()
+    called = ctxt.function()
+    return x + 1
    + +

    All the interfaces around the XPath parser(or rather evaluation) context +are not finalized, but it should be sufficient to do contextual work at the +evaluation point.

    + +

    Memory debugging:

    + +

    last but not least, all tests starts with the following prologue:

    +
    #memory debug specific
+libxml2.debugMemory(1)
+
    + +

    and ends with the following epilogue:

    +
    #memory debug specific
+libxml2.cleanupParser()
+if libxml2.debugMemory(1) == 0:
+    print "OK"
+else:
+    print "Memory leak %d bytes" % (libxml2.debugMemory(1))
+    libxml2.dumpMemory()
    + +

    Those activate the memory debugging interface of libxml2 where all +alloacted block in the library are tracked. The prologue then cleans up the +library state and checks that all allocated memory has been freed. If not it +calls dumpMemory() which saves that list in a .memdump file.

    libxml architecture

    @@ -2228,6 +2523,9 @@ xmlOutputBufferCreateOwn(FILE *file, xmlCharEncodingHandlerPtr encoder) { + + + diff --git a/doc/xmldtd.html b/doc/xmldtd.html index 8c1b7f17..fde7953c 100644 --- a/doc/xmldtd.html +++ b/doc/xmldtd.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • diff --git a/doc/xmlio.html b/doc/xmlio.html index 8b7fb25e..43cfbad5 100644 --- a/doc/xmlio.html +++ b/doc/xmlio.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface
    • @@ -238,6 +239,9 @@ xmlOutputBufferCreateOwn(FILE *file, xmlCharEncodingHandlerPtr encoder) { + + + diff --git a/doc/xmlmem.html b/doc/xmlmem.html index 4441709b..fd4c050b 100644 --- a/doc/xmlmem.html +++ b/doc/xmlmem.html @@ -37,6 +37,7 @@ A:link, A:visited, A:active { text-decoration: underline }
  • News
  • XML
  • XSLT
    • +
  • Python and bindings
  • libxml architecture
  • The tree output
  • The SAX interface