<snip>

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``

- 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

- user-mixed enums and flags
   the user creates their own integer-, float-, str-, whatever-enums instead of
   using enum.IntEnum, etc.

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, while the last 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
         |                       |
+-------------+----------+-----------------+------------+-----------------------+-----------------------+------------------------+-----------------------+