#
# Copyright (c) 2024-2026, Daily
#
# SPDX-License-Identifier: BSD 2-Clause License
#
"""Environment variable helpers.
This module provides small, centralized parsing helpers for environment variables.
"""
from __future__ import annotations
import os
[docs]
class InvalidEnvVarValueError(ValueError):
"""Raised when an environment variable value cannot be parsed."""
[docs]
def __init__(self, name: str, value: str, expected: str):
"""Initialize an InvalidEnvVarValueError."""
super().__init__(f"Invalid value for env var {name!r}: {value!r}. Expected {expected}.")
self.name = name
self.value = value
self.expected = expected
[docs]
def env_truthy(name: str, default: bool = False) -> bool:
"""Interpret an environment variable as a boolean.
- If the variable is **not set**, returns `default`.
- If the variable is set to a recognized boolean string, returns the parsed value.
- Otherwise, raises `InvalidEnvVarValueError`.
Recognized values (case-insensitive, whitespace ignored):
- Truthy: "1", "true", "yes", "y", "on"
- Falsy: "0", "false", "no", "n", "off", ""
"""
raw = os.getenv(name)
if raw is None:
return default
val = raw.strip().lower()
if val in {"1", "true", "yes", "y", "on"}:
return True
if val in {"0", "false", "no", "n", "off", ""}:
return False
raise InvalidEnvVarValueError(
name=name,
value=raw,
expected="true or false",
)