IMAP examples

[Sean 'Shaleh' Perry]

>
> If my english was better I would love to help improve the python
> documentation, most modules in the standard libraries lack good
> examples how to *use* them with just a simple description.  And a
> short motivation for the design of a module if possible like "just
> copied the C API" or "Because of efficiency ..." or "We use a class
> framework here because ...".  A gigantic task.  The PSL book by effbot
> is great but it's a book.  And it needs a new version.

part of the reason why the docs are not but so great is that most of the 
library is Python code which means any questions can be answered by reading 
the source.  I find myself doing this quite often.

Many modules have a little blurb at the top that gives an example of their 
usage.

from imaplib.py:

    Instantiate with: IMAP4([host[, port]])

            host - host's name (default: localhost);
            port - port number (default: standard IMAP4 port).

    All IMAP4rev1 commands are supported by methods of the same
    name (in lower-case).

    All arguments to commands are converted to strings, except for
    AUTHENTICATE, and the last argument to APPEND which is passed as
    an IMAP4 literal.  If necessary (the string contains any
    non-printing characters or white-space and isn't enclosed with
    either parentheses or double quotes) each string is quoted.
    However, the 'password' argument to the LOGIN command is always
    quoted.  If you want to avoid having an argument string quoted
    (eg: the 'flags' argument to STORE) then enclose the string in
    parentheses (eg: "(\Deleted)").

    Each command returns a tuple: (type, [data, ...]) where 'type'
    is usually 'OK' or 'NO', and 'data' is either the text from the
    tagged response, or untagged results from command.