provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/process/runner.py

@@ -0,0 +1,390 @@
+"""Core subprocess execution utilities."""
+
+from collections.abc import Iterator, Mapping
+import os
+from pathlib import Path
+import subprocess
+from typing import Any
+
+from attrs import define
+
+from provide.foundation.errors.integration import TimeoutError
+from provide.foundation.errors.runtime import ProcessError
+from provide.foundation.logger import get_logger
+
+plog = get_logger(__name__)
+
+
+@define
+class CompletedProcess:
+    """Result of a completed process."""
+
+    args: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+    cwd: str | None = None
+    env: dict[str, str] | None = None
+
+
+def run_command(
+    cmd: list[str] | str,
+    cwd: str | Path | None = None,
+    env: Mapping[str, str] | None = None,
+    capture_output: bool = True,
+    check: bool = True,
+    timeout: float | None = None,
+    text: bool = True,
+    input: str | bytes | None = None,
+    shell: bool = False,
+    **kwargs: Any,
+) -> CompletedProcess:
+    """
+    Run a subprocess command with consistent error handling and logging.
+
+    Args:
+        cmd: Command and arguments as a list
+        cwd: Working directory for the command
+        env: Environment variables (if None, uses current environment)
+        capture_output: Whether to capture stdout/stderr
+        check: Whether to raise exception on non-zero exit
+        timeout: Command timeout in seconds
+        text: Whether to decode output as text
+        input: Input to send to the process
+        shell: Whether to run command through shell
+        **kwargs: Additional arguments passed to subprocess.run
+
+    Returns:
+        CompletedProcess with results
+
+    Raises:
+        ProcessError: If command fails and check=True
+        TimeoutError: If timeout is exceeded
+    """
+    cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd)
+    plog.info("🚀 Running command", command=cmd_str, cwd=str(cwd) if cwd else None)
+
+    # Prepare environment, disabling foundation telemetry by default
+    run_env = os.environ.copy()
+    if env is not None:
+        run_env.update(env)
+    run_env.setdefault("PROVIDE_TELEMETRY_DISABLED", "true")
+
+    # Convert Path to string
+    if isinstance(cwd, Path):
+        cwd = str(cwd)
+
+    # If command is a string, we need shell=True
+    if isinstance(cmd, str) and not shell:
+        shell = True
+
+    try:
+        # Prepare command for subprocess
+        if shell:
+            # For shell commands, ensure it's a string
+            subprocess_cmd = cmd_str
+        else:
+            # For non-shell, use the original cmd (list or string)
+            subprocess_cmd = cmd
+
+        # Handle input based on text mode
+        if input is not None and text and isinstance(input, bytes):
+            # Convert bytes to string if text mode is enabled
+            subprocess_input = input.decode("utf-8")
+        elif input is not None and not text and isinstance(input, str):
+            # Convert string to bytes if text mode is disabled
+            subprocess_input = input.encode("utf-8")
+        else:
+            subprocess_input = input
+
+        result = subprocess.run(
+            subprocess_cmd,
+            cwd=cwd,
+            env=run_env,
+            capture_output=capture_output,
+            text=text,
+            input=subprocess_input,
+            timeout=timeout,
+            check=False,  # We'll handle the check ourselves
+            shell=shell,
+            **kwargs,
+        )
+
+        completed = CompletedProcess(
+            args=cmd if isinstance(cmd, list) else [cmd],
+            returncode=result.returncode,
+            stdout=result.stdout if capture_output else "",
+            stderr=result.stderr if capture_output else "",
+            cwd=cwd,
+            env=dict(run_env) if env else None,
+        )
+
+        if check and result.returncode != 0:
+            plog.error(
+                "❌ Command failed",
+                command=cmd_str,
+                returncode=result.returncode,
+                stderr=result.stderr if capture_output else None,
+            )
+            raise ProcessError(
+                f"Command failed with exit code {result.returncode}: {cmd_str}",
+                code="PROCESS_COMMAND_FAILED",
+                command=cmd_str,
+                returncode=result.returncode,
+                stdout=result.stdout if capture_output else None,
+                stderr=result.stderr if capture_output else None,
+            )
+
+        plog.debug(
+            "✅ Command completed",
+            command=cmd_str,
+            returncode=result.returncode,
+        )
+
+        return completed
+
+    except subprocess.TimeoutExpired as e:
+        plog.error(
+            "⏱️ Command timed out",
+            command=cmd_str,
+            timeout=timeout,
+        )
+        raise TimeoutError(
+            f"Command timed out after {timeout}s: {cmd_str}",
+            code="PROCESS_TIMEOUT",
+            command=cmd_str,
+            timeout=timeout,
+        ) from e
+    except Exception as e:
+        if isinstance(e, ProcessError | TimeoutError):
+            raise
+        plog.error(
+            "💥 Command execution failed",
+            command=cmd_str,
+            error=str(e),
+        )
+        raise ProcessError(
+            f"Failed to execute command: {cmd_str}",
+            code="PROCESS_EXECUTION_FAILED",
+            command=cmd_str,
+            error=str(e),
+        ) from e
+
+
+def run_command_simple(
+    cmd: list[str],
+    cwd: str | Path | None = None,
+    **kwargs: Any,
+) -> str:
+    """
+    Simple wrapper for run_command that returns stdout as a string.
+
+    Args:
+        cmd: Command and arguments as a list
+        cwd: Working directory for the command
+        **kwargs: Additional arguments passed to run_command
+
+    Returns:
+        Stdout as a stripped string
+
+    Raises:
+        ProcessError: If command fails
+    """
+    result = run_command(cmd, cwd=cwd, capture_output=True, check=True, **kwargs)
+    return result.stdout.strip()
+
+
+def stream_command(
+    cmd: list[str],
+    cwd: str | Path | None = None,
+    env: Mapping[str, str] | None = None,
+    timeout: float | None = None,
+    stream_stderr: bool = False,
+    **kwargs: Any,
+) -> Iterator[str]:
+    """
+    Stream command output line by line.
+
+    Args:
+        cmd: Command and arguments as a list
+        cwd: Working directory for the command
+        env: Environment variables
+        timeout: Command timeout in seconds
+        stream_stderr: Whether to stream stderr (merged with stdout)
+        **kwargs: Additional arguments passed to subprocess.Popen
+
+    Yields:
+        Lines of output from the command
+
+    Raises:
+        ProcessError: If command fails
+        TimeoutError: If timeout is exceeded
+    """
+    import fcntl
+    import os
+    import select
+    import time
+
+    cmd_str = " ".join(cmd) if isinstance(cmd, list) else str(cmd)
+    plog.info("🌊 Streaming command", command=cmd_str, cwd=str(cwd) if cwd else None)
+
+    # Prepare environment, disabling foundation telemetry by default
+    run_env = os.environ.copy()
+    if env is not None:
+        run_env.update(env)
+    run_env.setdefault("PROVIDE_TELEMETRY_DISABLED", "true")
+
+    # Convert Path to string
+    if isinstance(cwd, Path):
+        cwd = str(cwd)
+
+    try:
+        process = subprocess.Popen(
+            cmd,
+            cwd=cwd,
+            env=run_env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT if stream_stderr else subprocess.PIPE,
+            text=True,
+            bufsize=1,
+            universal_newlines=True,
+            **kwargs,
+        )
+
+        if timeout is not None:
+            start_time = time.time()
+
+            if process.stdout:
+                # Use non-blocking I/O with timeout
+                # Make stdout non-blocking
+                fd = process.stdout.fileno()
+                fl = fcntl.fcntl(fd, fcntl.F_GETFL)
+                fcntl.fcntl(fd, fcntl.F_SETFL, fl | os.O_NONBLOCK)
+
+                buffer = ""
+                while True:
+                    elapsed = time.time() - start_time
+                    if elapsed >= timeout:
+                        process.kill()
+                        process.wait()
+                        plog.error(
+                            "⏱️ Stream timed out", command=cmd_str, timeout=timeout
+                        )
+                        raise TimeoutError(
+                            f"Command timed out after {timeout}s: {cmd_str}",
+                            code="PROCESS_STREAM_TIMEOUT",
+                            command=cmd_str,
+                            timeout=timeout,
+                        )
+
+                    # Use select with timeout
+                    remaining = timeout - elapsed
+                    ready, _, _ = select.select(
+                        [process.stdout], [], [], min(0.1, remaining)
+                    )
+
+                    if ready:
+                        try:
+                            chunk = process.stdout.read(1024)
+                            if not chunk:
+                                break  # EOF
+                            buffer += chunk
+
+                            # Yield complete lines
+                            while "\n" in buffer:
+                                line, buffer = buffer.split("\n", 1)
+                                yield line.rstrip()
+                        except OSError:
+                            # No data available yet
+                            pass
+
+                    # Check if process ended
+                    if process.poll() is not None:
+                        # Read any remaining data
+                        remaining_data = process.stdout.read()
+                        if remaining_data:
+                            buffer += remaining_data
+
+                        # Yield any remaining lines
+                        for line in buffer.split("\n"):
+                            if line:
+                                yield line.rstrip()
+                        break
+
+                # Wait for process to complete
+                returncode = process.poll()
+                if returncode is None:
+                    returncode = process.wait()
+        else:
+            # No timeout - use blocking I/O
+            if process.stdout:
+                for line in process.stdout:
+                    yield line.rstrip()
+
+            # Wait for process to complete
+            returncode = process.wait()
+
+        if returncode != 0:
+            raise ProcessError(
+                f"Command failed with exit code {returncode}: {cmd_str}",
+                code="PROCESS_STREAM_FAILED",
+                command=cmd_str,
+                returncode=returncode,
+            )
+
+        plog.debug("✅ Stream completed", command=cmd_str)
+    except Exception as e:
+        if isinstance(e, ProcessError | TimeoutError):
+            raise
+        plog.error("💥 Stream failed", command=cmd_str, error=str(e))
+        raise ProcessError(
+            f"Failed to stream command: {cmd_str}",
+            code="PROCESS_STREAM_ERROR",
+            command=cmd_str,
+            error=str(e),
+        ) from e
+
+
+def run_shell(
+    cmd: str,
+    cwd: str | Path | None = None,
+    env: Mapping[str, str] | None = None,
+    capture_output: bool = True,
+    check: bool = True,
+    timeout: float | None = None,
+    **kwargs: Any,
+) -> CompletedProcess:
+    """Run a shell command.
+
+    Args:
+        cmd: Shell command string
+        cwd: Working directory
+        env: Environment variables
+        capture_output: Whether to capture output
+        check: Whether to raise on non-zero exit
+        timeout: Command timeout
+        **kwargs: Additional subprocess arguments
+
+    Returns:
+        CompletedProcess with results
+    """
+    return run_command(
+        cmd,
+        cwd=cwd,
+        env=env,
+        capture_output=capture_output,
+        check=check,
+        timeout=timeout,
+        shell=True,
+        **kwargs,
+    )
+
+
+# Export all public functions
+__all__ = [
+    "CompletedProcess",
+    "run_command",
+    "run_command_simple",
+    "run_shell",
+    "stream_command",
+]

provide/foundation/setup/__init__.py

@@ -0,0 +1,101 @@
+#
+# __init__.py
+#
+"""
+Foundation Setup Module.
+
+This module provides the main setup API for Foundation,
+orchestrating logging, tracing, and other subsystems.
+"""
+
+from provide.foundation.logger.config import TelemetryConfig
+from provide.foundation.logger.setup import internal_setup
+from provide.foundation.logger.setup.coordinator import _PROVIDE_SETUP_LOCK
+from provide.foundation.logger.setup.testing import reset_foundation_setup_for_testing
+from provide.foundation.metrics.otel import (
+    setup_opentelemetry_metrics,
+    shutdown_opentelemetry_metrics,
+)
+from provide.foundation.streams.file import configure_file_logging, flush_log_streams
+from provide.foundation.tracer.otel import (
+    setup_opentelemetry_tracing,
+    shutdown_opentelemetry,
+)
+
+_EXPLICIT_SETUP_DONE = False
+
+
+def setup_foundation(config: TelemetryConfig | None = None) -> None:
+    """
+    Initialize the Foundation system with all its subsystems.
+
+    This orchestrates:
+    - Logging system setup
+    - Stream configuration
+    - Future: Tracer initialization
+
+    Args:
+        config: Optional configuration to use. If None, loads from environment.
+    """
+    global _EXPLICIT_SETUP_DONE
+
+    with _PROVIDE_SETUP_LOCK:
+        current_config = config if config is not None else TelemetryConfig.from_env()
+
+        # Configure file logging if specified
+        log_file_path = getattr(current_config.logging, "log_file", None)
+        configure_file_logging(log_file_path)
+
+        # Run the main logging setup
+        internal_setup(current_config, is_explicit_call=True)
+
+        # Initialize OpenTelemetry tracing and metrics if available and enabled
+        setup_opentelemetry_tracing(current_config)
+        setup_opentelemetry_metrics(current_config)
+
+        _EXPLICIT_SETUP_DONE = True
+
+
+def setup_telemetry(config: TelemetryConfig | None = None) -> None:
+    """
+    Legacy alias for setup_foundation.
+
+    Args:
+        config: Optional configuration to use. If None, loads from environment.
+    """
+    setup_foundation(config)
+
+
+async def shutdown_foundation(timeout_millis: int = 5000) -> None:
+    """
+    Gracefully shutdown all Foundation subsystems.
+
+    Args:
+        timeout_millis: Timeout for shutdown (currently unused)
+    """
+    with _PROVIDE_SETUP_LOCK:
+        # Shutdown OpenTelemetry tracing and metrics
+        shutdown_opentelemetry()
+        shutdown_opentelemetry_metrics()
+
+        # Flush logging streams
+        flush_log_streams()
+
+
+async def shutdown_foundation_telemetry(timeout_millis: int = 5000) -> None:
+    """
+    Legacy alias for shutdown_foundation.
+
+    Args:
+        timeout_millis: Timeout for shutdown (currently unused)
+    """
+    await shutdown_foundation(timeout_millis)
+
+
+__all__ = [
+    "reset_foundation_setup_for_testing",
+    "setup_foundation",
+    "setup_telemetry",  # Legacy alias
+    "shutdown_foundation",
+    "shutdown_foundation_telemetry",  # Legacy alias
+]

provide/foundation/streams/__init__.py

@@ -0,0 +1,44 @@
+#
+# __init__.py
+#
+"""
+Foundation Streams Module.
+
+Provides stream management functionality including console, file,
+and core stream operations.
+"""
+
+from provide.foundation.streams.console import (
+    get_console_stream,
+    is_tty,
+    supports_color,
+    write_to_console,
+)
+from provide.foundation.streams.core import (
+    ensure_stderr_default,
+    get_log_stream,
+    set_log_stream_for_testing,
+)
+from provide.foundation.streams.file import (
+    close_log_streams,
+    configure_file_logging,
+    flush_log_streams,
+    reset_streams,
+)
+
+__all__ = [
+    # Core stream functions
+    "get_log_stream",
+    "set_log_stream_for_testing",
+    "ensure_stderr_default",
+    # File stream functions
+    "configure_file_logging",
+    "flush_log_streams",
+    "close_log_streams",
+    "reset_streams",
+    # Console stream functions
+    "get_console_stream",
+    "is_tty",
+    "supports_color",
+    "write_to_console",
+]

provide/foundation/streams/console.py

@@ -0,0 +1,57 @@
+#
+# console.py
+#
+"""
+Console stream utilities for Foundation.
+Handles console-specific stream operations and formatting.
+"""
+
+import sys
+from typing import TextIO
+
+from provide.foundation.streams.core import get_log_stream
+
+
+def get_console_stream() -> TextIO:
+    """Get the appropriate console stream for output."""
+    return get_log_stream()
+
+
+def is_tty() -> bool:
+    """Check if the current stream is a TTY (terminal)."""
+    stream = get_log_stream()
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def supports_color() -> bool:
+    """Check if the current stream supports color output."""
+    import os
+
+    # Check NO_COLOR environment variable
+    if os.getenv("NO_COLOR"):
+        return False
+
+    # Check FORCE_COLOR environment variable
+    if os.getenv("FORCE_COLOR"):
+        return True
+
+    # Check if we're in a TTY
+    return is_tty()
+
+
+def write_to_console(message: str, stream: TextIO | None = None) -> None:
+    """
+    Write a message to the console stream.
+
+    Args:
+        message: Message to write
+        stream: Optional specific stream to write to, defaults to current console stream
+    """
+    target_stream = stream or get_console_stream()
+    try:
+        target_stream.write(message)
+        target_stream.flush()
+    except Exception:
+        # Fallback to stderr
+        sys.stderr.write(message)
+        sys.stderr.flush()

provide/foundation/streams/core.py

@@ -0,0 +1,65 @@
+#
+# core.py
+#
+"""
+Core stream management for Foundation.
+Handles log streams, file handles, and output configuration.
+"""
+
+import sys
+import threading
+from typing import TextIO
+
+_PROVIDE_LOG_STREAM: TextIO = sys.stderr
+_LOG_FILE_HANDLE: TextIO | None = None
+_STREAM_LOCK = threading.Lock()
+
+
+def _is_in_click_testing() -> bool:
+    """Check if we're running inside Click's testing framework."""
+    import inspect
+    import os
+
+    # Check environment variables for Click testing
+    if os.getenv("CLICK_TESTING"):
+        return True
+
+    # Check the call stack for Click's testing module or CLI integration tests
+    for frame_info in inspect.stack():
+        module = frame_info.frame.f_globals.get("__name__", "")
+        filename = frame_info.filename or ""
+
+        if "click.testing" in module or "test_cli_integration" in filename:
+            return True
+
+        # Also check for common Click testing patterns
+        locals_self = frame_info.frame.f_locals.get("self")
+        if hasattr(locals_self, "runner"):
+            runner = locals_self.runner
+            if hasattr(runner, "invoke") and "CliRunner" in str(type(runner)):
+                return True
+
+    return False
+
+
+def get_log_stream() -> TextIO:
+    """Get the current log stream."""
+    return _PROVIDE_LOG_STREAM
+
+
+def set_log_stream_for_testing(stream: TextIO | None) -> None:
+    """Set the log stream for testing purposes."""
+    global _PROVIDE_LOG_STREAM
+    with _STREAM_LOCK:
+        # Don't modify streams if we're in Click testing context
+        if _is_in_click_testing():
+            return
+        _PROVIDE_LOG_STREAM = stream if stream is not None else sys.stderr
+
+
+def ensure_stderr_default() -> None:
+    """Ensure the log stream defaults to stderr if it's stdout."""
+    global _PROVIDE_LOG_STREAM
+    with _STREAM_LOCK:
+        if _PROVIDE_LOG_STREAM is sys.stdout:
+            _PROVIDE_LOG_STREAM = sys.stderr