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 definition body. The use cases for dealing with the class namespace (__dict__) post-definition are a separate matter. __definition_order__ would be a significantly misleading name for a feature focused on more than class definition.

Why not ignore “dunder” names?

Names starting and ending with “__” are reserved for use by the interpreter. In practice they should not be relevant to the users of __definition_order__. Instead, for nearly everyone they would only be clutter, causing the same extra work (filtering out the dunder names) for the majority. In cases where a dunder name is significant, the class definition could manually set __definition_order__, making the common case simpler.

However, leaving dunder names out of __definition_order__ means that their place in the definition order would be unrecoverably lost. Dropping dunder names by default may inadvertently cause problems for classes that use dunder names unconventionally. In this case it’s better to play it safe and preserve all the names from the class definition. This isn’t a big problem since it is easy to filter out dunder names:

(name for name in cls.__definition_order__
      if not (name.startswith('__') and name.endswith('__')))

In fact, in some application contexts there may be other criteria on which similar filtering would be applied, such as ignoring any name starting with “_”, leaving out all methods, or including only descriptors. Ultimately dunder names aren’t a special enough case to be treated exceptionally.

Note that a couple of dunder names (__name__ and __qualname__) are injected by default by the compiler. So they will be included even though they are not strictly part of the class definition body.

Why None instead of an empty tuple?

A key objective of adding __definition_order__ is to preserve information in class definitions which was lost prior to this PEP. One consequence is that __definition_order__ implies an original class definition. Using None allows us to clearly distinguish classes that do not have a definition order. An empty tuple clearly indicates a class that came from a definition statement but did not define any attributes there.

Why None instead of not setting the attribute?

The absence of an attribute requires more complex handling than None does for consumers of __definition_order__.

Why constrain manually set values?

If __definition_order__ is manually set in the class body then it will be used. We require it to be a tuple of identifiers (or None) so that consumers of __definition_order__ may have a consistent expectation for the value. That helps maximize the feature’s usefulness.

We could also allow an arbitrary iterable for a manually set __definition_order__ and convert it into a tuple. However, not all iterables infer a definition order (e.g. set). So we opt in favor of requiring a tuple.

Why not hide __definition_order__ on non-type objects?

Python doesn’t make much effort to hide class-specific attributes during lookup on instances of classes. While it may make sense to consider __definition_order__ a class-only attribute, hidden during lookup on objects, setting precedent in that regard is beyond the goals of this PEP.

What about __slots__?

__slots__ will be added to __definition_order__ like any other name in the class definition body. The actual slot names will not be added to __definition_order__ since they aren’t set as names in the definition namespace.

Why is __definition_order__ even necessary?

Since the definition order is not preserved in __dict__, it is lost once class definition execution completes. Classes could explicitly set the attribute as the last thing in the body. However, then independent decorators could only make use of classes that had done so. Instead, __definition_order__ preserves this one bit of info from the class body so that it is universally available.

An Order-preserving cls.__dict__

Instead of storing the definition order in __definition_order__, the now-ordered definition namespace could be copied into a new OrderedDict. This would then be used as the mapping proxied as __dict__. Doing so would mostly provide the same semantics.

However, using OrderedDict for __dict__ would obscure the relationship with the definition namespace, making it less useful.

Additionally, (in the case of OrderedDict specifically) doing this would require significant changes to the semantics of the concrete dict C-API.

There has been some discussion about moving to a compact dict implementation which would (mostly) preserve insertion order. However the lack of an explicit __definition_order__ would still remain as a pain point.

A “namespace” Keyword Arg for Class Definition

PEP 422 introduced a new “namespace” keyword arg to class definitions that effectively replaces the need to __prepare__(). [pep422] However, the proposal was withdrawn in favor of the simpler PEP 487.

A stdlib Metaclass that Implements __prepare__() with OrderedDict

This has all the same problems as writing your own metaclass. The only advantage is that you don’t have to actually write this metaclass. So it doesn’t offer any benefit in the context of this PEP.

Set __definition_order__ at Compile-time

Each class’s __qualname__ is determined at compile-time. This same concept could be applied to __definition_order__. The result of composing __definition_order__ at compile-time would be nearly the same as doing so at run-time.

Comparative implementation difficulty aside, the key difference would be that at compile-time it would not be practical to preserve definition order for attributes that are set dynamically in the class body (e.g. locals()[name] = value). However, they should still be reflected in the definition order. One possible resolution would be to require class authors to manually set __definition_order__ if they define any class attributes dynamically.

Ultimately, the use of OrderedDict at run-time or compile-time discovery is almost entirely an implementation detail.