Enum Mate - Comprehensive Usage Guide

The enum_mate library enhances Python’s standard enum module with explicit APIs for validation and retrieval. It provides safer, more intuitive enum handling with comprehensive validation methods.

One of the key advantages of enum_mate is its intuitive and self-explanatory API naming convention. The library uses human-friendly method and attribute names that clearly convey their purpose. This means you can leverage your IDE’s auto-complete functionality to discover and use the available APIs without having to constantly refer to the documentation or memorize the exact syntax.

Import

from enum_mate.api import BetterIntEnum, BetterStrEnum

BetterIntEnum - Enhanced Integer Enums

class BetterIntEnum: is an more advanced version of class YourEnumClass(int, enum.Enum):.

Basic Usage

class StatusCode(BetterIntEnum):
    SUCCESS = 200
    NOT_FOUND = 404
    SERVER_ERROR = 500
    TIMEOUT = -1

Standard Enum Operations

# Works exactly like standard int enums
StatusCode.SUCCESS == 200

True

StatusCode.SUCCESS + 1

201

StatusCode.SUCCESS > StatusCode.NOT_FOUND

False

{StatusCode.SUCCESS, StatusCode.NOT_FOUND} == {200, 404}

True

# String representation
print(StatusCode.SUCCESS)                 # StatusCode.SUCCESS

StatusCode.SUCCESS

StatusCode.SUCCESS.name

'SUCCESS'

StatusCode.SUCCESS.value

200

Enhanced API Methods

1. Retrieval by Name

member = StatusCode.get_by_name("SUCCESS")
member

<StatusCode.SUCCESS: 200>

member is StatusCode.SUCCESS

True

try:
    StatusCode.get_by_name("INVALID")
except KeyError as e:
    print(e)

"Invalid `class __main__.StatusCode` member name: 'INVALID'"

2. Retrieval by Value

member = StatusCode.get_by_value(200)
print(member)

StatusCode.SUCCESS

member is StatusCode.SUCCESS

True

try:
    StatusCode.get_by_value(999)
except ValueError as e:
    print(e)

999 is not a valid StatusCode

3. Name Validation

# Check if name is valid
StatusCode.is_valid_name("SUCCESS")

True

StatusCode.is_valid_name("success") # case-sensitive

False

StatusCode.is_valid_name("INVALID")

False

StatusCode.is_valid_name(200) # wrong type

False

4. Value Validation

# Check if value is valid
StatusCode.is_valid_value(200)

True

StatusCode.is_valid_value(-1) # negative values work

True

StatusCode.is_valid_value(999)

False

StatusCode.is_valid_value("200") # wrong type

False

5. Value Validation with Exceptions

# Validate and raise exception if invalid
StatusCode.ensure_is_valid_value(200) # No exception

try:
    StatusCode.ensure_is_valid_value(999)
except ValueError as e: # Invalid StatusCode: 999
    print(e)

Invalid `class __main__.StatusCode`: 999

6. Type Conversion and Validation

# Convert to int with validation
StatusCode.ensure_int(200) # 200 (int)

200

StatusCode.ensure_int(StatusCode.SUCCESS)

200

# Error handling
try:
    StatusCode.ensure_int(999)
except ValueError as e:
    print(e)

999 is not a valid StatusCode

7. Get All Names and Values

# Get all enum names
StatusCode.get_names()

['SUCCESS', 'NOT_FOUND', 'SERVER_ERROR', 'TIMEOUT']

# Get all enum values
StatusCode.get_values()

[200, 404, 500, -1]

BetterStrEnum - Enhanced String Enums

Basic Usage

class Environment(BetterStrEnum):
    DEVELOPMENT = "dev"
    STAGING = "staging"
    PRODUCTION = "prod"
    TEST = "test"

Standard String Operations

# Works exactly like standard str enums
Environment.DEVELOPMENT == "dev"

True

Environment.DEVELOPMENT.upper()

'DEV'

f"Running in {Environment.PRODUCTION}"

'Running in Environment.PRODUCTION'

{"dev", "prod"} & {Environment.DEVELOPMENT, Environment.PRODUCTION} # {'dev', 'prod'}

{<Environment.DEVELOPMENT: 'dev'>, <Environment.PRODUCTION: 'prod'>}

Environment.DEVELOPMENT.replace("v", "velopment")

'development'

Enhanced API Methods

1. Retrieval by Name

# Get enum member by name
member = Environment.get_by_name("DEVELOPMENT")
member

<Environment.DEVELOPMENT: 'dev'>

member is Environment.DEVELOPMENT

True

id(Environment.DEVELOPMENT)

4429131728

# Error handling
try:
    Environment.get_by_name("dev") # Wrong - this is the value, not name
except KeyError as e:
    print(repr(e))

KeyError("Invalid `class __main__.Environment` member name: 'dev'")

2. Retrieval by Value

# Get enum member by value
member = Environment.get_by_value("dev")
member

<Environment.DEVELOPMENT: 'dev'>

member is Environment.DEVELOPMENT

True

# Error handling
try:
    Environment.get_by_value("DEVELOPMENT") # Wrong - this is the name, not value
except ValueError as e:
    print(repr(e))

ValueError("'DEVELOPMENT' is not a valid Environment")

3. Name Validation

# Check if name is valid
Environment.is_valid_name("DEVELOPMENT")

True

Environment.is_valid_name("dev") # this is a value, not name

False

Environment.is_valid_name("INVALID")

False

4. Value Validation

Environment.is_valid_value("dev")

True

Environment.is_valid_value("DEVELOPMENT") # this is a name, not value

False

Environment.is_valid_value("invalid")

False

Environment.is_valid_value("")

False

5. Value Validation with Exceptions

# Validate and raise exception if invalid
Environment.ensure_is_valid_value("dev") # No exception

try:
    Environment.ensure_is_valid_value("invalid")
except ValueError as e:
    print(repr(e))

ValueError("Invalid `class __main__.Environment`: 'invalid'")

6. Type Conversion and Validation

# Convert to str with validation
Environment.ensure_str("dev")

'dev'

Environment.ensure_str(Environment.DEVELOPMENT)

'dev'

# Error handling
try:
    Environment.ensure_str("invalid")
except ValueError as e:
    print(repr(e))

ValueError("'invalid' is not a valid Environment")

7. Get All Names and Values

# Get all enum names
Environment.get_names()

['DEVELOPMENT', 'STAGING', 'PRODUCTION', 'TEST']

# Get all enum values
Environment.get_values()

['dev', 'staging', 'prod', 'test']

Advanced Usage Examples

Input Validation in Functions

def process_request(status_code: int):
    """Process request based on status code."""
    # Validate input and convert to enum
    code = StatusCode.ensure_int(status_code)

    if code == StatusCode.SUCCESS:
        return "Request processed successfully"
    elif code == StatusCode.NOT_FOUND:
        return "Resource not found"
    else:
        return "Request failed"

# Usage
process_request(200) # Request processed successfully

'Request processed successfully'

process_request(404) # Resource not found

'Resource not found'

try:
    process_request(999)
except ValueError as e:
    print(repr(e)) # Invalid status code: 999

ValueError('999 is not a valid StatusCode')

Configuration Management

def get_database_config(env_name):
    """Get database configuration for environment."""
    # Ensure valid environment
    env = Environment.ensure_str(env_name)

    configs = {
        Environment.DEVELOPMENT: "localhost:5432",
        Environment.STAGING: "staging-db:5432",
        Environment.PRODUCTION: "prod-db:5432",
        Environment.TEST: "test-db:5432"
    }

    return configs[env]

# Usage
get_database_config("dev")

'localhost:5432'

get_database_config("prod")

'prod-db:5432'

Summary

The enum_mate library provides:

• Explicit APIs for getting enum members by name or value

• Built-in validation methods for safe enum handling

• Type conversion utilities with validation

• Comprehensive error handling with clear error messages

• Full compatibility with standard Python enum operations

• IDE-friendly method names for better development experience

Use BetterIntEnum for integer-based enums and BetterStrEnum for string-based enums to get enhanced functionality while maintaining all standard enum capabilities.