From 35d0d4859dc5d402d26fdc024d5924b56c9b34e5 Mon Sep 17 00:00:00 2001 From: RafaelWO Date: Sat, 19 Jul 2025 13:17:49 +0200 Subject: [PATCH 1/4] Docs: Move Enum functions and add examples When the `Enum` functions `_add_alias_` and `_add_value_alias_` were added in de6bca956432cc852a4a41e2a2cee9cdacd19f35, the documentation for them was done under `EnumType` instead of `Enum`. This change moves them to the docs of the `Enum` class and adds an example for each function. --- Doc/howto/enum.rst | 4 ++-- Doc/library/enum.rst | 38 ++++++++++++++++++++++++++------------ 2 files changed, 28 insertions(+), 14 deletions(-) diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index 6441b7aed1eda8..7713aede6d564a 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -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:: diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index c9b2c7d76b6746..f2586fb84f09e3 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -251,16 +251,6 @@ Data Types >>> list(reversed(Color)) [, , ] - .. 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. @@ -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 + + + 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) + + + Raises a :exc:`ValueError` if the value is already linked with a different member. + + .. versionadded:: 3.13 + .. class:: IntEnum @@ -864,9 +878,9 @@ 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 +- :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. - :attr:`~Enum._name_` -- name of the member - :attr:`~Enum._value_` -- value of the member; can be set in ``__new__`` From 4b25a5f553e37dc1e30c1b5e33b83e58a15b6ce3 Mon Sep 17 00:00:00 2001 From: RafaelWO Date: Sat, 19 Jul 2025 13:24:38 +0200 Subject: [PATCH 2/4] Docs: Move `versionadded` for `EnumType` This change moves the `versionadded` for `EnumType` to the top. Additionally, it fixes the indentation of another `versionchanged` entry. --- Doc/library/enum.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index f2586fb84f09e3..79ad1bd112977d 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -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: @@ -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. @@ -251,10 +255,6 @@ Data Types >>> list(reversed(Color)) [, , ] - .. versionadded:: 3.11 - - Before 3.11 ``EnumType`` was called ``EnumMeta``, which is still available as an alias. - .. class:: Enum From 614f8eff4a3804ff30985b717db507f701c79783 Mon Sep 17 00:00:00 2001 From: RafaelWO Date: Sun, 20 Jul 2025 10:53:14 +0200 Subject: [PATCH 3/4] fixup! Docs: Move Enum functions and add examples --- Doc/library/enum.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 79ad1bd112977d..af4b748cea6d23 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -878,10 +878,6 @@ Once all the members are created it is no longer used. Supported ``_sunder_`` names """""""""""""""""""""""""""" -- :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. - :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; @@ -902,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: From 01f450574bf785534e9b542706b0f05544c52c6a Mon Sep 17 00:00:00 2001 From: Ethan Furman Date: Mon, 11 Aug 2025 20:19:02 -0700 Subject: [PATCH 4/4] Apply suggestions from code review --- Doc/library/enum.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index af4b748cea6d23..c5cb34bc4d20da 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -464,7 +464,7 @@ Data Types Adds a new name as an alias to an existing member:: - >>> Color._add_alias_(Color.RED, "ERROR") + >>> Color.RED._add_alias_("ERROR") >>> Color.ERROR @@ -476,7 +476,7 @@ Data Types Adds a new value as an alias to an existing member:: - >>> Color._add_value_alias_(Color.RED, 42) + >>> Color.RED._add_value_alias_(42) >>> Color(42)