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