vitruvian-tool-kit 0.10.0__tar.gz

vitruvian_tool_kit-0.10.0/.gitignore

@@ -0,0 +1,2 @@
+.build/
+.swiftpm/

vitruvian_tool_kit-0.10.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VitruvianSoftware
+
+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.

vitruvian_tool_kit-0.10.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: vitruvian-tool-kit
+Version: 0.10.0
+Summary: Write a tool for the Vitruvian app in Python: declare its commands, handle them, call the app.
+Project-URL: Repository, https://github.com/VitruvianSoftware/vitruvian-sdk
+Project-URL: Documentation, https://github.com/VitruvianSoftware/vitruvian-sdk/blob/main/docs/writing-a-tool.md
+Author: VitruvianSoftware
+License-Expression: MIT
+License-File: LICENSE
+Keywords: json-rpc,macos,tool,vitruvian
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# vitruvian-tool-kit
+
+Write a tool for the [Vitruvian](https://vitruviansoftware.dev) Mac app in
+Python. A tool is a folder with a `vitruvian-tool.json` and a program; the app
+starts the program and talks to it over its standard input and output. This
+kit is that conversation: you say what each command does, and call the app
+from inside a command as an ordinary function call.
+
+```python
+from vitruvian_tool_kit import Tool
+
+tool = Tool(version="0.1.0")
+
+
+@tool.command("hello")
+def hello(app):
+    app.notify.hud(icon="hand.wave", message="Hello")
+
+
+tool.run()
+```
+
+- **One call per message.** `app.notify.hud(...)`, `app.clipboard.read_text()`,
+  `app.storage.get(key=...)`: each is one request of the protocol, named as
+  the protocol names it. The app may refuse any of them; the call then raises
+  `Refusal`. Raise `CommandRefused("why")` to refuse a command yourself.
+- **Synchronous, on one thread.** A call to the app waits for its answer, ten
+  seconds at most. A handler must not be `async`.
+- **Never `print`.** Standard output is the link to the app. Write to
+  standard error, or call `app.log(message=...)`.
+
+## Shipping it
+
+The app starts a tool with Apple's `python3` (`/usr/bin/python3`, Python
+3.9), which has none of your packages. So the kit goes inside the tool's
+folder, and the program finds it there:
+
+```sh
+python3 -m pip install --target lib vitruvian-tool-kit
+```
+
+```python
+import os, sys
+
+HERE = os.path.dirname(os.path.realpath(__file__))
+sys.path.insert(0, os.path.join(HERE, "..", "lib"))
+```
+
+`vitruvian-tool init --template python-kit` writes a tool set up this way.
+The kit needs nothing but the standard library and Python 3.9 or later.
+
+The whole guide, the protocol and the other kits are in
+[the SDK](https://github.com/VitruvianSoftware/vitruvian-sdk). MIT licence.

vitruvian_tool_kit-0.10.0/README.md

@@ -0,0 +1,53 @@
+# vitruvian-tool-kit
+
+Write a tool for the [Vitruvian](https://vitruviansoftware.dev) Mac app in
+Python. A tool is a folder with a `vitruvian-tool.json` and a program; the app
+starts the program and talks to it over its standard input and output. This
+kit is that conversation: you say what each command does, and call the app
+from inside a command as an ordinary function call.
+
+```python
+from vitruvian_tool_kit import Tool
+
+tool = Tool(version="0.1.0")
+
+
+@tool.command("hello")
+def hello(app):
+    app.notify.hud(icon="hand.wave", message="Hello")
+
+
+tool.run()
+```
+
+- **One call per message.** `app.notify.hud(...)`, `app.clipboard.read_text()`,
+  `app.storage.get(key=...)`: each is one request of the protocol, named as
+  the protocol names it. The app may refuse any of them; the call then raises
+  `Refusal`. Raise `CommandRefused("why")` to refuse a command yourself.
+- **Synchronous, on one thread.** A call to the app waits for its answer, ten
+  seconds at most. A handler must not be `async`.
+- **Never `print`.** Standard output is the link to the app. Write to
+  standard error, or call `app.log(message=...)`.
+
+## Shipping it
+
+The app starts a tool with Apple's `python3` (`/usr/bin/python3`, Python
+3.9), which has none of your packages. So the kit goes inside the tool's
+folder, and the program finds it there:
+
+```sh
+python3 -m pip install --target lib vitruvian-tool-kit
+```
+
+```python
+import os, sys
+
+HERE = os.path.dirname(os.path.realpath(__file__))
+sys.path.insert(0, os.path.join(HERE, "..", "lib"))
+```
+
+`vitruvian-tool init --template python-kit` writes a tool set up this way.
+The kit needs nothing but the standard library and Python 3.9 or later.
+
+The whole guide, the protocol and the other kits are in
+[the SDK](https://github.com/VitruvianSoftware/vitruvian-sdk). MIT licence.

vitruvian_tool_kit-0.10.0/pyproject.toml

@@ -0,0 +1,53 @@
+# Copyright (c) 2026 VitruvianSoftware
+#
+# 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.
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vitruvian-tool-kit"
+# The SDK's version: every kit is published at it on every release
+# (release-please, component vitruvian-sdk).
+version = "0.10.0"
+description = "Write a tool for the Vitruvian app in Python: declare its commands, handle them, call the app."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+# 3.9: the python3 the Command Line Tools put on every Mac, which is the one
+# the app finds when it starts a tool. The standard library only.
+requires-python = ">=3.9"
+authors = [{ name = "VitruvianSoftware" }]
+keywords = ["vitruvian", "macos", "tool", "json-rpc"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: MacOS",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/VitruvianSoftware/vitruvian-sdk"
+Documentation = "https://github.com/VitruvianSoftware/vitruvian-sdk/blob/main/docs/writing-a-tool.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["vitruvian_tool_kit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["vitruvian_tool_kit", "tests", "README.md", "LICENSE"]

vitruvian_tool_kit-0.10.0/tests/test_generated.py

@@ -0,0 +1,114 @@
+# Copyright (c) 2026 VitruvianSoftware
+#
+# 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.
+"""The generated types read every example the protocol calls valid, and give
+back what they read.
+
+protocol/examples/ is what the schemas and the Swift types are both held to
+(protocol_examples_test.py, ProtocolExamplesTests.swift). Reading the same
+files here holds the generated Python to them too: a field the generator
+dropped or misnamed fails here, by the example's own words.
+"""
+
+import json
+import os
+import sys
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+PROTOCOL = os.path.join(HERE, "..", "..", "..", "protocol")
+
+from vitruvian_tool_kit import METHODS, ShapeError, ToolManifest  # noqa: E402
+from vitruvian_tool_kit.generated import messages  # noqa: E402
+
+
+def load(name):
+    with open(os.path.join(PROTOCOL, name), encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def type_named(name):
+    title = {"empty": "EmptyObject", "error": "RPCErrorObject"}.get(
+        name, name[:1].upper() + name[1:]
+    )
+    return getattr(messages, title)
+
+
+class GeneratedTests(unittest.TestCase):
+    def test_every_valid_message_reads_and_writes_back(self):
+        """What is written back is what was read, less a field the schema does
+        not name: the protocol says such a field is ignored."""
+        table = {m.method: m for m in METHODS}
+        named = {
+            name: set(node.get("properties", {}))
+            for name, node in load("messages.schema.json")["$defs"].items()
+        }
+
+        def known(name, value):
+            return {key: item for key, item in value.items() if key in named[name]}
+
+        read = 0
+        for example in load("examples/messages.json")["examples"]:
+            if not example["valid"]:
+                continue
+            message = example["message"]
+            row = table.get(example.get("answers", message.get("method")))
+            if row is None:
+                continue
+            with self.subTest(example["about"]):
+                if "method" in message and row.params:
+                    value = type_named(row.params).from_json(message.get("params"))
+                    self.assertEqual(
+                        value.to_json(), known(row.params, message["params"])
+                    )
+                    read += 1
+                elif "result" in message:
+                    value = type_named(row.result).from_json(message["result"])
+                    self.assertEqual(
+                        value.to_json(), known(row.result, message["result"])
+                    )
+                    read += 1
+        self.assertGreater(read, 20)
+
+    def test_a_wrong_field_is_named(self):
+        with self.assertRaises(ShapeError) as raised:
+            messages.NotifyHUDParams.from_json({"icon": "x", "message": 3})
+        self.assertEqual(raised.exception.where, "notifyHUDParams.message")
+
+    def test_every_valid_manifest_reads(self):
+        examples = load("examples/manifests.json")
+        read = 0
+        for example in examples["examples"]:
+            if not example["valid"]:
+                continue
+            manifest = dict(examples["base"])
+            for key, value in example["change"].items():
+                if value is None:
+                    manifest.pop(key, None)
+                else:
+                    manifest[key] = value
+            with self.subTest(example["about"]):
+                ToolManifest.from_json(manifest)
+                read += 1
+        self.assertGreater(read, 5)
+
+
+if __name__ == "__main__":
+    unittest.main()