X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=bindings%2Fpython%2Fnotmuch%2Fglobals.py;h=a42f2a40d68f4217d9f29691d44eb9b8ac8ef97b;hb=05926adf73e7b1bad0faa4a0a5514d554353cdaa;hp=8b0d8d0b41a7c205980f425aaafca6cbf81742aa;hpb=3b558de7811a765c3295a58bd53e2156eca0e32e;p=notmuch

diff --git a/bindings/python/notmuch/globals.py b/bindings/python/notmuch/globals.py
index 8b0d8d0b..a42f2a40 100644
--- a/bindings/python/notmuch/globals.py
+++ b/bindings/python/notmuch/globals.py
@@ -23,21 +23,20 @@ from ctypes.util import find_library
 #-----------------------------------------------------------------------------
 #package-global instance of the notmuch library
 try:
-    nmlib = CDLL("libnotmuch.so.1")
+    nmlib = CDLL("libnotmuch.so.2")
 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."""
-    __name__="foo"
     _status2str = nmlib.notmuch_status_to_string
     _status2str.restype = c_char_p
     _status2str.argtypes = [c_int]
@@ -50,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',
@@ -66,15 +65,119 @@ 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.
 
+  * SUCCESS
+  * OUT_OF_MEMORY
+  * READ_ONLY_DATABASE
+  * XAPIAN_EXCEPTION
+  * FILE_ERROR
+  * FILE_NOT_EMAIL
+  * DUPLICATE_MESSAGE_ID
+  * 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'
 
 class NotmuchError(Exception):
+    """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_exc_subclass(cls, status):
+        """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]
+
+    def __new__(cls, *args, **kwargs):
+        """Return a correct subclass of NotmuchError if needed
+
+        We return a NotmuchError instance if status is None (or 0) and a
+        subclass that inherits from NotmuchError depending on the
+        'status' parameter otherwise."""
+        # get 'status'. Passed in as arg or kwarg?
+        status = args[0] if len(args) else kwargs.get('status', None)
+        # no 'status' or cls is subclass already, return 'cls' instance
+        if not status or cls != NotmuchError:
+            return super(NotmuchError, cls).__new__(cls)
+        subclass = cls.get_exc_subclass(status) # which class to use?
+        return subclass.__new__(subclass, *args, **kwargs)
+
     def __init__(self, status=None, message=None):
-        """Is initiated with a (notmuch.STATUS[,message=None])"""
-        super(NotmuchError, self).__init__(message, status)
+        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):
+    """Derived from NotmuchError, this occurs if the underlying data
+    structure (e.g. database is not initialized (yet) or an iterator has
+    been exhausted. You can test for NotmuchError with .status =
+    STATUS.NOT_INITIALIZED"""
+    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