tuiloom 0.1.0__py3-none-any.whl

tuiloom/__init__.py

@@ -0,0 +1,34 @@
+"""Build typed terminal applications with menus and dynamic content."""
+
+from tuiloom._message_registry import MessageKey
+from tuiloom.command import (
+    CommandBehavior,
+    CommandContext,
+    GlobalCommand,
+    InputBehavior,
+    MenuCommand,
+)
+from tuiloom.formatting import hyperlink
+from tuiloom.key_binding import KeyBinding, KeyMap
+from tuiloom.render.content_renderer import ContentSource
+from tuiloom.render.terminal_renderer import AutoScrollMode
+from tuiloom.screen_context.screen_context import ScreenContext
+from tuiloom.terminal_app import TerminalApp
+from tuiloom.terminal_menu import TerminalMenu
+
+__all__ = [
+    "AutoScrollMode",
+    "CommandBehavior",
+    "CommandContext",
+    "GlobalCommand",
+    "InputBehavior",
+    "KeyBinding",
+    "KeyMap",
+    "MenuCommand",
+    "hyperlink",
+    "ContentSource",
+    "ScreenContext",
+    "TerminalApp",
+    "TerminalMenu",
+    "MessageKey",
+]

tuiloom/_message_registry.py

@@ -0,0 +1,134 @@
+from collections.abc import Callable
+from enum import StrEnum
+
+type MessageFactory = Callable[..., str]
+type MessageValue = str | MessageFactory
+
+
+class MessageKey(StrEnum):
+    """Identify built-in messages that may be shown or disabled.
+
+    ``NO_CONTENT_SOURCE`` explains that a menu has no content box.
+    ``UNKNOWN_COMMAND`` describes discarded textual command input retained for
+    integrations. ``TASK_EXIT_CHOICES`` presents safe task-closing choices and
+    ``TASK_WAITING`` labels the animated wait state.
+    """
+
+    NO_CONTENT_SOURCE = "no_content_source"
+    UNKNOWN_COMMAND = "unknown_command"
+    TASK_EXIT_CHOICES = "task_exit_choices"
+    TASK_WAITING = "task_waiting"
+
+
+class MessageRegistry:
+    """Store, customize, and selectively disable application messages."""
+
+    def __init__(self) -> None:
+        """Create a registry populated with the built-in messages."""
+        self._built_in_messages: dict[str, MessageValue] = {}
+        self._custom_messages: dict[str, str] = {}
+        self._disabled: set[str] = set()
+
+        self._register_built_in_messages()
+
+    # Keep every built-in message registration in one visible place.
+    def _register_built_in_messages(self) -> None:
+        """Populate the registry with Tuiloom's built-in messages."""
+        self._add_built_in_message(
+            MessageKey.NO_CONTENT_SOURCE,
+            self._no_content_source_message,
+        )
+
+        self._add_built_in_message(
+            MessageKey.UNKNOWN_COMMAND,
+            self._unknown_command,
+        )
+        self._add_built_in_message(
+            MessageKey.TASK_EXIT_CHOICES,
+            "1: Force quit\n2: Wait and quit\n0: Cancel",
+        )
+        self._add_built_in_message(MessageKey.TASK_WAITING, "Task in progress")
+
+    # Register a message owned by the library.
+    def _add_built_in_message(
+        self,
+        key: str,
+        message: MessageValue,
+    ) -> None:
+        """Register one message owned by the library."""
+        self._validate_new_key(key)
+        self._built_in_messages[key] = message
+
+    # Register a custom, user-owned message.
+    def add_message(self, key: str, text: str) -> None:
+        """Register a custom static message under a unique key."""
+        self._validate_new_key(key)
+        self._custom_messages[key] = text
+
+    def disable(self, key: str) -> None:
+        """Disable a registered message globally."""
+        self._validate_existing_key(key)
+        self._disabled.add(key)
+
+    def enable(self, key: str) -> None:
+        """Re-enable a registered message globally."""
+        self._validate_existing_key(key)
+        self._disabled.discard(key)
+
+    def get(self, key: str, **context: object) -> str | None:
+        """Resolve an enabled message using any required context."""
+        if key in self._disabled:
+            return None
+
+        message = self._built_in_messages.get(key)
+
+        if message is None:
+            message = self._custom_messages.get(key)
+
+        if callable(message):
+            return message(**context)
+
+        return message
+
+    def validate_key(self, key: str) -> None:
+        """Raise ``KeyError`` unless ``key`` is registered."""
+        self._validate_existing_key(key)
+
+    def is_enabled(self, key: str) -> bool:
+        """Validate and report global enablement."""
+        self._validate_existing_key(key)
+        return key not in self._disabled
+
+    def _validate_new_key(self, key: str) -> None:
+        """Reject empty or already registered message keys."""
+        if not key:
+            raise ValueError("A message key cannot be empty")
+
+        if key in self._built_in_messages or key in self._custom_messages:
+            raise ValueError(f"A message already exists for key: {key}")
+
+    def _validate_existing_key(self, key: str) -> None:
+        """Reject message keys that are not registered."""
+        if key not in self._built_in_messages and key not in self._custom_messages:
+            raise KeyError(f"Unknown message key: {key}")
+
+    @staticmethod
+    def _no_content_source_message(menu_name: str) -> str:
+        """Build the message shown when a menu has no content source."""
+        return (
+            "No content source has been set for this menu "
+            f"({menu_name})\n"
+            "You can set it by using this method: \n"
+            "  'set_content_source(content_source: ContentSource)'\n"
+            "  ContentSource being: (\n"
+            "    str\n"
+            "    | list[str]\n"
+            "    | Iterator[str]\n"
+            "    | Callable[[], str | list[str]]\n"
+            "  )"
+        )
+
+    @staticmethod
+    def _unknown_command(command: str) -> str:
+        """Build the message shown for an unknown command."""
+        return f"Unknown command '{command}'"

tuiloom/command.py

@@ -0,0 +1,127 @@
+"""Callback aliases, execution contexts, and stable command handles.
+
+``CommandBehavior`` is a callback receiving :class:`CommandContext`.
+``InputBehavior`` receives the submitted Unicode text from free-form input.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from tuiloom.key_binding import KeyBinding
+
+if TYPE_CHECKING:
+    from tuiloom.terminal_app import TerminalApp
+    from tuiloom.terminal_menu import TerminalMenu
+
+
+@dataclass(frozen=True, slots=True)
+class CommandContext:
+    """Describe one callback execution created by Tuiloom.
+
+    Attributes:
+        app: Application dispatching the callback.
+        menu: Menu active when the callback was dispatched.
+        command: Stable menu/global handle, or ``None`` for alert confirmation.
+        binding: Triggering binding, or ``None`` for programmatic execution.
+    """
+
+    app: TerminalApp
+    menu: TerminalMenu
+    command: MenuCommand | GlobalCommand | None
+    binding: KeyBinding | None
+
+
+type CommandBehavior = Callable[[CommandContext], None]
+type InputBehavior = Callable[[str], None]
+
+
+class MenuCommand:
+    """Stable handle for one selectable menu command.
+
+    Attributes:
+        label: Current visible label.
+        behavior: Current callback.
+        position: Zero-based position among user commands.
+        enabled: Whether the command can currently be selected and activated.
+    """
+
+    __slots__ = ("_menu", "_label", "_behavior", "_enabled")
+
+    def __init__(
+        self, menu: TerminalMenu, label: str, behavior: CommandBehavior
+    ) -> None:
+        self._menu = menu
+        self._label = label
+        self._behavior = behavior
+        self._enabled = True
+
+    @property
+    def label(self) -> str:
+        """Return the command's current label."""
+        return self._label
+
+    @property
+    def behavior(self) -> CommandBehavior:
+        """Return the command's current callback."""
+        return self._behavior
+
+    @property
+    def position(self) -> int:
+        """Return the command's current zero-based position."""
+        return self._menu._position_of(self)
+
+    @property
+    def enabled(self) -> bool:
+        """Return whether the command is locally enabled."""
+        return self._enabled
+
+
+class GlobalCommand:
+    """Stable handle and read-only metadata for one invisible global command.
+
+    Attributes:
+        binding: Binding that immediately invokes the command.
+        label: User-defined label suitable for a custom help display.
+        behavior: Application-level callback.
+    """
+
+    __slots__ = ("_app", "_binding", "_label", "_behavior")
+
+    def __init__(
+        self,
+        app: TerminalApp,
+        binding: KeyBinding,
+        label: str,
+        behavior: CommandBehavior,
+    ) -> None:
+        self._app = app
+        self._binding = binding
+        self._label = label
+        self._behavior = behavior
+
+    @property
+    def binding(self) -> KeyBinding:
+        """Return the current triggering binding."""
+        return self._binding
+
+    @property
+    def label(self) -> str:
+        """Return the descriptive label."""
+        return self._label
+
+    @property
+    def behavior(self) -> CommandBehavior:
+        """Return the application-level callback."""
+        return self._behavior
+
+
+def _without_context(action: Callable[[], None]) -> CommandBehavior:
+    """Adapt an internal zero-argument action to a command callback."""
+
+    def wrapped(context: CommandContext) -> None:
+        action()
+
+    return wrapped

tuiloom/event_loop/event_loop.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from queue import Empty, Queue
+from selectors import EVENT_READ, BaseSelector, DefaultSelector
+from shutil import get_terminal_size
+from socket import socketpair
+from time import monotonic
+from typing import TYPE_CHECKING
+
+from tuiloom.event_loop.source_event import SourceEvent
+from tuiloom.event_loop.source_worker import SourceWorker
+from tuiloom.input_handler.input_handler import InputHandler
+from tuiloom.render.content_renderer import ContentRenderer, ContentSource
+from tuiloom.render.menu_renderer import MenuRenderer
+from tuiloom.render.terminal_renderer import TerminalRenderer
+
+if TYPE_CHECKING:
+    from tuiloom.terminal_menu import TerminalMenu
+
+
+class EventLoop:
+    """Coordinate input, content sources, and frame scheduling for one menu."""
+
+    _FRAME_INTERVAL = 1 / 60
+    _STATE_CHECK_INTERVAL = 0.1
+    _SOURCE_QUEUE_SIZE = 256
+
+    def __init__(
+        self,
+        menu: TerminalMenu,
+        input_handler: InputHandler,
+        menu_renderer: MenuRenderer,
+        terminal_renderer: TerminalRenderer,
+        content_renderer: ContentRenderer,
+        *,
+        clock: Callable[[], float] = monotonic,
+        selector_factory: Callable[[], BaseSelector] = DefaultSelector,
+    ) -> None:
+        """Create an event loop over initialized menu renderers."""
+        self._menu = menu
+        self._input_handler = input_handler
+        self._menu_renderer = menu_renderer
+        self._terminal_renderer = terminal_renderer
+        self._content_renderer = content_renderer
+        self._clock = clock
+        self._selector = selector_factory()
+        self._wakeup_reader, self._wakeup_writer = socketpair()
+        self._wakeup_reader.setblocking(False)
+        self._wakeup_writer.setblocking(False)
+        self._selector.register(input_handler.fileno(), EVENT_READ, "input")
+        self._selector.register(self._wakeup_reader, EVENT_READ, "source")
+
+        self._source_events: Queue[SourceEvent] = Queue(maxsize=self._SOURCE_QUEUE_SIZE)
+        self._generation = 0
+        self._source_worker: SourceWorker | None = None
+        self._dirty = True
+        now = self._clock()
+        self._next_frame_at = now
+        self._next_state_check_at = now
+        self._dynamic_in_flight = False
+        self._next_dynamic_at = now
+        self._terminal_size = get_terminal_size()
+        self._closed = False
+
+        self._install_worker(content_renderer)
+
+    def run(self) -> None:
+        """Process events until the owning menu stops."""
+        while self._menu._running:
+            self.run_once()
+
+    def run_once(self) -> None:
+        """Process one selectable event-loop turn."""
+        ready = self._selector.select(self._get_wait_timeout())
+
+        for key, _ in ready:
+            if key.data == "source":
+                self._drain_wakeup()
+                self._drain_source_events()
+
+        self._drain_input()
+        self._request_dynamic_update()
+        completed_menu = self._menu.app._dispatch_output_task_outcome()
+
+        if completed_menu is self._menu:
+            self.request_render(immediate=True)
+
+        self._check_visible_state()
+        self._render_if_due()
+
+    def request_render(self, immediate: bool = False) -> None:
+        """Mark visible state dirty for the next permitted frame."""
+        self._dirty = True
+
+        if immediate:
+            self._next_frame_at = self._clock()
+
+    def install_source(self, source: ContentSource) -> None:
+        """Replace the active source and discard every stale source event."""
+        content_renderer = ContentRenderer(source)
+        self._content_renderer = content_renderer
+        self._menu._content_renderer = content_renderer
+        self._terminal_renderer.set_content_renderer(content_renderer)
+        self._install_worker(content_renderer)
+        self.request_render(immediate=True)
+
+    def close(self) -> None:
+        """Release event-loop resources without waiting on blocked source code."""
+        if self._closed:
+            return
+
+        self._closed = True
+
+        if self._source_worker is not None:
+            self._source_worker.cancel()
+
+        self._selector.close()
+        self._wakeup_reader.close()
+        self._wakeup_writer.close()
+
+    def _install_worker(self, content_renderer: ContentRenderer) -> None:
+        """Cancel the old generation and start the new source when required."""
+        if self._source_worker is not None:
+            self._source_worker.cancel()
+
+        self._generation += 1
+        self._clear_source_events()
+        self._source_worker = None
+        self._dynamic_in_flight = False
+
+        if content_renderer.state == "static":
+            return
+
+        source = content_renderer.source
+
+        if not callable(source) and not hasattr(source, "__next__"):
+            raise RuntimeError("Non-static content source cannot be consumed")
+
+        self._source_worker = SourceWorker(
+            generation=self._generation,
+            source=source,
+            events=self._source_events,
+            notify=self._notify_source,
+        )
+        self._source_worker.start()
+
+    def _clear_source_events(self) -> None:
+        """Discard queued results belonging to a replaced source."""
+        while True:
+            try:
+                self._source_events.get_nowait()
+            except Empty:
+                return
+
+    def _drain_input(self) -> None:
+        """Handle every input event immediately available from the terminal."""
+        while True:
+            event = self._input_handler.poll()
+
+            if event is None:
+                return
+
+            self._menu._handle_event(event)
+            self.request_render()
+
+            if not self._menu._running:
+                return
+
+    def _drain_source_events(self) -> None:
+        """Apply every current generation event as one content update batch."""
+        events: list[SourceEvent] = []
+
+        while True:
+            try:
+                event = self._source_events.get_nowait()
+            except Empty:
+                break
+
+            if event.generation == self._generation:
+                events.append(event)
+
+        if not events:
+            return
+
+        if self._content_renderer.state == "streaming":
+            chunks = [
+                event.value
+                for event in events
+                if event.kind == "data" and isinstance(event.value, str)
+            ]
+
+            if chunks:
+                self._content_renderer.append_stream_batch(chunks)
+                self._terminal_renderer.apply_stream_auto_scroll(self._menu.auto_scroll)
+                self.request_render()
+
+        elif self._content_renderer.state == "dynamic":
+            values = [event.value for event in events if event.kind == "data"]
+
+            if values:
+                value = values[-1]
+
+                if not isinstance(value, (str, list)):
+                    raise RuntimeError("Dynamic worker returned invalid content")
+
+                self._content_renderer.replace_dynamic_content(value)
+                self.request_render()
+
+            self._dynamic_in_flight = False
+
+        for event in events:
+            self._handle_source_event(event)
+
+    def _handle_source_event(self, event: SourceEvent) -> None:
+        """Handle completion and failures after applying source data."""
+        if event.kind == "complete":
+            self._content_renderer.finish_stream()
+            self.request_render()
+            return
+
+        if event.kind == "error":
+            if event.error is None:
+                raise RuntimeError("Source failure event has no exception")
+
+            raise event.error.with_traceback(event.traceback)
+
+    def _request_dynamic_update(self) -> None:
+        """Request one dynamic result when no evaluation is in flight."""
+        if (
+            self._content_renderer.state != "dynamic"
+            or self._source_worker is None
+            or self._dynamic_in_flight
+            or self._clock() < self._next_dynamic_at
+        ):
+            return
+
+        self._dynamic_in_flight = True
+        self._next_dynamic_at = self._clock() + self._FRAME_INTERVAL
+        self._source_worker.request_dynamic_update()
+
+    def _render_if_due(self) -> None:
+        """Render dirty state no faster than the configured frame interval."""
+        now = self._clock()
+
+        if not self._dirty or now < self._next_frame_at:
+            return
+
+        self._menu_renderer.update()
+        self._terminal_renderer.render()
+        self._dirty = False
+        self._next_frame_at = now + self._FRAME_INTERVAL
+
+    def _get_wait_timeout(self) -> float:
+        """Return the delay until the next scheduled loop responsibility."""
+        now = self._clock()
+        deadlines = [self._next_state_check_at]
+
+        if self._dirty:
+            deadlines.append(self._next_frame_at)
+
+        input_timeout = self._input_handler.get_pending_timeout(now)
+
+        if input_timeout is not None:
+            deadlines.append(now + input_timeout)
+
+        if self._content_renderer.state == "dynamic" and not self._dynamic_in_flight:
+            deadlines.append(self._next_dynamic_at)
+
+        return max(0.0, min(deadlines) - now)
+
+    def _check_visible_state(self) -> None:
+        """Detect screen-context and terminal-size changes at a fixed cadence."""
+        now = self._clock()
+
+        if now < self._next_state_check_at:
+            return
+
+        revision = self._menu_renderer.revision
+        self._menu_renderer.update()
+
+        if self._menu_renderer.revision != revision:
+            self.request_render()
+
+        if self._menu._tick_task_exit(now):
+            self.request_render()
+
+        terminal_size = get_terminal_size()
+
+        if terminal_size != self._terminal_size:
+            self._terminal_size = terminal_size
+            self.request_render(immediate=True)
+
+        self._next_state_check_at = now + self._STATE_CHECK_INTERVAL
+
+    def _notify_source(self) -> None:
+        """Wake the selector after publishing a source event."""
+        try:
+            self._wakeup_writer.send(b"\0")
+        except (BlockingIOError, OSError):
+            pass
+
+    def _drain_wakeup(self) -> None:
+        """Discard every coalesced source wakeup byte."""
+        while True:
+            try:
+                if not self._wakeup_reader.recv(256):
+                    return
+            except BlockingIOError:
+                return

tuiloom/event_loop/source_event.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Literal
+
+type SourceEventKind = Literal["data", "complete", "error"]
+
+
+@dataclass(frozen=True, slots=True)
+class SourceEvent:
+    """Carry one generation-tagged result from a content source worker."""
+
+    generation: int
+    kind: SourceEventKind
+    value: str | list[str] | None = None
+    error: BaseException | None = None
+    traceback: TracebackType | None = None