pydoc vs. non-def'd methods

[Dan Sommers]

On Thu, 22 Aug 2013 06:39:48 +0000, Steven D'Aprano wrote:

> On Thu, 22 Aug 2013 05:13:03 +0000, Dan Sommers wrote:

>> class Spam1:
>> 
>>     def eggs(self):
>>         '''Return the Meaning of Life.'''
>>         return 42
>> 
>>     ham = eggs
>> 
>> 
>> help(Spam1) shows that ham = eggs(self), which isn't all bad, but it
>> could be better.  help(Spam1.ham) shows the help for eggs; I know
>> why, but this could be better as well.

> I'm not entirely sure how it could possibly be better. Since ham is
> just another name for eggs, it makes sense that they show the same
> docstring.

Yes, help(Spam1.eggs) and help(Spam1.ham) show the same docstring.
help(Spam1), however, doesn't show any docstring for ham; it shows that
ham = eggs(self).

>> And in any case, eggs looks somehow better than ham, because eggs has
>> its own def statement and ham doesn't.
> 
> I don't think I agree, but perhaps that's just an aesthetic judgement
> where we disagree.

Yep, just the aesthetics.

> class Spam:
>     def eggs(self):
>         """eggs docstring"""
>         return "ham and eggs"
>     def ham(self):
>         return self.eggs()
>     ham.__doc__ = eggs.__doc__.replace('eggs', 'ham')
> 
> This allows you two distinct docstrings, at the cost of duplicating
> the information in them. Spam.ham will be a *tiny* bit less efficient,
> due to the extra method call, but if you're worried about that, you're
> probably up to no good :-)

That I am up to no good goes without saying!  ;-)

> But really, I would find that a confusing API. I would wonder what
> subtle difference in semantics there was between ham and eggs. I would
> much prefer to see that ham was just an alias:
> 
> class Spam:
>     def eggs(self):
>         """eggs docstring"""
>         pass
>     ham = eggs
> 
> which brings us back to the beginning of your post :-)

Yeah, okay, I'll go with that, despite the asymmetry.  The names in
question are encrypt and decrypt, which for a stream cipher, are the
same.

Thanks, Steven, for confirming my ability to read the documentation and
play around in my interactive shell.  ;-)

And Thanks, Fábio, for your suggestions, too.

-- 
Dan