git.notmuchmail.org Git - notmuch/blob - bindings/python/notmuch/message.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                Jesse Rosenthal <jrosenthal@jhu.edu>
  19 """
  20
  21
  22 from ctypes import c_char_p, c_void_p, c_long, c_uint, c_int
  23 from datetime import date
  24 from notmuch.globals import nmlib, STATUS, NotmuchError, Enum, _str
  25 from notmuch.tag import Tags
  26 from notmuch.filename import Filenames
  27 import sys
  28 import email
  29 import types
  30 try:
  31     import simplejson as json
  32 except ImportError:
  33     import json
  34
  35
  36 class Messages(object):
  37     """Represents a list of notmuch messages
  38
  39     This object provides an iterator over a list of notmuch messages
  40     (Technically, it provides a wrapper for the underlying
  41     *notmuch_messages_t* structure). Do note that the underlying library
  42     only provides a one-time iterator (it cannot reset the iterator to
  43     the start). Thus iterating over the function will "exhaust" the list
  44     of messages, and a subsequent iteration attempt will raise a
  45     :exc:`NotmuchError` STATUS.NOT_INITIALIZED. If you need to
  46     re-iterate over a list of messages you will need to retrieve a new
  47     :class:`Messages` object or cache your :class:`Message`\s in a list
  48     via::
  49
  50        msglist = list(msgs)
  51
  52     You can store and reuse the single :class:`Message` objects as often
  53     as you want as long as you keep the parent :class:`Messages` object
  54     around. (Due to hierarchical memory allocation, all derived
  55     :class:`Message` objects will be invalid when we delete the parent
  56     :class:`Messages` object, even if it was already exhausted.) So
  57     this works::
  58
  59       db   = Database()
  60       msgs = Query(db,'').search_messages() #get a Messages() object
  61       msglist = list(msgs)
  62
  63       # msgs is "exhausted" now and msgs.next() will raise an exception.
  64       # However it will be kept alive until all retrieved Message()
  65       # objects are also deleted. If you do e.g. an explicit del(msgs)
  66       # here, the following lines would fail.
  67
  68       # You can reiterate over *msglist* however as often as you want.
  69       # It is simply a list with :class:`Message`s.
  70
  71       print (msglist[0].get_filename())
  72       print (msglist[1].get_filename())
  73       print (msglist[0].get_message_id())
  74
  75
  76     As :class:`Message` implements both __hash__() and __cmp__(), it is
  77     possible to make sets out of :class:`Messages` and use set
  78     arithmetic (this happens in python and will of course be *much*
  79     slower than redoing a proper query with the appropriate filters::
  80
  81         s1, s2 = set(msgs1), set(msgs2)
  82         s.union(s2)
  83         s1 -= s2
  84         ...
  85
  86     Be careful when using set arithmetic between message sets derived
  87     from different Databases (ie the same database reopened after
  88     messages have changed). If messages have added or removed associated
  89     files in the meantime, it is possible that the same message would be
  90     considered as a different object (as it points to a different file).
  91     """
  92
  93     #notmuch_messages_get
  94     _get = nmlib.notmuch_messages_get
  95     _get.restype = c_void_p
  96
  97     _collect_tags = nmlib.notmuch_messages_collect_tags
  98     _collect_tags.restype = c_void_p
  99
 100     def __init__(self, msgs_p, parent=None):
 101         """
 102         :param msgs_p:  A pointer to an underlying *notmuch_messages_t*
 103              structure. These are not publically exposed, so a user
 104              will almost never instantiate a :class:`Messages` object
 105              herself. They are usually handed back as a result,
 106              e.g. in :meth:`Query.search_messages`.  *msgs_p* must be
 107              valid, we will raise an :exc:`NotmuchError`
 108              (STATUS.NULL_POINTER) if it is `None`.
 109         :type msgs_p: :class:`ctypes.c_void_p`
 110         :param parent: The parent object
 111              (ie :class:`Query`) these tags are derived from. It saves
 112              a reference to it, so we can automatically delete the db
 113              object once all derived objects are dead.
 114         :TODO: Make the iterator work more than once and cache the tags in
 115                the Python object.(?)
 116         """
 117         if msgs_p is None:
 118             raise NotmuchError(STATUS.NULL_POINTER)
 119
 120         self._msgs = msgs_p
 121         #store parent, so we keep them alive as long as self  is alive
 122         self._parent = parent
 123
 124     def collect_tags(self):
 125         """Return the unique :class:`Tags` in the contained messages
 126
 127         :returns: :class:`Tags`
 128         :exceptions: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if not inited
 129
 130         .. note:: :meth:`collect_tags` will iterate over the messages and
 131           therefore will not allow further iterations.
 132         """
 133         if self._msgs is None:
 134             raise NotmuchError(STATUS.NOT_INITIALIZED)
 135
 136         # collect all tags (returns NULL on error)
 137         tags_p = Messages._collect_tags(self._msgs)
 138         #reset _msgs as we iterated over it and can do so only once
 139         self._msgs = None
 140
 141         if tags_p == None:
 142             raise NotmuchError(STATUS.NULL_POINTER)
 143         return Tags(tags_p, self)
 144
 145     def __iter__(self):
 146         """ Make Messages an iterator """
 147         return self
 148
 149     def next(self):
 150         if self._msgs is None:
 151             raise NotmuchError(STATUS.NOT_INITIALIZED)
 152
 153         if not nmlib.notmuch_messages_valid(self._msgs):
 154             self._msgs = None
 155             raise StopIteration
 156
 157         msg = Message(Messages._get(self._msgs), self)
 158         nmlib.notmuch_messages_move_to_next(self._msgs)
 159         return msg
 160
 161     def __nonzero__(self):
 162         """
 163         :return: True if there is at least one more thread in the
 164             Iterator, False if not."""
 165         return self._msgs is not None and \
 166             nmlib.notmuch_messages_valid(self._msgs) > 0
 167
 168     def __del__(self):
 169         """Close and free the notmuch Messages"""
 170         if self._msgs is not None:
 171             nmlib.notmuch_messages_destroy(self._msgs)
 172
 173     def print_messages(self, format, indent=0, entire_thread=False):
 174         """Outputs messages as needed for 'notmuch show' to sys.stdout
 175
 176         :param format: A string of either 'text' or 'json'.
 177         :param indent: A number indicating the reply depth of these messages.
 178         :param entire_thread: A bool, indicating whether we want to output
 179                        whole threads or only the matching messages.
 180         """
 181         if format.lower() == "text":
 182             set_start = ""
 183             set_end = ""
 184             set_sep = ""
 185         elif format.lower() == "json":
 186             set_start = "["
 187             set_end = "]"
 188             set_sep = ", "
 189         else:
 190             raise TypeError("format must be either 'text' or 'json'")
 191
 192         first_set = True
 193
 194         sys.stdout.write(set_start)
 195
 196         # iterate through all toplevel messages in this thread
 197         for msg in self:
 198             # if not msg:
 199             #     break
 200             if not first_set:
 201                 sys.stdout.write(set_sep)
 202             first_set = False
 203
 204             sys.stdout.write(set_start)
 205             match = msg.is_match()
 206             next_indent = indent
 207
 208             if (match or entire_thread):
 209                 if format.lower() == "text":
 210                     sys.stdout.write(msg.format_message_as_text(indent))
 211                 else:
 212                     sys.stdout.write(msg.format_message_as_json(indent))
 213                 next_indent = indent + 1
 214
 215             # get replies and print them also out (if there are any)
 216             replies = msg.get_replies()
 217             if not replies is None:
 218                 sys.stdout.write(set_sep)
 219                 replies.print_messages(format, next_indent, entire_thread)
 220
 221             sys.stdout.write(set_end)
 222         sys.stdout.write(set_end)
 223
 224
 225 class Message(object):
 226     """Represents a single Email message
 227
 228     Technically, this wraps the underlying *notmuch_message_t*
 229     structure. A user will usually not create these objects themselves
 230     but get them as search results.
 231
 232     As it implements :meth:`__cmp__`, it is possible to compare two
 233     :class:`Message`\s using `if msg1 == msg2: ...`.
 234     """
 235
 236     """notmuch_message_get_filename (notmuch_message_t *message)"""
 237     _get_filename = nmlib.notmuch_message_get_filename
 238     _get_filename.restype = c_char_p
 239
 240     """return all filenames for a message"""
 241     _get_filenames = nmlib.notmuch_message_get_filenames
 242     _get_filenames.restype = c_void_p
 243
 244     """notmuch_message_get_flag"""
 245     _get_flag = nmlib.notmuch_message_get_flag
 246     _get_flag.restype = c_uint
 247
 248     """notmuch_message_get_message_id (notmuch_message_t *message)"""
 249     _get_message_id = nmlib.notmuch_message_get_message_id
 250     _get_message_id.restype = c_char_p
 251
 252     """notmuch_message_get_thread_id"""
 253     _get_thread_id = nmlib.notmuch_message_get_thread_id
 254     _get_thread_id.restype = c_char_p
 255
 256     """notmuch_message_get_replies"""
 257     _get_replies = nmlib.notmuch_message_get_replies
 258     _get_replies.restype = c_void_p
 259
 260     """notmuch_message_get_tags (notmuch_message_t *message)"""
 261     _get_tags = nmlib.notmuch_message_get_tags
 262     _get_tags.restype = c_void_p
 263
 264     _get_date = nmlib.notmuch_message_get_date
 265     _get_date.restype = c_long
 266
 267     _get_header = nmlib.notmuch_message_get_header
 268     _get_header.restype = c_char_p
 269
 270     """notmuch_status_t ..._maildir_flags_to_tags (notmuch_message_t *)"""
 271     _tags_to_maildir_flags = nmlib.notmuch_message_tags_to_maildir_flags
 272     _tags_to_maildir_flags.restype = c_int
 273
 274     """notmuch_status_t ..._tags_to_maildir_flags (notmuch_message_t *)"""
 275     _maildir_flags_to_tags = nmlib.notmuch_message_maildir_flags_to_tags
 276     _maildir_flags_to_tags.restype = c_int
 277
 278     #Constants: Flags that can be set/get with set_flag
 279     FLAG = Enum(['MATCH'])
 280
 281     def __init__(self, msg_p, parent=None):
 282         """
 283         :param msg_p: A pointer to an internal notmuch_message_t
 284             Structure.  If it is `None`, we will raise an :exc:`NotmuchError`
 285             STATUS.NULL_POINTER.
 286
 287         :param parent: A 'parent' object is passed which this message is
 288               derived from. We save a reference to it, so we can
 289               automatically delete the parent object once all derived
 290               objects are dead.
 291         """
 292         if msg_p is None:
 293             raise NotmuchError(STATUS.NULL_POINTER)
 294         self._msg = msg_p
 295         #keep reference to parent, so we keep it alive
 296         self._parent = parent
 297
 298     def get_message_id(self):
 299         """Returns the message ID
 300
 301         :returns: String with a message ID
 302         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 303                     is not initialized.
 304         """
 305         if self._msg is None:
 306             raise NotmuchError(STATUS.NOT_INITIALIZED)
 307         return Message._get_message_id(self._msg)
 308
 309     def get_thread_id(self):
 310         """Returns the thread ID
 311
 312         The returned string belongs to 'message' will only be valid for as
 313         long as the message is valid.
 314
 315         This function will not return `None` since Notmuch ensures that every
 316         message belongs to a single thread.
 317
 318         :returns: String with a thread ID
 319         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 320                     is not initialized.
 321         """
 322         if self._msg is None:
 323             raise NotmuchError(STATUS.NOT_INITIALIZED)
 324
 325         return Message._get_thread_id(self._msg)
 326
 327     def get_replies(self):
 328         """Gets all direct replies to this message as :class:`Messages`
 329         iterator
 330
 331         .. note:: This call only makes sense if 'message' was
 332           ultimately obtained from a :class:`Thread` object, (such as
 333           by coming directly from the result of calling
 334           :meth:`Thread.get_toplevel_messages` or by any number of
 335           subsequent calls to :meth:`get_replies`). If this message was
 336           obtained through some non-thread means, (such as by a call
 337           to :meth:`Query.search_messages`), then this function will
 338           return `None`.
 339
 340         :returns: :class:`Messages` or `None` if there are no replies to
 341             this message.
 342         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 343                     is not initialized.
 344         """
 345         if self._msg is None:
 346             raise NotmuchError(STATUS.NOT_INITIALIZED)
 347
 348         msgs_p = Message._get_replies(self._msg)
 349
 350         if msgs_p is None:
 351             return None
 352
 353         return Messages(msgs_p, self)
 354
 355     def get_date(self):
 356         """Returns time_t of the message date
 357
 358         For the original textual representation of the Date header from the
 359         message call notmuch_message_get_header() with a header value of
 360         "date".
 361
 362         :returns: A time_t timestamp.
 363         :rtype: c_unit64
 364         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 365                     is not initialized.
 366         """
 367         if self._msg is None:
 368             raise NotmuchError(STATUS.NOT_INITIALIZED)
 369         return Message._get_date(self._msg)
 370
 371     def get_header(self, header):
 372         """Returns a message header
 373
 374         This returns any message header that is stored in the notmuch database.
 375         This is only a selected subset of headers, which is currently:
 376
 377           TODO: add stored headers
 378
 379         :param header: The name of the header to be retrieved.
 380                        It is not case-sensitive (TODO: confirm).
 381         :type header: str
 382         :returns: The header value as string
 383         :exception: :exc:`NotmuchError`
 384
 385                     * STATUS.NOT_INITIALIZED if the message
 386                       is not initialized.
 387                     * STATUS.NULL_POINTER, if no header was found
 388         """
 389         if self._msg is None:
 390             raise NotmuchError(STATUS.NOT_INITIALIZED)
 391
 392         #Returns NULL if any error occurs.
 393         header = Message._get_header(self._msg, header)
 394         if header == None:
 395             raise NotmuchError(STATUS.NULL_POINTER)
 396         return header.decode('UTF-8')
 397
 398     def get_filename(self):
 399         """Returns the file path of the message file
 400
 401         :returns: Absolute file path & name of the message file
 402         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 403               is not initialized.
 404         """
 405         if self._msg is None:
 406             raise NotmuchError(STATUS.NOT_INITIALIZED)
 407         return Message._get_filename(self._msg)
 408
 409     def get_filenames(self):
 410         """Get all filenames for the email corresponding to 'message'
 411
 412         Returns a Filenames() generator with all absolute filepaths for
 413         messages recorded to have the same Message-ID. These files must
 414         not necessarily have identical content."""
 415         if self._msg is None:
 416             raise NotmuchError(STATUS.NOT_INITIALIZED)
 417
 418         files_p = Message._get_filenames(self._msg)
 419
 420         return Filenames(files_p, self).as_generator()
 421
 422     def get_flag(self, flag):
 423         """Checks whether a specific flag is set for this message
 424
 425         The method :meth:`Query.search_threads` sets
 426         *Message.FLAG.MATCH* for those messages that match the
 427         query. This method allows us to get the value of this flag.
 428
 429         :param flag: One of the :attr:`Message.FLAG` values (currently only
 430                      *Message.FLAG.MATCH*
 431         :returns: An unsigned int (0/1), indicating whether the flag is set.
 432         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 433               is not initialized.
 434         """
 435         if self._msg is None:
 436             raise NotmuchError(STATUS.NOT_INITIALIZED)
 437         return Message._get_flag(self._msg, flag)
 438
 439     def set_flag(self, flag, value):
 440         """Sets/Unsets a specific flag for this message
 441
 442         :param flag: One of the :attr:`Message.FLAG` values (currently only
 443                      *Message.FLAG.MATCH*
 444         :param value: A bool indicating whether to set or unset the flag.
 445
 446         :returns: Nothing
 447         :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
 448               is not initialized.
 449         """
 450         if self._msg is None:
 451             raise NotmuchError(STATUS.NOT_INITIALIZED)
 452         nmlib.notmuch_message_set_flag(self._msg, flag, value)
 453
 454     def get_tags(self):
 455         """Returns the message tags
 456
 457         :returns: A :class:`Tags` iterator.
 458         :exception: :exc:`NotmuchError`
 459
 460                       * STATUS.NOT_INITIALIZED if the message
 461                         is not initialized.
 462                       * STATUS.NULL_POINTER, on error
 463         """
 464         if self._msg is None:
 465             raise NotmuchError(STATUS.NOT_INITIALIZED)
 466
 467         tags_p = Message._get_tags(self._msg)
 468         if tags_p == None:
 469             raise NotmuchError(STATUS.NULL_POINTER)
 470         return Tags(tags_p, self)
 471
 472     def add_tag(self, tag, sync_maildir_flags=False):
 473         """Adds a tag to the given message
 474
 475         Adds a tag to the current message. The maximal tag length is defined in
 476         the notmuch library and is currently 200 bytes.
 477
 478         :param tag: String with a 'tag' to be added.
 479
 480         :param sync_maildir_flags: If notmuch configuration is set to do
 481             this, add maildir flags corresponding to notmuch tags. See
 482             underlying method :meth:`tags_to_maildir_flags`. Use False
 483             if you want to add/remove many tags on a message without
 484             having to physically rename the file every time. Do note,
 485             that this will do nothing when a message is frozen, as tag
 486             changes will not be committed to the database yet.
 487
 488         :returns: STATUS.SUCCESS if the tag was successfully added.
 489                   Raises an exception otherwise.
 490         :exception: :exc:`NotmuchError`. They have the following meaning:
 491
 492                   STATUS.NULL_POINTER
 493                     The 'tag' argument is NULL
 494                   STATUS.TAG_TOO_LONG
 495                     The length of 'tag' is too long
 496                     (exceeds Message.NOTMUCH_TAG_MAX)
 497                   STATUS.READ_ONLY_DATABASE
 498                     Database was opened in read-only mode so message cannot be
 499                     modified.
 500                   STATUS.NOT_INITIALIZED
 501                      The message has not been initialized.
 502        """
 503         if self._msg is None:
 504             raise NotmuchError(STATUS.NOT_INITIALIZED)
 505
 506         status = nmlib.notmuch_message_add_tag(self._msg, _str(tag))
 507
 508         # bail out on failure
 509         if status != STATUS.SUCCESS:
 510             raise NotmuchError(status)
 511
 512         if sync_maildir_flags:
 513             self.tags_to_maildir_flags()
 514         return STATUS.SUCCESS
 515
 516     def remove_tag(self, tag, sync_maildir_flags=False):
 517         """Removes a tag from the given message
 518
 519         If the message has no such tag, this is a non-operation and
 520         will report success anyway.
 521
 522         :param tag: String with a 'tag' to be removed.
 523         :param sync_maildir_flags: If notmuch configuration is set to do
 524             this, add maildir flags corresponding to notmuch tags. See
 525             underlying method :meth:`tags_to_maildir_flags`. Use False
 526             if you want to add/remove many tags on a message without
 527             having to physically rename the file every time. Do note,
 528             that this will do nothing when a message is frozen, as tag
 529             changes will not be committed to the database yet.
 530
 531         :returns: STATUS.SUCCESS if the tag was successfully removed or if
 532                   the message had no such tag.
 533                   Raises an exception otherwise.
 534         :exception: :exc:`NotmuchError`. They have the following meaning:
 535
 536                    STATUS.NULL_POINTER
 537                      The 'tag' argument is NULL
 538                    STATUS.TAG_TOO_LONG
 539                      The length of 'tag' is too long
 540                      (exceeds NOTMUCH_TAG_MAX)
 541                    STATUS.READ_ONLY_DATABASE
 542                      Database was opened in read-only mode so message cannot
 543                      be modified.
 544                    STATUS.NOT_INITIALIZED
 545                      The message has not been initialized.
 546         """
 547         if self._msg is None:
 548             raise NotmuchError(STATUS.NOT_INITIALIZED)
 549
 550         status = nmlib.notmuch_message_remove_tag(self._msg, _str(tag))
 551         # bail out on error
 552         if status != STATUS.SUCCESS:
 553             raise NotmuchError(status)
 554
 555         if sync_maildir_flags:
 556             self.tags_to_maildir_flags()
 557         return STATUS.SUCCESS
 558
 559     def remove_all_tags(self, sync_maildir_flags=False):
 560         """Removes all tags from the given message.
 561
 562         See :meth:`freeze` for an example showing how to safely
 563         replace tag values.
 564
 565
 566         :param sync_maildir_flags: If notmuch configuration is set to do
 567             this, add maildir flags corresponding to notmuch tags. See
 568             :meth:`tags_to_maildir_flags`. Use False if you want to
 569             add/remove many tags on a message without having to
 570             physically rename the file every time. Do note, that this
 571             will do nothing when a message is frozen, as tag changes
 572             will not be committed to the database yet.
 573
 574         :returns: STATUS.SUCCESS if the tags were successfully removed.
 575                   Raises an exception otherwise.
 576         :exception: :exc:`NotmuchError`. They have the following meaning:
 577
 578                    STATUS.READ_ONLY_DATABASE
 579                      Database was opened in read-only mode so message cannot
 580                      be modified.
 581                    STATUS.NOT_INITIALIZED
 582                      The message has not been initialized.
 583         """
 584         if self._msg is None:
 585             raise NotmuchError(STATUS.NOT_INITIALIZED)
 586
 587         status = nmlib.notmuch_message_remove_all_tags(self._msg)
 588
 589         # bail out on error
 590         if status != STATUS.SUCCESS:
 591             raise NotmuchError(status)
 592
 593         if sync_maildir_flags:
 594             self.tags_to_maildir_flags()
 595         return STATUS.SUCCESS
 596
 597     def freeze(self):
 598         """Freezes the current state of 'message' within the database
 599
 600         This means that changes to the message state, (via :meth:`add_tag`,
 601         :meth:`remove_tag`, and :meth:`remove_all_tags`), will not be
 602         committed to the database until the message is :meth:`thaw`ed.
 603
 604         Multiple calls to freeze/thaw are valid and these calls will
 605         "stack". That is there must be as many calls to thaw as to freeze
 606         before a message is actually thawed.
 607
 608         The ability to do freeze/thaw allows for safe transactions to
 609         change tag values. For example, explicitly setting a message to
 610         have a given set of tags might look like this::
 611
 612           msg.freeze()
 613           msg.remove_all_tags(False)
 614           for tag in new_tags:
 615               msg.add_tag(tag, False)
 616           msg.thaw()
 617           msg.tags_to_maildir_flags()
 618
 619         With freeze/thaw used like this, the message in the database is
 620         guaranteed to have either the full set of original tag values, or
 621         the full set of new tag values, but nothing in between.
 622
 623         Imagine the example above without freeze/thaw and the operation
 624         somehow getting interrupted. This could result in the message being
 625         left with no tags if the interruption happened after
 626         :meth:`remove_all_tags` but before :meth:`add_tag`.
 627
 628         :returns: STATUS.SUCCESS if the message was successfully frozen.
 629                   Raises an exception otherwise.
 630         :exception: :exc:`NotmuchError`. They have the following meaning:
 631
 632                    STATUS.READ_ONLY_DATABASE
 633                      Database was opened in read-only mode so message cannot
 634                      be modified.
 635                    STATUS.NOT_INITIALIZED
 636                      The message has not been initialized.
 637         """
 638         if self._msg is None:
 639             raise NotmuchError(STATUS.NOT_INITIALIZED)
 640
 641         status = nmlib.notmuch_message_freeze(self._msg)
 642
 643         if STATUS.SUCCESS == status:
 644             # return on success
 645             return status
 646
 647         raise NotmuchError(status)
 648
 649     def thaw(self):
 650         """Thaws the current 'message'
 651
 652         Thaw the current 'message', synchronizing any changes that may have
 653         occurred while 'message' was frozen into the notmuch database.
 654
 655         See :meth:`freeze` for an example of how to use this
 656         function to safely provide tag changes.
 657
 658         Multiple calls to freeze/thaw are valid and these calls with
 659         "stack". That is there must be as many calls to thaw as to freeze
 660         before a message is actually thawed.
 661
 662         :returns: STATUS.SUCCESS if the message was successfully frozen.
 663                   Raises an exception otherwise.
 664         :exception: :exc:`NotmuchError`. They have the following meaning:
 665
 666                    STATUS.UNBALANCED_FREEZE_THAW
 667                      An attempt was made to thaw an unfrozen message.
 668                      That is, there have been an unbalanced number of calls
 669                      to :meth:`freeze` and :meth:`thaw`.
 670                    STATUS.NOT_INITIALIZED
 671                      The message has not been initialized.
 672         """
 673         if self._msg is None:
 674             raise NotmuchError(STATUS.NOT_INITIALIZED)
 675
 676         status = nmlib.notmuch_message_thaw(self._msg)
 677
 678         if STATUS.SUCCESS == status:
 679             # return on success
 680             return status
 681
 682         raise NotmuchError(status)
 683
 684     def is_match(self):
 685         """(Not implemented)"""
 686         return self.get_flag(Message.FLAG.MATCH)
 687
 688     def tags_to_maildir_flags(self):
 689         """Synchronize notmuch tags to file Maildir flags
 690
 691               'D' if the message has the "draft" tag
 692               'F' if the message has the "flagged" tag
 693               'P' if the message has the "passed" tag
 694               'R' if the message has the "replied" tag
 695               'S' if the message does not have the "unread" tag
 696
 697         Any existing flags unmentioned in the list above will be
 698         preserved in the renaming.
 699
 700         Also, if this filename is in a directory named "new", rename it
 701         to be within the neighboring directory named "cur".
 702
 703         Do note that calling this method while a message is frozen might
 704         not work yet, as the modified tags have not been committed yet
 705         to the database.
 706
 707         :returns: a :class:`STATUS`. In short, you want to see
 708             notmuch.STATUS.SUCCESS here. See there for details."""
 709         if self._msg is None:
 710             raise NotmuchError(STATUS.NOT_INITIALIZED)
 711         status = Message._tags_to_maildir_flags(self._msg)
 712
 713     def maildir_flags_to_tags(self):
 714         """Synchronize file Maildir flags to notmuch tags
 715
 716             Flag    Action if present
 717             ----    -----------------
 718             'D'     Adds the "draft" tag to the message
 719             'F'     Adds the "flagged" tag to the message
 720             'P'     Adds the "passed" tag to the message
 721             'R'     Adds the "replied" tag to the message
 722             'S'     Removes the "unread" tag from the message
 723
 724         For each flag that is not present, the opposite action
 725         (add/remove) is performed for the corresponding tags.  If there
 726         are multiple filenames associated with this message, the flag is
 727         considered present if it appears in one or more filenames. (That
 728         is, the flags from the multiple filenames are combined with the
 729         logical OR operator.)
 730
 731         As a convenience, you can set the sync_maildir_flags parameter in
 732         :meth:`Database.add_message` to implicitly call this.
 733
 734         :returns: a :class:`STATUS`. In short, you want to see
 735             notmuch.STATUS.SUCCESS here. See there for details."""
 736         if self._msg is None:
 737             raise NotmuchError(STATUS.NOT_INITIALIZED)
 738         status = Message._tags_to_maildir_flags(self._msg)
 739
 740     def __repr__(self):
 741         """Represent a Message() object by str()"""
 742         return self.__str__()
 743
 744     def __str__(self):
 745         """A message() is represented by a 1-line summary"""
 746         msg = {}
 747         msg['from'] = self.get_header('from')
 748         msg['tags'] = self.get_tags()
 749         msg['date'] = date.fromtimestamp(self.get_date())
 750         return "%(from)s (%(date)s) (%(tags)s)" % (msg)
 751
 752     def get_message_parts(self):
 753         """Output like notmuch show"""
 754         fp = open(self.get_filename())
 755         email_msg = email.message_from_file(fp)
 756         fp.close()
 757
 758         out = []
 759         for msg in email_msg.walk():
 760             if not msg.is_multipart():
 761                 out.append(msg)
 762         return out
 763
 764     def get_part(self, num):
 765         """Returns the nth message body part"""
 766         parts = self.get_message_parts()
 767         if (num <= 0 or num > len(parts)):
 768             return ""
 769         else:
 770             out_part = parts[(num - 1)]
 771             return out_part.get_payload(decode=True)
 772
 773     def format_message_internal(self):
 774         """Create an internal representation of the message parts,
 775         which can easily be output to json, text, or another output
 776         format. The argument match tells whether this matched a
 777         query."""
 778         output = {}
 779         output["id"] = self.get_message_id()
 780         output["match"] = self.is_match()
 781         output["filename"] = self.get_filename()
 782         output["tags"] = list(self.get_tags())
 783
 784         headers = {}
 785         for h in ["Subject", "From", "To", "Cc", "Bcc", "Date"]:
 786             headers[h] = self.get_header(h)
 787         output["headers"] = headers
 788
 789         body = []
 790         parts = self.get_message_parts()
 791         for i in xrange(len(parts)):
 792             msg = parts[i]
 793             part_dict = {}
 794             part_dict["id"] = i + 1
 795             # We'll be using this is a lot, so let's just get it once.
 796             cont_type = msg.get_content_type()
 797             part_dict["content-type"] = cont_type
 798             # NOTE:
 799             # Now we emulate the current behaviour, where it ignores
 800             # the html if there's a text representation.
 801             #
 802             # This is being worked on, but it will be easier to fix
 803             # here in the future than to end up with another
 804             # incompatible solution.
 805             disposition = msg["Content-Disposition"]
 806             if disposition and disposition.lower().startswith("attachment"):
 807                 part_dict["filename"] = msg.get_filename()
 808             else:
 809                 if cont_type.lower() == "text/plain":
 810                     part_dict["content"] = msg.get_payload()
 811                 elif (cont_type.lower() == "text/html" and
 812                       i == 0):
 813                     part_dict["content"] = msg.get_payload()
 814             body.append(part_dict)
 815
 816         output["body"] = body
 817
 818         return output
 819
 820     def format_message_as_json(self, indent=0):
 821         """Outputs the message as json. This is essentially the same
 822         as python's dict format, but we run it through, just so we
 823         don't have to worry about the details."""
 824         return json.dumps(self.format_message_internal())
 825
 826     def format_message_as_text(self, indent=0):
 827         """Outputs it in the old-fashioned notmuch text form. Will be
 828         easy to change to a new format when the format changes."""
 829
 830         format = self.format_message_internal()
 831         output = "\fmessage{ id:%s depth:%d match:%d filename:%s" \
 832                  % (format['id'], indent, format['match'], format['filename'])
 833         output += "\n\fheader{"
 834
 835         #Todo: this date is supposed to be prettified, as in the index.
 836         output += "\n%s (%s) (" % (format["headers"]["From"],
 837                                    format["headers"]["Date"])
 838         output += ", ".join(format["tags"])
 839         output += ")"
 840
 841         output += "\nSubject: %s" % format["headers"]["Subject"]
 842         output += "\nFrom: %s" % format["headers"]["From"]
 843         output += "\nTo: %s" % format["headers"]["To"]
 844         if format["headers"]["Cc"]:
 845             output += "\nCc: %s" % format["headers"]["Cc"]
 846         if format["headers"]["Bcc"]:
 847             output += "\nBcc: %s" % format["headers"]["Bcc"]
 848         output += "\nDate: %s" % format["headers"]["Date"]
 849         output += "\n\fheader}"
 850
 851         output += "\n\fbody{"
 852
 853         parts = format["body"]
 854         parts.sort(key=lambda x: x['id'])
 855         for p in parts:
 856             if not "filename" in p:
 857                 output += "\n\fpart{ "
 858                 output += "ID: %d, Content-type: %s\n" % (p["id"],
 859                                                           p["content-type"])
 860                 if "content" in p:
 861                     output += "\n%s\n" % p["content"]
 862                 else:
 863                     output += "Non-text part: %s\n" % p["content-type"]
 864                     output += "\n\fpart}"
 865             else:
 866                 output += "\n\fattachment{ "
 867                 output += "ID: %d, Content-type:%s\n" % (p["id"],
 868                                                          p["content-type"])
 869                 output += "Attachment: %s\n" % p["filename"]
 870                 output += "\n\fattachment}\n"
 871
 872         output += "\n\fbody}\n"
 873         output += "\n\fmessage}"
 874
 875         return output
 876
 877     def __hash__(self):
 878         """Implement hash(), so we can use Message() sets"""
 879         file = self.get_filename()
 880         if file is None:
 881             return None
 882         return hash(file)
 883
 884     def __cmp__(self, other):
 885         """Implement cmp(), so we can compare Message()s
 886
 887         2 messages are considered equal if they point to the same
 888         Message-Id and if they point to the same file names. If 2
 889         Messages derive from different queries where some files have
 890         been added or removed, the same messages would not be considered
 891         equal (as they do not point to the same set of files
 892         any more)."""
 893         res = cmp(self.get_message_id(), other.get_message_id())
 894         if res:
 895             res = cmp(list(self.get_filenames()), list(other.get_filenames()))
 896         return res
 897
 898     def __del__(self):
 899         """Close and free the notmuch Message"""
 900         if self._msg is not None:
 901             nmlib.notmuch_message_destroy(self._msg)