python: Do not implicitely call maildir_flags_to_tags etc

In order to remain consistent with the underlying C API, we do not
automatically synchronize notmuch tags and maildir flags anymore.

The underlying functions Message.maildir_flags_to_tags and
Message.tags_to_maildir_flags still exist and are available to the user.

Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>

diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py
index 926bac63f5931882941238b866dc3b4ee5b14bc1..5deb2a5dc06a62cb8d97096b376baf44812c7648 100644 (file)
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -261,10 +261,10 @@ class Database(object):
         # return the Directory, init it with the absolute path
         return Directory(abs_dirpath, dir_p, self)
 
-    def add_message(self, filename):
+    def add_message(self, filename, sync_maildir_flags=False):
         """Adds a new message to the database
 
-        `filename` should be a path relative to the path of the open
+        :param filename: should be a path relative to the path of the open
         database (see :meth:`get_path`), or else should be an absolute
         filename with initial components that match the path of the
         database.
@@ -274,8 +274,12 @@ class Database(object):
         notmuch database will reference the filename, and will not copy the
         entire contents of the file.
 
-        If the message contains Maildir flags, we will -depending on the
-        notmuch configuration- sync those tags to initial notmuch tags.
+        :param sync_maildir_flags: If the message contains Maildir
+            flags, we will -depending on the notmuch configuration- sync
+            those tags to initial notmuch tags, if set to `True`. It is
+            `False` by default to remain consistent with the libnotmuch
+            API. You might want to look into the underlying method
+            :meth:`Message.maildir_flags_to_tags`.
 
         :returns: On success, we return 
 
@@ -317,9 +321,11 @@ class Database(object):
         if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
             raise NotmuchError(status)
 
-        #construct Message(), sync initial tags from Maildir flags and return
+        #construct Message() and return
         msg = Message(msg_p, self)
-        msg.maildir_flags_to_tags()
+        #automatic sync initial tags from Maildir flags
+        if sync_maildir_flags:
+            msg.maildir_flags_to_tags()
         return (msg, status)
 
     def remove_message(self, filename):

diff --git a/bindings/python/notmuch/message.py b/bindings/python/notmuch/message.py
index 68de555248082efd58f0f7d8554652204c9124d6..763d2c6827b6f6e3243c98a9af4ca25ee9aaf254 100644 (file)
--- a/bindings/python/notmuch/message.py
+++ b/bindings/python/notmuch/message.py
@@ -470,7 +470,7 @@ class Message(object):
             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
@@ -480,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
-            :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.
@@ -514,7 +514,7 @@ class Message(object):
             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
@@ -523,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
-            :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.
@@ -559,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.
 
+
         :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
@@ -703,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".
 
-        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."""
@@ -730,8 +732,8 @@ class Message(object):
         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."""