read_env and read_int typed config

"""Read settings from environment variables with defaults and clear errors."""
import os


class ConfigError(ValueError):
    """A required or malformed environment value."""


def read_env(name: str, default: str | None = None, *, required: bool = False) -> str:
    """Return the stripped value; raise when required and absent."""
    value = os.environ.get(name, default)
    if value is None or not value.strip():
        if required:
            raise ConfigError(f"{name} is required but not set")
        return ""
    return value.strip()


def read_int(name: str, default: int | None = None, *, minimum: int = 0) -> int:
    """Parse an integer variable and validate its lower bound."""
    fallback = str(default) if default is not None else None
    raw = read_env(name, fallback, required=default is None)
    try:
        value = int(raw)
    except ValueError as exc:
        raise ConfigError(f"{name} must be an integer, got {raw!r}") from exc
    if value < minimum:
        raise ConfigError(f"{name} must be >= {minimum}, got {value}")
    return value


def read_flag(name: str, default: bool = False) -> bool:
    """Parse common truthy spellings; anything else is False."""
    raw = read_env(name, "1" if default else "0").lower()
    return raw in {"1", "true", "yes", "on"}