Skip to content

gh-98298, gh-74730: [Enum] update docs #103163

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Apr 3, 2023
Merged

gh-98298, gh-74730: [Enum] update docs #103163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
5 changes: 5 additions & 0 deletions Doc/howto/enum.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,6 +372,11 @@ below)::
>>> Color.BLUE == 2
False

.. warning::

It is possible to reload modules -- if a reloaded module contains
enums, they will be recreated, and the new members may not
compare identical/equal to the original members.

Allowed members and attributes of enumerations
----------------------------------------------
Expand Down
51 changes: 25 additions & 26 deletions Doc/library/enum.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,9 +141,8 @@ Module Contents
:func:`global_enum`

Modify the :class:`str() <str>` and :func:`repr` of an enum
to show its members as belonging to the module instead of its class.
Should only be used if the enum members will be exported to the
module global namespace.
to show its members as belonging to the module instead of its class,
and export the enum members to the global namespace.

:func:`show_flag_values`

Expand All @@ -170,6 +169,27 @@ Data Types
final *enum*, as well as creating the enum members, properly handling
duplicates, providing iteration over the enum class, etc.

.. method:: EnumType.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

This method is called in two different ways:

* to look up an existing member:

:cls: The enum class being called.
:value: The value to lookup.

* to use the ``cls`` enum to create a new enum (only if the existing enum
does not have any members):

:cls: The enum class being called.
:value: The name of the new Enum to create.
:names: The names/values of the members for the new Enum.
:module: The name of the module the new Enum is created in.
:qualname: The actual location in the module where this Enum can be found.
:type: A mix-in type for the new Enum.
:start: The first integer value for the Enum (used by :class:`auto`).
:boundary: How to handle out-of-range values from bit operations (:class:`Flag` only).

.. method:: EnumType.__contains__(cls, member)

Returns ``True`` if member belongs to the ``cls``::
Expand Down Expand Up @@ -255,26 +275,6 @@ Data Types
names will also be removed from the completed enumeration. See
:ref:`TimePeriod <enum-time-period>` for an example.

.. method:: Enum.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

This method is called in two different ways:

* to look up an existing member:

:cls: The enum class being called.
:value: The value to lookup.

* to use the ``cls`` enum to create a new enum:

:cls: The enum class being called.
:value: The name of the new Enum to create.
:names: The names/values of the members for the new Enum.
:module: The name of the module the new Enum is created in.
:qualname: The actual location in the module where this Enum can be found.
:type: A mix-in type for the new Enum.
:start: The first integer value for the Enum (used by :class:`auto`).
:boundary: How to handle out-of-range values from bit operations (:class:`Flag` only).

.. method:: Enum.__dir__(self)

Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
Expand Down Expand Up @@ -728,7 +728,6 @@ Data Types
.. attribute:: EJECT

Out-of-range values lose their *Flag* membership and revert to :class:`int`.
This is the default for :class:`IntFlag`::

>>> from enum import Flag, EJECT, auto
>>> class EjectFlag(Flag, boundary=EJECT):
Expand All @@ -741,8 +740,8 @@ Data Types

.. attribute:: KEEP

Out-of-range values are kept, and the *Flag* membership is kept. This is
used for some stdlib flags::
Out-of-range values are kept, and the *Flag* membership is kept.
This is the default for :class:`IntFlag`::

>>> from enum import Flag, KEEP, auto
>>> class KeepFlag(Flag, boundary=KEEP):
Expand Down
8 changes: 4 additions & 4 deletions Lib/enum.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1306,10 +1306,10 @@ def _reduce_ex_by_global_name(self, proto):
class FlagBoundary(StrEnum):
"""
control how out of range values are handled
"strict" -> error is raised [default for Flag]
"conform" -> extra bits are discarded
"eject" -> lose flag status [default for IntFlag]
"keep" -> keep flag status and all bits
"strict" -> error is raised
"conform" -> extra bits are discarded [default for Flag]
"eject" -> lose flag status
"keep" -> keep flag status and all bits [default for IntFlag]
"""
STRICT = auto()
CONFORM = auto()
Expand Down