[Python-ideas] Proposal for new-style decorators

[Christophe Schlick]

I am really sorry for splitting the text. My first post was in one
piece but got blocked by the moderators. I didn't want to create some
ridiculous suspense at the end of the first part. Here is the second
part...

---

Part 2 - The new-style syntax for decorators:

Here is the code of the same decorators as in Part 1 above, but the
proposed syntax. The first decorator ('new_style_repeat_fix') is
created without parameters, while the second one
('new_style_repeat_var') uses arguments 'n' and 'trace' with the same
role as previously:

#---
@decorator
def new_style_repeat_fix(self, *args, **keys):
  """docstring for decorating function"""
  print "apply %r on %r" % (self.deco.__name__, self.func.__name__)
  for n in range(3): self.func(*args, **keys)

@decorator(n=3, trace=True)
def new_style_repeat_var(self, *args, **keys):
  """docstring for decorating function"""
  if self.trace:
    print "apply %r on %r" % (self.deco.__name__, self.func.__name__)
  for n in range(self.n): self.func(*args, **keys)
#---

When examining the new-style syntax, one can notice that there are
basically four characteristics that distinguish NSD from OSD:

* Each NSD is decorated by a newly-introduced callable class called
'decorator' (code provided in Part 3) by using one of two possible
decorating forms. The first form '@decorator' is employed for
decorators that do not need any parameter. The second form
'@decorator(arg1=val1, arg2=val2...)' is employed to specify a
sequence of named arguments (combined with their default values) that
are passed to the decorator using the standard notation for keyword
arguments.

* The role of the 'decorator' class is to generate the decorated
function (i.e. the inner nested function with the classic OSD syntax)
and to broadcast it to the decorating function as its first argument
'self'. When the second decorating form is used, all keyword arguments
used in '@decorator(...)' are automatically injected as
meta-attributes in this decorated function 'self'. In the example
above, the two decorator arguments 'n' and 'trace' are available
within the code of 'new_style_repeat_var' as 'self.n' and 'self.trace'
respectively. This mechanism avoids one level of nested functions used
in standard OSD.

* In addition to these decorator arguments, the decorating process
also injects two other meta-attributes in the decorated function:
'self.deco' represents a reference to the decorating function, while
'self.func' represents a reference to the undecorated function. If
there are several chained decorators, the mechanism is made recursive
(more on this later). Note that this implies a slight name
restriction: neither 'deco' nor 'func' can be used as the name of a
parameter passed to the decorator, as this would generate collision in
the corresponding namespace. An alternative might be to consider the
two references as "special" attributes and rename them as
'self.__deco__' and 'self.__func__' respectively. I have no clear
opinion about the pros/cons of the two alternatives.

* Finally, note that each NSD has the same 3-argument signature:
(self, *args, **keys). The first argument 'self' has been explained
above. The two others 'args' and 'keys' respectively represent the set
of positional and keyword arguments, as usual. However, all the values
in either 'args' or 'keys' are not meant to be used by the decorating
function, but always directly passed to the undecorated function. This
means that the statement 'self.func(*args, **keys)' will always appear
somewhere in the code of an NSD. Following this mechanism in the
decorating function avoids the other level of nested functions used in
standard OSD, and guarantees that flat functions are always
sufficient.

Once the NSD have been defined with the new syntax, they can be used
to decorate functions using the standard @-notation, either for single
or multiple decoration. For instance:

#---
@new_style_repeat_fix
def testA(first=0, last=0):
  """docstring for undecorated function"""
  print "testA: first=%s last=%s" % (first, last)

@new_style_repeat_var(n=5) # 'n' is changed, 'trace' keeps default value
def testB(first=0, last=0):
  """docstring for undecorated function"""
  print "testB: first=%s last=%s" % (first, last)

@new_style_repeat_var # both 'n' and 'trace' keep their default values
@new_style_repeat_fix
@new_style_repeat_var(n=5, trace=False) # both 'n' and 'trace' are changed
def testC(first=0, last=0):
  """docstring for undecorated function"""
  print "testC: first=%s last=%s" % (first, last)
#---

When applying a decorator without arguments, or when *all* its
arguments use their default values, the parenthesis after the
decorator name may be dropped. In other words, '@mydeco' and
'@mydeco()' are totally equivalent, whether 'mydeco' takes arguments
or not. This solves a non-symmetric behavior of standard OSD that has
always bothered me: '@old_style_repeat_fix' works but
'@old_style_repeat_fix()' does not, and inversely
'@old_style_repeat_var()' works but '@old_style_repeat_var' does not.

Note also that in the case of chained decorators, each decoration
level stores its own set of parameters, so there is no conflict when
applying the same decorator several times on the same function, as
done with 'new_style_repeat_var' on 'testC'.

Now let's play a bit with some introspection tools:

#---
>>> testA
<function <deco>testA...>

>>> testB
<function <deco>testB...>

>>> testC
<function <deco><deco><deco>testC...>
#---

To explicitely expose the decoration process, a '<deco>' substring is
added as a prefix to the '__name__' attribute for each decorated
function (more precisely, there is one '<deco>' for each level of
decoration, as can be seen with 'testC'). So, each time a '<deco>'
prefix is encountered, the user knows that the reference to the
corresponding undecorated function (resp. decorating function) is
available through the meta-attribute '.func' (resp. '.deco'). When
calling 'help' on a decorated function, this principle is clearly
displayed, and the user can thus easily obtain useful information,
including correct name/signature/docstring:

#---
>>> help(testA)
<deco>testA(*args, **keys)
    use help(testA.func) to get genuine help

>>> testA.func, testA.deco
(<function testA...>, <function new_style_repeat_fix...>)

>>> help(testA.func)
testA(first=0, last=0)
    docstring for undecorated function

>>> help(testA.deco)
new_style_repeat_fix(self, *args, **keys)
    docstring for decorating function
#---

In the case of chained decorators, the same principle holds
recursively. As can be seen in the example below, all information
relative to a multi-decorated function (including all decorator
arguments used at any decoration level) can be easily fetched by
successive applications of the '.func' suffix:

#---
>>> help(testC)
<deco><deco><deco>testC(*args, **keys)
    use help(testC.func.func.func) to get genuine help

>>> testC.func, testC.deco, testC.n, testC.trace
(<function <deco><deco>testC...>, <function new_style_repeat_var...>, 3, True)

>>> testC.func.func, testC.func.deco
(<function <deco>testC...>, <function new_style_repeat_fix...>)

>>> testC.func.func.func, testC.func.func.deco, testC.func.func.n, testC.func.func.trace
(<function testC...>, <function new_style_repeat_var...>, 5, False)

>>> help(testC.func.func.func)
testC(first=0, last=0)
    docstring for undecorated function
#---

------
to be continued in Part 3...

CS