[Python-checkins] gh-98298, gh-74730: [Enum] update docs (GH-103163)
ethanfurman
webhook-mailer at python.org
Mon Apr 3 17:57:49 EDT 2023
https://github.com/python/cpython/commit/5ffc1e5a21de9a30566095386236db44695d184a
commit: 5ffc1e5a21de9a30566095386236db44695d184a
branch: main
author: Ethan Furman <ethan at stoneleaf.us>
committer: ethanfurman <ethan at stoneleaf.us>
date: 2023-04-03T14:57:42-07:00
summary:
gh-98298, gh-74730: [Enum] update docs (GH-103163)
fix FlagBoundary statements
add warning about reloading modules and enum identity
files:
M Doc/howto/enum.rst
M Doc/library/enum.rst
M Lib/enum.py
diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
index 4525acb04503..fc8ea55069a9 100644
--- a/Doc/howto/enum.rst
+++ b/Doc/howto/enum.rst
@@ -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
----------------------------------------------
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst
index 24b6dbfe37cd..c690c837309e 100644
--- a/Doc/library/enum.rst
+++ b/Doc/library/enum.rst
@@ -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):
diff --git a/Lib/enum.py b/Lib/enum.py
index b8ea7af9e747..9d836c716d84 100644
--- a/Lib/enum.py
+++ b/Lib/enum.py
@@ -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()
More information about the Python-checkins
mailing list