mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

gh-95913: Copyedit, xref and organize enum section (#98295)

Browse source 
* 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
This commit is contained in:
C.A.M. Gerlach 2022-10-18 04:26:24 -05:00 • committed by GitHub
parent 0a0c7e5a7a
commit 73e5180faf
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 52 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

78
Doc/whatsnew/3.11.rst
View file

@ -632,48 +632,74 @@ datetime
formats (barring only those that support fractional hours and minutes). formats (barring only those that support fractional hours and minutes).
(Contributed by Paul Ganssle in :gh:`80010`.) (Contributed by Paul Ganssle in :gh:`80010`.)
.. _whatsnew311-enum:
enum enum
---- ----
* ``EnumMeta`` renamed to ``EnumType`` (``EnumMeta`` kept as alias). * Renamed :class:`!EnumMeta` to :class:`~enum.EnumType`
(:class:`!EnumMeta` kept as an alias).
* ``StrEnum`` added -- enum members are and must be strings. * Added :class:`~enum.StrEnum`,
with members that can be used as (and must be) strings.
* ``ReprEnum`` added -- causes only the ``__repr__`` to be modified, not the * Added :class:`~enum.ReprEnum`,
``__str__`` nor the ``__format__``. 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).
* ``FlagBoundary`` added -- controls behavior when invalid values are given to * Changed :class:`~enum.IntEnum`, :class:`~enum.IntFlag` and :class:`~enum.StrEnum`
a flag. 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'``.
* ``EnumCheck`` added -- used by ``verify`` to ensure various constraints. * Changed :meth:`Enum.__format__() <enum.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'``.
* ``verify`` added -- function to ensure given ``EnumCheck`` constraints. * 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.
* ``member`` added -- decorator to ensure given object is converted to an enum * Added the :func:`~enum.verify` enum decorator
member. and the :class:`~enum.EnumCheck` enum with its options,
to check enum classes against several specific constraints.
* ``nonmember`` added -- decorator to ensure given object is not converted to * Added the :func:`~enum.member` and :func:`~enum.nonmember` decorators,
an enum member. to ensure the decorated object is/is not converted to an enum member.
* ``property`` added -- use instead of ``types.DynamicClassAttribute``. * Added the :func:`~enum.property` decorator,
which works like :func:`property` except for enums.
Use this instead of :func:`types.DynamicClassAttribute`.
* ``global_enum`` added -- enum decorator to adjust ``__repr__`` and ``__str__`` * Added the :func:`~enum.global_enum` enum decorator,
to show members in the global context -- see ``re.RegexFlag`` for an example. 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'``.
* ``Flag`` enhancements: members support length, iteration, and containment * Enhanced :class:`~enum.Flag` to support
checks. :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)``
* ``Enum``/``Flag`` fixes: members are now defined before ``__init_subclass__`` * Changed :class:`~enum.Enum` and :class:`~enum.Flag`
is called; ``dir()`` now includes methods, etc., from mixed-in data types. so that 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 * Changed :class:`~enum.Flag`
while composite values (3, 6, 10, etc.) are considered aliases; inverted to only consider primary values (power of two) canonical
flags are coerced to their positive equivalent. 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 fractions
--------- ---------