Enum Registry Module

The enum registry module provides a sophisticated framework for managing and combining multiple Enum classes with advanced functionality.

Key Components

Warning

When defining enum values, always use true.enum_registry.auto() instead of enum.auto(). Using enum.auto() from the standard library can cause crashes and unexpected behavior.

Correct usage:

from true.enum_registry import auto

class MyEnum(Enum):
    VALUE_1 = auto()  # Correct
    VALUE_2 = auto()  # Correct

Incorrect usage:

from enum import auto  # Do not use this!

class MyEnum(Enum):
    VALUE_1 = auto()  # Will cause crashes
    VALUE_2 = auto()  # Will cause crashes

• EnumRegistry: Main registry class for managing multiple Enum classes

• EnumMapping: Base class for enum mappings with caching support

• EnumData: TypedDict for enum metadata

• EnumStats: Statistics about the enum registry

• BaseMetadata: Base class for metadata

• EnumMetadata: Enhanced metadata for enum members

Classes

EnumRegistry

class true.enum_registry.EnumRegistry(enums=None, duplication=False)

A sophisticated class for combining and managing multiple Enum classes with advanced functionality. Supports arithmetic operations between CombineEnums instances and Enum classes.

Features: - Combines multiple Enum classes into a single manageable entity - Supports arithmetic operations (addition, subtraction, etc.) - Supports iteration, comparison, and membership testing - Provides value validation and duplicate detection - Includes serialization/deserialization capabilities - Implements custom string representations - Supports advanced filtering and query operations

Parameters:

• enums (Iterable[Type[Enum]]) – Collection of Enum classes to combine

• duplication (bool, optional) – Whether to allow duplicate values. Defaults to False.

__init__(enums=None, duplication=False)

property enum_classes: Set[Type[Enum]]

Get set of registered enum classes

property metadata: EnumMetadata

Returns the metadata associated with the enum registry.

_initialize_members(allow_duplicates)

Initialize internal member mappings

Return type:

None

register(enums)

Register new enums to the registry.

Return type:

EnumRegistry

deregister(enums)

Deregister enums from the registry.

Return type:

EnumRegistry

dregister(enum_class=None)

Decorator to register an enum class.

get_enum_metadata(member)

Get metadata for an enum member

Return type:

Dict[str, Any]

members_of(enum_class)

Get all enum members from a specific enum class.

Return type:

List[Enum]

set_member_metadata(member, **kwargs)

Set metadata for an enum member

Return type:

None

get_member_metadata(member)

Get metadata for an enum member

Return type:

Dict[str, Any]

_create_filtered_instance(members)

Helper method to create new instance from filtered members.

Return type:

EnumRegistry

to_dict()

Convert registry to dictionary format

Return type:

Dict[str, List[EnumData]]

statistics()

Get comprehensive statistics about the registry :returns: An EnumStats dataclass instance :rtype: EnumStats

members()

Group members by their original enum class.

Return type:

Dict[Type[Enum], List[Enum]]

merge(*combine_enums)

Merge multiple CombineEnums instances into a new instance.

Return type:

EnumRegistry

__add__(other)

Add another CombineEnums instance or Enum class to this instance. Returns a new CombineEnums instance containing members from both operands.

Parameters:

other (Union[EnumRegistry, Type[Enum]]) – Another CombineEnums instance or Enum class

Returns:

A new instance containing combined members

Return type:

EnumRegistry

Raises:

IncompatibleTypesError – If other is not a CombineEnums instance or Enum class

__sub__(other)

Subtract another CombineEnums instance or Enum class from this instance. Returns a new CombineEnums instance containing members only from this instance.

Parameters:

other (Union[EnumRegistry, Type[Enum]]) – Another CombineEnums instance or Enum class

Returns:

A new instance containing remaining members

Return type:

EnumRegistry

Raises:

IncompatibleTypesError – If other is not a CombineEnums instance or Enum class

static is_enum(other)

Return type:

bool

format_debug()

Comprehensive debug representation showing all internal state.

Returns a detailed multi-line string showing: - All enum classes - All members with their values - Value mappings - Statistics

Return type:

str

__radd__(other)

Add another CombineEnums instance or Enum class to this instance. Returns a new CombineEnums instance containing members from both operands.

Parameters:

other (Union[EnumRegistry, Type[Enum]]) – Another CombineEnums instance or Enum class

Returns:

A new instance containing combined members

Return type:

EnumRegistry

Raises:

IncompatibleTypesError – If other is not a CombineEnums instance or Enum class

__rsub__(other)

Subtract another CombineEnums instance or Enum class from this instance. Returns a new CombineEnums instance containing members only from this instance.

Parameters:

other (Union[EnumRegistry, Type[Enum]]) – Another CombineEnums instance or Enum class

Returns:

A new instance containing remaining members

Return type:

EnumRegistry

Raises:

IncompatibleTypesError – If other is not a CombineEnums instance or Enum class

__iadd__(other)

Inplace addition.

Return type:

EnumRegistry

__isub__(other)

Inplace subtraction.

Return type:

EnumRegistry

__iter__()

Iterate over all enum members.

Return type:

Iterator[Enum]

__next__()

Get the next enum member.

Return type:

Enum

__hash__()

Generate hash based on enum members.

Return type:

int

__eq__(other)

Compare equality with another CombineEnums instance.

Return type:

bool

__lt__(other)

Compare less than with another CombineEnums instance.

Return type:

bool

__contains__(item)

Check if an item exists in the combined enums. Supports checking by name, enum member, or value.

Return type:

bool

EnumMapping

class true.enum_registry.EnumMapping(registry)

Base class for enum mappings

__init__(registry)

clear_cache()

Clear the mapping cache

Return type:

None

all()

Get all enum member names

Return type:

List[str]

count()

Get total count of enum members

Return type:

int

EnumStats

class true.enum_registry.EnumStats(total_members=0, unique_values=0, enum_counts=0, value_counts=0, name_conflicts=0, created_at=None)

total_members: int = 0

unique_values: int = 0

enum_counts: int = 0

value_counts: int = 0

name_conflicts: int = 0

created_at: datetime = None

to_dict()

Return type:

Dict[str, Any]

__init__(total_members=0, unique_values=0, enum_counts=0, value_counts=0, name_conflicts=0, created_at=None)

EnumMetadata

class true.enum_registry.EnumMetadata(description='', tags=None, deprecated=False, created_at=None, modified_at=None, *, aliases=None, category='', extra=<factory>)

Metadata for enum members

aliases: List[str] = None

category: str = ''

extra: Dict[Any, Any]

to_dict()

Return type:

Dict[str, Any]

__init__(description='', tags=None, deprecated=False, created_at=None, modified_at=None, *, aliases=None, category='', extra=<factory>)

Exceptions

class true.exceptions.InvalidEnumTypeError

Bases: Exception

Raised when an invalid enum type is provided.

class true.exceptions.IncompatibleTypesError

Bases: Exception

Examples

Basic Usage

from true.enum_registry import EnumRegistry
from enum import Enum

# Define enums
class UserStatus(Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"
    SUSPENDED = "suspended"

class OrderStatus(Enum):
    PENDING = "pending"
    PROCESSING = "processing"
    SHIPPED = "shipped"

# Register enums
registry = EnumRegistry([UserStatus, OrderStatus])

# Or use decorator
@registry.dregister
class Priority(Enum):
    LOW = 1
    MEDIUM = 2
    HIGH = 3

Advanced Features

# Arithmetic operations
combined = registry + another_registry
filtered = registry - excluded_registry
common = registry.intersect(other_registry)

# Filtering and querying
high_priority = registry.by_value_type(int)
active_states = registry.by_prefix("ACTIVE")
custom_filter = registry.by_predicate(lambda x: x.value > 1)

# Metadata management
registry.set_member_metadata(UserStatus.ACTIVE,
                           description="Active user state",
                           tags={"user", "state"})

# Statistics and debug info
stats = registry.statistics()
debug_info = registry.format_debug()

# Serialization
data = registry.to_dict()

Type Checking

def process_task(priority: int) -> None:
    if priority not in registry:
        raise ValueError(f"Invalid priority: {priority}")

    if priority == Priority.HIGH:
        print("Processing high priority task")
    elif priority == Priority.MEDIUM:
        print("Processing medium priority task")
    else:
        print("Processing low priority task")