python: provide more exception classes

[notmuch] / bindings / python / notmuch / globals.py

diff --git a/bindings/python/notmuch/globals.py b/bindings/python/notmuch/globals.py
index c675d04406a9f38377e7fa508a1c579170f0b9fa..5fca3d9bd7fc1bc4c02e5b8ef2bc2d26dee04822 100644 (file)
--- a/bindings/python/notmuch/globals.py
+++ b/bindings/python/notmuch/globals.py
@@ -27,14 +27,14 @@ try:
 except:
     raise ImportError("Could not find shared 'notmuch' library.")
 
-#-----------------------------------------------------------------------------
+
 class Enum(object):
     """Provides ENUMS as "code=Enum(['a','b','c'])" where code.a=0 etc..."""
     def __init__(self, names):
         for number, name in enumerate(names):
             setattr(self, name, number)
 
-#-----------------------------------------------------------------------------
+
 class Status(Enum):
     """Enum with a string representation of a notmuch_status_t value."""
     _status2str = nmlib.notmuch_status_to_string
@@ -49,10 +49,10 @@ class Status(Enum):
 
     @classmethod
     def status2str(self, status):
-        """Get a string representation of a notmuch_status_t value."""   
+        """Get a string representation of a notmuch_status_t value."""
         # define strings for custom error messages
         if status == STATUS.NOT_INITIALIZED:
-          return "Operation on uninitialized object impossible."
+            return "Operation on uninitialized object impossible."
         return str(Status._status2str(status))
 
 STATUS = Status(['SUCCESS',
@@ -65,8 +65,12 @@ STATUS = Status(['SUCCESS',
   'NULL_POINTER',
   'TAG_TOO_LONG',
   'UNBALANCED_FREEZE_THAW',
+  'UNBALANCED_ATOMIC',
   'NOT_INITIALIZED'])
-"""STATUS is a class, whose attributes provide constants that serve as return indicators for notmuch functions. Currently the following ones are defined. For possible return values and specific meaning for each method, see the method description.
+"""STATUS is a class, whose attributes provide constants that serve as return
+indicators for notmuch functions. Currently the following ones are defined. For
+possible return values and specific meaning for each method, see the method
+description.
 
   * SUCCESS
   * OUT_OF_MEMORY
@@ -78,17 +82,84 @@ STATUS = Status(['SUCCESS',
   * NULL_POINTER
   * TAG_TOO_LONG
   * UNBALANCED_FREEZE_THAW
+  * UNBALANCED_ATOMIC
   * NOT_INITIALIZED
 
-  Invoke the class method `notmuch.STATUS.status2str` with a status value as argument to receive a human readable string"""
-STATUS.__name__ = 'STATUS' 
+Invoke the class method `notmuch.STATUS.status2str` with a status value as
+argument to receive a human readable string"""
+STATUS.__name__ = 'STATUS'
 
 class NotmuchError(Exception):
-    def __init__(self, status=None, message=None):
-        """Is initiated with a (notmuch.STATUS[,message=None])"""
-        super(NotmuchError, self).__init__(message, status)
+    """Is initiated with a (notmuch.STATUS[, message=None]). It will not
+    return an instance of the class NotmuchError, but a derived instance
+    of a more specific Error Message, e.g. OutOfMemoryError. Each status
+    but SUCCESS has a corresponding subclassed Exception."""
+
+    @classmethod
+    def get_subclass_exc(cls, status, message=None):
+        """Returns a fine grained Exception() type,detailing the error status"""
+        subclasses = {
+            STATUS.OUT_OF_MEMORY: OutOfMemoryError,
+            STATUS.READ_ONLY_DATABASE: ReadOnlyDatabaseError,
+            STATUS.XAPIAN_EXCEPTION: XapianError,
+            STATUS.FILE_ERROR: FileError,
+            STATUS.FILE_NOT_EMAIL: FileNotEmailError,
+            STATUS.DUPLICATE_MESSAGE_ID: DuplicateMessageIdError,
+            STATUS.NULL_POINTER: NullPointerError,
+            STATUS.TAG_TOO_LONG: TagTooLongError,
+            STATUS.UNBALANCED_FREEZE_THAW: UnbalancedFreezeThawError,
+            STATUS.UNBALANCED_ATOMIC: UnbalancedAtomicError,
+            STATUS.NOT_INITIALIZED: NotInitializedError
+        }
+        assert 0 < status <= len(subclasses)
+        return subclasses[status](status, message)
+
+    def __init__(self, status, message=None):
+        self.status = status
+        self.message = message
 
     def __str__(self):
-        if self.args[0] is not None: return self.args[0]
-        else: return STATUS.status2str(self.args[1])
+        if self.message is not None:
+            return self.message
+        elif self.status is not None:
+            return STATUS.status2str(self.status)
+        else:
+            return 'Unknown error'
+
+# List of Subclassed exceptions that correspond to STATUS values and are
+# subclasses of NotmuchError:
+class OutOfMemoryError(NotmuchError):
+    pass
+class ReadOnlyDatabaseError(NotmuchError):
+    pass
+class XapianError(NotmuchError):
+    pass
+class FileError(NotmuchError):
+    pass
+class FileNotEmailError(NotmuchError):
+    pass
+class DuplicateMessageIdError(NotmuchError):
+    pass
+class NullPointerError(NotmuchError):
+    pass
+class TagTooLongError(NotmuchError):
+    pass
+class UnbalancedFreezeThawError(NotmuchError):
+    pass
+class UnbalancedAtomicError(NotmuchError):
+    pass
+class NotInitializedError(NotmuchError):
+    pass
+
+
+def _str(value):
+    """Ensure a nicely utf-8 encoded string to pass to libnotmuch
+
+    C++ code expects strings to be well formatted and
+    unicode strings to have no null bytes."""
+    if not isinstance(value, basestring):
+        raise TypeError("Expected str or unicode, got %s" % str(type(value)))
+    if isinstance(value, unicode):
+        return value.encode('UTF-8')
+    return value