flexdeck 0.1.1__tar.gz → 0.2.0__tar.gz

{flexdeck-0.1.1 → flexdeck-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flexdeck
-Version: 0.1.1
+Version: 0.2.0
 Summary: Write FlexDeck plugins in Python: declare actions, values, events and feeds; test, pack and verify them against FlexDeck itself.
 License: MIT
 Keywords: flexdeck,plugin,sdk,deck,tablet

{flexdeck-0.1.1 → flexdeck-0.2.0}/flexdeck.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flexdeck
-Version: 0.1.1
+Version: 0.2.0
 Summary: Write FlexDeck plugins in Python: declare actions, values, events and feeds; test, pack and verify them against FlexDeck itself.
 License: MIT
 Keywords: flexdeck,plugin,sdk,deck,tablet

{flexdeck-0.1.1 → flexdeck-0.2.0}/flexdeck_plugin/__init__.py

@@ -53,6 +53,8 @@ PERMISSIONS = ("network", "notifications", "processes", "filesystem")
 MAX_SERIES_POINTS = 600
 MAX_IMAGE_BYTES = 256 * 1024
 IMAGE_MIMES = ("image/png", "image/jpeg", "image/webp")
+CAPABILITIES = ("series", "presets", "feeds", "toggles")
+_PLACEHOLDER = re.compile(r"\{\{\s*([^{}\s]+)\s*\}\}")
 
 Value = Union[str, float, int, bool]
 
@@ -109,6 +111,15 @@ class _Action:
     run: Callable[[Dict[str, str], "Context"], Any]
     arguments: Dict[str, Argument]
     check: Optional[Callable[[Dict[str, str], "Context"], Optional[str]]] = None
+    active: Optional[Dict[str, str]] = None
+
+    def active_dto(self, offered: Iterable[str]) -> Optional[Dict[str, str]]:
+        """The light as the host reads it: the plain kind (``equals``, no
+        placeholders) for any host, the rest only for one offering ``toggles``."""
+        if self.active is None:
+            return None
+        plain = "equals" in self.active and not _PLACEHOLDER.search(self.active["variable"])
+        return dict(self.active) if plain or "toggles" in offered else None
 
 
 @dataclass
@@ -311,17 +322,31 @@ class Plugin:
         """Something that happens, which an automation can be started by."""
         self._events[name] = {"description": description, "fields": list(fields)}
 
-    def action(self, name: str, description: str, arguments: Optional[Mapping[str, Argument]] = None, *, check=None):
+    def action(self, name: str, description: str, arguments: Optional[Mapping[str, Argument]] = None, *, check=None, active: Optional[Mapping[str, str]] = None):
         """Decorate a function ``run(args, ctx)`` as an action. It may return
-        ``{"state": "<look>"}`` for the key to show."""
+        ``{"state": "<look>"}`` for the key to show.
+
+        ``active`` says when a key running it is lit: ``{"variable": "x.muted"}``
+        while that is true, ``{"variable": "x.mode", "is": "ptt"}`` while it holds
+        that value, ``{"variable": "x.scene", "equals": "scene"}`` while it holds
+        the ``scene`` argument's value. The variable may hold ``{{argument}}``
+        placeholders."""
         arguments = dict(arguments or {})
         for arg_name, argument in arguments.items():
             _require(argument.kind in KINDS, f"{name}.{arg_name}: '{argument.kind}' is not a kind")
             if argument.kind == "choice":
                 _require(argument.example in argument.choices, f"{name}.{arg_name}: the example must be one of its choices")
+        if active is not None:
+            active = dict(active)
+            variable = active.get("variable", "")
+            _require(set(active) <= {"variable", "equals", "is"}, f"{name}.active: takes variable, equals and is")
+            _require(not ("equals" in active and "is" in active), f"{name}.active: takes equals or is, not both")
+            _require(variable.startswith(f"{self.id}."), f"{name}.active: variable '{variable}' must start with '{self.id}.'")
+            for named in _PLACEHOLDER.findall(variable) + ([active["equals"]] if "equals" in active else []):
+                _require(named in arguments, f"{name}.active: '{named}' is not one of its arguments")
 
         def register(run):
-            self._actions[name] = _Action(description=description, run=run, arguments=arguments, check=check)
+            self._actions[name] = _Action(description=description, run=run, arguments=arguments, check=check, active=active)
             return run
 
         return register
@@ -360,8 +385,16 @@ class Plugin:
 
     # ---- What the host is told -------------------------------------------------
 
-    def manifest(self) -> Dict[str, Any]:
-        """What ``initialize`` answers with."""
+    def manifest(self, offered: Iterable[str] = CAPABILITIES) -> Dict[str, Any]:
+        """What ``initialize`` answers with, to a host offering ``offered``."""
+        offered = tuple(offered)
+        actions = []
+        for n, a in self._actions.items():
+            dto: Dict[str, Any] = {"action": n, "description": a.description, "arguments": [arg.dto(k) for k, arg in a.arguments.items()]}
+            light = a.active_dto(offered)
+            if light is not None:
+                dto["active"] = light
+            actions.append(dto)
         manifest: Dict[str, Any] = {
             "abi": ABI_VERSION,
             "id": self.id,
@@ -369,10 +402,7 @@ class Plugin:
             "version": self.version,
             "description": self.description,
             "author": self.author,
-            "actions": [
-                {"action": n, "description": a.description, "arguments": [arg.dto(k) for k, arg in a.arguments.items()]}
-                for n, a in self._actions.items()
-            ],
+            "actions": actions,
             "settings": [
                 {"key": k, "description": s["description"], "kind": s["kind"], "choices": s["choices"], "defaultValue": s["default"], "secret": s["secret"]}
                 for k, s in self._settings_spec.items()
@@ -395,6 +425,8 @@ class Plugin:
                 }
                 for n, f in self._feeds.items()
             ]
+        if "toggles" in offered and any(a.active is not None and a.active_dto(()) is None for a in self._actions.values()):
+            uses.append("toggles")
         manifest["uses"] = uses
         return manifest
 
@@ -451,7 +483,7 @@ class Plugin:
             if asked not in SUPPORTED_ABIS:
                 raise PluginError(f"this plugin speaks ABI {' or '.join(map(str, SUPPORTED_ABIS))}, the agent speaks {asked}")
             self.configure(body.get("settings") or {}, body.get("dataDir"))
-            return {"manifest": self.manifest(), "variables": self.variables()}
+            return {"manifest": self.manifest(body.get("hostCapabilities") or ()), "variables": self.variables()}
         if method == "variables":
             return self.variables()
         if method == "check":

{flexdeck-0.1.1 → flexdeck-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flexdeck"
-version = "0.1.1"
+version = "0.2.0"
 description = "Write FlexDeck plugins in Python: declare actions, values, events and feeds; test, pack and verify them against FlexDeck itself."
 readme = "README.md"
 requires-python = ">=3.10"

{flexdeck-0.1.1 → flexdeck-0.2.0}/tests/test_sdk.py

@@ -57,6 +57,24 @@ class DefinitionTest(unittest.TestCase):
         )
         self.assertEqual(manifest["uses"], ["series"])
 
+    def test_a_toggle_light_reaches_only_a_host_that_offers_toggles(self):
+        plugin = Plugin(id="lights", name="Lights", version="1.0.0")
+        plugin.variable("lights.room.desk.on", "bool")
+        plugin.action("toggle", "Toggle", {"room": arg("text", "desk")}, active={"variable": "lights.room.{{room}}.on"})(lambda args, ctx: None)
+        plugin.action("pick", "Pick", {"scene": arg("text", "a")}, active={"variable": "lights.room.desk.on", "equals": "scene"})(lambda args, ctx: None)
+
+        newer = plugin.handle("initialize", {"abi": 4, "hostCapabilities": ["series", "toggles"]})["manifest"]
+        self.assertEqual([a.get("active") for a in newer["actions"]], [{"variable": "lights.room.{{room}}.on"}, {"variable": "lights.room.desk.on", "equals": "scene"}])
+        self.assertIn("toggles", newer["uses"])
+        older = plugin.handle("initialize", {"abi": 4, "hostCapabilities": ["series"]})["manifest"]
+        self.assertEqual([a.get("active") for a in older["actions"]], [None, {"variable": "lights.room.desk.on", "equals": "scene"}])
+        self.assertNotIn("toggles", older["uses"])
+
+        with self.assertRaisesRegex(PluginError, "'place' is not one of its arguments"):
+            plugin.action("bad", "Bad", {}, active={"variable": "lights.{{place}}.on"})
+        with self.assertRaisesRegex(PluginError, "must start with 'lights.'"):
+            plugin.action("bad", "Bad", {}, active={"variable": "obs.on"})
+
 
 class ProtocolTest(unittest.TestCase):
     def test_actions_values_events_and_failures_as_the_host_sees_them(self):