PEP 422 – Simpler customisation of class creation | peps.python.org
PEP 422 – Simpler customisation of class creation PEP 422 – Simpler customisation of class creation Author : Alyssa Coghlan <ncoghlan at gmail.com>, Daniel Urban <urban.dani+py at gmail.com> Status : Withdrawn Type : Standards Track Created : 05-Jun-2012 Python-Version : 3.5 Post-History : 05-Jun-2012, 10-Feb-2013 Table of Contents Abstract PEP Withdrawal Background Proposal Key Benefits Easier use of custom namespaces for a class Easier inheritance of definition time behaviour Reduced chance of metaclass conflicts Integrates cleanly with PEP 3135 Replaces many use cases for dynamic setting of __metaclass__ Design Notes Determining if the class being decorated is the base class Replacing a class with a different kind of object Open Questions Is the namespace concept worth the extra complexity?
New Ways of Using Classes Order preserving classes Prepopulated namespaces Cloning a prototype class Extending a class Rejected Design Options Calling __autodecorate__ from type.__init__ Calling the automatic decoration hook __init_class__ Requiring an explicit decorator on __autodecorate__ Making __autodecorate__ implicitly static, like __new__ Passing in the namespace directly rather than a factory function Reference Implementation TODO Copyright Abstract Currently, customising class creation requires the use of a custom metaclass.
This custom metaclass then persists for the entire lifecycle of the class, creating the potential for spurious metaclass conflicts. This PEP proposes to instead support a wide range of customisation scenarios through a new namespace parameter in the class header, and a new __autodecorate__ hook in the class body. The new mechanism should be easier to understand and use than implementing a custom metaclass, and thus should provide a gentler introduction to the full power Python’s metaclass machinery.
PEP Withdrawal This proposal has been withdrawn in favour of Martin Teichmann’s proposal in PEP 487 , which achieves the same goals through a simpler, easier to use __init_subclass__ hook that simply isn’t invoked for the base class that defines the hook. Background For an already created class cls , the term “metaclass” has a clear meaning: it is the value of type(cls) . During class creation, it has another meaning: it is also used to refer to the metaclass hint that may be provided as part of the class definition.
While in many cases these two meanings end up referring to one and the same object, there are two situations where that is not the case: If the metaclass hint refers to an instance of type , then it is considered as a candidate metaclass along with the metaclasses of all of the parents of the class being defined. If a more appropriate metaclass is found amongst the candidates, then it will be used instead of the one given in the metaclass hint.
Otherwise, an explicit metaclass hint is assumed to be a factory function and is called directly to create the class object. In this case, the final metaclass will be determined by the factory function definition. In the typical case (where the factory functions just calls type , or, in Python 3.3 or later, types.new_class ) the actual metaclass is then determined based on the parent classes. It is notable that only the actual metaclass is inherited - a factory function used as a metaclass hook sees only the class currently being defined, and is not invoked for any subclasses.
In Python 3, the metaclass hint is provided using the metaclass=Meta keyword syntax in the class header. This allows the __prepare__ method on the metaclass to be used to create the locals() namespace used during execution of the class body (for example, specifying the use of collections.OrderedDict instead of a regular dict ). In Python 2, there was no __prepare__ method (that API was added for Python 3 by PEP 3115 ).
Instead, a class body could set the __metaclass__ attribute, and the class creation process would extract that value from the class namespace to use as the metaclass hint. There is published code that makes use of this feature. Another new feature in Python 3 is the zero-argument form of the super() builtin, introduced by PEP 3135 . This feature uses an implicit __class__ reference to the class being defined to replace the “by name” references required in Python 2.
Just as code invoked during execution of a Python 2 metaclass could not call methods that referenced the class by name (as the name had not yet been bound in the containing scope), similarly, Python 3 metaclasses cannot call methods that rely on the implicit __class__ reference (as it is not populated until after the metaclass has returned control to the class creation machinery). Finally, when a class uses a custom metaclass, it can pose additional challenges to the use of multiple inheritance, as a new class cannot inherit from parent classes with unrelated metaclasses.
This means that it is impossible to add a metaclass to an already published class: such an addition is a backwards incompatible change due to the risk of metaclass conflicts. Proposal This PEP proposes that a new mechanism to customise class creation be added to Python 3.4 that meets the following criteria: Integrates nicely with class inheritance structures (including mixins and multiple inheritance) Integrates nicely with the implicit __class__ reference and zero-argument super() syntax introduced by PEP 3135 Can be added to an existing base class without a significant risk of introducing backwards compatibility problems Restores the ability for class namespaces to have some influence on the class creation process (above and beyond populating the namespace itself), but potentially without the full flexibility of the Python 2 style __metaclass__ hook One mechanism that can achieve this goal is to add a new implicit class decoration hook, modelled directly on the existing explicit class decorators, but defined in the class body or in a parent class, rather than being part of the class definition header.
Specifically, it is proposed that class definitions be able to provide a class initialisation hook as follows: class Example : def __autodecorate__ ( cls ): # This is invoked after the class is created, but before any # explicit decorators are called # The usual super() mechanisms are used to correctly support # multiple inheritance. The class decorator style signature helps # ensure that invoking the parent class is as simple as possible. cls = super () . __autodecorate__ () return cls To simplify the cooperative multiple inheritance case, object will gain a default implementation of the hook that returns the class unmodified: class object : def __autodecorate__ ( cls ): return cls If a metaclass wishes to block implicit class decoration for some reason, it must arrange for cls.__autodecorate__ to trigger AttributeError .
If present on the created object, this new hook will be called by the class creation machinery after the __class__ reference has been initialised. For types.new_class() , it will be called as the last step before returning the created class object. __autodecorate__ is implicitly converted to a class method when the class is created (prior to the hook being invoked). Note, that when __autodecorate__ is called, the name of the class is not yet bound to the new class object.
As a consequence, the two argument form of super() cannot be used to call methods (e.g., super(Example, cls) wouldn’t work in the example above). However, the zero argument form of super() works as expected, since the __class__ reference is already initialised. This general proposal is not a new idea (it was first suggested for inclusion in the language definition more than 10 years ago , and a similar mechanism has long been supported by Zope’s ExtensionClass ), but the situation has changed sufficiently in recent years that the idea is worth reconsidering for inclusion as a native language feature.
In addition, the introduction of the metaclass __prepare__
The rest of this page is on the live site.