What threading algorithm(s) does Python's IMAP library support?

Question

The documentation for IMAP4.thread() in the imaplib library says

The thread command is a variant of search with threading semantics for the results. Returned data contains a space separated list of thread members.

Thread members consist of zero or more messages numbers, delimited by spaces, indicating successive parent and child.

Thread has two arguments before the search_criterion argument(s); a threading_algorithm, and the searching charset.

It's not clear to me what to use for the threading_algorithm argument. The documentation doesn't indicate a default value, and the source code for the IMAP4.thread() function

def thread(self, threading_algorithm, charset, *search_criteria):
        """IMAPrev1 extension THREAD command.

        (type, [data]) = <instance>.thread(threading_algorithm, charset, search_criteria, ...)
        """

        name = 'THREAD'
        typ, dat = self._simple_command(name, threading_algorithm, charset, *search_criteria)
        return self._untagged_response(typ, dat, name)

doesn't give me any ideas either, even after digging into the _simple_command helper function.

What should I use for this argument? Is there documentation elsewhere for this?

Stafani

Answer 1

This depends on the server; the CAPABILITIES response should tell you what threading algorithms the server supports, under the THREAD= keys.

For example:

* OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE AUTH=PLAIN ACL ACL2=UNION ID] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc.  See COPYING for distribution information.

This server supports the ORDEREDSUBJECT and REFERENCES algorithms.

The description of the baseline algorithms is indicated in the IMAP SORT and THREAD RFC.

imaplib is a very low level library, you will need to parse the responses yourself.

Furtive

Likely, you wish to use REFERENCES if the server supports it. – Furtive

You can see the list of capabilities in the return value of imaplib.IMAP4_SSL().login(username, password) . Gmail doesn't seem to return this information. – Monteith

Some servers will return capabilities unprompted, some you need to ask for it. – Furtive

How do I ask for capabilities? – Monteith

It seems not to be documented, but the IMAP4 classes support a capability() command: github.com/python/cpython/blob/3.12/Lib/imaplib.py#L449 – Furtive