[3.10] 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'.
(cherry picked from commit f60b07ab6c943fce084772c3c7731ab3bbd213ff)
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 077a354..d3df151b 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 @@
:attr:`Color.RED` is ``RED``, the value of :attr:`Color.BLUE` is
``3``, etc.)
+---------------
Module Contents
---------------
@@ -73,12 +74,12 @@
: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 @@
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 @@
.. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto``
.. versionadded:: 3.10 ``StrEnum``, ``EnumCheck``, ``FlagBoundary``
+---------------
Data Types
----------
@@ -647,6 +649,8 @@
.. versionadded:: 3.10
+---------------
+
Utilites and Decorators
-----------------------
@@ -706,3 +710,25 @@
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