python: add begin|end_atomic bindings

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

diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py
index dc124f5e91b97739ade5857320220781d8ad427f..bafe497e02c4f0466b3e230f0ce3117148edafea 100644 (file)
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -63,6 +63,10 @@ class Database(object):
     _find_message = nmlib.notmuch_database_find_message
     _find_message.restype = c_void_p
 
+    """notmuch_database_find_message_by_filename"""
+    _find_message_by_filename = nmlib.notmuch_database_find_message_by_filename
+    _find_message_by_filename.restype = c_void_p
+
     """notmuch_database_get_all_tags"""
     _get_all_tags = nmlib.notmuch_database_get_all_tags
     _get_all_tags.restype = c_void_p
@@ -217,6 +221,49 @@ class Database(object):
         #TODO: catch exceptions, document return values and etc
         return status
 
+    def begin_atomic(self):
+        """Begin an atomic database operation
+
+        Any modifications performed between a successful
+        :meth:`begin_atomic` and a :meth:`end_atomic` will be applied to
+        the database atomically.  Note that, unlike a typical database
+        transaction, this only ensures atomicity, not durability;
+        neither begin nor end necessarily flush modifications to disk.
+
+        :returns: STATUS.SUCCESS or raises
+
+        :exception: :exc:`NotmuchError` STATUS.XAPIAN_EXCEPTION::
+
+                        A Xapian exception occurred; atomic section not
+                        entered."""
+        # Raise a NotmuchError if not initialized
+        self._verify_initialized_db()
+        status = nmlib.notmuch_database_begin_atomic(self._db)
+        if status != STATUS.SUCCESS:
+            raise NotmuchError(status)
+        return status
+
+    def end_atomic(self):
+        """Indicate the end of an atomic database operation
+
+        See :meth:`begin_atomic` for details.
+
+        :returns: STATUS.SUCCESS or raises
+
+        :exception:
+            :exc:`NotmuchError`:
+                STATUS.XAPIAN_EXCEPTION
+                    A Xapian exception occurred; atomic section not
+                    ended.
+                STATUS.UNBALANCED_ATOMIC:
+                    end_atomic has been called more times than begin_atomic."""
+        # Raise a NotmuchError if not initialized
+        self._verify_initialized_db()
+        status = nmlib.notmuch_database_end_atomic(self._db)
+        if status != STATUS.SUCCESS:
+            raise NotmuchError(status)
+        return status
+
     def get_directory(self, path):
         """Returns a :class:`Directory` of path,
         (creating it if it does not exist(?))
@@ -291,7 +338,7 @@ class Database(object):
               STATUS.DUPLICATE_MESSAGE_ID
                   Message has the same message ID as another message already
                   in the database. The new filename was successfully added
-                  to the message in the database.
+                  to the list of the filenames for the existing message.
 
         :rtype:   2-tuple(:class:`Message`, STATUS)
 
@@ -329,7 +376,7 @@ class Database(object):
         return (msg, status)
 
     def remove_message(self, filename):
-        """Removes a message from the given notmuch database
+        """Removes a message (filename) from the given notmuch database
 
         Note that only this particular filename association is removed from
         the database. If the same message (as determined by the message ID)
@@ -387,6 +434,20 @@ class Database(object):
         msg_p = Database._find_message(self._db, _str(msgid))
         return msg_p and Message(msg_p, self) or None
 
+    def find_message_by_filename(self, filename):
+        """Find a message with the given filename
+
+        :returns: If the database contains a message with the given
+            filename, then a class:`Message:` is returned.  This
+            function returns None in the following situations:
+
+                * No message is found with the given filename
+                * An out-of-memory situation occurs
+                * A Xapian exception occurs"""
+        self._verify_initialized_db()
+        msg_p = Database._find_message_by_filename(self._db, _str(filename))
+        return msg_p and Message(msg_p, self) or None
+
     def get_all_tags(self):
         """Returns :class:`Tags` with a list of all tags found in the database