python-interactive-courses 1.0.0__py3-none-any.whl

pyics/app/actions.py

@@ -0,0 +1,179 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+from pyics.util.logging import get_logger
+
+
+class Action(ABC):
+    """A parameterless, kwargs-bound unit of work."""
+
+    def __init__(self, name: str, **kwargs):
+        """
+        Compose an Action object. Note that an Action object should be callable without
+        parameters (refer to how kwargs are used).
+
+        Parameters
+        ----------
+        name: str
+            Name of the Action
+        **kwargs
+            kwargs to encode call parameters to specific values.
+        """
+        self.name = name
+        self.kwargs = kwargs
+
+    def __call__(self):
+        get_logger(__name__).info(f"Triggered {self.name} action.")
+        self.exec(**self.kwargs)
+
+    @staticmethod
+    @abstractmethod
+    def exec(**kwargs) -> None: ...
+
+
+class KeyAction(Action):
+    """An Action bound to a hotkey"""
+
+    def __init__(self, name: str, key: str, ref: Optional[str] = None, **kwargs):
+        """
+        Compose a KeyAction object. Note that an Action object should be callable without
+        parameters (refer to how kwargs are used).
+
+        Parameters
+        ----------
+        name: str
+            Name of the KeyAction
+        key: str
+            Hotkey associated with the action
+        ref: str (optional)
+            Optional key reference, in case the actual key-press is unwieldy.
+        **kwargs
+            kwargs to encode call parameters to specific values.
+        """
+        super().__init__(name, **kwargs)
+        self.key = key
+        self.ref = ref if ref else self.key
+
+    def __call__(self) -> None:
+        self.exec(**self.kwargs)
+
+
+class Quit(KeyAction):
+    """
+    Quit application on ctrl-c press
+    """
+
+    def __init__(self, name: str = "Quit", key: str = "\x03", ref="ctrl-c", **kwargs):
+        """
+        Parameters
+        ----------
+        cli: CLI (kwarg)
+            CLI object
+        pyics: PyICs (kwarg)
+            PyICs object
+        """
+        super().__init__(name, key, ref=ref, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs):
+        cli = kwargs["cli"]
+        pyics = kwargs["pyics"]
+
+        cli.running = False
+        pyics.running = False
+
+
+class Next(KeyAction):
+    """Move to the next task."""
+
+    def __init__(self, name: str = "Next", key: str = "n", **kwargs):
+        super().__init__(name, key, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs) -> None:
+        if (course := kwargs["pyics"].current_course) is not None:
+            course.next()
+
+
+class Previous(KeyAction):
+    """Go back to the previous task."""
+
+    def __init__(self, name: str = "Previous", key: str = "p", **kwargs):
+        super().__init__(name, key, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs) -> None:
+        if (course := kwargs["pyics"].current_course) is not None:
+            course.previous()
+
+
+class Courses(KeyAction):
+    """Leave the current course for the course selector."""
+
+    def __init__(self, name: str = "Courses", key: str = "c", **kwargs):
+        super().__init__(name, key, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs) -> None:
+        kwargs["pyics"].leave_course()
+
+
+class ResetTask(KeyAction):
+    """Reset the current task."""
+
+    def __init__(self, name: str = "Reset Task", key: str = "r", **kwargs):
+        super().__init__(name, key, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs) -> None:
+        """TODO"""
+        ...
+
+
+class ToggleTrace(KeyAction):
+    """Turn tracing the current task's failed tests with snoop on or off."""
+
+    def __init__(self, name: str = "Trace", key: str = "t", **kwargs):
+        super().__init__(name, key, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs) -> None:
+        if (course := kwargs["pyics"].current_course) is not None:
+            course.toggle_tracing()
+
+
+class ScrollUp(KeyAction):
+    """Scroll the main content viewport up."""
+
+    def __init__(
+        self, name: str = "Scroll", key: str = "UP", ref: str = "\u2191/\u2193", **kwargs
+    ):
+        super().__init__(name, key, ref=ref, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs) -> None:
+        kwargs["cli"].scroll(-1)
+
+
+class ScrollDown(KeyAction):
+    """Scroll the main content viewport down."""
+
+    def __init__(
+        self, name: str = "Scroll", key: str = "DOWN", ref: str = "\u2191/\u2193", **kwargs
+    ):
+        super().__init__(name, key, ref=ref, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs) -> None:
+        kwargs["cli"].scroll(1)
+
+
+class Hint(KeyAction):
+    """Reveal the current task's next hint."""
+
+    def __init__(self, name: str = "Hint", key: str = "h", **kwargs):
+        super().__init__(name, key, **kwargs)
+
+    @staticmethod
+    def exec(**kwargs) -> None:
+        kwargs["pyics"].reveal_hint()

pyics/app/cli.py

@@ -0,0 +1,335 @@
+import importlib.metadata
+import sys
+import threading
+import time
+from typing import Any
+
+from pyfiglet import Figlet
+from rich import box
+from rich.align import Align
+from rich.cells import cell_len
+from rich.console import Console, ConsoleDimensions, Group, RenderableType
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.progress import BarColumn, Progress, TextColumn
+from rich.segment import Segment
+from rich.table import Table
+from rich.text import Text, TextType
+
+# the escape codes not used here are re-exported, as they used to be defined here
+from pyics.util.terminal import (  # noqa: F401
+    ALT_SCREEN_ENTER,
+    ALT_SCREEN_LEAVE,
+    HIDE_CURSOR,
+    LINE_CLEAR,
+    LINE_UP,
+    SHOW_CURSOR,
+)
+
+# Private-use codepoint that input widgets (see pyics.app.prompts) embed in the main content
+# to mark where the terminal cursor goes. Stripped before the frame is written.
+CURSOR_MARKER = ""
+
+
+class CLI:
+    def __init__(self) -> None:
+        self.running = False
+        self._thread: threading.Thread | None = None
+        # escape codes are written on Windows, too (see ``pyics.util.terminal``)
+        self.console = Console(legacy_windows=False)
+        self.progress = Progress(
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(
+                bar_width=None,
+                finished_style="blue",
+                pulse_style="blue",
+                complete_style="blue",
+            ),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+            expand=True,
+        )
+        self.task_id = self.progress.add_task("Progress", total=1)
+        self.hotkeys = {}
+
+        # main-content viewport scroll state, in lines
+        self.scroll_offset = 0
+        self._max_scroll_offset = 0
+        # scroll a CURSOR_MARKER into view on the next draw; only set when the content
+        # changes, so manual scrolling isn't undone by the next redraw
+        self._follow_cursor = False
+
+        # whether the terminal cursor is shown at a CURSOR_MARKER in the main content
+        self.cursor_visible = True
+
+        # the terminal size the last frame was drawn for, to redraw it once that changes
+        self._drawn_size: ConsoleDimensions | None = None
+
+        self.update_info("Ready")
+        self.update_main_content(
+            Text("Main program outputs will appear here...", style="dim"), "Main Output"
+        )
+        self.update_progress(0.0)
+
+    def __call__(self, *args: Any, **kwds: Any) -> Any:
+        """
+        Start up the cli Daemon.
+        """
+        self.running = True
+        self._thread = threading.Thread(target=self.run, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """
+        Stop the cli Daemon, waiting for a frame that is being drawn, so that nothing is
+        drawn once this returns (e.g. after leaving the alternate screen).
+        """
+        self.running = False
+        if self._thread is not None and self._thread is not threading.current_thread():
+            self._thread.join(timeout=1)
+
+    def generate_header(self) -> Panel:
+        """
+        Construct the header from the info-text attribute.
+        """
+        figlet_text = Figlet(font="big").renderText("PyICs").strip("\n")
+
+        table = Table(
+            expand=True, box=box.MINIMAL, show_header=False, style="blue", padding=(0, 2)
+        )
+        table.add_column(
+            vertical="middle",
+            min_width=(len_figlet := len(figlet_text.split("\n")[0])),
+            max_width=len_figlet,
+        )
+        table.add_column(vertical="middle", ratio=1)
+        table.add_row(
+            Text(figlet_text, style="blue", no_wrap=True),
+            Text.from_markup(self.info_text, style="white", emoji=False),
+        )
+
+        return Panel(
+            table,
+            title=f"[blue]PyICs[white] {importlib.metadata.version('pyics')}",
+            title_align="left",
+            border_style="blue",
+            box=box.ROUNDED,
+            padding=(0, 0),
+        )
+
+    def generate_footer(self) -> Panel:
+        """
+        Construct the footer from the hotkey and progress bar attributes.
+        """
+        # wrapped between hotkeys only, so a hotkey isn't separated from its action
+        width = self.console.width - 4  # the panel's borders and padding
+        lines: list[Text] = []
+        for key, action in self.hotkeys.items():
+            hotkey = Text.assemble((f"<{key}>", "bold cyan"), f" {action}")
+            if lines and lines[-1].cell_len + 3 + hotkey.cell_len <= width:
+                lines[-1].append(" | ", style="dim")
+                lines[-1].append_text(hotkey)
+            else:
+                lines.append(hotkey)
+        hotkeys_text = Text("\n", justify="center").join(lines)
+
+        self.progress.update(self.task_id, completed=self.percentage)
+
+        group = Group(self.progress, Align.center(hotkeys_text))
+
+        return Panel(group, border_style="blue", box=box.ROUNDED)
+
+    def update_main_content(self, renderable: RenderableType, title: TextType = ""):
+        """
+        Update the content of the main panel.
+
+        Parameters
+        ----------
+        renderable: RenderableType
+            New content to put inside the main panel.
+        title: TextType (optional)
+            Set a frame title for the main content. If a title other than "" (default)
+            is provided, adds top padding to renderable.
+        """
+        self.main_content = Padding(renderable, (0 if title == "" else 1, 0, 0, 0))
+        self.main_title = title
+        self._follow_cursor = True
+        self._needs_redraw = True
+
+    def add_to_main_content(self, renderable: RenderableType) -> None:
+        """
+        _Add_ renderable below current main content.
+
+        **Important:** anything added to the main content this way will be overwritten
+        the next time a `ùpdate_main_content`` method call occurs.
+
+        Parameters
+        ----------
+        renderable: RenderableType
+            New content to _add_ to the main content.
+        """
+        self.main_content = Group(self.main_content, Padding(renderable, (1, 0, 0, 0)))
+        self._needs_redraw = True
+
+    def update_progress(self, percentage: float):
+        """
+        Update the progress displayed in the progress bar in the footer.
+
+        Parameters
+        ----------
+        percentage: float
+            New progress percentage (as a fraction!)
+        """
+        self.percentage = percentage
+        self._needs_redraw = True
+
+    def update_hotkeys(self, hotkeys: dict):
+        """
+        Update the hotkeys displayed in the footer. This intentionally _replaces_ the dict,
+        because that way it is easy for the controller to both remove and add or update
+        components.
+
+        Parameters
+        ----------
+        hotkeys: dict
+            Hotkey dict.
+        """
+        self.hotkeys = hotkeys
+        self._needs_redraw = True
+
+    def update_info(self, text: str):
+        """
+        Update the info_text. The info text is shown in the right part of the header panel.
+
+        Parameters
+        ----------
+        text: str
+            The new info-text to draw. Supports ``rich`` markup, so plain text that may
+            contain square brackets must be escaped (``rich.markup.escape``).
+        """
+        self.info_text = text
+        self._needs_redraw = True
+
+    def scroll(self, delta: int) -> None:
+        """
+        Move the main-content viewport by ``delta`` lines, clamped to the scrollable range.
+
+        Parameters
+        ----------
+        delta: int
+            Number of lines to scroll by. Positive scrolls down, negative scrolls up.
+        """
+        self.scroll_offset = max(
+            0, min(self.scroll_offset + delta, self._max_scroll_offset)
+        )
+        self._needs_redraw = True
+
+    def _render_lines(self, renderable: RenderableType) -> list[list[Segment]]:
+        """Render a renderable to its lines, uncropped by the console's current height."""
+        options = self.console.options.update(height=None)
+        return self.console.render_lines(renderable, options, pad=False)
+
+    def _locate_and_strip_cursor(
+        self, lines: list[list[Segment]]
+    ) -> tuple[int, int] | None:
+        """Strip CURSOR_MARKER from the rendered ``lines`` (in place) and return its
+        0-indexed ``(row, col)``, or ``None`` if absent."""
+        for row, line in enumerate(lines):
+            for i, seg in enumerate(line):
+                idx = seg.text.find(CURSOR_MARKER)
+                if idx == -1:
+                    continue
+                col = cell_len("".join(s.text for s in line[:i])) + cell_len(seg.text[:idx])
+                line[i] = seg._replace(text=seg.text[:idx] + seg.text[idx + 1 :])
+                return row, col
+        return None
+
+    def _lines_to_text(self, lines: list[list[Segment]]) -> str:
+        """Join rendered lines back into a single ANSI-encoded string."""
+        segments: list[Segment] = []
+        for i, line in enumerate(lines):
+            if i:
+                segments.append(Segment.line())
+            segments.extend(line)
+        return self.console._render_buffer(segments)
+
+    def draw_interface(self):
+        """
+        Draw the PyICs interface. Header and footer are pinned to the top/bottom of the
+        terminal; only the main content scrolls, windowed to the space left between them.
+        """
+        # cleared before anything is read, so changes made while this frame is drawn
+        # (e.g. from other threads) are drawn by the next one
+        self._needs_redraw = False
+        follow_cursor, self._follow_cursor = self._follow_cursor, False
+        # likewise, a frame drawn while the terminal is resized is drawn again
+        self._drawn_size = self.console.size
+        header_panel = self.generate_header()
+        footer_panel = self.generate_footer()
+
+        main_panel = Panel(
+            self.main_content,
+            title=self.main_title,  # should display task-id/task-number later
+            title_align="left",
+            box=box.SIMPLE,
+        )
+
+        term_height = self._drawn_size.height
+
+        header_lines = self._render_lines(header_panel)
+        footer_lines = self._render_lines(footer_panel)
+        viewport_height = max(0, term_height - len(header_lines) - len(footer_lines))
+
+        main_lines = self._render_lines(main_panel)
+        cursor_pos = self._locate_and_strip_cursor(main_lines)
+
+        self._max_scroll_offset = max(0, len(main_lines) - viewport_height)
+        if cursor_pos is not None and follow_cursor:
+            row, _ = cursor_pos
+            if row < self.scroll_offset:
+                # scroll all the way up if that shows the cursor, to keep the title visible
+                self.scroll_offset = 0 if row < viewport_height else row
+            elif row >= self.scroll_offset + viewport_height:
+                self.scroll_offset = row - viewport_height + 1
+        self.scroll_offset = max(0, min(self.scroll_offset, self._max_scroll_offset))
+        visible_main_lines = main_lines[
+            self.scroll_offset : self.scroll_offset + viewport_height
+        ]
+
+        sys.stdout.write("\033[H\033[2J")
+        sys.stdout.write(self._lines_to_text(header_lines))
+        sys.stdout.write("\n")
+        sys.stdout.write(self._lines_to_text(visible_main_lines))
+        sys.stdout.write(f"\033[{term_height - len(footer_lines) + 1};1H")
+        sys.stdout.write(self._lines_to_text(footer_lines))
+
+        if cursor_pos is not None and (
+            self.scroll_offset <= cursor_pos[0] < self.scroll_offset + viewport_height
+        ):
+            row, col = cursor_pos
+            abs_row = len(header_lines) + 1 + (row - self.scroll_offset)
+            sys.stdout.write(f"\033[{abs_row};{1 + col}H")
+            sys.stdout.write(SHOW_CURSOR if self.cursor_visible else HIDE_CURSOR)
+        else:
+            sys.stdout.write(HIDE_CURSOR)
+
+        sys.stdout.flush()
+
+    def run(self):
+        """
+        Main CLI loop. While running, checks if a redraw is necessary (either updated
+        content or window-resize), and redraws the interface when necessary.
+        """
+        sys.stdout.write(HIDE_CURSOR)
+        sys.stdout.flush()
+
+        try:
+            while self.running:
+                # the size is polled, as only Unix signals a resize
+                if self._needs_redraw or self.console.size != self._drawn_size:
+                    self.draw_interface()
+
+                time.sleep(0.05)
+
+        finally:
+            sys.stdout.write(SHOW_CURSOR)
+            sys.stdout.flush()

pyics/app/key_listener.py

@@ -0,0 +1,133 @@
+import queue
+import sys
+import threading
+import time
+from collections.abc import Callable
+from contextlib import ExitStack
+
+from prompt_toolkit.input import Input, create_input
+from prompt_toolkit.key_binding import KeyPress
+from prompt_toolkit.keys import Keys
+
+# Tokens of keys that don't type a character. Terminals also send the arrow keys (or the
+# scroll keys) for mouse-wheel scrolling while in the alt-screen buffer (xterm "alternate
+# scroll mode"), so this doubles as mouse-wheel support.
+_KEY_TOKENS: dict[str, str] = {
+    Keys.Up: "UP",
+    Keys.Down: "DOWN",
+    Keys.Left: "LEFT",
+    Keys.Right: "RIGHT",
+    Keys.ScrollUp: "UP",
+    Keys.ScrollDown: "DOWN",
+    Keys.Escape: "\x1b",
+}
+
+
+def _terminal_input() -> Input:
+    """The input of the terminal that stdin is, for the platform (see
+    ``prompt_toolkit.input``). Raises if stdin isn't a terminal."""
+    if sys.stdin is None or not sys.stdin.isatty():
+        raise OSError("stdin is not a terminal")
+    return create_input()
+
+
+def _tokens(key_press: KeyPress) -> list[str]:
+    """
+    The tokens ``key_press`` is queued as: one of ``_KEY_TOKENS``, or else the text the
+    terminal sent for it, e.g. ``"a"``, or the control character of enter or ctrl-c.
+    Other keys that don't type a character (e.g. delete) are sent as escape sequences,
+    which are queued as single tokens of several characters.
+    """
+    if key_press.key == Keys.BracketedPaste:
+        # e.g. pasted text, as Windows detects it: typed character by character
+        return list(key_press.data)
+    token = _KEY_TOKENS.get(key_press.key, key_press.data)
+    return [token] if token else []
+
+
+class KeyListener(queue.Queue):
+    """
+    Queues the keys pressed while in this context as tokens (see ``_tokens``). The
+    terminal is in raw mode in the meantime: keys aren't echoed, and ctrl-c is a key
+    rather than a signal.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._raw_mode_ready = threading.Event()
+        self._stop_event = threading.Event()
+        # why keys can't be read, raised by __enter__
+        self._error: Exception | None = None
+        self.thread: threading.Thread | None = None
+
+    def _key_listener(self) -> None:
+        """
+        KeyListener main functionality.
+        """
+        with ExitStack() as stack:
+            try:
+                keyboard = _terminal_input()
+                stack.enter_context(keyboard.raw_mode())
+            except Exception as err:  # noqa: BLE001 - raised by __enter__
+                self._error = err
+                return
+            finally:
+                # Unblock __enter__ only once raw mode is actually in effect (or setup
+                # failed), so nothing else can race the terminal into a stale mode.
+                self._raw_mode_ready.set()
+
+            while not self._stop_event.is_set():
+                key_presses = keyboard.read_keys()
+                if not key_presses:
+                    time.sleep(0.01)
+                    # a lone esc can't be told from the start of an escape sequence
+                    # (e.g. an arrow key) until nothing follows it
+                    key_presses = keyboard.read_keys() or keyboard.flush_keys()
+                for key_press in key_presses:
+                    for token in _tokens(key_press):
+                        self.put(token)
+
+    def stop(self) -> None:
+        """
+        Signal the reader thread to stop and block until it has actually exited (and cooked
+        terminal mode has been restored), so callers can rely on that being true the instant
+        this returns.
+        """
+        self._stop_event.set()
+        if self.thread is not None:
+            self.thread.join(timeout=1.0)
+
+    def __enter__(self):
+        self.thread = threading.Thread(target=self._key_listener, daemon=True)
+        self.thread.start()
+        self._raw_mode_ready.wait()
+        if self._error is not None:
+            raise self._error
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.stop()
+
+    @staticmethod
+    def hey_listen(q_param: str) -> Callable:
+        """
+        KeyListener nested decorator. I.e., this static method decorates the decorator
+        (so that we can use the ``q_param`` parameter)
+
+        Parameters
+        ----------
+        q_param: str
+            The parameter name, under which the queue is passed to the decorated function.
+        """
+
+        def dec(func: Callable) -> Callable:
+            def mod(*args, **kwargs):
+                with KeyListener() as q:
+                    func(*args, **kwargs, **{q_param: q})
+
+            return mod
+
+        return dec
+
+
+hey_listen = KeyListener.hey_listen