[Tutor] Documentation concerns. [example:__builtins__.zip, __builtins__.dict]

[Danny Yoo]

On Fri, 23 May 2003, Paul Tremblay wrote:

> >
> > Magnus Lyck=E5 <magnus@thinkware.se> writes:
> >
> > > Perhaps the Python documentation needs to contain even more
> > > suggestions to try out and experiment with features.
> >
> > IMHO it would benefit a lot of examples.


Hmmm...


I think we can attack this problem of missing examples: how about whenever
we write a short example for a module function, that we add a small tag on
the subject line of our emails, like [example:cgi] or
[example:MySQLdb.connect]?


We can then later cull these out from the rest of the Tutor archive by
doing a simple regex search based on the subject line, fix them up to be
more presentable, and then send them over to the doc folks.  Doing this
manually might be a pain, but we can write software to help us do this.



For example, here's a small snippet that shows one way of playing with
dict() and zip() to quickly create a set of items:

###
STOP_WORDS =3D """
NOT
NULL
NONE
AIM
MIN
A
DID
IT
PERHAPS
THESE
ABOUT
DO
ITS
QUITE
THEY
AGAIN
DOES
ITSELF
RATHER
""".split()

def make_dictionary_from_words(words):
    return dict(zip(words, [1] * len(words)))

word_dict =3D make_dictionary_from_words(STOP_WORDS)
###


Actually, this is more of a cute trick that will become obsolete as soon
as real Sets come through Python 2.3, but it still shows where zip() can
be useful in combination with dict().



Anyway, the idea of writing some software to conveniently data mine the
whole Tutor archive at:

    http://mail.python.org/pipermail/tutor/


sounds very seductive!  *grin* We've got a lot of stored content in here;
we just need to make it easier to make it more accessible.


So if we find ourselves writing a small snippet of code that demonstrates
the use of a function or class, perhaps tagging our subject lines with a
short identifier like [example:foo] will help people out.


Any thoughts on this?