function v. method

[Alex Martelli]

Gerhard Fiedler <gelists at gmail.com> wrote:

> On 2006-07-25 05:16:04, Wesley Brooks wrote:
> 
> >> prefix your names with _ or __. Both are ommited from autogenerated
> >> docuementation and both are OFFICALLY not supposed to be used.
> >>
> > 
> > Could you elaborate on that a little or point me in the right direction to
> > read up on it? I'm currently re-writing a large lump of my coding and trying
> > to use best practice. I thought it was considered good practice to make
> > stuff private (in this case using __ ) that wasn't intened to be accessed
> > from outside the function/class?
> 
> I think fuzzylollipop meant that such members should not be used from the
> outside of the class; that is, they should be considered implementation,
> not API. (Which is why apparently autogenerated docs leave them out.)

Unfortunately, there is a slight ambiguity here.  Consider for example
the wonderful Queue class.  Its methods _put, _get are not documented in
help(Queue.Queue) nor on <http://docs.python.org/lib/QueueObjects.html>,
respecting the "private" convention.

But if you read Queue.py, you'll see...:

    # Override these methods to implement other queue organizations
    # (e.g. stack or priority queue).
    # These will only be called with appropriate locks held

    ...

    # Put a new item in the queue
    def _put(self, item):
       ...

etc -- i.e., Queue.py itself strongly appears to consider these methods
*protected* (in C++ parlance), NOT *private*.  Indeed, the only reason
these methods are factored out is exactly as "hook methods" (meant to be
overridden by subclasses), in a beautiful example of the "Template
Method" design pattern (in the specific variant in which the methods MAY
but DON'T HAVE TO be overridden, because the base class, Queue.Queue,
already provides them with useful functionality -- a LIFO queue).

Unfortunately Python does not have any specific naming convention to
indicate "methods that should never be CALLED by client code, but may be
usefully OVERRIDDEN in subclasses", so the leading-underscore one does
double duty -- and since the simpler interpretation "this is a private
implementation detail, ignore it completely" is so much more common than
the one about "this is a hook method which you should override in a
subclass if you want to tweak some detail of functionality", it's all
too easy to forget about the latter case (fortunately Queue.Queue is
there to remind us of it:-).


Alex