Changeset 249:456de0713e01

Timestamp:

05/06/11 17:24:20 (12 months ago)

Author:

Menno Smits <menno@…>

Branch:

default

Parents:

248:bbef196a11da (diff), 234:1be67b3e0445 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Synced sphinx branch with current trunk

Files:

• imapclient/imapclient.py (modified) (37 diffs)
• imapclient/imapclient.py (modified) (10 diffs)

imapclient/imapclient.py

@@ -56 +56 @@
 class IMAPClient(object):
     """
-    A Pythonic, easy-to-use IMAP client class.
-
-    Unlike imaplib, arguments and returns values are Pythonic and readily
-    usable. Exceptions are raised when problems occur (no error checking of
-    return values is required).
-
-    Message unique identifiers (UID) can be used with any call. The use_uid
-    argument to the constructor and the use_uid attribute control whether UIDs
-    are used.
-
-    Any method that accepts message id's takes either a sequence containing
-    message IDs (eg. [1,2,3]) or a single message ID as an integer.
-
-    Any method that accepts message flags takes either a sequence containing
-    message flags (eg. [DELETED, 'foo', 'Bar']) or a single message flag (eg.
-    'Foo'). See the constants at the top of this file for commonly used flags.
-
-    Any method that takes a folder name will accept a standard string or a
-    unicode string. Unicode strings will be transparently encoded using
-    modified UTF-7 as specified by RFC-2060. Such folder names will be returned
-    as unicode strings by methods that return folder names.
-
-    Transparent folder name encoding can be enabled or disabled with the
-    folder_encode attribute. It defaults to True.
-
-    The IMAP related exceptions that will be raised by this class are:
-        IMAPClient.Error
-        IMAPClient.AbortError
-        IMAPClient.ReadOnlyError
-    These are aliases for the imaplib.IMAP4 exceptions of the same name. Socket
-    errors may also be raised in the case of network errors.
+    A connection to the IMAP server specified by *host* is made when
+    the class is instantiated.
+
+    *port* defaults to 143, or 993 if *ssl* is ``True``.
+
+    If *use_uid* is ``True`` unique message UIDs be used for all calls
+    that accept message ids (defaults to ``True``).
+
+    If *ssl* is ``True`` an SSL connection will be made (defaults to
+    ``False``).
     """
 
@@ -97 +76 @@
 
     def __init__(self, host, port=None, use_uid=True, ssl=False):
-        """Initialise object instance and connect to the remote IMAP server.
-
-        @param host: The IMAP server address/hostname to connect to.
-        @param port: The port number to use (default is 143, 993 for SSL).
-        @param use_uid: Should message UIDs be used (default is True).
-        @param ssl: Make an SSL connection (default is False)
-        """
         if port is None:
             port = ssl and 993 or 143
@@ -124 +96 @@
 
     def login(self, username, password):
-        """Perform a simple login
+        """Login using *username* and *password*, returning the
+        server response.
         """
         typ, data = self._imap.login(username, password)
@@ -152 +125 @@
 
     def logout(self):
-        """Perform a logout
+        """Logout, returning the server response.
         """
         typ, data = self._imap.logout()
@@ -160 +133 @@
 
     def capabilities(self):
-        """Returns the server capability list
+        """Returns the server capability list.
         """
         return self._imap.capabilities
@@ -166 +139 @@
 
     def has_capability(self, capability):
-        """Checks if the server has the given capability.
-
-        @param capability: capability to test (eg 'SORT')
+        """Return ``True`` if the IMAP server has the given *capability*.
         """
         # FIXME: this will not detect capabilities that are backwards
@@ -181 +152 @@
 
     def namespace(self):
-        """Return the namespace for the account as a (personal, other, shared) tuple.
+        """Return the namespace for the account as a (personal, other,
+        shared) tuple.
 
         Each element may be None if no namespace of that type exists,
@@ -187 +159 @@
 
         For convenience the tuple elements may be accessed
-        positionally or attributes named "personal", "other" and
-        "shared".
+        positionally or using attributes named *personal*, *other* and
+        *shared*.
 
         See RFC 2342 for more details.
@@ -197 +169 @@
 
     def get_folder_delimiter(self):
-        """Determine the folder separator used by the IMAP server.
-
-        WARNING: The implementation just picks the first folder
-        separator from the first namespace returned. This is not
-        particularly sensible. Use namespace instead().
-
-        @return: The folder separator.
-        @rtype: string
+        """Return the folder separator used by the IMAP server.
+
+        .. warning::
+
+            The implementation just picks the first folder separator
+            from the first namespace returned. This is not
+            particularly sensible. Use namespace instead().
         """
         warnings.warn(DeprecationWarning('get_folder_delimiter is going away. Use namespace() instead.'))
@@ -213 +184 @@
 
     def list_folders(self, directory="", pattern="*"):
-        """Get a listing of folders on the server.
-
-        The default behaviour (no args) will list all folders for the logged in
-        user.
-
-        @param directory: The base directory to look for folders from.
-        @param pattern: A pattern to match against folder names. Only folder
-            names matching this pattern will be returned. Wildcards accepted.
-        @return: A list of (flags, delim, folder_name). Each folder name will
-            be either a string or a unicode string (if the folder on the
-            server required decoding). If the folder_encode attribute is
-            False, no decoding will be performed and only ordinary strings
-            will be returned.
+        """Get a listing of folders on the server as a list of
+        ``(flags, delimiter, name)`` tuples.
+
+        Calling list_folders with no arguments will list all
+        folders.
+
+        Specifying *directory* will limit returned folders to that
+        base directory. Specifying *pattern* will limit returned
+        folders to those with matching names. The wildcards are
+        supported in *pattern*. ``*`` matches zero or more of any
+        character and ``%`` matches 0 or more characters except the
+        folder delimiter.
+
+        Folder names are always returned as unicode strings except if
+        folder_decode is not set.
         """
         return self._do_list('LIST', directory, pattern)
 
     def xlist_folders(self, directory="", pattern="*"):
-        """A gmail-specific IMAP extension.
-        
-        This method returns special flags for each folder and a localized name
-        for certain folders (eg, the name of the 'inbox' may be localized as the
-        flags can be used to determine the actual inbox, even if the name has
-        been localized.  It is the responsibility of the caller to either check
-        for 'XLIST' in the server capabilites, or to handle the error if the
-        server doesn't support this externsion.
-
-        @param directory: The base directory to look for folders from.
-        @param pattern: A pattern to match against folder names. Only folder
-            names matching this pattern will be returned. Wildcards accepted.
-        @return: A list of (flags, delim, folder_name). As per the return of
-            list_folders().
+        """Execute the XLIST command, returning ``(flags, delimiter,
+        name)`` tuples.
+
+        This method returns special flags for each folder and a
+        localized name for certain folders (e.g. the name of the
+        inbox may be localized and the flags can be used to
+        determine the actual inbox, even if the name has been
+        localized.
+
+        A ``XLIST`` response could look something like::
+
+            [([u'\\HasNoChildren', u'\\Inbox'], '/', u'Inbox'),
+             ([u'\\Noselect', u'\\HasChildren'], '/', u'[Gmail]'),
+             ([u'\\HasNoChildren', u'\\AllMail'], '/', u'[Gmail]/All Mail'),
+             ([u'\\HasNoChildren', u'\\Drafts'], '/', u'[Gmail]/Drafts'),
+             ([u'\\HasNoChildren', u'\\Important'], '/', u'[Gmail]/Important'),
+             ([u'\\HasNoChildren', u'\\Sent'], '/', u'[Gmail]/Sent Mail'),
+             ([u'\\HasNoChildren', u'\\Spam'], '/', u'[Gmail]/Spam'),
+             ([u'\\HasNoChildren', u'\\Starred'], '/', u'[Gmail]/Starred'),
+             ([u'\\HasNoChildren', u'\\Trash'], '/', u'[Gmail]/Trash')]
+
+        This is a Gmail-specific IMAP extension. It is the
+        responsibility of the caller to either check for ``XLIST`` in
+        the server capabilites, or to handle the error if the server
+        doesn't support this externsion.
+
+        The *directory* and *pattern* arguments are as per
+        list_folders().
         """
         return self._do_list('XLIST', directory, pattern)
 
     def list_sub_folders(self, directory="", pattern="*"):
-        """Get a listing of subscribed folders on the server.
-
-        The default behaviour (no args) will list all subscribed folders for the
-        logged in user.
-
-        @param directory: The base directory to look for folders from.
-        @param pattern: A pattern to match against folder names. Only folder
-            names matching this pattern will be returned. Wildcards accepted.
-        @return: A list of (flags, delim, folder_name). As per the return of
-            list_folders().
+        """Return a list of subscribed folders on the server as
+        ``(flags, delimiter, name)`` tuples.
+
+        The default behaviour will list all subscribed folders. The
+        *directory* and *pattern* arguments are as per list_folders().
         """
         return self._do_list('LSUB', directory, pattern)
@@ -283 +265 @@
 
     def select_folder(self, folder, readonly=False):
-        """Select the current folder on the server. Future calls to methods
-        such as search and fetch will act on the selected folder.
-
-        @param folder: The folder name.
-        @return: A dictionary containing the SELECT response
-          values. At least the EXISTS, FLAGS and RECENT keys are
-          guaranteed to exist. Example:
+        """Set the current folder on the server.
+
+        Future calls to methods such as search and fetch will act on
+        the selected folder.
+
+        Returns a dictionary containing the ``SELECT`` response. At least
+        the ``EXISTS``, ``FLAGS`` and ``RECENT`` keys are guaranteed
+        to exist. An example::
+
             {'EXISTS': 3,
              'FLAGS': ('\\Answered', '\\Flagged', '\\Deleted', ... ),
@@ -406 +390 @@
 
     def folder_status(self, folder, what=None):
-        """Requests the status from folder.
-
-        @param folder: The folder name.
-        @param what: A sequence of status items to query. Defaults to
-            ('MESSAGES', 'RECENT', 'UIDNEXT', 'UIDVALIDITY', 'UNSEEN').
-        @return: Dictionary of the status items for the folder. The keys match
-            the items specified in the what parameter.
-        @rtype: dict
+        """Return the status of *folder*.
+
+        *what* should be a sequence of status items to query. This
+        defaults to ``('MESSAGES', 'RECENT', 'UIDNEXT', 'UIDVALIDITY',
+        'UNSEEN')``.
+
+        Returns a dictionary of the status items for the folder with
+        keys matching *what*.
         """
         if what is None:
@@ -438 +422 @@
 
     def close_folder(self):
-        """Close the currently selected folder.
-
-        @return: Server response.
+        """Close the currently selected folder, returning the server
+        response string.
         """
         typ, data = self._imap.close()
@@ -446 +429 @@
         return data[0]
 
-
     def create_folder(self, folder):
-        """Create a new folder on the server.
-
-        @param folder: The folder name.
-        @return: Server response.
+        """Create *folder* on the server returning the server response string.
         """
         typ, data = self._imap.create(self._encode_folder_name(folder))
@@ -457 +436 @@
         return data[0]
 
-
     def delete_folder(self, folder):
-        """Delete a new folder on the server.
-
-        @param folder: Folder name to delete.
-        @return: Server response.
+        """Delete *folder* on the server returning the server response string.
         """
         typ, data = self._imap.delete(self._encode_folder_name(folder))
@@ -468 +443 @@
         return data[0]
 
-
     def folder_exists(self, folder):
-        """Determine if a folder exists on the server.
-
-        @param folder: Full folder name to look for.
-        @return: True if the folder exists. False otherwise.
+        """Return ``True`` if *folder* exists on the server.
         """
         typ, data = self._imap.list('', self._encode_folder_name(folder))
@@ -480 +451 @@
         return len(data) == 1 and data[0] != None
 
-
     def subscribe_folder(self, folder):
-        """Subscribe to a folder.
-
-        @param folder: Folder name to subscribe to.
-        @return: Server response message.
+        """Subscribe to *folder*, returning the server response string.
         """
         typ, data = self._imap.subscribe(self._encode_folder_name(folder))
@@ -491 +458 @@
         return data
 
-
     def unsubscribe_folder(self, folder):
-        """Unsubscribe a folder.
-
-        @param folder: Folder name to unsubscribe.
-        @return: Server response message.
+        """Unsubscribe to *folder*, returning the server response string.
         """
         typ, data = self._imap.unsubscribe(self._encode_folder_name(folder))
@@ -502 +465 @@
         return data
 
-
     def search(self, criteria='ALL', charset=None):
+        """Return a list of messages ids matching *criteria*.
+
+        *criteria* should be a list of of one or more criteria
+        specifications or a single critera string. Example values
+        include::
+
+             'NOT DELETED'
+             'UNSEEN'
+             'SINCE 1-Feb-2011'
+
+        *charset* specifies the character set of the strings in the
+        criteria. It defaults to US-ASCII.
+
+        See `RFC-3501 section 6.4.4 <http://tools.ietf.org/html/rfc3501#section-6.4.4>`_
+        for more details.
+        """
         if not criteria:
             raise ValueError('no criteria specified')
@@ -527 +505 @@
 
 
-    def sort(self, sort_criteria, criteria='ALL', charset='UTF-8' ):
-        """Returns a list of messages sorted by sort_criteria.
-
-        Note that this is an extension to the IMAP4:
-        http://www.ietf.org/internet-drafts/draft-ietf-imapext-sort-19.txt
+    def sort(self, sort_criteria, criteria='ALL', charset='UTF-8'):
+        """Return a list of message ids sorted by *sort_criteria* and
+        optionally filtered by *criteria*.
+
+        Example values for *sort_criteria* include::
+
+            ARRIVAL
+            REVERSE SIZE
+            SUBJECT
+
+        The *criteria* argument is as per search(). 
+        See `RFC-5256 <http://tools.ietf.org/html/rfc5256>`_ for full details.
+
+        Note that SORT is an extension to the IMAP4 standard so it may
+        not be supported by all IMAP servers.
         """
         if not criteria:
@@ -553 +541 @@
         self._checkok('sort', typ, data)
 
-        return [ long(i) for i in data[0].split() ]
+        return [long(i) for i in data[0].split()]
 
 
     def get_flags(self, messages):
-        """Return the flags set for messages
-
-        @param messages: Message IDs to check flags for
-        @return: As for add_f
-            { msgid1: [flag1, flag2, ... ], }
+        """Return the flags set for each message in *messages*.
+
+        The return value is a dictionary structured like this: ``{
+        msgid1: [flag1, flag2, ... ], }``.
         """
         response = self.fetch(messages, ['FLAGS'])
@@ -568 +555 @@
 
     def add_flags(self, messages, flags):
-        """Add one or more flags to messages
-
-        @param messages: Message IDs to add flags to
-        @param flags: Sequence of flags to add
-        @return: The flags set for each message ID as a dictionary
-            { msgid1: [flag1, flag2, ... ], }
+        """Add *flags* to *messages*.
+
+        *flags* should be a sequence of strings.
+
+        Returns the flags set for each modified message (see
+        *get_flags*).
         """
         return self._store('+FLAGS', messages, flags)
@@ -579 +566 @@
 
     def remove_flags(self, messages, flags):
-        """Remove one or more flags from messages
-
-        @param messages: Message IDs to remove flags from
-        @param flags: Sequence of flags to remove
-        @return: As for get_flags.
+        """Remove one or more *flags* from *messages*.
+
+        *flags* should be a sequence of strings.
+
+        Returns the flags set for each modified message (see
+        *get_flags*).
         """
         return self._store('-FLAGS', messages, flags)
@@ -589 +577 @@
 
     def set_flags(self, messages, flags):
-        """Set the flags for messages
-
-        @param messages: Message IDs to set flags for
-        @param flags: Sequence of flags to set
-        @return: As for get_flags.
+        """Set the *flags* for *messages*.
+
+        *flags* should be a sequence of strings.
+
+        Returns the flags set for each modified message (see
+        *get_flags*).
         """
         return self._store('FLAGS', messages, flags)
@@ -599 +588 @@
 
     def delete_messages(self, messages):
-        """Short-hand method for deleting one or more messages
-
-        @param messages: Message IDs to mark for deletion.
-        @return: Same as for get_flags.
+        """Delete one or more *messages* from the currently selected
+        folder.
+
+        Returns the flags set for each modified message (see
+        *get_flags*).
         """
         return self.add_flags(messages, DELETED)
 
 
-    def fetch(self, messages, parts, modifiers=None):
-        """Retrieve selected data items for one or more messages.
-
-        @param messages: Message IDs to fetch.
-        @param parts: A sequence of data items to retrieve.
-        @param modifiers: An optional sequence of modifiers (where
-            supported by the server, eg. ['CHANGEDSINCE 123']).
-        @return: A dictionary indexed by message number. Each item is itself a
-            dictionary containing the requested message parts.
-            INTERNALDATE parts will be returned as datetime objects converted
-            to the local machine's time zone.
+    def fetch(self, messages, data, modifiers=None):
+        """Retrieve selected *data* associated with one or more *messages*.
+
+        *data* should be specified as a sequnce of strings, one item
+        per data selector, for example ``['INTERNALDATE',
+        'RFC822']``.
+
+        *modifiers* are required for some extensions to the IMAP
+        protocol (eg. RFC 4551). These should be a sequnce of strings
+        if specified, for example ``['CHANGEDSINCE 123']``.
+
+        A dictionary is returned, indexed by message number. Each item
+        in this dictionary is also a dictionary, with an entry
+        corresponding to each item in *data*.
+
+        In addition to an element for each *data* item, the dict
+        returned for each message also contains a *SEQ* key containing
+        the sequence number for the message. This allows for mapping
+        between the UID and sequence number (when the *use_uid*
+        property is ``True``).
+
+        Example::
+
+            >> c.fetch([3293, 3230], ['INTERNALDATE', 'FLAGS'])
+            {3230: {'FLAGS': ('\\Seen',),
+                    'INTERNALDATE': datetime.datetime(2011, 1, 30, 13, 32, 9),
+                    'SEQ': 84},
+             3293: {'FLAGS': (),
+                    'INTERNALDATE': datetime.datetime(2011, 2, 24, 19, 30, 36),
+                    'SEQ': 110}}
+
         """
         if not messages:
@@ -623 +633 @@
 
         msg_list = messages_to_str(messages)
-        parts_list = seq_to_parenlist([p.upper() for p in parts])
+        data_list = seq_to_parenlist([p.upper() for p in data])
         modifiers_list = None
         if modifiers is not None:
@@ -629 +639 @@
 
         if self.use_uid:
-            tag = self._imap._command('UID', 'FETCH', msg_list, parts_list, modifiers_list)
+            tag = self._imap._command('UID', 'FETCH', msg_list, data_list, modifiers_list)
         else:
-            tag = self._imap._command('FETCH', msg_list, parts_list, modifiers_list)
+            tag = self._imap._command('FETCH', msg_list, data_list, modifiers_list)
         typ, data = self._imap._command_complete('FETCH', tag)
         self._checkok('fetch', typ, data)
@@ -637 +647 @@
         return parse_fetch_response(data)
 
-
     def append(self, folder, msg, flags=(), msg_time=None):
-        """Append a message to a folder
-
-        @param folder: Folder name to append to.
-        @param msg: Message body as a string.
-        @param flags: Sequnce of message flags to set. If not specified no
-            flags will be set.
-        @param msg_time: Optional date and time to set for the message. The
-            server will set a time if it isn't specified. If msg_time contains
-            timezone information (tzinfo), this will be honoured. Otherwise the
-            local machine's time zone sent to the server.
-        @type msg_time: datetime.datetime
-        @return: The append response returned by the server.
-        @rtype: str
+        """Append a message to *folder*.
+
+        *msg* should be a string contains the full message including
+        headers.
+
+        *flags* should be a sequence of message flags to set. If not
+        specified no flags will be set.
+
+        *msg_time* is an optional datetime instance specifying the
+        date and time to set on the message. The server will set a
+        time if it isn't specified. If *msg_time* contains timezone
+        information (tzinfo), this will be honoured. Otherwise the
+        local machine's time zone sent to the server.
+
+        Returns the APPEND response as returned by the server.
         """
         if msg_time:
@@ -666 +677 @@
         return data[0]
 
-
     def copy(self, messages, folder):
-        """Copy one or more messages from the current folder to another folder
-
-        @param messages: Message IDs to fetch.
-        @param folder: Folder name to append to.
-        @return: The COPY command response message returned by the
-          server.
+        """Copy one or more messages from the current folder to
+        *folder*. Returns the COPY response string returned by the
+        server.
         """
         msg_list = messages_to_str(messages)
@@ -685 +692 @@
         return data[0]
 
-
     def expunge(self):
+        """Remove any messages from the currently selected folder that
+        have the ``\\Deleted`` flag set.
+        """
         typ, data = self._imap.expunge()
         self._checkok('expunge', typ, data)
         #TODO: expunge response
 
-
     def getacl(self, folder):
-        """Get the ACL for a folder
-
-        @param folder: Folder name to get the ACL for.
-        @return: A list of (who, acl) tuples
+        """Returns a list of ``(who, acl)`` tuples describing the
+        access controls for *folder*.
         """
         typ, data = self._imap.getacl(folder)
@@ -705 +711 @@
         return [(parts[i], parts[i+1]) for i in xrange(0, len(parts), 2)]
 
-
     def setacl(self, folder, who, what):
-        """Set an ACL for a folder
-
-        @param folder: Folder name to set an ACL for.
-        @param who: User or group ID for the ACL.
-        @param what: A string describing the ACL. Set to '' to remove an ACL.
-        @return: Server response string.
+        """Set an ACL (*what*) for user (*who*) for a folder.
+
+        Set *what* to an empty string to remove an ACL. Returns the
+        server response string.
         """
         typ, data = self._imap.setacl(folder, who, what)
@@ -718 +721 @@
         return data[0]
 
-
     def _check_resp(self, expected, command, typ, data):
         """Check command responses for errors.
 
-        @raise: Error if a command failed.
+        Raises IMAPClient.Error if the command fails.
         """
         if typ != expected:
             raise self.Error('%s failed: %r' % (command, data[0]))
 
-
     def _checkok(self, command, typ, data):
         self._check_resp('OK', command, typ, data)
 
-
     def _checkbye(self, command, typ, data):
         self._check_resp('BYE', command, typ, data)
 
-
     def _store(self, cmd, messages, flags):
-        """Worker function for flag manipulation functions
-
-        @param cmd: STORE command to use (eg. '+FLAGS')
-        @param messages: Sequence of message IDs
-        @param flags: Sequence of flags to set.
-        @return: The flags set for each message ID as a dictionary
-            { msgid1: [flag1, flag2, ... ], }
+        """Worker function for the various flag manipulation methods.
+
+        *cmd* is the STORE command to use (eg. '+FLAGS').
         """
         if not messages:
@@ -758 +753 @@
         return self._flatten_dict(parse_fetch_response((data)))
 
-
     def _flatten_dict(self, fetch_dict):
         return dict([
@@ -769 +763 @@
             return imap_utf7.decode(name)
         return name
-
 
     def _encode_folder_name(self, name):
@@ -806 +799 @@
 
 def messages_to_str(messages):
-    """Convert a sequence of messages ids or a single message id into an
-    message ID list for use with IMAP commands.
-
-    @param messages: A sequence of messages IDs or a single message ID.
-        (eg. [1,4,5,7,8])
-    @return: Message list string (eg. "1,4,5,6,8")
+    """Convert a sequence of messages ids or a single integer message id
+    into an id list string for use with IMAP commands
     """
     if isinstance(messages, (str, int, long)):
@@ -821 +810 @@
 
 def seq_to_parenlist(flags):
-    """Convert a sequence into parenthised list for use with IMAP commands
-
-    @param flags: Sequence to process (eg. ['abc', 'def'])
-    @return: IMAP parenthenised list (eg. '(abc def)')
+    """Convert a sequence of strings into parenthised list string for
+    use with IMAP commands.
     """
     if isinstance(flags, str):
@@ -834 +821 @@
 
 def datetime_to_imap(dt):
-    """Convert a datetime instance to a IMAP datetime string
-
-    If timezone information is missing the current system timezone is used.
+    """Convert a datetime instance to a IMAP datetime string.
+
+    If timezone information is missing the current system
+    timezone is used.
     """
     if not dt.tzinfo:

imapclient/imapclient.py

@@ -4 +4 @@
 
 import re
+import select
+import socket
+import sys
+import warnings
+from datetime import datetime
+from operator import itemgetter
+
 import imaplib
 import response_lexer
-from operator import itemgetter
-import warnings
-#imaplib.Debug = 5
+
+    
+try:
+    import oauth2
+except ImportError:
+    oauth2 = None
 
 import imap_utf7
@@ -14 +24 @@
 
 
-__all__ = ['IMAPClient', 'DELETED', 'SEEN', 'ANSWERED', 'FLAGGED', 'DRAFT',
-    'RECENT']
+__all__ = ['IMAPClient', 'DELETED', 'SEEN', 'ANSWERED', 'FLAGGED', 'DRAFT', 'RECENT']
 
 from response_parser import parse_response, parse_fetch_response
@@ -22 +31 @@
 if 'XLIST' not in imaplib.Commands:
   imaplib.Commands['XLIST'] = imaplib.Commands['LIST']
+
+# ...and IDLE
+if 'IDLE' not in imaplib.Commands:
+  imaplib.Commands['IDLE'] = imaplib.Commands['APPEND']
 
 
@@ -63 +76 @@
 
     def __init__(self, host, port=None, use_uid=True, ssl=False):
-        if ssl:
-            ImapClass = imaplib.IMAP4_SSL
-            default_port = 993
-        else:
-            ImapClass = imaplib.IMAP4
-            default_port = 143
-
         if port is None:
-            port = default_port
-
-        self._imap = ImapClass(host, port)
+            port = ssl and 993 or 143
+
+        self.host = host
+        self.port = port
+        self.ssl = ssl
         self.use_uid = use_uid
         self.folder_encode = True
-
-   
+        self.log_file = sys.stderr
+
+        self._imap = self._create_IMAP4()
+        self._imap._mesg = self._log    # patch in custom debug log method
+        self._idle_tag = None
+
+    def _create_IMAP4(self):
+        # Create the IMAP instance in a separate method to make unit tests easier
+        ImapClass = self.ssl and imaplib.IMAP4_SSL or imaplib.IMAP4
+        return ImapClass(self.host, self.port)
+
     def login(self, username, password):
         """Login using *username* and *password*, returning the
@@ -86 +103 @@
         return data[0]
 
+    def oauth_login(self, url, oauth_token, oauth_token_secret,
+                    consumer_key='anonymous', consumer_secret='anonymous'):
+        """Authenticate using oauth.
+
+        @param url: The OAuth request URL.
+        @param oauth_token: An OAuth key.
+        @param oauth_token_secret: An OAuth secret.
+        @param consumer_key: An OAuth consumer key (defaults to 'anonymous').
+        @param consumer_secret: An OAuth consumer secret (defaults to 'anonymous').
+        """
+        if oauth2:
+            token = oauth2.Token(oauth_token, oauth_token_secret)
+            consumer = oauth2.Consumer(consumer_key, consumer_secret)
+            xoauth_callable = lambda x: oauth2.build_xoauth_string(url, consumer, token)
+            
+            typ, data = self._imap.authenticate('XOAUTH', xoauth_callable)
+            self._checkok('authenticate', typ, data)
+            return data[0]
+        else:
+            raise self.Error('The optional oauth2 dependency is needed for oauth authentication')
 
     def logout(self):
@@ -248 +285 @@
         self._checkok('select', typ, data)
         return self._process_select_response(self._imap.untagged_responses)
-
 
     def _process_select_response(self, resp):
@@ -266 +302 @@
         return out
 
+    def idle(self):
+        """Put server into IDLE mode.
+
+        In this mode the server will return unsolicited responses
+        about changes to the selected mailbox.
+
+        This method returns immediately. Use idle_check() to check for
+        IDLE responses and idle_done() to stop IDLE mode.
+
+        Note: Any other commmands issued while the server is in IDLE
+        mode will fail.
+
+        See RFC 2177 for more information about the IDLE extension.
+        http://tools.ietf.org/html/rfc2177
+        """
+        self._idle_tag = self._imap._command('IDLE')
+        resp = self._imap._get_response()
+        if resp is not None:
+            raise self.Error('Unexpected IDLE response: %s' % resp)
+
+    def idle_check(self, timeout=None):
+        """Check for any IDLE responses sent by the server.
+
+        This method should only be called if the server is in IDLE
+        mode (see idle()).
+
+        By default, this method will block until an IDLE response is
+        received. If timeout is provided, the call will block for at
+        most this number of seconds while waiting for an IDLE response.
+
+        The return value is a list of received IDLE responses. These
+        will be parsed with values converted to appropriate types. For
+        example:
+
+        [('OK', 'Still here'),
+         (1, 'EXISTS'),
+         (1, 'FETCH', ('FLAGS', ('\\NotJunk',)))]
+        """
+        # make the socket non-blocking so the timeout can be
+        # implemented for this call
+        if self.ssl:
+            sock = self._imap.sslobj
+        else:
+            sock = self._imap.sock
+        sock.setblocking(0)
+        try:
+            resps = []
+            rs, _, _ = select.select([sock], [], [], timeout)
+            if rs:
+                while True:
+                    try:
+                        line = self._imap._get_line()
+                    except (socket.timeout, socket.error):
+                        break
+                    else:
+                        resps.append(_parse_idle_response(line))
+            return resps
+        finally:
+            sock.setblocking(1)
+
+    def idle_done(self):
+        """Take the server out of IDLE mode.
+
+        This method should only be called if the server is in IDLE mode.
+
+        The return value is (command_text, idle_responses) where
+        command_text is the text sent by the server when the IDLE
+        command finished (eg. 'Idle terminated') and idle_responses is
+        a list of parsed idle responses received since the last call
+        to idle_check() (if any). These are returned in parsed form as
+        per idle_check().
+        """
+        self._imap.send('DONE\r\n')
+        # Slurp up any remaining IDLE responses until the IDLE is done
+        tag = self._idle_tag
+        tagged_commands = self._imap.tagged_commands
+        resps = []
+        while True:
+            line = self._imap._get_response()
+            if tagged_commands[tag]:
+                break
+            resps.append(_parse_idle_response(line))
+        self._idle_tag = None
+        typ, data = tagged_commands.pop(tag)
+        self._checkok('idle', typ, data)
+        return data[0], resps
 
     def folder_status(self, folder, what=None):
@@ -585 +707 @@
         self._checkok('getacl', typ, data)
 
-        parts = list(response_lexer.Lexer([data[0]]))
+        parts = list(response_lexer.TokenSource(data))
         parts = parts[1:]       # First item is folder name
-
-        out = []
-        for i in xrange(0, len(parts), 2):
-            out.append((parts[i], parts[i+1]))
-        return out
+        return [(parts[i], parts[i+1]) for i in xrange(0, len(parts), 2)]
 
     def setacl(self, folder, who, what):
@@ -660 +778 @@
         return _quote_arg(name)
 
+    def __debug_get(self):
+        return self._imap.debug
+
+    def __debug_set(self, level):
+        if level is True:
+            level = 4
+        elif level is False:
+            level = 0
+        self._imap.debug = level
+
+    debug = property(__debug_get, __debug_set,
+                     doc="Set debug level. Integers from 0 to 5 or, True and " \
+                         "False can be used. True specifies debug level 4. " \
+                         "Debug output goes to stderr.")
+
+    def _log(self, text):
+        self.log_file.write('%s %s\n' % (datetime.now().strftime('%M:%S.%f'), text))
+        self.log_file.flush()
+        
 
 def messages_to_str(messages):
@@ -698 +835 @@
   arg = arg.replace('"', '\\"')
   return '"%s"' % arg
+
+
+def _parse_idle_response(text):
+    assert text.startswith('* ')
+    text = text[2:]
+    if text.startswith(('OK ', 'NO ')):
+        return tuple(text.split(' ', 1))
+    return parse_response([text]) 
+