diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst index 56a35f4e4802ba..9bd3dc0d28454d 100644 --- a/Doc/whatsnew/3.11.rst +++ b/Doc/whatsnew/3.11.rst @@ -619,48 +619,74 @@ datetime formats (barring only those that support fractional hours and minutes). (Contributed by Paul Ganssle in :gh:`80010`.) -enum ----- - -* ``EnumMeta`` renamed to ``EnumType`` (``EnumMeta`` kept as alias). - -* ``StrEnum`` added -- enum members are and must be strings. - -* ``ReprEnum`` added -- causes only the ``__repr__`` to be modified, not the - ``__str__`` nor the ``__format__``. - -* ``FlagBoundary`` added -- controls behavior when invalid values are given to - a flag. - -* ``EnumCheck`` added -- used by ``verify`` to ensure various constraints. -* ``verify`` added -- function to ensure given ``EnumCheck`` constraints. +.. _whatsnew311-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. - -* ``property`` added -- use instead of ``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. - -* ``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. +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. +* Renamed :class:`!EnumMeta` to :class:`~enum.EnumType` + (:class:`!EnumMeta` kept as an alias). + +* Added :class:`~enum.StrEnum`, + with members that can be used as (and must be) strings. + +* Added :class:`~enum.ReprEnum`, + which only modifies the :meth:`~object.__repr__` of members + 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). + +* 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, + to control how to handle out-of-range flag values. + +* 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.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. + Use this instead of :func:`types.DynamicClassAttribute`. + +* 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'``. + +* 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 + before :meth:`~object.__init_subclass__` is called; + :func:`dir` now includes methods, etc., from mixed-in data types. + +* 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. -* ``IntEnum`` / ``IntFlag`` / ``StrEnum`` fixes: these now inherit from - ``ReprEnum`` so the ``str()`` output now matches ``format()`` output, - which is the data types' (so both ``str(AnIntEnum.ONE)`` and - ``format(AnIntEnum.ONE)`` is equal to ``'1'``). fractions ---------