[Python-checkins] gh-98298, gh-74730: [Enum] update docs (GH-103163)
miss-islington
webhook-mailer at python.org
Mon Apr 3 18:27:41 EDT 2023
https://github.com/python/cpython/commit/cf72cc25f600183c69e3639e78cfae3571f8d4d0
commit: cf72cc25f600183c69e3639e78cfae3571f8d4d0
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2023-04-03T15:27:33-07:00
summary:
gh-98298, gh-74730: [Enum] update docs (GH-103163)
fix FlagBoundary statements
add warning about reloading modules and enum identity
(cherry picked from commit 5ffc1e5a21de9a30566095386236db44695d184a)
Co-authored-by: Ethan Furman <ethan at stoneleaf.us>
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 990d006b3e98..f2a10c03fa88 100644
--- a/Doc/howto/enum.rst
+++ b/Doc/howto/enum.rst
@@ -371,6 +371,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 180399938208..34df5c511bf4 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``::
@@ -262,26 +282,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
@@ -722,7 +722,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):
@@ -734,8 +733,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 76575500e424..9138e50c3c6f 100644
--- a/Lib/enum.py
+++ b/Lib/enum.py
@@ -1302,10 +1302,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