bioexperiment-lab-devices 0.1.0__tar.gz

bioexperiment_lab_devices-0.1.0/LICENSE

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

bioexperiment_lab_devices-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: bioexperiment-lab-devices
+Version: 0.1.0
+Summary: Async Python library to discover and manage lab devices (pump, valve, densitometer).
+License-Expression: MIT
+License-File: LICENSE
+Keywords: lab,automation,devices,async,httpx
+Author: khamitovdr
+Author-email: khamitov.personal@gmail.com
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Provides-Extra: dev
+Requires-Dist: httpx (>=0.27)
+Requires-Dist: mypy (>=1.8) ; extra == "dev"
+Requires-Dist: pytest (>=8) ; extra == "dev"
+Requires-Dist: pytest-asyncio (>=0.23) ; extra == "dev"
+Requires-Dist: ruff (>=0.4) ; extra == "dev"
+Project-URL: Homepage, https://github.com/bioexperiment-lab-devices/lab-devices
+Project-URL: Issues, https://github.com/bioexperiment-lab-devices/lab-devices/issues
+Project-URL: Repository, https://github.com/bioexperiment-lab-devices/lab-devices
+Description-Content-Type: text/markdown
+
+# lab_devices
+
+Async Python library to discover and manage lab devices — peristaltic pumps,
+distribution valves, and densitometers — over the SerialHop / lab-bridge API.
+
+## Install
+
+    pip install bioexperiment-lab-devices    # import as: import lab_devices
+
+For development (runtime + dev deps):
+
+    poetry install --all-extras
+    # or, without Poetry:
+    pip install -e ".[dev]"
+
+## Core usage (host + port)
+
+```python
+import asyncio
+from lab_devices import LabClient
+
+async def main():
+    async with LabClient("chisel", 8089) as lab:
+        pump = lab.pump(1)
+        job = await pump.dispense(volume_ml=10, speed_ml_min=3.0)
+        result = await job.result()
+        print(result.dispensed_ml)
+
+asyncio.run(main())
+```
+
+## Server-only discovery (inside labnet)
+
+```python
+from lab_devices.discovery import LabRegistry
+
+async with LabRegistry() as reg:            # LAB_DEVICES_DISCOVERY_URL overrides the endpoint
+    print(await reg.list_labs())
+    lab = await reg.connect("khamit_desktop")
+    async with lab:
+        await lab.densitometer(1).measure()
+```
+
+Discovery uses the internal, unauthenticated roster endpoint and needs no token.
+It only works from inside the lab-bridge network.
+
+## Development
+
+    poetry run pytest        # hermetic; no hardware needed
+    poetry run mypy
+    poetry run ruff check .
+

bioexperiment_lab_devices-0.1.0/README.md

@@ -0,0 +1,51 @@
+# lab_devices
+
+Async Python library to discover and manage lab devices — peristaltic pumps,
+distribution valves, and densitometers — over the SerialHop / lab-bridge API.
+
+## Install
+
+    pip install bioexperiment-lab-devices    # import as: import lab_devices
+
+For development (runtime + dev deps):
+
+    poetry install --all-extras
+    # or, without Poetry:
+    pip install -e ".[dev]"
+
+## Core usage (host + port)
+
+```python
+import asyncio
+from lab_devices import LabClient
+
+async def main():
+    async with LabClient("chisel", 8089) as lab:
+        pump = lab.pump(1)
+        job = await pump.dispense(volume_ml=10, speed_ml_min=3.0)
+        result = await job.result()
+        print(result.dispensed_ml)
+
+asyncio.run(main())
+```
+
+## Server-only discovery (inside labnet)
+
+```python
+from lab_devices.discovery import LabRegistry
+
+async with LabRegistry() as reg:            # LAB_DEVICES_DISCOVERY_URL overrides the endpoint
+    print(await reg.list_labs())
+    lab = await reg.connect("khamit_desktop")
+    async with lab:
+        await lab.densitometer(1).measure()
+```
+
+Discovery uses the internal, unauthenticated roster endpoint and needs no token.
+It only works from inside the lab-bridge network.
+
+## Development
+
+    poetry run pytest        # hermetic; no hardware needed
+    poetry run mypy
+    poetry run ruff check .

bioexperiment_lab_devices-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["poetry-core>=2.1"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "bioexperiment-lab-devices"
+version = "0.1.0"
+description = "Async Python library to discover and manage lab devices (pump, valve, densitometer)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "khamitovdr", email = "khamitov.personal@gmail.com" }]
+requires-python = ">=3.11"
+keywords = ["lab", "automation", "devices", "async", "httpx"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "mypy>=1.8", "ruff>=0.4"]
+
+[project.urls]
+Homepage = "https://github.com/bioexperiment-lab-devices/lab-devices"
+Repository = "https://github.com/bioexperiment-lab-devices/lab-devices"
+Issues = "https://github.com/bioexperiment-lab-devices/lab-devices/issues"
+
+[tool.poetry]
+packages = [{ include = "lab_devices", from = "src" }]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/lab_devices"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

bioexperiment_lab_devices-0.1.0/src/lab_devices/__init__.py

@@ -0,0 +1,140 @@
+"""Async library to discover and manage lab devices (pump, valve, densitometer).
+
+Quick start:
+
+    from lab_devices import LabClient
+
+    async with LabClient("chisel", 8089) as lab:
+        job = await lab.pump(1).dispense(volume_ml=10, speed_ml_min=3.0)
+        result = await job.result()
+
+Server-only discovery (inside labnet):
+
+    from lab_devices.discovery import LabRegistry
+
+    async with LabRegistry() as reg:
+        lab = await reg.connect("khamit_desktop")
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+from lab_devices.client import LabClient
+from lab_devices.devices import Densitometer, Device, Pump, Valve
+from lab_devices.errors import (
+    BusyError,
+    ClientLookupEndpointError,
+    ClientLookupEndpointUnreachable,
+    DeviceUnreachableError,
+    DiscoveryError,
+    DiscoveryFailedError,
+    DiscoveryInProgressError,
+    HardwareError,
+    InternalDeviceError,
+    InvalidParamsError,
+    InvalidRequestError,
+    JobCancelledError,
+    JobFailedError,
+    JobInProgressError,
+    JobTimeoutError,
+    LabDevicesError,
+    LabError,
+    LabOffline,
+    LabProtocolError,
+    NotCalibratedError,
+    NotHomedError,
+    UnknownCommandError,
+    UnknownDeviceError,
+    UnknownLabClient,
+)
+from lab_devices.jobs import Job, PumpJob
+from lab_devices.models import (
+    AgentInfo,
+    Calibration,
+    CalibrationRunResult,
+    DensitometerCapabilities,
+    DensitometerStatus,
+    DeviceInfo,
+    DispenseResult,
+    Identify,
+    MeasureResult,
+    PingResult,
+    PumpCapabilities,
+    PumpStatus,
+    Range,
+    RawModel,
+    ReadRawResult,
+    Reading,
+    ReadingsResult,
+    Thermostat,
+    ThermostatState,
+    ValveCapabilities,
+    ValveConfig,
+    ValveMoveResult,
+    ValveStatus,
+)
+
+try:
+    __version__ = _version("bioexperiment-lab-devices")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled source tree
+    __version__ = "0.0.0.dev0"
+
+# NOTE: kept as a plain sorted literal list (rather than `sorted([...])`) so ruff's
+# re-export detection (F401) recognizes every name below as intentionally exported.
+__all__ = [
+    "AgentInfo",
+    "BusyError",
+    "Calibration",
+    "CalibrationRunResult",
+    "ClientLookupEndpointError",
+    "ClientLookupEndpointUnreachable",
+    "Densitometer",
+    "DensitometerCapabilities",
+    "DensitometerStatus",
+    "Device",
+    "DeviceInfo",
+    "DeviceUnreachableError",
+    "DiscoveryError",
+    "DiscoveryFailedError",
+    "DiscoveryInProgressError",
+    "DispenseResult",
+    "HardwareError",
+    "Identify",
+    "InternalDeviceError",
+    "InvalidParamsError",
+    "InvalidRequestError",
+    "Job",
+    "JobCancelledError",
+    "JobFailedError",
+    "JobInProgressError",
+    "JobTimeoutError",
+    "LabClient",
+    "LabDevicesError",
+    "LabError",
+    "LabOffline",
+    "LabProtocolError",
+    "MeasureResult",
+    "NotCalibratedError",
+    "NotHomedError",
+    "PingResult",
+    "Pump",
+    "PumpCapabilities",
+    "PumpJob",
+    "PumpStatus",
+    "Range",
+    "RawModel",
+    "ReadRawResult",
+    "Reading",
+    "ReadingsResult",
+    "Thermostat",
+    "ThermostatState",
+    "UnknownCommandError",
+    "UnknownDeviceError",
+    "UnknownLabClient",
+    "Valve",
+    "ValveCapabilities",
+    "ValveConfig",
+    "ValveMoveResult",
+    "ValveStatus",
+]

bioexperiment_lab_devices-0.1.0/src/lab_devices/client.py

@@ -0,0 +1,82 @@
+"""LabClient — core entry point for one lab. See spec §4.1."""
+
+from __future__ import annotations
+
+from typing import Any, Self
+
+import httpx
+
+from lab_devices.devices.base import Device
+from lab_devices.devices.densitometer import Densitometer
+from lab_devices.devices.pump import Pump
+from lab_devices.devices.valve import Valve
+from lab_devices.models import AgentInfo, DeviceInfo
+from lab_devices.transport import Transport
+
+_PREFIX_TO_CLASS: dict[str, type[Device]] = {
+    "pump": Pump,
+    "valve": Valve,
+    "densitometer": Densitometer,
+}
+
+
+class LabClient:
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        *,
+        request_timeout: float = 10.0,
+        discover_timeout: float = 30.0,
+        http: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self._owns_http = http is None
+        self._http = http or httpx.AsyncClient(
+            base_url=f"http://{host}:{port}", timeout=request_timeout
+        )
+        self._transport = Transport(self._http, discover_timeout=discover_timeout)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    # ---- device handles (lazy) ----
+    def pump(self, n: int) -> Pump:
+        return Pump(self._transport, f"pump_{n}")
+
+    def valve(self, n: int) -> Valve:
+        return Valve(self._transport, f"valve_{n}")
+
+    def densitometer(self, n: int) -> Densitometer:
+        return Densitometer(self._transport, f"densitometer_{n}")
+
+    def device(self, device_id: str) -> Device:
+        prefix = device_id.rsplit("_", 1)[0]
+        cls = _PREFIX_TO_CLASS.get(prefix)
+        if cls is None:
+            raise ValueError(f"unrecognized device id prefix: {device_id!r}")
+        return cls(self._transport, device_id)
+
+    # ---- enumeration & lifecycle ----
+    async def list_devices(self) -> list[DeviceInfo]:
+        body = await self._transport.get_devices()
+        return [DeviceInfo.from_raw(d) for d in body.get("devices", [])]
+
+    async def rediscover(self) -> list[DeviceInfo]:
+        body = await self._transport.discover()
+        return [DeviceInfo.from_raw(d) for d in body.get("devices", [])]
+
+    async def disconnect(self, port: str | None = None) -> int:
+        body = await self._transport.disconnect(port)
+        return int(body.get("released", 0))
+
+    async def agent_info(self) -> AgentInfo:
+        return AgentInfo.from_raw(await self._transport.agent_info())

bioexperiment_lab_devices-0.1.0/src/lab_devices/devices/__init__.py

@@ -0,0 +1,6 @@
+from lab_devices.devices.base import Device
+from lab_devices.devices.densitometer import Densitometer
+from lab_devices.devices.pump import Pump
+from lab_devices.devices.valve import Valve
+
+__all__ = ["Device", "Densitometer", "Pump", "Valve"]

bioexperiment_lab_devices-0.1.0/src/lab_devices/devices/base.py

@@ -0,0 +1,57 @@
+"""Base device: universal commands shared by every device type. See spec §4.2."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from lab_devices.jobs import Job
+from lab_devices.models import Identify, PingResult, RawModel
+from lab_devices.transport import Transport
+
+
+class Device:
+    STATUS_MODEL: ClassVar[type[RawModel] | None] = None
+    CAPABILITIES_MODEL: ClassVar[type[RawModel] | None] = None
+
+    def __init__(self, transport: Transport, device_id: str) -> None:
+        self._transport = transport
+        self.id = device_id
+        self.type = device_id.rsplit("_", 1)[0]
+
+    async def ping(self) -> PingResult:
+        return PingResult.from_raw(await self._transport.command(self.id, "ping"))
+
+    async def status(self) -> Any:
+        result = await self._transport.command(self.id, "status")
+        if self.STATUS_MODEL is not None and isinstance(result, dict):
+            return self.STATUS_MODEL.from_raw(result)
+        return result
+
+    async def identify(self) -> Identify:
+        result = await self._transport.command(self.id, "identify")
+        identify = Identify.from_raw(result if isinstance(result, dict) else {})
+        if self.CAPABILITIES_MODEL is not None and isinstance(result, dict):
+            identify.capabilities = self.CAPABILITIES_MODEL.from_raw(result.get("capabilities"))
+        return identify
+
+    async def stop(self) -> Any:
+        return await self._transport.command(self.id, "stop")
+
+    async def get_job(self, job_id: str) -> Job:
+        data = await self._transport.command(self.id, "get_job", {"job_id": job_id})
+        return Job(self, job_id, data=data if isinstance(data, dict) else None)
+
+    async def command(self, cmd: str, params: dict[str, Any] | None = None) -> Any:
+        """Raw escape hatch for any command not wrapped by a typed method."""
+        return await self._transport.command(self.id, cmd, params)
+
+    async def _start_job(
+        self,
+        cmd: str,
+        params: dict[str, Any] | None = None,
+        *,
+        result_model: type[RawModel] | None = None,
+        job_cls: type[Job] = Job,
+    ) -> Job:
+        result = await self._transport.command(self.id, cmd, params)
+        return job_cls.from_start_result(self, result, result_model=result_model)

bioexperiment_lab_devices-0.1.0/src/lab_devices/devices/densitometer.py

@@ -0,0 +1,64 @@
+"""Densitometer. See spec §3.8."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from lab_devices.devices.base import Device
+from lab_devices.jobs import Job
+from lab_devices.models.common import RawModel
+from lab_devices.models.densitometer import (
+    DensitometerCapabilities,
+    DensitometerStatus,
+    MeasureResult,
+    ReadingsResult,
+    ReadRawResult,
+)
+
+
+class Densitometer(Device):
+    STATUS_MODEL: ClassVar[type[RawModel] | None] = DensitometerStatus
+    CAPABILITIES_MODEL: ClassVar[type[RawModel] | None] = DensitometerCapabilities
+
+    async def measure_blank(self) -> Job:
+        return await self._start_job("measure_blank")
+
+    async def measure(self, *, include_raw: bool = False) -> Job:
+        params = {"include_raw": include_raw} if include_raw else None
+        return await self._start_job("measure", params, result_model=MeasureResult)
+
+    async def start_monitoring(self, *, interval_s: float | None = None) -> Any:
+        params = {"interval_s": interval_s} if interval_s is not None else None
+        return await self.command("start_monitoring", params)
+
+    async def get_readings(
+        self, *, since_seq: int | None = None, limit: int | None = None
+    ) -> ReadingsResult:
+        params: dict[str, Any] = {}
+        if since_seq is not None:
+            params["since_seq"] = since_seq
+        if limit is not None:
+            params["limit"] = limit
+        return ReadingsResult.from_raw(await self.command("get_readings", params or None))
+
+    async def stop_monitoring(self) -> Any:
+        return await self.command("stop_monitoring")
+
+    async def set_thermostat(self, *, enabled: bool, target_c: float | None = None) -> Any:
+        params: dict[str, Any] = {"enabled": enabled}
+        if target_c is not None:
+            params["target_c"] = target_c
+        return await self.command("set_thermostat", params)
+
+    async def set_tube_correction(self, *, factor: float) -> Any:
+        return await self.command("set_tube_correction", {"factor": factor})
+
+    async def calibrate_tube(self, *, reference_absorbance: float) -> Any:
+        return await self.command("calibrate_tube", {"reference_absorbance": reference_absorbance})
+
+    async def set_led(self, *, level: int) -> Any:
+        return await self.command("set_led", {"level": level})
+
+    async def read_raw(self, *, level: int | None = None) -> Job:
+        params = {"level": level} if level is not None else None
+        return await self._start_job("read_raw", params, result_model=ReadRawResult)

bioexperiment_lab_devices-0.1.0/src/lab_devices/devices/pump.py

@@ -0,0 +1,81 @@
+"""Peristaltic pump. See spec §3.6."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from lab_devices.devices.base import Device
+from lab_devices.jobs import Job, PumpJob
+from lab_devices.models.common import RawModel
+from lab_devices.models.pump import (
+    Calibration,
+    CalibrationRunResult,
+    DispenseResult,
+    PumpCapabilities,
+    PumpStatus,
+)
+
+
+class Pump(Device):
+    STATUS_MODEL: ClassVar[type[RawModel] | None] = PumpStatus
+    CAPABILITIES_MODEL: ClassVar[type[RawModel] | None] = PumpCapabilities
+
+    async def rotate(self, *, direction: str, speed_ml_min: float) -> Any:
+        return await self.command(
+            "rotate", {"direction": direction, "speed_ml_min": speed_ml_min}
+        )
+
+    async def rotate_raw(self, *, direction: str, speed_pct: float) -> Any:
+        return await self.command("rotate_raw", {"direction": direction, "speed_pct": speed_pct})
+
+    async def dispense(
+        self,
+        *,
+        volume_ml: float,
+        speed_ml_min: float | None = None,
+        direction: str = "forward",
+        drop_suckback_ml: float | None = None,
+        speed_profile: dict[str, Any] | None = None,
+    ) -> PumpJob:
+        params: dict[str, Any] = {"direction": direction, "volume_ml": volume_ml}
+        if speed_ml_min is not None:
+            params["speed_ml_min"] = speed_ml_min
+        if drop_suckback_ml is not None:
+            params["drop_suckback_ml"] = drop_suckback_ml
+        if speed_profile is not None:
+            params["speed_profile"] = speed_profile
+        job = await self._start_job(
+            "dispense", params, result_model=DispenseResult, job_cls=PumpJob
+        )
+        return job  # type: ignore[return-value]
+
+    async def pause(self) -> Any:
+        return await self.command("pause")
+
+    async def resume(self) -> Any:
+        return await self.command("resume")
+
+    async def start_calibration(self, *, speed_pct: float | None = None) -> Job:
+        params = {"speed_pct": speed_pct} if speed_pct is not None else None
+        return await self._start_job(
+            "start_calibration", params, result_model=CalibrationRunResult
+        )
+
+    async def set_calibration(
+        self,
+        *,
+        job_id: str | None = None,
+        measured_volume_ml: float | None = None,
+        ml_per_step: float | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if job_id is not None:
+            params["job_id"] = job_id
+        if measured_volume_ml is not None:
+            params["measured_volume_ml"] = measured_volume_ml
+        if ml_per_step is not None:
+            params["ml_per_step"] = ml_per_step
+        return await self.command("set_calibration", params)
+
+    async def get_calibration(self) -> Calibration:
+        return Calibration.from_raw(await self.command("get_calibration"))

bioexperiment_lab_devices-0.1.0/src/lab_devices/devices/valve.py

@@ -0,0 +1,34 @@
+"""Distribution valve. See spec §3.7."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from lab_devices.devices.base import Device
+from lab_devices.jobs import Job
+from lab_devices.models.common import RawModel
+from lab_devices.models.valve import ValveCapabilities, ValveMoveResult, ValveStatus
+
+
+class Valve(Device):
+    STATUS_MODEL: ClassVar[type[RawModel] | None] = ValveStatus
+    CAPABILITIES_MODEL: ClassVar[type[RawModel] | None] = ValveCapabilities
+
+    async def home(self, *, position: int) -> Any:
+        return await self.command("home", {"position": position})
+
+    async def set_position(self, *, position: int, rotation: str | None = None) -> Job:
+        params: dict[str, Any] = {"position": position}
+        if rotation is not None:
+            params["rotation"] = rotation
+        return await self._start_job("set_position", params, result_model=ValveMoveResult)
+
+    async def configure(
+        self, *, default_rotation: str | None = None, hold_torque: bool | None = None
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if default_rotation is not None:
+            params["default_rotation"] = default_rotation
+        if hold_torque is not None:
+            params["hold_torque"] = hold_torque
+        return await self.command("configure", params)