Merge commit '0.6.1'

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

diff --git a/bindings/python/notmuch/message.py b/bindings/python/notmuch/message.py
index 8944af42b33323be7142a251589834989d354824..763d2c6827b6f6e3243c98a9af4ca25ee9aaf254 100644 (file)
--- a/bindings/python/notmuch/message.py
+++ b/bindings/python/notmuch/message.py
@@ -43,7 +43,7 @@ class Messages(object):
     of messages, and a subsequent iteration attempt will raise a
     :exc:`NotmuchError` STATUS.NOT_INITIALIZED. If you need to
     re-iterate over a list of messages you will need to retrieve a new
     of messages, and a subsequent iteration attempt will raise a
     :exc:`NotmuchError` STATUS.NOT_INITIALIZED. 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
+    :class:`Messages` object or cache your :class:`Message`\s in a list

     via::
 
        msglist = list(msgs)
     via::
 
        msglist = list(msgs)


@@ -226,12 +226,12 @@ class Messages(object):
 class Message(object):
     """Represents a single Email message
 
 class Message(object):
     """Represents a single Email message
 

-    Technically, this wraps the underlying *notmuch_message_t* structure.
+    Technically, this wraps the underlying *notmuch_message_t*
+    structure. A user will usually not create these objects themselves
+    but get them as search results.

 
 

-    As this implements __cmp__() it is possible to compare 2
-    :class:`Message`s with::
-
-        if msg1 == msg2:
+    As it implements :meth:`__cmp__`, it is possible to compare two
+    :class:`Message`\s using `if msg1 == msg2: ...`.

     """
 
     """notmuch_message_get_filename (notmuch_message_t *message)"""
     """
 
     """notmuch_message_get_filename (notmuch_message_t *message)"""


@@ -284,6 +284,7 @@ class Message(object):
         :param msg_p: A pointer to an internal notmuch_message_t
             Structure.  If it is `None`, we will raise an :exc:`NotmuchError`
             STATUS.NULL_POINTER.
         :param msg_p: A pointer to an internal notmuch_message_t
             Structure.  If it is `None`, we will raise an :exc:`NotmuchError`
             STATUS.NULL_POINTER.

+

         :param parent: A 'parent' object is passed which this message is
               derived from. We save a reference to it, so we can
               automatically delete the parent object once all derived
         :param parent: A 'parent' object is passed which this message is
               derived from. We save a reference to it, so we can
               automatically delete the parent object once all derived


@@ -313,7 +314,7 @@ class Message(object):
         The returned string belongs to 'message' will only be valid for as 
         long as the message is valid.
 
         The returned string belongs to 'message' will only be valid for as 
         long as the message is valid.
 

-        This function will not return None since Notmuch ensures that every
+        This function will not return `None` since Notmuch ensures that every

         message belongs to a single thread.
 
         :returns: String with a thread ID
         message belongs to a single thread.
 
         :returns: String with a thread ID


@@ -469,7 +470,7 @@ class Message(object):
             raise NotmuchError(STATUS.NULL_POINTER)
         return Tags(tags_p, self)
 
             raise NotmuchError(STATUS.NULL_POINTER)
         return Tags(tags_p, self)
 

-    def add_tag(self, tag, sync_maildir_flags=True):
+    def add_tag(self, tag, sync_maildir_flags=False):

         """Adds a tag to the given message
 
         Adds a tag to the current message. The maximal tag length is defined in
         """Adds a tag to the given message
 
         Adds a tag to the current message. The maximal tag length is defined in


@@ -479,11 +480,11 @@ class Message(object):
 
         :param sync_maildir_flags: If notmuch configuration is set to do
             this, add maildir flags corresponding to notmuch tags. See
 
         :param sync_maildir_flags: If notmuch configuration is set to do
             this, add maildir flags corresponding to notmuch tags. See

-            :meth:`tags_to_maildir_flags`. Use False if you want to
-            add/remove many tags on a message without having to
-            physically rename the file every time. Do note, that this
-            will do nothing when a message is frozen, as tag changes
-            will not be committed to the database yet.
+            underlying method :meth:`tags_to_maildir_flags`. Use False
+            if you want to add/remove many tags on a message without
+            having to physically rename the file every time. Do note,
+            that this will do nothing when a message is frozen, as tag
+            changes will not be committed to the database yet.

 
         :returns: STATUS.SUCCESS if the tag was successfully added.
                   Raises an exception otherwise.
 
         :returns: STATUS.SUCCESS if the tag was successfully added.
                   Raises an exception otherwise.


@@ -513,7 +514,7 @@ class Message(object):
             self.tags_to_maildir_flags()
         return STATUS.SUCCESS
 
             self.tags_to_maildir_flags()
         return STATUS.SUCCESS
 

-    def remove_tag(self, tag, sync_maildir_flags=True):
+    def remove_tag(self, tag, sync_maildir_flags=False):

         """Removes a tag from the given message
 
         If the message has no such tag, this is a non-operation and
         """Removes a tag from the given message
 
         If the message has no such tag, this is a non-operation and


@@ -522,11 +523,11 @@ class Message(object):
         :param tag: String with a 'tag' to be removed.
         :param sync_maildir_flags: If notmuch configuration is set to do
             this, add maildir flags corresponding to notmuch tags. See
         :param tag: String with a 'tag' to be removed.
         :param sync_maildir_flags: If notmuch configuration is set to do
             this, add maildir flags corresponding to notmuch tags. See

-            :meth:`tags_to_maildir_flags`. Use False if you want to
-            add/remove many tags on a message without having to
-            physically rename the file every time. Do note, that this
-            will do nothing when a message is frozen, as tag changes
-            will not be committed to the database yet.
+            underlying method :meth:`tags_to_maildir_flags`. Use False
+            if you want to add/remove many tags on a message without
+            having to physically rename the file every time. Do note,
+            that this will do nothing when a message is frozen, as tag
+            changes will not be committed to the database yet.

 
         :returns: STATUS.SUCCESS if the tag was successfully removed or if 
                   the message had no such tag.
 
         :returns: STATUS.SUCCESS if the tag was successfully removed or if 
                   the message had no such tag.


@@ -558,12 +559,13 @@ class Message(object):
 
 
 
 
 
 

-    def remove_all_tags(self, sync_maildir_flags=True):
+    def remove_all_tags(self, sync_maildir_flags=False):

         """Removes all tags from the given message.
 
         See :meth:`freeze` for an example showing how to safely
         replace tag values.
 
         """Removes all tags from the given message.
 
         See :meth:`freeze` for an example showing how to safely
         replace tag values.
 

+

         :param sync_maildir_flags: If notmuch configuration is set to do
             this, add maildir flags corresponding to notmuch tags. See
             :meth:`tags_to_maildir_flags`. Use False if you want to
         :param sync_maildir_flags: If notmuch configuration is set to do
             this, add maildir flags corresponding to notmuch tags. See
             :meth:`tags_to_maildir_flags`. Use False if you want to


@@ -702,8 +704,9 @@ class Message(object):
         Also, if this filename is in a directory named "new", rename it
         to be within the neighboring directory named "cur".
 
         Also, if this filename is in a directory named "new", rename it
         to be within the neighboring directory named "cur".
 

-        Usually, you do not need to call this manually as
-        tag changing methods should be implicitly calling it.
+        Do note that calling this method while a message is frozen might
+        not work yet, as the modified tags have not been committed yet
+        to the database.

 
         :returns: a :class:`STATUS`. In short, you want to see
             notmuch.STATUS.SUCCESS here. See there for details."""
 
         :returns: a :class:`STATUS`. In short, you want to see
             notmuch.STATUS.SUCCESS here. See there for details."""


@@ -729,8 +732,8 @@ class Message(object):
         is, the flags from the multiple filenames are combined with the
         logical OR operator.)
 
         is, the flags from the multiple filenames are combined with the
         logical OR operator.)
 

-        Usually, you do not need to call this manually as
-        :meth:`Database.add_message` implicitly calls it.
+        As a convenience, you can set the sync_maildir_flags parameter in
+        :meth:`Database.add_message` to implicitly call this.

 
         :returns: a :class:`STATUS`. In short, you want to see
             notmuch.STATUS.SUCCESS here. See there for details."""
 
         :returns: a :class:`STATUS`. In short, you want to see
             notmuch.STATUS.SUCCESS here. See there for details."""


@@ -748,9 +751,7 @@ class Message(object):
         msg['from'] = self.get_header('from')
         msg['tags'] = str(self.get_tags())
         msg['date'] = date.fromtimestamp(self.get_date())
         msg['from'] = self.get_header('from')
         msg['tags'] = str(self.get_tags())
         msg['date'] = date.fromtimestamp(self.get_date())

-        replies = self.get_replies()
-        msg['replies'] = len(replies) if replies is not None else 0
-        return "%(from)s (%(date)s) (%(tags)s) %(replies)d replies" % (msg)
+        return "%(from)s (%(date)s) (%(tags)s)" % (msg)

 
 
     def get_message_parts(self):
 
 
     def get_message_parts(self):