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'

1 files changed, 29 insertions, 4 deletions

diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index d53e340..89ce94b 100644
--- a/Doc/library/enum.rst
+++ 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