169 lines
5.2 KiB
Plaintext
169 lines
5.2 KiB
Plaintext
PEP: 422
|
||
Title: Dynamic class decorators
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: Nick Coghlan <ncoghlan@gmail.com>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 5-Jun-2012
|
||
Post-History: 5-Jun-2012
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
Classes currently support two mechanisms for modification of the class at
|
||
definition time: metaclasses and lexical decorators.
|
||
|
||
Metaclasses can be awkward and challenging to use correctly in conjunction
|
||
with multiple inheritance and lexical decorators don't interact with class
|
||
inheritance at all.
|
||
|
||
This PEP proposes a new mechanism for dynamic class decoration that
|
||
interacts more cleanly with class inheritance mechanisms.
|
||
|
||
|
||
Specification
|
||
=============
|
||
|
||
This PEP proposes that a new step be added to the class creation process,
|
||
after the metaclass invocation to construct the class instance and before
|
||
the application of lexical decorators.
|
||
|
||
This step will walk the class MRO in reverse order, looking for
|
||
``__decorators__`` entries in each class dictionary. These entries are
|
||
expected to be iterables that are also walked in reverse order to retrieve
|
||
class decorators that are automatically applied to the class being defined::
|
||
|
||
for entry in reversed(cls.mro()):
|
||
decorators = entry.__dict__.get("__decorators__", ())
|
||
for deco in reversed(decorators):
|
||
cls = deco(cls)
|
||
|
||
This step in the class creation process will be an implicit part of the
|
||
class statement and also part of the behaviour of ``types.new_class()``.
|
||
|
||
|
||
Rationale
|
||
=========
|
||
|
||
When decorator support was added to classes, the lexical decoration syntax
|
||
was copied directly from function decorators::
|
||
|
||
@decorator
|
||
class Example:
|
||
# Subclasses will not be decorated automatically
|
||
pass
|
||
|
||
This mechanism works well, so long as it is considered acceptable that the
|
||
decorator is *not* applied automatically to any subclasses. If it is
|
||
desired that the behaviour be inherited, it is currently necessary to
|
||
make the step up to defining a `custom metaclass`_::
|
||
|
||
class DynamicDecorators(type):
|
||
"""Metaclass for dynamic decorator support
|
||
|
||
Creates the class normally, then runs through the MRO looking for
|
||
__decorators__ attributes and applying the contained decorators to
|
||
the newly created class
|
||
"""
|
||
def __new__(meta, name, bases, ns):
|
||
cls = super(DynamicDecorators, meta).__new__(meta, name, bases, ns)
|
||
for entry in reversed(cls.mro()):
|
||
decorators = entry.__dict__.get("__decorators__", ())
|
||
for deco in reversed(decorators):
|
||
cls = deco(cls)
|
||
return cls
|
||
|
||
class Example(metaclass=DynamicDecorators):
|
||
# Subclasses *will* be decorated automatically
|
||
__decorators__ = [decorator]
|
||
|
||
The main potential problem with this approach, is that it can place
|
||
significant constraints on the type heirarchy, as it requires that all
|
||
metaclasses used be well behaved with respect to multiple inheritance.
|
||
|
||
By making dynamic decorators an inherent part of the class creation process,
|
||
many current use cases of metaclasses may be replaced with dynamic decorators
|
||
instead, greatly reducing the likelihood of metaclass conflicts, as well
|
||
as being substantially easier to write correctly in the first place.
|
||
|
||
|
||
Design Discussion
|
||
=================
|
||
|
||
|
||
Allowing metaclasses to override the dynamic decoration process
|
||
---------------------------------------------------------------
|
||
|
||
This PEP does not provide a mechanism that allows metaclasses to override the
|
||
dynamic decoration process. If this feature is deemed desirable in the
|
||
future, then it can be added by moving the functionality described in
|
||
this PEP into a new method on the metaclass (for example, ``__decorate__``),
|
||
with ``type`` providing a suitable default implementation that matches
|
||
the behaviour described here.
|
||
|
||
This PEP chose the simplicity of the current approach, as lexical decorators
|
||
are currently outside the scope of metaclass control, so it seems reasonable
|
||
to pursue the simpler strategy in the absence of a solid use case for
|
||
making this behaviour configurable.
|
||
|
||
|
||
Iterating over decorator entries in reverse order
|
||
-------------------------------------------------
|
||
|
||
This order was chosen to match the layout of lexical decorators when
|
||
converted to ordinary function calls. Just as the following are equivalent::
|
||
|
||
@deco2
|
||
@deco1
|
||
class C:
|
||
pass
|
||
|
||
class C:
|
||
pass
|
||
C = deco2(deco1(C))
|
||
|
||
So too will the following be roughly equivalent (aside from inheritance)::
|
||
|
||
class C:
|
||
__decorators__ = [deco2, deco1]
|
||
|
||
class C:
|
||
pass
|
||
C = deco2(deco1(C))
|
||
|
||
|
||
Iterating over the MRO in reverse order
|
||
---------------------------------------
|
||
|
||
The order of iteration over the MRO for decorator application was chosen to
|
||
match the order of actual call *evaluation* when using ``super`` to invoke
|
||
parent class implementations: the first method to run to completion is that
|
||
closest to the base of the class hierarchy.
|
||
|
||
|
||
References
|
||
==========
|
||
|
||
.. _custom metaclass:
|
||
https://bitbucket.org/ncoghlan/misc/src/default/pep422.py
|
||
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
coding: utf-8
|
||
End:
|
||
|