Path: csiph.com!fu-berlin.de!uni-berlin.de!not-for-mail
From: Ian Kelly <ian.g.kelly@gmail.com>
Newsgroups: comp.lang.python
Subject: Re: Meta decorator with parameters, defined in explicit functions
Date: Sun, 3 Jul 2016 05:52:47 -0600
Lines: 46
Message-ID: <mailman.38.1467546815.2295.python-list@python.org>
References: <85mvm5vrbw.fsf@benfinney.id.au> <mailman.61.1467090177.2358.python-list@python.org> <21916e7b-9e19-4cef-94e0-bac331540ca2@googlegroups.com> <CALwzidn8DuSo-L2UQTJ7wZfzK+eHGzgGuy_ZfHFR9v4J_NHnjQ@mail.gmail.com> <mailman.15.1467436194.2295.python-list@python.org> <facf7142-25f5-4a8b-ab37-771884ab8d64@googlegroups.com> <CALwzid=GfLU8nbc5m4M9FxEO1ObWDTcvLJ3-wJXS0=w88-v8sw@mail.gmail.com> <mailman.33.1467521333.2295.python-list@python.org> <46690e10-1534-4f99-a40f-a148b4a21a27@googlegroups.com> <CALwzidmn-0TyxfKxcZoNoV5CgiFuOqRS_X=W34gSn5a-NVOy_w@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
In-Reply-To: <46690e10-1534-4f99-a40f-a148b4a21a27@googlegroups.com>
Precedence: list
Xref: csiph.com comp.lang.python:110992

On Sat, Jul 2, 2016 at 11:37 PM, Lawrence D=E2=80=99Oliveiro
<lawrencedo99@gmail.com> wrote:
> On Sunday, July 3, 2016 at 4:49:15 PM UTC+12, Ian wrote:
>>
>> On Sat, Jul 2, 2016 at 12:40 AM, Lawrence D=E2=80=99Oliveiro wrote:
>>>
>>> On Saturday, July 2, 2016 at 5:10:06 PM UTC+12, Ian wrote:
>>>>
>>>> You should use functools.wraps instead of clobbering the decorated
>>>> function's name and docstring:
>>>
>>> Where am I doing that?
>>
>> Using the implementation you posted:
>>
>>>>> @decorator_with_args
>> ... def my_decorator(func, *args, **kwargs):
>> ...     """Returns func unmodified."""
>> ...     return func
>> ...
>>>>> my_decorator.__doc__
>> 'generates a decorator which applies my_decorator to the given arguments=
'
>
> That is a function that I am generating, so naturally I want to give it a=
 useful docstring. Am I =E2=80=9Cclobbering=E2=80=9D any objects passed in =
by the caller, or returned by the caller? No, I am not.

It isn't useful, though. If somebody writes a docstring for a
function, it's because they want that to be the docstring for the
function, not some arbitrary and vague docstring assigned by a
decorator. If I type "help(my_decorator)" in the interactive
interpreter, I should see what my_decorator actually does, not
"generates a decorator which applies my_decorator", which just
confuses with its recursiveness. The only way to find out what
my_decorator actually does from the interactive interpreter would be
to realize that it's been opaquely decorated and type out something
like this:

>>> my_decorator.__closure__[0].cell_contents.__doc__
'Returns func unmodified.'

That's far too obscure. Alternatively, one could go read the source.
But if you have to go read the source to understand what a function
does, then you've lost the purpose of having a docstring in the first
place.