zettcode-engine 0.3.4__tar.gz → 0.4.0__tar.gz

{zettcode_engine-0.3.4 → zettcode_engine-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zettcode-engine
-Version: 0.3.4
+Version: 0.4.0
 Summary: The agent core of ZettCode: the runtime over zett-agent, and the leaf types it is written on
 Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
 Author: Chang-LeHung

{zettcode_engine-0.3.4 → zettcode_engine-0.4.0}/src/zettcode/engine/plugins/context.py

@@ -196,6 +196,15 @@ class PluginContext:
         """Return the object available under ``name``, or ``None`` when there is none (see :meth:`service`)."""
         return lookup({**self._available, **self._services}, name, kind)
 
+    def inject(self, name: str, service: object) -> object:
+        """Make an object available to the other plugins under ``name``; the same as :meth:`provide`.
+
+        A plugin that lists this one in ``deps`` is activated after it and finds the object with :meth:`service`.
+        What the object is, and how it is used, is for the plugins to agree on: the loader only keeps the name
+        unique and the order right.
+        """
+        return self.provide(name, service)
+
     def provide(self, name: str, service: object) -> object:
         """Register an object under a name, so other parts of the application can look it up.
 

zettcode_engine-0.4.0/src/zettcode/engine/plugins/graph.py

@@ -0,0 +1,96 @@
+"""Put plugins in dependency order, and say which of them cannot be loaded at all.
+
+A plugin names the plugins it needs in :attr:`~zettcode.engine.plugins.plugin.Plugin.deps`. :func:`order` turns those
+names into a topological order — a plugin is always activated after every plugin it needs — and into the reasons a
+plugin has to be left out: a plugin it needs is absent, or the needs go round in a circle. The order is stable: among
+the plugins that are ready, the one that was offered first goes first, so a graph with no edges keeps exactly the
+order it was given in, and the built-in plugins stay ahead of the installed ones unless one of them needs a later one.
+
+The module knows names and edges only, not plugins, so it is one pure function that a test can feed strings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    """One plugin as the graph sees it: the name it is known by and the names it needs."""
+
+    name: str
+    deps: tuple[str, ...] = ()
+
+
+def order(nodes: list[Node]) -> tuple[list[int], dict[int, str]]:
+    """Return the activation order of ``nodes`` and the reason each node that cannot be activated has.
+
+    Args:
+        nodes: The candidates, in the order they were offered.
+
+    Returns:
+        The indices of the nodes that can be activated, dependencies first, and ``{index: why}`` for the ones that
+        cannot. A node that needs a failed node fails too, so the reasons name the first thing missing and the chain
+        it took down is in the later reasons. A name offered twice belongs to its first node; the second is ordered
+        like any other and left for the loader to refuse as a duplicate.
+    """
+    owner: dict[str, int] = {}
+    for index, node in enumerate(nodes):
+        owner.setdefault(node.name, index)
+
+    failed: dict[int, str] = {}
+    changed = True
+    while changed:
+        changed = False
+        for index, node in enumerate(nodes):
+            if index in failed:
+                continue
+            for dep in node.deps:
+                if dep == node.name:
+                    failed[index] = f"plugin {node.name!r} lists itself in deps"
+                elif dep not in owner:
+                    failed[index] = f"needs plugin {dep!r}, which is not installed or is turned off"
+                elif owner[dep] in failed:
+                    failed[index] = f"needs plugin {dep!r}, which cannot be loaded"
+                else:
+                    continue
+                changed = True
+                break
+
+    alive = [index for index in range(len(nodes)) if index not in failed]
+    waiting = {index: {owner[dep] for dep in nodes[index].deps if owner[dep] != index} for index in alive}
+    ordered: list[int] = []
+    done: set[int] = set()
+    remaining = list(alive)
+    while remaining:
+        ready = next((index for index in remaining if waiting[index] <= done), None)
+        if ready is None:
+            break
+        ordered.append(ready)
+        done.add(ready)
+        remaining.remove(ready)
+
+    for index in remaining:
+        cycle = _cycle(index, nodes, owner, set(remaining))
+        failed[index] = (
+            f"dependency cycle: {' -> '.join(cycle)}" if cycle else "needs a plugin that is part of a dependency cycle"
+        )
+    return ordered, failed
+
+
+def _cycle(start: int, nodes: list[Node], owner: dict[str, int], within: set[int]) -> list[str]:
+    """Return the names on a path from ``start`` back to itself inside ``within``, or ``[]`` when it is on none."""
+    stack: list[tuple[int, list[int]]] = [(start, [start])]
+    seen: set[int] = set()
+    while stack:
+        index, path = stack.pop()
+        for dep in nodes[index].deps:
+            target = owner.get(dep)
+            if target is None or target not in within:
+                continue
+            if target == start:
+                return [nodes[step].name for step in (*path, start)]
+            if target not in seen:
+                seen.add(target)
+                stack.append((target, [*path, target]))
+    return []

{zettcode_engine-0.3.4 → zettcode_engine-0.4.0}/src/zettcode/engine/plugins/loader.py

@@ -27,13 +27,19 @@ from __future__ import annotations
 
 import hashlib
 import importlib.util
+import logging
+import re
 import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import partial
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from zettcode.config import read_disabled_plugins
 from zettcode.providers import BUILTIN_PROVIDERS
 
+from . import graph
 from .context import PluginContext
 from .extension import HOST_NAME, PluginExtension
 from .plugin import Plugin, Plugins, PluginSetting
@@ -47,9 +53,18 @@ if TYPE_CHECKING:  # pragma: no cover - annotations only
     from zettcode.mention import MentionProvider
     from zettcode.providers import Provider
 
+logger = logging.getLogger("zettcode.plugins")
+
 #: Entry-point group a distribution publishes its plugin under.
 PLUGIN_ENTRY_POINT_GROUP = "zettcode.plugins"
 
+#: Entry-point group the distributions of the program itself publish the plugins only a screen has any use for under
+#: (the presenters, the pets, the palettes). They are loaded the same way, ahead of the installed plugins, but they are
+#: released with the program (one version, one tag) and are not something a reader installs or removes, so the plugin
+#: tooling and the release line for plugins never see them. A process with no terminal (the SDK, the server) does not
+#: load them: they would import the whole terminal to offer it nothing.
+TERMINAL_PART_GROUP = "zettcode.terminal"
+
 
 def installed_entry_points() -> tuple[EntryPoint, ...]:
     """Return every plugin entry point installed in this environment.
@@ -59,7 +74,9 @@ def installed_entry_points() -> tuple[EntryPoint, ...]:
     """
     from importlib.metadata import entry_points
 
-    return tuple(sorted(entry_points(group=PLUGIN_ENTRY_POINT_GROUP), key=lambda point: point.name))
+    parts = sorted(entry_points(group=TERMINAL_PART_GROUP), key=lambda point: point.name)
+    plugins = sorted(entry_points(group=PLUGIN_ENTRY_POINT_GROUP), key=lambda point: point.name)
+    return (*parts, *plugins)
 
 
 def installed_files(directory: Path) -> tuple[Path, ...]:
@@ -124,6 +141,7 @@ def load_plugins(
     entry_points: Iterable[EntryPoint] | None = None,
     builtins: Sequence[Plugin[Any]],
     shared: Mapping[str, object] | None = None,
+    required: Sequence[str] = (),
 ) -> Plugins:
     """Load the builtin plugins and every enabled distribution into one bundle.
 
@@ -143,7 +161,48 @@ def load_plugins(
     Returns:
         The host extension, services, and load failures the plugins produced.
     """
-    return run(Loader(config, shared), config, builtins=builtins, entry_points=entry_points)
+    return run(Loader(config, shared), config, builtins=builtins, entry_points=entry_points, required=required)
+
+
+class RequiredPluginError(RuntimeError):
+    """A plugin the program cannot run without did not load.
+
+    Attributes:
+        missing: ``{name: why}`` for each required plugin that is not among the loaded ones, in the order they were
+            asked for. The message lists them, so a front end can print it as it is.
+    """
+
+    def __init__(self, missing: dict[str, str]) -> None:
+        self.missing = dict(missing)
+        lines = "; ".join(f"{name}: {why}" for name, why in self.missing.items())
+        super().__init__(f"cannot start without the required plugins ({lines})")
+
+
+@dataclass(frozen=True, slots=True)
+class _Candidate:
+    """One plugin on its way to ``accept``, or the failure of one that could not even be built.
+
+    A failure travels with the others so it is reported where it was found, in discovery order, and not before or
+    after the plugins around it.
+    """
+
+    plugin: Plugin[Any] | None
+    origin: str
+    builtin: bool = False
+    label: str | None = None
+    error: BaseException | None = None
+    #: Whether it came from the program's own entry-point group, which is ahead of every installed plugin.
+    part: bool = False
+
+    @property
+    def name(self) -> str:
+        if self.plugin is None:
+            return f"\0failed:{self.origin}:{self.label}"
+        return self.plugin.name or self.origin or type(self.plugin).__name__
+
+    @property
+    def deps(self) -> tuple[str, ...]:
+        return tuple(self.plugin.deps) if self.plugin is not None else ()
 
 
 def run(
@@ -152,50 +211,193 @@ def run(
     *,
     builtins: Sequence[Plugin[Any]],
     entry_points: Iterable[EntryPoint] | None,
+    required: Sequence[str] = (),
+    terminal: bool = False,
 ) -> Plugins:
     """Feed the builtins, the enabled distributions and the single-file plugins to ``loader``, and return what it bundled.
 
-    The builtins go first, so a plugin that registers under one of their names replaces it in place.
+    The candidates are offered builtins first, then distributions, then files, and are activated in dependency order
+    (:mod:`~zettcode.engine.plugins.graph`): stable, so without ``deps`` that is the order they were offered in.
     Builtins always load, while ``[plugins] enabled`` only gates the distributions and the files.
+
+    Args:
+        required: Names of plugins the program cannot run without. A ``disable`` line that names one — or one of the
+            plugins it needs — is ignored and logged, and one that still did not load makes the call raise. A name is
+            matched against the entry-point name (the origin) as well as ``Plugin.name``, so a required plugin keeps
+            the two equal; one whose ``name`` differs cannot be pulled back in once disabled.
+        terminal: Whether the loader has a screen, which is what the parts in the ``zettcode.terminal`` group wait for.
+
+    Raises:
+        RequiredPluginError: A plugin in ``required`` is not loaded.
     """
+    candidates: list[_Candidate] = []
     for plugin in builtins:
-        loader.accept(plugin, origin=plugin.name or type(plugin).__name__, builtin=True)
-    loader.builtins_loaded()
+        candidates.append(_Candidate(plugin, plugin.name or type(plugin).__name__, builtin=True))
+        if candidates[-1].origin not in loader.builtins:
+            loader.builtins.append(candidates[-1].origin)
+    # Offered by origin, so the ones a ``disable`` line holds back can still be pulled in when the program needs them.
+    sources: dict[str, Callable[[], list[_Candidate]]] = {}
+    # With `[plugins] enabled = false` nothing is loaded but the parts of the program (the `zettcode.terminal` group,
+    # which that switch is not about) and the plugins the program requires.
+    points = tuple(entry_points) if entry_points is not None else installed_entry_points()
+    # The parts of the program that need a screen are for a loader that has one.
+    points = tuple(point for point in points if terminal or getattr(point, "group", None) != TERMINAL_PART_GROUP)
+    parts = {point.name for point in points if getattr(point, "group", None) == TERMINAL_PART_GROUP}
+    # The configuration file's own list and the switch file's, merged for the one caller that loads. The switch
+    # module cannot be imported here (it imports this one), so the union is written out; `off_names` is the same
+    # rule for the front ends.
+    disabled = set(config.disabled_plugins) | set(read_disabled_plugins(config.plugins_file))
+    #: Who has each name, and who asked for a name that was taken, so the second can be told why it did not load.
+    owners: dict[str, str] = {}
+    owners_dist: dict[str, str | None] = {}
+    taken: dict[str, list[str]] = {}
+    for point in points:
+        who = _described(point)
+        if point.name in sources:
+            # The program's parts come first, so a later plugin under the same name is the one that loses; it must
+            # not take the place of a part, a required one least of all. The same distribution listed twice (a stale
+            # `dist-info` beside an editable copy) is an environment quirk, not a clash.
+            if _distribution(point) is None or _distribution(point) != owners_dist.get(point.name):
+                taken.setdefault(point.name, []).append(who)
+            continue
+        owners[point.name] = who
+        owners_dist[point.name] = _distribution(point)
+        sources[point.name] = partial(_from_point, loader, point)
     if config.plugins_enabled:
-        points = tuple(entry_points) if entry_points is not None else installed_entry_points()
-        # The configuration file's own list and the switch file's, merged for the one caller that loads. The switch
-        # module cannot be imported here (it imports this one), so the union is written out; `off_names` is the same
-        # rule for the front ends.
-        disabled = set(config.disabled_plugins) | set(read_disabled_plugins(config.plugins_file))
-        for point in points:
-            if point.name in disabled:
+        for path in installed_files(config.plugins_dir):
+            if path.stem in sources:
+                taken.setdefault(path.stem, []).append(f"the file {path.name}")
                 continue
-            try:
-                plugin = _instantiate(point)
-            except KeyboardInterrupt:
-                raise
-            except BaseException as error:
-                loader.fail(point.name, error)
+            owners[path.stem] = f"the file {path.name}"
+            sources[path.stem] = partial(_from_file, loader, path)
+    held = {origin for origin in sources if origin in disabled or (not config.plugins_enabled and origin not in parts)}
+    for origin in sources:
+        if origin not in held:
+            candidates.extend(sources[origin]())
+    # A name on that list can only reach a distribution or a file, unless the program needs it: the plugins it lists
+    # as builtin loaded above, and the required ones, with what they need, are pulled in below. A line that names one
+    # does nothing, and a reader who wrote it is told so instead of left to think the part is off.
+    for origin in sorted(disabled & set(loader.builtins)):
+        logger.warning(
+            "plugins.required",
+            extra={"plugin": origin, "reason": "part of the program; [plugins] disable does not reach it"},
+        )
+    protected = set(required)
+    while True:
+        by_name = {candidate.name: candidate for candidate in candidates}
+        wanted: set[str] = set()
+        queue = [name for name in protected]
+        while queue:
+            name = queue.pop()
+            if name in wanted:
                 continue
-            loader.accept(plugin, origin=point.name)
-        for path in installed_files(config.plugins_dir):
-            origin = path.stem
+            wanted.add(name)
+            if name in by_name:
+                queue.extend(by_name[name].deps)
+        pulled = sorted(origin for origin in held if origin in wanted)
+        if not pulled:
+            break
+        for origin in pulled:
+            held.discard(origin)
             if origin in disabled:
+                logger.warning(
+                    "plugins.required",
+                    extra={
+                        "plugin": origin,
+                        "reason": "the program cannot run without it; [plugins] disable does not reach it",
+                    },
+                )
+            candidates.extend(sources[origin]())
+    # A name that was taken is reported only when the one that has it was actually offered: a part the reader switched
+    # off refused nothing, and its row on the plugins page says "off", not "failed".
+    for name, losers in taken.items():
+        if name in held:
+            continue
+        for who in losers:
+            # Not a failure of the plugin that has the name: it loaded, and its row says so. The loser has no row of
+            # its own (it shares the name, or is a file with nothing but the name), so it is written to the log.
+            logger.warning(
+                "plugins.name_taken",
+                extra={"plugin": name, "who": who, "reason": f"{owners[name]} already has the name {name!r}"},
+            )
+    ordered, refused = graph.order([graph.Node(c.name, c.deps) for c in candidates])
+    loaded: set[int] = set()
+    for index in sorted(refused):
+        candidate = candidates[index]
+        loader.fail(candidate.origin, refused[index], label=candidate.label)
+    names_loaded: set[str] = set()
+    for index in ordered:
+        candidate = candidates[index]
+        lost = next((dep for dep in candidate.deps if dep not in names_loaded), None)
+        if candidate.plugin is None:
+            assert candidate.error is not None
+            loader.fail(candidate.origin, candidate.error, label=candidate.label)
+        elif lost is not None:
+            # It was ready, but a plugin it needs failed to activate: the failure is that plugin's, and this one is
+            # reported as the casualty it is rather than activated without what it asked for.
+            loader.fail(candidate.origin, f"needs plugin {lost!r}, which cannot be loaded", label=candidate.label)
+        elif loader.accept(
+            candidate.plugin,
+            origin=candidate.origin,
+            builtin=candidate.builtin,
+            part=candidate.part,
+            label=candidate.label,
+        ):
+            loaded.add(index)
+            names_loaded.add(candidate.name)
+    # A required plugin is the program's own as much as a compiled-in one: no switch reaches it, and a list says so.
+    loader.builtins.extend(name for name in required if name not in loader.builtins)
+    if required:
+        have = {candidates[index].name for index in loaded}
+        absent: dict[str, str] = {}
+        for name in required:
+            if name in have:
                 continue
-            try:
-                plugins, failures = _file_plugins(path)
-            except KeyboardInterrupt:
-                raise
-            except BaseException as error:
-                loader.fail(origin, error)
-                continue
-            for class_name, failure in failures:
-                loader.fail(origin, failure, label=class_name)
-            for plugin in plugins:
-                loader.accept(plugin, origin=origin, label=type(plugin).__name__)
+            why = next((reason for origin, reason in loader.failed if origin == name), None)
+            absent[name] = why or "not installed"
+        if absent:
+            raise RequiredPluginError(absent)
     return loader.bundle()
 
 
+def _distribution(point: EntryPoint) -> str | None:
+    """Return the name of the distribution an entry point came from, or ``None`` when it does not say."""
+    dist = getattr(point, "dist", None)
+    name = getattr(dist, "name", None)
+    return re.sub(r"[-_.]+", "-", str(name)).lower() if name else None
+
+
+def _described(point: EntryPoint) -> str:
+    """Say who an entry point is, for a message that has to name what to uninstall."""
+    dist = _distribution(point)
+    value = getattr(point, "value", None)
+    return f"{point.name!r} ({dist or 'unknown distribution'}" + (f", {value})" if value else ")")
+
+
+def _from_point(loader: Loader, point: EntryPoint) -> list[_Candidate]:
+    """Resolve one entry point into a candidate; a failure is a candidate that carries it."""
+    part = getattr(point, "group", None) == TERMINAL_PART_GROUP
+    try:
+        return [_Candidate(_instantiate(point), point.name, part=part)]
+    except KeyboardInterrupt:
+        raise
+    except BaseException as error:
+        return [_Candidate(None, point.name, error=error, part=part)]
+
+
+def _from_file(loader: Loader, path: Path) -> list[_Candidate]:
+    """Import one single-file plugin into candidates; a failure is recorded and gives none."""
+    origin = path.stem
+    try:
+        plugins, failures = _file_plugins(path)
+    except KeyboardInterrupt:
+        raise
+    except BaseException as error:
+        return [_Candidate(None, origin, error=error)]
+    broken = [_Candidate(None, origin, label=class_name, error=failure) for class_name, failure in failures]
+    return [*broken, *(_Candidate(plugin, origin, label=type(plugin).__name__) for plugin in plugins)]
+
+
 class Loader:
     """Accumulate accepted plugins into the one bundle the application gets."""
 
@@ -212,6 +414,8 @@ class Loader:
         self.failed: list[tuple[str, str]] = []
         #: The origins of the compiled-in plugins, in load order, so a bundle can say which rows are the program's.
         self.builtins: list[str] = []
+        #: Whether the plugin being accepted is the program's own (built in, or one of its parts); read by ``merge``.
+        self.program = False
         self._identities: set[str] = set()
         self._extension_names: set[str] = {HOST_NAME}
         self._mention_kinds: set[str] = set()
@@ -269,9 +473,6 @@ class Loader:
         self.mentions.extend(context.mentions)
         self.plain_commands.extend(context.commands.commands)
 
-    def builtins_loaded(self) -> None:
-        """Called once the builtin plugins have all been offered, before any distribution."""
-
     def bundle(self) -> Plugins:
         """Return everything the accepted plugins contributed."""
         host = PluginExtension(self.plugins) if self.plugins else None
@@ -293,15 +494,30 @@ class Loader:
         reason = _reason(error)
         self.failed.append((origin, f"{label}: {reason}" if label else reason))
 
-    def accept(self, plugin: Plugin[Any], *, origin: str, builtin: bool = False, label: str | None = None) -> None:
+    def accept(
+        self,
+        plugin: Plugin[Any],
+        *,
+        origin: str,
+        builtin: bool = False,
+        part: bool = False,
+        label: str | None = None,
+    ) -> bool:
         """Activate one plugin and merge what it registered, or report why not.
 
+        Returns:
+            Whether the plugin was activated and merged.
+
         Args:
             plugin: The plugin to activate.
             origin: The name of the distribution (or of the compiled-in plugin) it came from.
             builtin: Whether it is compiled into the program, which is what makes it impossible to switch off.
+            part: Whether it is one of the program's own parts (the ``zettcode.terminal`` group). Unlike a builtin it
+                can be switched off, unless the loader's caller requires it; what it registers is the program's own,
+                which is what :attr:`program` tells :meth:`merge` while it runs.
             label: The class name, when this plugin came from a file that can hold several; a failure says which.
         """
+        self.program = builtin or part
         name = plugin.name or origin or type(plugin).__name__
         if builtin and origin not in self.builtins:
             # Recorded before it is activated: a compiled-in plugin is the program's own whether or not it loaded,
@@ -315,10 +531,10 @@ class Loader:
                 f"setting {plugin.setting.path} names no boolean setting of the configuration",
                 label=label,
             )
-            return
+            return False
         if name in self._identities:
             self.fail(origin, f"duplicate plugin name {name!r}", label=label)
-            return
+            return False
         if not plugin.name:
             plugin.name = name
         if not plugin.origin:
@@ -331,14 +547,15 @@ class Loader:
             raise
         except BaseException as error:
             self.fail(origin, error, label=label)
-            return
+            return False
         clash = self.clash(container)
         if clash is not None:
             self.fail(origin, clash, label=label)
-            return
+            return False
         self._identities.add(name)
         self.merge(container)
         self.plugins.append(plugin)
+        return True
 
 
 def _is_bool_setting(config: ZettCodeConfig, setting: PluginSetting) -> bool:

{zettcode_engine-0.3.4 → zettcode_engine-0.4.0}/src/zettcode/engine/plugins/plugin.py

@@ -90,6 +90,9 @@ class Plugin(PluginAgentMixin, Generic[_C], ABC):
     #: switch file are matched against it.
     origin: str = ""
     description: ClassVar[str] = ""
+    #: The names of the plugins this one needs. The loader activates a plugin after every plugin it lists, and
+    #: leaves it out, reported, when one of them is absent, turned off, failed, or the lists go round in a circle.
+    deps: ClassVar[tuple[str, ...]] = ()
     priority: ClassVar[int] = 100
     #: The configuration key that decides whether a compiled-in plugin does its work, or ``None`` when there is none:
     #: a plugin the reader cannot turn off is left out of the list rather than shown without a switch.

{zettcode_engine-0.3.4 → zettcode_engine-0.4.0}/src/zettcode/engine/plugins/switches.py

@@ -123,8 +123,15 @@ def catalog(
     points = tuple(entry_points) if entry_points is not None else loader.installed_entry_points()
     seen = {entry.origin for entry in installed} | {origin for origin, _why in bundle.failed}
     for point in points:
-        if point.name not in seen:
-            installed.append(_installed(point.name, point.name, config, off=off))
+        # A required plugin has an entry point and is the program's own: it is not a row nobody can move.
+        if point.name in seen or point.name in builtins:
+            continue
+        # A part for a screen is listed by a process that has one. A bundle that holds none of it (the SDK, the
+        # server) is not offering switches for things it never loads — unless one is switched off, which is the one
+        # state in which a part is absent from a bundle that would have it.
+        if getattr(point, "group", None) == loader.TERMINAL_PART_GROUP and point.name not in off:
+            continue
+        installed.append(_installed(point.name, point.name, config, off=off))
     # A single-file plugin that is switched off is not in the bundle (the loader never imported it), so the folder is
     # what says it exists: it stays on the page, off, where it can be switched back on.
     for path in loader.installed_files(config.plugins_dir):

{zettcode_engine-0.3.4 → zettcode_engine-0.4.0}/src/zettcode/plugin_tui.py

@@ -62,8 +62,8 @@ class TuiGroup(ABC):
     ) -> Any:
         """Add a command that may open a page, ask the shell to act, or wait for a request to end.
 
-        ``handler`` is called with a :class:`~zettcode.app.commands.CommandContext` and returns a
-        :class:`~zettcode.app.commands.CommandResult`. A command whose whole answer is text belongs on
+        ``handler`` is called with a :class:`~zettcode.plugin_api.CommandContext` and returns a
+        :class:`~zettcode.plugin_api.CommandResult`. A command whose whole answer is text belongs on
         ``ctx.commands`` instead, where a process without a screen can run it too.
         """
 

{zettcode_engine-0.3.4 → zettcode_engine-0.4.0}/src/zettcode/version.py

@@ -8,4 +8,4 @@ of the dependency graph: everything else may import `zettcode.version`, nothing
 from __future__ import annotations
 
 #: The version of the program and of every distribution built beside it.
-__version__ = "0.3.4"
+__version__ = "0.4.0"