monosmith-plugin-sdk 0.1.0__tar.gz

monosmith_plugin_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Russo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

monosmith_plugin_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: monosmith-plugin-sdk
+Version: 0.1.0
+Summary: The Python SDK for writing smith plugins: the protocol's types, the serve loop, a test host, the conformance checks, templating and key-order-keeping JSON editing. No runtime dependencies.
+Author: Eduardo Russo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/monosmith-app/monosmith/tree/main/packages/plugin-sdk-py#readme
+Project-URL: Documentation, https://github.com/monosmith-app/monosmith/blob/main/docs/plugins/creating/python-sdk.md
+Project-URL: Repository, https://github.com/monosmith-app/monosmith
+Project-URL: Issues, https://github.com/monosmith-app/monosmith/issues
+Keywords: smith,monosmith,plugin,sdk,json-rpc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# monosmith-plugin-sdk
+
+The Python SDK for writing [smith](https://github.com/monosmith-app/monosmith) plugins: the
+protocol's types, the serve loop, a host to test a plugin with, the conformance checks of
+`smith plugin check`, `[[ ]]` templating and JSON editing that keeps key order. No runtime
+dependencies; Python 3.10 or later; fully type-annotated.
+
+```sh
+pip install monosmith-plugin-sdk
+```
+
+A plugin is an object with `describe` and one method for each thing it does. The SDK frames the
+JSON-RPC messages, answers `initialize`, derives the capabilities from the methods the object has and
+keeps standard output for the protocol:
+
+```python
+from monosmith_plugin_sdk import contribute_to, serve, task
+
+
+class WidgetLint:
+    def describe(self, params):
+        return {
+            "plugin": {"name": "widget-lint", "version": "0.1.0"},
+            "kind": "convention",
+            "roles": ["structure"],
+            "languages": ["widget"],
+        }
+
+    def contribute(self, params):
+        return contribute_to(
+            params["projects"],
+            lambda project: {
+                "tasks": {"layout-check": task(["python", "check.py"], cache=True)},
+                "dependsOn": {"lint": ["layout-check"]},
+            },
+        )
+
+
+if __name__ == "__main__":
+    serve(WidgetLint())
+```
+
+Test it in-process, with the real handshake and framing, and run the same checks as
+`smith plugin check`:
+
+```python
+from monosmith_plugin_sdk import HostOptions, check_plugin, connect_in_process
+
+with connect_in_process(WidgetLint(), HostOptions(workspace_root=str(tmp_path))) as client:
+    report = check_plugin(client)
+    assert report.ok, report.failures()
+```
+
+The full guide and API reference:
+[The Python SDK](https://github.com/monosmith-app/monosmith/blob/main/docs/plugins/creating/python-sdk.md).
+Examples that use it:
+[`structure-layout-py`](https://github.com/monosmith-app/monosmith/tree/main/docs/examples/plugins/structure-layout-py),
+[`structure-scan-py`](https://github.com/monosmith-app/monosmith/tree/main/docs/examples/plugins/structure-scan-py) and
+[`language-widget-py`](https://github.com/monosmith-app/monosmith/tree/main/docs/examples/plugins/language-widget-py).
+
+## The protocol schema is the source of truth
+
+The types in `src/monosmith_plugin_sdk/protocol` are not written by hand. The Go types of the protocol
+(`packages/plugin-sdk/protocol`) are the source of truth; their JSON Schema is committed as
+[`packages/plugin-sdk/schema/protocol.schema.json`](../plugin-sdk/schema/protocol.schema.json), and
+`tools/generate_protocol` turns that into `protocol_types_contract.py` (a `TypedDict` per message, the
+methods table, the error codes) and `protocol_schema_contract.py` (the schema itself, which the wire codec
+and the host's capability check read at run time). After a change to the protocol:
+
+```sh
+smith run schema -p plugin-sdk          # the Go side writes the schema
+smith run generate -p plugin-sdk-py     # this side writes the types
+```
+
+A test (`tests/generate_protocol`) and `smith run generate-check -p plugin-sdk-py` fail when either file
+is stale. A test also fails when the schema has a method this SDK does not know how to serve
+(`PLUGIN_MEMBERS`), so a new method has to be given its place in the plugin object.
+
+## What is where
+
+| Folder of `src/monosmith_plugin_sdk` | What it holds |
+|---|---|
+| `protocol` | the generated types, the schema as data, `RpcError` |
+| `codec` | the wire form of the messages: key order, `omitempty`, sorted maps and escaping as the Go SDK writes them, so the bytes are equal; params shaped as the types promise |
+| `framing` | `Content-Length` framing over a byte stream |
+| `cancellation` | `CancelToken`, what a cancellable method watches |
+| `serve` | `serve`, `serve_streams` (a bounded pool of worker threads, `cancel` and the plugin's `concurrency`), the plugin protocols, capability derivation, standard input and output claimed for the protocol |
+| `concurrency` | what a declared `concurrency` means: one at a time by default, a count, or unlimited |
+| `host` | `start_plugin`, `connect_plugin`, `connect_in_process`, `PluginClient`: the host side, for tests; it keeps to the plugin's concurrency and cancels a call with a `CancelToken` |
+| `conformance` | `check_plugin`: the checks of `smith plugin check` |
+| `templating`, `jsondoc` | ports of the Go SDK's `templating` and `jsondoc` |
+| `tasks`, `scaffold`, `ci` | helpers to build the answers of contribute, generate and ci |
+| `build_dir`, `plugin_roles`, `plugin_refs`, `projects` | the protocol package's small functions: build directories, roles, plugin references, project kinds, manifests |
+
+The source is organised by vertical slices (`smith slices check` lints it); `tests/integration` holds the
+tests that start real processes: the examples under `smith plugin check` and in a throwaway workspace, and
+the compatibility test that a Python plugin, a TypeScript plugin and a Go plugin with the same logic answer
+with the same bytes.
+
+## Develop
+
+```sh
+smith run lint typecheck test build generate-check -p plugin-sdk-py
+```
+
+The integration tests need `smith`, `go` and `node` on the path and skip themselves without them (in CI,
+where they exist, a missing one fails the test). The package is released by smith from conventional
+commits, like the other packages of this repository.

monosmith_plugin_sdk-0.1.0/README.md

@@ -0,0 +1,108 @@
+# monosmith-plugin-sdk
+
+The Python SDK for writing [smith](https://github.com/monosmith-app/monosmith) plugins: the
+protocol's types, the serve loop, a host to test a plugin with, the conformance checks of
+`smith plugin check`, `[[ ]]` templating and JSON editing that keeps key order. No runtime
+dependencies; Python 3.10 or later; fully type-annotated.
+
+```sh
+pip install monosmith-plugin-sdk
+```
+
+A plugin is an object with `describe` and one method for each thing it does. The SDK frames the
+JSON-RPC messages, answers `initialize`, derives the capabilities from the methods the object has and
+keeps standard output for the protocol:
+
+```python
+from monosmith_plugin_sdk import contribute_to, serve, task
+
+
+class WidgetLint:
+    def describe(self, params):
+        return {
+            "plugin": {"name": "widget-lint", "version": "0.1.0"},
+            "kind": "convention",
+            "roles": ["structure"],
+            "languages": ["widget"],
+        }
+
+    def contribute(self, params):
+        return contribute_to(
+            params["projects"],
+            lambda project: {
+                "tasks": {"layout-check": task(["python", "check.py"], cache=True)},
+                "dependsOn": {"lint": ["layout-check"]},
+            },
+        )
+
+
+if __name__ == "__main__":
+    serve(WidgetLint())
+```
+
+Test it in-process, with the real handshake and framing, and run the same checks as
+`smith plugin check`:
+
+```python
+from monosmith_plugin_sdk import HostOptions, check_plugin, connect_in_process
+
+with connect_in_process(WidgetLint(), HostOptions(workspace_root=str(tmp_path))) as client:
+    report = check_plugin(client)
+    assert report.ok, report.failures()
+```
+
+The full guide and API reference:
+[The Python SDK](https://github.com/monosmith-app/monosmith/blob/main/docs/plugins/creating/python-sdk.md).
+Examples that use it:
+[`structure-layout-py`](https://github.com/monosmith-app/monosmith/tree/main/docs/examples/plugins/structure-layout-py),
+[`structure-scan-py`](https://github.com/monosmith-app/monosmith/tree/main/docs/examples/plugins/structure-scan-py) and
+[`language-widget-py`](https://github.com/monosmith-app/monosmith/tree/main/docs/examples/plugins/language-widget-py).
+
+## The protocol schema is the source of truth
+
+The types in `src/monosmith_plugin_sdk/protocol` are not written by hand. The Go types of the protocol
+(`packages/plugin-sdk/protocol`) are the source of truth; their JSON Schema is committed as
+[`packages/plugin-sdk/schema/protocol.schema.json`](../plugin-sdk/schema/protocol.schema.json), and
+`tools/generate_protocol` turns that into `protocol_types_contract.py` (a `TypedDict` per message, the
+methods table, the error codes) and `protocol_schema_contract.py` (the schema itself, which the wire codec
+and the host's capability check read at run time). After a change to the protocol:
+
+```sh
+smith run schema -p plugin-sdk          # the Go side writes the schema
+smith run generate -p plugin-sdk-py     # this side writes the types
+```
+
+A test (`tests/generate_protocol`) and `smith run generate-check -p plugin-sdk-py` fail when either file
+is stale. A test also fails when the schema has a method this SDK does not know how to serve
+(`PLUGIN_MEMBERS`), so a new method has to be given its place in the plugin object.
+
+## What is where
+
+| Folder of `src/monosmith_plugin_sdk` | What it holds |
+|---|---|
+| `protocol` | the generated types, the schema as data, `RpcError` |
+| `codec` | the wire form of the messages: key order, `omitempty`, sorted maps and escaping as the Go SDK writes them, so the bytes are equal; params shaped as the types promise |
+| `framing` | `Content-Length` framing over a byte stream |
+| `cancellation` | `CancelToken`, what a cancellable method watches |
+| `serve` | `serve`, `serve_streams` (a bounded pool of worker threads, `cancel` and the plugin's `concurrency`), the plugin protocols, capability derivation, standard input and output claimed for the protocol |
+| `concurrency` | what a declared `concurrency` means: one at a time by default, a count, or unlimited |
+| `host` | `start_plugin`, `connect_plugin`, `connect_in_process`, `PluginClient`: the host side, for tests; it keeps to the plugin's concurrency and cancels a call with a `CancelToken` |
+| `conformance` | `check_plugin`: the checks of `smith plugin check` |
+| `templating`, `jsondoc` | ports of the Go SDK's `templating` and `jsondoc` |
+| `tasks`, `scaffold`, `ci` | helpers to build the answers of contribute, generate and ci |
+| `build_dir`, `plugin_roles`, `plugin_refs`, `projects` | the protocol package's small functions: build directories, roles, plugin references, project kinds, manifests |
+
+The source is organised by vertical slices (`smith slices check` lints it); `tests/integration` holds the
+tests that start real processes: the examples under `smith plugin check` and in a throwaway workspace, and
+the compatibility test that a Python plugin, a TypeScript plugin and a Go plugin with the same logic answer
+with the same bytes.
+
+## Develop
+
+```sh
+smith run lint typecheck test build generate-check -p plugin-sdk-py
+```
+
+The integration tests need `smith`, `go` and `node` on the path and skip themselves without them (in CI,
+where they exist, a missing one fails the test). The package is released by smith from conventional
+commits, like the other packages of this repository.

monosmith_plugin_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "monosmith-plugin-sdk"
+version = "0.1.0"
+description = "The Python SDK for writing smith plugins: the protocol's types, the serve loop, a test host, the conformance checks, templating and key-order-keeping JSON editing. No runtime dependencies."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Eduardo Russo" }]
+keywords = ["smith", "monosmith", "plugin", "sdk", "json-rpc"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/monosmith-app/monosmith/tree/main/packages/plugin-sdk-py#readme"
+Documentation = "https://github.com/monosmith-app/monosmith/blob/main/docs/plugins/creating/python-sdk.md"
+Repository = "https://github.com/monosmith-app/monosmith"
+Issues = "https://github.com/monosmith-app/monosmith/issues"
+
+[tool.smith]
+kind = "package"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+monosmith_plugin_sdk = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# The tools folder (the schema generator) is a package at the project root; the tests
+# of slices with the same file name in different folders do not clash.
+pythonpath = ["."]
+addopts = "--import-mode=importlib"
+markers = ["integration: starts real processes (smith, go, the example plugins)"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src", "tools", "tests"]
+mypy_path = "src"
+explicit_package_bases = true
+warn_unreachable = true
+
+[tool.ruff]
+extend = "../../ruff.toml"
+# The SDK runs on Python 3.10 and later, whatever the workspace's own interpreter is.
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.format]
+# Written by tools/generate_protocol; the drift check compares them byte for byte.
+exclude = ["src/monosmith_plugin_sdk/protocol/protocol_*_contract.py"]

monosmith_plugin_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

monosmith_plugin_sdk-0.1.0/src/monosmith_plugin_sdk/__init__.py

@@ -0,0 +1,204 @@
+"""The Python SDK for writing smith plugins.
+
+A plugin is an object with `describe` and one method for each thing it does. `serve` frames the
+JSON-RPC messages, answers `initialize`, derives the capabilities from the methods the object has and
+keeps standard output for the protocol:
+
+    from monosmith_plugin_sdk import contribute_to, serve, task
+
+    class WidgetLint:
+        def describe(self, params):
+            return {"plugin": {"name": "widget-lint", "version": "0.1.0"}, "kind": "convention",
+                    "roles": ["structure"], "languages": ["widget"]}
+
+        def contribute(self, params):
+            return contribute_to(params["projects"], lambda project: {
+                "tasks": {"layout-check": task(["python", "check.py"], cache=True)},
+                "dependsOn": {"lint": ["layout-check"]},
+            })
+
+    if __name__ == "__main__":
+        serve(WidgetLint())
+
+Test it in-process, with the real handshake and framing, and run the checks of `smith plugin check`:
+
+    from monosmith_plugin_sdk import HostOptions, check_plugin, connect_in_process
+
+    with connect_in_process(WidgetLint(), HostOptions(workspace_root=str(tmp_path))) as client:
+        report = check_plugin(client)
+        assert report.ok, report.failures()
+
+The messages of the protocol are `TypedDict`s generated from the protocol's JSON Schema; the wire
+form is the one the Go and TypeScript SDKs write, byte for byte. No runtime dependencies.
+"""
+
+from . import protocol as _protocol
+from .build_dir import BUILD_DIR, build_dir_from_project, in_build_dir, project_build_dir
+from .cancellation import CancelToken, RequestCancelledError
+from .ci import action_step, ci_step, credential
+from .codec import (
+    EncodeError,
+    MessageParseError,
+    ParamsError,
+    decode_params,
+    decode_result,
+    encode_params,
+    encode_result,
+)
+from .concurrency import (
+    CONCURRENCY_UNLIMITED,
+    UNLIMITED_IN_FLIGHT,
+    UNLIMITED_WORKERS,
+    in_flight_limit,
+    is_valid_concurrency,
+    worker_limit,
+)
+from .conformance import CONFORMANCE_STACK, CheckResult, ConformanceReport, check_plugin
+from .framing import FrameReader, FramingError, frame_message
+from .host import (
+    DEFAULT_CALL_TIMEOUT,
+    DEFAULT_CANCEL_GRACE,
+    CallInterruptedError,
+    HostOptions,
+    PluginClient,
+    PluginStreams,
+    StartOptions,
+    connect_in_process,
+    connect_plugin,
+    start_plugin,
+)
+from .jsondoc import JsonDocument, JsonDocumentError
+from .plugin_refs import conflicts_with, describe_ref, is_empty_ref, requires_language
+from .plugin_roles import (
+    ROLES,
+    default_roles,
+    effective_roles,
+    is_additive_role,
+    is_exclusive_role,
+    is_known_role,
+)
+from .projects import (
+    audit_blocks,
+    audit_enabled,
+    is_manifest,
+    project_kind_directory,
+    publishes,
+    resolve_project_kind,
+    set_toolchain,
+    stack_plugins,
+)
+from .protocol import *  # noqa: F403
+from .scaffold import scaffold_data, scaffold_project
+from .serve import (
+    CIContributor,
+    Contributor,
+    DeclarationEditor,
+    DependencyManager,
+    Discoverer,
+    DoctorContributor,
+    Generator,
+    LatestReader,
+    Plugin,
+    Publisher,
+    RegistryReader,
+    Remover,
+    ServeStreams,
+    Versioner,
+    capabilities_of,
+    serve,
+    serve_streams,
+)
+from .tasks import build_task, contribute_to, task
+from .templating import TemplateError, TemplateFileExistsError, render_template, write_templates
+
+__all__ = [
+    *_protocol.__all__,
+    # Writing a plugin.
+    "serve",
+    "Plugin",
+    "Discoverer",
+    "Generator",
+    "Versioner",
+    "Publisher",
+    "RegistryReader",
+    "CIContributor",
+    "DoctorContributor",
+    "Remover",
+    "DependencyManager",
+    "DeclarationEditor",
+    "LatestReader",
+    "Contributor",
+    "CancelToken",
+    "RequestCancelledError",
+    "CONCURRENCY_UNLIMITED",
+    "task",
+    "build_task",
+    "contribute_to",
+    "scaffold_project",
+    "scaffold_data",
+    "action_step",
+    "ci_step",
+    "credential",
+    "BUILD_DIR",
+    "project_build_dir",
+    "build_dir_from_project",
+    "in_build_dir",
+    "ROLES",
+    "default_roles",
+    "effective_roles",
+    "is_known_role",
+    "is_exclusive_role",
+    "is_additive_role",
+    "requires_language",
+    "conflicts_with",
+    "describe_ref",
+    "is_empty_ref",
+    "audit_enabled",
+    "audit_blocks",
+    "is_manifest",
+    "project_kind_directory",
+    "publishes",
+    "resolve_project_kind",
+    "set_toolchain",
+    "stack_plugins",
+    "render_template",
+    "write_templates",
+    "TemplateError",
+    "TemplateFileExistsError",
+    "JsonDocument",
+    "JsonDocumentError",
+    # Testing a plugin.
+    "HostOptions",
+    "StartOptions",
+    "PluginClient",
+    "PluginStreams",
+    "CallInterruptedError",
+    "DEFAULT_CALL_TIMEOUT",
+    "DEFAULT_CANCEL_GRACE",
+    "start_plugin",
+    "connect_plugin",
+    "connect_in_process",
+    "check_plugin",
+    "ConformanceReport",
+    "CheckResult",
+    "CONFORMANCE_STACK",
+    # Building blocks: the wire form of the messages, for tools that speak the protocol themselves.
+    "serve_streams",
+    "ServeStreams",
+    "capabilities_of",
+    "decode_params",
+    "decode_result",
+    "encode_params",
+    "encode_result",
+    "EncodeError",
+    "MessageParseError",
+    "ParamsError",
+    "FrameReader",
+    "FramingError",
+    "frame_message",
+    "UNLIMITED_IN_FLIGHT",
+    "UNLIMITED_WORKERS",
+    "in_flight_limit",
+    "is_valid_concurrency",
+    "worker_limit",
+]

monosmith_plugin_sdk-0.1.0/src/monosmith_plugin_sdk/build_dir/__init__.py

@@ -0,0 +1,5 @@
+"""The directory every build writes into."""
+
+from .build_dir_algorithm import BUILD_DIR, build_dir_from_project, in_build_dir, project_build_dir
+
+__all__ = ["BUILD_DIR", "build_dir_from_project", "in_build_dir", "project_build_dir"]

monosmith_plugin_sdk-0.1.0/src/monosmith_plugin_sdk/build_dir/build_dir_algorithm.py

@@ -0,0 +1,30 @@
+"""Where every build writes its output."""
+
+from __future__ import annotations
+
+BUILD_DIR = "dist"
+"""The directory at the workspace root every build writes into.
+
+It is smith's opinion, so all output is in one place, outside every source tree, and cleaning is
+deleting one folder. A plugin builds a project into `project_build_dir`; `smith doctor` fails a task
+whose outputs fall outside it.
+"""
+
+
+def project_build_dir(root: str) -> str:
+    """Where a project's build goes, workspace-relative: `dist/<project dir>` (`dist/apps/web`)."""
+    return f"{BUILD_DIR}/{root.strip('/')}"
+
+
+def build_dir_from_project(root: str) -> str:
+    """The same directory relative to the project (`../../dist/apps/web`).
+
+    It is what a tool configured from inside the project, or a task's `outputs`, name.
+    """
+    trimmed = root.strip("/")
+    return "../" * len(trimmed.split("/")) + project_build_dir(trimmed)
+
+
+def in_build_dir(path: str) -> bool:
+    """Whether a workspace-relative path is inside the build directory."""
+    return path == BUILD_DIR or path.startswith(f"{BUILD_DIR}/")

monosmith_plugin_sdk-0.1.0/src/monosmith_plugin_sdk/cancellation/__init__.py

@@ -0,0 +1,6 @@
+"""Cooperative cancellation: the token a method watches, and the error it raises when it stops."""
+
+from .cancel_token_model import CancelToken
+from .request_cancelled_error import RequestCancelledError
+
+__all__ = ["CancelToken", "RequestCancelledError"]

monosmith_plugin_sdk-0.1.0/src/monosmith_plugin_sdk/cancellation/cancel_token_model.py

@@ -0,0 +1,75 @@
+"""The token that carries a cancel to the work it concerns."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+
+from .request_cancelled_error import RequestCancelledError
+
+
+class CancelToken:
+    """A flag one thread sets and another watches, to stop work cooperatively.
+
+    The serve loop gives a method one for the request it is answering, and sets it when the
+    host sends `cancel` for the request (or when the plugin shuts down). A host in a test
+    passes one to `PluginClient.call` and sets it to cancel the call.
+
+    The usual loop checks it between steps, and waits on it instead of sleeping:
+
+        for path in files:
+            cancel.raise_if_cancelled()
+            scan(path)
+        if cancel.wait(0.1):   # sleeps up to 0.1 s, and wakes at once on a cancel
+            return partial_result
+    """
+
+    def __init__(self) -> None:
+        self._event = threading.Event()
+        self._lock = threading.Lock()
+        self._callbacks: list[Callable[[], None]] = []
+
+    @property
+    def cancelled(self) -> bool:
+        """Whether the work was asked to stop."""
+        return self._event.is_set()
+
+    def cancel(self) -> None:
+        """Ask the work to stop. Calling it again does nothing."""
+        with self._lock:
+            if self._event.is_set():
+                return
+            self._event.set()
+            callbacks, self._callbacks = self._callbacks, []
+        for callback in callbacks:
+            callback()
+
+    def wait(self, timeout: float | None = None) -> bool:
+        """Wait up to `timeout` seconds (forever for `None`); return whether it was cancelled.
+
+        A cancellable sleep: it returns early, with `True`, the moment the token is cancelled.
+        """
+        return self._event.wait(timeout)
+
+    def raise_if_cancelled(self, message: str = "the request was cancelled") -> None:
+        """Raise `RequestCancelledError` when the work was asked to stop."""
+        if self._event.is_set():
+            raise RequestCancelledError(message)
+
+    def on_cancel(self, callback: Callable[[], None]) -> Callable[[], None]:
+        """Call `callback` (in the cancelling thread) when the token is cancelled, at once if it already is.
+
+        Returns a function that removes the callback again.
+        """
+        with self._lock:
+            if not self._event.is_set():
+                self._callbacks.append(callback)
+
+                def remove() -> None:
+                    with self._lock:
+                        if callback in self._callbacks:
+                            self._callbacks.remove(callback)
+
+                return remove
+        callback()
+        return lambda: None

monosmith_plugin_sdk-0.1.0/src/monosmith_plugin_sdk/cancellation/request_cancelled_error.py

@@ -0,0 +1,11 @@
+"""The error a method raises to say it stopped because the request was cancelled."""
+
+from __future__ import annotations
+
+
+class RequestCancelledError(Exception):
+    """Raised by a method that noticed its request was cancelled (`CancelToken.raise_if_cancelled`).
+
+    The serve loop answers a cancelled request that fails with any error with the code
+    `REQUEST_CANCELLED`, so raising this is a convenience, not a requirement.
+    """