zettcode-app 0.4.2__py3-none-any.whl

zettcode/app/plugins/loader.py

@@ -0,0 +1,268 @@
+"""Load the plugins for the terminal: the engine's loader, plus the commands, palettes, pets, presenters and rows.
+
+Everything the engine's :class:`~zettcode.engine.plugins.loader.Loader` checks and merges, this one does too, and in
+addition it keeps command names, theme names and pet names unique and merges the header and status rows, so a plugin
+that collides on any of them is reported.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections import Counter
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from zettcode.engine.plugins.commands import PlainCommandContext, TextCommandResult, TurnCommandResult
+from zettcode.engine.plugins.context import PluginContext
+from zettcode.engine.plugins.loader import Loader, run
+from zettcode.plugin_api.commands import Command, CommandResult
+from zettcode.plugin_api.host import HOST_LINK, HostLink
+from zettcode.plugin_api.plugin import TuiPlugin, TuiPlugins
+from zettcode.plugin_api.state import TurnSegment
+from zettcode.sdk.builtins import require_agent_parts
+from zettcode.tui import RESERVED_THEMES
+
+from .groups import TuiGroups, UiSlots
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from collections.abc import Iterable, Mapping, Sequence
+    from importlib.metadata import EntryPoint
+
+    from zettcode.config import ZettCodeConfig
+    from zettcode.engine.plugins.commands import PlainCommand
+    from zettcode.engine.plugins.loader import OfferedPlugin
+    from zettcode.engine.plugins.plugin import Plugin
+    from zettcode.plugin_api.commands import Command
+    from zettcode.plugin_api.pets import PetSource
+    from zettcode.plugin_api.presenters import Presenter
+    from zettcode.tui import ThemeSource
+
+
+def load_terminal_plugins(
+    config: ZettCodeConfig,
+    *,
+    entry_points: Iterable[EntryPoint] | None = None,
+    builtins: Sequence[OfferedPlugin] = (),
+    shared: Mapping[str, object] | None = None,
+    required: Sequence[str] = (),
+    agent: bool = True,
+) -> TuiPlugins:
+    """Load the builtin plugins and every enabled distribution into one bundle, for the terminal.
+
+    The arguments are those of :func:`zettcode.engine.plugins.loader.load_plugins`; the builtins default to the
+    terminal's own, and the agent's come from discovery like the other parts. ``agent=False`` leaves them out, for a
+    picture or a test that draws the shell with no runtime behind it.
+    """
+    bundle = run(
+        TerminalLoader(config, shared),
+        config,
+        builtins=builtins,
+        entry_points=entry_points,
+        required=required,
+        terminal=True,
+        agent=agent,
+    )
+    assert isinstance(bundle, TuiPlugins)
+    return bundle
+
+
+#: The plugins the terminal cannot run without: the rows it paints, the presenters that draw the conversation and the
+#: commands that are the way back to a working setup (`/help`, `/plugins`, `/model`).
+#: ``[plugins] disable`` does not reach them, and the terminal does not start when one is missing.
+REQUIRED_PLUGINS: tuple[str, ...] = ("shell", "turn-line", "presenters", "commands")
+
+
+def terminal_plugins(config: ZettCodeConfig, shared: Mapping[str, object]) -> TuiPlugins:
+    """Load the plugins the terminal's way, in the shape :meth:`ZettCodeEngine.preview` takes as its loader."""
+    return require_agent_parts(load_terminal_plugins(config, shared=shared, required=REQUIRED_PLUGINS))
+
+
+def _tui(context: PluginContext) -> TuiGroups:
+    """Return the terminal group of ``context``, which this loader always attaches."""
+    if context.tui is None or not isinstance(context.tui, TuiGroups):
+        raise TypeError(f"{type(context).__name__} has no terminal group")
+    return context.tui
+
+
+def terminal_context(
+    config: ZettCodeConfig, services: Mapping[str, object] | None = None, *, name: str = ""
+) -> PluginContext:
+    """Build one context with the terminal group attached, the way this loader does for a plugin."""
+    context = PluginContext(config, services, name=name)
+    context.attach_tui(TuiGroups(context))
+    return context
+
+
+def plain_commands(context: PluginContext) -> list[Command]:
+    """Turn the plugin's plain commands into the shell's, keeping the handler's contract.
+
+    The handler returns a :class:`~zettcode.engine.plugins.commands.TextCommandResult` or a
+    :class:`~zettcode.engine.plugins.commands.TurnCommandResult` — words, a document, or a request to start — so there
+    is nothing a shell could show that a process without one could not; the adapter maps each onto what the shell does
+    with it.
+    """
+    adapted: list[Command] = []
+    for plain in context.commands.commands:
+        adapted.append(
+            Command(
+                name=plain.name,
+                description=plain.summary,
+                type="plugin",
+                handler=_plain_handler(plain),
+                when_busy=plain.when_busy,  # type: ignore[arg-type]  # the shell validates the word
+                subcommands=plain.subcommands,  # type: ignore[arg-type]
+            )
+        )
+    return adapted
+
+
+def _plain_handler(plain: PlainCommand):
+    """Wrap one plain handler as the shell's, one result type at a time."""
+
+    async def run(context):
+        host = context.host
+        level = host.client.permission if host is not None else "ask"
+        result = plain.handler(PlainCommandContext(argument=context.argument, level=level))
+        if inspect.isawaitable(result):
+            result = await result
+        if isinstance(result, TurnCommandResult):
+            # A preset for a turn: the shell starts it, and the conversation keeps the short form the command was
+            # typed as.
+            await context.require_host().prompt(result.prompt, shown=result.shown or None, cache=result.cache or None)
+            return CommandResult(notification=result.notification)
+        if isinstance(result, TextCommandResult):
+            # A document is a page of its own, so the shell opens one instead of stacking it into the conversation;
+            # the message beside it is unchanged, so a command that gives both gets both. The widget library is
+            # imported only where there is a document: a command that answers with words alone never pays for it.
+            widget = None
+            if result.markdown:
+                from zettcode.app.ui.widgets import DocumentPage
+
+                # Titled by the command as it was typed: the summary is already in the menu, and this page covers the
+                # conversation, so it has to say which command opened it.
+                widget = DocumentPage(result.markdown, title=plain.name)
+            return CommandResult(message=result.message, notification=result.notification, widget=widget)
+        raise TypeError(
+            f"a plain command returns a TextCommandResult or a TurnCommandResult, not {type(result).__name__}"
+        )
+
+    return run
+
+
+class TerminalLoader(Loader):
+    """The engine's loader with the terminal's registries."""
+
+    def __init__(self, config: ZettCodeConfig, shared: Mapping[str, object] | None = None) -> None:
+        super().__init__(config, shared)
+        self.services.setdefault(HOST_LINK, HostLink())
+        self.slots = UiSlots()
+        self.turn_segments: dict[str, TurnSegment] = {}
+        self.commands: list[Command] = []
+        #: The commands the program's own plugins (built in, or its parts) registered; the bundle puts them first.
+        self.program_commands: list[Command] = []
+        self.themes: list[ThemeSource] = []
+        self.pets: list[PetSource] = []
+        self.presenters: list[Presenter[Any]] = []
+        #: Told when the terminal window gains or loses focus, and when a turn of the conversation ends.
+        self.focus_handlers: list[Callable[[bool], None]] = []
+        self.turn_start_handlers: list[Callable[[], None]] = []
+        self.turn_end_handlers: list[Callable[[bool], None]] = []
+        self._claimed: set[str] = set()
+        self._theme_names: set[str] = set(RESERVED_THEMES)
+        self._pet_names: set[str] = set()
+
+    def new_context(self, name: str = "") -> PluginContext:
+        # Seed the registry with what is already loaded, so a segment that
+        # reuses a name — or asks to override a side — acts on the real rows
+        # instead of on an empty copy. A failure leaves it untouched.
+        context = terminal_context(self.config, self.services, name=name)
+        tui = _tui(context)
+        tui.slots.take_from(self.slots)
+        for segment in self.turn_segments.values():
+            tui.register_turn_segment(segment.name, segment.summary, segment.builder)
+        return context
+
+    def activated(self, plugin: Plugin[Any], context: PluginContext) -> None:
+        if isinstance(plugin, TuiPlugin):
+            terminal = _tui(context)
+            for region, side, slot_name, builder in plugin.ui_slots():
+                terminal.slots.add(region, side, slot_name, builder)
+
+    def clash(self, context: PluginContext) -> str | None:
+        terminal = _tui(context)
+        # Command lookup takes the first match, so a second plugin claiming the
+        # same name would be silently unreachable. Reject the plugin instead.
+        claimed = [command.name for command in terminal.registered_commands]
+        claimed += [plain.name for plain in context.commands.commands]
+        # Both registries of this plugin, and everything loaded before it, are one namespace: the shell keeps the
+        # first match, so a second spelling of a name would be unreachable rather than refused.
+        command_clash = next(
+            (name for name, count in Counter(claimed).items() if count > 1 or name in self._claimed), None
+        )
+        if command_clash is not None:
+            return f"command {command_clash} is already registered by another plugin"
+        found = super().clash(context)
+        if found is not None:
+            return found
+        # `/theme <name>` has to mean one palette, so a name an earlier plugin (the built-in one first) or the
+        # program itself already has is not shared out a second time.
+        theme_clash = next((source.name for source in terminal.themes if source.name in self._theme_names), None)
+        if theme_clash is not None:
+            return f"theme {theme_clash} is already registered"
+        # `/pet <name>` has to mean one pet, so a name an earlier plugin (the built-in one first) already has is not
+        # shared out a second time.
+        pet_clash = next((source.name for source in terminal.pets if source.name in self._pet_names), None)
+        if pet_clash is not None:
+            return f"pet {pet_clash} is already registered"
+        return None
+
+    def merge(self, context: PluginContext) -> None:
+        terminal = _tui(context)
+        super().merge(context)
+        # A plain command is one the shell can run too: text and a toast need no page, so the plugin's
+        # ``ctx.commands`` become ordinary commands here, beside the ones registered on ``ctx.tui``.
+        plain = plain_commands(context)
+        self._claimed.update(command.name for command in plain)
+        before = len(self.commands)
+        self.commands.extend(plain)
+        self._theme_names.update(source.name for source in terminal.themes)
+        self.themes.extend(terminal.themes)
+        self._pet_names.update(source.name for source in terminal.pets)
+        self.pets.extend(terminal.pets)
+        self.presenters.extend(terminal.presenters)
+        self.focus_handlers.extend(terminal.focus_handlers)
+        self.turn_start_handlers.extend(terminal.turn_start_handlers)
+        self.turn_end_handlers.extend(terminal.turn_end_handlers)
+        self._claimed.update(command.name for command in terminal.registered_commands)
+        self.commands.extend(terminal.registered_commands)
+        if self.program:
+            self.program_commands.extend(self.commands[before:])
+        self.slots = terminal.slots
+        self.turn_segments = {segment.name: segment for segment in terminal.turn_segments}
+
+    def bundle(self) -> TuiPlugins:
+        plain = super().bundle()
+        program = tuple(self.program_commands)
+        own = {id(command) for command in program}
+        return TuiPlugins(
+            host=plain.host,
+            mentions=plain.mentions,
+            providers=plain.providers,
+            contributed=plain.contributed,
+            services=plain.services,
+            plain_commands=plain.plain_commands,
+            failed=plain.failed,
+            builtins=plain.builtins,
+            triggers=plain.triggers,
+            taken=plain.taken,
+            commands=(*program, *(command for command in self.commands if id(command) not in own)),
+            builtin_commands=tuple(program),
+            themes=tuple(self.themes),
+            pets=tuple(self.pets),
+            presenters=tuple(self.presenters),
+            rows=self.slots.rows(),
+            turn_segments=tuple(self.turn_segments.values()),
+            focus_handlers=tuple(self.focus_handlers),
+            turn_start_handlers=tuple(self.turn_start_handlers),
+            turn_end_handlers=tuple(self.turn_end_handlers),
+        )

zettcode/app/ui/__init__.py

@@ -0,0 +1,63 @@
+"""The ZettCode interface: the application shell and the widgets it composes."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING
+
+#: Where each public name lives; read by :func:`__getattr__` on first use.
+_EXPORTS = {
+    "CommandCompleter": ".widgets",
+    "ModelPage": ".widgets",
+    "TranscriptSource": ".widgets",
+    "TranscriptView": ".widgets",
+    "WELCOME": ".widgets",
+    "ZettCodeApp": ".app",
+    "ZettCodeRoot": ".widgets",
+    "help_text": ".widgets",
+}
+
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
+    from .app import ZettCodeApp
+    from .widgets import (
+        WELCOME,
+        CommandCompleter,
+        ModelPage,
+        TranscriptSource,
+        TranscriptView,
+        ZettCodeRoot,
+        help_text,
+    )
+
+
+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__ = [
+    "CommandCompleter",
+    "ModelPage",
+    "TranscriptSource",
+    "TranscriptView",
+    "WELCOME",
+    "ZettCodeApp",
+    "ZettCodeRoot",
+    "help_text",
+]