[Python-checkins] peps: Add stricter constraints to manually set __definition_order__.

Sat Jun 11 22:26:32 EDT 2016

https://hg.python.org/peps/rev/53d1281bd9da
changeset: 6369:53d1281bd9da
user: Eric Snow <ericsnowcurrently at gmail.com>
date: Sat Jun 11 20:22:50 2016 -0600
summary:
 Add stricter constraints to manually set __definition_order__.
files:
 pep-0520.txt | 39 ++++++++++++++++++++++++++++++++++-----
 1 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/pep-0520.txt b/pep-0520.txt
--- a/pep-0520.txt
+++ b/pep-0520.txt
@@ -61,19 +61,21 @@
 * 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 @@
 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 @@
 ``__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?
 -------------------------------------------
 
-- 
Repository URL: https://hg.python.org/peps
