<div class="gmail_quote">2010/2/24 Lars Gustäbel <span dir="ltr"><<a href="mailto:lars@gustaebel.de">lars@gustaebel.de</a>></span><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">

<div class="im">On Wed, Feb 24, 2010 at 09:37:19AM +0100, Baptiste Lepilleur wrote:<br>
> I stumbled uppon this and find it somewhat odd: some class methods of<br>
> TarFile and TarInfo do not appears in either the online documentation or<br>
> search while they have a doc string:<br>
><br>
> <a href="http://docs.python.org/search.html?q=gzopen" target="_blank">http://docs.python.org/search.html?q=gzopen</a><br>
> <a href="http://docs.python.org/library/tarfile.html?highlight=tarfile#tarfile.TarFile" target="_blank">http://docs.python.org/library/tarfile.html?highlight=tarfile#tarfile.TarFile</a><br>
><br>
> See script at the end for list of class methods.<br>
><br>
> Is this "by design" or is there some an odd bug in doc generation lurking<br>
> around? This somehow seem to be specific to module tarfile. Fraction<br>
> classmethod from_float() is available in the documentation and found by a<br>
> search for example...<br>
<br>
</div>First of all, Python's module documentation is not generated from module<br>
docstrings, each module has its own rst text file in the documentation tree<br>
instead.<br></blockquote><div><br>I was ignorant of that fact. Thanks for letting me know. <br> </div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">



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

<br>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.<br>

<br>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.<br><br>Anyway, thanks for writing this module, it very easy to use!<br>

<br>Baptiste. <br></div><br></div><br>