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

[Terry Reedy]

On 2/24/2010 5:14 AM, Lars Gustäbel wrote:
> 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.
>
> 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.

By current standards, the three private methods should be prefixed with 
'_' to indicate their private status. Could they be changed to head off 
such questions?

Terry Jan Reedy