gh-98298, gh-74730: [Enum] update docs (GH-103163)

fix FlagBoundary statements
add warning about reloading modules and enum identity
This commit is contained in:
Ethan Furman 2023-04-03 14:57:42 -07:00 committed by GitHub
parent d3a7732dd5
commit 5ffc1e5a21
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 34 additions and 30 deletions

View File

@ -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
----------------------------------------------

View File

@ -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`
@ -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``::
@ -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
@ -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):
@ -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):

View File

@ -1301,10 +1301,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()