[PATCH 8/9] python: use the new exception classes and update the documentation

Justus Winter 4winter at informatik.uni-hamburg.de
Sun Sep 25 18:05:36 PDT 2011


Signed-off-by: Justus Winter <4winter at informatik.uni-hamburg.de>
---
 bindings/python/notmuch/database.py |  138 +++++++++++++++++++++--------------
 bindings/python/notmuch/filename.py |    9 +-
 bindings/python/notmuch/message.py  |   79 ++++++++++----------
 bindings/python/notmuch/tag.py      |   10 ++-
 bindings/python/notmuch/thread.py   |   47 ++++++------
 5 files changed, 158 insertions(+), 125 deletions(-)

diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py
index edde70e..8df7c2f 100644
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -19,7 +19,9 @@ Copyright 2010 Sebastian Spaeth <Sebastian at SSpaeth.de>'
 
 import os
 from ctypes import c_int, c_char_p, c_void_p, c_uint, c_long, byref
-from notmuch.globals import nmlib, STATUS, NotmuchError, Enum, _str
+from notmuch.globals import nmlib, STATUS, NotmuchError, Enum, _str, \
+                            NotInitializedError, FileError, \
+                            NullPointerError
 from notmuch.thread import Threads
 from notmuch.message import Messages, Message
 from notmuch.tag import Tags
@@ -106,9 +108,9 @@ class Database(object):
             self.create(path)
 
     def _assert_db_is_initialized(self):
-        """Raises a NotmuchError in case self._db is still None"""
+        """Raises a :exc:`NotInitializedError` in case self._db is still None"""
         if self._db is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
     def create(self, path):
         """Creates a new notmuch database
@@ -160,7 +162,12 @@ class Database(object):
     def get_path(self):
         """Returns the file path of an open database
 
-        Wraps *notmuch_database_get_path*."""
+        Wraps *notmuch_database_get_path*.
+
+        :returns: The path to the database as string
+        :exception: :exc:`NotInitializedError` if
+                    the database was not intitialized.
+        """
         self._assert_db_is_initialized()
 
         return Database._get_path(self._db).decode('utf-8')
@@ -169,7 +176,7 @@ class Database(object):
         """Returns the database format version
 
         :returns: The database version as positive integer
-        :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
+        :exception: :exc:`NotInitializedError` if
                     the database was not intitialized.
         """
         self._assert_db_is_initialized()
@@ -185,7 +192,7 @@ class Database(object):
         etc.) will work unless :meth:`upgrade` is called successfully first.
 
         :returns: `True` or `False`
-        :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
+        :exception: :exc:`NotInitializedError` if
                     the database was not intitialized.
         """
         self._assert_db_is_initialized()
@@ -206,6 +213,9 @@ class Database(object):
         indicating the progress made so far in the upgrade process.
 
         :TODO: catch exceptions, document return values and etc...
+
+        :exception: :exc:`NotInitializedError` if
+                    the database was not intitialized.
         """
         self._assert_db_is_initialized()
 
@@ -225,15 +235,14 @@ class Database(object):
               of database (see :meth:`get_path`), or else should be an absolute path
               with initial components that match the path of 'database'.
         :returns: :class:`Directory` or raises an exception.
-        :exception: :exc:`NotmuchError`
+        :exception: :exc:`NotInitializedError` or :exc:`FileError`
 
-                  STATUS.NOT_INITIALIZED
+                  :exc:`NotInitializedError`
                     If the database was not intitialized.
 
-                  STATUS.FILE_ERROR
+                  :exc:`FileError`
                     If path is not relative database or absolute with initial
                     components same as database.
-
         """
         self._assert_db_is_initialized()
 
@@ -242,9 +251,8 @@ class Database(object):
             # we got an absolute path
             if not path.startswith(self.get_path()):
                 # but its initial components are not equal to the db path
-                raise NotmuchError(message="Database().get_directory() called "
-                                           "with a wrong absolute path.",
-                                   status=STATUS.FILE_ERROR)
+                raise FileError("Database().get_directory() called "
+                                "with a wrong absolute path.")
             abs_dirpath = path
         else:
             #we got a relative path, make it absolute
@@ -293,16 +301,16 @@ class Database(object):
         :exception: Raises a :exc:`NotmuchError` with the following meaning.
               If such an exception occurs, nothing was added to the database.
 
-              STATUS.FILE_ERROR
+              :exc:`FileError`
                       An error occurred trying to open the file, (such as
                       permission denied, or file not found, etc.).
-              STATUS.FILE_NOT_EMAIL
+              :exc:`FileNotEmail`
                       The contents of filename don't look like an email
                       message.
-              STATUS.READ_ONLY_DATABASE
+              :exc:`ReadOnlyDatabaseError`
                       Database was opened in read-only mode so no message can
                       be added.
-              STATUS.NOT_INITIALIZED
+              :exc:`NotInitializedError`
                       The database has not been initialized.
         """
         self._assert_db_is_initialized()
@@ -313,7 +321,7 @@ class Database(object):
                                                   byref(msg_p))
 
         if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
-            raise NotmuchError(status=status)
+            raise NotmuchError.decode(status)
 
         #construct Message() and return
         msg = Message(msg_p, self)
@@ -345,10 +353,10 @@ class Database(object):
              If such an exception occurs, nothing was removed from the
              database.
 
-             STATUS.READ_ONLY_DATABASE
+             :exc:`ReadOnlyDatabaseError`
                Database was opened in read-only mode so no message can be
                removed.
-             STATUS.NOT_INITIALIZED
+             :exc:`NotInitializedError`
                The database has not been initialized.
         """
         self._assert_db_is_initialized()
@@ -371,7 +379,7 @@ class Database(object):
                   another program in the meantime. A return value of
                   `None` is therefore no guarantee that the message
                   does not exist.
-        :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
+        :exception: :exc:`NotInitializedError` if
                   the database was not intitialized.
         """
         self._assert_db_is_initialized()
@@ -383,13 +391,13 @@ class Database(object):
         """Returns :class:`Tags` with a list of all tags found in the database
 
         :returns: :class:`Tags`
-        :execption: :exc:`NotmuchError` with STATUS.NULL_POINTER on error
+        :execption: :exc:`NullPointerError` on error
         """
         self._assert_db_is_initialized()
 
         tags_p = Database._get_all_tags(self._db)
         if tags_p == None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
         return Tags(tags_p, self)
 
     def create_query(self, querystring):
@@ -409,6 +417,9 @@ class Database(object):
           q  = Query(db,'from:"Biene Maja"')
 
         This function is a python extension and not in the underlying C API.
+
+        :exception: :exc:`NotInitializedError` if
+                  the database was not intitialized.
         """
         self._assert_db_is_initialized()
 
@@ -425,7 +436,8 @@ class Database(object):
     def _get_user_default_db(self):
         """ Reads a user's notmuch config and returns his db location
 
-        Throws a NotmuchError if it cannot find it"""
+        :exception: :exc:`NotMuchError` if it cannot find it
+        """
         from ConfigParser import SafeConfigParser
         config = SafeConfigParser()
         conf_f = os.getenv('NOTMUCH_CONFIG',
@@ -507,20 +519,20 @@ class Query(object):
         :param querystr: The query string
         :type querystr: utf-8 encoded str or unicode
         :returns: Nothing
-        :exception: :exc:`NotmuchError`
+        :exception: :exc:`NotInitializedError` or :exc:`NullPointerError`
 
-                      * STATUS.NOT_INITIALIZED if db is not inited
-                      * STATUS.NULL_POINTER if the query creation failed
+                      :exc:`NotInitializedError` if db is not initialized
+                      :exc:`NullPointerError` if the query creation failed
                         (too little memory)
         """
         if db.db_p is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         # create reference to parent db to keep it alive
         self._db = db
         # create query, return None if too little mem available
         query_p = Query._create(db.db_p, _str(querystr))
         if query_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
         self._query = query_p
 
     def set_sort(self, sort):
@@ -530,11 +542,11 @@ class Query(object):
 
         :param sort: Sort order (see :attr:`Query.SORT`)
         :returns: Nothing
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if query has not
+        :exception: :exc:`NotInitializedError` if query has not
                     been initialized.
         """
         if self._query is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         self.sort = sort
         nmlib.notmuch_query_set_sort(self._query, sort)
@@ -554,18 +566,18 @@ class Query(object):
         *notmuch_query_search_threads* function.
 
         :returns: :class:`Threads`
-        :exception: :exc:`NotmuchError`
+        :exception: :exc:`NotInitializedError` or :exc:`NullPointerError`
 
-                      * STATUS.NOT_INITIALIZED if query is not inited
-                      * STATUS.NULL_POINTER if search_threads failed
+                      :exc:`NotInitializedError` if query is not initialized
+                      :exc:`NullPointerError` if the search_threads failed
         """
         if self._query is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         threads_p = Query._search_threads(self._query)
 
         if threads_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
 
         return Threads(threads_p, self)
 
@@ -577,18 +589,18 @@ class Query(object):
         *notmuch_query_search_messages* function.
 
         :returns: :class:`Messages`
-        :exception: :exc:`NotmuchError`
+        :exception: :exc:`NotInitializedError` or :exc:`NullPointerError`
 
-                      * STATUS.NOT_INITIALIZED if query is not inited
-                      * STATUS.NULL_POINTER if search_messages failed
+                      :exc:`NotInitializedError` if query is not initialized
+                      :exc:`NullPointerError` if the search_messages failed
         """
         if self._query is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         msgs_p = Query._search_messages(self._query)
 
         if msgs_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
 
         return Messages(msgs_p, self)
 
@@ -603,12 +615,12 @@ class Query(object):
         *notmuch_query_count_messages* function.
 
         :returns: :class:`Messages`
-        :exception: :exc:`NotmuchError`
+        :exception: :exc:`NotInitializedError`
 
-                      * STATUS.NOT_INITIALIZED if query is not inited
+                      :exc:`NotInitializedError` if query is not initialized
         """
         if self._query is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         return Query._count_messages(self._query)
 
@@ -651,7 +663,7 @@ class Directory(object):
     def _assert_dir_is_initialized(self):
         """Raises a NotmuchError(status=STATUS.NOT_INITIALIZED) if dir_p is None"""
         if self._dir_p is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
     def __init__(self, path, dir_p, parent):
         """
@@ -693,14 +705,15 @@ class Directory(object):
 
           :param mtime: A (time_t) timestamp
           :returns: Nothing on success, raising an exception on failure.
-          :exception: :exc:`NotmuchError`:
+          :exception: :exc:`NotInitializedError`, :exc:`XapianError` or
+                      :exc:`ReadOnlyDatabaseError`
 
-                        STATUS.XAPIAN_EXCEPTION
+                        :exc:`XapianError`
                           A Xapian exception occurred, mtime not stored.
-                        STATUS.READ_ONLY_DATABASE
+                        :exc:`ReadOnlyDatabaseError`
                           Database was opened in read-only mode so directory
                           mtime cannot be modified.
-                        STATUS.NOT_INITIALIZED
+                        :exc:`NotInitializedError`
                           The directory has not been initialized
         """
         self._assert_dir_is_initialized()
@@ -712,7 +725,7 @@ class Directory(object):
         if status == STATUS.SUCCESS:
             return
         #fail with Exception otherwise
-        raise NotmuchError(status=status)
+        raise NotmuchError.decode(status)
 
     def get_mtime(self):
         """Gets the mtime value of this directory in the database
@@ -721,9 +734,9 @@ class Directory(object):
 
         :param mtime: A (time_t) timestamp
         :returns: Nothing on success, raising an exception on failure.
-        :exception: :exc:`NotmuchError`:
+        :exception: :exc:`NotInitializedError`
 
-                        STATUS.NOT_INITIALIZED
+                        :exc:`NotInitializedError`
                           The directory has not been initialized
         """
         self._assert_dir_is_initialized()
@@ -743,6 +756,11 @@ class Directory(object):
 
         The returned filenames will be the basename-entries only (not
         complete paths.
+
+        :exception: :exc:`NotInitializedError`
+
+                        :exc:`NotInitializedError`
+                          The directory has not been initialized
         """
         self._assert_dir_is_initialized()
 
@@ -755,6 +773,11 @@ class Directory(object):
 
         The returned filenames will be the basename-entries only (not
         complete paths.
+
+        :exception: :exc:`NotInitializedError`
+
+                        :exc:`NotInitializedError`
+                          The directory has not been initialized
         """
         self._assert_dir_is_initialized()
 
@@ -801,7 +824,7 @@ class Filenames(object):
 
     def next(self):
         if self._files_p is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         if not nmlib.notmuch_filenames_valid(self._files_p):
             self._files_p = None
@@ -820,11 +843,16 @@ class Filenames(object):
                  #THIS FAILS
                  files = Database().get_directory('').get_child_files()
                  if len(files) > 0:              #this 'exhausts' msgs
-                     # next line raises NotmuchError(status=STATUS.NOT_INITIALIZED)!!!
+                     # next line raises NotInitializedError()!!!
                      for file in files: print file
+
+        :exception: :exc:`NotInitializedError`
+
+                        :exc:`NotInitializedError`
+                          If self._files_p is None
         """
         if self._files_p is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         i = 0
         while nmlib.notmuch_filenames_valid(self._files_p):
diff --git a/bindings/python/notmuch/filename.py b/bindings/python/notmuch/filename.py
index c5dfd94..ddfd494 100644
--- a/bindings/python/notmuch/filename.py
+++ b/bindings/python/notmuch/filename.py
@@ -17,7 +17,8 @@ along with notmuch.  If not, see <http://www.gnu.org/licenses/>.
 Copyright 2010 Sebastian Spaeth <Sebastian at SSpaeth.de>'
 """
 from ctypes import c_char_p
-from notmuch.globals import nmlib, STATUS, NotmuchError
+from notmuch.globals import nmlib, STATUS, NotmuchError, \
+                            NullPointerError, NotInitializedError
 
 
 class Filenames(object):
@@ -68,7 +69,7 @@ class Filenames(object):
              once all derived objects are dead.
         """
         if files_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
 
         self._files = files_p
         #save reference to parent object so we keep it alive
@@ -80,7 +81,7 @@ class Filenames(object):
         This is the main function that will usually be used by the
         user."""
         if self._files is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         if not nmlib.notmuch_filenames_valid(self._files):
             self._files = None
@@ -96,7 +97,7 @@ class Filenames(object):
         .. note:: As this iterates over the filenames, we will not be
                able to iterate over them again (as in retrieve them)! If
                the tags have been exhausted already, this will raise a
-               :exc:`NotmuchError` STATUS.NOT_INITIALIZED on subsequent
+               :exc:`NotInitializedError` on subsequent
                attempts. However, you can use
                :meth:`Message.get_filenames` repeatedly to perform
                various actions on filenames.
diff --git a/bindings/python/notmuch/message.py b/bindings/python/notmuch/message.py
index 5cc3175..ac708ec 100644
--- a/bindings/python/notmuch/message.py
+++ b/bindings/python/notmuch/message.py
@@ -21,7 +21,8 @@ Copyright 2010 Sebastian Spaeth <Sebastian at SSpaeth.de>'
 
 from ctypes import c_char_p, c_void_p, c_long, c_uint, c_int
 from datetime import date
-from notmuch.globals import nmlib, STATUS, NotmuchError, Enum, _str
+from notmuch.globals import nmlib, STATUS, Enum, _str, NotmuchError, \
+                            NullPointerError, NotInitializedError
 from notmuch.tag import Tags
 from notmuch.filename import Filenames
 import sys
@@ -42,7 +43,7 @@ class Messages(object):
     only provides a one-time iterator (it cannot reset the iterator to
     the start). Thus iterating over the function will "exhaust" the list
     of messages, and a subsequent iteration attempt will raise a
-    :exc:`NotmuchError` STATUS.NOT_INITIALIZED. If you need to
+    :exc:`NotInitializedError`. If you need to
     re-iterate over a list of messages you will need to retrieve a new
     :class:`Messages` object or cache your :class:`Message`\s in a list
     via::
@@ -115,7 +116,7 @@ class Messages(object):
                the Python object.(?)
         """
         if msgs_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
 
         self._msgs = msgs_p
         #store parent, so we keep them alive as long as self  is alive
@@ -125,13 +126,13 @@ class Messages(object):
         """Return the unique :class:`Tags` in the contained messages
 
         :returns: :class:`Tags`
-        :exceptions: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if not inited
+        :exceptions: :exc:`NotInitializedError` if not inited
 
         .. note:: :meth:`collect_tags` will iterate over the messages and
           therefore will not allow further iterations.
         """
         if self._msgs is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         # collect all tags (returns NULL on error)
         tags_p = Messages._collect_tags(self._msgs)
@@ -139,7 +140,7 @@ class Messages(object):
         self._msgs = None
 
         if tags_p == None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
         return Tags(tags_p, self)
 
     def __iter__(self):
@@ -148,7 +149,7 @@ class Messages(object):
 
     def next(self):
         if self._msgs is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         if not nmlib.notmuch_messages_valid(self._msgs):
             self._msgs = None
@@ -292,7 +293,7 @@ class Message(object):
               objects are dead.
         """
         if msg_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
         self._msg = msg_p
         #keep reference to parent, so we keep it alive
         self._parent = parent
@@ -301,11 +302,11 @@ class Message(object):
         """Returns the message ID
 
         :returns: String with a message ID
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
                     is not initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return Message._get_message_id(self._msg)
 
     def get_thread_id(self):
@@ -318,11 +319,11 @@ class Message(object):
         message belongs to a single thread.
 
         :returns: String with a thread ID
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
                     is not initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         return Message._get_thread_id(self._msg)
 
@@ -341,11 +342,11 @@ class Message(object):
 
         :returns: :class:`Messages` or `None` if there are no replies to
             this message.
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
                     is not initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         msgs_p = Message._get_replies(self._msg)
 
@@ -363,11 +364,11 @@ class Message(object):
 
         :returns: A time_t timestamp.
         :rtype: c_unit64
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
                     is not initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return Message._get_date(self._msg)
 
     def get_header(self, header):
@@ -389,23 +390,23 @@ class Message(object):
                     * STATUS.NULL_POINTER, if no header was found
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         #Returns NULL if any error occurs.
         header = Message._get_header(self._msg, header)
         if header == None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
         return header.decode('UTF-8')
 
     def get_filename(self):
         """Returns the file path of the message file
 
         :returns: Absolute file path & name of the message file
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
               is not initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return Message._get_filename(self._msg)
 
     def get_filenames(self):
@@ -415,7 +416,7 @@ class Message(object):
         messages recorded to have the same Message-ID. These files must
         not necessarily have identical content."""
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         files_p = Message._get_filenames(self._msg)
 
@@ -431,11 +432,11 @@ class Message(object):
         :param flag: One of the :attr:`Message.FLAG` values (currently only
                      *Message.FLAG.MATCH*
         :returns: An unsigned int (0/1), indicating whether the flag is set.
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
               is not initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return Message._get_flag(self._msg, flag)
 
     def set_flag(self, flag, value):
@@ -446,11 +447,11 @@ class Message(object):
         :param value: A bool indicating whether to set or unset the flag.
 
         :returns: Nothing
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
               is not initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         nmlib.notmuch_message_set_flag(self._msg, flag, value)
 
     def get_tags(self):
@@ -464,11 +465,11 @@ class Message(object):
                       * STATUS.NULL_POINTER, on error
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         tags_p = Message._get_tags(self._msg)
         if tags_p == None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
         return Tags(tags_p, self)
 
     def add_tag(self, tag, sync_maildir_flags=False):
@@ -503,13 +504,13 @@ class Message(object):
                      The message has not been initialized.
        """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         status = nmlib.notmuch_message_add_tag(self._msg, _str(tag))
 
         # bail out on failure
         if status != STATUS.SUCCESS:
-            raise NotmuchError(status=status)
+            raise NotmuchError.decode(status)
 
         if sync_maildir_flags:
             self.tags_to_maildir_flags()
@@ -547,12 +548,12 @@ class Message(object):
                      The message has not been initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         status = nmlib.notmuch_message_remove_tag(self._msg, _str(tag))
         # bail out on error
         if status != STATUS.SUCCESS:
-            raise NotmuchError(status=status)
+            raise NotmuchError.decode(status)
 
         if sync_maildir_flags:
             self.tags_to_maildir_flags()
@@ -584,13 +585,13 @@ class Message(object):
                      The message has not been initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         status = nmlib.notmuch_message_remove_all_tags(self._msg)
 
         # bail out on error
         if status != STATUS.SUCCESS:
-            raise NotmuchError(status=status)
+            raise NotmuchError.decode(status)
 
         if sync_maildir_flags:
             self.tags_to_maildir_flags()
@@ -638,7 +639,7 @@ class Message(object):
                      The message has not been initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         status = nmlib.notmuch_message_freeze(self._msg)
 
@@ -646,7 +647,7 @@ class Message(object):
             # return on success
             return status
 
-        raise NotmuchError(status=status)
+        raise NotmuchError.decode(status)
 
     def thaw(self):
         """Thaws the current 'message'
@@ -673,7 +674,7 @@ class Message(object):
                      The message has not been initialized.
         """
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         status = nmlib.notmuch_message_thaw(self._msg)
 
@@ -681,7 +682,7 @@ class Message(object):
             # return on success
             return status
 
-        raise NotmuchError(status=status)
+        raise NotmuchError.decode(status)
 
     def is_match(self):
         """(Not implemented)"""
@@ -709,7 +710,7 @@ class Message(object):
         :returns: a :class:`STATUS`. In short, you want to see
             notmuch.STATUS.SUCCESS here. See there for details."""
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         status = Message._tags_to_maildir_flags(self._msg)
 
     def maildir_flags_to_tags(self):
@@ -736,7 +737,7 @@ class Message(object):
         :returns: a :class:`STATUS`. In short, you want to see
             notmuch.STATUS.SUCCESS here. See there for details."""
         if self._msg is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         status = Message._tags_to_maildir_flags(self._msg)
 
     def __repr__(self):
diff --git a/bindings/python/notmuch/tag.py b/bindings/python/notmuch/tag.py
index 9ca871a..b903864 100644
--- a/bindings/python/notmuch/tag.py
+++ b/bindings/python/notmuch/tag.py
@@ -17,7 +17,9 @@ along with notmuch.  If not, see <http://www.gnu.org/licenses/>.
 Copyright 2010 Sebastian Spaeth <Sebastian at SSpaeth.de>'
 """
 from ctypes import c_char_p
-from notmuch.globals import nmlib, STATUS, NotmuchError
+from notmuch.globals import nmlib, STATUS, NotmuchError, \
+                            NullPointerError, NotInitializedError
+
 
 
 class Tags(object):
@@ -70,7 +72,7 @@ class Tags(object):
                cache the tags in the Python object(?)
         """
         if tags_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
 
         self._tags = tags_p
         #save reference to parent object so we keep it alive
@@ -82,7 +84,7 @@ class Tags(object):
 
     def next(self):
         if self._tags is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         if not nmlib.notmuch_tags_valid(self._tags):
             self._tags = None
             raise StopIteration
@@ -107,7 +109,7 @@ class Tags(object):
         .. note:: As this iterates over the tags, we will not be able
                to iterate over them again (as in retrieve them)! If
                the tags have been exhausted already, this will raise a
-               :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
+               :exc:`NotInitializedError` on
                subsequent attempts.
         """
         return " ".join(self)
diff --git a/bindings/python/notmuch/thread.py b/bindings/python/notmuch/thread.py
index 93089d0..e9d1185 100644
--- a/bindings/python/notmuch/thread.py
+++ b/bindings/python/notmuch/thread.py
@@ -18,7 +18,8 @@ Copyright 2010 Sebastian Spaeth <Sebastian at SSpaeth.de>'
 """
 
 from ctypes import c_char_p, c_void_p, c_long
-from notmuch.globals import nmlib, STATUS, NotmuchError
+from notmuch.globals import nmlib, STATUS, NotmuchError, \
+                            NullPointerError, NotInitializedError
 from notmuch.message import Messages
 from notmuch.tag import Tags
 from datetime import date
@@ -33,7 +34,7 @@ class Threads(object):
     library only provides a one-time iterator (it cannot reset the
     iterator to the start). Thus iterating over the function will
     "exhaust" the list of threads, and a subsequent iteration attempt
-    will raise a :exc:`NotmuchError` STATUS.NOT_INITIALIZED. Also
+    will raise a :exc:`NotInitializedError`. Also
     note, that any function that uses iteration will also
     exhaust the messages. So both::
 
@@ -95,7 +96,7 @@ class Threads(object):
                the Python object.(?)
         """
         if threads_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
 
         self._threads = threads_p
         #store parent, so we keep them alive as long as self  is alive
@@ -107,7 +108,7 @@ class Threads(object):
 
     def next(self):
         if self._threads is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         if not nmlib.notmuch_threads_valid(self._threads):
             self._threads = None
@@ -126,11 +127,11 @@ class Threads(object):
                  #THIS FAILS
                  threads = Database().create_query('').search_threads()
                  if len(threads) > 0:              #this 'exhausts' threads
-                     # next line raises NotmuchError(status=STATUS.NOT_INITIALIZED)!!!
+                     # next line raises NotInitializedError()!!!
                      for thread in threads: print thread
         """
         if self._threads is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         i = 0
         # returns 'bool'. On out-of-memory it returns None
@@ -206,7 +207,7 @@ class Thread(object):
               objects are dead.
         """
         if thread_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
         self._thread = thread_p
         #keep reference to parent, so we keep it alive
         self._parent = parent
@@ -218,11 +219,11 @@ class Thread(object):
         for as long as the thread is valid.
 
         :returns: String with a message ID
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the thread
+        :exception: :exc:`NotInitializedError` if the thread
                     is not initialized.
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return Thread._get_thread_id(self._thread)
 
     def get_total_messages(self):
@@ -231,11 +232,11 @@ class Thread(object):
         :returns: The number of all messages in the database
                   belonging to this thread. Contrast with
                   :meth:`get_matched_messages`.
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the thread
+        :exception: :exc:`NotInitializedError` if the thread
                     is not initialized.
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return nmlib.notmuch_thread_get_total_messages(self._thread)
 
     def get_toplevel_messages(self):
@@ -258,12 +259,12 @@ class Thread(object):
                       * STATUS.NULL_POINTER if search_messages failed
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         msgs_p = Thread._get_toplevel_messages(self._thread)
 
         if msgs_p is None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
 
         return Messages(msgs_p, self)
 
@@ -273,11 +274,11 @@ class Thread(object):
         :returns: The number of all messages belonging to this thread that
                   matched the :class:`Query`from which this thread was created.
                   Contrast with :meth:`get_total_messages`.
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the thread
+        :exception: :exc:`NotInitializedError` if the thread
                     is not initialized.
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return nmlib.notmuch_thread_get_matched_messages(self._thread)
 
     def get_authors(self):
@@ -291,7 +292,7 @@ class Thread(object):
         as long as this Thread() is not deleted.
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         authors = Thread._get_authors(self._thread)
         if authors is None:
             return None
@@ -304,7 +305,7 @@ class Thread(object):
         as long as this Thread() is not deleted.
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         subject = Thread._get_subject(self._thread)
         if subject is None:
             return None
@@ -315,11 +316,11 @@ class Thread(object):
 
         :returns: A time_t timestamp.
         :rtype: c_unit64
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
                     is not initialized.
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return Thread._get_newest_date(self._thread)
 
     def get_oldest_date(self):
@@ -327,11 +328,11 @@ class Thread(object):
 
         :returns: A time_t timestamp.
         :rtype: c_unit64
-        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+        :exception: :exc:`NotInitializedError` if the message
                     is not initialized.
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
         return Thread._get_oldest_date(self._thread)
 
     def get_tags(self):
@@ -354,11 +355,11 @@ class Thread(object):
                       * STATUS.NULL_POINTER, on error
         """
         if self._thread is None:
-            raise NotmuchError(status=STATUS.NOT_INITIALIZED)
+            raise NotInitializedError()
 
         tags_p = Thread._get_tags(self._thread)
         if tags_p == None:
-            raise NotmuchError(status=STATUS.NULL_POINTER)
+            raise NullPointerError()
         return Tags(tags_p, self)
 
     def __str__(self):
-- 
1.7.6.3



More information about the notmuch mailing list