mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-24 03:35:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

gh-98298: [Enum] document ReprEnum, global_enum, and show_flag_values (GH-98455)

Browse source 
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit 3e95ffc7ae)

Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
This commit is contained in:
Miss Islington (bot) 2022-10-21 15:43:23 -07:00 • committed by GitHub
parent b2aa28eec5
commit 31d23ae894
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 47 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

48
Doc/library/enum.rst
View file

@ -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``
---------------
@ -580,6 +596,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
@ -815,6 +845,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