bec-lib 4.1.7__tar.gz → 4.2.0__tar.gz

{bec_lib-4.1.7 → bec_lib-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bec_lib
-Version: 4.1.7
+Version: 4.2.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.1.7 → bec_lib-4.2.0}/bec_lib/endpoints.py

@@ -361,6 +361,23 @@ class MessageEndpoints:
             message_op=MessageOp.KEY_VALUE,
         )
 
+    @staticmethod
+    def scan_device_info() -> EndpointInfo:
+        """
+        Endpoint for scan device runtime information. The device server publishes
+        messages.ScanDeviceInfoMessage snapshots for all scans to this shared stream.
+        Consumers should use scan_id to associate device information with a scan.
+
+        Returns:
+            EndpointInfo: Shared stream endpoint for scan device runtime information.
+        """
+        endpoint = f"{EndpointType.INFO.value}/scan_device_info"
+        return EndpointInfo(
+            endpoint=endpoint,
+            message_type=messages.ScanDeviceInfoMessage,
+            message_op=MessageOp.STREAM,
+        )
+
     @staticmethod
     def device_staged(device: str):
         """

{bec_lib-4.1.7 → bec_lib-4.2.0}/bec_lib/messages.py

@@ -24,9 +24,18 @@ from typing import (
 from uuid import uuid4
 
 import numpy as np
-from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+from pydantic import (
+    AliasChoices,
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
 from typing_extensions import deprecated
 
+from bec_lib.endpoints import EndpointInfo, MessageOp
 from bec_lib.metadata_schema import get_metadata_schema_for_scan
 
 
@@ -606,6 +615,7 @@ DeviceInstructionAction = Literal[
     "baseline_reading",
     "close_scan",
     "publish_data_as_read",
+    "broadcast_scan_device_info",
 ]
 
 
@@ -629,6 +639,7 @@ class DeviceInstructionMessage(BECMessage):
                         "baseline_reading",
                         "close_scan",
                         "publish_data_as_read",
+                        "broadcast_scan_device_info",
                         ]) : Device action, note rpc calls can run any method of the device. The function name needs to be specified in parameters['func']
         parameter (dict): Parameters required for the device action
         metadata (dict, optional): Metadata to describe the conditions of the device instruction
@@ -880,10 +891,91 @@ class DeviceInfoMessage(BECMessage):
     info: dict
 
 
+class RedisSignalTransport(BaseModel):
+    """Redis subscription described by a resolved ``EndpointInfo``.
+
+    Consumers use their existing Redis connection. Endpoint strings are obtained
+    from ``MessageEndpoints`` helpers rather than constructed by callers.
+    """
+
+    transport: Literal["redis"] = "redis"
+    endpoint: str = Field(min_length=1, description="Resolved Redis endpoint.")
+    message_type: str = Field(min_length=1, description="Name of the BEC message class.")
+    message_op: MessageOp = Field(description="Supported Redis endpoint operations.")
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    @classmethod
+    def from_endpoint_info(cls, endpoint_info: EndpointInfo) -> Self:
+        """Build a Redis transport descriptor from a message endpoint.
+
+        Args:
+            endpoint_info (EndpointInfo): Endpoint returned by a ``MessageEndpoints`` helper.
+
+        Returns:
+            Self: Transport descriptor containing the endpoint's subscription information.
+        """
+        return cls(
+            endpoint=endpoint_info.endpoint,
+            message_type=endpoint_info.message_type.__name__,
+            message_op=endpoint_info.message_op,
+        )
+
+
+class ZMQSignalTransport(BaseModel):
+    """ZMQ image subscription described from the receiving client's perspective.
+
+    The address is a peer URI when connecting, or a local listening URI when
+    binding. The encoder identifies the complete wire format, including whether
+    a separate topic frame is present, rather than just JSON or CBOR encoding.
+    """
+
+    transport: Literal["zmq"] = "zmq"
+    address: str = Field(min_length=1, description="ZMQ URI to connect to or bind locally.")
+    socket_type: Literal["sub", "pull"] = Field(
+        default="sub", description="Client socket type: SUB for broadcast or PULL for a pipeline."
+    )
+    connection_mode: Literal["connect", "bind"] = Field(
+        default="connect", description="Whether the client connects to a peer or binds locally."
+    )
+    topic: str | None = Field(
+        default=None,
+        description="UTF-8 subscription prefix for SUB sockets. None means no named topic "
+        "and clients subscribe with an empty filter; an empty string also selects all messages. "
+        "PULL sockets must leave this unset. The encoder defines the topic framing.",
+    )
+    encoder: str = Field(
+        min_length=1, description="Identifier of the complete payload wire format."
+    )
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_topic_socket_type(cls, value: Any) -> Any:
+        """Reject subscription topics for PULL sockets, including on assignment."""
+        if (
+            isinstance(value, Mapping)
+            and value.get("socket_type") == "pull"
+            and value.get("topic") is not None
+        ):
+            raise ValueError("Subscription topics are only supported for SUB sockets.")
+        return value
+
+
+SignalTransport = Annotated[
+    RedisSignalTransport | ZMQSignalTransport, Field(discriminator="transport")
+]
+
+
 class SignalInfo(BaseModel):
     """
     Base class for signal information.
     This is used to store metadata about the signal.
+
+    Use ``correlation_group`` to group related signals. ``acquisition_group`` is
+    a deprecated input and attribute alias excluded from serialized messages.
+    If both names are supplied, ``correlation_group`` takes precedence.
     """
 
     data_type: Literal["raw", "processed"] = Field(
@@ -919,20 +1011,95 @@ class SignalInfo(BaseModel):
         default=None,
         description="Metadata for the signal, which can include additional information about the signal's properties.",
     )
-    acquisition_group: Literal["baseline", "monitored"] | str | None = Field(
+    correlation_group: Literal["baseline", "monitored"] | str | None = Field(
         default=None,
-        description="""Specifies the acquisition group of the signal.
+        validation_alias=AliasChoices("correlation_group", "acquisition_group"),
+        description="""Specifies the correlation group of the signal.
         It can be in sync with 'baseline' or 'monitored' groups mapping readoutPriority.
-        Or mapped to a custom tag that allows grouping signals for acquisition and plotting.
-        If None, the signal does not belong to any specific acquisition group.
+        Or mapped to a custom tag that allows grouping signals for correlation and plotting.
+        If None, the signal does not belong to any specific correlation group.
         """,
     )
+    acquisition_group: Literal["baseline", "monitored"] | str | None = Field(
+        default=None,
+        deprecated=deprecated("acquisition_group is deprecated, use correlation_group instead"),
+        description="Deprecated input and attribute alias for correlation_group.",
+        repr=False,
+        exclude=True,
+    )
     use_alias: bool = Field(
         default=False, description="Whether the signal aliases one or more EPICS signals."
     )
 
+    transports: list[SignalTransport] | None = Field(
+        default=None,
+        description="Available subscriptions for this signal, populated by the publisher. "
+        "None means transport metadata is unavailable; consumers retain their existing routing. "
+        "Clients choose a supported transport according to their own preferences.",
+    )
+
     model_config = ConfigDict(validate_assignment=True)
 
+    @model_validator(mode="before")
+    @classmethod
+    def warn_deprecated_acquisition_group(cls, value: Any) -> Any:
+        """Warn for legacy input; the canonical name takes precedence when both are supplied."""
+        if (
+            isinstance(value, Mapping)
+            and "acquisition_group" in value
+            and "correlation_group" not in value
+        ):
+            warnings.warn(
+                "acquisition_group is deprecated, use correlation_group instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return value
+
+    @model_validator(mode="after")
+    def synchronize_acquisition_group(self) -> Self:
+        """Keep the deprecated attribute synchronized with the canonical value."""
+        self.__dict__["acquisition_group"] = self.correlation_group
+        return self
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name == "acquisition_group":
+            warnings.warn(
+                "acquisition_group is deprecated, use correlation_group instead",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            name = "correlation_group"
+        super().__setattr__(name, value)
+
+
+class DeviceRuntimeInfo(BaseModel):
+    """Runtime information for a device, captured for a scan.
+
+    Args:
+        signal_info (dict[str, SignalInfo]): BEC signal information keyed by dotted component
+            name. Defaults to an empty dictionary for devices without BEC signals.
+        disabled_signals (list[str]): Dotted component names of signals to ignore for this
+            scan, relative to this device. Defaults to an empty list.
+    """
+
+    signal_info: dict[str, SignalInfo] = Field(default_factory=dict)
+    disabled_signals: list[str] = Field(default_factory=list)
+
+
+class ScanDeviceInfoMessage(BECMessage):
+    """Snapshot of device runtime information for a scan.
+
+    Args:
+        scan_id (str): Scan ID that the snapshot belongs to.
+        devices (dict[str, DeviceRuntimeInfo]): Runtime information keyed by device name.
+        metadata (dict, optional): Additional metadata.
+    """
+
+    msg_type: ClassVar[str] = "scan_device_info_message"
+    scan_id: str
+    devices: dict[str, DeviceRuntimeInfo]
+
 
 class DeviceMonitor2DMessage(BECMessage):
     """Message type for sending device monitor updates from the device server.

{bec_lib-4.1.7 → bec_lib-4.2.0}/pyproject.toml

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

{bec_lib-4.1.7 → bec_lib-4.2.0}/tests/test_bec_messages.py

@@ -1,10 +1,13 @@
 import getpass
+import json
+import warnings
 
 import numpy as np
 import pydantic
 import pytest
 
 from bec_lib import messages
+from bec_lib.endpoints import MessageEndpoints, MessageOp
 from bec_lib.messaging_services import NotificationMessageObject
 from bec_lib.serialization import MsgpackSerialization
 
@@ -82,6 +85,8 @@ def test_signal_info_defaults_and_roundtrip():
     assert info.signals is None
     assert info.signal_metadata is None
     assert info.use_alias is False
+    assert info.correlation_group is None
+    assert info.transports is None
 
     configured = messages.SignalInfo(
         data_type="processed",
@@ -91,12 +96,242 @@ def test_signal_info_defaults_and_roundtrip():
         role="preview",
         signals=[("image", 1)],
         signal_metadata={"units": "counts"},
-        acquisition_group="monitored",
+        correlation_group="monitored",
         use_alias=True,
     )
     assert messages.SignalInfo.model_validate(configured.model_dump()) == configured
 
 
+@pytest.mark.parametrize(
+    "transports",
+    [
+        None,
+        [],
+        [messages.RedisSignalTransport.from_endpoint_info(MessageEndpoints.scan_status())],
+        [
+            messages.RedisSignalTransport.from_endpoint_info(
+                MessageEndpoints.device_preview("detector", "preview")
+            ).model_dump(mode="json"),
+            {
+                "transport": "zmq",
+                "address": "tcp://detector-host:5555",
+                "topic": "detector/preview",
+                "encoder": "bec-v1",
+            },
+        ],
+    ],
+)
+def test_signal_info_transports_roundtrip(transports):
+    info = messages.SignalInfo(transports=transports)
+    assert messages.SignalInfo.model_validate_json(info.model_dump_json()) == info
+    msg = messages.DeviceInfoMessage(device="detector", info=info.model_dump())
+    loaded = MsgpackSerialization.loads(MsgpackSerialization.dumps(msg))
+    assert messages.SignalInfo.model_validate(loaded.info) == info
+    if transports:
+        assert isinstance(info.transports[0], messages.RedisSignalTransport)
+        if len(transports) > 1:
+            assert isinstance(info.transports[1], messages.ZMQSignalTransport)
+
+
+@pytest.mark.parametrize(
+    "transport",
+    [
+        {"transport": "unknown"},
+        {"transport": "redis"},
+        {"transport": "redis", "endpoint": ""},
+        {"transport": "redis", "endpoint": "preview", "message_op": MessageOp.STREAM},
+        {"transport": "redis", "endpoint": "preview", "message_type": "DevicePreviewMessage"},
+        {
+            "transport": "redis",
+            "endpoint": "preview",
+            "message_type": "DevicePreviewMessage",
+            "message_op": "invalid",
+        },
+        {"transport": "zmq", "address": "tcp://localhost:5555", "topic": "preview"},
+        {"transport": "zmq", "topic": "preview", "encoder": "bec-v1"},
+        {"transport": "zmq", "address": "", "topic": "preview", "encoder": "bec-v1"},
+        {"transport": "zmq", "address": "tcp://localhost:5555", "topic": "", "encoder": ""},
+    ],
+)
+def test_signal_info_transports_reject_invalid_descriptors(transport):
+    with pytest.raises(pydantic.ValidationError):
+        messages.SignalInfo(transports=[transport])
+    info = messages.SignalInfo()
+    with pytest.raises(pydantic.ValidationError):
+        info.transports = [transport]
+
+
+@pytest.mark.parametrize(
+    "endpoint_info",
+    [
+        MessageEndpoints.device_preview("detector", "preview"),
+        MessageEndpoints.device_readback("samx"),
+        MessageEndpoints.scan_status(),
+    ],
+)
+def test_redis_signal_transport_from_endpoint_info(endpoint_info):
+    transport = messages.RedisSignalTransport.from_endpoint_info(endpoint_info)
+    assert transport.transport == "redis"
+    assert transport.endpoint == endpoint_info.endpoint
+    assert transport.message_type == endpoint_info.message_type.__name__
+    assert transport.message_op == endpoint_info.message_op
+    restored = messages.RedisSignalTransport.model_validate_json(transport.model_dump_json())
+    assert restored == transport
+    assert restored.message_op is endpoint_info.message_op
+    info = messages.SignalInfo(transports=[transport])
+    assert messages.SignalInfo.model_validate_json(info.model_dump_json()) == info
+    with pytest.raises(pydantic.ValidationError):
+        transport.endpoint = ""
+    with pytest.raises(pydantic.ValidationError):
+        transport.message_op = "invalid"
+
+
+def test_zmq_signal_transport_assignment():
+    zmq = messages.ZMQSignalTransport(address="ipc:///tmp/bec-preview", topic="", encoder="bec-v1")
+    assert zmq.transport == "zmq"
+    with pytest.raises(pydantic.ValidationError):
+        zmq.encoder = ""
+
+
+def test_zmq_signal_transport_defaults():
+    transport = messages.ZMQSignalTransport(address="tcp://localhost:5555", encoder="bec-v1")
+    assert transport.socket_type == "sub"
+    assert transport.connection_mode == "connect"
+    assert transport.topic is None
+
+
+@pytest.mark.parametrize("socket_type", ["sub", "pull"])
+@pytest.mark.parametrize("connection_mode", ["connect", "bind"])
+def test_zmq_signal_transport_modes_roundtrip(socket_type, connection_mode):
+    transport = messages.ZMQSignalTransport(
+        address="tcp://localhost:5555",
+        socket_type=socket_type,
+        connection_mode=connection_mode,
+        encoder="dectris-stream-v2" if socket_type == "pull" else "array-1.0",
+    )
+    info = messages.SignalInfo(transports=[transport])
+    assert messages.SignalInfo.model_validate_json(info.model_dump_json()) == info
+    msg = messages.DeviceInfoMessage(device="detector", info=info.model_dump())
+    loaded = MsgpackSerialization.loads(MsgpackSerialization.dumps(msg))
+    assert messages.SignalInfo.model_validate(loaded.info) == info
+
+
+@pytest.mark.parametrize("topic", [None, "", "camera/color"])
+def test_zmq_signal_transport_sub_topics(topic):
+    transport = messages.ZMQSignalTransport(
+        address="tcp://localhost:5555", topic=topic, encoder="camera-stream-v1"
+    )
+    assert transport.topic == topic
+    assert messages.ZMQSignalTransport.model_validate_json(transport.model_dump_json()) == transport
+
+
+@pytest.mark.parametrize(
+    "invalid_fields",
+    [
+        {"socket_type": "pub"},
+        {"connection_mode": "listen"},
+        {"socket_type": "pull", "topic": "camera/color"},
+        {"socket_type": "pull", "topic": ""},
+    ],
+)
+def test_zmq_signal_transport_rejects_invalid_modes(invalid_fields):
+    with pytest.raises(pydantic.ValidationError):
+        messages.SignalInfo(
+            transports=[
+                {
+                    "transport": "zmq",
+                    "address": "tcp://localhost:5555",
+                    "encoder": "bec-v1",
+                    **invalid_fields,
+                }
+            ]
+        )
+
+
+def test_zmq_signal_transport_topic_assignment():
+    transport = messages.ZMQSignalTransport(
+        address="tcp://localhost:5555", topic="preview", encoder="bec-v1"
+    )
+    with pytest.raises(pydantic.ValidationError):
+        transport.socket_type = "pull"
+    assert transport.socket_type == "sub"
+    transport.topic = None
+    transport.socket_type = "pull"
+    with pytest.raises(pydantic.ValidationError):
+        transport.topic = "preview"
+    assert transport.topic is None
+    transport.connection_mode = "bind"
+    with pytest.raises(pydantic.ValidationError):
+        transport.connection_mode = "listen"
+    assert transport.connection_mode == "bind"
+
+
+@pytest.mark.parametrize("group", [None, "baseline", "monitored", "fly-scan"])
+def test_signal_info_correlation_group_legacy_compatibility(group):
+    info = messages.SignalInfo(correlation_group=group)
+    assert info.correlation_group == group
+    with pytest.warns(DeprecationWarning, match="use correlation_group instead"):
+        legacy = messages.SignalInfo(acquisition_group=group)
+    assert legacy == info
+    with pytest.warns(DeprecationWarning, match="use correlation_group instead"):
+        assert info.acquisition_group == group
+    payload = info.model_dump()
+    assert payload["correlation_group"] == group
+    assert "acquisition_group" not in payload
+    assert legacy.model_dump() == payload
+    assert messages.SignalInfo.model_validate(payload) == info
+
+
+def test_signal_info_correlation_group_assignment():
+    info = messages.SignalInfo(correlation_group="baseline")
+    with pytest.warns(DeprecationWarning, match="use correlation_group instead"):
+        info.acquisition_group = "monitored"
+    assert info.correlation_group == "monitored"
+    info.correlation_group = "fly-scan"
+    with pytest.warns(DeprecationWarning, match="use correlation_group instead"):
+        assert info.acquisition_group == "fly-scan"
+    with pytest.raises(pydantic.ValidationError):
+        info.correlation_group = 42
+    with pytest.warns(DeprecationWarning, match="use correlation_group instead"):
+        with pytest.raises(pydantic.ValidationError):
+            info.acquisition_group = 42
+    assert info.correlation_group == "fly-scan"
+    with pytest.warns(DeprecationWarning, match="use correlation_group instead"):
+        info.acquisition_group = None
+    assert info.correlation_group is None
+
+
+def test_signal_info_correlation_group_takes_precedence():
+    info = messages.SignalInfo(correlation_group=None, acquisition_group="legacy")
+    assert info.correlation_group is None
+    assert "acquisition_group" not in info.model_dump()
+
+
+def test_signal_info_acquisition_group_schema_is_deprecated():
+    properties = messages.SignalInfo.model_json_schema(mode="validation")["properties"]
+    assert properties["acquisition_group"]["deprecated"] is True
+    assert not properties["correlation_group"].get("deprecated", False)
+    serialized = messages.SignalInfo.model_json_schema(mode="serialization")["properties"]
+    assert "acquisition_group" not in serialized
+
+
+def test_signal_info_serialization_excludes_deprecated_alias_without_warnings():
+    info = messages.SignalInfo(correlation_group="monitored")
+    msg = messages.ScanDeviceInfoMessage(
+        scan_id="scan-1",
+        devices={"detector": messages.DeviceRuntimeInfo(signal_info={"preview": info})},
+    )
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        payload = info.model_dump()
+        assert json.loads(info.model_dump_json()) == payload
+        assert "acquisition_group" not in payload
+        nested = msg.model_dump()["devices"]["detector"]["signal_info"]["preview"]
+        assert nested == payload
+        assert MsgpackSerialization.loads(MsgpackSerialization.dumps(msg)) == msg
+    assert not caught
+
+
 def test_signal_info_rejects_invalid_dimensions():
     with pytest.raises(pydantic.ValidationError):
         messages.SignalInfo(ndim=3)
@@ -112,6 +347,65 @@ def test_signal_info_rejects_invalid_dimension_assignment():
     assert info.ndim == 2
 
 
+def test_scan_device_info_message_roundtrip():
+    msg = messages.ScanDeviceInfoMessage(
+        scan_id="scan-1",
+        devices={
+            "eiger": messages.DeviceRuntimeInfo(
+                signal_info={
+                    "preview": messages.SignalInfo(
+                        data_type="processed",
+                        saved=False,
+                        ndim=2,
+                        scope="continuous",
+                        role="preview",
+                        rpc_access=True,
+                        signals=[("image", 1)],
+                        signal_metadata={"units": "counts"},
+                        correlation_group="monitored",
+                        use_alias=True,
+                    )
+                },
+                disabled_signals=["raw_image", "sub.diagnostic"],
+            ),
+            "samx": messages.DeviceRuntimeInfo(),
+        },
+        metadata={"RID": "rid-1"},
+    )
+
+    res = MsgpackSerialization.dumps(msg)
+    res_loaded = MsgpackSerialization.loads(res)
+
+    assert res_loaded == msg
+    assert res_loaded.devices["eiger"].signal_info["preview"].ndim == 2
+    assert res_loaded.devices["eiger"].signal_info["preview"].role == "preview"
+    assert res_loaded.devices["eiger"].disabled_signals == ["raw_image", "sub.diagnostic"]
+
+
+def test_device_runtime_info_defaults_are_independent():
+    detector = messages.DeviceRuntimeInfo()
+    motor = messages.DeviceRuntimeInfo()
+    detector.signal_info["preview"] = messages.SignalInfo(role="preview")
+    detector.disabled_signals.append("raw_image")
+    assert motor.signal_info == {}
+    assert motor.disabled_signals == []
+
+
+def test_scan_device_info_validates_nested_signal_info():
+    with pytest.raises(pydantic.ValidationError):
+        messages.ScanDeviceInfoMessage(
+            scan_id="scan-1", devices={"eiger": {"signal_info": {"preview": {"ndim": 3}}}}
+        )
+
+
+def test_scan_device_info_endpoint_contract():
+    endpoint = MessageEndpoints.scan_device_info()
+
+    assert endpoint.endpoint == "info/scan_device_info"
+    assert endpoint.message_type is messages.ScanDeviceInfoMessage
+    assert endpoint.message_op == MessageOp.STREAM
+
+
 def test_bundled_message():
     sub_msg = messages.DeviceMessage(signals={"samx": {"value": 5.2}}, metadata={"RID": "1234"})
     msg = messages.BundleMessage()