From 2e15caa298e223531b2e3658fc19116bbd4f3ac2 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 15 Oct 2022 13:40:44 -0500 Subject: [PATCH 1/5] Whatsnew: Convert literals in enum section to actual x-references --- Doc/whatsnew/3.11.rst | 61 ++++++++++++++++++++++++++----------------- 1 file changed, 37 insertions(+), 24 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 56a35f4e4802ba..42018aa179fc60 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -619,46 +619,59 @@ datetime formats (barring only those that support fractional hours and minutes). (Contributed by Paul Ganssle in :gh:`80010`.) + +.. _whatsnew311-enum: + enum ---- -* ``EnumMeta`` renamed to ``EnumType`` (``EnumMeta`` kept as alias). +* :class:`!EnumMeta` renamed to :class:`~enum.EnumType` + (:class:`!EnumMeta` kept as alias). -* ``StrEnum`` added -- enum members are and must be strings. +* :class:`~enum.StrEnum` added -- enum members are and must be strings. -* ``ReprEnum`` added -- causes only the ``__repr__`` to be modified, not the - ``__str__`` nor the ``__format__``. +* :class:`~enum.ReprEnum` added -- + causes only the :meth:`~object.__repr__` to be modified, + not the :meth:`~object.__str__` nor the :meth:`~object.__format__`. -* ``FlagBoundary`` added -- controls behavior when invalid values are given to - a flag. +* :class:`~enum.FlagBoundary` added -- + controls behavior when invalid values are given to a flag. -* ``EnumCheck`` added -- used by ``verify`` to ensure various constraints. +* :class:`~enum.EnumCheck` added -- + used by :func:`~enum.verify` to ensure various constraints. -* ``verify`` added -- function to ensure given ``EnumCheck`` constraints. +* :func:`~enum.verify` added -- + function to ensure given :class:`~enum.EnumCheck` constraints. -* ``member`` added -- decorator to ensure given object is converted to an enum - member. +* :func:`~enum.member` added -- + decorator to ensure given object is converted to an enum member. -* ``nonmember`` added -- decorator to ensure given object is not converted to - an enum member. +* :func:`~enum.nonmember` added -- + decorator to ensure given object is not converted to an enum member. -* ``property`` added -- use instead of ``types.DynamicClassAttribute``. +* :func:`~enum.property` added -- + use instead of :func:`types.DynamicClassAttribute`. -* ``global_enum`` added -- enum decorator to adjust ``__repr__`` and ``__str__`` - to show members in the global context -- see ``re.RegexFlag`` for an example. +* :func:`~enum.global_enum` added -- + enum decorator to adjust :meth:`~object.__repr__` and :meth:`~object.__str__` + to show members in the global context. + See :class:`re.RegexFlag` for an example. -* ``Flag`` enhancements: members support length, iteration, and containment - checks. +* :class:`~enum.Flag` enhancements: + members support length, iteration, and containment checks. -* ``Enum``/``Flag`` fixes: members are now defined before ``__init_subclass__`` - is called; ``dir()`` now includes methods, etc., from mixed-in data types. +* :class:`~enum.Enum`/:class:`~enum.Flag` fixes: + members are now defined before :meth:`~object.__init_subclass__` is called; + :func:`dir` now includes methods, etc., from mixed-in data types. -* ``Flag`` fixes: only primary values (power of two) are considered canonical - while composite values (3, 6, 10, etc.) are considered aliases; inverted - flags are coerced to their positive equivalent. +* :class:`~enum.Flag` fixes: + only primary values (power of two) are considered canonical + while composite values (3, 6, 10, etc.) are considered aliases; + inverted flags are coerced to their positive equivalent. -* ``IntEnum`` / ``IntFlag`` / ``StrEnum`` fixes: these now inherit from - ``ReprEnum`` so the ``str()`` output now matches ``format()`` output, +* :class:`~enum.IntEnum` / :class:`~enum.IntFlag` / :class:`~enum.StrEnum` fixes: + these now inherit from :class:`~enum.ReprEnum` + so the :func:`str` output now matches :func:`format` output, which is the data types' (so both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` is equal to ``'1'``). From 9a61957ab61e6e04be81c91cd9c397059ca9cf9c Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 15 Oct 2022 14:36:47 -0500 Subject: [PATCH 2/5] Whatsnew: Rewrite enum section for clear and consistant phrasing --- Doc/whatsnew/3.11.rst | 75 +++++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 34 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 42018aa179fc60..f202cfdb627dcb 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -625,55 +625,62 @@ datetime enum ---- -* :class:`!EnumMeta` renamed to :class:`~enum.EnumType` - (:class:`!EnumMeta` kept as alias). +* Renamed :class:`!EnumMeta` to :class:`~enum.EnumType` + (:class:`!EnumMeta` kept as an alias). -* :class:`~enum.StrEnum` added -- enum members are and must be strings. +* Added :class:`~enum.StrEnum`, + with members that can be used as (and must be) strings. -* :class:`~enum.ReprEnum` added -- - causes only the :meth:`~object.__repr__` to be modified, - not the :meth:`~object.__str__` nor the :meth:`~object.__format__`. +* Added :class:`~enum.ReprEnum`, + which only modifies the :meth:`~object.__repr__` of members + while returning just their values for + :meth:`~object.__str__` and :meth:`~object.__format__` -* :class:`~enum.FlagBoundary` added -- - controls behavior when invalid values are given to a flag. +* Added the :class:`~enum.FlagBoundary` enum, + containing the options for the *behavior* class parameter + to :class:`~enum.Flag` enums, controlling how to handle out-of-range values. -* :class:`~enum.EnumCheck` added -- - used by :func:`~enum.verify` to ensure various constraints. +* Added the :class:`~enum.EnumCheck` enum, + containing the flags to pass to the :meth:`~enum.verify` decorator + to control what constraints are checked. -* :func:`~enum.verify` added -- - function to ensure given :class:`~enum.EnumCheck` constraints. +* Added the :func:`~enum.verify` enum decorator, + to check the passed :class:`~enum.EnumCheck` constraints. -* :func:`~enum.member` added -- - decorator to ensure given object is converted to an enum member. +* Added the :func:`~enum.member` decorator, + to ensure the decorated object is converted to an enum member. -* :func:`~enum.nonmember` added -- - decorator to ensure given object is not converted to an enum member. +* Added the :func:`~enum.nonmember` decorator, + to ensure the decorated object is not converted to an enum member. -* :func:`~enum.property` added -- - use instead of :func:`types.DynamicClassAttribute`. +* Added the :func:`~enum.property` decorator, + which works like :func:`property` except for enums. + Use this instead of :func:`types.DynamicClassAttribute`. -* :func:`~enum.global_enum` added -- - enum decorator to adjust :meth:`~object.__repr__` and :meth:`~object.__str__` - to show members in the global context. - See :class:`re.RegexFlag` for an example. +* Added the :func:`~enum.global_enum` enum decorator, + which adjusts :meth:`~object.__repr__` and :meth:`~object.__str__` + to show values as members of their module rather than the enum class. + For example, ``'re.ASCII'`` for the :data:`~re.ASCII` member + of :class:`re.RegexFlag` rather than ``'RegexFlag.ASCII'``. -* :class:`~enum.Flag` enhancements: - members support length, iteration, and containment checks. +* Enhanced :class:`~enum.Flag` + to support length, iteration, and contains checks on its members. -* :class:`~enum.Enum`/:class:`~enum.Flag` fixes: - members are now defined before :meth:`~object.__init_subclass__` is called; - :func:`dir` now includes methods, etc., from mixed-in data types. +* Changed :class:`~enum.Enum` and :class:`~enum.Flag` + so that members are now defined + before :meth:`~object.__init_subclass__` is called; + :func:`dir` now includes methods, etc., from mixed-in data types. -* :class:`~enum.Flag` fixes: - only primary values (power of two) are considered canonical - while composite values (3, 6, 10, etc.) are considered aliases; +* Changed :class:`~enum.Flag` + to only consider primary values (power of two) canonical + while composite values (``3``, ``6``, ``10``, etc.) are considered aliases; inverted flags are coerced to their positive equivalent. -* :class:`~enum.IntEnum` / :class:`~enum.IntFlag` / :class:`~enum.StrEnum` fixes: - these now inherit from :class:`~enum.ReprEnum` +* Changed :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum` + to inherit from :class:`~enum.ReprEnum` so the :func:`str` output now matches :func:`format` output, - which is the data types' (so both ``str(AnIntEnum.ONE)`` and - ``format(AnIntEnum.ONE)`` is equal to ``'1'``). + which is just the default string representation of their values + (so both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` return ``'1'``). fractions --------- From 1ddd452d6125123f3840e80e5976022dd2b61322 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 15 Oct 2022 14:56:02 -0500 Subject: [PATCH 3/5] Whatsnew: Combine directly related enum items instead of seperating them --- Doc/whatsnew/3.11.rst | 36 ++++++++++++++---------------------- 1 file changed, 14 insertions(+), 22 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index f202cfdb627dcb..eff8f89e4840f4 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -634,24 +634,21 @@ enum * Added :class:`~enum.ReprEnum`, which only modifies the :meth:`~object.__repr__` of members while returning just their values for - :meth:`~object.__str__` and :meth:`~object.__format__` + :meth:`~object.__str__` and :meth:`~object.__format__`. + :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum` + now inherit from it, so their :func:`str` output now matches :func:`format` + (both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` return ``'1'``). -* Added the :class:`~enum.FlagBoundary` enum, - containing the options for the *behavior* class parameter - to :class:`~enum.Flag` enums, controlling how to handle out-of-range values. +* Added a new *boundary* class parameter to :class:`~enum.Flag` enums + and the :class:`~enum.FlagBoundary` enum with its options, + to control how to handle out-of-range flag values. -* Added the :class:`~enum.EnumCheck` enum, - containing the flags to pass to the :meth:`~enum.verify` decorator - to control what constraints are checked. +* Added the :func:`~enum.verify` enum decorator + and the :class:`~enum.EnumCheck` enum with its options, + to check enum classes against several specific constraints. -* Added the :func:`~enum.verify` enum decorator, - to check the passed :class:`~enum.EnumCheck` constraints. - -* Added the :func:`~enum.member` decorator, - to ensure the decorated object is converted to an enum member. - -* Added the :func:`~enum.nonmember` decorator, - to ensure the decorated object is not converted to an enum member. +* Added the :func:`~enum.member` and :func:`~enum.nonmember` decorators, + to ensure the decorated object is/is not converted to an enum member. * Added the :func:`~enum.property` decorator, which works like :func:`property` except for enums. @@ -663,8 +660,8 @@ enum For example, ``'re.ASCII'`` for the :data:`~re.ASCII` member of :class:`re.RegexFlag` rather than ``'RegexFlag.ASCII'``. -* Enhanced :class:`~enum.Flag` - to support length, iteration, and contains checks on its members. +* Enhanced :class:`~enum.Flag` to support + :func:`len`, iteration and :keyword:`in`/:keyword:`not in` on its members. * Changed :class:`~enum.Enum` and :class:`~enum.Flag` so that members are now defined @@ -676,11 +673,6 @@ enum while composite values (``3``, ``6``, ``10``, etc.) are considered aliases; inverted flags are coerced to their positive equivalent. -* Changed :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum` - to inherit from :class:`~enum.ReprEnum` - so the :func:`str` output now matches :func:`format` output, - which is just the default string representation of their values - (so both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` return ``'1'``). fractions --------- From a596720e72256e951b4ae86a867b5cdd1c9c1732 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Sat, 15 Oct 2022 18:08:21 -0500 Subject: [PATCH 4/5] gh-98250: Describe __str__/__format__ changes more clearly/accurately --- Doc/whatsnew/3.11.rst | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index eff8f89e4840f4..5351c33cf91ffd 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -633,11 +633,23 @@ enum * Added :class:`~enum.ReprEnum`, which only modifies the :meth:`~object.__repr__` of members - while returning just their values for - :meth:`~object.__str__` and :meth:`~object.__format__`. - :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum` - now inherit from it, so their :func:`str` output now matches :func:`format` - (both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` return ``'1'``). + while returning their literal values (rather than keys) + for :meth:`~object.__str__` and :meth:`~object.__format__` + (used by :func:`str`, :func:`format` and :term:`f-string`\s). + +* Changed :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum` + to now inherit from :class:`ReprEnum`, + so their :func:`str` output now matches :func:`format` + (both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` return ``'1'``, + whereas before ``str(AnIntEnum.ONE)`` returned ``'AnIntEnum.ONE'``. + +* Changed :meth:`Enum.__format__() ` + (the default for :func:`format`, :meth:`str.format` and :term:`f-string`\s) + of enums with mixed-in types (e.g. :class:`int`, :class:`str`) + to also include the class name in the output, not just the member's key. + This matches the existing behavior of :meth:`enum.Enum.__str__`, + returning e.g. ``'AnEnum.MEMBER'`` for an enum ``AnEnum(str, Enum)`` + instead of just ``'MEMBER'``. * Added a new *boundary* class parameter to :class:`~enum.Flag` enums and the :class:`~enum.FlagBoundary` enum with its options, From 9d2486e072c406b09184e23064295a55b8ea5b40 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 17 Oct 2022 12:30:23 -0500 Subject: [PATCH 5/5] Tweak enum section language per feedback from Ethan --- Doc/whatsnew/3.11.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 5351c33cf91ffd..9bd3dc0d28454d 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -633,7 +633,7 @@ enum * Added :class:`~enum.ReprEnum`, which only modifies the :meth:`~object.__repr__` of members - while returning their literal values (rather than keys) + while returning their literal values (rather than names) for :meth:`~object.__str__` and :meth:`~object.__format__` (used by :func:`str`, :func:`format` and :term:`f-string`\s). @@ -674,6 +674,8 @@ enum * Enhanced :class:`~enum.Flag` to support :func:`len`, iteration and :keyword:`in`/:keyword:`not in` on its members. + For example, the following now works: + ``len(AFlag(3)) == 2 and list(AFlag(3)) == (AFlag.ONE, AFlag.TWO)`` * Changed :class:`~enum.Enum` and :class:`~enum.Flag` so that members are now defined