From c98a3e5b80dad4307ffa17cb2cd85853bb7b43f2 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Fri, 6 Nov 2026 15:39:02 +0000 Subject: [PATCH 01/37] add distinct connections object, added to controllers via the runner --- docs/how-to/migrate-to-multi-controller.md | 15 +++--- docs/how-to/multiple-transports.md | 16 +++--- docs/snippets/dynamic.py | 7 ++- docs/snippets/static02.py | 4 +- docs/snippets/static03.py | 4 +- docs/snippets/static04.py | 7 ++- docs/snippets/static05.py | 7 ++- docs/snippets/static06.py | 7 ++- docs/snippets/static07.py | 7 ++- docs/snippets/static08.py | 7 ++- docs/snippets/static09.py | 7 ++- docs/snippets/static10.py | 7 ++- docs/snippets/static11.py | 7 ++- docs/snippets/static12.py | 7 ++- docs/snippets/static13.py | 7 ++- docs/snippets/static14.py | 7 ++- docs/snippets/static15.py | 7 ++- docs/tutorials/static-drivers.md | 14 ++--- src/fastcs/connections/__init__.py | 1 + src/fastcs/connections/connection.py | 17 ++++++ src/fastcs/control_system.py | 47 ++++++++-------- src/fastcs/controllers/__init__.py | 1 + src/fastcs/controllers/controller_spec.py | 50 +++++++++++++++++ src/fastcs/launch.py | 26 +++++---- src/fastcs/runner.py | 53 ++++++++++++++----- tests/benchmarking/controller.py | 7 ++- tests/example_p4p_ioc.py | 4 +- tests/example_softioc.py | 4 +- tests/test_control_system.py | 10 ++-- tests/test_controller_runner.py | 50 ++++++++++++++--- tests/test_controllers.py | 4 +- tests/test_launch.py | 6 +-- tests/test_multi_controller.py | 10 ++-- .../transports/epics/ca/test_initial_value.py | 6 +-- tests/transports/epics/pva/test_p4p.py | 5 +- 35 files changed, 280 insertions(+), 165 deletions(-) create mode 100644 src/fastcs/connections/connection.py create mode 100644 src/fastcs/controllers/controller_spec.py diff --git a/docs/how-to/migrate-to-multi-controller.md b/docs/how-to/migrate-to-multi-controller.md index a7038f5c4..9a4c902d3 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 +`ControllerSpec` instead of a constructed controller: +`FastCS(ControllerSpec("DEVICE", MyController), transports)`. For +multi-controller, pass a sequence: +`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..f515ca890 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/snippets/dynamic.py b/docs/snippets/dynamic.py index 7dde6dfe5..941091ec5 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -13,7 +13,7 @@ AttrW, ) from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +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 @@ -140,9 +140,8 @@ async def initialise(self): epics_ca = EpicsCATransport() connection_settings = IPConnectionSettings("localhost", 25565) -controller = TemperatureController(connection_settings) -controller.set_path(["DEMO"]) -fastcs = FastCS(controller, [epics_ca]) +spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static02.py b/docs/snippets/static02.py index dbb79a551..1dcc446e6 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..88245a75a 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..91bbe2da5 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..deea9573b 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..2e94bda5c 100644 --- a/docs/snippets/static06.py +++ b/docs/snippets/static06.py @@ -2,7 +2,7 @@ from fastcs.attributes import AttrR from fastcs.connections import IPConnection, IPConnectionSettings -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 @@ -25,9 +25,8 @@ async def connect(self): 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]) +spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static07.py b/docs/snippets/static07.py index cac5549d3..e4458503b 100644 --- a/docs/snippets/static07.py +++ b/docs/snippets/static07.py @@ -4,7 +4,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR from fastcs.connections import IPConnection, IPConnectionSettings -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 @@ -47,9 +47,8 @@ async def connect(self): 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]) +spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static08.py b/docs/snippets/static08.py index 5382fa3c9..92c93d4e8 100644 --- a/docs/snippets/static08.py +++ b/docs/snippets/static08.py @@ -4,7 +4,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Float, String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -53,9 +53,8 @@ async def connect(self): 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]) +spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static09.py b/docs/snippets/static09.py index dc5bb9d54..644097ec1 100644 --- a/docs/snippets/static09.py +++ b/docs/snippets/static09.py @@ -4,7 +4,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Float, String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -60,9 +60,8 @@ async def connect(self): 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]) +spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static10.py b/docs/snippets/static10.py index 24f6d523d..0ce447866 100644 --- a/docs/snippets/static10.py +++ b/docs/snippets/static10.py @@ -4,7 +4,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Float, Int, String from fastcs.launch import FastCS from fastcs.transports.epics import EpicsGUIOptions @@ -78,9 +78,8 @@ async def connect(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]) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static11.py b/docs/snippets/static11.py index e07ed5a41..7325896d5 100644 --- a/docs/snippets/static11.py +++ b/docs/snippets/static11.py @@ -5,7 +5,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +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 @@ -85,9 +85,8 @@ async def connect(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]) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static12.py b/docs/snippets/static12.py index 9f1f2af14..0b3275f47 100644 --- a/docs/snippets/static12.py +++ b/docs/snippets/static12.py @@ -6,7 +6,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS from fastcs.methods import scan @@ -98,9 +98,8 @@ 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]) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static13.py b/docs/snippets/static13.py index b2036c66f..98bf272f9 100644 --- a/docs/snippets/static13.py +++ b/docs/snippets/static13.py @@ -7,7 +7,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +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 @@ -106,9 +106,8 @@ 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]) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static14.py b/docs/snippets/static14.py index f54c93d3d..1937d5de8 100644 --- a/docs/snippets/static14.py +++ b/docs/snippets/static14.py @@ -7,7 +7,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +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 @@ -113,9 +113,8 @@ async def disable_all(self) -> None: 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]) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static15.py b/docs/snippets/static15.py index aa2d53a92..e84359ca9 100644 --- a/docs/snippets/static15.py +++ b/docs/snippets/static15.py @@ -7,7 +7,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, AttrR, AttrRW, AttrW from fastcs.connections import IPConnection, IPConnectionSettings -from fastcs.controllers import Controller +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 @@ -116,9 +116,8 @@ async def disable_all(self) -> None: 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]) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/tutorials/static-drivers.md b/docs/tutorials/static-drivers.md index f28f9b603..332327a2b 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 @@ -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 ::: :::: @@ -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,64,70-74,82 ::: :::: diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 5001409a1..f94182d5c 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -1,3 +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 diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py new file mode 100644 index 000000000..e39707b2e --- /dev/null +++ b/src/fastcs/connections/connection.py @@ -0,0 +1,17 @@ +from abc import ABC, abstractmethod + + +class Connection(ABC): + """A link to a device. + + Passed to a `ControllerSpec`. The runner opens it before the controller is + constructed, and closes it when the application stops. + """ + + @abstractmethod + async def connect(self) -> None: + """Open the link, or raise.""" + + @abstractmethod + async def close(self) -> None: + """Close the link.""" diff --git a/src/fastcs/control_system.py b/src/fastcs/control_system.py index 9c3a12138..fa2d99b44 100644 --- a/src/fastcs/control_system.py +++ b/src/fastcs/control_system.py @@ -7,7 +7,7 @@ from IPython.terminal.embed import InteractiveShellEmbed -from fastcs.controllers import Controller +from fastcs.controllers import ControllerSpec from fastcs.logging import logger from fastcs.runner import ControllerRunner from fastcs.tracer import Tracer @@ -16,43 +16,42 @@ tracer = Tracer() -def _context_key(controller: Controller) -> str: +def _context_key(spec: ControllerSpec) -> 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. + Falls back to the class name when the spec has no id. """ - try: - return controller.path[0] - except IndexError: - return controller.__class__.__name__ + if spec.id is not None: + return spec.id + + return getattr(spec.controller_class, "__name__", repr(spec.controller_class)) class FastCS: """Entrypoint for a FastCS application. - This class takes one or more `Controller` instances, runs them with a + 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. + controllers: What to construct each top-level controller from. Accepts + either a single ``ControllerSpec`` or a sequence of them. 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], + controllers: ControllerSpec | Sequence[ControllerSpec], transports: Sequence[Transport], loop: asyncio.AbstractEventLoop | None = None, ): - if isinstance(controllers, Controller): + if isinstance(controllers, ControllerSpec): controllers = [controllers] - self._controllers: list[Controller] = list(controllers) - if not self._controllers: + self._specs: list[ControllerSpec] = list(controllers) + if not self._specs: raise ValueError("FastCS requires at least one controller") - keys = [_context_key(c) for c in self._controllers] + keys = [_context_key(spec) for spec in self._specs] if len(set(keys)) != len(keys): duplicates = sorted({k for k in keys if keys.count(k) > 1}) raise ValueError( @@ -95,16 +94,14 @@ async def serve(self, interactive: bool = True) -> None: """ # 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._controllers) + self._runner = await ControllerRunner.build(self._specs) + keys = [_context_key(spec) for spec in self._specs] 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._runner.controller_apis, strict=True - ) - }, + "controllers": dict(zip(keys, self._runner.controllers, strict=True)), + "controller_apis": dict( + zip(keys, self._runner.controller_apis, strict=True) + ), "transports": [ transport.__class__.__name__ for transport in self._transports ], @@ -138,7 +135,7 @@ async def block_forever(): logger.info( "Starting FastCS", - controllers=[_context_key(c) for c in self._controllers], + controllers=keys, transports=f"[{', '.join(str(t) for t in self._transports)}]", ) 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/controller_spec.py b/src/fastcs/controllers/controller_spec.py new file mode 100644 index 000000000..59b6b26e1 --- /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. + + ``ControllerSpec("DEMO", MyController, connection, count=4)`` describes + ``MyController(connection, count=4)``, with its path set to ``["DEMO"]``. The + runner opens every `Connection` in the arguments, then makes the call. + + Args: + id: The root of the controller's path, or ``None`` for an empty 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 | None, + 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) + if self.id is not None: + controller.set_path([self.id]) + + return controller diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index 7bbe7726e..ebfbb5d48 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -11,7 +11,7 @@ from fastcs import __version__ 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, @@ -182,10 +182,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,17 +195,16 @@ 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. +) -> list[ControllerSpec]: + """Create a `ControllerSpec` for each entry under `controllers:`. 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 + ``_build_entry_model``). The entry's ``id`` becomes the spec's id, so that ``ControllerAPI.path`` is rooted at the YAML id. """ seen_ids: set[str] = set() @@ -219,7 +218,7 @@ def _instantiate_controllers( f"Duplicate controller id(s) in `controllers:`: {sorted(set(duplicates))}" ) - controllers: list[Controller] = [] + specs: list[ControllerSpec] = [] for entry in controllers_options: entry_cls: type[BaseModel] = type(entry) registered = _ENTRY_REGISTRY[entry_cls] @@ -229,12 +228,11 @@ def _instantiate_controllers( for name in entry_cls.model_fields if name not in ("id", "type") } - controller = registered.cls(registered.options_type(**field_values)) + options = registered.options_type(**field_values) + specs.append(ControllerSpec(entry.id, registered.cls, options)) else: - controller = registered.cls() - controller.set_path([entry.id]) - controllers.append(controller) - return controllers + specs.append(ControllerSpec(entry.id, registered.cls)) + return specs def _options_field_definitions(options_type: type) -> dict[str, tuple[Any, Any]]: diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 5a34c5858..3fe00a0c0 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -5,24 +5,30 @@ from fastcs.attributes.attr_r import AttrR from fastcs.attributes.attribute_io_ref import AttributeIORef +from fastcs.connections import Connection 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 `Controller` s: initialising, connecting, - the initial reads, the scan tasks, and stopping. + """Runs the lifecycle of one or more top-level controllers: opening their + connections, constructing and initialising them, connecting, the initial reads, + the scan tasks, and stopping. Args: - controllers: The top-level controllers to run + specs: What to construct each top-level controller from """ - def __init__(self, controllers: list[Controller]) -> None: - self._controllers = controllers + def __init__(self, specs: list[ControllerSpec]) -> None: + self._specs = specs + + self._connections: list[Connection] = [] + self._controllers: list[Controller] = [] self._controller_apis: list[ControllerAPI] = [] self._initial_coros: list[ScanCallback] = [] @@ -30,24 +36,31 @@ def __init__(self, controllers: list[Controller]) -> None: self._tasks: set[asyncio.Task] = set() @classmethod - async def build(cls, controllers: list[Controller]) -> Self: - """Initialise the controllers and create a runner with their APIs. + async def build(cls, specs: list[ControllerSpec]) -> Self: + """Open the connections, then construct and initialise the controllers and + create a runner with their APIs. Args: - controllers: The top-level controllers to run + 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 they were given + ``controller_apis``, in the order the specs were given """ - runner = cls(controllers) + runner = cls(specs) + + for spec in specs: + for connection in spec.connections: + await connection.connect() + runner._connections.append(connection) - for controller in controllers: + runner._controllers = [spec.construct() for spec in specs] + for controller in runner._controllers: await controller.initialise() controller.post_initialise() - for controller in controllers: + 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) @@ -56,9 +69,14 @@ async def build(cls, controllers: list[Controller]) -> Self: 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 they were given""" + """The API of each controller, in the order the specs were given""" return self._controller_apis async def start(self) -> None: @@ -72,7 +90,8 @@ async def start(self) -> None: self._tasks = {asyncio.create_task(coro()) for coro in self._scan_coros} async def stop(self) -> None: - """Stop the scan tasks and disconnect the controllers.""" + """Stop the scan tasks, disconnect the controllers and close the + connections.""" self._cancel_tasks() for controller in self._controllers: @@ -83,6 +102,12 @@ async def stop(self) -> None: "Exception during disconnect", controller=controller.path ) + for connection in reversed(self._connections): + 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]]: diff --git a/tests/benchmarking/controller.py b/tests/benchmarking/controller.py index fc2d187e9..120a12bfa 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/example_p4p_ioc.py b/tests/example_p4p_ioc.py index 95cc8e70b..500de5263 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 @@ -112,7 +112,7 @@ def __init__(self, children, description=None): controller.add_sub_controller("child", sub_controller) - fastcs = FastCS(controller, [p4p_options]) + fastcs = FastCS(ControllerSpec(None, lambda: controller), [p4p_options]) fastcs.run() diff --git a/tests/example_softioc.py b/tests/example_softioc.py index 3688ff4fb..363609bf6 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 ( @@ -41,7 +41,7 @@ def run(id="SOFTIOC_TEST_DEVICE"): controller.add_sub_controller("ChildVector", vector) gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Vector") fastcs = FastCS( - controller, + ControllerSpec(None, lambda: controller), [ EpicsCATransport( epicsca=EpicsCAOptions( diff --git a/tests/test_control_system.py b/tests/test_control_system.py index 591844a3c..353714931 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -5,7 +5,7 @@ from fastcs.attributes import AttributeIO, AttributeIORef, 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.methods import Command, command from fastcs.util import ONCE @@ -15,7 +15,7 @@ async def test_scan_tasks(controller): loop = asyncio.get_event_loop() transport_options = [] - fastcs = FastCS(controller, transport_options, loop) + fastcs = FastCS(ControllerSpec(None, lambda: controller), transport_options, loop) asyncio.create_task(fastcs.serve(interactive=False)) await asyncio.sleep(0.1) @@ -45,7 +45,7 @@ async def do_nothing_static(self): controller = MyTestController() loop = asyncio.get_event_loop() transport_options = [] - fastcs = FastCS(controller, transport_options, loop) + fastcs = FastCS(ControllerSpec(None, lambda: controller), transport_options, loop) asyncio.create_task(fastcs.serve(interactive=False)) await asyncio.sleep(0.1) @@ -81,7 +81,7 @@ class MyController(Controller): controller = MyController(ios=[AttributeIOTimesCalled()]) loop = asyncio.get_event_loop() - fastcs = FastCS(controller, [], loop) + fastcs = FastCS(ControllerSpec(None, lambda: controller), [], loop) assert controller.update_quickly.get() == 0 assert controller.update_once.get() == 0 @@ -115,7 +115,7 @@ async def disconnect(self): controller = MyTestController() loop = asyncio.get_event_loop() - fastcs = FastCS(controller, [], loop) + fastcs = FastCS(ControllerSpec(None, lambda: controller), [], loop) task = asyncio.create_task(fastcs.serve(interactive=False)) diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index d85cae3e1..a9ed4643e 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -2,7 +2,8 @@ import pytest -from fastcs.controllers import Controller +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 @@ -40,10 +41,9 @@ async def block(self) -> None: @pytest.mark.asyncio async def test_build_creates_an_api_per_controller(): - a, b = ScanController(), ScanController() - a.set_path(["A"]) - b.set_path(["B"]) - runner = await ControllerRunner.build([a, b]) + runner = await ControllerRunner.build( + [ControllerSpec("A", ScanController), ControllerSpec("B", ScanController)] + ) assert [api.path for api in runner.controller_apis] == [["A"], ["B"]] @@ -51,7 +51,7 @@ async def test_build_creates_an_api_per_controller(): @pytest.mark.asyncio async def test_start_runs_scans_and_stop_stops_them(): controller = ScanController() - runner = await ControllerRunner.build([controller]) + runner = await ControllerRunner.build([ControllerSpec(None, lambda: controller)]) await runner.start() await asyncio.wait_for(controller.multiple_scans.wait(), timeout=1) @@ -60,3 +60,41 @@ async def test_start_runs_scans_and_stop_stops_them(): await asyncio.wait_for(controller.started.wait(), timeout=1) await runner.stop() await asyncio.wait_for(controller.stopped.wait(), timeout=1) + + +class RecordingConnection(Connection): + def __init__(self, events: list[str]) -> None: + self.events = events + + async def connect(self) -> None: + self.events.append("connect") + + async def close(self) -> None: + self.events.append("close") + + +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"] diff --git a/tests/test_controllers.py b/tests/test_controllers.py index f8da91515..93ba2f7f5 100644 --- a/tests/test_controllers.py +++ b/tests/test_controllers.py @@ -4,7 +4,7 @@ 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 @@ -266,7 +266,7 @@ async def failing_scan(self): raise RuntimeError("scan error") controller = MyTestController() - runner = await ControllerRunner.build([controller]) + runner = await ControllerRunner.build([ControllerSpec(None, lambda: controller)]) controller._connected = True task = asyncio.create_task(runner._scan_coros[0]()) diff --git a/tests/test_launch.py b/tests/test_launch.py index 17e935f4c..e6704c9ce 100644 --- a/tests/test_launch.py +++ b/tests/test_launch.py @@ -318,6 +318,6 @@ 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] diff --git a/tests/test_multi_controller.py b/tests/test_multi_controller.py index f317ebb16..b172b83e3 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 @@ -334,16 +334,18 @@ 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", lambda: a), ControllerSpec("beta", lambda: b)], + [transport], + asyncio.get_event_loop(), + ) task = asyncio.create_task(fastcs.serve(interactive=False)) try: await asyncio.sleep(0.1) diff --git a/tests/transports/epics/ca/test_initial_value.py b/tests/transports/epics/ca/test_initial_value.py index b78090dd0..b6697302e 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..a9b7d1d4d 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,7 @@ 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(): From 6eddcaf029a2ca275a5e23cc531bfdcfd89b2911 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Fri, 6 Nov 2026 15:45:09 +0000 Subject: [PATCH 02/37] ensure clean shutdown --- src/fastcs/runner.py | 29 ++++++++++++++++++++--------- tests/test_controller_runner.py | 16 ++++++++++++++++ 2 files changed, 36 insertions(+), 9 deletions(-) diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 3fe00a0c0..ba0f2d8a5 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -47,18 +47,24 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: A runner ready to `start`, with an API per controller in ``controller_apis``, in the order the specs were given + If anything fails, the connections opened so far are closed again. + """ runner = cls(specs) - for spec in specs: - for connection in spec.connections: - await connection.connect() - runner._connections.append(connection) + try: + for spec in specs: + for connection in spec.connections: + await connection.connect() + runner._connections.append(connection) - runner._controllers = [spec.construct() for spec in specs] - for controller in runner._controllers: - await controller.initialise() - controller.post_initialise() + runner._controllers = [spec.construct() for spec in specs] + for controller in runner._controllers: + await controller.initialise() + controller.post_initialise() + except BaseException: + await runner._close_connections() + raise for controller in runner._controllers: api = controller.build_api(controller.path) @@ -102,7 +108,12 @@ async def stop(self) -> None: "Exception during disconnect", controller=controller.path ) - for connection in reversed(self._connections): + await self._close_connections() + + async def _close_connections(self) -> None: + """Close the open connections, in the reverse of the order they opened.""" + while self._connections: + connection = self._connections.pop() try: await connection.close() except Exception: diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index a9ed4643e..9b928a240 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -98,3 +98,19 @@ async def test_connection_opened_before_construction_and_closed_on_stop(): 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"] From 37ce946fafcd46569f93ba316500bb8a8663fcbd Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 15:25:27 +0000 Subject: [PATCH 03/37] create Connection base class, and use it for connection logic, hand over connection and controller intialisation over to the runner --- docs/explanations/controllers.md | 52 ++++---- docs/explanations/what-is-fastcs.md | 4 +- docs/how-to/launch-framework.md | 33 ++++- docs/how-to/update-attributes-from-device.md | 3 +- docs/snippets/dynamic.py | 18 +-- docs/snippets/static06.py | 14 +-- docs/snippets/static07.py | 14 +-- docs/snippets/static08.py | 14 +-- docs/snippets/static09.py | 14 +-- docs/snippets/static10.py | 14 +-- docs/snippets/static11.py | 14 +-- docs/snippets/static12.py | 14 +-- docs/snippets/static13.py | 14 +-- docs/snippets/static14.py | 16 +-- docs/snippets/static15.py | 16 +-- docs/tutorials/dynamic-drivers.md | 2 +- docs/tutorials/static-drivers.md | 22 ++-- src/fastcs/connections/__init__.py | 2 - src/fastcs/connections/ip_connection.py | 25 ++-- src/fastcs/connections/serial_connection.py | 25 ++-- src/fastcs/controllers/controller.py | 16 +-- src/fastcs/demo/controllers.py | 14 +-- src/fastcs/demo/fastcs.yaml | 14 ++- src/fastcs/demo/schema.json | 24 +++- src/fastcs/launch.py | 126 +++++++++++++------ src/fastcs/runner.py | 21 +--- tests/assertable_controller.py | 6 - tests/test_control_system.py | 30 ----- tests/test_launch.py | 37 +++++- tests/test_multi_controller.py | 12 -- 30 files changed, 318 insertions(+), 312 deletions(-) diff --git a/docs/explanations/controllers.md b/docs/explanations/controllers.md index 2378144d2..53f4a663a 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. +(`reconnect`, `initialise`) are not called automatically by FastCS. The parent +controller is responsible for calling them 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 | | `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) diff --git a/docs/explanations/what-is-fastcs.md b/docs/explanations/what-is-fastcs.md index 501a54284..e336e2c0c 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 (`initialise`, `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..2dea82379 100644 --- a/docs/how-to/launch-framework.md +++ b/docs/how-to/launch-framework.md @@ -52,6 +52,35 @@ 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: + +```python +from fastcs.connections import IPConnection +from fastcs.controllers import Controller + +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 +``` + ## YAML Configuration Files Create a YAML configuration file matching the schema. The conventional @@ -204,8 +233,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/update-attributes-from-device.md b/docs/how-to/update-attributes-from-device.md index 895eb5f2a..b933c220f 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 initialise(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 941091ec5..09805c7fe 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -12,7 +12,7 @@ AttrRW, AttrW, ) -from fastcs.connections import IPConnection, IPConnectionSettings +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 @@ -108,19 +108,13 @@ async def initialise(self): class TemperatureController(Controller): - def __init__(self, settings: IPConnectionSettings): - self._ip_settings = settings - self._connection = IPConnection() + def __init__(self, connection: IPConnection): + self._connection = connection self._io = TemperatureControllerAttributeIO(self._connection) super().__init__(ios=[self._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") @@ -135,12 +129,10 @@ async def initialise(self): await ramp_controller.initialise() self.add_sub_controller(f"Ramp{idx + 1:02d}", ramp_controller) - await self._connection.close() - epics_ca = EpicsCATransport() -connection_settings = IPConnectionSettings("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection) fastcs = FastCS(spec, [epics_ca]) diff --git a/docs/snippets/static06.py b/docs/snippets/static06.py index 2e94bda5c..083e70324 100644 --- a/docs/snippets/static06.py +++ b/docs/snippets/static06.py @@ -1,7 +1,7 @@ from pathlib import Path from fastcs.attributes import AttrR -from fastcs.connections import IPConnection, IPConnectionSettings +from fastcs.connections import IPConnection from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import String from fastcs.launch import FastCS @@ -12,20 +12,16 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection) fastcs = FastCS(spec, [epics_ca]) diff --git a/docs/snippets/static07.py b/docs/snippets/static07.py index e4458503b..759aeeef7 100644 --- a/docs/snippets/static07.py +++ b/docs/snippets/static07.py @@ -3,7 +3,7 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR -from fastcs.connections import IPConnection, IPConnectionSettings +from fastcs.connections import IPConnection from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import String from fastcs.launch import FastCS @@ -34,20 +34,16 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static08.py b/docs/snippets/static08.py index 92c93d4e8..2283078f0 100644 --- a/docs/snippets/static08.py +++ b/docs/snippets/static08.py @@ -3,7 +3,7 @@ from typing import TypeVar from fastcs.attributes import AttributeIO, AttributeIORef, AttrR -from fastcs.connections import IPConnection, IPConnectionSettings +from fastcs.connections import IPConnection from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Float, String from fastcs.launch import FastCS @@ -40,20 +40,16 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static09.py b/docs/snippets/static09.py index 644097ec1..becb41840 100644 --- a/docs/snippets/static09.py +++ b/docs/snippets/static09.py @@ -3,7 +3,7 @@ from typing import TypeVar 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, ControllerSpec from fastcs.datatypes import Float, String from fastcs.launch import FastCS @@ -47,20 +47,16 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static10.py b/docs/snippets/static10.py index 0ce447866..041b16e2b 100644 --- a/docs/snippets/static10.py +++ b/docs/snippets/static10.py @@ -3,7 +3,7 @@ from typing import TypeVar 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, ControllerSpec from fastcs.datatypes import Float, Int, String from fastcs.launch import FastCS @@ -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,14 +70,11 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static11.py b/docs/snippets/static11.py index 7325896d5..93e54595e 100644 --- a/docs/snippets/static11.py +++ b/docs/snippets/static11.py @@ -4,7 +4,7 @@ from typing import TypeVar 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, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS @@ -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,14 +77,11 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static12.py b/docs/snippets/static12.py index 0b3275f47..b5b292b12 100644 --- a/docs/snippets/static12.py +++ b/docs/snippets/static12.py @@ -5,7 +5,7 @@ from typing import TypeVar 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, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS @@ -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,8 +93,8 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static13.py b/docs/snippets/static13.py index 98bf272f9..f3ab435bc 100644 --- a/docs/snippets/static13.py +++ b/docs/snippets/static13.py @@ -6,7 +6,7 @@ from typing import TypeVar 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, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS @@ -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,8 +101,8 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +connection = IPConnection("localhost", 25565) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static14.py b/docs/snippets/static14.py index 1937d5de8..68ba3e9f8 100644 --- a/docs/snippets/static14.py +++ b/docs/snippets/static14.py @@ -6,7 +6,7 @@ from typing import TypeVar 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, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS @@ -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,9 +107,9 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +connection = IPConnection("localhost", 25565) +logger.info("Configuring connection", ip=connection.ip, port=connection.port) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static15.py b/docs/snippets/static15.py index e84359ca9..a302f5574 100644 --- a/docs/snippets/static15.py +++ b/docs/snippets/static15.py @@ -6,7 +6,7 @@ from typing import TypeVar 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, ControllerSpec from fastcs.datatypes import Enum, Float, Int, String from fastcs.launch import FastCS @@ -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,9 +110,9 @@ 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) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection_settings) +connection = IPConnection("localhost", 25565) +logger.info("Configuring connection", ip=connection.ip, port=connection.port) +spec = ControllerSpec("DEMO", TemperatureController, 4, connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/tutorials/dynamic-drivers.md b/docs/tutorials/dynamic-drivers.md index 8b02b1e7b..2e6dc29d9 100644 --- a/docs/tutorials/dynamic-drivers.md +++ b/docs/tutorials/dynamic-drivers.md @@ -57,7 +57,7 @@ Update the controllers to not define attributes statically and implement initial methods to create these attributes dynamically. :::{literalinclude} /snippets/dynamic.py -:lines: 91-131 +:lines: 91-125 ::: 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 332327a2b..e2ec797a3 100644 --- a/docs/tutorials/static-drivers.md +++ b/docs/tutorials/static-drivers.md @@ -144,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. @@ -157,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 ::: :::: @@ -181,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 ::: :::: @@ -290,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,82 +:emphasize-lines: 10,28,32,35,44,48-56,62-63,69-72,78 ::: :::: @@ -368,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 ::: :::: @@ -389,7 +389,7 @@ controller. :class: dropdown, hint :::{literalinclude} /snippets/static13.py -:emphasize-lines: 1,17,100-105 +:emphasize-lines: 1,17,96-101 ::: :::: @@ -421,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 ::: :::: @@ -446,7 +446,7 @@ visible. :class: dropdown, hint :::{literalinclude} /snippets/static15.py -:emphasize-lines: 13,49-51,118 +:emphasize-lines: 13,49-51,114 ::: :::: diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index f94182d5c..1696c2a30 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -1,6 +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/ip_connection.py b/src/fastcs/connections/ip_connection.py index f021aa913..1492bbf43 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 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, 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..dd788584d 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 + 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): + """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/controllers/controller.py b/src/fastcs/controllers/controller.py index a06c2f086..aae91fd25 100755 --- a/src/fastcs/controllers/controller.py +++ b/src/fastcs/controllers/controller.py @@ -13,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(): @@ -32,15 +33,6 @@ def mark_disconnected(self) -> None: """Mark the controller disconnected, pausing its scan tasks until reconnect""" self._connected = False - 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. - - """ - self._connected = True - async def reconnect(self): """Hook to reconnect to device after an error @@ -52,7 +44,3 @@ async def reconnect(self): """ self._connected = True - - async def disconnect(self) -> None: - """Hook to tidy up resources before stopping the application""" - pass diff --git a/src/fastcs/demo/controllers.py b/src/fastcs/demo/controllers.py index 5926fc8ce..a33814b2f 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,8 +70,10 @@ 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, connection: IPConnection, settings: TemperatureControllerSettings + ) -> None: + self.connection = connection self.suffix = "" super().__init__( ios=[TemperatureControllerAttributeIO(self.connection, self.suffix)] @@ -93,13 +94,10 @@ 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.connection.connect() except BaseException: logger.exception("Reconnect failed") return diff --git a/src/fastcs/demo/fastcs.yaml b/src/fastcs/demo/fastcs.yaml index 1784ef2f4..7235c9138 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: + connection: + ip: "localhost" + port: 25565 num_ramp_controllers: 4 - id: AUX type: fastcs.TemperatureController - ip_settings: - ip: "localhost" - port: 25566 + connections: + connection: + 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..4ee786c4c 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": { + "connection": { + "$ref": "#/$defs/IPConnectionSettings" + } + }, + "required": [ + "connection" + ], + "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 ebfbb5d48..cc153e578 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -1,5 +1,6 @@ import asyncio import dataclasses +import functools import inspect import json from pathlib import Path @@ -10,6 +11,7 @@ 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, ControllerSpec from fastcs.exceptions import LaunchError @@ -28,15 +30,16 @@ @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``.""" +Controller class, the connections it takes and its options arg (name and +type, if any). Populated by ``_build_entry_model`` and read by +``_controller_specs``.""" def launch( @@ -53,7 +56,9 @@ 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 + __init__ method. Its ``Connection`` arguments become its + ``connections:`` block, and it may take one other argument, an + options type whose fields are inlined into its entry. The chosen class for each id is selected by a required ``type`` discriminator in the config. version (Optional[str]): The version of the FastCS application. @@ -201,9 +206,10 @@ def _controller_specs( """Create a `ControllerSpec` for each entry under `controllers:`. 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 + model that exposes ``id``, ``type``, ``connections`` (if the controller + takes any) and the controller's options fields inlined as siblings. The + originating Controller class, its connection types and its options-type are + looked up in ``_ENTRY_REGISTRY`` (populated by ``_build_entry_model``). The entry's ``id`` becomes the spec's id, so that ``ControllerAPI.path`` is rooted at the YAML id. """ @@ -222,19 +228,49 @@ def _controller_specs( 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") } - options = registered.options_type(**field_values) - specs.append(ControllerSpec(entry.id, registered.cls, options)) - else: - specs.append(ControllerSpec(entry.id, registered.cls)) + 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:`. + + Its fields are the connection's constructor arguments. Cached so that a + connection class used by several controllers appears once in the schema. + """ + 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 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]]: """Field-by-field definitions for inlining ``options_type`` into an Entry. @@ -269,36 +305,54 @@ 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``. + Each entry exposes ``id`` and a ``type`` discriminator literal, a + ``connections`` block with one field per ``Connection`` argument, and the + options-type's fields, inlined as siblings (no nested ``controller:`` + block). The Controller class, its connection types and its options-type are + recorded in ``_ENTRY_REGISTRY`` for use by ``_controller_specs``. """ sig = inspect.signature(controller_class.__init__) - args = inspect.getfullargspec(controller_class.__init__)[0] + args = inspect.getfullargspec(controller_class.__init__)[0][1:] + 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: + hint = 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: + 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 " @@ -306,10 +360,11 @@ def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: f"which collides with a launch-framework key." ) fields.update(options_fields) - else: + elif len(option_args) > 1: raise LaunchError( - f"Expected no more than 2 arguments for '{controller_class.__name__}" - f".__init__' but received {len(args)} as `{sig}`" + f"Expected no more than 1 argument besides connections for " + f"'{controller_class.__name__}.__init__' but received " + f"{len(option_args)} as `{sig}`" ) entry_model = create_model( @@ -319,7 +374,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 @@ -334,7 +390,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 ``_controller_specs``. """ entries = [_build_entry_model(cls) for cls in controller_classes] diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index ba0f2d8a5..6694ccf28 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -16,8 +16,8 @@ class ControllerRunner: """Runs the lifecycle of one or more top-level controllers: opening their - connections, constructing and initialising them, connecting, the initial reads, - the scan tasks, and stopping. + connections, constructing and initialising them, the initial reads, the scan + tasks, and stopping. Args: specs: What to construct each top-level controller from @@ -86,28 +86,15 @@ def controller_apis(self) -> list[ControllerAPI]: return self._controller_apis async def start(self) -> None: - """Connect the controllers, run the initial reads and start the scan tasks.""" - for controller in self._controllers: - await controller.connect() - + """Run the initial reads and start the scan tasks.""" 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, disconnect the controllers and close the - connections.""" + """Stop the scan tasks and close the connections.""" self._cancel_tasks() - - for controller in self._controllers: - try: - await controller.disconnect() - except Exception: - logger.exception( - "Exception during disconnect", controller=controller.path - ) - await self._close_connections() async def _close_connections(self) -> None: diff --git a/tests/assertable_controller.py b/tests/assertable_controller.py index eb5046bab..2785416ac 100644 --- a/tests/assertable_controller.py +++ b/tests/assertable_controller.py @@ -53,12 +53,6 @@ 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 diff --git a/tests/test_control_system.py b/tests/test_control_system.py index 353714931..8d8781de5 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -96,33 +96,3 @@ class MyController(Controller): 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): - def __init__(self) -> None: - super().__init__() - self.connect_called = asyncio.Event() - self.disconnect_called = asyncio.Event() - - async def connect(self): - self.connect_called.set() - - async def disconnect(self): - self.disconnect_called.set() - - controller = MyTestController() - - loop = asyncio.get_event_loop() - fastcs = FastCS(ControllerSpec(None, lambda: controller), [], loop) - - task = asyncio.create_task(fastcs.serve(interactive=False)) - - # connect is called at the start of serve - await asyncio.wait_for(controller.connect_called.wait(), timeout=1) - - task.cancel() - - # disconnect is called at the end of serve - await asyncio.wait_for(controller.disconnect_called.wait(), timeout=1) diff --git a/tests/test_launch.py b/tests/test_launch.py index e6704c9ce..64951fcce 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 IPConnection from fastcs.control_system import FastCS from fastcs.controllers import Controller from fastcs.datatypes import Int @@ -56,6 +57,11 @@ def __init__(self, arg: SomeConfig, too_many): super().__init__() +class WithConnection(Controller): + def __init__(self, connection: IPConnection, arg: SomeConfig) -> None: + super().__init__() + + class OtherHinted(Controller): def __init__(self, arg: OtherConfig) -> None: super().__init__() @@ -132,8 +138,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: @@ -321,3 +328,29 @@ def test_multi_controller_run_reaches_fastcs(mocker: MockerFixture, tmp_path): 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") diff --git a/tests/test_multi_controller.py b/tests/test_multi_controller.py index b172b83e3..ed07f2acc 100644 --- a/tests/test_multi_controller.py +++ b/tests/test_multi_controller.py @@ -307,8 +307,6 @@ class _LifecycleController(Controller): def __init__(self): super().__init__() - self.connect_called = False - self.disconnect_called = False self.initialised = False self.post_initialised = False @@ -318,12 +316,6 @@ async def initialise(self): def post_initialise(self): self.post_initialised = True - async def connect(self): - self.connect_called = True - - async def disconnect(self): - self.disconnect_called = True - class _OtherLifecycleController(_LifecycleController): bar = AttrR(Int()) @@ -353,7 +345,6 @@ async def test_fastcs_serves_two_controllers_end_to_end(mocker: MockerFixture): for controller in (a, b): assert controller.initialised assert controller.post_initialised - assert controller.connect_called with TestClient(transport._server._app) as client: assert client.get("/alpha/foo").status_code == 200 @@ -371,6 +362,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 controller.disconnect_called From 08b65e6a67e0ec9c13f1526dcdd343759b5eea43 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 15:42:40 +0000 Subject: [PATCH 04/37] add depends_on to Connection, allowing reconnect order to be defined by the author --- docs/how-to/launch-framework.md | 13 +++++ src/fastcs/connections/connection.py | 14 ++++++ src/fastcs/runner.py | 48 +++++++++++++++++- tests/test_controller_runner.py | 73 ++++++++++++++++++++++++++++ 4 files changed, 147 insertions(+), 1 deletion(-) diff --git a/docs/how-to/launch-framework.md b/docs/how-to/launch-framework.md index 2dea82379..f840b9e93 100644 --- a/docs/how-to/launch-framework.md +++ b/docs/how-to/launch-framework.md @@ -81,6 +81,19 @@ controllers: 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 diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index e39707b2e..63c0eb3fe 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -1,4 +1,8 @@ +from __future__ import annotations + from abc import ABC, abstractmethod +from collections.abc import Sequence +from typing import ClassVar class Connection(ABC): @@ -8,6 +12,16 @@ class Connection(ABC): constructed, and closes it when the application stops. """ + depends_on: ClassVar[type[Connection] | Sequence[type[Connection]]] = () + """The connection type, or types, this one needs before it can work. + + This connection depends on every connection of these types in the same + `ControllerSpec`. The runner opens those first, and closes them last:: + + class OdinConnection(Connection): + depends_on = EigerConnection + """ + @abstractmethod async def connect(self) -> None: """Open the link, or raise.""" diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 6694ccf28..30dc75c66 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -54,7 +54,7 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: try: for spec in specs: - for connection in spec.connections: + for connection in _dependency_order(spec.connections): await connection.connect() runner._connections.append(connection) @@ -155,6 +155,52 @@ def __del__(self): self._cancel_tasks() +def _dependency_types(connection: Connection) -> tuple[type[Connection], ...]: + """A connection's ``depends_on``, whether given as one type or several""" + 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. + + A connection depends on every other connection whose type is in its + ``depends_on``. Otherwise the given order is kept. A connection given more than + once appears once. + + 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: diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 9b928a240..b8a8d6e6e 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -114,3 +114,76 @@ async def test_connections_closed_if_build_fails(): ) assert events == ["connect", "close"] + + +class NamedConnection(Connection): + def __init__(self, name: str, events: list[str]) -> None: + self.name = name + self.events = events + + async def connect(self) -> None: + self.events.append(f"connect {self.name}") + + async def close(self) -> None: + self.events.append(f"close {self.name}") + + +class EigerConnection(NamedConnection): + pass + + +class OdinConnection(NamedConnection): + 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("odin", events), + eiger=EigerConnection("eiger", events), + ) + ] + ) + await runner.start() + await runner.stop() + + assert events == ["connect eiger", "connect odin", "close odin", "close eiger"] + + +class ConnectionA(NamedConnection): + pass + + +class ConnectionB(NamedConnection): + depends_on = [ConnectionA] + + +ConnectionA.depends_on = [ConnectionB] + + +@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", + TwoConnectionController, + ConnectionA("a", events), + ConnectionB("b", events), + ) + ] + ) + + assert events == [] From 2d45e12c9c307b67a7627ad3da6a125fbd35be37 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 15:54:04 +0000 Subject: [PATCH 05/37] allow Connections to return device introspection (type IntrospectionT) --- pyproject.toml | 1 + src/fastcs/connections/connection.py | 48 ++++++++++++++++++++++++---- src/fastcs/runner.py | 3 +- tests/test_controller_runner.py | 45 +++++++++++++++++++++++++- uv.lock | 2 ++ 5 files changed, 91 insertions(+), 8 deletions(-) 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/connection.py b/src/fastcs/connections/connection.py index 63c0eb3fe..bee13a795 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -2,14 +2,23 @@ from abc import ABC, abstractmethod from collections.abc import Sequence -from typing import ClassVar +from typing import ClassVar, Generic +from typing_extensions import TypeVar -class Connection(ABC): +IntrospectionT = TypeVar("IntrospectionT", default=None) + + +class Connection(ABC, Generic[IntrospectionT]): """A link to a device. - Passed to a `ControllerSpec`. The runner opens it before the controller is - constructed, and closes it when the application stops. + A connection to a device that can describe itself returns that description from + ``connect``, and declares its type as the type parameter:: + + class EigerConnection(Connection[EigerIntrospection]): + async def connect(self) -> EigerIntrospection: ... + + A plain ``Connection`` doesn't introspect, and its ``connect`` returns ``None``. """ depends_on: ClassVar[type[Connection] | Sequence[type[Connection]]] = () @@ -22,9 +31,36 @@ class OdinConnection(Connection): depends_on = EigerConnection """ + _introspection: IntrospectionT + + @property + def introspection(self) -> IntrospectionT: + """What ``connect`` returned when the runner first opened this connection. + + Every connection is open before any controller is constructed, so a + controller can use this in its ``__init__``. + + Raises: + RuntimeError: If the runner hasn't opened this connection yet + + """ + try: + return self._introspection + except AttributeError: + raise RuntimeError( + f"{type(self).__name__} has no introspection until the runner " + "has opened it" + ) from None + @abstractmethod - async def connect(self) -> None: - """Open the link, or raise.""" + async def connect(self) -> IntrospectionT: + """Open the link, or raise. + + Returns: + The device's description of itself, or ``None`` if this connection + doesn't introspect + + """ @abstractmethod async def close(self) -> None: diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 30dc75c66..379841052 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -55,7 +55,8 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: try: for spec in specs: for connection in _dependency_order(spec.connections): - await connection.connect() + introspection = await connection.connect() + connection._introspection = introspection # noqa: SLF001 runner._connections.append(connection) runner._controllers = [spec.construct() for spec in specs] diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index b8a8d6e6e..bc508472f 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -1,4 +1,5 @@ import asyncio +from dataclasses import dataclass import pytest @@ -171,6 +172,11 @@ class ConnectionB(NamedConnection): 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] = [] @@ -179,7 +185,7 @@ async def test_dependency_cycle_raises_before_anything_opens(): [ ControllerSpec( "A", - TwoConnectionController, + CycleController, ConnectionA("a", events), ConnectionB("b", events), ) @@ -187,3 +193,40 @@ async def test_dependency_cycle_raises_before_anything_opens(): ) assert events == [] + + +@dataclass +class DeviceIntrospection: + parameters: dict[str, int] + + +class IntrospectingConnection(Connection[DeviceIntrospection]): + async def connect(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 runner"): + _ = IntrospectingConnection().introspection 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" }, ] From cff998ca7d5b722370ca2eee8a984b1d5c3f8c0b Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 16:00:01 +0000 Subject: [PATCH 06/37] simplify docstrings --- src/fastcs/connections/connection.py | 20 ++++++------------ src/fastcs/controllers/controller_spec.py | 7 ++++--- src/fastcs/runner.py | 25 +++++------------------ 3 files changed, 15 insertions(+), 37 deletions(-) diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index bee13a795..0448321a7 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -10,22 +10,18 @@ class Connection(ABC, Generic[IntrospectionT]): - """A link to a device. + """A link to a device, optionally returning an introspection from ``connect``. - A connection to a device that can describe itself returns that description from - ``connect``, and declares its type as the type parameter:: + Example:: class EigerConnection(Connection[EigerIntrospection]): async def connect(self) -> EigerIntrospection: ... - - A plain ``Connection`` doesn't introspect, and its ``connect`` returns ``None``. """ depends_on: ClassVar[type[Connection] | Sequence[type[Connection]]] = () - """The connection type, or types, this one needs before it can work. + """Connection type(s) in the same `ControllerSpec` to open before this one. - This connection depends on every connection of these types in the same - `ControllerSpec`. The runner opens those first, and closes them last:: + Example:: class OdinConnection(Connection): depends_on = EigerConnection @@ -35,10 +31,7 @@ class OdinConnection(Connection): @property def introspection(self) -> IntrospectionT: - """What ``connect`` returned when the runner first opened this connection. - - Every connection is open before any controller is constructed, so a - controller can use this in its ``__init__``. + """What ``connect`` returned when the runner opened this connection. Raises: RuntimeError: If the runner hasn't opened this connection yet @@ -57,8 +50,7 @@ async def connect(self) -> IntrospectionT: """Open the link, or raise. Returns: - The device's description of itself, or ``None`` if this connection - doesn't introspect + The introspection, or ``None`` if this connection doesn't introspect """ diff --git a/src/fastcs/controllers/controller_spec.py b/src/fastcs/controllers/controller_spec.py index 59b6b26e1..e18438139 100644 --- a/src/fastcs/controllers/controller_spec.py +++ b/src/fastcs/controllers/controller_spec.py @@ -10,9 +10,10 @@ class ControllerSpec(Generic[P]): """A deferred call that constructs a top-level controller. - ``ControllerSpec("DEMO", MyController, connection, count=4)`` describes - ``MyController(connection, count=4)``, with its path set to ``["DEMO"]``. The - runner opens every `Connection` in the arguments, then makes the call. + Example:: + + # MyController(connection, count=4), with path ["DEMO"] + ControllerSpec("DEMO", MyController, connection, count=4) Args: id: The root of the controller's path, or ``None`` for an empty path diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 379841052..cf2c68363 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -15,9 +15,7 @@ class ControllerRunner: - """Runs the lifecycle of one or more top-level controllers: opening their - connections, constructing and initialising them, the initial reads, the scan - tasks, and stopping. + """Runs the lifecycle of one or more top-level controllers. Args: specs: What to construct each top-level controller from @@ -37,8 +35,8 @@ def __init__(self, specs: list[ControllerSpec]) -> None: @classmethod async def build(cls, specs: list[ControllerSpec]) -> Self: - """Open the connections, then construct and initialise the controllers and - create a runner with their APIs. + """Open the connections, construct the controllers and create a runner with + their APIs. Args: specs: What to construct each top-level controller from @@ -47,8 +45,6 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: A runner ready to `start`, with an API per controller in ``controller_apis``, in the order the specs were given - If anything fails, the connections opened so far are closed again. - """ runner = cls(specs) @@ -99,7 +95,7 @@ async def stop(self) -> None: await self._close_connections() async def _close_connections(self) -> None: - """Close the open connections, in the reverse of the order they opened.""" + """Close the open connections, in reverse order.""" while self._connections: connection = self._connections.pop() try: @@ -112,9 +108,6 @@ def _collect_scans( ) -> tuple[list[ScanCallback], list[ScanCallback]]: """Find the initial reads and periodic scans in a controller's tree. - Periodic scans are grouped into one task per period for each top-level - controller. - Returns: The initial coroutines, and one periodic coroutine per period @@ -157,7 +150,7 @@ def __del__(self): def _dependency_types(connection: Connection) -> tuple[type[Connection], ...]: - """A connection's ``depends_on``, whether given as one type or several""" + """A connection's ``depends_on`` as a tuple""" depends_on = connection.depends_on if isinstance(depends_on, type): return (depends_on,) @@ -168,10 +161,6 @@ def _dependency_types(connection: Connection) -> tuple[type[Connection], ...]: def _dependency_order(connections: list[Connection]) -> list[Connection]: """Order connections so that each comes after the connections it depends on. - A connection depends on every other connection whose type is in its - ``depends_on``. Otherwise the given order is kept. A connection given more than - once appears once. - Raises: ValueError: If the dependencies form a cycle @@ -207,10 +196,6 @@ def _periodic_scan_coro( ) -> ScanCallback: """Create a coroutine to run scans at a given period - If a scan raises, the exception is logged and the controller is marked - disconnected, which pauses every scan task of that controller until its - ``reconnect`` hook marks it connected again. - Args: controller: The top-level controller whose connection gates the scans period: The period to run the scans at From 2b6b29810a429863f06c4bd154a9ef94232cff02 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 16:05:50 +0000 Subject: [PATCH 07/37] add setup() method to controllers, called by the runner in start() --- docs/explanations/controllers.md | 1 + src/fastcs/controllers/base_controller.py | 4 ++++ src/fastcs/runner.py | 16 ++++++++++++++-- tests/test_controller_runner.py | 5 +++++ 4 files changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/explanations/controllers.md b/docs/explanations/controllers.md index 53f4a663a..908576927 100644 --- a/docs/explanations/controllers.md +++ b/docs/explanations/controllers.md @@ -21,6 +21,7 @@ controller is responsible for calling them as part of its own lifecycle, if requ | Method | Purpose | |---|---| | `initialise` | Dynamically add attributes on startup, before the API is built | +| `setup` | Run once at startup, before the initial reads. Called on every controller in the tree | | `reconnect` | Re-open connection after scan error | Connections to the device are not opened by the controller. They are `Connection`s diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index b6b972be9..ba30abbe2 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -189,6 +189,10 @@ async def initialise(self): """Hook for subclasses to dynamically add attributes before building the API""" pass + async def setup(self): + """Hook to run once at startup, before the initial reads""" + pass + def post_initialise(self): """Hook to call after all attributes added, before serving the application""" self._validate_type_hints() diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index cf2c68363..225f4b054 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -1,11 +1,12 @@ import asyncio from collections import defaultdict -from collections.abc import Sequence +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 @@ -83,7 +84,11 @@ def controller_apis(self) -> list[ControllerAPI]: return self._controller_apis async def start(self) -> None: - """Run the initial reads and start the scan tasks.""" + """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() @@ -149,6 +154,13 @@ 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 _dependency_types(connection: Connection) -> tuple[type[Connection], ...]: """A connection's ``depends_on`` as a tuple""" depends_on = connection.depends_on diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index bc508472f..524dba7cc 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -15,10 +15,14 @@ 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 @@ -56,6 +60,7 @@ async def test_start_runs_scans_and_stop_stops_them(): 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) From 8a6b648890d3acc378c5e2db928882173220d803 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 16:20:56 +0000 Subject: [PATCH 08/37] remove initialise, post_initialise, and add seal() which stops attributes and subcontrollers being added after --- docs/explanations/controllers.md | 9 ++-- docs/explanations/what-is-fastcs.md | 2 +- docs/how-to/update-attributes-from-device.md | 2 +- docs/snippets/dynamic.py | 48 ++++++++++++-------- docs/tutorials/dynamic-drivers.md | 34 ++++++++------ src/fastcs/controllers/base_controller.py | 25 +++++++--- src/fastcs/controllers/controller_vector.py | 2 +- src/fastcs/runner.py | 3 +- tests/assertable_controller.py | 5 -- tests/test_attributes.py | 24 ++++------ tests/test_control_system.py | 1 - tests/test_controller_runner.py | 10 ++++ tests/test_multi_controller.py | 13 ++---- 13 files changed, 101 insertions(+), 77 deletions(-) diff --git a/docs/explanations/controllers.md b/docs/explanations/controllers.md index 908576927..213c7f744 100644 --- a/docs/explanations/controllers.md +++ b/docs/explanations/controllers.md @@ -12,15 +12,14 @@ role, FastCS opens the `Connection`s it is given, constructs it, calls its lifec 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 -(`reconnect`, `initialise`) 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 | | `setup` | Run once at startup, before the initial reads. Called on every controller in the tree | | `reconnect` | Re-open connection after scan error | @@ -136,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 e336e2c0c..cbcce2729 100644 --- a/docs/explanations/what-is-fastcs.md +++ b/docs/explanations/what-is-fastcs.md @@ -55,7 +55,7 @@ using `ControllerVector`. See [Controllers](controllers.md) for details. To create a driver, subclass `Controller`, declare attributes and commands as typed class members, take the `Connection`s it needs as constructor arguments, and implement -lifecycle hooks (`initialise`, `reconnect`) and periodic scan tasks. The [tutorials](../tutorials.md) walk through a complete example. +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/update-attributes-from-device.md b/docs/how-to/update-attributes-from-device.md index b933c220f..ed9b1f4f3 100644 --- a/docs/how-to/update-attributes-from-device.md +++ b/docs/how-to/update-attributes-from-device.md @@ -261,7 +261,7 @@ class SubscriptionController(Controller): super().__init__() self._client = subscription_client - async def initialise(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) diff --git a/docs/snippets/dynamic.py b/docs/snippets/dynamic.py index 09805c7fe..325f9dc9a 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -12,7 +12,7 @@ AttrRW, AttrW, ) -from fastcs.connections import IPConnection +from fastcs.connections import Connection, IPConnection from fastcs.controllers import Controller, ControllerSpec from fastcs.datatypes import Bool, DataType, Float, Int, String from fastcs.launch import FastCS @@ -60,6 +60,25 @@ def create_attributes(parameters: dict[str, Any]) -> dict[str, Attribute]: return attributes +class TemperatureControllerConnection(Connection[dict[str, Any]]): + def __init__(self, ip: str, port: int): + self._connection = IPConnection(ip, port) + + async def connect(self) -> dict[str, Any]: + await self._connection.connect() + response = await self._connection.send_query("API?\r\n") + return json.loads(response.strip("\r\n")) + + async def close(self) -> None: + await self._connection.close() + + async def send_query(self, message: str) -> str: + return await self._connection.send_query(message) + + async def send_command(self, message: str) -> None: + await self._connection.send_command(message) + + NumberT = TypeVar("NumberT", int, float) @@ -73,7 +92,7 @@ class TemperatureControllerAttributeIORef(AttributeIORef): class TemperatureControllerAttributeIO( AttributeIO[NumberT, TemperatureControllerAttributeIORef] ): - def __init__(self, connection: IPConnection): + def __init__(self, connection: TemperatureControllerConnection): super().__init__() self._connection = connection @@ -96,42 +115,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, connection: IPConnection): - self._connection = connection - - self._io = TemperatureControllerAttributeIO(self._connection) - super().__init__(ios=[self._io]) - - async def initialise(self): - api = json.loads((await self._connection.send_query("API?\r\n")).strip("\r\n")) + def __init__(self, connection: TemperatureControllerConnection): + io = TemperatureControllerAttributeIO(connection) + super().__init__(ios=[io]) + api = dict(connection.introspection) ramps_api = api.pop("Ramps") for name, attribute in create_attributes(api).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() + ramp_controller = TemperatureRampController(idx + 1, ramp_parameters, io) self.add_sub_controller(f"Ramp{idx + 1:02d}", ramp_controller) epics_ca = EpicsCATransport() -connection = IPConnection("localhost", 25565) +connection = TemperatureControllerConnection("localhost", 25565) spec = ControllerSpec("DEMO", TemperatureController, connection) fastcs = FastCS(spec, [epics_ca]) diff --git a/docs/tutorials/dynamic-drivers.md b/docs/tutorials/dynamic-drivers.md index 2e6dc29d9..81d49f1b5 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 returning that description +from `connect`. FastCS opens every connection before constructing any controller, and +stores what `connect` 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. +Create a connection that queries the `API?` command when it connects, and returns the +parsed response. The type parameter, `Connection[dict[str, Any]]`, is the type that +`connect` returns. :::{literalinclude} /snippets/dynamic.py -:lines: 91-125 +:lines: 63-79 +::: + +Update the controllers to create their attributes from `connection.introspection` in +`__init__`, instead of defining them statically. + +:::{literalinclude} /snippets/dynamic.py +:lines: 114-140 ::: The `suffix` field should also be removed from `TemperatureController` and diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index ba30abbe2..689806664 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -37,6 +37,8 @@ class BaseController(Tracer): root_attribute: Attribute | None = None description: str | None = None + _sealed: bool = False + def __init__( self, path: list[str] | None = None, @@ -185,18 +187,25 @@ 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""" - pass - async def setup(self): """Hook to run once at startup, before the initial reads""" pass - def post_initialise(self): - """Hook to call after all attributes added, before serving the application""" + def _seal(self): + """Validate the tree and connect its attribute IOs, then stop anything being + added to it""" self._validate_type_hints() self._connect_attribute_ios() + self._set_sealed() + + def _set_sealed(self): + self._sealed = True + for controller in self.sub_controllers.values(): + controller._set_sealed() # noqa: SLF001 + + def _check_not_sealed(self, name: str): + if self._sealed: + raise RuntimeError(f"Cannot add {name} to {self} after it has been sealed") def _validate_type_hints(self): """Validate all type-hints were introspected""" @@ -314,6 +323,7 @@ def _check_for_name_clash(self, name: str): ) def add_attribute(self, name, attr: Attribute): + self._check_not_sealed(name) try: self._check_for_name_clash(name) except ValueError as exc: @@ -345,6 +355,7 @@ def attributes(self) -> dict[str, Attribute]: return self.__attributes def add_sub_controller(self, name: str, sub_controller: BaseController): + self._check_not_sealed(name) try: self._check_for_name_clash(name) except ValueError as exc: @@ -383,6 +394,7 @@ def _validate_method(self, name: str, method: Method): ) def add_command(self, name: str, command: Command): + self._check_not_sealed(name) try: self._check_for_name_clash(name) self._validate_method(name, command) @@ -397,6 +409,7 @@ def command_methods(self) -> dict[str, Command]: return self.__command_methods def add_scan(self, name: str, scan: Scan): + self._check_not_sealed(name) try: self._check_for_name_clash(name) self._validate_method(name, scan) 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/runner.py b/src/fastcs/runner.py index 225f4b054..01361bfa4 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -58,8 +58,7 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: runner._controllers = [spec.construct() for spec in specs] for controller in runner._controllers: - await controller.initialise() - controller.post_initialise() + controller._seal() # noqa: SLF001 except BaseException: await runner._close_connections() raise diff --git a/tests/assertable_controller.py b/tests/assertable_controller.py index 2785416ac..f4a1733c7 100644 --- a/tests/assertable_controller.py +++ b/tests/assertable_controller.py @@ -46,13 +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 - @command() async def go(self): pass 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 8d8781de5..cf998ee3e 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -32,7 +32,6 @@ class MyTestController(Controller): def __init__(self): super().__init__() - async def initialise(self): async def do_nothing_dynamic() -> None: pass diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 524dba7cc..5e576529a 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -235,3 +235,13 @@ async def test_introspection_available_when_controller_constructed(): def test_introspection_before_connecting_raises(): with pytest.raises(RuntimeError, match="no introspection until the runner"): _ = IntrospectingConnection().introspection + + +@pytest.mark.asyncio +async def test_controller_tree_sealed_after_build(): + controller = ScanController() + controller.add_sub_controller("SUB", Controller()) + await ControllerRunner.build([ControllerSpec(None, lambda: controller)]) + + with pytest.raises(RuntimeError, match="after it has been sealed"): + controller.sub_controllers["SUB"].add_sub_controller("LATE", Controller()) diff --git a/tests/test_multi_controller.py b/tests/test_multi_controller.py index ed07f2acc..76345caf9 100644 --- a/tests/test_multi_controller.py +++ b/tests/test_multi_controller.py @@ -307,14 +307,10 @@ class _LifecycleController(Controller): def __init__(self): super().__init__() - 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 setup(self): + self.set_up = True class _OtherLifecycleController(_LifecycleController): @@ -343,8 +339,7 @@ async def test_fastcs_serves_two_controllers_end_to_end(mocker: MockerFixture): await asyncio.sleep(0.1) for controller in (a, b): - assert controller.initialised - assert controller.post_initialised + assert controller.set_up with TestClient(transport._server._app) as client: assert client.get("/alpha/foo").status_code == 200 From f5e5a8a0118e937265f949dbacd400313d9a80da Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 16:39:12 +0000 Subject: [PATCH 09/37] move introspection to its own method, update IP Serial connections to make them more easily subclassable --- docs/snippets/dynamic.py | 21 ++++----------------- docs/tutorials/dynamic-drivers.md | 18 +++++++++--------- src/fastcs/connections/connection.py | 16 ++++++++++------ src/fastcs/connections/ip_connection.py | 4 ++-- src/fastcs/connections/serial_connection.py | 4 ++-- src/fastcs/runner.py | 3 ++- tests/test_controller_runner.py | 5 ++++- 7 files changed, 33 insertions(+), 38 deletions(-) diff --git a/docs/snippets/dynamic.py b/docs/snippets/dynamic.py index 325f9dc9a..24fe7319e 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -12,7 +12,7 @@ AttrRW, AttrW, ) -from fastcs.connections import Connection, IPConnection +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 @@ -60,24 +60,11 @@ def create_attributes(parameters: dict[str, Any]) -> dict[str, Attribute]: return attributes -class TemperatureControllerConnection(Connection[dict[str, Any]]): - def __init__(self, ip: str, port: int): - self._connection = IPConnection(ip, port) - - async def connect(self) -> dict[str, Any]: - await self._connection.connect() - response = await self._connection.send_query("API?\r\n") +class TemperatureControllerConnection(IPConnection[dict[str, Any]]): + async def introspect(self) -> dict[str, Any]: + response = await self.send_query("API?\r\n") return json.loads(response.strip("\r\n")) - async def close(self) -> None: - await self._connection.close() - - async def send_query(self, message: str) -> str: - return await self._connection.send_query(message) - - async def send_command(self, message: str) -> None: - await self._connection.send_command(message) - NumberT = TypeVar("NumberT", int, float) diff --git a/docs/tutorials/dynamic-drivers.md b/docs/tutorials/dynamic-drivers.md index 81d49f1b5..81254d273 100644 --- a/docs/tutorials/dynamic-drivers.md +++ b/docs/tutorials/dynamic-drivers.md @@ -31,10 +31,10 @@ or a description for the parameter. ## Introspection -A `Connection` can describe the device it connects to by returning that description -from `connect`. FastCS opens every connection before constructing any controller, and -stores what `connect` returned as `connection.introspection`, so a controller can use it -in its `__init__`. +A `Connection` can describe the device it connects to by implementing `introspect`. +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 create them @@ -53,19 +53,19 @@ create `Attributes`. :lines: 42-60 ::: -Create a connection that queries the `API?` command when it connects, and returns the -parsed response. The type parameter, `Connection[dict[str, Any]]`, is the type that -`connect` returns. +Create a connection whose `introspect` queries the `API?` command and returns the +parsed response. The type parameter, `IPConnection[dict[str, Any]]`, is the type that +`introspect` returns. :::{literalinclude} /snippets/dynamic.py -:lines: 63-79 +:lines: 63-66 ::: Update the controllers to create their attributes from `connection.introspection` in `__init__`, instead of defining them statically. :::{literalinclude} /snippets/dynamic.py -:lines: 114-140 +:lines: 101-127 ::: The `suffix` field should also be removed from `TemperatureController` and diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index 0448321a7..be524730d 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -2,7 +2,7 @@ from abc import ABC, abstractmethod from collections.abc import Sequence -from typing import ClassVar, Generic +from typing import ClassVar, Generic, cast from typing_extensions import TypeVar @@ -10,12 +10,12 @@ class Connection(ABC, Generic[IntrospectionT]): - """A link to a device, optionally returning an introspection from ``connect``. + """A link to a device, which can optionally introspect it. Example:: class EigerConnection(Connection[EigerIntrospection]): - async def connect(self) -> EigerIntrospection: ... + async def introspect(self) -> EigerIntrospection: ... """ depends_on: ClassVar[type[Connection] | Sequence[type[Connection]]] = () @@ -31,7 +31,7 @@ class OdinConnection(Connection): @property def introspection(self) -> IntrospectionT: - """What ``connect`` returned when the runner opened this connection. + """What ``introspect`` returned when the runner opened this connection. Raises: RuntimeError: If the runner hasn't opened this connection yet @@ -46,13 +46,17 @@ def introspection(self) -> IntrospectionT: ) from None @abstractmethod - async def connect(self) -> IntrospectionT: - """Open the link, or raise. + async def connect(self) -> None: + """Open the link, or raise.""" + + async def introspect(self) -> IntrospectionT: + """Describe the device. Called by the runner after ``connect``. Returns: The introspection, or ``None`` if this connection doesn't introspect """ + return cast(IntrospectionT, None) @abstractmethod async def close(self) -> None: diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index 1492bbf43..a690c2afa 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -1,7 +1,7 @@ import asyncio from dataclasses import dataclass -from fastcs.connections.connection import Connection +from fastcs.connections.connection import Connection, IntrospectionT from fastcs.tracer import Tracer @@ -41,7 +41,7 @@ async def close(self): await self.writer.wait_closed() -class IPConnection(Connection, Tracer): +class IPConnection(Connection[IntrospectionT], Tracer): """For connecting to an ip using a `StreamConnection`. Args: diff --git a/src/fastcs/connections/serial_connection.py b/src/fastcs/connections/serial_connection.py index dd788584d..e719d1495 100644 --- a/src/fastcs/connections/serial_connection.py +++ b/src/fastcs/connections/serial_connection.py @@ -2,7 +2,7 @@ import aioserial -from fastcs.connections.connection import Connection +from fastcs.connections.connection import Connection, IntrospectionT class NotOpenedError(Exception): @@ -11,7 +11,7 @@ class NotOpenedError(Exception): pass -class SerialConnection(Connection): +class SerialConnection(Connection[IntrospectionT]): """A serial connection. Args: diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 01361bfa4..bf4d4466b 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -52,7 +52,8 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: try: for spec in specs: for connection in _dependency_order(spec.connections): - introspection = await connection.connect() + await connection.connect() + introspection = await connection.introspect() connection._introspection = introspection # noqa: SLF001 runner._connections.append(connection) diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 5e576529a..04e619f70 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -206,7 +206,10 @@ class DeviceIntrospection: class IntrospectingConnection(Connection[DeviceIntrospection]): - async def connect(self) -> DeviceIntrospection: + async def connect(self) -> None: + pass + + async def introspect(self) -> DeviceIntrospection: return DeviceIntrospection({"gain": 2}) async def close(self) -> None: From 774d34dbc2552b96832990b1f7ba619109aeb05c Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 16:44:36 +0000 Subject: [PATCH 10/37] update example to define its own introspection type --- docs/snippets/dynamic.py | 28 +++++++++++++++++----------- docs/tutorials/dynamic-drivers.md | 10 +++++----- 2 files changed, 22 insertions(+), 16 deletions(-) diff --git a/docs/snippets/dynamic.py b/docs/snippets/dynamic.py index 24fe7319e..32a74de90 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -60,10 +60,18 @@ def create_attributes(parameters: dict[str, Any]) -> dict[str, Attribute]: return attributes -class TemperatureControllerConnection(IPConnection[dict[str, Any]]): - async def introspect(self) -> dict[str, Any]: +@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") - return json.loads(response.strip("\r\n")) + parameters = json.loads(response.strip("\r\n")) + ramps = parameters.pop("Ramps") + return TemperatureIntrospection(parameters, ramps) NumberT = TypeVar("NumberT", int, float) @@ -79,7 +87,7 @@ class TemperatureControllerAttributeIORef(AttributeIORef): class TemperatureControllerAttributeIO( AttributeIO[NumberT, TemperatureControllerAttributeIORef] ): - def __init__(self, connection: TemperatureControllerConnection): + def __init__(self, connection: TemperatureConnection): super().__init__() self._connection = connection @@ -112,23 +120,21 @@ def __init__( class TemperatureController(Controller): - def __init__(self, connection: TemperatureControllerConnection): + def __init__(self, connection: TemperatureConnection): io = TemperatureControllerAttributeIO(connection) super().__init__(ios=[io]) - api = dict(connection.introspection) - 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): + 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) epics_ca = EpicsCATransport() -connection = TemperatureControllerConnection("localhost", 25565) +connection = TemperatureConnection("localhost", 25565) spec = ControllerSpec("DEMO", TemperatureController, connection) fastcs = FastCS(spec, [epics_ca]) diff --git a/docs/tutorials/dynamic-drivers.md b/docs/tutorials/dynamic-drivers.md index 81254d273..4382e5f8c 100644 --- a/docs/tutorials/dynamic-drivers.md +++ b/docs/tutorials/dynamic-drivers.md @@ -53,19 +53,19 @@ create `Attributes`. :lines: 42-60 ::: -Create a connection whose `introspect` queries the `API?` command and returns the -parsed response. The type parameter, `IPConnection[dict[str, Any]]`, is the type that -`introspect` returns. +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: 63-66 +: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: 101-127 +:lines: 109-133 ::: The `suffix` field should also be removed from `TemperatureController` and From fb5d76a1934072cc3019d7355a9fb23895eedfac Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 9 Nov 2026 16:55:29 +0000 Subject: [PATCH 11/37] cleanup --- src/fastcs/control_system.py | 26 ++++++++++-------------- src/fastcs/demo/controllers.py | 5 ----- src/fastcs/launch.py | 36 ++++++++++++--------------------- tests/test_controller_runner.py | 35 +++++++++++--------------------- 4 files changed, 36 insertions(+), 66 deletions(-) diff --git a/src/fastcs/control_system.py b/src/fastcs/control_system.py index fa2d99b44..1c88a1cf7 100644 --- a/src/fastcs/control_system.py +++ b/src/fastcs/control_system.py @@ -7,7 +7,7 @@ from IPython.terminal.embed import InteractiveShellEmbed -from fastcs.controllers import ControllerSpec +from fastcs.controllers import Controller, ControllerSpec from fastcs.logging import logger from fastcs.runner import ControllerRunner from fastcs.tracer import Tracer @@ -16,15 +16,12 @@ tracer = Tracer() -def _context_key(spec: ControllerSpec) -> str: - """Key used for a controller in IPython context dicts. +def _context_key(controller: Controller) -> str: + """Key used for a controller in IPython context dicts and logs""" + if controller.path: + return controller.path[0] - Falls back to the class name when the spec has no id. - """ - if spec.id is not None: - return spec.id - - return getattr(spec.controller_class, "__name__", repr(spec.controller_class)) + return type(controller).__name__ class FastCS: @@ -51,12 +48,11 @@ def __init__( self._specs: list[ControllerSpec] = list(controllers) if not self._specs: raise ValueError("FastCS requires at least one controller") - keys = [_context_key(spec) for spec in self._specs] - 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 spec.id is not None] + 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._transports = transports self._loop = loop or asyncio.get_event_loop() @@ -96,7 +92,7 @@ async def serve(self, interactive: bool = True) -> None: # registers its callbacks before the first values are read. self._runner = await ControllerRunner.build(self._specs) - keys = [_context_key(spec) for spec in self._specs] + keys = [_context_key(controller) for controller in self._runner.controllers] context = { "controllers": dict(zip(keys, self._runner.controllers, strict=True)), "controller_apis": dict( diff --git a/src/fastcs/demo/controllers.py b/src/fastcs/demo/controllers.py index a33814b2f..70430f6ee 100755 --- a/src/fastcs/demo/controllers.py +++ b/src/fastcs/demo/controllers.py @@ -79,8 +79,6 @@ def __init__( ios=[TemperatureControllerAttributeIO(self.connection, 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) @@ -104,9 +102,6 @@ async def reconnect(self): self._connected = True - async def close(self) -> None: - await self.connection.close() - @scan(0.1) async def update_voltages(self): query = "V?" diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index cc153e578..7d4c06548 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -36,10 +36,7 @@ class _RegisteredClass: _ENTRY_REGISTRY: dict[type[BaseModel], _RegisteredClass] = {} -"""Maps each dynamically-built Entry model class to its originating -Controller class, the connections it takes and its options arg (name and -type, if any). Populated by ``_build_entry_model`` and read by -``_controller_specs``.""" +"""Maps each Entry model to its Controller class, connections and options""" def launch( @@ -56,11 +53,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. Its ``Connection`` arguments become its - ``connections:`` block, and it may take one other argument, an - options type whose fields are inlined into its entry. 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: @@ -205,13 +199,9 @@ def _controller_specs( ) -> list[ControllerSpec]: """Create a `ControllerSpec` for each entry under `controllers:`. - Each item in ``controllers_options`` is a dynamically-built Pydantic - model that exposes ``id``, ``type``, ``connections`` (if the controller - takes any) and the controller's options fields inlined as siblings. The - originating Controller class, its connection types and its options-type are - looked up in ``_ENTRY_REGISTRY`` (populated by - ``_build_entry_model``). The entry's ``id`` becomes the spec's id, so that - ``ControllerAPI.path`` is rooted at the YAML id. + Raises: + LaunchError: If two entries have the same id + """ seen_ids: set[str] = set() duplicates: list[str] = [] @@ -251,8 +241,9 @@ def _controller_specs( def _connection_settings_model(connection_type: type[Connection]) -> type[BaseModel]: """Build the Pydantic model for one connection's block under `connections:`. - Its fields are the connection's constructor arguments. Cached so that a - connection class used by several controllers appears once in the schema. + Raises: + LaunchError: If a constructor argument has no type hint + """ sig = inspect.signature(connection_type.__init__) hints = get_type_hints(connection_type.__init__) @@ -305,11 +296,10 @@ 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, a - ``connections`` block with one field per ``Connection`` argument, and the - options-type's fields, inlined as siblings (no nested ``controller:`` - block). The Controller class, its connection types and its options-type are - recorded in ``_ENTRY_REGISTRY`` for use by ``_controller_specs``. + 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][1:] diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 04e619f70..7ba8b3b7d 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -69,14 +69,15 @@ async def test_start_runs_scans_and_stop_stops_them(): class RecordingConnection(Connection): - def __init__(self, events: list[str]) -> None: + 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("connect") + self.events.append(f"connect{self.suffix}") async def close(self) -> None: - self.events.append("close") + self.events.append(f"close{self.suffix}") class ConnectedController(Controller): @@ -122,23 +123,11 @@ async def test_connections_closed_if_build_fails(): assert events == ["connect", "close"] -class NamedConnection(Connection): - def __init__(self, name: str, events: list[str]) -> None: - self.name = name - self.events = events - - async def connect(self) -> None: - self.events.append(f"connect {self.name}") - - async def close(self) -> None: - self.events.append(f"close {self.name}") - - -class EigerConnection(NamedConnection): +class EigerConnection(RecordingConnection): pass -class OdinConnection(NamedConnection): +class OdinConnection(RecordingConnection): depends_on = EigerConnection @@ -155,8 +144,8 @@ async def test_connections_opened_in_dependency_order_and_closed_in_reverse(): ControllerSpec( "A", TwoConnectionController, - odin=OdinConnection("odin", events), - eiger=EigerConnection("eiger", events), + odin=OdinConnection(events, "odin"), + eiger=EigerConnection(events, "eiger"), ) ] ) @@ -166,11 +155,11 @@ async def test_connections_opened_in_dependency_order_and_closed_in_reverse(): assert events == ["connect eiger", "connect odin", "close odin", "close eiger"] -class ConnectionA(NamedConnection): +class ConnectionA(RecordingConnection): pass -class ConnectionB(NamedConnection): +class ConnectionB(RecordingConnection): depends_on = [ConnectionA] @@ -191,8 +180,8 @@ async def test_dependency_cycle_raises_before_anything_opens(): ControllerSpec( "A", CycleController, - ConnectionA("a", events), - ConnectionB("b", events), + ConnectionA(events, "a"), + ConnectionB(events, "b"), ) ] ) From 0668d98a198215ca7919a85965d536ec4b504567 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 11:02:18 +0000 Subject: [PATCH 12/37] remove depends_on docstring --- src/fastcs/connections/connection.py | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index be524730d..155db52ef 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -18,14 +18,8 @@ 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]]] = () - """Connection type(s) in the same `ControllerSpec` to open before this one. - - Example:: - - class OdinConnection(Connection): - depends_on = EigerConnection - """ _introspection: IntrospectionT From 0e7991e01500dd2529f507791516f4b08883524d Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 11:09:16 +0000 Subject: [PATCH 13/37] add a setter to introspection, to remove noqa and raise an error if the user tries to set the introspection themselves --- src/fastcs/connections/connection.py | 7 +++++++ src/fastcs/runner.py | 3 +-- tests/test_controller_runner.py | 7 +++++++ 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index 155db52ef..1d628c1a7 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -39,6 +39,13 @@ def introspection(self) -> IntrospectionT: "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.""" diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index bf4d4466b..2b2128fe3 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -53,8 +53,7 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: for spec in specs: for connection in _dependency_order(spec.connections): await connection.connect() - introspection = await connection.introspect() - connection._introspection = introspection # noqa: SLF001 + connection.introspection = await connection.introspect() runner._connections.append(connection) runner._controllers = [spec.construct() for spec in specs] diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 7ba8b3b7d..cf5c286ff 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -229,6 +229,13 @@ def test_introspection_before_connecting_raises(): _ = 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(): controller = ScanController() From 69fa5cd2b37458427152b487a3e977e55ee26477 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 11:25:25 +0000 Subject: [PATCH 14/37] make seal a public method, raise if set twice --- src/fastcs/controllers/base_controller.py | 25 +++++++++++------------ src/fastcs/runner.py | 2 +- tests/test_controller_runner.py | 7 +++++++ 3 files changed, 20 insertions(+), 14 deletions(-) diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index 689806664..73ed8ad7e 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -191,17 +191,22 @@ async def setup(self): """Hook to run once at startup, before the initial reads""" pass - def _seal(self): - """Validate the tree and connect its attribute IOs, then stop anything being - added to it""" + def seal(self): + """Validate and connect this controller and its sub controllers, then stop + anything being added to them + + 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._set_sealed() - - def _set_sealed(self): self._sealed = True for controller in self.sub_controllers.values(): - controller._set_sealed() # noqa: SLF001 + controller.seal() def _check_not_sealed(self, name: str): if self._sealed: @@ -218,9 +223,6 @@ 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""" member = getattr(self, name, None) @@ -292,9 +294,6 @@ 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.""" diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 2b2128fe3..fcc8b3166 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -58,7 +58,7 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: runner._controllers = [spec.construct() for spec in specs] for controller in runner._controllers: - controller._seal() # noqa: SLF001 + controller.seal() except BaseException: await runner._close_connections() raise diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index cf5c286ff..a3f6f96ae 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -244,3 +244,10 @@ async def test_controller_tree_sealed_after_build(): 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() From cd66d0e00828ca58be76e41993d5ae90662fb1c3 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 11:43:15 +0000 Subject: [PATCH 15/37] update docstrings so they are clearer to authors who look at them --- src/fastcs/connections/connection.py | 12 ++++++------ src/fastcs/controllers/base_controller.py | 4 ++-- tests/test_controller_runner.py | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index 1d628c1a7..61079b7e9 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -25,17 +25,17 @@ async def introspect(self) -> EigerIntrospection: ... @property def introspection(self) -> IntrospectionT: - """What ``introspect`` returned when the runner opened this connection. + """What ``introspect`` returned when the framework opened this connection. Raises: - RuntimeError: If the runner hasn't opened this connection yet + 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 runner " + f"{type(self).__name__} has no introspection until the framework " "has opened it" ) from None @@ -48,10 +48,10 @@ def introspection(self, value: IntrospectionT) -> None: @abstractmethod async def connect(self) -> None: - """Open the link, or raise.""" + """Open the link, or raise. Called by the framework before construction.""" async def introspect(self) -> IntrospectionT: - """Describe the device. Called by the runner after ``connect``. + """Describe the device. Called by the framework after ``connect``. Returns: The introspection, or ``None`` if this connection doesn't introspect @@ -61,4 +61,4 @@ async def introspect(self) -> IntrospectionT: @abstractmethod async def close(self) -> None: - """Close the link.""" + """Close the link. Called by the framework on stop, or if build fails.""" diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index 73ed8ad7e..81c1a5525 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -188,12 +188,12 @@ def __setattr__(self, name, value): super().__setattr__(name, value) async def setup(self): - """Hook to run once at startup, before the initial reads""" + """Hook that runs after all attributes added, before serving the application""" pass def seal(self): """Validate and connect this controller and its sub controllers, then stop - anything being added to them + anything being added to them. Called by the framework after construction. Raises: RuntimeError: If the controller is already sealed diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index a3f6f96ae..ee5de43d8 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -225,7 +225,7 @@ async def test_introspection_available_when_controller_constructed(): def test_introspection_before_connecting_raises(): - with pytest.raises(RuntimeError, match="no introspection until the runner"): + with pytest.raises(RuntimeError, match="no introspection until the framework"): _ = IntrospectingConnection().introspection From 8fe066096626d3aaabad752f8bfeb5202d410d64 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 11:55:18 +0000 Subject: [PATCH 16/37] make ControllerSpec id required and use kw args in docs and examples --- docs/snippets/dynamic.py | 2 +- docs/snippets/static06.py | 2 +- docs/snippets/static07.py | 2 +- docs/snippets/static08.py | 2 +- docs/snippets/static09.py | 2 +- docs/snippets/static10.py | 4 +++- docs/snippets/static11.py | 4 +++- docs/snippets/static12.py | 4 +++- docs/snippets/static13.py | 4 +++- docs/snippets/static14.py | 4 +++- docs/snippets/static15.py | 4 +++- docs/tutorials/static-drivers.md | 2 +- src/fastcs/controllers/controller_spec.py | 11 +++++------ tests/example_p4p_ioc.py | 3 +-- tests/example_softioc.py | 3 +-- tests/test_control_system.py | 6 +++--- tests/test_controller_runner.py | 4 ++-- tests/test_controllers.py | 2 +- 18 files changed, 37 insertions(+), 28 deletions(-) diff --git a/docs/snippets/dynamic.py b/docs/snippets/dynamic.py index 32a74de90..e65c7864a 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -135,7 +135,7 @@ def __init__(self, connection: TemperatureConnection): epics_ca = EpicsCATransport() connection = TemperatureConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, connection) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) fastcs = FastCS(spec, [epics_ca]) diff --git a/docs/snippets/static06.py b/docs/snippets/static06.py index 083e70324..99ede92a5 100644 --- a/docs/snippets/static06.py +++ b/docs/snippets/static06.py @@ -21,7 +21,7 @@ def __init__(self, connection: IPConnection): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, connection) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) fastcs = FastCS(spec, [epics_ca]) diff --git a/docs/snippets/static07.py b/docs/snippets/static07.py index 759aeeef7..58c5f9698 100644 --- a/docs/snippets/static07.py +++ b/docs/snippets/static07.py @@ -43,7 +43,7 @@ def __init__(self, connection: IPConnection): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, connection) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static08.py b/docs/snippets/static08.py index 2283078f0..7430809b0 100644 --- a/docs/snippets/static08.py +++ b/docs/snippets/static08.py @@ -49,7 +49,7 @@ def __init__(self, connection: IPConnection): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, connection) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static09.py b/docs/snippets/static09.py index becb41840..4b6525bb6 100644 --- a/docs/snippets/static09.py +++ b/docs/snippets/static09.py @@ -56,7 +56,7 @@ def __init__(self, connection: IPConnection): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, connection) +spec = ControllerSpec("DEMO", TemperatureController, connection=connection) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static10.py b/docs/snippets/static10.py index 041b16e2b..8731a9db6 100644 --- a/docs/snippets/static10.py +++ b/docs/snippets/static10.py @@ -74,7 +74,9 @@ def __init__(self, ramp_count: int, connection: IPConnection): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static11.py b/docs/snippets/static11.py index 93e54595e..13f6965e3 100644 --- a/docs/snippets/static11.py +++ b/docs/snippets/static11.py @@ -81,7 +81,9 @@ def __init__(self, ramp_count: int, connection: IPConnection): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static12.py b/docs/snippets/static12.py index b5b292b12..1453d978a 100644 --- a/docs/snippets/static12.py +++ b/docs/snippets/static12.py @@ -94,7 +94,9 @@ async def update_voltages(self): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static13.py b/docs/snippets/static13.py index f3ab435bc..ff4fc1e57 100644 --- a/docs/snippets/static13.py +++ b/docs/snippets/static13.py @@ -102,7 +102,9 @@ async def disable_all(self) -> None: gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static14.py b/docs/snippets/static14.py index 68ba3e9f8..8796f94c0 100644 --- a/docs/snippets/static14.py +++ b/docs/snippets/static14.py @@ -109,7 +109,9 @@ async def disable_all(self) -> None: epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) logger.info("Configuring connection", ip=connection.ip, port=connection.port) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static15.py b/docs/snippets/static15.py index a302f5574..54e4017d8 100644 --- a/docs/snippets/static15.py +++ b/docs/snippets/static15.py @@ -112,7 +112,9 @@ async def disable_all(self) -> None: epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) logger.info("Configuring connection", ip=connection.ip, port=connection.port) -spec = ControllerSpec("DEMO", TemperatureController, 4, connection) +spec = ControllerSpec( + "DEMO", TemperatureController, ramp_count=4, connection=connection +) fastcs = FastCS(spec, [epics_ca]) if __name__ == "__main__": diff --git a/docs/tutorials/static-drivers.md b/docs/tutorials/static-drivers.md index e2ec797a3..87afaca85 100644 --- a/docs/tutorials/static-drivers.md +++ b/docs/tutorials/static-drivers.md @@ -290,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,62-63,69-72,78 +:emphasize-lines: 10,28,32,35,44,48-56,62-63,69-72,77-79 ::: :::: diff --git a/src/fastcs/controllers/controller_spec.py b/src/fastcs/controllers/controller_spec.py index e18438139..6a9b595bf 100644 --- a/src/fastcs/controllers/controller_spec.py +++ b/src/fastcs/controllers/controller_spec.py @@ -12,11 +12,11 @@ class ControllerSpec(Generic[P]): Example:: - # MyController(connection, count=4), with path ["DEMO"] - ControllerSpec("DEMO", MyController, connection, count=4) + # MyController(connection=connection, count=4), with path ["DEMO"] + ControllerSpec("DEMO", MyController, connection=connection, count=4) Args: - id: The root of the controller's path, or ``None`` for an empty path + 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`` @@ -25,7 +25,7 @@ class ControllerSpec(Generic[P]): def __init__( self, - id: str | None, + id: str, controller_class: Callable[P, Controller], /, *args: P.args, @@ -45,7 +45,6 @@ def connections(self) -> list[Connection]: def construct(self) -> Controller: """Construct the controller and set its path""" controller = self.controller_class(*self.args, **self.kwargs) - if self.id is not None: - controller.set_path([self.id]) + controller.set_path([self.id]) return controller diff --git a/tests/example_p4p_ioc.py b/tests/example_p4p_ioc.py index 500de5263..2b77d204c 100644 --- a/tests/example_p4p_ioc.py +++ b/tests/example_p4p_ioc.py @@ -90,7 +90,6 @@ 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()) @@ -112,7 +111,7 @@ def __init__(self, children, description=None): controller.add_sub_controller("child", sub_controller) - fastcs = FastCS(ControllerSpec(None, lambda: controller), [p4p_options]) + fastcs = FastCS(ControllerSpec(id, lambda: controller), [p4p_options]) fastcs.run() diff --git a/tests/example_softioc.py b/tests/example_softioc.py index 363609bf6..72626b5f9 100644 --- a/tests/example_softioc.py +++ b/tests/example_softioc.py @@ -36,12 +36,11 @@ 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( - ControllerSpec(None, lambda: controller), + ControllerSpec(id, lambda: controller), [ EpicsCATransport( epicsca=EpicsCAOptions( diff --git a/tests/test_control_system.py b/tests/test_control_system.py index cf998ee3e..aef0382b5 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -15,7 +15,7 @@ async def test_scan_tasks(controller): loop = asyncio.get_event_loop() transport_options = [] - fastcs = FastCS(ControllerSpec(None, lambda: controller), transport_options, loop) + fastcs = FastCS(ControllerSpec("A", lambda: controller), transport_options, loop) asyncio.create_task(fastcs.serve(interactive=False)) await asyncio.sleep(0.1) @@ -44,7 +44,7 @@ async def do_nothing_static(self): controller = MyTestController() loop = asyncio.get_event_loop() transport_options = [] - fastcs = FastCS(ControllerSpec(None, lambda: controller), transport_options, loop) + fastcs = FastCS(ControllerSpec("A", lambda: controller), transport_options, loop) asyncio.create_task(fastcs.serve(interactive=False)) await asyncio.sleep(0.1) @@ -80,7 +80,7 @@ class MyController(Controller): controller = MyController(ios=[AttributeIOTimesCalled()]) loop = asyncio.get_event_loop() - fastcs = FastCS(ControllerSpec(None, lambda: controller), [], loop) + fastcs = FastCS(ControllerSpec("A", lambda: controller), [], loop) assert controller.update_quickly.get() == 0 assert controller.update_once.get() == 0 diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index ee5de43d8..1e3a750e5 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -56,7 +56,7 @@ async def test_build_creates_an_api_per_controller(): @pytest.mark.asyncio async def test_start_runs_scans_and_stop_stops_them(): controller = ScanController() - runner = await ControllerRunner.build([ControllerSpec(None, lambda: controller)]) + runner = await ControllerRunner.build([ControllerSpec("A", lambda: controller)]) await runner.start() await asyncio.wait_for(controller.multiple_scans.wait(), timeout=1) @@ -240,7 +240,7 @@ def test_introspection_set_twice_raises(): async def test_controller_tree_sealed_after_build(): controller = ScanController() controller.add_sub_controller("SUB", Controller()) - await ControllerRunner.build([ControllerSpec(None, lambda: controller)]) + await ControllerRunner.build([ControllerSpec("A", lambda: controller)]) with pytest.raises(RuntimeError, match="after it has been sealed"): controller.sub_controllers["SUB"].add_sub_controller("LATE", Controller()) diff --git a/tests/test_controllers.py b/tests/test_controllers.py index 93ba2f7f5..3b0b6ae48 100644 --- a/tests/test_controllers.py +++ b/tests/test_controllers.py @@ -266,7 +266,7 @@ async def failing_scan(self): raise RuntimeError("scan error") controller = MyTestController() - runner = await ControllerRunner.build([ControllerSpec(None, lambda: controller)]) + runner = await ControllerRunner.build([ControllerSpec("A", lambda: controller)]) controller._connected = True task = asyncio.create_task(runner._scan_coros[0]()) From 4e316ef113a5ca4b4f527ff8a1733d3668c172c6 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 11:57:24 +0000 Subject: [PATCH 17/37] fix setup docstring --- src/fastcs/controllers/base_controller.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index 81c1a5525..cbd1216d2 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -188,7 +188,8 @@ def __setattr__(self, name, value): super().__setattr__(name, value) async def setup(self): - """Hook that runs after all attributes added, before serving the application""" + """Hook called by the framework after all attributes are added, before serving + the application""" pass def seal(self): From e0497923340b8d5977fa885909ef92e4a1ae8bec Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 12:05:12 +0000 Subject: [PATCH 18/37] use specific connection name in examples to make things more clear --- src/fastcs/demo/controllers.py | 19 +++++++++---------- src/fastcs/demo/fastcs.yaml | 4 ++-- src/fastcs/demo/schema.json | 4 ++-- 3 files changed, 13 insertions(+), 14 deletions(-) diff --git a/src/fastcs/demo/controllers.py b/src/fastcs/demo/controllers.py index 70430f6ee..1328781b7 100755 --- a/src/fastcs/demo/controllers.py +++ b/src/fastcs/demo/controllers.py @@ -71,17 +71,17 @@ class TemperatureController(Controller): voltages = AttrR(Waveform(np.int32, shape=(4,))) def __init__( - self, connection: IPConnection, settings: TemperatureControllerSettings + self, sensor: IPConnection, settings: TemperatureControllerSettings ) -> None: - self.connection = connection + self.sensor = sensor self.suffix = "" super().__init__( - ios=[TemperatureControllerAttributeIO(self.connection, self.suffix)] + ios=[TemperatureControllerAttributeIO(self.sensor, self.suffix)] ) 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) @@ -94,8 +94,8 @@ async def cancel_all(self) -> None: async def reconnect(self): try: - await self.connection.close() - await self.connection.connect() + await self.sensor.close() + await self.sensor.connect() except BaseException: logger.exception("Reconnect failed") return @@ -106,7 +106,7 @@ async def reconnect(self): 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) @@ -131,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 7235c9138..47271630a 100644 --- a/src/fastcs/demo/fastcs.yaml +++ b/src/fastcs/demo/fastcs.yaml @@ -3,14 +3,14 @@ controllers: - id: MAIN type: fastcs.TemperatureController connections: - connection: + sensor: ip: "localhost" port: 25565 num_ramp_controllers: 4 - id: AUX type: fastcs.TemperatureController connections: - connection: + sensor: ip: "localhost" port: 25566 num_ramp_controllers: 2 diff --git a/src/fastcs/demo/schema.json b/src/fastcs/demo/schema.json index 4ee786c4c..127681251 100644 --- a/src/fastcs/demo/schema.json +++ b/src/fastcs/demo/schema.json @@ -251,12 +251,12 @@ "TemperatureControllerConnections": { "additionalProperties": false, "properties": { - "connection": { + "sensor": { "$ref": "#/$defs/IPConnectionSettings" } }, "required": [ - "connection" + "sensor" ], "title": "TemperatureControllerConnections", "type": "object" From 9e4aa51b42b7f1cb71c7ff1fc4ff816ceac296cc Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 12:08:06 +0000 Subject: [PATCH 19/37] rename FastCS attribute to specs --- src/fastcs/control_system.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/fastcs/control_system.py b/src/fastcs/control_system.py index 1c88a1cf7..caefc5d0b 100644 --- a/src/fastcs/control_system.py +++ b/src/fastcs/control_system.py @@ -31,7 +31,7 @@ class FastCS: `ControllerRunner` and serves their APIs over the given `Transport` instances. Args: - controllers: What to construct each top-level controller from. Accepts + specs: What to construct each top-level controller from. Accepts either a single ``ControllerSpec`` or a sequence of them. transports: A list of transports to serve the API over loop: Optional event loop to run the control system in @@ -39,16 +39,16 @@ class FastCS: def __init__( self, - controllers: ControllerSpec | Sequence[ControllerSpec], + specs: ControllerSpec | Sequence[ControllerSpec], transports: Sequence[Transport], loop: asyncio.AbstractEventLoop | None = None, ): - if isinstance(controllers, ControllerSpec): - controllers = [controllers] - self._specs: list[ControllerSpec] = list(controllers) + if isinstance(specs, ControllerSpec): + specs = [specs] + self._specs: list[ControllerSpec] = list(specs) if not self._specs: raise ValueError("FastCS requires at least one controller") - ids = [spec.id for spec in self._specs if spec.id is not None] + 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( From 02a547cf7333bb20b9cef1823b9dd2a028a1e663 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 12:39:43 +0000 Subject: [PATCH 20/37] fix launch bugs --- src/fastcs/launch.py | 15 +++++++++++++-- tests/test_launch.py | 31 ++++++++++++++++++++++++++++++- 2 files changed, 43 insertions(+), 3 deletions(-) diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index 7d4c06548..7fb4ba55e 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -4,7 +4,15 @@ 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 @@ -249,6 +257,8 @@ def _connection_settings_model(connection_type: type[Connection]) -> type[BaseMo 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__' " @@ -313,7 +323,8 @@ def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: connection_types: dict[str, type[Connection]] = {} for name in args: - hint = hints.get(name) + # 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 diff --git a/tests/test_launch.py b/tests/test_launch.py index 64951fcce..6f7ee9bcc 100644 --- a/tests/test_launch.py +++ b/tests/test_launch.py @@ -11,7 +11,7 @@ from fastcs import __version__ from fastcs.attributes import AttrR -from fastcs.connections import IPConnection +from fastcs.connections import Connection, IPConnection from fastcs.control_system import FastCS from fastcs.controllers import Controller from fastcs.datatypes import Int @@ -62,6 +62,19 @@ def __init__(self, connection: IPConnection, arg: SomeConfig) -> 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__() @@ -354,3 +367,19 @@ def test_connections_built_from_config(mocker: MockerFixture, tmp_path): 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": {}}], + } + ) From c027e0300cc54890f18cb92daa7e8c0910a1d3bc Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 12:41:20 +0000 Subject: [PATCH 21/37] tidy up --- docs/explanations/controllers.md | 2 +- src/fastcs/control_system.py | 12 ++---------- src/fastcs/runner.py | 13 +++---------- 3 files changed, 6 insertions(+), 21 deletions(-) diff --git a/docs/explanations/controllers.md b/docs/explanations/controllers.md index 213c7f744..b1cb7ddca 100644 --- a/docs/explanations/controllers.md +++ b/docs/explanations/controllers.md @@ -20,7 +20,7 @@ as part of its own lifecycle, if required. | Method | Purpose | |---|---| -| `setup` | Run once at startup, before the initial reads. Called on every controller in the tree | +| `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 | Connections to the device are not opened by the controller. They are `Connection`s diff --git a/src/fastcs/control_system.py b/src/fastcs/control_system.py index caefc5d0b..310ad447e 100644 --- a/src/fastcs/control_system.py +++ b/src/fastcs/control_system.py @@ -7,7 +7,7 @@ from IPython.terminal.embed import InteractiveShellEmbed -from fastcs.controllers import Controller, ControllerSpec +from fastcs.controllers import ControllerSpec from fastcs.logging import logger from fastcs.runner import ControllerRunner from fastcs.tracer import Tracer @@ -16,14 +16,6 @@ tracer = Tracer() -def _context_key(controller: Controller) -> str: - """Key used for a controller in IPython context dicts and logs""" - if controller.path: - return controller.path[0] - - return type(controller).__name__ - - class FastCS: """Entrypoint for a FastCS application. @@ -92,7 +84,7 @@ async def serve(self, interactive: bool = True) -> None: # registers its callbacks before the first values are read. self._runner = await ControllerRunner.build(self._specs) - keys = [_context_key(controller) for controller in self._runner.controllers] + keys = [controller.path[0] for controller in self._runner.controllers] context = { "controllers": dict(zip(keys, self._runner.controllers, strict=True)), "controller_apis": dict( diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index fcc8b3166..398857aa6 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -16,16 +16,9 @@ class ControllerRunner: - """Runs the lifecycle of one or more top-level controllers. - - Args: - specs: What to construct each top-level controller from - - """ - - def __init__(self, specs: list[ControllerSpec]) -> None: - self._specs = specs + """Runs the lifecycle of one or more top-level controllers.""" + def __init__(self) -> None: self._connections: list[Connection] = [] self._controllers: list[Controller] = [] @@ -47,7 +40,7 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: ``controller_apis``, in the order the specs were given """ - runner = cls(specs) + runner = cls() try: for spec in specs: From 455d80f3c7ea5d1c6e18d9de4a43884a2b0509bb Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 16:13:53 +0000 Subject: [PATCH 22/37] document IntrospectionT so the docs build can link to it Co-Authored-By: Claude Opus 5.5 --- src/fastcs/connections/connection.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index 61079b7e9..3ccc44b9a 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -7,6 +7,7 @@ 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]): From 607e829f541255f0c4740d519c430ae1221884b9 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 10:13:50 +0000 Subject: [PATCH 23/37] fix startup/cleanup issues, and add tests to fail on these types of mistakes --- src/fastcs/control_system.py | 91 +++++++++++++++++---------------- src/fastcs/runner.py | 16 +++--- tests/test_control_system.py | 30 +++++++++++ tests/test_controller_runner.py | 20 ++++++++ 4 files changed, 104 insertions(+), 53 deletions(-) diff --git a/src/fastcs/control_system.py b/src/fastcs/control_system.py index 310ad447e..26c8c8669 100644 --- a/src/fastcs/control_system.py +++ b/src/fastcs/control_system.py @@ -84,57 +84,58 @@ async def serve(self, interactive: bool = True) -> None: # registers its callbacks before the first values are read. self._runner = await ControllerRunner.build(self._specs) - keys = [controller.path[0] for controller in self._runner.controllers] - context = { - "controllers": dict(zip(keys, self._runner.controllers, strict=True)), - "controller_apis": dict( - zip(keys, self._runner.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._runner.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}) }" + try: + keys = [controller.path[0] for controller in self._runner.controllers] + context = { + "controllers": dict(zip(keys, self._runner.controllers, strict=True)), + "controller_apis": dict( + zip(keys, 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) - - if interactive: - coros.append(self._interactive_shell(context)) - else: + 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) + + logger.info( + "Starting FastCS", + controllers=keys, + 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=keys, - 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()) - 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") await self._runner.stop() diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 398857aa6..75c9957d1 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -46,23 +46,23 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: for spec in specs: for connection in _dependency_order(spec.connections): await connection.connect() - connection.introspection = await connection.introspect() 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 - 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) - return runner @property diff --git a/tests/test_control_system.py b/tests/test_control_system.py index aef0382b5..a50af5e18 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -4,6 +4,7 @@ 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, ControllerSpec from fastcs.datatypes import Int @@ -95,3 +96,32 @@ class MyController(Controller): assert len(fastcs._runner._tasks) == 1 assert len(fastcs._runner._initial_coros) == 1 + + +class ClosingConnection(Connection): + closed = False + + async def connect(self) -> None: + pass + + async def close(self) -> None: + self.closed = True + + +class FailingSetupController(Controller): + def __init__(self, connection: ClosingConnection) -> None: + super().__init__() + + async def setup(self) -> None: + raise RuntimeError("setup failed") + + +@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 index 1e3a750e5..4df581798 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -123,6 +123,26 @@ async def test_connections_closed_if_build_fails(): 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"] + + class EigerConnection(RecordingConnection): pass From b008a3d79eb82d3391ac1378e6fc4b1d74417715 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 10:19:49 +0000 Subject: [PATCH 24/37] fix keyword only connections appear in schema, and add test --- src/fastcs/launch.py | 6 +++++- tests/test_launch.py | 21 +++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index 7fb4ba55e..5dfe4094c 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -312,7 +312,11 @@ def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: """ sig = inspect.signature(controller_class.__init__) - args = inspect.getfullargspec(controller_class.__init__)[0][1:] + 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) diff --git a/tests/test_launch.py b/tests/test_launch.py index 6f7ee9bcc..00820d6cc 100644 --- a/tests/test_launch.py +++ b/tests/test_launch.py @@ -62,6 +62,11 @@ 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: ... @@ -383,3 +388,19 @@ def test_parametrised_and_no_settings_connections(): "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": {}}], + } + ) From 4c05462046f50db9c261ad3ab53349aac30d8211 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 10:20:51 +0000 Subject: [PATCH 25/37] fix stale references in tutorial --- docs/tutorials/static-drivers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/static-drivers.md b/docs/tutorials/static-drivers.md index 87afaca85..7dbadcc53 100644 --- a/docs/tutorials/static-drivers.md +++ b/docs/tutorials/static-drivers.md @@ -80,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]: '' ::: @@ -456,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 @@ -470,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 From 64ddd9a34cef1cd8787ae8fb278fa9653200e6b3 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 10:23:08 +0000 Subject: [PATCH 26/37] make sure we wait for scans to actually stop --- src/fastcs/runner.py | 2 ++ tests/test_controller_runner.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 75c9957d1..8d56f27ae 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -88,7 +88,9 @@ async def start(self) -> None: 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: diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 4df581798..5e9aa09d0 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -65,7 +65,7 @@ async def test_start_runs_scans_and_stop_stops_them(): await asyncio.wait_for(controller.started.wait(), timeout=1) await runner.stop() - await asyncio.wait_for(controller.stopped.wait(), timeout=1) + assert controller.stopped.is_set() class RecordingConnection(Connection): From e0ced9c5dc3c77b6bfd00ee32210d5642d8e1eb0 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 10:34:18 +0000 Subject: [PATCH 27/37] fix the root path issue, add test to check for correct paths --- src/fastcs/controllers/base_controller.py | 21 ++++++++++++++++++-- tests/test_controllers.py | 24 +++++++++++++++++++++-- 2 files changed, 41 insertions(+), 4 deletions(-) diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index cbd1216d2..fd3274156 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -38,6 +38,7 @@ class BaseController(Tracer): description: str | None = None _sealed: bool = False + _registered: bool = False def __init__( self, @@ -301,12 +302,23 @@ def path(self) -> list[str]: 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_for_name_clash(self, name: str): namespaces = { @@ -371,7 +383,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) diff --git a/tests/test_controllers.py b/tests/test_controllers.py index 3b0b6ae48..ec9620e82 100644 --- a/tests/test_controllers.py +++ b/tests/test_controllers.py @@ -17,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} @@ -30,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__() From f0b769fd591ddc959c5f75891bc6bbc158bfe081 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 10:38:38 +0000 Subject: [PATCH 28/37] standardise path names in new tests --- tests/test_controllers.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/test_controllers.py b/tests/test_controllers.py index ec9620e82..b4bf01ead 100644 --- a/tests/test_controllers.py +++ b/tests/test_controllers.py @@ -43,11 +43,11 @@ def __init__(self) -> None: def test_spec_sets_path_of_sub_controllers_added_in_init(): - controller = ControllerSpec("ROOT", TreeController).construct() + 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" + assert leaf.path == ["root", "child", "leaf"] + assert leaf.attributes["x"].full_name == "root.child.leaf.x" class SomeSubController(Controller): From 2a33384d4732dae87d5d9b851eae649ce96784ef Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 10:41:44 +0000 Subject: [PATCH 29/37] add clear fail if a connection is shared across two sister top level controllers --- src/fastcs/runner.py | 23 +++++++++++++++++++++++ tests/test_controller_runner.py | 15 +++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/src/fastcs/runner.py b/src/fastcs/runner.py index 8d56f27ae..dc0b60980 100644 --- a/src/fastcs/runner.py +++ b/src/fastcs/runner.py @@ -39,7 +39,11 @@ async def build(cls, specs: list[ControllerSpec]) -> Self: 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: @@ -155,6 +159,25 @@ def _walk(controller: BaseController) -> Iterator[BaseController]: 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 diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 5e9aa09d0..11af40b5a 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -143,6 +143,21 @@ async def test_connection_closed_if_introspect_fails(): 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 From 94cba781d79a122c62524be959dbe4957cc8cc51 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 16:22:23 +0000 Subject: [PATCH 30/37] improve base controller checks with sensible error raising --- src/fastcs/controllers/base_controller.py | 95 ++++++++++------------- 1 file changed, 40 insertions(+), 55 deletions(-) diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index fd3274156..2f81baef0 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -210,10 +210,6 @@ def seal(self): for controller in self.sub_controllers.values(): controller.seal() - def _check_not_sealed(self, name: str): - if self._sealed: - raise RuntimeError(f"Cannot add {name} to {self} after it has been sealed") - def _validate_type_hints(self): """Validate all type-hints were introspected""" for name in self.__hinted_attributes: @@ -225,22 +221,26 @@ def _validate_type_hints(self): for name in self.__hinted_methods: self._validate_hinted_method(name) - def _validate_hinted_member(self, name: str, expected_type: type[T]) -> T: - """Validate that a hinted member exists on the controller""" + def _validate_hinted_member( + self, name: str, kind: str, expected_type: type[T] + ) -> T: + """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 {kind} `{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, "method", Method) logger.debug( "Validated hinted method", name=name, controller=self, method=method @@ -248,13 +248,7 @@ 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, "attribute", Attribute) logger.debug( "Validated hinted attribute", name=name, controller=self, attribute=attr @@ -262,13 +256,7 @@ 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, "controller", BaseController) logger.debug( "Validated hinted sub controller", @@ -320,26 +308,34 @@ def set_path(self, path: list[str]): for name, sub_controller in self.__sub_controllers.items(): sub_controller.set_path(path + [name]) - def _check_for_name_clash(self, name: str): + def _check_can_add(self, name: str, kind: str, member: object): + """Check that a member can be added to this controller under ``name``. + + Raises: + RuntimeError: If the controller has been sealed + ValueError: If ``name`` is already used by another member + + """ + if self._sealed: + raise RuntimeError( + f"Cannot add {kind} {name} to {self} after it has been sealed" + ) + namespaces = { "attribute": self.__attributes, "sub controller": self.__sub_controllers, "scan method": self.__scan_methods, "command method": self.__command_methods, } - - for kind, namespace in namespaces.items(): + for existing_kind, namespace in namespaces.items(): 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): - self._check_not_sealed(name) - 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, "attribute", attr) if name in self.__hinted_attributes: hint = self.__hinted_attributes[name] @@ -367,11 +363,7 @@ def attributes(self) -> dict[str, Attribute]: return self.__attributes def add_sub_controller(self, name: str, sub_controller: BaseController): - self._check_not_sealed(name) - 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", sub_controller) if name in self.__hinted_sub_controllers: hint = self.__hinted_sub_controllers[name] @@ -399,11 +391,12 @@ def add_sub_controller(self, name: str, sub_controller: BaseController): def sub_controllers(self) -> dict[str, BaseController]: return self.__sub_controllers - def _validate_method(self, name: str, method: Method): + def _validate_method(self, name: str, kind: str, method: Method): if name in self.__hinted_methods: hint = self.__hinted_methods[name] if not isinstance(method, hint): raise RuntimeError( + f"Cannot add {kind} {method}. " f"Controller '{self.__class__.__name__}' introspection of " f"hinted method '{name}' does not match defined type. " f"Expected '{hint.__name__}' got " @@ -411,12 +404,8 @@ def _validate_method(self, name: str, method: Method): ) def add_command(self, name: str, command: Command): - self._check_not_sealed(name) - 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 method", command) + self._validate_method(name, "command method", command) self.__command_methods[name] = command super().__setattr__(name, command) @@ -426,12 +415,8 @@ def command_methods(self) -> dict[str, Command]: return self.__command_methods def add_scan(self, name: str, scan: Scan): - self._check_not_sealed(name) - 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 method", scan) + self._validate_method(name, "scan method", scan) self.__scan_methods[name] = scan super().__setattr__(name, scan) From 10c3e09b3ea663469eefaed65b8fb49826e8fc9e Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 16:26:25 +0000 Subject: [PATCH 31/37] accept lists of spec only --- docs/how-to/migrate-to-multi-controller.md | 6 +++--- docs/how-to/multiple-transports.md | 4 ++-- docs/snippets/dynamic.py | 2 +- docs/snippets/static02.py | 2 +- docs/snippets/static03.py | 2 +- docs/snippets/static04.py | 2 +- docs/snippets/static05.py | 2 +- docs/snippets/static06.py | 2 +- docs/snippets/static07.py | 2 +- docs/snippets/static08.py | 2 +- docs/snippets/static09.py | 2 +- docs/snippets/static10.py | 2 +- docs/snippets/static11.py | 2 +- docs/snippets/static12.py | 2 +- docs/snippets/static13.py | 2 +- docs/snippets/static14.py | 2 +- docs/snippets/static15.py | 2 +- src/fastcs/control_system.py | 7 ++----- tests/benchmarking/controller.py | 2 +- tests/example_p4p_ioc.py | 2 +- tests/example_softioc.py | 2 +- tests/test_control_system.py | 8 ++++---- tests/transports/epics/ca/test_initial_value.py | 2 +- tests/transports/epics/pva/test_p4p.py | 4 +++- 24 files changed, 33 insertions(+), 34 deletions(-) diff --git a/docs/how-to/migrate-to-multi-controller.md b/docs/how-to/migrate-to-multi-controller.md index 9a4c902d3..09ea7b962 100644 --- a/docs/how-to/migrate-to-multi-controller.md +++ b/docs/how-to/migrate-to-multi-controller.md @@ -106,9 +106,9 @@ transport: ## 5. Direct `FastCS(...)` usage takes `ControllerSpec`s If you instantiate `FastCS` directly rather than via `launch()`, pass a -`ControllerSpec` instead of a constructed controller: -`FastCS(ControllerSpec("DEVICE", MyController), transports)`. For -multi-controller, pass a sequence: +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([...])`. diff --git a/docs/how-to/multiple-transports.md b/docs/how-to/multiple-transports.md index f515ca890..b93f934de 100644 --- a/docs/how-to/multiple-transports.md +++ b/docs/how-to/multiple-transports.md @@ -19,7 +19,7 @@ from fastcs.transports import ( spec = ControllerSpec("DEVICE", MyController) fastcs = FastCS( - spec, + [spec], [ EpicsCATransport(), RestTransport(), @@ -164,7 +164,7 @@ from fastcs.transports import ( spec = ControllerSpec("DEVICE", MyController) fastcs = FastCS( - spec, + [spec], [ EpicsCATransport( gui=EpicsGUIOptions(output_dir=Path("./opis")), diff --git a/docs/snippets/dynamic.py b/docs/snippets/dynamic.py index e65c7864a..39d9c4fda 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -136,7 +136,7 @@ def __init__(self, connection: TemperatureConnection): epics_ca = EpicsCATransport() connection = TemperatureConnection("localhost", 25565) spec = ControllerSpec("DEMO", TemperatureController, connection=connection) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static02.py b/docs/snippets/static02.py index 1dcc446e6..398cdef38 100644 --- a/docs/snippets/static02.py +++ b/docs/snippets/static02.py @@ -6,7 +6,7 @@ class TemperatureController(Controller): pass -fastcs = FastCS(ControllerSpec("DEMO", TemperatureController), []) +fastcs = FastCS([ControllerSpec("DEMO", TemperatureController)], []) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static03.py b/docs/snippets/static03.py index 88245a75a..71d4b683b 100644 --- a/docs/snippets/static03.py +++ b/docs/snippets/static03.py @@ -8,7 +8,7 @@ class TemperatureController(Controller): device_id = AttrR(String()) -fastcs = FastCS(ControllerSpec("DEMO", TemperatureController), []) +fastcs = FastCS([ControllerSpec("DEMO", TemperatureController)], []) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static04.py b/docs/snippets/static04.py index 91bbe2da5..3c867765f 100644 --- a/docs/snippets/static04.py +++ b/docs/snippets/static04.py @@ -11,7 +11,7 @@ class TemperatureController(Controller): epics_ca = EpicsCATransport() spec = ControllerSpec("DEMO", TemperatureController) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static05.py b/docs/snippets/static05.py index deea9573b..b6c48162c 100644 --- a/docs/snippets/static05.py +++ b/docs/snippets/static05.py @@ -15,7 +15,7 @@ class TemperatureController(Controller): gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Temperature Controller") epics_ca = EpicsCATransport(gui=gui_options) spec = ControllerSpec("DEMO", TemperatureController) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static06.py b/docs/snippets/static06.py index 99ede92a5..81e73d757 100644 --- a/docs/snippets/static06.py +++ b/docs/snippets/static06.py @@ -22,7 +22,7 @@ def __init__(self, connection: IPConnection): epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) spec = ControllerSpec("DEMO", TemperatureController, connection=connection) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": diff --git a/docs/snippets/static07.py b/docs/snippets/static07.py index 58c5f9698..9835da054 100644 --- a/docs/snippets/static07.py +++ b/docs/snippets/static07.py @@ -44,7 +44,7 @@ def __init__(self, connection: IPConnection): epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) spec = ControllerSpec("DEMO", TemperatureController, connection=connection) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static08.py b/docs/snippets/static08.py index 7430809b0..5b27f8054 100644 --- a/docs/snippets/static08.py +++ b/docs/snippets/static08.py @@ -50,7 +50,7 @@ def __init__(self, connection: IPConnection): epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) spec = ControllerSpec("DEMO", TemperatureController, connection=connection) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static09.py b/docs/snippets/static09.py index 4b6525bb6..d40515a43 100644 --- a/docs/snippets/static09.py +++ b/docs/snippets/static09.py @@ -57,7 +57,7 @@ def __init__(self, connection: IPConnection): epics_ca = EpicsCATransport(gui=gui_options) connection = IPConnection("localhost", 25565) spec = ControllerSpec("DEMO", TemperatureController, connection=connection) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static10.py b/docs/snippets/static10.py index 8731a9db6..e701157df 100644 --- a/docs/snippets/static10.py +++ b/docs/snippets/static10.py @@ -77,7 +77,7 @@ def __init__(self, ramp_count: int, connection: IPConnection): spec = ControllerSpec( "DEMO", TemperatureController, ramp_count=4, connection=connection ) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static11.py b/docs/snippets/static11.py index 13f6965e3..8001f092f 100644 --- a/docs/snippets/static11.py +++ b/docs/snippets/static11.py @@ -84,7 +84,7 @@ def __init__(self, ramp_count: int, connection: IPConnection): spec = ControllerSpec( "DEMO", TemperatureController, ramp_count=4, connection=connection ) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static12.py b/docs/snippets/static12.py index 1453d978a..b2e1a964d 100644 --- a/docs/snippets/static12.py +++ b/docs/snippets/static12.py @@ -97,7 +97,7 @@ async def update_voltages(self): spec = ControllerSpec( "DEMO", TemperatureController, ramp_count=4, connection=connection ) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static13.py b/docs/snippets/static13.py index ff4fc1e57..bc955556f 100644 --- a/docs/snippets/static13.py +++ b/docs/snippets/static13.py @@ -105,7 +105,7 @@ async def disable_all(self) -> None: spec = ControllerSpec( "DEMO", TemperatureController, ramp_count=4, connection=connection ) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static14.py b/docs/snippets/static14.py index 8796f94c0..c6839afda 100644 --- a/docs/snippets/static14.py +++ b/docs/snippets/static14.py @@ -112,7 +112,7 @@ async def disable_all(self) -> None: spec = ControllerSpec( "DEMO", TemperatureController, ramp_count=4, connection=connection ) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/docs/snippets/static15.py b/docs/snippets/static15.py index 54e4017d8..e0a60c7df 100644 --- a/docs/snippets/static15.py +++ b/docs/snippets/static15.py @@ -115,7 +115,7 @@ async def disable_all(self) -> None: spec = ControllerSpec( "DEMO", TemperatureController, ramp_count=4, connection=connection ) -fastcs = FastCS(spec, [epics_ca]) +fastcs = FastCS([spec], [epics_ca]) if __name__ == "__main__": fastcs.run() diff --git a/src/fastcs/control_system.py b/src/fastcs/control_system.py index 26c8c8669..a222611f5 100644 --- a/src/fastcs/control_system.py +++ b/src/fastcs/control_system.py @@ -23,20 +23,17 @@ class FastCS: `ControllerRunner` and serves their APIs over the given `Transport` instances. Args: - specs: What to construct each top-level controller from. Accepts - either a single ``ControllerSpec`` 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, - specs: ControllerSpec | Sequence[ControllerSpec], + specs: Sequence[ControllerSpec], transports: Sequence[Transport], loop: asyncio.AbstractEventLoop | None = None, ): - if isinstance(specs, ControllerSpec): - specs = [specs] self._specs: list[ControllerSpec] = list(specs) if not self._specs: raise ValueError("FastCS requires at least one controller") diff --git a/tests/benchmarking/controller.py b/tests/benchmarking/controller.py index 120a12bfa..da7125669 100644 --- a/tests/benchmarking/controller.py +++ b/tests/benchmarking/controller.py @@ -22,7 +22,7 @@ def run(): TangoTransport(), ] spec = ControllerSpec("BENCHMARK-DEVICE", MyTestController) - instance = FastCS(spec, transport_options, asyncio.get_event_loop()) + instance = FastCS([spec], transport_options, asyncio.get_event_loop()) instance.run() diff --git a/tests/example_p4p_ioc.py b/tests/example_p4p_ioc.py index 2b77d204c..9b642adec 100644 --- a/tests/example_p4p_ioc.py +++ b/tests/example_p4p_ioc.py @@ -111,7 +111,7 @@ def __init__(self, children, description=None): controller.add_sub_controller("child", sub_controller) - fastcs = FastCS(ControllerSpec(id, lambda: controller), [p4p_options]) + fastcs = FastCS([ControllerSpec(id, lambda: controller)], [p4p_options]) fastcs.run() diff --git a/tests/example_softioc.py b/tests/example_softioc.py index 72626b5f9..ac9b1b68f 100644 --- a/tests/example_softioc.py +++ b/tests/example_softioc.py @@ -40,7 +40,7 @@ def run(id="SOFTIOC_TEST_DEVICE"): controller.add_sub_controller("ChildVector", vector) gui_options = EpicsGUIOptions(output_dir=Path("."), title="Demo Vector") fastcs = FastCS( - ControllerSpec(id, lambda: controller), + [ControllerSpec(id, lambda: controller)], [ EpicsCATransport( epicsca=EpicsCAOptions( diff --git a/tests/test_control_system.py b/tests/test_control_system.py index a50af5e18..c6f149427 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -16,7 +16,7 @@ async def test_scan_tasks(controller): loop = asyncio.get_event_loop() transport_options = [] - fastcs = FastCS(ControllerSpec("A", lambda: controller), transport_options, loop) + fastcs = FastCS([ControllerSpec("A", lambda: controller)], transport_options, loop) asyncio.create_task(fastcs.serve(interactive=False)) await asyncio.sleep(0.1) @@ -45,7 +45,7 @@ async def do_nothing_static(self): controller = MyTestController() loop = asyncio.get_event_loop() transport_options = [] - fastcs = FastCS(ControllerSpec("A", lambda: controller), transport_options, loop) + fastcs = FastCS([ControllerSpec("A", lambda: controller)], transport_options, loop) asyncio.create_task(fastcs.serve(interactive=False)) await asyncio.sleep(0.1) @@ -81,7 +81,7 @@ class MyController(Controller): controller = MyController(ios=[AttributeIOTimesCalled()]) loop = asyncio.get_event_loop() - fastcs = FastCS(ControllerSpec("A", lambda: controller), [], loop) + fastcs = FastCS([ControllerSpec("A", lambda: controller)], [], loop) assert controller.update_quickly.get() == 0 assert controller.update_once.get() == 0 @@ -119,7 +119,7 @@ async def setup(self) -> None: @pytest.mark.asyncio async def test_connections_closed_if_startup_fails(): connection = ClosingConnection() - fastcs = FastCS(ControllerSpec("A", FailingSetupController, connection), []) + fastcs = FastCS([ControllerSpec("A", FailingSetupController, connection)], []) with pytest.raises(RuntimeError, match="setup failed"): await fastcs.serve(interactive=False) diff --git a/tests/transports/epics/ca/test_initial_value.py b/tests/transports/epics/ca/test_initial_value.py index b6697302e..e90ffda00 100644 --- a/tests/transports/epics/ca/test_initial_value.py +++ b/tests/transports/epics/ca/test_initial_value.py @@ -52,7 +52,7 @@ async def test_initial_values_set_in_ca(mocker): loop = asyncio.get_event_loop() fastcs = FastCS( - ControllerSpec(pv_prefix, InitialValuesController), + [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 a9b7d1d4d..b6d3c4d59 100644 --- a/tests/transports/epics/pva/test_p4p.py +++ b/tests/transports/epics/pva/test_p4p.py @@ -248,7 +248,9 @@ async def put_pvs(): def make_fastcs(pv_prefix: str, controller: Controller) -> FastCS: - return FastCS(ControllerSpec(pv_prefix, lambda: controller), [EpicsPVATransport()]) + return FastCS( + [ControllerSpec(pv_prefix, lambda: controller)], [EpicsPVATransport()] + ) def test_read_signal_set(): From ff234cb1e2a89878d98ecfe6b58398249e86cd6d Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 16:31:56 +0000 Subject: [PATCH 32/37] remove duplicate check and use ids directly from fastcs --- src/fastcs/control_system.py | 10 ++++++---- src/fastcs/launch.py | 20 ++------------------ tests/test_launch.py | 7 +++---- 3 files changed, 11 insertions(+), 26 deletions(-) diff --git a/src/fastcs/control_system.py b/src/fastcs/control_system.py index a222611f5..f88952026 100644 --- a/src/fastcs/control_system.py +++ b/src/fastcs/control_system.py @@ -43,6 +43,7 @@ def __init__( raise ValueError( f"FastCS received controllers with duplicate ids {duplicates}" ) + self._ids = ids self._transports = transports self._loop = loop or asyncio.get_event_loop() @@ -82,11 +83,12 @@ async def serve(self, interactive: bool = True) -> None: self._runner = await ControllerRunner.build(self._specs) try: - keys = [controller.path[0] for controller in self._runner.controllers] context = { - "controllers": dict(zip(keys, self._runner.controllers, strict=True)), + "controllers": dict( + zip(self._ids, self._runner.controllers, strict=True) + ), "controller_apis": dict( - zip(keys, self._runner.controller_apis, strict=True) + zip(self._ids, self._runner.controller_apis, strict=True) ), "transports": [ transport.__class__.__name__ for transport in self._transports @@ -110,7 +112,7 @@ async def serve(self, interactive: bool = True) -> None: logger.info( "Starting FastCS", - controllers=keys, + controllers=self._ids, transports=f"[{', '.join(str(t) for t in self._transports)}]", ) diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index 5dfe4094c..0ff1ba011 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -205,23 +205,7 @@ def run( def _controller_specs( controllers_options: list[Any], ) -> list[ControllerSpec]: - """Create a `ControllerSpec` for each entry under `controllers:`. - - Raises: - LaunchError: If two entries have the same 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))}" - ) - + """Create a `ControllerSpec` for each entry under `controllers:`.""" specs: list[ControllerSpec] = [] for entry in controllers_options: entry_cls: type[BaseModel] = type(entry) @@ -395,7 +379,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 ``_controller_specs``. + rejected by `FastCS`. """ entries = [_build_entry_model(cls) for cls in controller_classes] diff --git a/tests/test_launch.py b/tests/test_launch.py index 00820d6cc..4373764eb 100644 --- a/tests/test_launch.py +++ b/tests/test_launch.py @@ -301,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( @@ -318,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): From 231c3c921fed03ac70dd0253f4248c76ae90f39d Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 16:34:26 +0000 Subject: [PATCH 33/37] move the fail route above on build entry model --- src/fastcs/launch.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/fastcs/launch.py b/src/fastcs/launch.py index 0ff1ba011..f121066f5 100644 --- a/src/fastcs/launch.py +++ b/src/fastcs/launch.py @@ -332,7 +332,14 @@ def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: options_name: str | None = None options_type: Any = None - if len(option_args) == 1: + 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( @@ -349,12 +356,6 @@ def _build_entry_model(controller_class: type[Controller]) -> type[BaseModel]: f"which collides with a launch-framework key." ) fields.update(options_fields) - elif 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}`" - ) entry_model = create_model( f"{controller_class.__name__}Entry", From f4b5a7742baf7713b35ab7e95764eaf12d09a421 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 16:38:16 +0000 Subject: [PATCH 34/37] improve test examples --- tests/example_p4p_ioc.py | 50 ++++++++++++++++++++-------------------- tests/example_softioc.py | 11 +++++---- 2 files changed, 32 insertions(+), 29 deletions(-) diff --git a/tests/example_p4p_ioc.py b/tests/example_p4p_ioc.py index 9b642adec..a34183f91 100644 --- a/tests/example_p4p_ioc.py +++ b/tests/example_p4p_ioc.py @@ -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,32 +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]) - - 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([ControllerSpec(id, lambda: 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 ac9b1b68f..a13fd1fad 100644 --- a/tests/example_softioc.py +++ b/tests/example_softioc.py @@ -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,12 +41,9 @@ async def d(self): def run(id="SOFTIOC_TEST_DEVICE"): - controller = ParentController() - 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( - [ControllerSpec(id, lambda: controller)], + [ControllerSpec(id, ParentController)], [ EpicsCATransport( epicsca=EpicsCAOptions( From 43e099a512997a7fa5568bc7718d64f240700fb8 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 16:45:17 +0000 Subject: [PATCH 35/37] tidy up tests, remove lambdas where easy --- tests/conftest.py | 6 ++++++ tests/test_control_system.py | 14 ++++++++------ tests/test_controller_runner.py | 15 ++++++++++----- tests/test_controllers.py | 4 ++-- tests/test_multi_controller.py | 11 ++++++----- 5 files changed, 32 insertions(+), 18 deletions(-) diff --git a/tests/conftest.py b/tests/conftest.py index 10a219849..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,6 +56,11 @@ def controller(): return BackendTestController() +@pytest.fixture +def controller_spec(): + return ControllerSpec("A", BackendTestController) + + @pytest.fixture def controller_api(controller): return controller.build_api([]) diff --git a/tests/test_control_system.py b/tests/test_control_system.py index c6f149427..b1b392d86 100644 --- a/tests/test_control_system.py +++ b/tests/test_control_system.py @@ -10,16 +10,18 @@ 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([ControllerSpec("A", lambda: 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 @@ -42,13 +44,13 @@ async def do_nothing_dynamic() -> None: async def do_nothing_static(self): pass - controller = MyTestController() loop = asyncio.get_event_loop() - transport_options = [] - fastcs = FastCS([ControllerSpec("A", lambda: 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() diff --git a/tests/test_controller_runner.py b/tests/test_controller_runner.py index 11af40b5a..d4e9b6ecc 100644 --- a/tests/test_controller_runner.py +++ b/tests/test_controller_runner.py @@ -55,8 +55,9 @@ async def test_build_creates_an_api_per_controller(): @pytest.mark.asyncio async def test_start_runs_scans_and_stop_stops_them(): - controller = ScanController() - runner = await ControllerRunner.build([ControllerSpec("A", lambda: controller)]) + 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) @@ -273,9 +274,13 @@ def test_introspection_set_twice_raises(): @pytest.mark.asyncio async def test_controller_tree_sealed_after_build(): - controller = ScanController() - controller.add_sub_controller("SUB", Controller()) - await ControllerRunner.build([ControllerSpec("A", lambda: controller)]) + 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()) diff --git a/tests/test_controllers.py b/tests/test_controllers.py index b4bf01ead..38370adc9 100644 --- a/tests/test_controllers.py +++ b/tests/test_controllers.py @@ -285,8 +285,8 @@ class MyTestController(Controller): async def failing_scan(self): raise RuntimeError("scan error") - controller = MyTestController() - runner = await ControllerRunner.build([ControllerSpec("A", lambda: controller)]) + runner = await ControllerRunner.build([ControllerSpec("A", MyTestController)]) + controller = runner.controllers[0] controller._connected = True task = asyncio.create_task(runner._scan_coros[0]()) diff --git a/tests/test_multi_controller.py b/tests/test_multi_controller.py index 76345caf9..9cf6bbda2 100644 --- a/tests/test_multi_controller.py +++ b/tests/test_multi_controller.py @@ -321,16 +321,16 @@ 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() - b = _OtherLifecycleController() - 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( - [ControllerSpec("alpha", lambda: a), ControllerSpec("beta", lambda: b)], + [ + ControllerSpec("alpha", _LifecycleController), + ControllerSpec("beta", _OtherLifecycleController), + ], [transport], asyncio.get_event_loop(), ) @@ -338,7 +338,8 @@ async def test_fastcs_serves_two_controllers_end_to_end(mocker: MockerFixture): try: await asyncio.sleep(0.1) - for controller in (a, b): + for controller in fastcs._runner.controllers: + assert isinstance(controller, _LifecycleController) assert controller.set_up with TestClient(transport._server._app) as client: From 273b08428ed25dd14987ff8e462491259c1b15db Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 16:48:34 +0000 Subject: [PATCH 36/37] fix launch framework how to documentation --- docs/how-to/launch-framework.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/how-to/launch-framework.md b/docs/how-to/launch-framework.md index f840b9e93..1004f1cf2 100644 --- a/docs/how-to/launch-framework.md +++ b/docs/how-to/launch-framework.md @@ -57,12 +57,21 @@ if __name__ == "__main__": 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: +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__() From 92117da5b699fb137b9cb8e7ac3ea005dc0e7262 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Mon, 16 Nov 2026 09:49:32 +0000 Subject: [PATCH 37/37] replace kind with hinted types in validation messages --- src/fastcs/controllers/base_controller.py | 52 +++++++++++++---------- tests/test_controllers.py | 10 ++--- 2 files changed, 34 insertions(+), 28 deletions(-) diff --git a/src/fastcs/controllers/base_controller.py b/src/fastcs/controllers/base_controller.py index 2f81baef0..7307359a8 100755 --- a/src/fastcs/controllers/base_controller.py +++ b/src/fastcs/controllers/base_controller.py @@ -221,9 +221,7 @@ def _validate_type_hints(self): for name in self.__hinted_methods: self._validate_hinted_method(name) - def _validate_hinted_member( - self, name: str, kind: str, expected_type: type[T] - ) -> T: + def _validate_hinted_member(self, name: str, expected_type: type[T]) -> T: """Validate that a hinted member exists on the controller Raises: @@ -234,13 +232,13 @@ def _validate_hinted_member( if member is None or not isinstance(member, expected_type): raise RuntimeError( f"Controller `{self.__class__.__name__}` failed to introspect " - f"hinted {kind} `{name}` during initialisation" + 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""" - method = self._validate_hinted_member(name, "method", Method) + method = self._validate_hinted_member(name, self.__hinted_methods[name]) logger.debug( "Validated hinted method", name=name, controller=self, method=method @@ -248,7 +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""" - attr = self._validate_hinted_member(name, "attribute", Attribute) + attr = self._validate_hinted_member( + name, self.__hinted_attributes[name].attr_type + ) logger.debug( "Validated hinted attribute", name=name, controller=self, attribute=attr @@ -256,7 +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""" - controller = self._validate_hinted_member(name, "controller", BaseController) + controller = self._validate_hinted_member( + name, self.__hinted_sub_controllers[name] + ) logger.debug( "Validated hinted sub controller", @@ -308,7 +310,7 @@ def set_path(self, path: list[str]): for name, sub_controller in self.__sub_controllers.items(): sub_controller.set_path(path + [name]) - def _check_can_add(self, name: str, kind: str, member: object): + def _check_can_add(self, name: str, member: Attribute | BaseController | Method): """Check that a member can be added to this controller under ``name``. Raises: @@ -316,18 +318,22 @@ def _check_can_add(self, name: str, kind: str, member: object): ValueError: If ``name`` is already used by another member """ + namespaces = { + 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" ) - namespaces = { - "attribute": self.__attributes, - "sub controller": self.__sub_controllers, - "scan method": self.__scan_methods, - "command method": self.__command_methods, - } - for existing_kind, namespace in namespaces.items(): + for existing_kind, namespace in namespaces.values(): if name in namespace: raise ValueError( f"Cannot add {kind} {member}. Controller {self} has existing " @@ -335,7 +341,7 @@ def _check_can_add(self, name: str, kind: str, member: object): ) def add_attribute(self, name, attr: Attribute): - self._check_can_add(name, "attribute", attr) + self._check_can_add(name, attr) if name in self.__hinted_attributes: hint = self.__hinted_attributes[name] @@ -363,7 +369,7 @@ def attributes(self) -> dict[str, Attribute]: return self.__attributes def add_sub_controller(self, name: str, sub_controller: BaseController): - self._check_can_add(name, "sub controller", sub_controller) + self._check_can_add(name, sub_controller) if name in self.__hinted_sub_controllers: hint = self.__hinted_sub_controllers[name] @@ -391,12 +397,12 @@ def add_sub_controller(self, name: str, sub_controller: BaseController): def sub_controllers(self) -> dict[str, BaseController]: return self.__sub_controllers - def _validate_method(self, name: str, kind: str, method: Method): + def _validate_method(self, name: str, method: Method): if name in self.__hinted_methods: hint = self.__hinted_methods[name] if not isinstance(method, hint): raise RuntimeError( - f"Cannot add {kind} {method}. " + 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 " @@ -404,8 +410,8 @@ def _validate_method(self, name: str, kind: str, method: Method): ) def add_command(self, name: str, command: Command): - self._check_can_add(name, "command method", command) - self._validate_method(name, "command method", command) + self._check_can_add(name, command) + self._validate_method(name, command) self.__command_methods[name] = command super().__setattr__(name, command) @@ -415,8 +421,8 @@ def command_methods(self) -> dict[str, Command]: return self.__command_methods def add_scan(self, name: str, scan: Scan): - self._check_can_add(name, "scan method", scan) - self._validate_method(name, "scan method", scan) + self._check_can_add(name, scan) + self._validate_method(name, scan) self.__scan_methods[name] = scan super().__setattr__(name, scan) diff --git a/tests/test_controllers.py b/tests/test_controllers.py index 38370adc9..e1bb40344 100644 --- a/tests/test_controllers.py +++ b/tests/test_controllers.py @@ -189,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())) @@ -224,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"): @@ -241,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))