[Python-Dev] Re: Re: Call for defense of @decorators

[Chris King]

On Tue, 10 Aug 2004 13:21:42 -0400, Phillip J. Eby
<pje at telecommunity.com> wrote:

> This doesn't apply to other decorators.  For example, some decorators turn
> a function into a property.

Ew.  If you did that, you'd be declaring get properties one way (with
decorators) and get/set properties another (using property()).

> Others change the (effective) call signature.

But will a casual observer be able to see exactly how a given
decorator is mutating the call signature?  If such a function is meant
for external use, its effective signature should be in the docstring,
not unlike those of C extension functions.  On the other hand, the
developer will know which functions are using such a decorator, or
will know to look for whether such a decorator is being used in a
function.

> Indeed, staticmethod changes the call signature, since there is no special
> first argument.

No, static methods are called with the same signature you see defined,
just like a normal function.  Not seeing 'self' as the first argument
should be enough to tip you off that this isn't a bound method.

Concerning users, whether a method is a static or class method should
be indicated in the method's docstring.  I should hope any user reads
a function's docstring for usage information before using it.

> In frameworks where methods can be wrapped in transactions, lock
> synchronization, security checks, remote communication, etc., these are all
> decorations that are potentially part of the interface and important for
> the reader to know, even if they don't look at the method body (apart from
> the doc string).

Assuming they look at the docstring, perhaps the method author would
be kind enough to specify "This function performs an exclusively
locked record transaction.", or, better yet, the decorator itself
could extend the docstring with its own "record-locking method"
indicator.  Making decorators more visible in the source doesn't make
then more visible in the docstring.

If the user can't be bothered to read a three-line description that is
a docstring, I doubt they will be bothered to read (and possibly
decipher) the information contained in decorators, no matter where
they're placed.