[Python-checkins] python/nondist/peps pep-0318.txt,1.21,1.22
anthonybaxter at users.sourceforge.net
anthonybaxter at users.sourceforge.net
Thu Aug 19 17:36:17 CEST 2004
Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv28238
Modified Files:
pep-0318.txt
Log Message:
checking in work-in-progress. this is by no means finished -
I will attack it some more this weekend and attempt to finish it.
Please feel free to fill out any bits you think I've missed.
See the WarningWarningWarning section at the top.
Index: pep-0318.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0318.txt,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -d -r1.21 -r1.22
*** pep-0318.txt 12 Aug 2004 20:33:02 -0000 1.21
--- pep-0318.txt 19 Aug 2004 15:36:14 -0000 1.22
***************
*** 5,9 ****
Author: Kevin D. Smith <Kevin.Smith at theMorgue.org>,
Jim Jewett <jimjjewett at users.sourceforge.net>,
! Skip Montanaro <skip at pobox.com>
Status: Draft
Type: Standards Track
--- 5,10 ----
Author: Kevin D. Smith <Kevin.Smith at theMorgue.org>,
Jim Jewett <jimjjewett at users.sourceforge.net>,
! Skip Montanaro <skip at pobox.com>,
! Anthony Baxter <anthony at python.org>
Status: Draft
Type: Standards Track
***************
*** 14,25 ****
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.
--- 15,37 ----
+ WarningWarningWarning
+ =====================
+
+ This is not yet complete. This is still a work-in-progress. Feedback
+ to anthony. Please note that the point of this PEP is _not_ to provide
+ an open-slather of plusses and minuses for each syntax, but is instead
+ to justify the choice made. If, in 2.4a3, the syntax is changed, the
+ PEP will be updated to match this, complete with the arguments for the
+ change.
+
Abstract
========
! The current method for transforming functions and methods (for instance,
! declaring them as a class or static method) 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
! function or method declaration.
***************
*** 62,67 ****
metaclasses, but using metaclasses is sufficiently obscure that there
is some attraction to having an easier way to make simple
! modifications to classes. For Python 2.4, only function decorators
! are being added.
--- 74,79 ----
metaclasses, but using metaclasses is sufficiently obscure that there
is some attraction to having an easier way to make simple
! modifications to classes. For Python 2.4, only function/method
! decorators are being added.
***************
*** 75,79 ****
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`_.
--- 87,91 ----
extensions he proposed there "semi-jokingly". `Michael Hudson raised
the topic`_ on ``python-dev`` shortly after the conference,
! attributing the initial bracketed syntax to an earlier proposal on
``comp.lang.python`` by `Gareth McCaughan`_.
***************
*** 93,100 ****
The discussion continued on and off on python-dev from February 2002
! through July 2004. Many hundreds of posts were made, with people
proposing many possible syntax variations. Guido took a list of
proposals to `EuroPython 2004`_, where a discussion took place.
! Subsequent to this, he decided that for 2.4a2 we'd have the Java-style
@decorator syntax. Barry Warsaw named this the 'pie-decorator'
syntax, in honor of the Pie-thon Parrot shootout which was announced
--- 105,112 ----
The discussion continued on and off on python-dev from February 2002
! through July 2004. Hundreds and hundreds of posts were made, with people
proposing many possible syntax variations. Guido took a list of
proposals to `EuroPython 2004`_, where a discussion took place.
! Subsequent to this, he decided that for 2.4a2 we'd have the `Java-style`_
@decorator syntax. Barry Warsaw named this the 'pie-decorator'
syntax, in honor of the Pie-thon Parrot shootout which was announced
***************
*** 112,115 ****
--- 124,142 ----
http://mail.python.org/pipermail/python-dev/2004-August/046672.html
+ .. Java-style:
+ http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html
+
+ On the name 'Decorator'
+ =======================
+
+ There's been a number of complaints about the choice of the name
+ 'decorator' for this feature. The major one is that the name is
+ not consistent with it's use in the `GoF book`_. The name 'decorator'
+ probably owes more to it's use in the compiler area - a syntax tree
+ is walked and annotated. It's quite possible that a better name may
+ turn up.
+
+ .. GoF book:
+ http://patterndigest.com/patterns/Decorator.html
Design Goals
***************
*** 140,154 ****
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
Andrew Kuchling has links to a bunch of the discussions about motivations
! `in his blog`_.
.. _in his blog:
http://www.amk.ca/diary/archives/cat_python.html#003255
! Proposed Syntax
! ===============
The current syntax for function decorators as implemented in Python
--- 167,191 ----
there`_"
+ * move from the end of the function, where it's currently hidden, to
+ the front where it is more `in your face`_
+
.. _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
+ .. in your face:
+ http://mail.python.org/pipermail/python-dev/2004-August/047112.html
+
Andrew Kuchling has links to a bunch of the discussions about motivations
! and use cases `in his blog`_. Particularly notable is `Jim Huginin's list
! of use cases`_.
.. _in his blog:
http://www.amk.ca/diary/archives/cat_python.html#003255
! .. _Jim Huginin's list of use cases:
! http://mail.python.org/pipermail/python-dev/2004-April/044132.html
!
! Current Syntax
! ==============
The current syntax for function decorators as implemented in Python
***************
*** 176,183 ****
--- 213,388 ----
http://mail.python.org/pipermail/python-dev/2004-August/046711.html
+ Syntax Alternatives
+ ===================
+
+ There have been `a large number`_ of different syntaxes proposed - rather
+ than attempting to work through these individual syntaxes, it's worthwhile
+ to break the syntax discussion down into a number of areas. Attempting to
+ discuss `each possible syntax`_ individually would be an act of madness,
+ and produce a completely unwieldly PEP.
+
+ .. a large number:
+ http://www.python.org/moin/PythonDecorators
+ .. each possible syntax:
+ http://ucsu.colorado.edu/~bethard/py/decorators-output.py
+
+ Decorator Location
+ ------------------
+
+ The first syntax point is the location of the decorators. For the
+ following examples, we use the @syntax used in 2.4a2.
+
+ Decorators before the def statement are the first alternative,
+ and the syntax used in 2.4a2::
+
+ @classmethod
+ def foo(arg1,arg2):
+ pass
+
+ @accepts(int,int)
+ @returns(float)
+ def bar(low,high):
+ pass
+
+ There have been a number of objections raised to this location -
+ the primary one is that it's the first real Python case where a
+ line of code has a result on a following line. The syntax that
+ will be in 2.4a3 will also require one decorator per line (in a2,
+ multiple decorators can be specified on the same line).
+
+ Some of the advantages of this form are that the decorators live
+ outside the method body - they are obviously executed at the time
+ the function is defined
+
+ The second form is the decorators between the def and the function
+ name, or the function name and the argument list::
+
+ def @classmethod foo(arg1,arg2):
+ pass
+
+ def @accepts(int,int), at returns(float) bar(low,high):
+ pass
+
+ def foo @classmethod (arg1,arg2):
+ pass
+
+ def bar @accepts(int,int), at returns(float) (low,high):
+ pass
+
+ There are a couple of objections to this form.
+ The first is that it breaks easily 'greppability' of the source - you
+ can no longer search for 'def foo(' and find the definition of the
+ function. The second, more serious, objection is that in the case
+ of multiple decorators, the syntax would be extremely unwieldy.
+
+ The next form, which has had a number of strong proponents, is to
+ have the decorators between the argument list and the trailing ``:``
+ in the 'def' line::
+
+ def foo(arg1,arg2) @classmethod:
+ pass
+
+ def bar(low,high) @accepts(int,int), at returns(float):
+ pass
+
+ Guido `summarised the arguments`_ against this form (many of which
+ also apply to the previous form) as:
+
+ - it hides crucial information (e.g. that it is a static method)
+ after the signature, where it is easily missed
+
+ - it's easy to miss the transition between a long argument list and a
+ long decorator list
+
+ - it's cumbersome to cut and paste a decorator list for reuse, because
+ it starts and ends in the middle of a line
+
+ .. summarised the arguments:
+ http://mail.python.org/pipermail/python-dev/2004-August/047112.html
+
+ The next form is that the decorator syntax go inside the method
+ body at the start, in the same place that docstrings currently
+ live:
+
+ def foo(arg1,arg2):
+ @classmethod
+ pass
+
+ def bar(low,high):
+ @accepts(int,int)
+ @returns(float)
+ pass
+
+ The primary objection to this form is that it requires "peeking inside"
+ the method body to determine the decorators. In addition, even though
+ the code is inside the method body, it is not executed when the method
+ is run. Guido felt that docstrings were not a good counter-example, and
+ that it was quite possible that a 'docstring' decorator could help move
+ the docstring to outside the function body.
+
+ The final form is a new block that encloses the method's code. For this
+ example, we'll use a 'decorate' keyword, as it makes no sense with the
+ @syntax.
+
+ decorate:
+ classmethod
+ def foo(arg1,arg2):
+ pass
+
+ decorate:
+ accepts(int,int)
+ returns(float)
+ def bar(low,high):
+ pass
+
+ This form would result in inconsistent indentation for decorated and
+ undecorated methods. In addition, a decorated method's body would start
+ three indent levels in.
+
+ Syntax forms
+ ------------
+
+ @decorator
+
+ The major objections against this syntax are that the @ symbol
+ is not currently used in Python (and is used in both IPython and
+ Leo), that the @ symbol is not meaningful,
+
+ |decorator
+
+ This is a variant on the @decorator syntax - it has the advantage
+ that it does not break IPython and Leo. It's major disadvantage
+ compared to the @syntax is that the | symbol looks like both a
+ capital I and a lowercase l.
+
+ * list syntax
+
+ The major objection to the list syntax is that it's currently
+ meaningful (when used in the form before the method). It's also
+ lacking any indication that the expression is a decorator.
+
+ * list syntax using other brackets ( <...>, [[...]], ... )
+
+
+ * decorate()
+
+ The decorate() proposal was that no new syntax be implemented -
+ instead a magic function that used introspection to manipulate
+ the following function. Both Jp Calderone and Philip Eby produced
+ implementations of functions that did this. Guido was pretty firmly
+ against this - with no new syntax, the magicness of a function like
+ this is extremely high.
+
+ * new keyword (and block)
+
+
Alternate Proposals
===================
+ The text in this section will be integrated into the previous section.
+ They're here for hysterical raisins for now.
+
+
Several other syntaxes have been proposed::
***************
*** 301,305 ****
There is some history in Java using @ initially as a marker in
! `Javadoc comments`_ and later in ... mumble mumble ... The fact that
@ was previously unused as a token in Python also means it's clear
there is no possibility of such code being parsed by an earlier
--- 506,511 ----
There is some history in Java using @ initially as a marker in
! `Javadoc comments`_ and later in Java 1.5 for `annotations`_,
! which are similar to Python decorators. The fact that
@ was previously unused as a token in Python also means it's clear
there is no possibility of such code being parsed by an earlier
***************
*** 321,324 ****
--- 527,533 ----
http://java.sun.com/j2se/javadoc/writingdoccomments/
+ .. annotations:
+ http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html
+
Current Implementation
======================
More information about the Python-checkins
mailing list