zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/theme_file.py

@@ -0,0 +1,300 @@
+"""Load a theme palette from TOML so colours do not have to be edited in code.
+
+A palette is a file, and a palette's name is the file's name. The ones that ship with the program are TOML files in
+``themes/`` beside this module, and the reader's own are ``<name>.toml`` files in a directory of theirs
+(``~/.zettcode/themes``); both are read by the same code, so adding a palette is writing one file and nothing else.
+Only the *names* are listed up front (a directory listing); a palette's file is read when it is asked for, so a
+start pays for no palette it does not use.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, fields, replace
+from functools import partial
+from importlib import resources
+from pathlib import Path
+
+from ._compat import tomllib
+from .core.theme import DARK, LIGHT, Theme, ToolTheme, theme_named
+from .render.code import CodeTheme
+from .render.color import parse_hex
+
+#: The palettes that ship as files, in the order a menu lists them: the dark ones, then the light ones.
+BUNDLED = (
+    "catppuccin-mocha",
+    "tokyo-night",
+    "nord",
+    "gruvbox-dark",
+    "rose-pine",
+    "kanagawa",
+    "dracula",
+    "one-dark",
+    "solarized-dark",
+    "github-dimmed",
+    "ayu-mirage",
+    "catppuccin-latte",
+    "rose-pine-dawn",
+    "gruvbox-light",
+    "solarized-light",
+    "github-light",
+)
+
+#: What a palette's name may be. It is typed after ``/theme`` as one word, so it holds no space.
+THEME_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
+
+#: Names the program reserves: they are what the terminal's own light or dark is mapped to, and a file cannot
+#: take them over.
+RESERVED_THEMES = (DARK.name, LIGHT.name)
+
+#: The page the two built-in palettes paint when they are chosen by name.
+PAGES = {DARK.name: "#232a2e", LIGHT.name: "#f7f8f5"}
+
+EXAMPLE = """\
+base = "dark"                 # dark | light
+description = "my palette"    # shown beside its name in the /theme menu
+
+[ui]
+accent = "#a7c080"
+error = "#e67e80"
+# diff_added = "#a7c080"       # default: the accent
+# diff_removed = "#e67e80"     # default: the error colour
+surface_side = "#393a44"
+surface_peer = "#313244"
+
+[tools]
+read = "#89b4fa"
+shell = "#fab387"
+
+[code]
+keyword = "#e58fa8"
+string = "#9bddad"
+comment = "#6d7a70"
+number = "#d8b46a"
+function = "#7fb7d8"
+builtin = "#b8a6e0"
+inline = "#9bddad"
+"""
+
+
+class ThemeFileError(ValueError):
+    """Raised when a theme file cannot be understood."""
+
+
+def theme_from_toml(text: str, *, base: Theme | None = None) -> Theme:
+    """Build a theme from TOML text, starting from its base palette.
+
+    Args:
+        text: TOML source; ``base`` selects ``dark`` or ``light`` and the ``ui``,
+            ``tools``, and ``code`` tables override individual roles, so a file
+            only names the colours it wants to change.
+        base: Palette to override directly; when omitted the file's ``base`` key
+            (default ``dark``) is resolved through ``theme_named``.
+    """
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise ThemeFileError(f"Invalid theme file: {error}") from error
+    if not isinstance(data, dict):
+        raise ThemeFileError("Theme file must be a table")
+
+    palette = base
+    if palette is None:
+        requested = data.get("base", DARK.name)
+        try:
+            palette = theme_named(str(requested))
+        except ValueError as error:
+            raise ThemeFileError(str(error)) from error
+
+    ui = _select(data.get("ui", {}), {field.name for field in fields(Theme)} - {"code", "tools"})
+    tools = _select(
+        data.get("tools", {}),
+        {field.name for field in fields(ToolTheme)},
+        hyphenated={"web-search": "web_search", "ask-user": "ask_user"},
+    )
+    code = _select(data.get("code", {}), {field.name for field in fields(CodeTheme)})
+    return replace(palette, **ui, tools=replace(palette.tools, **tools), code=replace(palette.code, **code))
+
+
+def load_theme(path: Path, *, base: Theme | None = None) -> Theme:
+    """Read a theme file from disk.
+
+    Args:
+        path: File to read; a missing or unreadable file raises
+            ``ThemeFileError`` rather than an ``OSError``.
+        base: Palette to override directly, bypassing the file's ``base`` key.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as error:
+        raise ThemeFileError(f"Cannot read {path}: {error}") from error
+    return theme_from_toml(text, base=base)
+
+
+@dataclass(frozen=True, slots=True)
+class ThemeSource:
+    """A palette that something offers by name: the program's own files, or a plugin.
+
+    Attributes:
+        name: What ``/theme`` is typed with; one word.
+        load: Builds the palette. Called when it is asked for, never before, so a source costs nothing until picked.
+        description: The one-line note the menu shows beside the name, or a function that returns it (called only
+            when a menu is opened, for the same reason).
+    """
+
+    name: str
+    load: Callable[[], Theme]
+    description: str | Callable[[], str] = ""
+
+
+def _bundled_text(name: str) -> str:
+    """Return the text of one palette file that ships with the program."""
+    return (resources.files(__package__) / "themes" / f"{name}.toml").read_text(encoding="utf-8")
+
+
+def _load_bundled(name: str) -> Theme:
+    return theme_from_toml(_bundled_text(name))
+
+
+def _bundled_note(name: str) -> str:
+    note = tomllib.loads(_bundled_text(name)).get("description")
+    return note if isinstance(note, str) else ""
+
+
+def _file_note(path: Path) -> str:
+    note = tomllib.loads(path.read_text(encoding="utf-8")).get("description")
+    return note if isinstance(note, str) else ""
+
+
+def file_theme(name: str, path: Path) -> ThemeSource:
+    """Return a source for a palette kept in a TOML file, read when it is asked for and not before."""
+    return ThemeSource(name, partial(load_theme, path), partial(_file_note, path))
+
+
+def bundled_themes() -> tuple[ThemeSource, ...]:
+    """Return the palettes that ship as files, as sources: the built-in plugin registers these.
+
+    Nothing is read here; each file is opened when its palette is asked for, or its note when a menu is.
+    """
+    return tuple(ThemeSource(name, partial(_load_bundled, name), partial(_bundled_note, name)) for name in BUNDLED)
+
+
+def _user_file(name: str, directory: Path | None) -> Path | None:
+    """Return the reader's file for a palette name, or ``None``. A name that is not one word is never a file."""
+    if directory is None or name in RESERVED_THEMES or not THEME_NAME.fullmatch(name):
+        return None
+    path = directory / f"{name}.toml"
+    return path if path.is_file() else None
+
+
+def _user_names(directory: Path | None) -> tuple[str, ...]:
+    """Return the names of the reader's palettes: the ``.toml`` files in their directory, by name."""
+    if directory is None:
+        return ()
+    try:
+        stems = sorted(path.stem for path in directory.glob("*.toml") if path.is_file())
+    except OSError:
+        return ()
+    return tuple(stem for stem in stems if THEME_NAME.fullmatch(stem) and stem not in RESERVED_THEMES)
+
+
+class ThemeCatalog:
+    """Every palette that can be asked for by name, and where each comes from.
+
+    There are three places, in this order: the two the terminal's own light or dark maps to (``dark`` and ``light``,
+    which nothing can replace), the *sources* (the built-in plugin's files, then any other plugin's, in the order
+    they loaded), and the reader's own ``<name>.toml`` files. A reader's file shadows a source of the same name,
+    which is how a palette that ships is adjusted: copy it, change what is wrong with it, keep the name. A source
+    whose name is taken is ignored, the first one winning.
+
+    Only names are listed up front. A palette is built when it is asked for, so a catalog of sixty costs a start
+    nothing.
+
+    Args:
+        sources: What plugins and the program offer.
+        directory: The reader's palette directory; one that is missing is the same as an empty one.
+    """
+
+    def __init__(self, sources: Sequence[ThemeSource] = (), directory: Path | None = None) -> None:
+        chosen: dict[str, ThemeSource] = {}
+        for source in sources:
+            if source.name not in RESERVED_THEMES and source.name not in chosen and THEME_NAME.fullmatch(source.name):
+                chosen[source.name] = source
+        self._sources = chosen
+        self.directory = directory
+
+    def names(self) -> tuple[str, ...]:
+        """Return the names in the order a menu lists them. Nothing is parsed."""
+        own = [name for name in _user_names(self.directory) if name not in self._sources]
+        return (*RESERVED_THEMES, *self._sources, *own)
+
+    def load(self, name: str) -> Theme:
+        """Return the palette called ``name``.
+
+        Raises:
+            ThemeFileError: There is no such palette, or it cannot be built or understood. The message names what is
+                available, so a typo is answered by the list.
+        """
+        if name in RESERVED_THEMES:
+            # Chosen by name, they paint their own page like every other palette: a light one over a dark terminal is
+            # light, not dark text on the terminal's black. Only the *automatic* pick leaves the page alone.
+            return replace(theme_named(name), background=PAGES[name])
+        path = _user_file(name, self.directory)
+        if path is not None:
+            loaded = load_theme(path)
+        elif name in self._sources:
+            try:
+                loaded = self._sources[name].load()
+            except ThemeFileError:
+                raise
+            except Exception as error:  # noqa: BLE001 - a plugin's palette is its author's code
+                raise ThemeFileError(f"Theme {name!r} could not be built: {error}") from error
+        else:
+            raise ThemeFileError(f"Unknown theme: {name!r}. Available: {', '.join(self.names())}")
+        return replace(loaded, name=name, code=replace(loaded.code, name=name))
+
+    def notes(self) -> dict[str, str]:
+        """Return the one-line note each palette carries, by name; a palette with none is left out.
+
+        Read from the files and the plugins, so this is for a menu that is being opened and not for the start.
+        Whatever cannot be read has no note, and is not an error here: it is the error of the person who picks it.
+        """
+        notes: dict[str, str] = {}
+        for name in self.names():
+            if name in RESERVED_THEMES:
+                continue
+            path = _user_file(name, self.directory)
+            try:
+                if path is not None:
+                    data = tomllib.loads(path.read_text(encoding="utf-8")).get("description")
+                else:
+                    described = self._sources[name].description
+                    data = described() if callable(described) else described
+            except Exception:  # noqa: BLE001 - see above
+                continue
+            if isinstance(data, str) and data.strip():
+                notes[name] = data.strip()
+        return notes
+
+
+def _select(values: object, allowed: set[str], *, hyphenated: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Validate one palette table against the keys the theme knows.
+
+    A role whose name is a word rather than an identifier is written with a hyphen in the file (``web-search``)
+    and kept as the field it names (``web_search``); ``hyphenated`` is that spelling, when a table has one.
+    """
+    if not isinstance(values, dict):
+        raise ThemeFileError("Palette sections must be tables")
+    spelled = hyphenated or {}
+    chosen: dict[str, str] = {}
+    for key, value in values.items():
+        name = spelled.get(key, key)
+        if name not in allowed:
+            raise ThemeFileError(f"Unknown theme key: {key!r}")
+        if not isinstance(value, str):
+            raise ThemeFileError(f"{key} must be a string colour")
+        if name != "name" and parse_hex(value) is None:
+            raise ThemeFileError(f"{key} must be a #rrggbb colour, got {value!r}")
+        chosen[name] = value
+    return chosen

zettcode/tui/themes/ayu-mirage.toml

@@ -0,0 +1,44 @@
+description = "blue-grey with warm gold"
+base = "dark"
+
+[ui]
+background = "#1f2430"
+surface = "#242936"
+surface_alt = "#2d3446"
+surface_side = "#344458"
+surface_peer = "#44465e"
+text = "#cccac2"
+muted = "#8d95a3"
+subtle = "#a7aebc"
+accent = "#ffcc66"
+accent_bright = "#ffd173"
+warning = "#ffcc66"
+error = "#f28779"
+border = "#33415e"
+focus = "#ffd173"
+selection = "#34455a"
+diff_added = "#87d96c"
+diff_removed = "#f28779"
+
+[tools]
+read = "#ffcc66"
+search = "#73d0ff"
+image = "#73d0ff"
+write = "#ffad66"
+delete = "#f28779"
+shell = "#73d0ff"
+plan = "#73d0ff"
+subagent = "#5ccfe6"
+message = "#f29e74"
+
+[code]
+inline = "#87d96c"
+text = "#cccac2"
+keyword = "#ffad66"
+string = "#87d96c"
+comment = "#8d95a3"
+number = "#ffad66"
+function = "#73d0ff"
+builtin = "#dfbfff"
+operator = "#a7aebc"
+punctuator = "#a7aebc"

zettcode/tui/themes/catppuccin-latte.toml

@@ -0,0 +1,44 @@
+description = "creamy lavender-grey, saturated accents"
+base = "light"
+
+[ui]
+background = "#eff1f5"
+surface = "#f7f8fb"
+surface_alt = "#e6e9ef"
+surface_side = "#d2dcf0"
+surface_peer = "#dad2ef"
+text = "#484b64"
+muted = "#6c6f81"
+subtle = "#575a71"
+accent = "#8839ef"
+accent_bright = "#5b6cca"
+warning = "#a26715"
+error = "#d20f39"
+border = "#ccd0da"
+focus = "#5b6cca"
+selection = "#ccd0da"
+diff_added = "#358423"
+diff_removed = "#d20f39"
+
+[tools]
+read = "#a26715"
+search = "#5b6cca"
+image = "#5b6cca"
+write = "#c54e09"
+delete = "#d20f39"
+shell = "#5b6cca"
+plan = "#5b6cca"
+subagent = "#148086"
+message = "#aa5693"
+
+[code]
+inline = "#358423"
+text = "#484b64"
+keyword = "#8839ef"
+string = "#358423"
+comment = "#6c6f81"
+number = "#c54e09"
+function = "#1e66f5"
+builtin = "#8839ef"
+operator = "#575a71"
+punctuator = "#575a71"

zettcode/tui/themes/catppuccin-mocha.toml

@@ -0,0 +1,44 @@
+description = "soft purple-grey, pastel accents"
+base = "dark"
+
+[ui]
+background = "#1e1e2e"
+surface = "#262637"
+surface_alt = "#313244"
+surface_side = "#3a3f56"
+surface_peer = "#45415b"
+text = "#cdd6f4"
+muted = "#8f93a8"
+subtle = "#a6adc8"
+accent = "#cba6f7"
+accent_bright = "#b4befe"
+warning = "#f9e2af"
+error = "#f38ba8"
+border = "#45475a"
+focus = "#b4befe"
+selection = "#45475a"
+diff_added = "#a6e3a1"
+diff_removed = "#f38ba8"
+
+[tools]
+read = "#f9e2af"
+search = "#b4befe"
+image = "#b4befe"
+write = "#fab387"
+delete = "#f38ba8"
+shell = "#b4befe"
+plan = "#b4befe"
+subagent = "#94e2d5"
+message = "#f5c2e7"
+
+[code]
+inline = "#a6e3a1"
+text = "#cdd6f4"
+keyword = "#cba6f7"
+string = "#a6e3a1"
+comment = "#8f93a8"
+number = "#fab387"
+function = "#89b4fa"
+builtin = "#cba6f7"
+operator = "#a6adc8"
+punctuator = "#a6adc8"

zettcode/tui/themes/dracula.toml

@@ -0,0 +1,44 @@
+description = "vivid purple, pink and green"
+base = "dark"
+
+[ui]
+background = "#282a36"
+surface = "#2f3140"
+surface_alt = "#343746"
+surface_side = "#3d4958"
+surface_peer = "#46435d"
+text = "#f8f8f2"
+muted = "#8d99bd"
+subtle = "#bdc0d6"
+accent = "#bd93f9"
+accent_bright = "#ff79c6"
+warning = "#f1fa8c"
+error = "#ff5555"
+border = "#44475a"
+focus = "#ff79c6"
+selection = "#44475a"
+diff_added = "#50fa7b"
+diff_removed = "#ff5555"
+
+[tools]
+read = "#f1fa8c"
+search = "#8be9fd"
+image = "#8be9fd"
+write = "#ffb86c"
+delete = "#ff5555"
+shell = "#8be9fd"
+plan = "#8be9fd"
+subagent = "#8be9fd"
+message = "#ff79c6"
+
+[code]
+inline = "#50fa7b"
+text = "#f8f8f2"
+keyword = "#ff79c6"
+string = "#50fa7b"
+comment = "#8d99bd"
+number = "#ffb86c"
+function = "#8be9fd"
+builtin = "#bd93f9"
+operator = "#bdc0d6"
+punctuator = "#bdc0d6"

zettcode/tui/themes/github-dimmed.toml

@@ -0,0 +1,44 @@
+description = "GitHub's dimmed dark, restrained"
+base = "dark"
+
+[ui]
+background = "#22272e"
+surface = "#2d333b"
+surface_alt = "#373e47"
+surface_side = "#3a4758"
+surface_peer = "#44445b"
+text = "#cad2db"
+muted = "#959fa9"
+subtle = "#b1bac4"
+accent = "#539bf5"
+accent_bright = "#6cb6ff"
+warning = "#c69026"
+error = "#e5534b"
+border = "#444c56"
+focus = "#6cb6ff"
+selection = "#2f4766"
+diff_added = "#57ab5a"
+diff_removed = "#e5534b"
+
+[tools]
+read = "#c69026"
+search = "#539bf5"
+image = "#539bf5"
+write = "#cc6b2c"
+delete = "#e5534b"
+shell = "#539bf5"
+plan = "#539bf5"
+subagent = "#39c5cf"
+message = "#e275ad"
+
+[code]
+inline = "#57ab5a"
+text = "#cad2db"
+keyword = "#f47067"
+string = "#57ab5a"
+comment = "#959fa9"
+number = "#cc6b2c"
+function = "#539bf5"
+builtin = "#986ee2"
+operator = "#b1bac4"
+punctuator = "#b1bac4"

zettcode/tui/themes/github-light.toml

@@ -0,0 +1,44 @@
+description = "plain white, standard blue/green/red"
+base = "light"
+
+[ui]
+background = "#ffffff"
+surface = "#f6f8fa"
+surface_alt = "#eaeef2"
+surface_side = "#d4e1f0"
+surface_peer = "#dcd9f0"
+text = "#1f2328"
+muted = "#656d76"
+subtle = "#555e67"
+accent = "#0969da"
+accent_bright = "#0550ae"
+warning = "#9a6700"
+error = "#cf222e"
+border = "#d0d7de"
+focus = "#0550ae"
+selection = "#ddf4ff"
+diff_added = "#1a7f37"
+diff_removed = "#cf222e"
+
+[tools]
+read = "#9a6700"
+search = "#0969da"
+image = "#0969da"
+write = "#bc4c00"
+delete = "#cf222e"
+shell = "#0969da"
+plan = "#0969da"
+subagent = "#1b7c83"
+message = "#bf3989"
+
+[code]
+inline = "#1a7f37"
+text = "#1f2328"
+keyword = "#cf222e"
+string = "#1a7f37"
+comment = "#656d76"
+number = "#bc4c00"
+function = "#0969da"
+builtin = "#8250df"
+operator = "#555e67"
+punctuator = "#555e67"

zettcode/tui/themes/gruvbox-dark.toml

@@ -0,0 +1,44 @@
+description = "warm brown-yellow, retro paper"
+base = "dark"
+
+[ui]
+background = "#282828"
+surface = "#32302f"
+surface_alt = "#3c3836"
+surface_side = "#434340"
+surface_peer = "#504243"
+text = "#ebdbb2"
+muted = "#a29689"
+subtle = "#c0b298"
+accent = "#fe8019"
+accent_bright = "#fabd2f"
+warning = "#d79921"
+error = "#fb4934"
+border = "#504945"
+focus = "#fabd2f"
+selection = "#504945"
+diff_added = "#b8bb26"
+diff_removed = "#fb4934"
+
+[tools]
+read = "#d79921"
+search = "#83a598"
+image = "#83a598"
+write = "#fe8019"
+delete = "#fb4934"
+shell = "#83a598"
+plan = "#83a598"
+subagent = "#8ec07c"
+message = "#d3869b"
+
+[code]
+inline = "#b8bb26"
+text = "#ebdbb2"
+keyword = "#fb4934"
+string = "#b8bb26"
+comment = "#a29689"
+number = "#fe8019"
+function = "#83a598"
+builtin = "#d3869b"
+operator = "#c0b298"
+punctuator = "#c0b298"

zettcode/tui/themes/gruvbox-light.toml

@@ -0,0 +1,44 @@
+description = "cream paper, brown text"
+base = "light"
+
+[ui]
+background = "#fbf1c7"
+surface = "#f9f5d7"
+surface_alt = "#ebdbb2"
+surface_side = "#d4cfac"
+surface_peer = "#dfc7aa"
+text = "#3c3836"
+muted = "#73675c"
+subtle = "#504945"
+accent = "#af3a03"
+accent_bright = "#9e6712"
+warning = "#9e6712"
+error = "#9d0006"
+border = "#d5c4a1"
+focus = "#9e6712"
+selection = "#d5c4a1"
+diff_added = "#79740e"
+diff_removed = "#9d0006"
+
+[tools]
+read = "#9e6712"
+search = "#076678"
+image = "#076678"
+write = "#af3a03"
+delete = "#9d0006"
+shell = "#076678"
+plan = "#076678"
+subagent = "#427b58"
+message = "#8f3f71"
+
+[code]
+inline = "#79740e"
+text = "#3c3836"
+keyword = "#9d0006"
+string = "#79740e"
+comment = "#73675c"
+number = "#af3a03"
+function = "#076678"
+builtin = "#8f3f71"
+operator = "#504945"
+punctuator = "#504945"