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
 
     _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
     """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
 
         #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(?))
     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
               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)
 
 
         :rtype:   2-tuple(:class:`Message`, STATUS)
 


@@ -329,7 +376,7 @@ class Database(object):
         return (msg, status)
 
     def remove_message(self, filename):
         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)
 
         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
 
         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
 
     def get_all_tags(self):
         """Returns :class:`Tags` with a list of all tags found in the database