diff --git a/pep-0520.txt b/pep-0520.txt index 8113b47c6..65a5b6e4b 100644 --- a/pep-0520.txt +++ b/pep-0520.txt @@ -61,19 +61,21 @@ Specification * the order in which class attributes are defined is preserved in the new ``__definition_order__`` attribute on each class * "dunder" attributes (e.g. ``__init__``, ``__module__``) are ignored -* ``__definition_order__`` is a tuple +* ``__definition_order__`` is a ``tuple`` (or ``None``) * ``__definition_order__`` is a read-only attribute * ``__definition_order__`` is always set: - 1. if ``__definition_order__`` is defined in the class body then the - value is used as-is, though the attribute will still be read-only + 1. 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`` 2. classes that do not have a class definition (e.g. builtins) have their ``__definition_order__`` set to ``None`` 3. classes for which `__prepare__()`` returned something other than ``OrderedDict`` (or a subclass) have their ``__definition_order__`` set to ``None`` (except where #1 applies) -The following code demonstrates roughly equivalent semantics:: +The following code demonstrates roughly equivalent semantics for the +default behavior:: class Meta(type): def __prepare__(cls, *args, **kwargs): @@ -115,7 +117,8 @@ unlikely and furthermore it is usually best to go immutable-by-default. Note that ``__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 supporting feature. +be a significantly misleading name for a feature focused on more than +class definition. See [nick_concern_] for more discussion. @@ -127,6 +130,32 @@ 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 for everyone. +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 distinquish +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. + Why is __definition_order__ even necessary? -------------------------------------------