Configuration

def load_environment(profiles: str = None, env=os.environ) -> List[str]:
    """
    Load configuration from profiles and environment variables.
    
    Args:
        profiles: Comma-separated list of profile names to load
        env: Environment dictionary (defaults to os.environ)
    
    Returns:
        List of loaded profile names
        
    Location: localstack.config
    """

def parse_boolean_env(env_var_name: str) -> bool | None:
    """
    Parse boolean environment variables using LocalStack conventions.
    
    Args:
        env_var_name: Name of environment variable to parse
        
    Returns:
        True for TRUE_STRINGS ("1", "true", "True")
        False for FALSE_STRINGS ("0", "false", "False")  
        None if variable not set or invalid value
        
    Location: localstack.config
    """

def is_env_true(env_var_name: str) -> bool:
    """
    Check if environment variable is set to a true value.
    
    Args:
        env_var_name: Name of environment variable
        
    Returns:
        True if variable equals TRUE_STRINGS, False otherwise
        
    Location: localstack.config
    """

def is_env_not_false(env_var_name: str) -> bool:
    """
    Check if environment variable is NOT explicitly set to false.
    
    Args:
        env_var_name: Name of environment variable
        
    Returns:
        True unless variable explicitly equals FALSE_STRINGS
        
    Location: localstack.config  
    """

def eval_log_type(env_var_name: str) -> str | bool:
    """
    Parse logging-specific environment variable with boolean fallback.
    
    Args:
        env_var_name: Name of logging environment variable
        
    Returns:
        String log level or boolean based on content
        
    Location: localstack.config
    """

def is_linux() -> bool:
    """Check if running on Linux platform"""

def is_macos() -> bool:
    """Check if running on macOS platform"""

def is_windows() -> bool:
    """Check if running on Windows platform"""

def is_wsl() -> bool:
    """Check if running inside Windows Subsystem for Linux"""

def in_docker() -> bool:
    """Check if LocalStack is running inside a Docker container"""

def ping(host: str) -> bool:
    """
    Test network connectivity to a host.
    
    Args:
        host: Hostname or IP address to ping
        
    Returns:
        True if host is reachable, False otherwise
    """

class Directories:
    """
    LocalStack directory structure management.
    
    Location: localstack.config.Directories
    """
    
    static_libs: str      # Static binaries and libraries
    var_libs: str         # Runtime computed libraries  
    cache: str            # Persistent cache storage
    tmp: str              # Temporary files
    mounted_tmp: str      # Shared temporary files (Docker mounts)
    functions: str        # Lambda container communication
    data: str             # LocalStack state and pods
    config: str           # Configuration files
    init: str             # Initialization/provisioning scripts  
    logs: str             # Log files
    
    @classmethod
    def defaults() -> 'Directories':
        """
        Get default directory paths based on environment.
        
        Returns:
            Directories instance with platform-appropriate defaults
        """
        
    @classmethod  
    def for_container() -> 'Directories':
        """
        Get directory paths optimized for container environments.
        
        Returns:
            Directories instance with container-specific paths
        """
        
    @classmethod
    def for_host() -> 'Directories':
        """
        Get directory paths for host-mode execution.
        
        Returns:
            Directories instance for direct host execution
        """
        
    @classmethod
    def for_cli() -> 'Directories':
        """
        Get directory paths optimized for CLI operations.
        
        Returns:
            Directories instance for CLI usage
        """
        
    def mkdirs(self) -> None:
        """
        Create all directories in the structure.
        Creates parent directories as needed, ignores existing directories.
        """

# Profile and environment
CONFIG_PROFILE: str           # Active configuration profile name
CONFIG_DIR: str              # Configuration directory (~/.localstack)
VOLUME_DIR: str              # LocalStack volume directory  
DATA_DIR: str                # Data directory override
PERSISTENCE: bool            # Enable state persistence across restarts

# Debugging and logging
DEBUG: bool                  # Enable debug mode with verbose logging
LS_LOG: str                  # Logging level (trace-internal, trace, debug, info, warn, error)

# Docker configuration
DOCKER_SOCK: str             # Docker socket path (/var/run/docker.sock)
DOCKER_CMD: str              # Docker command executable
DOCKER_FLAGS: str            # Additional Docker CLI flags
MAIN_CONTAINER_NAME: str     # Container name (default: localstack-main)
MAIN_DOCKER_NETWORK: str     # Docker network name

# Service management
SERVICES: str                # Enabled services (deprecated, use EAGER_SERVICE_LOADING)
EAGER_SERVICE_LOADING: bool  # Preload services on startup
STRICT_SERVICE_LOADING: bool # Strict service loading validation

# Network and gateway
GATEWAY_LISTEN: str          # Gateway listen addresses (comma-separated)
EDGE_PORT: int              # Main LocalStack port (default: 4566)  
USE_SSL: bool               # Enable SSL/TLS for endpoints

# Lambda execution
LAMBDA_EXECUTOR: str              # Lambda executor type (docker, local)
LAMBDA_RUNTIME_EXECUTOR: str      # Runtime executor implementation
LAMBDA_DOCKER_NETWORK: str        # Docker network for Lambda containers
LAMBDA_DOCKER_DNS: str            # DNS settings for Lambda containers
LAMBDA_DOCKER_FLAGS: str          # Additional Docker flags for Lambda

# Lambda container management
LAMBDA_REMOVE_CONTAINERS: bool    # Auto-remove Lambda containers after execution
LAMBDA_KEEPALIVE_MS: int         # Container keepalive time in milliseconds

# Error simulation
KINESIS_ERROR_PROBABILITY: float    # Kinesis error simulation (0.0-1.0)
DYNAMODB_ERROR_PROBABILITY: float   # DynamoDB error simulation (0.0-1.0)

# Service behavior
SQS_ENDPOINT_STRATEGY: str          # SQS endpoint strategy (domain, path, off) 
S3_SKIP_SIGNATURE_VALIDATION: bool  # Skip S3 signature validation

# DNS configuration
DNS_ADDRESS: str                    # DNS server bind address
DNS_PORT: int                       # DNS server port (default: 53)

# Profile system
def load_profile(profile_name: str) -> dict[str, str]:
    """
    Load configuration from named profile.
    
    Profile files located at: ~/.localstack/profiles/{profile_name}
    Format: KEY=VALUE pairs, one per line
    Supports variable substitution and inheritance
    
    Args:
        profile_name: Name of profile to load
        
    Returns:
        Dictionary of configuration key-value pairs
    """

# Configuration precedence (highest to lowest):
# 1. Environment variables
# 2. Command line arguments  
# 3. Profile files (~/.localstack/profiles/<profile>)
# 4. Default config file (~/.localstack/config)
# 5. Built-in defaults

# Profile file: ~/.localstack/profiles/development
DEBUG=1
LS_LOG=debug
SERVICES=s3,lambda,dynamodb
LAMBDA_EXECUTOR=docker
PERSISTENCE=1

# Profile file: ~/.localstack/profiles/testing  
DEBUG=0
LS_LOG=info
SERVICES=s3,sqs,sns
LAMBDA_EXECUTOR=local
KINESIS_ERROR_PROBABILITY=0.1

# Loading profiles programmatically
from localstack.config import load_environment

# Load single profile
profiles = load_environment("development")

# Load multiple profiles (later profiles override earlier ones)  
profiles = load_environment("base,development,local")

# Version constants
VERSION: str                      # LocalStack version string
LOCALSTACK_MAVEN_VERSION: str     # Java utilities version

# Network defaults
DEFAULT_PORT_EDGE: int = 4566          # Main LocalStack port
LOCALHOST: str = "localhost"           # Localhost hostname
LOCALHOST_IP: str = "127.0.0.1"       # Localhost IP address  
BIND_HOST: str = "0.0.0.0"            # Default bind address

# Directory defaults
DEFAULT_VOLUME_DIR: str = "/var/lib/localstack"    # Container volume directory
DEFAULT_AWS_ACCOUNT_ID: str = "000000000000"      # Default AWS account ID

# HTTP content types
APPLICATION_JSON: str = "application/json"
APPLICATION_XML: str = "application/xml"
APPLICATION_AMZ_JSON_1_0: str = "application/x-amz-json-1.0"  
APPLICATION_AMZ_JSON_1_1: str = "application/x-amz-json-1.1"
TEXT_XML: str = "text/xml"

# Boolean value parsing
TRUE_STRINGS: tuple[str, ...] = ("1", "true", "True")
FALSE_STRINGS: tuple[str, ...] = ("0", "false", "False")

# Logging configuration
LOG_LEVELS: tuple[str, ...] = (
    "trace-internal", "trace", "debug", 
    "info", "warn", "error", "warning"
)
TRACE_LOG_LEVELS: list[str] = ["trace", "trace-internal"]

# Docker image names
DOCKER_IMAGE_NAME: str = "localstack/localstack"
DOCKER_IMAGE_NAME_PRO: str = "localstack/localstack-pro"
DOCKER_IMAGE_NAME_FULL: str = "localstack/localstack-full"

# External service endpoints
API_ENDPOINT: str = "https://api.localstack.cloud/v1"
ANALYTICS_API: str = "https://analytics.localstack.cloud/v1"  
ASSETS_ENDPOINT: str = "https://assets.localstack.cloud"
ARTIFACTS_REPO: str = "https://github.com/localstack/localstack-artifacts"

# Environment variables for local development
export DEBUG=1
export LS_LOG=debug
export SERVICES=s3,lambda,dynamodb,sqs
export LAMBDA_EXECUTOR=docker
export PERSISTENCE=1
export DATA_DIR=/tmp/localstack-data

# Minimal logging and specific services
export DEBUG=0
export LS_LOG=info  
export EAGER_SERVICE_LOADING=0
export STRICT_SERVICE_LOADING=1
export USE_SSL=1
export GATEWAY_LISTEN=0.0.0.0:4566,0.0.0.0:443

# Error simulation for chaos testing
export KINESIS_ERROR_PROBABILITY=0.05
export DYNAMODB_ERROR_PROBABILITY=0.02
export S3_SKIP_SIGNATURE_VALIDATION=1
export LAMBDA_REMOVE_CONTAINERS=1

# Custom networking setup
export MAIN_DOCKER_NETWORK=my-app-network
export LAMBDA_DOCKER_NETWORK=my-app-network
export LAMBDA_DOCKER_DNS=8.8.8.8
export DNS_ADDRESS=0.0.0.0