X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=bindings%2Fpython%2Fnotmuch%2Fdatabase.py;h=8fb507fafc1bfad1b246775470129061e2a1ab0c;hb=3771832b013012e408696897215fd0edde7dce37;hp=82cb803a0f2fd6687bc274f55570512731f2b147;hpb=fcf19ad029913e88558a21135feb0b5e1b33cef3;p=notmuch
diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py
index 82cb803a..8fb507fa 100644
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -12,33 +12,38 @@ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
-along with notmuch. If not, see .
+along with notmuch. If not, see .
-Copyright 2010 Sebastian Spaeth '
+Copyright 2010 Sebastian Spaeth
"""
import os
import codecs
-from ctypes import c_char_p, c_void_p, c_uint, c_long, byref, POINTER
-from notmuch.globals import (
+import warnings
+from ctypes import c_char_p, c_void_p, c_uint, byref, POINTER
+from .compat import SafeConfigParser
+from .globals import (
nmlib,
- STATUS,
- FileError,
- NotmuchError,
- NullPointerError,
- NotInitializedError,
- ReadOnlyDatabaseError,
Enum,
_str,
+ NotmuchConfigListP,
NotmuchDatabaseP,
NotmuchDirectoryP,
+ NotmuchIndexoptsP,
NotmuchMessageP,
NotmuchTagsP,
- NotmuchFilenamesP
)
-from notmuch.message import Message
-from notmuch.tag import Tags
+from .errors import (
+ STATUS,
+ FileError,
+ NotmuchError,
+ NullPointerError,
+ NotInitializedError,
+)
+from .message import Message
+from .tag import Tags
from .query import Query
+from .directory import Directory
class Database(object):
"""The :class:`Database` is the highest-level object that notmuch
@@ -54,21 +59,14 @@ class Database(object):
:class:`Database` objects implement the context manager protocol
so you can use the :keyword:`with` statement to ensure that the
- database is properly closed.
+ database is properly closed. See :meth:`close` for more
+ information.
.. note::
Any function in this class can and will throw an
- :exc:`NotInitializedError` if the database was not intitialized
+ :exc:`NotInitializedError` if the database was not initialized
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.
"""
_std_db_path = None
"""Class attribute to cache user's default database"""
@@ -76,10 +74,13 @@ class Database(object):
MODE = Enum(['READ_ONLY', 'READ_WRITE'])
"""Constants: Mode in which to open the database"""
+ DECRYPTION_POLICY = Enum(['FALSE', 'TRUE', 'AUTO', 'NOSTASH'])
+ """Constants: policies for decrypting messages during indexing"""
+
"""notmuch_database_get_directory"""
_get_directory = nmlib.notmuch_database_get_directory
- _get_directory.argtypes = [NotmuchDatabaseP, c_char_p]
- _get_directory.restype = NotmuchDirectoryP
+ _get_directory.argtypes = [NotmuchDatabaseP, c_char_p, POINTER(NotmuchDirectoryP)]
+ _get_directory.restype = c_uint
"""notmuch_database_get_path"""
_get_path = nmlib.notmuch_database_get_path
@@ -91,10 +92,15 @@ class Database(object):
_get_version.argtypes = [NotmuchDatabaseP]
_get_version.restype = c_uint
+ """notmuch_database_get_revision"""
+ _get_revision = nmlib.notmuch_database_get_revision
+ _get_revision.argtypes = [NotmuchDatabaseP, POINTER(c_char_p)]
+ _get_revision.restype = c_uint
+
"""notmuch_database_open"""
_open = nmlib.notmuch_database_open
- _open.argtypes = [c_char_p, c_uint]
- _open.restype = NotmuchDatabaseP
+ _open.argtypes = [c_char_p, c_uint, POINTER(NotmuchDatabaseP)]
+ _open.restype = c_uint
"""notmuch_database_upgrade"""
_upgrade = nmlib.notmuch_database_upgrade
@@ -120,8 +126,8 @@ class Database(object):
"""notmuch_database_create"""
_create = nmlib.notmuch_database_create
- _create.argtypes = [c_char_p]
- _create.restype = NotmuchDatabaseP
+ _create.argtypes = [c_char_p, POINTER(NotmuchDatabaseP)]
+ _create.restype = c_uint
def __init__(self, path = None, create = False,
mode = MODE.READ_ONLY):
@@ -159,8 +165,15 @@ class Database(object):
else:
self.create(path)
+ _destroy = nmlib.notmuch_database_destroy
+ _destroy.argtypes = [NotmuchDatabaseP]
+ _destroy.restype = c_uint
+
def __del__(self):
- self.close()
+ if self._db:
+ status = self._destroy(self._db)
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)
def _assert_db_is_initialized(self):
"""Raises :exc:`NotInitializedError` if self._db is `None`"""
@@ -182,16 +195,17 @@ class Database(object):
:raises: :exc:`NotmuchError` in case of any failure
(possibly after printing an error message on stderr).
"""
- if self._db is not None:
+ if self._db:
raise NotmuchError(message="Cannot create db, this Database() "
"already has an open one.")
- res = Database._create(_str(path), Database.MODE.READ_WRITE)
+ db = NotmuchDatabaseP()
+ status = Database._create(_str(path), byref(db))
- if not res:
- raise NotmuchError(
- message="Could not create the specified database")
- self._db = res
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)
+ self._db = db
+ return status
def open(self, path, mode=0):
"""Opens an existing database
@@ -205,21 +219,33 @@ class Database(object):
:raises: Raises :exc:`NotmuchError` in case of any failure
(possibly after printing an error message on stderr).
"""
- res = Database._open(_str(path), mode)
+ db = NotmuchDatabaseP()
+ status = Database._open(_str(path), mode, byref(db))
- if not res:
- raise NotmuchError(message="Could not open the specified database")
- self._db = res
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)
+ self._db = db
+ return status
_close = nmlib.notmuch_database_close
_close.argtypes = [NotmuchDatabaseP]
- _close.restype = None
+ _close.restype = c_uint
def close(self):
- """Close and free the notmuch database if needed"""
- if self._db is not None:
- self._close(self._db)
- self._db = None
+ '''
+ 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.
+ '''
+ if self._db:
+ status = self._close(self._db)
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)
def __enter__(self):
'''
@@ -246,6 +272,17 @@ class Database(object):
self._assert_db_is_initialized()
return Database._get_version(self._db)
+ def get_revision (self):
+ """Returns the committed database revision and UUID
+
+ :returns: (revision, uuid) The database revision as a positive integer
+ and the UUID of the database.
+ """
+ self._assert_db_is_initialized()
+ uuid = c_char_p ()
+ revision = Database._get_revision(self._db, byref (uuid))
+ return (revision, uuid.value.decode ('utf-8'))
+
_needs_upgrade = nmlib.notmuch_database_needs_upgrade
_needs_upgrade.argtypes = [NotmuchDatabaseP]
_needs_upgrade.restype = bool
@@ -254,7 +291,7 @@ class Database(object):
"""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`,
+ database (:meth:`index_file`,
:meth:`Message.add_tag`, :meth:`Directory.set_mtime`,
etc.) will work unless :meth:`upgrade` is called successfully first.
@@ -280,7 +317,7 @@ class Database(object):
"""
self._assert_db_is_initialized()
status = Database._upgrade(self._db, None, None)
- #TODO: catch exceptions, document return values and etc
+ # TODO: catch exceptions, document return values and etc
return status
_begin_atomic = nmlib.notmuch_database_begin_atomic
@@ -335,7 +372,6 @@ class Database(object):
def get_directory(self, path):
"""Returns a :class:`Directory` of path,
- (creating it if it does not exist(?))
:param path: An unicode string containing the path relative to the path
of database (see :meth:`get_path`), or else should be an absolute
@@ -343,18 +379,9 @@ class Database(object):
:returns: :class:`Directory` or raises an exception.
:raises: :exc:`FileError` if path is not relative database or absolute
with initial components same as database.
- :raises: :exc:`ReadOnlyDatabaseError` if the database has not been
- opened in read-write mode
"""
self._assert_db_is_initialized()
- # work around libnotmuch calling exit(3), see
- # id:20120221002921.8534.57091@thinkbox.jade-hamburg.de
- # TODO: remove once this issue is resolved
- if self.mode != Database.MODE.READ_WRITE:
- raise ReadOnlyDatabaseError('The database has to be opened in '
- 'read-write mode for get_directory')
-
# sanity checking if path is valid, and make path absolute
if path and path[0] == os.sep:
# we got an absolute path
@@ -367,17 +394,36 @@ class Database(object):
#we got a relative path, make it absolute
abs_dirpath = os.path.abspath(os.path.join(self.get_path(), path))
- dir_p = Database._get_directory(self._db, _str(path))
+ dir_p = NotmuchDirectoryP()
+ status = Database._get_directory(self._db, _str(path), byref(dir_p))
+
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)
+ if not dir_p:
+ return None
# return the Directory, init it with the absolute path
return Directory(abs_dirpath, dir_p, self)
- _add_message = nmlib.notmuch_database_add_message
- _add_message.argtypes = [NotmuchDatabaseP, c_char_p,
+ _get_default_indexopts = nmlib.notmuch_database_get_default_indexopts
+ _get_default_indexopts.argtypes = [NotmuchDatabaseP]
+ _get_default_indexopts.restype = NotmuchIndexoptsP
+
+ _indexopts_set_decrypt_policy = nmlib.notmuch_indexopts_set_decrypt_policy
+ _indexopts_set_decrypt_policy.argtypes = [NotmuchIndexoptsP, c_uint]
+ _indexopts_set_decrypt_policy.restype = None
+
+ _indexopts_destroy = nmlib.notmuch_indexopts_destroy
+ _indexopts_destroy.argtypes = [NotmuchIndexoptsP]
+ _indexopts_destroy.restype = None
+
+ _index_file = nmlib.notmuch_database_index_file
+ _index_file.argtypes = [NotmuchDatabaseP, c_char_p,
+ c_void_p,
POINTER(NotmuchMessageP)]
- _add_message.restype = c_uint
+ _index_file.restype = c_uint
- def add_message(self, filename, sync_maildir_flags=False):
+ def index_file(self, filename, sync_maildir_flags=False, decrypt_policy=None):
"""Adds a new message to the database
:param filename: should be a path relative to the path of the
@@ -398,6 +444,23 @@ class Database(object):
API. You might want to look into the underlying method
:meth:`Message.maildir_flags_to_tags`.
+ :param decrypt_policy: If the message contains any encrypted
+ parts, and decrypt_policy is set to
+ :attr:`DECRYPTION_POLICY`.TRUE, notmuch will try to
+ decrypt the message and index the cleartext, stashing any
+ discovered session keys. If it is set to
+ :attr:`DECRYPTION_POLICY`.FALSE, it will never try to
+ decrypt during indexing. If it is set to
+ :attr:`DECRYPTION_POLICY`.AUTO, then it will try to use
+ any stashed session keys it knows about, but will not try
+ to access the user's secret keys.
+ :attr:`DECRYPTION_POLICY`.NOSTASH behaves the same as
+ :attr:`DECRYPTION_POLICY`.TRUE except that no session keys
+ are stashed in the database. If decrypt_policy is set to
+ None (the default), then the database itself will decide
+ whether to decrypt, based on the `index.decrypt`
+ configuration setting (see notmuch-config(1)).
+
:returns: On success, we return
1) a :class:`Message` object that can be used for things
@@ -428,7 +491,15 @@ class Database(object):
"""
self._assert_db_is_initialized()
msg_p = NotmuchMessageP()
- status = self._add_message(self._db, _str(filename), byref(msg_p))
+ indexopts = c_void_p(None)
+ if decrypt_policy is not None:
+ indexopts = self._get_default_indexopts(self._db)
+ self._indexopts_set_decrypt_policy(indexopts, decrypt_policy)
+
+ status = self._index_file(self._db, _str(filename), indexopts, byref(msg_p))
+
+ if indexopts:
+ self._indexopts_destroy(indexopts)
if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
raise NotmuchError(status)
@@ -440,6 +511,14 @@ class Database(object):
msg.maildir_flags_to_tags()
return (msg, status)
+ def add_message(self, filename, sync_maildir_flags=False):
+ """Deprecated alias for :meth:`index_file`
+ """
+ warnings.warn(
+ "This function is deprecated and will be removed in the future, use index_file.", DeprecationWarning)
+
+ return self.index_file(filename, sync_maildir_flags=sync_maildir_flags)
+
_remove_message = nmlib.notmuch_database_remove_message
_remove_message.argtypes = [NotmuchDatabaseP, c_char_p]
_remove_message.restype = c_uint
@@ -472,7 +551,10 @@ class Database(object):
removed.
"""
self._assert_db_is_initialized()
- return self._remove_message(self._db, _str(filename))
+ status = self._remove_message(self._db, _str(filename))
+ if status not in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
+ raise NotmuchError(status)
+ return status
def find_message(self, msgid):
"""Returns a :class:`Message` as identified by its message ID
@@ -484,7 +566,7 @@ class Database(object):
:returns: :class:`Message` or `None` if no message is found.
:raises:
:exc:`OutOfMemoryError`
- If an Out-of-memory occured while constructing the message.
+ If an Out-of-memory occurred while constructing the message.
:exc:`XapianError`
In case of a Xapian Exception. These exceptions
include "Database modified" situations, e.g. when the
@@ -492,7 +574,7 @@ class Database(object):
in the meantime. In this case, you should close and
reopen the database and retry.
:exc:`NotInitializedError` if
- the database was not intitialized.
+ the database was not initialized.
"""
self._assert_db_is_initialized()
msg_p = NotmuchMessageP()
@@ -504,31 +586,25 @@ class Database(object):
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 if no message is found with the given
filename.
- :raises:
- :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.
+ :raises: :exc:`OutOfMemoryError` if an Out-of-memory occurred while
+ constructing the message.
+ :raises: :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.
+ :raises: :exc:`NotInitializedError` if the database was not
+ initialized.
*Added in notmuch 0.9*"""
self._assert_db_is_initialized()
+
msg_p = NotmuchMessageP()
status = Database._find_message_by_filename(self._db, _str(filename),
byref(msg_p))
@@ -540,12 +616,12 @@ class Database(object):
"""Returns :class:`Tags` with a list of all tags found in the database
:returns: :class:`Tags`
- :execption: :exc:`NotmuchError` with :attr:`STATUS`.NULL_POINTER
+ :exception: :exc:`NotmuchError` with :attr:`STATUS`.NULL_POINTER
on error
"""
self._assert_db_is_initialized()
tags_p = Database._get_all_tags(self._db)
- if tags_p == None:
+ if not tags_p:
raise NullPointerError()
return Tags(tags_p, self)
@@ -569,6 +645,22 @@ class Database(object):
"""
return Query(self, querystring)
+ """notmuch_database_status_string"""
+ _status_string = nmlib.notmuch_database_status_string
+ _status_string.argtypes = [NotmuchDatabaseP]
+ _status_string.restype = c_char_p
+
+ def status_string(self):
+ """Returns the status string of the database
+
+ This is sometimes used for additional error reporting
+ """
+ self._assert_db_is_initialized()
+ s = Database._status_string(self._db)
+ if s:
+ return s.decode('utf-8', 'ignore')
+ return s
+
def __repr__(self):
return "'Notmuch DB " + self.get_path() + "'"
@@ -576,13 +668,6 @@ class Database(object):
""" Reads a user's notmuch config and returns his db location
Throws a NotmuchError if it cannot find it"""
- 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'))
@@ -590,248 +675,115 @@ class Database(object):
if not config.has_option('database', 'path'):
raise NotmuchError(message="No DB path specified"
" and no user default found")
- return config.get('database', 'path')
-
- @property
- def db_p(self):
- """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 Directory(object):
- """Represents a directory entry in the notmuch directory
-
- Modifying attributes of this object will modify the
- database, not the real directory attributes.
-
- The Directory object is usually derived from another object
- e.g. via :meth:`Database.get_directory`, and will automatically be
- become invalid whenever that parent is deleted. You should
- therefore initialized this object handing it a reference to the
- parent, preventing the parent from automatically being garbage
- collected.
- """
-
- """notmuch_directory_get_mtime"""
- _get_mtime = nmlib.notmuch_directory_get_mtime
- _get_mtime.argtypes = [NotmuchDirectoryP]
- _get_mtime.restype = c_long
-
- """notmuch_directory_set_mtime"""
- _set_mtime = nmlib.notmuch_directory_set_mtime
- _set_mtime.argtypes = [NotmuchDirectoryP, c_long]
- _set_mtime.restype = c_uint
-
- """notmuch_directory_get_child_files"""
- _get_child_files = nmlib.notmuch_directory_get_child_files
- _get_child_files.argtypes = [NotmuchDirectoryP]
- _get_child_files.restype = NotmuchFilenamesP
-
- """notmuch_directory_get_child_directories"""
- _get_child_directories = nmlib.notmuch_directory_get_child_directories
- _get_child_directories.argtypes = [NotmuchDirectoryP]
- _get_child_directories.restype = NotmuchFilenamesP
-
- def _assert_dir_is_initialized(self):
- """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
- if dir_p is None"""
- if not self._dir_p:
- raise NotInitializedError()
+ db_path = config.get('database', 'path')
+ if not os.path.isabs(db_path):
+ db_path = os.path.expanduser(os.path.join("~", db_path))
+ return db_path
+
+ """notmuch_database_get_config"""
+ _get_config = nmlib.notmuch_database_get_config
+ _get_config.argtypes = [NotmuchDatabaseP, c_char_p, POINTER(c_char_p)]
+ _get_config.restype = c_uint
+
+ def get_config(self, key):
+ """Return the value of the given config key.
+
+ Note that only config values that are stored in the database are
+ searched and returned. The config file is not read.
+
+ :param key: the config key under which a value should be looked up, it
+ should probably be in the form "section.key"
+ :type key: str
+ :returns: the config value or the empty string if no value is present
+ for that key
+ :rtype: str
+ :raises: :exc:`NotmuchError` in case of failure.
- def __init__(self, path, dir_p, parent):
- """
- :param path: The absolute path of the directory object.
- :param dir_p: The pointer to an internal notmuch_directory_t object.
- :param parent: The object this Directory is derived from
- (usually a :class:`Database`). We do not directly use
- this, but store a reference to it as long as
- this Directory object lives. This keeps the
- parent object alive.
"""
- self._path = path
- self._dir_p = dir_p
- self._parent = parent
-
- def set_mtime(self, mtime):
- """Sets the mtime value of this directory in the database
-
- The intention is for the caller to use the mtime to allow efficient
- identification of new messages to be added to the database. The
- recommended usage is as follows:
-
- * Read the mtime of a directory from the filesystem
-
- * Call :meth:`Database.add_message` for all mail files in
- the directory
-
- * Call notmuch_directory_set_mtime with the mtime read from the
- filesystem. Then, when wanting to check for updates to the
- directory in the future, the client can call :meth:`get_mtime`
- 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.
-
- :param mtime: A (time_t) timestamp
- :raises: :exc:`XapianError` a Xapian exception occurred, mtime
- not stored
- :raises: :exc:`ReadOnlyDatabaseError` the database was opened
- in read-only mode so directory mtime cannot be modified
- :raises: :exc:`NotInitializedError` the directory object has not
- been initialized
- """
- self._assert_dir_is_initialized()
- status = Directory._set_mtime(self._dir_p, mtime)
-
+ self._assert_db_is_initialized()
+ return_string = c_char_p()
+ status = self._get_config(self._db, _str(key), byref(return_string))
if status != STATUS.SUCCESS:
raise NotmuchError(status)
+ return return_string.value.decode('utf-8')
- def get_mtime(self):
- """Gets the mtime value of this directory in the database
-
- Retrieves a previously stored mtime for this directory.
-
- :param mtime: A (time_t) timestamp
- :raises: :exc:`NotmuchError`:
+ """notmuch_database_get_config_list"""
+ _get_config_list = nmlib.notmuch_database_get_config_list
+ _get_config_list.argtypes = [NotmuchDatabaseP, c_char_p,
+ POINTER(NotmuchConfigListP)]
+ _get_config_list.restype = c_uint
- :attr:`STATUS`.NOT_INITIALIZED
- The directory has not been initialized
- """
- self._assert_dir_is_initialized()
- return Directory._get_mtime(self._dir_p)
-
- # Make mtime attribute a property of Directory()
- mtime = property(get_mtime, set_mtime, doc="""Property that allows getting
- and setting of the Directory *mtime* (read-write)
+ _config_list_valid = nmlib.notmuch_config_list_valid
+ _config_list_valid.argtypes = [NotmuchConfigListP]
+ _config_list_valid.restype = bool
- See :meth:`get_mtime` and :meth:`set_mtime` for usage and
- possible exceptions.""")
+ _config_list_key = nmlib.notmuch_config_list_key
+ _config_list_key.argtypes = [NotmuchConfigListP]
+ _config_list_key.restype = c_char_p
- def get_child_files(self):
- """Gets a Filenames iterator listing all the filenames of
- messages in the database within the given directory.
-
- The returned filenames will be the basename-entries only (not
- complete paths.
- """
- self._assert_dir_is_initialized()
- files_p = Directory._get_child_files(self._dir_p)
- return Filenames(files_p, self)
-
- def get_child_directories(self):
- """Gets a :class:`Filenames` iterator listing all the filenames of
- sub-directories in the database within the given directory
-
- The returned filenames will be the basename-entries only (not
- complete paths.
- """
- self._assert_dir_is_initialized()
- files_p = Directory._get_child_directories(self._dir_p)
- return Filenames(files_p, self)
+ _config_list_value = nmlib.notmuch_config_list_value
+ _config_list_value.argtypes = [NotmuchConfigListP]
+ _config_list_value.restype = c_char_p
- @property
- def path(self):
- """Returns the absolute path of this Directory (read-only)"""
- return self._path
+ _config_list_move_to_next = nmlib.notmuch_config_list_move_to_next
+ _config_list_move_to_next.argtypes = [NotmuchConfigListP]
+ _config_list_move_to_next.restype = None
- def __repr__(self):
- """Object representation"""
- return "" % self._path
+ _config_list_destroy = nmlib.notmuch_config_list_destroy
+ _config_list_destroy.argtypes = [NotmuchConfigListP]
+ _config_list_destroy.restype = None
- _destroy = nmlib.notmuch_directory_destroy
- _destroy.argtypes = [NotmuchDirectoryP]
- _destroy.argtypes = None
+ def get_configs(self, prefix=''):
+ """Return a generator of key, value pairs where the start of key
+ matches the given prefix
- def __del__(self):
- """Close and free the Directory"""
- if self._dir_p is not None:
- self._destroy(self._dir_p)
+ Note that only config values that are stored in the database are
+ searched and returned. The config file is not read. If no `prefix` is
+ given all config values are returned.
+ This could be used to get all named queries into a dict for example::
-class Filenames(object):
- """An iterator over File- or Directory names stored in the database"""
+ queries = {k[6:]: v for k, v in db.get_configs('query.')}
- #notmuch_filenames_get
- _get = nmlib.notmuch_filenames_get
- _get.argtypes = [NotmuchFilenamesP]
- _get.restype = c_char_p
+ :param prefix: a string by which the keys should be selected
+ :type prefix: str
+ :yields: all key-value pairs where `prefix` matches the beginning
+ of the key
+ :ytype: pairs of str
+ :raises: :exc:`NotmuchError` in case of failure.
- def __init__(self, files_p, parent):
"""
- :param files_p: The pointer to an internal notmuch_filenames_t object.
- :param parent: The object this Directory is derived from
- (usually a Directory()). We do not directly use
- this, but store a reference to it as long as
- this Directory object lives. This keeps the
- parent object alive.
- """
- self._files_p = files_p
- self._parent = parent
-
- def __iter__(self):
- """ Make Filenames an iterator """
- return self
-
- _valid = nmlib.notmuch_filenames_valid
- _valid.argtypes = [NotmuchFilenamesP]
- _valid.restype = bool
-
- _move_to_next = nmlib.notmuch_filenames_move_to_next
- _move_to_next.argtypes = [NotmuchFilenamesP]
- _move_to_next.restype = None
-
- def __next__(self):
- if not self._files_p:
- raise NotInitializedError()
-
- if not self._valid(self._files_p):
- self._files_p = None
- raise StopIteration
+ self._assert_db_is_initialized()
+ config_list_p = NotmuchConfigListP()
+ status = self._get_config_list(self._db, _str(prefix),
+ byref(config_list_p))
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)
+ while self._config_list_valid(config_list_p):
+ key = self._config_list_key(config_list_p).decode('utf-8')
+ value = self._config_list_value(config_list_p).decode('utf-8')
+ yield key, value
+ self._config_list_move_to_next(config_list_p)
- file_ = Filenames._get(self._files_p)
- self._move_to_next(self._files_p)
- return file_.decode('utf-8', 'ignore')
- next = __next__ # python2.x iterator protocol compatibility
+ """notmuch_database_set_config"""
+ _set_config = nmlib.notmuch_database_set_config
+ _set_config.argtypes = [NotmuchDatabaseP, c_char_p, c_char_p]
+ _set_config.restype = c_uint
- def __len__(self):
- """len(:class:`Filenames`) returns the number of contained files
+ def set_config(self, key, value):
+ """Set a config value in the notmuch database.
- .. note::
+ If an empty string is provided as `value` the `key` is unset!
- As this iterates over the files, we will not be able to
- iterate over them again! So this will fail::
+ :param key: the key to set
+ :type key: str
+ :param value: the value to store under `key`
+ :type value: str
+ :returns: None
+ :raises: :exc:`NotmuchError` in case of failure.
- #THIS FAILS
- files = Database().get_directory('').get_child_files()
- if len(files) > 0: # this 'exhausts' msgs
- # next line raises
- # NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
- for file in files: print file
"""
- if not self._files_p:
- raise NotInitializedError()
-
- i = 0
- while self._valid(self._files_p):
- self._move_to_next(self._files_p)
- i += 1
- self._files_p = None
- return i
-
- _destroy = nmlib.notmuch_filenames_destroy
- _destroy.argtypes = [NotmuchFilenamesP]
- _destroy.restype = None
-
- def __del__(self):
- """Close and free Filenames"""
- if self._files_p is not None:
- self._destroy(self._files_p)
+ self._assert_db_is_initialized()
+ status = self._set_config(self._db, _str(key), _str(value))
+ if status != STATUS.SUCCESS:
+ raise NotmuchError(status)