Skip to content

Commit 1f192c3

Browse files
miss-islingtonCAM-Gerlach
authored andcommitted
gh-95913: Copyedit, xref and organize enum section (GH-98295)
* Whatsnew: Convert literals in enum section to actual x-references * Whatsnew: Rewrite enum section for clear and consistant phrasing * Whatsnew: Combine directly related enum items instead of seperating them * gh-98250: Describe __str__/__format__ changes more clearly/accurately * Tweak enum section language per feedback from Ethan (cherry picked from commit 73e5180) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
1 parent 425bec3 commit 1f192c3

File tree

1 file changed

+64
-38
lines changed

1 file changed

+64
-38
lines changed

Doc/whatsnew/3.11.rst

+64-38
Original file line numberDiff line numberDiff line change
@@ -636,48 +636,74 @@ datetime
636636
formats (barring only those that support fractional hours and minutes).
637637
(Contributed by Paul Ganssle in :gh:`80010`.)
638638

639-
enum
640-
----
641-
642-
* ``EnumMeta`` renamed to ``EnumType`` (``EnumMeta`` kept as alias).
643-
644-
* ``StrEnum`` added -- enum members are and must be strings.
645-
646-
* ``ReprEnum`` added -- causes only the ``__repr__`` to be modified, not the
647-
``__str__`` nor the ``__format__``.
648-
649-
* ``FlagBoundary`` added -- controls behavior when invalid values are given to
650-
a flag.
651-
652-
* ``EnumCheck`` added -- used by ``verify`` to ensure various constraints.
653639

654-
* ``verify`` added -- function to ensure given ``EnumCheck`` constraints.
640+
.. _whatsnew311-enum:
655641

656-
* ``member`` added -- decorator to ensure given object is converted to an enum
657-
member.
658-
659-
* ``nonmember`` added -- decorator to ensure given object is not converted to
660-
an enum member.
661-
662-
* ``property`` added -- use instead of ``types.DynamicClassAttribute``.
663-
664-
* ``global_enum`` added -- enum decorator to adjust ``__repr__`` and ``__str__``
665-
to show members in the global context -- see ``re.RegexFlag`` for an example.
666-
667-
* ``Flag`` enhancements: members support length, iteration, and containment
668-
checks.
669-
670-
* ``Enum``/``Flag`` fixes: members are now defined before ``__init_subclass__``
671-
is called; ``dir()`` now includes methods, etc., from mixed-in data types.
642+
enum
643+
----
672644

673-
* ``Flag`` fixes: only primary values (power of two) are considered canonical
674-
while composite values (3, 6, 10, etc.) are considered aliases; inverted
675-
flags are coerced to their positive equivalent.
645+
* Renamed :class:`!EnumMeta` to :class:`~enum.EnumType`
646+
(:class:`!EnumMeta` kept as an alias).
647+
648+
* Added :class:`~enum.StrEnum`,
649+
with members that can be used as (and must be) strings.
650+
651+
* Added :class:`~enum.ReprEnum`,
652+
which only modifies the :meth:`~object.__repr__` of members
653+
while returning their literal values (rather than names)
654+
for :meth:`~object.__str__` and :meth:`~object.__format__`
655+
(used by :func:`str`, :func:`format` and :term:`f-string`\s).
656+
657+
* Changed :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum`
658+
to now inherit from :class:`ReprEnum`,
659+
so their :func:`str` output now matches :func:`format`
660+
(both ``str(AnIntEnum.ONE)`` and ``format(AnIntEnum.ONE)`` return ``'1'``,
661+
whereas before ``str(AnIntEnum.ONE)`` returned ``'AnIntEnum.ONE'``.
662+
663+
* Changed :meth:`Enum.__format__() <enum.Enum.__format__>`
664+
(the default for :func:`format`, :meth:`str.format` and :term:`f-string`\s)
665+
of enums with mixed-in types (e.g. :class:`int`, :class:`str`)
666+
to also include the class name in the output, not just the member's key.
667+
This matches the existing behavior of :meth:`enum.Enum.__str__`,
668+
returning e.g. ``'AnEnum.MEMBER'`` for an enum ``AnEnum(str, Enum)``
669+
instead of just ``'MEMBER'``.
670+
671+
* Added a new *boundary* class parameter to :class:`~enum.Flag` enums
672+
and the :class:`~enum.FlagBoundary` enum with its options,
673+
to control how to handle out-of-range flag values.
674+
675+
* Added the :func:`~enum.verify` enum decorator
676+
and the :class:`~enum.EnumCheck` enum with its options,
677+
to check enum classes against several specific constraints.
678+
679+
* Added the :func:`~enum.member` and :func:`~enum.nonmember` decorators,
680+
to ensure the decorated object is/is not converted to an enum member.
681+
682+
* Added the :func:`~enum.property` decorator,
683+
which works like :func:`property` except for enums.
684+
Use this instead of :func:`types.DynamicClassAttribute`.
685+
686+
* Added the :func:`~enum.global_enum` enum decorator,
687+
which adjusts :meth:`~object.__repr__` and :meth:`~object.__str__`
688+
to show values as members of their module rather than the enum class.
689+
For example, ``'re.ASCII'`` for the :data:`~re.ASCII` member
690+
of :class:`re.RegexFlag` rather than ``'RegexFlag.ASCII'``.
691+
692+
* Enhanced :class:`~enum.Flag` to support
693+
:func:`len`, iteration and :keyword:`in`/:keyword:`not in` on its members.
694+
For example, the following now works:
695+
``len(AFlag(3)) == 2 and list(AFlag(3)) == (AFlag.ONE, AFlag.TWO)``
696+
697+
* Changed :class:`~enum.Enum` and :class:`~enum.Flag`
698+
so that members are now defined
699+
before :meth:`~object.__init_subclass__` is called;
700+
:func:`dir` now includes methods, etc., from mixed-in data types.
701+
702+
* Changed :class:`~enum.Flag`
703+
to only consider primary values (power of two) canonical
704+
while composite values (``3``, ``6``, ``10``, etc.) are considered aliases;
705+
inverted flags are coerced to their positive equivalent.
676706

677-
* ``IntEnum`` / ``IntFlag`` / ``StrEnum`` fixes: these now inherit from
678-
``ReprEnum`` so the ``str()`` output now matches ``format()`` output,
679-
which is the data types' (so both ``str(AnIntEnum.ONE)`` and
680-
``format(AnIntEnum.ONE)`` is equal to ``'1'``).
681707

682708
fractions
683709
---------

0 commit comments

Comments
 (0)