The Database is the highest-level object that notmuch provides. It references a notmuch database, and can be opened in read-only or read-write mode. A Query can be derived from or be applied to a specific database to find messages. Also adding and removing messages to the database happens via this object. Modifications to the database are not atmic by default (see begin_atomic()) and once a database has been modified, all other database objects pointing to the same data-base will throw an XapianError as the underlying database has been modified. Close and reopen the database to continue working with it.
Database objects implement the context manager protocol so you can use the with statement to ensure that the database is properly closed. See close() for more information.
Note
Any function in this class can and will throw an NotInitializedError if the database was not intitialized properly.
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 MODE.READ_WRITE mode. Default mode for opening is READ_ONLY.
Parameters: | |
---|---|
Raises : | NotmuchError or derived exception in case of failure. |
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 MODE .READ_WRITE mode as creating an empty database for reading only does not make a great deal of sense.
Parameters: | path (str) – A directory in which we should create the database. |
---|---|
Raises : | NotmuchError in case of any failure (possibly after printing an error message on stderr). |
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.
Parameters: | status (MODE) – Open the database in read-only or read-write mode |
---|---|
Raises : | Raises NotmuchError in case of any failure (possibly after printing an error message on stderr). |
Closes the notmuch database.
Warning
This function closes the notmuch database. From that point on every method invoked on any object ever derived from the closed database may cease to function and raise a NotmuchError.
Returns the file path of an open database
Returns the database format version
Returns: | The database version as positive integer |
---|
Does this database need to be upgraded before writing to it?
If this function returns True then no functions that modify the database (add_message(), Message.add_tag(), Directory.set_mtime(), etc.) will work unless upgrade() is called successfully first.
Returns: | True or False |
---|
Upgrades the current database
After opening a database in read-write mode, the client should check if an upgrade is needed (notmuch_database_needs_upgrade) and if so, upgrade with this function before making any modifications.
NOT IMPLEMENTED: The optional progress_notify callback can be used by the caller to provide progress indication to the user. If non-NULL it will be called periodically with ‘progress’ as a floating-point value in the range of [0.0..1.0] indicating the progress made so far in the upgrade process.
Todo : | catch exceptions, document return values and etc... |
---|
Begin an atomic database operation
Any modifications performed between a successful begin_atomic() and a 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 |
---|---|
Raises : | NotmuchError: STATUS.XAPIAN_EXCEPTION Xapian exception occurred; atomic section not entered. |
Added in notmuch 0.9
Indicate the end of an atomic database operation
See begin_atomic() for details.
Returns: | STATUS.SUCCESS or raises |
---|---|
Raises : |
Added in notmuch 0.9
Returns a Directory of path,
Parameters: | path – An unicode string containing the path relative to the path of database (see get_path()), or else should be an absolute path with initial components that match the path of ‘database’. |
---|---|
Returns: | Directory or raises an exception. |
Raises : | FileError if path is not relative database or absolute with initial components same as database. |
Adds a new message to the database
Parameters: |
|
---|---|
Returns: | On success, we return |
Return type: | |
Raises : | Raises a NotmuchError with the following meaning. If such an exception occurs, nothing was added to the 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) 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: |
---|---|
Raises : | Raises a NotmuchError with the following meaning. If such an exception occurs, nothing was removed from the database.
|
Returns a Message as identified by its message ID
Wraps the underlying notmuch_database_find_message function.
Parameters: | msgid (unicode or str) – The message ID |
---|---|
Returns: | Message or None if no message is found. |
Raises : |
|
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 if no message is found with the given filename. |
---|---|
Raises : | OutOfMemoryError if an Out-of-memory occured while constructing the message. |
Raises : | XapianError in case of a Xapian Exception. These exceptions include “Database modified” situations, e.g. when the notmuch database has been modified by another program in the meantime. In this case, you should close and reopen the database and retry. |
Raises : | NotInitializedError if the database was not intitialized. |
Added in notmuch 0.9
Returns Tags with a list of all tags found in the database
Returns: | Tags |
---|---|
Execption : | NotmuchError with STATUS.NULL_POINTER on error |
Returns a 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.
Defines constants that are used as the mode in which to open a database.