Refactor: Replace boolean traps with enums

[filthyrake]

Problem

Boolean parameters create "boolean traps" where the meaning is unclear at call sites.

Example: api/errors.py line 90

def sanitize_error_message(
    error: Optional[str], 
    log_original: bool = True, 
    context: str = ""
) -> Optional[str]:

When called:

sanitize_error_message(err, False)  # What does False mean?

The reader must look at the function signature to understand False means "don't log original".

Suggested Approach

Replace boolean flags with enums:

from enum import Enum

class ErrorLogging(str, Enum):
    LOG_ORIGINAL = "log_original"
    SKIP_LOGGING = "skip_logging"

def sanitize_error_message(
    error: Optional[str], 
    logging: ErrorLogging = ErrorLogging.LOG_ORIGINAL, 
    context: str = ""
) -> Optional[str]:

Now calls are self-documenting:

sanitize_error_message(err, ErrorLogging.SKIP_LOGGING)

Other Candidates

Search for functions with boolean parameters like:

• include_*
• skip_*
• force_*
• allow_*

Benefits

• Call sites are immediately understandable
• IDE autocomplete shows available options
• Easier to add new options later
• Type safety prevents passing wrong values

Files to Review

• api/errors.py
• api/common.py
• worker/transcoder.py

---

From code clarity review by Conway