Update of /cvsroot/python/python/nondist/peps In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10566 Modified Files: pep-0318.txt Log Message: Add verbiage about class decorators and their status Index: pep-0318.txt =================================================================== RCS file: /cvsroot/python/python/nondist/peps/pep-0318.txt,v retrieving revision 1.5 retrieving revision 1.6 diff -C2 -d -r1.5 -r1.6 *** pep-0318.txt 23 Mar 2004 16:41:17 -0000 1.5 --- pep-0318.txt 25 Mar 2004 21:45:58 -0000 1.6 *************** *** 1,4 **** PEP: 318 ! Title: Function/Method Decorator Syntax Version: $Revision$ Last-Modified: $Date$ --- 1,4 ---- PEP: 318 ! Title: Decorators for Functions, Methods and Classes Version: $Revision$ Last-Modified: $Date$ *************** *** 16,24 **** 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. --- 16,24 ---- 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. *************** *** 55,58 **** --- 55,65 ---- 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 ========== *************** *** 65,70 **** 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 --- 72,76 ---- 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 *************** *** 74,77 **** --- 80,86 ---- .. _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 ============ *************** *** 84,98 **** * 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 --- 93,107 ---- * 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 *************** *** 106,110 **** =============== ! The currently proposed syntax is:: def func(arg1, arg2, ...) [dec1, dec2, ...]: --- 115,119 ---- =============== ! The currently proposed syntax for function decorators is:: def func(arg1, arg2, ...) [dec1, dec2, ...]: *************** *** 115,118 **** --- 124,132 ---- 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 =================== *************** *** 124,129 **** The absence of brackets makes it cumbersome to break long lists of ! decorators across multiple lines. The keyword "as" doesn't have the ! same meaning as its use in the ``import`` statement. :: --- 138,146 ---- 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 :: *************** *** 132,136 **** pass ! This form has the disadvantage that the decorators become visually higher priority than the function name and argument list. --- 149,153 ---- pass ! This form has the disadvantage that the decorators visually assume higher priority than the function name and argument list. *************** *** 140,148 **** pass ! 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. :: --- 157,167 ---- 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 + :: *************** *** 157,169 **** 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. Current Implementation ====================== ! Michael Hudson has posted a `patch`_ at Starship, which implements the ! proposed syntax and left-first application of decorators:: def func(arg1, arg2, ...) [dec1, dec2]: --- 176,189 ---- 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. 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]: *************** *** 178,182 **** though without the intermediate creation of a variable named ``func``. ! .. _patch: http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar.diff Examples --- 198,202 ---- though without the intermediate creation of a variable named ``func``. ! .. _patch: http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar-3.diff Examples *************** *** 184,190 **** Much of the discussion on ``comp.lang.python`` and the ``python-dev`` ! mailing list focuses on the use of 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 --- 204,211 ---- 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 *************** *** 225,230 **** return decorate ! def classmethod(f) [release(versionadded="2.2", ! author="Guido van Rossum")]: ... --- 246,251 ---- return decorate ! def mymethod(f) [release(versionadded="2.2", ! author="Guido van Rossum")]: ... *************** *** 235,238 **** --- 256,260 ---- 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): *************** *** 240,244 **** "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 --- 262,265 ---- *************** *** 258,275 **** return arg1 * arg2 Of course, all these examples are possible today, though without the syntactic support. ! Possible Extensions ! =================== ! ! The proposed syntax is general enough that it could be used on class ! definitions as well:: ! class foo(object) [dec1, dec2, ...]: ! class definition here ! Use would likely be much less than function decorators. The current ! patch only implements function decorators. --- 279,319 ---- 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``. ! .. _strong arguments: http://mail.python.org/pipermail/python-dev/2004-March/thread.html