bpo-43945: [Enum] reduce scope of new format() behavior (GH-26752)

* [Enum] reduce scope of new format behavior

Instead of treating all Enums the same for format(), only user mixed-in
enums will be affected.  In other words, IntEnum and IntFlag will not be
changing the format() behavior, due to the requirement that they be
drop-in replacements of existing integer constants.

If a user creates their own integer-based enum, then the new behavior
will apply:

    class Grades(int, Enum):
        A = 5
        B = 4
        C = 3
        D = 2
        F = 0

Now:  format(Grades.B)  -> DeprecationWarning and '4'
3.12:                   -> no warning, and 'B'

Doc/library/enum.rst

@@ -22,7 +22,7 @@
    * :ref:`Advanced Tutorial <enum-advanced-tutorial>`
    * :ref:`Enum Cookbook <enum-cookbook>`
 
-----------------
+---------------
 
 An enumeration:
 
@@ -58,6 +58,7 @@ are not normal Python classes.  See
      :attr:`Color.RED` is ``RED``, the value of :attr:`Color.BLUE` is
      ``3``, etc.)
 
+---------------
 
 Module Contents
 ---------------
@@ -73,12 +74,12 @@ Module Contents
    :class:`IntEnum`
 
       Base class for creating enumerated constants that are also
-      subclasses of :class:`int`.
+      subclasses of :class:`int`. (`Notes`_)
 
    :class:`StrEnum`
 
       Base class for creating enumerated constants that are also
-      subclasses of :class:`str`.
+      subclasses of :class:`str`. (`Notes`_)
 
    :class:`Flag`
 
@@ -89,7 +90,7 @@ Module Contents
 
       Base class for creating enumerated constants that can be combined using
       the bitwise operators without losing their :class:`IntFlag` membership.
-      :class:`IntFlag` members are also subclasses of :class:`int`.
+      :class:`IntFlag` members are also subclasses of :class:`int`. (`Notes`_)
 
    :class:`EnumCheck`
 
@@ -132,6 +133,7 @@ Module Contents
 .. versionadded:: 3.6  ``Flag``, ``IntFlag``, ``auto``
 .. versionadded:: 3.10  ``StrEnum``, ``EnumCheck``, ``FlagBoundary``
 
+---------------
 
 Data Types
 ----------
@@ -647,6 +649,7 @@ Data Types
 
 .. versionadded:: 3.10
 
+---------------
 
 Utilites and Decorators
 -----------------------
@@ -710,3 +713,25 @@ Utilites and Decorators
    on the decorated enumeration.
 
 .. versionadded:: 3.10
+
+---------------
+
+Notes
+-----
+
+:class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag`
+
+    These three enum types are designed to be drop-in replacements for existing
+    integer- and string-based values; as such, they have extra limitations:
+
+    - ``format()`` will use the value of the enum member, unless ``__str__``
+      has been overridden
+
+    - ``StrEnum.__str__`` uses the value and not the name of the enum member
+
+    If you do not need/want those limitations, you can create your own base
+    class by mixing in the ``int`` or ``str`` type yourself::
+
+        >>> from enum import Enum
+        >>> class MyIntEnum(int, Enum):
+        ...     pass

Lib/asyncio/unix_events.py

@@ -126,7 +126,7 @@ def add_signal_handler(self, sig, callback, *args):
                     logger.info('set_wakeup_fd(-1) failed: %s', nexc)
 
             if exc.errno == errno.EINVAL:
-                raise RuntimeError(f'sig {sig:d} cannot be caught')
+                raise RuntimeError(f'sig {sig} cannot be caught')
             else:
                 raise
 
@@ -160,7 +160,7 @@ def remove_signal_handler(self, sig):
             signal.signal(sig, handler)
         except OSError as exc:
             if exc.errno == errno.EINVAL:
-                raise RuntimeError(f'sig {sig:d} cannot be caught')
+                raise RuntimeError(f'sig {sig} cannot be caught')
             else:
                 raise
 

Lib/enum.py

@@ -993,9 +993,9 @@ def __format__(self, format_spec):
         # mixed-in Enums should use the mixed-in type's __format__, otherwise
         # we can get strange results with the Enum name showing up instead of
         # the value
-
+        #
         # pure Enum branch, or branch with __str__ explicitly overridden
-        str_overridden = type(self).__str__ not in (Enum.__str__, Flag.__str__)
+        str_overridden = type(self).__str__ not in (Enum.__str__, IntEnum.__str__, Flag.__str__)
         if self._member_type_ is object or str_overridden:
             cls = str
             val = str(self)
@@ -1005,7 +1005,7 @@ def __format__(self, format_spec):
                 import warnings
                 warnings.warn(
                         "in 3.12 format() will use the enum member, not the enum member's value;\n"
-                        "use a format specifier, such as :d for an IntEnum member, to maintain "
+                        "use a format specifier, such as :d for an integer-based Enum, to maintain "
                         "the current display",
                         DeprecationWarning,
                         stacklevel=2,
@@ -1044,6 +1044,22 @@ class IntEnum(int, Enum):
     Enum where members are also (and must be) ints
     """
 
+    def __str__(self):
+        return "%s" % (self._name_, )
+
+    def __format__(self, format_spec):
+        """
+        Returns format using actual value unless __str__ has been overridden.
+        """
+        str_overridden = type(self).__str__ != IntEnum.__str__
+        if str_overridden:
+            cls = str
+            val = str(self)
+        else:
+            cls = self._member_type_
+            val = self._value_
+        return cls.__format__(val, format_spec)
+
 
 class StrEnum(str, Enum):
     """
@@ -1072,6 +1088,8 @@ def __new__(cls, *values):
 
     __str__ = str.__str__
 
+    __format__ = str.__format__
+
     def _generate_next_value_(name, start, count, last_values):
         """
         Return the lower-cased version of the member name.
@@ -1300,6 +1318,16 @@ class IntFlag(int, Flag, boundary=EJECT):
     Support for integer-based Flags
     """
 
+    def __format__(self, format_spec):
+        """
+        Returns format using actual value unless __str__ has been overridden.
+        """
+        str_overridden = type(self).__str__ != Flag.__str__
+        value = self
+        if not str_overridden:
+            value = self._value_
+        return int.__format__(value, format_spec)
+
     def __or__(self, other):
         if isinstance(other, self.__class__):
             other = other._value_

Lib/test/test_enum.py

@@ -557,16 +557,27 @@ def __format__(self, spec):
             'mixin-format is still using member.value',
             )
     def test_mixin_format_warning(self):
-        with self.assertWarns(DeprecationWarning):
+        class Grades(int, Enum):
-            self.assertEqual(f'{self.Grades.B}', 'Grades.B')
+            A = 5
+            B = 4
+            C = 3
+            D = 2
+            F = 0
+        self.assertEqual(f'{self.Grades.B}', 'B')
 
     @unittest.skipIf(
             python_version >= (3, 12),
             'mixin-format now uses member instead of member.value',
             )
     def test_mixin_format_warning(self):
+        class Grades(int, Enum):
+            A = 5
+            B = 4
+            C = 3
+            D = 2
+            F = 0
         with self.assertWarns(DeprecationWarning):
-            self.assertEqual(f'{self.Grades.B}', '4')
+            self.assertEqual(f'{Grades.B}', '4')
 
     def assertFormatIsValue(self, spec, member):
         if python_version < (3, 12) and (not spec or spec in ('{}','{:}')):
@@ -599,7 +610,12 @@ def test_format_enum_float(self):
         self.assertFormatIsValue('{:f}', Konstants.TAU)
 
     def test_format_enum_int(self):
-        Grades = self.Grades
+        class Grades(int, Enum):
+            A = 5
+            B = 4
+            C = 3
+            D = 2
+            F = 0
         self.assertFormatIsValue('{}', Grades.C)
         self.assertFormatIsValue('{:}', Grades.C)
         self.assertFormatIsValue('{:20}', Grades.C)
@@ -2236,8 +2252,10 @@ class GoodStrEnum(StrEnum):
             four = b'4', 'latin1', 'strict'
         self.assertEqual(GoodStrEnum.one, '1')
         self.assertEqual(str(GoodStrEnum.one), '1')
+        self.assertEqual('{}'.format(GoodStrEnum.one), '1')
         self.assertEqual(GoodStrEnum.one, str(GoodStrEnum.one))
         self.assertEqual(GoodStrEnum.one, '{}'.format(GoodStrEnum.one))
+        self.assertEqual(repr(GoodStrEnum.one), 'GoodStrEnum.one')
         #
         class DumbMixin:
             def __str__(self):
@@ -2287,6 +2305,132 @@ class ThirdFailedStrEnum(StrEnum):
                 one = '1'
                 two = b'2', 'ascii', 9
 
+    @unittest.skipIf(
+            python_version >= (3, 12),
+            'mixin-format now uses member instead of member.value',
+            )
+    def test_custom_strenum_with_warning(self):
+        class CustomStrEnum(str, Enum):
+            pass
+        class OkayEnum(CustomStrEnum):
+            one = '1'
+            two = '2'
+            three = b'3', 'ascii'
+            four = b'4', 'latin1', 'strict'
+        self.assertEqual(OkayEnum.one, '1')
+        self.assertEqual(str(OkayEnum.one), 'one')
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual('{}'.format(OkayEnum.one), '1')
+        self.assertEqual(OkayEnum.one, '{}'.format(OkayEnum.one))
+        self.assertEqual(repr(OkayEnum.one), 'OkayEnum.one')
+        #
+        class DumbMixin:
+            def __str__(self):
+                return "don't do this"
+        class DumbStrEnum(DumbMixin, CustomStrEnum):
+            five = '5'
+            six = '6'
+            seven = '7'
+        self.assertEqual(DumbStrEnum.seven, '7')
+        self.assertEqual(str(DumbStrEnum.seven), "don't do this")
+        #
+        class EnumMixin(Enum):
+            def hello(self):
+                print('hello from %s' % (self, ))
+        class HelloEnum(EnumMixin, CustomStrEnum):
+            eight = '8'
+        self.assertEqual(HelloEnum.eight, '8')
+        self.assertEqual(str(HelloEnum.eight), 'eight')
+        #
+        class GoodbyeMixin:
+            def goodbye(self):
+                print('%s wishes you a fond farewell')
+        class GoodbyeEnum(GoodbyeMixin, EnumMixin, CustomStrEnum):
+            nine = '9'
+        self.assertEqual(GoodbyeEnum.nine, '9')
+        self.assertEqual(str(GoodbyeEnum.nine), 'nine')
+        #
+        class FirstFailedStrEnum(CustomStrEnum):
+            one = 1   # this will become '1'
+            two = '2'
+        class SecondFailedStrEnum(CustomStrEnum):
+            one = '1'
+            two = 2,  # this will become '2'
+            three = '3'
+        class ThirdFailedStrEnum(CustomStrEnum):
+            one = '1'
+            two = 2  # this will become '2'
+        with self.assertRaisesRegex(TypeError, '.encoding. must be str, not '):
+            class ThirdFailedStrEnum(CustomStrEnum):
+                one = '1'
+                two = b'2', sys.getdefaultencoding
+        with self.assertRaisesRegex(TypeError, '.errors. must be str, not '):
+            class ThirdFailedStrEnum(CustomStrEnum):
+                one = '1'
+                two = b'2', 'ascii', 9
+
+    @unittest.skipIf(
+            python_version < (3, 12),
+            'mixin-format currently uses member.value',
+            )
+    def test_custom_strenum(self):
+        class CustomStrEnum(str, Enum):
+            pass
+        class OkayEnum(CustomStrEnum):
+            one = '1'
+            two = '2'
+            three = b'3', 'ascii'
+            four = b'4', 'latin1', 'strict'
+        self.assertEqual(OkayEnum.one, '1')
+        self.assertEqual(str(OkayEnum.one), 'one')
+        self.assertEqual('{}'.format(OkayEnum.one), 'one')
+        self.assertEqual(repr(OkayEnum.one), 'OkayEnum.one')
+        #
+        class DumbMixin:
+            def __str__(self):
+                return "don't do this"
+        class DumbStrEnum(DumbMixin, CustomStrEnum):
+            five = '5'
+            six = '6'
+            seven = '7'
+        self.assertEqual(DumbStrEnum.seven, '7')
+        self.assertEqual(str(DumbStrEnum.seven), "don't do this")
+        #
+        class EnumMixin(Enum):
+            def hello(self):
+                print('hello from %s' % (self, ))
+        class HelloEnum(EnumMixin, CustomStrEnum):
+            eight = '8'
+        self.assertEqual(HelloEnum.eight, '8')
+        self.assertEqual(str(HelloEnum.eight), 'eight')
+        #
+        class GoodbyeMixin:
+            def goodbye(self):
+                print('%s wishes you a fond farewell')
+        class GoodbyeEnum(GoodbyeMixin, EnumMixin, CustomStrEnum):
+            nine = '9'
+        self.assertEqual(GoodbyeEnum.nine, '9')
+        self.assertEqual(str(GoodbyeEnum.nine), 'nine')
+        #
+        class FirstFailedStrEnum(CustomStrEnum):
+            one = 1   # this will become '1'
+            two = '2'
+        class SecondFailedStrEnum(CustomStrEnum):
+            one = '1'
+            two = 2,  # this will become '2'
+            three = '3'
+        class ThirdFailedStrEnum(CustomStrEnum):
+            one = '1'
+            two = 2  # this will become '2'
+        with self.assertRaisesRegex(TypeError, '.encoding. must be str, not '):
+            class ThirdFailedStrEnum(CustomStrEnum):
+                one = '1'
+                two = b'2', sys.getdefaultencoding
+        with self.assertRaisesRegex(TypeError, '.errors. must be str, not '):
+            class ThirdFailedStrEnum(CustomStrEnum):
+                one = '1'
+                two = b'2', 'ascii', 9
+
     def test_missing_value_error(self):
         with self.assertRaisesRegex(TypeError, "_value_ not set in __new__"):
             class Combined(str, Enum):
@@ -3080,15 +3224,19 @@ def test_repr(self):
         self.assertEqual(repr(~(Open.WO | Open.CE)), 'Open.RW')
         self.assertEqual(repr(Open(~4)), '-5')
 
-    @unittest.skipUnless(
-            python_version < (3, 12),
-            'mixin-format now uses member instead of member.value',
-            )
     def test_format(self):
-        with self.assertWarns(DeprecationWarning):
+        Perm = self.Perm
-            Perm = self.Perm
+        self.assertEqual(format(Perm.R, ''), '4')
-            self.assertEqual(format(Perm.R, ''), '4')
+        self.assertEqual(format(Perm.R | Perm.X, ''), '5')
-            self.assertEqual(format(Perm.R | Perm.X, ''), '5')
+        #
+        class NewPerm(IntFlag):
+            R = 1 << 2
+            W = 1 << 1
+            X = 1 << 0
+            def __str__(self):
+                return self._name_
+        self.assertEqual(format(NewPerm.R, ''), 'R')
+        self.assertEqual(format(NewPerm.R | Perm.X, ''), 'R|X')
 
     def test_or(self):
         Perm = self.Perm
@@ -3979,10 +4127,6 @@ def test_convert_raise(self):
                 ('test.test_enum', '__main__')[__name__=='__main__'],
                 filter=lambda x: x.startswith('CONVERT_TEST_'))
 
-    @unittest.skipUnless(
-            python_version < (3, 12),
-            'mixin-format now uses member instead of member.value',
-            )
     def test_convert_repr_and_str(self):
         module = ('test.test_enum', '__main__')[__name__=='__main__']
         test_type = enum.IntEnum._convert_(
@@ -3991,8 +4135,7 @@ def test_convert_repr_and_str(self):
                 filter=lambda x: x.startswith('CONVERT_STRING_TEST_'))
         self.assertEqual(repr(test_type.CONVERT_STRING_TEST_NAME_A), '%s.CONVERT_STRING_TEST_NAME_A' % module)
         self.assertEqual(str(test_type.CONVERT_STRING_TEST_NAME_A), 'CONVERT_STRING_TEST_NAME_A')
-        with self.assertWarns(DeprecationWarning):
+        self.assertEqual(format(test_type.CONVERT_STRING_TEST_NAME_A), '5')
-            self.assertEqual(format(test_type.CONVERT_STRING_TEST_NAME_A), '5')
 
 # global names for StrEnum._convert_ test
 CONVERT_STR_TEST_2 = 'goodbye'

Lib/test/test_httpservers.py

@@ -259,7 +259,7 @@ def test_send_error(self):
         for code in (HTTPStatus.NO_CONTENT, HTTPStatus.NOT_MODIFIED,
                      HTTPStatus.PROCESSING, HTTPStatus.RESET_CONTENT,
                      HTTPStatus.SWITCHING_PROTOCOLS):
-            self.con.request('SEND_ERROR', '/{:d}'.format(code))
+            self.con.request('SEND_ERROR', '/{}'.format(code))
             res = self.con.getresponse()
             self.assertEqual(code, res.status)
             self.assertEqual(None, res.getheader('Content-Length'))
@@ -276,7 +276,7 @@ def test_head_via_send_error(self):
         for code in (HTTPStatus.OK, HTTPStatus.NO_CONTENT,
                      HTTPStatus.NOT_MODIFIED, HTTPStatus.RESET_CONTENT,
                      HTTPStatus.SWITCHING_PROTOCOLS):
-            self.con.request('HEAD', '/{:d}'.format(code))
+            self.con.request('HEAD', '/{}'.format(code))
             res = self.con.getresponse()
             self.assertEqual(code, res.status)
             if code == HTTPStatus.OK: