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
--
http://mail.python.org/mailman/listinfo/python-list
