function v. method

[Bruno Desthuilliers]

Re: function v. method

Antoon Pardon wrote:

On 2006-07-21, fuzzylollipop <jarrod.roberso n@gmail.comwrot e:
>

>>Antoon Pardon wrote:
>>
>>

>>>Suppose I am writing my own module, I use an underscore, to
>>>mark variables which are an implementation detail for my
>>>module.
>>>
>>>Now I need to import an other module in my module and need access
>>>to an implementation variable from that module. So now I have
>>>variables with an underscore which have two different meanings:

>>
>>you don't understand what "implementa tion detail" means, it means it is
>>NOT part of the public API and no client code should ever use it.
>>
>>If you reference _vara in your code and it is in someone elses module
>>you don't understand YOU ARE NOT SUPPOSED TO DO THAT!

>
>
Why do you assume that in my example the other module is
not understood?

He doesn't, but it's clear that *you* didn't understand what
fuzzylollipop meant !-)

Hint : add a comma at the right place so parsing is unambigous:
"""
If you reference _vara in your code and it is in someone elses module,
you don't understand YOU ARE NOT SUPPOSED TO DO THAT!
"""

>

>> 1) This is an implemantation detail of this module, It is the
>> users of my module who have to be extra carefull using it.

>>
>>Users of your module should NEVER KNOW any of the _ or __ stuff exists
>>to begin with.
>>
>>

>> 2) This is an implemantation detail of the other module,
>> I should be extra carefull using it.

>>
>>You should NEVER use it.

>
>
Well that may be your view, but AFAICS it is not the view of
the python community. Because each time some mechanism is
proposed for real private variable, people oppose it, they
want people to have access to what are supposed to be
private variables.

I'd express it in a somewhat different way: the view of the Python
community is that language-inforced access restrictions are useless and
annoying, IOW an unnecessary pain. Which doesn't imply that messing with
implementation of other modules is actually *encouraged*. Having the
possibility to easily do so is quite handy when that's the only/less
worse solution, but is not a recommended approach in general.

--
bruno desthuilliers
python -c "print '@'.join(['.'.join([w[::-1] for w in p.split('.')]) for
p in 'onurb@xiludom. gro'.split('@')])"

[fuzzylollipop]

Re: function v. method


Gerhard Fiedler wrote:

On 2006-07-22 16:32:38, danielx wrote:
>

>>...and source code...
>>
>*shudders* What happened to all the goodness of abstraction?
>
Abstraction as you seem to use it requires complete docs of the interface.
Which is what you said you don't have... So the original abstractor broke
the abstraction when publishing insufficient docs, not the one who looks
into the sources to find out what actually happens.

Absolutely. I didn't mean the user was breaking abstraction (let's not
blame the victim). I was saying that we should really have more
sympathy for him.

>
I have all the sympathy in the world for him... after all, he's me :)
>
But one reason why I try to write (and insist on as much as possible from
people writing for or with me) self-documenting code is that wherever you
have documentation and code separated (which is the case of API docs), you
can bet (without losing) that sooner or later code and doc will diverge.
This has a probability that approaches 1 :)
>
So, I agree with you that good API docs are a good thing, as they tell me
everything I need to know without having to wade through tons of
implementation details that may be interesting but don't serve my immediate
need (of having to use the API). But reality seems to be (and mine so far
definitely is) that these docs, even the good ones, are not completely in
alignment with the reality of the code. (We all know that code has bugs...
and the API always describes, at best, how the code /should/ work. It never
describes how it actually works, including the bugs <g(this
notwithstanding the bugs that have been elevated to features and henceforth
been described in the API docs).
>
So... the final authority /is/ the code. I don't see an alternative. For
me, good abstraction doesn't mean I don't have to read the sources; good
abstraction means (among other things) that I can read the sources easily.
>
Gerhard

having auto generated docs, which means the documentatin is in the code
as doc strings, javadoc, reflex, or whatever format is the BEST way of
doing API documentation, period.

[fuzzylollipop]

Re: function v. method


Antoon Pardon wrote:

On 2006-07-21, fuzzylollipop <jarrod.roberso n@gmail.comwrot e:

Antoon Pardon wrote:

Suppose I am writing my own module, I use an underscore, to
mark variables which are an implementation detail for my
module.
>
Now I need to import an other module in my module and need access
to an implementation variable from that module. So now I have
variables with an underscore which have two different meanings:

you don't understand what "implementa tion detail" means, it means it is
NOT part of the public API and no client code should ever use it.

If you reference _vara in your code and it is in someone elses module
you don't understand YOU ARE NOT SUPPOSED TO DO THAT!

>
Why do you assume that in my example the other module is
not understood?
>

1) This is an implemantation detail of this module, It is the
users of my module who have to be extra carefull using it.

Users of your module should NEVER KNOW any of the _ or __ stuff exists
to begin with.

2) This is an implemantation detail of the other module,
I should be extra carefull using it.

You should NEVER use it.

>
Well that may be your view, but AFAICS it is not the view of
the python community. Because each time some mechanism is
proposed for real private variable, people oppose it, they
want people to have access to what are supposed to be
private variables.
>
--
Antoon Pardon

actually you are really way off base, the _ and __ convention IS the
INTENDED way of doing private and "really private" documentation of
members in Python.

I didn't make this up, it is in the official Python documentation.

You need to read my previous response for COMPREHENSION one more time.
There is LESS THAN ZERO value in having a runtime enforcement of member
access control.

Python does have ALREADY have an OFFICAL mechanism for private members,
prefix your names with _ or __. Both are ommited from autogenerated
docuementation and both are OFFICALLY not supposed to be used.

[Gerhard Fiedler]

Re: function v. method

On 2006-07-24 13:25:14, fuzzylollipop wrote:

>So... the final authority /is/ the code. I don't see an alternative. For
>me, good abstraction doesn't mean I don't have to read the sources; good
>abstraction means (among other things) that I can read the sources easily.

having auto generated docs, which means the documentatin is in the code
as doc strings, javadoc, reflex, or whatever format is the BEST way of
doing API documentation, period.

It may be the best way, no contest to that. But it still is not the code.
(I actually think that possibly the current way of embedding javadoc-like
documentation into sources is only a stepping stone into the direction
generally pointed to by what Wirth called "literate programming". In any
case, I'd rather not call it the "best way, period"; calling it the "best
currently widely supported way" seems more appropriate to me.)

Even doc strings tend to get out of sync with the code. And even doc
strings document (at best) what the code should do, not what it actually
does. And even doc strings are not always complete in describing the
functionality.

So auto generated docs are also incomplete and out of sync with the code,
sometimes more, sometimes less, sometimes so little that it is not
relevant. But you can't know how much out of sync they are from reading the
docs alone. So when push comes to shove (or so the saying goes? :), the
code is the authority. Even with auto generated docs. Period... ?!? <g>

Gerhard

[Gerhard Fiedler]

Re: function v. method

On 2006-07-24 14:41:02, Gerhard Fiedler wrote:

(I actually think that possibly the current way of embedding javadoc-like
documentation into sources is only a stepping stone into the direction
generally pointed to by what Wirth called "literate programming".

That was Knuth, not Wirth. But this is not really that relevant.

Gerhard

[Gerhard Fiedler]

Re: function v. method

On 2006-07-25 05:16:04, Wesley Brooks wrote:

>prefix your names with _ or __. Both are ommited from autogenerated
>docuementati on 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.)

Gerhard

[Alex Martelli]

Re: function v. method

Gerhard Fiedler <gelists@gmail. comwrote:

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.Queu e) nor on <http://docs.python.org/lib/QueueObjects.ht ml>,
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