python: Encode query string as a utf-8 byte array

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

diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py
index fc7edf0b57f572007f726eacd1ef5586e91a655a..84cf79bbad13f90e8d438bb51d4fac44a818bf4a 100644 (file)
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -100,6 +100,7 @@ class Database(object):
                 Database._std_db_path = self._get_user_default_db()
             path = Database._std_db_path
 
+        assert isinstance(path, basestring), 'Path needs to be a string or None.'
         if create == False:
             self.open(path, mode)
         else:
@@ -194,7 +195,7 @@ class Database(object):
         # Raise a NotmuchError if not initialized
         self._verify_initialized_db()
 
-        return notmuch_database_needs_upgrade(self._db) 
+        return nmlib.notmuch_database_needs_upgrade(self._db) 
 
     def upgrade(self):
         """Upgrades the current database
@@ -260,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.
@@ -273,6 +274,13 @@ class Database(object):
         notmuch database will reference the filename, and will not copy the
         entire contents of the file.
 
+        :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 
 
            1) a :class:`Message` object that can be used for things
@@ -310,11 +318,14 @@ class Database(object):
                                                   filename,
                                                   byref(msg_p))
  
-        if not status in [STATUS.SUCCESS,STATUS.DUPLICATE_MESSAGE_ID]:
+        if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
             raise NotmuchError(status)
 
         #construct Message() and return
         msg = Message(msg_p, self)
+        #automatic sync initial tags from Maildir flags
+        if sync_maildir_flags:
+            msg.maildir_flags_to_tags()
         return (msg, status)
 
     def remove_message(self, filename):
@@ -358,8 +369,14 @@ class Database(object):
 
         :param msgid: The message ID
         :type msgid: string
-        :returns: :class:`Message` or `None` if no message is found or if an
-                  out-of-memory situation occurs.
+        :returns: :class:`Message` or `None` if no message is found or
+                  if any xapian exception or out-of-memory situation
+                  occurs. Do note that Xapian Exceptions include
+                  "Database modified" situations, e.g. when the
+                  notmuch database has been modified by
+                  another program in the meantime. A return value of 
+                  `None` is therefore no guarantee that the message 
+                  does not exist.
         :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
                   the database was not intitialized.
         """
@@ -484,7 +501,7 @@ class Query(object):
         :param db: An open database which we derive the Query from.
         :type db: :class:`Database`
         :param querystr: The query string for the message.
-        :type querystr: str
+        :type querystr: utf-8 encoded str or unicode
         """
         self._db = None
         self._query = None
@@ -500,7 +517,7 @@ class Query(object):
         :param db: Database to create the query from.
         :type db: :class:`Database`
         :param querystr: The query string
-        :type querystr: str
+        :type querystr: utf-8 encoded str or unicode
         :returns: Nothing
         :exception: :exc:`NotmuchError`
 
@@ -512,7 +529,9 @@ class Query(object):
             raise NotmuchError(STATUS.NOT_INITIALIZED)            
         # create reference to parent db to keep it alive
         self._db = db
-        
+        if isinstance(querystr, unicode):
+            # xapian takes utf-8 encoded byte arrays
+            querystr = querystr.encode('utf-8')
         # create query, return None if too little mem available
         query_p = Query._create(db.db_p, querystr)
         if query_p is None: