]> git.cworth.org Git - notmuch/blob - bindings/python/notmuch/database.py
Merge tag 'debian/0.27-1' into debian/stretch-backports
[notmuch] / bindings / python / notmuch / database.py
1 """
2 This file is part of notmuch.
3
4 Notmuch is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by the
6 Free Software Foundation, either version 3 of the License, or (at your
7 option) any later version.
8
9 Notmuch is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
12 for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with notmuch.  If not, see <https://www.gnu.org/licenses/>.
16
17 Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>
18 """
19
20 import os
21 import codecs
22 import warnings
23 from ctypes import c_char_p, c_void_p, c_uint, byref, POINTER
24 from .compat import SafeConfigParser
25 from .globals import (
26     nmlib,
27     Enum,
28     _str,
29     NotmuchConfigListP,
30     NotmuchDatabaseP,
31     NotmuchDirectoryP,
32     NotmuchIndexoptsP,
33     NotmuchMessageP,
34     NotmuchTagsP,
35 )
36 from .errors import (
37     STATUS,
38     FileError,
39     NotmuchError,
40     NullPointerError,
41     NotInitializedError,
42 )
43 from .message import Message
44 from .tag import Tags
45 from .query import Query
46 from .directory import Directory
47
48 class Database(object):
49     """The :class:`Database` is the highest-level object that notmuch
50     provides. It references a notmuch database, and can be opened in
51     read-only or read-write mode. A :class:`Query` can be derived from
52     or be applied to a specific database to find messages. Also adding
53     and removing messages to the database happens via this
54     object. Modifications to the database are not atmic by default (see
55     :meth:`begin_atomic`) and once a database has been modified, all
56     other database objects pointing to the same data-base will throw an
57     :exc:`XapianError` as the underlying database has been
58     modified. Close and reopen the database to continue working with it.
59
60     :class:`Database` objects implement the context manager protocol
61     so you can use the :keyword:`with` statement to ensure that the
62     database is properly closed. See :meth:`close` for more
63     information.
64
65     .. note::
66
67         Any function in this class can and will throw an
68         :exc:`NotInitializedError` if the database was not intitialized
69         properly.
70     """
71     _std_db_path = None
72     """Class attribute to cache user's default database"""
73
74     MODE = Enum(['READ_ONLY', 'READ_WRITE'])
75     """Constants: Mode in which to open the database"""
76
77     DECRYPTION_POLICY = Enum(['FALSE', 'TRUE', 'AUTO', 'NOSTASH'])
78     """Constants: policies for decrypting messages during indexing"""
79
80     """notmuch_database_get_directory"""
81     _get_directory = nmlib.notmuch_database_get_directory
82     _get_directory.argtypes = [NotmuchDatabaseP, c_char_p, POINTER(NotmuchDirectoryP)]
83     _get_directory.restype = c_uint
84
85     """notmuch_database_get_path"""
86     _get_path = nmlib.notmuch_database_get_path
87     _get_path.argtypes = [NotmuchDatabaseP]
88     _get_path.restype = c_char_p
89
90     """notmuch_database_get_version"""
91     _get_version = nmlib.notmuch_database_get_version
92     _get_version.argtypes = [NotmuchDatabaseP]
93     _get_version.restype = c_uint
94
95     """notmuch_database_get_revision"""
96     _get_revision = nmlib.notmuch_database_get_revision
97     _get_revision.argtypes = [NotmuchDatabaseP, POINTER(c_char_p)]
98     _get_revision.restype = c_uint
99
100     """notmuch_database_open"""
101     _open = nmlib.notmuch_database_open
102     _open.argtypes = [c_char_p, c_uint, POINTER(NotmuchDatabaseP)]
103     _open.restype = c_uint
104
105     """notmuch_database_upgrade"""
106     _upgrade = nmlib.notmuch_database_upgrade
107     _upgrade.argtypes = [NotmuchDatabaseP, c_void_p, c_void_p]
108     _upgrade.restype = c_uint
109
110     """ notmuch_database_find_message"""
111     _find_message = nmlib.notmuch_database_find_message
112     _find_message.argtypes = [NotmuchDatabaseP, c_char_p,
113                               POINTER(NotmuchMessageP)]
114     _find_message.restype = c_uint
115
116     """notmuch_database_find_message_by_filename"""
117     _find_message_by_filename = nmlib.notmuch_database_find_message_by_filename
118     _find_message_by_filename.argtypes = [NotmuchDatabaseP, c_char_p,
119                                           POINTER(NotmuchMessageP)]
120     _find_message_by_filename.restype = c_uint
121
122     """notmuch_database_get_all_tags"""
123     _get_all_tags = nmlib.notmuch_database_get_all_tags
124     _get_all_tags.argtypes = [NotmuchDatabaseP]
125     _get_all_tags.restype = NotmuchTagsP
126
127     """notmuch_database_create"""
128     _create = nmlib.notmuch_database_create
129     _create.argtypes = [c_char_p, POINTER(NotmuchDatabaseP)]
130     _create.restype = c_uint
131
132     def __init__(self, path = None, create = False,
133                  mode = MODE.READ_ONLY):
134         """If *path* is `None`, we will try to read a users notmuch
135         configuration and use his configured database. The location of the
136         configuration file can be specified through the environment variable
137         *NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
138
139         If *create* is `True`, the database will always be created in
140         :attr:`MODE`.READ_WRITE mode. Default mode for opening is READ_ONLY.
141
142         :param path:   Directory to open/create the database in (see
143                        above for behavior if `None`)
144         :type path:    `str` or `None`
145         :param create: Pass `False` to open an existing, `True` to create a new
146                        database.
147         :type create:  bool
148         :param mode:   Mode to open a database in. Is always
149                        :attr:`MODE`.READ_WRITE when creating a new one.
150         :type mode:    :attr:`MODE`
151         :raises: :exc:`NotmuchError` or derived exception in case of
152             failure.
153         """
154         self._db = None
155         self.mode = mode
156         if path is None:
157             # no path specified. use a user's default database
158             if Database._std_db_path is None:
159                 #the following line throws a NotmuchError if it fails
160                 Database._std_db_path = self._get_user_default_db()
161             path = Database._std_db_path
162
163         if create == False:
164             self.open(path, mode)
165         else:
166             self.create(path)
167
168     _destroy = nmlib.notmuch_database_destroy
169     _destroy.argtypes = [NotmuchDatabaseP]
170     _destroy.restype = c_uint
171
172     def __del__(self):
173         if self._db:
174             status = self._destroy(self._db)
175             if status != STATUS.SUCCESS:
176                 raise NotmuchError(status)
177
178     def _assert_db_is_initialized(self):
179         """Raises :exc:`NotInitializedError` if self._db is `None`"""
180         if not self._db:
181             raise NotInitializedError()
182
183     def create(self, path):
184         """Creates a new notmuch database
185
186         This function is used by __init__() and usually does not need
187         to be called directly. It wraps the underlying
188         *notmuch_database_create* function and creates a new notmuch
189         database at *path*. It will always return a database in :attr:`MODE`
190         .READ_WRITE mode as creating an empty database for
191         reading only does not make a great deal of sense.
192
193         :param path: A directory in which we should create the database.
194         :type path: str
195         :raises: :exc:`NotmuchError` in case of any failure
196                     (possibly after printing an error message on stderr).
197         """
198         if self._db:
199             raise NotmuchError(message="Cannot create db, this Database() "
200                                        "already has an open one.")
201
202         db = NotmuchDatabaseP()
203         status = Database._create(_str(path), byref(db))
204
205         if status != STATUS.SUCCESS:
206             raise NotmuchError(status)
207         self._db = db
208         return status
209
210     def open(self, path, mode=0):
211         """Opens an existing database
212
213         This function is used by __init__() and usually does not need
214         to be called directly. It wraps the underlying
215         *notmuch_database_open* function.
216
217         :param status: Open the database in read-only or read-write mode
218         :type status:  :attr:`MODE`
219         :raises: Raises :exc:`NotmuchError` in case of any failure
220                     (possibly after printing an error message on stderr).
221         """
222         db = NotmuchDatabaseP()
223         status = Database._open(_str(path), mode, byref(db))
224
225         if status != STATUS.SUCCESS:
226             raise NotmuchError(status)
227         self._db = db
228         return status
229
230     _close = nmlib.notmuch_database_close
231     _close.argtypes = [NotmuchDatabaseP]
232     _close.restype = c_uint
233
234     def close(self):
235         '''
236         Closes the notmuch database.
237
238         .. warning::
239
240             This function closes the notmuch database. From that point
241             on every method invoked on any object ever derived from
242             the closed database may cease to function and raise a
243             NotmuchError.
244         '''
245         if self._db:
246             status = self._close(self._db)
247             if status != STATUS.SUCCESS:
248                 raise NotmuchError(status)
249
250     def __enter__(self):
251         '''
252         Implements the context manager protocol.
253         '''
254         return self
255
256     def __exit__(self, exc_type, exc_value, traceback):
257         '''
258         Implements the context manager protocol.
259         '''
260         self.close()
261
262     def get_path(self):
263         """Returns the file path of an open database"""
264         self._assert_db_is_initialized()
265         return Database._get_path(self._db).decode('utf-8')
266
267     def get_version(self):
268         """Returns the database format version
269
270         :returns: The database version as positive integer
271         """
272         self._assert_db_is_initialized()
273         return Database._get_version(self._db)
274
275     def get_revision (self):
276         """Returns the committed database revison and UUID
277
278         :returns: (revison, uuid) The database revision as a positive integer
279         and the UUID of the database.
280         """
281         self._assert_db_is_initialized()
282         uuid = c_char_p ()
283         revision = Database._get_revision(self._db, byref (uuid))
284         return (revision, uuid.value.decode ('utf-8'))
285
286     _needs_upgrade = nmlib.notmuch_database_needs_upgrade
287     _needs_upgrade.argtypes = [NotmuchDatabaseP]
288     _needs_upgrade.restype = bool
289
290     def needs_upgrade(self):
291         """Does this database need to be upgraded before writing to it?
292
293         If this function returns `True` then no functions that modify the
294         database (:meth:`index_file`,
295         :meth:`Message.add_tag`, :meth:`Directory.set_mtime`,
296         etc.) will work unless :meth:`upgrade` is called successfully first.
297
298         :returns: `True` or `False`
299         """
300         self._assert_db_is_initialized()
301         return self._needs_upgrade(self._db)
302
303     def upgrade(self):
304         """Upgrades the current database
305
306         After opening a database in read-write mode, the client should
307         check if an upgrade is needed (notmuch_database_needs_upgrade) and
308         if so, upgrade with this function before making any modifications.
309
310         NOT IMPLEMENTED: The optional progress_notify callback can be
311         used by the caller to provide progress indication to the
312         user. If non-NULL it will be called periodically with
313         'progress' as a floating-point value in the range of [0.0..1.0]
314         indicating the progress made so far in the upgrade process.
315
316         :TODO: catch exceptions, document return values and etc...
317         """
318         self._assert_db_is_initialized()
319         status = Database._upgrade(self._db, None, None)
320         # TODO: catch exceptions, document return values and etc
321         return status
322
323     _begin_atomic = nmlib.notmuch_database_begin_atomic
324     _begin_atomic.argtypes = [NotmuchDatabaseP]
325     _begin_atomic.restype = c_uint
326
327     def begin_atomic(self):
328         """Begin an atomic database operation
329
330         Any modifications performed between a successful
331         :meth:`begin_atomic` and a :meth:`end_atomic` will be applied to
332         the database atomically.  Note that, unlike a typical database
333         transaction, this only ensures atomicity, not durability;
334         neither begin nor end necessarily flush modifications to disk.
335
336         :returns: :attr:`STATUS`.SUCCESS or raises
337         :raises: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION
338                     Xapian exception occurred; atomic section not entered.
339
340         *Added in notmuch 0.9*"""
341         self._assert_db_is_initialized()
342         status = self._begin_atomic(self._db)
343         if status != STATUS.SUCCESS:
344             raise NotmuchError(status)
345         return status
346
347     _end_atomic = nmlib.notmuch_database_end_atomic
348     _end_atomic.argtypes = [NotmuchDatabaseP]
349     _end_atomic.restype = c_uint
350
351     def end_atomic(self):
352         """Indicate the end of an atomic database operation
353
354         See :meth:`begin_atomic` for details.
355
356         :returns: :attr:`STATUS`.SUCCESS or raises
357
358         :raises:
359             :exc:`NotmuchError`:
360                 :attr:`STATUS`.XAPIAN_EXCEPTION
361                     A Xapian exception occurred; atomic section not
362                     ended.
363                 :attr:`STATUS`.UNBALANCED_ATOMIC:
364                     end_atomic has been called more times than begin_atomic.
365
366         *Added in notmuch 0.9*"""
367         self._assert_db_is_initialized()
368         status = self._end_atomic(self._db)
369         if status != STATUS.SUCCESS:
370             raise NotmuchError(status)
371         return status
372
373     def get_directory(self, path):
374         """Returns a :class:`Directory` of path,
375
376         :param path: An unicode string containing the path relative to the path
377               of database (see :meth:`get_path`), or else should be an absolute
378               path with initial components that match the path of 'database'.
379         :returns: :class:`Directory` or raises an exception.
380         :raises: :exc:`FileError` if path is not relative database or absolute
381                  with initial components same as database.
382         """
383         self._assert_db_is_initialized()
384
385         # sanity checking if path is valid, and make path absolute
386         if path and path[0] == os.sep:
387             # we got an absolute path
388             if not path.startswith(self.get_path()):
389                 # but its initial components are not equal to the db path
390                 raise FileError('Database().get_directory() called '
391                                 'with a wrong absolute path')
392             abs_dirpath = path
393         else:
394             #we got a relative path, make it absolute
395             abs_dirpath = os.path.abspath(os.path.join(self.get_path(), path))
396
397         dir_p = NotmuchDirectoryP()
398         status = Database._get_directory(self._db, _str(path), byref(dir_p))
399
400         if status != STATUS.SUCCESS:
401             raise NotmuchError(status)
402         if not dir_p:
403             return None
404
405         # return the Directory, init it with the absolute path
406         return Directory(abs_dirpath, dir_p, self)
407
408     _get_default_indexopts = nmlib.notmuch_database_get_default_indexopts
409     _get_default_indexopts.argtypes = [NotmuchDatabaseP]
410     _get_default_indexopts.restype = NotmuchIndexoptsP
411
412     _indexopts_set_decrypt_policy = nmlib.notmuch_indexopts_set_decrypt_policy
413     _indexopts_set_decrypt_policy.argtypes = [NotmuchIndexoptsP, c_uint]
414     _indexopts_set_decrypt_policy.restype = None
415
416     _indexopts_destroy = nmlib.notmuch_indexopts_destroy
417     _indexopts_destroy.argtypes = [NotmuchIndexoptsP]
418     _indexopts_destroy.restype = None
419
420     _index_file = nmlib.notmuch_database_index_file
421     _index_file.argtypes = [NotmuchDatabaseP, c_char_p,
422                              c_void_p,
423                              POINTER(NotmuchMessageP)]
424     _index_file.restype = c_uint
425
426     def index_file(self, filename, sync_maildir_flags=False, decrypt_policy=None):
427         """Adds a new message to the database
428
429         :param filename: should be a path relative to the path of the
430             open database (see :meth:`get_path`), or else should be an
431             absolute filename with initial components that match the
432             path of the database.
433
434             The file should be a single mail message (not a
435             multi-message mbox) that is expected to remain at its
436             current location, since the notmuch database will reference
437             the filename, and will not copy the entire contents of the
438             file.
439
440         :param sync_maildir_flags: If the message contains Maildir
441             flags, we will -depending on the notmuch configuration- sync
442             those tags to initial notmuch tags, if set to `True`. It is
443             `False` by default to remain consistent with the libnotmuch
444             API. You might want to look into the underlying method
445             :meth:`Message.maildir_flags_to_tags`.
446
447         :param decrypt_policy: If the message contains any encrypted
448             parts, and decrypt_policy is set to
449             :attr:`DECRYPTION_POLICY`.TRUE, notmuch will try to
450             decrypt the message and index the cleartext, stashing any
451             discovered session keys.  If it is set to
452             :attr:`DECRYPTION_POLICY`.FALSE, it will never try to
453             decrypt during indexing.  If it is set to
454             :attr:`DECRYPTION_POLICY`.AUTO, then it will try to use
455             any stashed session keys it knows about, but will not try
456             to access the user's secret keys.
457             :attr:`DECRYPTION_POLICY`.NOSTASH behaves the same as
458             :attr:`DECRYPTION_POLICY`.TRUE except that no session keys
459             are stashed in the database.  If decrypt_policy is set to
460             None (the default), then the database itself will decide
461             whether to decrypt, based on the `index.decrypt`
462             configuration setting (see notmuch-config(1)).
463
464         :returns: On success, we return
465
466            1) a :class:`Message` object that can be used for things
467               such as adding tags to the just-added message.
468            2) one of the following :attr:`STATUS` values:
469
470               :attr:`STATUS`.SUCCESS
471                   Message successfully added to database.
472               :attr:`STATUS`.DUPLICATE_MESSAGE_ID
473                   Message has the same message ID as another message already
474                   in the database. The new filename was successfully added
475                   to the list of the filenames for the existing message.
476
477         :rtype:   2-tuple(:class:`Message`, :attr:`STATUS`)
478
479         :raises: Raises a :exc:`NotmuchError` with the following meaning.
480               If such an exception occurs, nothing was added to the database.
481
482               :attr:`STATUS`.FILE_ERROR
483                       An error occurred trying to open the file, (such as
484                       permission denied, or file not found, etc.).
485               :attr:`STATUS`.FILE_NOT_EMAIL
486                       The contents of filename don't look like an email
487                       message.
488               :attr:`STATUS`.READ_ONLY_DATABASE
489                       Database was opened in read-only mode so no message can
490                       be added.
491         """
492         self._assert_db_is_initialized()
493         msg_p = NotmuchMessageP()
494         indexopts = c_void_p(None)
495         if decrypt_policy is not None:
496             indexopts = self._get_default_indexopts(self._db)
497             self._indexopts_set_decrypt_policy(indexopts, decrypt_policy)
498
499         status = self._index_file(self._db, _str(filename), indexopts, byref(msg_p))
500
501         if indexopts:
502             self._indexopts_destroy(indexopts)
503
504         if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
505             raise NotmuchError(status)
506
507         #construct Message() and return
508         msg = Message(msg_p, self)
509         #automatic sync initial tags from Maildir flags
510         if sync_maildir_flags:
511             msg.maildir_flags_to_tags()
512         return (msg, status)
513
514     def add_message(self, filename, sync_maildir_flags=False):
515         """Deprecated alias for :meth:`index_file`
516         """
517         warnings.warn(
518                 "This function is deprecated and will be removed in the future, use index_file.", DeprecationWarning)
519
520         return self.index_file(filename, sync_maildir_flags=sync_maildir_flags)
521
522     _remove_message = nmlib.notmuch_database_remove_message
523     _remove_message.argtypes = [NotmuchDatabaseP, c_char_p]
524     _remove_message.restype = c_uint
525
526     def remove_message(self, filename):
527         """Removes a message (filename) from the given notmuch database
528
529         Note that only this particular filename association is removed from
530         the database. If the same message (as determined by the message ID)
531         is still available via other filenames, then the message will
532         persist in the database for those filenames. When the last filename
533         is removed for a particular message, the database content for that
534         message will be entirely removed.
535
536         :returns: A :attr:`STATUS` value with the following meaning:
537
538              :attr:`STATUS`.SUCCESS
539                The last filename was removed and the message was removed
540                from the database.
541              :attr:`STATUS`.DUPLICATE_MESSAGE_ID
542                This filename was removed but the message persists in the
543                database with at least one other filename.
544
545         :raises: Raises a :exc:`NotmuchError` with the following meaning.
546              If such an exception occurs, nothing was removed from the
547              database.
548
549              :attr:`STATUS`.READ_ONLY_DATABASE
550                Database was opened in read-only mode so no message can be
551                removed.
552         """
553         self._assert_db_is_initialized()
554         status = self._remove_message(self._db, _str(filename))
555         if status not in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
556             raise NotmuchError(status)
557         return status
558
559     def find_message(self, msgid):
560         """Returns a :class:`Message` as identified by its message ID
561
562         Wraps the underlying *notmuch_database_find_message* function.
563
564         :param msgid: The message ID
565         :type msgid: unicode or str
566         :returns: :class:`Message` or `None` if no message is found.
567         :raises:
568             :exc:`OutOfMemoryError`
569                   If an Out-of-memory occurred while constructing the message.
570             :exc:`XapianError`
571                   In case of a Xapian Exception. These exceptions
572                   include "Database modified" situations, e.g. when the
573                   notmuch database has been modified by another program
574                   in the meantime. In this case, you should close and
575                   reopen the database and retry.
576             :exc:`NotInitializedError` if
577                     the database was not intitialized.
578         """
579         self._assert_db_is_initialized()
580         msg_p = NotmuchMessageP()
581         status = Database._find_message(self._db, _str(msgid), byref(msg_p))
582         if status != STATUS.SUCCESS:
583             raise NotmuchError(status)
584         return msg_p and Message(msg_p, self) or None
585
586     def find_message_by_filename(self, filename):
587         """Find a message with the given filename
588
589         :returns: If the database contains a message with the given
590             filename, then a class:`Message:` is returned.  This
591             function returns None if no message is found with the given
592             filename.
593
594         :raises: :exc:`OutOfMemoryError` if an Out-of-memory occurred while
595                  constructing the message.
596         :raises: :exc:`XapianError` in case of a Xapian Exception.
597                  These exceptions include "Database modified"
598                  situations, e.g. when the notmuch database has been
599                  modified by another program in the meantime. In this
600                  case, you should close and reopen the database and
601                  retry.
602         :raises: :exc:`NotInitializedError` if the database was not
603                  intitialized.
604
605         *Added in notmuch 0.9*"""
606         self._assert_db_is_initialized()
607
608         msg_p = NotmuchMessageP()
609         status = Database._find_message_by_filename(self._db, _str(filename),
610                                                     byref(msg_p))
611         if status != STATUS.SUCCESS:
612             raise NotmuchError(status)
613         return msg_p and Message(msg_p, self) or None
614
615     def get_all_tags(self):
616         """Returns :class:`Tags` with a list of all tags found in the database
617
618         :returns: :class:`Tags`
619         :execption: :exc:`NotmuchError` with :attr:`STATUS`.NULL_POINTER
620                     on error
621         """
622         self._assert_db_is_initialized()
623         tags_p = Database._get_all_tags(self._db)
624         if not tags_p:
625             raise NullPointerError()
626         return Tags(tags_p, self)
627
628     def create_query(self, querystring):
629         """Returns a :class:`Query` derived from this database
630
631         This is a shorthand method for doing::
632
633           # short version
634           # Automatically frees the Database() when 'q' is deleted
635
636           q  = Database(dbpath).create_query('from:"Biene Maja"')
637
638           # long version, which is functionally equivalent but will keep the
639           # Database in the 'db' variable around after we delete 'q':
640
641           db = Database(dbpath)
642           q  = Query(db,'from:"Biene Maja"')
643
644         This function is a python extension and not in the underlying C API.
645         """
646         return Query(self, querystring)
647
648     """notmuch_database_status_string"""
649     _status_string = nmlib.notmuch_database_status_string
650     _status_string.argtypes = [NotmuchDatabaseP]
651     _status_string.restype = c_char_p
652
653     def status_string(self):
654         """Returns the status string of the database
655
656         This is sometimes used for additional error reporting
657         """
658         self._assert_db_is_initialized()
659         s = Database._status_string(self._db)
660         if s:
661             return s.decode('utf-8', 'ignore')
662         return s
663
664     def __repr__(self):
665         return "'Notmuch DB " + self.get_path() + "'"
666
667     def _get_user_default_db(self):
668         """ Reads a user's notmuch config and returns his db location
669
670         Throws a NotmuchError if it cannot find it"""
671         config = SafeConfigParser()
672         conf_f = os.getenv('NOTMUCH_CONFIG',
673                            os.path.expanduser('~/.notmuch-config'))
674         config.readfp(codecs.open(conf_f, 'r', 'utf-8'))
675         if not config.has_option('database', 'path'):
676             raise NotmuchError(message="No DB path specified"
677                                        " and no user default found")
678         return config.get('database', 'path')
679
680     """notmuch_database_get_config"""
681     _get_config = nmlib.notmuch_database_get_config
682     _get_config.argtypes = [NotmuchDatabaseP, c_char_p, POINTER(c_char_p)]
683     _get_config.restype = c_uint
684
685     def get_config(self, key):
686         """Return the value of the given config key.
687
688         Note that only config values that are stored in the database are
689         searched and returned.  The config file is not read.
690
691         :param key: the config key under which a value should be looked up, it
692                     should probably be in the form "section.key"
693         :type key:  str
694         :returns:   the config value or the empty string if no value is present
695                     for that key
696         :rtype:     str
697         :raises:    :exc:`NotmuchError` in case of failure.
698
699         """
700         self._assert_db_is_initialized()
701         return_string = c_char_p()
702         status = self._get_config(self._db, _str(key), byref(return_string))
703         if status != STATUS.SUCCESS:
704             raise NotmuchError(status)
705         return return_string.value.decode('utf-8')
706
707     """notmuch_database_get_config_list"""
708     _get_config_list = nmlib.notmuch_database_get_config_list
709     _get_config_list.argtypes = [NotmuchDatabaseP, c_char_p,
710                                  POINTER(NotmuchConfigListP)]
711     _get_config_list.restype = c_uint
712
713     _config_list_valid = nmlib.notmuch_config_list_valid
714     _config_list_valid.argtypes = [NotmuchConfigListP]
715     _config_list_valid.restype = bool
716
717     _config_list_key = nmlib.notmuch_config_list_key
718     _config_list_key.argtypes = [NotmuchConfigListP]
719     _config_list_key.restype = c_char_p
720
721     _config_list_value = nmlib.notmuch_config_list_value
722     _config_list_value.argtypes = [NotmuchConfigListP]
723     _config_list_value.restype = c_char_p
724
725     _config_list_move_to_next = nmlib.notmuch_config_list_move_to_next
726     _config_list_move_to_next.argtypes = [NotmuchConfigListP]
727     _config_list_move_to_next.restype = None
728
729     _config_list_destroy = nmlib.notmuch_config_list_destroy
730     _config_list_destroy.argtypes = [NotmuchConfigListP]
731     _config_list_destroy.restype = None
732
733     def get_configs(self, prefix=''):
734         """Return a generator of key, value pairs where the start of key
735         matches the given prefix
736
737         Note that only config values that are stored in the database are
738         searched and returned.  The config file is not read.  If no `prefix` is
739         given all config values are returned.
740
741         This could be used to get all named queries into a dict for example::
742
743             queries = {k[6:]: v for k, v in db.get_configs('query.')}
744
745         :param prefix: a string by which the keys should be selected
746         :type prefix:  str
747         :yields:       all key-value pairs where `prefix` matches the beginning
748                        of the key
749         :ytype:        pairs of str
750         :raises:      :exc:`NotmuchError` in case of failure.
751
752         """
753         self._assert_db_is_initialized()
754         config_list_p = NotmuchConfigListP()
755         status = self._get_config_list(self._db, _str(prefix),
756                                        byref(config_list_p))
757         if status != STATUS.SUCCESS:
758             raise NotmuchError(status)
759         while self._config_list_valid(config_list_p):
760             key = self._config_list_key(config_list_p).decode('utf-8')
761             value = self._config_list_value(config_list_p).decode('utf-8')
762             yield key, value
763             self._config_list_move_to_next(config_list_p)
764
765     """notmuch_database_set_config"""
766     _set_config = nmlib.notmuch_database_set_config
767     _set_config.argtypes = [NotmuchDatabaseP, c_char_p, c_char_p]
768     _set_config.restype = c_uint
769
770     def set_config(self, key, value):
771         """Set a config value in the notmuch database.
772
773         If an empty string is provided as `value` the `key` is unset!
774
775         :param key:   the key to set
776         :type key:    str
777         :param value: the value to store under `key`
778         :type value:  str
779         :returns:     None
780         :raises:      :exc:`NotmuchError` in case of failure.
781
782         """
783         self._assert_db_is_initialized()
784         status = self._set_config(self._db, _str(key), _str(value))
785         if status != STATUS.SUCCESS:
786             raise NotmuchError(status)