Terry Reedy
2/25/2010 6:32:00 PM
On 2/25/2010 11:51 AM, Lars Gustäbel wrote:
> 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.
If you intended for the *names* (if not the base methods themselves) to
be part of the public interface, then no underscores is appropriate. It
is a tough in-between case. I guess good docs, including doc stings, is
the best you can do to make the situation clear.
tjr