This document is meant to describe the decorator syntax and the process that resulted in the decisions that were made. It does not attempt to cover the huge number of potential alternative syntaxes, nor is it an attempt to exhaustively list all the positives and negatives of each form.
The current method for transforming functions and methods (for instance, declaring them as a class or static method) is awkward and can lead to code that is difficult to understand. Ideally, these transformations should be made at the same point in the code where the declaration itself is made. This PEP introduces new syntax for transformations of a function or method declaration.
The current method of applying a transformation to a function or method places the actual transformation after the function body. For large functions this separates a key component of the function’s behavior from the definition of the rest of the function’s external interface. For example:
This becomes less readable with longer methods. It also seems less than pythonic to name the function three times for what is conceptually a single declaration. A solution to this problem is to move the transformation of the method closer to the method’s own declaration. The intent of the new syntax is to replace
with an alternative that places the decoration in the function’s declaration:
Modifying classes in this fashion is also possible, though the benefits are not as immediately apparent. Almost certainly, anything which could be done with class decorators could be done using metaclasses, but using metaclasses is sufficiently obscure that there is some attraction to having an easier way to make simple modifications to classes. For Python 2.4, only function/method decorators are being added.
PEP 3129 proposes to add class decorators as of Python 2.6.
Two decorators (classmethod() and staticmethod()) have been available in Python since version 2.2. It’s been assumed since approximately that time that some syntactic support for them would eventually be added to the language. Given this assumption, one might wonder why it’s been so difficult to arrive at a consensus. Discussions have raged off-and-on at times in both comp.lang.python and the python-dev mailing list about how best to implement function decorators. There is no one clear reason why this should be so, but a few problems seem to be most divisive.
There is general agreement that syntactic support is desirable to the current state of affairs. Guido mentioned syntactic support for decorators in his DevDay keynote presentation at the 10th Python Conference, though he later said it was only one of several extensions he proposed there “semi-jokingly”. Michael Hudson raised the topic on python-dev shortly after the conference, attributing the initial bracketed syntax to an earlier proposal on comp.lang.python by Gareth McCaughan.
Class decorations seem like an obvious next step because class definition and function definition are syntactically similar, however Guido remains unconvinced, and class decorators will almost certainly not be in Python 2.4.
The discussion continued on and off on python-dev from February 2002 through July 2004. Hundreds and hundreds of posts were made, with people proposing many possible syntax variations. Guido took a list of proposals to EuroPython 2004, where a discussion took place. Subsequent to this, he decided that we’d have the Java-style @decorator syntax, and this appeared for the first time in 2.4a2. Barry Warsaw named this the ‘pie-decorator’ syntax, in honor of the Pie-thon Parrot shootout which occurred around the same time as the decorator syntax, and because the @ looks a little like a pie. Guido outlined his case on Python-dev, including this piece on some of the (many) rejected forms.
There’s been a number of complaints about the choice of the name ‘decorator’ for this feature. The major one is that the name is not consistent with its use in the GoF book. The name ‘decorator’ probably owes more to its use in the compiler area – a syntax tree is walked and annotated. It’s quite possible that a better name may turn up.
The new syntax should
Andrew Kuchling has links to a bunch of the discussions about motivations and use cases in his blog. Particularly notable is Jim Huginin’s list of use cases.
The current syntax for function decorators as implemented in Python 2.4a2 is:
This is equivalent to:
without the intermediate assignment to the variable func. The decorators are near the function declaration. The @ sign makes it clear that something new is going on here.
The rationale for the order of application (bottom to top) is that it matches the usual order for function-application. In mathematics, composition of functions (g o f)(x) translates to g(f(x)). In Python, @g @f def foo() translates to foo=g(f(foo).
The decorator statement is limited in what it can accept – arbitrary expressions will not work. Guido preferred this because of a gut feeling.
The current syntax also allows decorator declarations to call a function that returns a decorator:
This is equivalent to:
The rationale for having a function that returns a decorator is that the part after the @ sign can be considered to be an expression (though syntactically restricted to just a function), and whatever that expression returns is called. See declaration arguments.
There have been a large number of different syntaxes proposed – rather than attempting to work through these individual syntaxes, it’s worthwhile to break the syntax discussion down into a number of areas. Attempting to discuss each possible syntax individually would be an act of madness, and produce a completely unwieldy PEP.
The first syntax point is the location of the decorators. For the following examples, we use the @syntax used in 2.4a2.
Decorators before the def statement are the first alternative, and the syntax used in 2.4a2:
There have been a number of objections raised to this location – the primary one is that it’s the first real Python case where a line of code has an effect on a following line. The syntax available in 2.4a3 requires one decorator per line (in a2, multiple decorators could be specified on the same line), and the final decision for 2.4 final stayed one decorator per line.
People also complained that the syntax quickly got unwieldy when multiple decorators were used. The point was made, though, that the chances of a large number of decorators being used on a single function were small and thus this was not a large worry.
Some of the advantages of this form are that the decorators live outside the method body – they are obviously executed at the time the function is defined.
Another advantage is that a prefix to the function definition fits the idea of knowing about a change to the semantics of the code before the code itself, thus you know how to interpret the code’s semantics properly without having to go back and change your initial perceptions if the syntax did not come before the function definition.
Guido decided he preferred having the decorators on the line before the ‘def’, because it was felt that a long argument list would mean that the decorators would be ‘hidden’
The second form is the decorators between the def and the function name, or the function name and the argument list:
There are a couple of objections to this form. The first is that it breaks easily ‘greppability’ of the source – you can no longer search for ‘def foo(’ and find the definition of the function. The second, more serious, objection is that in the case of multiple decorators, the syntax would be extremely unwieldy.
The next form, which has had a number of strong proponents, is to have the decorators between the argument list and the trailing : in the ‘def’ line:
Guido summarized the arguments against this form (many of which also apply to the previous form) as:
The next form is that the decorator syntax goes inside the method body at the start, in the same place that docstrings currently live:
The primary objection to this form is that it requires “peeking inside” the method body to determine the decorators. In addition, even though the code is inside the method body, it is not executed when the method is run. Guido felt that docstrings were not a good counter-example, and that it was quite possible that a ‘docstring’ decorator could help move the docstring to outside the function body.
The final form is a new block that encloses the method’s code. For this example, we’ll use a ‘decorate’ keyword, as it makes no sense with the @syntax.
This form would result in inconsistent indentation for decorated and undecorated methods. In addition, a decorated method’s body would start three indent levels in.
The major objections against this syntax are that the @ symbol is not currently used in Python (and is used in both IPython and Leo), and that the @ symbol is not meaningful. Another objection is that this “wastes” a currently unused character (from a limited set) on something that is not perceived as a major use.
This is a variant on the @decorator syntax – it has the advantage that it does not break IPython and Leo. Its major disadvantage compared to the @syntax is that the | symbol looks like both a capital I and a lowercase l.
The major objection to the list syntax is that it’s currently meaningful (when used in the form before the method). It’s also lacking any indication that the expression is a decorator.
None of these alternatives gained much traction. The alternatives which involve square brackets only serve to make it obvious that the decorator construct is not a list. They do nothing to make parsing any easier. The ‘<…>’ alternative presents parsing problems because ‘<’ and ‘>’ already parse as un-paired. They present a further parsing ambiguity because a right angle bracket might be a greater than symbol instead of a closer for the decorators.
The decorate() proposal was that no new syntax be implemented – instead a magic function that used introspection to manipulate the following function. Both Jp Calderone and Philip Eby produced implementations of functions that did this. Guido was pretty firmly against this – with no new syntax, the magicness of a function like this is extremely high:
This idea was the consensus alternate from comp.lang.python (more on this in Community Consensus below.) Robert Brewer wrote up a detailed J2 proposal document outlining the arguments in favor of this form. The initial issues with this form are:
A few days later, Guido rejected the proposal on two main grounds, firstly:
and secondly:
Readers are invited to read the full response.
There are plenty of other variants and proposals on the wiki page.
There is some history in Java using @ initially as a marker in Javadoc comments and later in Java 1.5 for annotations, which are similar to Python decorators. The fact that @ was previously unused as a token in Python also means it’s clear there is no possibility of such code being parsed by an earlier version of Python, leading to possibly subtle semantic bugs. It also means that ambiguity of what is a decorator and what isn’t is removed. That said, @ is still a fairly arbitrary choice. Some have suggested using | instead.
For syntax options which use a list-like syntax (no matter where it appears) to specify the decorators a few alternatives were proposed: [|...|], *[...]*, and <...>.
Guido asked for a volunteer to implement his preferred syntax, and Mark Russell stepped up and posted a patch to SF. This new syntax was available in 2.4a2.
This is equivalent to:
though without the intermediate creation of a variable named func.
The version implemented in 2.4a2 allowed multiple @decorator clauses on a single line. In 2.4a3, this was tightened up to only allowing one decorator per line.
A previous patch from Michael Hudson which implements the list-after-def syntax is also still kicking around.
After 2.4a2 was released, in response to community reaction, Guido stated that he’d re-examine a community proposal, if the community could come up with a community consensus, a decent proposal, and an implementation. After an amazing number of posts, collecting a vast number of alternatives in the Python wiki, a community consensus emerged (below). Guido subsequently rejected this alternate form, but added:
This section documents the rejected J2 syntax, and is included for historical completeness.
The consensus that emerged on comp.lang.python was the proposed J2 syntax (the “J2” was how it was referenced on the PythonDecorators wiki page): the new keyword using prefixing a block of decorators before the def statement. For example:
The main arguments for this syntax fall under the “readability counts” doctrine. In brief, they are:
Robert Brewer wrote a detailed proposal for this form, and Michael Sparks produced a patch.
As noted previously, Guido rejected this form, outlining his problems with it in a message to python-dev and comp.lang.python.
Much of the discussion on comp.lang.python and the python-dev mailing list focuses on the use of decorators as a cleaner way to use the staticmethod() and classmethod() builtins. This capability is much more powerful than that. This section presents some examples of use.
Note that this example is probably not suitable for real usage, but is for example purposes only.
Of course, all these examples are possible today, though without syntactic support.
PEP 3129 proposes to add class decorators as of Python 2.6.
In the end, the @ character was kept.
This document has been placed in the public domain.
Source: https://github.com/python/peps/blob/main/peps/pep-0318.rst
Last modified: 2025-02-01 08:59:27 UTC