iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Checking in what we have so far. Still digesting some of Jim Jewett's 

inputs.
This commit is contained in:
Skip Montanaro 2004-03-23 16:41:17 +00:00
parent efebd8e76c
commit b2436faf3b
1 changed files with 206 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

366
pep-0318.txt
View File

@ -2,241 +2,279 @@ PEP: 318
Title: Function/Method Decorator Syntax Title: Function/Method Decorator Syntax
Version: $Revision$ Version: $Revision$
Last-Modified: $Date$ Last-Modified: $Date$
Author: Kevin D. Smith <Kevin.Smith@theMorgue.org> Author: Kevin D. Smith <Kevin.Smith@theMorgue.org>,
Jim Jewett <jimjjewett@users.sourceforge.net>,
Skip Montanaro <skip@pobox.com>
Status: Draft Status: Draft
Type: Standards Track Type: Standards Track
Content-Type: text/plain Content-Type: text/x-rst
Created: 05-Jun-2003 Created: 05-Jun-2003
Python-Version: 2.4 Python-Version: 2.4
Post-History: 09-Jun-2003, 10-Jun-2003, 27-Feb-2004 Post-History: 09-Jun-2003, 10-Jun-2003, 27-Feb-2004, 23-Mar-2004
Abstract Abstract
========
The current method for declaring class and static methods The current method for declaring class and static methods is awkward
is awkward and can lead to code that is difficult to understand. and can lead to code that is difficult to understand. Ideally, these
This PEP introduces possible new syntax which will place the transformations should be made at the same point in the code where the
translation of instance methods to class/static methods at declaration itself is made. This PEP introduces new syntax for
the same point in the code as the method's declaration. transformations of a declaration.
Motivation Motivation
==========
The current method of translating an instance method into a The current method of applying a transformation to a function or
class/static method places the actual translation at a different method places the actual translation after the function body. For
point in the code than the declaration of the method. The large functions this separates a key component of the function's
code below demonstrates this. behavior from the definition of the rest of the function's external
interface. For example::
def foo(self): def foo(self):
perform method operation perform method operation
foo = classmethod(foo) foo = classmethod(foo)
When the method is very short, it is easy to look ahead and see This becomes less readable with longer methods. It also seems less
that this is a class method. However, if the method is more than than pythonic to name the function three times for what is
15 lines or so, the translation into a class method is not conceptually a single declaration. A solution to this problem is to
obvious. A solution to this problem is to move the translation move the transformation of the method closer to the method's own
of the method to the same point as the method's declaration. declaration. While the new syntax is not yet final, the intent is to
The proposed syntax, shown in the example below, is discussed replace::
in the following sections.
def foo(self) as synchronized(lock), classmethod: def foo(cls):
perform method operation pass
foo = synchronized(lock)(foo)
Proposal
Probably the simplest way to place the decorator that translates
an instance method to a class/static method is illustrated in the
code below.
def classmethod foo(self):
perform method operation
The code in this example will simply perform the following.
def foo(self):
perform method operation
foo = classmethod(foo) foo = classmethod(foo)
This syntax does not introduce any new keywords and is completely with an alternative that places the decoration in the function's
backwards compatible with any existing code. The word between the declaration::
'def' and the actual name of the method is simply a reference to
a callable object that returns a new function reference.
This syntax could also be extended to allow multiple function
decorators in the form of a space delimited list as follows:
def protected classmethod foo(self): def foo(cls) using [synchronized(lock), classmethod]:
perform method operation pass
which would be equivalent to the current form: Background
==========
def foo(self): There is general agreement that syntactic support is desirable to the
perform method operation current state of affairs. Guido mentioned `syntactic support for
foo = protected(classmethod(foo)) 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`_.
While this syntax is simple and easy to read, it does become .. _syntactic support for decorators: http://www.python.org/doc/essays/ppt/python10/py10keynote.pdf
cluttered and more obscure if you wish to allow arguments to be .. _10th python conference: http://www.python.org/workshops/2002-02/
sent to the function decorator. .. _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
def synchronized(lock) classmethod foo(self): Design Goals
perform method operation ============
Instead of placing the decorators in front of the function name, The new syntax should
a better place might be after it, as shown below. The word 'as' is
added simply as a separator to assist in readability.
def foo(self) as synchronized(lock), classmethod: * work for arbitrary wrappers, including user-defined callables and
perform method operation the existing builtins ``classmethod()`` and ``staticmethod``
This syntax is quite clear and could probably be interpreted * work with multiple wrappers per definition
by those not familiar with Python. The proposed syntax can be
generalized as follows:
'def' NAME '(' PARAMETERS ')' ['as' DECORATORS] ':' * 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
where DECORATORS is a comma-separated list of expressions, * not make future extensions more difficult
or a tuple. Using the latter form, the last example above
would look like:
def foo(self) as (synchronized(lock), classmethod): * be easy to type; programs that use it are expected to use it very
perform method operation frequently
This form make is possible for the list of decorators to * not make it more difficult to scan through code quickly. It should
span multiple lines without using the line continuation operator. still be easy to search for all definitions, a particular
definition, or the arguments that a function accepts
Alternate Syntaxes * not needlessly complicate secondary support tools such as
language-sensitive editors and other "`toy parser tools out
there`_"
Other syntaxes have been proposed in comp.lang.python and .. _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
python-dev. Unfortunately, no one syntax has come out as a clear
winner in the lengthy discussions. The most common suggestions
are demonstrated below. The proposed syntax is also included
for easy comparison.
Proposed Syntax Proposed Syntax
===============
def foo(self) as synchronized(lock), classmethod: The currently proposed syntax is::
perform method operation
def foo(self) as (synchronized(lock), classmethod): def func(arg1, arg2, ...) [dec1, dec2, ...]:
perform method operation pass
Prefix Forms 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.
def [synchronized(lock), classmethod] foo(self): Alternate Proposals
perform method operation ===================
def synchronized(lock), classmethod foo(self): A few other syntaxes have been proposed::
perform method operation
# Same as above, but only identifiers are allowed def func(arg1, arg2, ...) as dec1, dec2, ...:
sync = synchronized(lock) pass
def sync, classmethod foo(self):
perform method operation
# Java-like The absence of brackets makes it cumbersome to break long lists of
sync = synchronized(lock) decorators across multiple lines. The keyword "as" doesn't have the
def @sync @classmethod foo(self): same meaning as its use in the ``import`` statement.
perform method operation
Postfix Forms ::
def foo(self) [synchronized(lock), classmethod]: def [dec1, dec2, ...] func(arg1, arg2, ...):
perform method operation pass
def foo(self) (synchronized(lock), classmethod): This form has the disadvantage that the decorators become visually
perform method operation higher priority than the function name and argument list.
def foo(self) {'pre': synchronized(lock), 'classmethod': True}: ::
perform method operation
I'm not as fond of the forms that use '[ ]' since code like def func [dec1, dec2, ...] (arg1, arg2, ...):
'foo()[a]' looks as if you are getting the item 'a' from 'foo()'. pass
Although, this isn't as much of an issue when using '[ ]' in
a prefix form. The Java-like syntax adds new syntax that is
very arbitrary and is almost Perl-ish. In addition, since the
order in which the decorators are applied may matter, the last,
dictionary-style, syntax must be eliminated.
Implementation Issues Quixote's Page 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.
In the following example there are two function decorators: ::
synchronized(lock) and classmethod.
def foo(self) as synchronized(lock), classmethod: using:
perform method operation dec1
dec2
...
def foo(arg1, arg2, ...):
pass
Since these all appear within the operation of the 'def' The function definition is not nested within the using: block making
itself, it makes sense that synchronized, lock, and it impossible to tell which objects following the block will be
classmethod must exist at the time that the definition decorated. Nesting the function definition within the using: block
is executed. In addition, each of these arguments will be suggests block structure that doesn't exist. The name ``foo`` would
evaluated before being applied to the compiled function. actually exist at the same scope as the using: block. Finally, it
This means that arguments like synchronized(lock) must would require the introduction of a new keyword.
return a descriptor that will be applied to foo. Therefore,
the code above translates to:
def foo(self): Current Implementation
perform method operation ======================
foo = classmethod(<returned-descriptor>(foo))
In the example above, <returned-descriptor> refers to the Michael Hudson has posted a `patch`_ at Starship, which implements the
descriptor returned by evaluating synchronized(lock). proposed syntax and left-first application of decorators::
It could easily be argued that the descriptors should be applied def func(arg1, arg2, ...) [dec1, dec2]:
in reverse order to make the application of the descriptor look pass
more like the resultant code. I tend to prefer this form.
def foo(self): is equivalent to::
perform method operation
foo = <returned-descriptor>(classmethod(foo))
In either case, the modified function is bound to the function def func(arg1, arg2, ...):
name when the 'def' statement is executed. pass
func = dec2(dec1(func))
Open Issues though without the intermediate creation of a variable named ``func``.
It is not clear at the moment if it is even possible to have .. _patch: http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar.diff
multiple decorators for a function. If decorators are required
to take a function/method and return a descriptor, it might
not even be possible to wrap multiple decorators. This should
be explored since the best syntax for multiple decorators
may not be the same as the best syntax for a single decorator.
Current Implementations Examples
========
I am not personally familiar enough with Python's source to Much of the discussion on ``comp.lang.python`` and the ``python-dev``
implement the proposed syntax; however, Michael Hudson has mailing list focuses on the use of the ``staticmethod()`` and
implemented the "square-bracketed" syntax (see patch at ``classmethod()`` builtins. This capability is much more powerful
http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar.diff). than that. This section presents some examples of use.
It should be fairly simple for the Python development team
to translate this patch to the proposed syntax.
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):
return cls()
class MyClass [singleton]:
...
3. Decorate a function with release information. (Based on an example
posted by Anders Munch on ``python-dev``.)
::
def release(**kwds):
def decorate(f):
for k in kwds:
setattr(f, k, kwds[k])
return f
return decorate
def classmethod(f) [release(versionadded="2.2",
author="Guido van Rossum")]:
...
4. Enforce function argument and return types.
::
def accepts(*types):
def check_accepts(f):
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)
assert len(types) == f.func_code.co_argcount
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
Of course, all these examples are possible today, though without the
syntactic support.
Possible Extensions Possible Extensions
===================
The proposed syntax is general enough that it could be used The proposed syntax is general enough that it could be used on class
on class definitions as well as shown below. definitions as well::
class foo(object) as classmodifier: class foo(object) [dec1, dec2, ...]:
class definition here class definition here
However, there are no obvious parallels for use with other Use would likely be much less than function decorators. The current
descriptors such as property(). patch only implements function decorators.
Conclusion
The current method of translating an instance method to a class
or static method is awkward. A new syntax for applying function
decorators should be implemented (proposed syntax shown below).
def foo(self) as synchronized(lock), classmethod:
perform method operation
The proposed syntax is simple, powerful, easy to read, and
therefore preserves those qualities of the Python language.
Copyright Copyright
=========
This document has been placed in the public domain. This document has been placed in the public domain.