[Python-Dev] Yet Another Decorator Syntax Suggestion (YADSS)

[Jack Diederich]

YASTBG (Yet Another Syntax That Breaks Grep)

On Mon, Mar 29, 2004 at 05:11:09PM +1000, Mike Thompson wrote:
> I believe that cognitively speaking, when a function is first being 
> understood by a reader, decorators need to be seen BEFORE the other 
> details of the function (even its name).  Understanding that a function 
> is a 'classmethod', provides crucial context for understanding the 
> function's name, argument list, documentation and body. So, I believe 
> 'classmethod' should be seen first in the function definition.
I don't think they are the most important, we've lived with them a mile
away this long and people seem to get by *wink*.

> I believe this requirement has motivated some to support syntax where 
> the decorator list is promoted to be 'early' in the 'def':
>     def  [classmethod] func(args)
> OR  def func [classmethod] func(args)
> etc.
grep 'func(' *.py   # finds most calls to func, and it's definition
grep 'def func' *.py  # which file has the definition and what is it?

The more a proposal breaks grep, the less I like it.  Most decorator
lists will be single decorators (if there is one at all).  Your suggestion
(below) will always 'break' grep.  IDEs would alleviate the problem,
but I've never used an IDE and I have no desire to start.

> 
>     as:
>         classmethod
>     def func(arg):
>         pass
un-grepable! we'll never see the decorators.

def func(arg) [classmethod]: pass

grepable!

> This solution scales up reasonably to multiple decorators:
>     as:
>         runOnExit
>         staticmethod
>         syncronisedWith(attr='lock')
>         attributedBy(
>             author='MT',
>             release='5.4'
>         )
>         returns(int)
>         takes((int, int))
>     def func(args):
>         pass
un-grepable!  regular funcs and decorated funcs grep the same.

def func(args) [runOnExit,
                ..
grepable! the unterminated square brackets let us know we aren't
seeing the full definition.

This is one of the reasons I dislike the decorator list between the
'def' and the function name.  I could grep for 'def.*?func(' but that
is an annoyance from the command line, and a major pain in most editors.

Even the current way is made grepable by popular convention,
if the first argument is 'cls' instead of 'self' you expect it to be
a classmethod.  If the first argument is neither 'cls' or 'self' it
is a plain function or staticmethod (and you don't care which).
Other decorators than these two are currently un-grepable.

-jackdied