zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/__init__.py

@@ -0,0 +1,422 @@
+"""ZettCode's internally implemented terminal UI framework."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+#: Where each public name lives; read by :func:`__getattr__` on first use.
+_EXPORTS = {
+    "ARROW_DOWN": ".glyphs",
+    "ARROW_UP": ".glyphs",
+    "Anchor": ".layout",
+    "AnyEvent": ".core",
+    "AsyncInput": ".input",
+    "BAR_EMPTY": ".glyphs",
+    "BAR_FULL": ".glyphs",
+    "Binding": ".core",
+    "Border": ".layout",
+    "AnsiBuffer": ".render",
+    "Canvas": ".render",
+    "Collapsible": ".widgets",
+    "ColorDepth": ".render",
+    "Column": ".widgets",
+    "Command": ".core",
+    "CommandRegistry": ".core",
+    "Completer": ".widgets",
+    "CompletionItem": ".widgets",
+    "CompletionPopup": ".widgets",
+    "ConsolePanel": ".widgets",
+    "Constraints": ".core",
+    "DARK": ".core",
+    "DONE": ".glyphs",
+    "Dialog": ".widgets",
+    "DialogAction": ".widgets",
+    "DiffLine": ".widgets",
+    "DiffSegment": ".widgets",
+    "DiffView": ".widgets",
+    "DifferentialRenderer": ".render",
+    "ELLIPSIS": ".glyphs",
+    "EXAMPLE": ".theme_file",
+    "EXPANDED": ".glyphs",
+    "EdgeInsets": ".core",
+    "Event": ".core",
+    "EventKind": ".core",
+    "EventType": ".input",
+    "FAILED": ".glyphs",
+    "FocusEvent": ".core",
+    "FocusManager": ".core",
+    "HBox": ".layout",
+    "HEADER": ".glyphs",
+    "Host": ".core",
+    "InputDecoder": ".input",
+    "InputEvent": ".input",
+    "KeyEvent": ".core",
+    "Keymap": ".core",
+    "LIGHT": ".core",
+    "LineSource": ".layout",
+    "ListItem": ".widgets",
+    "ListPage": ".widgets",
+    "ListView": ".widgets",
+    "MARKER": ".glyphs",
+    "Markdown": ".widgets",
+    "MarkdownSource": ".widgets",
+    "MarkdownView": ".widgets",
+    "MouseAction": ".core",
+    "MouseEvent": ".core",
+    "Overlay": ".layout",
+    "OverlaySlot": ".layout",
+    "PENDING": ".glyphs",
+    "PROMPT": ".glyphs",
+    "Padding": ".layout",
+    "PasteEvent": ".core",
+    "Point": ".core",
+    "ProgressBar": ".widgets",
+    "RULE": ".glyphs",
+    "RUNNING": ".glyphs",
+    "Rect": ".core",
+    "ResizeEvent": ".core",
+    "RichText": ".widgets",
+    "Rule": ".widgets",
+    "SEPARATOR": ".glyphs",
+    "OPTION": ".capabilities",
+    "SKIPPED": ".glyphs",
+    "SPINNER": ".glyphs",
+    "STATUS": ".glyphs",
+    "STEERING": ".glyphs",
+    "Scheduler": ".core",
+    "Screen": ".core",
+    "ScreenStack": ".core",
+    "ScrollView": ".layout",
+    "Size": ".core",
+    "Slot": ".layout",
+    "Span": ".render",
+    "Spinner": ".widgets",
+    "StaticLines": ".layout",
+    "StatusBar": ".widgets",
+    "Style": ".render",
+    "Table": ".widgets",
+    "TaskPanel": ".widgets",
+    "Terminal": ".terminal",
+    "TerminalCapabilities": ".capabilities",
+    "TerminalRunner": ".runner",
+    "Text": ".widgets",
+    "TextArea": ".widgets",
+    "TextEvent": ".core",
+    "TextLine": ".render",
+    "Theme": ".core",
+    "ThemeFileError": ".theme_file",
+    "Toast": ".widgets",
+    "ToolTheme": ".core",
+    "Track": ".layout",
+    "TuiApp": ".core",
+    "VBox": ".layout",
+    "Widget": ".core",
+    "build_unified": ".widgets",
+    "centered": ".layout",
+    "detect_capabilities": ".capabilities",
+    "detect_reduced_motion": ".capabilities",
+    "bundled_themes": ".theme_file",
+    "file_theme": ".theme_file",
+    "ThemeCatalog": ".theme_file",
+    "ThemeSource": ".theme_file",
+    "RESERVED_THEMES": ".theme_file",
+    "THEME_NAME": ".theme_file",
+    "event_key": ".core",
+    "key_id": ".core",
+    "load_theme": ".theme_file",
+    "normalize_key": ".core",
+    "parse_background": ".terminal",
+    "parse_unified": ".widgets",
+    "resolve_tracks": ".layout",
+    "run_app": ".runner",
+    "scheme_named": ".core",
+    "theme_from_toml": ".theme_file",
+    "theme_named": ".core",
+    "theme_names": ".core",
+    "title_sequence": ".terminal",
+    "walk": ".core",
+    "word_diff": ".widgets",
+}
+
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
+    from .capabilities import OPTION, TerminalCapabilities, detect_capabilities, detect_reduced_motion
+    from .core import (
+        DARK,
+        LIGHT,
+        AnyEvent,
+        Binding,
+        Command,
+        CommandRegistry,
+        Constraints,
+        EdgeInsets,
+        Event,
+        EventKind,
+        FocusEvent,
+        FocusManager,
+        Host,
+        KeyEvent,
+        Keymap,
+        MouseAction,
+        MouseEvent,
+        PasteEvent,
+        Point,
+        Rect,
+        ResizeEvent,
+        Scheduler,
+        Screen,
+        ScreenStack,
+        Size,
+        TextEvent,
+        Theme,
+        ToolTheme,
+        TuiApp,
+        Widget,
+        event_key,
+        key_id,
+        normalize_key,
+        scheme_named,
+        theme_named,
+        theme_names,
+        walk,
+    )
+    from .glyphs import (
+        ARROW_DOWN,
+        ARROW_UP,
+        BAR_EMPTY,
+        BAR_FULL,
+        DONE,
+        ELLIPSIS,
+        EXPANDED,
+        FAILED,
+        HEADER,
+        MARKER,
+        PENDING,
+        PROMPT,
+        RULE,
+        RUNNING,
+        SEPARATOR,
+        SKIPPED,
+        SPINNER,
+        STATUS,
+        STEERING,
+    )
+    from .input import AsyncInput, EventType, InputDecoder, InputEvent
+    from .layout import (
+        Anchor,
+        Border,
+        HBox,
+        LineSource,
+        Overlay,
+        OverlaySlot,
+        Padding,
+        ScrollView,
+        Slot,
+        StaticLines,
+        Track,
+        VBox,
+        centered,
+        resolve_tracks,
+    )
+    from .render import AnsiBuffer, Canvas, ColorDepth, DifferentialRenderer, Span, Style, TextLine
+    from .runner import TerminalRunner, run_app
+    from .terminal import Terminal, parse_background, title_sequence
+    from .theme_file import (
+        EXAMPLE,
+        RESERVED_THEMES,
+        THEME_NAME,
+        ThemeCatalog,
+        ThemeFileError,
+        ThemeSource,
+        bundled_themes,
+        file_theme,
+        load_theme,
+        theme_from_toml,
+    )
+    from .widgets import (
+        Collapsible,
+        Column,
+        Completer,
+        CompletionItem,
+        CompletionPopup,
+        ConsolePanel,
+        Dialog,
+        DialogAction,
+        DiffLine,
+        DiffSegment,
+        DiffView,
+        ListItem,
+        ListPage,
+        ListView,
+        Markdown,
+        MarkdownSource,
+        MarkdownView,
+        ProgressBar,
+        RichText,
+        Rule,
+        Spinner,
+        StatusBar,
+        Table,
+        TaskPanel,
+        Text,
+        TextArea,
+        Toast,
+        build_unified,
+        parse_unified,
+        word_diff,
+    )
+
+
+def __getattr__(name: str) -> object:
+    """Import the module a public name lives in, the first time it is asked for.
+
+    This package is a facade over several subpackages, and a caller that wants
+    one name should not pay for the rest of them — the TUI alone holds the
+    widget library, the Markdown parser, the diff viewer, and the syntax
+    scanners. ``__all__`` is still the public surface.
+    """
+    try:
+        module = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    return getattr(importlib.import_module(module, __name__), name)
+
+
+def __dir__() -> list[str]:
+    """Return the names this package publishes."""
+    return sorted(__all__)
+
+
+__all__ = [
+    "AnyEvent",
+    "ARROW_DOWN",
+    "ARROW_UP",
+    "BAR_EMPTY",
+    "BAR_FULL",
+    "DONE",
+    "ELLIPSIS",
+    "EXPANDED",
+    "FAILED",
+    "HEADER",
+    "MARKER",
+    "OPTION",
+    "PENDING",
+    "PROMPT",
+    "RULE",
+    "RUNNING",
+    "SEPARATOR",
+    "SKIPPED",
+    "SPINNER",
+    "STATUS",
+    "STEERING",
+    "Anchor",
+    "AsyncInput",
+    "TuiApp",
+    "Binding",
+    "Border",
+    "AnsiBuffer",
+    "Canvas",
+    "Collapsible",
+    "ColorDepth",
+    "Column",
+    "Command",
+    "CommandRegistry",
+    "Completer",
+    "CompletionItem",
+    "CompletionPopup",
+    "ConsolePanel",
+    "Constraints",
+    "DARK",
+    "DifferentialRenderer",
+    "Dialog",
+    "DialogAction",
+    "DiffLine",
+    "DiffSegment",
+    "DiffView",
+    "EdgeInsets",
+    "Event",
+    "EventKind",
+    "EventType",
+    "FocusEvent",
+    "FocusManager",
+    "HBox",
+    "Host",
+    "InputDecoder",
+    "InputEvent",
+    "KeyEvent",
+    "Keymap",
+    "LIGHT",
+    "LineSource",
+    "ListItem",
+    "ListPage",
+    "ListView",
+    "Markdown",
+    "MarkdownSource",
+    "MarkdownView",
+    "MouseAction",
+    "MouseEvent",
+    "Overlay",
+    "OverlaySlot",
+    "Padding",
+    "PasteEvent",
+    "Point",
+    "ProgressBar",
+    "RichText",
+    "Rect",
+    "ResizeEvent",
+    "Rule",
+    "Scheduler",
+    "Screen",
+    "ScreenStack",
+    "ScrollView",
+    "Size",
+    "Slot",
+    "Span",
+    "Spinner",
+    "StaticLines",
+    "StatusBar",
+    "Style",
+    "Table",
+    "TaskPanel",
+    "Terminal",
+    "TerminalRunner",
+    "TerminalCapabilities",
+    "Text",
+    "TextArea",
+    "TextEvent",
+    "TextLine",
+    "Theme",
+    "ThemeFileError",
+    "Toast",
+    "Track",
+    "VBox",
+    "Widget",
+    "build_unified",
+    "EXAMPLE",
+    "detect_capabilities",
+    "bundled_themes",
+    "file_theme",
+    "RESERVED_THEMES",
+    "THEME_NAME",
+    "ThemeCatalog",
+    "ThemeSource",
+    "detect_reduced_motion",
+    "centered",
+    "event_key",
+    "key_id",
+    "load_theme",
+    "normalize_key",
+    "parse_unified",
+    "resolve_tracks",
+    "run_app",
+    "theme_named",
+    "title_sequence",
+    "scheme_named",
+    "parse_background",
+    "ToolTheme",
+    "theme_names",
+    "theme_from_toml",
+    "walk",
+    "word_diff",
+]

zettcode/tui/_compat.py

@@ -0,0 +1,32 @@
+"""The two version shims the framework needs, so `zettcode-tui` depends on nothing of ours.
+
+The release notes of the framework say what it is: a widget toolkit that knows nothing of the agent. It needs the
+string-valued enum (the standard library's is 3.11's, and its spelling is what the rows and the theme files rely on) and
+a TOML reader for a theme file. Both are ten lines here rather than an import of another distribution, which would put
+`zett-agent` behind a widget.
+"""
+
+from __future__ import annotations
+
+import sys
+from enum import Enum
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - the branch only the 3.10 runtime takes
+    import tomli as tomllib
+
+__all__ = ["StrEnum", "tomllib"]
+
+
+class StrEnum(str, Enum):
+    """A string-valued enum, for the versions before ``enum.StrEnum``.
+
+    The standard library's version formats as its value, so ``f"{member}"`` is ``"ready"`` rather than
+    ``"Activity.READY"``; the rows and the theme files rely on that, so every interpreter uses this class instead of the
+    standard one and the wording cannot drift with the version.
+    """
+
+    def __str__(self) -> str:
+        """Return the member's value, as ``enum.StrEnum`` does."""
+        return str(self.value)

zettcode/tui/capabilities.py

@@ -0,0 +1,107 @@
+"""Terminal capability detection used to pick conservative rendering options."""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .render.color import ColorDepth
+
+#: What the modifier that sends ``alt``-prefixed keys is called on this machine: the Option key on a Mac, Alt
+#: elsewhere. The same physical key sends the same bytes; only its name differs, and a hint that says "alt" to
+#: someone looking at a key marked "option" is a hint they have to translate.
+OPTION = "option" if sys.platform == "darwin" else "alt"
+
+_TRUECOLOR_COLORTERM = {"truecolor", "24bit"}
+_MOTION_VARIABLES = ("ZETTCODE_REDUCED_MOTION", "NO_MOTION", "REDUCED_MOTION")
+
+
+@dataclass(frozen=True, slots=True)
+class TerminalCapabilities:
+    """What the attached terminal can be trusted to render.
+
+    Attributes:
+        color_depth: Safest depth the environment advertises.
+        unicode: The locale looks like it can encode UTF-8. Advisory for now: no
+            widget switches to an ASCII glyph set when it is False.
+        mouse: The terminal accepts mouse reporting. Advisory, like ``unicode``.
+        bracketed_paste: The terminal wraps pastes in ``ESC[200~`` guards.
+            Advisory as well; the decoder accepts them either way.
+        width: Initial width guess in cells, replaced on the first resize.
+        height: Initial height guess in cells.
+    """
+
+    color_depth: ColorDepth = ColorDepth.ANSI16
+    unicode: bool = True
+    mouse: bool = True
+    bracketed_paste: bool = True
+    width: int = 80
+    height: int = 24
+
+    @property
+    def truecolor(self) -> bool:
+        """Return whether the terminal can be trusted with 24-bit colour."""
+        return self.color_depth is ColorDepth.TRUECOLOR
+
+
+def detect_capabilities(environ: Mapping[str, str] | None = None) -> TerminalCapabilities:
+    """Derive capabilities from environment variables.
+
+    Everything here is a heuristic, so each default errs toward the option that
+    still looks correct on a weaker terminal.
+
+    Args:
+        environ: Environment to read; defaults to ``os.environ`` and is
+            injectable so tests can describe a terminal without owning one.
+    """
+    env = os.environ if environ is None else environ
+    return TerminalCapabilities(
+        color_depth=detect_color_depth(env),
+        unicode=detect_unicode(env),
+    )
+
+
+def detect_color_depth(environ: Mapping[str, str] | None = None) -> ColorDepth:
+    """Return the safest color depth the environment advertises.
+
+    Args:
+        environ: Environment to read; defaults to ``os.environ``.
+    """
+    env = os.environ if environ is None else environ
+    term = env.get("TERM", "")
+    if env.get("NO_COLOR") or term == "dumb":
+        return ColorDepth.MONO
+    colorterm = env.get("COLORTERM", "").lower()
+    if colorterm in _TRUECOLOR_COLORTERM or "truecolor" in term or "direct" in term:
+        return ColorDepth.TRUECOLOR
+    if "256" in term or colorterm:
+        return ColorDepth.ANSI256
+    return ColorDepth.ANSI16
+
+
+def detect_unicode(environ: Mapping[str, str] | None = None) -> bool:
+    """Return whether the environment looks like it can encode UTF-8.
+
+    Args:
+        environ: Environment to read; defaults to ``os.environ``. An unset
+            locale is treated as UTF-8 capable, because that is the common case
+            on modern systems.
+    """
+    env = os.environ if environ is None else environ
+    locale = env.get("LC_ALL") or env.get("LC_CTYPE") or env.get("LANG", "")
+    if locale:
+        return "utf" in locale.lower()
+    return True
+
+
+def detect_reduced_motion(environ: Mapping[str, str] | None = None) -> bool:
+    """Return whether decorative animation should be suppressed.
+
+    Args:
+        environ: Environment to read; defaults to ``os.environ``. Any of
+            ``_MOTION_VARIABLES`` being set to a non-empty value wins.
+    """
+    env = os.environ if environ is None else environ
+    return any(env.get(name) for name in _MOTION_VARIABLES)

zettcode/tui/clipboard.py

@@ -0,0 +1,91 @@
+"""Where a copy goes: the machine's own clipboard, or the terminal's.
+
+A program writes to *a* clipboard, and which one the reader means depends on where the
+program is running. On the reader's own machine the two are the same thing. Over ``ssh`` they
+are not: the program runs on the server, the reader sits at a terminal on another machine, and
+the clipboard they will paste from is that machine's. A system clipboard tool on the server
+reaches the server's clipboard — if it reaches anything at all — and the reader finds nothing
+when they paste.
+
+The only way across the connection is the terminal itself. OSC 52 (``ESC ] 52 ; c ; <base64>
+BEL``) asks the terminal to put text on *its* clipboard, and it travels over the same byte
+stream as everything else the program prints, so it arrives wherever the reader is. That is
+why it is the route over ``ssh`` and only a fallback on a local machine: where a system tool
+works, using it never needs the terminal's permission — several terminals ask the reader, or
+refuse by default, before letting a program write their clipboard.
+
+This module only decides and encodes. Writing is :func:`zettcode.tui.runner.clipboard_writer`'s
+job, and the shell reads :func:`copy_route` to say truthfully where the text went.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+from collections.abc import Mapping
+from typing import Literal
+
+#: Environment variable that overrides the choice: ``system``, ``terminal``, or ``auto``.
+#: Detection reads the environment, and the environment can be wrong — ``sudo`` and some
+#: multiplexers drop the variables, and a forwarded X display makes the server's clipboard
+#: the right one — so the reader can say.
+CLIPBOARD_ENV = "ZETTCODE_CLIPBOARD"
+
+#: Variables the SSH server sets for the session it starts; any one of them means the program
+#: is running on the far side of a connection.
+SSH_VARIABLES = ("SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY")
+
+CopyRoute = Literal["system", "terminal"]
+
+
+def is_remote(environ: Mapping[str, str] | None = None) -> bool:
+    """Return whether this process was started through an SSH session.
+
+    Args:
+        environ: Environment to read; defaults to ``os.environ``.
+    """
+    env = os.environ if environ is None else environ
+    return any(env.get(name) for name in SSH_VARIABLES)
+
+
+def copy_route(environ: Mapping[str, str] | None = None) -> CopyRoute:
+    """Return which clipboard a copy should reach.
+
+    ``terminal`` over ``ssh``, ``system`` otherwise, unless :data:`CLIPBOARD_ENV` says
+    which. A value that is neither ``system`` nor ``terminal`` — ``auto``, or a typo — leaves
+    the detection in charge, because a mistyped override that silently disabled copying would
+    be worse than one that is ignored.
+
+    Args:
+        environ: Environment to read; defaults to ``os.environ``.
+    """
+    env = os.environ if environ is None else environ
+    override = env.get(CLIPBOARD_ENV, "").strip().lower()
+    if override == "system":
+        return "system"
+    if override == "terminal":
+        return "terminal"
+    return "terminal" if is_remote(env) else "system"
+
+
+def osc52(text: str, environ: Mapping[str, str] | None = None) -> str:
+    """Return the escape sequence that asks the terminal to copy ``text``.
+
+    Inside tmux the sequence is sent twice: bare, which tmux honours when its
+    ``set-clipboard`` option is ``on``, and wrapped in tmux's passthrough, which it forwards to
+    the outer terminal when ``allow-passthrough`` is on. Which of the two a given tmux accepts
+    is a setting the program cannot see, and both carry the same text, so a copy that lands
+    twice is the same copy.
+
+    Args:
+        text: What to put on the clipboard.
+        environ: Environment to read; defaults to ``os.environ``.
+    """
+    env = os.environ if environ is None else environ
+    payload = base64.b64encode(text.encode()).decode()
+    sequence = f"\x1b]52;c;{payload}\x07"
+    if env.get("TMUX"):
+        # DCS tmux ; <sequence with every ESC doubled> ST: the doubling is how a passthrough
+        # tells the escapes it carries from the one that ends it.
+        return sequence + "\x1bPtmux;" + sequence.replace("\x1b", "\x1b\x1b") + "\x1b\\"
+    return sequence