bz2 module

[Raymond Hettinger]

[Alex Martelli]
> > > If the docs were perfect, who'd ever buy Python in a Nutshell, or the
> > > Python Cookbook?  So I sneak in at night in the CVS repository and
> > > secretly sabotage them just enough, destroying, without leaving a trace,
> > > all the wonderful doc patches that people are submitting all the time,
> > > fixing problems rather than whining about them...
 . . .
> I'm not comfortable with the library
> *reference* being full of examples; I think it should probably be split
> into a reference (a real one) and a collection of how-to/tutorials (with
> the examples).  So, I've submitted doc pathes for correction of errors,
> omissions, imperfect or ambiguous phrasing, etc, but not ones for the
> addition of examples.

As a countermeaure for Alex secretly sabotaging doc patches, I've been
waging a counter campaign to put *more* examples in the reference ;-)

While Alex wasn't looking, I added the "Basic Example" for the
unittest docs.  Now, it's possible to get some immediate benefit from
the module without reading the other seven sections or buying Alex's
wonderful books.

The new decimal module has a "Quick Start" section, the itertools
module has both examples and recipes, and now even the tutorial has
two new chapters chuck full of examples covering a swath of the
Standard Library.

Still more valiant efforts are needed.  Currently, only his book
effectively documents the __new__ method and shows how to use
meta-classes.  When his guard is down, *someone* should sneak in a doc
patch.  Unless we all contribute, Alex's superb books will continue to
be must haves.


Raymond


P.S.  Remember, this Alex character is dastardly.  You may have to
resort to slippery measures.  For goodness sake, don't let him find
out about all the superb examples carefully hidden in
Lib/test/test_generators.py ;-)