Easier use of custom namespaces for a class

Currently, to use a different type (such as collections.OrderedDict) for a class namespace, or to use a pre-populated namespace, it is necessary to write and use a custom metaclass. With this PEP, using a custom namespace becomes as simple as specifying an appropriate factory function in the class header.

Easier inheritance of definition time behaviour

Understanding Python's metaclasses requires a deep understanding of the type system and the class construction process. This is legitimately seen as challenging, due to the need to keep multiple moving parts (the code, the metaclass hint, the actual metaclass, the class object, instances of the class object) clearly distinct in your mind. Even when you know the rules, it's still easy to make a mistake if you're not being extremely careful. An earlier version of this PEP actually included such a mistake: it stated "subclass of type" for a constraint that is actually "instance of type".

Understanding the proposed implicit class decoration hook only requires understanding decorators and ordinary method inheritance, which isn't quite as daunting a task. The new hook provides a more gradual path towards understanding all of the phases involved in the class definition process.

Reduced chance of metaclass conflicts

One of the big issues that makes library authors reluctant to use metaclasses (even when they would be appropriate) is the risk of metaclass conflicts. These occur whenever two unrelated metaclasses are used by the desired parents of a class definition. This risk also makes it very difficult to add a metaclass to a class that has previously been published without one.

By contrast, adding an __autodecorate__ method to an existing type poses a similar level of risk to adding an __init__ method: technically, there is a risk of breaking poorly implemented subclasses, but when that occurs, it is recognised as a bug in the subclass rather than the library author breaching backwards compatibility guarantees. In fact, due to the constrained signature of __autodecorate__, the risk in this case is actually even lower than in the case of __init__.

Integrates cleanly with PEP 3135

Unlike code that runs as part of the metaclass, code that runs as part of the new hook will be able to freely invoke class methods that rely on the implicit __class__ reference introduced by PEP 3135, including methods that use the zero argument form of super().

Replaces many use cases for dynamic setting of __metaclass__

For use cases that don't involve completely replacing the defined class, Python 2 code that dynamically set __metaclass__ can now dynamically set __autodecorate__ instead. For more advanced use cases, introduction of an explicit metaclass (possibly made available as a required base class) will still be necessary in order to support Python 3.

Determining if the class being decorated is the base class

In the body of an __autodecorate__ method, as in any other class method, __class__ will be bound to the class declaring the method, while the value passed in may be a subclass.

This makes it relatively straightforward to skip processing the base class if necessary:

class Example:
    def __autodecorate__(cls):
        cls = super().__autodecorate__()
        # Don't process the base class
        if cls is __class__:
            return
        # Process subclasses here
        ...

Replacing a class with a different kind of object

As an implicit decorator, __autodecorate__ is able to relatively easily replace the defined class with a different kind of object. Technically custom metaclasses and even __new__ methods can already do this implicitly, but the decorator model makes such code much easier to understand and implement.

class BuildDict:
    def __autodecorate__(cls):
        cls = super().__autodecorate__()
        # Don't process the base class
        if cls is __class__:
            return
        # Convert subclasses to ordinary dictionaries
        return cls.__dict__.copy()

It's not clear why anyone would ever do this implicitly based on inheritance rather than just using an explicit decorator, but the possibility seems worth noting.

Is the namespace concept worth the extra complexity?

Unlike the new __autodecorate__ hook the proposed namespace keyword argument is not automatically inherited by subclasses. Given the way this proposal is currently written , the only way to get a special namespace used consistently in subclasses is still to write a custom metaclass with a suitable __prepare__ implementation.

Changing the custom namespace factory to also be inherited would significantly increase the complexity of this proposal, and introduce a number of the same potential base class conflict issues as arise with the use of custom metaclasses.

Eric Snow has put forward a separate proposal to instead make the execution namespace for class bodies an ordered dictionary by default, and capture the class attribute definition order for future reference as an attribute (e.g. __definition_order__) on the class object.

Eric's suggested approach may be a better choice for a new default behaviour for type that combines well with the proposed __autodecorate__ hook, leaving the more complex configurable namespace factory idea to a custom metaclass like the one shown below.

Order preserving classes

class OrderedClass(namespace=collections.OrderedDict):
    a = 1
    b = 2
    c = 3

Prepopulated namespaces

seed_data = dict(a=1, b=2, c=3)
class PrepopulatedClass(namespace=seed_data.copy):
    pass

Cloning a prototype class

class NewClass(namespace=Prototype.__dict__.copy):
    pass

Extending a class

from collections import MutableMapping

# The MutableMapping + dict combination should give something that
# generally behaves correctly as a mapping, while still being accepted
# as a class namespace
class ClassNamespace(MutableMapping, dict):
    def __init__(self, cls):
        self._cls = cls
    def __len__(self):
        return len(dir(self._cls))
    def __iter__(self):
        for attr in dir(self._cls):
            yield attr
    def __contains__(self, attr):
        return hasattr(self._cls, attr)
    def __getitem__(self, attr):
        return getattr(self._cls, attr)
    def __setitem__(self, attr, value):
        setattr(self._cls, attr, value)
    def __delitem__(self, attr):
        delattr(self._cls, attr)

def extend(cls):
    return lambda: ClassNamespace(cls)

class Example:
    pass

class ExtendedExample(namespace=extend(Example)):
    a = 1
    b = 2
    c = 3

>>> Example.a, Example.b, Example.c
(1, 2, 3)

Calling __autodecorate__ from type.__init__

Calling the new hook automatically from type.__init__, would achieve most of the goals of this PEP. However, using that approach would mean that __autodecorate__ implementations would be unable to call any methods that relied on the __class__ reference (or used the zero-argument form of super()), and could not make use of those features themselves.

The current design instead ensures that the implicit decorator hook is able to do anything an explicit decorator can do by running it after the initial class creation is already complete.

Calling the automatic decoration hook __init_class__

Earlier versions of the PEP used the name __init_class__ for the name of the new hook. There were three significant problems with this name:

• it was hard to remember if the correct spelling was __init_class__ or __class_init__
• the use of "init" in the name suggested the signature should match that of type.__init__, which is not the case
• the use of "init" in the name suggested the method would be run as part of initial class object creation, which is not the case

The new name __autodecorate__ was chosen to make it clear that the new initialisation hook is most usefully thought of as an implicitly invoked class decorator, rather than as being like an __init__ method.

Requiring an explicit decorator on __autodecorate__

Originally, this PEP required the explicit use of @classmethod on the __autodecorate__ decorator. It was made implicit since there's no sensible interpretation for leaving it out, and that case would need to be detected anyway in order to give a useful error message.

This decision was reinforced after noticing that the user experience of defining __prepare__ and forgetting the @classmethod method decorator is singularly incomprehensible (particularly since PEP 3115 documents it as an ordinary method, and the current documentation doesn't explicitly say anything one way or the other).

Making __autodecorate__ implicitly static, like __new__

While it accepts the class to be instantiated as the first argument, __new__ is actually implicitly treated as a static method rather than as a class method. This allows it to be readily extracted from its defining class and called directly on a subclass, rather than being coupled to the class object it is retrieved from.

Such behaviour initially appears to be potentially useful for the new __autodecorate__ hook, as it would allow __autodecorate__ methods to readily be used as explicit decorators on other classes.

However, that apparent support would be an illusion as it would only work correctly if invoked on a subclass, in which case the method can just as readily be retrieved from the subclass and called that way. Unlike __new__, there's no issue with potentially changing method signatures at different points in the inheritance chain.

Passing in the namespace directly rather than a factory function

At one point, this PEP proposed that the class namespace be passed directly as a keyword argument, rather than passing a factory function. However, this encourages an unsupported behaviour (that is, passing the same namespace to multiple classes, or retaining direct write access to a mapping used as a class namespace), so the API was switched to the factory function version.