Messages – A bunch of messages

class Messages(msgs_p, parent=None)

Represents a list of notmuch messages

This object provides an iterator over a list of notmuch messages (Technically, it provides a wrapper for the underlying notmuch_messages_t structure). Do note that the underlying library only provides a one-time iterator (it cannot reset the iterator to the start). Thus iterating over the function will “exhaust” the list of messages, and a subsequent iteration attempt will raise a NotInitializedError. If you need to re-iterate over a list of messages you will need to retrieve a new Messages object or cache your Messages in a list via:

msglist = list(msgs)

You can store and reuse the single Message objects as often as you want as long as you keep the parent Messages object around. (Due to hierarchical memory allocation, all derived Message objects will be invalid when we delete the parent Messages object, even if it was already exhausted.) So this works:

db   = Database()
msgs = Query(db,'').search_messages() #get a Messages() object
msglist = list(msgs)

# msgs is "exhausted" now and msgs.next() will raise an exception.
# However it will be kept alive until all retrieved Message()
# objects are also deleted. If you do e.g. an explicit del(msgs)
# here, the following lines would fail.

# You can reiterate over *msglist* however as often as you want.
# It is simply a list with :class:`Message`s.

print (msglist[0].get_filename())
print (msglist[1].get_filename())
print (msglist[0].get_message_id())

As Message implements both __hash__() and __cmp__(), it is possible to make sets out of Messages and use set arithmetic (this happens in python and will of course be much slower than redoing a proper query with the appropriate filters:

s1, s2 = set(msgs1), set(msgs2)
s.union(s2)
s1 -= s2
...

Be careful when using set arithmetic between message sets derived from different Databases (ie the same database reopened after messages have changed). If messages have added or removed associated files in the meantime, it is possible that the same message would be considered as a different object (as it points to a different file).

Parameters:

• msgs_p (ctypes.c_void_p) – A pointer to an underlying notmuch_messages_t structure. These are not publicly exposed, so a user will almost never instantiate a Messages object herself. They are usually handed back as a result, e.g. in Query.search_messages(). msgs_p must be valid, we will raise an NullPointerError if it is None.

• parent – The parent object (ie Query) these tags are derived from. It saves a reference to it, so we can automatically delete the db object once all derived objects are dead.

TODO:

Make the iterator work more than once and cache the tags in the Python object.(?)

collect_tags()

Return the unique Tags in the contained messages

Returns:

Tags

Exceptions:

NotInitializedError if not init’ed

Note

collect_tags() will iterate over the messages and therefore will not allow further iterations.

__len__()

Warning

__len__() was removed in version 0.6 as it exhausted the iterator and broke list(Messages()). Use the Query.count_messages() function or use len(list(msgs)).