Changeset 221:c5912b9d2cf9

Timestamp:

17/04/11 11:33:16 (13 months ago)

Author:

Menno Smits <menno@…>

Branch:

default

Message:

Updated documentation and examples wrt IDLE support

Files:

• NEWS (modified) (1 diff)
• imapclient/examples/idle_example.py (modified) (2 diffs)
• imapclient/imapclient.py (modified) (3 diffs)

NEWS

@@ -11 +11 @@
 installed. Thanks to Johannes Heckel for contributing the patch to
 this.
+
+IDLE Support (#50) [NEW]
+------------------------
+The IDLE extension is now supported through the new idle(),
+idle_check() and idle_done() methods. See the example in
+imapclient/examples/idle_example.py.
 
 Small Bug Fixes

imapclient/examples/idle_example.py

@@ +1 @@
+# This example is a lot more interesting if you have an active client
+# connected to the same IMAP account!
+
 from imapclient import IMAPClient
-import time
 
 HOST = 'imap.host.com'
@@ -8 +10 @@
 
 server = IMAPClient(HOST, use_uid=True, ssl=ssl)
+server.login(USERNAME, PASSWORD)
+server.select_folder('INBOX')
 
-server.login(USERNAME, PASSWORD)
+# Start IDLE mode
+server.idle()     
 
-select_info = server.select_folder('INBOX')
-print select_info
-print
+# Wait for up to 30 seconds for an IDLE response
+responses = server.idle_check(timeout=30)
+print responses
 
-idling = True
-
-def callback(resp, arg):
-    global idling
-    
-    print "Something happened, or timeout was reached"
-    print
-    print "Callback response:"
-    print resp
-    print
-    print "The callback function received arg: ", arg
-    print
-    idling = False
-
-server.idle(timeout=5, callback=callback, cb_arg="Hello future self!")
-print "Began idling"
-
-while idling:
-    print "..still idling.."
-    time.sleep(1)
+# Come out of IDLE mode
+text, responses = server.idle_done()
+print 'IDLE done. Server said %r' % text
+print 'Final responses: ', responses
     
 print server.logout()

imapclient/imapclient.py

@@ -316 +316 @@
         """Put server into IDLE mode.
 
-        IDLE mode will end when the server notifies of a change, the server
-        reaches the timeout, or another IMAP4 command is scheduled.
-        
-        @param timeout: timeout for the IDLE command in seconds (default: 29 mins)
-        @param callback: Function to be called when IDLE mode ends. If a callback
-            is supplied the idle function will be asynchronous, returning immediately.
-        @param cb_arg: An optional argument that will be passed to the callback function.
-        @return: Server response. (None if callback is specified).
-
-        #XXX update documentation
-        #XXX what about finding out what the IDLE data was?
+        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')
@@ -334 +334 @@
 
     def idle_check(self, timeout=None):
-        """XXX
+        """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 (approximately) 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:
+
+        [(1, 'EXISTS'),
+         ('OK', 'Still here'), 
+         (1, 'FETCH', ('FLAGS', ('\NotJunk',))), 
+         (0, 'EXPUNGE')]
+
+        An attempt is made to group responses that were sent together
+        by the server by waiting for a little longer after the first
+        IDLE response is received.
         """
         timeouts = 0
         resps = []
         start_t = time.time()
-        def done():
-            if timeout is None:
-                if resps and timeouts > 1:
-                    return True
-            else:
-                if time.time() - start_t >= timeout:
-                    return True
-            return False
+
+        def blocking_done():
+            # Wait for one timed out read to try group IDLE responses
+            # that were sent together
+            return resps and timeouts > 1
+
+        if timeout is None:
+            done = blocking_done
+        else:
+            def done():
+                return blocking_done() or (time.time() - start_t >= timeout)
         
         # make the socket non-blocking so the timeout can be
@@ -364 +388 @@
 
     def idle_done(self):
-        """XXX
+        """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 data until the IDLE is done
+        # Slurp up any remaining IDLE responses until the IDLE is done
         tag = self._idle_tag
         tagged_commands = self._imap.tagged_commands