gh-103365: [Enum] STRICT boundary corrections (GH-103494)

STRICT boundary:

- fix bitwise operations
- make default for Flag
(cherry picked from commit 2194071)

Co-authored-by: Ethan Furman <[email protected]>

Author: miss-islington

Doc/library/enum.rst

@@ -692,7 +692,8 @@ Data Types
 
    .. attribute:: STRICT
 
-      Out-of-range values cause a :exc:`ValueError` to be raised::
+      Out-of-range values cause a :exc:`ValueError` to be raised. This is the
+      default for :class:`Flag`::
 
          >>> from enum import Flag, STRICT, auto
          >>> class StrictFlag(Flag, boundary=STRICT):
@@ -709,7 +710,7 @@ Data Types
    .. attribute:: CONFORM
 
       Out-of-range values have invalid values removed, leaving a valid *Flag*
-      value. This is the default for :class:`Flag`::
+      value::
 
          >>> from enum import Flag, CONFORM, auto
          >>> class ConformFlag(Flag, boundary=CONFORM):

Lib/enum.py

@@ -273,6 +273,13 @@ def __set_name__(self, enum_class, member_name):
         enum_member.__objclass__ = enum_class
         enum_member.__init__(*args)
         enum_member._sort_order_ = len(enum_class._member_names_)
+
+        if Flag is not None and issubclass(enum_class, Flag):
+            enum_class._flag_mask_ |= value
+            if _is_single_bit(value):
+                enum_class._singles_mask_ |= value
+            enum_class._all_bits_ = 2 ** ((enum_class._flag_mask_).bit_length()) - 1
+
         # If another member with the same value was already defined, the
         # new member becomes an alias to the existing one.
         try:
@@ -525,12 +532,8 @@ def __new__(metacls, cls, bases, classdict, *, boundary=None, _simple=False, **k
         classdict['_use_args_'] = use_args
         #
         # convert future enum members into temporary _proto_members
-        # and record integer values in case this will be a Flag
-        flag_mask = 0
         for name in member_names:
             value = classdict[name]
-            if isinstance(value, int):
-                flag_mask |= value
             classdict[name] = _proto_member(value)
         #
         # house-keeping structures
@@ -547,8 +550,9 @@ def __new__(metacls, cls, bases, classdict, *, boundary=None, _simple=False, **k
                 boundary
                 or getattr(first_enum, '_boundary_', None)
                 )
-        classdict['_flag_mask_'] = flag_mask
-        classdict['_all_bits_'] = 2 ** ((flag_mask).bit_length()) - 1
+        classdict['_flag_mask_'] = 0
+        classdict['_singles_mask_'] = 0
+        classdict['_all_bits_'] = 0
         classdict['_inverted_'] = None
         try:
             exc = None
@@ -637,21 +641,10 @@ def __new__(metacls, cls, bases, classdict, *, boundary=None, _simple=False, **k
             ):
             delattr(enum_class, '_boundary_')
             delattr(enum_class, '_flag_mask_')
+            delattr(enum_class, '_singles_mask_')
             delattr(enum_class, '_all_bits_')
             delattr(enum_class, '_inverted_')
         elif Flag is not None and issubclass(enum_class, Flag):
-            # ensure _all_bits_ is correct and there are no missing flags
-            single_bit_total = 0
-            multi_bit_total = 0
-            for flag in enum_class._member_map_.values():
-                flag_value = flag._value_
-                if _is_single_bit(flag_value):
-                    single_bit_total |= flag_value
-                else:
-                    # multi-bit flags are considered aliases
-                    multi_bit_total |= flag_value
-            enum_class._flag_mask_ = single_bit_total
-            #
             # set correct __iter__
             member_list = [m._value_ for m in enum_class]
             if member_list != sorted(member_list):
@@ -1303,8 +1296,8 @@ def _reduce_ex_by_global_name(self, proto):
 class FlagBoundary(StrEnum):
     """
     control how out of range values are handled
-    "strict" -> error is raised
-    "conform" -> extra bits are discarded   [default for Flag]
+    "strict" -> error is raised             [default for Flag]
+    "conform" -> extra bits are discarded
     "eject" -> lose flag status
     "keep" -> keep flag status and all bits [default for IntFlag]
     """
@@ -1315,7 +1308,7 @@ class FlagBoundary(StrEnum):
 STRICT, CONFORM, EJECT, KEEP = FlagBoundary
 
 
-class Flag(Enum, boundary=CONFORM):
+class Flag(Enum, boundary=STRICT):
     """
     Support for flags
     """
@@ -1393,6 +1386,7 @@ def _missing_(cls, value):
         # - value must not include any skipped flags (e.g. if bit 2 is not
         #   defined, then 0d10 is invalid)
         flag_mask = cls._flag_mask_
+        singles_mask = cls._singles_mask_
         all_bits = cls._all_bits_
         neg_value = None
         if (
@@ -1424,7 +1418,8 @@ def _missing_(cls, value):
             value = all_bits + 1 + value
         # get members and unknown
         unknown = value & ~flag_mask
-        member_value = value & flag_mask
+        aliases = value & ~singles_mask
+        member_value = value & singles_mask
         if unknown and cls._boundary_ is not KEEP:
             raise ValueError(
                     '%s(%r) -->  unknown values %r [%s]'
@@ -1438,11 +1433,25 @@ def _missing_(cls, value):
             pseudo_member = cls._member_type_.__new__(cls, value)
         if not hasattr(pseudo_member, '_value_'):
             pseudo_member._value_ = value
-        if member_value:
-            pseudo_member._name_ = '|'.join([
-                m._name_ for m in cls._iter_member_(member_value)
-                ])
-            if unknown:
+        if member_value or aliases:
+            members = []
+            combined_value = 0
+            for m in cls._iter_member_(member_value):
+                members.append(m)
+                combined_value |= m._value_
+            if aliases:
+                value = member_value | aliases
+                for n, pm in cls._member_map_.items():
+                    if pm not in members and pm._value_ and pm._value_ & value == pm._value_:
+                        members.append(pm)
+                        combined_value |= pm._value_
+            unknown = value ^ combined_value
+            pseudo_member._name_ = '|'.join([m._name_ for m in members])
+            if not combined_value:
+                pseudo_member._name_ = None
+            elif unknown and cls._boundary_ is STRICT:
+                raise ValueError('%r: no members with value %r' % (cls, unknown))
+            elif unknown:
                 pseudo_member._name_ += '|%s' % cls._numeric_repr_(unknown)
         else:
             pseudo_member._name_ = None
@@ -1671,6 +1680,7 @@ def convert_class(cls):
             body['_boundary_'] = boundary or etype._boundary_
             body['_flag_mask_'] = None
             body['_all_bits_'] = None
+            body['_singles_mask_'] = None
             body['_inverted_'] = None
             body['__or__'] = Flag.__or__
             body['__xor__'] = Flag.__xor__
@@ -1743,7 +1753,8 @@ def convert_class(cls):
                     else:
                         multi_bits |= value
                     gnv_last_values.append(value)
-            enum_class._flag_mask_ = single_bits
+            enum_class._flag_mask_ = single_bits | multi_bits
+            enum_class._singles_mask_ = single_bits
             enum_class._all_bits_ = 2 ** ((single_bits|multi_bits).bit_length()) - 1
             # set correct __iter__
             member_list = [m._value_ for m in enum_class]

Lib/test/test_enum.py

@@ -2758,6 +2758,8 @@ def __new__(cls, c):
             #
             a = ord('a')
         #
+        self.assertEqual(FlagFromChar._all_bits_, 316912650057057350374175801343)
+        self.assertEqual(FlagFromChar._flag_mask_, 158456325028528675187087900672)
         self.assertEqual(FlagFromChar.a, 158456325028528675187087900672)
         self.assertEqual(FlagFromChar.a|1, 158456325028528675187087900673)
         #
@@ -2772,6 +2774,8 @@ def __new__(cls, c):
             a = ord('a')
             z = 1
         #
+        self.assertEqual(FlagFromChar._all_bits_, 316912650057057350374175801343)
+        self.assertEqual(FlagFromChar._flag_mask_, 158456325028528675187087900674)
         self.assertEqual(FlagFromChar.a.value, 158456325028528675187087900672)
         self.assertEqual((FlagFromChar.a|FlagFromChar.z).value, 158456325028528675187087900674)
         #
@@ -2785,6 +2789,8 @@ def __new__(cls, c):
             #
             a = ord('a')
         #
+        self.assertEqual(FlagFromChar._all_bits_, 316912650057057350374175801343)
+        self.assertEqual(FlagFromChar._flag_mask_, 158456325028528675187087900672)
         self.assertEqual(FlagFromChar.a, 158456325028528675187087900672)
         self.assertEqual(FlagFromChar.a|1, 158456325028528675187087900673)
 
@@ -2962,18 +2968,18 @@ def test_bool(self):
             self.assertEqual(bool(f.value), bool(f))
 
     def test_boundary(self):
-        self.assertIs(enum.Flag._boundary_, CONFORM)
-        class Iron(Flag, boundary=STRICT):
+        self.assertIs(enum.Flag._boundary_, STRICT)
+        class Iron(Flag, boundary=CONFORM):
             ONE = 1
             TWO = 2
             EIGHT = 8
-        self.assertIs(Iron._boundary_, STRICT)
+        self.assertIs(Iron._boundary_, CONFORM)
         #
-        class Water(Flag, boundary=CONFORM):
+        class Water(Flag, boundary=STRICT):
             ONE = 1
             TWO = 2
             EIGHT = 8
-        self.assertIs(Water._boundary_, CONFORM)
+        self.assertIs(Water._boundary_, STRICT)
         #
         class Space(Flag, boundary=EJECT):
             ONE = 1
@@ -2986,17 +2992,42 @@ class Bizarre(Flag, boundary=KEEP):
             c = 4
             d = 6
         #
-        self.assertRaisesRegex(ValueError, 'invalid value 7', Iron, 7)
+        self.assertRaisesRegex(ValueError, 'invalid value 7', Water, 7)
         #
-        self.assertIs(Water(7), Water.ONE|Water.TWO)
-        self.assertIs(Water(~9), Water.TWO)
+        self.assertIs(Iron(7), Iron.ONE|Iron.TWO)
+        self.assertIs(Iron(~9), Iron.TWO)
         #
         self.assertEqual(Space(7), 7)
         self.assertTrue(type(Space(7)) is int)
         #
         self.assertEqual(list(Bizarre), [Bizarre.c])
         self.assertIs(Bizarre(3), Bizarre.b)
         self.assertIs(Bizarre(6), Bizarre.d)
+        #
+        class SkipFlag(enum.Flag):
+            A = 1
+            B = 2
+            C = 4 | B
+        #
+        self.assertTrue(SkipFlag.C in (SkipFlag.A|SkipFlag.C))
+        self.assertRaisesRegex(ValueError, 'SkipFlag.. invalid value 42', SkipFlag, 42)
+        #
+        class SkipIntFlag(enum.IntFlag):
+            A = 1
+            B = 2
+            C = 4 | B
+        #
+        self.assertTrue(SkipIntFlag.C in (SkipIntFlag.A|SkipIntFlag.C))
+        self.assertEqual(SkipIntFlag(42).value, 42)
+        #
+        class MethodHint(Flag):
+            HiddenText = 0x10
+            DigitsOnly = 0x01
+            LettersOnly = 0x02
+            OnlyMask = 0x0f
+        #
+        self.assertEqual(str(MethodHint.HiddenText|MethodHint.OnlyMask), 'MethodHint.HiddenText|DigitsOnly|LettersOnly|OnlyMask')
+
 
     def test_iter(self):
         Color = self.Color

Misc/NEWS.d/next/Library/2023-04-12-17-59-55.gh-issue-103365.UBEE0U.rst

@@ -0,0 +1 @@
+Set default Flag boundary to ``STRICT`` and fix bitwise operations.