bpo-44242: [Enum] remove missing bits test from Flag creation (GH-26586)

Move the check for missing named flags in flag aliases from Flag creation
to a new *verify* decorator.

1 files changed, 82 insertions, 4 deletions

diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index d9b06fb..e1263f1 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -28,8 +28,8 @@ An enumeration:
 
 * is a set of symbolic names (members) bound to unique values
 * can be iterated over to return its members in definition order
-* uses :meth:`call` syntax to return members by value
-* uses :meth:`index` syntax to return members by name
+* uses *call* syntax to return members by value
+* uses *index* syntax to return members by name
 
 Enumerations are created either by using the :keyword:`class` syntax, or by
 using function-call syntax::
@@ -91,6 +91,12 @@ Module Contents
       the bitwise operators without losing their :class:`IntFlag` membership.
       :class:`IntFlag` members are also subclasses of :class:`int`.
 
+   :class:`EnumCheck`
+
+      An enumeration with the values ``CONTINUOUS``, ``NAMED_FLAGS``, and
+      ``UNIQUE``, for use with :func:`verify` to ensure various constraints
+      are met by a given enumeration.
+
    :class:`FlagBoundary`
 
       An enumeration with the values ``STRICT``, ``CONFORM``, ``EJECT``, and
@@ -117,9 +123,14 @@ Module Contents
 
       Enum class decorator that ensures only one name is bound to any one value.
 
+   :func:`verify`
+
+      Enum class decorator that checks user-selectable constraints on an
+      enumeration.
+
 
 .. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
-.. versionadded:: 3.10  ``StrEnum``
+.. versionadded:: 3.10  ``StrEnum``, ``EnumCheck``, ``FlagBoundary``
 
 
 Data Types
@@ -514,6 +525,65 @@ Data Types
    Using :class:`auto` with :class:`IntFlag` results in integers that are powers
    of two, starting with ``1``.
 
+.. class:: EnumCheck
+
+   *EnumCheck* contains the options used by the :func:`verify` decorator to ensure
+   various constraints; failed constraints result in a :exc:`TypeError`.
+
+   .. attribute:: UNIQUE
+
+      Ensure that each value has only one name::
+
+         >>> from enum import Enum, verify, UNIQUE
+         >>> @verify(UNIQUE)
+         ... class Color(Enum):
+         ...     RED = 1
+         ...     GREEN = 2
+         ...     BLUE = 3
+         ...     CRIMSON = 1
+         Traceback (most recent call last):
+         ...
+         ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED
+
+
+   .. attribute:: CONTINUOUS
+
+      Ensure that there are no missing values between the lowest-valued member
+      and the highest-valued member::
+
+         >>> from enum import Enum, verify, CONTINUOUS
+         >>> @verify(CONTINUOUS)
+         ... class Color(Enum):
+         ...     RED = 1
+         ...     GREEN = 2
+         ...     BLUE = 5
+         Traceback (most recent call last):
+         ...
+         ValueError: invalid enum 'Color': missing values 3, 4
+
+   .. attribute:: NAMED_FLAGS
+
+      Ensure that any flag groups/masks contain only named flags -- useful when
+      values are specified instead of being generated by :func:`auto`
+
+         >>> from enum import Flag, verify, NAMED_FLAGS
+         >>> @verify(NAMED_FLAGS)
+         ... class Color(Flag):
+         ...     RED = 1
+         ...     GREEN = 2
+         ...     BLUE = 4
+         ...     WHITE = 15
+         ...     NEON = 31
+         Traceback (most recent call last):
+         ...
+         ValueError: invalid Flag 'Color': 'WHITE' is missing a named flag for value 8; 'NEON' is missing named flags for values 8, 16
+
+.. note::
+
+   CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members.
+
+.. versionadded:: 3.10
+
 .. class:: FlagBoundary
 
    *FlagBoundary* controls how out-of-range values are handled in *Flag* and its
@@ -575,7 +645,7 @@ Data Types
          >>> KeepFlag(2**2 + 2**4)
          KeepFlag.BLUE|0x10
 
-.. versionadded:: 3.10  ``FlagBoundary``
+.. versionadded:: 3.10
 
 
 Utilites and Decorators
@@ -632,3 +702,11 @@ Utilites and Decorators
       Traceback (most recent call last):
       ...
       ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
+
+.. decorator:: verify
+
+   A :keyword:`class` decorator specifically for enumerations.  Members from
+   :class:`EnumCheck` are used to specify which constraints should be checked
+   on the decorated enumeration.
+
+.. versionadded:: 3.10