zettcode-tui 0.4.0__tar.gz

zettcode_tui-0.4.0/.gitignore

@@ -0,0 +1,37 @@
+**/.venv/
+**/__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.smoke/
+.coverage
+**/.pytest_cache/
+**/.ruff_cache/
+.zett-tool-output/
+.env
+.DS_Store
+
+# viztracer writes its trace here by default.
+/result.json
+
+# The docs site: dependencies, build output, and VitePress' cache.
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+docs/.vitepress/.temp/
+
+# The TypeScript client is built from its sources; only dist/ is published.
+clients/typescript/dist/
+
+# The gateway's page is built from clients/gateway into the package when a distribution is made (`make gateway-ui`);
+# the build output is not kept in the repository. pyproject's `artifacts` puts it in the wheel all the same.
+packages/zettcode-gateway/src/zettcode/gateway/static/
+
+# The palette gallery is generated by `make palettes`: every widget painted in
+# every palette, written by docs/scripts/palette_gallery.py. Regenerate it
+# rather than committing a 2 MB copy that goes stale the moment a colour moves.
+docs/internal/palettes.html
+
+# The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
+packages/order.txt

zettcode_tui-0.4.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.5
+Name: zettcode-tui
+Version: 0.4.0
+Summary: The widget framework ZettCode's terminal is drawn with, and nothing else
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: terminal,tui,widgets,zettcode
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyperclip<2,>=1.9
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Requires-Dist: wcwidth<1,>=0.2

zettcode_tui-0.4.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "zettcode-tui"
+description = "The widget framework ZettCode's terminal is drawn with, and nothing else"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "tui", "terminal", "widgets"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Typing :: Typed",
+]
+dependencies = [
+  "wcwidth>=0.2,<1",
+  "pyperclip>=1.9,<2",
+  # `tui/_compat.py` reads a theme file; the stdlib only learned TOML in 3.11.
+  "tomli>=2,<3; python_version < '3.11'",
+]
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+# One version for the whole repository: the engine ships the file.
+path = "../zettcode-engine/src/zettcode/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

zettcode_tui-0.4.0/src/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-0.4.0/src/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-0.4.0/src/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)