From d8921379e9ce1b4133ba54feab9ea0b3d641c94d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20v=2E=20L=C3=B6wis?= <martin@v.loewis.de>
Date: Mon, 10 Nov 2003 06:44:44 +0000
Subject: [PATCH] Patch #798297: Add IMAP THREAD command.

---
 Doc/lib/libimaplib.tex | 22 ++++++++++++++++++++++
 Lib/imaplib.py         | 11 +++++++++++
 Misc/ACKS              |  1 +
 Misc/NEWS              |  4 ++++
 4 files changed, 38 insertions(+)

diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex
index 27e493baacd..2ebd0c13c3d 100644
--- a/Doc/lib/libimaplib.tex
+++ b/Doc/lib/libimaplib.tex
@@ -355,6 +355,28 @@ msgnums = M.search(None, '(FROM "LDJ")')
   Subscribe to new mailbox.
 \end{methoddesc}
 
+\begin{methoddesc}{thread}{threading_algorithm, charset, search_criterion\optional{, ...}}
+  The \code{thread} command is a variant of \code{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 \var{search_criterion}
+  argument(s); a \var{threading_algorithm}, and the searching \var{charset}.
+  Note that unlike \code{search}, the searching \var{charset} argument is mandatory.
+  There is also a \code{uid thread} command which corresponds to \code{thread} the way
+  that \code{uid search} corresponds to \code{search}.
+  The \code{thread} command first searches the mailbox for messages that
+  match the given searching criteria using the charset argument for
+  the interpretation of strings in the searching criteria. It thren
+  returns the matching messages threaded according to the specified
+  threading algorithm.
+
+  This is an \samp{IMAP4rev1} extension command. \versionadded{2.4}
+\end{methoddesc}
+
 \begin{methoddesc}{uid}{command, arg\optional{, ...}}
   Execute command args with messages identified by UID, rather than
   message number.  Returns response appropriate to command.  At least
diff --git a/Lib/imaplib.py b/Lib/imaplib.py
index d9166e08530..80049828ed7 100644
--- a/Lib/imaplib.py
+++ b/Lib/imaplib.py
@@ -69,6 +69,7 @@ Commands = {
         'STATUS':       ('AUTH', 'SELECTED'),
         'STORE':        ('SELECTED',),
         'SUBSCRIBE':    ('AUTH', 'SELECTED'),
+        'THREAD':       ('SELECTED',),
         'UID':          ('SELECTED',),
         'UNSUBSCRIBE':  ('AUTH', 'SELECTED'),
         }
@@ -679,6 +680,16 @@ class IMAP4:
         return self._simple_command('SUBSCRIBE', mailbox)
 
 
+    def thread(self, threading_algorithm, charset, *search_criteria):
+        """IMAPrev1 extension THREAD command.
+
+        (type, [data]) = <instance>.thread(threading_alogrithm, charset, search_criteria, ...)
+        """
+        name = 'THREAD'
+        typ, dat = self._simple_command(name, threading_algorithm, charset, *search_criteria)
+        return self._untagged_response(typ, dat, name)
+
+
     def uid(self, command, *args):
         """Execute "command arg ..." with messages identified by UID,
                 rather than message number.
diff --git a/Misc/ACKS b/Misc/ACKS
index 16f3f62f22a..4ddd6a3ec87 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -137,6 +137,7 @@ John DeGood
 Vincent Delft
 Roger Dev
 Toby Dickenson
+Yves Dionne
 Daniel Dittmar
 Walter Dörwald
 Jaromir Dolecek
diff --git a/Misc/NEWS b/Misc/NEWS
index 014a099c580..ff1e426aba2 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -57,6 +57,8 @@ Core and builtins
 Extension modules
 -----------------
 
+- os.getsid was added.
+
 - The pwd module incorrectly advertised its struct type as
   struct_pwent; this has been renamed to struct_passwd.  (The old name
   is still supported for backwards compatibility.)
@@ -104,6 +106,8 @@ Extension modules
 Library
 -------
 
+- imaplib.IMAP4.thread was added.
+
 - Plugged a minor hole in tempfile.mktemp() due to the use of
   os.path.exists(), switched to using os.lstat() directly if possible.