[3.10] bpo-44242: [Enum] remove missing bits test from Flag creation (GH-26586) (GH-26635)
Move the check for missing named flags in flag aliases from Flag creation
to a new *verify* decorator..
(cherry picked from commit eea8148b7dff5ffc7b84433859ac819b1d92a74d)
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 137fe50..2d19ef6 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -28,8 +28,8 @@
* 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 @@
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 @@
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 @@
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,6 +645,7 @@
>>> KeepFlag(2**2 + 2**4)
KeepFlag.BLUE|0x10
+.. versionadded:: 3.10
Utilites and Decorators
-----------------------
@@ -627,3 +698,11 @@
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