|
Python 2.2 extended Python's object model by adding static methods and
class methods, but it didn't extend Python's syntax to provide any new
way of defining static or class methods. Instead, you had to write a
def statement in the usual way, and pass the resulting
method to a staticmethod() or classmethod()
function that would wrap up the function as a method of the new type.
Your code would look like this:
class C:
def meth (cls):
...
meth = classmethod(meth) # Rebind name to wrapped-up class method
If the method was very long, it would be easy to miss or forget the
classmethod() invocation after the function body.
The intention was always to add some syntax to make such definitions
more readable, but at the time of 2.2's release a good syntax was not
obvious. Today a good syntax still isn't obvious but users are
asking for easier access to the feature; a new syntactic feature has
been added to meet this need.
The new feature is called ``function decorators''. The name comes
from the idea that classmethod, staticmethod,
and friends are storing additional information on a function object;
they're decorating functions with more details.
The notation borrows from Java and uses the "@" character as an
indicator. Using the new syntax, the example above would be written:
class C:
@classmethod
def meth (cls):
...
The @classmethod is shorthand for the
meth=classmethod(meth) assignment. More generally, if you have
the following:
It's equivalent to the following pre-decorator code:
def f(): ...
f = A(B(C(f)))
Decorators must come on the line before a function definition, and
can't be on the same line, meaning that @A def f(): ... is
illegal. You can only decorate function definitions, either at the
module level or inside a class; you can't decorate class definitions.
A decorator is just a function that takes the function to be decorated
as an argument and returns either the same function or some new
callable thing. It's easy to write your own decorators. The
following simple example just sets an attribute on the function
object:
>>> def deco(func):
... func.attr = 'decorated'
... return func
...
>>> @deco
... def f(): pass
...
>>> f
<function f at 0x402ef0d4>
>>> f.attr
'decorated'
>>>
As a slightly more realistic example, the following decorator checks
that the supplied argument is an integer:
def require_int (func):
def wrapper (arg):
assert isinstance(arg, int)
return func(arg)
return wrapper
@require_int
def p1 (arg):
print arg
@require_int
def p2(arg):
print arg*2
An example in PEP 318 contains a fancier version of this idea that
lets you both specify the required type and check the returned type.
Decorator functions can take arguments. If arguments are supplied,
your decorator function is called with only those arguments and must
return a new decorator function; this function must take a single
function and return a function, as previously described. In other
words, @A @B @C(args) becomes:
def f(): ...
_deco = C(args)
f = A(B(_deco(f)))
Getting this right can be slightly brain-bending, but it's not too
difficult.
A small related change makes the func_name attribute of
functions writable. This attribute is used to display function names
in tracebacks, so decorators should change the name of any new
function that's constructed and returned.
See Also:
- PEP 318, Decorators for Functions, Methods and Classes
- Written
by Kevin D. Smith, Jim Jewett, and Skip Montanaro. Several people
wrote patches implementing function decorators, but the one that was
actually checked in was patch #979728, written by Mark Russell.
See About this document... for information on suggesting changes.
|
