From d00adac946aa136019f7c7ee68c0a230c4179111 Mon Sep 17 00:00:00 2001 From: Rafi Date: Sun, 14 Jul 2024 10:17:19 +0200 Subject: [PATCH 1/5] Document EnumDict in docs and release notes --- Doc/library/enum.rst | 20 +++++++++++++++++++- Doc/whatsnew/3.13.rst | 5 +++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 8b3f397ea862f4..8192d270208381 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -64,6 +64,10 @@ are not normal Python classes. See Module Contents --------------- + :class:`EnumDict` + + An enum class :class:`dict` that tracks order and enforces unique member names. + :class:`EnumType` The ``type`` for Enum and its subclasses. @@ -159,7 +163,21 @@ Data Types ---------- -.. class:: EnumType +.. class:: EnumDict + + *EnumDict* is used by *EnumType* to keep track of the enum member orders and prevent reusing the member names. + + .. attribute:: EnumDict.member_names + + Return list of member names. + + .. method:: EnumDict.__setitem__(self, key, value) + + Set any item as an enum member that is not dundered and not a descriptor. + + .. method:: EnumDict.update(self, members, **more_members) + + Update the dictionary from the given iterable or dictionary members and more_members. *EnumType* is the :term:`metaclass` for *enum* enumerations. It is possible to subclass *EnumType* -- see :ref:`Subclassing EnumType ` diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst index 4a9a0b77d068b3..97e64abc9c8beb 100644 --- a/Doc/whatsnew/3.13.rst +++ b/Doc/whatsnew/3.13.rst @@ -742,6 +742,11 @@ email (Contributed by Thomas Dwyer and Victor Stinner for :gh:`102988` to improve the :cve:`2023-27043` fix.) +enum +---- + +* :class:`~enum.EnumDict` has been made public in :mod:`enum`. + fractions --------- From 3bff0b954adddedc766cf8309d06b62e7d9e139f Mon Sep 17 00:00:00 2001 From: Rafi Date: Sun, 14 Jul 2024 10:26:43 +0200 Subject: [PATCH 2/5] Restore deleted EnumType --- Doc/library/enum.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 8192d270208381..d6f14745bb5fb2 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -183,6 +183,8 @@ Data Types to subclass *EnumType* -- see :ref:`Subclassing EnumType ` for details. +.. class:: EnumType + ``EnumType`` is responsible for setting the correct :meth:`!__repr__`, :meth:`!__str__`, :meth:`!__format__`, and :meth:`!__reduce__` methods on the final *enum*, as well as creating the enum members, properly handling From 11e2fd194b6c74f0c0b2f7c7d1babb52a488a33a Mon Sep 17 00:00:00 2001 From: Md Rokibul Islam Date: Tue, 16 Jul 2024 23:37:19 +0200 Subject: [PATCH 3/5] Update Doc/library/enum.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- 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 d6f14745bb5fb2..2d1d8c0cf1f680 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -179,12 +179,12 @@ Data Types Update the dictionary from the given iterable or dictionary members and more_members. +.. class:: EnumType + *EnumType* is the :term:`metaclass` for *enum* enumerations. It is possible to subclass *EnumType* -- see :ref:`Subclassing EnumType ` for details. -.. class:: EnumType - ``EnumType`` is responsible for setting the correct :meth:`!__repr__`, :meth:`!__str__`, :meth:`!__format__`, and :meth:`!__reduce__` methods on the final *enum*, as well as creating the enum members, properly handling From e8c368ef9bf2ae1ac2eda0a62650ef28d00fd50c Mon Sep 17 00:00:00 2001 From: Rafi Date: Sun, 28 Jul 2024 22:08:54 +0200 Subject: [PATCH 4/5] Update description --- 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 2d1d8c0cf1f680..426d0b86ff32bd 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -66,7 +66,7 @@ Module Contents :class:`EnumDict` - An enum class :class:`dict` that tracks order and enforces unique member names. + A subclass of :class:`dict` that tracks order and enforces unique member names. :class:`EnumType` @@ -165,7 +165,7 @@ Data Types .. class:: EnumDict - *EnumDict* is used by *EnumType* to keep track of the enum member orders and prevent reusing the member names. + *EnumDict* is a subclass of :class:`dict` that keeps track of the order of enum members and prevents reusing member names. Use *EnumDict* when member names must be unique and their order needs to be preserved. .. attribute:: EnumDict.member_names From 58fbf7ba81687a7732e90f105e19957a09562009 Mon Sep 17 00:00:00 2001 From: Ethan Furman Date: Thu, 19 Dec 2024 14:29:05 -0800 Subject: [PATCH 5/5] move entries; some rewording --- Doc/library/enum.rst | 37 ++++++++++++++++--------------------- Doc/whatsnew/3.13.rst | 3 ++- 2 files changed, 18 insertions(+), 22 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 426d0b86ff32bd..90ed62cc4db3c0 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -64,10 +64,6 @@ are not normal Python classes. See Module Contents --------------- - :class:`EnumDict` - - A subclass of :class:`dict` that tracks order and enforces unique member names. - :class:`EnumType` The ``type`` for Enum and its subclasses. @@ -153,9 +149,14 @@ Module Contents Return a list of all power-of-two integers contained in a flag. + :class:`EnumDict` + + A subclass of :class:`dict` for use when subclassing :class:`EnumType`. + .. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto`` .. versionadded:: 3.11 ``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, ``member``, ``nonmember``, ``global_enum``, ``show_flag_values`` +.. versionadded:: 3.14 ``EnumDict`` --------------- @@ -163,22 +164,6 @@ Data Types ---------- -.. class:: EnumDict - - *EnumDict* is a subclass of :class:`dict` that keeps track of the order of enum members and prevents reusing member names. Use *EnumDict* when member names must be unique and their order needs to be preserved. - - .. attribute:: EnumDict.member_names - - Return list of member names. - - .. method:: EnumDict.__setitem__(self, key, value) - - Set any item as an enum member that is not dundered and not a descriptor. - - .. method:: EnumDict.update(self, members, **more_members) - - Update the dictionary from the given iterable or dictionary members and more_members. - .. class:: EnumType *EnumType* is the :term:`metaclass` for *enum* enumerations. It is possible @@ -839,7 +824,17 @@ Data Types >>> KeepFlag(2**2 + 2**4) -.. versionadded:: 3.11 + .. versionadded:: 3.11 + +.. class:: EnumDict + + *EnumDict* is a subclass of :class:`dict` for use when subclassing :class:`EnumType`. + + .. attribute:: EnumDict.member_names + + Return list of member names. + + .. versionadded:: 3.14 --------------- diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst index 97e64abc9c8beb..f274da6eb19393 100644 --- a/Doc/whatsnew/3.13.rst +++ b/Doc/whatsnew/3.13.rst @@ -745,7 +745,8 @@ email enum ---- -* :class:`~enum.EnumDict` has been made public in :mod:`enum`. +* :class:`~enum.EnumDict` has been made public in :mod:`enum` to better support + subclassing :class:`~enum.EnumType`. fractions ---------