From 3b5746053ae47a7670ca6e3bd38d3a7f3072fbf5 Mon Sep 17 00:00:00 2001 From: RafaelWO <38643099+RafaelWO@users.noreply.github.com> Date: Thu, 21 Aug 2025 17:36:28 +0000 Subject: [PATCH 1/4] Move parts of Enum how-to to API docs To avoid duplicate content in the Enum HOWTO and API documentation which is not automatically synced, the section about supported __dunder__ and _sunder names is moved from HOWTO to API docs. See also https://github.com/python/cpython/pull/136791 --- Doc/howto/enum.rst | 66 +++----------------------------------------- Doc/library/enum.rst | 28 +++++++++++++++++-- 2 files changed, 30 insertions(+), 64 deletions(-) diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index 7713aede6d564a..ef6881c18f863e 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -967,69 +967,10 @@ want one of them to be the value:: Finer Points ^^^^^^^^^^^^ -Supported ``__dunder__`` names -"""""""""""""""""""""""""""""" +Supported ``__dunder__`` and ``_sunder_`` 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. - - .. 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 `. _Private__names @@ -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 ^^^^^^^^^^^^^^^^^ diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 8875669ffccc37..5c170bba1cf2ec 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -301,6 +301,26 @@ 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. + .. attribute:: Enum._ignore_ ``_ignore_`` is only used during creation and is removed from the @@ -480,7 +500,8 @@ Data Types >>> Color(42) - 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 @@ -879,6 +900,8 @@ Data Types --------------- +.. _enum-dunder-sunder: + Supported ``__dunder__`` names """""""""""""""""""""""""""""" @@ -886,7 +909,7 @@ Supported ``__dunder__`` names 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. @@ -902,6 +925,7 @@ 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 From 706ad60b5269c1f7fa3beb761cdf518c69219fa5 Mon Sep 17 00:00:00 2001 From: RafaelWO <38643099+RafaelWO@users.noreply.github.com> Date: Thu, 28 Aug 2025 07:25:32 +0000 Subject: [PATCH 2/4] Move "Finer Points" in Enum HOWTO one level out Before this change, the section "Finer Points" was a subsection of "When to use __new__() vs. __init__()" which does not make much sense. This change moves "Finer Points" one level out making it a top level section. All its subsections are moved as well. --- Doc/howto/enum.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst index ef6881c18f863e..93850b57af2c65 100644 --- a/Doc/howto/enum.rst +++ b/Doc/howto/enum.rst @@ -965,16 +965,16 @@ want one of them to be the value:: Finer Points -^^^^^^^^^^^^ +------------ Supported ``__dunder__`` and ``_sunder_`` names -""""""""""""""""""""""""""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The supported ``__dunder__`` and ``_sunder_`` names can be found in the :ref:`Enum API documentation `. _Private__names -""""""""""""""" +^^^^^^^^^^^^^^^ :ref:`Private names ` are not converted to enum members, but remain normal attributes. @@ -983,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 @@ -996,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 @@ -1010,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 @@ -1025,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, @@ -1038,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:: @@ -1058,7 +1058,7 @@ are comprised of a single bit:: ``Flag`` and ``IntFlag`` minutia -"""""""""""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Using the following snippet for our examples:: From 6c757197862d3f68934d4f9aea9a14b85868f132 Mon Sep 17 00:00:00 2001 From: Rafael Weingartner-Ortner Date: Sun, 14 Sep 2025 16:39:30 +0200 Subject: [PATCH 3/4] Add version changed indicators to Enum members The Enum members listed in the sections of `__dunder__` and `_sunder_` did not have version indicators in the API docs. This changes adds the version indicators mentioned in the `__dunder__` and `_sunder_` section to the corresponding Enum member. --- Doc/library/enum.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 5c170bba1cf2ec..4bc406236775c3 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -321,6 +321,8 @@ Data Types 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 @@ -330,6 +332,8 @@ Data Types names will also be removed from the completed enumeration. See :ref:`TimePeriod ` for an example. + .. versionadded:: 3.7 + .. method:: Enum.__dir__(self) Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and @@ -372,6 +376,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 @@ -410,6 +418,8 @@ Data Types >>> Build('deBUG') + .. versionadded:: 3.6 + .. method:: Enum.__new__(cls, *args, **kwds) By default, doesn't exist. If specified, either in the enum class From ff84f9470267d08ef1c027509599cb59e26e2d51 Mon Sep 17 00:00:00 2001 From: Rafael Weingartner-Ortner Date: Sun, 14 Sep 2025 16:42:02 +0200 Subject: [PATCH 4/4] Move note for Enum member to API section This changes moves a note for the Enum member `_generate_next_value_` from the `_sunder_` section to the API section. The intention is to let `_sunder_` section list all members but have the details in the API section. --- Doc/library/enum.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 4bc406236775c3..4270a978282411 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -363,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): @@ -939,14 +948,6 @@ Supported ``_sunder_`` names - :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