"""
Environment variable utilities for secure configuration management.

This module provides functions to safely retrieve and validate environment
variables, ensuring that sensitive configuration is properly handled.
"""

import os


def get_required_env(var_name: str, description: str | None = None) -> str:
    """
    Get a required environment variable or raise an error with helpful message.

    Args:
        var_name: The name of the environment variable to retrieve.
        description: Optional description of what the variable is used for.

    Returns:
        The value of the environment variable.

    Raises:
        ValueError: If the environment variable is not set or is empty.

    Example:
        >>> api_key = get_required_env("OPENAI_API_KEY", "OpenAI API authentication")
    """
    value = os.getenv(var_name)
    if not value:
        desc_part = f" ({description})" if description else ""
        raise ValueError(
            f"Missing required environment variable: {var_name}{desc_part}. "
            f"Please set it in your .env file or environment."
        )
    return value


def validate_env_vars(*var_names: str) -> dict[str, str]:
    """
    Validate that multiple environment variables are set.

    Args:
        *var_names: Variable names to check.

    Returns:
        Dictionary mapping variable names to their values.

    Raises:
        ValueError: If any of the required variables are missing.

    Example:
        >>> env = validate_env_vars("AZURE_OPENAI_ENDPOINT", "AZURE_OPENAI_API_KEY")
        >>> print(env["AZURE_OPENAI_ENDPOINT"])
    """
    missing = []
    values = {}

    for var_name in var_names:
        value = os.getenv(var_name)
        if not value:
            missing.append(var_name)
        else:
            values[var_name] = value

    if missing:
        raise ValueError(
            f"Missing required environment variables: {', '.join(missing)}. "
            f"Please set them in your .env file or environment."
        )

    return values


def get_env_with_default(var_name: str, default: str) -> str:
    """
    Get an environment variable with a default value.

    Args:
        var_name: The name of the environment variable.
        default: The default value if the variable is not set.

    Returns:
        The value of the environment variable or the default.

    Example:
        >>> model = get_env_with_default("MODEL_NAME", "gpt-4o")
    """
    return os.getenv(var_name, default)