X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=cnotmuch%2Fdatabase.py;h=dde7da16eecea67fec9e513d27c16588a1abccf8;hp=d13294334f4ab2050e3418795e0d0b9a69273c73;hb=63c5a6d77d2b51104305e91676720099f4667e92;hpb=c54b2683cdb15197284f936b3da4877c253912a3 diff --git a/cnotmuch/database.py b/cnotmuch/database.py index d1329433..dde7da16 100644 --- a/cnotmuch/database.py +++ b/cnotmuch/database.py @@ -1,25 +1,32 @@ -import ctypes -from ctypes import c_int, c_char_p, c_void_p -from cnotmuch.globals import nmlib, STATUS, NotmuchError - +import ctypes, os +from ctypes import c_int, c_char_p, c_void_p, c_uint, c_uint64, c_bool, byref +from cnotmuch.globals import nmlib, STATUS, NotmuchError, Enum +import logging +from datetime import date class Database(object): - """ Wrapper around a notmuch_database_t + """Represents a notmuch database (wraps notmuch_database_t) - Do note that as soon as we tear down this object, all derived queries, - threads, and messages will be freed as well. + .. note:: Do remember that as soon as we tear down this object, + all underlying derived objects such as queries, threads, + messages, tags etc will be freed by the underlying library + as well. Accessing these objects will lead to segfaults and + other unexpected behavior. See above for more details. """ - #constants - MODE_READ_ONLY = 0 - MODE_READ_WRITE = 1 - _std_db_path = None - """Class attribute of users default database""" + """Class attribute to cache user's default database""" + + MODE = Enum(['READ_ONLY','READ_WRITE']) + """Constants: Mode in which to open the database""" """notmuch_database_get_path (notmuch_database_t *database)""" _get_path = nmlib.notmuch_database_get_path _get_path.restype = c_char_p + """notmuch_database_get_version""" + _get_version = nmlib.notmuch_database_get_version + _get_version.restype = c_uint + """notmuch_database_open (const char *path, notmuch_database_mode_t mode)""" _open = nmlib.notmuch_database_open _open.restype = c_void_p @@ -36,12 +43,26 @@ class Database(object): _create = nmlib.notmuch_database_create _create.restype = c_void_p - def __init__(self, path=None, create=False, status= MODE_READ_ONLY): - """ Open or create a notmuch database - - If path is None, we will try to read a users notmuch configuration and - use his default database. - Throws a NotmuchError in case of failure. + def __init__(self, path=None, create=False, mode= 0): + """If *path* is *None*, we will try to read a users notmuch + configuration and use his configured database. The location of the + configuration file can be specified through the environment variable + *NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`. + + If *create* is `True`, the database will always be created in + :attr:`MODE`.READ_WRITE mode. Default mode for opening is READ_ONLY. + + :param path: Directory to open/create the database in (see + above for behavior if `None`) + :type path: `str` or `None` + :param create: Pass `False` to open an existing, `True` to create a new + database. + :type create: bool + :param mode: Mode to open a database in. Is always + :attr:`MODE`.READ_WRITE when creating a new one. + :type mode: :attr:`MODE` + :returns: Nothing + :exception: :exc:`NotmuchError` in case of failure. """ self._db = None if path is None: @@ -52,30 +73,57 @@ class Database(object): path = Database._std_db_path if create == False: - self.open(path, status) + self.open(path, mode) else: - self.create(path, status) + self.create(path) - def create(self, path, status=MODE_READ_ONLY): - """ notmuch_database_create(const char *path) + def _verify_initialized_db(self): + """Raises a NotmuchError in case self._db is still None""" + if self._db is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) - :returns: Raises :exc:`notmuch.NotmuchError` in case - of any failure (after printing an error message on stderr). + def create(self, path): + """Creates a new notmuch database + + This function is used by __init__() and usually does not need + to be called directly. It wraps the underlying + *notmuch_database_create* function and creates a new notmuch + database at *path*. It will always return a database in + :attr:`MODE`.READ_WRITE mode as creating an empty database for + reading only does not make a great deal of sense. + + :param path: A directory in which we should create the database. + :type path: str + :returns: Nothing + :exception: :exc:`NotmuchError` in case of any failure + (after printing an error message on stderr). """ - res = Database._create(path, status) + if self._db is not None: + raise NotmuchError( + message="Cannot create db, this Database() already has an open one.") + + res = Database._create(path, Database.MODE.READ_WRITE) if res is None: raise NotmuchError( message="Could not create the specified database") self._db = res - def open(self, path, status= MODE_READ_ONLY): - """calls notmuch_database_open + def open(self, path, mode= 0): + """Opens an existing database + + This function is used by __init__() and usually does not need + to be called directly. It wraps the underlying + *notmuch_database_open* function. - :returns: Raises :exc:`notmuch.NotmuchError` in case - of any failure (after printing an error message on stderr). + :param status: Open the database in read-only or read-write mode + :type status: :attr:`MODE` + :returns: Nothing + :exception: Raises :exc:`NotmuchError` in case + of any failure (after printing an error message on stderr). """ - res = Database._open(path, status) + + res = Database._open(path, mode) if res is None: raise NotmuchError( @@ -83,45 +131,198 @@ class Database(object): self._db = res def get_path(self): - """notmuch_database_get_path (notmuch_database_t *database); """ + """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) + def get_version(self): + """Returns the database format version + + :returns: The database version as positive integer + :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if + the database was not intitialized. + """ + # Raise a NotmuchError if not initialized + self._verify_initialized_db() + + return Database._get_version (self._db) + + def needs_upgrade(self): + """Does this database need to be upgraded before writing to it? + + If this function returns True then no functions that modify the + database (:meth:`add_message`, :meth:`add_tag`, + :meth:`Directory.set_mtime`, etc.) will work unless :meth:`upgrade` + is called successfully first. + + :returns: `True` or `False` + :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if + the database was not intitialized. + """ + # Raise a NotmuchError if not initialized + self._verify_initialized_db() + + return notmuch_database_needs_upgrade(self.db) + + def add_message(self, filename): + """Adds a new message to the database + + `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. + + The file should be a single mail message (not a multi-message mbox) + that is expected to remain at its current location, since the + notmuch database will reference the filename, and will not copy the + entire contents of the file. + + :returns: On success, we return + + 1) a :class:`Message` object that can be used for things + such as adding tags to the just-added message. + 2) one of the following STATUS values: + + STATUS.SUCCESS + Message successfully added to database. + 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. + + :rtype: 2-tuple(:class:`Message`, STATUS) + + :exception: Raises a :exc:`NotmuchError` with the following meaning. + If such an exception occurs, nothing was added to the database. + + STATUS.FILE_ERROR + An error occurred trying to open the file, (such as + permission denied, or file not found, etc.). + STATUS.FILE_NOT_EMAIL + The contents of filename don't look like an email message. + STATUS.READ_ONLY_DATABASE + Database was opened in read-only mode so no message can + be added. + STATUS.NOT_INITIALIZED + The database has not been initialized. + """ + # Raise a NotmuchError if not initialized + self._verify_initialized_db() + + msg_p = c_void_p() + status = nmlib.notmuch_database_add_message(self._db, + filename, + byref(msg_p)) + + if not status in [STATUS.SUCCESS,STATUS.DUPLICATE_MESSAGE_ID]: + raise NotmuchError(status) + + #construct Message() and return + msg = Message(msg_p, self) + return (msg, status) + + def remove_message(self, filename): + """Removes a message 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) + is still available via other filenames, then the message will + persist in the database for those filenames. When the last filename + is removed for a particular message, the database content for that + message will be entirely removed. + + :returns: A STATUS.* value with the following meaning: + + STATUS.SUCCESS + The last filename was removed and the message was removed + from the database. + STATUS.DUPLICATE_MESSAGE_ID + This filename was removed but the message persists in the + database with at least one other filename. + + :exception: Raises a :exc:`NotmuchError` with the following meaning. + If such an exception occurs, nothing was removed from the database. + + STATUS.READ_ONLY_DATABASE + Database was opened in read-only mode so no message can be + removed. + STATUS.NOT_INITIALIZED + The database has not been initialized. + """ + # Raise a NotmuchError if not initialized + self._verify_initialized_db() + + status = nmlib.notmuch_database_remove_message(self._db, + filename) + def find_message(self, msgid): - """notmuch_database_find_message - :param msgid: The message id - :ptype msgid: string + """Returns a :class:`Message` as identified by its message ID + + Wraps the underlying *notmuch_database_find_message* function. - :returns: Message() or None if no message is found or if an + :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. + :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if + the database was not intitialized. """ - if self._db is None: - raise NotmuchError(STATUS.NOT_INITIALIZED) + # Raise a NotmuchError if not initialized + self._verify_initialized_db() + msg_p = Database._find_message(self._db, msgid) if msg_p is None: return None return Message(msg_p, self) def get_all_tags(self): - """Return a Tags() object (list of all tags found in the database) + """Returns :class:`Tags` with a list of all tags found in the database - :returns: Tags() object or raises :exc:`NotmuchError` with - STATUS.NULL_POINTER on error + :returns: :class:`Tags` + :execption: :exc:`NotmuchError` with STATUS.NULL_POINTER on error """ - if self._db is None: - raise NotmuchError(STATUS.NOT_INITIALIZED) + # Raise a NotmuchError if not initialized + self._verify_initialized_db() tags_p = Database._get_all_tags (self._db) if tags_p == None: raise NotmuchError(STATUS.NULL_POINTER) return Tags(tags_p, self) + def create_query(self, querystring): + """Returns a :class:`Query` derived from this database + + This is a shorthand method for doing:: + + # short version + # Automatically frees the Database() when 'q' is deleted + + q = Database(dbpath).create_query('from:"Biene Maja"') + + # long version, which is functionally equivalent but will keep the + # Database in the 'db' variable around after we delete 'q': + + db = Database(dbpath) + q = Query(db,'from:"Biene Maja"') + + This function is a python extension and not in the underlying C API. + """ + # Raise a NotmuchError if not initialized + self._verify_initialized_db() + + return Query(self, querystring) + def __repr__(self): return "'Notmuch DB " + self.get_path() + "'" def __del__(self): """Close and free the notmuch database if needed""" if self._db is not None: - print("Freeing the database now") + logging.debug("Freeing the database now") nmlib.notmuch_database_close(self._db) def _get_user_default_db(self): @@ -129,9 +330,10 @@ class Database(object): Throws a NotmuchError if it cannot find it""" from ConfigParser import SafeConfigParser - import os.path config = SafeConfigParser() - config.read(os.path.expanduser('~/.notmuch-config')) + conf_f = os.getenv('NOTMUCH_CONFIG', + os.path.expanduser('~/.notmuch-config')) + config.read(conf_f) if not config.has_option('database','path'): raise NotmuchError(message= "No DB path specified and no user default found") @@ -139,20 +341,31 @@ class Database(object): @property def db_p(self): - """Returns a pointer to the current notmuch_database_t or None""" + """Property returning a pointer to `notmuch_database_t` or `None` + + This should normally not be needed by a user (and is not yet + guaranteed to remain stable in future versions). + """ return self._db #------------------------------------------------------------------------------ class Query(object): - """ Wrapper around a notmuch_query_t + """Represents a search query on an opened :class:`Database`. + + A query selects and filters a subset of messages from the notmuch + database we derive from. + + Technically, it wraps the underlying *notmuch_query_t* struct. - Do note that as soon as we tear down this object, all derived - threads, and messages will be freed as well. + .. note:: Do remember that as soon as we tear down this object, + all underlying derived objects such as threads, + messages, tags etc will be freed by the underlying library + as well. Accessing these objects will lead to segfaults and + other unexpected behavior. See above for more details. """ # constants - SORT_OLDEST_FIRST = 0 - SORT_NEWEST_FIRST = 1 - SORT_MESSAGE_ID = 2 + SORT = Enum(['OLDEST_FIRST','NEWEST_FIRST','MESSAGE_ID']) + """Constants: Sort order in which to return results""" """notmuch_query_create""" _create = nmlib.notmuch_query_create @@ -162,17 +375,38 @@ class Query(object): _search_messages = nmlib.notmuch_query_search_messages _search_messages.restype = c_void_p + + """notmuch_query_count_messages""" + _count_messages = nmlib.notmuch_query_count_messages + _count_messages.restype = c_uint + def __init__(self, db, querystr): - """TODO: document""" + """ + :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 + """ self._db = None self._query = None self.create(db, querystr) def create(self, db, querystr): - """db is a Database() and querystr a string + """Creates a new query derived from a Database + + This function is utilized by __init__() and usually does not need to + be called directly. + + :param db: Database to create the query from. + :type db: :class:`Database` + :param querystr: The query string + :type querystr: str + :returns: Nothing + :exception: :exc:`NotmuchError` - raises NotmuchError STATUS.NOT_INITIALIZED if db is not inited and - STATUS.NULL_POINTER if the query creation failed (too little memory) + * STATUS.NOT_INITIALIZED if db is not inited + * STATUS.NULL_POINTER if the query creation failed + (too little memory) """ if db.db_p is None: raise NotmuchError(STATUS.NOT_INITIALIZED) @@ -185,10 +419,33 @@ class Query(object): NotmuchError(STATUS.NULL_POINTER) self._query = query_p + def set_sort(self, sort): + """Set the sort order future results will be delivered in + + Wraps the underlying *notmuch_query_set_sort* function. + + :param sort: Sort order (see :attr:`Query.SORT`) + :returns: Nothing + :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if query has not + been initialized. + """ + if self._query is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + nmlib.notmuch_query_set_sort(self._query, sort) def search_messages(self): - """notmuch_query_search_messages - Returns Messages() or a raises a NotmuchError() + """Filter messages according to the query and return + :class:`Messages` in the defined sort order + + Technically, it wraps the underlying + *notmuch_query_search_messages* function. + + :returns: :class:`Messages` + :exception: :exc:`NotmuchError` + + * STATUS.NOT_INITIALIZED if query is not inited + * STATUS.NULL_POINTER if search_messages failed """ if self._query is None: raise NotmuchError(STATUS.NOT_INITIALIZED) @@ -200,85 +457,213 @@ class Query(object): return Messages(msgs_p,self) + def count_messages(self): + """Estimate the number of messages matching the query + + This function performs a search and returns Xapian's best + guess as to the number of matching messages. It is much faster + than performing :meth:`search_messages` and counting the + result with `len()` (although it always returned the same + result in my tests). Technically, it wraps the underlying + *notmuch_query_count_messages* function. + + :returns: :class:`Messages` + :exception: :exc:`NotmuchError` + + * STATUS.NOT_INITIALIZED if query is not inited + """ + if self._query is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + return Query._count_messages(self._query) def __del__(self): """Close and free the Query""" if self._query is not None: - print("Freeing the Query now") + logging.debug("Freeing the Query now") nmlib.notmuch_query_destroy (self._query) #------------------------------------------------------------------------------ class Tags(object): - """Wrapper around notmuch_tags_t""" + """Represents a list of notmuch tags + + This object provides an iterator over a list of notmuch tags. Do + note that the underlying library only provides a one-time iterator + (it cannot reset the iterator to the start). Thus iterating over + the function will "exhaust" the list of tags, and a subsequent + iteration attempt will raise a :exc:`NotmuchError` + STATUS.NOT_INITIALIZED. Also note, that any function that uses + iteration (nearly all) will also exhaust the tags. So both:: + + for tag in tags: print tag + + as well as:: + + number_of_tags = len(tags) + + and even a simple:: + + #str() iterates over all tags to construct a space separated list + print(str(tags)) + + will "exhaust" the Tags. If you need to re-iterate over a list of + tags you will need to retrieve a new :class:`Tags` object. + """ #notmuch_tags_get _get = nmlib.notmuch_tags_get _get.restype = c_char_p - def __init__(self, tags_p, db=None): + def __init__(self, tags_p, parent=None): """ - msg_p is a pointer to an notmuch_message_t Structure. If it is None, - we will raise an NotmuchError(STATUS.NULL_POINTER). - - Is passed the db these tags are derived from, and saves a - reference to it, so we can automatically delete the db object - once all derived objects are dead. - - Tags() provides an iterator over all contained tags. However, you will - only be able to iterate over the Tags once, because the underlying C - function only allows iterating once. - #TODO: make the iterator work more than once and cache the tags in - the Python object. + :param tags_p: A pointer to an underlying *notmuch_tags_t* + structure. These are not publically exposed, so a user + will almost never instantiate a :class:`Tags` object + herself. They are usually handed back as a result, + e.g. in :meth:`Database.get_all_tags`. *tags_p* must be + valid, we will raise an :exc:`NotmuchError` + (STATUS.NULL_POINTER) if it is `None`. + :type tags_p: :class:`ctypes.c_void_p` + :param parent: The parent object (ie :class:`Database` or + :class:`Message` these tags are derived from, and saves a + reference to it, so we can automatically delete the db object + once all derived objects are dead. + :TODO: Make the iterator optionally work more than once by + cache the tags in the Python object(?) """ if tags_p is None: NotmuchError(STATUS.NULL_POINTER) self._tags = tags_p - self._db = db - print "Inited Tags derived from %s" %(str(db)) + #save reference to parent object so we keep it alive + self._parent = parent + logging.debug("Inited Tags derived from %s" %(repr(parent))) def __iter__(self): """ Make Tags an iterator """ - if self._tags is None: - raise NotmuchError(STATUS.NOT_INITIALIZED) return self def next(self): - nmlib.notmuch_tags_move_to_next(self._tags) + if self._tags is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + if not nmlib.notmuch_tags_valid(self._tags): self._tags = None raise StopIteration - return Tags._get (self._tags) + + tag = Tags._get (self._tags) + nmlib.notmuch_tags_move_to_next(self._tags) + return tag + + def __len__(self): + """len(:class:`Tags`) returns the number of contained tags + + .. note:: As this iterates over the tags, we will not be able + to iterate over them again (as in retrieve them)! If + the tags have been exhausted already, this will raise a + :exc:`NotmuchError` STATUS.NOT_INITIALIZED on + subsequent attempts. + """ + if self._tags is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + i=0 + while nmlib.notmuch_tags_valid(self._msgs): + nmlib.notmuch_tags_move_to_next(self._msgs) + i += 1 + self._tags = None + return i + + def __str__(self): + """The str() representation of Tags() is a space separated list of tags + + .. note:: As this iterates over the tags, we will not be able + to iterate over them again (as in retrieve them)! If + the tags have been exhausted already, this will raise a + :exc:`NotmuchError` STATUS.NOT_INITIALIZED on + subsequent attempts. + """ + return " ".join(self) def __del__(self): """Close and free the notmuch tags""" if self._tags is not None: - print("Freeing the Tags now") + logging.debug("Freeing the Tags now") nmlib.notmuch_tags_destroy (self._tags) #------------------------------------------------------------------------------ class Messages(object): - """Wrapper around notmuch_messages_t""" + """Represents a list of notmuch messages + + This object provides an iterator over a list of notmuch messages + (Technically, it provides a wrapper for the underlying + *notmuch_messages_t* structure). Do note that the underlying + library only provides a one-time iterator (it cannot reset the + iterator to the start). Thus iterating over the function will + "exhaust" the list of messages, and a subsequent iteration attempt + will raise a :exc:`NotmuchError` STATUS.NOT_INITIALIZED. Also + note, that any function that uses iteration will also + exhaust the messages. So both:: + + for msg in msgs: print msg + + as well as:: + + number_of_msgs = len(msgs) + + will "exhaust" the Messages. If you need to re-iterate over a list of + messages you will need to retrieve a new :class:`Messages` object. + + Things are not as bad as it seems though, you can store and reuse + the single Message objects as often as you want as long as you + keep the parent Messages object around. (Recall that due to + hierarchical memory allocation, all derived Message objects will + be invalid when we delete the parent Messages() object, even if it + was already "exhausted".) So this works:: + + db = Database() + msgs = Query(db,'').search_messages() #get a Messages() object + msglist = [] + for m in msgs: + msglist.append(m) + + # msgs is "exhausted" now and even len(msgs) will raise an exception. + # However it will be kept around until all retrieved Message() objects are + # also deleted. If you did e.g. an explicit del(msgs) here, the + # following lines would fail. + + # You can reiterate over *msglist* however as often as you want. + # It is simply a list with Message objects. + + print (msglist[0].get_filename()) + print (msglist[1].get_filename()) + print (msglist[0].get_message_id()) + """ #notmuch_tags_get _get = nmlib.notmuch_messages_get _get.restype = c_void_p + _collect_tags = nmlib.notmuch_messages_collect_tags + _collect_tags.restype = c_void_p + def __init__(self, msgs_p, parent=None): """ - msg_p is a pointer to an notmuch_messages_t Structure. If it is None, - we will raise an NotmuchError(STATUS.NULL_POINTER). - - If passed the parent query this Messages() is derived from, it saves a - reference to it, so we can automatically delete the parent query object - once all derived objects are dead. - - Messages() provides an iterator over all contained Message()s. - However, you will only be able to iterate over it once, - because the underlying C function only allows iterating once. - #TODO: make the iterator work more than once and cache the tags in - the Python object. + :param msgs_p: A pointer to an underlying *notmuch_messages_t* + structure. These are not publically exposed, so a user + will almost never instantiate a :class:`Messages` object + herself. They are usually handed back as a result, + e.g. in :meth:`Query.search_messages`. *msgs_p* must be + valid, we will raise an :exc:`NotmuchError` + (STATUS.NULL_POINTER) if it is `None`. + :type msgs_p: :class:`ctypes.c_void_p` + :param parent: The parent object + (ie :class:`Query`) these tags are derived from. It saves + a reference to it, so we can automatically delete the db + object once all derived objects are dead. + :TODO: Make the iterator work more than once and cache the tags in + the Python object.(?) """ if msgs_p is None: NotmuchError(STATUS.NULL_POINTER) @@ -286,8 +671,29 @@ class Messages(object): self._msgs = msgs_p #store parent, so we keep them alive as long as self is alive self._parent = parent - print "Inited Messages derived from %s" %(str(parent)) - + logging.debug("Inited Messages derived from %s" %(str(parent))) + + def collect_tags(self): + """Return the unique :class:`Tags` in the contained messages + + :returns: :class:`Tags` + :exceptions: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if not inited + + .. note:: :meth:`collect_tags` will iterate over the messages and + therefore will not allow further iterations. + """ + if self._msgs is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + # collect all tags (returns NULL on error) + tags_p = Messages._collect_tags (self._msgs) + #reset _msgs as we iterated over it and can do so only once + self._msgs = None + + if tags_p == None: + raise NotmuchError(STATUS.NULL_POINTER) + return Tags(tags_p, self) + def __iter__(self): """ Make Messages an iterator """ return self @@ -296,75 +702,216 @@ class Messages(object): if self._msgs is None: raise NotmuchError(STATUS.NOT_INITIALIZED) - nmlib.notmuch_messages_move_to_next(self._msgs) if not nmlib.notmuch_messages_valid(self._msgs): self._msgs = None raise StopIteration - return Message(Messages._get (self._msgs), self) + + msg = Message(Messages._get (self._msgs), self) + nmlib.notmuch_messages_move_to_next(self._msgs) + return msg + + def __len__(self): + """len(:class:`Messages`) returns the number of contained messages + + .. note:: As this iterates over the messages, we will not be able to + iterate over them again! So this will fail:: + + #THIS FAILS + msgs = Database().create_query('').search_message() + if len(msgs) > 0: #this 'exhausts' msgs + # next line raises NotmuchError(STATUS.NOT_INITIALIZED)!!! + for msg in msgs: print msg + """ + if self._msgs is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + i=0 + while nmlib.notmuch_messages_valid(self._msgs): + nmlib.notmuch_messages_move_to_next(self._msgs) + i += 1 + self._msgs = None + return i + + def __del__(self): """Close and free the notmuch Messages""" if self._msgs is not None: - print("Freeing the Messages now") + logging.debug("Freeing the Messages now") nmlib.notmuch_messages_destroy (self._msgs) #------------------------------------------------------------------------------ class Message(object): - """Wrapper around notmuch_message_t""" + """Represents a single Email message + + Technically, this wraps the underlying *notmuch_message_t* structure. + """ """notmuch_message_get_filename (notmuch_message_t *message)""" _get_filename = nmlib.notmuch_message_get_filename _get_filename.restype = c_char_p + """notmuch_message_get_message_id (notmuch_message_t *message)""" _get_message_id = nmlib.notmuch_message_get_message_id _get_message_id.restype = c_char_p + """notmuch_message_get_thread_id""" + _get_thread_id = nmlib.notmuch_message_get_thread_id + _get_thread_id.restype = c_char_p + + """notmuch_message_get_replies""" + _get_replies = nmlib.notmuch_message_get_replies + _get_replies.restype = c_void_p + """notmuch_message_get_tags (notmuch_message_t *message)""" _get_tags = nmlib.notmuch_message_get_tags _get_tags.restype = c_void_p + _get_date = nmlib.notmuch_message_get_date + _get_date.restype = c_uint64 + + _get_header = nmlib.notmuch_message_get_header + _get_header.restype = c_char_p + def __init__(self, msg_p, parent=None): """ - msg_p is a pointer to an notmuch_message_t Structure. If it is None, - we will raise an NotmuchError(STATUS.NULL_POINTER). - - Is a 'parent' object is passed which this message is derived from, - we save a reference to it, so we can automatically delete the parent - object once all derived objects are dead. + :param msg_p: A pointer to an internal notmuch_message_t + Structure. If it is `None`, we will raise an :exc:`NotmuchError` + STATUS.NULL_POINTER. + :param parent: A 'parent' object is passed which this message is + derived from. We save a reference to it, so we can + automatically delete the parent object once all derived + objects are dead. """ if msg_p is None: NotmuchError(STATUS.NULL_POINTER) self._msg = msg_p #keep reference to parent, so we keep it alive self._parent = parent - print "Inited Message derived from %s" %(str(parent)) + logging.debug("Inited Message derived from %s" %(str(parent))) def get_message_id(self): - """ return the msg id + """Returns the message ID - Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited + :returns: String with a message ID + :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message + is not initialized. """ if self._msg is None: raise NotmuchError(STATUS.NOT_INITIALIZED) return Message._get_message_id(self._msg) + def get_thread_id(self): + """Returns the thread ID - def get_filename(self): - """ return the msg filename + The returned string belongs to 'message' will only be valid for as + long as the message is valid. + + This function will not return None since Notmuch ensures that every + message belongs to a single thread. + + :returns: String with a thread ID + :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message + is not initialized. + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + return Message._get_thread_id (self._msg); + + def get_replies(self): + """Gets all direct replies to this message as :class:`Messages` iterator + + .. note:: This call only makes sense if 'message' was + ultimately obtained from a :class:`Thread` object, (such as + by coming directly from the result of calling + :meth:`Thread.get_toplevel_messages` or by any number of + subsequent calls to :meth:`get_replies`). If this message was + obtained through some non-thread means, (such as by a call + to :meth:`Query.search_messages`), then this function will + return `None`. + + :returns: :class:`Messages` or `None` if there are no replies to + this message. + :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message + is not initialized. + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + msgs_p = Message._get_replies(self._msg); + + if msgs_p is None: + return None + + return Messages(msgs_p,self) + + def get_date(self): + """Returns time_t of the message date + + For the original textual representation of the Date header from the + message call notmuch_message_get_header() with a header value of + "date". + + :returns: a time_t timestamp + :rtype: c_unit64 + :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message + is not initialized. + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + return Message._get_date(self._msg) + + def get_header(self, header): + """Returns a message header - Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited + This returns any message header that is stored in the notmuch database. + This is only a selected subset of headers, which is currently: + + TODO: add stored headers + + :param header: The name of the header to be retrieved. + It is not case-sensitive (TODO: confirm). + :type header: str + :returns: The header value as string + :exception: :exc:`NotmuchError` + + * STATUS.NOT_INITIALIZED if the message + is not initialized. + * STATUS.NULL_POINTER, if no header was found + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + #Returns NULL if any error occurs. + header = Message._get_header (self._msg, header) + if header == None: + raise NotmuchError(STATUS.NULL_POINTER) + return header + + def get_filename(self): + """Return the file path of the message file + + :returns: Absolute file path & name of the message file + :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message + is not initialized. """ if self._msg is None: raise NotmuchError(STATUS.NOT_INITIALIZED) return Message._get_filename(self._msg) def get_tags(self): - """ return the msg tags - - Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited - Raises NotmuchError(STATUS.NULL_POINTER) on error. + """ Return the message tags + + :returns: Message tags + :rtype: :class:`Tags` + :exception: :exc:`NotmuchError` + + * STATUS.NOT_INITIALIZED if the message + is not initialized. + * STATUS.NULL_POINTER, on error """ if self._msg is None: raise NotmuchError(STATUS.NOT_INITIALIZED) @@ -374,8 +921,203 @@ class Message(object): raise NotmuchError(STATUS.NULL_POINTER) return Tags(tags_p, self) + def add_tag(self, tag): + """Add a tag to the given message + + Adds a tag to the current message. The maximal tag length is defined in + the notmuch library and is currently 200 bytes. + + :param tag: String with a 'tag' to be added. + :returns: STATUS.SUCCESS if the tag was successfully added. + Raises an exception otherwise. + :exception: :exc:`NotmuchError`. They have the following meaning: + + STATUS.NULL_POINTER + The 'tag' argument is NULL + STATUS.TAG_TOO_LONG + The length of 'tag' is too long + (exceeds Message.NOTMUCH_TAG_MAX) + STATUS.READ_ONLY_DATABASE + Database was opened in read-only mode so message cannot be + modified. + STATUS.NOT_INITIALIZED + The message has not been initialized. + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + status = nmlib.notmuch_message_add_tag (self._msg, tag) + + if STATUS.SUCCESS == status: + # return on success + return status + + raise NotmuchError(status) + + def remove_tag(self, tag): + """Removes a tag from the given message + + If the message has no such tag, this is a non-operation and + will report success anyway. + + :param tag: String with a 'tag' to be removed. + :returns: STATUS.SUCCESS if the tag was successfully removed or if + the message had no such tag. + Raises an exception otherwise. + :exception: :exc:`NotmuchError`. They have the following meaning: + + STATUS.NULL_POINTER + The 'tag' argument is NULL + STATUS.TAG_TOO_LONG + The length of 'tag' is too long + (exceeds NOTMUCH_TAG_MAX) + STATUS.READ_ONLY_DATABASE + Database was opened in read-only mode so message cannot + be modified. + STATUS.NOT_INITIALIZED + The message has not been initialized. + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + status = nmlib.notmuch_message_remove_tag(self._msg, tag) + + if STATUS.SUCCESS == status: + # return on success + return status + + raise NotmuchError(status) + + def remove_all_tags(self): + """Removes all tags from the given message. + + See :meth:`freeze` for an example showing how to safely + replace tag values. + + :returns: STATUS.SUCCESS if the tags were successfully removed. + Raises an exception otherwise. + :exception: :exc:`NotmuchError`. They have the following meaning: + + STATUS.READ_ONLY_DATABASE + Database was opened in read-only mode so message cannot + be modified. + STATUS.NOT_INITIALIZED + The message has not been initialized. + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + status = nmlib.notmuch_message_remove_all_tags(self._msg) + + if STATUS.SUCCESS == status: + # return on success + return status + + raise NotmuchError(status) + + def freeze(self): + """Freezes the current state of 'message' within the database + + This means that changes to the message state, (via :meth:`add_tag`, + :meth:`remove_tag`, and :meth:`remove_all_tags`), will not be + committed to the database until the message is :meth:`thaw`ed. + + Multiple calls to freeze/thaw are valid and these calls will + "stack". That is there must be as many calls to thaw as to freeze + before a message is actually thawed. + + The ability to do freeze/thaw allows for safe transactions to + change tag values. For example, explicitly setting a message to + have a given set of tags might look like this:: + + msg.freeze() + msg.remove_all_tags() + for tag in new_tags: + msg.add_tag(tag) + msg.thaw() + + With freeze/thaw used like this, the message in the database is + guaranteed to have either the full set of original tag values, or + the full set of new tag values, but nothing in between. + + Imagine the example above without freeze/thaw and the operation + somehow getting interrupted. This could result in the message being + left with no tags if the interruption happened after + :meth:`remove_all_tags` but before :meth:`add_tag`. + + :returns: STATUS.SUCCESS if the message was successfully frozen. + Raises an exception otherwise. + :exception: :exc:`NotmuchError`. They have the following meaning: + + STATUS.READ_ONLY_DATABASE + Database was opened in read-only mode so message cannot + be modified. + STATUS.NOT_INITIALIZED + The message has not been initialized. + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + status = nmlib.notmuch_message_freeze(self._msg) + + if STATUS.SUCCESS == status: + # return on success + return status + + raise NotmuchError(status) + + def thaw(self): + """Thaws the current 'message' + + Thaw the current 'message', synchronizing any changes that may have + occurred while 'message' was frozen into the notmuch database. + + See :meth:`freeze` for an example of how to use this + function to safely provide tag changes. + + Multiple calls to freeze/thaw are valid and these calls with + "stack". That is there must be as many calls to thaw as to freeze + before a message is actually thawed. + + :returns: STATUS.SUCCESS if the message was successfully frozen. + Raises an exception otherwise. + :exception: :exc:`NotmuchError`. They have the following meaning: + + STATUS.UNBALANCED_FREEZE_THAW + An attempt was made to thaw an unfrozen message. + That is, there have been an unbalanced number of calls + to :meth:`freeze` and :meth:`thaw`. + STATUS.NOT_INITIALIZED + The message has not been initialized. + """ + if self._msg is None: + raise NotmuchError(STATUS.NOT_INITIALIZED) + + status = nmlib.notmuch_message_thaw(self._msg) + + if STATUS.SUCCESS == status: + # return on success + return status + + raise NotmuchError(status) + + + def __str__(self): + """A message() is represented by a 1-line summary""" + msg = {} + msg['from'] = self.get_header('from') + msg['tags'] = str(self.get_tags()) + msg['date'] = date.fromtimestamp(self.get_date()) + replies = self.get_replies() + msg['replies'] = len(replies) if replies is not None else -1 + return "%(from)s (%(date)s) (%(tags)s) (%(replies)d) replies" % (msg) + + def format_as_text(self): + """Output like notmuch show (Not implemented)""" + return str(self) + def __del__(self): """Close and free the notmuch Message""" if self._msg is not None: - print("Freeing the Message now") + logging.debug("Freeing the Message now") nmlib.notmuch_message_destroy (self._msg)