litlaunch 1.0.0__py3-none-any.whl

litlaunch/__init__.py

@@ -0,0 +1,192 @@
+"""Public API for LitLaunch."""
+
+from litlaunch.backend import (
+    BackendCommand,
+    BackendCommandContext,
+    BackendCommandProvider,
+    StreamlitBackendCommandProvider,
+)
+from litlaunch.browsers import (
+    BrowserCapability,
+    BrowserKind,
+    BrowserLauncher,
+    BrowserLaunchResult,
+    BrowserResolution,
+)
+from litlaunch.colors import (
+    THEME_COLORS,
+    ThemeColor,
+    get_theme_color,
+    hook_orange,
+    is_hex_color,
+    is_theme_color_name,
+)
+from litlaunch.config import BrowserChoice, LauncherConfig, LaunchMode, TrustMode
+from litlaunch.console import (
+    ConsoleMode,
+    ConsolePhase,
+    ConsoleRenderer,
+    ConsoleTheme,
+)
+from litlaunch.diagnostics_page import (
+    DiagnosticsPageBuilder,
+    DiagnosticsPageOptions,
+    create_diagnostics_page,
+)
+from litlaunch.events import (
+    RuntimeEvent,
+    RuntimeEventSink,
+    create_runtime_event_file_sink,
+)
+from litlaunch.exceptions import (
+    BrowserError,
+    CommandBuildError,
+    ConfigurationError,
+    LitLaunchError,
+    PortError,
+    ProcessError,
+)
+from litlaunch.health import HealthChecker
+from litlaunch.inspect import (
+    DiagnosticCollector,
+    DiagnosticItem,
+    DiagnosticSection,
+    DiagnosticsReport,
+    DiagnosticStatus,
+    HTMLDiagnosticsRenderer,
+    JSONDiagnosticsRenderer,
+    SanitizedBundleRenderer,
+)
+from litlaunch.launcher import StreamlitLauncher
+from litlaunch.lifecycle import LaunchEvent, LaunchPlan, LaunchResult, LaunchState
+from litlaunch.monitored import MonitoredRunResult, run_monitored_webapp, run_profile
+from litlaunch.platforms import (
+    Architecture,
+    OperatingSystem,
+    PlatformDetector,
+    PlatformInfo,
+)
+from litlaunch.ports import PortManager
+from litlaunch.process import ManagedProcess, ProcessManager
+from litlaunch.profiles import LaunchProfile, load_profile, load_profiles
+from litlaunch.session import RuntimeSession
+from litlaunch.shutdown import (
+    HookConsoleVisibility,
+    LauncherRuntime,
+    ShutdownClient,
+    ShutdownConfig,
+    ShutdownHook,
+    ShutdownHookRegistry,
+    ShutdownHookResult,
+    ShutdownHookStatus,
+    ShutdownRequestResult,
+    ShutdownResult,
+)
+from litlaunch.streamlit import StreamlitCommandBuilder
+from litlaunch.version import __version__
+from litlaunch.windowing import (
+    NoopWindowMonitor,
+    PollingWindowMonitor,
+    WindowInfo,
+    WindowMonitor,
+    WindowMonitorConfig,
+    WindowMonitorEvent,
+    WindowMonitorResult,
+    WindowMonitorStatus,
+    WindowsChromiumWindowMonitor,
+    WindowsWindowProvider,
+    WindowTarget,
+    create_window_monitor,
+    is_chromium_window,
+)
+
+__all__ = [
+    "Architecture",
+    "BrowserCapability",
+    "BrowserChoice",
+    "BrowserKind",
+    "BrowserLaunchResult",
+    "BrowserLauncher",
+    "BrowserResolution",
+    "BrowserError",
+    "BackendCommand",
+    "BackendCommandContext",
+    "BackendCommandProvider",
+    "CommandBuildError",
+    "ConfigurationError",
+    "ConsoleMode",
+    "ConsolePhase",
+    "ConsoleRenderer",
+    "ConsoleTheme",
+    "get_theme_color",
+    "hook_orange",
+    "HealthChecker",
+    "HookConsoleVisibility",
+    "DiagnosticCollector",
+    "DiagnosticItem",
+    "DiagnosticSection",
+    "DiagnosticStatus",
+    "DiagnosticsPageBuilder",
+    "DiagnosticsPageOptions",
+    "DiagnosticsReport",
+    "HTMLDiagnosticsRenderer",
+    "JSONDiagnosticsRenderer",
+    "SanitizedBundleRenderer",
+    "LaunchMode",
+    "LauncherConfig",
+    "LaunchProfile",
+    "LitLaunchError",
+    "LaunchEvent",
+    "LaunchPlan",
+    "LaunchResult",
+    "LaunchState",
+    "LauncherRuntime",
+    "OperatingSystem",
+    "PlatformDetector",
+    "PlatformInfo",
+    "ManagedProcess",
+    "MonitoredRunResult",
+    "NoopWindowMonitor",
+    "PortManager",
+    "PollingWindowMonitor",
+    "PortError",
+    "ProcessError",
+    "ProcessManager",
+    "load_profile",
+    "load_profiles",
+    "RuntimeSession",
+    "RuntimeEvent",
+    "RuntimeEventSink",
+    "create_runtime_event_file_sink",
+    "run_profile",
+    "run_monitored_webapp",
+    "ShutdownClient",
+    "ShutdownConfig",
+    "ShutdownHook",
+    "ShutdownHookRegistry",
+    "ShutdownHookResult",
+    "ShutdownHookStatus",
+    "ShutdownRequestResult",
+    "ShutdownResult",
+    "StreamlitCommandBuilder",
+    "StreamlitBackendCommandProvider",
+    "StreamlitLauncher",
+    "WindowsChromiumWindowMonitor",
+    "WindowsWindowProvider",
+    "WindowInfo",
+    "WindowMonitor",
+    "WindowMonitorConfig",
+    "WindowMonitorEvent",
+    "WindowMonitorResult",
+    "WindowMonitorStatus",
+    "WindowTarget",
+    "__version__",
+    "create_diagnostics_page",
+    "create_window_monitor",
+    "is_chromium_window",
+    "is_hex_color",
+    "is_theme_color_name",
+    "THEME_COLORS",
+    "ThemeColor",
+    "TrustMode",
+]

litlaunch/__main__.py

@@ -0,0 +1,8 @@
+"""Module execution entry point for ``python -m litlaunch``."""
+
+from __future__ import annotations
+
+from litlaunch.cli import main
+
+if __name__ == "__main__":  # pragma: no cover - exercised through subprocess
+    raise SystemExit(main())

litlaunch/_protocols.py

@@ -0,0 +1,35 @@
+"""Internal structural protocols for injectable runtime dependencies."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ClockProvider(Protocol):
+    """Clock surface used for deterministic lifecycle event timestamps."""
+
+    def monotonic(self) -> float:
+        """Return a monotonic timestamp."""
+
+    def time(self) -> float:
+        """Return a wall-clock timestamp."""
+
+
+@runtime_checkable
+class ManagedPopen(Protocol):
+    """Subprocess surface required by LitLaunch process ownership."""
+
+    pid: int
+
+    def poll(self) -> int | None:
+        """Return the process return code, or None while running."""
+
+    def wait(self, timeout: float | None = None) -> int | None:
+        """Wait for process exit and return the return code."""
+
+    def terminate(self) -> None:
+        """Request graceful process termination."""
+
+    def kill(self) -> None:
+        """Force process termination."""

litlaunch/artifacts.py

@@ -0,0 +1,79 @@
+"""Project-local generated artifact paths for LitLaunch."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from litlaunch.config import LauncherConfig
+
+ARTIFACT_DIR_NAME = ".litlaunch"
+REPORTS_DIR_NAME = "reports"
+SHORTCUTS_DIR_NAME = "shortcuts"
+TMP_DIR_NAME = "tmp"
+BROWSER_PROFILES_DIR_NAME = "browser-profiles"
+
+
+def project_root_for_config(config: LauncherConfig) -> Path:
+    """Return the project root LitLaunch should use for generated artifacts."""
+
+    if config.cwd is not None:
+        return config.cwd
+    app_parent = config.app_path.parent
+    if str(app_parent) in ("", "."):
+        return Path.cwd()
+    return app_parent
+
+
+def artifact_dir(root: Path | None = None) -> Path:
+    """Return the root generated-artifacts directory for a project."""
+
+    return (root or Path.cwd()) / ARTIFACT_DIR_NAME
+
+
+def reports_dir(root: Path | None = None, *, create: bool = False) -> Path:
+    """Return the reports artifact directory."""
+
+    path = artifact_dir(root) / REPORTS_DIR_NAME
+    if create:
+        path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def shortcuts_dir(root: Path | None = None, *, create: bool = False) -> Path:
+    """Return the shortcut artifact directory."""
+
+    path = artifact_dir(root) / SHORTCUTS_DIR_NAME
+    if create:
+        path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def browser_profiles_dir(root: Path | None = None, *, create: bool = False) -> Path:
+    """Return the managed browser-profile temp directory."""
+
+    path = artifact_dir(root) / TMP_DIR_NAME / BROWSER_PROFILES_DIR_NAME
+    if create:
+        path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def default_report_path(
+    root: Path | None = None, *, create_parent: bool = False
+) -> Path:
+    """Return the default human-readable HTML report path."""
+
+    return reports_dir(root, create=create_parent) / "litlaunch-report.html"
+
+
+def default_shortcut_path(root: Path, basename: str, extension: str) -> Path:
+    """Return the default project-local shortcut path."""
+
+    return shortcuts_dir(root) / f"{basename}{extension}"
+
+
+def create_managed_browser_profile_dir(root: Path | None = None) -> Path:
+    """Create a project-local temporary browser profile directory."""
+
+    parent = browser_profiles_dir(root, create=True)
+    return Path(tempfile.mkdtemp(prefix="litlaunch-browser-", dir=parent))

litlaunch/backend.py

@@ -0,0 +1,85 @@
+"""Backend command provider abstractions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from litlaunch.config import LauncherConfig
+from litlaunch.exceptions import CommandBuildError
+from litlaunch.streamlit import StreamlitCommandBuilder
+
+
+@dataclass(frozen=True)
+class BackendCommandContext:
+    """Resolved launch context passed to backend command providers."""
+
+    config: LauncherConfig
+    host: str
+    port: int
+    app_url: str
+    health_url: str
+    headless: bool
+
+
+@dataclass(frozen=True)
+class BackendCommand:
+    """Shell-free command returned by a backend command provider."""
+
+    command: Sequence[str]
+    description: str = "backend"
+    backend_kind: str | None = None
+
+    def __post_init__(self) -> None:
+        if isinstance(self.command, (str, bytes)):
+            raise CommandBuildError("Backend command must be a sequence of strings.")
+        try:
+            command = tuple(str(part) for part in self.command)
+        except TypeError as exc:
+            raise CommandBuildError(
+                "Backend command must be a sequence of strings."
+            ) from exc
+        if not command:
+            raise CommandBuildError("Backend command cannot be empty.")
+        if any(not part for part in command):
+            raise CommandBuildError("Backend command arguments cannot be empty.")
+        object.__setattr__(self, "command", command)
+
+        description = str(self.description).strip()
+        if not description:
+            raise CommandBuildError("Backend command description cannot be empty.")
+        object.__setattr__(self, "description", description)
+
+        if self.backend_kind is not None:
+            kind = str(self.backend_kind).strip()
+            object.__setattr__(self, "backend_kind", kind or None)
+
+
+class BackendCommandProvider(Protocol):
+    """Protocol for command-only backend customization."""
+
+    def build_backend_command(
+        self,
+        context: BackendCommandContext,
+    ) -> BackendCommand:
+        """Return the backend command LitLaunch should start."""
+
+
+class StreamlitBackendCommandProvider:
+    """Default backend command provider for source Streamlit apps."""
+
+    description = "Streamlit backend"
+    backend_kind = "streamlit"
+
+    def build_backend_command(
+        self,
+        context: BackendCommandContext,
+    ) -> BackendCommand:
+        """Build the standard `python -m streamlit run ...` command."""
+
+        return BackendCommand(
+            command=StreamlitCommandBuilder(context.config).build(port=context.port),
+            description=self.description,
+            backend_kind=self.backend_kind,
+        )