imaplib: support for more cyrus extension : expire

[aspineux]

setacl and getacl look to be already "Cyrus" specific (according the
doc),
why not to extend imaplib a little bit more ?

Here are some code I wrote and tested to support cyrus "expire" that
manage how long a message
can stay into a mailbox.
This is usefull for NEWS server !

The code is preceded by lot of sample.
I wrote the 2 generic functions getannotation and setannotation that
coul be used with any IMAP server.
And use them to access the Cyrus extensions !
I tried to use http://www.potaroo.net/ietf/all-ids/draft-daboo-imap-
annotatemore-00.txt
but used a lot TCPDUMP to compare with cyradm :-)

Any chances to see this small part of me into the official python
release ?

"""IMAP4 Client

Extend default python imaplib to include ANNOTATION as described in
http://www.potaroo.net/ietf/all-ids/draft-daboo-imap-annotatemore-00.txt

This extention is used by cyrus imap, for exemple to manage
automatique
removale of expired mail based on '/vendor/cmu/cyrus-imapd/expir'
annotation
"""

"""
Some usage

>>> i.getannotation('user/alain.spineux at asxnet.loc', '"*"', '"value.shared"')
>>> i.getannotation('user/alain.spineux at asxnet.loc', '/vendor/cmu/cyrus-imapd/expire', '"value.shared"')
('OK', ['"user/alain.spineux at asxnet.loc" "/vendor/cmu/cyrus-imapd/
expire" ("value.shared" "44")'])
>>> i.getannotation('user/alain.spineux at asxnet.loc', '/vendor/cmu/cyrus-imapd/expire', '("value.shared")')
('OK', ['"user/alain.spineux at asxnet.loc" "/vendor/cmu/cyrus-imapd/
expire" ("value.shared" "44")'])
>>> i.getannotation('user/alain.spineux at asxnet.loc', '/vendor/cmu/cyrus-imapd/expire', '("*")')
('OK', ['"user/alain.spineux at asxnet.loc" "/vendor/cmu/cyrus-imapd/
expire" ("value.shared" "44" "content-type.shared" "text/plain"
"size.shared" "2" "modifiedsince.shared" "1156264470")'])
>>> i.getannotation('user/alain.spineux at asxnet.loc', '/vendor/cmu/cyrus-imapd/expire', '("value.shared" "content-type.shared")')
('OK', ['"user/alain.spineux at asxnet.loc" "/vendor/cmu/cyrus-imapd/
expire" ("value.shared" "44" "content-type.shared" "text/plain")'])
>>> i.setannotation('user/alain.spineux at asxnet.loc', '/vendor/cmu/cyrus-imapd/expire',  '("value.shared" "44")')
('OK', [None])
>>> i.setannotation('user/alain.spineux at asxnet.loc', '/vendor/cmu/cyrus-imapd/expire',  '("value.shared" NIL)')
('OK', [None])
>>> i.getannotation('user/alain.spineux at asxnet.loc', '/vendor/cmu/cyrus-imapd/expire', '("value.shared")')
('OK', [None])

some more

>>> i=cyrusimap.CYRUSIMAP4('localhost')
>>> i.login('manager', 'password')
('OK', ['User logged in'])
>>> i.getcyrusexpire("user/alain.spineux at asxnet.loc")
('OK', 0)
>>> i.setcyrusexpire("user/alain.spineux at asxnet.loc", 88)
('OK', [None])
>>> i.getcyrusexpire("user/alain.spineux at asxnet.loc")
('OK', 88)
>>> i.setcyrusexpire("user/alain.spineux at asxnet.loc", None)
('OK', [None])
>>> i.getcyrusexpire("user/alain.spineux at asxnet.loc")
('OK', 0)


"""


import imaplib

imaplib.Commands.update(
       {
        'GETANNOTATION':     ('AUTH', 'SELECTED'),
        'SETANNOTATION':     ('AUTH', 'SELECTED'),
        })

class CYRUSIMAP4(imaplib.IMAP4):

    def getannotation(self, root, entry, attrib):
        """Get annotation

        (typ, [data]) = <instance>.getannotation(self, root, entry,
attrib)
        """
        typ, dat = self._simple_command('GETANNOTATION', root, entry,
attrib)
        return self._untagged_response(typ, dat, 'ANNOTATION')

    def setannotation(self, root, entry, value):
        """Set annotation value.

        (typ, [data]) = <instance>.setannotation(root, limits)
        """
        typ, dat = self._simple_command('SETANNOTATION', root, entry,
value)
        return self._untagged_response(typ, dat, 'ANNOTATION')

    def getcyrusexpire(self, root):
        """Get cyrus 'expire' annotation value.

        (typ, [data]) = <instance>.getcyrusexpire(root)
        """

        typ, dat=self.getannotation(root, '/vendor/cmu/cyrus-imapd/
expire', '("value.shared")')
        if typ!='OK':
            return typ, dat

        if dat[0]==None:
            return typ, 0

        # ['"user/alain.spineux at asxnet.loc" "/vendor/cmu/cyrus-imapd/
expire" ("value.shared" "44")'])
        v=int(dat[0].split(None,2)[2].strip('()').split(None,1)
[1].strip('"'))
        return typ, v

    def setcyrusexpire(self, root, value):
        """Get cyrus 'expire' annotation value.

        (typ, [data]) = <instance>.setcyrusexpire(root, value)
        """
        if value==None or value==0:
            v='NIL'
        else:
            v='"%d"' % (value,)

        return self.setannotation(root, '/vendor/cmu/cyrus-imapd/
expire', '("value.shared" %s)'%(v,))