"""
import os
-from ctypes import c_int, c_char_p, c_void_p, c_uint, c_long, byref, POINTER
+import codecs
+from ctypes import c_char_p, c_void_p, c_uint, c_long, byref, POINTER
from notmuch.globals import (nmlib, STATUS, NotmuchError, NotInitializedError,
- NullPointerError, OutOfMemoryError, XapianError, Enum, _str,
+ NullPointerError, Enum, _str,
NotmuchDatabaseP, NotmuchDirectoryP, NotmuchMessageP, NotmuchTagsP,
NotmuchQueryP, NotmuchMessagesP, NotmuchThreadsP, NotmuchFilenamesP)
from notmuch.thread import Threads
from notmuch.message import Messages, Message
from notmuch.tag import Tags
+
class Database(object):
"""The :class:`Database` is the highest-level object that notmuch
provides. It references a notmuch database, and can be opened in
:exc:`XapianError` as the underlying database has been
modified. Close and reopen the database to continue working with it.
- .. note:: Any function in this class can and will throw an
- :exc:`NotInitializedError` if the database was not
- intitialized properly.
+ :class:`Database` objects implement the context manager protocol
+ so you can use the :keyword:`with` statement to ensure that the
+ database is properly closed.
+
+ .. note::
+
+ Any function in this class can and will throw an
+ :exc:`NotInitializedError` if the database was not intitialized
+ properly.
- .. note:: Do remember that as soon as we tear down (e.g. via `del
- db`) 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.
+ .. note::
+
+ Do remember that as soon as we tear down (e.g. via `del db`) 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.
"""
_std_db_path = None
"""Class attribute to cache user's default database"""
""" notmuch_database_find_message"""
_find_message = nmlib.notmuch_database_find_message
- _find_message.argtypes = [NotmuchDatabaseP, c_char_p, POINTER(NotmuchMessageP)]
+ _find_message.argtypes = [NotmuchDatabaseP, c_char_p,
+ POINTER(NotmuchMessageP)]
_find_message.restype = c_uint
"""notmuch_database_find_message_by_filename"""
_find_message_by_filename = nmlib.notmuch_database_find_message_by_filename
- _find_message_by_filename.argtypes = [NotmuchDatabaseP, c_char_p, POINTER(NotmuchMessageP)]
+ _find_message_by_filename.argtypes = [NotmuchDatabaseP, c_char_p,
+ POINTER(NotmuchMessageP)]
_find_message_by_filename.restype = c_uint
"""notmuch_database_get_all_tags"""
else:
self.create(path)
+ def __del__(self):
+ self.close()
+
def _assert_db_is_initialized(self):
"""Raises :exc:`NotInitializedError` if self._db is `None`"""
if self._db is None:
res = Database._create(_str(path), Database.MODE.READ_WRITE)
- if res is None:
+ if not res:
raise NotmuchError(
message="Could not create the specified database")
self._db = res
: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 (possibly after printing an error message on stderr).
+ :exception: Raises :exc:`NotmuchError` in case of any failure
+ (possibly after printing an error message on stderr).
"""
res = Database._open(_str(path), mode)
- if res is None:
+ if not res:
raise NotmuchError(message="Could not open the specified database")
self._db = res
+ _close = nmlib.notmuch_database_close
+ _close.argtypes = [NotmuchDatabaseP]
+ _close.restype = None
+
+ def close(self):
+ """Close and free the notmuch database if needed"""
+ if self._db is not None:
+ self._close(self._db)
+ self._db = None
+
+ def __enter__(self):
+ '''
+ Implements the context manager protocol.
+ '''
+ return self
+
+ def __exit__(self, exc_type, exc_value, traceback):
+ '''
+ Implements the context manager protocol.
+ '''
+ self.close()
+
def get_path(self):
"""Returns the file path of an open database"""
self._assert_db_is_initialized()
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.
+ :exception: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION
+ Xapian exception occurred; atomic section not entered.
*Added in notmuch 0.9*"""
self._assert_db_is_initialized()
"""Returns a :class:`Directory` of path,
(creating it if it does not exist(?))
- .. 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!
+ .. 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!
: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'.
+ 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` with :attr:`STATUS`.FILE_ERROR
return Directory(_str(abs_dirpath), dir_p, self)
_add_message = nmlib.notmuch_database_add_message
- _add_message.argtypes = [NotmuchDatabaseP, c_char_p, POINTER(NotmuchMessageP)]
+ _add_message.argtypes = [NotmuchDatabaseP, c_char_p,
+ POINTER(NotmuchMessageP)]
_add_message.restype = c_uint
def add_message(self, filename, sync_maildir_flags=False):
be added.
"""
self._assert_db_is_initialized()
- msg_p = c_void_p()
+ msg_p = NotmuchMessageP()
status = self._add_message(self._db, _str(filename), byref(msg_p))
if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
removed.
"""
self._assert_db_is_initialized()
- return self._remove_message(self._db, filename)
+ return self._remove_message(self._db, _str(filename))
def find_message(self, msgid):
"""Returns a :class:`Message` as identified by its message ID
the database was not intitialized.
"""
self._assert_db_is_initialized()
- msg_p = c_void_p()
+ msg_p = NotmuchMessageP()
status = Database._find_message(self._db, _str(msgid), byref(msg_p))
if status != STATUS.SUCCESS:
raise NotmuchError(status)
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!
+ .. 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
*Added in notmuch 0.9*"""
self._assert_db_is_initialized()
- msg_p = c_void_p()
+ msg_p = NotmuchMessageP()
status = Database._find_message_by_filename(self._db, _str(filename),
byref(msg_p))
if status != STATUS.SUCCESS:
"""Returns :class:`Tags` with a list of all tags found in the database
:returns: :class:`Tags`
- :execption: :exc:`NotmuchError` with :attr:`STATUS`.NULL_POINTER on error
+ :execption: :exc:`NotmuchError` with :attr:`STATUS`.NULL_POINTER
+ on error
"""
self._assert_db_is_initialized()
tags_p = Database._get_all_tags(self._db)
def __repr__(self):
return "'Notmuch DB " + self.get_path() + "'"
- _close = nmlib.notmuch_database_close
- _close.argtypes = [NotmuchDatabaseP]
- _close.restype = None
-
- def __del__(self):
- """Close and free the notmuch database if needed"""
- if self._db is not None:
- self._close(self._db)
-
def _get_user_default_db(self):
""" Reads a user's notmuch config and returns his db location
Throws a NotmuchError if it cannot find it"""
- from ConfigParser import SafeConfigParser
+ try:
+ # python3.x
+ from configparser import SafeConfigParser
+ except ImportError:
+ # python2.x
+ from ConfigParser import SafeConfigParser
+
config = SafeConfigParser()
conf_f = os.getenv('NOTMUCH_CONFIG',
os.path.expanduser('~/.notmuch-config'))
- config.read(conf_f)
+ config.readfp(codecs.open(conf_f, 'r', 'utf-8'))
if not config.has_option('database', 'path'):
raise NotmuchError(message="No DB path specified"
" and no user default found")
- return config.get('database', 'path').decode('utf-8')
+ return config.get('database', 'path')
@property
def db_p(self):
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:
+ if not query_p:
raise NullPointerError
self._query = query_p
self._assert_query_is_initialized()
threads_p = Query._search_threads(self._query)
- if threads_p is None:
+ if not threads_p:
raise NullPointerError
return Threads(threads_p, self)
self._assert_query_is_initialized()
msgs_p = Query._search_messages(self._query)
- if msgs_p is None:
+ if not msgs_p:
raise NullPointerError
return Messages(msgs_p, self)
_get_child_directories.restype = NotmuchFilenamesP
def _assert_dir_is_initialized(self):
- """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED) if dir_p is None"""
- if self._dir_p is None:
+ """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
+ if dir_p is None"""
+ if not self._dir_p:
raise NotmuchError(STATUS.NOT_INITIALIZED)
def __init__(self, path, dir_p, parent):
and know that it only needs to add files if the mtime of the
directory and files are newer than the stored timestamp.
- .. note:: :meth:`get_mtime` function does not allow the caller
- to distinguish a timestamp of 0 from a non-existent
- timestamp. So don't store a timestamp of 0 unless you are
- comfortable with that.
+ .. note::
+
+ :meth:`get_mtime` function does not allow the caller to
+ distinguish a timestamp of 0 from a non-existent timestamp. So
+ don't store a timestamp of 0 unless you are comfortable with
+ that.
:param mtime: A (time_t) timestamp
:returns: Nothing on success, raising an exception on failure.
_move_to_next.argtypes = [NotmuchFilenamesP]
_move_to_next.restype = None
- def next(self):
- if self._files_p is None:
+ def __next__(self):
+ if not self._files_p:
raise NotmuchError(STATUS.NOT_INITIALIZED)
if not self._valid(self._files_p):
self._files_p = None
raise StopIteration
- file = Filenames._get(self._files_p)
+ file_ = Filenames._get(self._files_p)
self._move_to_next(self._files_p)
- return file
+ return file_.decode('utf-8', 'ignore')
+ next = __next__ # python2.x iterator protocol compatibility
def __len__(self):
"""len(:class:`Filenames`) returns the number of contained files
- .. note:: As this iterates over the files, we will not be able to
- iterate over them again! So this will fail::
+ .. note::
+
+ As this iterates over the files, we will not be able to
+ iterate over them again! So this will fail::
#THIS FAILS
files = Database().get_directory('').get_child_files()
- if len(files) > 0: #this 'exhausts' msgs
- # next line raises NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)!!!
+ if len(files) > 0: # this 'exhausts' msgs
+ # next line raises
+ # NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
for file in files: print file
"""
- if self._files_p is None:
+ if not self._files_p:
raise NotmuchError(STATUS.NOT_INITIALIZED)
i = 0