lab-sync-driver-sdk 0.3.0__py3-none-any.whl

lab_sync_driver_sdk/settings_binding.py

@@ -0,0 +1,162 @@
+"""Bind a device's saved settings onto a `connect` that declares them as parameters.
+
+The supervisor sends a device's connection settings as one dict, keyed by each
+setting's display name. A driver can take them in either of two shapes, and the
+host picks by looking at `connect`:
+
+* ``connect(self, settings)`` -- the dict, as sent. Every driver written before
+  this module existed takes this shape, usually beside an empty
+  ``@settings()``-decorated ``connection_settings`` method that carries the form.
+* ``@settings()`` on ``connect`` itself, with one parameter per setting --
+  lab-device-sdk's shape::
+
+      @settings()
+      @string_in("Host", "device address", default="10.0.0.1", maps_to="host")
+      @int_in("Port", "device port", default=4321, maps_to="port")
+      async def connect(self, host: str, port: int) -> None: ...
+
+  Each parameter is named by its setting's ``maps_to``, else its display name,
+  and is filled from the saved value, else the declared default, else the
+  signature's own default, else the type's zero value -- the same fallback the
+  supervisor's settings form uses -- and coerced to the declared type, since a
+  value saved from a form may arrive as text.
+
+Binding needs both the decoration and a parameter named for a declared setting.
+The host has always passed a decorated ``connect`` the dict, whatever its one
+parameter is called, so ``connect(self, settings)``, ``connect(self, config)``
+and a parameterless ``connect(self)`` keep exactly the call they had.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from typing import TYPE_CHECKING
+
+from lab_sync_driver_sdk.decorators import TYPE_BOOL
+from lab_sync_driver_sdk.decorators import TYPE_FLOAT
+from lab_sync_driver_sdk.decorators import TYPE_INT
+from lab_sync_driver_sdk.decorators import TYPE_STRING
+from lab_sync_driver_sdk.decorators import get_command_meta
+from lab_sync_driver_sdk.decorators import is_settings_method
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from collections.abc import Mapping
+
+    from lab_sync_driver_sdk.decorators import Param
+
+# What the supervisor's command coercion accepts as a true boolean given as text.
+_TRUTHY_TEXT = ("true", "yes", "1", "on")
+_ZERO: dict[str, object] = {TYPE_INT: 0, TYPE_FLOAT: 0.0, TYPE_BOOL: False, TYPE_STRING: ""}
+
+
+class SettingsBindingError(ValueError):
+    """The declared settings and `connect`'s parameters do not fit together, or a value will not coerce."""
+
+
+def binds_settings(connect: Callable[..., object]) -> bool:
+    """Whether `connect` takes its settings as keyword arguments rather than as one dict.
+
+    Pass the bound method: an unbound function's `self` would count as a parameter.
+    """
+    meta = get_command_meta(connect)
+    if meta is None or not is_settings_method(connect):
+        return False
+    parameters = inspect.signature(connect).parameters.values()
+    named = {p.name for p in parameters if p.kind not in {p.VAR_POSITIONAL, p.VAR_KEYWORD}}
+    if not named:
+        return any(p.kind is p.VAR_KEYWORD for p in parameters)
+    return any((param.maps_to or param.name) in named for param in meta.inputs)
+
+
+def described_settings(fn: Callable[..., object]) -> list[Param]:
+    """The settings `fn` declares, each defaulting to its parameter's default when it declares none.
+
+    The supervisor fills a setting nobody has saved with the declared default, else
+    the type's zero value, before it ever reaches the driver. So a default that
+    exists only in `connect`'s signature has to be described, or the form shows
+    0 and `connect(timeout_s=7.5)` is handed 0.0. Undecorated carriers have no
+    parameters to read, so their settings come back unchanged.
+    """
+    meta = get_command_meta(fn)
+    if meta is None:
+        return []
+    parameters = inspect.signature(fn).parameters
+    described: list[Param] = []
+    for param in meta.inputs:
+        target = parameters.get(param.maps_to or param.name)
+        if (
+            param.default is None
+            and target is not None
+            and target.default is not target.empty
+            and target.default is not None
+        ):
+            param = dataclasses.replace(param, default=target.default)  # noqa: PLW2901 - a copy, never the decorator's
+        described.append(param)
+    return described
+
+
+def bind_settings(connect: Callable[..., object], saved: Mapping[str, object] | None) -> dict[str, object]:
+    """Build `connect`'s keyword arguments from the saved settings and their declarations.
+
+    Raises:
+        SettingsBindingError: A setting names a parameter `connect` does not have,
+            a required parameter has no setting, or a value does not fit its type.
+    """
+    declared = described_settings(connect)
+    parameters = inspect.signature(connect).parameters
+    accepts_any = any(p.kind is p.VAR_KEYWORD for p in parameters.values())
+    values = saved or {}
+
+    kwargs: dict[str, object] = {}
+    for param in declared:
+        kwarg = param.maps_to or param.name
+        target = parameters.get(kwarg)
+        if target is None and not accepts_any:
+            msg = f"setting {param.name!r} maps to {kwarg!r}, which connect() has no parameter for"
+            raise SettingsBindingError(msg)
+        # Keyed by display name on the wire; the kwarg spelling is accepted too.
+        value = values.get(param.name, values.get(kwarg))
+        if value is None:
+            value = param.default
+        if value is None:
+            if target is not None and target.default is not target.empty:
+                continue  # the signature's own default applies
+            value = _ZERO.get(param.type, "")
+        kwargs[kwarg] = _coerce(param, value)
+
+    unbound = [
+        name
+        for name, p in parameters.items()
+        if p.kind in {p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY} and p.default is p.empty and name not in kwargs
+    ]
+    if unbound:
+        msg = f"connect() parameter(s) {', '.join(map(repr, unbound))} have no @settings declaration"
+        raise SettingsBindingError(msg)
+    return kwargs
+
+
+def _coerce(param: Param, value: object) -> object:
+    try:
+        match param.type:
+            case "int":
+                # bool is an int subclass; a flag silently becoming 0/1 is a bug, not a value.
+                if isinstance(value, bool) or not isinstance(value, int | float | str):
+                    raise TypeError(param.type)
+                return int(value)
+            case "float":
+                if isinstance(value, bool) or not isinstance(value, int | float | str):
+                    raise TypeError(param.type)
+                return float(value)
+            case "bool":
+                if isinstance(value, str):
+                    return value.strip().lower() in _TRUTHY_TEXT
+                return bool(value)
+            case "string":
+                return str(value)
+            case _:
+                return value
+    except (TypeError, ValueError) as exc:
+        msg = f"setting {param.name!r} expects {param.type}, got {value!r}"
+        raise SettingsBindingError(msg) from exc

lab_sync_driver_sdk/testing.py

@@ -0,0 +1,41 @@
+"""In-process test harness: drive a Device's command without the stdio protocol.
+
+With the same output validation the host applies. Lets a driver author
+unit-test commands.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from lab_sync_driver_sdk.decorators import validate_outputs
+
+if TYPE_CHECKING:
+    from lab_sync_driver_sdk.device import Device
+
+ProgressFn = Callable[[float, str], Awaitable[None]]
+
+
+async def run_command(
+    device: Device,
+    name: str,
+    params: dict[str, object] | None = None,
+    *,
+    progress: ProgressFn | None = None,
+) -> dict[str, object]:
+    specs = type(device).command_specs()
+    if name not in specs:
+        msg = f"no such command: {name}"
+        raise KeyError(msg)
+    method_name, meta = specs[name]
+    method = getattr(device, method_name)
+    kwargs: dict[str, object] = {}
+    kwargs.update(params or {})
+    if progress is not None and "progress" in inspect.signature(method).parameters:
+        kwargs["progress"] = progress
+    result: dict[str, object] = await method(**kwargs)
+    validate_outputs(meta, result)
+    return result

lab_sync_driver_sdk-0.3.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: lab-sync-driver-sdk
+Version: 0.3.0
+Summary: Public driver-authoring SDK for the device engine: subclass Device, decorate commands, serve() over stdio
+Author: Lab Sync
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lab-sync-driver-protocol==0.3.0
+Provides-Extra: lab
+Requires-Dist: lab-device-sdk>=0.1.12; extra == "lab"
+Requires-Dist: fastapi>=0.110; extra == "lab"
+Requires-Dist: uvicorn>=0.30; extra == "lab"
+Dynamic: license-file
+
+# lab-sync-driver-sdk
+
+Write a lab device driver as a decorated Python class and serve it as a
+supervised child process. A driver subclasses `Device`, decorates async
+methods with `@command` and the typed in/out decorators, and calls
+`serve(device)` to speak the stdio wire protocol defined by
+[`lab-sync-driver-protocol`](https://pypi.org/project/lab-sync-driver-protocol/). The SDK depends on
+nothing but that package, so a driver ships with its own runtime and never
+imports the supervisor that launches it.
+
+```bash
+pip install lab-sync-driver-sdk
+```
+
+## A driver
+
+```python
+import asyncio
+
+from lab_sync_driver_sdk import Device, command, float_in, string_in, string_out, serve
+
+
+class Greeter(Device):
+    device_type_id = "acme-greeter"
+    manufacturer = "Acme"
+    model = "Greeter 1"
+
+    @command("Greet", "Say hello", default_sim_sec=1.0)
+    @string_in("Name", "who to greet", default="world", maps_to="name")
+    @float_in("Delay", "seconds to wait first", default=0.0, min_value=0.0, maps_to="delay")
+    @string_out("Greeting", "what was said")
+    async def greet(self, name: str = "world", delay: float = 0.0, progress=None) -> dict[str, object]:
+        await asyncio.sleep(delay)
+        if progress is not None:
+            await progress(1.0, "greeted")
+        return {"Greeting": f"Hello, {name}!"}
+
+
+if __name__ == "__main__":
+    asyncio.run(serve(Greeter()))
+```
+
+The decorators produce the driver's `describe` reply: its commands, their
+inputs and outputs, and any optional metadata the class declares (`category`,
+physical dimensions, `default_nests`, `configurations`, telemetry channels).
+A command returns a dict, and every key in it must be declared with an output
+decorator. An undeclared key fails the command with `OutputValidationError`.
+A command that takes a `progress` parameter is handed an async
+`progress(fraction, message)` reporter.
+
+Once `serve` starts, stdout carries protocol frames only. The host points
+`sys.stdout` at stderr, so a stray `print` lands on the log channel rather
+than corrupting a frame.
+
+## Testing a driver
+
+`lab_sync_driver_sdk.testing.run_command` runs one command in-process, applying the
+same output validation the host applies:
+
+```python
+from lab_sync_driver_sdk.testing import run_command
+
+result = await run_command(Greeter(), "Greet", {"name": "lab"})
+assert result == {"Greeting": "Hello, lab!"}
+```
+
+## Connection settings
+
+`@settings()` plus the typed input decorators declare the form an operator fills
+in. `connect` receives the saved values in one of two shapes:
+
+```python
+# The dict, keyed by display name, beside a carrier that holds the form.
+@settings()
+@string_in("Host", "device address", default="10.0.0.1")
+async def connection_settings(self) -> None: ...
+
+async def connect(self, settings: dict[str, Any] | None = None) -> None:
+    host = str((settings or {}).get("Host", "10.0.0.1"))
+
+# Or one parameter per setting, with @settings() on connect itself.
+@settings()
+@string_in("Host", "device address", default="10.0.0.1", maps_to="host")
+@int_in("Port", "device port", default=4321, maps_to="port")
+async def connect(self, host: str, port: int) -> None: ...
+```
+
+In the second shape the host binds each parameter by `maps_to` (else the
+display name). The value comes from the saved setting, else the declared
+default, else the signature's own default, and is coerced to the declared type,
+so `connect` receives an `int` even when the value was saved as text. A setting
+with no matching parameter, or a required parameter with no setting, fails the
+connect with a message naming it. See `lab_sync_driver_sdk.settings_binding`.
+
+## Hosting a lab-device-sdk driver
+
+`lab_sync_driver_sdk.lab_host` serves a driver written against
+[`lab-device-sdk`](https://pypi.org/project/lab-device-sdk/) over the same
+protocol, unchanged. It needs the `lab` extra, which also brings in FastAPI
+and uvicorn for drivers that serve HTTP routes of their own:
+
+```bash
+pip install "lab-sync-driver-sdk[lab]"
+```
+
+It hosts one device per process, so it has to be told which instance it is
+running. A driver manifest declares that with the supervisor's `{device_id}`
+token rather than a hardcoded id, which is what lets a site run several
+devices of the same type:
+
+```toml
+[launch]
+type = "command"
+command = ["python", "-m", "lab_sync_driver_sdk.lab_host",
+           "--device", "my_pkg.my_device:MyDevice",
+           "--device-id", "{device_id}"]
+```
+
+## License
+
+MIT

lab_sync_driver_sdk-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+lab_sync_driver_sdk/__init__.py,sha256=oarZ4mkv-INByECcozf68s3kJA4CgQ7JOkRZQ67sC2M,1433
+lab_sync_driver_sdk/decorators.py,sha256=qNqxg0CpLHxuQFgOslozz9mOmA8CNd0hzd4MAVvQuUA,13410
+lab_sync_driver_sdk/device.py,sha256=123GNc05IktIFaHLceGatm2nmhjKFCY-S5IbvXk45Gg,10536
+lab_sync_driver_sdk/host.py,sha256=GLhki8CcH9EwsZQgjRNJd2AWRQiPG97ftfVjcp3DH5U,29922
+lab_sync_driver_sdk/lab_host.py,sha256=dLBWF8ActlQQvi2g8_BuQYP5iKGO74qXCRxFLWQFqbg,22852
+lab_sync_driver_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lab_sync_driver_sdk/settings_binding.py,sha256=IZ77Qr3hMjjbPJ0CQXG2WN67rPkqTMTsQIQuWbXxWyA,7084
+lab_sync_driver_sdk/testing.py,sha256=2dTkyz85IM1ZS-cOMczGWsAnPCwZMew0r3yo_KXjWZY,1208
+lab_sync_driver_sdk-0.3.0.dist-info/licenses/LICENSE,sha256=jm-ZYaMIQMfZVTbmqsfK44orj0ZnKzzsKwwJwq21xOI,1065
+lab_sync_driver_sdk-0.3.0.dist-info/METADATA,sha256=YR-oz5bWrHdkuU88-lq-M2GAqxnlF2xrX-BqWtz3c_w,5293
+lab_sync_driver_sdk-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+lab_sync_driver_sdk-0.3.0.dist-info/top_level.txt,sha256=Q_-3AaXxeJ0cCC3dq3r_W5wB189zkmt0OvlyX5os1qg,20
+lab_sync_driver_sdk-0.3.0.dist-info/RECORD,,

lab_sync_driver_sdk-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lab_sync_driver_sdk-0.3.0.dist-info/licenses/LICENSE

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

lab_sync_driver_sdk-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lab_sync_driver_sdk