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, _str
+from notmuch.globals import (nmlib, STATUS, NotmuchError, NotInitializedError,
+ OutOfMemoryError, XapianError, Enum, _str)
from notmuch.thread import Threads
from notmuch.message import Messages, Message
from notmuch.tag import Tags
""" notmuch_database_find_message"""
_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
: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.
+ :exception: :exc:`NotmuchError` or derived exception in case of
+ failure.
"""
self._db = None
if path is None:
self.create(path)
def _assert_db_is_initialized(self):
- """Raises a NotmuchError in case self._db is still None"""
+ """Raises :exc:`NotInitializedError` if self._db is `None`"""
if self._db is None:
- raise NotmuchError.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotInitializedError()
def create(self, path):
"""Creates a new notmuch database
:type path: str
:returns: Nothing
:exception: :exc:`NotmuchError` in case of any failure
- (after printing an error message on stderr).
+ (possibly after printing an error message on stderr).
"""
if self._db is not None:
raise NotmuchError(message="Cannot create db, this Database() "
"""Returns the database format version
:returns: The database version as positive integer
- :exception: :exc:`NotmuchError` with :attr:`STATUS`.NOT_INITIALIZED if
+ :exception: :exc:`NotInitializedError` if
the database was not intitialized.
"""
self._assert_db_is_initialized()
etc.) will work unless :meth:`upgrade` is called successfully first.
:returns: `True` or `False`
- :exception: :exc:`NotmuchError` with :attr:`STATUS`.NOT_INITIALIZED if
+ :exception: :exc:`NotInitializedError` if
the database was not intitialized.
"""
self._assert_db_is_initialized()
indicating the progress made so far in the upgrade process.
:TODO: catch exceptions, document return values and etc...
+
+ :exception: :exc:`NotInitializedError` if
+ the database was not intitialized.
"""
self._assert_db_is_initialized()
status = Database._upgrade(self._db, None, None)
:attr:`STATUS`.XAPIAN_EXCEPTION
Xapian exception occurred; atomic section not entered.
+ :exc:`NotInitializedError` if
+ the database was not intitialized.
+
*Added in notmuch 0.9*"""
self._assert_db_is_initialized()
status = nmlib.notmuch_database_begin_atomic(self._db)
if status != STATUS.SUCCESS:
- raise NotmuchError.get_subclass_exc(status)
+ raise NotmuchError(status)
return status
def end_atomic(self):
:attr:`STATUS`.UNBALANCED_ATOMIC:
end_atomic has been called more times than begin_atomic.
+ :exc:`NotInitializedError` if
+ the database was not intitialized.
+
*Added in notmuch 0.9*"""
self._assert_db_is_initialized()
status = nmlib.notmuch_database_end_atomic(self._db)
if status != STATUS.SUCCESS:
- raise NotmuchError.get_subclass_exc(status)
+ raise NotmuchError(status)
return status
def get_directory(self, 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`
-
- :attr:`STATUS`.NOT_INITIALIZED
- If the database was not intitialized.
-
- :attr:`STATUS`.FILE_ERROR
+ :exception:
+ :exc:`NotmuchError` with :attr:`STATUS`.FILE_ERROR
If path is not relative database or absolute with initial
components same as database.
+ :exc:`NotInitializedError` if
+ the database was not intitialized.
"""
self._assert_db_is_initialized()
# sanity checking if path is valid, and make path absolute
# we got an absolute path
if not path.startswith(self.get_path()):
# but its initial components are not equal to the db path
- raise NotmuchError.get_subclass_exc(STATUS.FILE_ERROR,
+ raise NotmuchError(STATUS.FILE_ERROR,
message="Database().get_directory() called "
"with a wrong absolute path.")
abs_dirpath = path
:attr:`STATUS`.READ_ONLY_DATABASE
Database was opened in read-only mode so no message can
be added.
- :attr:`STATUS`.NOT_INITIALIZED
- The database has not been initialized.
+
+ :exc:`NotInitializedError` if
+ the database was not intitialized.
"""
self._assert_db_is_initialized()
msg_p = c_void_p()
byref(msg_p))
if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
- raise NotmuchError.get_subclass_exc(status)
+ raise NotmuchError(status)
#construct Message() and return
msg = Message(msg_p, self)
:attr:`STATUS`.READ_ONLY_DATABASE
Database was opened in read-only mode so no message can be
removed.
- :attr:`STATUS`.NOT_INITIALIZED
- The database has not been initialized.
+
+ :exc:`NotInitializedError` if
+ the database was not intitialized.
"""
self._assert_db_is_initialized()
return nmlib.notmuch_database_remove_message(self._db,
Wraps the underlying *notmuch_database_find_message* function.
:param msgid: The message ID
- :type msgid: string
- :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 :attr:`STATUS`.NOT_INITIALIZED if
- the database was not intitialized.
+ :type msgid: unicode or str
+ :returns: :class:`Message` or `None` if no message is found.
+ :exception:
+ :exc:`OutOfMemoryError`
+ If an Out-of-memory occured while constructing the message.
+ :exc:`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.
+
+ :exc:`NotInitializedError` if
+ the database was not intitialized.
"""
self._assert_db_is_initialized()
- msg_p = Database._find_message(self._db, _str(msgid))
+ msg_p = c_void_p()
+ status = Database._find_message(self._db, _str(msgid), byref(msg_p))
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)
return msg_p and Message(msg_p, self) or None
def find_message_by_filename(self, filename):
: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:
+ function returns None if no message is found with the given
+ filename.
- * No message is found with the given filename
- * An out-of-memory situation occurs
- * A Xapian exception occurs
+ :exception:
+ :exc:`OutOfMemoryError`
+ If an Out-of-memory occured while constructing the message.
+ :exc:`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.
+
+ :exc:`NotInitializedError` if
+ the database was not intitialized.
*Added in notmuch 0.9*"""
self._assert_db_is_initialized()
- msg_p = Database._find_message_by_filename(self._db, _str(filename))
+ msg_p = c_void_p()
+ status = Database._find_message_by_filename(self._db, _str(filename),
+ byref(msg_p))
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)
return msg_p and Message(msg_p, self) or None
def get_all_tags(self):
self._assert_db_is_initialized()
tags_p = Database._get_all_tags(self._db)
if tags_p == None:
- raise NotmuchError.get_subclass_exc(STATUS.NULL_POINTER)
+ raise NotmuchError(STATUS.NULL_POINTER)
return Tags(tags_p, self)
def create_query(self, querystring):
(too little memory)
"""
if db.db_p is None:
- raise NotmuchError.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
# create reference to parent db to keep it alive
self._db = db
# create query, return None if too little mem available
query_p = Query._create(db.db_p, _str(querystr))
if query_p is None:
- raise NotmuchError.get_subclass_exc(STATUS.NULL_POINTER)
+ raise NotmuchError(STATUS.NULL_POINTER)
self._query = query_p
def set_sort(self, sort):
been initialized.
"""
if self._query is None:
- raise NotmuchError.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
self.sort = sort
nmlib.notmuch_query_set_sort(self._query, sort)
* :attr:`STATUS`.NULL_POINTER if search_threads failed
"""
if self._query is None:
- raise NotmuchError.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
threads_p = Query._search_threads(self._query)
* :attr:`STATUS`.NULL_POINTER if search_messages failed
"""
if self._query is None:
- raise NotmuchError.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
msgs_p = Query._search_messages(self._query)
if msgs_p is None:
- raise NotmuchError.get_subclass_exc(STATUS.NULL_POINTER)
+ raise NotmuchError(STATUS.NULL_POINTER)
return Messages(msgs_p, self)
* :attr:`STATUS`.NOT_INITIALIZED if query is not inited
"""
if self._query is None:
- raise NotmuchError.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
return Query._count_messages(self._query)
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.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
def __init__(self, path, dir_p, parent):
"""
if status == STATUS.SUCCESS:
return
#fail with Exception otherwise
- raise NotmuchError.get_subclass_exc(status)
+ raise NotmuchError(status)
def get_mtime(self):
"""Gets the mtime value of this directory in the database
def next(self):
if self._files_p is None:
- raise NotmuchError.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
if not nmlib.notmuch_filenames_valid(self._files_p):
self._files_p = None
for file in files: print file
"""
if self._files_p is None:
- raise NotmuchError.get_subclass_exc(STATUS.NOT_INITIALIZED)
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
i = 0
while nmlib.notmuch_filenames_valid(self._files_p):
projects / notmuch / blobdiff