pydoc vs. non-def'd methods

[Fábio Santos]

On 22 Aug 2013 06:17, "Dan Sommers" <dan at tombstonezero.net> wrote:
>
> Greetings,
>
> I'm hava a class in which there are two equally useful names for one
> method.  Consider this design (there are other approaches, but that's
> not what my question is about):
>
> 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.  And in any case, eggs looks somehow
> better than ham, because eggs has its own def statement and ham doesn't.
>
> Now consider this design, designed to overcome the previous issues:
>
> class Spam2:
>
>     def _private(self):
>         '''Return the Meaning of Life.'''
>         return 42
>
>     ham = _private
>     eggs = _private
>
> Now help(Spam2.ham) and help(Spam2.eggs) show the same thing, but
> help(Spam2) hides _private and its docstring and shows that ham and eggs
> both call _private.  That's no good.  I can expose _private (e.g., by
> renaming it to public), but that defeats the purpose of making it
> private in the first place.  I can go ahead and define ham to invoke
> eggs, but then I have to duplicate the docstring, and it's not
> being-hit-on-the-head obvious that ham and eggs are simply synonyms for
> the same functionality.
>
> I could put the documentation at the class level, but then it doesn't
> show up as part of help(Spam2.eggs) or help(Spam1.ham).
>
> So is there a clean way to define SpamN such that help(SpamN),
> help(SpamN.ham), and help(SpamN.eggs) all do the Right Thing, and the
> symmetry of ham and eggs is perfectly obvious to the most casual
> observer?
>
> Thanks,
> Dan

If if one of them is the canonical method name, you could define the other
with a docstring indicating it is an alias for the other. If you don't want
to spend code lines you can just define a helper function for that. Heck,
you can even warn a DeprecationWarning if the alias is just backwards
compatibility.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20130822/33be64c8/attachment.html>