Implement an Enum class and make the STATUS object one

[notmuch] / cnotmuch / database.py

diff --git a/cnotmuch/database.py b/cnotmuch/database.py
index 82c4f2bc2a86975ec09fc86748f2e523e56f87f1..b4411ab1ee71ff87c265b471ec8e1b0ffa3a6fd3 100644 (file)
--- a/cnotmuch/database.py
+++ b/cnotmuch/database.py
@@ -1,7 +1,8 @@
 import ctypes
 import ctypes

-from ctypes import c_int, c_char_p, c_void_p
-from cnotmuch.globals import nmlib, STATUS, NotmuchError
-
+from ctypes import c_int, c_char_p, c_void_p, c_uint64
+from cnotmuch.globals import nmlib, STATUS, NotmuchError, Enum
+import logging
+from datetime import date

 
 class Database(object):
     """ Wrapper around a notmuch_database_t
 
 class Database(object):
     """ Wrapper around a notmuch_database_t


@@ -9,9 +10,8 @@ class Database(object):
     Do note that as soon as we tear down this object, all derived queries,
     threads, and messages will be freed as well.
     """
     Do note that as soon as we tear down this object, all derived queries,
     threads, and messages will be freed as well.
     """

-    #constants
-    MODE_READ_ONLY = 0
-    MODE_READ_WRITE = 1
+    MODE = Enum(['READ_ONLY','READ_WRITE'])
+    """Constants: Mode in which to open the database"""

 
     _std_db_path = None
     """Class attribute of users default database"""
 
     _std_db_path = None
     """Class attribute of users default database"""


@@ -121,7 +121,7 @@ class Database(object):
     def __del__(self):
         """Close and free the notmuch database if needed"""
         if self._db is not None:
     def __del__(self):
         """Close and free the notmuch database if needed"""
         if self._db is not None:

-            print("Freeing the database now")
+            logging.debug("Freeing the database now")

             nmlib.notmuch_database_close(self._db)
 
     def _get_user_default_db(self):
             nmlib.notmuch_database_close(self._db)
 
     def _get_user_default_db(self):


@@ -149,26 +149,88 @@ class Query(object):
     Do note that as soon as we tear down this object, all derived
     threads, and messages will be freed as well.
     """
     Do note that as soon as we tear down this object, all derived
     threads, and messages will be freed as well.
     """

+    # constants
+    SORT_OLDEST_FIRST = 0
+    SORT_NEWEST_FIRST = 1
+    SORT_MESSAGE_ID = 2
+
+    """notmuch_query_create"""
+    _create = nmlib.notmuch_query_create
+    _create.restype = c_void_p
+
+    """notmuch_query_search_messages"""
+    _search_messages = nmlib.notmuch_query_search_messages
+    _search_messages.restype = c_void_p
+

     def __init__(self, db, querystr):
     def __init__(self, db, querystr):

-        pass
+        """TODO: document"""
+        self._db = None
+        self._query = None
+        self.create(db, querystr)
+
+    def create(self, db, querystr):
+        """db is a Database() and querystr a string
+
+        raises NotmuchError STATUS.NOT_INITIALIZED if db is not inited and
+        STATUS.NULL_POINTER if the query creation failed (too little memory)
+        """
+        if db.db_p is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)            
+        # 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, querystr)
+        if query_p is None:
+            NotmuchError(STATUS.NULL_POINTER)
+        self._query = query_p
+
+    def set_sort(self, sort):
+        """notmuch_query_set_sort
+
+        :param sort: one of Query.SORT_OLDEST_FIRST|SORT_NEWEST_FIRST|SORT_MESSAGE_ID
+        :returns: Nothing, but raises NotmuchError if query is not inited
+        """
+        if self._query is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+        nmlib.notmuch_query_set_sort(self._query, sort)
+
+    def search_messages(self):
+        """notmuch_query_search_messages
+        Returns Messages() or a raises a NotmuchError()
+        """
+        if self._query is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)            
+
+        msgs_p = Query._search_messages(self._query)
+
+        if msgs_p is None:
+            NotmuchError(STATUS.NULL_POINTER)
+
+        return Messages(msgs_p,self)
+
+
+    def __del__(self):
+        """Close and free the Query"""
+        if self._query is not None:
+            logging.debug("Freeing the Query now")
+            nmlib.notmuch_query_destroy (self._query)

 
 #------------------------------------------------------------------------------
 class Tags(object):
     """Wrapper around notmuch_tags_t"""
 
 #------------------------------------------------------------------------------
 class Tags(object):
     """Wrapper around notmuch_tags_t"""

-    class notmuch_tags_t(ctypes.Structure):
-        """the opaque tags struct that is returned by functions."""
-        pass

 
     #notmuch_tags_get
     _get = nmlib.notmuch_tags_get
     _get.restype = c_char_p
 
 
     #notmuch_tags_get
     _get = nmlib.notmuch_tags_get
     _get.restype = c_char_p
 

-    def __init__(self, tags_p, db=None):
+    def __init__(self, tags_p, parent=None):

         """
         msg_p is a pointer to an notmuch_message_t Structure. If it is None,
         we will raise an NotmuchError(STATUS.NULL_POINTER).
 
         """
         msg_p is a pointer to an notmuch_message_t Structure. If it is None,
         we will raise an NotmuchError(STATUS.NULL_POINTER).
 

-        Is passed the db these tags are derived from, and saves a
+        Is passed the parent these tags are derived from, and saves a

         reference to it, so we can automatically delete the db object
         once all derived objects are dead.
 
         reference to it, so we can automatically delete the db object
         once all derived objects are dead.
 


@@ -182,8 +244,9 @@ class Tags(object):
             NotmuchError(STATUS.NULL_POINTER)
 
         self._tags = tags_p
             NotmuchError(STATUS.NULL_POINTER)
 
         self._tags = tags_p

-        self._db = db
-        print "Inited Tags derived from %s" %(str(db))
+        #save reference to parent object so we keep it alive
+        self._parent = parent
+        logging.debug("Inited Tags derived from %s" %(repr(parent)))

     
     def __iter__(self):
         """ Make Tags an iterator """
     
     def __iter__(self):
         """ Make Tags an iterator """


@@ -191,20 +254,124 @@ class Tags(object):
 
     def next(self):
         if self._tags is None:
 
     def next(self):
         if self._tags is None:

-            raise StopIteration
-        nmlib.notmuch_tags_move_to_next(self._tags)
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+

         if not nmlib.notmuch_tags_valid(self._tags):
         if not nmlib.notmuch_tags_valid(self._tags):

-            print("Freeing the Tags now")
-            nmlib.notmuch_tags_destroy (self._tags)
+            self._tags = None

             raise StopIteration
             raise StopIteration

-        return Tags._get (self._tags)
+
+        tag = Tags._get (self._tags)
+        nmlib.notmuch_tags_move_to_next(self._tags)
+        return tag
+
+    def __str__(self):
+        """str() of Tags() is a space separated list of tags
+
+        This iterates over the list of Tags and will therefore 'exhaust' Tags()
+        """
+        return " ".join(self)

 
     def __del__(self):
         """Close and free the notmuch tags"""
         if self._tags is not None:
 
     def __del__(self):
         """Close and free the notmuch tags"""
         if self._tags is not None:

-            print("Freeing the Tags now")
+            logging.debug("Freeing the Tags now")

             nmlib.notmuch_tags_destroy (self._tags)
 
             nmlib.notmuch_tags_destroy (self._tags)
 

+
+#------------------------------------------------------------------------------
+class Messages(object):
+    """Wrapper around notmuch_messages_t"""
+
+    #notmuch_tags_get
+    _get = nmlib.notmuch_messages_get
+    _get.restype = c_void_p
+
+    _collect_tags = nmlib.notmuch_messages_collect_tags
+    _collect_tags.restype = c_void_p
+
+    def __init__(self, msgs_p, parent=None):
+        """
+        msg_p is a pointer to an notmuch_messages_t Structure. If it is None,
+        we will raise an NotmuchError(STATUS.NULL_POINTER).
+
+        If passed the parent query this Messages() is derived from, it saves a
+        reference to it, so we can automatically delete the parent query object
+        once all derived objects are dead.
+
+        Messages() provides an iterator over all contained Message()s.
+        However, you will only be able to iterate over it once,
+        because the underlying C function only allows iterating once.
+        #TODO: make the iterator work more than once and cache the tags in 
+               the Python object.
+        """
+        if msgs_p is None:
+            NotmuchError(STATUS.NULL_POINTER)
+
+        self._msgs = msgs_p
+        #store parent, so we keep them alive as long as self  is alive
+        self._parent = parent
+        logging.debug("Inited Messages derived from %s" %(str(parent)))
+
+    def collect_tags(self):
+        """ return the Tags() belonging to the messages
+        
+        Do note that collect_tags will iterate over the messages and
+        therefore will not allow further iterationsl
+        Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
+        """
+        if self._msgs is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+        # collect all tags (returns NULL on error)
+        tags_p = Messages._collect_tags (self._msgs)
+        #reset _msgs as we iterated over it and can do so only once
+        self._msgs = None
+
+        if tags_p == None:
+            raise NotmuchError(STATUS.NULL_POINTER)
+        return Tags(tags_p, self)
+
+    def __iter__(self):
+        """ Make Messages an iterator """
+        return self
+
+    def next(self):
+        if self._msgs is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+        if not nmlib.notmuch_messages_valid(self._msgs):
+            self._msgs = None
+            raise StopIteration
+
+        msg = Message(Messages._get (self._msgs), self)
+        nmlib.notmuch_messages_move_to_next(self._msgs)
+        return msg
+
+    def __len__(self):
+        """ Returns the number of contained messages
+
+        :note: As this iterates over the messages, we will not be able to 
+               iterate over them again (as in retrieve them)!
+        """
+        if self._msgs is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+        i=0
+        while nmlib.notmuch_messages_valid(self._msgs):
+            nmlib.notmuch_messages_move_to_next(self._msgs)
+            i += 1
+        self._msgs = None
+        return i
+
+
+
+    def __del__(self):
+        """Close and free the notmuch Messages"""
+        if self._msgs is not None:
+            logging.debug("Freeing the Messages now")
+            nmlib.notmuch_messages_destroy (self._msgs)
+
+

 #------------------------------------------------------------------------------
 class Message(object):
     """Wrapper around notmuch_message_t"""
 #------------------------------------------------------------------------------
 class Message(object):
     """Wrapper around notmuch_message_t"""


@@ -220,6 +387,12 @@ class Message(object):
     _get_tags = nmlib.notmuch_message_get_tags
     _get_tags.restype = c_void_p
 
     _get_tags = nmlib.notmuch_message_get_tags
     _get_tags.restype = c_void_p
 

+    _get_date = nmlib.notmuch_message_get_date
+    _get_date.restype = c_uint64
+
+    _get_header = nmlib.notmuch_message_get_header
+    _get_header.restype = c_char_p
+

     def __init__(self, msg_p, parent=None):
         """
         msg_p is a pointer to an notmuch_message_t Structure. If it is None,
     def __init__(self, msg_p, parent=None):
         """
         msg_p is a pointer to an notmuch_message_t Structure. If it is None,


@@ -232,8 +405,9 @@ class Message(object):
         if msg_p is None:
             NotmuchError(STATUS.NULL_POINTER)
         self._msg = msg_p
         if msg_p is None:
             NotmuchError(STATUS.NULL_POINTER)
         self._msg = msg_p

+        #keep reference to parent, so we keep it alive

         self._parent = parent
         self._parent = parent

-        print "Inited Message derived from %s" %(str(parent))
+        logging.debug("Inited Message derived from %s" %(str(parent)))

 
 
     def get_message_id(self):
 
 
     def get_message_id(self):


@@ -245,6 +419,28 @@ class Message(object):
             raise NotmuchError(STATUS.NOT_INITIALIZED)
         return Message._get_message_id(self._msg)
 
             raise NotmuchError(STATUS.NOT_INITIALIZED)
         return Message._get_message_id(self._msg)
 

+    def get_date(self):
+        """returns time_t of the message date
+
+        For the original textual representation of the Date header from the
+        message call notmuch_message_get_header() with a header value of
+        "date".
+        Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
+        """
+        if self._msg is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+        return Message._get_date(self._msg)
+
+    def get_header(self, header):
+        """ TODO document me"""
+        if self._msg is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+        #Returns NULL if any error occurs.
+        header = Message._get_header (self._msg, header)
+        if header == None:
+            raise NotmuchError(STATUS.NULL_POINTER)
+        return header

 
     def get_filename(self):
         """ return the msg filename
 
     def get_filename(self):
         """ return the msg filename


@@ -269,8 +465,20 @@ class Message(object):
             raise NotmuchError(STATUS.NULL_POINTER)
         return Tags(tags_p, self)
 
             raise NotmuchError(STATUS.NULL_POINTER)
         return Tags(tags_p, self)
 

+    def __str__(self):
+        """A message() is represented by a 1-line summary"""
+        msg = {}
+        msg['from'] = self.get_header('from')
+        msg['tags'] = str(self.get_tags())
+        msg['date'] = date.fromtimestamp(self.get_date())
+        return "%(from)s (%(date)s) (%(tags)s)" % (msg)
+
+    def format_as_text(self):
+        """ Output like notmuch show """
+        return str(self)
+

     def __del__(self):
         """Close and free the notmuch Message"""
         if self._msg is not None:
     def __del__(self):
         """Close and free the notmuch Message"""
         if self._msg is not None:

-            print("Freeing the Message now")
+            logging.debug("Freeing the Message now")

             nmlib.notmuch_message_destroy (self._msg)
             nmlib.notmuch_message_destroy (self._msg)