IMAP examples

[James T. Dennis]

Sean 'Shaleh' Perry <shalehperry at comcast.net> wrote:

>> 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.

 <flame>That's BS!</flame>

 As a dabbler in programming I have to say that poor documentation is not
 excused by the availability of sources.  If the sources are that 
 informative than relevant portions should be pasted into the docs
 (or, better, marked up in some way that a doc generator and extract
 them into the officials docs).

 If the docs need to refer to the sources so often, perhaps we should
 re-write the docs so that every page has hyperlink references to the 
 relevant source modules.  Making someone manually hunt down information 
 from alternative sources is a great way to frustrate them!

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

 Sounds like a job for doc strings.  Moreover it sounds like a job
 for an automated docstring processing (http://docutils.sourceforge.net/ 
 perhaps?)

> 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).

 More importantly this module *does* give a 10 line code example: 

   http://www.python.org/doc/current/lib/imap4-example.html

 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()

 Okay, now I go back to another page and read about the .search() and
 .fetch() methods.  Hmmm, .fetch() lists UID and BODY, no reference to 
 RFC822 and not hint as to where I'd find any other valid strings here;
 I guess I have to go read the IMAP RFCs, where are those?  Ooops, another
 trip to Google!

 <flame mode="rant" context="off">Google would be so necessary if 
 HTML authors would link to other relevant sources!</flame>

 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!  (Putting a copy
 on our own servers to ensure a stable URL is Okay).

 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!)

 I'm only picking on this particular page because you brought it up.
 Actually it's one of the better pages because it does include an 
 example.  The pty module is one of the worst.  Pipe in if you were
 able to use the pty module just from the docs!

 Python includes the broadest wealth of modules I've never seen in a 
 programming language.  Docstrings are a stroke of pure genius.  The
 interpreter's readline and rlcompleter support is wonderful for beginners
 and dabblers --- and rlcompleter2 is EVEN BETTER (Guido --- please 
 merge that! :) ).  The docs are Okay --- but could be ALOT better.

 I'd love to see a way for members of the community (even duffers and dabblers 
 like me) to submit doc enhancement suggestions and requests directly through
 the online HTML documentation (similar to the PHP system at: 
 http://www.php.net/docs.php).  Of course more well-known, trusted members
 of the community should have the power to editing, revise, even throw out
 comments. 

 One danger I see in __doc__ is the various ways in which they are being
 overloaded.  doctest seems reasonable; a small sample usage that also 
 serves as an automated test suite.  (Yes, I have read the little Soapbox
 note at: http://www.python.org/doc/current/lib/node130.html) However 
 some of the programming by contract (http://www.wayforward.net/pycontract/ ) 
 starts to worry me.  

 How will doctest and pycontract play together?  How will docutils
 handle the results?  What will be the next clever uses of __doc__
 members?  How will it mesh with all the other uses?  It sounds
 like one might very reasonably argue that these other uses should
 have their own standards (or conventions) with their own namespaces:
 __testsuite__ and __contract__ (or __pre-condition__, __post-condition__,
 and __invariants__), for example.

 (Even that use is *almost* documentation so I can stretch a little to 
 see it --- and it is a nice hack.  However, if something like pycontract 
 is ever accepted into the standard libraries, I'd suggest it be given
 it's own __ namespace)