diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index 009dc4562..6b06bf8e0 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -118,7 +118,15 @@ 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. `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, disconnect_after_timeouts=3 +) +``` | Connection | `reconnect_attempts` | `reconnect_period` | |---|---|---| @@ -141,6 +149,51 @@ 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'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, + such as a new port, FastCS stops with an `IntrospectionMismatchError`. 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..0c7e1f492 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -2,17 +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 .ip_connection import IPConnection as IPConnection +from .connection_spec import ConnectionSpec as ConnectionSpec 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..12f669255 --- /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/connections/connection.py b/src/fastcs/connections/connection.py index e1f2a9d9d..d314a8520 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -7,15 +7,54 @@ 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 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 +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""" +@dataclasses.dataclass +class Introspection(Generic[IntrospectionT]): + """What a `Connection`'s ``introspect`` returns. + + Example:: + + 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): """Raised when using a connection whose link is down or closed""" @@ -88,7 +127,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 @@ -129,9 +168,58 @@ 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, + 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, 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``, or + ``disconnect_after_timeouts`` is less than 1 + + """ + if attempts and period is None: + raise ValueError( + 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 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 +250,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: @@ -279,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/connections/connection_spec.py b/src/fastcs/connections/connection_spec.py new file mode 100644 index 000000000..8434595b3 --- /dev/null +++ b/src/fastcs/connections/connection_spec.py @@ -0,0 +1,83 @@ +import copy +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) +"""The `Connection` that a `ConnectionSpec` constructs""" + + +class ConnectionSpec(Generic[P, ConnectionT]): + """A deferred call that constructs a named connection. + + Example:: + + # 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 + 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 + + 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()), + ] + return f"ConnectionSpec({', '.join(arguments)})" + + def _fields(self) -> tuple: + return (self.name, self.connection_class, self.args, self.kwargs) + + 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.with_parent("odin").name # "meta" -> "odin_meta" + + Args: + parent_name: The name of the connection whose introspection returned this + + Returns: + The renamed copy + + """ + spec = copy.copy(self) + spec.name = f"{parent_name}_{self.name}" + return spec + + def construct(self) -> ConnectionT: + """Construct the connection""" + return 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/launch.py b/src/fastcs/launch.py index 71470f216..380a51eb5 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -12,7 +12,6 @@ Optional, Self, Union, - get_origin, get_type_hints, ) @@ -28,7 +27,8 @@ from ruamel.yaml import YAML from fastcs import __version__ -from fastcs.connections import Connection +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 @@ -223,15 +223,18 @@ 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") timeouts = values.pop("disconnect_after_timeouts") - connection = connection_type(**values) - connection.reconnect_attempts = attempts - connection.reconnect_period = period - connection.disconnect_after_timeouts = timeouts - kwargs[name] = connection + connection = ConnectionSpec(name, connection_type, **values).construct() + kwargs[name] = connection.set_reconnect( + attempts=attempts, period=period, disconnect_after_timeouts=timeouts + ) if registered.options_name is not None: field_values = { @@ -402,17 +405,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/src/fastcs/runner.py b/src/fastcs/runner.py index 46b5c0bf3..866492cce 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -1,11 +1,17 @@ import asyncio +import inspect from collections import defaultdict from collections.abc import Iterator, Sequence -from typing import Self +from typing import Self, TypeVar, get_type_hints from fastcs.attributes.attr_r import AttrR -from fastcs.connections import Connection, ConnectionState -from fastcs.connections.connection import _reconnecting +from fastcs.connections import ( + Connection, + ConnectionSpec, + ConnectionState, + Introspection, +) +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 @@ -15,6 +21,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.""" @@ -27,6 +35,10 @@ 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) @@ -48,24 +60,23 @@ 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, two discovered + connections have the same name, or a connection depends on one that + 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: - for spec in specs: - for connection in _dependency_order(spec.connections): - connection.state = ConnectionState() - await connection.connect() - runner._connections.append(connection) - connection.introspection = await connection.introspect() - 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() @@ -78,6 +89,79 @@ 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, or a + connection depends on one that is discovered after it's opened + + """ + self._names.update(_connection_names(spec)) + given = _given(spec) + parameters = inspect.signature(spec.controller_class).parameters + takes = set(parameters) - given + discovered: dict[str, Connection] = {} + + pending = spec.connections + while pending: + found: list[Connection] = [] + for connection in _dependency_order(pending): + introspection = await self._open(connection) + named = _named_subconnections( + introspection, self._names[id(connection)] + ) + self._takes[id(connection)] = takes + 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) + 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()] + opened = {id(c): index for index, c in enumerate(self._connections)} + for connection in 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 + + 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""" @@ -188,10 +272,11 @@ 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 = type(connection).__name__ + name = self._names[id(connection)] attempts = connection.reconnect_attempts period = connection.reconnect_period if not attempts: @@ -215,21 +300,32 @@ 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 + "Reconnect failed", connection=name, attempt=attempt + 1 ) continue 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" ) + 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) + 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 @@ -320,6 +416,92 @@ def _held_connections(controller: BaseController) -> list[Connection]: return list({id(v): v for v in values if isinstance(v, Connection)}.values()) +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] + + +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} + + +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` + + """ + 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 + + +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 _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/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 diff --git a/tests/test_connection.py b/tests/test_connection.py index fee75ba14..f44595561 100644 --- a/tests/test_connection.py +++ b/tests/test_connection.py @@ -112,3 +112,16 @@ def test_disconnect_after_timeouts_must_be_at_least_one(): class _NeverConnection(_FlakyConnection): disconnect_after_timeouts = 0 + + +def test_set_reconnect_on_connection(): + connection = _FlakyConnection().set_reconnect(attempts=5, period=1.0) + + 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) 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..560aaa19e 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -3,7 +3,13 @@ import pytest -from fastcs.connections import Connection, DisconnectedError, disconnect_on +from fastcs.connections import ( + Connection, + ConnectionSpec, + DisconnectedError, + Introspection, + disconnect_on, +) from fastcs.connections.connection import _structure from fastcs.controllers import Controller, ControllerSpec from fastcs.exceptions import IntrospectionMismatchError, ReconnectFailedError @@ -213,7 +219,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 +238,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 +346,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 +386,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 @@ -536,7 +555,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() @@ -594,11 +615,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 @@ -621,3 +644,205 @@ 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_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() + 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 + + +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() + + +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() + + +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 + + def __init__(self) -> None: + self.opened = False + + async def connect(self) -> None: + self.opened = True + + +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_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(), 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())] + ) 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