[Python-checkins] bpo-43945: [Enum] reduce scope of new format() behavior (GH-26752)
ethanfurman
webhook-mailer at python.org
Fri Jun 18 16:15:55 EDT 2021
https://github.com/python/cpython/commit/f60b07ab6c943fce084772c3c7731ab3bbd213ff
commit: f60b07ab6c943fce084772c3c7731ab3bbd213ff
branch: main
author: Ethan Furman <ethan at stoneleaf.us>
committer: ethanfurman <ethan at stoneleaf.us>
date: 2021-06-18T13:15:46-07:00
summary:
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'
files:
M Doc/library/enum.rst
M Lib/asyncio/unix_events.py
M Lib/enum.py
M Lib/test/test_enum.py
M Lib/test/test_httpservers.py
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index d53e3405e531f..89ce94b9f048c 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
diff --git a/Lib/asyncio/unix_events.py b/Lib/asyncio/unix_events.py
index a55b3a375fa22..e4f445e95026b 100644
--- a/Lib/asyncio/unix_events.py
+++ b/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
diff --git a/Lib/enum.py b/Lib/enum.py
index 90777988dd041..84e3cc17bbc53 100644
--- a/Lib/enum.py
+++ b/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_
diff --git a/Lib/test/test_enum.py b/Lib/test/test_enum.py
index c4c458e6bfc4e..0267ff5684c0d 100644
--- a/Lib/test/test_enum.py
+++ b/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):
- self.assertEqual(f'{self.Grades.B}', 'Grades.B')
+ class Grades(int, Enum):
+ 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
- self.assertEqual(format(Perm.R, ''), '4')
- self.assertEqual(format(Perm.R | Perm.X, ''), '5')
+ Perm = self.Perm
+ self.assertEqual(format(Perm.R, ''), '4')
+ 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'
diff --git a/Lib/test/test_httpservers.py b/Lib/test/test_httpservers.py
index cb0a3aa9e4045..aeea020d2416d 100644
--- a/Lib/test/test_httpservers.py
+++ b/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:
More information about the Python-checkins
mailing list