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)
def get_path(self):
"""Returns the file path of an open database
- Wraps *notmuch_database_get_path*."""
- # Raise a NotmuchError if not initialized
- self._verify_initialized_db()
-
+ .. ..:: Wraps underlying `notmuch_database_get_path`"""
+ self._assert_db_is_initialized()
return Database._get_path(self._db).decode('utf-8')
def get_version(self):
"""Returns the database format version
:returns: The database version as positive integer
- :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
+ :exception: :exc:`NotmuchError` with :attr:`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):
etc.) will work unless :meth:`upgrade` is called successfully first.
:returns: `True` or `False`
- :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
+ :exception: :exc:`NotmuchError` with :attr:`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):
: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: :attr:`STATUS`.SUCCESS or raises
+
+ :exception: :exc:`NotmuchError`:
+ :attr:`STATUS`.XAPIAN_EXCEPTION
+ Xapian exception occurred; atomic section not entered.
+
+ *Added in notmuch 0.9*"""
+ 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: :attr:`STATUS`.SUCCESS or raises
+
+ :exception:
+ :exc:`NotmuchError`:
+ :attr:`STATUS`.XAPIAN_EXCEPTION
+ A Xapian exception occurred; atomic section not
+ ended.
+ :attr:`STATUS`.UNBALANCED_ATOMIC:
+ end_atomic has been called more times than begin_atomic.
+
+ *Added in notmuch 0.9*"""
+ 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(?))
.. warning:: This call needs a writeable database in
- Database.MODE.READ_WRITE mode. The underlying library will exit the
+ :attr:`Database.MODE`.READ_WRITE mode. The underlying library will exit the
program if this method is used on a read-only database!
:param path: An unicode string containing the path relative to the path
:returns: :class:`Directory` or raises an exception.
:exception: :exc:`NotmuchError`
- STATUS.NOT_INITIALIZED
+ :attr:`STATUS`.NOT_INITIALIZED
If the database was not intitialized.
- STATUS.FILE_ERROR
+ :attr:`STATUS`.FILE_ERROR
If path is not relative database or absolute with initial
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
def add_message(self, filename, sync_maildir_flags=False):
"""Adds a new message to the database
- :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.
+ :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.
- 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.
+ 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.
:param sync_maildir_flags: If the message contains Maildir
flags, we will -depending on the notmuch configuration- sync
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:
+ 2) one of the following :attr:`STATUS` values:
- STATUS.SUCCESS
+ :attr:`STATUS`.SUCCESS
Message successfully added to database.
- STATUS.DUPLICATE_MESSAGE_ID
+ :attr:`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 list of the filenames for the existing message.
- :rtype: 2-tuple(:class:`Message`, STATUS)
+ :rtype: 2-tuple(:class:`Message`, :attr:`STATUS`)
:exception: Raises a :exc:`NotmuchError` with the following meaning.
If such an exception occurs, nothing was added to the database.
- STATUS.FILE_ERROR
+ :attr:`STATUS`.FILE_ERROR
An error occurred trying to open the file, (such as
permission denied, or file not found, etc.).
- STATUS.FILE_NOT_EMAIL
+ :attr:`STATUS`.FILE_NOT_EMAIL
The contents of filename don't look like an email
message.
- STATUS.READ_ONLY_DATABASE
+ :attr:`STATUS`.READ_ONLY_DATABASE
Database was opened in read-only mode so no message can
be added.
- STATUS.NOT_INITIALIZED
+ :attr:`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,
_str(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:
+ :returns: A :attr:`STATUS` value with the following meaning:
- STATUS.SUCCESS
+ :attr:`STATUS`.SUCCESS
The last filename was removed and the message was removed
from the database.
- STATUS.DUPLICATE_MESSAGE_ID
+ :attr:`STATUS`.DUPLICATE_MESSAGE_ID
This filename was removed but the message persists in the
database with at least one other filename.
If such an exception occurs, nothing was removed from the
database.
- STATUS.READ_ONLY_DATABASE
+ :attr:`STATUS`.READ_ONLY_DATABASE
Database was opened in read-only mode so no message can be
removed.
- STATUS.NOT_INITIALIZED
+ :attr:`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)
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
+ :exception: :exc:`NotmuchError` with :attr:`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
+ .. warning:: This call needs a writeable database in
+ :attr:`Database.MODE`.READ_WRITE mode. The underlying library will
+ exit the program if this method is used on a read-only
+ database!
+
: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()
+ * A Xapian exception occurs
+
+ *Added in notmuch 0.9*"""
+ 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
"""Returns :class:`Tags` with a list of all tags found in the database
:returns: :class:`Tags`
- :execption: :exc:`NotmuchError` with STATUS.NULL_POINTER on error
+ :execption: :exc:`NotmuchError` with :attr:`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)
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):
:returns: Nothing
:exception: :exc:`NotmuchError`
- * STATUS.NOT_INITIALIZED if db is not inited
- * STATUS.NULL_POINTER if the query creation failed
+ * :attr:`STATUS`.NOT_INITIALIZED if db is not inited
+ * :attr:`STATUS`.NULL_POINTER if the query creation failed
(too little memory)
"""
if db.db_p is None:
# create query, return None if too little mem available
query_p = Query._create(db.db_p, _str(querystr))
if query_p is None:
- NotmuchError(STATUS.NULL_POINTER)
+ raise NotmuchError(STATUS.NULL_POINTER)
self._query = query_p
def set_sort(self, sort):
:param sort: Sort order (see :attr:`Query.SORT`)
:returns: Nothing
- :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if query has not
+ :exception: :exc:`NotmuchError` :attr:`STATUS`.NOT_INITIALIZED if query has not
been initialized.
"""
if self._query is None:
:returns: :class:`Threads`
:exception: :exc:`NotmuchError`
- * STATUS.NOT_INITIALIZED if query is not inited
- * STATUS.NULL_POINTER if search_threads failed
+ * :attr:`STATUS`.NOT_INITIALIZED if query is not inited
+ * :attr:`STATUS`.NULL_POINTER if search_threads failed
"""
if self._query is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
:returns: :class:`Messages`
:exception: :exc:`NotmuchError`
- * STATUS.NOT_INITIALIZED if query is not inited
- * STATUS.NULL_POINTER if search_messages failed
+ * :attr:`STATUS`.NOT_INITIALIZED if query is not inited
+ * :attr:`STATUS`.NULL_POINTER if search_messages failed
"""
if self._query is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
msgs_p = Query._search_messages(self._query)
if msgs_p is None:
- NotmuchError(STATUS.NULL_POINTER)
+ raise NotmuchError(STATUS.NULL_POINTER)
return Messages(msgs_p, self)
:returns: :class:`Messages`
:exception: :exc:`NotmuchError`
- * STATUS.NOT_INITIALIZED if query is not inited
+ * :attr:`STATUS`.NOT_INITIALIZED if query is not inited
"""
if self._query is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
_get_child_directories = nmlib.notmuch_directory_get_child_directories
_get_child_directories.restype = c_void_p
- def _verify_dir_initialized(self):
- """Raises a NotmuchError(STATUS.NOT_INITIALIZED) if dir_p is None"""
+ def _assert_dir_is_initialized(self):
+ """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED) if dir_p is None"""
if self._dir_p is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
:returns: Nothing on success, raising an exception on failure.
:exception: :exc:`NotmuchError`:
- STATUS.XAPIAN_EXCEPTION
+ :attr:`STATUS`.XAPIAN_EXCEPTION
A Xapian exception occurred, mtime not stored.
- STATUS.READ_ONLY_DATABASE
+ :attr:`STATUS`.READ_ONLY_DATABASE
Database was opened in read-only mode so directory
mtime cannot be modified.
- STATUS.NOT_INITIALIZED
+ :attr:`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)
:returns: Nothing on success, raising an exception on failure.
:exception: :exc:`NotmuchError`:
- STATUS.NOT_INITIALIZED
+ :attr:`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()
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)
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)
#THIS FAILS
files = Database().get_directory('').get_child_files()
if len(files) > 0: #this 'exhausts' msgs
- # next line raises NotmuchError(STATUS.NOT_INITIALIZED)!!!
+ # next line raises NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)!!!
for file in files: print file
"""
if self._files_p is None: