[Python-checkins] python/nondist/peps pep-0318.txt,1.22,1.23
goodger at users.sourceforge.net
goodger at users.sourceforge.net
Fri Aug 20 03:14:26 CEST 2004
Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv31018
Modified Files:
pep-0318.txt
Log Message:
reST foo to the rescue!
Index: pep-0318.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0318.txt,v
retrieving revision 1.22
retrieving revision 1.23
diff -C2 -d -r1.22 -r1.23
*** pep-0318.txt 19 Aug 2004 15:36:14 -0000 1.22
--- pep-0318.txt 20 Aug 2004 01:14:23 -0000 1.23
***************
*** 18,37 ****
=====================
! 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.
--- 18,38 ----
=====================
! 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.
***************
*** 74,78 ****
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 ----
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.
***************
*** 105,143 ****
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
! about the same time as the decorator syntax, and because the @ looks a
! little like a pie. Guido `outlined his case`_ on Python-dev,
! including `this piece`_ on the various rejected forms.
.. _EuroPython 2004:
http://www.python.org/doc/essays/ppt/euro2004/euro2004.pdf
-
.. _outlined his case:
http://mail.python.org/pipermail/python-dev/2004-August/author.html
-
.. _this piece:
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
============
--- 106,143 ----
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 about the same time as the decorator syntax, and because
! the @ looks a little like a pie. Guido `outlined his case`_ on
! Python-dev, including `this piece`_ on the various rejected forms.
.. _EuroPython 2004:
http://www.python.org/doc/essays/ppt/euro2004/euro2004.pdf
.. _outlined his case:
http://mail.python.org/pipermail/python-dev/2004-August/author.html
.. _this piece:
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 its use in the `GoF book`_. The name 'decorator'
! probably owes more to its 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
============
***************
*** 145,189 ****
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`_"
! * 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
==============
--- 145,187 ----
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`_"
! * move from the end of the function, where it's currently hidden, to
! the front where it is more `in your face`_
!
! 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`_.
.. _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
.. _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
==============
***************
*** 207,234 ****
clear that something new is going on here.
! The decorator statement is limited in what it can accept - arbitrary
! expressions will not work. Guido preferred this because of a `gut feeling`_
.. _gut feeling:
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.
--- 205,235 ----
clear that something new is going on here.
! The decorator statement is limited in what it can accept -- arbitrary
! expressions will not work. Guido preferred this because of a `gut
! feeling`_.
.. _gut feeling:
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.
***************
*** 245,256 ****
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
--- 246,257 ----
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
***************
*** 270,278 ****
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
--- 271,279 ----
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
***************
*** 298,302 ****
it starts and ends in the middle of a line
! .. summarised the arguments:
http://mail.python.org/pipermail/python-dev/2004-August/047112.html
--- 299,303 ----
it starts and ends in the middle of a line
! .. _summarised the arguments:
http://mail.python.org/pipermail/python-dev/2004-August/047112.html
***************
*** 314,327 ****
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:
--- 315,328 ----
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:
***************
*** 337,381 ****
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
===================
--- 338,381 ----
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. Its 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
===================
***************
*** 393,423 ****
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:
--- 393,414 ----
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. :-) ::
def [dec1, dec2, ...] func(arg1, arg2, ...):
pass
! .. _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
! 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. ::
using:
***************
*** 428,431 ****
--- 419,425 ----
pass
+ .. _Python Template Language:
+ http://www.mems-exchange.org/software/quixote/doc/PTL.html
+
The function definition is not nested within the using: block making
it impossible to tell which objects following the block will be
***************
*** 435,441 ****
it would require the introduction of a new keyword.
! The obvious alternative that nests the function within the block
!
! ::
using:
--- 429,433 ----
it would require the introduction of a new keyword.
! The obvious alternative that nests the function within the block ::
using:
***************
*** 460,466 ****
pass
! For a while this was Guido's preferred solution, but negative sentiment ran
! 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:
--- 452,459 ----
pass
! For a while this was Guido's preferred solution, but negative
! sentiment ran 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:
***************
*** 482,486 ****
no new syntax, but instead used some fairly advanced introspection
to provide decorator-like behavoiur, but Guido was unimpressed by
! these, stating::
Using functions with "action-at-a-distance" through
--- 475,479 ----
no new syntax, but instead used some fairly advanced introspection
to provide decorator-like behavoiur, but Guido was unimpressed by
! these, stating:
Using functions with "action-at-a-distance" through
***************
*** 502,516 ****
! Why @?
------
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
! version of Python, leading to possibly subtle semantic bugs. That
! said, @ is still a fairly arbitrary choice. Some have suggested using
! | instead.
For syntax options which use a list-like syntax (no matter where it
--- 495,508 ----
! Why @?
------
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 version of Python,
! leading to possibly subtle semantic bugs. That said, @ is still a
! fairly arbitrary choice. Some have suggested using | instead.
For syntax options which use a list-like syntax (no matter where it
***************
*** 526,541 ****
.. _Javadoc comments:
http://java.sun.com/j2se/javadoc/writingdoccomments/
!
! .. annotations:
http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html
Current Implementation
======================
Guido asked for a voluteer to implement his preferred syntax, and Mark
! Russell stepped up and posted a `patch`_ to SF. The syntax accepted
for 2.4a2 is::
-
@dec2
@dec1
--- 518,532 ----
.. _Javadoc comments:
http://java.sun.com/j2se/javadoc/writingdoccomments/
! .. _annotations:
http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html
+
Current Implementation
======================
Guido asked for a voluteer to implement his preferred syntax, and Mark
! Russell stepped up and posted a `patch`_ to SF. The syntax accepted
for 2.4a2 is::
@dec2
@dec1
***************
*** 543,547 ****
pass
! is equivalent to::
def func(arg1, arg2, ...):
--- 534,538 ----
pass
! This is equivalent to::
def func(arg1, arg2, ...):
***************
*** 551,559 ****
though without the intermediate creation of a variable named ``func``.
- .. _patch: http://www.python.org/sf/979728
-
A `previous patch`_ from Michael Hudson which implements the
list-after-def syntax is also still kicking around.
.. _previous patch: http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar-3.diff
--- 542,549 ----
though without the intermediate creation of a variable named ``func``.
A `previous patch`_ from Michael Hudson which implements the
list-after-def syntax is also still kicking around.
+ .. _patch: http://www.python.org/sf/979728
.. _previous patch: http://starship.python.net/crew/mwh/hacks/meth-syntax-sugar-3.diff
***************
*** 569,575 ****
1. Define a function to be executed at exit. Note that the function
! isn't actually "wrapped" in the usual sense.
!
! ::
def onexit(f):
--- 559,563 ----
1. Define a function to be executed at exit. Note that the function
! isn't actually "wrapped" in the usual sense. ::
def onexit(f):
***************
*** 585,589 ****
disappears enterprising programmers would have to be more creative
to create more instances. (From Shane Hathaway on ``python-dev``.)
-
::
--- 573,576 ----
***************
*** 601,607 ****
3. Add attributes to a function. (Based on an example posted by
! Anders Munch on ``python-dev``.)
!
! ::
def attrs(**kwds):
--- 588,592 ----
3. Add attributes to a function. (Based on an example posted by
! Anders Munch on ``python-dev``.) ::
def attrs(**kwds):
***************
*** 619,625 ****
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):
--- 604,608 ----
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):
***************
*** 651,659 ****
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):
--- 634,638 ----
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`_. ::
def provides(*interfaces):
***************
*** 675,678 ****
--- 654,659 ----
"""Implement something here..."""
+ .. _PyProtocols: http://peak.telecommunity.com/PyProtocols.html
+
Of course, all these examples are possible today, though without
syntactic support.
***************
*** 685,689 ****
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``.
--- 666,670 ----
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``.
More information about the Python-checkins
mailing list