enum_modifiers

The enums 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, value):
        super().__init__(value)
        self.uses = 0

    PI = 3.14159

    POINT4D = lambda w, x, y, z: ...

    @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(i_self, x: int):
        i_self.uses += 1
        return {'y': i_self.uses * i_self.gen_random() * x}

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

Static Member Access Examples:

print(MyEnum.PI)    # prints 3.14159
print(MyEnum.PI())  # raises a TypeError
print(MyEnum.PI[0]) # raises a TypeError
print(MyEnum.PI.x)  # raises an AttributeError

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 makes a difference.
point2 = MyEnum.POINT2D(42, 55)
print(point2.x)  # prints 42
print(point2[0]) # prints 42
print(point2.y)  # prints 55
print(point2[1]) # prints 55

# positional, positional-or-keyword, and keyword arguments are treated differently.
point3 = MyEnum.POINT3D(53, 19, z=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)  # raises an AttributeError
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

# Lambdas are treated like static methods.
point7 = MyEnum.POINT4D(5, 6, 7, 8)
print(point7.w)  # prints 5
print(point7[0]) # prints 5
print(point7.x)  # prints 6
print(point7[1]) # prints 6
print(point7.y)  # prints 7
print(point7[2]) # prints 7
print(point7.z)  # prints 8
print(point7[3]) # prints 8

# ignore decorator should keep a function from being interpreted as an attribute.
print(MyEnum.gen_random()) # prints 4

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.