From d80ef02ec0e2445d34824bf908f93024a7079809 Mon Sep 17 00:00:00 2001
From: Piers Lauder <piers@cs.su.oz.au>
Date: Wed, 1 Jun 2005 23:50:52 +0000
Subject: [PATCH] added GET/SETANNOTATION methods

---
 Doc/lib/libimaplib.tex | 10 ++++++++++
 Lib/imaplib.py         | 45 +++++++++++++++++++++++++++++++++---------
 2 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex
index 3448ba6925d..2c4555dbae7 100644
--- a/Doc/lib/libimaplib.tex
+++ b/Doc/lib/libimaplib.tex
@@ -222,6 +222,11 @@ data = authobject(response)
   The method is non-standard, but is supported by the \samp{Cyrus} server.
 \end{methoddesc}
 
+\begin{methoddesc}{getannotation}{mailbox, entry, attribute}
+  Retrieve the specified \samp{ANNOTATION}s for \var{mailbox}.
+  The method is non-standard, but is supported by the \samp{Cyrus} server.
+\end{methoddesc}
+
 \begin{methoddesc}{getquota}{root}
   Get the \samp{quota} \var{root}'s resource usage and limits.
   This method is part of the IMAP4 QUOTA extension defined in rfc2087.
@@ -357,6 +362,11 @@ msgnums = M.search(None, '(FROM "LDJ")')
   The method is non-standard, but is supported by the \samp{Cyrus} server.
 \end{methoddesc}
 
+\begin{methoddesc}{setannotation}{mailbox, entry, attribute\optional{, ...}}
+  Set \samp{ANNOTATION}s for \var{mailbox}.
+  The method is non-standard, but is supported by the \samp{Cyrus} server.
+\end{methoddesc}
+
 \begin{methoddesc}{setquota}{root, limits}
   Set the \samp{quota} \var{root}'s resource \var{limits}.
   This method is part of the IMAP4 QUOTA extension defined in rfc2087.
diff --git a/Lib/imaplib.py b/Lib/imaplib.py
index 6b0576fe317..3914c393e5f 100644
--- a/Lib/imaplib.py
+++ b/Lib/imaplib.py
@@ -18,8 +18,9 @@ Public functions:       Internaldate2tuple
 # IMAP4_SSL contributed by Tino Lange <Tino.Lange@isg.de> March 2002.
 # GET/SETQUOTA contributed by Andreas Zeidler <az@kreativkombinat.de> June 2002.
 # PROXYAUTH contributed by Rick Holbert <holbert.13@osu.edu> November 2002.
+# GET/SETANNOTATION contributed by Tomas Lindroos <skitta@abo.fi> June 2005.
 
-__version__ = "2.55"
+__version__ = "2.56"
 
 import binascii, os, random, re, socket, sys, time
 
@@ -51,6 +52,7 @@ Commands = {
         'EXPUNGE':      ('SELECTED',),
         'FETCH':        ('SELECTED',),
         'GETACL':       ('AUTH', 'SELECTED'),
+        'GETANNOTATION':('AUTH', 'SELECTED'),
         'GETQUOTA':     ('AUTH', 'SELECTED'),
         'GETQUOTAROOT': ('AUTH', 'SELECTED'),
         'MYRIGHTS':     ('AUTH', 'SELECTED'),
@@ -66,6 +68,7 @@ Commands = {
         'SEARCH':       ('SELECTED',),
         'SELECT':       ('AUTH', 'SELECTED'),
         'SETACL':       ('AUTH', 'SELECTED'),
+        'SETANNOTATION':('AUTH', 'SELECTED'),
         'SETQUOTA':     ('AUTH', 'SELECTED'),
         'SORT':         ('SELECTED',),
         'STATUS':       ('AUTH', 'SELECTED'),
@@ -133,10 +136,10 @@ class IMAP4:
             the command re-tried.
     "readonly" exceptions imply the command should be re-tried.
 
-    Note: to use this module, you must read the RFCs pertaining
-    to the IMAP4 protocol, as the semantics of the arguments to
-    each IMAP4 command are left to the invoker, not to mention
-    the results.
+    Note: to use this module, you must read the RFCs pertaining to the
+    IMAP4 protocol, as the semantics of the arguments to each IMAP4
+    command are left to the invoker, not to mention the results. Also,
+    most IMAP servers implement a sub-set of the commands available here.
     """
 
     class error(Exception): pass    # Logical errors - debug required
@@ -186,11 +189,10 @@ class IMAP4:
         else:
             raise self.error(self.welcome)
 
-        cap = 'CAPABILITY'
-        self._simple_command(cap)
-        if not cap in self.untagged_responses:
+        typ, dat = self.capability()
+        if dat == [None]:
             raise self.error('no CAPABILITY response from server')
-        self.capabilities = tuple(self.untagged_responses[cap][-1].upper().split())
+        self.capabilities = tuple(dat[-1].upper().split())
 
         if __debug__:
             if self.debug >= 3:
@@ -345,6 +347,15 @@ class IMAP4:
         return typ, dat
 
 
+    def capability(self):
+        """(typ, [data]) = <instance>.capability()
+        Fetch capabilities list from server."""
+
+        name = 'CAPABILITY'
+        typ, dat = self._simple_command(name)
+        return self._untagged_response(typ, dat, name)
+
+
     def check(self):
         """Checkpoint mailbox on server.
 
@@ -436,6 +447,14 @@ class IMAP4:
         return self._untagged_response(typ, dat, 'ACL')
 
 
+    def getannotation(self, mailbox, entry, attribute):
+        """(typ, [data]) = <instance>.getannotation(mailbox, entry, attribute)
+        Retrieve ANNOTATIONs."""
+
+        typ, dat = self._simple_command('GETANNOTATION', mailbox, entry, attribute)
+        return self._untagged_response(typ, dat, 'ANNOTATION')
+
+
     def getquota(self, root):
         """Get the quota root's resource usage and limits.
 
@@ -643,6 +662,14 @@ class IMAP4:
         return self._simple_command('SETACL', mailbox, who, what)
 
 
+    def setannotation(self, *args):
+        """(typ, [data]) = <instance>.setannotation(mailbox[, entry, attribute]+)
+        Set ANNOTATIONs."""
+
+        typ, dat = self._simple_command('SETANNOTATION', *args)
+        return self._untagged_response(typ, dat, 'ANNOTATION')
+
+
     def setquota(self, root, limits):
         """Set the quota root's resource limits.