From 0fdb31b6db77711e4dc2d47f5c3c5887fe92044f Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 13:36:16 +0000 Subject: [PATCH 01/14] use explicit Introspection dataclass of type IntrospectionT --- docs/snippets/dynamic.py | 6 ++--- docs/tutorials/dynamic-drivers.md | 9 +++---- src/fastcs/connections/__init__.py | 1 + src/fastcs/connections/connection.py | 30 +++++++++++++++++++---- src/fastcs/runner.py | 27 +++++++++++++++++---- tests/test_control_system.py | 6 ++--- tests/test_controller_runner.py | 36 +++++++++++++++++++++------- 7 files changed, 88 insertions(+), 27 deletions(-) diff --git a/docs/snippets/dynamic.py b/docs/snippets/dynamic.py index b195b924a..1156fd4b1 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -12,7 +12,7 @@ AttrRW, AttrW, ) -from fastcs.connections import IPConnection +from fastcs.connections import Introspection, IPConnection from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Bool, DataType, Float, Int, String from fastcs.launch import FastCS @@ -67,10 +67,10 @@ class TemperatureIntrospection: class TemperatureConnection(IPConnection[TemperatureIntrospection]): - async def introspect(self) -> TemperatureIntrospection: + async def introspect(self) -> Introspection[TemperatureIntrospection]: api = json.loads(await self.query("API?")) ramps = api.pop("Ramps") - return TemperatureIntrospection(parameters=api, ramps=ramps) + return Introspection(TemperatureIntrospection(parameters=api, ramps=ramps)) NumberT = TypeVar("NumberT", int, float) diff --git a/docs/tutorials/dynamic-drivers.md b/docs/tutorials/dynamic-drivers.md index 923384498..d00692053 100644 --- a/docs/tutorials/dynamic-drivers.md +++ b/docs/tutorials/dynamic-drivers.md @@ -31,10 +31,11 @@ or a description for the parameter. ## Introspection -A `Connection` can describe the device it connects to by implementing `introspect`. -FastCS opens every connection and calls `introspect` before constructing any -controller, and stores what it returned as `connection.introspection`, so a controller -can use it in its `__init__`. +A `Connection` can describe the device it connects to by implementing `introspect`, +which returns the description wrapped in an `Introspection`. FastCS opens every +connection and calls `introspect` before constructing any controller, and stores the +description as `connection.introspection`, so a controller can use it in its +`__init__`. Take the driver implementation from the previous tutorial and remove the statically defined `Attributes` and creation of sub controllers in `__init__`. Then create them diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index f84d26d7e..24228cd0e 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -5,6 +5,7 @@ from .connection import Connection as Connection from .connection import ConnectionState as ConnectionState from .connection import DisconnectedError as DisconnectedError +from .connection import Introspection as Introspection from .connection import disconnect_on as disconnect_on from .ip_connection import IPConnection as IPConnection diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index e1f2a9d9d..a321503f2 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -16,6 +16,24 @@ """What a `Connection`'s ``introspect`` returns, or ``None`` if it doesn't introspect""" +@dataclasses.dataclass +class Introspection(Generic[IntrospectionT]): + """What a `Connection`'s ``introspect`` returns. + + Example:: + + async def introspect(self) -> Introspection[EigerIntrospection]: + return Introspection(EigerIntrospection(...)) + + Args: + value: The description of the device, available as + ``connection.introspection`` + + """ + + value: IntrospectionT + + class DisconnectedError(Exception): """Raised when using a connection whose link is down or closed""" @@ -88,7 +106,7 @@ class Connection(ABC, Generic[IntrospectionT]): Example:: class EigerConnection(Connection[EigerIntrospection]): - async def introspect(self) -> EigerIntrospection: ... + async def introspect(self) -> Introspection[EigerIntrospection]: ... """ # Connection type(s) in the same ControllerSpec to open before this one @@ -131,7 +149,8 @@ def __init_subclass__(cls, **kwargs: Any) -> None: @property def introspection(self) -> IntrospectionT: - """What ``introspect`` returned when the framework opened this connection. + """The value of the `Introspection` that ``introspect`` returned when the + framework opened this connection. Raises: RuntimeError: If the framework hasn't opened this connection yet @@ -162,14 +181,15 @@ def introspection_changed(self, introspection: IntrospectionT) -> bool: async def connect(self) -> None: """Open the link, or raise. Called by the framework before construction.""" - async def introspect(self) -> IntrospectionT: + async def introspect(self) -> Introspection[IntrospectionT]: """Describe the device. Called by the framework after ``connect``. Returns: - The introspection, or ``None`` if this connection doesn't introspect + The introspection, whose value is ``None`` if this connection doesn't + introspect """ - return cast(IntrospectionT, None) + return Introspection(cast(IntrospectionT, None)) @abstractmethod async def close(self) -> None: diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 46b5c0bf3..b663a71eb 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -1,10 +1,10 @@ import asyncio from collections import defaultdict from collections.abc import Iterator, Sequence -from typing import Self +from typing import Self, TypeVar from fastcs.attributes.attr_r import AttrR -from fastcs.connections import Connection, ConnectionState +from fastcs.connections import Connection, ConnectionState, Introspection from fastcs.connections.connection import _reconnecting from fastcs.controllers.base_controller import BaseController from fastcs.controllers.controller import Controller @@ -15,6 +15,8 @@ from fastcs.methods import ScanCallback from fastcs.util import ONCE +T = TypeVar("T") + class ControllerRunner: """Runs the lifecycle of one or more top-level controllers.""" @@ -60,7 +62,7 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: connection.state = ConnectionState() await connection.connect() runner._connections.append(connection) - connection.introspection = await connection.introspect() + connection.introspection = await _introspect(connection) runner._dependencies[id(connection)] = _dependencies( connection, spec.connections ) @@ -215,7 +217,7 @@ async def _reconnect(self, connection: Connection) -> None: try: await connection.close() await connection.connect() - introspection = await connection.introspect() + introspection = await _introspect(connection) except Exception: logger.exception( "Reconnect failed", connection=connection, attempt=attempt + 1 @@ -320,6 +322,23 @@ def _held_connections(controller: BaseController) -> list[Connection]: return list({id(v): v for v in values if isinstance(v, Connection)}.values()) +async def _introspect(connection: Connection[T]) -> T: + """Introspect a connection, returning the value of its `Introspection`. + + Raises: + TypeError: If ``introspect`` doesn't return an `Introspection` + + """ + introspection = await connection.introspect() + if not isinstance(introspection, Introspection): + raise TypeError( + f"{type(connection).__name__}.introspect returned " + f"{type(introspection).__name__}, not an Introspection" + ) + + return introspection.value + + def _check_connections_not_shared(specs: list[ControllerSpec]) -> None: """Check that no connection is used by more than one spec. diff --git a/tests/test_control_system.py b/tests/test_control_system.py index d5e9afbf9..5bb98c08d 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -4,7 +4,7 @@ import pytest from fastcs.attributes import AttributeIO, AttributeIORef, AttrR -from fastcs.connections import Connection +from fastcs.connections import Connection, Introspection from fastcs.control_system import FastCS from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Int @@ -143,9 +143,9 @@ def __init__(self) -> None: async def connect(self) -> None: pass - async def introspect(self) -> dict[str, int]: + async def introspect(self) -> Introspection[dict[str, int]]: self.introspections += 1 - return {"gain": 1} if self.introspections == 1 else {"offset": 1} + return Introspection({"gain": 1} if self.introspections == 1 else {"offset": 1}) async def close(self) -> None: self.closes += 1 diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 72e89f46b..4c5ef6be8 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -3,7 +3,12 @@ import pytest -from fastcs.connections import Connection, DisconnectedError, disconnect_on +from fastcs.connections import ( + Connection, + DisconnectedError, + Introspection, + disconnect_on, +) from fastcs.connections.connection import _structure from fastcs.controllers import Controller, ControllerSpec from fastcs.exceptions import IntrospectionMismatchError, ReconnectFailedError @@ -213,7 +218,7 @@ async def test_connections_closed_if_build_fails(): class FailingIntrospectConnection(RecordingConnection): - async def introspect(self) -> None: + async def introspect(self) -> Introspection: raise RuntimeError("introspect failed") @@ -232,6 +237,19 @@ async def test_connection_closed_if_introspect_fails(): assert events == ["connect", "close"] +class BareIntrospectConnection(RecordingConnection): + async def introspect(self) -> Introspection: + return {"gain": 2} # type: ignore[return-value] + + +@pytest.mark.asyncio +async def test_introspect_not_returning_introspection_raises(): + with pytest.raises(TypeError, match="returned dict, not an Introspection"): + await ControllerRunner.build( + [ControllerSpec("A", ConnectedController, BareIntrospectConnection([]))] + ) + + @pytest.mark.asyncio async def test_connection_shared_between_specs_raises_before_anything_opens(): events: list[str] = [] @@ -327,8 +345,8 @@ class IntrospectingConnection(Connection[DeviceIntrospection]): async def connect(self) -> None: pass - async def introspect(self) -> DeviceIntrospection: - return DeviceIntrospection({"gain": 2}) + async def introspect(self) -> Introspection[DeviceIntrospection]: + return Introspection(DeviceIntrospection({"gain": 2})) async def close(self) -> None: pass @@ -367,11 +385,11 @@ class ChangingConnection(IntrospectingConnection): def __init__(self) -> None: self.introspections = 0 - async def introspect(self) -> DeviceIntrospection: + async def introspect(self) -> Introspection[DeviceIntrospection]: self.introspections += 1 if self.introspections == 1: - return DeviceIntrospection({"gain": 2}) - return DeviceIntrospection({"offset": 2}) + return Introspection(DeviceIntrospection({"gain": 2})) + return Introspection(DeviceIntrospection({"offset": 2})) @pytest.mark.asyncio @@ -594,11 +612,13 @@ async def connect(self) -> None: async def handshake(self) -> None: self.handshakes += 1 - async def introspect(self) -> None: + async def introspect(self) -> Introspection: if self.handshakes > 1: self.introspecting.set() await self.release.wait() + return Introspection(None) + async def close(self) -> None: pass From 371ad86e43612e4f139d41c43d6665058cd97ae8 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 13:45:53 +0000 Subject: [PATCH 02/14] add ConnectionSpec --- src/fastcs/connections/__init__.py | 1 + src/fastcs/connections/connection_spec.py | 75 +++++++++++++++++++++++ src/fastcs/launch.py | 8 +-- src/fastcs/runner.py | 20 +++++- tests/test_connection.py | 11 ++++ tests/test_controller_runner.py | 4 +- 6 files changed, 112 insertions(+), 7 deletions(-) create mode 100644 src/fastcs/connections/connection_spec.py diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 24228cd0e..32d4ece03 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -7,6 +7,7 @@ from .connection import DisconnectedError as DisconnectedError from .connection import Introspection as Introspection from .connection import disconnect_on as disconnect_on +from .connection_spec import ConnectionSpec as ConnectionSpec from .ip_connection import IPConnection as IPConnection with optional_dependency("httpx"): diff --git a/src/fastcs/connections/connection_spec.py b/src/fastcs/connections/connection_spec.py new file mode 100644 index 000000000..a7163e7e9 --- /dev/null +++ b/src/fastcs/connections/connection_spec.py @@ -0,0 +1,75 @@ +from collections.abc import Callable +from typing import Generic, ParamSpec, Self + +from typing_extensions import TypeVar + +from fastcs.connections.connection import Connection + +P = ParamSpec("P") +ConnectionT = TypeVar("ConnectionT", bound=Connection) + + +class ConnectionSpec(Generic[P, ConnectionT]): + """A deferred call that constructs a named connection. + + Example:: + + # MetaConnection(port=5000), reconnecting 5 times a second apart + ConnectionSpec("meta", MetaConnection, port=5000).reconnect( + attempts=5, period=1.0 + ) + + Args: + name: The name of the connection, which is the controller argument it fills + connection_class: The connection class, or any callable returning one + args: Positional arguments for ``connection_class`` + kwargs: Keyword arguments for ``connection_class`` + + """ + + def __init__( + self, + name: str, + connection_class: Callable[P, ConnectionT], + /, + *args: P.args, + **kwargs: P.kwargs, + ) -> None: + self.name = name + self.connection_class = connection_class + self.args = args + self.kwargs = kwargs + self._reconnect: tuple[int | None, float | None] | None = None + + def reconnect(self, *, attempts: int | None, period: float | None) -> Self: + """Set the connection's ``reconnect_attempts`` and ``reconnect_period``, + instead of using its class's. + + Args: + attempts: How many times to try to reconnect. None or 0 means don't + period: How many seconds apart to try + + Returns: + This spec + + Raises: + ValueError: If ``attempts`` is set without ``period`` + + """ + if attempts and period is None: + raise ValueError( + f"{self.name} sets reconnect attempts but not reconnect period" + ) + + self._reconnect = (attempts, period) + return self + + def construct(self) -> ConnectionT: + """Construct the connection, with any reconnect settings from `reconnect`""" + connection = self.connection_class(*self.args, **self.kwargs) + if self._reconnect is not None: + attempts, period = self._reconnect + connection.reconnect_attempts = attempts + connection.reconnect_period = period + + return connection diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index 71470f216..d8e4dbe3b 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -28,7 +28,7 @@ from ruamel.yaml import YAML from fastcs import __version__ -from fastcs.connections import Connection +from fastcs.connections import Connection, ConnectionSpec from fastcs.control_system import FastCS from fastcs.controllers import Controller, ControllerSpec from fastcs.exceptions import LaunchError @@ -227,9 +227,9 @@ def _controller_specs( attempts = values.pop("reconnect_attempts") period = values.pop("reconnect_period") timeouts = values.pop("disconnect_after_timeouts") - connection = connection_type(**values) - connection.reconnect_attempts = attempts - connection.reconnect_period = period + connection_spec = ConnectionSpec(name, connection_type, **values) + connection_spec.reconnect(attempts=attempts, period=period) + connection = connection_spec.construct() connection.disconnect_after_timeouts = timeouts kwargs[name] = connection diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index b663a71eb..930553493 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -1,4 +1,5 @@ import asyncio +import inspect from collections import defaultdict from collections.abc import Iterator, Sequence from typing import Self, TypeVar @@ -29,6 +30,7 @@ def __init__(self) -> None: ) self._dependencies: dict[int, list[Connection]] = {} + self._names: dict[int, str] = {} self._controller_apis: list[ControllerAPI] = [] self._initial_coros: dict[int, list[ScanCallback]] = defaultdict(list) @@ -58,6 +60,7 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: try: for spec in specs: + runner._names.update(_connection_names(spec)) for connection in _dependency_order(spec.connections): connection.state = ConnectionState() await connection.connect() @@ -193,7 +196,7 @@ async def _reconnect(self, connection: Connection) -> None: different """ - name = type(connection).__name__ + name = self._names[id(connection)] attempts = connection.reconnect_attempts period = connection.reconnect_period if not attempts: @@ -220,7 +223,7 @@ async def _reconnect(self, connection: Connection) -> None: introspection = await _introspect(connection) except Exception: logger.exception( - "Reconnect failed", connection=connection, attempt=attempt + 1 + "Reconnect failed", connection=name, attempt=attempt + 1 ) continue finally: @@ -339,6 +342,19 @@ async def _introspect(connection: Connection[T]) -> T: return introspection.value +def _connection_names(spec: ControllerSpec) -> dict[int, str]: + """Name each connection in a spec after the controller argument it's passed as, + or after its class if it's passed into ``*args``""" + names = {id(c): type(c).__name__ for c in spec.connections} + positional = inspect.signature(spec.controller_class).bind_partial(*spec.args) + arguments = {**positional.arguments, **spec.kwargs} + for name, value in arguments.items(): + if isinstance(value, Connection): + names[id(value)] = name + + return names + + def _check_connections_not_shared(specs: list[ControllerSpec]) -> None: """Check that no connection is used by more than one spec. diff --git a/tests/test_connection.py b/tests/test_connection.py index fee75ba14..2eb9a5379 100644 --- a/tests/test_connection.py +++ b/tests/test_connection.py @@ -2,6 +2,7 @@ from fastcs.connections import ( Connection, + ConnectionSpec, ConnectionState, DisconnectedError, disconnect_on, @@ -112,3 +113,13 @@ def test_disconnect_after_timeouts_must_be_at_least_one(): class _NeverConnection(_FlakyConnection): disconnect_after_timeouts = 0 + + +def test_connection_spec_constructs_with_reconnect_settings(): + spec = ConnectionSpec("flaky", _FlakyConnection).reconnect(attempts=5, period=1.0) + connection = spec.construct() + + assert isinstance(connection, _FlakyConnection) + assert (connection.reconnect_attempts, connection.reconnect_period) == (5, 1.0) + with pytest.raises(ValueError, match="flaky sets reconnect attempts but not"): + spec.reconnect(attempts=5, period=None) diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 4c5ef6be8..f34d285cd 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -554,7 +554,9 @@ async def test_watcher_raises_when_instance_has_attempts_but_no_period(): await runner.start() connection.state.mark_down() - with pytest.raises(ReconnectFailedError, match="no reconnect_period"): + with pytest.raises( + ReconnectFailedError, match="^connection can't.*no reconnect_period" + ): await asyncio.wait_for(runner.wait_for_fatal_error(), timeout=1) await runner.stop() From 4103c19a0a3d82c201ba44e34f05a03a9618858b Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 13:47:22 +0000 Subject: [PATCH 03/14] move builtin connections to their own subfolder --- src/fastcs/connections/__init__.py | 6 +++--- src/fastcs/connections/builtin/__init__.py | 1 + src/fastcs/connections/{ => builtin}/http_connection.py | 0 src/fastcs/connections/{ => builtin}/ip_connection.py | 0 src/fastcs/connections/{ => builtin}/serial_connection.py | 0 src/fastcs/util.py | 2 +- 6 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 src/fastcs/connections/builtin/__init__.py rename src/fastcs/connections/{ => builtin}/http_connection.py (100%) rename src/fastcs/connections/{ => builtin}/ip_connection.py (100%) rename src/fastcs/connections/{ => builtin}/serial_connection.py (100%) diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 32d4ece03..0c7e1f492 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -2,19 +2,19 @@ from fastcs.util import optional_dependency +from .builtin.ip_connection import IPConnection as IPConnection from .connection import Connection as Connection from .connection import ConnectionState as ConnectionState from .connection import DisconnectedError as DisconnectedError from .connection import Introspection as Introspection from .connection import disconnect_on as disconnect_on from .connection_spec import ConnectionSpec as ConnectionSpec -from .ip_connection import IPConnection as IPConnection with optional_dependency("httpx"): - from .http_connection import HTTPConnection as HTTPConnection + from .builtin.http_connection import HTTPConnection as HTTPConnection with optional_dependency("aioserial"): - from .serial_connection import SerialConnection as SerialConnection + from .builtin.serial_connection import SerialConnection as SerialConnection # The extra that installs each optional connection _EXTRAS = {"HTTPConnection": "http", "SerialConnection": "serial"} diff --git a/src/fastcs/connections/builtin/__init__.py b/src/fastcs/connections/builtin/__init__.py new file mode 100644 index 000000000..1d604cc50 --- /dev/null +++ b/src/fastcs/connections/builtin/__init__.py @@ -0,0 +1 @@ +"""Connections that FastCS provides, re-exported from `fastcs.connections`""" diff --git a/src/fastcs/connections/http_connection.py b/src/fastcs/connections/builtin/http_connection.py similarity index 100% rename from src/fastcs/connections/http_connection.py rename to src/fastcs/connections/builtin/http_connection.py diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/builtin/ip_connection.py similarity index 100% rename from src/fastcs/connections/ip_connection.py rename to src/fastcs/connections/builtin/ip_connection.py diff --git a/src/fastcs/connections/serial_connection.py b/src/fastcs/connections/builtin/serial_connection.py similarity index 100% rename from src/fastcs/connections/serial_connection.py rename to src/fastcs/connections/builtin/serial_connection.py diff --git a/src/fastcs/util.py b/src/fastcs/util.py index fee179c93..d341fd532 100644 --- a/src/fastcs/util.py +++ b/src/fastcs/util.py @@ -29,7 +29,7 @@ def optional_dependency(*names: str) -> Generator[None, None, None]: Example:: with optional_dependency("httpx"): - from .http_connection import HTTPConnection as HTTPConnection + from .builtin.http_connection import HTTPConnection as HTTPConnection Args: names: The packages that the block may be missing From 8cebaa3f3c558765fb7f56c323c66316dbf01624 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 13:55:32 +0000 Subject: [PATCH 04/14] add discovery upon introspection, and setup discovered connections from the runner --- src/fastcs/connections/connection.py | 15 +++- src/fastcs/connections/connection_spec.py | 13 ++++ src/fastcs/controllers/controller_spec.py | 19 +++-- src/fastcs/runner.py | 86 ++++++++++++++++++----- tests/test_controller_runner.py | 58 +++++++++++++++ 5 files changed, 166 insertions(+), 25 deletions(-) diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index a321503f2..bb1045ade 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -7,11 +7,14 @@ from abc import ABC, abstractmethod from collections.abc import Callable, Coroutine, Mapping, Sequence from contextvars import ContextVar -from typing import Any, ClassVar, Generic, cast, overload +from typing import TYPE_CHECKING, Any, ClassVar, Generic, cast, overload from pydantic import BaseModel from typing_extensions import TypeVar +if TYPE_CHECKING: + from fastcs.connections.connection_spec import ConnectionSpec + IntrospectionT = TypeVar("IntrospectionT", default=None) """What a `Connection`'s ``introspect`` returns, or ``None`` if it doesn't introspect""" @@ -22,16 +25,22 @@ class Introspection(Generic[IntrospectionT]): Example:: - async def introspect(self) -> Introspection[EigerIntrospection]: - return Introspection(EigerIntrospection(...)) + async def introspect(self) -> Introspection[OdinIntrospection]: + info = OdinIntrospection(...) + meta = ConnectionSpec("meta", MetaConnection, port=info.meta_port) + return Introspection(info, subconnections=[meta]) Args: value: The description of the device, available as ``connection.introspection`` + subconnections: Other connections found on the device. Each is renamed + ``_<_name>``, and opened if the controller takes an argument of + that name that isn't given another way. """ value: IntrospectionT + subconnections: list[ConnectionSpec] = dataclasses.field(default_factory=list) class DisconnectedError(Exception): diff --git a/src/fastcs/connections/connection_spec.py b/src/fastcs/connections/connection_spec.py index a7163e7e9..d37e29b52 100644 --- a/src/fastcs/connections/connection_spec.py +++ b/src/fastcs/connections/connection_spec.py @@ -64,6 +64,19 @@ def reconnect(self, *, attempts: int | None, period: float | None) -> Self: self._reconnect = (attempts, period) return self + def add_parent(self, parent_name: str) -> None: + """Prefix the name with that of the connection that discovered it. + + Example:: + + spec.add_parent("odin") # "meta" -> "odin_meta" + + Args: + parent_name: The name of the connection whose introspection returned this + + """ + self.name = f"{parent_name}_{self.name}" + def construct(self) -> ConnectionT: """Construct the connection, with any reconnect settings from `reconnect`""" connection = self.connection_class(*self.args, **self.kwargs) diff --git a/src/fastcs/controllers/controller_spec.py b/src/fastcs/controllers/controller_spec.py index 6a9b595bf..b0094a251 100644 --- a/src/fastcs/controllers/controller_spec.py +++ b/src/fastcs/controllers/controller_spec.py @@ -1,5 +1,5 @@ -from collections.abc import Callable -from typing import Generic, ParamSpec +from collections.abc import Callable, Mapping +from typing import Generic, ParamSpec, cast from fastcs.connections import Connection from fastcs.controllers.controller import Controller @@ -42,9 +42,18 @@ def connections(self) -> list[Connection]: values = [*self.args, *self.kwargs.values()] return [value for value in values if isinstance(value, Connection)] - def construct(self) -> Controller: - """Construct the controller and set its path""" - controller = self.controller_class(*self.args, **self.kwargs) + def construct( + self, discovered: Mapping[str, Connection] | None = None + ) -> Controller: + """Construct the controller and set its path. + + Args: + discovered: Connections found by introspecting, each passed as the keyword + argument of the same name + + """ + controller_class = cast(Callable[..., Controller], self.controller_class) + controller = controller_class(*self.args, **self.kwargs, **(discovered or {})) controller.set_path([self.id]) return controller diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 930553493..0be3536ac 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -52,25 +52,19 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: ``controller_apis``, in the order the specs were given Raises: - ValueError: If a connection is shared between specs + ValueError: If a connection is shared between specs, or two discovered + connections have the same name """ _check_connections_not_shared(specs) runner = cls() try: - for spec in specs: - runner._names.update(_connection_names(spec)) - for connection in _dependency_order(spec.connections): - connection.state = ConnectionState() - await connection.connect() - runner._connections.append(connection) - connection.introspection = await _introspect(connection) - runner._dependencies[id(connection)] = _dependencies( - connection, spec.connections - ) - - runner._controllers = [spec.construct() for spec in specs] + discovered = [await runner._open_connections(spec) for spec in specs] + runner._controllers = [ + spec.construct(connections) + for spec, connections in zip(specs, discovered, strict=True) + ] runner._seal() runner._map_connection_holders() @@ -83,6 +77,64 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: return runner + async def _open_connections(self, spec: ControllerSpec) -> dict[str, Connection]: + """Open a spec's connections, then any they discover that the controller takes + and isn't given, and so on for those. + + Returns: + The discovered connections that were opened, by name + + Raises: + ValueError: If two discovered connections have the same name + + """ + names = _connection_names(spec) + self._names.update(names) + given = set(names.values()) + parameters = inspect.signature(spec.controller_class).parameters + discovered: dict[str, Connection] = {} + + pending = spec.connections + while pending: + found: list[Connection] = [] + for connection in _dependency_order(pending): + introspection = await self._open(connection) + for subconnection in introspection.subconnections: + subconnection.add_parent(self._names[id(connection)]) + name = subconnection.name + if name in given: + logger.info("Using given connection, not discovered", name=name) + elif name not in parameters: + logger.info("Controller doesn't take discovered", name=name) + elif name in discovered: + raise ValueError(f"More than one connection discovered {name}") + else: + discovered[name] = subconnection.construct() + self._names[id(discovered[name])] = name + found.append(discovered[name]) + pending = found + + connections = [*spec.connections, *discovered.values()] + for connection in connections: + self._dependencies[id(connection)] = _dependencies(connection, connections) + + return discovered + + async def _open(self, connection: Connection) -> Introspection: + """Connect and introspect a connection, storing its introspection's value. + + Returns: + The introspection + + """ + connection.state = ConnectionState() + await connection.connect() + self._connections.append(connection) + introspection = await _introspect(connection) + connection.introspection = introspection.value + + return introspection + @property def controllers(self) -> list[Controller]: """The top-level controllers, in the order the specs were given""" @@ -220,7 +272,7 @@ async def _reconnect(self, connection: Connection) -> None: try: await connection.close() await connection.connect() - introspection = await _introspect(connection) + introspection = (await _introspect(connection)).value except Exception: logger.exception( "Reconnect failed", connection=name, attempt=attempt + 1 @@ -325,8 +377,8 @@ def _held_connections(controller: BaseController) -> list[Connection]: return list({id(v): v for v in values if isinstance(v, Connection)}.values()) -async def _introspect(connection: Connection[T]) -> T: - """Introspect a connection, returning the value of its `Introspection`. +async def _introspect(connection: Connection[T]) -> Introspection[T]: + """Introspect a connection, checking it returns an `Introspection`. Raises: TypeError: If ``introspect`` doesn't return an `Introspection` @@ -339,7 +391,7 @@ async def _introspect(connection: Connection[T]) -> T: f"{type(introspection).__name__}, not an Introspection" ) - return introspection.value + return introspection def _connection_names(spec: ControllerSpec) -> dict[int, str]: diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index f34d285cd..2946c01f3 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -5,6 +5,7 @@ from fastcs.connections import ( Connection, + ConnectionSpec, DisconnectedError, Introspection, disconnect_on, @@ -643,3 +644,60 @@ async def test_only_the_reconnect_can_use_a_down_connection(): await controller.connected.wait_for_value(True, timeout=1) assert connection.handshakes == 2 await runner.stop() + + +class MetaConnection(Connection): + async def connect(self) -> None: + pass + + async def close(self) -> None: + pass + + +class DetectorConnection(MetaConnection): + async def introspect(self) -> Introspection: + subconnections = [ + ConnectionSpec("meta", MetaConnection), + ConnectionSpec("unused", MetaConnection), + ] + return Introspection(None, subconnections=subconnections) + + +class DetectorController(Controller): + def __init__( + self, detector: DetectorConnection, detector_meta: MetaConnection | None = None + ) -> None: + super().__init__() + self.detector = detector + self.meta = HoldingController(detector_meta) if detector_meta else None + + +@pytest.mark.asyncio +async def test_discovered_connection_is_opened_and_passed_by_name(): + runner = await ControllerRunner.build( + [ControllerSpec("A", DetectorController, DetectorConnection())] + ) + controller = runner.controllers[0] + assert isinstance(controller, DetectorController) and controller.meta + + meta = controller.meta.connection + assert type(meta) is MetaConnection + assert runner._names[id(meta)] == "detector_meta" + assert len(runner._connections) == 2 + + +@pytest.mark.asyncio +async def test_given_connection_is_used_instead_of_discovered(): + given = MetaConnection() + runner = await ControllerRunner.build( + [ + ControllerSpec( + "A", DetectorController, DetectorConnection(), detector_meta=given + ) + ] + ) + controller = runner.controllers[0] + assert isinstance(controller, DetectorController) and controller.meta + + assert controller.meta.connection is given + assert len(runner._connections) == 2 From 97dd02e19da05f68ecd158660c868bc220344dc2 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 13:59:26 +0000 Subject: [PATCH 05/14] check for changes in discovered connections upon reconnect --- src/fastcs/connections/connection_spec.py | 30 +++++++++++++++ src/fastcs/runner.py | 46 ++++++++++++++++++++--- tests/test_controller_runner.py | 32 ++++++++++++++++ 3 files changed, 103 insertions(+), 5 deletions(-) diff --git a/src/fastcs/connections/connection_spec.py b/src/fastcs/connections/connection_spec.py index d37e29b52..d85c9f9d1 100644 --- a/src/fastcs/connections/connection_spec.py +++ b/src/fastcs/connections/connection_spec.py @@ -64,6 +64,36 @@ def reconnect(self, *, attempts: int | None, period: float | None) -> Self: self._reconnect = (attempts, period) return self + def __eq__(self, other: object) -> bool: + if not isinstance(other, ConnectionSpec): + return NotImplemented + + return self._fields() == other._fields() + + def __repr__(self) -> str: + class_name = getattr(self.connection_class, "__name__", self.connection_class) + arguments = [ + repr(self.name), + str(class_name), + *(repr(arg) for arg in self.args), + *(f"{key}={value!r}" for key, value in self.kwargs.items()), + ] + spec = f"ConnectionSpec({', '.join(arguments)})" + if self._reconnect is not None: + attempts, period = self._reconnect + spec += f".reconnect(attempts={attempts}, period={period})" + + return spec + + def _fields(self) -> tuple: + return ( + self.name, + self.connection_class, + self.args, + self.kwargs, + self._reconnect, + ) + def add_parent(self, parent_name: str) -> None: """Prefix the name with that of the connection that discovered it. diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 0be3536ac..1803a5e50 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -5,7 +5,12 @@ from typing import Self, TypeVar from fastcs.attributes.attr_r import AttrR -from fastcs.connections import Connection, ConnectionState, Introspection +from fastcs.connections import ( + Connection, + ConnectionSpec, + ConnectionState, + Introspection, +) from fastcs.connections.connection import _reconnecting from fastcs.controllers.base_controller import BaseController from fastcs.controllers.controller import Controller @@ -31,6 +36,9 @@ def __init__(self) -> None: self._dependencies: dict[int, list[Connection]] = {} self._names: dict[int, str] = {} + # Per connection, the names of the discovered connections its controller takes + self._takes: dict[int, set[str]] = {} + self._subconnections: dict[int, dict[str, ConnectionSpec]] = {} self._controller_apis: list[ControllerAPI] = [] self._initial_coros: dict[int, list[ScanCallback]] = defaultdict(list) @@ -92,6 +100,7 @@ async def _open_connections(self, spec: ControllerSpec) -> dict[str, Connection] self._names.update(names) given = set(names.values()) parameters = inspect.signature(spec.controller_class).parameters + takes = set(parameters) - given discovered: dict[str, Connection] = {} pending = spec.connections @@ -99,8 +108,12 @@ async def _open_connections(self, spec: ControllerSpec) -> dict[str, Connection] found: list[Connection] = [] for connection in _dependency_order(pending): introspection = await self._open(connection) + specs = _subconnections( + introspection, self._names[id(connection)], takes + ) + self._takes[id(connection)] = takes + self._subconnections[id(connection)] = specs for subconnection in introspection.subconnections: - subconnection.add_parent(self._names[id(connection)]) name = subconnection.name if name in given: logger.info("Using given connection, not discovered", name=name) @@ -245,7 +258,8 @@ async def _reconnect(self, connection: Connection) -> None: ``reconnect_period``, or it doesn't reconnect within ``reconnect_attempts`` IntrospectionMismatchError: If the new introspection's structure is - different + different, or it discovers different connections that the controller + takes """ name = self._names[id(connection)] @@ -272,7 +286,7 @@ async def _reconnect(self, connection: Connection) -> None: try: await connection.close() await connection.connect() - introspection = (await _introspect(connection)).value + introspection = await _introspect(connection) except Exception: logger.exception( "Reconnect failed", connection=name, attempt=attempt + 1 @@ -281,12 +295,22 @@ async def _reconnect(self, connection: Connection) -> None: finally: _reconnecting.reset(token) - if connection.introspection_changed(introspection): + if connection.introspection_changed(introspection.value): raise IntrospectionMismatchError( f"{name} introspection changed structure on reconnect, so the " "controllers built from it are out of date" ) + specs = _subconnections(introspection, name, self._takes[id(connection)]) + old_specs = self._subconnections[id(connection)] + for changed in sorted(old_specs.keys() | specs.keys()): + old, new = old_specs.get(changed), specs.get(changed) + if old != new: + raise IntrospectionMismatchError( + f"{name} discovered {new} on reconnect instead of {old}, so " + "the controllers built from it are out of date" + ) + connection.state.mark_up() return @@ -377,6 +401,18 @@ def _held_connections(controller: BaseController) -> list[Connection]: return list({id(v): v for v in values if isinstance(v, Connection)}.values()) +def _subconnections( + introspection: Introspection, parent_name: str, takes: set[str] +) -> dict[str, ConnectionSpec]: + """Name an introspection's subconnections after their parent, and keep those the + controller takes, by name""" + for subconnection in introspection.subconnections: + subconnection.add_parent(parent_name) + + specs = introspection.subconnections + return {spec.name: spec for spec in specs if spec.name in takes} + + async def _introspect(connection: Connection[T]) -> Introspection[T]: """Introspect a connection, checking it returns an `Introspection`. diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 2946c01f3..14ca5d09c 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -701,3 +701,35 @@ async def test_given_connection_is_used_instead_of_discovered(): assert controller.meta.connection is given assert len(runner._connections) == 2 + + +class PortConnection(MetaConnection): + def __init__(self, port: int) -> None: + self.port = port + + +class MovingDetectorConnection(DetectorConnection): + reconnect_attempts = 10 + reconnect_period = 0 + + def __init__(self) -> None: + self.introspections = 0 + + async def introspect(self) -> Introspection: + self.introspections += 1 + meta = ConnectionSpec("meta", PortConnection, port=5000 + self.introspections) + return Introspection(None, subconnections=[meta]) + + +@pytest.mark.asyncio +async def test_discovered_connection_changing_on_reconnect_is_fatal(): + connection = MovingDetectorConnection() + runner = await ControllerRunner.build( + [ControllerSpec("A", DetectorController, connection)] + ) + await runner.start() + + connection.state.mark_down() + with pytest.raises(IntrospectionMismatchError, match="port=5002.*port=5001"): + await asyncio.wait_for(runner.wait_for_fatal_error(), timeout=1) + await runner.stop() From 660afe595082f5c7be1fe54b4a7683df760cb173 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 14:02:53 +0000 Subject: [PATCH 06/14] allow optional connections blocks in fastcs.yaml --- src/fastcs/launch.py | 41 +++++++++++++++++++++++++++++++++-------- tests/test_launch.py | 30 ++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+), 8 deletions(-) diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index d8e4dbe3b..b96b0933c 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -4,6 +4,7 @@ import inspect import json from pathlib import Path +from types import UnionType from typing import ( TYPE_CHECKING, Annotated, @@ -12,6 +13,7 @@ Optional, Self, Union, + get_args, get_origin, get_type_hints, ) @@ -223,6 +225,10 @@ def _controller_specs( kwargs: dict[str, Any] = {} for name, connection_type in registered.connection_types.items(): settings = getattr(entry.connections, name) + if settings is None: + # An optional connection left out, which may be discovered instead + continue + values = {k: getattr(settings, k) for k in type(settings).model_fields} attempts = values.pop("reconnect_attempts") period = values.pop("reconnect_period") @@ -297,6 +303,25 @@ def _drop_default(schema: dict[str, Any]) -> None: @functools.cache +def _connection_hint(hint: Any) -> tuple[type[Connection] | None, bool]: + """The connection class a controller argument's hint names, if any, and whether + it's optional, as in ``MetaConnection | None``""" + optional = False + if get_origin(hint) in (Union, UnionType): + members = [member for member in get_args(hint) if member is not type(None)] + if len(members) != 1: + return None, False + + hint, optional = members[0], True + + # A parametrised hint like IPConnection[Introspection] is checked by its class + hint = get_origin(hint) or hint + if isinstance(hint, type) and issubclass(hint, Connection): + return hint, optional + + return None, False + + def _connection_settings_model(connection_type: type[Connection]) -> type[BaseModel]: """Build the Pydantic model for one connection's block under `connections:`. @@ -402,17 +427,17 @@ def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: } connection_types: dict[str, type[Connection]] = {} + connection_fields: dict[str, Any] = {} for name in args: - # A parametrised hint like IPConnection[Introspection] is checked by its class - hint = get_origin(hints.get(name)) or hints.get(name) - if isinstance(hint, type) and issubclass(hint, Connection): - connection_types[name] = hint + connection_type, optional = _connection_hint(hints.get(name)) + if connection_type is not None: + connection_types[name] = connection_type + settings_model = _connection_settings_model(connection_type) + connection_fields[name] = ( + (settings_model | None, None) if optional else (settings_model, ...) + ) if connection_types: - connection_fields: dict[str, Any] = { - name: (_connection_settings_model(connection_type), ...) - for name, connection_type in connection_types.items() - } connections_model = create_model( f"{controller_class.__name__}Connections", __config__={"extra": "forbid"}, diff --git a/tests/test_launch.py b/tests/test_launch.py index a1794fd79..49ebc27c9 100644 --- a/tests/test_launch.py +++ b/tests/test_launch.py @@ -19,6 +19,7 @@ from fastcs.launch import ( _build_options_model, _connection_settings_model, + _controller_specs, _launch, get_controller_schema, launch, @@ -81,6 +82,13 @@ def __init__( super().__init__() +class WithOptionalConnection(Controller): + def __init__( + self, odin: IPConnection, odin_meta: IPConnection | None = None + ) -> None: + super().__init__() + + class OtherHinted(Controller): def __init__(self, arg: OtherConfig) -> None: super().__init__() @@ -426,3 +434,25 @@ def test_keyword_only_connection_in_schema(): "transport": [{"rest": {}}], } ) + + +@pytest.mark.parametrize("given", [False, True]) +def test_optional_connection_block_can_be_left_out(given: bool): + connections = {"odin": {"ip": "localhost", "port": 8000}} + if given: + connections["odin_meta"] = {"ip": "localhost", "port": 8001} + options = _build_options_model([WithOptionalConnection]).model_validate( + { + "controllers": [ + { + "id": "one", + "type": "tests.WithOptionalConnection", + "connections": connections, + } + ], + "transport": [{"rest": {}}], + } + ) + + [spec] = _controller_specs(options.controllers) # type: ignore[attr-defined] + assert ("odin_meta" in spec.kwargs) is given From 4f5fa70c8945e669821a922795151be9d2947e5f Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 14:05:00 +0000 Subject: [PATCH 07/14] update docs --- docs/explanations/connections.md | 44 +++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index 009dc4562..514259c0f 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -141,6 +141,48 @@ FastCS finds the controllers to mark down by looking for the connection on them, and passes it to any sub controllers that need it, which store it too. - Each controller stores at most one connection. - Every connection a controller stores was opened by FastCS, from the top-level - controller's arguments. + controller's arguments or discovered for them. FastCS raises a `ValueError` at startup if any of these is broken. + +## Discovered connections + +Some devices report where other links are, like Odin reporting the port of its meta +writer. `introspect()` can return a `ConnectionSpec` for each of these alongside the +description: + +```python +from fastcs.connections import Connection, ConnectionSpec, Introspection + + +class OdinConnection(Connection[OdinIntrospection]): + async def introspect(self) -> Introspection[OdinIntrospection]: + info = OdinIntrospection(await self.get("/api/tree")) + meta = ConnectionSpec("meta", MetaWriterConnection, port=info.meta_port) + return Introspection(info, subconnections=[meta]) +``` + +FastCS renames each one after the connection that discovered it, here `odin_meta`, and +passes it to the top-level controller's argument of that name, which is hinted +`X | None`: + +```python +class EigerController(Controller): + def __init__( + self, + eiger: EigerConnection, + odin: OdinConnection, + odin_meta: MetaWriterConnection | None = None, + ) -> None: ... +``` + +- It's opened after the connections that are given, and only if the controller takes + it. It can discover connections of its own, named the same way, e.g. `odin_meta_x`. +- An `odin_meta` block in `fastcs.yaml`, or an `odin_meta` argument in the + `ControllerSpec`, is used instead of the discovered one. +- It's independent of the connection that discovered it, so it only goes down when its + own IO fails. Set `depends_on` on its class if it needs its parent to be up first. +- It uses its class's reconnect settings, unless the spec sets them with + `ConnectionSpec(...).reconnect(attempts=5, period=1.0)`. +- If a reconnect discovers a different spec for a connection the controller takes, + such as a new port, FastCS stops with an `IntrospectionMismatchError`. From e853fe452e092df3a5e3f328f010e3a16238ab81 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 14:39:15 +0000 Subject: [PATCH 08/14] simplify changig reconnect settings in code --- docs/explanations/connections.md | 11 +++-- src/fastcs/connections/connection.py | 31 +++++++++++- src/fastcs/connections/connection_spec.py | 57 +++-------------------- src/fastcs/launch.py | 5 +- tests/test_connection.py | 11 ++--- 5 files changed, 51 insertions(+), 64 deletions(-) diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index 514259c0f..ecaf4e0b1 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -118,7 +118,12 @@ class EigerConnection(Connection): ``` A class that sets `reconnect_attempts` must set `reconnect_period` too, or defining it -raises a `TypeError`. +raises a `TypeError`. In Python, set them on one connection with `set_reconnect`, which +returns the connection: + +```python +connection = IPConnection("10.0.0.5", 4000).set_reconnect(attempts=5, period=2.0) +``` | Connection | `reconnect_attempts` | `reconnect_period` | |---|---|---| @@ -182,7 +187,7 @@ class EigerController(Controller): `ControllerSpec`, is used instead of the discovered one. - It's independent of the connection that discovered it, so it only goes down when its own IO fails. Set `depends_on` on its class if it needs its parent to be up first. -- It uses its class's reconnect settings, unless the spec sets them with - `ConnectionSpec(...).reconnect(attempts=5, period=1.0)`. +- It uses its class's reconnect settings. To set others, give it a block in + `fastcs.yaml` instead. - If a reconnect discovers a different spec for a connection the controller takes, such as a new port, FastCS stops with an `IntrospectionMismatchError`. diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index bb1045ade..9b7364388 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -7,7 +7,7 @@ from abc import ABC, abstractmethod from collections.abc import Callable, Coroutine, Mapping, Sequence from contextvars import ContextVar -from typing import TYPE_CHECKING, Any, ClassVar, Generic, cast, overload +from typing import TYPE_CHECKING, Any, ClassVar, Generic, Self, cast, overload from pydantic import BaseModel from typing_extensions import TypeVar @@ -156,6 +156,35 @@ def __init_subclass__(cls, **kwargs: Any) -> None: "it must be an integer of at least 1" ) + def set_reconnect(self, *, attempts: int | None, period: float | None) -> Self: + """Set this connection's ``reconnect_attempts`` and ``reconnect_period``, + instead of using its class's. + + Example:: + + odin = OdinConnection(url).set_reconnect(attempts=10, period=2.0) + + Args: + attempts: How many times to try to reconnect. None or 0 means don't + period: How many seconds apart to try + + Returns: + This connection + + Raises: + ValueError: If ``attempts`` is set without ``period`` + + """ + if attempts and period is None: + raise ValueError( + f"{type(self).__name__} sets reconnect attempts but not reconnect " + "period" + ) + + self.reconnect_attempts = attempts + self.reconnect_period = period + return self + @property def introspection(self) -> IntrospectionT: """The value of the `Introspection` that ``introspect`` returned when the diff --git a/src/fastcs/connections/connection_spec.py b/src/fastcs/connections/connection_spec.py index d85c9f9d1..e946eeaba 100644 --- a/src/fastcs/connections/connection_spec.py +++ b/src/fastcs/connections/connection_spec.py @@ -1,5 +1,5 @@ from collections.abc import Callable -from typing import Generic, ParamSpec, Self +from typing import Generic, ParamSpec from typing_extensions import TypeVar @@ -14,10 +14,8 @@ class ConnectionSpec(Generic[P, ConnectionT]): Example:: - # MetaConnection(port=5000), reconnecting 5 times a second apart - ConnectionSpec("meta", MetaConnection, port=5000).reconnect( - attempts=5, period=1.0 - ) + # MetaConnection(port=5000), to fill the controller argument "meta" + ConnectionSpec("meta", MetaConnection, port=5000) Args: name: The name of the connection, which is the controller argument it fills @@ -39,30 +37,6 @@ def __init__( self.connection_class = connection_class self.args = args self.kwargs = kwargs - self._reconnect: tuple[int | None, float | None] | None = None - - def reconnect(self, *, attempts: int | None, period: float | None) -> Self: - """Set the connection's ``reconnect_attempts`` and ``reconnect_period``, - instead of using its class's. - - Args: - attempts: How many times to try to reconnect. None or 0 means don't - period: How many seconds apart to try - - Returns: - This spec - - Raises: - ValueError: If ``attempts`` is set without ``period`` - - """ - if attempts and period is None: - raise ValueError( - f"{self.name} sets reconnect attempts but not reconnect period" - ) - - self._reconnect = (attempts, period) - return self def __eq__(self, other: object) -> bool: if not isinstance(other, ConnectionSpec): @@ -78,21 +52,10 @@ def __repr__(self) -> str: *(repr(arg) for arg in self.args), *(f"{key}={value!r}" for key, value in self.kwargs.items()), ] - spec = f"ConnectionSpec({', '.join(arguments)})" - if self._reconnect is not None: - attempts, period = self._reconnect - spec += f".reconnect(attempts={attempts}, period={period})" - - return spec + return f"ConnectionSpec({', '.join(arguments)})" def _fields(self) -> tuple: - return ( - self.name, - self.connection_class, - self.args, - self.kwargs, - self._reconnect, - ) + return (self.name, self.connection_class, self.args, self.kwargs) def add_parent(self, parent_name: str) -> None: """Prefix the name with that of the connection that discovered it. @@ -108,11 +71,5 @@ def add_parent(self, parent_name: str) -> None: self.name = f"{parent_name}_{self.name}" def construct(self) -> ConnectionT: - """Construct the connection, with any reconnect settings from `reconnect`""" - connection = self.connection_class(*self.args, **self.kwargs) - if self._reconnect is not None: - attempts, period = self._reconnect - connection.reconnect_attempts = attempts - connection.reconnect_period = period - - return connection + """Construct the connection""" + return self.connection_class(*self.args, **self.kwargs) diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index b96b0933c..5be0f0e79 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -233,9 +233,8 @@ def _controller_specs( attempts = values.pop("reconnect_attempts") period = values.pop("reconnect_period") timeouts = values.pop("disconnect_after_timeouts") - connection_spec = ConnectionSpec(name, connection_type, **values) - connection_spec.reconnect(attempts=attempts, period=period) - connection = connection_spec.construct() + connection = ConnectionSpec(name, connection_type, **values).construct() + connection.set_reconnect(attempts=attempts, period=period) connection.disconnect_after_timeouts = timeouts kwargs[name] = connection diff --git a/tests/test_connection.py b/tests/test_connection.py index 2eb9a5379..5a64e1a84 100644 --- a/tests/test_connection.py +++ b/tests/test_connection.py @@ -2,7 +2,6 @@ from fastcs.connections import ( Connection, - ConnectionSpec, ConnectionState, DisconnectedError, disconnect_on, @@ -115,11 +114,9 @@ class _NeverConnection(_FlakyConnection): disconnect_after_timeouts = 0 -def test_connection_spec_constructs_with_reconnect_settings(): - spec = ConnectionSpec("flaky", _FlakyConnection).reconnect(attempts=5, period=1.0) - connection = spec.construct() +def test_set_reconnect_on_connection(): + connection = _FlakyConnection().set_reconnect(attempts=5, period=1.0) - assert isinstance(connection, _FlakyConnection) assert (connection.reconnect_attempts, connection.reconnect_period) == (5, 1.0) - with pytest.raises(ValueError, match="flaky sets reconnect attempts but not"): - spec.reconnect(attempts=5, period=None) + with pytest.raises(ValueError, match="_FlakyConnection sets reconnect attempts"): + connection.set_reconnect(attempts=5, period=None) From 68f9f7b662047139371b3a86e1e05a9dd701ec9e Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 14:46:55 +0000 Subject: [PATCH 09/14] fix docs build --- src/fastcs/connections/builtin/__init__.py | 2 +- src/fastcs/connections/connection_spec.py | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/src/fastcs/connections/builtin/__init__.py b/src/fastcs/connections/builtin/__init__.py index 1d604cc50..12f669255 100644 --- a/src/fastcs/connections/builtin/__init__.py +++ b/src/fastcs/connections/builtin/__init__.py @@ -1 +1 @@ -"""Connections that FastCS provides, re-exported from `fastcs.connections`""" +"""Connections that FastCS provides, re-exported from ``fastcs.connections``""" diff --git a/src/fastcs/connections/connection_spec.py b/src/fastcs/connections/connection_spec.py index e946eeaba..451774196 100644 --- a/src/fastcs/connections/connection_spec.py +++ b/src/fastcs/connections/connection_spec.py @@ -7,6 +7,7 @@ P = ParamSpec("P") ConnectionT = TypeVar("ConnectionT", bound=Connection) +"""The `Connection` that a `ConnectionSpec` constructs""" class ConnectionSpec(Generic[P, ConnectionT]): From 03229471633db6bf0c03ab1786e203858becb0e5 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 16:30:24 +0000 Subject: [PATCH 10/14] add disconnect_after_timeouts to set_reconnect() --- docs/explanations/connections.md | 7 +++++-- src/fastcs/connections/connection.py | 29 +++++++++++++++++++++++----- src/fastcs/launch.py | 6 +++--- tests/test_connection.py | 5 +++++ 4 files changed, 37 insertions(+), 10 deletions(-) diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index ecaf4e0b1..cdc14a8a0 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -119,10 +119,13 @@ class EigerConnection(Connection): A class that sets `reconnect_attempts` must set `reconnect_period` too, or defining it raises a `TypeError`. In Python, set them on one connection with `set_reconnect`, which -returns the connection: +returns the connection. `disconnect_after_timeouts` is optional, and keeps the class's +value if it's left out: ```python -connection = IPConnection("10.0.0.5", 4000).set_reconnect(attempts=5, period=2.0) +connection = IPConnection("10.0.0.5", 4000).set_reconnect( + attempts=5, period=2.0, disconnect_after_timeouts=3 +) ``` | Connection | `reconnect_attempts` | `reconnect_period` | diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index 9b7364388..3f3ef60fe 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -156,23 +156,34 @@ def __init_subclass__(cls, **kwargs: Any) -> None: "it must be an integer of at least 1" ) - def set_reconnect(self, *, attempts: int | None, period: float | None) -> Self: - """Set this connection's ``reconnect_attempts`` and ``reconnect_period``, - instead of using its class's. + def set_reconnect( + self, + *, + attempts: int | None, + period: float | None, + disconnect_after_timeouts: int | None = None, + ) -> Self: + """Set this connection's ``reconnect_attempts`` and ``reconnect_period``, and + optionally its ``disconnect_after_timeouts``, instead of using its class's. Example:: - odin = OdinConnection(url).set_reconnect(attempts=10, period=2.0) + odin = OdinConnection(url).set_reconnect( + attempts=10, period=2.0, disconnect_after_timeouts=3 + ) Args: attempts: How many times to try to reconnect. None or 0 means don't period: How many seconds apart to try + disconnect_after_timeouts: How many timeouts in a row mean the link has + gone, or None to keep the class's Returns: This connection Raises: - ValueError: If ``attempts`` is set without ``period`` + ValueError: If ``attempts`` is set without ``period``, or + ``disconnect_after_timeouts`` is less than 1 """ if attempts and period is None: @@ -180,9 +191,17 @@ def set_reconnect(self, *, attempts: int | None, period: float | None) -> Self: f"{type(self).__name__} sets reconnect attempts but not reconnect " "period" ) + if disconnect_after_timeouts is not None and disconnect_after_timeouts < 1: + raise ValueError( + f"{type(self).__name__} sets disconnect_after_timeouts to " + f"{disconnect_after_timeouts}, but it must be at least 1" + ) self.reconnect_attempts = attempts self.reconnect_period = period + if disconnect_after_timeouts is not None: + self.disconnect_after_timeouts = disconnect_after_timeouts + return self @property diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index 5be0f0e79..fc9ed9532 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -234,9 +234,9 @@ def _controller_specs( period = values.pop("reconnect_period") timeouts = values.pop("disconnect_after_timeouts") connection = ConnectionSpec(name, connection_type, **values).construct() - connection.set_reconnect(attempts=attempts, period=period) - connection.disconnect_after_timeouts = timeouts - kwargs[name] = connection + kwargs[name] = connection.set_reconnect( + attempts=attempts, period=period, disconnect_after_timeouts=timeouts + ) if registered.options_name is not None: field_values = { diff --git a/tests/test_connection.py b/tests/test_connection.py index 5a64e1a84..f44595561 100644 --- a/tests/test_connection.py +++ b/tests/test_connection.py @@ -120,3 +120,8 @@ def test_set_reconnect_on_connection(): assert (connection.reconnect_attempts, connection.reconnect_period) == (5, 1.0) with pytest.raises(ValueError, match="_FlakyConnection sets reconnect attempts"): connection.set_reconnect(attempts=5, period=None) + + connection.set_reconnect(attempts=5, period=1.0, disconnect_after_timeouts=3) + assert connection.disconnect_after_timeouts == 3 + with pytest.raises(ValueError, match="must be at least 1"): + connection.set_reconnect(attempts=5, period=1.0, disconnect_after_timeouts=0) From 6eea06c04d379e31a139eb0d8ae0c7e9b9516ff1 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 16:47:26 +0000 Subject: [PATCH 11/14] connections pass as None arent discovered --- src/fastcs/runner.py | 7 +++++-- tests/test_controller_runner.py | 16 ++++++++++++++++ 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 1803a5e50..45e9e17fe 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -98,8 +98,11 @@ async def _open_connections(self, spec: ControllerSpec) -> dict[str, Connection] """ names = _connection_names(spec) self._names.update(names) - given = set(names.values()) - parameters = inspect.signature(spec.controller_class).parameters + # Every argument the spec passes, even None, so it isn't passed again + signature = inspect.signature(spec.controller_class) + supplied = signature.bind_partial(*spec.args).arguments + given = {*names.values(), *supplied, *spec.kwargs} + parameters = signature.parameters takes = set(parameters) - given discovered: dict[str, Connection] = {} diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 14ca5d09c..2b14ffd8c 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -686,6 +686,22 @@ async def test_discovered_connection_is_opened_and_passed_by_name(): assert len(runner._connections) == 2 +@pytest.mark.asyncio +async def test_connection_given_as_none_is_not_discovered(): + runner = await ControllerRunner.build( + [ + ControllerSpec( + "A", DetectorController, DetectorConnection(), detector_meta=None + ) + ] + ) + controller = runner.controllers[0] + assert isinstance(controller, DetectorController) + + assert controller.meta is None + assert len(runner._connections) == 1 + + @pytest.mark.asyncio async def test_given_connection_is_used_instead_of_discovered(): given = MetaConnection() From 13e4a6542f327fad22718e9ad810b68fde3a14da Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 16:49:29 +0000 Subject: [PATCH 12/14] replace add_parent with with_parent --- src/fastcs/connections/connection_spec.py | 17 +++++++++----- src/fastcs/runner.py | 27 ++++++++++++----------- tests/test_controller_runner.py | 26 ++++++++++++++++++++++ 3 files changed, 52 insertions(+), 18 deletions(-) diff --git a/src/fastcs/connections/connection_spec.py b/src/fastcs/connections/connection_spec.py index 451774196..8434595b3 100644 --- a/src/fastcs/connections/connection_spec.py +++ b/src/fastcs/connections/connection_spec.py @@ -1,5 +1,6 @@ +import copy from collections.abc import Callable -from typing import Generic, ParamSpec +from typing import Generic, ParamSpec, Self from typing_extensions import TypeVar @@ -58,18 +59,24 @@ def __repr__(self) -> str: def _fields(self) -> tuple: return (self.name, self.connection_class, self.args, self.kwargs) - def add_parent(self, parent_name: str) -> None: - """Prefix the name with that of the connection that discovered it. + def with_parent(self, parent_name: str) -> Self: + """A copy of this spec, with its name prefixed by that of the connection that + discovered it. Example:: - spec.add_parent("odin") # "meta" -> "odin_meta" + spec.with_parent("odin").name # "meta" -> "odin_meta" Args: parent_name: The name of the connection whose introspection returned this + Returns: + The renamed copy + """ - self.name = f"{parent_name}_{self.name}" + spec = copy.copy(self) + spec.name = f"{parent_name}_{self.name}" + return spec def construct(self) -> ConnectionT: """Construct the connection""" diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 45e9e17fe..68fb598f5 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -111,12 +111,12 @@ async def _open_connections(self, spec: ControllerSpec) -> dict[str, Connection] found: list[Connection] = [] for connection in _dependency_order(pending): introspection = await self._open(connection) - specs = _subconnections( - introspection, self._names[id(connection)], takes + named = _named_subconnections( + introspection, self._names[id(connection)] ) self._takes[id(connection)] = takes - self._subconnections[id(connection)] = specs - for subconnection in introspection.subconnections: + self._subconnections[id(connection)] = _taken(named, takes) + for subconnection in named: name = subconnection.name if name in given: logger.info("Using given connection, not discovered", name=name) @@ -304,7 +304,8 @@ async def _reconnect(self, connection: Connection) -> None: "controllers built from it are out of date" ) - specs = _subconnections(introspection, name, self._takes[id(connection)]) + named = _named_subconnections(introspection, name) + specs = _taken(named, self._takes[id(connection)]) old_specs = self._subconnections[id(connection)] for changed in sorted(old_specs.keys() | specs.keys()): old, new = old_specs.get(changed), specs.get(changed) @@ -404,15 +405,15 @@ def _held_connections(controller: BaseController) -> list[Connection]: return list({id(v): v for v in values if isinstance(v, Connection)}.values()) -def _subconnections( - introspection: Introspection, parent_name: str, takes: set[str] -) -> dict[str, ConnectionSpec]: - """Name an introspection's subconnections after their parent, and keep those the - controller takes, by name""" - for subconnection in introspection.subconnections: - subconnection.add_parent(parent_name) +def _named_subconnections( + introspection: Introspection, parent_name: str +) -> list[ConnectionSpec]: + """Copies of an introspection's subconnections, named after their parent""" + return [spec.with_parent(parent_name) for spec in introspection.subconnections] - specs = introspection.subconnections + +def _taken(specs: list[ConnectionSpec], takes: set[str]) -> dict[str, ConnectionSpec]: + """The specs the controller takes, by name""" return {spec.name: spec for spec in specs if spec.name in takes} diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 2b14ffd8c..631da6f7b 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -749,3 +749,29 @@ async def test_discovered_connection_changing_on_reconnect_is_fatal(): with pytest.raises(IntrospectionMismatchError, match="port=5002.*port=5001"): await asyncio.wait_for(runner.wait_for_fatal_error(), timeout=1) await runner.stop() + + +class CachedDetectorConnection(DetectorConnection): + reconnect_attempts = 10 + reconnect_period = 0 + + def __init__(self) -> None: + meta = ConnectionSpec("meta", MetaConnection) + self.cached = Introspection(None, subconnections=[meta]) + + async def introspect(self) -> Introspection: + return self.cached + + +@pytest.mark.asyncio +async def test_introspection_returning_the_same_specs_still_reconnects(): + connection = CachedDetectorConnection() + runner = await ControllerRunner.build( + [ControllerSpec("A", DetectorController, connection)] + ) + await runner.start() + + connection.state.mark_down() + await asyncio.wait_for(connection.state.wait_up(), timeout=1) + assert connection.cached.subconnections[0].name == "meta" + await runner.stop() From aa9682c8a4abb01639a6a9cf3a4c70b46ea2b9ef Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 16:52:38 +0000 Subject: [PATCH 13/14] don't allow connections ot depend on discovered connections --- docs/explanations/connections.md | 2 ++ src/fastcs/runner.py | 20 ++++++++++++---- tests/test_controller_runner.py | 39 ++++++++++++++++++++++++++++++++ 3 files changed, 57 insertions(+), 4 deletions(-) diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index cdc14a8a0..ec87c4ccb 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -190,6 +190,8 @@ class EigerController(Controller): `ControllerSpec`, is used instead of the discovered one. - It's independent of the connection that discovered it, so it only goes down when its own IO fails. Set `depends_on` on its class if it needs its parent to be up first. +- It's opened after the connection that discovered it, so no connection opened before + it can depend on it. FastCS raises a `ValueError` at startup if one does. - It uses its class's reconnect settings. To set others, give it a block in `fastcs.yaml` instead. - If a reconnect discovers a different spec for a connection the controller takes, diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 68fb598f5..b13991e51 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -60,8 +60,9 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: ``controller_apis``, in the order the specs were given Raises: - ValueError: If a connection is shared between specs, or two discovered - connections have the same name + ValueError: If a connection is shared between specs, two discovered + connections have the same name, or a connection depends on one that + is discovered after it's opened """ _check_connections_not_shared(specs) @@ -93,7 +94,8 @@ async def _open_connections(self, spec: ControllerSpec) -> dict[str, Connection] The discovered connections that were opened, by name Raises: - ValueError: If two discovered connections have the same name + ValueError: If two discovered connections have the same name, or a + connection depends on one that is discovered after it's opened """ names = _connection_names(spec) @@ -131,8 +133,18 @@ async def _open_connections(self, spec: ControllerSpec) -> dict[str, Connection] pending = found connections = [*spec.connections, *discovered.values()] + opened = {id(c): index for index, c in enumerate(self._connections)} for connection in connections: - self._dependencies[id(connection)] = _dependencies(connection, connections) + dependencies = _dependencies(connection, connections) + self._dependencies[id(connection)] = dependencies + for dependency in dependencies: + if opened[id(dependency)] > opened[id(connection)]: + name = self._names[id(connection)] + later = self._names[id(dependency)] + raise ValueError( + f"{name} depends on {later}, but {later} is only discovered " + f"after {name} has been opened" + ) return discovered diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 631da6f7b..863626a64 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -775,3 +775,42 @@ async def test_introspection_returning_the_same_specs_still_reconnects(): await asyncio.wait_for(connection.state.wait_up(), timeout=1) assert connection.cached.subconnections[0].name == "meta" await runner.stop() + + +class LateConnection(MetaConnection): + pass + + +class LateDiscoveringConnection(MetaConnection): + async def introspect(self) -> Introspection: + late = ConnectionSpec("late", LateConnection) + return Introspection(None, subconnections=[late]) + + +class NeedsLateConnection(MetaConnection): + depends_on = LateConnection + + +class LateController(Controller): + def __init__( + self, + parent: LateDiscoveringConnection, + needs: NeedsLateConnection, + parent_late: LateConnection | None = None, + ) -> None: + super().__init__() + + +@pytest.mark.asyncio +async def test_depending_on_a_connection_discovered_later_raises(): + with pytest.raises(ValueError, match="needs depends on parent_late, but"): + await ControllerRunner.build( + [ + ControllerSpec( + "A", + LateController, + LateDiscoveringConnection(), + NeedsLateConnection(), + ) + ] + ) From 7aa551c360d347edc78a0477db3672a93952e5d3 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 17:12:04 +0000 Subject: [PATCH 14/14] ensure dependency check for discovered connections happens earlier --- docs/explanations/connections.md | 5 ++- src/fastcs/connections/connection.py | 33 ++++++++++++++- src/fastcs/launch.py | 23 +--------- src/fastcs/runner.py | 63 +++++++++++++++++++++++----- tests/test_controller_runner.py | 52 ++++++++++++++++++----- 5 files changed, 131 insertions(+), 45 deletions(-) diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index ec87c4ccb..6b06bf8e0 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -190,8 +190,9 @@ class EigerController(Controller): `ControllerSpec`, is used instead of the discovered one. - It's independent of the connection that discovered it, so it only goes down when its own IO fails. Set `depends_on` on its class if it needs its parent to be up first. -- It's opened after the connection that discovered it, so no connection opened before - it can depend on it. FastCS raises a `ValueError` at startup if one does. +- It's opened after the connections that are given, so none of those can depend on + it. If a given connection's `depends_on` matches the type of a controller argument + that isn't given, FastCS raises a `ValueError` before opening anything. - It uses its class's reconnect settings. To set others, give it a block in `fastcs.yaml` instead. - If a reconnect discovers a different spec for a connection the controller takes, diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index 3f3ef60fe..d314a8520 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -7,7 +7,19 @@ from abc import ABC, abstractmethod from collections.abc import Callable, Coroutine, Mapping, Sequence from contextvars import ContextVar -from typing import TYPE_CHECKING, Any, ClassVar, Generic, Self, cast, overload +from types import UnionType +from typing import ( + TYPE_CHECKING, + Any, + ClassVar, + Generic, + Self, + Union, + cast, + get_args, + get_origin, + overload, +) from pydantic import BaseModel from typing_extensions import TypeVar @@ -356,3 +368,22 @@ def _structure(value: Any) -> Any: if isinstance(value, list | tuple): return [_structure(item) for item in value] return None + + +def _connection_hint(hint: Any) -> tuple[type[Connection] | None, bool]: + """The connection class a controller argument's hint names, if any, and whether + it's optional, as in ``MetaConnection | None``""" + optional = False + if get_origin(hint) in (Union, UnionType): + members = [member for member in get_args(hint) if member is not type(None)] + if len(members) != 1: + return None, False + + hint, optional = members[0], True + + # A parametrised hint like IPConnection[Introspection] is checked by its class + hint = get_origin(hint) or hint + if isinstance(hint, type) and issubclass(hint, Connection): + return hint, optional + + return None, False diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index fc9ed9532..380a51eb5 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -4,7 +4,6 @@ import inspect import json from pathlib import Path -from types import UnionType from typing import ( TYPE_CHECKING, Annotated, @@ -13,8 +12,6 @@ Optional, Self, Union, - get_args, - get_origin, get_type_hints, ) @@ -31,6 +28,7 @@ from fastcs import __version__ from fastcs.connections import Connection, ConnectionSpec +from fastcs.connections.connection import _connection_hint from fastcs.control_system import FastCS from fastcs.controllers import Controller, ControllerSpec from fastcs.exceptions import LaunchError @@ -302,25 +300,6 @@ def _drop_default(schema: dict[str, Any]) -> None: @functools.cache -def _connection_hint(hint: Any) -> tuple[type[Connection] | None, bool]: - """The connection class a controller argument's hint names, if any, and whether - it's optional, as in ``MetaConnection | None``""" - optional = False - if get_origin(hint) in (Union, UnionType): - members = [member for member in get_args(hint) if member is not type(None)] - if len(members) != 1: - return None, False - - hint, optional = members[0], True - - # A parametrised hint like IPConnection[Introspection] is checked by its class - hint = get_origin(hint) or hint - if isinstance(hint, type) and issubclass(hint, Connection): - return hint, optional - - return None, False - - def _connection_settings_model(connection_type: type[Connection]) -> type[BaseModel]: """Build the Pydantic model for one connection's block under `connections:`. diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index b13991e51..866492cce 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -2,7 +2,7 @@ import inspect from collections import defaultdict from collections.abc import Iterator, Sequence -from typing import Self, TypeVar +from typing import Self, TypeVar, get_type_hints from fastcs.attributes.attr_r import AttrR from fastcs.connections import ( @@ -11,7 +11,7 @@ ConnectionState, Introspection, ) -from fastcs.connections.connection import _reconnecting +from fastcs.connections.connection import _connection_hint, _reconnecting from fastcs.controllers.base_controller import BaseController from fastcs.controllers.controller import Controller from fastcs.controllers.controller_api import ControllerAPI @@ -62,10 +62,13 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: Raises: ValueError: If a connection is shared between specs, two discovered connections have the same name, or a connection depends on one that - is discovered after it's opened + can only be discovered after it's opened """ _check_connections_not_shared(specs) + for spec in specs: + _check_dependencies_not_discovered(spec) + runner = cls() try: @@ -98,13 +101,9 @@ async def _open_connections(self, spec: ControllerSpec) -> dict[str, Connection] connection depends on one that is discovered after it's opened """ - names = _connection_names(spec) - self._names.update(names) - # Every argument the spec passes, even None, so it isn't passed again - signature = inspect.signature(spec.controller_class) - supplied = signature.bind_partial(*spec.args).arguments - given = {*names.values(), *supplied, *spec.kwargs} - parameters = signature.parameters + self._names.update(_connection_names(spec)) + given = _given(spec) + parameters = inspect.signature(spec.controller_class).parameters takes = set(parameters) - given discovered: dict[str, Connection] = {} @@ -459,6 +458,50 @@ def _connection_names(spec: ControllerSpec) -> dict[int, str]: return names +def _given(spec: ControllerSpec) -> set[str]: + """The controller arguments a spec passes, even as None, so that a connection + isn't discovered for them""" + signature = inspect.signature(spec.controller_class) + supplied = signature.bind_partial(*spec.args).arguments + return {*_connection_names(spec).values(), *supplied, *spec.kwargs} + + +def _check_dependencies_not_discovered(spec: ControllerSpec) -> None: + """Check that no connection a spec gives depends on one that could only be + discovered, which would be opened after it. + + Raises: + ValueError: If a given connection's ``depends_on`` matches the type of a + controller argument that isn't given + + """ + controller_class = spec.controller_class + try: + init = controller_class.__init__ if isinstance(controller_class, type) else None + hints = get_type_hints(init or controller_class) + except NameError: + # Hints that can't be resolved are left to the check after opening + return + + given = _given(spec) + discoverable: dict[str, type[Connection]] = {} + for name in inspect.signature(controller_class).parameters: + connection_type, _ = _connection_hint(hints.get(name)) + if name not in given and connection_type is not None: + discoverable[name] = connection_type + + names = _connection_names(spec) + for connection in {id(c): c for c in spec.connections}.values(): + for dependency in _dependency_types(connection): + for name, connection_type in discoverable.items(): + if issubclass(connection_type, dependency): + raise ValueError( + f"{names[id(connection)]} depends on {dependency.__name__}, " + f"but {name} can only be discovered after " + f"{names[id(connection)]} has been opened" + ) + + def _check_connections_not_shared(specs: list[ControllerSpec]) -> None: """Check that no connection is used by more than one spec. diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 863626a64..560aaa19e 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -790,6 +790,12 @@ async def introspect(self) -> Introspection: class NeedsLateConnection(MetaConnection): depends_on = LateConnection + def __init__(self) -> None: + self.opened = False + + async def connect(self) -> None: + self.opened = True + class LateController(Controller): def __init__( @@ -802,15 +808,41 @@ def __init__( @pytest.mark.asyncio -async def test_depending_on_a_connection_discovered_later_raises(): - with pytest.raises(ValueError, match="needs depends on parent_late, but"): +async def test_depending_on_a_connection_only_discovered_raises_before_opening(): + needs = NeedsLateConnection() + message = "needs depends on LateConnection, but parent_late can only be discovered" + with pytest.raises(ValueError, match=message): await ControllerRunner.build( - [ - ControllerSpec( - "A", - LateController, - LateDiscoveringConnection(), - NeedsLateConnection(), - ) - ] + [ControllerSpec("A", LateController, LateDiscoveringConnection(), needs)] + ) + + assert not needs.opened + + +class NestedLateConnection(LateDiscoveringConnection): + depends_on = LateConnection + + +class NestingConnection(MetaConnection): + async def introspect(self) -> Introspection: + nested = ConnectionSpec("nested", NestedLateConnection) + return Introspection(None, subconnections=[nested]) + + +class NestingController(Controller): + def __init__( + self, + parent: NestingConnection, + parent_nested: NestedLateConnection | None = None, + parent_nested_late: LateConnection | None = None, + ) -> None: + super().__init__() + + +@pytest.mark.asyncio +async def test_discovered_connection_depending_on_one_discovered_later_raises(): + message = "parent_nested depends on parent_nested_late, but" + with pytest.raises(ValueError, match=message): + await ControllerRunner.build( + [ControllerSpec("A", NestingController, NestingConnection())] )