Message
– A single message¶
-
class
Message
(msg_p, parent=None)¶ Represents a single Email message
Technically, this wraps the underlying notmuch_message_t structure. A user will usually not create these objects themselves but get them as search results.
As it implements
__cmp__()
, it is possible to compare twoMessage
s using if msg1 == msg2: ....Parameters: - msg_p – A pointer to an internal notmuch_message_t
Structure. If it is None, we will raise an
NullPointerError
. - parent – A ‘parent’ object is passed which this message is derived from. We save a reference to it, so we can automatically delete the parent object once all derived objects are dead.
-
get_message_id
()¶ Returns the message ID
Returns: String with a message ID Raises: NotInitializedError
if the message is not initialized.
-
get_thread_id
()¶ Returns the thread ID
The returned string belongs to ‘message’ will only be valid for as long as the message is valid.
This function will not return None since Notmuch ensures that every message belongs to a single thread.
Returns: String with a thread ID Raises: NotInitializedError
if the message is not initialized.
-
get_replies
()¶ Gets all direct replies to this message as
Messages
iteratorNote
This call only makes sense if ‘message’ was ultimately obtained from a
Thread
object, (such as by coming directly from the result of callingThread.get_toplevel_messages()
or by any number of subsequent calls toget_replies()
). If this message was obtained through some non-thread means, (such as by a call toQuery.search_messages()
), then this function will return an empty Messages iterator.Returns: Messages
.Raises: NotInitializedError
if the message is not initialized.
-
get_filename
()¶ Returns the file path of the message file
Returns: Absolute file path & name of the message file Raises: NotInitializedError
if the message is not initialized.
-
get_filenames
()¶ Get all filenames for the email corresponding to ‘message’
Returns a Filenames() generator with all absolute filepaths for messages recorded to have the same Message-ID. These files must not necessarily have identical content.
-
FLAG
¶ - FLAG.MATCH
- This flag is automatically set by a Query.search_threads on those messages that match the query. This allows us to distinguish matches from the rest of the messages in that thread.
-
get_flag
(flag)¶ Checks whether a specific flag is set for this message
The method
Query.search_threads()
sets Message.FLAG.MATCH for those messages that match the query. This method allows us to get the value of this flag.Parameters: flag – One of the Message.FLAG
values (currently only Message.FLAG.MATCHReturns: An unsigned int (0/1), indicating whether the flag is set. Raises: NotInitializedError
if the message is not initialized.
-
set_flag
(flag, value)¶ Sets/Unsets a specific flag for this message
Parameters: - flag – One of the
Message.FLAG
values (currently only Message.FLAG.MATCH - value – A bool indicating whether to set or unset the flag.
Raises: NotInitializedError
if the message is not initialized.- flag – One of the
-
get_date
()¶ Returns time_t of the message date
For the original textual representation of the Date header from the message call notmuch_message_get_header() with a header value of “date”.
Returns: A time_t timestamp. Return type: c_unit64 Raises: NotInitializedError
if the message is not initialized.
-
get_header
(header)¶ Get the value of the specified header.
The value will be read from the actual message file, not from the notmuch database. The header name is case insensitive.
Returns an empty string (“”) if the message does not contain a header line matching ‘header’.
Parameters: header (str) – The name of the header to be retrieved. It is not case-sensitive. Returns: The header value as string Raises: NotInitializedError
if the message is not initializedRaises: NullPointerError
if any error occured
Returns the message tags
Returns: A Tags
iterator.Raises: NotInitializedError
if the message is not initializedRaises: NullPointerError
if any error occured
Synchronize file Maildir flags to notmuch tags
Flag Action if present —- —————– ‘D’ Adds the “draft” tag to the message ‘F’ Adds the “flagged” tag to the message ‘P’ Adds the “passed” tag to the message ‘R’ Adds the “replied” tag to the message ‘S’ Removes the “unread” tag from the messageFor each flag that is not present, the opposite action (add/remove) is performed for the corresponding tags. If there are multiple filenames associated with this message, the flag is considered present if it appears in one or more filenames. (That is, the flags from the multiple filenames are combined with the logical OR operator.)
As a convenience, you can set the sync_maildir_flags parameter in
Database.add_message()
to implicitly call this.Returns: a STATUS
. In short, you want to see notmuch.STATUS.SUCCESS here. See there for details.
Synchronize notmuch tags to file Maildir flags
‘D’ if the message has the “draft” tag ‘F’ if the message has the “flagged” tag ‘P’ if the message has the “passed” tag ‘R’ if the message has the “replied” tag ‘S’ if the message does not have the “unread” tagAny existing flags unmentioned in the list above will be preserved in the renaming.
Also, if this filename is in a directory named “new”, rename it to be within the neighboring directory named “cur”.
Do note that calling this method while a message is frozen might not work yet, as the modified tags have not been committed yet to the database.
Returns: a STATUS
value. In short, you want to see notmuch.STATUS.SUCCESS here. See there for details.
-
remove_tag
(tag, sync_maildir_flags=False)¶ Removes a tag from the given message
If the message has no such tag, this is a non-operation and will report success anyway.
Parameters: - tag – String with a ‘tag’ to be removed.
- sync_maildir_flags – If notmuch configuration is set to do
this, add maildir flags corresponding to notmuch tags. See
underlying method
tags_to_maildir_flags()
. Use False if you want to add/remove many tags on a message without having to physically rename the file every time. Do note, that this will do nothing when a message is frozen, as tag changes will not be committed to the database yet.
Returns: STATUS.SUCCESS if the tag was successfully removed or if the message had no such tag. Raises an exception otherwise.
Raises: NullPointerError
if the tag argument is NULLRaises: TagTooLongError
if the length of tag exceeds Message.NOTMUCH_TAG_MAX)Raises: ReadOnlyDatabaseError
if the database was opened in read-only mode so message cannot be modifiedRaises: NotInitializedError
if message has not been initialized
-
add_tag
(tag, sync_maildir_flags=False)¶ Adds a tag to the given message
Adds a tag to the current message. The maximal tag length is defined in the notmuch library and is currently 200 bytes.
Parameters: - tag – String with a ‘tag’ to be added.
- sync_maildir_flags – If notmuch configuration is set to do
this, add maildir flags corresponding to notmuch tags. See
underlying method
tags_to_maildir_flags()
. Use False if you want to add/remove many tags on a message without having to physically rename the file every time. Do note, that this will do nothing when a message is frozen, as tag changes will not be committed to the database yet.
Returns: STATUS.SUCCESS if the tag was successfully added. Raises an exception otherwise.
Raises: NullPointerError
if the tag argument is NULLRaises: TagTooLongError
if the length of tag exceeds Message.NOTMUCH_TAG_MAX)Raises: ReadOnlyDatabaseError
if the database was opened in read-only mode so message cannot be modifiedRaises: NotInitializedError
if message has not been initialized
Removes all tags from the given message.
See
freeze()
for an example showing how to safely replace tag values.Parameters: sync_maildir_flags – If notmuch configuration is set to do this, add maildir flags corresponding to notmuch tags. See tags_to_maildir_flags()
. Use False if you want to add/remove many tags on a message without having to physically rename the file every time. Do note, that this will do nothing when a message is frozen, as tag changes will not be committed to the database yet.Returns: STATUS.SUCCESS if the tags were successfully removed. Raises an exception otherwise. Raises: ReadOnlyDatabaseError
if the database was opened in read-only mode so message cannot be modifiedRaises: NotInitializedError
if message has not been initialized
-
freeze
()¶ Freezes the current state of ‘message’ within the database
This means that changes to the message state, (via
add_tag()
,remove_tag()
, andremove_all_tags()
), will not be committed to the database until the message isthaw()
ed.Multiple calls to freeze/thaw are valid and these calls will “stack”. That is there must be as many calls to thaw as to freeze before a message is actually thawed.
The ability to do freeze/thaw allows for safe transactions to change tag values. For example, explicitly setting a message to have a given set of tags might look like this:
msg.freeze() msg.remove_all_tags(False) for tag in new_tags: msg.add_tag(tag, False) msg.thaw() msg.tags_to_maildir_flags()
With freeze/thaw used like this, the message in the database is guaranteed to have either the full set of original tag values, or the full set of new tag values, but nothing in between.
Imagine the example above without freeze/thaw and the operation somehow getting interrupted. This could result in the message being left with no tags if the interruption happened after
remove_all_tags()
but beforeadd_tag()
.Returns: STATUS.SUCCESS if the message was successfully frozen. Raises an exception otherwise. Raises: ReadOnlyDatabaseError
if the database was opened in read-only mode so message cannot be modifiedRaises: NotInitializedError
if message has not been initialized
-
thaw
()¶ Thaws the current ‘message’
Thaw the current ‘message’, synchronizing any changes that may have occurred while ‘message’ was frozen into the notmuch database.
See
freeze()
for an example of how to use this function to safely provide tag changes.Multiple calls to freeze/thaw are valid and these calls with “stack”. That is there must be as many calls to thaw as to freeze before a message is actually thawed.
Returns: STATUS.SUCCESS if the message was successfully frozen. Raises an exception otherwise. Raises: UnbalancedFreezeThawError
if an attempt was made to thaw an unfrozen message. That is, there have been an unbalanced number of calls tofreeze()
andthaw()
.Raises: NotInitializedError
if message has not been initialized
-
__str__
()¶
- msg_p – A pointer to an internal notmuch_message_t
Structure. If it is None, we will raise an