branchkit 0.2.0__tar.gz → 0.3.0__tar.gz

{branchkit-0.2.0 → branchkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: branchkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: BranchKit plugin SDK for Python
 Author: BranchKit
 License-Expression: MIT

{branchkit-0.2.0 → branchkit-0.3.0}/branchkit/plugin.py

@@ -211,6 +211,31 @@ class PluginCore:
         self._action_handlers[action] = fn
         return fn
 
+    def handle_command(self, method: str, fn: Callable | None = None):
+        """Register a command: a method a settings control posts to. A
+        command changes state and returns nothing — the platform's method
+        proxy answers the post with 204 and re-renders the tab through its
+        stream, and refuses any result with 422 and the
+        settings-method-result diagnostic. Whatever `fn` returns is dropped
+        here; the response carries ``"result": null``. Usable directly or
+        as a decorator (``@plugin.handle_command("set_volume")``); plain
+        ``def`` or ``async def``, as with ``handle``.
+
+        Use ``handle`` for a method whose result another caller reads — a
+        platform hook, or another plugin — never for a settings control."""
+        if fn is None:
+            def deco(f):
+                self.handle_command(method, f)
+                return f
+            return deco
+
+        async def command(params):
+            await self._invoke(fn, params if params is not None else {})
+            return None
+
+        self.handle(method, command)
+        return fn
+
     # The design-doc registration idiom (`@plugin.action("…")`) — an alias
     # of handle_action, which keeps the Go/TS name greppable too.
     action = handle_action

{branchkit-0.2.0 → branchkit-0.3.0}/branchkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: branchkit
-Version: 0.2.0
+Version: 0.3.0
 Summary: BranchKit plugin SDK for Python
 Author: BranchKit
 License-Expression: MIT

{branchkit-0.2.0 → branchkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "branchkit"
-version = "0.2.0"
+version = "0.3.0"
 description = "BranchKit plugin SDK for Python"
 readme = "README.md"
 license = "MIT"

{branchkit-0.2.0 → branchkit-0.3.0}/tests/test_settings_tabs.py

@@ -2,6 +2,7 @@
 registered stylesheet on every response, an error for a key nobody
 registered, and every settings mirror refreshed before the tab draws."""
 
+import asyncio
 import unittest
 
 import branchkit
@@ -71,6 +72,21 @@ class TestSettingsTabs(unittest.IsolatedAsyncioTestCase):
         with self.assertRaisesRegex(RuntimeError, "settings_tab"):
             b.handle("render_settings", lambda params: {})
 
+    # A command answers with no result however its handler is written — the
+    # proxy refuses anything else with 422; this is the SDK's half.
+    def test_handle_command_drops_the_return_value(self):
+        p = fake_plugin({})
+        seen = {}
+
+        @p.handle_command("set_volume")
+        def set_volume(req):
+            seen["volume"] = req["volume"]
+            return {"leak": True}
+
+        fn = p._handlers["set_volume"]
+        self.assertIsNone(asyncio.run(fn({"volume": 3})))
+        self.assertEqual(seen, {"volume": 3})
+
 
 if __name__ == "__main__":
     unittest.main()