Implement Message().get|set_flag()

These were the last 2 missing methods from the Message object, which should be feature complete now.

cnotmuch/database.py

@@ -1,4 +1,4 @@
-import ctypes, os
+import os
 from ctypes import c_int, c_char_p, c_void_p, c_uint, byref
 from cnotmuch.globals import nmlib, STATUS, NotmuchError, Enum
 from cnotmuch.thread import Threads
@@ -451,6 +451,10 @@ class Query(object):
         The returned threads are owned by the query and as such, will only be 
         valid until the Query is deleted.
 
+        The method sets :attr:`Message.FLAG`\.MATCH for those messages that
+        match the query. The method :meth:`Message.get_flag` allows us
+        to get the value of this flag.
+
         Technically, it wraps the underlying
         *notmuch_query_search_threads* function.
 

cnotmuch/message.py

@@ -1,6 +1,6 @@
-from ctypes import c_char_p, c_void_p, c_long
+from ctypes import c_char_p, c_void_p, c_long, c_bool
 from datetime import date
-from cnotmuch.globals import nmlib, STATUS, NotmuchError
+from cnotmuch.globals import nmlib, STATUS, NotmuchError, Enum
 from cnotmuch.tag import Tags
 #------------------------------------------------------------------------------
 class Messages(object):
@@ -166,6 +166,10 @@ class Message(object):
     _get_filename = nmlib.notmuch_message_get_filename
     _get_filename.restype = c_char_p 
 
+    """notmuch_message_get_flag"""
+    _get_flag = nmlib.notmuch_message_get_flag
+    _get_flag.restype = c_bool
+
     """notmuch_message_get_message_id (notmuch_message_t *message)"""
     _get_message_id = nmlib.notmuch_message_get_message_id
     _get_message_id.restype = c_char_p 
@@ -188,6 +192,9 @@ class Message(object):
     _get_header = nmlib.notmuch_message_get_header
     _get_header.restype = c_char_p
 
+    #Constants: Flags that can be set/get with set_flag
+    FLAG = Enum(['MATCH'])
+
     def __init__(self, msg_p, parent=None):
         """
         :param msg_p: A pointer to an internal notmuch_message_t
@@ -315,6 +322,38 @@ class Message(object):
             raise NotmuchError(STATUS.NOT_INITIALIZED)
         return Message._get_filename(self._msg)
 
+    def get_flag(self, flag):
+        """Checks whether a specific flag is set for this message
+
+        The method :meth:`Query.search_threads` sets
+        *Message.FLAG.MATCH* for those messages that match the
+        query. This method allows us to get the value of this flag.
+
+        :param flag: One of the :attr:`Message.FLAG` values (currently only 
+                     *Message.FLAG.MATCH*
+        :returns: A bool, indicating whether the flag is set.
+        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message 
+              is not initialized.
+        """
+        if self._msg is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+        return Message._get_flag(self._msg, flag)
+
+    def set_flag(self, flag, value):
+        """Sets/Unsets a specific flag for this message
+
+        :param flag: One of the :attr:`Message.FLAG` values (currently only 
+                     *Message.FLAG.MATCH*
+        :param value: A bool indicating whether to set or unset the flag.
+
+        :returns: Nothing
+        :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message 
+              is not initialized.
+        """
+        if self._msg is None:
+            raise NotmuchError(STATUS.NOT_INITIALIZED)
+        nmlib.notmuch_message_set_flag(self._msg, flag, value)
+
     def get_tags(self):
         """Returns the message tags
 

cnotmuch/notmuch.py

@@ -33,8 +33,8 @@
 
 """
 from database import Database, Query
-from message import Messages
-from thread import Threads
+from message import Messages, Message
+from thread import Threads, Thread
 from tag import Tags
 from cnotmuch.globals import nmlib, STATUS, NotmuchError
 __LICENSE__="GPL v3+"

docs/source/index.rst

@@ -140,7 +140,15 @@ More information on specific topics can be found on the following pages:
 
    .. automethod:: get_filename
 
-   .. automethod:: get_flag
+   .. attribute:: FLAG
+
+        FLAG.MATCH 
+          This flag is automatically set by a
+	  Query.search_threads on those messages that match the
+	  query. This allows us to distinguish matches from the rest
+	  of the messages in that thread.
+
+  .. automethod:: get_flag
 
    .. automethod:: set_flag