PEP-0318

[Mark Bottjer]

Skip Montanaro wrote:
> Incorporation of all or part of
> http://www.python.org/moin/PythonDecoratorsinto the PEP would also be
> appreciated.

Neat page. I would like to flesh out (5.D), though, as it is not quite 
just "(5.C) with pie syntax" like the document currently states:

     E. pie decorator at top of function body syntax

     def foo(arg1,arg2):
         @classmethod
         ...

     def bar(low,high):
         @accepts(int,int)
         @returns(float)
         ...

     * + Java-like, so not completely unknown to everyone.
     * + Makes the syntax obvious visually
     * + Will not be silently ignored
     * + Compile-time
     * + One decorator per line
     * + Separate from the def syntax (desired by some for making
         decoration stand out and keeping def the same)
     * + Consistent with how docstrings are used.
     * + Looks ok for simple or complex decorators
     * + Won't break simplistic code analyzers or grep for function def
     * + Solves line wrap problem with proposal (5.C)
     * + Shouldn't break in interactive shell
     * + Easily foldable, the decorations are all "in" the function.
     * + @ symbol makes syntax coloring easier than trying to identify
         normal syntactic elements (e.g., lists) in magic positions.
     * + @ symbol makes it obvious that the decoration is not a normal
         statement.

     * 0 Perhaps decorators should be allowed before or after the
         docstring. If you have to choose, I'd choose making it before
         the docstring.
     * 0 The @ character is often used (in other languages) to mean
         "attribute". For annotations, this is good. For more active
         decorators, it may not be so good.
     * 0 Could use @doc too as a docstring alternative

     * - Separate from the def syntax (undesired by some for simple
         decorators like classmethod/staticmethod)
     * - Ugly?
     * - Introduces a new character in the language
     * - The @ special character is used in IPython and Leo, though not
         in this context (right?)
     * - Punctuation-based syntax raises Perlfears.
     * - @staticmethod may look like staticmethod is not a defined
         variable, but a compile time option
     * - "Buried" after a potentially-long list of arguments, which can
         make them harder to spot.
     * - Lots of decorators will make it harder to find the start of the
         function implementation. Then again, so will a large docstring.

I would also like to add a few points to (5.A):

     * + @ symbol makes syntax coloring easier than trying to identify
         normal syntactic elements (e.g., lists) in magic positions.
     * + @ symbol makes it obvious that the decoration is not a normal
         statement.

     * - Requires the programmer to keep track of a potentially-large
         number of stacked up decorators before even knowing what is
         being decorated.
     * - Because of no indentation, looks confusing when definitions are
         not separated by empty lines. But adding empty lines makes it
         hard to determine where the function definition truly starts.
     * - Cannot be folded easily, since an arbitrary number of "leader
         lines" should also be folded into the function. This will
         involve a lot of reverse scanning of the file.

I would be happy to add these myself if someone would tell me how?

   -- Mark