bec-lib 4.4.2__tar.gz → 4.5.0__tar.gz

{bec_lib-4.4.2 → bec_lib-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bec_lib
-Version: 4.4.2
+Version: 4.5.0
 Summary: BEC library
 Project-URL: Bug Tracker, https://github.com/bec-project/bec/issues
 Project-URL: Homepage, https://github.com/bec-project/bec

{bec_lib-4.4.2 → bec_lib-4.5.0}/bec_lib/endpoints.py

@@ -796,6 +796,22 @@ class MessageEndpoints:
             message_op=MessageOp.SET_PUBLISH,
         )
 
+    @staticmethod
+    def scan_hook() -> EndpointInfo:
+        """Endpoint for the latest scan hook or instruction update of the running scan.
+
+        Step changes are published at once, instruction updates at most once per 0.1 second
+        window. The latest update is stored, so clients that start mid-scan can read it.
+
+        Returns:
+            EndpointInfo: Endpoint carrying messages.ScanHookMessage updates.
+        """
+        return EndpointInfo(
+            endpoint=f"{EndpointType.INFO.value}/scans/scan_hook",
+            message_type=messages.ScanHookMessage,
+            message_op=MessageOp.SET_PUBLISH,
+        )
+
     @staticmethod
     def scan_progress():
         """

{bec_lib-4.4.2 → bec_lib-4.5.0}/bec_lib/messages.py

@@ -763,6 +763,38 @@ class DeviceInstructionMessage(BECMessage):
     parameter: dict
 
 
+class ScanHookMessage(BECMessage):
+    """A scan lifecycle event, optionally including dispatched device instructions.
+
+    Args:
+        scan_id (str): Scan whose lifecycle is being reported.
+        hook (str | None): Active lifecycle hook, or None before a hook has started.
+        status (Literal["running", "completed", "interrupted", "error"]): Hook execution state.
+            "interrupted" means the step was ended by a user or alarm interruption of the scan
+            (finish now, abort or halt); "error" is used for any other exception.
+        instructions (list[DeviceInstructionMessage]): Instructions dispatched in this hook.
+            Instruction updates are coalesced to the latest one in each 0.1 second window;
+            the start, completion or failure of a top-level step is sent at once.
+        waiting (bool): Whether this update was recorded during a device or exposure wait.
+            Wait updates include only pending instructions. The next hook or instruction update
+            replaces the wait; no separate update is emitted when waiting ends.
+        wait_started_at (float | None): Start time of the reported wait, or None for other updates.
+        hook_started_at (float | None): Start time of the current top-level step, e.g. scan_core,
+            or None outside a step.
+        timestamp (float): Time at which the lifecycle or instruction event was recorded.
+    """
+
+    msg_type: ClassVar[str] = "scan_hook"
+    scan_id: str
+    hook: str | None
+    status: Literal["running", "completed", "interrupted", "error"] = "running"
+    instructions: list[DeviceInstructionMessage] = Field(default_factory=list)
+    timestamp: float = Field(default_factory=time.time)
+    waiting: bool = False
+    wait_started_at: float | None = None
+    hook_started_at: float | None = None
+
+
 class ErrorInfo(BaseModel):
     id: str = Field(default_factory=lambda: str(uuid.uuid4()))
     error_message: str

{bec_lib-4.4.2 → bec_lib-4.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bec_lib"
-version = "4.4.2"
+version = "4.5.0"
 description = "BEC library"
 requires-python = ">=3.11"
 classifiers = [

{bec_lib-4.4.2 → bec_lib-4.5.0}/tests/test_bec_messages.py

@@ -1124,3 +1124,49 @@ def test_feedback_message():
     assert res_loaded == msg
     assert res_loaded.username == getpass.getuser()
     assert res_loaded.versions == messages.ServiceVersions._get_version_numbers()
+
+
+def test_scan_hook_message_roundtrip():
+    instruction = messages.DeviceInstructionMessage(
+        device="samx", action="set", parameter={"value": 2}, metadata={"device_instr_id": "move"}
+    )
+    msg = messages.ScanHookMessage(
+        scan_id="scan-id",
+        hook="pre_scan",
+        instructions=[instruction],
+        metadata={"RID": "request-id", "queue_id": "queue-id"},
+    )
+    loaded = MsgpackSerialization.loads(MsgpackSerialization.dumps(msg))
+    assert loaded == msg
+    assert isinstance(loaded.instructions[0], messages.DeviceInstructionMessage)
+    assert messages.ScanHookMessage(scan_id="scan-id", hook="stage").instructions == []
+
+
+def test_scan_hook_wait_fields_are_optional_and_roundtrip():
+    old_update = messages.ScanHookMessage.model_validate(
+        {"scan_id": "scan-id", "hook": "at_each_point", "status": "running", "instructions": []}
+    )
+    assert old_update.waiting is False
+    assert old_update.wait_started_at is None
+    assert old_update.hook_started_at is None
+    waiting = old_update.model_copy(update={"waiting": True, "wait_started_at": 1791244800.0})
+    loaded = MsgpackSerialization.loads(MsgpackSerialization.dumps(waiting))
+    assert loaded == waiting
+    assert loaded.waiting is True
+    assert loaded.wait_started_at == 1791244800.0
+
+
+def test_scan_hook_step_start_roundtrips():
+    msg = messages.ScanHookMessage(
+        scan_id="scan-id", hook="scan_core", status="error", hook_started_at=1791244800.0
+    )
+    loaded = MsgpackSerialization.loads(MsgpackSerialization.dumps(msg))
+    assert loaded == msg
+    assert loaded.hook_started_at == 1791244800.0
+
+
+def test_scan_hook_interrupted_status_roundtrips():
+    msg = messages.ScanHookMessage(scan_id="scan-id", hook="scan_core", status="interrupted")
+    loaded = MsgpackSerialization.loads(MsgpackSerialization.dumps(msg))
+    assert loaded == msg
+    assert loaded.status == "interrupted"