elements of decorator syntax suggestions

[Steven Bethard]

I think one of the biggest reasons we're having such problems coming
to any agreement on decorator syntax is that each proposal makes a
number of syntax decisions, not just one.  For decorators, I see the
following decisions that must be made:

1) Indicator
Proposals differ on how some sort of indicator of "decoratorhood" is
use.  These include:
* none (e.g. just the list, as in the "list-after-def" suggestion)
* the '@' character
* a new keyword (with, using, decorate, etc.)

2) Location
Proposals also differ on exactly where the decorator declaration
should be made.  These include:
* before def
* between def and function name
* between function name and argument list
* between argument list and colon
* after colon (first line in body)

3) List notation
As I understand it, it's already decided that any implementation of
decorators must allow for a list of decorators to be applied.  So
proposals that might be accepted must explain how this can be done. 
The options I've seen:
* one per line (as currently)
* commas only
* current list syntax (or some similar variant)

4) Indentation
Proposals also differ on whether or not decorators should introduce a
new block.  What I've seen:
* no block
* block

I thought the summary above might put some things into perspective so
that when you're arguing for one syntax or another, you can argue
separately for the points that matter most to you.  It might be that
we mostly agree on, say, the need for a keyword, or the block
indentation (though I'm certainly not holding my breath).  But I'd
rather hear arguments for the different sections separately because,
to some degree, they're pretty much orthogonal.


In case you were just asking yourself, "well, gee, Steve, what do you
think?", =) here's what I think for each of the points above:

1) Indicator
I want a new keyword.  A list alone (no matter where it's placed)
doesn't look any more like a decorator to me than '@' does.  I want
some sort of cue that reads more clearly.  I'm not picky on what this
keyword is -- 'decorate' seemed like a reasonable proposal, but I'd
even be happy with 'with' or 'using' -- but I don't just want
arbitrary symbols.  I think this is most important from the
perspective of new Python users, who will have to guess the meaning of
such syntax from someone else's code.  Having a keyword that makes the
usage clear makes this reading much easier.

2) Location
I don't like "between def and function name" or "between function name
and argument list" because I think they make it harder to see the
basic signature of the function.  Remember that we have to support
lists, so just sticking a in single word, like staticmethod or
classmethod, isn't an option -- otherwise, I could have perhaps seen
the merit of "between def and function name".

I'm not a big fan of "after colon" (like a doc-string) because I'm
more likely to read this as part of the function definition.  (In
fact, that's what I'd do now, so this is a semantic change, one of the
things I'd rather avoid.)

As far as "before def" or "betwen argument list and colon" go (and I
believe these are the major contenders), I could go either way -- and
I'm really not particular here; I'd rather have /some/ decorator
syntax than argue over these forever.  "before def" seems to deal
better with functions that have long names or argument lists (Guido's
example convinced me that I'd be confused where arguments ended and
decorators started), but "between argument list and colon" avoids the
two-lines-define-a-single-function problem.  Eh...  Like I say, I'm
not going to argue this one -- I could be happy with either.

3) List notation
I don't really have a preference here.  I can see that commas only
might be a pain if you need to use multiple lines perhaps.  But "one
per line" or "list syntax" would both be fine with me.

4) Indentation
I'd prefer that decorators didn't start a new block mainly because
that makes, for example, an instance method with an 'accepts'
decorator on a different block level than an instance method without
one.  Still, I could live with indented decorators.


So in summary
-> yay keywords!
-> before def or before colon, and 
-> whatever list notation and indentation floats your boat

=)

Steve