chore: import upstream snapshot with attribution

shared/python/env_utils.py

@@ -0,0 +1,88 @@
+"""
+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)