[Python-Dev] Unit testing (again)

[Tim Peters]

[Thomas Wouters]
> ...
> I think what's missing is a library *tutorial*.

How would that differ from the effbot guide (to the std library)?  The
Python (language) Tutorial can be pretty small, because the Python language
is pretty small.  But the libraries are massive, and growing, and are
increasingly in the hands of people with no Unix experience, or even
programming experience.  So I suppose "tutorial" can mean many things.

> The reference is exactly that, a reference,

In part.  In other parts (a good example is the profile docs) it's a lot of
everything; in others it's so much "a reference" you can't figure out what
it's saying unless you study the code (the pre-2.1 "random" docs sure come
to mind).  It's no more consistent in content level than anything else with
umpteen authors.

> and if we expand the reference we'll end up cursing it ourself,
> should we ever need it.

If the people who wanted "just a reference" were happy, I don't think David
Beazley would have found an audience for his "Python Essential Reference".

I can't argue about this, though, because nobody will ever agree.  Guido
doesn't want leisurely docs in the Reference Manual, nor does he like
leisurely docs in docstrings.  OTOH, those are what average and sub-average
programmers *need*, and I write docs for them first, sneaking in examples
when possible that I hope even experts will find pleasure in pondering.

A good compromise by my lights-- and perhaps because I only care about the
HTML docs, where "size" isn't apparent or a problem for navigation --would
be to follow a terse but accurate reference with as many subsections as felt
needed, with examples and rationale and tutorial material (has anyone ever
figured how to use rexec or bastion from the docs?  heh).

But since nobody will agree with that either, I stick everything into
docstrings and leave it to Fred to throw away the most useful parts for the
"real docs" <wink>.

> ...
> I remember when I'd finished the Python tutorial and wondered where to
> go next. I tried reading the library reference, but it was boring and
> most of it not interesting (since it isn't built up to go from
> seful/common -> rare, but just a list of all modules ordered by
> service'.)

Excellent point!  I had the same question when I first learned Python, but
at that time the libraries were maybe 10% of what's there now.  I *still*
didn't know where to go next.  But I was pretty sure I didn't need the SGI
multimedia libraries that occupied half the docs <wink>.

> ...
> I'll write the library tutorial once I finish the 'from-foo-import-*
> considered harmful' chapter ;-)

Hmm.  Feel free to finish the listcomp PEP too <wink>.