| """Utility helpers for validating and normalizing Robomme difficulty hints.""" | |
| from __future__ import annotations | |
| from typing import Optional | |
| VALID_DIFFICULTIES = {"easy", "medium", "hard"} | |
| def normalize_robomme_difficulty(value: Optional[str]) -> Optional[str]: | |
| """Return a canonical difficulty string or ``None`` if no override was provided.""" | |
| if value is None: | |
| return None | |
| if not isinstance(value, str): | |
| raise TypeError( | |
| "difficulty must be a string (got " | |
| f"{type(value).__name__!r})." | |
| ) | |
| normalized = value.strip().lower() | |
| if normalized not in VALID_DIFFICULTIES: | |
| raise ValueError( | |
| "Unsupported difficulty level. Available options: " | |
| f"{sorted(VALID_DIFFICULTIES)}." | |
| ) | |
| return normalized | |