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

368
pep-0318.txt
View File

@ -2,243 +2,281 @@ 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)
foo = classmethod(foo)
with an alternative that places the decoration in the function's
declaration::
Proposal def foo(cls) using [synchronized(lock), classmethod]:
pass
Probably the simplest way to place the decorator that translates Background
an instance method to a class/static method is illustrated in the ==========
code below.
def classmethod 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
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`_.
The code in this example will simply perform the following. .. _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
def foo(self): Design Goals
perform method operation ============
foo = classmethod(foo)
This syntax does not introduce any new keywords and is completely The new syntax should
backwards compatible with any existing code. The word between the
'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): * work for arbitrary wrappers, including user-defined callables and
perform method operation the existing builtins ``classmethod()`` and ``staticmethod``
which would be equivalent to the current form: * work with multiple wrappers per definition
def foo(self): * make it obvious what is happening; at the very least it should be
perform method operation obvious that new users can safely ignore it when writing their own
foo = protected(classmethod(foo)) code
While this syntax is simple and easy to read, it does become * not make future extensions more difficult
cluttered and more obscure if you wish to allow arguments to be
sent to the function decorator.
def synchronized(lock) classmethod foo(self): * be easy to type; programs that use it are expected to use it very
perform method operation frequently
Instead of placing the decorators in front of the function name, * not make it more difficult to scan through code quickly. It should
a better place might be after it, as shown below. The word 'as' is still be easy to search for all definitions, a particular
added simply as a separator to assist in readability. definition, or the arguments that a function accepts
def foo(self) as synchronized(lock), classmethod: * not needlessly complicate secondary support tools such as
perform method operation language-sensitive editors and other "`toy parser tools out
there`_"
This syntax is quite clear and could probably be interpreted .. _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
by those not familiar with Python. The proposed syntax can be
generalized as follows:
'def' NAME '(' PARAMETERS ')' ['as' DECORATORS] ':' Proposed Syntax
===============
where DECORATORS is a comma-separated list of expressions, The currently proposed syntax is::
or a tuple. Using the latter form, the last example above
would look like:
def foo(self) as (synchronized(lock), classmethod): def func(arg1, arg2, ...) [dec1, dec2, ...]:
perform method operation pass
This form make is possible for the list of decorators to The decorators are near the declaration of the function's API but are
span multiple lines without using the line continuation operator. clearly secondary. The square brackets make it possible to fairly
easily break long lists of decorators across multiple lines.
Alternate Syntaxes Alternate Proposals
===================
Other syntaxes have been proposed in comp.lang.python and A few other syntaxes have been proposed::
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 def func(arg1, arg2, ...) as dec1, dec2, ...:
pass
def foo(self) as synchronized(lock), classmethod: The absence of brackets makes it cumbersome to break long lists of
perform method operation decorators across multiple lines. The keyword "as" doesn't have the
same meaning as its use in the ``import`` statement.
def foo(self) as (synchronized(lock), classmethod): ::
perform method operation
Prefix Forms def [dec1, dec2, ...] func(arg1, arg2, ...):
pass
def [synchronized(lock), classmethod] foo(self): This form has the disadvantage that the decorators become visually
perform method operation higher priority than the function name and argument list.
def synchronized(lock), classmethod foo(self): ::
perform method operation
# Same as above, but only identifiers are allowed def func [dec1, dec2, ...] (arg1, arg2, ...):
sync = synchronized(lock) pass
def sync, classmethod foo(self):
perform method operation
# Java-like Quixote's Page Template Language uses this form, but only supports a
sync = synchronized(lock) single decorator chosen from a restricted set. For short lists it
def @sync @classmethod foo(self): works okay, but for long list it separates the argument list from the
perform method operation function name.
Postfix Forms ::
def foo(self) [synchronized(lock), classmethod]: using:
perform method operation dec1
dec2
...
def foo(arg1, arg2, ...):
pass
def foo(self) (synchronized(lock), classmethod): The function definition is not nested within the using: block making
perform method operation it impossible to tell which objects following the block will be
decorated. Nesting the function definition within the using: block
suggests block structure 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.
def foo(self) {'pre': synchronized(lock), 'classmethod': True}: Current Implementation
perform method operation ======================
I'm not as fond of the forms that use '[ ]' since code like Michael Hudson has posted a `patch`_ at Starship, which implements the
'foo()[a]' looks as if you are getting the item 'a' from 'foo()'. proposed syntax and left-first application of decorators::
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 def func(arg1, arg2, ...) [dec1, dec2]:
pass
In the following example there are two function decorators: is equivalent to::
synchronized(lock) and classmethod.
def foo(self) as synchronized(lock), classmethod: def func(arg1, arg2, ...):
perform method operation pass
func = dec2(dec1(func))
Since these all appear within the operation of the 'def' though without the intermediate creation of a variable named ``func``.
itself, it makes sense that synchronized, lock, and
classmethod must exist at the time that the definition
is executed. In addition, each of these arguments will be
evaluated before being applied to the compiled function.
This means that arguments like synchronized(lock) must
return a descriptor that will be applied to foo. Therefore,
the code above translates to:
def foo(self): .. _patch: http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar.diff
perform method operation
foo = classmethod(<returned-descriptor>(foo))
In the example above, <returned-descriptor> refers to the Examples
descriptor returned by evaluating synchronized(lock). ========
It could easily be argued that the descriptors should be applied Much of the discussion on ``comp.lang.python`` and the ``python-dev``
in reverse order to make the application of the descriptor look mailing list focuses on the use of the ``staticmethod()`` and
more like the resultant code. I tend to prefer this form. ``classmethod()`` builtins. This capability is much more powerful
than that. This section presents some examples of use.
def foo(self): 1. Define a function to be executed at exit. Note that the function
perform method operation isn't actually "wrapped" in the usual sense.
foo = <returned-descriptor>(classmethod(foo))
In either case, the modified function is bound to the function ::
name when the 'def' statement is executed.
Open Issues def onexit(f):
import atexit
atexit.register(f)
return f
It is not clear at the moment if it is even possible to have def func() [onexit]:
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 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``.)
I am not personally familiar enough with Python's source to ::
implement the proposed syntax; however, Michael Hudson has
implemented the "square-bracketed" syntax (see patch at
http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar.diff).
It should be fairly simple for the Python development team
to translate this patch to the proposed syntax.
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.