Reference

Module

                ███████╗███╗   ██╗██╗   ██╗███╗   ███╗
                ██╔════╝████╗  ██║██║   ██║████╗ ████║
                █████╗  ██╔██╗ ██║██║   ██║██╔████╔██║
                ██╔══╝  ██║╚██╗██║██║   ██║██║╚██╔╝██║
                ███████╗██║ ╚████║╚██████╔╝██║ ╚═╝ ██║
                ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝     ╚═╝

██████╗ ██████╗  ██████╗ ██████╗ ███████╗██████╗ ████████╗██╗███████╗███████╗
██╔══██╗██╔══██╗██╔═══██╗██╔══██╗██╔════╝██╔══██╗╚══██╔══╝██║██╔════╝██╔════╝
██████╔╝██████╔╝██║   ██║██████╔╝█████╗  ██████╔╝   ██║   ██║█████╗  ███████╗
██╔═══╝ ██╔══██╗██║   ██║██╔═══╝ ██╔══╝  ██╔══██╗   ██║   ██║██╔══╝  ╚════██║
██║     ██║  ██║╚██████╔╝██║     ███████╗██║  ██║   ██║   ██║███████╗███████║
╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═╝   ╚═╝   ╚═╝╚══════╝╚══════╝

Metaprogramming and mixin tools that implement property tuple and method specialization support for python enumeration classes.

class enum_properties.DecomposeMixin

Bases: object

A mixin for Flag enumerations that decomposes composite enumeration values and allows us to treat composite enumeration values as iterables of activated flags.

property flagged

Returns the list of flags that are active.

class enum_properties.EnumProperties(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: SymmetricMixin, Enum

Use this base class instead of enum.Enum to enable enumeration properties. For example:

class EnumType(
    EnumProperties,
    p('prop1'),
    s('prop1', case_fold=True)  # case insensitive symmetric property
):

    VAL1 = 1, "prop1's value1", "prop2's value1"
    VAL2 = 2, "prop1's value2", "prop2's value2"
    VAL3 = 3, "prop1's value3", "prop2's value3"

This is a shortcut for:

class EnumType(SymmetricMixin, Enum, metaclass=EnumPropertiesMeta):
    ...

See How To for more details.

__first_class_members__: list[str] = []

The list of first class members - this includes all members and aliases. May be overridden.

_ep_coerce_types_: list[type[Any]] = []

On instantiation, if _missing_ is invoked a coercion attempt will be made to each of these types before failure.

_ep_isymmetric_map_: dict[str, Enum] = {}

The case insensitive mapping of symmetric values to enumeration values.

_ep_symmetric_map_: dict[Any, Enum] = {}

The case sensitive mapping of symmetric values to enumeration values.

_num_sym_props_: int = 0

The number of symmetric properties on this enumeration.

_properties_: list[_Prop] = []

List of properties defined on the enumeration class.

class enum_properties.EnumPropertiesMeta(classname, bases, classdict, **kwargs)

Bases: EnumType

A metaclass for creating enum choices with additional named properties for each value. An enum.Enum can be given property support simply by:

import enum
from enum_properties import EnumPropertiesMeta

class MyEnum(enum.Enum, metaclass=EnumPropertiesMeta):
    ...

To support symmetrical properties, add the SymmetricMixin:

import enum
from enum_properties import (
    EnumPropertiesMeta,
    SymmetricMixin
)

class MyEnum(SymmetricMixin, enum.Enum, metaclass=EnumPropertiesMeta):
    ...

All enum.Enum functionality is compatible with the EnumPropertiesMeta metaclass. This class works by stripping out the p() and s() values during __prepare__ and using their class name’s as expected property values to set the appropriate values to properties in __new__.

classmethod __prepare__(cls, bases, **kwds)

Strip properties out of inheritance and record them on our class dictionary for per-value based assignment in __new__.

Raises:

ValueError – If a reserved name is present as either a property or a member, or if the number of specified properties does not match the number of listed property values in the value tuples.

EXPECTED = ['_symmetric_builtins_']
RESERVED = ['_properties_', '_num_sym_props_', '_ep_coerce_types_', '_ep_symmetric_map_', '_ep_isymmetric_map_']
__call__(value, names=None, *, module=None, qualname=None, type=None, start=1, properties=None, **kwargs)

Overrides enum.EnumMeta.__call__() to support the functional API with a properties argument. When names is provided along with properties, a new enum class is created with the given properties.

properties may be an iterable of:

  • str – creates a non-symmetric property with that name

  • p() or s() type – used directly (preserves case-fold / match-none options on symmetric properties)

Example:

AnEnum = EnumProperties(
    "AnEnum",
    {"A": ("a", True), "B": ("b", False)},
    properties=("prop",),
)
Parameters:

  • value – Class name when using the functional API, otherwise the member value to look up.

  • names – Member definitions (dict, list of pairs, or string).

  • module – Module name for the new class.

  • qualname – Qualified name for the new class.

  • type – An optional mixin type for the new class.

  • start – Starting value for auto-generated member values.

  • properties – Property specifications for the functional API.

__first_class_members__: list[str]
_ep_coerce_types_: list[type[Any]]
_ep_isymmetric_map_: dict[str, Enum]
_ep_symmetric_map_: dict[Any, Enum]
_num_sym_props_: int
_properties_: list[_Prop]
class enum_properties.FlagProperties(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DecomposeMixin, SymmetricMixin, Flag

A Flag that supports properties

__first_class_members__: list[str] = []

The list of first class members - this includes all members and aliases. May be overridden.

_all_bits_ = 0
_boundary_ = 'strict'
_ep_coerce_types_: list[type[Any]] = []

On instantiation, if _missing_ is invoked a coercion attempt will be made to each of these types before failure.

_ep_isymmetric_map_: dict[str, Enum] = {}

The case insensitive mapping of symmetric values to enumeration values.

_ep_symmetric_map_: dict[Any, Enum] = {}

The case sensitive mapping of symmetric values to enumeration values.

_flag_mask_ = 0
static _generate_next_value_(name, start, count, last_values)

Intermixed property tuples can corrupt the last_values list with tuples. This method ensures only ints are present in last_values and delegates to the super class.

_inverted_ = None
_num_sym_props_: int = 0

The number of symmetric properties on this enumeration.

_properties_: list[_Prop] = []

List of properties defined on the enumeration class.

_singles_mask_ = 0
class enum_properties.IntEnumProperties(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: SymmetricMixin, IntEnum

An IntEnum that supports properties.

Note

Because SymmetricMixin implements __eq__ we also need an implementation of __hash__ on our class to keep it hashable We walk the mro to find the first implementation of __hash__ and use it - this keeps our implementation hash equivalent to Enum/IntEnum behavior

__first_class_members__: list[str] = []

The list of first class members - this includes all members and aliases. May be overridden.

_ep_coerce_types_: list[type[Any]] = []

On instantiation, if _missing_ is invoked a coercion attempt will be made to each of these types before failure.

_ep_isymmetric_map_: dict[str, Enum] = {}

The case insensitive mapping of symmetric values to enumeration values.

_ep_symmetric_map_: dict[Any, Enum] = {}

The case sensitive mapping of symmetric values to enumeration values.

_num_sym_props_: int = 0

The number of symmetric properties on this enumeration.

_properties_: list[_Prop] = []

List of properties defined on the enumeration class.

class enum_properties.IntFlagProperties(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DecomposeMixin, SymmetricMixin, IntFlag

An IntFlag that supports properties.

__first_class_members__: list[str] = []

The list of first class members - this includes all members and aliases. May be overridden.

_all_bits_ = 0
_boundary_ = 'keep'
_ep_coerce_types_: list[type[Any]] = []

On instantiation, if _missing_ is invoked a coercion attempt will be made to each of these types before failure.

_ep_isymmetric_map_: dict[str, Enum] = {}

The case insensitive mapping of symmetric values to enumeration values.

_ep_symmetric_map_: dict[Any, Enum] = {}

The case sensitive mapping of symmetric values to enumeration values.

_flag_mask_ = 0
static _generate_next_value_(name, start, count, last_values)

Intermixed property tuples can corrupt the last_values list with tuples. This method ensures only ints are present in last_values and delegates to the super class.

_inverted_ = None
_num_sym_props_: int = 0

The number of symmetric properties on this enumeration.

_properties_: list[_Prop] = []

List of properties defined on the enumeration class.

_singles_mask_ = 0
class enum_properties.StrEnumProperties(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: SymmetricMixin, StrEnum

An StrEnum that supports properties.

__first_class_members__: list[str] = []

The list of first class members - this includes all members and aliases. May be overridden.

_ep_coerce_types_: list[type[Any]] = []

On instantiation, if _missing_ is invoked a coercion attempt will be made to each of these types before failure.

_ep_isymmetric_map_: dict[str, Enum] = {}

The case insensitive mapping of symmetric values to enumeration values.

_ep_symmetric_map_: dict[Any, Enum] = {}

The case sensitive mapping of symmetric values to enumeration values.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

_num_sym_props_: int = 0

The number of symmetric properties on this enumeration.

_properties_: list[_Prop] = []

List of properties defined on the enumeration class.

class enum_properties.Symmetric(case_fold: bool = False, match_none: bool = False)

Bases: object

A dataclass to hold symmetric property options.

case_fold: bool = False

If False, symmetric lookup will be case sensitive (default)

match_none: bool = False

If True, none values will be symmetric, if False (default), none values for symmetric properties will not map back to the enumeration value.

class enum_properties.SymmetricMixin

Bases: object

This mixin enables symmetric enum.Enum creation from properties marked symmetric. It is included by default in the EnumProperties base class, but can be disabled by overriding _missing_ and explicitly skipping it.

If an enumeration type inherits builtin properties (e.g. name), those properties can be made symmetric by supplying a _symmetric_builtins_ member containing a list of string property names or s() values. By default, the name property will be a case sensitive symmetric property.

__first_class_members__: list[str]

The list of first class members - this includes all members and aliases. May be overridden.

_ep_coerce_types_: list[type[Any]]

On instantiation, if _missing_ is invoked a coercion attempt will be made to each of these types before failure.

_ep_isymmetric_map_: dict[str, Enum]

The case insensitive mapping of symmetric values to enumeration values.

_ep_symmetric_map_: dict[Any, Enum]

The case sensitive mapping of symmetric values to enumeration values.

classmethod _missing_(value: Any) → Any

Arbitrary types can be mapped to enumeration values so long as they are hashable. Coercion to all possible types must be attempted on value, in priority order before failure.

Parameters:

value – The value (possibly wrapped) to attempt coercion to our enumeration type.

Raises:

ValueError – if no enumeration match can be found.

Returns:

A valid instance of this enumeration

_num_sym_props_: int

The number of symmetric properties on this enumeration.

_properties_: list[_Prop]

List of properties defined on the enumeration class.

enum_properties.p(prop_name: str) → type[_Prop]

Add a property of the given name to the enumeration class by inheritance. Properties must be specified in the order in which they appear in the value tuple specification. This call works by constructing a new type with a classname that corresponds to the property name. The class inherits from str and can be instantiated as a string by calling its empty constructor.

Parameters:

prop_name – The name of the property

Returns:

a named property class

enum_properties.s(prop_name: str, case_fold: bool = False, match_none: bool = False) → type[_SProp]

Add a symmetric property. Enumeration values will be coercible from this property’s values.

Parameters:

  • prop_name – The name of the property

  • case_fold – If False, symmetric lookup will be case sensitive (default)

  • match_none – If True, none values will be symmetric, if False (default), none values for symmetric properties will not map back to the enumeration value.

Returns:

a named symmetric property class

enum_properties.specialize(*values)

A decorator to specialize a method for a given enumeration value.

Parameters:

values – The enumeration value(s) to specialize

Returns:

A decorated specialized member method

enum_properties.symmetric(case_fold: bool = False, match_none: bool = False)

A decorator that marks non-enum value members as symmetric. Plain functions are automatically wrapped with property(). For example:

class MyEnum(EnumProperties):

    ...

    @symmetric(case_fold=True)
    def name(self):
        return "value"
Parameters:

  • case_fold – Pass True to make the property case insensitive

  • match_none – Pass True to make None values symmetric

Returns:

A decorated specialized member method