mirror of https://github.com/python/cpython
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:
parent
d3a7732dd5
commit
5ffc1e5a21
|
@ -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
|
||||
----------------------------------------------
|
||||
|
|
|
@ -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):
|
||||
|
|
|
@ -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()
|
||||
|
|
Loading…
Reference in New Issue