Changeset 243:35fc2ded237d

Timestamp:

19/02/11 23:37:20 (15 months ago)

Author:

Menno Smits <menno@…>

Branch:

default

Parents:

240:ca209b0b5f0c (diff), 242:295f2c9d5b4f (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:

resynced with trunk

Files:

• imapclient/imapclient.py (modified) (8 diffs)
• imapclient/imapclient.py (modified) (31 diffs)
• run_tests.py (deleted)

imapclient/imapclient.py

@@ -1 @@
-# Copyright (c) 2010, Menno Smits
+# Copyright (c) 2011, Menno Smits
 # Released subject to the New BSD License
 # Please see http://en.wikipedia.org/wiki/BSD_licenses
@@ -6 +6 @@
 import imaplib
 import response_lexer
+from operator import itemgetter
+import warnings
 #imaplib.Debug = 5
 
@@ -30 +32 @@
 RECENT = r'\Recent'         # This flag is read-only
 
+class Namespace(tuple):
+    def __new__(cls, personal, other, shared):
+        return tuple.__new__(cls, (personal, other, shared)) 
+
+    personal = property(itemgetter(0))
+    other = property(itemgetter(1))
+    shared = property(itemgetter(2))
+
 
 class IMAPClient(object):
@@ -49 +59 @@
     ReadOnlyError = imaplib.IMAP4.readonly
 
-    re_sep = re.compile('^\(\("[^"]*" "([^"]+)"\)\)')
     re_status = re.compile(r'^\s*"?(?P<folder>[^"]+)"?\s+'
                            r'\((?P<status_items>.*)\)$')
@@ -105 +114 @@
             return False
 
-    def get_folder_delimiter(self):
-        """Return the folder separator used by the IMAP server (eg. "/").
+    def namespace(self):
+        """Return the namespace for the account as a (personal, other, shared) tuple.
+
+        Each element may be None if no namespace of that type exists,
+        or a sequence of (prefix, separator) pairs.
+
+        For convenience the tuple elements may be accessed
+        positionally or attributes named "personal", "other" and
+        "shared".
+
+        See RFC 2342 for more details.
         """
         typ, data = self._imap.namespace()
         self._checkok('namespace', typ, data)
-
-        match = self.re_sep.match(data[0])
-        if match:
-            return match.group(1)
-        else:
-            raise self.Error('could not determine folder separator')
+        return Namespace(*parse_response(data))
+
+    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
+        """
+        warnings.warn(DeprecationWarning('get_folder_delimiter is going away. Use namespace() instead.'))
+        for part in self.namespace():
+            for ns in part:
+                return ns[1]
+        raise self.Error('could not determine folder separator')
 
     def list_folders(self, directory="", pattern="*"):
@@ -415 +444 @@
 
 
-    def fetch(self, messages, parts):
+    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.
@@ -430 +461 @@
         msg_list = messages_to_str(messages)
         parts_list = seq_to_parenlist([p.upper() for p in parts])
+        modifiers_list = None
+        if modifiers is not None:
+          modifiers_list = seq_to_parenlist([m.upper() for m in modifiers])
 
         if self.use_uid:
-            tag = self._imap._command('UID', 'FETCH', msg_list, parts_list)
-        else:
-            tag = self._imap._command('FETCH', msg_list, parts_list)
+            tag = self._imap._command('UID', 'FETCH', msg_list, parts_list, modifiers_list)
+        else:
+            tag = self._imap._command('FETCH', msg_list, parts_list, modifiers_list)
         typ, data = self._imap._command_complete('FETCH', tag)
         self._checkok('fetch', typ, data)
         typ, data = self._imap._untagged_response(typ, data, 'FETCH')
-        # appears to be a special case - no 'untagged' responses (ie, no
-        # folders) results in [None]
-        if data == [None]:
-          return {}
-
         return parse_fetch_response(data)
 
@@ -555 +584 @@
             typ, data = self._imap.store(msg_list, cmd, flag_list)
         self._checkok('store', typ, data)
-
         return self._flatten_dict(parse_fetch_response((data)))
 

imapclient/imapclient.py

@@ -43 +43 @@
 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``).
     """
 
@@ -84 +63 @@
 
     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 ssl:
             ImapClass = imaplib.IMAP4_SSL
@@ -107 +79 @@
    
     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)
@@ -115 +88 @@
 
     def logout(self):
-        """Perform a logout
+        """Logout, returning the server response.
         """
         typ, data = self._imap.logout()
@@ -123 +96 @@
 
     def capabilities(self):
-        """Returns the server capability list
+        """Returns the server capability list.
         """
         return self._imap.capabilities
@@ -129 +102 @@
 
     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
@@ -176 +147 @@
 
     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. Wildcards (``*`` and
+        ``?``) are supported in *pattern*.
+
+        #XXX check wildcard facts
+
+        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.
+
+        #XXX check the above is still true
         """
         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.
+
+        XXX example response
+                                            
+        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)
@@ -284 +260 @@
 
     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:
@@ -316 +292 @@
 
     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()
@@ -324 +299 @@
         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))
@@ -335 +306 @@
         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))
@@ -346 +313 @@
         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))
@@ -358 +321 @@
         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))
@@ -369 +328 @@
         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))
@@ -380 +335 @@
         return data
 
-
     def search(self, criteria='ALL', charset=None):
+        """Return a list of messages ids matching *criteria*.
+
+        XXX more detail
+        """
         if not criteria:
             raise ValueError('no criteria specified')
@@ -406 +364 @@
 
     def sort(self, sort_criteria, criteria='ALL', charset='UTF-8' ):
-        """Returns a list of messages sorted by sort_criteria.
+        """Return a list of message ids sorted by *sort_criteria* and
+        optionally filtered by *criteria*.
+
+        The *critera* are as per search().  
 
         Note that this is an extension to the IMAP4:
         http://www.ietf.org/internet-drafts/draft-ietf-imapext-sort-19.txt
+
+        XXX needs more detail
+        XXX explain charset
         """
         if not criteria:
@@ -435 +399 @@
 
     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, ... ], }
+        """Returns the flags set for each message in *messages* as a
+        dictionary structured like this:
+          ``{ msgid1: [flag1, flag2, ... ], }``.
         """
         response = self.fetch(messages, ['FLAGS'])
@@ -446 +408 @@
 
     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)
@@ -457 +417 @@
 
     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)
@@ -467 +426 @@
 
     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)
@@ -477 +435 @@
 
     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)
@@ -515 +474 @@
         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:
@@ -544 +504 @@
         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)
@@ -563 +519 @@
         return data[0]
 
-
     def expunge(self):
+        """Remove any messaages from the server that have the \Deleted
+        flag set.
+
+        XXX check if this is just for the current folder
+        """
         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)
@@ -587 +544 @@
         return out
 
-
     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)
@@ -600 +554 @@
         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:
@@ -639 +585 @@
         self._checkok('store', typ, data)
         return self._flatten_dict(parse_fetch_response((data)))
-
 
     def _flatten_dict(self, fetch_dict):
@@ -651 +596 @@
             return imap_utf7.decode(name)
         return name
-
 
     def _encode_folder_name(self, name):
@@ -669 +613 @@
 
 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)):
@@ -684 +624 @@
 
 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):
@@ -697 +635 @@
 
 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: