Skip to content

gh-136672: Docs: Move Enum functions and add examples #136791

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.

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

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 2 additions & 2 deletions Doc/howto/enum.rst
Original file line number Diff line number Diff line change
Expand Up @@ -990,9 +990,9 @@ Supported ``_sunder_`` names
from the final class
- :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
an enum member; may be overridden
- :meth:`~EnumType._add_alias_` -- adds a new name as an alias to an existing
- :meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing
member.
- :meth:`~EnumType._add_value_alias_` -- adds a new value as an alias to an
- :meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an
existing member. See `MultiValueEnum`_ for an example.

.. note::
Expand Down
53 changes: 34 additions & 19 deletions Doc/library/enum.rst
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,10 @@ Data Types
final *enum*, as well as creating the enum members, properly handling
duplicates, providing iteration over the enum class, etc.

.. versionadded:: 3.11

Before 3.11 ``EnumType`` was called ``EnumMeta``, which is still available as an alias.

.. method:: EnumType.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

This method is called in two different ways:
Expand Down Expand Up @@ -206,7 +210,7 @@ Data Types
>>> Color.RED.value in Color
True

.. versionchanged:: 3.12
.. versionchanged:: 3.12

Before Python 3.12, a ``TypeError`` is raised if a
non-Enum-member is used in a containment check.
Expand Down Expand Up @@ -251,20 +255,6 @@ Data Types
>>> list(reversed(Color))
[<Color.BLUE: 3>, <Color.GREEN: 2>, <Color.RED: 1>]

.. method:: EnumType._add_alias_

Adds a new name as an alias to an existing member. Raises a
:exc:`NameError` if the name is already assigned to a different member.

.. method:: EnumType._add_value_alias_

Adds a new value as an alias to an existing member. Raises a
:exc:`ValueError` if the value is already linked with a different member.

.. versionadded:: 3.11

Before 3.11 ``EnumType`` was called ``EnumMeta``, which is still available as an alias.


.. class:: Enum

Expand Down Expand Up @@ -470,6 +460,30 @@ Data Types

.. versionchanged:: 3.12 Added :ref:`enum-dataclass-support`

.. method:: Enum._add_alias_

Adds a new name as an alias to an existing member::

>>> Color._add_alias_(Color.RED, "ERROR")
>>> Color.ERROR
<Color.RED: 1>

Raises a :exc:`NameError` if the name is already assigned to a different member.

.. versionadded:: 3.13

.. method:: Enum._add_value_alias_

Adds a new value as an alias to an existing member::

>>> Color._add_value_alias_(Color.RED, 42)
>>> Color(42)
<Color.RED: 1>

Raises a :exc:`ValueError` if the value is already linked with a different member.

.. versionadded:: 3.13


.. class:: IntEnum

Expand Down Expand Up @@ -864,10 +878,6 @@ Once all the members are created it is no longer used.
Supported ``_sunder_`` names
""""""""""""""""""""""""""""

- :meth:`~EnumType._add_alias_` -- adds a new name as an alias to an existing
member.
- :meth:`~EnumType._add_value_alias_` -- adds a new value as an alias to an
existing member.
- :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;
Expand All @@ -888,6 +898,11 @@ Supported ``_sunder_`` names
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
existing member.

- While ``_sunder_`` names are generally reserved for the further development
of the :class:`Enum` class and can not be used, some are explicitly allowed:

Expand Down
Loading