Skip to content

gh-136672: Docs: Move parts of Enum HOWTO to API Docs #139176

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

gh-136672: Docs: Move parts of Enum HOWTO to API Docs #139176

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3b57460
Move parts of Enum how-to to API docs
RafaelWO Aug 21, 2025
706ad60
Move "Finer Points" in Enum HOWTO one level out
RafaelWO Aug 28, 2025
6c75719
Add version changed indicators to Enum members
RafaelWO Sep 14, 2025
ff84f94
Move note for Enum member to API section
RafaelWO Sep 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 12 additions & 70 deletions Doc/howto/enum.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -965,75 +965,16 @@ want one of them to be the value::


Finer Points
^^^^^^^^^^^^

Supported ``__dunder__`` names
""""""""""""""""""""""""""""""

:attr:`~enum.EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
items. It is only available on the class.

:meth:`~object.__new__`, if specified, must create and return the enum members; it is
also a very good idea to set the member's :attr:`~Enum._value_` appropriately. Once
all the members are created it is no longer used.


Supported ``_sunder_`` names
""""""""""""""""""""""""""""
------------

- :attr:`~Enum._name_` -- name of the member
- :attr:`~Enum._value_` -- value of the member; can be set in ``__new__``
- :meth:`~Enum._missing_` -- a lookup function used when a value is not found;
may be overridden
- :attr:`~Enum._ignore_` -- a list of names, either as a :class:`list` or a
:class:`str`, that will not be transformed into members, and will be removed
from the final class
- :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
an enum member; may be overridden
- :meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing
member.
- :meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an
existing member. See `MultiValueEnum`_ for an example.
Supported ``__dunder__`` and ``_sunder_`` names
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::

For standard :class:`Enum` classes the next value chosen is the highest
value seen incremented by one.

For :class:`Flag` classes the next value chosen will be the next highest
power-of-two.

.. versionchanged:: 3.13
Prior versions would use the last seen value instead of the highest value.

.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
.. versionadded:: 3.7 ``_ignore_``
.. versionadded:: 3.13 ``_add_alias_``, ``_add_value_alias_``

To help keep Python 2 / Python 3 code in sync an :attr:`~Enum._order_` attribute can
be provided. It will be checked against the actual order of the enumeration
and raise an error if the two do not match::

>>> class Color(Enum):
... _order_ = 'RED GREEN BLUE'
... RED = 1
... BLUE = 3
... GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_:
['RED', 'BLUE', 'GREEN']
['RED', 'GREEN', 'BLUE']

.. note::

In Python 2 code the :attr:`~Enum._order_` attribute is necessary as definition
order is lost before it can be recorded.
The supported ``__dunder__`` and ``_sunder_`` names can be found in the :ref:`Enum API documentation <enum-dunder-sunder>`.


_Private__names
"""""""""""""""
^^^^^^^^^^^^^^^

:ref:`Private names <private-name-mangling>` are not converted to enum members,
but remain normal attributes.
Expand All @@ -1042,7 +983,7 @@ but remain normal attributes.


``Enum`` member type
""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^

Enum members are instances of their enum class, and are normally accessed as
``EnumClass.member``. In certain situations, such as writing custom enum
Expand All @@ -1055,7 +996,7 @@ recommended.


Creating members that are mixed with other data types
"""""""""""""""""""""""""""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When subclassing other data types, such as :class:`int` or :class:`str`, with
an :class:`Enum`, all values after the ``=`` are passed to that data type's
Expand All @@ -1069,7 +1010,7 @@ constructor. For example::


Boolean value of ``Enum`` classes and members
"""""""""""""""""""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Enum classes that are mixed with non-:class:`Enum` types (such as
:class:`int`, :class:`str`, etc.) are evaluated according to the mixed-in
Expand All @@ -1084,7 +1025,7 @@ Plain :class:`Enum` classes always evaluate as :data:`True`.


``Enum`` classes with methods
"""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you give your enum subclass extra methods, like the `Planet`_
class below, those methods will show up in a :func:`dir` of the member,
Expand All @@ -1097,7 +1038,7 @@ but not of the class::


Combining members of ``Flag``
"""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Iterating over a combination of :class:`Flag` members will only return the members that
are comprised of a single bit::
Expand All @@ -1117,7 +1058,7 @@ are comprised of a single bit::


``Flag`` and ``IntFlag`` minutia
""""""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the following snippet for our examples::

Expand Down Expand Up @@ -1478,6 +1419,7 @@ alias::
behaviors as well as disallowing aliases. If the only desired change is
disallowing aliases, the :func:`unique` decorator can be used instead.

.. _multi-value-enum:

MultiValueEnum
^^^^^^^^^^^^^^^^^
Expand Down
57 changes: 46 additions & 11 deletions Doc/library/enum.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,28 @@ Data Types
No longer used, kept for backward compatibility.
(class attribute, removed during class creation).

The :attr:`~Enum._order_` attribute can be provided to help keep Python 2 / Python 3 code in sync.
It will be checked against the actual order of the enumeration and raise an error if the two do not match::

>>> class Color(Enum):
... _order_ = 'RED GREEN BLUE'
... RED = 1
... BLUE = 3
... GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_:
['RED', 'BLUE', 'GREEN']
['RED', 'GREEN', 'BLUE']

.. note::

In Python 2 code the :attr:`~Enum._order_` attribute is necessary as definition
order is lost before it can be recorded.

.. versionadded:: 3.6

.. attribute:: Enum._ignore_

``_ignore_`` is only used during creation and is removed from the
Expand All @@ -310,6 +332,8 @@ Data Types
names will also be removed from the completed enumeration. See
:ref:`TimePeriod <enum-time-period>` for an example.

.. versionadded:: 3.7

.. method:: Enum.__dir__(self)

Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
Expand Down Expand Up @@ -339,7 +363,16 @@ Data Types
:last_values: A list of the previous values.

A *staticmethod* that is used to determine the next value returned by
:class:`auto`::
:class:`auto`.

.. note::
For standard :class:`Enum` classes the next value chosen is the highest
value seen incremented by one.

For :class:`Flag` classes the next value chosen will be the next highest
power-of-two.

This method may be overridden, e.g.::

>>> from enum import auto
>>> class PowersOfThree(Enum):
Expand All @@ -352,6 +385,10 @@ Data Types
>>> PowersOfThree.SECOND.value
9

.. versionadded:: 3.6
.. versionchanged:: 3.13
Prior versions would use the last seen value instead of the highest value.

.. method:: Enum.__init__(self, *args, **kwds)

By default, does nothing. If multiple values are given in the member
Expand Down Expand Up @@ -390,6 +427,8 @@ Data Types
>>> Build('deBUG')
<Build.DEBUG: 'debug'>

.. versionadded:: 3.6

.. method:: Enum.__new__(cls, *args, **kwds)

By default, doesn't exist. If specified, either in the enum class
Expand Down Expand Up @@ -480,7 +519,8 @@ Data Types
>>> Color(42)
<Color.RED: 1>

Raises a :exc:`ValueError` if the value is already linked with a different member.
| Raises a :exc:`ValueError` if the value is already linked with a different member.
| See :ref:`multi-value-enum` for an example.

.. versionadded:: 3.13

Expand Down Expand Up @@ -879,14 +919,16 @@ Data Types

---------------

.. _enum-dunder-sunder:

Supported ``__dunder__`` names
""""""""""""""""""""""""""""""

:attr:`~EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
items. It is only available on the class.

:meth:`~Enum.__new__`, if specified, must create and return the enum members;
it is also a very good idea to set the member's :attr:`!_value_` appropriately.
it is also a very good idea to set the member's :attr:`~Enum._value_` appropriately.
Once all the members are created it is no longer used.


Expand All @@ -902,17 +944,10 @@ Supported ``_sunder_`` names
from the final class
- :attr:`~Enum._order_` -- no longer used, kept for backward
compatibility (class attribute, removed during class creation)

- :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
an enum member; may be overridden

.. note::

For standard :class:`Enum` classes the next value chosen is the highest
value seen incremented by one.

For :class:`Flag` classes the next value chosen will be the next highest
power-of-two.

- :meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing
member.
- :meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an
Expand Down
Loading