Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 5 commits into from
Oct 18, 2022
Merged
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 62 additions & 38 deletions Doc/whatsnew/3.11.rst
Original file line number Diff line number Diff line change
Expand Up @@ -619,48 +619,72 @@ 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 keys)
CAM-Gerlach marked this conversation as resolved.
Show resolved Hide resolved
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__() <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'``.

* 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.
CAM-Gerlach marked this conversation as resolved.
Show resolved Hide resolved

* 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
---------
Expand Down