CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 422 – Simpler customisation of class creation | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0422/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 422 – Simpler customisation of class creation | peps.python.org'> <meta property="og:description" content="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."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0422/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="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."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 422</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 422 – Simpler customisation of class creation</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Alyssa Coghlan <ncoghlan at gmail.com>, Daniel Urban <urban.dani+py at gmail.com></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Removed from consideration by sponsor or authors">Withdrawn</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">05-Jun-2012</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.5</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">05-Jun-2012, 10-Feb-2013</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#pep-withdrawal">PEP Withdrawal</a></li> <li><a class="reference internal" href="#background">Background</a></li> <li><a class="reference internal" href="#proposal">Proposal</a></li> <li><a class="reference internal" href="#key-benefits">Key Benefits</a><ul> <li><a class="reference internal" href="#easier-use-of-custom-namespaces-for-a-class">Easier use of custom namespaces for a class</a></li> <li><a class="reference internal" href="#easier-inheritance-of-definition-time-behaviour">Easier inheritance of definition time behaviour</a></li> <li><a class="reference internal" href="#reduced-chance-of-metaclass-conflicts">Reduced chance of metaclass conflicts</a></li> <li><a class="reference internal" href="#integrates-cleanly-with-pep-3135">Integrates cleanly with PEP 3135</a></li> <li><a class="reference internal" href="#replaces-many-use-cases-for-dynamic-setting-of-metaclass">Replaces many use cases for dynamic setting of <code class="docutils literal notranslate">__metaclass__</code></a></li> </ul> </li> <li><a class="reference internal" href="#design-notes">Design Notes</a><ul> <li><a class="reference internal" href="#determining-if-the-class-being-decorated-is-the-base-class">Determining if the class being decorated is the base class</a></li> <li><a class="reference internal" href="#replacing-a-class-with-a-different-kind-of-object">Replacing a class with a different kind of object</a></li> </ul> </li> <li><a class="reference internal" href="#open-questions">Open Questions</a><ul> <li><a class="reference internal" href="#is-the-namespace-concept-worth-the-extra-complexity">Is the <code class="docutils literal notranslate">namespace</code> concept worth the extra complexity?</a></li> </ul> </li> <li><a class="reference internal" href="#new-ways-of-using-classes">New Ways of Using Classes</a><ul> <li><a class="reference internal" href="#order-preserving-classes">Order preserving classes</a></li> <li><a class="reference internal" href="#prepopulated-namespaces">Prepopulated namespaces</a></li> <li><a class="reference internal" href="#cloning-a-prototype-class">Cloning a prototype class</a></li> <li><a class="reference internal" href="#extending-a-class">Extending a class</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-design-options">Rejected Design Options</a><ul> <li><a class="reference internal" href="#calling-autodecorate-from-type-init">Calling <code class="docutils literal notranslate">__autodecorate__</code> from <code class="docutils literal notranslate">type.__init__</code></a></li> <li><a class="reference internal" href="#calling-the-automatic-decoration-hook-init-class">Calling the automatic decoration hook <code class="docutils literal notranslate">__init_class__</code></a></li> <li><a class="reference internal" href="#requiring-an-explicit-decorator-on-autodecorate">Requiring an explicit decorator on <code class="docutils literal notranslate">__autodecorate__</code></a></li> <li><a class="reference internal" href="#making-autodecorate-implicitly-static-like-new">Making <code class="docutils literal notranslate">__autodecorate__</code> implicitly static, like <code class="docutils literal notranslate">__new__</code></a></li> <li><a class="reference internal" href="#passing-in-the-namespace-directly-rather-than-a-factory-function">Passing in the namespace directly rather than a factory function</a></li> </ul> </li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#todo">TODO</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> 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 <code class="docutils literal notranslate">namespace</code> parameter in the class header, and a new <code class="docutils literal notranslate">__autodecorate__</code> 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. </section> <section id="pep-withdrawal"> <h2><a class="toc-backref" href="#pep-withdrawal" role="doc-backlink">PEP Withdrawal</a></h2> This proposal has been withdrawn in favour of Martin Teichmann’s proposal in <a class="pep reference internal" href="../pep-0487/" title="PEP 487 – Simpler customisation of class creation">PEP 487</a>, which achieves the same goals through a simpler, easier to use <code class="docutils literal notranslate">__init_subclass__</code> hook that simply isn’t invoked for the base class that defines the hook. </section> <section id="background"> <h2><a class="toc-backref" href="#background" role="doc-backlink">Background</a></h2> For an already created class <code class="docutils literal notranslate">cls</code>, the term “metaclass” has a clear meaning: it is the value of <code class="docutils literal notranslate">type(cls)</code>. 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: <ul class="simple"> <li>If the metaclass hint refers to an instance of <code class="docutils literal notranslate">type</code>, 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.</li> <li>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 <code class="docutils literal notranslate">type</code>, or, in Python 3.3 or later, <code class="docutils literal notranslate">types.new_class</code>) the actual metaclass is then determined based on the parent classes.</li> </ul> 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 <code class="docutils literal notranslate">metaclass=Meta</code> keyword syntax in the class header. This allows the <code class="docutils literal notranslate">__prepare__</code> method on the metaclass to be used to create the <code class="docutils literal notranslate">locals()</code> namespace used during execution of the class body (for example, specifying the use of <code class="docutils literal notranslate">collections.OrderedDict</code> instead of a regular <code class="docutils literal notranslate">dict</code>). In Python 2, there was no <code class="docutils literal notranslate">__prepare__</code> method (that API was added for Python 3 by <a class="pep reference internal" href="../pep-3115/" title="PEP 3115 – Metaclasses in Python 3000">PEP 3115</a>). Instead, a class body could set the <code class="docutils literal notranslate">__metaclass__</code> attribute, and the class creation process would extract that value from the class namespace to use as the metaclass hint. There is <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2012-June/119878.html">published code</a> that makes use of this feature. Another new feature in Python 3 is the zero-argument form of the <code class="docutils literal notranslate">super()</code> builtin, introduced by <a class="pep reference internal" href="../pep-3135/" title="PEP 3135 – New Super">PEP 3135</a>. This feature uses an implicit <code class="docutils literal notranslate">__class__</code> 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 <code class="docutils literal notranslate">__class__</code> 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. </section> <section id="proposal"> <h2><a class="toc-backref" href="#proposal" role="doc-backlink">Proposal</a></h2> This PEP proposes that a new mechanism to customise class creation be added to Python 3.4 that meets the following criteria: <ol class="arabic simple"> <li>Integrates nicely with class inheritance structures (including mixins and multiple inheritance)</li> <li>Integrates nicely with the implicit <code class="docutils literal notranslate">__class__</code> reference and zero-argument <code class="docutils literal notranslate">super()</code> syntax introduced by <a class="pep reference internal" href="../pep-3135/" title="PEP 3135 – New Super">PEP 3135</a></li> <li>Can be added to an existing base class without a significant risk of introducing backwards compatibility problems</li> <li>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 <code class="docutils literal notranslate">__metaclass__</code> hook</li> </ol> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>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 </pre></div> </div> To simplify the cooperative multiple inheritance case, <code class="docutils literal notranslate">object</code> will gain a default implementation of the hook that returns the class unmodified: <div class="highlight-default notranslate"><div class="highlight"><pre>class object: def __autodecorate__(cls): return cls </pre></div> </div> If a metaclass wishes to block implicit class decoration for some reason, it must arrange for <code class="docutils literal notranslate">cls.__autodecorate__</code> to trigger <code class="docutils literal notranslate">AttributeError</code>. If present on the created object, this new hook will be called by the class creation machinery after the <code class="docutils literal notranslate">__class__</code> reference has been initialised. For <code class="docutils literal notranslate">types.new_class()</code>, it will be called as the last step before returning the created class object. <code class="docutils literal notranslate">__autodecorate__</code> is implicitly converted to a class method when the class is created (prior to the hook being invoked). Note, that when <code class="docutils literal notranslate">__autodecorate__</code> is called, the name of the class is not yet bound to the new class object. As a consequence, the two argument form of <code class="docutils literal notranslate">super()</code> cannot be used to call methods (e.g., <code class="docutils literal notranslate">super(Example, cls)</code> wouldn’t work in the example above). However, the zero argument form of <code class="docutils literal notranslate">super()</code> works as expected, since the <code class="docutils literal notranslate">__class__</code> reference is already initialised. This general proposal is not a new idea (it was first suggested for inclusion in the language definition <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2001-November/018651.html">more than 10 years ago</a>, and a similar mechanism has long been supported by <a class="reference external" href="http://docs.zope.org/zope_secrets/extensionclass.html">Zope’s ExtensionClass</a>), 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 <code class="docutils literal notranslate">__prepare__</code> method in PEP 3115 allows a further enhancement that was not possible in Python 2: this PEP also proposes that <code class="docutils literal notranslate">type.__prepare__</code> be updated to accept a factory function as a <code class="docutils literal notranslate">namespace</code> keyword-only argument. If present, the value provided as the <code class="docutils literal notranslate">namespace</code> argument will be called without arguments to create the result of <code class="docutils literal notranslate">type.__prepare__</code> instead of using a freshly created dictionary instance. For example, the following will use an ordered dictionary as the class namespace: <div class="highlight-default notranslate"><div class="highlight"><pre>class OrderedExample(namespace=collections.OrderedDict): def __autodecorate__(cls): # cls.__dict__ is still a read-only proxy to the class namespace, # but the underlying storage is an OrderedDict instance </pre></div> </div> <div class="admonition note"> Note This PEP, along with the existing ability to use __prepare__ to share a single namespace amongst multiple class objects, highlights a possible issue with the attribute lookup caching: when the underlying mapping is updated by other means, the attribute lookup cache is not invalidated correctly (this is a key part of the reason class <code class="docutils literal notranslate">__dict__</code> attributes produce a read-only view of the underlying storage). Since the optimisation provided by that cache is highly desirable, the use of a preexisting namespace as the class namespace may need to be declared as officially unsupported (since the observed behaviour is rather strange when the caches get out of sync). </div> </section> <section id="key-benefits"> <h2><a class="toc-backref" href="#key-benefits" role="doc-backlink">Key Benefits</a></h2> <section id="easier-use-of-custom-namespaces-for-a-class"> <h3><a class="toc-backref" href="#easier-use-of-custom-namespaces-for-a-class" role="doc-backlink">Easier use of custom namespaces for a class</a></h3> Currently, to use a different type (such as <code class="docutils literal notranslate">collections.OrderedDict</code>) 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. </section> <section id="easier-inheritance-of-definition-time-behaviour"> <h3><a class="toc-backref" href="#easier-inheritance-of-definition-time-behaviour" role="doc-backlink">Easier inheritance of definition time behaviour</a></h3> 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. </section> <section id="reduced-chance-of-metaclass-conflicts"> <h3><a class="toc-backref" href="#reduced-chance-of-metaclass-conflicts" role="doc-backlink">Reduced chance of metaclass conflicts</a></h3> 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 <code class="docutils literal notranslate">__autodecorate__</code> method to an existing type poses a similar level of risk to adding an <code class="docutils literal notranslate">__init__</code> 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 <code class="docutils literal notranslate">__autodecorate__</code>, the risk in this case is actually even lower than in the case of <code class="docutils literal notranslate">__init__</code>. </section> <section id="integrates-cleanly-with-pep-3135"> <h3><a class="toc-backref" href="#integrates-cleanly-with-pep-3135" role="doc-backlink">Integrates cleanly with PEP 3135</a></h3> 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 <code class="docutils literal notranslate">__class__</code> reference introduced by <a class="pep reference internal" href="../pep-3135/" title="PEP 3135 – New Super">PEP 3135</a>, including methods that use the zero argument form of <code class="docutils literal notranslate">super()</code>. </section> <section id="replaces-many-use-cases-for-dynamic-setting-of-metaclass"> <h3><a class="toc-backref" href="#replaces-many-use-cases-for-dynamic-setting-of-metaclass" role="doc-backlink">Replaces many use cases for dynamic setting of <code class="docutils literal notranslate">__metaclass__</code></a></h3> For use cases that don’t involve completely replacing the defined class, Python 2 code that dynamically set <code class="docutils literal notranslate">__metaclass__</code> can now dynamically set <code class="docutils literal notranslate">__autodecorate__</code> 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. </section> </section> <section id="design-notes"> <h2><a class="toc-backref" href="#design-notes" role="doc-backlink">Design Notes</a></h2> <section id="determining-if-the-class-being-decorated-is-the-base-class"> <h3><a class="toc-backref" href="#determining-if-the-class-being-decorated-is-the-base-class" role="doc-backlink">Determining if the class being decorated is the base class</a></h3> In the body of an <code class="docutils literal notranslate">__autodecorate__</code> method, as in any other class method, <code class="docutils literal notranslate">__class__</code> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>class Example: def __autodecorate__(cls): cls = super().__autodecorate__() # Don't process the base class if cls is __class__: return # Process subclasses here ... </pre></div> </div> </section> <section id="replacing-a-class-with-a-different-kind-of-object"> <h3><a class="toc-backref" href="#replacing-a-class-with-a-different-kind-of-object" role="doc-backlink">Replacing a class with a different kind of object</a></h3> As an implicit decorator, <code class="docutils literal notranslate">__autodecorate__</code> is able to relatively easily replace the defined class with a different kind of object. Technically custom metaclasses and even <code class="docutils literal notranslate">__new__</code> methods can already do this implicitly, but the decorator model makes such code much easier to understand and implement. <div class="highlight-default notranslate"><div class="highlight"><pre>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() </pre></div> </div> 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. </section> </section> <section id="open-questions"> <h2><a class="toc-backref" href="#open-questions" role="doc-backlink">Open Questions</a></h2> <section id="is-the-namespace-concept-worth-the-extra-complexity"> <h3><a class="toc-backref" href="#is-the-namespace-concept-worth-the-extra-complexity" role="doc-backlink">Is the <code class="docutils literal notranslate">namespace</code> concept worth the extra complexity?</a></h3> Unlike the new <code class="docutils literal notranslate">__autodecorate__</code> hook the proposed <code class="docutils literal notranslate">namespace</code> 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 <code class="docutils literal notranslate">__prepare__</code> 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 <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2013-June/127103.html">separate proposal</a> 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. <code class="docutils literal notranslate">__definition_order__</code>) 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 <code class="docutils literal notranslate">__autodecorate__</code> hook, leaving the more complex configurable namespace factory idea to a custom metaclass like the one shown below. </section> </section> <section id="new-ways-of-using-classes"> <h2><a class="toc-backref" href="#new-ways-of-using-classes" role="doc-backlink">New Ways of Using Classes</a></h2> The new <code class="docutils literal notranslate">namespace</code> keyword in the class header enables a number of interesting options for controlling the way a class is initialised, including some aspects of the object models of both Javascript and Ruby. All of the examples below are actually possible today through the use of a custom metaclass: <div class="highlight-default notranslate"><div class="highlight"><pre>class CustomNamespace(type): @classmethod def __prepare__(meta, name, bases, *, namespace=None, **kwds): parent_namespace = super().__prepare__(name, bases, **kwds) return namespace() if namespace is not None else parent_namespace def __new__(meta, name, bases, ns, *, namespace=None, **kwds): return super().__new__(meta, name, bases, ns, **kwds) def __init__(cls, name, bases, ns, *, namespace=None, **kwds): return super().__init__(name, bases, ns, **kwds) </pre></div> </div> The advantage of implementing the new keyword directly in <code class="docutils literal notranslate">type.__prepare__</code> is that the only persistent effect is then the change in the underlying storage of the class attributes. The metaclass of the class remains unchanged, eliminating many of the drawbacks typically associated with these kinds of customisations. <section id="order-preserving-classes"> <h3><a class="toc-backref" href="#order-preserving-classes" role="doc-backlink">Order preserving classes</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>class OrderedClass(namespace=collections.OrderedDict): a = 1 b = 2 c = 3 </pre></div> </div> </section> <section id="prepopulated-namespaces"> <h3><a class="toc-backref" href="#prepopulated-namespaces" role="doc-backlink">Prepopulated namespaces</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>seed_data = dict(a=1, b=2, c=3) class PrepopulatedClass(namespace=seed_data.copy): pass </pre></div> </div> </section> <section id="cloning-a-prototype-class"> <h3><a class="toc-backref" href="#cloning-a-prototype-class" role="doc-backlink">Cloning a prototype class</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>class NewClass(namespace=Prototype.__dict__.copy): pass </pre></div> </div> </section> <section id="extending-a-class"> <h3><a class="toc-backref" href="#extending-a-class" role="doc-backlink">Extending a class</a></h3> <div class="admonition note"> Note Just because the PEP makes it possible to do this relatively cleanly doesn’t mean anyone should do this! </div> <div class="highlight-default notranslate"><div class="highlight"><pre>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) </pre></div> </div> </section> </section> <section id="rejected-design-options"> <h2><a class="toc-backref" href="#rejected-design-options" role="doc-backlink">Rejected Design Options</a></h2> <section id="calling-autodecorate-from-type-init"> <h3><a class="toc-backref" href="#calling-autodecorate-from-type-init" role="doc-backlink">Calling <code class="docutils literal notranslate">__autodecorate__</code> from <code class="docutils literal notranslate">type.__init__</code></a></h3> Calling the new hook automatically from <code class="docutils literal notranslate">type.__init__</code>, would achieve most of the goals of this PEP. However, using that approach would mean that <code class="docutils literal notranslate">__autodecorate__</code> implementations would be unable to call any methods that relied on the <code class="docutils literal notranslate">__class__</code> reference (or used the zero-argument form of <code class="docutils literal notranslate">super()</code>), 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. </section> <section id="calling-the-automatic-decoration-hook-init-class"> <h3><a class="toc-backref" href="#calling-the-automatic-decoration-hook-init-class" role="doc-backlink">Calling the automatic decoration hook <code class="docutils literal notranslate">__init_class__</code></a></h3> Earlier versions of the PEP used the name <code class="docutils literal notranslate">__init_class__</code> for the name of the new hook. There were three significant problems with this name: <ul class="simple"> <li>it was hard to remember if the correct spelling was <code class="docutils literal notranslate">__init_class__</code> or <code class="docutils literal notranslate">__class_init__</code></li> <li>the use of “init” in the name suggested the signature should match that of <code class="docutils literal notranslate">type.__init__</code>, which is not the case</li> <li>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</li> </ul> The new name <code class="docutils literal notranslate">__autodecorate__</code> 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 <code class="docutils literal notranslate">__init__</code> method. </section> <section id="requiring-an-explicit-decorator-on-autodecorate"> <h3><a class="toc-backref" href="#requiring-an-explicit-decorator-on-autodecorate" role="doc-backlink">Requiring an explicit decorator on <code class="docutils literal notranslate">__autodecorate__</code></a></h3> Originally, this PEP required the explicit use of <code class="docutils literal notranslate">@classmethod</code> on the <code class="docutils literal notranslate">__autodecorate__</code> 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 <code class="docutils literal notranslate">__prepare__</code> and forgetting the <code class="docutils literal notranslate">@classmethod</code> method decorator is singularly incomprehensible (particularly since <a class="pep reference internal" href="../pep-3115/" title="PEP 3115 – Metaclasses in Python 3000">PEP 3115</a> documents it as an ordinary method, and the current documentation doesn’t explicitly say anything one way or the other). </section> <section id="making-autodecorate-implicitly-static-like-new"> <h3><a class="toc-backref" href="#making-autodecorate-implicitly-static-like-new" role="doc-backlink">Making <code class="docutils literal notranslate">__autodecorate__</code> implicitly static, like <code class="docutils literal notranslate">__new__</code></a></h3> While it accepts the class to be instantiated as the first argument, <code class="docutils literal notranslate">__new__</code> 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 <code class="docutils literal notranslate">__autodecorate__</code> hook, as it would allow <code class="docutils literal notranslate">__autodecorate__</code> 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 <code class="docutils literal notranslate">__new__</code>, there’s no issue with potentially changing method signatures at different points in the inheritance chain. </section> <section id="passing-in-the-namespace-directly-rather-than-a-factory-function"> <h3><a class="toc-backref" href="#passing-in-the-namespace-directly-rather-than-a-factory-function" role="doc-backlink">Passing in the namespace directly rather than a factory function</a></h3> 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. </section> </section> <section id="reference-implementation"> <h2><a class="toc-backref" href="#reference-implementation" role="doc-backlink">Reference Implementation</a></h2> A reference implementation for <code class="docutils literal notranslate">__autodecorate__</code> has been posted to the <a class="reference external" href="http://bugs.python.org/issue17044">issue tracker</a>. It uses the original <code class="docutils literal notranslate">__init_class__</code> naming. does not yet allow the implicit decorator to replace the class with a different object and does not implement the suggested <code class="docutils literal notranslate">namespace</code> parameter for <code class="docutils literal notranslate">type.__prepare__</code>. </section> <section id="todo"> <h2><a class="toc-backref" href="#todo" role="doc-backlink">TODO</a></h2> <ul class="simple"> <li>address the 5 points in <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2013-February/123970.html">https://mail.python.org/pipermail/python-dev/2013-February/123970.html</a></li> </ul> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0422.rst">https://github.com/python/peps/blob/main/peps/pep-0422.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0422.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#pep-withdrawal">PEP Withdrawal</a></li> <li><a class="reference internal" href="#background">Background</a></li> <li><a class="reference internal" href="#proposal">Proposal</a></li> <li><a class="reference internal" href="#key-benefits">Key Benefits</a><ul> <li><a class="reference internal" href="#easier-use-of-custom-namespaces-for-a-class">Easier use of custom namespaces for a class</a></li> <li><a class="reference internal" href="#easier-inheritance-of-definition-time-behaviour">Easier inheritance of definition time behaviour</a></li> <li><a class="reference internal" href="#reduced-chance-of-metaclass-conflicts">Reduced chance of metaclass conflicts</a></li> <li><a class="reference internal" href="#integrates-cleanly-with-pep-3135">Integrates cleanly with PEP 3135</a></li> <li><a class="reference internal" href="#replaces-many-use-cases-for-dynamic-setting-of-metaclass">Replaces many use cases for dynamic setting of <code class="docutils literal notranslate">__metaclass__</code></a></li> </ul> </li> <li><a class="reference internal" href="#design-notes">Design Notes</a><ul> <li><a class="reference internal" href="#determining-if-the-class-being-decorated-is-the-base-class">Determining if the class being decorated is the base class</a></li> <li><a class="reference internal" href="#replacing-a-class-with-a-different-kind-of-object">Replacing a class with a different kind of object</a></li> </ul> </li> <li><a class="reference internal" href="#open-questions">Open Questions</a><ul> <li><a class="reference internal" href="#is-the-namespace-concept-worth-the-extra-complexity">Is the <code class="docutils literal notranslate">namespace</code> concept worth the extra complexity?</a></li> </ul> </li> <li><a class="reference internal" href="#new-ways-of-using-classes">New Ways of Using Classes</a><ul> <li><a class="reference internal" href="#order-preserving-classes">Order preserving classes</a></li> <li><a class="reference internal" href="#prepopulated-namespaces">Prepopulated namespaces</a></li> <li><a class="reference internal" href="#cloning-a-prototype-class">Cloning a prototype class</a></li> <li><a class="reference internal" href="#extending-a-class">Extending a class</a></li> </ul> </li> <li><a class="reference internal" href="#rejected-design-options">Rejected Design Options</a><ul> <li><a class="reference internal" href="#calling-autodecorate-from-type-init">Calling <code class="docutils literal notranslate">__autodecorate__</code> from <code class="docutils literal notranslate">type.__init__</code></a></li> <li><a class="reference internal" href="#calling-the-automatic-decoration-hook-init-class">Calling the automatic decoration hook <code class="docutils literal notranslate">__init_class__</code></a></li> <li><a class="reference internal" href="#requiring-an-explicit-decorator-on-autodecorate">Requiring an explicit decorator on <code class="docutils literal notranslate">__autodecorate__</code></a></li> <li><a class="reference internal" href="#making-autodecorate-implicitly-static-like-new">Making <code class="docutils literal notranslate">__autodecorate__</code> implicitly static, like <code class="docutils literal notranslate">__new__</code></a></li> <li><a class="reference internal" href="#passing-in-the-namespace-directly-rather-than-a-factory-function">Passing in the namespace directly rather than a factory function</a></li> </ul> </li> <li><a class="reference internal" href="#reference-implementation">Reference Implementation</a></li> <li><a class="reference internal" href="#todo">TODO</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0422.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>