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, byref, POINTER
  23 from .compat import SafeConfigParser
  24 from .globals import (
  25     nmlib,
  26     Enum,
  27     _str,
  28     NotmuchDatabaseP,
  29     NotmuchDirectoryP,
  30     NotmuchMessageP,
  31     NotmuchTagsP,
  32 )
  33 from .errors import (
  34     STATUS,
  35     FileError,
  36     NotmuchError,
  37     NullPointerError,
  38     NotInitializedError,
  39     ReadOnlyDatabaseError,
  40 )
  41 from .message import Message
  42 from .tag import Tags
  43 from .query import Query
  44 from .directory import Directory
  45
  46 class Database(object):
  47     """The :class:`Database` is the highest-level object that notmuch
  48     provides. It references a notmuch database, and can be opened in
  49     read-only or read-write mode. A :class:`Query` can be derived from
  50     or be applied to a specific database to find messages. Also adding
  51     and removing messages to the database happens via this
  52     object. Modifications to the database are not atmic by default (see
  53     :meth:`begin_atomic`) and once a database has been modified, all
  54     other database objects pointing to the same data-base will throw an
  55     :exc:`XapianError` as the underlying database has been
  56     modified. Close and reopen the database to continue working with it.
  57
  58     :class:`Database` objects implement the context manager protocol
  59     so you can use the :keyword:`with` statement to ensure that the
  60     database is properly closed. See :meth:`close` for more
  61     information.
  62
  63     .. note::
  64
  65         Any function in this class can and will throw an
  66         :exc:`NotInitializedError` if the database was not intitialized
  67         properly.
  68     """
  69     _std_db_path = None
  70     """Class attribute to cache user's default database"""
  71
  72     MODE = Enum(['READ_ONLY', 'READ_WRITE'])
  73     """Constants: Mode in which to open the database"""
  74
  75     """notmuch_database_get_directory"""
  76     _get_directory = nmlib.notmuch_database_get_directory
  77     _get_directory.argtypes = [NotmuchDatabaseP, c_char_p, POINTER(NotmuchDirectoryP)]
  78     _get_directory.restype = c_uint
  79
  80     """notmuch_database_get_path"""
  81     _get_path = nmlib.notmuch_database_get_path
  82     _get_path.argtypes = [NotmuchDatabaseP]
  83     _get_path.restype = c_char_p
  84
  85     """notmuch_database_get_version"""
  86     _get_version = nmlib.notmuch_database_get_version
  87     _get_version.argtypes = [NotmuchDatabaseP]
  88     _get_version.restype = c_uint
  89
  90     """notmuch_database_open"""
  91     _open = nmlib.notmuch_database_open
  92     _open.argtypes = [c_char_p, c_uint, POINTER(NotmuchDatabaseP)]
  93     _open.restype = c_uint
  94
  95     """notmuch_database_upgrade"""
  96     _upgrade = nmlib.notmuch_database_upgrade
  97     _upgrade.argtypes = [NotmuchDatabaseP, c_void_p, c_void_p]
  98     _upgrade.restype = c_uint
  99
 100     """ notmuch_database_find_message"""
 101     _find_message = nmlib.notmuch_database_find_message
 102     _find_message.argtypes = [NotmuchDatabaseP, c_char_p,
 103                               POINTER(NotmuchMessageP)]
 104     _find_message.restype = c_uint
 105
 106     """notmuch_database_find_message_by_filename"""
 107     _find_message_by_filename = nmlib.notmuch_database_find_message_by_filename
 108     _find_message_by_filename.argtypes = [NotmuchDatabaseP, c_char_p,
 109                                           POINTER(NotmuchMessageP)]
 110     _find_message_by_filename.restype = c_uint
 111
 112     """notmuch_database_get_all_tags"""
 113     _get_all_tags = nmlib.notmuch_database_get_all_tags
 114     _get_all_tags.argtypes = [NotmuchDatabaseP]
 115     _get_all_tags.restype = NotmuchTagsP
 116
 117     """notmuch_database_create"""
 118     _create = nmlib.notmuch_database_create
 119     _create.argtypes = [c_char_p, POINTER(NotmuchDatabaseP)]
 120     _create.restype = c_uint
 121
 122     def __init__(self, path = None, create = False,
 123                  mode = MODE.READ_ONLY):
 124         """If *path* is `None`, we will try to read a users notmuch
 125         configuration and use his configured database. The location of the
 126         configuration file can be specified through the environment variable
 127         *NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
 128
 129         If *create* is `True`, the database will always be created in
 130         :attr:`MODE`.READ_WRITE mode. Default mode for opening is READ_ONLY.
 131
 132         :param path:   Directory to open/create the database in (see
 133                        above for behavior if `None`)
 134         :type path:    `str` or `None`
 135         :param create: Pass `False` to open an existing, `True` to create a new
 136                        database.
 137         :type create:  bool
 138         :param mode:   Mode to open a database in. Is always
 139                        :attr:`MODE`.READ_WRITE when creating a new one.
 140         :type mode:    :attr:`MODE`
 141         :raises: :exc:`NotmuchError` or derived exception in case of
 142             failure.
 143         """
 144         self._db = None
 145         self.mode = mode
 146         if path is None:
 147             # no path specified. use a user's default database
 148             if Database._std_db_path is None:
 149                 #the following line throws a NotmuchError if it fails
 150                 Database._std_db_path = self._get_user_default_db()
 151             path = Database._std_db_path
 152
 153         if create == False:
 154             self.open(path, mode)
 155         else:
 156             self.create(path)
 157
 158     _destroy = nmlib.notmuch_database_destroy
 159     _destroy.argtypes = [NotmuchDatabaseP]
 160     _destroy.restype = None
 161
 162     def __del__(self):
 163         if self._db:
 164             self._destroy(self._db)
 165
 166     def _assert_db_is_initialized(self):
 167         """Raises :exc:`NotInitializedError` if self._db is `None`"""
 168         if not self._db:
 169             raise NotInitializedError()
 170
 171     def create(self, path):
 172         """Creates a new notmuch database
 173
 174         This function is used by __init__() and usually does not need
 175         to be called directly. It wraps the underlying
 176         *notmuch_database_create* function and creates a new notmuch
 177         database at *path*. It will always return a database in :attr:`MODE`
 178         .READ_WRITE mode as creating an empty database for
 179         reading only does not make a great deal of sense.
 180
 181         :param path: A directory in which we should create the database.
 182         :type path: str
 183         :raises: :exc:`NotmuchError` in case of any failure
 184                     (possibly after printing an error message on stderr).
 185         """
 186         if self._db:
 187             raise NotmuchError(message="Cannot create db, this Database() "
 188                                        "already has an open one.")
 189
 190         db = NotmuchDatabaseP()
 191         status = Database._create(_str(path), Database.MODE.READ_WRITE, byref(db))
 192
 193         if status != STATUS.SUCCESS:
 194             raise NotmuchError(status)
 195         self._db = db
 196         return status
 197
 198     def open(self, path, mode=0):
 199         """Opens an existing database
 200
 201         This function is used by __init__() and usually does not need
 202         to be called directly. It wraps the underlying
 203         *notmuch_database_open* function.
 204
 205         :param status: Open the database in read-only or read-write mode
 206         :type status:  :attr:`MODE`
 207         :raises: Raises :exc:`NotmuchError` in case of any failure
 208                     (possibly after printing an error message on stderr).
 209         """
 210         db = NotmuchDatabaseP()
 211         status = Database._open(_str(path), mode, byref(db))
 212
 213         if status != STATUS.SUCCESS:
 214             raise NotmuchError(status)
 215         self._db = db
 216         return status
 217
 218     _close = nmlib.notmuch_database_close
 219     _close.argtypes = [NotmuchDatabaseP]
 220     _close.restype = None
 221
 222     def close(self):
 223         '''
 224         Closes the notmuch database.
 225
 226         .. warning::
 227
 228             This function closes the notmuch database. From that point
 229             on every method invoked on any object ever derived from
 230             the closed database may cease to function and raise a
 231             NotmuchError.
 232         '''
 233         if self._db:
 234             self._close(self._db)
 235
 236     def __enter__(self):
 237         '''
 238         Implements the context manager protocol.
 239         '''
 240         return self
 241
 242     def __exit__(self, exc_type, exc_value, traceback):
 243         '''
 244         Implements the context manager protocol.
 245         '''
 246         self.close()
 247
 248     def get_path(self):
 249         """Returns the file path of an open database"""
 250         self._assert_db_is_initialized()
 251         return Database._get_path(self._db).decode('utf-8')
 252
 253     def get_version(self):
 254         """Returns the database format version
 255
 256         :returns: The database version as positive integer
 257         """
 258         self._assert_db_is_initialized()
 259         return Database._get_version(self._db)
 260
 261     _needs_upgrade = nmlib.notmuch_database_needs_upgrade
 262     _needs_upgrade.argtypes = [NotmuchDatabaseP]
 263     _needs_upgrade.restype = bool
 264
 265     def needs_upgrade(self):
 266         """Does this database need to be upgraded before writing to it?
 267
 268         If this function returns `True` then no functions that modify the
 269         database (:meth:`add_message`,
 270         :meth:`Message.add_tag`, :meth:`Directory.set_mtime`,
 271         etc.) will work unless :meth:`upgrade` is called successfully first.
 272
 273         :returns: `True` or `False`
 274         """
 275         self._assert_db_is_initialized()
 276         return self._needs_upgrade(self._db)
 277
 278     def upgrade(self):
 279         """Upgrades the current database
 280
 281         After opening a database in read-write mode, the client should
 282         check if an upgrade is needed (notmuch_database_needs_upgrade) and
 283         if so, upgrade with this function before making any modifications.
 284
 285         NOT IMPLEMENTED: The optional progress_notify callback can be
 286         used by the caller to provide progress indication to the
 287         user. If non-NULL it will be called periodically with
 288         'progress' as a floating-point value in the range of [0.0..1.0]
 289         indicating the progress made so far in the upgrade process.
 290
 291         :TODO: catch exceptions, document return values and etc...
 292         """
 293         self._assert_db_is_initialized()
 294         status = Database._upgrade(self._db, None, None)
 295         #TODO: catch exceptions, document return values and etc
 296         return status
 297
 298     _begin_atomic = nmlib.notmuch_database_begin_atomic
 299     _begin_atomic.argtypes = [NotmuchDatabaseP]
 300     _begin_atomic.restype = c_uint
 301
 302     def begin_atomic(self):
 303         """Begin an atomic database operation
 304
 305         Any modifications performed between a successful
 306         :meth:`begin_atomic` and a :meth:`end_atomic` will be applied to
 307         the database atomically.  Note that, unlike a typical database
 308         transaction, this only ensures atomicity, not durability;
 309         neither begin nor end necessarily flush modifications to disk.
 310
 311         :returns: :attr:`STATUS`.SUCCESS or raises
 312         :raises: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION
 313                     Xapian exception occurred; atomic section not entered.
 314
 315         *Added in notmuch 0.9*"""
 316         self._assert_db_is_initialized()
 317         status = self._begin_atomic(self._db)
 318         if status != STATUS.SUCCESS:
 319             raise NotmuchError(status)
 320         return status
 321
 322     _end_atomic = nmlib.notmuch_database_end_atomic
 323     _end_atomic.argtypes = [NotmuchDatabaseP]
 324     _end_atomic.restype = c_uint
 325
 326     def end_atomic(self):
 327         """Indicate the end of an atomic database operation
 328
 329         See :meth:`begin_atomic` for details.
 330
 331         :returns: :attr:`STATUS`.SUCCESS or raises
 332
 333         :raises:
 334             :exc:`NotmuchError`:
 335                 :attr:`STATUS`.XAPIAN_EXCEPTION
 336                     A Xapian exception occurred; atomic section not
 337                     ended.
 338                 :attr:`STATUS`.UNBALANCED_ATOMIC:
 339                     end_atomic has been called more times than begin_atomic.
 340
 341         *Added in notmuch 0.9*"""
 342         self._assert_db_is_initialized()
 343         status = self._end_atomic(self._db)
 344         if status != STATUS.SUCCESS:
 345             raise NotmuchError(status)
 346         return status
 347
 348     def get_directory(self, path):
 349         """Returns a :class:`Directory` of path,
 350
 351         :param path: An unicode string containing the path relative to the path
 352               of database (see :meth:`get_path`), or else should be an absolute
 353               path with initial components that match the path of 'database'.
 354         :returns: :class:`Directory` or raises an exception.
 355         :raises: :exc:`FileError` if path is not relative database or absolute
 356                  with initial components same as database.
 357         """
 358         self._assert_db_is_initialized()
 359
 360         # sanity checking if path is valid, and make path absolute
 361         if path and path[0] == os.sep:
 362             # we got an absolute path
 363             if not path.startswith(self.get_path()):
 364                 # but its initial components are not equal to the db path
 365                 raise FileError('Database().get_directory() called '
 366                                 'with a wrong absolute path')
 367             abs_dirpath = path
 368         else:
 369             #we got a relative path, make it absolute
 370             abs_dirpath = os.path.abspath(os.path.join(self.get_path(), path))
 371
 372         dir_p = NotmuchDirectoryP()
 373         status = Database._get_directory(self._db, _str(path), byref(dir_p))
 374
 375         if status != STATUS.SUCCESS:
 376             raise NotmuchError(status)
 377         if not dir_p:
 378             return None
 379
 380         # return the Directory, init it with the absolute path
 381         return Directory(abs_dirpath, dir_p, self)
 382
 383     _add_message = nmlib.notmuch_database_add_message
 384     _add_message.argtypes = [NotmuchDatabaseP, c_char_p,
 385                              POINTER(NotmuchMessageP)]
 386     _add_message.restype = c_uint
 387
 388     def add_message(self, filename, sync_maildir_flags=False):
 389         """Adds a new message to the database
 390
 391         :param filename: should be a path relative to the path of the
 392             open database (see :meth:`get_path`), or else should be an
 393             absolute filename with initial components that match the
 394             path of the database.
 395
 396             The file should be a single mail message (not a
 397             multi-message mbox) that is expected to remain at its
 398             current location, since the notmuch database will reference
 399             the filename, and will not copy the entire contents of the
 400             file.
 401
 402         :param sync_maildir_flags: If the message contains Maildir
 403             flags, we will -depending on the notmuch configuration- sync
 404             those tags to initial notmuch tags, if set to `True`. It is
 405             `False` by default to remain consistent with the libnotmuch
 406             API. You might want to look into the underlying method
 407             :meth:`Message.maildir_flags_to_tags`.
 408
 409         :returns: On success, we return
 410
 411            1) a :class:`Message` object that can be used for things
 412               such as adding tags to the just-added message.
 413            2) one of the following :attr:`STATUS` values:
 414
 415               :attr:`STATUS`.SUCCESS
 416                   Message successfully added to database.
 417               :attr:`STATUS`.DUPLICATE_MESSAGE_ID
 418                   Message has the same message ID as another message already
 419                   in the database. The new filename was successfully added
 420                   to the list of the filenames for the existing message.
 421
 422         :rtype:   2-tuple(:class:`Message`, :attr:`STATUS`)
 423
 424         :raises: Raises a :exc:`NotmuchError` with the following meaning.
 425               If such an exception occurs, nothing was added to the database.
 426
 427               :attr:`STATUS`.FILE_ERROR
 428                       An error occurred trying to open the file, (such as
 429                       permission denied, or file not found, etc.).
 430               :attr:`STATUS`.FILE_NOT_EMAIL
 431                       The contents of filename don't look like an email
 432                       message.
 433               :attr:`STATUS`.READ_ONLY_DATABASE
 434                       Database was opened in read-only mode so no message can
 435                       be added.
 436         """
 437         self._assert_db_is_initialized()
 438         msg_p = NotmuchMessageP()
 439         status = self._add_message(self._db, _str(filename), byref(msg_p))
 440
 441         if not status in [STATUS.SUCCESS, STATUS.DUPLICATE_MESSAGE_ID]:
 442             raise NotmuchError(status)
 443
 444         #construct Message() and return
 445         msg = Message(msg_p, self)
 446         #automatic sync initial tags from Maildir flags
 447         if sync_maildir_flags:
 448             msg.maildir_flags_to_tags()
 449         return (msg, status)
 450
 451     _remove_message = nmlib.notmuch_database_remove_message
 452     _remove_message.argtypes = [NotmuchDatabaseP, c_char_p]
 453     _remove_message.restype = c_uint
 454
 455     def remove_message(self, filename):
 456         """Removes a message (filename) from the given notmuch database
 457
 458         Note that only this particular filename association is removed from
 459         the database. If the same message (as determined by the message ID)
 460         is still available via other filenames, then the message will
 461         persist in the database for those filenames. When the last filename
 462         is removed for a particular message, the database content for that
 463         message will be entirely removed.
 464
 465         :returns: A :attr:`STATUS` value with the following meaning:
 466
 467              :attr:`STATUS`.SUCCESS
 468                The last filename was removed and the message was removed
 469                from the database.
 470              :attr:`STATUS`.DUPLICATE_MESSAGE_ID
 471                This filename was removed but the message persists in the
 472                database with at least one other filename.
 473
 474         :raises: Raises a :exc:`NotmuchError` with the following meaning.
 475              If such an exception occurs, nothing was removed from the
 476              database.
 477
 478              :attr:`STATUS`.READ_ONLY_DATABASE
 479                Database was opened in read-only mode so no message can be
 480                removed.
 481         """
 482         self._assert_db_is_initialized()
 483         return self._remove_message(self._db, _str(filename))
 484
 485     def find_message(self, msgid):
 486         """Returns a :class:`Message` as identified by its message ID
 487
 488         Wraps the underlying *notmuch_database_find_message* function.
 489
 490         :param msgid: The message ID
 491         :type msgid: unicode or str
 492         :returns: :class:`Message` or `None` if no message is found.
 493         :raises:
 494             :exc:`OutOfMemoryError`
 495                   If an Out-of-memory occured while constructing the message.
 496             :exc:`XapianError`
 497                   In case of a Xapian Exception. These exceptions
 498                   include "Database modified" situations, e.g. when the
 499                   notmuch database has been modified by another program
 500                   in the meantime. In this case, you should close and
 501                   reopen the database and retry.
 502             :exc:`NotInitializedError` if
 503                     the database was not intitialized.
 504         """
 505         self._assert_db_is_initialized()
 506         msg_p = NotmuchMessageP()
 507         status = Database._find_message(self._db, _str(msgid), byref(msg_p))
 508         if status != STATUS.SUCCESS:
 509             raise NotmuchError(status)
 510         return msg_p and Message(msg_p, self) or None
 511
 512     def find_message_by_filename(self, filename):
 513         """Find a message with the given filename
 514
 515         :returns: If the database contains a message with the given
 516             filename, then a class:`Message:` is returned.  This
 517             function returns None if no message is found with the given
 518             filename.
 519
 520         :raises: :exc:`OutOfMemoryError` if an Out-of-memory occured while
 521                  constructing the message.
 522         :raises: :exc:`XapianError` in case of a Xapian Exception.
 523                  These exceptions include "Database modified"
 524                  situations, e.g. when the notmuch database has been
 525                  modified by another program in the meantime. In this
 526                  case, you should close and reopen the database and
 527                  retry.
 528         :raises: :exc:`NotInitializedError` if the database was not
 529                  intitialized.
 530
 531         *Added in notmuch 0.9*"""
 532         self._assert_db_is_initialized()
 533
 534         msg_p = NotmuchMessageP()
 535         status = Database._find_message_by_filename(self._db, _str(filename),
 536                                                     byref(msg_p))
 537         if status != STATUS.SUCCESS:
 538             raise NotmuchError(status)
 539         return msg_p and Message(msg_p, self) or None
 540
 541     def get_all_tags(self):
 542         """Returns :class:`Tags` with a list of all tags found in the database
 543
 544         :returns: :class:`Tags`
 545         :execption: :exc:`NotmuchError` with :attr:`STATUS`.NULL_POINTER
 546                     on error
 547         """
 548         self._assert_db_is_initialized()
 549         tags_p = Database._get_all_tags(self._db)
 550         if not tags_p:
 551             raise NullPointerError()
 552         return Tags(tags_p, self)
 553
 554     def create_query(self, querystring):
 555         """Returns a :class:`Query` derived from this database
 556
 557         This is a shorthand method for doing::
 558
 559           # short version
 560           # Automatically frees the Database() when 'q' is deleted
 561
 562           q  = Database(dbpath).create_query('from:"Biene Maja"')
 563
 564           # long version, which is functionally equivalent but will keep the
 565           # Database in the 'db' variable around after we delete 'q':
 566
 567           db = Database(dbpath)
 568           q  = Query(db,'from:"Biene Maja"')
 569
 570         This function is a python extension and not in the underlying C API.
 571         """
 572         return Query(self, querystring)
 573
 574     def __repr__(self):
 575         return "'Notmuch DB " + self.get_path() + "'"
 576
 577     def _get_user_default_db(self):
 578         """ Reads a user's notmuch config and returns his db location
 579
 580         Throws a NotmuchError if it cannot find it"""
 581         config = SafeConfigParser()
 582         conf_f = os.getenv('NOTMUCH_CONFIG',
 583                            os.path.expanduser('~/.notmuch-config'))
 584         config.readfp(codecs.open(conf_f, 'r', 'utf-8'))
 585         if not config.has_option('database', 'path'):
 586             raise NotmuchError(message="No DB path specified"
 587                                        " and no user default found")
 588         return config.get('database', 'path')