update tables and descriptions
This commit is contained in:
Ethan Furman
parent
ce2b901d7d
commit
f34a97383b
111
pep-0663.txt
111
pep-0663.txt
|
|
@ -75,19 +75,28 @@ Specification
|
|||
|
||||
There a three broad categories of enum usage:
|
||||
|
||||
- standard: Enum or Flag
|
||||
a new enum class is created, and the members are used as ``class.member_name``
|
||||
- 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__``; the ``repr`` can be changed by using the
|
||||
``global_enum`` decorator
|
||||
``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.
|
||||
|
||||
Some sample enums::
|
||||
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
|
||||
namespcae, and their module name shows in their ``repr()`` and ``str()``
|
||||
(where appropriate)
|
||||
|
||||
Some sample enums:
|
||||
|
||||
# module: tools.py
|
||||
|
||||
|
|
@ -106,54 +115,55 @@ Some sample enums::
|
|||
WHITE = 1
|
||||
|
||||
Using the above enumerations, the following table shows the old and new
|
||||
behavior, while the last shows the final result:
|
||||
behavior (blank cells indicate no behavioral change); the second table shows
|
||||
the final result:
|
||||
|
||||
|
||||
+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| type | enum repr() | enum str() | enum format() | flag repr() | flag str() | flag format() |
|
||||
+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| standard | 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 | | | 1 | <Grey.WHITE: 1> | | 1 |
|
||||
| +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | new | | | Grey.WHITE | <Grey(1): WHITE> | | Grey.WHITE |
|
||||
+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| int drop-in | 3.10 | | Hue.LIGHT | | <Color.RED|GREEN: 3> | Color.RED|GREEN | |
|
||||
| +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | new | | -1 | | <Color(3): RED|GREEN> | 3 | |
|
||||
+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| global | 3.10 | <Hue.LIGHT: -1> | Hue.LIGHT | Hue.LIGHT | <Color.RED|GREEN: 3> | Color.RED|GREEN | Color.RED|GREEN |
|
||||
| +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | new | tools.LIGHT | LIGHT | LIGHT | tools.RED|tools.GREEN | RED|GREEN | RED|GREEN |
|
||||
+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| user mixed | 3.10 | <Grey.WHITE: 1 | Grey.WHITE | Grey.WHITE | <Grey.WHITE: 1> | Grey.WHITE | 1 |
|
||||
| +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | new | tools.WHITE | WHITE | WHITE | tools.WHITE | WHITE | WHITE |
|
||||
+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| int drop-in | 3.10 | <Hue.LIGHT: -1> | Hue.LIGHT | | <Color.RED|GREEN: 3> | Color.RED|GREEN | |
|
||||
| +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | new | tools.LIGHT | -1 | | tools.RED|tools.GREEN | 3 | |
|
||||
+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
+--------+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| style | category | enum repr() | enum str() | enum format() | 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 | | | 1 | <Grey.WHITE: 1> | | 1 |
|
||||
| | +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | | new | | | Grey.WHITE | <Grey(1): WHITE> | | Grey.WHITE |
|
||||
+ +-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | int drop-in | 3.10 | | Hue.LIGHT | | <Color.RED|GREEN: 3> | Color.RED|GREEN | |
|
||||
| | +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | | new | | -1 | | <Color(3): RED|GREEN> | 3 | |
|
||||
|--------+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| global | simple | 3.10 | <Hue.LIGHT: -1> | Hue.LIGHT | Hue.LIGHT | <Color.RED|GREEN: 3> | Color.RED|GREEN | Color.RED|GREEN |
|
||||
| | +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | | new | tools.LIGHT | LIGHT | LIGHT | tools.RED|tools.GREEN | RED|GREEN | RED|GREEN |
|
||||
+ +-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | user mixed | 3.10 | <Grey.WHITE: 1 | Grey.WHITE | Grey.WHITE | <Grey.WHITE: 1> | Grey.WHITE | 1 |
|
||||
| | +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | | new | tools.WHITE | WHITE | WHITE | tools.WHITE | WHITE | WHITE |
|
||||
+ +-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | int drop-in | 3.10 | <Hue.LIGHT: -1> | Hue.LIGHT | | <Color.RED|GREEN: 3> | Color.RED|GREEN | |
|
||||
| | +----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | | new | tools.LIGHT | -1 | | tools.RED|tools.GREEN | 3 | |
|
||||
+--------+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
|
||||
Which will result in:
|
||||
|
||||
+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| type | enum repr() | enum str() | enum format() | flag repr() | flag str() | flag format() |
|
||||
+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| standard | <Hue.LIGHT: -1> | Hue.LIGHT | Hue.LIGHT | <Color(3): RED|GREEN> | Color.RED|Color.GREEN | Color.RED|Color.GREEN |
|
||||
+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| user mixed | <Grey.WHITE: 1> | Grey.WHITE | Grey.WHITE | <Grey(1): WHITE> | Grey.WHITE | Grey.WHITE |
|
||||
+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| int drop-in | <Hue.LIGHT: -1> | -1 | -1 | <Color(3): RED|GREEN> | 3 | 3 |
|
||||
+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| global | tools.LIGHT | LIGHT | LIGHT | tools.RED|tools.GREEN | RED|GREEN | RED|GREEN |
|
||||
+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| user mixed | tools.WHITE | WHITE | WHITE | tools.WHITE | WHITE | WHITE |
|
||||
+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| int drop-in | tools.LIGHT | -1 | -1 | tools.RED|tools.GREEN | 3 | 3 |
|
||||
+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
+--------+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| style | type | enum repr() | enum str() | enum format() | flag repr() | flag str() | flag format() |
|
||||
+--------+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| normal | simple | <Hue.LIGHT: -1> | Hue.LIGHT | Hue.LIGHT | <Color(3): RED|GREEN> | Color.RED|Color.GREEN | Color.RED|Color.GREEN |
|
||||
+ +-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | user mixed | <Grey.WHITE: 1> | Grey.WHITE | Grey.WHITE | <Grey(1): WHITE> | Grey.WHITE | Grey.WHITE |
|
||||
+ +-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | int drop-in | <Hue.LIGHT: -1> | -1 | -1 | <Color(3): RED|GREEN> | 3 | 3 |
|
||||
+--------+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| global | simple | tools.LIGHT | LIGHT | LIGHT | tools.RED|tools.GREEN | RED|GREEN | RED|GREEN |
|
||||
+ +-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | user mixed | tools.WHITE | WHITE | WHITE | tools.WHITE | WHITE | WHITE |
|
||||
+ +-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
|
||||
| | int drop-in | tools.LIGHT | -1 | -1 | 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
|
||||
|
|
@ -161,11 +171,6 @@ 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 very clunky.
|
||||
|
||||
The ``repr()`` for Enum vs Flag are different, primarily because the Enum
|
||||
``repr()`` does not work well for flags. I like being able to tell whether
|
||||
an enum member is a Flag or an Enum based on the ``repr()`` alone, but am open
|
||||
to arguments for changing Enum's ``repr()`` to match Flag's.
|
||||
|
||||
|
||||
Backwards Compatibility
|
||||
=======================
|
||||
|
|
|
|||
Loading…
Reference in New Issue