Velocity Reviews

Velocity Reviews (http://www.velocityreviews.com/forums/index.php)
-   Python (http://www.velocityreviews.com/forums/f43-python.html)
-   -   Re: IMAP examples (http://www.velocityreviews.com/forums/t319804-re-imap-examples.html)

Will Stuyvesant 07-17-2003 06:03 AM

Re: IMAP examples
 
> [Guyon Morée]
> I can't seem to find any decent examples on how to use the IMPALIB module.
> the docs aren't that sophisticated unfortunately.... the cookbook entry
> comes close, but i'd like to know if someone knows some nice examples
> somewhere.


I did not use it myself but there is an example in the book "Python
Standard Library" by Fredrik Lundh. The example file is called
imaplib-example-1.py, maybe you can find it somewhere on the internet.

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.

Van Gale 07-17-2003 08:15 AM

Re: IMAP examples
 
Will Stuyvesant wrote:
>>[Guyon Morée]
>>I can't seem to find any decent examples on how to use the IMPALIB module.
>>the docs aren't that sophisticated unfortunately.... the cookbook entry
>>comes close, but i'd like to know if someone knows some nice examples
>>somewhere.

>
>
> I did not use it myself but there is an example in the book "Python
> Standard Library" by Fredrik Lundh. The example file is called
> imaplib-example-1.py, maybe you can find it somewhere on the internet.


Fredrik has graciously made the book available online.

See: http://effbot.org/zone/librarybook-index.htm


Guyon Morée 07-17-2003 08:57 AM

Re: IMAP examples
 
wow, that's cool, not sure if it is what I was looking, but this book seems
pretty invaluable already :)

thanx

"Van Gale" <news@exultants.org> wrote in message
news:UWsRa.82$O94.42@newssvr24.news.prodigy.com...
> Will Stuyvesant wrote:
> >>[Guyon Morée]
> >>I can't seem to find any decent examples on how to use the IMPALIB

module.
> >>the docs aren't that sophisticated unfortunately.... the cookbook entry
> >>comes close, but i'd like to know if someone knows some nice examples
> >>somewhere.

> >
> >
> > I did not use it myself but there is an example in the book "Python
> > Standard Library" by Fredrik Lundh. The example file is called
> > imaplib-example-1.py, maybe you can find it somewhere on the internet.

>
> Fredrik has graciously made the book available online.
>
> See: http://effbot.org/zone/librarybook-index.htm
>




James T. Dennis 07-18-2003 08:50 PM

Re: IMAP examples
 
Sean 'Shaleh' Perry <shalehperry@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/li...4-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)


Peter Hansen 07-18-2003 11:12 PM

Re: IMAP examples
 
"James T. Dennis" wrote:
>
> Sean 'Shaleh' Perry <shalehperry@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.


True, but poor documentation *is* excused quite nicely by the LACK
of availability of _re_sources, specifically the human resources and time
required to make them better.

Or was your flame an indirect offer to assist with improving the
documentation of Python? If so, thank you!

(It's not like you've paid anything for the privilege of whining...)

-Peter

Donn Cave 07-18-2003 11:52 PM

Re: IMAP examples
 
In article <3F187ED4.6179CDDD@engcorp.com>,
Peter Hansen <peter@engcorp.com> wrote:

> "James T. Dennis" wrote:
> >
> > Sean 'Shaleh' Perry <shalehperry@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.

>
> True, but poor documentation *is* excused quite nicely by the LACK
> of availability of _re_sources, specifically the human resources and time
> required to make them better.
>
> Or was your flame an indirect offer to assist with improving the
> documentation of Python? If so, thank you!


Well, he did offer some suggestions, which is about all most of
us do around here. But I don't think I'd go along with the premise
as easily as you did - I mean, ``poor documentation is not excused
by the availability of source'' is true as far as it goes, but in
some cases I think ``source is good documentation'' can be true, too.

And in this specific case. IMAP4 support is a can of worms. Big
feature set here, baroque might be the word. Not trivial to parse.
The imaplib solution is minimal. It does a reasonable job setting
up an imap service connection and conducting a client/server dialogue,
but it doesn't get into the structure or significance of the data.
If you want to use IMAP, the documentation you need to read is the
RFC, unfortunately but it is a reasonable discussion of the protocol.

imaplib.__doc__ points to imaplib.IMAP4; imaplib.IMAP4.__doc__ is
30 or 40 lines of concise information about the API. I don't think
this is a crisis situation.

Donn Cave, donn@u.washington.edu

James T. Dennis 07-20-2003 11:31 AM

Re: IMAP examples
 
Peter Hansen <peter@engcorp.com> wrote:
> "James T. Dennis" wrote:


>> Sean 'Shaleh' Perry <shalehperry@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.


> True, but poor documentation *is* excused quite nicely by the LACK
> of availability of _re_sources, specifically the human resources and time
> required to make them better.


> Or was your flame an indirect offer to assist with improving the
> documentation of Python? If so, thank you!


> (It's not like you've paid anything for the privilege of whining...)


> -Peter


Yes. Moreover my suggestion for an enhancement to the web site
docs would be a way to facilitate that. Go look at the PHP
documentation. Anyone reading it can attach comments; those can be
merged into the docs as appropriate.



--
Jim Dennis,
Starshine: Signed, Sealed, Delivered


Guyon Morée 07-20-2003 10:50 PM

Re: IMAP examples
 
I vote for that to, it's a brilliant well-used system



"James T. Dennis" <jadestar@idiom.com> schreef in bericht
news:1058700676.64323@smirk...
> Peter Hansen <peter@engcorp.com> wrote:
> > "James T. Dennis" wrote:

>
> >> Sean 'Shaleh' Perry <shalehperry@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.

>
> > True, but poor documentation *is* excused quite nicely by the LACK
> > of availability of _re_sources, specifically the human resources and

time
> > required to make them better.

>
> > Or was your flame an indirect offer to assist with improving the
> > documentation of Python? If so, thank you!

>
> > (It's not like you've paid anything for the privilege of whining...)

>
> > -Peter

>
> Yes. Moreover my suggestion for an enhancement to the web site
> docs would be a way to facilitate that. Go look at the PHP
> documentation. Anyone reading it can attach comments; those can be
> merged into the docs as appropriate.
>
>
>
> --
> Jim Dennis,
> Starshine: Signed, Sealed, Delivered
>





All times are GMT. The time now is 04:32 PM.

Powered by vBulletin®. Copyright ©2000 - 2014, vBulletin Solutions, Inc.
SEO by vBSEO ©2010, Crawlability, Inc.