Why tarfile.TarFile.gzopen is not in the online documentation?

[Baptiste Lepilleur]

2010/2/24 Lars Gustäbel <lars at gustaebel.de>

> On Wed, Feb 24, 2010 at 09:37:19AM +0100, Baptiste Lepilleur wrote:
> > I stumbled uppon this and find it somewhat odd: some class methods of
> > TarFile and TarInfo do not appears in either the online documentation or
> > search while they have a doc string:
> >
> > http://docs.python.org/search.html?q=gzopen
> >
> http://docs.python.org/library/tarfile.html?highlight=tarfile#tarfile.TarFile
> >
> > See script at the end for list of class methods.
> >
> > Is this "by design" or is there some an odd bug in doc generation lurking
> > around? This somehow seem to be specific to module tarfile. Fraction
> > classmethod from_float() is available in the documentation and found by a
> > search for example...
>
> First of all, Python's module documentation is not generated from module
> docstrings, each module has its own rst text file in the documentation tree
> instead.
>

I was ignorant of that fact. Thanks for letting me know.


> But to answer your question: Yes, this is intentional. The TarFile class
> has
> three classmethods taropen(), gzopen(), and bz2open() each for a specific
> compression method. These three are used internally by the TarFile.open()
> classmethod and are not intended to be called directly. The TarFile.open()
> method is the one that is publicly documented and supposed to be used. It
> decides which of the three methods to use based on the mode argument and
> does many more other high-level things as well.
>

I think it would be best to annotate the help string to let people know of
the facts it is not intended for public usage (or restriction that apply,
e.g. only for subclassing as you hinted in another post).

If I find a method using dir/doc string, I don't check the public
documentation to see if it is present. And even if I did, now that I know
that documentation is maintained separately from the code base, I would
rather assumes a documentation bug than this being by design as is the case
here.

Notes: googling around, there is already a few uses of TarFile.gzopen(). My
guess would be that people find it more convenient for passing compression
level.

Anyway, thanks for writing this module, it very easy to use!

Baptiste.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20100226/e6a056b5/attachment-0001.html>