From 2e9a6c8ef98426fe291a0cddb46f9bb2c71759f4 Mon Sep 17 00:00:00 2001 From: Ethan Furman Date: Wed, 19 Oct 2022 09:27:26 -0700 Subject: [PATCH 1/3] document ReprEnum, global_enum, and show_flag_values --- Doc/library/enum.rst | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index a30a7a4ca34300..d69fb3edb7e772 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 ``IntEnum``, ``StrEnum``, and ``IntFlag`` to keep the ``str()`` of + the mixed-in type. + :class:`EnumCheck` An enumeration with the values ``CONTINUOUS``, ``NAMED_FLAGS``, and @@ -132,9 +137,19 @@ Module Contents Do not make ``obj`` a member. Can be used as a decorator. + :func:`global_enum` + + Modify the ``str()`` and ``repr()`` of an enum to show its module instead of + its class -- should only be used if the enum members will be exported to the + 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 +588,17 @@ Data Types better support the *replacement of existing constants* use-case. :meth:`__format__` was already :func:`int.__format__` for that same reason. +.. class:: ReprEnum + + *ReprEum* uses the *repr()* of *Enum*, but the *str()* of the mixed-in data type: + + * :meth:`int.__str__` for *IntEnum* and *IntFlag* + * :meth:`str.__str__` for *StrEnum* + + Inherit from *ReprEnum* when mixing in a data type when the *str()* output should + not be changed to the *Enum*-default *str()*. + + .. versionadded:: 3.11 .. class:: EnumCheck @@ -808,6 +834,20 @@ Utilities and Decorators .. versionadded:: 3.11 +.. decorator:: global_enum + + A decorator to change the *str()* and *repr()* of an enum to show the module + of the enum instead of its class. Should only be used when the enum members + are exported to the global namespace (see *re.RegexFlag* for an example). + + .. versionadded:: 3.11 + +.. function:: show_flag_values + + Return a list of all power-of-two integers contained in a flag. + + .. versionadded:: 3.11 + --------------- Notes From 25059f783b9eb2386eea85d9e47484d94f661d01 Mon Sep 17 00:00:00 2001 From: Ethan Furman Date: Thu, 20 Oct 2022 15:52:10 -0700 Subject: [PATCH 2/3] incorporate suggestions from CAM-Gerlach --- Doc/library/enum.rst | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index d69fb3edb7e772..b67d6b048788fd 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -94,8 +94,8 @@ Module Contents :class:`ReprEnum` - Used by ``IntEnum``, ``StrEnum``, and ``IntFlag`` to keep the ``str()`` of - the mixed-in type. + Used by :class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag` + to keep the :class:`str() ` of the mixed-in type. :class:`EnumCheck` @@ -139,9 +139,10 @@ Module Contents :func:`global_enum` - Modify the ``str()`` and ``repr()`` of an enum to show its module instead of - its class -- should only be used if the enum members will be exported to the - global namespace. + Modify the :class:`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` @@ -590,13 +591,16 @@ Data Types .. class:: ReprEnum - *ReprEum* uses the *repr()* of *Enum*, but the *str()* of the mixed-in data type: + :class:`!ReprEum` uses the :meth:`repr() ` of :class:`Enum`, + but the :class:`str() ` of the mixed-in data type: - * :meth:`int.__str__` for *IntEnum* and *IntFlag* - * :meth:`str.__str__` for *StrEnum* + * :meth:`int.__str__` for :class:`IntEnum` and :class:`IntFlag` + * :meth:`str.__str__` for :class:`StrEnum` + + Inherit from :class:`!ReprEnum` when mixing in a data type when the + :class:`str() ` output should not be changed to the + :class:`Enum`-default :meth:`str() `. - Inherit from *ReprEnum* when mixing in a data type when the *str()* output should - not be changed to the *Enum*-default *str()*. .. versionadded:: 3.11 @@ -836,15 +840,17 @@ Utilities and Decorators .. decorator:: global_enum - A decorator to change the *str()* and *repr()* of an enum to show the module - of the enum instead of its class. Should only be used when the enum members - are exported to the global namespace (see *re.RegexFlag* for an example). + A decorator to change the :class:`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 +.. function:: show_flag_values(value) - Return a list of all power-of-two integers contained in a flag. + Return a list of all power-of-two integers contained in a flag *value*. .. versionadded:: 3.11 From 5fabc7838b5b4ac2bd5432df66513d68e5a47bbb Mon Sep 17 00:00:00 2001 From: Ethan Furman Date: Fri, 21 Oct 2022 10:47:31 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- 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 b67d6b048788fd..1f317b9013d8db 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -594,11 +594,11 @@ Data Types :class:`!ReprEum` uses the :meth:`repr() ` of :class:`Enum`, but the :class:`str() ` of the mixed-in data type: - * :meth:`int.__str__` for :class:`IntEnum` and :class:`IntFlag` - * :meth:`str.__str__` for :class:`StrEnum` + * :meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag` + * :meth:`!str.__str__` for :class:`StrEnum` - Inherit from :class:`!ReprEnum` when mixing in a data type when the - :class:`str() ` output should not be changed to the + Inherit from :class:`!ReprEnum` to keep the :class:`str() / :func:`format` + of the mixed-in data type instead of using the :class:`Enum`-default :meth:`str() `. @@ -843,7 +843,7 @@ Utilities and Decorators A decorator to change the :class:`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). + to the module global namespace (see :class:`re.RegexFlag` for an example). .. versionadded:: 3.11