diff --git a/docs/explanations/controllers.md b/docs/explanations/controllers.md index 2378144d2..b1cb7ddca 100644 --- a/docs/explanations/controllers.md +++ b/docs/explanations/controllers.md @@ -7,23 +7,25 @@ FastCS provides three controller classes: `Controller`, `ControllerVector`, and `Controller` is the primary building block for FastCS drivers. It can serve two roles: -**Root controller:** passed directly to the `FastCS` launcher. In this role, FastCS -will call its lifecycle hooks and run the scan tasks it creates on the event loop. +**Root controller:** passed to the `FastCS` launcher in a `ControllerSpec`. In this +role, FastCS opens the `Connection`s it is given, constructs it, calls its lifecycle +hooks and runs the scan tasks it creates on the event loop. **Sub controller:** attached to a parent controller via `add_sub_controller()` or by -assigning it as an attribute. In this role, the sub controller's lifecycle hooks -(`connect`, `reconnect`, `initialise`, `disconnect`) are not called automatically by -FastCS. The parent controller is responsible for calling them as part of its own -lifecycle, if required. +assigning it as an attribute. In this role, the sub controller's `reconnect` hook is +not called automatically by FastCS. The parent controller is responsible for calling it +as part of its own lifecycle, if required. ### Lifecycle hooks | Method | Purpose | |---|---| -| `initialise` | Dynamically add attributes on startup, before the API is built | -| `connect` | Open connection to device | +| `setup` | Called by the framework after all attributes are added, before serving the application. Called on every controller in the tree | | `reconnect` | Re-open connection after scan error | -| `disconnect` | Release device resources before shutdown | + +Connections to the device are not opened by the controller. They are `Connection`s +passed to its constructor, which FastCS opens before constructing it and closes on +shutdown. ### Scan task behaviour @@ -44,23 +46,21 @@ class TemperatureController(Controller): temperature = AttrR(Float(units="degC")) setpoint = AttrRW(Float(units="degC")) - async def connect(self): - self._client = await DeviceClient.connect(self._host, self._port) - self._connected = True + def __init__(self, connection: DeviceConnection): + super().__init__() + self._connection = connection async def reconnect(self): try: - self._client = await DeviceClient.connect(self._host, self._port) + await self._connection.close() + await self._connection.connect() self._connected = True except Exception: logger.error("Failed to reconnect") - async def disconnect(self): - await self._client.close() - @scan(period=1.0) async def update_temperature(self): - value = await self._client.get_temperature() + value = await self._connection.get_temperature() await self.temperature.update(value) ``` @@ -68,27 +68,23 @@ class TemperatureController(Controller): When a `Controller` is nested inside another, it organises the driver into logical sections and its attributes are exposed under a prefixed path. If the sub -controller also has connection logic, the parent must invoke it explicitly: +controller needs the connection, the parent passes it down: ```python class ChannelController(Controller): value = AttrR(Float()) - async def connect(self): - ... - self._connected = True + def __init__(self, connection: DeviceConnection): + super().__init__() + self._connection = connection class RootController(Controller): channel: ChannelController - def __init__(self): + def __init__(self, connection: DeviceConnection): super().__init__() - self.channel = ChannelController() - - async def connect(self): - await self.channel.connect() - self._connected = True + self.channel = ChannelController(connection) ``` ## ControllerVector @@ -120,12 +116,6 @@ class RootController(Controller): {i: ChannelController() for i in range(num_channels)} ) - async def connect(self): - for channel in self.channels.values(): - await channel.connect() - - self._connected = True - async def update_all(self): for index, channel in self.channels.items(): value = await self._client.get_channel(index) @@ -145,7 +135,7 @@ Use `ControllerVector` when: - The device has a set of identical channels, axes, or modules identified by number - You need to iterate over sub controllers and perform the same action on each -- The number of instances may vary (e.g. determined at runtime during `initialise`) +- The number of instances may vary (e.g. determined from the connection's introspection) Use a plain `Controller` with named sub controllers when the sub controllers are distinct components with different types or roles. diff --git a/docs/explanations/what-is-fastcs.md b/docs/explanations/what-is-fastcs.md index 501a54284..cbcce2729 100644 --- a/docs/explanations/what-is-fastcs.md +++ b/docs/explanations/what-is-fastcs.md @@ -54,8 +54,8 @@ using `ControllerVector`. See [Controllers](controllers.md) for details. ## Writing a driver To create a driver, subclass `Controller`, declare attributes and commands as typed -class members, and implement lifecycle hooks (`connect`, `reconnect`, `disconnect`) and -periodic scan tasks. The [tutorials](../tutorials.md) walk through a complete example. +class members, take the `Connection`s it needs as constructor arguments, and implement +lifecycle hooks (`setup`, `reconnect`) and periodic scan tasks. The [tutorials](../tutorials.md) walk through a complete example. ## Deploying as an application diff --git a/docs/how-to/launch-framework.md b/docs/how-to/launch-framework.md index 7b9d811ee..1004f1cf2 100644 --- a/docs/how-to/launch-framework.md +++ b/docs/how-to/launch-framework.md @@ -52,6 +52,57 @@ if __name__ == "__main__": launch(DeviceController, version="1.0.0") ``` +## Adding Connections + +Any `__init__` argument whose type is a `Connection` becomes a block under the +entry's `connections:` key, named after the argument. Its fields are the +connection's constructor arguments. FastCS opens each connection before +constructing the controller, and closes it on shutdown. + +The address and port now belong to the connection, so they move out of +`DeviceSettings` and into the `connections:` block: + +```python +from dataclasses import dataclass + +from fastcs.connections import IPConnection +from fastcs.controllers import Controller + +@dataclass +class DeviceSettings: + timeout: float = 5.0 + +class DeviceController(Controller): + def __init__(self, connection: IPConnection, settings: DeviceSettings): + super().__init__() + self.connection = connection + self.settings = settings +``` + +```yaml +controllers: + - id: DEVICE + type: my_driver.DeviceController + connections: + connection: + ip: "192.168.1.100" + port: 25565 + timeout: 10.0 +``` + +If one connection needs another to be open first, declare it on the connection +class with `depends_on`. FastCS then opens the connections it depends on first, +and closes them last: + +```python +class OdinConnection(Connection): + depends_on = EigerConnection +``` + +For several types, use a list: `depends_on = [EigerConnection, OtherConnection]`. +A connection depends on every connection of the listed types in the same +controller entry. + ## YAML Configuration Files Create a YAML configuration file matching the schema. The conventional @@ -204,8 +255,10 @@ FastCS: 0.12.0 The `launch()` function requires: -1. Controller `__init__` must have at most 2 arguments (including `self`) +1. Controller `__init__` may take any number of `Connection` arguments, and at most + one other argument, the configuration 2. If a configuration argument exists, it must have a type hint +3. Every constructor argument of a `Connection` must have a type hint Using a dataclass or Pydantic model is recommended for the configuration type, as it enables JSON schema generation. Other type-hinted types will work, but will not produce a useful schema. diff --git a/docs/how-to/migrate-to-multi-controller.md b/docs/how-to/migrate-to-multi-controller.md index a7038f5c4..09ea7b962 100644 --- a/docs/how-to/migrate-to-multi-controller.md +++ b/docs/how-to/migrate-to-multi-controller.md @@ -75,7 +75,7 @@ transport: The same applies to PVA. If you construct transports in Python rather than via YAML, replace `EpicsCATransport(epicsca=EpicsIOCOptions( pv_prefix="DEVICE"))` with `EpicsCATransport()` plus -`controller.set_path(["DEVICE"])` (or set the id from the YAML entry's +`ControllerSpec("DEVICE", MyController)` (or set the id from the YAML entry's `id:` field when using `launch()`). ## 4. `type:` discriminator is required on every entry @@ -103,13 +103,14 @@ transport: - epicsca: {} ``` -## 5. Direct `FastCS(...)` usage is unchanged for the single-controller case +## 5. Direct `FastCS(...)` usage takes `ControllerSpec`s -If you instantiate `FastCS` directly rather than via `launch()`, the -single-controller form `FastCS(controller, transports)` still works. -For multi-controller, pass a sequence: -`FastCS([controller_a, controller_b], transports)`. Each Controller -must have had `set_path([...])` called before being handed to `FastCS`. +If you instantiate `FastCS` directly rather than via `launch()`, pass a +list of `ControllerSpec`s instead of a constructed controller: +`FastCS([ControllerSpec("DEVICE", MyController)], transports)`. For +multi-controller, add more specs to the list: +`FastCS([ControllerSpec("A", ControllerA), ControllerSpec("B", ControllerB)], transports)`. +The spec's id replaces calling `set_path([...])`. ## 6. GUI/docs emission output is now a directory diff --git a/docs/how-to/multiple-transports.md b/docs/how-to/multiple-transports.md index 12620129b..b93f934de 100644 --- a/docs/how-to/multiple-transports.md +++ b/docs/how-to/multiple-transports.md @@ -8,17 +8,18 @@ Pass a list of transports to `FastCS`: ```python from fastcs.control_system import FastCS +from fastcs.controllers import ControllerSpec from fastcs.transports import ( EpicsCATransport, GraphQLTransport, RestTransport, ) -controller = MyController() -controller.set_path(["DEVICE"]) # PV prefix for EPICS / route prefix for REST +# "DEVICE" is the PV prefix for EPICS / route prefix for REST +spec = ControllerSpec("DEVICE", MyController) fastcs = FastCS( - controller, + [spec], [ EpicsCATransport(), RestTransport(), @@ -72,9 +73,8 @@ Each transport has its own options: ### EPICS Channel Access -The PV prefix is the first segment of the controller's path (set via -`controller.set_path([...])` or auto-seeded by `launch()` from the YAML -entry's `id:`). +The PV prefix is the first segment of the controller's path (the id given +to its `ControllerSpec`, or the YAML entry's `id:` when using `launch()`). ```python from pathlib import Path @@ -161,10 +161,10 @@ from fastcs.transports import ( EpicsPVATransport, ) -controller.set_path(["DEVICE"]) +spec = ControllerSpec("DEVICE", MyController) fastcs = FastCS( - controller, + [spec], [ EpicsCATransport( gui=EpicsGUIOptions(output_dir=Path("./opis")), diff --git a/docs/how-to/update-attributes-from-device.md b/docs/how-to/update-attributes-from-device.md index 895eb5f2a..ed9b1f4f3 100644 --- a/docs/how-to/update-attributes-from-device.md +++ b/docs/how-to/update-attributes-from-device.md @@ -261,13 +261,12 @@ class SubscriptionController(Controller): super().__init__() self._client = subscription_client - async def connect(self): + async def setup(self): # Register an async callback that forwards updates into the attribute. async def on_temperature_change(value: float) -> None: await self.temperature.update(value) await self._client.subscribe("temperature", on_temperature_change) - await super().connect() ``` If the library only supports synchronous callbacks, schedule the coroutine onto the diff --git a/docs/snippets/dynamic.py b/docs/snippets/dynamic.py index 7dde6dfe5..39d9c4fda 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -12,8 +12,8 @@ AttrRW, AttrW, ) -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Bool, DataType, Float, Int, String from fastcs.launch import FastCS from fastcs.transports.epics.ca import EpicsCATransport @@ -60,6 +60,20 @@ def create_attributes(parameters: dict[str, Any]) -> dict[str, Attribute]: return attributes +@dataclass +class TemperatureIntrospection: + parameters: dict[str, Any] + ramps: list[dict[str, Any]] + + +class TemperatureConnection(IPConnection[TemperatureIntrospection]): + async def introspect(self) -> TemperatureIntrospection: + response = await self.send_query("API?\r\n") + parameters = json.loads(response.strip("\r\n")) + ramps = parameters.pop("Ramps") + return TemperatureIntrospection(parameters, ramps) + + NumberT = TypeVar("NumberT", int, float) @@ -73,7 +87,7 @@ class TemperatureControllerAttributeIORef(AttributeIORef): class TemperatureControllerAttributeIO( AttributeIO[NumberT, TemperatureControllerAttributeIORef] ): - def __init__(self, connection: IPConnection): + def __init__(self, connection: TemperatureConnection): super().__init__() self._connection = connection @@ -96,53 +110,33 @@ class TemperatureRampController(Controller): def __init__( self, index: int, - parameters: dict[str, TemperatureControllerParameter], + parameters: dict[str, Any], io: TemperatureControllerAttributeIO, ): - self._parameters = parameters super().__init__(f"Ramp{index}", ios=[io]) - async def initialise(self): - for name, attribute in create_attributes(self._parameters).items(): + for name, attribute in create_attributes(parameters).items(): self.add_attribute(name, attribute) class TemperatureController(Controller): - def __init__(self, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() - - self._io = TemperatureControllerAttributeIO(self._connection) - super().__init__(ios=[self._io]) + def __init__(self, connection: TemperatureConnection): + io = TemperatureControllerAttributeIO(connection) + super().__init__(ios=[io]) - async def connect(self): - await self._connection.connect(self._ip_settings) - - async def initialise(self): - await self.connect() - - api = json.loads((await self._connection.send_query("API?\r\n")).strip("\r\n")) - - ramps_api = api.pop("Ramps") - - for name, attribute in create_attributes(api).items(): + introspection = connection.introspection + for name, attribute in create_attributes(introspection.parameters).items(): self.add_attribute(name, attribute) - for idx, ramp_parameters in enumerate(ramps_api): - ramp_controller = TemperatureRampController( - idx + 1, ramp_parameters, self._io - ) - await ramp_controller.initialise() + for idx, ramp_parameters in enumerate(introspection.ramps): + ramp_controller = TemperatureRampController(idx + 1, ramp_parameters, io) self.add_sub_controller(f"Ramp{idx + 1:02d}", ramp_controller) - await self._connection.close() - epics_ca = EpicsCATransport() -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = TemperatureConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static02.py b/docs/snippets/static02.py index dbb79a551..398cdef38 100644 --- a/docs/snippets/static02.py +++ b/docs/snippets/static02.py @@ -1,4 +1,4 @@ -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.launch import FastCS @@ -6,7 +6,7 @@ class TemperatureController(Controller): pass -fastcs = FastCS(TemperatureController(), []) +fastcs = FastCS([ControllerSpec("DEMO", TemperatureController)], []) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static03.py b/docs/snippets/static03.py index ca73b357c..71d4b683b 100644 --- a/docs/snippets/static03.py +++ b/docs/snippets/static03.py @@ -1,5 +1,5 @@ from fastcs.attributes import AttrR -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import String from fastcs.launch import FastCS @@ -8,7 +8,7 @@ class TemperatureController(Controller): device_id = AttrR(String()) -fastcs = FastCS(TemperatureController(), []) +fastcs = FastCS([ControllerSpec("DEMO", TemperatureController)], []) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static04.py b/docs/snippets/static04.py index 345794ea9..3c867765f 100644 --- a/docs/snippets/static04.py +++ b/docs/snippets/static04.py @@ -1,5 +1,5 @@ from fastcs.attributes import AttrR -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import String from fastcs.launch import FastCS from fastcs.transports.epics.ca.transport import EpicsCATransport @@ -10,9 +10,8 @@ class TemperatureController(Controller): epics_ca = EpicsCATransport() -controller = TemperatureController() -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +spec = ControllerSpec("DEMO", TemperatureController) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static05.py b/docs/snippets/static05.py index 0d3b610af..b6c48162c 100644 --- a/docs/snippets/static05.py +++ b/docs/snippets/static05.py @@ -1,7 +1,7 @@ from pathlib import Path from fastcs.attributes import AttrR -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -14,9 +14,8 @@ class TemperatureController(Controller): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -controller = TemperatureController() -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +spec = ControllerSpec("DEMO", TemperatureController) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static06.py b/docs/snippets/static06.py index 269e3309e..81e73d757 100644 --- a/docs/snippets/static06.py +++ b/docs/snippets/static06.py @@ -1,8 +1,8 @@ from pathlib import Path from fastcs.attributes import AttrR -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -12,22 +12,17 @@ class TemperatureController(Controller): device_id = AttrR(String()) - def __init__(self, settings: IPConnectionSettings): + def __init__(self, connection: IPConnection): super().__init__() - self._ip_settings = settings - self._connection = IPConnection() - - async def connect(self): - await self._connection.connect(self._ip_settings) + self._connection = connection gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static07.py b/docs/snippets/static07.py index cac5549d3..9835da054 100644 --- a/docs/snippets/static07.py +++ b/docs/snippets/static07.py @@ -3,8 +3,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -34,22 +34,17 @@ async def update(self, attr: AttrR[NumberT, IDAttributeIORef]): class TemperatureController(Controller): device_id = AttrR(String(), io_ref=IDAttributeIORef()) - def __init__(self, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, connection: IPConnection): + self._connection = connection super().__init__(ios=[IDAttributeIO(self._connection)]) - async def connect(self): - await self._connection.connect(self._ip_settings) - gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static08.py b/docs/snippets/static08.py index 5382fa3c9..5b27f8054 100644 --- a/docs/snippets/static08.py +++ b/docs/snippets/static08.py @@ -3,8 +3,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Float, String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -40,22 +40,17 @@ class TemperatureController(Controller): device_id = AttrR(String(), io_ref=TemperatureControllerAttributeIORef("ID")) power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef("P")) - def __init__(self, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, connection: IPConnection): + self._connection = connection super().__init__(ios=[TemperatureControllerAttributeIO(self._connection)]) - async def connect(self): - await self._connection.connect(self._ip_settings) - gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static09.py b/docs/snippets/static09.py index dc5bb9d54..d40515a43 100644 --- a/docs/snippets/static09.py +++ b/docs/snippets/static09.py @@ -3,8 +3,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Float, String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -47,22 +47,17 @@ class TemperatureController(Controller): power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef("P")) ramp_rate = AttrRW(Float(), io_ref=TemperatureControllerAttributeIORef("R")) - def __init__(self, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, connection: IPConnection): + self._connection = connection super().__init__(ios=[TemperatureControllerAttributeIO(self._connection)]) - async def connect(self): - await self._connection.connect(self._ip_settings) - gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static10.py b/docs/snippets/static10.py index 24f6d523d..e701157df 100644 --- a/docs/snippets/static10.py +++ b/docs/snippets/static10.py @@ -3,8 +3,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Float, Int, String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -59,9 +59,8 @@ class TemperatureController(Controller): power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef("P")) ramp_rate = AttrRW(Float(), io_ref=TemperatureControllerAttributeIORef("R")) - def __init__(self, ramp_count: int, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, ramp_count: int, connection: IPConnection): + self._connection = connection super().__init__(ios=[TemperatureControllerAttributeIO(self._connection)]) @@ -71,16 +70,14 @@ def __init__(self, ramp_count: int, settings: IPConnectionSettings): self._ramp_controllers.append(controller) self.add_sub_controller(f"R{index}", controller) - async def connect(self): - await self._connection.connect(self._ip_settings) - gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(4, connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static11.py b/docs/snippets/static11.py index e07ed5a41..8001f092f 100644 --- a/docs/snippets/static11.py +++ b/docs/snippets/static11.py @@ -4,8 +4,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -66,9 +66,8 @@ class TemperatureController(Controller): power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef("P")) ramp_rate = AttrRW(Float(), io_ref=TemperatureControllerAttributeIORef("R")) - def __init__(self, ramp_count: int, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, ramp_count: int, connection: IPConnection): + self._connection = connection super().__init__(ios=[TemperatureControllerAttributeIO(self._connection)]) @@ -78,16 +77,14 @@ def __init__(self, ramp_count: int, settings: IPConnectionSettings): self._ramp_controllers.append(controller) self.add_sub_controller(f"R{index}", controller) - async def connect(self): - await self._connection.connect(self._ip_settings) - gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(4, connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static12.py b/docs/snippets/static12.py index 9f1f2af14..b2e1a964d 100644 --- a/docs/snippets/static12.py +++ b/docs/snippets/static12.py @@ -5,8 +5,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS from fastcs.methods import scan @@ -71,9 +71,8 @@ class TemperatureController(Controller): power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef("P")) ramp_rate = AttrRW(Float(), io_ref=TemperatureControllerAttributeIORef("R")) - def __init__(self, ramp_count: int, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, ramp_count: int, connection: IPConnection): + self._connection = connection super().__init__(ios=[TemperatureControllerAttributeIO(self._connection)]) @@ -83,9 +82,6 @@ def __init__(self, ramp_count: int, settings: IPConnectionSettings): self._ramp_controllers.append(controller) self.add_sub_controller(f"R{index}", controller) - async def connect(self): - await self._connection.connect(self._ip_settings) - @scan(0.1) async def update_voltages(self): voltages = json.loads( @@ -97,10 +93,11 @@ async def update_voltages(self): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(4, connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static13.py b/docs/snippets/static13.py index b2036c66f..bc955556f 100644 --- a/docs/snippets/static13.py +++ b/docs/snippets/static13.py @@ -6,8 +6,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS from fastcs.methods import command, scan @@ -72,9 +72,8 @@ class TemperatureController(Controller): power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef("P")) ramp_rate = AttrRW(Float(), io_ref=TemperatureControllerAttributeIORef("R")) - def __init__(self, ramp_count: int, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, ramp_count: int, connection: IPConnection): + self._connection = connection super().__init__(ios=[TemperatureControllerAttributeIO(self._connection)]) @@ -84,9 +83,6 @@ def __init__(self, ramp_count: int, settings: IPConnectionSettings): self._ramp_controllers.append(controller) self.add_sub_controller(f"R{index}", controller) - async def connect(self): - await self._connection.connect(self._ip_settings) - @scan(0.1) async def update_voltages(self): voltages = json.loads( @@ -105,10 +101,11 @@ async def disable_all(self) -> None: gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(4, connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static14.py b/docs/snippets/static14.py index f54c93d3d..c6839afda 100644 --- a/docs/snippets/static14.py +++ b/docs/snippets/static14.py @@ -6,8 +6,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS from fastcs.logging import configure_logging, logger @@ -75,9 +75,8 @@ class TemperatureController(Controller): power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef("P")) ramp_rate = AttrRW(Float(), io_ref=TemperatureControllerAttributeIORef("R")) - def __init__(self, ramp_count: int, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, ramp_count: int, connection: IPConnection): + self._connection = connection super().__init__(ios=[TemperatureControllerAttributeIO(self._connection)]) @@ -87,9 +86,6 @@ def __init__(self, ramp_count: int, settings: IPConnectionSettings): self._ramp_controllers.append(controller) self.add_sub_controller(f"R{index}", controller) - async def connect(self): - await self._connection.connect(self._ip_settings) - @scan(0.1) async def update_voltages(self): voltages = json.loads( @@ -111,11 +107,12 @@ async def disable_all(self) -> None: gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -logger.info("Configuring connection settings", connection_settings=connection_settings) -controller = TemperatureController(4, connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +logger.info("Configuring connection", ip=connection.ip, port=connection.port) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static15.py b/docs/snippets/static15.py index aa2d53a92..e0a60c7df 100644 --- a/docs/snippets/static15.py +++ b/docs/snippets/static15.py @@ -6,8 +6,8 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.connections import IPConnection +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS from fastcs.logging import LogLevel, configure_logging, logger @@ -78,9 +78,8 @@ class TemperatureController(Controller): power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef("P")) ramp_rate = AttrRW(Float(), io_ref=TemperatureControllerAttributeIORef("R")) - def __init__(self, ramp_count: int, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, ramp_count: int, connection: IPConnection): + self._connection = connection super().__init__(ios=[TemperatureControllerAttributeIO(self._connection)]) @@ -90,9 +89,6 @@ def __init__(self, ramp_count: int, settings: IPConnectionSettings): self._ramp_controllers.append(controller) self.add_sub_controller(f"R{index}", controller) - async def connect(self): - await self._connection.connect(self._ip_settings) - @scan(0.1) async def update_voltages(self): voltages = json.loads( @@ -114,11 +110,12 @@ async def disable_all(self) -> None: gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) -connection_settings = IPConnectionSettings("localhost", 25565) -logger.info("Configuring connection settings", connection_settings=connection_settings) -controller = TemperatureController(4, connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +connection = IPConnection("localhost", 25565) +logger.info("Configuring connection", ip=connection.ip, port=connection.port) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/tutorials/dynamic-drivers.md b/docs/tutorials/dynamic-drivers.md index 8b02b1e7b..4382e5f8c 100644 --- a/docs/tutorials/dynamic-drivers.md +++ b/docs/tutorials/dynamic-drivers.md @@ -29,35 +29,43 @@ This contains all the metadata about the parameters in the API needed to create fields such as the units of numerical parameters, limits that a parameter can be set to, or a description for the parameter. -## FastCS Initialisation +## Introspection -Specific `Controller` classes can optionally implement an async `initialise` method to -perform any start up logic. The intention here is that the `__init__` method should be -minimal and the `initialise` method performs any long running calls, such as querying an -API, allowing FastCS to run these concurrently to reduce start times. +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__`. -Take the driver implementation from the previous tutorial and remove the -statically defined `Attributes` and creation of sub controllers in `__init__`. Then -implement an `initialise` method to create these dynamically instead. +Take the driver implementation from the previous tutorial and remove the statically +defined `Attributes` and creation of sub controllers in `__init__`. Then create them +from the introspection instead. Create a pydantic model to validate the response from the device :::{literalinclude} /snippets/dynamic.py -:lines: 5,18-35 +:lines: 5,22-39 ::: Create a function to parse the dictionary, validate the entries against the model and create `Attributes`. :::{literalinclude} /snippets/dynamic.py -:lines: 38-56 +:lines: 42-60 ::: -Update the controllers to not define attributes statically and implement initialise -methods to create these attributes dynamically. +Define a type for the introspection, and a connection whose `introspect` queries the +`API?` command and returns one. The type parameter, +`IPConnection[TemperatureIntrospection]`, is the type that `introspect` returns. :::{literalinclude} /snippets/dynamic.py -:lines: 91-131 +:lines: 63-74 +::: + +Update the controllers to create their attributes from `connection.introspection` in +`__init__`, instead of defining them statically. + +:::{literalinclude} /snippets/dynamic.py +:lines: 109-133 ::: The `suffix` field should also be removed from `TemperatureController` and diff --git a/docs/tutorials/static-drivers.md b/docs/tutorials/static-drivers.md index f28f9b603..7dbadcc53 100644 --- a/docs/tutorials/static-drivers.md +++ b/docs/tutorials/static-drivers.md @@ -35,10 +35,12 @@ Create a `TemperatureController` class that inherits from `Controller`. ## FastCS Launcher -The entrypoint to a FastCS application is the `FastCS` class. This takes a `Controller` -and a list of transports to expose the API through and provides a `run` method to launch -the application. Create a `FastCS` instance, pass the `TemperatureController` to it -along with an empty list of transports (for now). +The entrypoint to a FastCS application is the `FastCS` class. This takes a +`ControllerSpec`, which says how to construct the `Controller` and what id to give it, +and a list of transports to expose the API through, and provides a `run` method to +launch the application. Create a `FastCS` instance, pass it a `ControllerSpec` for the +`TemperatureController` with the id `DEMO`, along with an empty list of transports (for +now). ::::{admonition} Code 2 :class: dropdown, hint @@ -78,11 +80,11 @@ doesn't have a connection. :class: dropdown, hint ::: -In [1]: controller.device_id +In [1]: controllers["DEMO"].device_id Out[1]: AttrR(String()) -In [2]: controller.device_id.get() +In [2]: controllers["DEMO"].device_id.get() Out[2]: '' ::: @@ -129,7 +131,7 @@ options to the transport options and generate a `demo.bob` file to use with Phoe :class: dropdown, hint :::{literalinclude} /snippets/static05.py -:emphasize-lines: 1,7,15-18,20 +:emphasize-lines: 1,7,15-19 ::: :::: @@ -142,10 +144,10 @@ The `Attributes` of a FastCS `Controller` need some IO with the device in order and set values. This is implemented with `AttributeIO`s and connections. Generally each driver implements its own IO and connection logic, but there are some built in options. -Update the controller to create an `IPConnection` to communicate with the simulator over -TCP and implement a `connect` method that establishes the connection. The `connect` -method is called by the FastCS application at the appropriate time during start up to -ensure the connection is established before it is used. +Create an `IPConnection` to communicate with the simulator over TCP, pass it to the +`ControllerSpec`, and update the controller to take it as a constructor argument. FastCS +opens the connection before constructing the controller, so it is ready to use, and +closes it when the application stops. :::{note} The simulator control connection is on port 25565. @@ -155,7 +157,7 @@ The simulator control connection is on port 25565. :class: dropdown, hint :::{literalinclude} /snippets/static06.py -:emphasize-lines: 4,15-22,27-28 +:emphasize-lines: 4,15-18,23-24 ::: :::: @@ -179,7 +181,7 @@ The `update_period` property tells the base class how often to call `update` :class: dropdown, hint :::{literalinclude} /snippets/static07.py -:emphasize-lines: 1,3,5-6,15-33,37,43 +:emphasize-lines: 1,3,5-6,15-33,37 ::: :::: @@ -288,7 +290,7 @@ are, which is used to register the correct number of ramp controllers with the p :class: dropdown, hint :::{literalinclude} /snippets/static10.py -:emphasize-lines: 10,28,32,35,44,48-56,64,70-74,83 +:emphasize-lines: 10,28,32,35,44,48-56,62-63,69-72,77-79 ::: :::: @@ -366,7 +368,7 @@ gets the array of voltages and sets each ramp controller with its value. Also ad :class: dropdown, hint :::{literalinclude} /snippets/static12.py -:emphasize-lines: 2,16,60-62,91-97 +:emphasize-lines: 2,16,60-62,87-93 ::: :::: @@ -387,7 +389,7 @@ controller. :class: dropdown, hint :::{literalinclude} /snippets/static13.py -:emphasize-lines: 1,17,100-105 +:emphasize-lines: 1,17,96-101 ::: :::: @@ -419,7 +421,7 @@ logger for `TemperatureControllerAttributeIO` to log the commands it sends. :class: dropdown, hint :::{literalinclude} /snippets/static14.py -:emphasize-lines: 13,48,110,115 +:emphasize-lines: 13,48,106,111 ::: :::: @@ -444,7 +446,7 @@ visible. :class: dropdown, hint :::{literalinclude} /snippets/static15.py -:emphasize-lines: 13,49-51,118 +:emphasize-lines: 13,49-51,114 ::: :::: @@ -454,7 +456,7 @@ ramp so that the value updates. Check the console to see the messages. Call `disable_tracing` to disable the log messages for `power`. ``` -In [1]: controller.power.enable_tracing() +In [1]: controllers["DEMO"].power.enable_tracing() [2025-11-18 11:11:12.060+0000 T] Query for attribute [TemperatureControllerAttributeIO] query=P?, response=0.0 [2025-11-18 11:11:12.060+0000 T] Attribute set [AttrR] attribute=AttrR(path=power, datatype=Float, io_ref=TemperatureControllerAttributeIORef(update_period=0.2, name='P')), value=0.0 [2025-11-18 11:11:12.060+0000 T] PV set from attribute [fastcs.transports.epics.ca.ioc] pv=DEMO:Power, value=0.0 @@ -468,7 +470,7 @@ In [1]: controller.power.enable_tracing() [2025-11-18 11:11:12.464+0000 T] Query for attribute [TemperatureControllerAttributeIO] query=P?, response=30.452524641833854 [2025-11-18 11:11:12.464+0000 T] Attribute set [AttrR] attribute=AttrR(path=power, datatype=Float, io_ref=TemperatureControllerAttributeIORef(update_period=0.2, name='P')), value=30.452524641833854 [2025-11-18 11:11:12.465+0000 T] PV set from attribute [fastcs.transports.epics.ca.ioc] pv=DEMO:Power, value=30.45 -In [2]: controller.power.disable_tracing() +In [2]: controllers["DEMO"].power.disable_tracing() ``` These log messages include other trace loggers that log messages with `power` as the diff --git a/pyproject.toml b/pyproject.toml index da948b3e6..d668f37f9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,6 +26,7 @@ dependencies = [ "loguru~=0.7", "pygelf", "stdio-socket", + "typing_extensions", ] dynamic = ["version"] license.file = "LICENSE" diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 5001409a1..1696c2a30 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -1,5 +1,4 @@ +from .connection import Connection as Connection from .ip_connection import IPConnection as IPConnection -from .ip_connection import IPConnectionSettings as IPConnectionSettings from .ip_connection import StreamConnection as StreamConnection from .serial_connection import SerialConnection as SerialConnection -from .serial_connection import SerialConnectionSettings as SerialConnectionSettings diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py new file mode 100644 index 000000000..3ccc44b9a --- /dev/null +++ b/src/fastcs/connections/connection.py @@ -0,0 +1,65 @@ +from __future__ import annotations + +from abc import ABC, abstractmethod +from collections.abc import Sequence +from typing import ClassVar, Generic, cast + +from typing_extensions import TypeVar + +IntrospectionT = TypeVar("IntrospectionT", default=None) +"""What a `Connection`'s ``introspect`` returns, or ``None`` if it doesn't introspect""" + + +class Connection(ABC, Generic[IntrospectionT]): + """A link to a device, which can optionally introspect it. + + Example:: + + class EigerConnection(Connection[EigerIntrospection]): + async def introspect(self) -> EigerIntrospection: ... + """ + + # Connection type(s) in the same ControllerSpec to open before this one + depends_on: ClassVar[type[Connection] | Sequence[type[Connection]]] = () + + _introspection: IntrospectionT + + @property + def introspection(self) -> IntrospectionT: + """What ``introspect`` returned when the framework opened this connection. + + Raises: + RuntimeError: If the framework hasn't opened this connection yet + + """ + try: + return self._introspection + except AttributeError: + raise RuntimeError( + f"{type(self).__name__} has no introspection until the framework " + "has opened it" + ) from None + + @introspection.setter + def introspection(self, value: IntrospectionT) -> None: + if hasattr(self, "_introspection"): + raise RuntimeError(f"{type(self).__name__} introspection is already set") + + self._introspection = value + + @abstractmethod + async def connect(self) -> None: + """Open the link, or raise. Called by the framework before construction.""" + + async def introspect(self) -> IntrospectionT: + """Describe the device. Called by the framework after ``connect``. + + Returns: + The introspection, or ``None`` if this connection doesn't introspect + + """ + return cast(IntrospectionT, None) + + @abstractmethod + async def close(self) -> None: + """Close the link. Called by the framework on stop, or if build fails.""" diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index f021aa913..a690c2afa 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -1,6 +1,7 @@ import asyncio from dataclasses import dataclass +from fastcs.connections.connection import Connection, IntrospectionT from fastcs.tracer import Tracer @@ -10,12 +11,6 @@ class DisconnectedError(Exception): pass -@dataclass -class IPConnectionSettings: - ip: str = "127.0.0.1" - port: int = 25565 - - @dataclass class StreamConnection: """For reading and writing to a stream.""" @@ -46,11 +41,19 @@ async def close(self): await self.writer.wait_closed() -class IPConnection(Tracer): - """For connecting to an ip using a `StreamConnection`.""" +class IPConnection(Connection[IntrospectionT], Tracer): + """For connecting to an ip using a `StreamConnection`. + + Args: + ip: The address to connect to + port: The port to connect to + + """ - def __init__(self): + def __init__(self, ip: str = "127.0.0.1", port: int = 25565): super().__init__() + self.ip = ip + self.port = port self.__connection = None @property @@ -60,8 +63,8 @@ def _connection(self) -> StreamConnection: return self.__connection - async def connect(self, settings: IPConnectionSettings): - reader, writer = await asyncio.open_connection(settings.ip, settings.port) + async def connect(self) -> None: + reader, writer = await asyncio.open_connection(self.ip, self.port) self.__connection = StreamConnection(reader, writer) async def send_command(self, message: str) -> None: diff --git a/src/fastcs/connections/serial_connection.py b/src/fastcs/connections/serial_connection.py index 65bbf6801..e719d1495 100644 --- a/src/fastcs/connections/serial_connection.py +++ b/src/fastcs/connections/serial_connection.py @@ -1,8 +1,9 @@ import asyncio -from dataclasses import dataclass import aioserial +from fastcs.connections.connection import Connection, IntrospectionT + class NotOpenedError(Exception): """If the serial stream is not opened.""" @@ -10,21 +11,23 @@ class NotOpenedError(Exception): pass -@dataclass -class SerialConnectionSettings: - port: str - baud: int = 115200 +class SerialConnection(Connection[IntrospectionT]): + """A serial connection. + Args: + port: The serial port to open + baud: The baud rate -class SerialConnection: - """A serial connection.""" + """ - def __init__(self): - self.stream = None + def __init__(self, port: str, baud: int = 115200): + self.port = port + self.baud = baud + self.__stream = None self._lock = asyncio.Lock() - async def connect(self, settings: SerialConnectionSettings) -> None: - self.__stream = aioserial.AioSerial(port=settings.port, baudrate=settings.baud) + async def connect(self) -> None: + self.__stream = aioserial.AioSerial(port=self.port, baudrate=self.baud) @property def _stream(self) -> aioserial.AioSerial: diff --git a/src/fastcs/control_system.py b/src/fastcs/control_system.py index e8604d703..f88952026 100644 --- a/src/fastcs/control_system.py +++ b/src/fastcs/control_system.py @@ -7,67 +7,46 @@ from IPython.terminal.embed import InteractiveShellEmbed -from fastcs.controllers import Controller, ControllerAPI +from fastcs.controllers import ControllerSpec from fastcs.logging import logger -from fastcs.methods import ScanCallback +from fastcs.runner import ControllerRunner from fastcs.tracer import Tracer from fastcs.transports import Transport tracer = Tracer() -def _context_key(controller: Controller) -> str: - """Key used for a controller in IPython context dicts. - - Falls back to the class name when no path has been seeded so - direct-construction callers (without launch()) still get a sensible key. - """ - try: - return controller.path[0] - except IndexError: - return controller.__class__.__name__ - - class FastCS: """Entrypoint for a FastCS application. - This class takes one or more `Controller`s, creates asyncio tasks to run their - update loops and builds their APIs to serve over the given `Transport`s. + This class takes one or more `ControllerSpec` instances, runs them with a + `ControllerRunner` and serves their APIs over the given `Transport` instances. Args: - controllers: The controller(s) to serve in the control system. Accepts - either a single ``Controller`` or a sequence of them. + specs: What to construct each top-level controller from transports: A list of transports to serve the API over loop: Optional event loop to run the control system in """ def __init__( self, - controllers: Controller | Sequence[Controller], + specs: Sequence[ControllerSpec], transports: Sequence[Transport], loop: asyncio.AbstractEventLoop | None = None, ): - if isinstance(controllers, Controller): - controllers = [controllers] - self._controllers: list[Controller] = list(controllers) - if not self._controllers: + self._specs: list[ControllerSpec] = list(specs) + if not self._specs: raise ValueError("FastCS requires at least one controller") - keys = [_context_key(c) for c in self._controllers] - if len(set(keys)) != len(keys): - duplicates = sorted({k for k in keys if keys.count(k) > 1}) + ids = [spec.id for spec in self._specs] + if len(set(ids)) != len(ids): + duplicates = sorted({i for i in ids if ids.count(i) > 1}) raise ValueError( - f"FastCS received controllers with duplicate context keys " - f"{duplicates}; ensure each controller has a unique id" + f"FastCS received controllers with duplicate ids {duplicates}" ) + self._ids = ids self._transports = transports self._loop = loop or asyncio.get_event_loop() - self._scan_coros: list[ScanCallback] = [] - self._initial_coros: list[ScanCallback] = [] - - self._scan_tasks: set[asyncio.Task] = set() - self.controller_apis: list[ControllerAPI] = [] - def run(self, interactive: bool = True): """Run the application @@ -84,25 +63,6 @@ def run(self, interactive: bool = True): self._loop.add_signal_handler(signal.SIGTERM, serve.cancel) self._loop.run_until_complete(serve) - async def _run_initial_coros(self): - for coro in self._initial_coros: - await coro() - - async def _start_scan_tasks(self): - self._scan_tasks = {self._loop.create_task(coro()) for coro in self._scan_coros} - - def _stop_scan_tasks(self): - for task in self._scan_tasks: - if not task.done(): - try: - task.cancel() - except (asyncio.CancelledError, RuntimeError): - pass - except Exception as e: - raise RuntimeError("Unhandled exception in stop scan tasks") from e - - self._scan_tasks.clear() - async def serve(self, interactive: bool = True) -> None: """Serve the control system over the given transports on the current event loop @@ -118,82 +78,66 @@ async def serve(self, interactive: bool = True) -> None: interactive: Whether to create an interactive IPython shell """ - for controller in self._controllers: - await controller.initialise() - controller.post_initialise() - - self.controller_apis = [] - self._scan_coros = [] - self._initial_coros = [] - for controller in self._controllers: - api, scan_coros, initial_coros = controller.create_api_and_tasks() - self.controller_apis.append(api) - self._scan_coros.extend(scan_coros) - self._initial_coros.extend(initial_coros) - - context = { - "controllers": {_context_key(c): c for c in self._controllers}, - "controller_apis": { - _context_key(c): api - for c, api in zip(self._controllers, self.controller_apis, strict=True) - }, - "transports": [ - transport.__class__.__name__ for transport in self._transports - ], - } - - coros: list[Coroutine] = [] - for transport in self._transports: - transport.connect(controller_apis=self.controller_apis, loop=self._loop) - coros.append(transport.serve()) - common_context = context.keys() & transport.context.keys() - if common_context: - raise RuntimeError( - "Duplicate context keys found between " - f"current context { ({k: context[k] for k in common_context}) } " - f"and {transport.__class__.__name__} context: " - f"{ ({k: transport.context[k] for k in common_context}) }" + # Build the APIs before wiring transports to them, so that a transport + # registers its callbacks before the first values are read. + self._runner = await ControllerRunner.build(self._specs) + + try: + context = { + "controllers": dict( + zip(self._ids, self._runner.controllers, strict=True) + ), + "controller_apis": dict( + zip(self._ids, self._runner.controller_apis, strict=True) + ), + "transports": [ + transport.__class__.__name__ for transport in self._transports + ], + } + + for transport in self._transports: + transport.connect( + controller_apis=self._runner.controller_apis, loop=self._loop ) - context.update(transport.context) + common_context = context.keys() & transport.context.keys() + if common_context: + current = {k: context[k] for k in common_context} + new = {k: transport.context[k] for k in common_context} + raise RuntimeError( + "Duplicate context keys found between " + f"current context {current} " + f"and {transport.__class__.__name__} context: {new}" + ) + context.update(transport.context) - if interactive: - coros.append(self._interactive_shell(context)) - else: + logger.info( + "Starting FastCS", + controllers=self._ids, + transports=f"[{', '.join(str(t) for t in self._transports)}]", + ) - async def block_forever(): - while True: - await asyncio.sleep(1) + await self._runner.start() - coros.append(block_forever()) + coros: list[Coroutine] = [t.serve() for t in self._transports] + if interactive: + coros.append(self._interactive_shell(context)) + else: - logger.info( - "Starting FastCS", - controllers=[_context_key(c) for c in self._controllers], - transports=f"[{', '.join(str(t) for t in self._transports)}]", - ) + async def block_forever(): + while True: + await asyncio.sleep(1) - for controller in self._controllers: - await controller.connect() - await self._run_initial_coros() - await self._start_scan_tasks() + coros.append(block_forever()) - try: - await asyncio.gather(*coros) - except asyncio.CancelledError: - pass - except Exception: - logger.exception("Unhandled exception in serve") + try: + await asyncio.gather(*coros) + except asyncio.CancelledError: + pass + except Exception: + logger.exception("Unhandled exception in serve") finally: logger.info("Shutting down FastCS") - self._stop_scan_tasks() - for controller in self._controllers: - try: - await controller.disconnect() - except Exception: - logger.exception( - "Exception during disconnect", - controller=_context_key(controller), - ) + await self._runner.stop() async def _interactive_shell(self, context: dict[str, Any]): """Spawn interactive shell in another thread and wait for it to complete.""" @@ -220,6 +164,3 @@ async def interactive_shell( stop_event = asyncio.Event() self._loop.create_task(interactive_shell(context, stop_event)) await stop_event.wait() - - def __del__(self): - self._stop_scan_tasks() diff --git a/src/fastcs/controllers/__init__.py b/src/fastcs/controllers/__init__.py index b982292de..06d3f4a0d 100644 --- a/src/fastcs/controllers/__init__.py +++ b/src/fastcs/controllers/__init__.py @@ -1,4 +1,5 @@ from .base_controller import BaseController as BaseController from .controller import Controller as Controller from .controller_api import ControllerAPI as ControllerAPI +from .controller_spec import ControllerSpec as ControllerSpec from .controller_vector import ControllerVector as ControllerVector diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index 8b29ed6d2..7307359a8 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -37,6 +37,9 @@ class BaseController(Tracer): root_attribute: Attribute | None = None description: str | None = None + _sealed: bool = False + _registered: bool = False + def __init__( self, path: list[str] | None = None, @@ -185,14 +188,27 @@ def __setattr__(self, name, value): else: super().__setattr__(name, value) - async def initialise(self): - """Hook for subclasses to dynamically add attributes before building the API""" + async def setup(self): + """Hook called by the framework after all attributes are added, before serving + the application""" pass - def post_initialise(self): - """Hook to call after all attributes added, before serving the application""" + def seal(self): + """Validate and connect this controller and its sub controllers, then stop + anything being added to them. Called by the framework after construction. + + Raises: + RuntimeError: If the controller is already sealed + + """ + if self._sealed: + raise RuntimeError(f"{self} is already sealed") + self._validate_type_hints() self._connect_attribute_ios() + self._sealed = True + for controller in self.sub_controllers.values(): + controller.seal() def _validate_type_hints(self): """Validate all type-hints were introspected""" @@ -205,25 +221,24 @@ def _validate_type_hints(self): for name in self.__hinted_methods: self._validate_hinted_method(name) - for subcontroller in self.sub_controllers.values(): - subcontroller._validate_type_hints() # noqa: SLF001 - def _validate_hinted_member(self, name: str, expected_type: type[T]) -> T: - """Validate that a hinted member exists on the controller""" + """Validate that a hinted member exists on the controller + + Raises: + RuntimeError: If no member of the expected type has the given name + + """ member = getattr(self, name, None) if member is None or not isinstance(member, expected_type): - raise RuntimeError() + raise RuntimeError( + f"Controller `{self.__class__.__name__}` failed to introspect " + f"hinted {expected_type.__name__} `{name}` during initialisation" + ) return member def _validate_hinted_method(self, name: str): """Check that a `Method` with the given name exists on the controller""" - try: - method = self._validate_hinted_member(name, Method) - except RuntimeError: - raise RuntimeError( - f"Controller `{self.__class__.__name__}` failed to introspect " - f"hinted method `{name}` during initialisation" - ) from None + method = self._validate_hinted_member(name, self.__hinted_methods[name]) logger.debug( "Validated hinted method", name=name, controller=self, method=method @@ -231,13 +246,9 @@ def _validate_hinted_method(self, name: str): def _validate_hinted_attribute(self, name: str): """Check that an `Attribute` with the given name exists on the controller""" - try: - attr = self._validate_hinted_member(name, Attribute) - except RuntimeError: - raise RuntimeError( - f"Controller `{self.__class__.__name__}` failed to introspect " - f"hinted attribute `{name}` during initialisation" - ) from None + attr = self._validate_hinted_member( + name, self.__hinted_attributes[name].attr_type + ) logger.debug( "Validated hinted attribute", name=name, controller=self, attribute=attr @@ -245,13 +256,9 @@ def _validate_hinted_attribute(self, name: str): def _validate_hinted_controller(self, name: str): """Check that a sub controller with the given name exists on the controller""" - try: - controller = self._validate_hinted_member(name, BaseController) - except RuntimeError: - raise RuntimeError( - f"Controller `{self.__class__.__name__}` failed to introspect " - f"hinted controller `{name}` during initialisation" - ) from None + controller = self._validate_hinted_member( + name, self.__hinted_sub_controllers[name] + ) logger.debug( "Validated hinted sub controller", @@ -279,41 +286,62 @@ def _connect_attribute_ios(self) -> None: if isinstance(attr, AttrR): attr.set_update_callback(io.update) - for controller in self.sub_controllers.values(): - controller._connect_attribute_ios() # noqa: SLF001 - @property def path(self) -> list[str]: """Path prefix of attributes, recursively including parent Controllers.""" return self._path def set_path(self, path: list[str]): + """Set the path of this controller, its attributes and its sub controllers. + + Args: + path: The path of this controller + + Raises: + ValueError: If the path is already set + + """ if self._path: - raise ValueError(f"sub controller is already registered under {self.path}") + raise ValueError(f"{self} already has path {self.path}") self._path = path for attribute in self.__attributes.values(): attribute.set_path(path) + for name, sub_controller in self.__sub_controllers.items(): + sub_controller.set_path(path + [name]) + + def _check_can_add(self, name: str, member: Attribute | BaseController | Method): + """Check that a member can be added to this controller under ``name``. - def _check_for_name_clash(self, name: str): + Raises: + RuntimeError: If the controller has been sealed + ValueError: If ``name`` is already used by another member + + """ namespaces = { - "attribute": self.__attributes, - "sub controller": self.__sub_controllers, - "scan method": self.__scan_methods, - "command method": self.__command_methods, + Attribute: ("attribute", self.__attributes), + BaseController: ("sub controller", self.__sub_controllers), + Scan: ("scan method", self.__scan_methods), + Command: ("command method", self.__command_methods), } + kind = next( + kind for cls, (kind, _) in namespaces.items() if isinstance(member, cls) + ) + + if self._sealed: + raise RuntimeError( + f"Cannot add {kind} {name} to {self} after it has been sealed" + ) - for kind, namespace in namespaces.items(): + for existing_kind, namespace in namespaces.values(): if name in namespace: raise ValueError( - f"Controller {self} has existing {kind} {name}: {namespace[name]}" + f"Cannot add {kind} {member}. Controller {self} has existing " + f"{existing_kind} {name}: {namespace[name]}" ) def add_attribute(self, name, attr: Attribute): - try: - self._check_for_name_clash(name) - except ValueError as exc: - raise ValueError(f"Cannot add attribute {attr}.") from exc + self._check_can_add(name, attr) if name in self.__hinted_attributes: hint = self.__hinted_attributes[name] @@ -341,10 +369,7 @@ def attributes(self) -> dict[str, Attribute]: return self.__attributes def add_sub_controller(self, name: str, sub_controller: BaseController): - try: - self._check_for_name_clash(name) - except ValueError as exc: - raise ValueError(f"Cannot add sub controller {sub_controller}.") from exc + self._check_can_add(name, sub_controller) if name in self.__hinted_sub_controllers: hint = self.__hinted_sub_controllers[name] @@ -356,7 +381,12 @@ def add_sub_controller(self, name: str, sub_controller: BaseController): f"'{sub_controller.__class__.__name__}'." ) - sub_controller.set_path(self.path + [name]) + if sub_controller._registered: # noqa: SLF001 + raise ValueError(f"{sub_controller} is already registered") + sub_controller._registered = True # noqa: SLF001 + + if self.path: + sub_controller.set_path(self.path + [name]) self.__sub_controllers[name] = sub_controller super().__setattr__(name, sub_controller) @@ -372,6 +402,7 @@ def _validate_method(self, name: str, method: Method): hint = self.__hinted_methods[name] if not isinstance(method, hint): raise RuntimeError( + f"Cannot add {method}. " f"Controller '{self.__class__.__name__}' introspection of " f"hinted method '{name}' does not match defined type. " f"Expected '{hint.__name__}' got " @@ -379,11 +410,8 @@ def _validate_method(self, name: str, method: Method): ) def add_command(self, name: str, command: Command): - try: - self._check_for_name_clash(name) - self._validate_method(name, command) - except (ValueError, RuntimeError) as exc: - raise exc.__class__(f"Cannot add command method {command}.") from exc + self._check_can_add(name, command) + self._validate_method(name, command) self.__command_methods[name] = command super().__setattr__(name, command) @@ -393,11 +421,8 @@ def command_methods(self) -> dict[str, Command]: return self.__command_methods def add_scan(self, name: str, scan: Scan): - try: - self._check_for_name_clash(name) - self._validate_method(name, scan) - except (ValueError, RuntimeError) as exc: - raise exc.__class__(f"Cannot add scan method {scan}.") from exc + self._check_can_add(name, scan) + self._validate_method(name, scan) self.__scan_methods[name] = scan super().__setattr__(name, scan) @@ -406,14 +431,14 @@ def add_scan(self, name: str, scan: Scan): def scan_methods(self) -> dict[str, Scan]: return self.__scan_methods - def _build_api(self, path: list[str]) -> ControllerAPI: + def build_api(self, path: list[str]) -> ControllerAPI: return ControllerAPI( path=path, attributes=self.attributes, command_methods=self.command_methods, scan_methods=self.scan_methods, sub_apis={ - name: sub_controller._build_api(path + [name]) # noqa: SLF001 + name: sub_controller.build_api(path + [name]) for name, sub_controller in self.sub_controllers.items() }, description=self.description, diff --git a/src/fastcs/controllers/controller.py b/src/fastcs/controllers/controller.py index a6c726027..aae91fd25 100755 --- a/src/fastcs/controllers/controller.py +++ b/src/fastcs/controllers/controller.py @@ -1,15 +1,7 @@ -import asyncio -from collections import defaultdict from collections.abc import Sequence from fastcs.attributes import AnyAttributeIO -from fastcs.attributes.attr_r import AttrR -from fastcs.attributes.attribute_io_ref import AttributeIORef from fastcs.controllers.base_controller import BaseController -from fastcs.controllers.controller_api import ControllerAPI -from fastcs.logging import logger -from fastcs.methods import ScanCallback -from fastcs.util import ONCE class Controller(BaseController): @@ -21,7 +13,8 @@ def __init__( ios: Sequence[AnyAttributeIO] | None = None, ) -> None: super().__init__(description=description, ios=ios) - self._connected = False + # Connections are open before any controller is constructed + self._connected = True def add_sub_controller(self, name: str, sub_controller: BaseController): if name.isdigit(): @@ -31,14 +24,14 @@ def add_sub_controller(self, name: str, sub_controller: BaseController): ) return super().add_sub_controller(name, sub_controller) - async def connect(self) -> None: - """Hook to perform initial connection to device - - This should set ``_connected`` to ``True`` if the connection was successful to - enable scan tasks. + @property + def connected(self) -> bool: + """Whether the controller is connected and its scan tasks should run""" + return self._connected - """ - self._connected = True + def mark_disconnected(self) -> None: + """Mark the controller disconnected, pausing its scan tasks until reconnect""" + self._connected = False async def reconnect(self): """Hook to reconnect to device after an error @@ -51,86 +44,3 @@ async def reconnect(self): """ self._connected = True - - async def disconnect(self) -> None: - """Hook to tidy up resources before stopping the application""" - pass - - def create_api_and_tasks( - self, - ) -> tuple[ControllerAPI, list[ScanCallback], list[ScanCallback]]: - """Create api for transports tasks for FastCS backend - - Creates a tuple of - - The `ControllerAPI` for this controller - - Initial coroutines to be run once on startup - - Periodic coroutines to run as background tasks - - Returns: - tuple[ControllerAPI, list[ScanCallback], list[ScanCallback]] - - """ - controller_api = self._build_api(self._path) - - scan_dict: dict[float, list[ScanCallback]] = defaultdict(list) - initial_coros: list[ScanCallback] = [] - - for api in controller_api.walk_api(): - for method in api.scan_methods.values(): - if method.period is ONCE: - initial_coros.append(method.fn) - else: - scan_dict[method.period].append(method.fn) - - for attribute in api.attributes.values(): - match attribute: - case AttrR(_io_ref=AttributeIORef(update_period=update_period)): - if update_period is ONCE: - initial_coros.append(attribute.bind_update_callback()) - elif update_period is not None: - scan_dict[update_period].append( - attribute.bind_update_callback() - ) - - periodic_scan_coros: list[ScanCallback] = [] - for period, methods in scan_dict.items(): - periodic_scan_coros.append(self._create_periodic_scan_coro(period, methods)) - - return controller_api, periodic_scan_coros, initial_coros - - def _create_periodic_scan_coro( - self, period: float, scans: Sequence[ScanCallback] - ) -> ScanCallback: - """Create a coroutine to run scans at a given period - - This returns a coroutine that runs scans at a given period. If an exception is - raised in a callback it is caught and the updates for the controller are - paused, waiting for `_connected` to be set back to true via the `reconnect` - method. - - Args: - period: The period to run the scans at - scans: A list of `ScanCallback` to run periodically - - Returns: - A wrapper `ScanCallback` that runs all of the callbacks at a given period - """ - - async def scan_coro() -> None: - while True: - if not self._connected: - await asyncio.sleep(1) - continue - - try: - await asyncio.gather( - asyncio.sleep(period), *[scan() for scan in scans] - ) - except Exception: - logger.exception("Exception in scan task", period=period) - self._connected = False - - await asyncio.sleep(1) # Wait so this message appears last - logger.error("Pausing scan tasks and waiting for reconnect") - - return scan_coro diff --git a/src/fastcs/controllers/controller_spec.py b/src/fastcs/controllers/controller_spec.py new file mode 100644 index 000000000..6a9b595bf --- /dev/null +++ b/src/fastcs/controllers/controller_spec.py @@ -0,0 +1,50 @@ +from collections.abc import Callable +from typing import Generic, ParamSpec + +from fastcs.connections import Connection +from fastcs.controllers.controller import Controller + +P = ParamSpec("P") + + +class ControllerSpec(Generic[P]): + """A deferred call that constructs a top-level controller. + + Example:: + + # MyController(connection=connection, count=4), with path ["DEMO"] + ControllerSpec("DEMO", MyController, connection=connection, count=4) + + Args: + id: The root of the controller's path + controller_class: The controller class, or any callable returning one + args: Positional arguments for ``controller_class`` + kwargs: Keyword arguments for ``controller_class`` + + """ + + def __init__( + self, + id: str, + controller_class: Callable[P, Controller], + /, + *args: P.args, + **kwargs: P.kwargs, + ) -> None: + self.id = id + self.controller_class = controller_class + self.args = args + self.kwargs = kwargs + + @property + def connections(self) -> list[Connection]: + """The `Connection` s among the arguments""" + 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) + controller.set_path([self.id]) + + return controller diff --git a/src/fastcs/controllers/controller_vector.py b/src/fastcs/controllers/controller_vector.py index 119258272..1b014a4d7 100755 --- a/src/fastcs/controllers/controller_vector.py +++ b/src/fastcs/controllers/controller_vector.py @@ -47,8 +47,8 @@ def __setitem__(self, key: int, value: Controller_T) -> None: if not isinstance(value, Controller): msg = f"Expected Controller, got {value}" raise TypeError(msg) - self._children[key] = value super().add_sub_controller(str(key), value) + self._children[key] = value def __delitem__(self, key: int) -> None: raise NotImplementedError("Cannot delete sub controller from ControllerVector.") diff --git a/src/fastcs/demo/controllers.py b/src/fastcs/demo/controllers.py index 5926fc8ce..1328781b7 100755 --- a/src/fastcs/demo/controllers.py +++ b/src/fastcs/demo/controllers.py @@ -7,7 +7,7 @@ import numpy as np from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.connections import IPConnection, IPConnectionSettings +from fastcs.connections import IPConnection from fastcs.controllers import Controller from fastcs.datatypes import Enum, Float, Int, Waveform from fastcs.logging import logger @@ -24,7 +24,6 @@ class OnOffEnum(enum.StrEnum): @dataclass class TemperatureControllerSettings: num_ramp_controllers: int - ip_settings: IPConnectionSettings @dataclass @@ -71,18 +70,18 @@ class TemperatureController(Controller): power = AttrR(Float(), io_ref=TemperatureControllerAttributeIORef(name="P")) voltages = AttrR(Waveform(np.int32, shape=(4,))) - def __init__(self, settings: TemperatureControllerSettings) -> None: - self.connection = IPConnection() + def __init__( + self, sensor: IPConnection, settings: TemperatureControllerSettings + ) -> None: + self.sensor = sensor self.suffix = "" super().__init__( - ios=[TemperatureControllerAttributeIO(self.connection, self.suffix)] + ios=[TemperatureControllerAttributeIO(self.sensor, self.suffix)] ) - self._settings = settings - self._ramp_controllers: list[TemperatureRampController] = [] for index in range(1, settings.num_ramp_controllers + 1): - controller = TemperatureRampController(index, self.connection) + controller = TemperatureRampController(index, self.sensor) self._ramp_controllers.append(controller) self.add_sub_controller(f"R{index}", controller) @@ -93,27 +92,21 @@ async def cancel_all(self) -> None: # TODO: The requests all get concatenated and the sim doesn't handle it await asyncio.sleep(0.1) - async def connect(self) -> None: - await self.connection.connect(self._settings.ip_settings) - async def reconnect(self): try: - await self.connection.close() - await self.connection.connect(self._settings.ip_settings) + await self.sensor.close() + await self.sensor.connect() except BaseException: logger.exception("Reconnect failed") return self._connected = True - async def close(self) -> None: - await self.connection.close() - @scan(0.1) async def update_voltages(self): query = "V?" voltages = json.loads( - (await self.connection.send_query(f"{query}\r\n")).strip("\r\n") + (await self.sensor.send_query(f"{query}\r\n")).strip("\r\n") ) await self.voltages.update(voltages) @@ -138,9 +131,8 @@ class TemperatureRampController(Controller): actual = AttrR(Float(prec=3), io_ref=TemperatureControllerAttributeIORef(name="A")) voltage = AttrR(Float(prec=3)) - def __init__(self, index: int, conn: IPConnection) -> None: + def __init__(self, index: int, sensor: IPConnection) -> None: suffix = f"{index:02d}" super().__init__( - f"Ramp{suffix}", ios=[TemperatureControllerAttributeIO(conn, suffix)] + f"Ramp{suffix}", ios=[TemperatureControllerAttributeIO(sensor, suffix)] ) - self.connection = conn diff --git a/src/fastcs/demo/fastcs.yaml b/src/fastcs/demo/fastcs.yaml index 1784ef2f4..47271630a 100644 --- a/src/fastcs/demo/fastcs.yaml +++ b/src/fastcs/demo/fastcs.yaml @@ -2,15 +2,17 @@ controllers: - id: MAIN type: fastcs.TemperatureController - ip_settings: - ip: "localhost" - port: 25565 + connections: + sensor: + ip: "localhost" + port: 25565 num_ramp_controllers: 4 - id: AUX type: fastcs.TemperatureController - ip_settings: - ip: "localhost" - port: 25566 + connections: + sensor: + ip: "localhost" + port: 25566 num_ramp_controllers: 2 transport: - graphql: diff --git a/src/fastcs/demo/schema.json b/src/fastcs/demo/schema.json index 210c36256..127681251 100644 --- a/src/fastcs/demo/schema.json +++ b/src/fastcs/demo/schema.json @@ -175,6 +175,7 @@ "type": "object" }, "IPConnectionSettings": { + "additionalProperties": false, "properties": { "ip": { "default": "127.0.0.1", @@ -247,6 +248,19 @@ "title": "TangoTransport", "type": "object" }, + "TemperatureControllerConnections": { + "additionalProperties": false, + "properties": { + "sensor": { + "$ref": "#/$defs/IPConnectionSettings" + } + }, + "required": [ + "sensor" + ], + "title": "TemperatureControllerConnections", + "type": "object" + }, "TemperatureControllerEntry": { "additionalProperties": false, "properties": { @@ -259,19 +273,19 @@ "title": "Type", "type": "string" }, + "connections": { + "$ref": "#/$defs/TemperatureControllerConnections" + }, "num_ramp_controllers": { "title": "Num Ramp Controllers", "type": "integer" - }, - "ip_settings": { - "$ref": "#/$defs/IPConnectionSettings" } }, "required": [ "id", "type", - "num_ramp_controllers", - "ip_settings" + "connections", + "num_ramp_controllers" ], "title": "TemperatureControllerEntry", "type": "object" diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index 7bbe7726e..f121066f5 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -1,17 +1,27 @@ import asyncio import dataclasses +import functools import inspect import json from pathlib import Path -from typing import Annotated, Any, Literal, Optional, Union, get_type_hints +from typing import ( + Annotated, + Any, + Literal, + Optional, + Union, + get_origin, + get_type_hints, +) import typer from pydantic import BaseModel, Field, ValidationError, create_model from ruamel.yaml import YAML from fastcs import __version__ +from fastcs.connections import Connection from fastcs.control_system import FastCS -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.exceptions import LaunchError from fastcs.logging import ( GraylogEndpoint, @@ -28,15 +38,13 @@ @dataclasses.dataclass(frozen=True) class _RegisteredClass: cls: type[Controller] - expects_options: bool + connection_types: dict[str, type[Connection]] + options_name: str | None options_type: Any _ENTRY_REGISTRY: dict[type[BaseModel], _RegisteredClass] = {} -"""Maps each dynamically-built Entry model class to its originating -Controller class and whether it expects an options arg (with the -options-type, if any). Populated by ``_build_entry_model`` and read by -``_instantiate_controllers``.""" +"""Maps each Entry model to its Controller class, connections and options""" def launch( @@ -53,9 +61,8 @@ def launch( Args: controller_classes: One or more FastCS Controller classes to make available for instantiation. Each must have a type-hinted - __init__ method and no more than 2 arguments. The chosen class - for each id is selected by a required ``type`` discriminator - in the config. + ``__init__`` taking any number of ``Connection`` arguments and at most + one options argument. version (Optional[str]): The version of the FastCS application. Raises: @@ -182,10 +189,10 @@ def run( raise LaunchError("Failed to validate config") from e - controllers = _instantiate_controllers(instance_options.controllers) + specs = _controller_specs(instance_options.controllers) instance = FastCS( - controllers, + specs, instance_options.transport, loop=asyncio.get_event_loop(), ) @@ -195,46 +202,58 @@ def run( return launch_typer -def _instantiate_controllers( +def _controller_specs( controllers_options: list[Any], -) -> list[Controller]: - """Instantiate each entry under `controllers:` and seed its path. - - Each item in ``controllers_options`` is a dynamically-built Pydantic - model that exposes ``id``, ``type`` and the controller's options fields - inlined as siblings. The originating Controller class and its - options-type are looked up in ``_ENTRY_REGISTRY`` (populated by - ``_build_entry_model``). The entry's ``id`` is seeded into the - controller's ``_path`` via ``set_path([id])`` so that - ``ControllerAPI.path`` is rooted at the YAML id. - """ - seen_ids: set[str] = set() - duplicates: list[str] = [] - for entry in controllers_options: - if entry.id in seen_ids: - duplicates.append(entry.id) - seen_ids.add(entry.id) - if duplicates: - raise LaunchError( - f"Duplicate controller id(s) in `controllers:`: {sorted(set(duplicates))}" - ) - - controllers: list[Controller] = [] +) -> list[ControllerSpec]: + """Create a `ControllerSpec` for each entry under `controllers:`.""" + specs: list[ControllerSpec] = [] for entry in controllers_options: entry_cls: type[BaseModel] = type(entry) registered = _ENTRY_REGISTRY[entry_cls] - if registered.expects_options: + + kwargs: dict[str, Any] = {} + for name, connection_type in registered.connection_types.items(): + settings = getattr(entry.connections, name) + values = {k: getattr(settings, k) for k in type(settings).model_fields} + kwargs[name] = connection_type(**values) + + if registered.options_name is not None: field_values = { name: getattr(entry, name) for name in entry_cls.model_fields - if name not in ("id", "type") + if name not in ("id", "type", "connections") } - controller = registered.cls(registered.options_type(**field_values)) - else: - controller = registered.cls() - controller.set_path([entry.id]) - controllers.append(controller) - return controllers + kwargs[registered.options_name] = registered.options_type(**field_values) + + specs.append(ControllerSpec(entry.id, registered.cls, **kwargs)) + return specs + + +@functools.cache +def _connection_settings_model(connection_type: type[Connection]) -> type[BaseModel]: + """Build the Pydantic model for one connection's block under `connections:`. + + Raises: + LaunchError: If a constructor argument has no type hint + + """ + sig = inspect.signature(connection_type.__init__) + hints = get_type_hints(connection_type.__init__) + fields: dict[str, Any] = {} + for name, param in list(sig.parameters.items())[1:]: + if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD): + continue + if name not in hints: + raise LaunchError( + f"Expected typehinting in '{connection_type.__name__}.__init__' " + f"but received {sig}. Add a typehint for `{name}`." + ) + default = ... if param.default is inspect.Parameter.empty else param.default + fields[name] = (hints[name], default) + + return create_model( + f"{connection_type.__name__}Settings", __config__={"extra": "forbid"}, **fields + ) def _options_field_definitions(options_type: type) -> dict[str, tuple[Any, Any]]: @@ -271,36 +290,65 @@ def _options_field_definitions(options_type: type) -> dict[str, tuple[Any, Any]] def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: """Build a Pydantic model for one entry under `controllers:`. - Each entry exposes ``id`` and a ``type`` discriminator literal alongside - the options-type's fields, inlined as siblings (no nested ``controller:`` - block). The Controller class and its options-type are recorded in - ``_ENTRY_REGISTRY`` for use by ``_instantiate_controllers``. + Raises: + LaunchError: If ``__init__`` is missing a type hint or takes more than one + options argument, or an options field uses a reserved key + """ sig = inspect.signature(controller_class.__init__) - args = inspect.getfullargspec(controller_class.__init__)[0] + args = [ + name + for name, param in list(sig.parameters.items())[1:] + if param.kind not in (param.VAR_POSITIONAL, param.VAR_KEYWORD) + ] + hints = get_type_hints(controller_class.__init__) discriminator = _discriminator(controller_class) fields: dict[str, Any] = { "id": (str, ...), "type": (Literal[discriminator], ...), } - expects_options = False + + connection_types: dict[str, type[Connection]] = {} + 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 + + 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"}, + **connection_fields, + ) + fields["connections"] = (connections_model, ...) + + option_args = [name for name in args if name not in connection_types] + options_name: str | None = None options_type: Any = None - if len(args) == 1: - pass - elif len(args) == 2: - expects_options = True - hints = get_type_hints(controller_class.__init__) - hints.pop("return", None) - if not hints: + if len(option_args) > 1: + raise LaunchError( + f"Expected no more than 1 argument besides connections for " + f"'{controller_class.__name__}.__init__' but received " + f"{len(option_args)} as `{sig}`" + ) + + if option_args: + options_name = option_args[0] + if options_name not in hints: raise LaunchError( f"Expected typehinting in '{controller_class.__name__}" - f".__init__' but received {sig}. Add a typehint for `{args[-1]}`." + f".__init__' but received {sig}. Add a typehint for `{options_name}`." ) - options_type = list(hints.values())[-1] + options_type = hints[options_name] options_fields = _options_field_definitions(options_type) - for reserved in ("id", "type"): + for reserved in ("id", "type", "connections"): if reserved in options_fields: raise LaunchError( f"Options type {options_type.__name__} for " @@ -308,11 +356,6 @@ def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: f"which collides with a launch-framework key." ) fields.update(options_fields) - else: - raise LaunchError( - f"Expected no more than 2 arguments for '{controller_class.__name__}" - f".__init__' but received {len(args)} as `{sig}`" - ) entry_model = create_model( f"{controller_class.__name__}Entry", @@ -321,7 +364,8 @@ def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: ) _ENTRY_REGISTRY[entry_model] = _RegisteredClass( cls=controller_class, - expects_options=expects_options, + connection_types=connection_types, + options_name=options_name, options_type=options_type, ) return entry_model @@ -336,7 +380,7 @@ def _build_options_model( registered class's entry model or a discriminated union over all registered classes; in both cases the entry's ``id:`` and ``type:`` fields are required. Duplicate ``id`` values across the list are - rejected by ``_instantiate_controllers``. + rejected by `FastCS`. """ entries = [_build_entry_model(cls) for cls in controller_classes] diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py new file mode 100644 index 000000000..dc0b60980 --- /dev/null +++ b/src/fastcs/runner.py @@ -0,0 +1,253 @@ +import asyncio +from collections import defaultdict +from collections.abc import Iterator, Sequence +from typing import Self + +from fastcs.attributes.attr_r import AttrR +from fastcs.attributes.attribute_io_ref import AttributeIORef +from fastcs.connections import Connection +from fastcs.controllers.base_controller import BaseController +from fastcs.controllers.controller import Controller +from fastcs.controllers.controller_api import ControllerAPI +from fastcs.controllers.controller_spec import ControllerSpec +from fastcs.logging import logger +from fastcs.methods import ScanCallback +from fastcs.util import ONCE + + +class ControllerRunner: + """Runs the lifecycle of one or more top-level controllers.""" + + def __init__(self) -> None: + self._connections: list[Connection] = [] + self._controllers: list[Controller] = [] + + self._controller_apis: list[ControllerAPI] = [] + self._initial_coros: list[ScanCallback] = [] + self._scan_coros: list[ScanCallback] = [] + self._tasks: set[asyncio.Task] = set() + + @classmethod + async def build(cls, specs: list[ControllerSpec]) -> Self: + """Open the connections, construct the controllers and create a runner with + their APIs. + + Args: + specs: What to construct each top-level controller from + + Returns: + A runner ready to `start`, with an API per controller in + ``controller_apis``, in the order the specs were given + + Raises: + ValueError: If a connection is shared between specs + + """ + _check_connections_not_shared(specs) + runner = cls() + + try: + for spec in specs: + for connection in _dependency_order(spec.connections): + await connection.connect() + runner._connections.append(connection) + connection.introspection = await connection.introspect() + + runner._controllers = [spec.construct() for spec in specs] + for controller in runner._controllers: + controller.seal() + + for controller in runner._controllers: + api = controller.build_api(controller.path) + initial_coros, scan_coros = runner._collect_scans(controller, api) + runner._controller_apis.append(api) + runner._initial_coros.extend(initial_coros) + runner._scan_coros.extend(scan_coros) + except BaseException: + await runner._close_connections() + raise + + return runner + + @property + def controllers(self) -> list[Controller]: + """The top-level controllers, in the order the specs were given""" + return self._controllers + + @property + def controller_apis(self) -> list[ControllerAPI]: + """The API of each controller, in the order the specs were given""" + return self._controller_apis + + async def start(self) -> None: + """Set up the controllers, run the initial reads and start the scan tasks.""" + for controller in self._controllers: + for sub_controller in _walk(controller): + await sub_controller.setup() + + for coro in self._initial_coros: + await coro() + + self._tasks = {asyncio.create_task(coro()) for coro in self._scan_coros} + + async def stop(self) -> None: + """Stop the scan tasks and close the connections.""" + tasks = list(self._tasks) + self._cancel_tasks() + await asyncio.gather(*tasks, return_exceptions=True) + await self._close_connections() + + async def _close_connections(self) -> None: + """Close the open connections, in reverse order.""" + while self._connections: + connection = self._connections.pop() + try: + await connection.close() + except Exception: + logger.exception("Exception closing connection", connection=connection) + + def _collect_scans( + self, controller: Controller, api: ControllerAPI + ) -> tuple[list[ScanCallback], list[ScanCallback]]: + """Find the initial reads and periodic scans in a controller's tree. + + Returns: + The initial coroutines, and one periodic coroutine per period + + """ + initial_coros: list[ScanCallback] = [] + scan_dict: dict[float, list[ScanCallback]] = defaultdict(list) + + for sub_api in api.walk_api(): + for method in sub_api.scan_methods.values(): + if method.period is ONCE: + initial_coros.append(method.fn) + else: + scan_dict[method.period].append(method.fn) + + for attribute in sub_api.attributes.values(): + match attribute: + case AttrR(_io_ref=AttributeIORef(update_period=update_period)): + if update_period is ONCE: + initial_coros.append(attribute.bind_update_callback()) + elif update_period is not None: + scan_dict[update_period].append( + attribute.bind_update_callback() + ) + + scan_coros = [ + _periodic_scan_coro(controller, period, scans) + for period, scans in scan_dict.items() + ] + return initial_coros, scan_coros + + def _cancel_tasks(self) -> None: + for task in self._tasks: + if not task.done(): + task.cancel() + + self._tasks.clear() + + def __del__(self): + self._cancel_tasks() + + +def _walk(controller: BaseController) -> Iterator[BaseController]: + """A controller and every controller below it, parents first""" + yield controller + for sub_controller in controller.sub_controllers.values(): + yield from _walk(sub_controller) + + +def _check_connections_not_shared(specs: list[ControllerSpec]) -> None: + """Check that no connection is used by more than one spec. + + Raises: + ValueError: If a connection is shared between specs + + """ + owners: dict[int, str] = {} + for spec in specs: + for connection in {id(c): c for c in spec.connections}.values(): + owner = owners.setdefault(id(connection), spec.id) + if owner != spec.id: + raise ValueError( + f"{type(connection).__name__} is used by controllers " + f"'{owner}' and '{spec.id}'; a connection can't be shared " + "between controllers. Put them in one controller tree instead." + ) + + +def _dependency_types(connection: Connection) -> tuple[type[Connection], ...]: + """A connection's ``depends_on`` as a tuple""" + depends_on = connection.depends_on + if isinstance(depends_on, type): + return (depends_on,) + + return tuple(depends_on) + + +def _dependency_order(connections: list[Connection]) -> list[Connection]: + """Order connections so that each comes after the connections it depends on. + + Raises: + ValueError: If the dependencies form a cycle + + """ + unique = list({id(c): c for c in connections}.values()) + ordered: list[Connection] = [] + visiting: list[Connection] = [] + + def visit(connection: Connection) -> None: + if any(connection is c for c in ordered): + return + if any(connection is c for c in visiting): + cycle = " -> ".join(type(c).__name__ for c in [*visiting, connection]) + raise ValueError(f"Cycle in connection dependencies: {cycle}") + + visiting.append(connection) + for other in unique: + if other is not connection and isinstance( + other, _dependency_types(connection) + ): + visit(other) + visiting.pop() + ordered.append(connection) + + for connection in unique: + visit(connection) + + return ordered + + +def _periodic_scan_coro( + controller: Controller, period: float, scans: Sequence[ScanCallback] +) -> ScanCallback: + """Create a coroutine to run scans at a given period + + Args: + controller: The top-level controller whose connection gates the scans + period: The period to run the scans at + scans: A list of `ScanCallback` to run periodically + + Returns: + A wrapper `ScanCallback` that runs all of the callbacks at a given period + + """ + + async def scan_coro() -> None: + while True: + if not controller.connected: + await asyncio.sleep(1) + continue + + try: + await asyncio.gather(asyncio.sleep(period), *[scan() for scan in scans]) + except Exception: + logger.exception("Exception in scan task", period=period) + controller.mark_disconnected() + + await asyncio.sleep(1) + logger.error("Pausing scan tasks and waiting for reconnect") + + return scan_coro diff --git a/tests/assertable_controller.py b/tests/assertable_controller.py index c57916134..f4a1733c7 100644 --- a/tests/assertable_controller.py +++ b/tests/assertable_controller.py @@ -46,19 +46,8 @@ def __init__(self) -> None: self._sub_controllers.append(controller) self.add_sub_controller(f"SubController{index:02d}", controller) - initialised = False count = 0 - async def initialise(self) -> None: - await super().initialise() - self.initialised = True - - async def connect(self) -> None: - self._connected = True - - async def disconnect(self) -> None: - self._connected = False - @command() async def go(self): pass @@ -81,7 +70,7 @@ def __init__( self.command_method_spys: dict[str, MockType] = {} # Build a ControllerAPI from the given Controller - controller_api = controller._build_api(path or []) + controller_api = controller.build_api(path or []) # Copy its fields self.path = controller_api.path self.attributes = controller_api.attributes diff --git a/tests/benchmarking/controller.py b/tests/benchmarking/controller.py index fc2d187e9..da7125669 100644 --- a/tests/benchmarking/controller.py +++ b/tests/benchmarking/controller.py @@ -2,7 +2,7 @@ from fastcs import FastCS from fastcs.attributes import AttrR, AttrW -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Bool, Int from fastcs.transports.epics.ca.transport import EpicsCATransport from fastcs.transports.rest.options import RestServerOptions @@ -21,9 +21,8 @@ def run(): EpicsCATransport(), TangoTransport(), ] - controller = MyTestController() - controller.set_path(["BENCHMARK-DEVICE"]) - instance = FastCS(controller, transport_options, asyncio.get_event_loop()) + spec = ControllerSpec("BENCHMARK-DEVICE", MyTestController) + instance = FastCS([spec], transport_options, asyncio.get_event_loop()) instance.run() diff --git a/tests/conftest.py b/tests/conftest.py index 818c7d178..482d688f7 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -19,6 +19,7 @@ from softioc import builder from fastcs.attributes import AttrR, AttrRW, AttrW +from fastcs.controllers import ControllerSpec from fastcs.datatypes import Bool, Float, Int, String from fastcs.logging import configure_logging, logger from fastcs.logging._logging import LogLevel @@ -55,9 +56,14 @@ def controller(): return BackendTestController() +@pytest.fixture +def controller_spec(): + return ControllerSpec("A", BackendTestController) + + @pytest.fixture def controller_api(controller): - return controller._build_api([]) + return controller.build_api([]) DATA_PATH = Path(__file__).parent / "data" diff --git a/tests/example_p4p_ioc.py b/tests/example_p4p_ioc.py index 95cc8e70b..a34183f91 100644 --- a/tests/example_p4p_ioc.py +++ b/tests/example_p4p_ioc.py @@ -5,7 +5,7 @@ import numpy as np from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.controllers import Controller, ControllerVector +from fastcs.controllers import Controller, ControllerSpec, ControllerVector from fastcs.datatypes import Bool, DType_T, Enum, Float, Int, Table, Waveform from fastcs.launch import FastCS from fastcs.methods import command, scan @@ -43,8 +43,25 @@ class ParentController(Controller): io_ref=SimpleAttributeIORef(), ) - def __init__(self, description=None, ios=None): - super().__init__(description, ios) + def __init__(self, description=None): + simple_attribute_io = SimpleAttributeIO() + super().__init__(description, ios=[simple_attribute_io]) + self.add_sub_controller( + "child", + ChildVector( + { + 1: ChildController( + description="some sub controller", + ios=[simple_attribute_io], + ), + 2: ChildController( + description="another sub controller", + ios=[simple_attribute_io], + ), + }, + description="some child vector", + ), + ) class ChildController(Controller): @@ -86,33 +103,15 @@ async def i(self): j: AttrR = AttrR(Int()) -def run(id="P4P_TEST_DEVICE"): - simple_attribute_io = SimpleAttributeIO() - p4p_options = EpicsPVATransport() - controller = ParentController(ios=[simple_attribute_io]) - controller.set_path([id]) - - class ChildVector(ControllerVector): - vector_attribute: AttrR = AttrR(Int()) - - def __init__(self, children, description=None): - super().__init__(children, description) +class ChildVector(ControllerVector): + vector_attribute: AttrR = AttrR(Int()) - sub_controller = ChildVector( - { - 1: ChildController( - description="some sub controller", ios=[simple_attribute_io] - ), - 2: ChildController( - description="another sub controller", ios=[simple_attribute_io] - ), - }, - description="some child vector", - ) + def __init__(self, children, description=None): + super().__init__(children, description) - controller.add_sub_controller("child", sub_controller) - fastcs = FastCS(controller, [p4p_options]) +def run(id="P4P_TEST_DEVICE"): + fastcs = FastCS([ControllerSpec(id, ParentController)], [EpicsPVATransport()]) fastcs.run() diff --git a/tests/example_softioc.py b/tests/example_softioc.py index 3688ff4fb..a13fd1fad 100644 --- a/tests/example_softioc.py +++ b/tests/example_softioc.py @@ -3,7 +3,7 @@ from fastcs.attributes import AttrR, AttrRW, AttrW from fastcs.control_system import FastCS -from fastcs.controllers import Controller, ControllerVector +from fastcs.controllers import Controller, ControllerSpec, ControllerVector from fastcs.datatypes import Int from fastcs.methods import command from fastcs.transports.epics.ca.transport import ( @@ -17,6 +17,12 @@ class ParentController(Controller): a: AttrR = AttrR(Int()) b: AttrRW = AttrRW(Int()) + def __init__(self): + super().__init__() + self.add_sub_controller( + "ChildVector", ControllerVector({i: ChildController() for i in range(2)}) + ) + class ChildController(Controller): fail_on_next_e: bool = True @@ -35,13 +41,9 @@ async def d(self): def run(id="SOFTIOC_TEST_DEVICE"): - controller = ParentController() - controller.set_path([id]) - vector = ControllerVector({i: ChildController() for i in range(2)}) - controller.add_sub_controller("ChildVector", vector) gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Vector") fastcs = FastCS( - controller, + [ControllerSpec(id, ParentController)], [ EpicsCATransport( epicsca=EpicsCAOptions( diff --git a/tests/test_attributes.py b/tests/test_attributes.py index 41bd8547e..0fc6bb971 100644 --- a/tests/test_attributes.py +++ b/tests/test_attributes.py @@ -194,7 +194,6 @@ class MissingIOController(Controller): controller = MissingIOController() controller._connect_attribute_ios() - await c.initialise() c._connect_attribute_ios() await c.my_attr.bind_update_callback()() @@ -301,21 +300,16 @@ class DemoParameterController(Controller): int_parameter: AttrRW float_parameter: AttrRW # hint to satisfy pyright - async def initialise(self): - self._connection = DummyConnection() - await self._connection.connect() + def __init__(self, connection: DummyConnection, parameters: list[dict]): + super().__init__(ios=[DemoParameterAttributeIO()]) dtype_mapping = {"int": Int, "float": Float} - example_introspection_response = await self._connection.get( - "config/introspect_api" - ) - assert isinstance(example_introspection_response, list) - for parameter_response in example_introspection_response: + for parameter_response in parameters: try: ro = parameter_response["read_only"] ref = DemoParameterAttributeIORef( name=parameter_response["name"], subsystem=parameter_response["subsystem"], - connection=self._connection, + connection=connection, ) attr_class = AttrR if ro else AttrRW attr = attr_class( @@ -335,8 +329,12 @@ async def initialise(self): e, ) - c = DemoParameterController(ios=[DemoParameterAttributeIO()]) - await c.initialise() + connection = DummyConnection() + await connection.connect() + parameters = await connection.get("config/introspect_api") + assert isinstance(parameters, list) + + c = DemoParameterController(connection, parameters) c._connect_attribute_ios() await c.ro_int_parameter.bind_update_callback()() assert c.ro_int_parameter.get() == 10 @@ -375,7 +373,6 @@ async def update(self, attr): assert not c.no_ref.has_io_ref() assert c.base_class_ref.has_io_ref() - await c.initialise() c._connect_attribute_ios() # There is a difference between providing an AttributeIO for the default @@ -394,7 +391,6 @@ async def update(self, attr): c2 = MyController(ios=[SimpleAttributeIO()]) - await c2.initialise() c2._connect_attribute_ios() assert c2.base_class_ref.get() == 0 diff --git a/tests/test_control_system.py b/tests/test_control_system.py index ca151cc02..b1b392d86 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -4,21 +4,24 @@ import pytest from fastcs.attributes import AttributeIO, AttributeIORef, AttrR +from fastcs.connections import Connection from fastcs.control_system import FastCS -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Int from fastcs.methods import Command, command from fastcs.util import ONCE +from tests.assertable_controller import MyTestController @pytest.mark.asyncio -async def test_scan_tasks(controller): +async def test_scan_tasks(controller_spec): loop = asyncio.get_event_loop() - transport_options = [] - fastcs = FastCS(controller, transport_options, loop) + fastcs = FastCS([controller_spec], [], loop) asyncio.create_task(fastcs.serve(interactive=False)) await asyncio.sleep(0.1) + controller = fastcs._runner.controllers[0] + assert isinstance(controller, MyTestController) for _ in range(3): count = controller.count @@ -32,7 +35,6 @@ class MyTestController(Controller): def __init__(self): super().__init__() - async def initialise(self): async def do_nothing_dynamic() -> None: pass @@ -42,19 +44,19 @@ async def do_nothing_dynamic() -> None: async def do_nothing_static(self): pass - controller = MyTestController() loop = asyncio.get_event_loop() - transport_options = [] - fastcs = FastCS(controller, transport_options, loop) + fastcs = FastCS([ControllerSpec("A", MyTestController)], [], loop) asyncio.create_task(fastcs.serve(interactive=False)) await asyncio.sleep(0.1) + controller = fastcs._runner.controllers[0] + assert isinstance(controller, MyTestController) await controller.do_nothing_static() await controller.do_nothing_dynamic() - await fastcs.controller_apis[0].command_methods["do_nothing_static"]() - await fastcs.controller_apis[0].command_methods["do_nothing_dynamic"]() + await fastcs._runner.controller_apis[0].command_methods["do_nothing_static"]() + await fastcs._runner.controller_apis[0].command_methods["do_nothing_dynamic"]() @pytest.mark.asyncio @@ -81,7 +83,7 @@ class MyController(Controller): controller = MyController(ios=[AttributeIOTimesCalled()]) loop = asyncio.get_event_loop() - fastcs = FastCS(controller, [], loop) + fastcs = FastCS([ControllerSpec("A", lambda: controller)], [], loop) assert controller.update_quickly.get() == 0 assert controller.update_once.get() == 0 @@ -94,32 +96,34 @@ class MyController(Controller): assert controller.update_once.get() == 1 assert controller.update_never.get() == 0 - assert len(fastcs._scan_tasks) == 1 - assert len(fastcs._initial_coros) == 1 + assert len(fastcs._runner._tasks) == 1 + assert len(fastcs._runner._initial_coros) == 1 -@pytest.mark.asyncio -async def test_controller_connect_disconnect(): - class MyTestController(Controller): - async def connect(self): - self.connected = True +class ClosingConnection(Connection): + closed = False - async def disconnect(self): - self.connected = False + async def connect(self) -> None: + pass - controller = MyTestController() + async def close(self) -> None: + self.closed = True - loop = asyncio.get_event_loop() - fastcs = FastCS(controller, [], loop) - task = asyncio.create_task(fastcs.serve(interactive=False)) +class FailingSetupController(Controller): + def __init__(self, connection: ClosingConnection) -> None: + super().__init__() - # connect is called at the start of serve - await asyncio.sleep(0.1) - assert controller.connected + async def setup(self) -> None: + raise RuntimeError("setup failed") - task.cancel() - # disconnect is called at the end of serve - await asyncio.sleep(0.1) - assert not controller.connected +@pytest.mark.asyncio +async def test_connections_closed_if_startup_fails(): + connection = ClosingConnection() + fastcs = FastCS([ControllerSpec("A", FailingSetupController, connection)], []) + + with pytest.raises(RuntimeError, match="setup failed"): + await fastcs.serve(interactive=False) + + assert connection.closed diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py new file mode 100644 index 000000000..d4e9b6ecc --- /dev/null +++ b/tests/test_controller_runner.py @@ -0,0 +1,293 @@ +import asyncio +from dataclasses import dataclass + +import pytest + +from fastcs.connections import Connection +from fastcs.controllers import Controller, ControllerSpec +from fastcs.methods import scan +from fastcs.runner import ControllerRunner +from fastcs.util import ONCE + + +class ScanController(Controller): + def __init__(self) -> None: + super().__init__() + self.read_once_count = 0 + self.scan_count = 0 + self.setup_before_read_once = False + self.multiple_scans = asyncio.Event() + self.started = asyncio.Event() + self.stopped = asyncio.Event() + + async def setup(self) -> None: + self.setup_before_read_once = self.read_once_count == 0 + + @scan(ONCE) + async def read_once(self) -> None: + self.read_once_count += 1 + + @scan(0.01) + async def counter(self) -> None: + self.scan_count += 1 + if self.scan_count > 1: + self.multiple_scans.set() + + # Different period to counter, so it runs in its own task and doesn't block it + @scan(0.02) + async def block(self) -> None: + self.started.set() + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + self.stopped.set() + raise + + +@pytest.mark.asyncio +async def test_build_creates_an_api_per_controller(): + runner = await ControllerRunner.build( + [ControllerSpec("A", ScanController), ControllerSpec("B", ScanController)] + ) + + assert [api.path for api in runner.controller_apis] == [["A"], ["B"]] + + +@pytest.mark.asyncio +async def test_start_runs_scans_and_stop_stops_them(): + runner = await ControllerRunner.build([ControllerSpec("A", ScanController)]) + controller = runner.controllers[0] + assert isinstance(controller, ScanController) + await runner.start() + + await asyncio.wait_for(controller.multiple_scans.wait(), timeout=1) + assert controller.setup_before_read_once + assert controller.read_once_count == 1 + + await asyncio.wait_for(controller.started.wait(), timeout=1) + await runner.stop() + assert controller.stopped.is_set() + + +class RecordingConnection(Connection): + def __init__(self, events: list[str], name: str = "") -> None: + self.events = events + self.suffix = f" {name}" if name else "" + + async def connect(self) -> None: + self.events.append(f"connect{self.suffix}") + + async def close(self) -> None: + self.events.append(f"close{self.suffix}") + + +class ConnectedController(Controller): + def __init__(self, connection: RecordingConnection) -> None: + super().__init__() + self.connection = connection + connection.events.append("construct") + + +@pytest.mark.asyncio +async def test_connection_opened_before_construction_and_closed_on_stop(): + events: list[str] = [] + connection = RecordingConnection(events) + runner = await ControllerRunner.build( + [ControllerSpec("A", ConnectedController, connection)] + ) + + controller = runner.controllers[0] + assert isinstance(controller, ConnectedController) + assert controller.connection is connection + assert controller.path == ["A"] + assert events == ["connect", "construct"] + + await runner.start() + await runner.stop() + + assert events == ["connect", "construct", "close"] + + +class FailingController(Controller): + def __init__(self, connection: RecordingConnection) -> None: + raise RuntimeError("construction failed") + + +@pytest.mark.asyncio +async def test_connections_closed_if_build_fails(): + events: list[str] = [] + with pytest.raises(RuntimeError, match="construction failed"): + await ControllerRunner.build( + [ControllerSpec("A", FailingController, RecordingConnection(events))] + ) + + assert events == ["connect", "close"] + + +class FailingIntrospectConnection(RecordingConnection): + async def introspect(self) -> None: + raise RuntimeError("introspect failed") + + +@pytest.mark.asyncio +async def test_connection_closed_if_introspect_fails(): + events: list[str] = [] + with pytest.raises(RuntimeError, match="introspect failed"): + await ControllerRunner.build( + [ + ControllerSpec( + "A", ConnectedController, FailingIntrospectConnection(events) + ) + ] + ) + + assert events == ["connect", "close"] + + +@pytest.mark.asyncio +async def test_connection_shared_between_specs_raises_before_anything_opens(): + events: list[str] = [] + connection = RecordingConnection(events) + with pytest.raises(ValueError, match="used by controllers 'A' and 'B'"): + await ControllerRunner.build( + [ + ControllerSpec("A", ConnectedController, connection), + ControllerSpec("B", ConnectedController, connection), + ] + ) + + assert events == [] + + +class EigerConnection(RecordingConnection): + pass + + +class OdinConnection(RecordingConnection): + depends_on = EigerConnection + + +class TwoConnectionController(Controller): + def __init__(self, odin: OdinConnection, eiger: EigerConnection) -> None: + super().__init__() + + +@pytest.mark.asyncio +async def test_connections_opened_in_dependency_order_and_closed_in_reverse(): + events: list[str] = [] + runner = await ControllerRunner.build( + [ + ControllerSpec( + "A", + TwoConnectionController, + odin=OdinConnection(events, "odin"), + eiger=EigerConnection(events, "eiger"), + ) + ] + ) + await runner.start() + await runner.stop() + + assert events == ["connect eiger", "connect odin", "close odin", "close eiger"] + + +class ConnectionA(RecordingConnection): + pass + + +class ConnectionB(RecordingConnection): + depends_on = [ConnectionA] + + +ConnectionA.depends_on = [ConnectionB] + + +class CycleController(Controller): + def __init__(self, a: ConnectionA, b: ConnectionB) -> None: + super().__init__() + + +@pytest.mark.asyncio +async def test_dependency_cycle_raises_before_anything_opens(): + events: list[str] = [] + with pytest.raises(ValueError, match="Cycle in connection dependencies"): + await ControllerRunner.build( + [ + ControllerSpec( + "A", + CycleController, + ConnectionA(events, "a"), + ConnectionB(events, "b"), + ) + ] + ) + + assert events == [] + + +@dataclass +class DeviceIntrospection: + parameters: dict[str, int] + + +class IntrospectingConnection(Connection[DeviceIntrospection]): + async def connect(self) -> None: + pass + + async def introspect(self) -> DeviceIntrospection: + return DeviceIntrospection({"gain": 2}) + + async def close(self) -> None: + pass + + +class IntrospectedController(Controller): + def __init__(self, connection: IntrospectingConnection) -> None: + super().__init__() + self.parameters = connection.introspection.parameters + + +@pytest.mark.asyncio +async def test_introspection_available_when_controller_constructed(): + connection = IntrospectingConnection() + runner = await ControllerRunner.build( + [ControllerSpec("A", IntrospectedController, connection)] + ) + + controller = runner.controllers[0] + assert isinstance(controller, IntrospectedController) + assert controller.parameters == {"gain": 2} + assert connection.introspection == DeviceIntrospection({"gain": 2}) + + +def test_introspection_before_connecting_raises(): + with pytest.raises(RuntimeError, match="no introspection until the framework"): + _ = IntrospectingConnection().introspection + + +def test_introspection_set_twice_raises(): + connection = IntrospectingConnection() + connection.introspection = DeviceIntrospection({"gain": 2}) + with pytest.raises(RuntimeError, match="already set"): + connection.introspection = DeviceIntrospection({"gain": 3}) + + +@pytest.mark.asyncio +async def test_controller_tree_sealed_after_build(): + class ParentController(Controller): + def __init__(self) -> None: + super().__init__() + self.add_sub_controller("SUB", Controller()) + + runner = await ControllerRunner.build([ControllerSpec("A", ParentController)]) + controller = runner.controllers[0] + + with pytest.raises(RuntimeError, match="after it has been sealed"): + controller.sub_controllers["SUB"].add_sub_controller("LATE", Controller()) + + +def test_seal_twice_raises(): + controller = Controller() + controller.seal() + with pytest.raises(RuntimeError, match="already sealed"): + controller.seal() diff --git a/tests/test_controllers.py b/tests/test_controllers.py index 5d5dfb4ed..e1bb40344 100644 --- a/tests/test_controllers.py +++ b/tests/test_controllers.py @@ -4,9 +4,10 @@ import pytest from fastcs.attributes import AttrR, AttrRW -from fastcs.controllers import Controller, ControllerVector +from fastcs.controllers import Controller, ControllerSpec, ControllerVector from fastcs.datatypes import Enum, Float, Int from fastcs.methods import Command, Scan, command, scan +from fastcs.runner import ControllerRunner def test_controller_nesting(): @@ -16,9 +17,10 @@ def test_controller_nesting(): controller.a = sub_controller sub_controller.b = sub_sub_controller + controller.set_path(["root"]) - assert sub_controller.path == ["a"] - assert sub_sub_controller.path == ["a", "b"] + assert sub_controller.path == ["root", "a"] + assert sub_sub_controller.path == ["root", "a", "b"] assert controller.sub_controllers == {"a": sub_controller} assert sub_controller.sub_controllers == {"b": sub_sub_controller} @@ -29,6 +31,25 @@ def test_controller_nesting(): controller.c = sub_controller +class LeafController(Controller): + x = AttrR(Int()) + + +class TreeController(Controller): + def __init__(self) -> None: + super().__init__() + self.child = Controller() + self.child.leaf = LeafController() + + +def test_spec_sets_path_of_sub_controllers_added_in_init(): + controller = ControllerSpec("root", TreeController).construct() + + leaf = controller.sub_controllers["child"].sub_controllers["leaf"] + assert leaf.path == ["root", "child", "leaf"] + assert leaf.attributes["x"].full_name == "root.child.leaf.x" + + class SomeSubController(Controller): def __init__(self): super().__init__() @@ -168,11 +189,11 @@ class HintedController(Controller): with pytest.raises(RuntimeError, match="does not match defined access mode"): controller.add_attribute("read_write_int", AttrR(Int())) - with pytest.raises(RuntimeError, match="failed to introspect hinted attribute"): + with pytest.raises(RuntimeError, match="failed to introspect hinted AttrRW"): controller.read_write_int = 5 # type: ignore controller._validate_type_hints() - with pytest.raises(RuntimeError, match="failed to introspect hinted attribute"): + with pytest.raises(RuntimeError, match="failed to introspect hinted AttrRW"): controller._validate_type_hints() controller.add_attribute("read_write_int", AttrRW(Int())) @@ -203,7 +224,7 @@ class HintedController(Controller): controller = HintedController() - with pytest.raises(RuntimeError, match="failed to introspect hinted controller"): + with pytest.raises(RuntimeError, match="introspect hinted SomeSubController"): controller._validate_type_hints() with pytest.raises(RuntimeError, match="does not match defined type"): @@ -220,10 +241,10 @@ class HintedController(Controller): controller = HintedController() - with pytest.raises(RuntimeError, match="failed to introspect hinted method"): + with pytest.raises(RuntimeError, match="failed to introspect hinted Scan"): controller._validate_type_hints() - with pytest.raises(RuntimeError, match="Cannot add command method"): + with pytest.raises(RuntimeError, match="does not match defined type"): controller.add_command("method", Command(noop)) controller.add_scan("method", Scan(fn=noop, period=0.1)) @@ -249,7 +270,7 @@ async def scan_nothing(self): pass controller = MyTestController() - api = controller._build_api([]) + api = controller.build_api([]) assert api.description == controller.description assert list(api.attributes) == ["attr1", "attr2"] @@ -264,20 +285,19 @@ class MyTestController(Controller): async def failing_scan(self): raise RuntimeError("scan error") - controller = MyTestController() - controller.post_initialise() - _, scan_coros, _ = controller.create_api_and_tasks() + runner = await ControllerRunner.build([ControllerSpec("A", MyTestController)]) + controller = runner.controllers[0] controller._connected = True - task = asyncio.create_task(scan_coros[0]()) + task = asyncio.create_task(runner._scan_coros[0]()) - # Wait long enough for the scan to run and raise, setting _connected = False + # Wait long enough for the scan to run and raise, marking it disconnected await asyncio.sleep(0.1) - assert not controller._connected + assert not controller.connected - # Trigger reconnect - _connected resumes scan tasks + # Trigger reconnect - connected resumes scan tasks await controller.reconnect() - assert controller._connected + assert controller.connected task.cancel() with pytest.raises(asyncio.CancelledError): diff --git a/tests/test_launch.py b/tests/test_launch.py index 17e935f4c..4373764eb 100644 --- a/tests/test_launch.py +++ b/tests/test_launch.py @@ -11,6 +11,7 @@ from fastcs import __version__ from fastcs.attributes import AttrR +from fastcs.connections import Connection, IPConnection from fastcs.control_system import FastCS from fastcs.controllers import Controller from fastcs.datatypes import Int @@ -56,6 +57,29 @@ def __init__(self, arg: SomeConfig, too_many): super().__init__() +class WithConnection(Controller): + def __init__(self, connection: IPConnection, arg: SomeConfig) -> None: + super().__init__() + + +class KeywordOnlyConnection(Controller): + def __init__(self, *, connection: IPConnection) -> None: + super().__init__() + + +class NoSettingsConnection(Connection): + async def connect(self) -> None: ... + + async def close(self) -> None: ... + + +class WithGenericConnections(Controller): + def __init__( + self, sensor: IPConnection[SomeConfig], link: NoSettingsConnection + ) -> None: + super().__init__() + + class OtherHinted(Controller): def __init__(self, arg: OtherConfig) -> None: super().__init__() @@ -132,8 +156,9 @@ def test_not_hinted_schema(): def test_over_defined_schema(): error = ( "" - "Expected no more than 2 arguments for 'ManyArgs.__init__' " - "but received 3 as `(self, arg: tests.test_launch.SomeConfig, too_many)`" + "Expected no more than 1 argument besides connections for " + "'ManyArgs.__init__' but received 2 as " + "`(self, arg: tests.test_launch.SomeConfig, too_many)`" ) with pytest.raises(LaunchError) as exc_info: @@ -276,8 +301,7 @@ def test_type_name_override(): def test_duplicate_id_rejected_at_run(mocker: MockerFixture, tmp_path): - """Two entries with the same `id` are rejected at run time. (List-form - YAML accepts duplicate ids syntactically, so the launcher checks.)""" + """Two entries with the same `id` are rejected when FastCS is created.""" mocker.patch("fastcs.launch.FastCS.run") cfg = tmp_path / "dup.yaml" cfg.write_text( @@ -293,8 +317,8 @@ def test_duplicate_id_rejected_at_run(mocker: MockerFixture, tmp_path): ) app = _launch(IsHinted) result = runner.invoke(app, ["run", str(cfg)]) - assert isinstance(result.exception, LaunchError) - assert "Duplicate controller id" in str(result.exception) + assert isinstance(result.exception, ValueError) + assert "duplicate ids ['same']" in str(result.exception) def test_multi_controller_run_reaches_fastcs(mocker: MockerFixture, tmp_path): @@ -318,6 +342,64 @@ def test_multi_controller_run_reaches_fastcs(mocker: MockerFixture, tmp_path): result = runner.invoke(app, ["run", str(cfg)]) assert result.exit_code == 0, result.output init_spy.assert_called_once() - controllers_arg = init_spy.call_args.args[1] - assert [c.path[0] for c in controllers_arg] == ["one", "two"] - assert [type(c) for c in controllers_arg] == [IsHinted, OtherHinted] + specs_arg = init_spy.call_args.args[1] + assert [s.id for s in specs_arg] == ["one", "two"] + assert [s.controller_class for s in specs_arg] == [IsHinted, OtherHinted] + + +def test_connections_built_from_config(mocker: MockerFixture, tmp_path): + init_spy = mocker.spy(FastCS, "__init__") + mocker.patch("fastcs.launch.FastCS.run") + cfg = tmp_path / "connected.yaml" + cfg.write_text( + "controllers:\n" + " - id: one\n" + " type: tests.WithConnection\n" + " connections:\n" + " connection:\n" + " ip: localhost\n" + " port: 8000\n" + " name: a\n" + "transport:\n" + " - rest: {}\n" + ) + result = runner.invoke(_launch(WithConnection), ["run", str(cfg)]) + assert result.exit_code == 0, result.output + + [spec] = init_spy.call_args.args[1] + connection = spec.kwargs["connection"] + assert isinstance(connection, IPConnection) + assert (connection.ip, connection.port) == ("localhost", 8000) + assert spec.kwargs["arg"] == SomeConfig(name="a") + + +def test_parametrised_and_no_settings_connections(): + options_model = _build_options_model([WithGenericConnections]) + options_model.model_validate( + { + "controllers": [ + { + "id": "one", + "type": "tests.WithGenericConnections", + "connections": {"sensor": {}, "link": {}}, + } + ], + "transport": [{"rest": {}}], + } + ) + + +def test_keyword_only_connection_in_schema(): + options_model = _build_options_model([KeywordOnlyConnection]) + options_model.model_validate( + { + "controllers": [ + { + "id": "one", + "type": "tests.KeywordOnlyConnection", + "connections": {"connection": {"ip": "localhost", "port": 8000}}, + } + ], + "transport": [{"rest": {}}], + } + ) diff --git a/tests/test_multi_controller.py b/tests/test_multi_controller.py index 9e27f62e5..9cf6bbda2 100644 --- a/tests/test_multi_controller.py +++ b/tests/test_multi_controller.py @@ -11,7 +11,7 @@ from fastcs.attributes import AttrR from fastcs.control_system import FastCS -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Int from fastcs.transports.epics import EpicsDocsOptions, EpicsGUIOptions from fastcs.transports.epics.ca.transport import EpicsCATransport @@ -39,7 +39,7 @@ def test_controller_api_path_uses_id(): controller.add_sub_controller("Sub", sub) controller.set_path(["X"]) - api, _, _ = controller.create_api_and_tasks() + api = controller.build_api(controller.path) assert api.path == ["X"] assert api.sub_apis["Sub"].path == ["X", "Sub"] @@ -48,7 +48,7 @@ def test_controller_api_path_uses_id(): def _api_with_id(controller_class: type[Controller], id: str): controller = controller_class() controller.set_path([id]) - api, _, _ = controller.create_api_and_tasks() + api = controller.build_api(controller.path) return api @@ -307,21 +307,10 @@ class _LifecycleController(Controller): def __init__(self): super().__init__() - self.connected = False - self.initialised = False - self.post_initialised = False + self.set_up = False - async def initialise(self): - self.initialised = True - - def post_initialise(self): - self.post_initialised = True - - async def connect(self): - self.connected = True - - async def disconnect(self): - self.connected = False + async def setup(self): + self.set_up = True class _OtherLifecycleController(_LifecycleController): @@ -332,25 +321,26 @@ class _OtherLifecycleController(_LifecycleController): async def test_fastcs_serves_two_controllers_end_to_end(mocker: MockerFixture): """FastCS.serve drives lifecycle on every controller and routes REST traffic per-id; combined OpenAPI describes both prefixes.""" - a = _LifecycleController() - a.set_path(["alpha"]) - b = _OtherLifecycleController() - b.set_path(["beta"]) - transport = RestTransport() # Stop RestTransport from binding to a real port; we exercise the FastAPI # app directly through TestClient. mocker.patch.object(RestTransport, "serve", new=lambda self: asyncio.sleep(3600)) - fastcs = FastCS([a, b], [transport], asyncio.get_event_loop()) + fastcs = FastCS( + [ + ControllerSpec("alpha", _LifecycleController), + ControllerSpec("beta", _OtherLifecycleController), + ], + [transport], + asyncio.get_event_loop(), + ) task = asyncio.create_task(fastcs.serve(interactive=False)) try: await asyncio.sleep(0.1) - for controller in (a, b): - assert controller.initialised - assert controller.post_initialised - assert controller.connected + for controller in fastcs._runner.controllers: + assert isinstance(controller, _LifecycleController) + assert controller.set_up with TestClient(transport._server._app) as client: assert client.get("/alpha/foo").status_code == 200 @@ -368,6 +358,3 @@ async def test_fastcs_serves_two_controllers_end_to_end(mocker: MockerFixture): await task except asyncio.CancelledError: pass - - for controller in (a, b): - assert not controller.connected diff --git a/tests/transports/epics/ca/test_gui.py b/tests/transports/epics/ca/test_gui.py index 46e000e15..492a0402e 100644 --- a/tests/transports/epics/ca/test_gui.py +++ b/tests/transports/epics/ca/test_gui.py @@ -103,7 +103,7 @@ def test_get_write_widget_none(): def test_get_components(controller): - controller_api = controller._build_api(["DEVICE"]) + controller_api = controller.build_api(["DEVICE"]) gui = EpicsGUI(controller_api) components = gui.extract_api_components(controller_api) @@ -205,7 +205,7 @@ class _B(Controller): def _api_with_id(cls, name): c = cls() c.set_path([name]) - api, _, _ = c.create_api_and_tasks() + api = c.build_api(c.path) return api diff --git a/tests/transports/epics/ca/test_initial_value.py b/tests/transports/epics/ca/test_initial_value.py index b78090dd0..e90ffda00 100644 --- a/tests/transports/epics/ca/test_initial_value.py +++ b/tests/transports/epics/ca/test_initial_value.py @@ -6,7 +6,7 @@ import fastcs.transports.epics.ca.ioc as ca_ioc from fastcs.attributes import AttrR, AttrRW, AttrW -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Bool, Enum, Float, Int, String, Waveform from fastcs.launch import FastCS from fastcs.transports.epics.ca.transport import EpicsCATransport @@ -51,10 +51,8 @@ async def test_initial_values_set_in_ca(mocker): pv_prefix = "SOFTIOC_INITIAL_DEVICE" loop = asyncio.get_event_loop() - controller = InitialValuesController() - controller.set_path([pv_prefix]) fastcs = FastCS( - controller, + [ControllerSpec(pv_prefix, InitialValuesController)], [EpicsCATransport()], loop, ) diff --git a/tests/transports/epics/pva/test_p4p.py b/tests/transports/epics/pva/test_p4p.py index e50f74695..b6d3c4d59 100644 --- a/tests/transports/epics/pva/test_p4p.py +++ b/tests/transports/epics/pva/test_p4p.py @@ -15,7 +15,7 @@ from p4p.nt import NTTable from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW -from fastcs.controllers import Controller, ControllerVector +from fastcs.controllers import Controller, ControllerSpec, ControllerVector from fastcs.datatypes import Bool, DType_T, Enum, Float, Int, String, Table, Waveform from fastcs.launch import FastCS from fastcs.methods import command @@ -248,8 +248,9 @@ async def put_pvs(): def make_fastcs(pv_prefix: str, controller: Controller) -> FastCS: - controller.set_path([pv_prefix]) - return FastCS(controller, [EpicsPVATransport()]) + return FastCS( + [ControllerSpec(pv_prefix, lambda: controller)], [EpicsPVATransport()] + ) def test_read_signal_set(): diff --git a/tests/transports/epics/test_emission.py b/tests/transports/epics/test_emission.py index b4e223650..c56564e85 100644 --- a/tests/transports/epics/test_emission.py +++ b/tests/transports/epics/test_emission.py @@ -34,7 +34,7 @@ class _Beta(Controller): def _api_with_id(controller_class: type[Controller], name: str): controller = controller_class() controller.set_path([name]) - api, _, _ = controller.create_api_and_tasks() + api = controller.build_api(controller.path) return api diff --git a/uv.lock b/uv.lock index e1a6aa374..115e5603b 100644 --- a/uv.lock +++ b/uv.lock @@ -915,6 +915,7 @@ dependencies = [ { name = "pygelf" }, { name = "ruamel-yaml" }, { name = "stdio-socket" }, + { name = "typing-extensions" }, ] [package.optional-dependencies] @@ -1012,6 +1013,7 @@ requires-dist = [ { name = "stdio-socket" }, { name = "strawberry-graphql", marker = "extra == 'graphql'" }, { name = "tickit", marker = "extra == 'demo'", specifier = "~=0.4.3" }, + { name = "typing-extensions" }, { name = "uvicorn", extras = ["standard"], marker = "extra == 'graphql'", specifier = ">=0.12.0" }, { name = "uvicorn", extras = ["standard"], marker = "extra == 'rest'", specifier = ">=0.12.0" }, ]