Re: Why tarfile.TarFile.gzopen is not in the online documentation?
Lars Gustäbel
> 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.
Regards,
--
Lars Gust�bel
la...@gustaebel.de
I do not care to belong to a club that
accepts people like me as members.
(Groucho Marx)
Terry Reedy
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
Lars Gustäbel
> 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:
>>
>> 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
la...@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)
Terry Reedy
> On Wed, Feb 24, 2010 at 04:29:18PM -0500, Terry Reedy 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
Lars Gustäbel
> 2010/2/24 Lars Gust�bel <la...@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:
> > >
> > 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.
> >
>
> the facts it is not intended for public usage (or restriction that apply,
> e.g. only for subclassing as you hinted in another post).
Well, then please take the time and open an issue at bugs.python.org, so
that this won't get lost. I will then see what I can do.
--
Lars Gust�bel
la...@gustaebel.de
Linux is like a wigwam - no Gates, no Windows, Apache inside.