enum_modifiers

The enum_modifiers module holds decorators related to enums.

Functions

class CarrierEnum(value)

Bases: object

An enumeration type that supports automatic generation of enum members from both values and functions. Members can be defined traditionally with values, or dynamically through callable functions, which are converted into callable class instances. These instances can then generate further enum instances when called with arguments matching the signature of the function.

Each member of the enum can be a traditional value, a function wrapped to return enum instances, or a dynamically generated instance representing function call results.

When an element is a wrapped function, it need not return a result, as the default result will be a container class holding the arguments it is called with; however, if desiring to add extra values to these holder classes by doing computations with the inputs, the user may define logic inside the method. In the case they do so, the method should return a mapping of names to values, otherwise the result of the function will be ignored.

Note

Holder instances generated by wrapped functions will follow access rules similar to how the function signature works. In other words, if the function includes positional-only arguments, they will only be accessible by index. If they are positional-or-keyword arguments, they will be included both as accessible via index and via attribute. If they are keyword-only arguments, they will only be included as attributes on the generated instances.

Warning

Because type hints are assumed necessary for holder instances, checks will be performed on arguments to ensure they match teh expected types.

Methods defined in the class can be ignored/not turned into elements by using the @ignore decorator.

Attributes:

value (Any): The value of the enum member. name (str): The name of the enum member.

Usage:

Given a class defined as such…

class MyEnum(CarrierEnum):
    def __init__(self):
        self.uses = 0

    PI = 3.14159

    @staticmethod
    def POINT2D(x: int, y: int = 0): ...

    @staticmethod
    def POINT3D(x: int, /, y: int, *, z: int): ...

    @classmethod
    def PI_POINT3D(cls, x: int, y: int):
        return {'z': cls.PI.value}

    def CALC_POINT2D(self, x: int):
        self.uses += 1
        return {'y': self.uses * self.gen_random() * x}

    @ignore
    @staticmethod
    def gen_random():
        return 4 // chosen by fair dice roll.
                 // guaranteed to be random.

Static Member Access Examples:

Functional Member Access Examples:

# Simple Examples:
# Default values will be used.
point1 = MyEnum.POINT2D(42)
print(point1.x)  # prints 42
print(point1[0]) # prints 42
print(point1.y)  # prints 0
print(point1[1]) # prints 0

# Filling the signature matters.
point2 = MyEnum.POINT2D(42, 55)
print(point1.x)  # prints 42
print(point1[0]) # prints 42
print(point1.y)  # prints 55
print(point1[1]) # prints 55

# positional, positional-or-keyword, and keyword arguments are treated differently.
point3 = MyEnum.POINT3D(53, 19, 93)
print(point3.x)   # raises an AttributeError
print(point3[0])  # prints 53
print(point3.y)   # prints 19
print(point3[1])  # prints 19
print(point3.z)   # prints 93
print(point3[2])  # raises an IndexError

# More-Complicated Examples:
# Values returned by executing the wrapped method will be added to kwargs.
# Class methods are also made to function normally when wrapped.
point4 = MyEnum.PI_POINT3D(1, 2)
print(point4.x)  # prints 1
print(point4[0]) # prints 1
print(point4.y)  # prints 2
print(point4[1]) # prints 2
print(point4.z)  # prints 3.14159
print(point4[2]) # raises an IndexError

# Values returned by executing the wrapped method will be added to kwargs.
# Instance methods are also made to function normally when wrapped.
point5 = MyEnum.CALC_POINT2D(14)
print(point5.x)  # prints 14
print(point5[0]) # prints 14
print(point5.y)  # prints 56
print(point5[1]) # raises an IndexError

point6 = MyEnum.CALC_POINT2D(14)
print(point6.x)  # prints 14
print(point6[0]) # prints 14
print(point6.y)  # prints 112
print(point6[1]) # raises an IndexError

converts_enums(func: Callable)

A decorator that will automatically convert enums fed to it into their values.

ignore(func: callable)

A decorator that can be used on functions inside a CarrierEnum to denote that they should not be used to create instances of the enum.