zettcode-plugin-api 0.4.0__tar.gz

zettcode_plugin_api-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_plugin_api-0.4.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: zettcode-plugin-api
+Version: 0.4.0
+Summary: The one package a ZettCode plugin depends on: the plugin surface, re-exported
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: api,plugin,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: zettcode-engine
+Requires-Dist: zettcode-tui
+Provides-Extra: types
+Requires-Dist: zettcode-sdk; extra == 'types'

zettcode_plugin_api-0.4.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "zettcode-plugin-api"
+description = "The one package a ZettCode plugin depends on: the plugin surface, re-exported"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "plugin", "api"]
+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 = [
+  # The bottom of the graph a plugin lives in: the runtime it hooks into and the widgets it draws with. Never the
+  # application, never an implementation of what this package defines, and not the SDK -- see the extra below.
+  "zettcode-engine",
+  "zettcode-tui",
+]
+
+[project.optional-dependencies]
+# `host.client` is the SDK's client and a hook is handed its `Usage` and `ModelInfo`, so a plugin that is type-checked
+# needs the SDK to resolve those names. Nothing is *imported* from it at run time (every one is a `TYPE_CHECKING`
+# reference, and the contract's names all resolve with the SDK unimportable), so a plugin that only runs does not pull
+# the broker's web stack in for it: it asks for this extra when it wants its types.
+types = ["zettcode-sdk"]
+
+[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_plugin_api-0.4.0/src/zettcode/plugin_api/__init__.py

@@ -0,0 +1,330 @@
+"""What a plugin imports: the contract, and the one dependency it needs.
+
+A ZettCode plugin is a class published under the ``zettcode.plugins`` entry point, and everything it may touch is
+re-exported here: the base classes and hooks of the agent side and of the terminal's rows, the command a handler returns,
+the row model and the presenter it implements, the pet format, the link to the shell, and the few widgets a panel is
+drawn with.
+
+This package is the bottom of the graph a plugin lives in. The engine, the widget framework and the SDK are what it
+needs; it imports neither the terminal application nor any implementation of the contracts it defines. The built-in rows
+(`zettcode-presenters`), the shell and the loader that builds ``ctx.tui`` (`zettcode-app`) are written *against* it, which
+is what lets a plugin and the program replace each other's parts without either importing the other.
+
+The names are resolved on first use, like the program's other facades: importing one row constant must not pull the
+settings, the runtime and a provider SDK in with it, because the boot frame is drawn before any of them exist.
+
+The names are the ones the guide shows in `docs/guide/plugins.md`. They are re-exports, not a second definition, so a
+plugin and the program cannot disagree about a signature.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+#: Where each public name lives; read by :func:`__getattr__` on first use.
+_EXPORTS = {
+    "Activity": ".state",
+    "ActivityState": ".state",
+    "AgentBuild": "zettcode.engine.plugins",
+    "BusyPolicy": ".commands",
+    "CONTENT_INDENT": ".presenters",
+    "Canvas": "zettcode.tui",
+    "ChangesEntry": ".entries",
+    "Command": ".commands",
+    "CommandAgent": ".commands",
+    "CommandContext": ".commands",
+    "CommandHandler": ".commands",
+    "CommandHost": ".commands",
+    "CommandList": ".commands",
+    "CommandProvider": ".commands",
+    "CommandResult": ".commands",
+    "CommandTranscript": ".commands",
+    "CommandUi": ".commands",
+    "Contribution": "zettcode.engine.plugins",
+    "DeleteEntry": ".entries",
+    "DisplayState": ".state",
+    "EditEntry": ".entries",
+    "Entry": ".entries",
+    "EntryKind": ".entries",
+    "EntryStatus": ".entries",
+    "ExtensionFactory": "zettcode.engine.plugins",
+    "FileChangeEntry": ".entries",
+    "FileSummary": ".entries",
+    "HOST_LINK": ".host",
+    "Host": "zettcode.tui",
+    "HostLink": ".host",
+    "MarkdownEntry": ".entries",
+    "Mention": "zettcode.mention",
+    "MentionProvider": "zettcode.mention",
+    "MessageEntry": ".entries",
+    "ModelConfig": "zettcode.config",
+    "ModelState": ".state",
+    "MouseAction": "zettcode.tui",
+    "MouseEvent": "zettcode.tui",
+    "NoticeLevel": ".entries",
+    "Pet": ".pets",
+    "PetSource": ".pets",
+    "PlainCommandContext": "zettcode.engine.plugins.commands",
+    "Plugin": "zettcode.engine.plugins",
+    "PluginAgentMixin": "zettcode.engine.plugins",
+    "PluginContext": "zettcode.engine.plugins",
+    "PluginEventMixin": "zettcode.engine.plugins",
+    "PluginExtension": "zettcode.engine.plugins",
+    "PluginMaintenanceMixin": "zettcode.engine.plugins",
+    "PluginMiddlewareMixin": "zettcode.engine.plugins",
+    "PluginModelMixin": "zettcode.engine.plugins",
+    "PluginRunMixin": "zettcode.engine.plugins",
+    "PluginSetting": "zettcode.engine.plugins",
+    "PluginSetupMixin": "zettcode.engine.plugins",
+    "PluginToolMixin": "zettcode.engine.plugins",
+    "PluginTurnMixin": "zettcode.engine.plugins",
+    "PluginUiMixin": ".mixins",
+    "Plugins": "zettcode.engine.plugins",
+    "Presenter": ".presenters",
+    "Presenters": ".presenters",
+    "Provider": "zettcode.providers",
+    "Rail": ".switch",
+    "ReadEntry": ".entries",
+    "Registry": "zettcode.registry",
+    "RelayEntry": ".entries",
+    "Row": ".rows",
+    "SWITCH_WIDTH": ".switch",
+    "SessionState": ".state",
+    "ShellContext": ".state",
+    "Span": "zettcode.tui",
+    "Style": "zettcode.tui",
+    "Subcommand": ".commands",
+    "TextCommandResult": "zettcode.engine.plugins.commands",
+    "TextEntry": ".entries",
+    "TextLine": "zettcode.tui",
+    "ThinkingEntry": ".entries",
+    "ToolEntry": ".entries",
+    "TuiGroup": "zettcode.plugin_tui",
+    "TuiPlugin": ".plugin",
+    "TuiPlugins": ".plugin",
+    "TurnCommandResult": "zettcode.engine.plugins.commands",
+    "TurnSegment": ".state",
+    "UiBuilder": ".state",
+    "UiRegion": ".state",
+    "UiRow": ".state",
+    "UiSegment": ".state",
+    "UiSide": ".state",
+    "WaitEntry": ".entries",
+    "Widget": "zettcode.tui",
+    "WriteEntry": ".entries",
+    "ZettCodeConfig": "zettcode.config",
+    "blend": "zettcode.tui.render",
+    "bottom_panel": ".panels",
+    "display_width": "zettcode.tui.render",
+    "draw_switch": ".switch",
+    "pressed": ".panels",
+    "truncate": "zettcode.tui.render",
+}
+
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
+    from zettcode.config import ModelConfig, ZettCodeConfig
+    from zettcode.engine.plugins import (
+        AgentBuild,
+        Contribution,
+        ExtensionFactory,
+        Plugin,
+        PluginAgentMixin,
+        PluginContext,
+        PluginEventMixin,
+        PluginExtension,
+        PluginMaintenanceMixin,
+        PluginMiddlewareMixin,
+        PluginModelMixin,
+        PluginRunMixin,
+        Plugins,
+        PluginSetting,
+        PluginSetupMixin,
+        PluginToolMixin,
+        PluginTurnMixin,
+    )
+    from zettcode.engine.plugins.commands import PlainCommandContext, TextCommandResult, TurnCommandResult
+    from zettcode.mention import Mention, MentionProvider
+    from zettcode.plugin_tui import TuiGroup
+    from zettcode.providers import Provider
+    from zettcode.registry import Registry
+    from zettcode.tui import Canvas, Host, MouseAction, MouseEvent, Span, Style, TextLine, Widget
+    from zettcode.tui.render import blend, display_width, truncate
+
+    from .commands import (
+        BusyPolicy,
+        Command,
+        CommandAgent,
+        CommandContext,
+        CommandHandler,
+        CommandHost,
+        CommandList,
+        CommandProvider,
+        CommandResult,
+        CommandTranscript,
+        CommandUi,
+        Subcommand,
+    )
+    from .entries import (
+        ChangesEntry,
+        DeleteEntry,
+        EditEntry,
+        Entry,
+        EntryKind,
+        EntryStatus,
+        FileChangeEntry,
+        FileSummary,
+        MarkdownEntry,
+        MessageEntry,
+        NoticeLevel,
+        ReadEntry,
+        RelayEntry,
+        TextEntry,
+        ThinkingEntry,
+        ToolEntry,
+        WaitEntry,
+        WriteEntry,
+    )
+    from .host import HOST_LINK, HostLink
+    from .mixins import PluginUiMixin
+    from .panels import bottom_panel, pressed
+    from .pets import Pet, PetSource
+    from .plugin import TuiPlugin, TuiPlugins
+    from .presenters import CONTENT_INDENT, Presenter, Presenters
+    from .rows import Row
+    from .state import (
+        Activity,
+        ActivityState,
+        DisplayState,
+        ModelState,
+        SessionState,
+        ShellContext,
+        TurnSegment,
+        UiBuilder,
+        UiRegion,
+        UiRow,
+        UiSegment,
+        UiSide,
+    )
+    from .switch import SWITCH_WIDTH, Rail, draw_switch
+
+
+def __getattr__(name: str) -> Any:
+    """Import the module a public name lives in, the first time it is asked for.
+
+    Args:
+        name: The public name the plugin asked for.
+
+    Returns:
+        What that module defines under the name.
+
+    Raises:
+        AttributeError: The package has no such name.
+    """
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(module, __name__), name)
+    globals()[name] = value
+    return value
+
+
+__all__ = [
+    "Activity",
+    "ActivityState",
+    "AgentBuild",
+    "BusyPolicy",
+    "CONTENT_INDENT",
+    "Canvas",
+    "ChangesEntry",
+    "Command",
+    "CommandAgent",
+    "CommandContext",
+    "CommandHandler",
+    "CommandHost",
+    "CommandList",
+    "CommandProvider",
+    "CommandResult",
+    "CommandTranscript",
+    "CommandUi",
+    "Contribution",
+    "DeleteEntry",
+    "DisplayState",
+    "EditEntry",
+    "Entry",
+    "EntryKind",
+    "EntryStatus",
+    "ExtensionFactory",
+    "FileChangeEntry",
+    "FileSummary",
+    "HOST_LINK",
+    "Host",
+    "HostLink",
+    "MarkdownEntry",
+    "Mention",
+    "MentionProvider",
+    "MessageEntry",
+    "ModelConfig",
+    "ModelState",
+    "MouseAction",
+    "MouseEvent",
+    "NoticeLevel",
+    "Pet",
+    "PetSource",
+    "PlainCommandContext",
+    "Plugin",
+    "PluginAgentMixin",
+    "PluginContext",
+    "PluginEventMixin",
+    "PluginExtension",
+    "PluginMaintenanceMixin",
+    "PluginMiddlewareMixin",
+    "PluginModelMixin",
+    "PluginRunMixin",
+    "PluginSetting",
+    "PluginSetupMixin",
+    "PluginToolMixin",
+    "PluginTurnMixin",
+    "PluginUiMixin",
+    "Plugins",
+    "Presenter",
+    "Presenters",
+    "Provider",
+    "Rail",
+    "ReadEntry",
+    "Registry",
+    "RelayEntry",
+    "Row",
+    "SWITCH_WIDTH",
+    "SessionState",
+    "ShellContext",
+    "Span",
+    "Style",
+    "Subcommand",
+    "TextCommandResult",
+    "TextEntry",
+    "TextLine",
+    "ThinkingEntry",
+    "ToolEntry",
+    "TuiGroup",
+    "TuiPlugin",
+    "TuiPlugins",
+    "TurnCommandResult",
+    "TurnSegment",
+    "UiBuilder",
+    "UiRegion",
+    "UiRow",
+    "UiSegment",
+    "UiSide",
+    "WaitEntry",
+    "Widget",
+    "WriteEntry",
+    "ZettCodeConfig",
+    "blend",
+    "bottom_panel",
+    "display_width",
+    "draw_switch",
+    "pressed",
+    "truncate",
+]