easy-docker-manager 1.0.0__py3-none-any.whl

easy_docker_manager/app/__init__.py

@@ -0,0 +1,3 @@
+from easy_docker_manager.app.app import EDMApp
+
+__all__ = ["EDMApp"]

easy_docker_manager/app/app.py

@@ -0,0 +1,176 @@
+"""Run the Easy Docker Manager terminal application."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+import urwid
+
+from easy_docker_manager.app.background_notifier import (
+    BackgroundNotifier,
+    create_background_notifier,
+)
+from easy_docker_manager.app.background_task_result_handler import (
+    BackgroundTaskResultHandler,
+)
+from easy_docker_manager.app.runtime_factory import EDMRuntimeFactory
+from easy_docker_manager.app.scheduler import BackgroundTaskScheduler
+from easy_docker_manager.core import AppConfig
+from easy_docker_manager.docker.base import ContainerDataSource
+from easy_docker_manager.ui.keyboard_controller import KeyAction, KeyboardController
+from easy_docker_manager.ui.terminal_layout import TerminalLayoutView
+from easy_docker_manager.ui.ui_controller import UIController
+
+logger = logging.getLogger(__name__)
+
+
+class _KeyboardRoutingWidget(urwid.WidgetWrap):
+    """Send Urwid keypresses to EDMApp."""
+
+    def __init__(self, app: EDMApp) -> None:
+        """Wrap the main layout so EDMApp can handle every keypress."""
+        self.app = app
+        super().__init__(app.layout)
+
+    def keypress(self, size: tuple[int, ...], key: str) -> Optional[str]:
+        """Pass one Urwid keypress to EDMApp."""
+        return self.app.handle_keyboard_input(key, size)
+
+
+class EDMApp:
+    """Run the terminal UI and coordinate the application.
+
+    EDMApp handles keyboard input, processes completed background tasks, redraws
+    the screen when data changes, and closes application resources during
+    shutdown. The console entry point creates one EDMApp and calls run().
+    """
+
+    def __init__(
+        self,
+        app_config: Optional[AppConfig] = None,
+        container_data_source: Optional[ContainerDataSource] = None,
+        runtime_factory: Optional[EDMRuntimeFactory] = None,
+        background_notifier: Optional[BackgroundNotifier] = None,
+    ) -> None:
+        # Workers need a way to wake EDMApp before the Urwid loop exists. The
+        # notifier uses a pipe on Unix-like systems and polling on Windows.
+        self.background_notifier = (
+            background_notifier
+            if background_notifier is not None
+            else create_background_notifier()
+        )
+        self.ui_event_loop: Optional[urwid.MainLoop] = None
+        self._background_check_timer_handle: Optional[Any] = None
+
+        selected_runtime_factory = (
+            runtime_factory
+            if runtime_factory is not None
+            else EDMRuntimeFactory(
+                app_config=app_config,
+                container_data_source=container_data_source,
+            )
+        )
+        runtime = selected_runtime_factory.create_runtime(
+            self._notify_background_task_ready
+        )
+
+        # Keep the objects used to run background work, draw the terminal, and
+        # close the Docker connection when EDM stops.
+        self.container_data_source: ContainerDataSource = runtime.container_data_source
+        self.task_runner = runtime.task_runner
+        self.terminal_layout_view: TerminalLayoutView = runtime.terminal_layout_view
+        self.layout = self.terminal_layout_view.layout
+
+        # Keep the objects that schedule Docker requests, handle keyboard
+        # actions, and apply results returned by background workers.
+        self.scheduler: BackgroundTaskScheduler = runtime.scheduler
+        self.ui_controller: UIController = runtime.ui_controller
+        self.keyboard_controller: KeyboardController = runtime.keyboard_controller
+        self.background_task_result_handler: BackgroundTaskResultHandler = (
+            runtime.background_task_result_handler
+        )
+
+    def run(self) -> None:
+        """Start the terminal UI, then close its resources when the UI stops."""
+        logger.info("Starting EDM app")
+        try:
+            self.ui_event_loop = urwid.MainLoop(
+                _KeyboardRoutingWidget(self),
+                palette=self.terminal_layout_view.build_palette(),
+                handle_mouse=False,
+            )
+            self.background_notifier.start(
+                self.ui_event_loop,
+                self._process_completed_background_tasks,
+            )
+            self.scheduler.schedule_container_refresh(force=True)
+            self.ui_controller.render_current_state()
+            self._schedule_next_background_check(delay=0)
+            self.ui_event_loop.run()
+        finally:
+            self.background_notifier.stop()
+            self.task_runner.shutdown(wait=True)
+            self.container_data_source.close()
+            logger.info("Stopped EDM app")
+
+    def handle_keyboard_input(
+        self,
+        key: str,
+        terminal_size: Optional[tuple[int, ...]] = None,
+    ) -> Optional[str]:
+        """Handle one keypress, redraw when needed, or exit on Quit."""
+        action = self.keyboard_controller.handle_keypress(key, terminal_size)
+        if action == KeyAction.QUIT:
+            raise urwid.ExitMainLoop()
+        if action == KeyAction.RENDER:
+            self.ui_controller.render_current_state()
+            self.scheduler.schedule_next_tasks()
+            self._schedule_next_background_check()
+        return None
+
+    def _schedule_next_background_tasks(
+        self,
+        _loop: urwid.MainLoop,
+        _data: Any = None,
+    ) -> None:
+        """Start due background work, then schedule the next check."""
+        self._background_check_timer_handle = None
+        self.scheduler.schedule_next_tasks()
+        self._schedule_next_background_check()
+
+    def _process_completed_background_tasks(self, _data: bytes) -> None:
+        """Handle completed background tasks and redraw if the screen changed."""
+        should_redraw = False
+        for completed_task in self.task_runner.pop_all_completed_tasks():
+            should_redraw = (
+                self.background_task_result_handler.handle_completed_task(
+                    completed_task
+                )
+                or should_redraw
+            )
+        self.scheduler.schedule_next_tasks()
+        self._schedule_next_background_check()
+        if should_redraw:
+            self.ui_controller.render_current_state()
+
+    def _schedule_next_background_check(self, delay: Optional[float] = None) -> None:
+        """Set a timer for the next container, tab, or log update."""
+        if self.ui_event_loop is None:
+            return
+        if self._background_check_timer_handle is not None:
+            self.ui_event_loop.remove_alarm(self._background_check_timer_handle)
+        next_delay = (
+            self.scheduler.seconds_until_next_task_check() if delay is None else delay
+        )
+        self._background_check_timer_handle = self.ui_event_loop.set_alarm_in(
+            next_delay,
+            self._schedule_next_background_tasks,
+        )
+
+    def _notify_background_task_ready(self) -> None:
+        """Tell the notifier that a worker result is ready for EDMApp."""
+        self.background_notifier.notify()
+
+
+__all__ = ["EDMApp"]

easy_docker_manager/app/background_notifier.py

@@ -0,0 +1,206 @@
+"""Tell EDMApp when background work is ready to process.
+
+Background threads cannot update the terminal UI directly. On Unix-like
+systems, a pipe wakes the UI as soon as a task finishes. On Windows, a timer
+checks for finished tasks every 0.2 seconds. Both methods run the callback on
+the UI thread, where it is safe to update the screen.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from threading import Lock
+from typing import Any, Optional
+
+import urwid
+
+logger = logging.getLogger(__name__)
+
+BackgroundTaskReadyCallback = Callable[[bytes], None]
+
+
+class BackgroundNotifier(ABC):
+    """Wake EDMApp on the UI thread when worker results are ready."""
+
+    @abstractmethod
+    def start(
+        self,
+        loop: urwid.MainLoop,
+        callback: BackgroundTaskReadyCallback,
+    ) -> None:
+        """Connect the notifier to the event loop that manages the terminal UI.
+
+        Urwid's MainLoop handles keyboard input, timers, and screen updates.
+        This method registers callback so completed work is handled on the same
+        thread as those UI operations.
+        """
+
+    @abstractmethod
+    def notify(self) -> None:
+        """Tell EDMApp that one or more worker results are ready."""
+
+    @abstractmethod
+    def stop(self) -> None:
+        """Stop notifications and release any Urwid resources."""
+
+
+class PipeBackgroundNotifier(BackgroundNotifier):
+    """Notify EDMApp through a pipe on Unix-like operating systems.
+
+    Linux and macOS support Urwid's watch_pipe feature. When background work
+    finishes, notify() writes one byte to the pipe. Urwid detects the byte and
+    immediately runs EDMApp's callback on the UI thread. This implementation
+    does not need a timer because the pipe itself signals that work is ready.
+    """
+
+    def __init__(self) -> None:
+        self._loop: Optional[urwid.MainLoop] = None
+        self._pipe_write: Optional[int] = None
+        self._lock = Lock()
+
+    def start(
+        self,
+        loop: urwid.MainLoop,
+        callback: BackgroundTaskReadyCallback,
+    ) -> None:
+        """Register a pipe that runs callback on the Urwid UI thread."""
+        watch_pipe = getattr(loop, "watch_pipe", None)
+        if not callable(watch_pipe):
+            raise RuntimeError("Urwid watch_pipe is not available on this platform")
+        with self._lock:
+            self._loop = loop
+            self._pipe_write = watch_pipe(callback)
+
+    def notify(self) -> None:
+        """Write one byte to wake the Urwid pipe watcher."""
+        with self._lock:
+            if self._pipe_write is None:
+                return
+            try:
+                os.write(self._pipe_write, b"x")
+            except OSError:
+                logger.debug("Unable to notify the terminal UI event loop")
+
+    def stop(self) -> None:
+        """Remove the pipe watcher and close its write descriptor."""
+        with self._lock:
+            loop = self._loop
+            pipe_write = self._pipe_write
+            self._loop = None
+            self._pipe_write = None
+        if loop is None or pipe_write is None:
+            return
+        try:
+            loop.remove_watch_pipe(pipe_write)
+        except (OSError, ValueError):
+            logger.debug("Unable to remove Urwid pipe watch")
+        try:
+            os.close(pipe_write)
+        except OSError:
+            logger.debug("Unable to close Urwid pipe")
+
+
+class PollingBackgroundNotifier(BackgroundNotifier):
+    """Notify EDMApp through a repeating timer on Windows.
+
+    Urwid's watch_pipe feature is unavailable on Windows. Instead, notify()
+    records that background work is ready. A timer checks that state every 0.2
+    seconds and runs EDMApp's callback on the UI thread when needed.
+    """
+
+    def __init__(self, poll_interval: float = 0.2) -> None:
+        if poll_interval <= 0:
+            raise ValueError("poll_interval must be positive")
+        self.poll_interval = poll_interval
+        self._loop: Optional[urwid.MainLoop] = None
+        self._callback: Optional[BackgroundTaskReadyCallback] = None
+        self._timer_handle: Optional[Any] = None
+        self._notification_pending = False
+        self._lock = Lock()
+
+    def start(
+        self,
+        loop: urwid.MainLoop,
+        callback: BackgroundTaskReadyCallback,
+    ) -> None:
+        """Start a repeating timer that checks for worker notifications."""
+        with self._lock:
+            self._loop = loop
+            self._callback = callback
+            self._notification_pending = False
+        self._schedule_next_notification_check()
+
+    def notify(self) -> None:
+        """Mark worker results as ready for the next timer check."""
+        with self._lock:
+            if self._loop is not None:
+                self._notification_pending = True
+
+    def stop(self) -> None:
+        """Stop the polling timer and clear the callback."""
+        with self._lock:
+            loop = self._loop
+            timer_handle = self._timer_handle
+            self._loop = None
+            self._callback = None
+            self._timer_handle = None
+            self._notification_pending = False
+        if loop is not None and timer_handle is not None:
+            try:
+                loop.remove_alarm(timer_handle)
+            except ValueError:
+                logger.debug("Unable to remove Urwid polling timer")
+
+    # Urwid calls timer callbacks with the event loop and optional user data.
+    # EDM does not use the loop here, but the callback must accept it to match that
+    # callback signature. The leading underscore marks it as intentionally unused.
+    def _check_for_task_notifications(
+        self,
+        _loop: urwid.MainLoop,
+        _data: Any = None,
+    ) -> None:
+        """Run the EDMApp callback when a worker notification is pending."""
+        callback: Optional[BackgroundTaskReadyCallback] = None
+        with self._lock:
+            self._timer_handle = None
+            if self._loop is None:
+                return
+            if self._notification_pending and self._callback is not None:
+                self._notification_pending = False
+                callback = self._callback
+        if callback is not None:
+            callback(b"")
+        self._schedule_next_notification_check()
+
+    def _schedule_next_notification_check(self) -> None:
+        """Schedule the next timer check while the notifier is running."""
+        with self._lock:
+            if self._loop is None:
+                return
+            self._timer_handle = self._loop.set_alarm_in(
+                self.poll_interval,
+                self._check_for_task_notifications,
+            )
+
+
+def create_background_notifier() -> BackgroundNotifier:
+    """Use polling on Windows and a pipe on other platforms."""
+    # os.name is "nt" on Windows, where Urwid's watch_pipe is unavailable.
+    # A short polling timer provides a Windows-compatible alternative.
+    if os.name == "nt":
+        return PollingBackgroundNotifier()
+
+    # Linux and macOS normally report "posix", where a pipe can wake the UI
+    # immediately after background work finishes.
+    return PipeBackgroundNotifier()
+
+
+__all__ = [
+    "BackgroundNotifier",
+    "PipeBackgroundNotifier",
+    "PollingBackgroundNotifier",
+    "create_background_notifier",
+]