This wiki is in the process of being archived due to lack of usage and the resources necessary to serve it — predominately to bots, crawlers, and LLM companies. Edits are discouraged.
Pages are preserved as they were at the time of archival. For current information, please visit python.org.
If a change to this archive is absolutely needed, requests can be made via the infrastructure@python.org mailing list.

Contents

  1. About this page
  2. What is a Decorator
  3. What is a Python Decorator
  4. Debate about decorators in Python
  5. Examples
  6. Current Python Decorator Proposals
    1. A1. pie decorator syntax
    2. A2. pie decorator and space syntax
    3. B. list-before-def syntax
    4. C1. list-after-def syntax
    5. C2. list-after-def syntax with a (pseudo-)keyword
    6. C3. tuple-after-def syntax with a (pseudo-)keyword
    7. C4. tuple-after-def syntax with a % operator
    8. D1. list at top of function body syntax
    9. D2. 'dot'decorators at top of function body syntax
    10. E1. pie decorator at top of function body syntax
    11. E2. vbar decorator at top of function body syntax
    12. E3. vbar decorator after arg
    13. E4. keyword decorator at top of function body syntax
    14. F. inline syntax
    15. F2. inline syntax + new keyword (decodef for example)
    16. G. as decorator
    17. H. pie decorator using a different character
    18. I. angle brackets decorator syntax
    19. J1. new keyword decorator syntax
    20. J2. expand the def suite
    21. J3. two part def suite
    22. J4 two part def suite with "@" decorators
    23. J5 two part def suite with "@" decorators and colon
    24. K. partitioned syntax syntax
    25. L. Keyword other than as and with before def
    26. M. Making def an expression / letting it return a value
    27. N: Another Proposal (supplied by Anonymous)
  7. Decorator Syntax Breakdown
    1. Indicator
    2. Location
    3. List Notation
    4. Indentation
    5. Order of Decorators
    6. Allowable Decorators
    7. Meaning of decorators
  8. Thinking ahead to Python 3 ?

About this page

This page largely documents the history of the process of adding decorators to Python.

If you're just interested in what decorators or the '@' symbol mean in Python, see the Wikipedia page http://en.wikipedia.org/wiki/Python_syntax_and_semantics#Decorators or PEP 318.

What is a Decorator

A decorator is the name used for a software design pattern. Decorators dynamically alter the functionality of a function, method, or class without having to directly use subclasses or change the source code of the function being decorated.

For more information about the decorator pattern in general, see:

What is a Python Decorator

The "decorators" we talk about with concern to Python are not exactly the same thing as the DecoratorPattern described above. A Python decorator is a specific change to the Python syntax that allows us to more conveniently alter functions and methods (and possibly classes in a future version). This supports more readable applications of the DecoratorPattern but also other uses as well.

Support for the decorator syntax was proposed for Python in PEP 318, and will be implemented in Python 2.4.

Note that the current proposal actually only decorates functions (including methods). Extending it to classes or even arbitrary code is possible, but Guido wasn't sure it made sense. (Later versions might become more permissive, but they can't easily snatch functionality back.)

Debate about decorators in Python

The winning syntax as of now uses the '@' symbol, as described in this message. Mark Russell implemented this version. Here is the message describing the patch he checked in.

There has been a long discussion about the syntax to use for decorators in Python.

Examples

   1 @classmethod
   2 def foo (arg1, arg2):
   3     ....

See PythonDecoratorLibrary for more complex and real-world examples. See also MixIns and MetaClasses for related resources.

Current Python Decorator Proposals

See section 6 for a categorization of different proposals; this section just provides concrete examples.

Decorator Poll (consider the poll now closed)

Here is an online poll where you can vote between a few different alternative syntaxes for python decorators: http://wiki.wxpython.org/index.cgi/PythonDecoratorsPoll

A more complete poll is currently running on comp.lang.python, with the unfortunate name of "Alternate decorator syntax decision", using the options on this WikiPage as the candidates. Please visit that thread and express your preference!

After the @decorator syntax was "accepted", lots of people threw up alarms and a huge series of threads started exploding on Python-dev. Here are the current alternatives that I could find that are being argued, with pros and cons.

I give two examples that might be common uses in the future. Classmethod declarations, and something like static typing (adapters), declaring what type parameters a function expects and returns.

A1. pie decorator syntax

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

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

FWIW, here is Guido's jumble example in this syntax. 

class C(object):

    @staticmethod
    @funcattrs(grammar="'@' dotted_name [ '(' [arglist] ')' ]",
               status="experimental", author="BDFL")
    def longMethodNameForEffect(longArgumentOne=None,
                                longArgumentTwo=42):
        """This method blah, blah.

        It supports the following arguments:
        - longArgumentOne -- a string giving ...
        - longArgumentTwo -- a number giving ...

        blah, blah.

        """
        raise NotYetImplemented

And here is an example taken from the current test_decorators.py. This exposes the problem of using two lines together with some meaning but without identation or vertical whitespace. 

class TestDecorators(unittest.TestCase):

    ...

    def test_dotted(self):
        decorators = MiscDecorators()
        @decorators.author('Cleese')
        def foo(): return 42
        self.assertEqual(foo(), 42)
        self.assertEqual(foo.author, 'Cleese')

A2. pie decorator and space syntax

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

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

* 0 This is more readable for some people, less readable for others.

B. list-before-def syntax

[classmethod]
def foo(arg1,arg2):
    ...

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

C1. list-after-def syntax

def foo(arg1,arg2) [classmethod]:
    ...

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

I don't see why longs lists of decorators are an issue with this syntax. Consider the following example: 

def foo(arg1, arg2) [
    complicated(manyArgs=1, notTooUgly='yes'),
    even_more_complicated(42)]:
    ...

That doesn't look particularly ugly to me.

---

It also isn't very long.

Here is an example Guido just sent to python-dev: 

class C(object):

    def longMethodNameForEffect(longArgumentOne=None,
                                longArgumentTwo=42) [
        staticmethod,
        funcattrs(grammar="'@' dotted_name [ '(' [arglist] ')' ]",
                  status="experimental", author="BDFL")
        ]:
        """This method blah, blah.

        It supports the following arguments:
        - longArgumentOne -- a string giving ...
        - longArgumentTwo -- a number giving ...

        blah, blah.

        """
        raise NotYetImplemented

And he editorializes: 

That's a total jumble of stuff ending with a smiley.  (True story: I
left out the colon when typing up this example and only noticed in
proofing.)

Problems with this form:

- it hides crucial information (e.g. that it is a static method)
  after the signature, where it is easily missed

- it's easy to miss the transition between a long argument list and a
  long decorator list

- it's cumbersome to cut and paste a decorator list for reuse, because
  it starts and ends in the middle of a line

Given that the whole point of adding decorator syntax is to move the
decorator from the end ("foo = staticmethod(foo)" after a 100-line
body) to the front, where it is more in-your-face, it should IMO be
moved all the way to the front.

C2. list-after-def syntax with a (pseudo-)keyword

def foo(arg1,arg2) using [classmethod]:
    ...

def bar(low,high) using [accepts(int,int), returns(float)]:
    ...

This combines C1 with a keyword; it general, it has all the advantages of either, so I will only list those that are unique to the combination.

FWIW, here is Guido's jumble example in this syntax. 

class C(object):

    def longMethodNameForEffect(longArgumentOne=None,
                                longArgumentTwo=42) using
        [staticmethod,
         funcattrs(grammar="'@' dotted_name [ '(' [arglist] ')' ]",
                   status="experimental", author="BDFL")]:
        """This method blah, blah.

        It supports the following arguments:
        - longArgumentOne -- a string giving ...
        - longArgumentTwo -- a number giving ...

        blah, blah.

        """
        raise NotYetImplemented

Without the pseudo-keyword acting as line continuation it reads : 

class C(object):

    def longMethodNameForEffect(longArgumentOne=None,
                                longArgumentTwo=42) using [
         staticmethod,
         funcattrs(grammar="'@' dotted_name [ '(' [arglist] ')' ]",
                   status="experimental", author="BDFL")]:
        """This method blah, blah.

        It supports the following arguments:
        - longArgumentOne -- a string giving ...
        - longArgumentTwo -- a number giving ...

        blah, blah.

        """
        raise NotYetImplemented

which feel is more consistent with the rest of python parsing-wise, without decreasing readability...

(See also J4 below, which moves the keyword, and uses "@" signs to make the decorators stand out more.)

C3. tuple-after-def syntax with a (pseudo-)keyword

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

def bar(low,high) using accepts(int,int), returns(float):
    ...
class C(object):

    def longMethodNameForEffect(longArgumentOne=None,
                                longArgumentTwo=42) using (
         staticmethod,
         funcattrs(grammar="'@' dotted_name [ '(' [arglist] ')' ]",
                   status="experimental", author="BDFL")):
        """This method blah, blah.

        It supports the following arguments:
        - longArgumentOne -- a string giving ...
        - longArgumentTwo -- a number giving ...

        blah, blah.

        """
        raise NotYetImplemented

Very similar to C2, but with those slight differences

The 1st drawback could be removed if one allows both tuple and single-element after the pseudo-keyword, trading consistency for readability and convenience.

C4. tuple-after-def syntax with a % operator

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

def bar(low,high) % accepts(int,int), returns(float):
    ...
class C(object):

    def longMethodNameForEffect(longArgumentOne=None,
                                longArgumentTwo=42)             # make implicit linebreak possible here
         % (staticmethod,
            funcattrs(grammar="'@' dotted_name [ '(' [arglist] ')' ]",
                      status="experimental", author="BDFL")):
        """This method blah, blah.

        It supports the following arguments:
        - longArgumentOne -- a string giving ...
        - longArgumentTwo -- a number giving ...

        blah, blah.

        """
        raise NotYetImplemented

# this is also possible for consistency:

foo %= classmethod
bar %= (accepts(int,int), returns(float))

Very similar to C3, but with those slight differences

One more point: % could also be used in chained fashion: 

bar = bar % accepts(int,int) % returns(float)

(making it similar to E2 below)

D1. list at top of function body syntax

def foo(arg1,arg2):
    [classmethod]
    ...

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

D2. 'dot'decorators at top of function body syntax

def bar(low,high):
    .accepts(int,int)
    .returns(float)
    """docstring"""
    pass

def longMethodNameForEffect(longArgumentOne=None,
                            longArgumentTwo=42):
    .staticmethod
    .funcattrs(grammar="'@' dotted_name [ '(' [arglist] ')' ]",
               status="experimental", author="BDFL")
    """
    asdfasdf
    """
    raise NotYetImplemented

Advantages/disadvantages of .decorators: 

def func():
    .author = "Kevin Butler"
    pass