bpo-43945: [Enum] Deprecate non-standard mixin format() behavior (GH-25649)

In 3.12 the enum member, not the member's value, will be used for
format() calls.  Format specifiers can be used to retain the current
display of enum members:

Example enumeration:

    class Color(IntEnum):
        RED = 1
        GREEN = 2
        BLUE = 3

Current behavior:

    f'{Color.RED}'  -->  '1'

Future behavior:

    f'{Color.RED}'  --> 'RED'

Using d specifier:

    f'{Color.RED:d}'  --> '1'

Using specifiers can be done now and is future-compatible.

1 files changed, 8 insertions, 0 deletions

diff --git a/Lib/enum.py b/Lib/enum.py
index ca6aff6..bcf411c 100644
--- a/Lib/enum.py
+++ b/Lib/enum.py
@@ -1005,6 +1005,14 @@ class Enum(metaclass=EnumType):
             val = str(self)
         # mix-in branch
         else:
+            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"
+                    "the current display",
+                    DeprecationWarning,
+                    stacklevel=2,
+                    )
             cls = self._member_type_
             val = self._value_
         return cls.__format__(val, format_spec)