From 3e95ffc7aefb970bfd23e488381eab0dc71532e5 Mon Sep 17 00:00:00 2001
From: Ethan Furman <ethan@stoneleaf.us>
Date: Fri, 21 Oct 2022 15:36:41 -0700
Subject: [PATCH] gh-98298: [Enum] document ReprEnum, global_enum, and
show_flag_values (GH-98455)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
---
Doc/library/enum.rst | 48 +++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 47 insertions(+), 1 deletion(-)
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index a30a7a4ca34..1f317b9013d 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -92,6 +92,11 @@ Module Contents
the bitwise operators without losing their :class:`IntFlag` membership.
:class:`IntFlag` members are also subclasses of :class:`int`. (`Notes`_)
+ :class:`ReprEnum`
+
+ Used by :class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag`
+ to keep the :class:`str() <str>` of the mixed-in type.
+
:class:`EnumCheck`
An enumeration with the values ``CONTINUOUS``, ``NAMED_FLAGS``, and
@@ -132,9 +137,20 @@ Module Contents
Do not make ``obj`` a member. Can be used as a decorator.
+ :func:`global_enum`
+
+ Modify the :class:`str() <str>` and :func:`repr` of an enum
+ to show its members as belonging to the module instead of its class.
+ Should only be used if the enum members will be exported to the
+ module global namespace.
+
+ :func:`show_flag_values`
+
+ Return a list of all power-of-two integers contained in a flag.
+
.. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto``
-.. versionadded:: 3.11 ``StrEnum``, ``EnumCheck``, ``FlagBoundary``, ``property``, ``member``, ``nonmember``
+.. versionadded:: 3.11 ``StrEnum``, ``EnumCheck``, ``ReprEnum``, ``FlagBoundary``, ``property``, ``member``, ``nonmember``, ``global_enum``, ``show_flag_values``
---------------
@@ -573,6 +589,20 @@ Data Types
better support the *replacement of existing constants* use-case.
:meth:`__format__` was already :func:`int.__format__` for that same reason.
+.. class:: ReprEnum
+
+ :class:`!ReprEum` uses the :meth:`repr() <Enum.__repr__>` of :class:`Enum`,
+ but the :class:`str() <str>` of the mixed-in data type:
+
+ * :meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`
+ * :meth:`!str.__str__` for :class:`StrEnum`
+
+ Inherit from :class:`!ReprEnum` to keep the :class:`str() <str> / :func:`format`
+ of the mixed-in data type instead of using the
+ :class:`Enum`-default :meth:`str() <Enum.__str__>`.
+
+
+ .. versionadded:: 3.11
.. class:: EnumCheck
@@ -808,6 +838,22 @@ Utilities and Decorators
.. versionadded:: 3.11
+.. decorator:: global_enum
+
+ A decorator to change the :class:`str() <str>` and :func:`repr` of an enum
+ to show its members as belonging to the module instead of its class.
+ Should only be used when the enum members are exported
+ to the module global namespace (see :class:`re.RegexFlag` for an example).
+
+
+ .. versionadded:: 3.11
+
+.. function:: show_flag_values(value)
+
+ Return a list of all power-of-two integers contained in a flag *value*.
+
+ .. versionadded:: 3.11
+
---------------
Notes
--
GitLab