python-peps/pep-0663.txt

PEP: 663
Title: Improving and Standardizing Enum str(), repr(), and format() behaviors
Version: $Revision$
Last-Modified: $Date$
Author: Ethan Furman <ethan@stoneleaf.us>
Discussions-To: python-dev@python.org
Status: Draft
Type: Informational
Content-Type: text/x-rst
Created: 23-Feb-2013
Python-Version: 3.11
Post-History: 20-Jul-2021
Resolution:


Abstract
========

Update the ``repr()``, ``str()``, and ``format()`` of the various Enum types
for consistency and to better match their intended purpose.


Motivation
==========

The addition of ``StrEnum`` with its requirement to have its ``str()`` be its
``value`` is inconsistent with other provided Enum's ``str``.

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 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 in 3.10, only str() needs
updating.

As much as possible, the ``str()`, ``repr()``, and ``format()`` of enum members
should be standardized across the stardard library.

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 a 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
  namespcae, 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 table shows the old and new
behavior (blank cells indicate no behavioral change); the second table shows
the final result:


+--------+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
| 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:

+--------+-------------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+
| 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
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.


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
compatibily 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.