git.notmuchmail.org Git - notmuch/blob - 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 <http://www.gnu.org/licenses/>.
  16
  17 Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
  18 """
  19
  20 import os
  21 from ctypes import c_char_p, c_void_p, c_uint, c_long, byref, POINTER
  22 from notmuch.globals import (nmlib, STATUS, NotmuchError, NotInitializedError,
  23      NullPointerError, Enum, _str,
  24      NotmuchDatabaseP, NotmuchDirectoryP, NotmuchMessageP, NotmuchTagsP,
  25      NotmuchQueryP, NotmuchMessagesP, NotmuchThreadsP, NotmuchFilenamesP)
  26 from notmuch.thread import Threads
  27 from notmuch.message import Messages, Message
  28 from notmuch.tag import Tags
  29
  30
  31 class Database(object):
  32     """The :class:`Database` is the highest-level object that notmuch
  33     provides. It references a notmuch database, and can be opened in
  34     read-only or read-write mode. A :class:`Query` can be derived from
  35     or be applied to a specific database to find messages. Also adding
  36     and removing messages to the database happens via this
  37     object. Modifications to the database are not atmic by default (see
  38     :meth:`begin_atomic`) and once a database has been modified, all
  39     other database objects pointing to the same data-base will throw an
  40     :exc:`XapianError` as the underlying database has been
  41     modified. Close and reopen the database to continue working with it.
  42
  43     .. note::
  44
  45         Any function in this class can and will throw an
  46         :exc:`NotInitializedError` if the database was not intitialized
  47         properly.
  48
  49     .. note::
  50
  51         Do remember that as soon as we tear down (e.g. via `del db`) this
  52         object, all underlying derived objects such as queries, threads,
  53         messages, tags etc will be freed by the underlying library as well.
  54         Accessing these objects will lead to segfaults and other unexpected
  55         behavior. See above for more details.
  56     """
  57     _std_db_path = None
  58     """Class attribute to cache user's default database"""
  59
  60     MODE = Enum(['READ_ONLY', 'READ_WRITE'])
  61     """Constants: Mode in which to open the database"""
  62
  63     """notmuch_database_get_directory"""
  64     _get_directory = nmlib.notmuch_database_get_directory
  65     _get_directory.argtypes = [NotmuchDatabaseP, c_char_p]
  66     _get_directory.restype = NotmuchDirectoryP
  67
  68     """notmuch_database_get_path"""
  69     _get_path = nmlib.notmuch_database_get_path
  70     _get_path.argtypes = [NotmuchDatabaseP]
  71     _get_path.restype = c_char_p
  72
  73     """notmuch_database_get_version"""
  74     _get_version = nmlib.notmuch_database_get_version
  75     _get_version.argtypes = [NotmuchDatabaseP]
  76     _get_version.restype = c_uint
  77
  78     """notmuch_database_open"""
  79     _open = nmlib.notmuch_database_open
  80     _open.argtypes = [c_char_p, c_uint]
  81     _open.restype = NotmuchDatabaseP
  82     #_open.restype = c_void_p
  83
  84     """notmuch_database_upgrade"""
  85     _upgrade = nmlib.notmuch_database_upgrade
  86     _upgrade.argtypes = [NotmuchDatabaseP, c_void_p, c_void_p]
  87     _upgrade.restype = c_uint
  88
  89     """ notmuch_database_find_message"""
  90     _find_message = nmlib.notmuch_database_find_message
  91     _find_message.argtypes = [NotmuchDatabaseP, c_char_p,
  92                               POINTER(NotmuchMessageP)]
  93     _find_message.restype = c_uint
  94
  95     """notmuch_database_find_message_by_filename"""
  96     _find_message_by_filename = nmlib.notmuch_database_find_message_by_filename
  97     _find_message_by_filename.argtypes = [NotmuchDatabaseP, c_char_p,
  98                                           POINTER(NotmuchMessageP)]
  99     _find_message_by_filename.restype = c_uint
 100
 101     """notmuch_database_get_all_tags"""
 102     _get_all_tags = nmlib.notmuch_database_get_all_tags
 103     _get_all_tags.argtypes = [NotmuchDatabaseP]
 104     _get_all_tags.restype = NotmuchTagsP
 105
 106     """notmuch_database_create"""
 107     _create = nmlib.notmuch_database_create
 108     _create.argtypes = [c_char_p]
 109     _create.restype = NotmuchDatabaseP
 110
 111     def __init__(self, path=None, create=False, mode=0):
 112         """If *path* is `None`, we will try to read a users notmuch
 113         configuration and use his configured database. The location of the
 114         configuration file can be specified through the environment variable
 115         *NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
 116
 117         If *create* is `True`, the database will always be created in
 118         :attr:`MODE`.READ_WRITE mode. Default mode for opening is READ_ONLY.
 119
 120         :param path:   Directory to open/create the database in (see
 121                        above for behavior if `None`)
 122         :type path:    `str` or `None`
 123         :param create: Pass `False` to open an existing, `True` to create a new
 124                        database.
 125         :type create:  bool
 126         :param mode:   Mode to open a database in. Is always
 127                        :attr:`MODE`.READ_WRITE when creating a new one.
 128         :type mode:    :attr:`MODE`
 129         :exception: :exc:`NotmuchError` or derived exception in case of
 130             failure.
 131         """
 132         self._db = None
 133         if path is None:
 134             # no path specified. use a user's default database
 135             if Database._std_db_path is None:
 136                 #the following line throws a NotmuchError if it fails
 137                 Database._std_db_path = self._get_user_default_db()
 138             path = Database._std_db_path
 139
 140         if create == False:
 141             self.open(path, mode)
 142         else:
 143             self.create(path)
 144
 145     def _assert_db_is_initialized(self):
 146         """Raises :exc:`NotInitializedError` if self._db is `None`"""
 147         if self._db is None:
 148             raise NotInitializedError()
 149
 150     def create(self, path):
 151         """Creates a new notmuch database
 152
 153         This function is used by __init__() and usually does not need
 154         to be called directly. It wraps the underlying
 155         *notmuch_database_create* function and creates a new notmuch
 156         database at *path*. It will always return a database in :attr:`MODE`
 157         .READ_WRITE mode as creating an empty database for
 158         reading only does not make a great deal of sense.
 159
 160         :param path: A directory in which we should create the database.
 161         :type path: str
 162         :returns: Nothing
 163         :exception: :exc:`NotmuchError` in case of any failure
 164                     (possibly after printing an error message on stderr).
 165         """
 166         if self._db is not None:
 167             raise NotmuchError(message="Cannot create db, this Database() "
 168                                        "already has an open one.")
 169
 170         res = Database._create(_str(path), Database.MODE.READ_WRITE)
 171
 172         if res is None:
 173             raise NotmuchError(
 174                 message="Could not create the specified database")
 175         self._db = res
 176
 177     def open(self, path, mode=0):
 178         """Opens an existing database
 179
 180         This function is used by __init__() and usually does not need
 181         to be called directly. It wraps the underlying
 182         *notmuch_database_open* function.
 183
 184         :param status: Open the database in read-only or read-write mode
 185         :type status:  :attr:`MODE`
 186         :returns: Nothing
 187         :exception: Raises :exc:`NotmuchError` in case of any failure
 188                     (possibly after printing an error message on stderr).
 189         """
 190         res = Database._open(_str(path), mode)
 191
 192         if res is None:
 193             raise NotmuchError(message="Could not open the specified database")
 194         self._db = res
 195
 196     def get_path(self):
 197         """Returns the file path of an open database"""
 198         self._assert_db_is_initialized()
 199         return Database._get_path(self._db).decode('utf-8')
 200
 201     def get_version(self):
 202         """Returns the database format version
 203
 204         :returns: The database version as positive integer
 205         """
 206         self._assert_db_is_initialized()
 207         return Database._get_version(self._db)
 208
 209     _needs_upgrade = nmlib.notmuch_database_needs_upgrade
 210     _needs_upgrade.argtypes = [NotmuchDatabaseP]
 211     _needs_upgrade.restype = bool
 212
 213     def needs_upgrade(self):
 214         """Does this database need to be upgraded before writing to it?
 215
 216         If this function returns `True` then no functions that modify the
 217         database (:meth:`add_message`,
 218         :meth:`Message.add_tag`, :meth:`Directory.set_mtime`,
 219         etc.) will work unless :meth:`upgrade` is called successfully first.
 220
 221         :returns: `True` or `False`
 222         """
 223         self._assert_db_is_initialized()
 224         return self._needs_upgrade(self._db)
 225
 226     def upgrade(self):
 227         """Upgrades the current database
 228
 229         After opening a database in read-write mode, the client should
 230         check if an upgrade is needed (notmuch_database_needs_upgrade) and
 231         if so, upgrade with this function before making any modifications.
 232
 233         NOT IMPLEMENTED: The optional progress_notify callback can be
 234         used by the caller to provide progress indication to the
 235         user. If non-NULL it will be called periodically with
 236         'progress' as a floating-point value in the range of [0.0..1.0]
 237         indicating the progress made so far in the upgrade process.
 238
 239         :TODO: catch exceptions, document return values and etc...
 240         """
 241         self._assert_db_is_initialized()
 242         status = Database._upgrade(self._db, None, None)
 243         #TODO: catch exceptions, document return values and etc
 244         return status
 245
 246     _begin_atomic = nmlib.notmuch_database_begin_atomic
 247     _begin_atomic.argtypes = [NotmuchDatabaseP]
 248     _begin_atomic.restype = c_uint
 249
 250     def begin_atomic(self):
 251         """Begin an atomic database operation
 252
 253         Any modifications performed between a successful
 254         :meth:`begin_atomic` and a :meth:`end_atomic` will be applied to
 255         the database atomically.  Note that, unlike a typical database
 256         transaction, this only ensures atomicity, not durability;
 257         neither begin nor end necessarily flush modifications to disk.
 258
 259         :returns: :attr:`STATUS`.SUCCESS or raises
 260         :exception: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION
 261                     Xapian exception occurred; atomic section not entered.
 262
 263         *Added in notmuch 0.9*"""
 264         self._assert_db_is_initialized()
 265         status = self._begin_atomic(self._db)
 266         if status != STATUS.SUCCESS:
 267             raise NotmuchError(status)
 268         return status
 269
 270     _end_atomic = nmlib.notmuch_database_end_atomic
 271     _end_atomic.argtypes = [NotmuchDatabaseP]
 272     _end_atomic.restype = c_uint
 273
 274     def end_atomic(self):
 275         """Indicate the end of an atomic database operation
 276
 277         See :meth:`begin_atomic` for details.
 278
 279         :returns: :attr:`STATUS`.SUCCESS or raises
 280
 281         :exception:
 282             :exc:`NotmuchError`:
 283                 :attr:`STATUS`.XAPIAN_EXCEPTION
 284                     A Xapian exception occurred; atomic section not
 285                     ended.
 286                 :attr:`STATUS`.UNBALANCED_ATOMIC:
 287                     end_atomic has been called more times than begin_atomic.
 288
 289         *Added in notmuch 0.9*"""
 290         self._assert_db_is_initialized()
 291         status = self._end_atomic(self._db)
 292         if status != STATUS.SUCCESS:
 293             raise NotmuchError(status)
 294         return status
 295
 296     def get_directory(self, path):
 297         """Returns a :class:`Directory` of path,
 298         (creating it if it does not exist(?))
 299
 300         .. warning::
 301
 302             This call needs a writeable database in
 303             :attr:`Database.MODE`.READ_WRITE mode. The underlying library will
 304             exit the program if this method is used on a read-only database!
 305
 306         :param path: An unicode string containing the path relative to the path
 307               of database (see :meth:`get_path`), or else should be an absolute
 308               path with initial components that match the path of 'database'.
 309         :returns: :class:`Directory` or raises an exception.
 310         :exception:
 311             :exc:`NotmuchError` with :attr:`STATUS`.FILE_ERROR
 312                     If path is not relative database or absolute with initial
 313                     components same as database.
 314         """
 315         self._assert_db_is_initialized()
 316         # sanity checking if path is valid, and make path absolute
 317         if path[0] == os.sep:
 318             # we got an absolute path
 319             if not path.startswith(self.get_path()):
 320                 # but its initial components are not equal to the db path
 321                 raise NotmuchError(STATUS.FILE_ERROR,
 322                                    message="Database().get_directory() called "
 323                                            "with a wrong absolute path.")
 324             abs_dirpath = path
 325         else:
 326             #we got a relative path, make it absolute
 327             abs_dirpath = os.path.abspath(os.path.join(self.get_path(), path))
 328
 329         dir_p = Database._get_directory(self._db, _str(path))
 330
 331         # return the Directory, init it with the absolute path
 332         return Directory(_str(abs_dirpath), dir_p, self)
 333
 334     _add_message = nmlib.notmuch_database_add_message
 335     _add_message.argtypes = [NotmuchDatabaseP, c_char_p,
 336                              POINTER(NotmuchMessageP)]
 337     _add_message.restype = c_uint
 338
 339     def add_message(self, filename, sync_maildir_flags=False):
 340         """Adds a new message to the database
 341
 342         :param filename: should be a path relative to the path of the
 343             open database (see :meth:`get_path`), or else should be an
 344             absolute filename with initial components that match the
 345             path of the database.
 346
 347             The file should be a single mail message (not a
 348             multi-message mbox) that is expected to remain at its
 349             current location, since the notmuch database will reference
 350             the filename, and will not copy the entire contents of the
 351             file.
 352
 353         :param sync_maildir_flags: If the message contains Maildir
 354             flags, we will -depending on the notmuch configuration- sync
 355             those tags to initial notmuch tags, if set to `True`. It is
 356             `False` by default to remain consistent with the libnotmuch
 357             API. You might want to look into the underlying method
 358             :meth:`Message.maildir_flags_to_tags`.
 359
 360         :returns: On success, we return
 361
 362            1) a :class:`Message` object that can be used for things
 363               such as adding tags to the just-added message.
 364            2) one of the following :attr:`STATUS` values:
 365
 366               :attr:`STATUS`.SUCCESS
 367                   Message successfully added to database.
 368               :attr:`STATUS`.DUPLICATE_MESSAGE_ID
 369                   Message has the same message ID as another message already
 370                   in the database. The new filename was successfully added
 371                   to the list of the filenames for the existing message.
 372
 373         :rtype:   2-tuple(:class:`Message`, :attr:`STATUS`)
 374
 375         :exception: Raises a :exc:`NotmuchError` with the following meaning.
 376               If such an exception occurs, nothing was added to the database.
 377
 378               :attr:`STATUS`.FILE_ERROR
 379                       An error occurred trying to open the file, (such as
 380                       permission denied, or file not found, etc.).
 381               :attr:`STATUS`.FILE_NOT_EMAIL
 382                       The contents of filename don't look like an email
 383                       message.
 384               :attr:`STATUS`.READ_ONLY_DATABASE
 385                       Database was opened in read-only mode so no message can
 386                       be added.
 387         """
 388         self._assert_db_is_initialized()
 389         msg_p = NotmuchMessageP()
 390         status = self._add_message(self._db, _str(filename), byref(msg_p))
 391
 392         if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
 393             raise NotmuchError(status)
 394
 395         #construct Message() and return
 396         msg = Message(msg_p, self)
 397         #automatic sync initial tags from Maildir flags
 398         if sync_maildir_flags:
 399             msg.maildir_flags_to_tags()
 400         return (msg, status)
 401
 402     _remove_message = nmlib.notmuch_database_remove_message
 403     _remove_message.argtypes = [NotmuchDatabaseP, c_char_p]
 404     _remove_message.restype = c_uint
 405
 406     def remove_message(self, filename):
 407         """Removes a message (filename) from the given notmuch database
 408
 409         Note that only this particular filename association is removed from
 410         the database. If the same message (as determined by the message ID)
 411         is still available via other filenames, then the message will
 412         persist in the database for those filenames. When the last filename
 413         is removed for a particular message, the database content for that
 414         message will be entirely removed.
 415
 416         :returns: A :attr:`STATUS` value with the following meaning:
 417
 418              :attr:`STATUS`.SUCCESS
 419                The last filename was removed and the message was removed
 420                from the database.
 421              :attr:`STATUS`.DUPLICATE_MESSAGE_ID
 422                This filename was removed but the message persists in the
 423                database with at least one other filename.
 424
 425         :exception: Raises a :exc:`NotmuchError` with the following meaning.
 426              If such an exception occurs, nothing was removed from the
 427              database.
 428
 429              :attr:`STATUS`.READ_ONLY_DATABASE
 430                Database was opened in read-only mode so no message can be
 431                removed.
 432         """
 433         self._assert_db_is_initialized()
 434         return self._remove_message(self._db, filename)
 435
 436     def find_message(self, msgid):
 437         """Returns a :class:`Message` as identified by its message ID
 438
 439         Wraps the underlying *notmuch_database_find_message* function.
 440
 441         :param msgid: The message ID
 442         :type msgid: unicode or str
 443         :returns: :class:`Message` or `None` if no message is found.
 444         :exception:
 445             :exc:`OutOfMemoryError`
 446                   If an Out-of-memory occured while constructing the message.
 447             :exc:`XapianError`
 448                   In case of a Xapian Exception. These exceptions
 449                   include "Database modified" situations, e.g. when the
 450                   notmuch database has been modified by another program
 451                   in the meantime. In this case, you should close and
 452                   reopen the database and retry.
 453             :exc:`NotInitializedError` if
 454                     the database was not intitialized.
 455         """
 456         self._assert_db_is_initialized()
 457         msg_p = NotmuchMessageP()
 458         status = Database._find_message(self._db, _str(msgid), byref(msg_p))
 459         if status != STATUS.SUCCESS:
 460             raise NotmuchError(status)
 461         return msg_p and Message(msg_p, self) or None
 462
 463     def find_message_by_filename(self, filename):
 464         """Find a message with the given filename
 465
 466         .. warning::
 467
 468             This call needs a writeable database in
 469             :attr:`Database.MODE`.READ_WRITE mode. The underlying library will
 470             exit the program if this method is used on a read-only database!
 471
 472         :returns: If the database contains a message with the given
 473             filename, then a class:`Message:` is returned.  This
 474             function returns None if no message is found with the given
 475             filename.
 476
 477         :exception:
 478             :exc:`OutOfMemoryError`
 479                   If an Out-of-memory occured while constructing the message.
 480             :exc:`XapianError`
 481                   In case of a Xapian Exception. These exceptions
 482                   include "Database modified" situations, e.g. when the
 483                   notmuch database has been modified by another program
 484                   in the meantime. In this case, you should close and
 485                   reopen the database and retry.
 486             :exc:`NotInitializedError` if
 487                     the database was not intitialized.
 488
 489         *Added in notmuch 0.9*"""
 490         self._assert_db_is_initialized()
 491         msg_p = NotmuchMessageP()
 492         status = Database._find_message_by_filename(self._db, _str(filename),
 493                                                     byref(msg_p))
 494         if status != STATUS.SUCCESS:
 495             raise NotmuchError(status)
 496         return msg_p and Message(msg_p, self) or None
 497
 498     def get_all_tags(self):
 499         """Returns :class:`Tags` with a list of all tags found in the database
 500
 501         :returns: :class:`Tags`
 502         :execption: :exc:`NotmuchError` with :attr:`STATUS`.NULL_POINTER
 503                     on error
 504         """
 505         self._assert_db_is_initialized()
 506         tags_p = Database._get_all_tags(self._db)
 507         if tags_p == None:
 508             raise NotmuchError(STATUS.NULL_POINTER)
 509         return Tags(tags_p, self)
 510
 511     def create_query(self, querystring):
 512         """Returns a :class:`Query` derived from this database
 513
 514         This is a shorthand method for doing::
 515
 516           # short version
 517           # Automatically frees the Database() when 'q' is deleted
 518
 519           q  = Database(dbpath).create_query('from:"Biene Maja"')
 520
 521           # long version, which is functionally equivalent but will keep the
 522           # Database in the 'db' variable around after we delete 'q':
 523
 524           db = Database(dbpath)
 525           q  = Query(db,'from:"Biene Maja"')
 526
 527         This function is a python extension and not in the underlying C API.
 528         """
 529         return Query(self, querystring)
 530
 531     def __repr__(self):
 532         return "'Notmuch DB " + self.get_path() + "'"
 533
 534     _close = nmlib.notmuch_database_close
 535     _close.argtypes = [NotmuchDatabaseP]
 536     _close.restype = None
 537
 538     def __del__(self):
 539         """Close and free the notmuch database if needed"""
 540         if self._db is not None:
 541             self._close(self._db)
 542
 543     def _get_user_default_db(self):
 544         """ Reads a user's notmuch config and returns his db location
 545
 546         Throws a NotmuchError if it cannot find it"""
 547         from ConfigParser import SafeConfigParser
 548         config = SafeConfigParser()
 549         conf_f = os.getenv('NOTMUCH_CONFIG',
 550                            os.path.expanduser('~/.notmuch-config'))
 551         config.read(conf_f)
 552         if not config.has_option('database', 'path'):
 553             raise NotmuchError(message="No DB path specified"
 554                                        " and no user default found")
 555         return config.get('database', 'path').decode('utf-8')
 556
 557     @property
 558     def db_p(self):
 559         """Property returning a pointer to `notmuch_database_t` or `None`
 560
 561         This should normally not be needed by a user (and is not yet
 562         guaranteed to remain stable in future versions).
 563         """
 564         return self._db
 565
 566
 567 class Query(object):
 568     """Represents a search query on an opened :class:`Database`.
 569
 570     A query selects and filters a subset of messages from the notmuch
 571     database we derive from.
 572
 573     :class:`Query` provides an instance attribute :attr:`sort`, which
 574     contains the sort order (if specified via :meth:`set_sort`) or
 575     `None`.
 576
 577     Any function in this class may throw an :exc:`NotInitializedError`
 578     in case the underlying query object was not set up correctly.
 579
 580     .. note:: Do remember that as soon as we tear down this object,
 581            all underlying derived objects such as threads,
 582            messages, tags etc will be freed by the underlying library
 583            as well. Accessing these objects will lead to segfaults and
 584            other unexpected behavior. See above for more details.
 585     """
 586     # constants
 587     SORT = Enum(['OLDEST_FIRST', 'NEWEST_FIRST', 'MESSAGE_ID', 'UNSORTED'])
 588     """Constants: Sort order in which to return results"""
 589
 590     """notmuch_query_create"""
 591     _create = nmlib.notmuch_query_create
 592     _create.argtypes = [NotmuchDatabaseP, c_char_p]
 593     _create.restype = NotmuchQueryP
 594
 595     """notmuch_query_search_threads"""
 596     _search_threads = nmlib.notmuch_query_search_threads
 597     _search_threads.argtypes = [NotmuchQueryP]
 598     _search_threads.restype = NotmuchThreadsP
 599
 600     """notmuch_query_search_messages"""
 601     _search_messages = nmlib.notmuch_query_search_messages
 602     _search_messages.argtypes = [NotmuchQueryP]
 603     _search_messages.restype = NotmuchMessagesP
 604
 605     """notmuch_query_count_messages"""
 606     _count_messages = nmlib.notmuch_query_count_messages
 607     _count_messages.argtypes = [NotmuchQueryP]
 608     _count_messages.restype = c_uint
 609
 610     def __init__(self, db, querystr):
 611         """
 612         :param db: An open database which we derive the Query from.
 613         :type db: :class:`Database`
 614         :param querystr: The query string for the message.
 615         :type querystr: utf-8 encoded str or unicode
 616         """
 617         self._db = None
 618         self._query = None
 619         self.sort = None
 620         self.create(db, querystr)
 621
 622     def _assert_query_is_initialized(self):
 623         """Raises :exc:`NotInitializedError` if self._query is `None`"""
 624         if self._query is None:
 625             raise NotInitializedError()
 626
 627     def create(self, db, querystr):
 628         """Creates a new query derived from a Database
 629
 630         This function is utilized by __init__() and usually does not need to
 631         be called directly.
 632
 633         :param db: Database to create the query from.
 634         :type db: :class:`Database`
 635         :param querystr: The query string
 636         :type querystr: utf-8 encoded str or unicode
 637         :returns: Nothing
 638         :exception:
 639             :exc:`NullPointerError` if the query creation failed
 640                 (e.g. too little memory).
 641             :exc:`NotInitializedError` if the underlying db was not
 642                 intitialized.
 643         """
 644         db._assert_db_is_initialized()
 645         # create reference to parent db to keep it alive
 646         self._db = db
 647         # create query, return None if too little mem available
 648         query_p = Query._create(db.db_p, _str(querystr))
 649         if query_p is None:
 650             raise NullPointerError
 651         self._query = query_p
 652
 653     _set_sort = nmlib.notmuch_query_set_sort
 654     _set_sort.argtypes = [NotmuchQueryP, c_uint]
 655     _set_sort.argtypes = None
 656
 657     def set_sort(self, sort):
 658         """Set the sort order future results will be delivered in
 659
 660         :param sort: Sort order (see :attr:`Query.SORT`)
 661         """
 662         self._assert_query_is_initialized()
 663         self.sort = sort
 664         self._set_sort(self._query, sort)
 665
 666     def search_threads(self):
 667         """Execute a query for threads
 668
 669         Execute a query for threads, returning a :class:`Threads` iterator.
 670         The returned threads are owned by the query and as such, will only be
 671         valid until the Query is deleted.
 672
 673         The method sets :attr:`Message.FLAG`\.MATCH for those messages that
 674         match the query. The method :meth:`Message.get_flag` allows us
 675         to get the value of this flag.
 676
 677         :returns: :class:`Threads`
 678         :exception: :exc:`NullPointerError` if search_threads failed
 679         """
 680         self._assert_query_is_initialized()
 681         threads_p = Query._search_threads(self._query)
 682
 683         if threads_p is None:
 684             raise NullPointerError
 685         return Threads(threads_p, self)
 686
 687     def search_messages(self):
 688         """Filter messages according to the query and return
 689         :class:`Messages` in the defined sort order
 690
 691         :returns: :class:`Messages`
 692         :exception: :exc:`NullPointerError` if search_messages failed
 693         """
 694         self._assert_query_is_initialized()
 695         msgs_p = Query._search_messages(self._query)
 696
 697         if msgs_p is None:
 698             raise NullPointerError
 699         return Messages(msgs_p, self)
 700
 701     def count_messages(self):
 702         """Estimate the number of messages matching the query
 703
 704         This function performs a search and returns Xapian's best
 705         guess as to the number of matching messages. It is much faster
 706         than performing :meth:`search_messages` and counting the
 707         result with `len()` (although it always returned the same
 708         result in my tests). Technically, it wraps the underlying
 709         *notmuch_query_count_messages* function.
 710
 711         :returns: :class:`Messages`
 712         """
 713         self._assert_query_is_initialized()
 714         return Query._count_messages(self._query)
 715
 716     _destroy = nmlib.notmuch_query_destroy
 717     _destroy.argtypes = [NotmuchQueryP]
 718     _destroy.restype = None
 719
 720     def __del__(self):
 721         """Close and free the Query"""
 722         if self._query is not None:
 723             self._destroy(self._query)
 724
 725
 726 class Directory(object):
 727     """Represents a directory entry in the notmuch directory
 728
 729     Modifying attributes of this object will modify the
 730     database, not the real directory attributes.
 731
 732     The Directory object is usually derived from another object
 733     e.g. via :meth:`Database.get_directory`, and will automatically be
 734     become invalid whenever that parent is deleted. You should
 735     therefore initialized this object handing it a reference to the
 736     parent, preventing the parent from automatically being garbage
 737     collected.
 738     """
 739
 740     """notmuch_directory_get_mtime"""
 741     _get_mtime = nmlib.notmuch_directory_get_mtime
 742     _get_mtime.argtypes = [NotmuchDirectoryP]
 743     _get_mtime.restype = c_long
 744
 745     """notmuch_directory_set_mtime"""
 746     _set_mtime = nmlib.notmuch_directory_set_mtime
 747     _set_mtime.argtypes = [NotmuchDirectoryP, c_long]
 748     _set_mtime.restype = c_uint
 749
 750     """notmuch_directory_get_child_files"""
 751     _get_child_files = nmlib.notmuch_directory_get_child_files
 752     _get_child_files.argtypes = [NotmuchDirectoryP]
 753     _get_child_files.restype = NotmuchFilenamesP
 754
 755     """notmuch_directory_get_child_directories"""
 756     _get_child_directories = nmlib.notmuch_directory_get_child_directories
 757     _get_child_directories.argtypes = [NotmuchDirectoryP]
 758     _get_child_directories.restype = NotmuchFilenamesP
 759
 760     def _assert_dir_is_initialized(self):
 761         """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
 762         if dir_p is None"""
 763         if self._dir_p is None:
 764             raise NotmuchError(STATUS.NOT_INITIALIZED)
 765
 766     def __init__(self, path, dir_p, parent):
 767         """
 768         :param path:   The absolute path of the directory object as unicode.
 769         :param dir_p:  The pointer to an internal notmuch_directory_t object.
 770         :param parent: The object this Directory is derived from
 771                        (usually a :class:`Database`). We do not directly use
 772                        this, but store a reference to it as long as
 773                        this Directory object lives. This keeps the
 774                        parent object alive.
 775         """
 776         assert isinstance(path, unicode), "Path needs to be an UNICODE object"
 777         self._path = path
 778         self._dir_p = dir_p
 779         self._parent = parent
 780
 781     def set_mtime(self, mtime):
 782         """Sets the mtime value of this directory in the database
 783
 784         The intention is for the caller to use the mtime to allow efficient
 785         identification of new messages to be added to the database. The
 786         recommended usage is as follows:
 787
 788         * Read the mtime of a directory from the filesystem
 789
 790         * Call :meth:`Database.add_message` for all mail files in
 791           the directory
 792
 793         * Call notmuch_directory_set_mtime with the mtime read from the
 794           filesystem.  Then, when wanting to check for updates to the
 795           directory in the future, the client can call :meth:`get_mtime`
 796           and know that it only needs to add files if the mtime of the
 797           directory and files are newer than the stored timestamp.
 798
 799           .. note::
 800
 801                 :meth:`get_mtime` function does not allow the caller to
 802                 distinguish a timestamp of 0 from a non-existent timestamp. So
 803                 don't store a timestamp of 0 unless you are comfortable with
 804                 that.
 805
 806           :param mtime: A (time_t) timestamp
 807           :returns: Nothing on success, raising an exception on failure.
 808           :exception: :exc:`NotmuchError`:
 809
 810                         :attr:`STATUS`.XAPIAN_EXCEPTION
 811                           A Xapian exception occurred, mtime not stored.
 812                         :attr:`STATUS`.READ_ONLY_DATABASE
 813                           Database was opened in read-only mode so directory
 814                           mtime cannot be modified.
 815                         :attr:`STATUS`.NOT_INITIALIZED
 816                           The directory has not been initialized
 817         """
 818         self._assert_dir_is_initialized()
 819         #TODO: make sure, we convert the mtime parameter to a 'c_long'
 820         status = Directory._set_mtime(self._dir_p, mtime)
 821
 822         #return on success
 823         if status == STATUS.SUCCESS:
 824             return
 825         #fail with Exception otherwise
 826         raise NotmuchError(status)
 827
 828     def get_mtime(self):
 829         """Gets the mtime value of this directory in the database
 830
 831         Retrieves a previously stored mtime for this directory.
 832
 833         :param mtime: A (time_t) timestamp
 834         :returns: Nothing on success, raising an exception on failure.
 835         :exception: :exc:`NotmuchError`:
 836
 837                         :attr:`STATUS`.NOT_INITIALIZED
 838                           The directory has not been initialized
 839         """
 840         self._assert_dir_is_initialized()
 841         return Directory._get_mtime(self._dir_p)
 842
 843     # Make mtime attribute a property of Directory()
 844     mtime = property(get_mtime, set_mtime, doc="""Property that allows getting
 845                      and setting of the Directory *mtime* (read-write)
 846
 847                      See :meth:`get_mtime` and :meth:`set_mtime` for usage and
 848                      possible exceptions.""")
 849
 850     def get_child_files(self):
 851         """Gets a Filenames iterator listing all the filenames of
 852         messages in the database within the given directory.
 853
 854         The returned filenames will be the basename-entries only (not
 855         complete paths.
 856         """
 857         self._assert_dir_is_initialized()
 858         files_p = Directory._get_child_files(self._dir_p)
 859         return Filenames(files_p, self)
 860
 861     def get_child_directories(self):
 862         """Gets a :class:`Filenames` iterator listing all the filenames of
 863         sub-directories in the database within the given directory
 864
 865         The returned filenames will be the basename-entries only (not
 866         complete paths.
 867         """
 868         self._assert_dir_is_initialized()
 869         files_p = Directory._get_child_directories(self._dir_p)
 870         return Filenames(files_p, self)
 871
 872     @property
 873     def path(self):
 874         """Returns the absolute path of this Directory (read-only)"""
 875         return self._path
 876
 877     def __repr__(self):
 878         """Object representation"""
 879         return "<notmuch Directory object '%s'>" % self._path
 880
 881     _destroy = nmlib.notmuch_directory_destroy
 882     _destroy.argtypes = [NotmuchDirectoryP]
 883     _destroy.argtypes = None
 884
 885     def __del__(self):
 886         """Close and free the Directory"""
 887         if self._dir_p is not None:
 888             self._destroy(self._dir_p)
 889
 890
 891 class Filenames(object):
 892     """An iterator over File- or Directory names stored in the database"""
 893
 894     #notmuch_filenames_get
 895     _get = nmlib.notmuch_filenames_get
 896     _get.argtypes = [NotmuchFilenamesP]
 897     _get.restype = c_char_p
 898
 899     def __init__(self, files_p, parent):
 900         """
 901         :param files_p: The pointer to an internal notmuch_filenames_t object.
 902         :param parent: The object this Directory is derived from
 903                        (usually a Directory()). We do not directly use
 904                        this, but store a reference to it as long as
 905                        this Directory object lives. This keeps the
 906                        parent object alive.
 907         """
 908         self._files_p = files_p
 909         self._parent = parent
 910
 911     def __iter__(self):
 912         """ Make Filenames an iterator """
 913         return self
 914
 915     _valid = nmlib.notmuch_filenames_valid
 916     _valid.argtypes = [NotmuchFilenamesP]
 917     _valid.restype = bool
 918
 919     _move_to_next = nmlib.notmuch_filenames_move_to_next
 920     _move_to_next.argtypes = [NotmuchFilenamesP]
 921     _move_to_next.restype = None
 922
 923     def next(self):
 924         if self._files_p is None:
 925             raise NotmuchError(STATUS.NOT_INITIALIZED)
 926
 927         if not self._valid(self._files_p):
 928             self._files_p = None
 929             raise StopIteration
 930
 931         file = Filenames._get(self._files_p)
 932         self._move_to_next(self._files_p)
 933         return file
 934
 935     def __len__(self):
 936         """len(:class:`Filenames`) returns the number of contained files
 937
 938         .. note::
 939
 940             As this iterates over the files, we will not be able to
 941             iterate over them again! So this will fail::
 942
 943                  #THIS FAILS
 944                  files = Database().get_directory('').get_child_files()
 945                  if len(files) > 0:  # this 'exhausts' msgs
 946                      # next line raises
 947                      # NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
 948                      for file in files: print file
 949         """
 950         if self._files_p is None:
 951             raise NotmuchError(STATUS.NOT_INITIALIZED)
 952
 953         i = 0
 954         while self._valid(self._files_p):
 955             self._move_to_next(self._files_p)
 956             i += 1
 957         self._files_p = None
 958         return i
 959
 960     _destroy = nmlib.notmuch_filenames_destroy
 961     _destroy.argtypes = [NotmuchFilenamesP]
 962     _destroy.restype = None
 963
 964     def __del__(self):
 965         """Close and free Filenames"""
 966         if self._files_p is not None:
 967             self._destroy(self._files_p)