Changeset 90:5ac3ccadb5fc

Timestamp:

12/18/09 17:17:30 (9 months ago)

Author:

Menno Smits <menno@…>

Branch:

default

Message:

use double quotes instead of single quotes in triple-quoted strings to keep Emacs happy

Location:

imapclient

Files:

• imapclient.py (modified) (46 diffs)
• test/test_FetchParser.py (modified) (6 diffs)

imapclient/imapclient.py

@@ -25 +25 @@
 
 class IMAPClient(object):
-    '''
+    """
     A Pythonic, easy-to-use IMAP client class.
 
@@ -57 +57 @@
     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
@@ -69 +69 @@
 
     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.
@@ -75 +75 @@
         @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
@@ -92 +92 @@
    
     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)
@@ -100 +100 @@
 
     def logout(self):
-        '''Perform a logout
-        '''
+        """Perform a logout
+        """
         typ, data = self._imap.logout()
         self._checkbye('logout', typ, data)
@@ -108 +108 @@
 
     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
@@ -129 +129 @@
 
     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)
@@ -145 +145 @@
 
     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
@@ -157 +157 @@
             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)
@@ -177 +177 @@
 
     def list_sub_folders(self, directory="", pattern="*"):
-        '''Get a listing of subscribed folders on the server.
+        """Get a listing of subscribed folders on the server.
 
         The default behaviour (no args) will list all subscribed folders for the
@@ -186 +186 @@
             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)
@@ -200 +200 @@
 
     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.
 
@@ -206 +206 @@
         @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)
@@ -213 +213 @@
 
     def folder_status(self, folder, what=None):
-        '''Requests the status from folder.
+        """Requests the status from folder.
 
         @param folder: The folder name.
@@ -221 +221 @@
             the items specified in the what parameter.
         @rtype: dict
-        '''
+        """
         if what is None:
             what = ('MESSAGES', 'RECENT', 'UIDNEXT', 'UIDVALIDITY', 'UNSEEN')
@@ -245 +245 @@
 
     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)
@@ -255 +255 @@
 
     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)
@@ -266 +266 @@
 
     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)
@@ -277 +277 @@
 
     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)
@@ -288 +288 @@
 
     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)
@@ -299 +299 @@
 
     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)
@@ -332 +332 @@
 
     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')
@@ -361 +361 @@
 
     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)
@@ -372 +372 @@
 
     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
@@ -378 +378 @@
         @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.
@@ -420 +420 @@
             INTERNALDATE parts will be returned as datetime objects converted
             to the local machine's time zone.
-        '''
+        """
         if not messages:
             return {}
@@ -438 +438 @@
 
     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.
@@ -451 +451 @@
         @return: The append response returned by the server.
         @rtype: str
-        '''
+        """
         if msg_time:
             time_val = '"%s"' % datetime_to_imap(msg_time)
@@ -473 +473 @@
 
     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)
@@ -491 +491 @@
 
     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.
@@ -497 +497 @@
         @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)
@@ -504 +504 @@
 
     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]))
@@ -521 +521 @@
 
     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')
@@ -528 +528 @@
         @return: The flags set for each message ID as a dictionary
             { msgid1: [flag1, flag2, ... ], }
-        '''
+        """
         if not messages:
             return {}
@@ -563 +563 @@
 
 class FetchParser(object):
-    '''
+    """
     Parse an IMAP FETCH response and convert the return values to useful Python
     values.
-    '''
+    """
 
     def parse(self, response):
@@ -634 +634 @@
 
     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)
@@ -669 +669 @@
 
 class FetchTokeniser(object):
-    '''
+    """
     General response tokenizer and converter
-    '''
+    """
 
     QUOTED_STRING = '(?:".*?")'
@@ -691 +691 @@
 
     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):
@@ -703 +703 @@
 
     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 []
@@ -731 +731 @@
 
 class Literal(object):
-    '''
+    """
     Simple class to represent a literal token in the fetch response
     (eg. "{21}")
-    '''
+    """
 
     def __init__(self, length):
@@ -747 +747 @@
 
 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
@@ -767 +767 @@
 
 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.
 
@@ -773 +773 @@
         (eg. [1,4,5,7,8])
     @return: Message list string (eg. "1,4,5,6,8")
-    '''
+    """
     if isinstance(messages, (str, int, long)):
         messages = (messages,)
@@ -782 +782 @@
 
 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,)
@@ -795 +795 @@
 
 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/test/test_FetchParser.py

@@ -3 +3 @@
 # Please see http://en.wikipedia.org/wiki/BSD_licenses
 
-'''
+"""
 Unit tests for the FetchTokeniser and FetchParser classes
-'''
+"""
 
 import unittest
@@ -94 +94 @@
 
     def testCharacterCase(self):
-        '''Test handling of varied case in the response type name
-        '''
+        """Test handling of varied case in the response type name
+        """
         self._parse_test(
             [r'2 (flaGS (\Deleted Foo \Seen))'],
@@ -131 +131 @@
 
     def testMultipleTypes(self):
-        '''Test multiple response types'''
+        """Test multiple response types"""
         self._parse_test(
             [r'2 (FLAGS (\Deleted Foo \Seen) INTERNALDATE " 9-Feb-2007 17:08:08 +0000")'],
@@ -144 +144 @@
 
     def testMultipleMessages(self):
-        '''Test with multple messages in the response
-        '''
+        """Test with multple messages in the response
+        """
         self._parse_test(
             [
@@ -158 +158 @@
 
     def testLiteral(self):
-        '''Test literal handling
-        '''
+        """Test literal handling
+        """
         self._parse_test(
             [('1 (RFC822 {21}', 'Subject: test\r\n\r\nbody'), ')'],
@@ -212 +212 @@
 
     def testUID(self):
-        '''Test UID handling. The UID is returned instead of the given message
+        """Test UID handling. The UID is returned instead of the given message
         ID if present.
-        '''
+        """
         self._parse_test(
             ['1 (UID 8)'],