Threads – Threads iterator

class Threads(threads_p, parent=None)

Represents a list of notmuch threads

This object provides an iterator over a list of notmuch threads (Technically, it provides a wrapper for the underlying notmuch_threads_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 threads, and a subsequent iteration attempt will raise a NotInitializedError. Also note, that any function that uses iteration will also exhaust the messages. So both:

for thread in threads: print thread

as well as:

list_of_threads = list(threads)

will “exhaust” the threads. If you need to re-iterate over a list of messages you will need to retrieve a new Threads object.

Things are not as bad as it seems though, you can store and reuse the single Thread objects as often as you want as long as you keep the parent Threads object around. (Recall that due to hierarchical memory allocation, all derived Threads objects will be invalid when we delete the parent Threads() object, even if it was already “exhausted”.) So this works:

db   = Database()
threads = Query(db,'').search_threads() #get a Threads() object
threadlist = []
for thread in threads:
   threadlist.append(thread)

# threads is "exhausted" now.
# However it will be kept around until all retrieved Thread() objects are
# also deleted. If you did e.g. an explicit del(threads) here, the
# following lines would fail.

# You can reiterate over *threadlist* however as often as you want.
# It is simply a list with Thread objects.

print (threadlist[0].get_thread_id())
print (threadlist[1].get_thread_id())
print (threadlist[0].get_total_messages())

Parameters:

• threads_p (ctypes.c_void_p) – A pointer to an underlying notmuch_threads_t structure. These are not publically exposed, so a user will almost never instantiate a Threads object herself. They are usually handed back as a result, e.g. in Query.search_threads(). threads_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.(?)

__len__()

Warning

__len__() was removed in version 0.22 as it exhausted the iterator and broke list(Threads()). Use len(list(msgs)) instead.