PEP 520 – Preserving Class Attribute Definition Order | peps.python.org
PEP 520 – Preserving Class Attribute Definition Order PEP 520 – Preserving Class Attribute Definition Order Author : Eric Snow <ericsnowcurrently at gmail.com> Status : Final Type : Standards Track Created : 07-Jun-2016 Python-Version : 3.6 Post-History : 07-Jun-2016, 11-Jun-2016, 20-Jun-2016, 24-Jun-2016 Resolution : Python-Dev message Table of Contents Abstract Motivation Background Specification Why a tuple? Why not a read-only attribute?
Why not “__attribute_order__”? Why not ignore “dunder” names? Why None instead of an empty tuple? Why None instead of not setting the attribute? Why constrain manually set values? Why not hide __definition_order__ on non-type objects? What about __slots__? Why is __definition_order__ even necessary? Support for C-API Types Compatibility Changes Other Python Implementations Implementation Alternatives An Order-preserving cls.__dict__ A “namespace” Keyword Arg for Class Definition A stdlib Metaclass that Implements __prepare__() with OrderedDict Set __definition_order__ at Compile-time References Copyright Note Since compact dict has landed in 3.6, __definition_order__ has been removed. cls.__dict__ now mostly accomplishes the same thing instead.
Abstract The class definition syntax is ordered by its very nature. Class attributes defined there are thus ordered. Aside from helping with readability, that ordering is sometimes significant. If it were automatically available outside the class definition then the attribute order could be used without the need for extra boilerplate (such as metaclasses or manually enumerating the attribute order). Given that this information already exists, access to the definition order of attributes is a reasonable expectation.
However, currently Python does not preserve the attribute order from the class definition. This PEP changes that by preserving the order in which attributes are introduced in the class definition body. That order will now be preserved in the __definition_order__ attribute of the class. This allows introspection of the original definition order, e.g. by class decorators. Additionally, this PEP requires that the default class definition namespace be ordered (e.g.
OrderedDict ) by default. The long-lived class namespace ( __dict__ ) will remain a dict . Motivation The attribute order from a class definition may be useful to tools that rely on name order. However, without the automatic availability of the definition order, those tools must impose extra requirements on users. For example, use of such a tool may require that your class use a particular metaclass. Such requirements are often enough to discourage use of the tool.
Some tools that could make use of this PEP include: documentation generators testing frameworks CLI frameworks web frameworks config generators data serializers enum factories (my original motivation) Background When a class is defined using a class statement, the class body is executed within a namespace. Currently that namespace defaults to dict . If the metaclass defines __prepare__() then the result of calling it is used for the class definition namespace.
After the execution completes, the definition namespace is copied into a new dict . Then the original definition namespace is discarded. The new copy is stored away as the class’s namespace and is exposed as __dict__ through a read-only proxy. The class attribute definition order is represented by the insertion order of names in the definition namespace. Thus, we can have access to the definition order by switching the definition namespace to an ordered mapping, such as collections.OrderedDict .
This is feasible using a metaclass and __prepare__ , as described above. In fact, exactly this is by far the most common use case for using __prepare__ . At that point, the only missing thing for later access to the definition order is storing it on the class before the definition namespace is thrown away. Again, this may be done using a metaclass. However, this means that the definition order is preserved only for classes that use such a metaclass.
There are two practical problems with that: First, it requires the use of a metaclass. Metaclasses introduce an extra level of complexity to code and in some cases (e.g. conflicts) are a problem. So reducing the need for them is worth doing when the opportunity presents itself. PEP 422 and PEP 487 discuss this at length. We have such an opportunity by using an ordered mapping (e.g. OrderedDict for CPython at least) for the default class definition namespace, virtually eliminating the need for __prepare__() .
Second, only classes that opt in to using the OrderedDict -based metaclass will have access to the definition order. This is problematic for cases where universal access to the definition order is important. Specification Part 1: all classes have a __definition_order__ attribute __definition_order__ is a tuple of identifiers (or None ) __definition_order__ is always set: during execution of the class body, the insertion order of names into the class definition namespace is stored in a tuple if __definition_order__ is defined in the class body then it must be a tuple of identifiers or None ; any other value will result in TypeError classes that do not have a class definition (e.g. builtins) have their __definition_order__ set to None classes for which __prepare__() returned something other than OrderedDict (or a subclass) have their __definition_order__ set to None (except where #2 applies) Not changing: dir() will not depend on __definition_order__ descriptors and custom __getattribute__ methods are unconstrained regarding __definition_order__ Part 2: the default class definition namespace is now an ordered mapping (e.g.
OrderdDict ) cls.__dict__ does not change, remaining a read-only proxy around dict Note that Python implementations which have an ordered dict won’t need to change anything. The following code demonstrates roughly equivalent semantics for both parts 1 and 2: class Meta ( type ): @classmethod def __prepare__ ( cls , * args , ** kwargs ): return OrderedDict () class Spam ( metaclass = Meta ): ham = None eggs = 5 __definition_order__ = tuple ( locals ()) Why a tuple?
Use of a tuple reflects the fact that we are exposing the order in which attributes on the class were defined . Since the definition is already complete by the time __definition_order__ is set, the content and order of the value won’t be changing. Thus we use a type that communicates that state of immutability. Why not a read-only attribute? There are some valid arguments for making __definition_order__ a read-only attribute (like cls.__dict__ is).
Most notably, a read-only attribute conveys the nature of the attribute as “complete”, which is exactly correct for __definition_order__ . Since it represents the state of a particular one-time event (execution of the class definition body), allowing the value to be replaced would reduce confidence that the attribute corresponds to the original class body. Furthermore, often an immutable-by-default approach helps to make data easier to reason about.
However, in this case there still isn’t a strong reason to counter the well-worn precedent found in Python. Per Guido: I don 't see why it needs to be a read-only attribute. There are very few of those -- in general we let users play around with things unless we have a hard reason to restrict assignment ( e . g . the interpreter 's internal state could be compromised). I don' t see such a hard reason here . Also, note that a writeable __definition_order__ allows dynamically created classes (e.g. by Cython) to still have __definition_order__ properly set.
That could certainly be handled through specific class-creation tools, such as type() or the C-API, without the need to lose the semantics of a read-only attribute. However, with a writeable attribute it’s a moot point. Why not “__attribute_order__”? __definition_order__ is centered on the class d
The rest of this page is on the live site.