Changeset 116:a975e50ceb32

Timestamp:

11/01/10 19:14:38 (2 years ago)

Author:

Menno Smits <menno@…>

Branch:

default

Parents:

115:7aa870b75d11 (diff), 98:bd244d16fcea (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:

Merged from trunk

Files:

• imapclient/imapclient.py (modified) (46 diffs)
• imapclient/imapclient.py (modified) (4 diffs)

imapclient/imapclient.py

@@ -11 +11 @@
 import imap_utf7
 from fixed_offset import FixedOffset
+
 
 __all__ = ['IMAPClient', 'DELETED', 'SEEN', 'ANSWERED', 'FLAGGED', 'DRAFT',
@@ -27 +28 @@
 
 class IMAPClient(object):
-    '''
+    """
     A Pythonic, easy-to-use IMAP client class.
 
@@ -59 +60 @@
     These are aliases for the imaplib.IMAP4 exceptions of the same name. Socket
     errors may also be raised in the case of network errors.
-    '''
+    """
 
     Error = imaplib.IMAP4.error
@@ -66 +67 @@
 
     re_sep = re.compile('^\(\("[^"]*" "([^"]+)"\)\)')
-    re_folder = re.compile('\([^)]*\) "[^"]+" "?([^"]+)"?')
+#     re_folder = re.compile('\([^)]*\) "[^"]+" "?([^"]+)"?')
+    re_folder = re.compile(r'\([^)]*\) "[^"]+" (?P<qqq>"?)(?P<folder>.+)(?P=qqq)')
     re_status = re.compile(r'^\s*"?(?P<folder>[^"]+)"?\s+'
                            r'\((?P<status_items>.*)\)$')
 
     def __init__(self, host, port=None, use_uid=True, ssl=False):
-        '''Initialise object instance and connect to the remote IMAP server.
+        """Initialise object instance and connect to the remote IMAP server.
 
         @param host: The IMAP server address/hostname to connect to.
@@ -77 +79 @@
         @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
@@ -94 +96 @@
    
     def login(self, username, password):
-        '''Perform a simple login
-        '''
+        """Perform a simple login
+        """
         typ, data = self._imap.login(username, password)
         self._checkok('login', typ, data)
@@ -102 +104 @@
 
     def logout(self):
-        '''Perform a logout
-        '''
+        """Perform a logout
+        """
         typ, data = self._imap.logout()
         self._checkbye('logout', typ, data)
@@ -110 +112 @@
 
     def capabilities(self):
-        '''Returns the server capability list
-        '''
+        """Returns the server capability list
+        """
         return self._imap.capabilities
 
 
     def has_capability(self, capability):
-        '''Checks if the server has the given capability.
+        """Checks if the server has the given capability.
 
         @param capability: capability to test (eg 'SORT')
-        '''
+        """
         # FIXME: this will not detect capabilities that are backwards
         # compatible with the current level. For instance the SORT
@@ -131 +133 @@
 
     def get_folder_delimiter(self):
-        '''Determine the folder separator used by the IMAP server.
+        """Determine the folder separator used by the IMAP server.
 
         @return: The folder separator.
         @rtype: string
-        '''
+        """
         typ, data = self._imap.namespace()
         self._checkok('namespace', typ, data)
@@ -147 +149 @@
 
     def list_folders(self, directory="", pattern="*"):
-        '''Get a listing of folders on the server.
+        """Get a listing of folders on the server.
 
         The default behaviour (no args) will list all folders for the logged in
@@ -159 +161 @@
             decoding). If the folder_encode attribute is False, no decoding
             will be performed and only ordinary strings will be returned.
-        '''
+        """
         typ, data = self._imap.list(directory, pattern)
         self._checkok('list', typ, data)
-
+        return self._proc_folder_list(data)
+
+
+    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 folder names. As per the return of list_folders().
+        """
+        typ, data = self._imap.lsub(directory, pattern)
+        self._checkok('lsub', typ, data)
+        return self._proc_folder_list(data)
+
+
+    def _proc_folder_list(self, folder_data):
         folders = []
-        for line in data:
+        for line in folder_data:
             #TODO can the FetchParser code be adapted for use here?
             folder_text = None
             if isinstance(line, tuple):
                 folder_text = line[-1]
-            else:
+            elif line:
                 match = self.re_folder.match(line)
                 if match:
-                    folder_text = match.group(1)
+                    folder_text = match.group('folder')
+                    folder_text = folder_text.replace(r'\"', '"')
+                    folder_text = folder_text.replace(r'\\', '\\')
             if folder_text is not None:
                 folders.append(self._decode_folder_name(folder_text))
         return folders
-
-
-    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 folder names. As per the return of list_folders().
-        '''
-        typ, data = self._imap.lsub(directory, pattern)
-        self._checkok('lsub', typ, data)
-
-        folders = []
-        for line in data:
-            if line:
-                m = self.re_folder.match(line)
-                if m:
-                    folders.append(self._decode_folder_name(m.group(1)))
-        return folders
-
+        
 
     def select_folder(self, folder):
-        '''Select the current folder on the server. Future calls to methods
+        """Select the current folder on the server. Future calls to methods
         such as search and fetch will act on the selected folder.
 
@@ -208 +208 @@
         @return: Number of messages in the folder.
         @rtype: long int
-        '''
+        """
         typ, data = self._imap.select(self._encode_folder_name(folder))
         self._checkok('select', typ, data)
@@ -215 +215 @@
 
     def folder_status(self, folder, what=None):
-        '''Requests the status from folder.
+        """Requests the status from folder.
 
         @param folder: The folder name.
@@ -223 +223 @@
             the items specified in the what parameter.
         @rtype: dict
-        '''
+        """
         if what is None:
             what = ('MESSAGES', 'RECENT', 'UIDNEXT', 'UIDVALIDITY', 'UNSEEN')
@@ -247 +247 @@
 
     def close_folder(self):
-        '''Close the currently selected folder.
+        """Close the currently selected folder.
 
         @return: Server response.
-        '''
+        """
         typ, data = self._imap.close()
         self._checkok('close', typ, data)
@@ -257 +257 @@
 
     def create_folder(self, folder):
-        '''Create a new folder on the server.
+        """Create a new folder on the server.
 
         @param folder: The folder name.
         @return: Server response.
-        '''
+        """
         typ, data = self._imap.create(self._encode_folder_name(folder))
         self._checkok('create', typ, data)
@@ -268 +268 @@
 
     def delete_folder(self, folder):
-        '''Delete a new folder on the server.
+        """Delete a new folder on the server.
 
         @param folder: Folder name to delete.
         @return: Server response.
-        '''
+        """
         typ, data = self._imap.delete(self._encode_folder_name(folder))
         self._checkok('delete', typ, data)
@@ -279 +279 @@
 
     def folder_exists(self, folder):
-        '''Determine if a folder exists on the server.
+        """Determine if a folder exists on the server.
 
         @param folder: Full folder name to look for.
         @return: True if the folder exists. False otherwise.
-        '''
+        """
         typ, data = self._imap.list('', self._encode_folder_name(folder))
         self._checkok('list', typ, data)
@@ -290 +290 @@
 
     def subscribe_folder(self, folder):
-        '''Subscribe to a folder.
+        """Subscribe to a folder.
 
         @param folder: Folder name to subscribe to.
         @return: Server response message.
-        '''
+        """
         typ, data = self._imap.subscribe(self._encode_folder_name(folder))
         self._checkok('subscribe', typ, data)
@@ -301 +301 @@
 
     def unsubscribe_folder(self, folder):
-        '''Unsubscribe a folder.
+        """Unsubscribe a folder.
 
         @param folder: Folder name to unsubscribe.
         @return: Server response message.
-        '''
+        """
         typ, data = self._imap.unsubscribe(self._encode_folder_name(folder))
         self._checkok('unsubscribe', typ, data)
@@ -336 +336 @@
 
     def sort(self, sort_criteria, criteria='ALL', charset='UTF-8' ):
-        '''Returns a list of messages sorted by sort_criteria.
+        """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
-        '''
+        """
         if not criteria:
             raise ValueError('no criteria specified')
@@ -365 +365 @@
 
     def get_flags(self, messages):
-        '''Return the flags set for messages
+        """Return the flags set for messages
 
         @param messages: Message IDs to check flags for
         @return: As for add_f
             { msgid1: [flag1, flag2, ... ], }
-        '''
+        """
         response = self.fetch(messages, ['FLAGS'])
         return self._flatten_dict(response)
@@ -376 +376 @@
 
     def add_flags(self, messages, flags):
-        '''Add one or more flags to messages
+        """Add one or more flags to messages
 
         @param messages: Message IDs to add flags to
@@ -382 +382 @@
         @return: The flags set for each message ID as a dictionary
             { msgid1: [flag1, flag2, ... ], }
-        '''
+        """
         return self._store('+FLAGS', messages, flags)
 
 
     def remove_flags(self, messages, flags):
-        '''Remove one or more flags from messages
+        """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.
-        '''
+        """
         return self._store('-FLAGS', messages, flags)
 
 
     def set_flags(self, messages, flags):
-        '''Set the flags for messages
+        """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.
-        '''
+        """
         return self._store('FLAGS', messages, flags)
 
 
     def delete_messages(self, messages):
-        '''Short-hand method for deleting one or more messages
+        """Short-hand method for deleting one or more messages
 
         @param messages: Message IDs to mark for deletion.
         @return: Same as for get_flags.
-        '''
+        """
         return self.add_flags(messages, DELETED)
 
 
     def fetch(self, messages, parts):
-        '''Retrieve selected data items for one or more messages.
+        """Retrieve selected data items for one or more messages.
 
         @param messages: Message IDs to fetch.
@@ -424 +424 @@
             INTERNALDATE parts will be returned as datetime objects converted
             to the local machine's time zone.
-        '''
+        """
         if not messages:
             return {}
@@ -462 +462 @@
 
     def append(self, folder, msg, flags=(), msg_time=None):
-        '''Append a message to a folder
+        """Append a message to a folder
 
         @param folder: Folder name to append to.
@@ -475 +475 @@
         @return: The append response returned by the server.
         @rtype: str
-        '''
+        """
         if msg_time:
             time_val = '"%s"' % datetime_to_imap(msg_time)
@@ -497 +497 @@
 
     def getacl(self, folder):
-        '''Get the ACL for a folder
+        """Get the ACL for a folder
 
         @param folder: Folder name to get the ACL for.
         @return: A list of (who, acl) tuples
-        '''
+        """
         typ, data = self._imap.getacl(folder)
         self._checkok('getacl', typ, data)
@@ -515 +515 @@
 
     def setacl(self, folder, who, what):
-        '''Set an ACL for a folder
+        """Set an ACL for a folder
 
         @param folder: Folder name to set an ACL for.
@@ -521 +521 @@
         @param what: A string describing the ACL. Set to '' to remove an ACL.
         @return: Server response string.
-        '''
+        """
         typ, data = self._imap.setacl(folder, who, what)
         self._checkok('setacl', typ, data)
@@ -528 +528 @@
 
     def _check_resp(self, expected, command, typ, data):
-        '''Check command responses for errors.
+        """Check command responses for errors.
 
         @raise: Error if a command failed.
-        '''
+        """
         if typ != expected:
             raise self.Error('%s failed: %r' % (command, data[0]))
@@ -545 +545 @@
 
     def _store(self, cmd, messages, flags):
-        '''Worker function for flag manipulation functions
+        """Worker function for flag manipulation functions
 
         @param cmd: STORE command to use (eg. '+FLAGS')
@@ -552 +552 @@
         @return: The flags set for each message ID as a dictionary
             { msgid1: [flag1, flag2, ... ], }
-        '''
+        """
         if not messages:
             return {}
@@ -587 +587 @@
 
 class FetchParser(object):
-    '''
+    """
     Parse an IMAP FETCH response and convert the return values to useful Python
     values.
-    '''
+    """
 
     def parse(self, response):
@@ -623 +623 @@
 
         data = data.lstrip()
+        msgid = None
         if data[0].isdigit():
             # Get message ID
@@ -630 +631 @@
             assert data.startswith('('), data
             data = data[1:]
-            if data.endswith(')'):
-                data = data[:-1]
-
-        else:
-            msgid = None
+
+        if data.endswith(')'):
+            data = data[:-1]
 
         for name, item in FetchTokeniser().process_pairs(data):
@@ -658 +657 @@
 
     def do_INTERNALDATE(self, arg):
-        '''Process an INTERNALDATE response
+        """Process an INTERNALDATE response
 
         @param arg: A quoted IMAP INTERNALDATE string
             (eg. " 9-Feb-2007 17:08:08 +0000")
         @return: datetime.datetime instance for the given time (in UTC)
-        '''
+        """
         arg = 'INTERNALDATE "%s"' % arg
         mo = imaplib.InternalDate.match(arg)
@@ -693 +692 @@
 
 class FetchTokeniser(object):
-    '''
+    """
     General response tokenizer and converter
-    '''
+    """
 
     QUOTED_STRING = '(?:".*?")'
@@ -715 +714 @@
 
     def process_pairs(self, s):
-        '''Break up and convert a string of FETCH response pairs
+        """Break up and convert a string of FETCH response pairs
 
         @param s: FETCH response string eg. "FOO 12 BAH (1 abc def "foo bar")"
         @return: Tokenised and converted input return as (name, data) pairs.
-        '''
+        """
         out = []
         for m in strict_finditer(self.PAIR_RE, s):
@@ -727 +726 @@
 
     def process_list(self, s):
-        '''Break up and convert a string of data items
+        """Break up and convert a string of data items
 
         @param s: FETCH response string eg. "(1 abc def "foo bar")"
         @return: A list of converted items.
-        '''
+        """
         if s == '':
             return []
@@ -755 +754 @@
 
 class Literal(object):
-    '''
+    """
     Simple class to represent a literal token in the fetch response
     (eg. "{21}")
-    '''
+    """
 
     def __init__(self, length):
@@ -771 +770 @@
 
 def strict_finditer(regex, s):
-    '''Like re.finditer except the regex must match from exactly where the
+    """Like re.finditer except the regex must match from exactly where the
     previous match ended and all the entire input must be matched.
-    '''
+    """
     i = 0
     matched = False
@@ -791 +790 @@
 
 def messages_to_str(messages):
-    '''Convert a sequence of messages ids or a single message id into an
+    """Convert a sequence of messages ids or a single message id into an
     message ID list for use with IMAP commands.
 
@@ -797 +796 @@
         (eg. [1,4,5,7,8])
     @return: Message list string (eg. "1,4,5,6,8")
-    '''
+    """
     if isinstance(messages, (str, int, long)):
         messages = (messages,)
@@ -806 +805 @@
 
 def seq_to_parenlist(flags):
-    '''Convert a sequence into parenthised list for use with IMAP commands
+    """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)')
-    '''
+    """
     if isinstance(flags, str):
         flags = (flags,)
@@ -819 +818 @@
 
 def datetime_to_imap(dt):
-    '''Convert a datetime instance to a IMAP datetime string
+    """Convert a datetime instance to a IMAP datetime string
 
     If timezone information is missing the current system timezone is used.
-    '''
+    """
     if not dt.tzinfo:
         dt = dt.replace(tzinfo=FixedOffset.for_system())

imapclient/imapclient.py

@@ -15 +15 @@
 __all__ = ['IMAPClient', 'DELETED', 'SEEN', 'ANSWERED', 'FLAGGED', 'DRAFT',
     'RECENT']
+
+from response_parser import parse_fetch_response
 
 # System flags
@@ -327 +329 @@
 
         self._checkok('search', typ, data)
+        if data == [None]: # no untagged responses...
+            return []
 
         return [ long(i) for i in data[0].split() ]
@@ -436 +440 @@
         return parser(data)
 
+    def altfetch(self, messages, parts):
+        if not messages:
+            return {}
+
+        msg_list = messages_to_str(messages)
+        parts_list = seq_to_parenlist([p.upper() for p in parts])
+
+        if self.use_uid:
+            tag = self._imap._command('UID', 'FETCH', msg_list, parts_list)
+        else:
+            tag = self._imap._command('FETCH', msg_list, parts_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)
 
     def append(self, folder, msg, flags=(), msg_time=None):
@@ -800 +824 @@
     if not dt.tzinfo:
         dt = dt.replace(tzinfo=FixedOffset.for_system())
-
     return dt.strftime("%d-%b-%Y %H:%M:%S %z")
-    
-
+
+