diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/enum.rst | 85 |
1 files changed, 82 insertions, 3 deletions
diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 137fe50..2d19ef6 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -28,8 +28,8 @@ An enumeration: * is a set of symbolic names (members) bound to unique values * can be iterated over to return its members in definition order -* uses :meth:`call` syntax to return members by value -* uses :meth:`index` syntax to return members by name +* uses *call* syntax to return members by value +* uses *index* syntax to return members by name Enumerations are created either by using the :keyword:`class` syntax, or by using function-call syntax:: @@ -91,6 +91,12 @@ Module Contents the bitwise operators without losing their :class:`IntFlag` membership. :class:`IntFlag` members are also subclasses of :class:`int`. + :class:`EnumCheck` + + An enumeration with the values ``CONTINUOUS``, ``NAMED_FLAGS``, and + ``UNIQUE``, for use with :func:`verify` to ensure various constraints + are met by a given enumeration. + :class:`FlagBoundary` An enumeration with the values ``STRICT``, ``CONFORM``, ``EJECT``, and @@ -117,9 +123,14 @@ Module Contents Enum class decorator that ensures only one name is bound to any one value. + :func:`verify` + + Enum class decorator that checks user-selectable constraints on an + enumeration. + .. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto`` -.. versionadded:: 3.10 ``StrEnum`` +.. versionadded:: 3.10 ``StrEnum``, ``EnumCheck``, ``FlagBoundary`` Data Types @@ -514,6 +525,65 @@ Data Types Using :class:`auto` with :class:`IntFlag` results in integers that are powers of two, starting with ``1``. +.. class:: EnumCheck + + *EnumCheck* contains the options used by the :func:`verify` decorator to ensure + various constraints; failed constraints result in a :exc:`TypeError`. + + .. attribute:: UNIQUE + + Ensure that each value has only one name:: + + >>> from enum import Enum, verify, UNIQUE + >>> @verify(UNIQUE) + ... class Color(Enum): + ... RED = 1 + ... GREEN = 2 + ... BLUE = 3 + ... CRIMSON = 1 + Traceback (most recent call last): + ... + ValueError: aliases found in <enum 'Color'>: CRIMSON -> RED + + + .. attribute:: CONTINUOUS + + Ensure that there are no missing values between the lowest-valued member + and the highest-valued member:: + + >>> from enum import Enum, verify, CONTINUOUS + >>> @verify(CONTINUOUS) + ... class Color(Enum): + ... RED = 1 + ... GREEN = 2 + ... BLUE = 5 + Traceback (most recent call last): + ... + ValueError: invalid enum 'Color': missing values 3, 4 + + .. attribute:: NAMED_FLAGS + + Ensure that any flag groups/masks contain only named flags -- useful when + values are specified instead of being generated by :func:`auto` + + >>> from enum import Flag, verify, NAMED_FLAGS + >>> @verify(NAMED_FLAGS) + ... class Color(Flag): + ... RED = 1 + ... GREEN = 2 + ... BLUE = 4 + ... WHITE = 15 + ... NEON = 31 + Traceback (most recent call last): + ... + ValueError: invalid Flag 'Color': 'WHITE' is missing a named flag for value 8; 'NEON' is missing named flags for values 8, 16 + +.. note:: + + CONTINUOUS and NAMED_FLAGS are designed to work with integer-valued members. + +.. versionadded:: 3.10 + .. class:: FlagBoundary *FlagBoundary* controls how out-of-range values are handled in *Flag* and its @@ -575,6 +645,7 @@ Data Types >>> KeepFlag(2**2 + 2**4) KeepFlag.BLUE|0x10 +.. versionadded:: 3.10 Utilites and Decorators ----------------------- @@ -627,3 +698,11 @@ Utilites and Decorators Traceback (most recent call last): ... ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE + +.. decorator:: verify + + A :keyword:`class` decorator specifically for enumerations. Members from + :class:`EnumCheck` are used to specify which constraints should be checked + on the decorated enumeration. + +.. versionadded:: 3.10 |