Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!news.mixmin.net!aioe.org!news.stack.nl!newsfeed.xs4all.nl!newsfeed1.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail Return-Path: X-Original-To: python-list@python.org Delivered-To: python-list@mail.python.org X-Spam-Status: OK 0.018 X-Spam-Evidence: '*H*': 0.96; '*S*': 0.00; 'duplicate': 0.07; 'indicating': 0.07; 'level,': 0.07; 'method.': 0.07; 'alias': 0.09; 'dan': 0.09; 'warn': 0.09; 'cc:addr:python-list': 0.11; 'def': 0.12; '(there': 0.16; 'backwards': 0.16; 'docstring': 0.16; 'hides': 0.16; 'renaming': 0.16; 'subject:def': 0.16; 'subject:non': 0.16; 'why,': 0.16; 'thanks,': 0.17; 'wrote:': 0.18; 'aug': 0.22; 'cc:addr:python.org': 0.22; 'helper': 0.24; 'looks': 0.24; 'question': 0.24; 'cc:2**0': 0.24; 'cc:no real name:2**0': 0.24; '>': 0.26; 'define': 0.26; 'header:In-Reply- To:1': 0.27; 'function': 0.29; "doesn't": 0.30; 'statement': 0.30; 'message-id:@mail.gmail.com': 0.30; "i'm": 0.30; 'code': 0.31; 'lines': 0.31; 'that.': 0.31; 'invoke': 0.31; 'class': 0.32; 'skip:_ 10': 0.34; 'could': 0.34; 'case,': 0.35; 'good.': 0.35; 'but': 0.35; 'received:google.com': 0.35; 'there': 0.35; '(e.g.,': 0.36; 'method': 0.36; 'shows': 0.36; 'useful': 0.36; 'two': 0.37; 'ahead': 0.38; 'previous': 0.38; '8bit%:6': 0.40; 'even': 0.60; 'most': 0.60; 'simply': 0.61; 'first': 0.61; 'making': 0.63; 'show': 0.63; 'such': 0.63; 'design,': 0.64; 'subject:. ': 0.67; 'obvious': 0.74; 'overcome': 0.74; 'other.': 0.75; 'approaches,': 0.84; 'expose': 0.84; 'issues:': 0.84; 'canonical': 0.91; 'thing,': 0.91; '2013': 0.98 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=Bn1FGX56wFKc5cL9IuSwnblfeWNFaoKpBj4zvzGM5J0=; b=PKGaH5fTvjSeAv6Dl+DVaSsNgho/AS8AzLri4RGLtzbV3Xq6rzIUJu7/CyM392CnD3 K3OagUxrgIbg3bN8wxVENTZ3m8yHnd3876DYzDhaMy2xGtNCgohiwRW9nXnvwX+eoV+I GfT6iQLtsQx9eORggei7aoUCexM3YsFA19ZyLmM/eN9UkkaEX9Hf8oV0+F9uUUzMpv2r opw7R9uig9jNCmUrLayDx2XIkKJcN2Ptw/YvNnMhEmY9mqat90+WjbHeyJ2s5+iQgmvj Rq/O5A9AZsZyDe48iUFDgSNyAS9xSPpZfBzhGU7Pu6PPL0mKMwLL0qy+l8MGzuQQhpzu katQ== MIME-Version: 1.0 X-Received: by 10.52.165.45 with SMTP id yv13mr8935230vdb.1.1377162633955; Thu, 22 Aug 2013 02:10:33 -0700 (PDT) In-Reply-To: References: Date: Thu, 22 Aug 2013 10:10:33 +0100 Subject: Re: pydoc vs. non-def'd methods From: =?ISO-8859-1?Q?F=E1bio_Santos?= To: Dan Sommers Content-Type: multipart/alternative; boundary=001a11c20802984e2404e485a9fc Cc: python-list@python.org X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: General discussion list for the Python programming language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 141 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1377162643 news.xs4all.nl 15916 [2001:888:2000:d::a6]:50191 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:52825 --001a11c20802984e2404e485a9fc Content-Type: text/plain; charset=ISO-8859-1 On 22 Aug 2013 06:17, "Dan Sommers" 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. --001a11c20802984e2404e485a9fc Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable


On 22 Aug 2013 06:17, "Dan Sommers" <dan@tombstonezero.net> wrote:
>
> Greetings,
>
> I'm hava a class in which there are two equally useful names for o= ne
> method. =A0Consider this design (there are other approaches, but that&= #39;s
> not what my question is about):
>
> class Spam1:
>
> =A0 =A0 def eggs(self):
> =A0 =A0 =A0 =A0 '''Return the Meaning of Life.''&#= 39;
> =A0 =A0 =A0 =A0 return 42
>
> =A0 =A0 ham =3D eggs
>
> help(Spam1) shows that ham =3D eggs(self), which isn't all bad, bu= t it
> could be better. =A0help(Spam1.ham) shows the help for eggs; I know wh= y,
> but this could be better as well. =A0And in any case, eggs looks someh= ow
> better than ham, because eggs has its own def statement and ham doesn&= #39;t.
>
> Now consider this design, designed to overcome the previous issues: >
> class Spam2:
>
> =A0 =A0 def _private(self):
> =A0 =A0 =A0 =A0 '''Return the Meaning of Life.''&#= 39;
> =A0 =A0 =A0 =A0 return 42
>
> =A0 =A0 ham =3D _private
> =A0 =A0 eggs =3D _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 eg= gs
> both call _private. =A0That's no good. =A0I can expose _private (e= .g., by
> renaming it to public), but that defeats the purpose of making it
> private in the first place. =A0I 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 fo= r
> the same functionality.
>
> I could put the documentation at the class level, but then it doesn= 9;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<= br> > 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 de= fine 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 functi= on for that. Heck, you can even warn a DeprecationWarning if the alias is j= ust backwards compatibility.

--001a11c20802984e2404e485a9fc--