leaf-framework 0.10.20__tar.gz → 0.10.22__tar.gz

{leaf_framework-0.10.20 → leaf_framework-0.10.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: leaf-framework
-Version: 0.10.20
+Version: 0.10.22
 Summary: Lightweight Adapter Framework (LEAF)
 License: Apache-2.0
 License-File: LICENSE

{leaf_framework-0.10.20 → leaf_framework-0.10.22}/leaf/adapters/equipment_adapter.py

@@ -315,7 +315,7 @@ class EquipmentAdapter(ABC):
         Stop the adapter and all associated processes and watchers.
         """
         self._stop_event.set()
-        self._output.on_adapter_stop()
+        self._output.on_adapter_stop(self._metadata_manager)
         if self._watcher.is_running():
             self._watcher.stop()
 

{leaf_framework-0.10.20 → leaf_framework-0.10.22}/leaf/modules/output_modules/mqtt.py

@@ -48,8 +48,9 @@ class MQTT(OutputModule):
         error_holder: ErrorHolder | None = None,
         name: str | None = None,
         # Heartbeat
+        heartbeat_interval: float = 300.0,
+        # Removed options, still accepted so existing configs keep loading.
         heartbeat_topic: str | None = None,
-        heartbeat_interval: float = 30.0,
         heartbeat_payload: str | dict | None = None,
     ) -> None:
         """
@@ -67,12 +68,12 @@ class MQTT(OutputModule):
             transport (Literal['tcp', 'websockets', 'unix']): The transport method, either TCP, WebSockets, or Unix socket.
             tls (bool): Boolean flag to enable or disable TLS encryption.
             error_holder (Optional[ErrorHolder]): An instance of ErrorHolder for tracking errors.
-            heartbeat_topic (Optional[str]): Topic to publish heartbeat messages on. If not set,
-                heartbeat and LWT are disabled.
-            heartbeat_interval (float): Seconds between heartbeat publishes. Defaults to 30.
-                Set to 0 to disable.
-            heartbeat_payload (Optional[str | dict]): Payload for heartbeat messages. Defaults to
-                ``{"status": "alive", "timestamp": <epoch>, "datetime": <datetime>}`` with the timestamp filled in at publish time.
+            heartbeat_interval (float): Seconds between heartbeat publishes. Defaults to 300.
+                Set to 0 to disable. Each equipment instance gets its own heartbeat on
+                <root>/<organisation>/<department>/<adapter_id>/<instance_id>/heartbeat.
+                The payload is always ``{"status": "alive", "interval": <seconds>,
+                "timestamp": <epoch>, "datetime": <datetime>}``.
+            heartbeat_topic, heartbeat_payload: Removed; ignored with a warning.
         """
 
         super().__init__(fallback=fallback, error_holder=error_holder, name=name)
@@ -110,10 +111,16 @@ class MQTT(OutputModule):
         # still False, tripping into the fallback path unnecessarily.
         self._connected_event: threading.Event = threading.Event()
 
-        self._heartbeat_topic: str | None = heartbeat_topic
-
+        # One output module is shared by all equipment instances, so each
+        # adapter registers its own heartbeat topic via on_adapter_ready.
+        self._heartbeat_topics: set[str] = set()
+        self._heartbeat_lock: threading.Lock = threading.Lock()
         self._heartbeat_interval: float = heartbeat_interval
-        self._heartbeat_payload: str | dict | None = heartbeat_payload
+        if heartbeat_topic is not None or heartbeat_payload is not None:
+            logger.warning(
+                "heartbeat_topic and heartbeat_payload are no longer supported and are ignored; "
+                "each instance publishes on its own .../<instance_id>/heartbeat topic."
+            )
         self._heartbeat_stop: threading.Event = threading.Event()
         self._heartbeat_thread: threading.Thread | None = None
 
@@ -147,12 +154,6 @@ class MQTT(OutputModule):
             except Exception as e:
                 raise AdapterBuildError(f"Failed to set up TLS: {e}")
 
-        if self._heartbeat_topic:
-            self.client.will_set(
-                self._heartbeat_topic, payload=json.dumps({"status": "disconnected"}), qos=1, retain=True
-            )
-            logger.info(f"LWT registered on '{self._heartbeat_topic}'")
-
         self.connect()
 
     def connect(self) -> None:
@@ -167,7 +168,7 @@ class MQTT(OutputModule):
             self._connected_event.clear()
             self.client.connect(self._broker, self._port, 20)
             self.client.loop_start()
-            if self._heartbeat_topic and self._heartbeat_interval > 0:
+            if self._heartbeat_interval > 0:
                 self._start_heartbeat()
         except (gaierror, OSError) as e:
             self._handle_exception(ClientUnreachableError(f"Error connecting to broker: {e}", output_module=self))
@@ -531,7 +532,7 @@ class MQTT(OutputModule):
             target=self._heartbeat_loop, name=f"HeartbeatThread-{self._name}", daemon=True
         )
         self._heartbeat_thread.start()
-        logger.info(f"Heartbeat started on '{self._heartbeat_topic}' every {self._heartbeat_interval}s")
+        logger.info(f"Heartbeat started every {self._heartbeat_interval}s")
 
     def _stop_heartbeat(self) -> None:
         """Signal the heartbeat thread to stop and wait for it to exit."""
@@ -541,30 +542,47 @@ class MQTT(OutputModule):
             self._heartbeat_thread = None
             logger.info("Heartbeat stopped.")
 
+    def on_adapter_ready(self, metadata_manager: Any) -> None:
+        """Register the instance's heartbeat topic and publish a first beat right away."""
+        topic = metadata_manager.heartbeat()
+        with self._heartbeat_lock:
+            self._heartbeat_topics.add(topic)
+        self._publish_heartbeat(topic)
+
+    def on_adapter_stop(self, metadata_manager: Any) -> None:
+        """Unregister the instance's heartbeat topic and mark it as stopped."""
+        topic = metadata_manager.heartbeat()
+        with self._heartbeat_lock:
+            self._heartbeat_topics.discard(topic)
+        self._publish_heartbeat(topic, "stopped")
+
+    def _publish_heartbeat(self, topic: str, status: str = "alive") -> None:
+        """Publish a single heartbeat, never raising."""
+        payload = {
+            "status": status,
+            # Lets consumers judge staleness without knowing the config.
+            "interval": self._heartbeat_interval,
+            "timestamp": time.time(),
+            "datetime": time.strftime("%Y-%m-%dT%H:%M:%S", time.localtime()),
+        }
+        logger.debug(f"Publishing heartbeat to '{topic}': {payload}")
+        try:
+            # use_fallback=False: a heartbeat is only meaningful live, so a
+            # failed publish is dropped rather than buffered in the fallback
+            # and replayed as a stale "alive" once the broker is back.
+            self.transmit(topic, payload, retain=True, use_fallback=False)
+        except LEAFError as e:
+            # Must not propagate - an unhandled exception in the heartbeat thread
+            # would silently kill it and stop all future heartbeats.
+            logger.debug(f"Heartbeat publish failed, will retry next interval: {e}")
+
     def _heartbeat_loop(self) -> None:
-        """Publish a heartbeat message at regular intervals until stopped."""
-        while True:
-            if self._heartbeat_payload is not None:
-                payload = self._heartbeat_payload
-            else:
-                payload = {
-                    "status": "alive",
-                    "timestamp": time.time(),
-                    "datetime": time.strftime("%Y-%m-%dT%H:%M:%S", time.localtime()),
-                }
-            logger.debug(f"Publishing heartbeat to '{self._heartbeat_topic}': {payload}")
-            try:
-                # use_fallback=False: a heartbeat is only meaningful live, so a
-                # failed publish is dropped rather than buffered in the fallback
-                # and replayed as a stale "alive" once the broker is back.
-                self.transmit(self._heartbeat_topic, payload, use_fallback=False)
-            except LEAFError as e:
-                # Must not propagate - an unhandled exception here (e.g. the broker
-                # connection not being fully up yet) would silently kill this daemon
-                # thread and stop all future heartbeats.
-                logger.debug(f"Heartbeat publish failed, will retry next interval: {e}")
-            if self._heartbeat_stop.wait(self._heartbeat_interval):
-                break
+        """Publish a heartbeat for every registered instance at regular intervals until stopped."""
+        while not self._heartbeat_stop.wait(self._heartbeat_interval):
+            with self._heartbeat_lock:
+                topics = list(self._heartbeat_topics)
+            for topic in topics:
+                self._publish_heartbeat(topic)
 
     def _handle_return_code(self, return_code: int) -> ClientUnreachableError | None:
         """

{leaf_framework-0.10.20 → leaf_framework-0.10.22}/leaf/modules/output_modules/output_module.py

@@ -367,7 +367,7 @@ class OutputModule(ABC):
         Output modules that need instance identity (e.g. MQTT heartbeat) override this.
         """
 
-    def on_adapter_stop(self) -> None:  # noqa: B027
+    def on_adapter_stop(self, metadata_manager: Any) -> None:  # noqa: B027
         """
         Called by EquipmentAdapter when the adapter is stopping.
         Output modules that started background tasks in on_adapter_ready override this.

{leaf_framework-0.10.20 → leaf_framework-0.10.22}/leaf/ui/utils.py

@@ -1,5 +1,6 @@
 """Utility functions and classes for LEAF UI."""
 
+import asyncio
 import logging
 import subprocess
 import sys
@@ -37,7 +38,28 @@ class LogElementHandler(logging.Handler):
             self._emitting = False
 
 
-def install_adapter(adapter: dict[Any, Any]) -> None:
+def _run_pip(*args: str) -> subprocess.CompletedProcess[str]:
+    """
+    Run pip in the interpreter currently running LEAF.
+
+    Blocking; call it off the event loop (asyncio.to_thread) so the UI keeps
+    responding while pip works.
+
+    Args:
+        *args: Arguments passed to pip, e.g. "install", "--upgrade", "git+<url>"
+
+    Returns:
+        The completed pip process, for the caller to check returncode/stderr
+    """
+    return subprocess.run(
+        [sys.executable, "-m", "pip", *args],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+
+async def install_adapter(adapter: dict[Any, Any]) -> None:
     """
     Install a LEAF adapter from a Git repository.
 
@@ -55,13 +77,25 @@ def install_adapter(adapter: dict[Any, Any]) -> None:
     # repo's default branch HEAD -- these adapters' pyproject.toml versions
     # don't get bumped per commit, so a plain `pip install` would see the
     # already-installed version as satisfying the requirement and skip
-    # fetching the newer commit entirely.
-    result = subprocess.run(
-        [sys.executable, "-m", "pip", "install", "--upgrade", "--force-reinstall", f"git+{repository}"],
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        text=True,
-    )
+    # fetching the newer commit entirely. --no-deps keeps the force away from
+    # the dependency tree (which may include LEAF itself); the second, plain
+    # install then only adds dependencies that are still missing.
+    try:
+        result = await asyncio.to_thread(
+            _run_pip, "install", "--upgrade", "--force-reinstall", "--no-deps", f"git+{repository}"
+        )
+        if result.returncode == 0:
+            result = await asyncio.to_thread(_run_pip, "install", f"git+{repository}")
+    except Exception as e:
+        logger.error(f"Could not run pip to install {adapter_name}: {e}", exc_info=True)
+        ui.notify(
+            f"Could not start the installation of {adapter_name}",
+            type="negative",
+            position="top",
+            close_button=True,
+            timeout=8000,
+        )
+        return
 
     if result.returncode != 0:
         logger.error(f"Failed to install {adapter_name}: {result.stderr}")
@@ -78,18 +112,17 @@ def install_adapter(adapter: dict[Any, Any]) -> None:
     )
 
 
-def uninstall_adapter(installed_adapter: dict) -> None:
+async def uninstall_adapter(installed_adapter: dict[Any, Any]) -> None:
     """
     Uninstall a LEAF adapter package.
 
     Args:
         installed_adapter: Dictionary containing adapter metadata with 'name' field
     """
-    print(f"Uninstalling {installed_adapter}...")
     package_name = installed_adapter.get("name")
 
     if not package_name:
-        print(f"Cannot uninstall adapter without package name: {installed_adapter}")
+        logger.error(f"Cannot uninstall adapter without package name: {installed_adapter}")
         ui.notify(
             "Cannot uninstall adapter without package name",
             type="negative",
@@ -102,26 +135,31 @@ def uninstall_adapter(installed_adapter: dict) -> None:
     logger.info(f"Uninstalling {package_name}...")
     ui.notify(f"Uninstalling {package_name}... This may take a moment.", type="info", position="top", timeout=3000)
 
-    result = subprocess.run(
-        [sys.executable, "-m", "pip", "uninstall", "-y", package_name],
-        stdout=subprocess.PIPE,
-        stderr=subprocess.PIPE,
-        text=True,
-    )
-
-    if result.returncode == 0:
-        print(f"Uninstalled {package_name} successfully.")
-        logger.info(f"Uninstalled {package_name} successfully.")
+    try:
+        result = await asyncio.to_thread(_run_pip, "uninstall", "-y", package_name)
+    except Exception as e:
+        logger.error(f"Could not run pip to uninstall {package_name}: {e}", exc_info=True)
         ui.notify(
-            f"Successfully uninstalled {package_name}! Click the Refresh button to update the list.",
-            type="positive",
+            f"Could not start the removal of {package_name}",
+            type="negative",
             position="top",
             close_button=True,
-            timeout=10000,
+            timeout=8000,
         )
-    else:
-        print(f"Failed to uninstall {package_name}.\nError: {result.stderr}")
+        return
+
+    if result.returncode != 0:
         logger.error(f"Failed to uninstall {package_name}: {result.stderr}")
         ui.notify(
             f"Failed to uninstall {package_name}", type="negative", position="top", close_button=True, timeout=8000
         )
+        return
+
+    logger.info(f"Uninstalled {package_name} successfully.")
+    ui.notify(
+        f"Successfully uninstalled {package_name}! Click the Refresh button to update the list.",
+        type="positive",
+        position="top",
+        close_button=True,
+        timeout=10000,
+    )

{leaf_framework-0.10.20 → leaf_framework-0.10.22}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "leaf-framework"
-version = "0.10.20"
+version = "0.10.22"
 description = "Lightweight Adapter Framework (LEAF)"
 authors = [
     "Matthew Crowther <nmc215@ncl.ac.uk>",