X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=bindings%2Fpython%2Fnotmuch%2Fdatabase.py;h=9fb30e6355d2ca9bca4d90311d2862e9455cb771;hp=c607011172845c95d18d941d363ce22e3fba95e5;hb=f88d985e507a96b5179c2de793b9b75da55457a3;hpb=e69e30edd71eb6c7ea3a004e80ff84accbd12199 diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py index c6070111..9fb30e63 100644 --- a/bindings/python/notmuch/database.py +++ b/bindings/python/notmuch/database.py @@ -19,12 +19,11 @@ Copyright 2010 Sebastian Spaeth ' import os from ctypes import c_int, c_char_p, c_void_p, c_uint, c_long, byref -from notmuch.globals import nmlib, STATUS, NotmuchError, Enum +from notmuch.globals import nmlib, STATUS, NotmuchError, Enum, _str from notmuch.thread import Threads from notmuch.message import Messages, Message from notmuch.tag import Tags - class Database(object): """Represents a notmuch database (wraps notmuch_database_t) @@ -64,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 @@ -101,13 +104,12 @@ class Database(object): Database._std_db_path = self._get_user_default_db() path = Database._std_db_path - assert isinstance(path, basestring), 'Path must be a string or None.' if create == False: self.open(path, mode) else: self.create(path) - def _verify_initialized_db(self): + def _assert_db_is_initialized(self): """Raises a NotmuchError in case self._db is still None""" if self._db is None: raise NotmuchError(STATUS.NOT_INITIALIZED) @@ -132,7 +134,7 @@ class Database(object): raise NotmuchError(message="Cannot create db, this Database() " "already has an open one.") - res = Database._create(path, Database.MODE.READ_WRITE) + res = Database._create(_str(path), Database.MODE.READ_WRITE) if res is None: raise NotmuchError( @@ -152,8 +154,7 @@ class Database(object): :exception: Raises :exc:`NotmuchError` in case of any failure (after printing an error message on stderr). """ - - res = Database._open(path, mode) + res = Database._open(_str(path), mode) if res is None: raise NotmuchError( @@ -164,10 +165,8 @@ class Database(object): """Returns the file path of an open database Wraps *notmuch_database_get_path*.""" - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - - return Database._get_path(self._db) + self._assert_db_is_initialized() + return Database._get_path(self._db).decode('utf-8') def get_version(self): """Returns the database format version @@ -176,9 +175,7 @@ class Database(object): :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if the database was not intitialized. """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - + self._assert_db_is_initialized() return Database._get_version(self._db) def needs_upgrade(self): @@ -193,9 +190,7 @@ class Database(object): :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if the database was not intitialized. """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - + self._assert_db_is_initialized() return nmlib.notmuch_database_needs_upgrade(self._db) def upgrade(self): @@ -213,13 +208,52 @@ class Database(object): :TODO: catch exceptions, document return values and etc... """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - + self._assert_db_is_initialized() status = Database._upgrade(self._db, None, None) #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.""" + self._assert_db_is_initialized() + 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.""" + self._assert_db_is_initialized() + 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(?)) @@ -228,8 +262,8 @@ class Database(object): Database.MODE.READ_WRITE mode. The underlying library will exit the program if this method is used on a read-only database! - :param path: A str containing the path relative to the path of database - (see :meth:`get_path`), or else should be an absolute path + :param path: An unicode string containing the path relative to the path + of database (see :meth:`get_path`), or else should be an absolute path with initial components that match the path of 'database'. :returns: :class:`Directory` or raises an exception. :exception: :exc:`NotmuchError` @@ -242,9 +276,7 @@ class Database(object): components same as database. """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - + self._assert_db_is_initialized() # sanity checking if path is valid, and make path absolute if path[0] == os.sep: # we got an absolute path @@ -258,10 +290,10 @@ class Database(object): #we got a relative path, make it absolute abs_dirpath = os.path.abspath(os.path.join(self.get_path(), path)) - dir_p = Database._get_directory(self._db, path) + dir_p = Database._get_directory(self._db, _str(path)) # return the Directory, init it with the absolute path - return Directory(abs_dirpath, dir_p, self) + return Directory(_str(abs_dirpath), dir_p, self) def add_message(self, filename, sync_maildir_flags=False): """Adds a new message to the database @@ -294,7 +326,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) @@ -313,12 +345,10 @@ class Database(object): STATUS.NOT_INITIALIZED The database has not been initialized. """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - + self._assert_db_is_initialized() msg_p = c_void_p() status = nmlib.notmuch_database_add_message(self._db, - filename, + _str(filename), byref(msg_p)) if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]: @@ -332,7 +362,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) @@ -360,9 +390,7 @@ class Database(object): STATUS.NOT_INITIALIZED The database has not been initialized. """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - + self._assert_db_is_initialized() return nmlib.notmuch_database_remove_message(self._db, filename) @@ -384,13 +412,23 @@ class Database(object): :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if the database was not intitialized. """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() + self._assert_db_is_initialized() + 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 - msg_p = Database._find_message(self._db, msgid) - if msg_p is None: - return None - return Message(msg_p, self) + :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._assert_db_is_initialized() + 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 @@ -398,9 +436,7 @@ class Database(object): :returns: :class:`Tags` :execption: :exc:`NotmuchError` with STATUS.NULL_POINTER on error """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - + self._assert_db_is_initialized() tags_p = Database._get_all_tags(self._db) if tags_p == None: raise NotmuchError(STATUS.NULL_POINTER) @@ -424,9 +460,7 @@ class Database(object): This function is a python extension and not in the underlying C API. """ - # Raise a NotmuchError if not initialized - self._verify_initialized_db() - + self._assert_db_is_initialized() return Query(self, querystring) def __repr__(self): @@ -449,7 +483,7 @@ class Database(object): if not config.has_option('database', 'path'): raise NotmuchError(message="No DB path specified" " and no user default found") - return config.get('database', 'path') + return config.get('database', 'path').decode('utf-8') @property def db_p(self): @@ -532,11 +566,8 @@ 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) + query_p = Query._create(db.db_p, _str(querystr)) if query_p is None: NotmuchError(STATUS.NULL_POINTER) self._query = query_p @@ -666,14 +697,14 @@ class Directory(object): _get_child_directories = nmlib.notmuch_directory_get_child_directories _get_child_directories.restype = c_void_p - def _verify_dir_initialized(self): + def _assert_dir_is_initialized(self): """Raises a NotmuchError(STATUS.NOT_INITIALIZED) if dir_p is None""" if self._dir_p is None: raise NotmuchError(STATUS.NOT_INITIALIZED) def __init__(self, path, dir_p, parent): """ - :param path: The absolute path of the directory object. + :param path: The absolute path of the directory object as unicode. :param dir_p: The pointer to an internal notmuch_directory_t object. :param parent: The object this Directory is derived from (usually a :class:`Database`). We do not directly use @@ -681,6 +712,7 @@ class Directory(object): this Directory object lives. This keeps the parent object alive. """ + assert isinstance(path, unicode), "Path needs to be an UNICODE object" self._path = path self._dir_p = dir_p self._parent = parent @@ -720,9 +752,7 @@ class Directory(object): STATUS.NOT_INITIALIZED The directory has not been initialized """ - #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if the dir_p is None - self._verify_dir_initialized() - + self._assert_dir_is_initialized() #TODO: make sure, we convert the mtime parameter to a 'c_long' status = Directory._set_mtime(self._dir_p, mtime) @@ -744,9 +774,7 @@ class Directory(object): STATUS.NOT_INITIALIZED The directory has not been initialized """ - #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self.dir_p is None - self._verify_dir_initialized() - + self._assert_dir_is_initialized() return Directory._get_mtime(self._dir_p) # Make mtime attribute a property of Directory() @@ -763,9 +791,7 @@ class Directory(object): The returned filenames will be the basename-entries only (not complete paths. """ - #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self._dir_p is None - self._verify_dir_initialized() - + self._assert_dir_is_initialized() files_p = Directory._get_child_files(self._dir_p) return Filenames(files_p, self) @@ -776,9 +802,7 @@ class Directory(object): The returned filenames will be the basename-entries only (not complete paths. """ - #Raise a NotmuchError(STATUS.NOT_INITIALIZED) if self._dir_p is None - self._verify_dir_initialized() - + self._assert_dir_is_initialized() files_p = Directory._get_child_directories(self._dir_p) return Filenames(files_p, self)