gh-136672: Docs: Move Enum functions and add examples (GH-136791)

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

---------

Co-authored-by: Ethan Furman <ethan@stoneleaf.us>

diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
index 6441b7aed1eda8c8f06fec6cf0d2c3a2bea7d659..7713aede6d564a46dc89b872bbfd0817af1774bf 100644 (file)
--- 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 2cfc2f4962979f49c5ab02961622e2f72e787c82..8875669ffccc378a97de9412b057df23835dd871 100644 (file)
--- 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,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
 
@@ -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.RED._add_alias_("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.RED._add_value_alias_(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
 
@@ -879,10 +893,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;
@@ -903,6 +913,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: