IMAP examples

[Tony Meyer]

>  It would be nice if it also explained some of the magic numbers 
>  and strings in comments or in some text around the example: 
> 
> 	Why data[0]
> 	Why M.search(None, 'ALL')
> 	and why '(RFC822)' as the 2nd arg in the M.fetch()

You're not asking for documentation about imaplib here, you're asking for
documentation about the imap protocol; of course it's not there, you're
looking in the wrong place.  If you don't understand imap, why should you
understand how to use imaplib?

Using imaplib is very similar to simply passing the commands to an imap
server - much more so, for example, than twisted's imap support (which hides
details of IMAP, and so should provide more documentation than imaplib).

>  If we expect people to read the RFCs in order to use the 
> bloody module  than we ought to at least provide the link to 
> the RFC!

What documentation are you looking at?  The 2.2.3 and 2.3b2 doc for imaplib
(i.e. "11.10 imaplib -- IMAP4 protocol client") have links to both RFC2060
and RFC1730; I use them all the time.  Look in the first and second
sentences in the bit just below the heading.

>  The documentation of the .search() method also neglects to 
> make any  mention of 'ALL' though we might expect that to be 
> the MOST COMMON CRITERIUM!  (at least for someone who's just
> trying to learn the module!)

There is no reason that 'ALL' would be any more use than any other fetch
parameter.  In fact, if you're learning imap, then ALL is a terrible place
to start because you'll be overwhelmed with the response, and because ALL is
a macro, not a standard parameter.  You're much better off starting with
something simple, like UID, FLAGS, INTERNALDATE or RFC822.

=Tony Meyer