390 lines
12 KiB
Plaintext
390 lines
12 KiB
Plaintext
PEP: 318
|
||
Title: Decorators for Functions, Methods and Classes
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Kevin D. Smith <Kevin.Smith@theMorgue.org>,
|
||
Jim Jewett <jimjjewett@users.sourceforge.net>,
|
||
Skip Montanaro <skip@pobox.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 05-Jun-2003
|
||
Python-Version: 2.4
|
||
Post-History: 09-Jun-2003, 10-Jun-2003, 27-Feb-2004, 23-Mar-2004
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
The current method for declaring class and static methods 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 declaration.
|
||
|
||
|
||
Motivation
|
||
==========
|
||
|
||
The current method of applying a transformation to a function or
|
||
method places the actual translation 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::
|
||
|
||
def foo(self):
|
||
perform method operation
|
||
foo = classmethod(foo)
|
||
|
||
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. While the new syntax is not yet final, the intent is to
|
||
replace::
|
||
|
||
def foo(cls):
|
||
pass
|
||
foo = synchronized(lock)(foo)
|
||
foo = classmethod(foo)
|
||
|
||
with an alternative that places the decoration in the function's
|
||
declaration::
|
||
|
||
def foo(cls) using [synchronized(lock), classmethod]:
|
||
pass
|
||
|
||
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.
|
||
|
||
|
||
Background
|
||
==========
|
||
|
||
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 bracketed syntax to an earlier proposal on
|
||
``comp.lang.python`` by `Gareth McCaughan`_.
|
||
|
||
.. _syntactic support for decorators:
|
||
http://www.python.org/doc/essays/ppt/python10/py10keynote.pdf
|
||
.. _10th python conference:
|
||
http://www.python.org/workshops/2002-02/
|
||
.. _michael hudson raised the topic:
|
||
http://mail.python.org/pipermail/python-dev/2002-February/020005.html
|
||
.. _he later said:
|
||
http://mail.python.org/pipermail/python-dev/2002-February/020017.html
|
||
.. _gareth mccaughan:
|
||
http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&selm=slrna40k88.2h9o.Gareth.McCaughan%40g.local
|
||
|
||
Class decorations seem like an obvious next step because class
|
||
definition and function definition are syntactically similar.
|
||
|
||
|
||
Design Goals
|
||
============
|
||
|
||
The new syntax should
|
||
|
||
* work for arbitrary wrappers, including user-defined callables and
|
||
the existing builtins ``classmethod()`` and ``staticmethod``
|
||
|
||
* work with multiple wrappers per definition
|
||
|
||
* make it obvious what is happening; at the very least it should be
|
||
obvious that new users can safely ignore it when writing their own
|
||
code
|
||
|
||
* not make future extensions more difficult
|
||
|
||
* be easy to type; programs that use it are expected to use it very
|
||
frequently
|
||
|
||
* not make it more difficult to scan through code quickly. It should
|
||
still be easy to search for all definitions, a particular
|
||
definition, or the arguments that a function accepts
|
||
|
||
* not needlessly complicate secondary support tools such as
|
||
language-sensitive editors and other "`toy parser tools out
|
||
there`_"
|
||
|
||
.. _toy parser tools out there:
|
||
http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&selm=mailman.1010809396.32158.python-list%40python.org
|
||
|
||
|
||
Proposed Syntax
|
||
===============
|
||
|
||
The currently proposed syntax for function decorators is::
|
||
|
||
def func(arg1, arg2, ...) [dec1, dec2, ...]:
|
||
pass
|
||
|
||
The decorators are near the declaration of the function's API but are
|
||
clearly secondary. The square brackets make it possible to fairly
|
||
easily break long lists of decorators across multiple lines.
|
||
|
||
Class decorators are defined in an analogous fashion::
|
||
|
||
class MyClass(base1, base2) [dec1, dec2, ...]:
|
||
pass
|
||
|
||
|
||
Alternate Proposals
|
||
===================
|
||
|
||
Several other syntaxes have been proposed::
|
||
|
||
def func(arg1, arg2, ...) as dec1, dec2, ...:
|
||
pass
|
||
|
||
The absence of brackets makes it cumbersome to break long lists of
|
||
decorators across multiple lines, and the keyword "as" doesn't have
|
||
the same meaning as its use in the ``import`` statement. Plenty of
|
||
`alternatives to "as"`_ have been proposed. :-)
|
||
|
||
.. _alternatives to "as":
|
||
http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&threadm=mailman.236.1079968472.742.python-list%40python.org&rnum=2&prev=/groups%3Fq%3Dpython%2Bpep%2B318%26hl%3Den%26lr%3D%26ie%3DUTF-8%26oe%3DUTF-8%26selm%3Dmailman.236.1079968472.742.python-list%2540python.org%26rnum%3D2
|
||
|
||
::
|
||
|
||
def [dec1, dec2, ...] func(arg1, arg2, ...):
|
||
pass
|
||
|
||
This form has the disadvantage that the decorators visually assume
|
||
higher priority than the function name and argument list.
|
||
|
||
::
|
||
|
||
def func [dec1, dec2, ...] (arg1, arg2, ...):
|
||
pass
|
||
|
||
Quixote's `Python Template Language`_ uses this form, but only supports a
|
||
single decorator chosen from a restricted set. For short lists it
|
||
works okay, but for long list it separates the argument list from the
|
||
function name.
|
||
|
||
.. _Python Template Language:
|
||
http://www.mems-exchange.org/software/quixote/doc/PTL.html
|
||
|
||
::
|
||
|
||
using:
|
||
dec1
|
||
dec2
|
||
...
|
||
def foo(arg1, arg2, ...):
|
||
pass
|
||
|
||
The function definition is not nested within the using: block making
|
||
it impossible to tell which objects following the block will be
|
||
decorated. Nesting the function definition within the using: block
|
||
suggests nesting of namespaces that doesn't exist. The name ``foo``
|
||
would actually exist at the same scope as the using: block. Finally,
|
||
it would require the introduction of a new keyword.
|
||
|
||
Guido proposed and implementated a patch to support interpretation of
|
||
a `list of decorators`_ as a prefix to function definitions ::
|
||
|
||
[dec1, dec2, ...]
|
||
def foo(arg1, arg2, ...):
|
||
pass
|
||
|
||
This appears to be his current favorite, but negative sentiment runs
|
||
high, mostly because that syntax, though useless except for side
|
||
effects of the list, is already legal and thus creates a special case.
|
||
|
||
.. _list of decorators:
|
||
http://python.org/sf/926860
|
||
|
||
|
||
Why [...]?
|
||
----------
|
||
|
||
For syntax options which use a list-like syntax to specify the
|
||
decorators a few alternatives have been proposed: ``[|...|]``,
|
||
``*[...]*``, and ``<...>``. None have gained 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.
|
||
|
||
|
||
Current Implementation
|
||
======================
|
||
|
||
Michael Hudson posted a `patch`_ at Starship, which implements the
|
||
proposed syntax changes for both functions and classes and left-first
|
||
application of decorators::
|
||
|
||
def func(arg1, arg2, ...) [dec1, dec2]:
|
||
pass
|
||
|
||
is equivalent to::
|
||
|
||
def func(arg1, arg2, ...):
|
||
pass
|
||
func = dec2(dec1(func))
|
||
|
||
though without the intermediate creation of a variable named ``func``.
|
||
|
||
.. _patch: http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar-3.diff
|
||
|
||
|
||
Examples
|
||
========
|
||
|
||
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.
|
||
|
||
1. Define a function to be executed at exit. Note that the function
|
||
isn't actually "wrapped" in the usual sense.
|
||
|
||
::
|
||
|
||
def onexit(f):
|
||
import atexit
|
||
atexit.register(f)
|
||
return f
|
||
|
||
def func() [onexit]:
|
||
...
|
||
|
||
2. Define a class with a singleton instance. Note that once the class
|
||
disappears enterprising programmers would have to be more creative
|
||
to create more instances. (From Shane Hathaway on ``python-dev``.)
|
||
|
||
::
|
||
|
||
def singleton(cls):
|
||
instances = {}
|
||
def getinstance():
|
||
if cls not in instances:
|
||
instances[cls] = cls()
|
||
return instances[cls]
|
||
return getinstance
|
||
|
||
class MyClass [singleton]:
|
||
...
|
||
|
||
3. Add attributes to a function. (Based on an example posted by
|
||
Anders Munch on ``python-dev``.)
|
||
|
||
::
|
||
|
||
def attrs(**kwds):
|
||
def decorate(f):
|
||
for k in kwds:
|
||
setattr(f, k, kwds[k])
|
||
return f
|
||
return decorate
|
||
|
||
def mymethod(f) [attrs(versionadded="2.2",
|
||
author="Guido van Rossum")]:
|
||
...
|
||
|
||
4. Enforce function argument and return types. (Note that this is not
|
||
exactly correct, as the returned new_f doesn't have "func" as its
|
||
func_name attribute.)
|
||
|
||
::
|
||
|
||
def accepts(*types):
|
||
def check_accepts(f):
|
||
assert len(types) == f.func_code.co_argcount
|
||
def new_f(*args, **kwds):
|
||
for (a, t) in zip(args, types):
|
||
assert isinstance(a, t), \
|
||
"arg %r does not match %s" % (a,t)
|
||
return f(*args, **kwds)
|
||
return new_f
|
||
return check_accepts
|
||
|
||
def returns(rtype):
|
||
def check_returns(f):
|
||
def new_f(*args, **kwds):
|
||
result = f(*args, **kwds)
|
||
assert isinstance(result, rtype), \
|
||
"return value %r does not match %s" % (result,rtype)
|
||
return result
|
||
return new_f
|
||
return check_returns
|
||
|
||
def func(arg1, arg2) [accepts(int, (int,float)),
|
||
returns((int,float))]:
|
||
return arg1 * arg2
|
||
|
||
5. Declare that a class implements a particular (set of) interface(s).
|
||
This is from a posting by Bob Ippolito on ``python-dev`` based on
|
||
experience with `PyProtocols`_.
|
||
|
||
.. _PyProtocols: http://peak.telecommunity.com/PyProtocols.html
|
||
|
||
::
|
||
|
||
def provides(*interfaces):
|
||
"""
|
||
An actual, working, implementation of provides for
|
||
the current implementation of PyProtocols. Not
|
||
particularly important for the PEP text.
|
||
"""
|
||
def provides(typ):
|
||
declareImplementation(typ, instancesProvide=interfaces)
|
||
return typ
|
||
return provides
|
||
|
||
class IBar(Interface):
|
||
"""Declare something about IBar here"""
|
||
|
||
class Foo(object) [provides(IBar)]:
|
||
"""Implement something here..."""
|
||
|
||
Of course, all these examples are possible today, though without the
|
||
syntactic support.
|
||
|
||
|
||
Open Issues
|
||
===========
|
||
|
||
1. It's not yet certain that class decorators will be incorporated
|
||
into the language at this point. Guido expressed skepticism about
|
||
the concept, but various people have made some `strong arguments`_
|
||
(search for ``PEP 318 - posting draft``) on their behalf in
|
||
``python-dev``.
|
||
|
||
2. Decorators which wrap a function and return a different function
|
||
should be able to easily change the func_name attribute without
|
||
constructing it with new.function(). Perhaps the func_name
|
||
attribute should be writable.
|
||
|
||
.. _strong arguments:
|
||
http://mail.python.org/pipermail/python-dev/2004-March/thread.html
|
||
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
End:
|