Changeset 248:bbef196a11da

Timestamp:

05/06/11 17:20:15 (12 months ago)

Author:

Menno Smits <menno@…>

Branch:

default

Message:

Remaining gaps in IMAPClient class docs done.

This is sufficient for an initial release

Files:

• doc-src/index.rst (modified) (1 diff)
• imapclient/imapclient.py (modified) (4 diffs)

doc-src/index.rst

@@ -111 +111 @@
 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-3501
+modified UTF-7 as specified by `RFC-3501 section 5.1.3
 <http://tools.ietf.org/html/rfc3501#section-5.1.3>`_.  This allows for
 arbitrary unicode characters (eg. non-English characters) to be used

imapclient/imapclient.py

@@ -134 +134 @@
         """Return 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().
+        .. warning::
+
+            The implementation just picks the first folder separator
+            from the first namespace returned. This is not
+            particularly sensible. Use namespace instead().
         """
         warnings.warn(DeprecationWarning('get_folder_delimiter is going away. Use namespace() instead.'))
@@ -344 +346 @@
         """Return a list of messages ids matching *criteria*.
 
-        XXX more detail
+        *criteria* should be a list of of one or more criteria
+        specifications or a single critera string. Example values
+        include::
+
+             'NOT DELETED'
+             'UNSEEN'
+             'SINCE 1-Feb-2011'
+
+        *charset* specifies the character set of the strings in the
+        criteria. It defaults to US-ASCII.
+
+        See `RFC-3501 section 6.4.4 <http://tools.ietf.org/html/rfc3501#section-6.4.4>`_
+        for more details.
         """
         if not criteria:
@@ -369 +383 @@
 
 
-    def sort(self, sort_criteria, criteria='ALL', charset='UTF-8' ):
+    def sort(self, sort_criteria, criteria='ALL', charset='UTF-8'):
         """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
+        Example values for *sort_criteria* include::
+
+            ARRIVAL
+            REVERSE SIZE
+            SUBJECT
+
+        The *criteria* argument is as per search(). 
+        See `RFC-5256 <http://tools.ietf.org/html/rfc5256>`_ for full details.
+
+        Note that SORT is an extension to the IMAP4 standard so it may
+        not be supported by all IMAP servers.
         """
         if not criteria:
@@ -401 +419 @@
         self._checkok('sort', typ, data)
 
-        return [ long(i) for i in data[0].split() ]
+        return [long(i) for i in data[0].split()]
 
 
     def get_flags(self, messages):
-        """Returns the flags set for each message in *messages* as a
-        dictionary structured like this:
-          ``{ msgid1: [flag1, flag2, ... ], }``.
+        """Return the flags set for each message in *messages*.
+
+        The return value is a dictionary structured like this: ``{
+        msgid1: [flag1, flag2, ... ], }``.
         """
         response = self.fetch(messages, ['FLAGS'])