-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
Copy pathpep-0663.txt
250 lines (201 loc) · 13.4 KB
/
pep-0663.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
PEP: 663
Title: Standardizing Enum str(), repr(), and format() behaviors
Version: $Revision$
Last-Modified: $Date$
Author: Ethan Furman <[email protected]>
Discussions-To: [email protected]
Status: Rejected
Type: Informational
Content-Type: text/x-rst
Created: 30-Jun-2021
Python-Version: 3.11
Post-History: 20-Jul-2021, 02-Nov-2021
Resolution: https://mail.python.org/archives/list/[email protected]/message/RN3WCRZSTQR55DOHJTZ2KIO6CZPJPCU7/
Abstract
========
Update the ``repr()``, ``str()``, and ``format()`` of the various Enum types
to better match their intended purpose. For example, ``IntEnum`` will have
its ``str()`` change to match its ``format()``, while a user-mixed int-enum
will have its ``format()`` match its ``str()``. In all cases, an enum's
``str()`` and ``format()`` will be the same (unless the user overrides
``format()``).
Add a global enum decorator which changes the ``str()`` and ``repr()`` (and
``format()``) of the decorated enum to be a valid global reference: i.e.
``re.IGNORECASE`` instead of ``<RegexFlag.IGNORECASE: 2>``.
Motivation
==========
Having the ``str()`` of ``IntEnum`` and ``IntFlag`` not be the value causes
bugs and extra work when replacing existing constants.
Having the ``str()`` and ``format()`` of an enum member be different can be
confusing.
The addition of ``StrEnum`` with its requirement to have its ``str()`` be its
``value`` is inconsistent with other provided Enum's ``str``.
The iteration of ``Flag`` members, which directly affects their ``repr()``, is
inelegant at best, and buggy at worst.
Rationale
=========
Enums are becoming more common in the standard library; being able to recognize
enum members by their ``repr()``, and having that ``repr()`` be easy to parse, is
useful and can save time and effort in understanding and debugging code.
However, the enums with mixed-in data types (``IntEnum``, ``IntFlag``, and the new
``StrEnum``) need to be more backwards compatible with the constants they are
replacing -- specifically, ``str(replacement_enum_member) == str(original_constant)``
should be true (and the same for ``format()``).
IntEnum, IntFlag, and StrEnum should be as close to a drop-in replacement of
existing integer and string constants as is possible. Towards that goal, the
``str()`` output of each should be its inherent value; e.g. if ``Color`` is an
``IntEnum``::
>>> Color.RED
<Color.RED: 1>
>>> str(Color.RED)
'1'
>>> format(Color.RED)
'1'
Note that ``format()`` already produces the correct output, only ``str()`` needs
updating.
As much as possible, the ``str()``, ``repr()``, and ``format()`` of enum members
should be standardized across the standard library. However, up to Python 3.10
several enums in the standard library have a custom ``str()`` and/or ``repr()``.
The ``repr()`` of Flag currently includes aliases, which it should not; fixing that
will, of course, already change its ``repr()`` in certain cases.
Specification
=============
There are three broad categories of enum usage:
- simple: ``Enum`` or ``Flag``
a new enum class is created with no data type mixins
- drop-in replacement: ``IntEnum``, ``IntFlag``, ``StrEnum``
a new enum class is created which also subclasses ``int`` or ``str`` and uses
``int.__str__`` or ``str.__str__``
- user-mixed enums and flags
the user creates their own integer-, float-, str-, whatever-enums instead of
using enum.IntEnum, etc.
There are also two styles:
- normal: the enumeration members remain in their classes and are accessed as
``classname.membername``, and the class name shows in their ``repr()`` and
``str()`` (where appropriate)
- global: the enumeration members are copied into their module's global
namespace, and their module name shows in their ``repr()`` and ``str()``
(where appropriate)
Some sample enums::
# module: tools.py
class Hue(Enum): # or IntEnum
LIGHT = -1
NORMAL = 0
DARK = +1
class Color(Flag): # or IntFlag
RED = 1
GREEN = 2
BLUE = 4
class Grey(int, Enum): # or (int, Flag)
BLACK = 0
WHITE = 1
Using the above enumerations, the following two tables show the old and new
output (blank cells indicate no change):
+--------+------------------------+-----------------+------------+-----------------------+
| style | category | enum repr() | enum str() | enum format() |
+--------+-------------+----------+-----------------+------------+-----------------------+
| normal | simple | 3.10 | | | |
| | +----------+-----------------+------------+-----------------------+
| | | new | | | |
| +-------------+----------+-----------------+------------+-----------------------+
| | user mixed | 3.10 | | | 1 |
| | +----------+-----------------+------------+-----------------------+
| | | new | | | Grey.WHITE |
| +-------------+----------+-----------------+------------+-----------------------+
| | int drop-in | 3.10 | | Hue.LIGHT | |
| | +----------+-----------------+------------+-----------------------+
| | | new | | -1 | |
+--------+-------------+----------+-----------------+------------+-----------------------+
| global | simple | 3.10 | <Hue.LIGHT: -1> | Hue.LIGHT | Hue.LIGHT |
| | +----------+-----------------+------------+-----------------------+
| | | new | tools.LIGHT | LIGHT | LIGHT |
| +-------------+----------+-----------------+------------+-----------------------+
| | user mixed | 3.10 | <Grey.WHITE: 1 | Grey.WHITE | Grey.WHITE |
| | +----------+-----------------+------------+-----------------------+
| | | new | tools.WHITE | WHITE | WHITE |
| +-------------+----------+-----------------+------------+-----------------------+
| | int drop-in | 3.10 | <Hue.LIGHT: -1> | Hue.LIGHT | |
| | +----------+-----------------+------------+-----------------------+
| | | new | tools.LIGHT | -1 | |
+--------+-------------+----------+-----------------+------------+-----------------------+
+--------+------------------------+-----------------------+------------------------+-----------------------+
| style | category | flag repr() | flag str() | flag format() |
+--------+-------------+----------+-----------------------+------------------------+-----------------------+
| normal | simple | 3.10 | <Color.RED|GREEN: 3> | Color.RED|GREEN | Color.RED|GREEN |
| | +----------+-----------------------+------------------------+-----------------------+
| | | new | <Color(3): RED|GREEN> | Color.RED|Color.GREEN | Color.RED|Color.GREEN |
| +-------------+----------+-----------------------+------------------------+-----------------------+
| | user mixed | 3.10 | <Grey.WHITE: 1> | | 1 |
| | +----------+-----------------------+------------------------+-----------------------+
| | | new | <Grey(1): WHITE> | | Grey.WHITE |
| +-------------+----------+-----------------------+------------------------+-----------------------+
| | int drop-in | 3.10 | <Color.RED|GREEN: 3> | Color.RED|GREEN | |
| | +----------+-----------------------+------------------------+-----------------------+
| | | new | <Color(3): RED|GREEN> | 3 | |
+--------+-------------+----------+-----------------------+------------------------+-----------------------+
| global | simple | 3.10 | <Color.RED|GREEN: 3> | Color.RED|GREEN | Color.RED|GREEN |
| | +----------+-----------------------+------------------------+-----------------------+
| | | new | tools.RED|tools.GREEN | RED|GREEN | RED|GREEN |
| +-------------+----------+-----------------------+------------------------+-----------------------+
| | user mixed | 3.10 | <Grey.WHITE: 1> | Grey.WHITE | 1 |
| | +----------+-----------------------+------------------------+-----------------------+
| | | new | tools.WHITE | WHITE | WHITE |
| +-------------+----------+-----------------------+------------------------+-----------------------+
| | int drop-in | 3.10 | <Color.RED|GREEN: 3> | Color.RED|GREEN | |
| | +----------+-----------------------+------------------------+-----------------------+
| | | new | tools.RED|tools.GREEN | 3 | |
+--------+-------------+----------+-----------------------+------------------------+-----------------------+
These two tables show the final result:
+--------+-------------+-----------------+------------+-----------------------+
| style | category | enum repr() | enum str() | enum format() |
+--------+-------------+-----------------+------------+-----------------------+
| normal | simple | <Hue.LIGHT: -1> | Hue.LIGHT | Hue.LIGHT |
| +-------------+-----------------+------------+-----------------------+
| | user mixed | <Grey.WHITE: 1> | Grey.WHITE | Grey.WHITE |
| +-------------+-----------------+------------+-----------------------+
| | int drop-in | <Hue.LIGHT: -1> | -1 | -1 |
+--------+-------------+-----------------+------------+-----------------------+
| global | simple | tools.LIGHT | LIGHT | LIGHT |
| +-------------+-----------------+------------+-----------------------+
| | user mixed | tools.WHITE | WHITE | WHITE |
| +-------------+-----------------+------------+-----------------------+
| | int drop-in | tools.LIGHT | -1 | -1 |
+--------+-------------+-----------------+------------+-----------------------+
+--------+-------------+-----------------------+------------------------+-----------------------+
| style | category | flag repr() | flag str() | flag format() |
+--------+-------------+-----------------------+------------------------+-----------------------+
| normal | simple | <Color(3): RED|GREEN> | Color.RED|Color.GREEN | Color.RED|Color.GREEN |
| +-------------+-----------------------+------------------------+-----------------------+
| | user mixed | <Grey(1): WHITE> | Grey.WHITE | Grey.WHITE |
| +-------------+-----------------------+------------------------+-----------------------+
| | int drop-in | <Color(3): RED|GREEN> | 3 | 3 |
+--------+-------------+-----------------------+------------------------+-----------------------+
| global | simple | tools.RED|tools.GREEN | RED|GREEN | RED|GREEN |
| +-------------+-----------------------+------------------------+-----------------------+
| | user mixed | tools.WHITE | WHITE | WHITE |
| +-------------+-----------------------+------------------------+-----------------------+
| | int drop-in | tools.RED|tools.GREEN | 3 | 3 |
+--------+-------------+-----------------------+------------------------+-----------------------+
As can be seen, ``repr()`` is primarily affected by whether the members are
global, while ``str()`` is affected by being global or by being a drop-in
replacement, with the drop-in replacement status having a higher priority.
Also, the basic ``repr()`` and ``str()`` have changed for flags as the old
style was flawed.
Backwards Compatibility
=======================
Backwards compatibility of stringified objects is not guaranteed across major
Python versions, and there will be backwards compatibility breaks where
software uses the ``repr()``, ``str()``, and ``format()`` output of enums in
tests, documentation, data structures, and/or code generation.
Normal usage of enum members will not change: ``re.ASCII`` can still be used
as ``re.ASCII`` and will still compare equal to ``256``.
If the previous output needs to be maintained, for example to ensure
compatibility between different Python versions, software projects will need to
create their own enum base class with the appropriate methods overridden.
Note that by changing the ``str()`` of the drop-in category, we will actually
prevent future breakage when ``IntEnum``, et al, are used to replace existing
constants.
Copyright
=========
This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.