Changeset 250:1fdb2f77fb2a

Timestamp:

05/06/11 17:45:04 (12 months ago)

Author:

Menno Smits <menno@…>

Branch:

default

Message:

Fixed up documentation for recently added functionality

Files:

• imapclient/imapclient.py (modified) (7 diffs)

imapclient/imapclient.py

@@ -66 +66 @@
     If *ssl* is ``True`` an SSL connection will be made (defaults to
     ``False``).
+
+    The *debug* property can be used to enable debug logging. It can
+    be set to an integer from 0 to 5 where 0 disables debug output and
+    5 enables full output with wire logging and parsing logs. ``True``
+    and ``False`` can also be assigned where ``True`` sets debug level
+    4.
+
+    By default, debug output goes to stderr. The *log_file* attribute
+    can be assigned to an alternate file handle for writing debug
+    output to.
     """
 
@@ -105 +115 @@
     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').
+        """Authenticate using the OAUTH method.
+
+        This only works with IMAP servers that support OAUTH (eg. Gmail).
         """
         if oauth2:
@@ -162 +168 @@
         *shared*.
 
-        See RFC 2342 for more details.
+        See `RFC-2342 <http://tools.ietf.org/html/rfc2342>`_ for more details.
         """
         typ, data = self._imap.namespace()
@@ -303 +309 @@
 
     def idle(self):
-        """Put server into IDLE mode.
+        """Put the 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
+        about changes to the selected mailbox. This method returns
+        immediately. Use ``idle_check()`` to look 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 <http://tools.ietf.org/html/rfc2177>`_ for more
+        information about the IDLE extension.
         """
         self._idle_tag = self._imap._command('IDLE')
@@ -326 +333 @@
 
         This method should only be called if the server is in IDLE
-        mode (see 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.
+        received. If *timeout* is provided, the call will block for at
+        most this many 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',)))]
+        example::
+
+            [('OK', 'Still here'),
+             (1, 'EXISTS'),
+             (1, 'FETCH', ('FLAGS', ('\\NotJunk',)))]
         """
         # make the socket non-blocking so the timeout can be
@@ -365 +372 @@
         """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().
+        This method should only be called if the server is already in
+        IDLE mode.
+
+        The return value is of the form ``(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')
@@ -788 +797 @@
         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.")
+    debug = property(__debug_get, __debug_set)
 
     def _log(self, text):