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

[Lars Gustäbel]

On Wed, Feb 24, 2010 at 04:29:18PM -0500, Terry Reedy wrote:
> 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:
>>
>> 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?

I hope that this is not necessary. There are quite a few TarFile methods
more that are not documented and don't start with an underscore. I don't think
renaming all these is a good idea.

The original intention behind these methods was that I wanted a lower level API for
TarFile that can be used for subclassing but stays as stable as possible at the
same time. Methods starting with underscores look very much like you can't make
use of them. I don't know if this was a particularly good idea back then and I
don't know how popular it is to subclass the TarFile class to customize it, but
we cannot simply change the methods' names at this point if we don't want to
break other people's code. In other words, the cure sounds worse than the
disease in my opinion.

-- 
Lars Gustäbel
lars at gustaebel.de

I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth.
(Umberto Eco)