git.notmuchmail.org Git - notmuch/blob - cnotmuch/database.py

   1 import ctypes, os
   2 from ctypes import c_int, c_char_p, c_void_p, c_uint, c_uint64, c_bool
   3 from cnotmuch.globals import nmlib, STATUS, NotmuchError, Enum
   4 import logging
   5 from datetime import date
   6
   7 class Database(object):
   8     """Represents a notmuch database (wraps notmuch_database_t)
   9
  10     .. note:: Do remember that as soon as we tear down this object,
  11            all underlying derived objects such as queries, threads,
  12            messages, tags etc will be freed by the underlying library
  13            as well. Accessing these objects will lead to segfaults and
  14            other unexpected behavior. See above for more details.
  15     """
  16     _std_db_path = None
  17     """Class attribute to cache user's default database"""
  18
  19     MODE = Enum(['READ_ONLY','READ_WRITE'])
  20     """Constants: Mode in which to open the database"""
  21
  22     """notmuch_database_get_path (notmuch_database_t *database)"""
  23     _get_path = nmlib.notmuch_database_get_path
  24     _get_path.restype = c_char_p
  25
  26     """notmuch_database_get_version"""
  27     _get_version = nmlib.notmuch_database_get_version
  28     _get_version.restype = c_uint
  29
  30     """notmuch_database_open (const char *path, notmuch_database_mode_t mode)"""
  31     _open = nmlib.notmuch_database_open
  32     _open.restype = c_void_p
  33
  34     """ notmuch_database_find_message """
  35     _find_message = nmlib.notmuch_database_find_message
  36     _find_message.restype = c_void_p
  37
  38     """notmuch_database_get_all_tags (notmuch_database_t *database)"""
  39     _get_all_tags = nmlib.notmuch_database_get_all_tags
  40     _get_all_tags.restype = c_void_p
  41
  42     """ notmuch_database_create(const char *path):"""
  43     _create = nmlib.notmuch_database_create
  44     _create.restype = c_void_p
  45
  46     def __init__(self, path=None, create=False, mode= 0):
  47         """If *path* is *None*, we will try to read a users notmuch
  48         configuration and use his configured database. The location of the
  49         configuration file can be specified through the environment variable
  50         *NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
  51
  52         If *create* is `True`, the database will always be created in
  53         :attr:`MODE`.READ_WRITE mode. Default mode for opening is READ_ONLY.
  54
  55         :param path:   Directory to open/create the database in (see
  56                        above for behavior if `None`)
  57         :type path:    `str` or `None`
  58         :param create: Pass `False` to open an existing, `True` to create a new
  59                        database.
  60         :type create:  bool
  61         :param mode:   Mode to open a database in. Is always
  62                        :attr:`MODE`.READ_WRITE when creating a new one.
  63         :type mode:    :attr:`MODE`
  64         :returns:      Nothing
  65         :exception:    :exc:`NotmuchError` in case of failure.
  66         """
  67         self._db = None
  68         if path is None:
  69             # no path specified. use a user's default database
  70             if Database._std_db_path is None:
  71                 #the following line throws a NotmuchError if it fails
  72                 Database._std_db_path = self._get_user_default_db()
  73             path = Database._std_db_path
  74
  75         if create == False:
  76             self.open(path, mode)
  77         else:
  78             self.create(path)
  79
  80     def create(self, path):
  81         """Creates a new notmuch database
  82
  83         This function is used by __init__() and usually does not need
  84         to be called directly. It wraps the underlying
  85         *notmuch_database_create* function and creates a new notmuch
  86         database at *path*. It will always return a database in
  87         :attr:`MODE`.READ_WRITE mode as creating an empty database for
  88         reading only does not make a great deal of sense.
  89
  90         :param path: A directory in which we should create the database.
  91         :type path: str
  92         :returns: Nothing
  93         :exception: :exc:`NotmuchError` in case of any failure
  94                     (after printing an error message on stderr).
  95         """
  96         if self._db is not None:
  97             raise NotmuchError(
  98             message="Cannot create db, this Database() already has an open one.")
  99
 100         res = Database._create(path, Database.MODE.READ_WRITE)
 101
 102         if res is None:
 103             raise NotmuchError(
 104                 message="Could not create the specified database")
 105         self._db = res
 106
 107     def open(self, path, mode= 0):
 108         """Opens an existing database
 109
 110         This function is used by __init__() and usually does not need
 111         to be called directly. It wraps the underlying
 112         *notmuch_database_open* function.
 113
 114         :param status: Open the database in read-only or read-write mode
 115         :type status:  :attr:`MODE`
 116         :returns: Nothing
 117         :exception: Raises :exc:`NotmuchError` in case
 118                     of any failure (after printing an error message on stderr).
 119         """
 120
 121         res = Database._open(path, mode)
 122
 123         if res is None:
 124             raise NotmuchError(
 125                 message="Could not open the specified database")
 126         self._db = res
 127
 128     def get_path(self):
 129         """Returns the file path of an open database
 130
 131         Wraps notmuch_database_get_path"""
 132         return Database._get_path(self._db)
 133
 134     def get_version(self):
 135         """Returns the database format version
 136
 137         :returns: The database version as positive integer
 138         :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
 139                     the database was not intitialized.
 140         """
 141         if self._db is None:
 142             raise NotmuchError(STATUS.NOT_INITIALIZED)
 143
 144         return Database._get_version (self._db)
 145
 146     def needs_upgrade(self):
 147         """Does this database need to be upgraded before writing to it?
 148
 149         If this function returns True then no functions that modify the
 150         database (:meth:`add_message`, :meth:`add_tag`,
 151         :meth:`Directory.set_mtime`, etc.) will work unless :meth:`upgrade`
 152         is called successfully first.
 153
 154         :returns: `True` or `False`
 155         :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
 156                     the database was not intitialized.
 157         """
 158         if self._db is None:
 159             raise NotmuchError(STATUS.NOT_INITIALIZED)
 160
 161         return notmuch_database_needs_upgrade(self.db)
 162
 163     def find_message(self, msgid):
 164         """Returns a :class:`Message` as identified by its message ID
 165
 166         Wraps the underlying *notmuch_database_find_message* function.
 167
 168         :param msgid: The message ID
 169         :type msgid: string
 170         :returns: :class:`Message` or `None` if no message is found or if an
 171                   out-of-memory situation occurs.
 172         :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
 173                   the database was not intitialized.
 174         """
 175         if self._db is None:
 176             raise NotmuchError(STATUS.NOT_INITIALIZED)
 177         msg_p = Database._find_message(self._db, msgid)
 178         if msg_p is None:
 179             return None
 180         return Message(msg_p, self)
 181
 182     def get_all_tags(self):
 183         """Returns :class:`Tags` with a list of all tags found in the database
 184
 185         :returns: :class:`Tags`
 186         :execption: :exc:`NotmuchError` with STATUS.NULL_POINTER on error
 187         """
 188         if self._db is None:
 189             raise NotmuchError(STATUS.NOT_INITIALIZED)
 190
 191         tags_p = Database._get_all_tags (self._db)
 192         if tags_p == None:
 193             raise NotmuchError(STATUS.NULL_POINTER)
 194         return Tags(tags_p, self)
 195
 196     def __repr__(self):
 197         return "'Notmuch DB " + self.get_path() + "'"
 198
 199     def __del__(self):
 200         """Close and free the notmuch database if needed"""
 201         if self._db is not None:
 202             logging.debug("Freeing the database now")
 203             nmlib.notmuch_database_close(self._db)
 204
 205     def _get_user_default_db(self):
 206         """ Reads a user's notmuch config and returns his db location
 207
 208         Throws a NotmuchError if it cannot find it"""
 209         from ConfigParser import SafeConfigParser
 210         config = SafeConfigParser()
 211         conf_f = os.getenv('NOTMUCH_CONFIG',
 212                            os.path.expanduser('~/.notmuch-config'))
 213         config.read(conf_f)
 214         if not config.has_option('database','path'):
 215             raise NotmuchError(message=
 216                                "No DB path specified and no user default found")
 217         return config.get('database','path')
 218
 219     @property
 220     def db_p(self):
 221         """Property returning a pointer to the notmuch_database_t or `None`
 222
 223         This should normally not be needed by a user."""
 224         return self._db
 225
 226 #------------------------------------------------------------------------------
 227 class Query(object):
 228     """ Represents a search query on an opened :class:`Database`.
 229
 230     A query selects and filters a subset of messages from the notmuch
 231     database we derive from.
 232
 233     Technically, it wraps the underlying *notmuch_query_t* struct.
 234
 235     .. note:: Do remember that as soon as we tear down this object,
 236            all underlying derived objects such as threads,
 237            messages, tags etc will be freed by the underlying library
 238            as well. Accessing these objects will lead to segfaults and
 239            other unexpected behavior. See above for more details.
 240     """
 241     # constants
 242     SORT = Enum(['OLDEST_FIRST','NEWEST_FIRST','MESSAGE_ID'])
 243     """Constants: Sort order in which to return results"""
 244
 245     """notmuch_query_create"""
 246     _create = nmlib.notmuch_query_create
 247     _create.restype = c_void_p
 248
 249     """notmuch_query_search_messages"""
 250     _search_messages = nmlib.notmuch_query_search_messages
 251     _search_messages.restype = c_void_p
 252
 253
 254     """notmuch_query_count_messages"""
 255     _count_messages = _nmlib.notmuch_query_count_messages
 256     _count_messages.restype = c_uint
 257
 258     def __init__(self, db, querystr):
 259         """
 260         :param db: An open database which we derive the Query from.
 261         :type db: :class:`Database`
 262         :param querystr: The query string for the message.
 263         :type querystr: str
 264         """
 265         self._db = None
 266         self._query = None
 267         self.create(db, querystr)
 268
 269     def create(self, db, querystr):
 270         """Creates a new query derived from a Database.
 271
 272         This function is utilized by __init__() and usually does not need to
 273         be called directly.
 274
 275         :param db: Database to create the query from.
 276         :type db: :class:`Database`
 277         :param querystr: The query string
 278         :type querystr: str
 279         :returns: Nothing
 280         :exception: :exc:`NotmuchError`
 281
 282                       * STATUS.NOT_INITIALIZED if db is not inited
 283                       * STATUS.NULL_POINTER if the query creation failed
 284                         (too little memory)
 285         """
 286         if db.db_p is None:
 287             raise NotmuchError(STATUS.NOT_INITIALIZED)
 288         # create reference to parent db to keep it alive
 289         self._db = db
 290
 291         # create query, return None if too little mem available
 292         query_p = Query._create(db.db_p, querystr)
 293         if query_p is None:
 294             NotmuchError(STATUS.NULL_POINTER)
 295         self._query = query_p
 296
 297     def set_sort(self, sort):
 298         """Set the sort order future results will be delivered in
 299
 300         Wraps the underlying *notmuch_query_set_sort* function.
 301
 302         :param sort: Sort order (see :attr:`Query.SORT`)
 303         :returns: Nothing
 304         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if query has not
 305                     been initialized.
 306         """
 307         if self._query is None:
 308             raise NotmuchError(STATUS.NOT_INITIALIZED)
 309
 310         nmlib.notmuch_query_set_sort(self._query, sort)
 311
 312     def search_messages(self):
 313         """Filter messages according to the query and return
 314         :class:`Messages` in the defined sort order
 315
 316         Technically, it wraps the underlying
 317         *notmuch_query_search_messages* function.
 318
 319         :returns: :class:`Messages`
 320         :exception: :exc:`NotmuchError`
 321
 322                       * STATUS.NOT_INITIALIZED if query is not inited
 323                       * STATUS.NULL_POINTER if search_messages failed
 324         """
 325         if self._query is None:
 326             raise NotmuchError(STATUS.NOT_INITIALIZED)
 327
 328         msgs_p = Query._search_messages(self._query)
 329
 330         if msgs_p is None:
 331             NotmuchError(STATUS.NULL_POINTER)
 332
 333         return Messages(msgs_p,self)
 334
 335     def count_messages(self):
 336         """Estimate the number of messages matching the query
 337
 338         This function performs a search and returns Xapian's best
 339         guess as to the number of matching messages. It is somewhat
 340         faster than performing :meth:`search_messages` and counting
 341         the result with `len()`. Technically, it wraps the underlying
 342         *notmuch_query_count_messages* function.
 343
 344         :returns: :class:`Messages`
 345         :exception: :exc:`NotmuchError`
 346
 347                       * STATUS.NOT_INITIALIZED if query is not inited
 348         """
 349         if self._query is None:
 350             raise NotmuchError(STATUS.NOT_INITIALIZED)
 351
 352         return Query._count_messages(self._query)
 353
 354     def __del__(self):
 355         """Close and free the Query"""
 356         if self._query is not None:
 357             logging.debug("Freeing the Query now")
 358             nmlib.notmuch_query_destroy (self._query)
 359
 360 #------------------------------------------------------------------------------
 361 class Tags(object):
 362     """Represents a list of notmuch tags
 363
 364     This object provides an iterator over a list of notmuch tags. Do
 365     note that the underlying library only provides a one-time iterator
 366     (it cannot reset the iterator to the start). Thus iterating over
 367     the function will "exhaust" the list of tags, and a subsequent
 368     iteration attempt will raise a :exc:`NotmuchError`
 369     STATUS.NOT_INITIALIZED. Also note, that any function that uses
 370     iteration (nearly all) will also exhaust the tags. So both::
 371
 372       for tag in tags: print tag
 373
 374     as well as::
 375
 376        number_of_tags = len(tags)
 377
 378     and even a simple::
 379
 380        #str() iterates over all tags to construct a space separated list
 381        print(str(tags))
 382
 383     will "exhaust" the Tags. If you need to re-iterate over a list of
 384     tags you will need to retrieve a new :class:`Tags` object.
 385     """
 386
 387     #notmuch_tags_get
 388     _get = nmlib.notmuch_tags_get
 389     _get.restype = c_char_p
 390
 391     def __init__(self, tags_p, parent=None):
 392         """
 393         :param tags_p: A pointer to an underlying *notmuch_tags_t*
 394              structure. These are not publically exposed, so a user
 395              will almost never instantiate a :class:`Tags` object
 396              herself. They are usually handed back as a result,
 397              e.g. in :meth:`Database.get_all_tags`.  *tags_p* must be
 398              valid, we will raise an :exc:`NotmuchError`
 399              (STATUS.NULL_POINTER) if it is `None`.
 400         :type tags_p: :class:`ctypes.c_void_p`
 401         :param parent: The parent object (ie :class:`Database` or
 402              :class:`Message` these tags are derived from, and saves a
 403              reference to it, so we can automatically delete the db object
 404              once all derived objects are dead.
 405         :TODO: Make the iterator optionally work more than once by
 406                cache the tags in the Python object(?)
 407         """
 408         if tags_p is None:
 409             NotmuchError(STATUS.NULL_POINTER)
 410
 411         self._tags = tags_p
 412         #save reference to parent object so we keep it alive
 413         self._parent = parent
 414         logging.debug("Inited Tags derived from %s" %(repr(parent)))
 415
 416     def __iter__(self):
 417         """ Make Tags an iterator """
 418         return self
 419
 420     def next(self):
 421         if self._tags is None:
 422             raise NotmuchError(STATUS.NOT_INITIALIZED)
 423
 424         if not nmlib.notmuch_tags_valid(self._tags):
 425             self._tags = None
 426             raise StopIteration
 427
 428         tag = Tags._get (self._tags)
 429         nmlib.notmuch_tags_move_to_next(self._tags)
 430         return tag
 431
 432     def __len__(self):
 433         """len(:class:`Tags`) returns the number of contained tags
 434
 435         .. note:: As this iterates over the tags, we will not be able
 436                to iterate over them again (as in retrieve them)! If
 437                the tags have been exhausted already, this will raise a
 438                :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
 439                subsequent attempts.
 440         """
 441         if self._tags is None:
 442             raise NotmuchError(STATUS.NOT_INITIALIZED)
 443
 444         i=0
 445         while nmlib.notmuch_tags_valid(self._msgs):
 446             nmlib.notmuch_tags_move_to_next(self._msgs)
 447             i += 1
 448         self._tags = None
 449         return i
 450
 451     def __str__(self):
 452         """The str() representation of Tags() is a space separated list of tags
 453
 454         .. note:: As this iterates over the tags, we will not be able
 455                to iterate over them again (as in retrieve them)! If
 456                the tags have been exhausted already, this will raise a
 457                :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
 458                subsequent attempts.
 459         """
 460         return " ".join(self)
 461
 462     def __del__(self):
 463         """Close and free the notmuch tags"""
 464         if self._tags is not None:
 465             logging.debug("Freeing the Tags now")
 466             nmlib.notmuch_tags_destroy (self._tags)
 467
 468
 469 #------------------------------------------------------------------------------
 470 class Messages(object):
 471     """Represents a list of notmuch messages
 472
 473     This object provides an iterator over a list of notmuch messages
 474     (Technically, it provides a wrapper for the underlying
 475     *notmuch_messages_t* structure). Do note that the underlying
 476     library only provides a one-time iterator (it cannot reset the
 477     iterator to the start). Thus iterating over the function will
 478     "exhaust" the list of messages, and a subsequent iteration attempt
 479     will raise a :exc:`NotmuchError` STATUS.NOT_INITIALIZED. Also
 480     note, that any function that uses iteration will also
 481     exhaust the messages. So both::
 482
 483       for msg in msgs: print msg
 484
 485     as well as::
 486
 487        number_of_msgs = len(msgs)
 488
 489     will "exhaust" the Messages. If you need to re-iterate over a list of
 490     messages you will need to retrieve a new :class:`Messages` object.
 491
 492     Things are not as bad as it seems though, you can store and reuse
 493     the single Message objects as often as you want as long as you
 494     keep the parent Messages object around. (Recall that due to
 495     hierarchical memory allocation, all derived Message objects will
 496     be invalid when we delete the parent Messages() object, even if it
 497     was already "exhausted".) So this works::
 498
 499       db   = Database()
 500       msgs = Query(db,'').search_messages() #get a Messages() object
 501       msglist = []
 502       for m in msgs:
 503          msglist.append(m)
 504
 505       # msgs is "exhausted" now and even len(msgs) will raise an exception.
 506       # However it will be kept around until all retrieved Message() objects are
 507       # also deleted. If you did e.g. an explicit del(msgs) here, the
 508       # following lines would fail.
 509
 510       # You can reiterate over *msglist* however as often as you want.
 511       # It is simply a list with Message objects.
 512
 513       print (msglist[0].get_filename())
 514       print (msglist[1].get_filename())
 515       print (msglist[0].get_message_id())
 516     """
 517
 518     #notmuch_tags_get
 519     _get = nmlib.notmuch_messages_get
 520     _get.restype = c_void_p
 521
 522     _collect_tags = nmlib.notmuch_messages_collect_tags
 523     _collect_tags.restype = c_void_p
 524
 525     def __init__(self, msgs_p, parent=None):
 526         """
 527         :param msgs_p:  A pointer to an underlying *notmuch_messages_t*
 528              structure. These are not publically exposed, so a user
 529              will almost never instantiate a :class:`Messages` object
 530              herself. They are usually handed back as a result,
 531              e.g. in :meth:`Query.search_messages`.  *msgs_p* must be
 532              valid, we will raise an :exc:`NotmuchError`
 533              (STATUS.NULL_POINTER) if it is `None`.
 534         :type msgs_p: :class:`ctypes.c_void_p`
 535         :param parent: The parent object
 536              (ie :class:`Query`) these tags are derived from. It saves
 537              a reference to it, so we can automatically delete the db
 538              object once all derived objects are dead.
 539         :TODO: Make the iterator work more than once and cache the tags in
 540                the Python object.(?)
 541         """
 542         if msgs_p is None:
 543             NotmuchError(STATUS.NULL_POINTER)
 544
 545         self._msgs = msgs_p
 546         #store parent, so we keep them alive as long as self  is alive
 547         self._parent = parent
 548         logging.debug("Inited Messages derived from %s" %(str(parent)))
 549
 550     def collect_tags(self):
 551         """Return the unique :class:`Tags` in the contained messages
 552
 553         :returns: :class:`Tags`
 554         :exceptions: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if not inited
 555
 556         .. note:: :meth:`collect_tags` will iterate over the messages and
 557           therefore will not allow further iterations.
 558         """
 559         if self._msgs is None:
 560             raise NotmuchError(STATUS.NOT_INITIALIZED)
 561
 562         # collect all tags (returns NULL on error)
 563         tags_p = Messages._collect_tags (self._msgs)
 564         #reset _msgs as we iterated over it and can do so only once
 565         self._msgs = None
 566
 567         if tags_p == None:
 568             raise NotmuchError(STATUS.NULL_POINTER)
 569         return Tags(tags_p, self)
 570
 571     def __iter__(self):
 572         """ Make Messages an iterator """
 573         return self
 574
 575     def next(self):
 576         if self._msgs is None:
 577             raise NotmuchError(STATUS.NOT_INITIALIZED)
 578
 579         if not nmlib.notmuch_messages_valid(self._msgs):
 580             self._msgs = None
 581             raise StopIteration
 582
 583         msg = Message(Messages._get (self._msgs), self)
 584         nmlib.notmuch_messages_move_to_next(self._msgs)
 585         return msg
 586
 587     def __len__(self):
 588         """len(:class:`Messages`) returns the number of contained messages
 589
 590         .. note:: As this iterates over the messages, we will not be able to
 591                iterate over them again (as in retrieve them)!
 592         """
 593         if self._msgs is None:
 594             raise NotmuchError(STATUS.NOT_INITIALIZED)
 595
 596         i=0
 597         while nmlib.notmuch_messages_valid(self._msgs):
 598             nmlib.notmuch_messages_move_to_next(self._msgs)
 599             i += 1
 600         self._msgs = None
 601         return i
 602
 603
 604
 605     def __del__(self):
 606         """Close and free the notmuch Messages"""
 607         if self._msgs is not None:
 608             logging.debug("Freeing the Messages now")
 609             nmlib.notmuch_messages_destroy (self._msgs)
 610
 611
 612 #------------------------------------------------------------------------------
 613 class Message(object):
 614     """Represents a single Email message
 615
 616     Technically, this wraps the underlying *notmuch_message_t* structure.
 617     """
 618
 619     """notmuch_message_get_filename (notmuch_message_t *message)"""
 620     _get_filename = nmlib.notmuch_message_get_filename
 621     _get_filename.restype = c_char_p
 622     """notmuch_message_get_message_id (notmuch_message_t *message)"""
 623     _get_message_id = nmlib.notmuch_message_get_message_id
 624     _get_message_id.restype = c_char_p
 625
 626     """notmuch_message_get_tags (notmuch_message_t *message)"""
 627     _get_tags = nmlib.notmuch_message_get_tags
 628     _get_tags.restype = c_void_p
 629
 630     _get_date = nmlib.notmuch_message_get_date
 631     _get_date.restype = c_uint64
 632
 633     _get_header = nmlib.notmuch_message_get_header
 634     _get_header.restype = c_char_p
 635
 636     def __init__(self, msg_p, parent=None):
 637         """
 638         :param msg_p: A pointer to an internal notmuch_message_t
 639             Structure.  If it is `None`, we will raise an :exc:`NotmuchError`
 640             STATUS.NULL_POINTER.
 641         :param parent: A 'parent' object is passed which this message is
 642               derived from. We save a reference to it, so we can
 643               automatically delete the parent object once all derived
 644               objects are dead.
 645         """
 646         if msg_p is None:
 647             NotmuchError(STATUS.NULL_POINTER)
 648         self._msg = msg_p
 649         #keep reference to parent, so we keep it alive
 650         self._parent = parent
 651         logging.debug("Inited Message derived from %s" %(str(parent)))
 652
 653
 654     def get_message_id(self):
 655         """Return the message ID
 656
 657         :returns: String with a message ID
 658         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 659                     is not initialized.
 660         """
 661         if self._msg is None:
 662             raise NotmuchError(STATUS.NOT_INITIALIZED)
 663         return Message._get_message_id(self._msg)
 664
 665     def get_date(self):
 666         """Returns time_t of the message date
 667
 668         For the original textual representation of the Date header from the
 669         message call notmuch_message_get_header() with a header value of
 670         "date".
 671
 672         :returns: a time_t timestamp
 673         :rtype: c_unit64
 674         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 675                     is not initialized.
 676         """
 677         if self._msg is None:
 678             raise NotmuchError(STATUS.NOT_INITIALIZED)
 679         return Message._get_date(self._msg)
 680
 681     def get_header(self, header):
 682         """Returns a message header
 683
 684         This returns any message header that is stored in the notmuch database.
 685         This is only a selected subset of headers, which is currently:
 686
 687           TODO: add stored headers
 688
 689         :param header: The name of the header to be retrieved.
 690                        It is not case-sensitive (TODO: confirm).
 691         :type header: str
 692         :returns: The header value as string
 693         :exception: :exc:`NotmuchError`
 694
 695                     * STATUS.NOT_INITIALIZED if the message
 696                       is not initialized.
 697                     * STATUS.NULL_POINTER, if no header was found
 698         """
 699         if self._msg is None:
 700             raise NotmuchError(STATUS.NOT_INITIALIZED)
 701
 702         #Returns NULL if any error occurs.
 703         header = Message._get_header (self._msg, header)
 704         if header == None:
 705             raise NotmuchError(STATUS.NULL_POINTER)
 706         return header
 707
 708     def get_filename(self):
 709         """Return the file path of the message file
 710
 711         :returns: Absolute file path & name of the message file
 712         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 713               is not initialized.
 714         """
 715         if self._msg is None:
 716             raise NotmuchError(STATUS.NOT_INITIALIZED)
 717         return Message._get_filename(self._msg)
 718
 719     def get_tags(self):
 720         """ Return the message tags
 721
 722         :returns: Message tags
 723         :rtype: :class:`Tags`
 724         :exception: :exc:`NotmuchError`
 725
 726                       * STATUS.NOT_INITIALIZED if the message
 727                         is not initialized.
 728                       * STATUS.NULL_POINTER, on error
 729         """
 730         if self._msg is None:
 731             raise NotmuchError(STATUS.NOT_INITIALIZED)
 732
 733         tags_p = Message._get_tags(self._msg)
 734         if tags_p == None:
 735             raise NotmuchError(STATUS.NULL_POINTER)
 736         return Tags(tags_p, self)
 737
 738     def add_tag(self, tag):
 739         """Add a tag to the given message
 740
 741         Adds a tag to the current message. The maximal tag length is defined in
 742         the notmuch library and is currently 200 bytes.
 743
 744         :param tag: String with a 'tag' to be added.
 745         :returns: STATUS.SUCCESS if the tag was successfully added.
 746                   Raises an exception otherwise.
 747         :exception: :exc:`NotmuchError`. They have the following meaning:
 748
 749                   STATUS.NULL_POINTER
 750                     The 'tag' argument is NULL
 751                   STATUS.TAG_TOO_LONG
 752                     The length of 'tag' is too long
 753                     (exceeds Message.NOTMUCH_TAG_MAX)
 754                   STATUS.READ_ONLY_DATABASE
 755                     Database was opened in read-only mode so message cannot be
 756                     modified.
 757                   STATUS.NOT_INITIALIZED
 758                      The message has not been initialized.
 759        """
 760         if self._msg is None:
 761             raise NotmuchError(STATUS.NOT_INITIALIZED)
 762
 763         status = nmlib.notmuch_message_add_tag (self._msg, tag)
 764
 765         if STATUS.SUCCESS == status:
 766             # return on success
 767             return status
 768
 769         raise NotmuchError(status)
 770
 771     def remove_tag(self, tag):
 772         """Removes a tag from the given message
 773
 774         If the message has no such tag, this is a non-operation and
 775         will report success anyway.
 776
 777         :param tag: String with a 'tag' to be removed.
 778         :returns: STATUS.SUCCESS if the tag was successfully removed or if
 779                   the message had no such tag.
 780                   Raises an exception otherwise.
 781         :exception: :exc:`NotmuchError`. They have the following meaning:
 782
 783                    STATUS.NULL_POINTER
 784                      The 'tag' argument is NULL
 785                    STATUS.TAG_TOO_LONG
 786                      The length of 'tag' is too long
 787                      (exceeds NOTMUCH_TAG_MAX)
 788                    STATUS.READ_ONLY_DATABASE
 789                      Database was opened in read-only mode so message cannot
 790                      be modified.
 791                    STATUS.NOT_INITIALIZED
 792                      The message has not been initialized.
 793         """
 794         if self._msg is None:
 795             raise NotmuchError(STATUS.NOT_INITIALIZED)
 796
 797         status = nmlib.notmuch_message_remove_tag(self._msg, tag)
 798
 799         if STATUS.SUCCESS == status:
 800             # return on success
 801             return status
 802
 803         raise NotmuchError(status)
 804
 805     def remove_all_tags(self):
 806         """Removes all tags from the given message.
 807
 808         See :meth:`freeze` for an example showing how to safely
 809         replace tag values.
 810
 811         :returns: STATUS.SUCCESS if the tags were successfully removed.
 812                   Raises an exception otherwise.
 813         :exception: :exc:`NotmuchError`. They have the following meaning:
 814
 815                    STATUS.READ_ONLY_DATABASE
 816                      Database was opened in read-only mode so message cannot
 817                      be modified.
 818                    STATUS.NOT_INITIALIZED
 819                      The message has not been initialized.
 820         """
 821         if self._msg is None:
 822             raise NotmuchError(STATUS.NOT_INITIALIZED)
 823
 824         status = nmlib.notmuch_message_remove_all_tags(self._msg)
 825
 826         if STATUS.SUCCESS == status:
 827             # return on success
 828             return status
 829
 830         raise NotmuchError(status)
 831
 832     def freeze(self):
 833         """Freezes the current state of 'message' within the database
 834
 835         This means that changes to the message state, (via :meth:`add_tag`,
 836         :meth:`remove_tag`, and :meth:`remove_all_tags`), will not be
 837         committed to the database until the message is :meth:`thaw`ed.
 838
 839         Multiple calls to freeze/thaw are valid and these calls will
 840         "stack". That is there must be as many calls to thaw as to freeze
 841         before a message is actually thawed.
 842
 843         The ability to do freeze/thaw allows for safe transactions to
 844         change tag values. For example, explicitly setting a message to
 845         have a given set of tags might look like this::
 846
 847           msg.freeze()
 848           msg.remove_all_tags()
 849           for tag in new_tags:
 850               msg.add_tag(tag)
 851           msg.thaw()
 852
 853         With freeze/thaw used like this, the message in the database is
 854         guaranteed to have either the full set of original tag values, or
 855         the full set of new tag values, but nothing in between.
 856
 857         Imagine the example above without freeze/thaw and the operation
 858         somehow getting interrupted. This could result in the message being
 859         left with no tags if the interruption happened after
 860         :meth:`remove_all_tags` but before :meth:`add_tag`.
 861
 862         :returns: STATUS.SUCCESS if the message was successfully frozen.
 863                   Raises an exception otherwise.
 864         :exception: :exc:`NotmuchError`. They have the following meaning:
 865
 866                    STATUS.READ_ONLY_DATABASE
 867                      Database was opened in read-only mode so message cannot
 868                      be modified.
 869                    STATUS.NOT_INITIALIZED
 870                      The message has not been initialized.
 871         """
 872         if self._msg is None:
 873             raise NotmuchError(STATUS.NOT_INITIALIZED)
 874
 875         status = nmlib.notmuch_message_freeze(self._msg)
 876
 877         if STATUS.SUCCESS == status:
 878             # return on success
 879             return status
 880
 881         raise NotmuchError(status)
 882
 883     def thaw(self):
 884         """Thaws the current 'message'
 885
 886         Thaw the current 'message', synchronizing any changes that may have
 887         occurred while 'message' was frozen into the notmuch database.
 888
 889         See :meth:`freeze` for an example of how to use this
 890         function to safely provide tag changes.
 891
 892         Multiple calls to freeze/thaw are valid and these calls with
 893         "stack". That is there must be as many calls to thaw as to freeze
 894         before a message is actually thawed.
 895
 896         :returns: STATUS.SUCCESS if the message was successfully frozen.
 897                   Raises an exception otherwise.
 898         :exception: :exc:`NotmuchError`. They have the following meaning:
 899
 900                    STATUS.UNBALANCED_FREEZE_THAW
 901                      An attempt was made to thaw an unfrozen message.
 902                      That is, there have been an unbalanced number of calls
 903                      to :meth:`freeze` and :meth:`thaw`.
 904                    STATUS.NOT_INITIALIZED
 905                      The message has not been initialized.
 906         """
 907         if self._msg is None:
 908             raise NotmuchError(STATUS.NOT_INITIALIZED)
 909
 910         status = nmlib.notmuch_message_thaw(self._msg)
 911
 912         if STATUS.SUCCESS == status:
 913             # return on success
 914             return status
 915
 916         raise NotmuchError(status)
 917
 918
 919     def __str__(self):
 920         """A message() is represented by a 1-line summary"""
 921         msg = {}
 922         msg['from'] = self.get_header('from')
 923         msg['tags'] = str(self.get_tags())
 924         msg['date'] = date.fromtimestamp(self.get_date())
 925         return "%(from)s (%(date)s) (%(tags)s)" % (msg)
 926
 927     def format_as_text(self):
 928         """Output like notmuch show (Not implemented)"""
 929         return str(self)
 930
 931     def __del__(self):
 932         """Close and free the notmuch Message"""
 933         if self._msg is not None:
 934             logging.debug("Freeing the Message now")
 935             nmlib.notmuch_message_destroy (self._msg)