[Lxml-checkins] r43318 - in lxml/trunk: doc src/lxml

[scoder at codespeak.net]

Author: scoder
Date: Sun May 13 20:42:04 2007
New Revision: 43318

Modified:
   lxml/trunk/doc/xpathxslt.txt
   lxml/trunk/src/lxml/extensions.pxi
   lxml/trunk/src/lxml/xpath.pxi
Log:
always raise eval exception from XPath evaluators

Modified: lxml/trunk/doc/xpathxslt.txt
==============================================================================
--- lxml/trunk/doc/xpathxslt.txt	(original)
+++ lxml/trunk/doc/xpathxslt.txt	Sun May 13 20:42:04 2007
@@ -14,6 +14,7 @@
      1.4  The ``XPath`` class
      1.5  The ``XPathEvaluator`` classes
      1.6  ``ETXPath``
+     1.7  Error handling
    2  XSLT
      2.1  XSLT result objects
      2.2  Stylesheet parameters
@@ -265,6 +266,58 @@
   {ns}b
 
 
+Error handling
+--------------
+
+lxml.etree raises exceptions when errors occur while parsing or evaluating an
+XPath expression::
+
+  >>> find = etree.XPath("\\")
+  Traceback (most recent call last):
+    ...
+  XPathSyntaxError: Error in xpath expression
+
+lxml will also try to give you a hint what went wrong, so if you pass a more
+complex expression, you may get a somewhat more specific error::
+
+  >>> find = etree.XPath("//*[1.1.1]")
+  Traceback (most recent call last):
+    ...
+  XPathSyntaxError: Invalid predicate
+
+During evaluation, lxml will emit an XPathEvalError on errors::
+
+  >>> find = etree.XPath("//ns:a")
+  >>> find(root)
+  Traceback (most recent call last):
+    ...
+  XPathEvalError: Undefined namespace prefix
+
+This works for the ``XPath`` class, however, the other evaluators (including
+the ``xpath()`` method) are one-shot operations that do parsing and evaluation
+in one step.  They therefore raise evaluation exceptions in all cases::
+
+  >>> root = etree.Element("test")
+  >>> find = root.xpath("//*[1.1.1]")
+  Traceback (most recent call last):
+    ...
+  XPathEvalError: Invalid predicate
+
+  >>> find = root.xpath("//ns:a")
+  Traceback (most recent call last):
+    ...
+  XPathEvalError: Undefined namespace prefix
+
+  >>> find = root.xpath("\\")
+  Traceback (most recent call last):
+    ...
+  XPathEvalError: Error in xpath evaluation
+
+Note that lxml versions before 1.3 always raised an ``XPathSyntaxError`` for
+all errors, including evaluation errors.  The best way to support older
+versions is to except on the superclass ``XPathError``.
+
+
 XSLT
 ====
 

Modified: lxml/trunk/src/lxml/extensions.pxi
==============================================================================
--- lxml/trunk/src/lxml/extensions.pxi	(original)
+++ lxml/trunk/src/lxml/extensions.pxi	Sun May 13 20:42:04 2007
@@ -3,10 +3,13 @@
 class XPathError(LxmlError):
     pass
 
-class XPathFunctionError(XPathError):
+class XPathEvalError(XPathError):
     pass
 
-class XPathResultError(XPathError):
+class XPathFunctionError(XPathEvalError):
+    pass
+
+class XPathResultError(XPathEvalError):
     pass
 
 # forward declarations

Modified: lxml/trunk/src/lxml/xpath.pxi
==============================================================================
--- lxml/trunk/src/lxml/xpath.pxi	(original)
+++ lxml/trunk/src/lxml/xpath.pxi	Sun May 13 20:42:04 2007
@@ -3,9 +3,6 @@
 class XPathSyntaxError(LxmlSyntaxError, XPathError):
     pass
 
-class XPathEvalError(XPathError):
-    pass
-
 ################################################################################
 # XPath
 
@@ -165,7 +162,7 @@
                self._xpathCtxt.lastError.message is not NULL:
             message = funicode(self._xpathCtxt.lastError.message)
         else:
-            message = "error in xpath expression"
+            message = "Error in xpath expression"
         raise XPathSyntaxError, message
 
     cdef _raise_eval_error(self):
@@ -178,12 +175,12 @@
         if entries:
             entry = entries[0]
             if entry is not None and entry.message:
-                raise XPathSyntaxError, entry.message
+                raise XPathEvalError, entry.message
         if self._xpathCtxt is not NULL and \
                self._xpathCtxt.lastError.message is not NULL:
             message = funicode(self._xpathCtxt.lastError.message)
         else:
-            message = "error in xpath evaluation"
+            message = "Error in xpath evaluation"
         raise XPathEvalError, message
 
     cdef object _handle_result(self, xpath.xmlXPathObject* xpathObj, _Document doc):