Re: IMAP examples

Discussion in 'Python' started by Will Stuyvesant, Jul 17, 2003.

  1. > [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.
    Will Stuyvesant, Jul 17, 2003
    #1
    1. Advertising

  2. Will Stuyvesant

    Van Gale Guest

    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
    Van Gale, Jul 17, 2003
    #2
    1. Advertising

  3. Will Stuyvesant

    Guyon Morée Guest

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

    thanx

    "Van Gale" <> wrote in message
    news:UWsRa.82$...
    > 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, Jul 17, 2003
    #3
  4. Sean 'Shaleh' Perry <> 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)
    James T. Dennis, Jul 18, 2003
    #4
  5. Will Stuyvesant

    Peter Hansen Guest

    "James T. Dennis" wrote:
    >
    > Sean 'Shaleh' Perry <> 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
    Peter Hansen, Jul 19, 2003
    #5
  6. Will Stuyvesant

    Donn Cave Guest

    In article <>,
    Peter Hansen <> wrote:

    > "James T. Dennis" wrote:
    > >
    > > Sean 'Shaleh' Perry <> 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 Cave, Jul 19, 2003
    #6
  7. Peter Hansen <> wrote:
    > "James T. Dennis" wrote:


    >> Sean 'Shaleh' Perry <> 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
    James T. Dennis, Jul 20, 2003
    #7
  8. Will Stuyvesant

    Guyon Morée Guest

    I vote for that to, it's a brilliant well-used system



    "James T. Dennis" <> schreef in bericht
    news:1058700676.64323@smirk...
    > Peter Hansen <> wrote:
    > > "James T. Dennis" wrote:

    >
    > >> Sean 'Shaleh' Perry <> 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, Jul 20, 2003
    #8
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Henrik Ormåsen

    Curier-IMAP and imap.create()

    Henrik Ormåsen, Aug 19, 2006, in forum: Ruby
    Replies:
    0
    Views:
    161
    Henrik Ormåsen
    Aug 19, 2006
  2. Jon Fi
    Replies:
    4
    Views:
    505
    Kashia Buch
    Oct 21, 2006
  3. jasonnaylor
    Replies:
    1
    Views:
    240
    jasonnaylor
    Apr 16, 2008
  4. Adam Akhtar
    Replies:
    1
    Views:
    162
    Eric Hodel
    Dec 15, 2008
  5. Abhishiv Saxena

    Support for IMAP IDLE in net/imap

    Abhishiv Saxena, Jul 3, 2009, in forum: Ruby
    Replies:
    4
    Views:
    185
    Eric Hodel
    Jul 4, 2009
Loading...

Share This Page