From a99e06a6375a6a3941a4762ed55450c0d278d8f9 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 13:59:50 +0000 Subject: [PATCH 01/16] standard fastcs builtin ip connection --- docs/how-to/update-attributes-from-device.md | 20 +- docs/snippets/dynamic.py | 12 +- docs/snippets/static07.py | 3 +- docs/snippets/static08.py | 3 +- docs/snippets/static09.py | 5 +- docs/snippets/static10.py | 5 +- docs/snippets/static11.py | 5 +- docs/snippets/static12.py | 9 +- docs/snippets/static13.py | 9 +- docs/snippets/static14.py | 9 +- docs/snippets/static15.py | 9 +- docs/tutorials/dynamic-drivers.md | 4 +- docs/tutorials/static-drivers.md | 22 +-- src/fastcs/connections/__init__.py | 2 +- src/fastcs/connections/connection.py | 4 + src/fastcs/connections/ip_connection.py | 190 ++++++++++++------- src/fastcs/demo/controllers.py | 9 +- tests/test_ip_connection.py | 64 +++---- 18 files changed, 198 insertions(+), 186 deletions(-) diff --git a/docs/how-to/update-attributes-from-device.md b/docs/how-to/update-attributes-from-device.md index ed9b1f4f3..451b51e84 100644 --- a/docs/how-to/update-attributes-from-device.md +++ b/docs/how-to/update-attributes-from-device.md @@ -33,11 +33,11 @@ class MyDeviceIO(AttributeIO[float, MyDeviceIORef]): self._connection = connection async def update(self, attr: AttrR[float, MyDeviceIORef]): - response = await self._connection.send_query(f"{attr.io_ref.register}?\r\n") - await attr.update(float(response.strip())) + response = await self._connection.query(f"{attr.io_ref.register}?") + await attr.update(float(response)) async def send(self, attr: AttrW[float, MyDeviceIORef], value: float): - await self._connection.send_command(f"{attr.io_ref.register}={value}\r\n") + await self._connection.write(f"{attr.io_ref.register}={value}") class MyController(Controller): @@ -95,13 +95,13 @@ class MyDeviceIO(AttributeIO[float, MyDeviceIORef]): self._on_put_response = on_put_response async def update(self, attr: AttrR[float, MyDeviceIORef]): - response = await self._connection.send_query(f"{attr.io_ref.register}?\r\n") - await attr.update(float(response.strip())) + response = await self._connection.query(f"{attr.io_ref.register}?") + await attr.update(float(response)) async def send(self, attr: AttrW[float, MyDeviceIORef], value: float): # Device responds with a snapshot of all current values after a set - response = await self._connection.send_query( - f"{attr.io_ref.register}={value}\r\n" + response = await self._connection.query( + f"{attr.io_ref.register}={value}" ) if self._on_put_response is not None: await self._on_put_response(response) @@ -117,7 +117,7 @@ class MyController(Controller): super().__init__(ios=[MyDeviceIO(connection, self._handle_put_response)]) async def _handle_put_response(self, response: str) -> None: - actual, power, status = response.strip().split(",") + actual, power, status = response.split(",") await self.actual_temperature.update(float(actual)) await self.power.update(float(power)) await self.status.update(float(status)) @@ -169,7 +169,7 @@ class MultiChannelController(Controller): async def update_voltages(self): # One request returns all channel voltages voltages = json.loads( - (await self._connection.send_query("V?\r\n")).strip() + await self._connection.query("V?") ) for channel, voltage in zip(self._channels, voltages): await channel.voltage.update(float(voltage)) @@ -235,7 +235,7 @@ class MultiChannelController(Controller): @scan(0.1) async def fetch_voltages(self): voltages = json.loads( - (await self._connection.send_query("V?\r\n")).strip() + await self._connection.query("V?") ) self._channel_io.update_cache(dict(enumerate(map(float, voltages)))) ``` diff --git a/docs/snippets/dynamic.py b/docs/snippets/dynamic.py index 39d9c4fda..b195b924a 100644 --- a/docs/snippets/dynamic.py +++ b/docs/snippets/dynamic.py @@ -68,10 +68,9 @@ class TemperatureIntrospection: class TemperatureConnection(IPConnection[TemperatureIntrospection]): async def introspect(self) -> TemperatureIntrospection: - response = await self.send_query("API?\r\n") - parameters = json.loads(response.strip("\r\n")) - ramps = parameters.pop("Ramps") - return TemperatureIntrospection(parameters, ramps) + api = json.loads(await self.query("API?")) + ramps = api.pop("Ramps") + return TemperatureIntrospection(parameters=api, ramps=ramps) NumberT = TypeVar("NumberT", int, float) @@ -94,8 +93,7 @@ def __init__(self, connection: TemperatureConnection): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) await attr.update(attr.dtype(value)) @@ -103,7 +101,7 @@ async def send( self, attr: AttrW[NumberT, TemperatureControllerAttributeIORef], value: NumberT ) -> None: command = f"{attr.io_ref.name}={attr.dtype(value)}" - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) class TemperatureRampController(Controller): diff --git a/docs/snippets/static07.py b/docs/snippets/static07.py index 9835da054..29c9771a3 100644 --- a/docs/snippets/static07.py +++ b/docs/snippets/static07.py @@ -25,8 +25,7 @@ def __init__(self, connection: IPConnection): self._connection = connection async def update(self, attr: AttrR[NumberT, IDAttributeIORef]): - response = await self._connection.send_query("ID?\r\n") - value = response.strip("\r\n") + value = await self._connection.query("ID?") await attr.update(attr.dtype(value)) diff --git a/docs/snippets/static08.py b/docs/snippets/static08.py index 5b27f8054..8adda4d7a 100644 --- a/docs/snippets/static08.py +++ b/docs/snippets/static08.py @@ -30,8 +30,7 @@ def __init__(self, connection: IPConnection): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) await attr.update(attr.dtype(value)) diff --git a/docs/snippets/static09.py b/docs/snippets/static09.py index d40515a43..12aa5e8f3 100644 --- a/docs/snippets/static09.py +++ b/docs/snippets/static09.py @@ -30,8 +30,7 @@ def __init__(self, connection: IPConnection): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) await attr.update(attr.dtype(value)) @@ -39,7 +38,7 @@ async def send( self, attr: AttrW[NumberT, TemperatureControllerAttributeIORef], value: NumberT ) -> None: command = f"{attr.io_ref.name}={attr.dtype(value)}" - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) class TemperatureController(Controller): diff --git a/docs/snippets/static10.py b/docs/snippets/static10.py index e701157df..9d94a32c9 100644 --- a/docs/snippets/static10.py +++ b/docs/snippets/static10.py @@ -31,8 +31,7 @@ def __init__(self, connection: IPConnection, suffix: str = ""): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}{self._suffix}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) await attr.update(attr.dtype(value)) @@ -40,7 +39,7 @@ async def send( self, attr: AttrW[NumberT, TemperatureControllerAttributeIORef], value: NumberT ) -> None: command = f"{attr.io_ref.name}{self._suffix}={attr.dtype(value)}" - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) class TemperatureRampController(Controller): diff --git a/docs/snippets/static11.py b/docs/snippets/static11.py index 8001f092f..32e1ebaf0 100644 --- a/docs/snippets/static11.py +++ b/docs/snippets/static11.py @@ -32,8 +32,7 @@ def __init__(self, connection: IPConnection, suffix: str = ""): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}{self._suffix}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) await attr.update(attr.dtype(value)) @@ -41,7 +40,7 @@ async def send( self, attr: AttrW[NumberT, TemperatureControllerAttributeIORef], value: NumberT ) -> None: command = f"{attr.io_ref.name}{self._suffix}={attr.dtype(value)}" - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) class OnOffEnum(enum.StrEnum): diff --git a/docs/snippets/static12.py b/docs/snippets/static12.py index b2e1a964d..5a754d49b 100644 --- a/docs/snippets/static12.py +++ b/docs/snippets/static12.py @@ -34,8 +34,7 @@ def __init__(self, connection: IPConnection, suffix: str = ""): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}{self._suffix}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) await attr.update(attr.dtype(value)) @@ -43,7 +42,7 @@ async def send( self, attr: AttrW[NumberT, TemperatureControllerAttributeIORef], value: NumberT ) -> None: command = f"{attr.io_ref.name}{self._suffix}={attr.dtype(value)}" - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) class OnOffEnum(enum.StrEnum): @@ -84,9 +83,7 @@ def __init__(self, ramp_count: int, connection: IPConnection): @scan(0.1) async def update_voltages(self): - voltages = json.loads( - (await self._connection.send_query("V?\r\n")).strip("\r\n") - ) + voltages = json.loads(await self._connection.query("V?")) for index, controller in enumerate(self._ramp_controllers): await controller.voltage.update(float(voltages[index])) diff --git a/docs/snippets/static13.py b/docs/snippets/static13.py index bc955556f..8addef784 100644 --- a/docs/snippets/static13.py +++ b/docs/snippets/static13.py @@ -35,8 +35,7 @@ def __init__(self, connection: IPConnection, suffix: str = ""): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}{self._suffix}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) await attr.update(attr.dtype(value)) @@ -44,7 +43,7 @@ async def send( self, attr: AttrW[NumberT, TemperatureControllerAttributeIORef], value: NumberT ) -> None: command = f"{attr.io_ref.name}{self._suffix}={attr.dtype(value)}" - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) class OnOffEnum(enum.StrEnum): @@ -85,9 +84,7 @@ def __init__(self, ramp_count: int, connection: IPConnection): @scan(0.1) async def update_voltages(self): - voltages = json.loads( - (await self._connection.send_query("V?\r\n")).strip("\r\n") - ) + voltages = json.loads(await self._connection.query("V?")) for index, controller in enumerate(self._ramp_controllers): await controller.voltage.update(float(voltages[index])) diff --git a/docs/snippets/static14.py b/docs/snippets/static14.py index c6839afda..b13ea869e 100644 --- a/docs/snippets/static14.py +++ b/docs/snippets/static14.py @@ -36,8 +36,7 @@ def __init__(self, connection: IPConnection, suffix: str = ""): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}{self._suffix}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) await attr.update(attr.dtype(value)) async def send( @@ -47,7 +46,7 @@ async def send( logger.info("Sending attribute value", command=command, attribute=attr) - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) class OnOffEnum(enum.StrEnum): @@ -88,9 +87,7 @@ def __init__(self, ramp_count: int, connection: IPConnection): @scan(0.1) async def update_voltages(self): - voltages = json.loads( - (await self._connection.send_query("V?\r\n")).strip("\r\n") - ) + voltages = json.loads(await self._connection.query("V?")) for index, controller in enumerate(self._ramp_controllers): await controller.voltage.update(float(voltages[index])) diff --git a/docs/snippets/static15.py b/docs/snippets/static15.py index e0a60c7df..c2dcadf6a 100644 --- a/docs/snippets/static15.py +++ b/docs/snippets/static15.py @@ -36,8 +36,7 @@ def __init__(self, connection: IPConnection, suffix: str = ""): async def update(self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef]): query = f"{attr.io_ref.name}{self._suffix}?" - response = await self._connection.send_query(f"{query}\r\n") - value = response.strip("\r\n") + value = await self._connection.query(query) self.log_event("Query for attribute", query=query, response=value, topic=attr) @@ -50,7 +49,7 @@ async def send( logger.info("Sending attribute value", command=command, attribute=attr) - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) class OnOffEnum(enum.StrEnum): @@ -91,9 +90,7 @@ def __init__(self, ramp_count: int, connection: IPConnection): @scan(0.1) async def update_voltages(self): - voltages = json.loads( - (await self._connection.send_query("V?\r\n")).strip("\r\n") - ) + voltages = json.loads(await self._connection.query("V?")) for index, controller in enumerate(self._ramp_controllers): await controller.voltage.update(float(voltages[index])) diff --git a/docs/tutorials/dynamic-drivers.md b/docs/tutorials/dynamic-drivers.md index 4382e5f8c..923384498 100644 --- a/docs/tutorials/dynamic-drivers.md +++ b/docs/tutorials/dynamic-drivers.md @@ -58,14 +58,14 @@ Define a type for the introspection, and a connection whose `introspect` queries `IPConnection[TemperatureIntrospection]`, is the type that `introspect` returns. :::{literalinclude} /snippets/dynamic.py -:lines: 63-74 +:lines: 63-73 ::: Update the controllers to create their attributes from `connection.introspection` in `__init__`, instead of defining them statically. :::{literalinclude} /snippets/dynamic.py -:lines: 109-133 +:lines: 107-131 ::: 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 7dbadcc53..f27269598 100644 --- a/docs/tutorials/static-drivers.md +++ b/docs/tutorials/static-drivers.md @@ -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 +:emphasize-lines: 1,3,5-6,15-32,36 ::: :::: @@ -222,7 +222,7 @@ etc. :class: dropdown, hint :::{literalinclude} /snippets/static08.py -:emphasize-lines: 10,19-21,33-38,42-43 +:emphasize-lines: 10,19-21,33-37,41-42 ::: :::: @@ -238,15 +238,15 @@ Update the IO to implement `send` and then add a new `AttrRW` with type `Float` and set the ramp rate. :::{note} -The set commands do not return a response, so use the `send_command` method instead of -`send_query`. +The set commands do not return a response, so use the `write` method instead of +`query`. ::: ::::{admonition} Code 9 :class: dropdown, hint :::{literalinclude} /snippets/static09.py -:emphasize-lines: 7,40-44,48-50 +:emphasize-lines: 7,39-43,47-49 ::: :::: @@ -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,77-79 +:emphasize-lines: 10,28,32,34,43,47-55,61-62,68-71,76-78 ::: :::: @@ -315,7 +315,7 @@ Add an `AttrRW` to the `TemperatureRampController`s with an `Enum` type, using a :class: dropdown, hint :::{literalinclude} /snippets/static11.py -:emphasize-lines: 1,11,49-51,57 +:emphasize-lines: 1,11,48-50,56 ::: :::: @@ -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,87-93 +:emphasize-lines: 2,16,59-61,86-90 ::: :::: @@ -389,7 +389,7 @@ controller. :class: dropdown, hint :::{literalinclude} /snippets/static13.py -:emphasize-lines: 1,17,96-101 +:emphasize-lines: 1,17,93-98 ::: :::: @@ -421,7 +421,7 @@ logger for `TemperatureControllerAttributeIO` to log the commands it sends. :class: dropdown, hint :::{literalinclude} /snippets/static14.py -:emphasize-lines: 13,48,106,111 +:emphasize-lines: 13,47,103,108 ::: :::: @@ -446,7 +446,7 @@ visible. :class: dropdown, hint :::{literalinclude} /snippets/static15.py -:emphasize-lines: 13,49-51,114 +:emphasize-lines: 13,48-50,111 ::: :::: diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 1696c2a30..e6d584c6f 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -1,4 +1,4 @@ from .connection import Connection as Connection +from .connection import DisconnectedError as DisconnectedError from .ip_connection import IPConnection as IPConnection -from .ip_connection import StreamConnection as StreamConnection from .serial_connection import SerialConnection as SerialConnection diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index 3ccc44b9a..61d91c6a5 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -10,6 +10,10 @@ """What a `Connection`'s ``introspect`` returns, or ``None`` if it doesn't introspect""" +class DisconnectedError(Exception): + """Raised when using a connection whose link isn't open""" + + class Connection(ABC, Generic[IntrospectionT]): """A link to a device, which can optionally introspect it. diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index a690c2afa..3898fe84c 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -1,95 +1,139 @@ import asyncio -from dataclasses import dataclass +from collections.abc import AsyncIterator +from contextlib import asynccontextmanager -from fastcs.connections.connection import Connection, IntrospectionT +from fastcs.connections.connection import Connection, DisconnectedError, IntrospectionT from fastcs.tracer import Tracer -class DisconnectedError(Exception): - """Raised if the ip connection is disconnected.""" - - pass - - -@dataclass -class StreamConnection: - """For reading and writing to a stream.""" - - reader: asyncio.StreamReader - writer: asyncio.StreamWriter - - def __post_init__(self): - self._lock = asyncio.Lock() - - async def __aenter__(self): - await self._lock.acquire() - return self - - async def __aexit__(self, exc_type, exc_val, exc_tb): - self._lock.release() - - async def send_message(self, message) -> None: - self.writer.write(message.encode("utf-8")) - await self.writer.drain() - - async def receive_response(self) -> str: - data = await self.reader.readline() - return data.decode("utf-8") - - async def close(self): - self.writer.close() - await self.writer.wait_closed() +class IPConnection(Connection[IntrospectionT], Tracer): + """A TCP link to a device that exchanges terminated messages. + Example:: -class IPConnection(Connection[IntrospectionT], Tracer): - """For connecting to an ip using a `StreamConnection`. + connection = IPConnection("10.0.0.5", 4000) + await connection.write("R=5") + reply = await connection.query("R?") Args: ip: The address to connect to port: The port to connect to + terminator: Added to the end of each message, and marks the end of each reply + encoding: The text encoding of messages and replies + timeout: Seconds to wait for each operation before closing the link """ - def __init__(self, ip: str = "127.0.0.1", port: int = 25565): + def __init__( + self, + ip: str = "127.0.0.1", + port: int = 25565, + terminator: str = "\r\n", + encoding: str = "utf-8", + timeout: float = 5.0, + ): super().__init__() self.ip = ip self.port = port - self.__connection = None - - @property - def _connection(self) -> StreamConnection: - if self.__connection is None: - raise DisconnectedError("Need to call connect() before using IPConnection.") - - return self.__connection + self.terminator = terminator + self.encoding = encoding + self.timeout = timeout + self._streams: tuple[asyncio.StreamReader, asyncio.StreamWriter] | None = None + self._lock = asyncio.Lock() 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: - async with self._connection as connection: - await connection.send_message(message) - - async def send_query(self, message: str) -> str: - async with self._connection as connection: - await connection.send_message(message) - response = await connection.receive_response() - self.log_event( - "Received query response", - query=message.strip(), - response=response.strip(), - ) - return response - - async def close(self): - if self.__connection is None: - return - - async with self._connection as connection: + async with asyncio.timeout(self.timeout): + self._streams = await asyncio.open_connection(self.ip, self.port) + + async def write(self, message: str) -> None: + """Send a message, adding the terminator. + + Raises: + DisconnectedError: If the link isn't open + TimeoutError: If sending takes longer than ``timeout`` + + """ + async with self._exchange() as (_, writer): + writer.write(f"{message}{self.terminator}".encode(self.encoding)) + await writer.drain() + + async def query(self, message: str) -> str: + """Send a message and read the reply. + + Returns: + The reply, without its terminator + + Raises: + DisconnectedError: If the link isn't open + TimeoutError: If the reply takes longer than ``timeout`` + + """ + terminator = self.terminator.encode(self.encoding) + async with self._exchange() as (reader, writer): + writer.write(f"{message}{self.terminator}".encode(self.encoding)) + await writer.drain() + reply = await reader.readuntil(terminator) + + response = reply.removesuffix(terminator).decode(self.encoding) + self.log_event("Received query response", query=message, response=response) + return response + + async def write_bytes(self, data: bytes) -> None: + """Send raw bytes, without a terminator. + + Raises: + DisconnectedError: If the link isn't open + TimeoutError: If sending takes longer than ``timeout`` + + """ + async with self._exchange() as (_, writer): + writer.write(data) + await writer.drain() + + async def query_bytes(self, data: bytes, size: int) -> bytes: + """Send raw bytes and read a reply of a fixed size. + + Returns: + The reply, exactly ``size`` bytes long + + Raises: + DisconnectedError: If the link isn't open + TimeoutError: If the reply takes longer than ``timeout`` + + """ + async with self._exchange() as (reader, writer): + writer.write(data) + await writer.drain() + return await reader.readexactly(size) + + async def close(self) -> None: + async with self._lock: + if self._streams is None: + return + + _, writer = self._streams + self._streams = None + writer.close() try: - await connection.close() + await writer.wait_closed() except ConnectionResetError: pass - finally: - self.__connection = None + + @asynccontextmanager + async def _exchange( + self, + ) -> AsyncIterator[tuple[asyncio.StreamReader, asyncio.StreamWriter]]: + """Hold the lock for one exchange, closing the link if it fails part way""" + async with self._lock: + if self._streams is None: + raise DisconnectedError(f"{self.ip}:{self.port} is not connected") + + reader, writer = self._streams + try: + async with asyncio.timeout(self.timeout): + yield reader, writer + except BaseException: + # A late reply could be left in the stream and read by the next query + self._streams = None + writer.close() + raise diff --git a/src/fastcs/demo/controllers.py b/src/fastcs/demo/controllers.py index 1328781b7..4d0f16e07 100755 --- a/src/fastcs/demo/controllers.py +++ b/src/fastcs/demo/controllers.py @@ -46,15 +46,14 @@ async def send( self, attr: AttrW[NumberT, TemperatureControllerAttributeIORef], value: NumberT ) -> None: command = f"{attr.io_ref.name}{self.suffix}={attr.dtype(value)}" - await self._connection.send_command(f"{command}\r\n") + await self._connection.write(command) self.log_event("Send command for attribute", topic=attr, command=command) async def update( self, attr: AttrR[NumberT, TemperatureControllerAttributeIORef] ) -> None: query = f"{attr.io_ref.name}{self.suffix}?" - response = await self._connection.send_query(f"{query}\r\n") - response = response.strip("\r\n") + response = await self._connection.query(query) self.log_event( "Query for attribute", topic=attr, @@ -105,9 +104,7 @@ async def reconnect(self): @scan(0.1) async def update_voltages(self): query = "V?" - voltages = json.loads( - (await self.sensor.send_query(f"{query}\r\n")).strip("\r\n") - ) + voltages = json.loads(await self.sensor.query(query)) await self.voltages.update(voltages) diff --git a/tests/test_ip_connection.py b/tests/test_ip_connection.py index 3770174f1..744171004 100644 --- a/tests/test_ip_connection.py +++ b/tests/test_ip_connection.py @@ -1,52 +1,38 @@ -from unittest.mock import AsyncMock, MagicMock +import asyncio import pytest +import pytest_asyncio -from fastcs.connections.ip_connection import IPConnection +from fastcs.connections import DisconnectedError, IPConnection -@pytest.fixture -def connection(): - conn = IPConnection() - mock_stream = MagicMock() - mock_stream.__aenter__ = AsyncMock(return_value=mock_stream) - mock_stream.__aexit__ = AsyncMock(return_value=False) - mock_stream.close = AsyncMock() - conn._IPConnection__connection = mock_stream # pyright: ignore[reportAttributeAccessIssue] - return conn, mock_stream +async def _reply_to_r(reader: asyncio.StreamReader, writer: asyncio.StreamWriter): + while line := await reader.readuntil(b"\r\n"): + if line == b"R?\r\n": + writer.write(b"5\r\n") + await writer.drain() -@pytest.mark.asyncio -async def test_close_when_not_connected(connection): - conn, mock_stream = connection - conn._IPConnection__connection = None - - await conn.close() - - mock_stream.close.assert_not_awaited() - assert conn._IPConnection__connection is None +@pytest_asyncio.fixture +async def connection(): + server = await asyncio.start_server(_reply_to_r, "127.0.0.1", 0) + port = server.sockets[0].getsockname()[1] + connection = IPConnection("127.0.0.1", port, timeout=0.1) + await connection.connect() + yield connection + await connection.close() + server.close() @pytest.mark.asyncio -async def test_close_connected_and_connection_reset(connection): - conn, mock_stream = connection - - await conn.close() - mock_stream.close.assert_awaited_once() - assert conn._IPConnection__connection is None +async def test_query_adds_and_strips_terminator(connection: IPConnection): + assert await connection.query("R?") == "5" - conn._IPConnection__connection = mock_stream - mock_stream.close.side_effect = ConnectionResetError - await conn.close() - assert mock_stream.close.await_count == 2 - assert conn._IPConnection__connection is None - - # Other exceptions are propagated, but connection is reset - conn._IPConnection__connection = mock_stream - mock_stream.close.side_effect = OSError - - with pytest.raises(OSError): - await conn.close() +@pytest.mark.asyncio +async def test_timeout_closes_connection(connection: IPConnection): + with pytest.raises(TimeoutError): + await connection.query("NO_REPLY?") - assert conn._IPConnection__connection is None + with pytest.raises(DisconnectedError): + await connection.write("R=5") From 8b6ee6ad46f994e9fc75928d99a0dada10baf896 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 14:11:22 +0000 Subject: [PATCH 02/16] use async generator instead --- src/fastcs/connections/ip_connection.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index 3898fe84c..135c82a2f 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -1,5 +1,5 @@ import asyncio -from collections.abc import AsyncIterator +from collections.abc import AsyncGenerator from contextlib import asynccontextmanager from fastcs.connections.connection import Connection, DisconnectedError, IntrospectionT @@ -53,8 +53,9 @@ async def write(self, message: str) -> None: TimeoutError: If sending takes longer than ``timeout`` """ + data = f"{message}{self.terminator}".encode(self.encoding) async with self._exchange() as (_, writer): - writer.write(f"{message}{self.terminator}".encode(self.encoding)) + writer.write(data) await writer.drain() async def query(self, message: str) -> str: @@ -68,9 +69,10 @@ async def query(self, message: str) -> str: TimeoutError: If the reply takes longer than ``timeout`` """ + data = f"{message}{self.terminator}".encode(self.encoding) terminator = self.terminator.encode(self.encoding) async with self._exchange() as (reader, writer): - writer.write(f"{message}{self.terminator}".encode(self.encoding)) + writer.write(data) await writer.drain() reply = await reader.readuntil(terminator) @@ -122,7 +124,7 @@ async def close(self) -> None: @asynccontextmanager async def _exchange( self, - ) -> AsyncIterator[tuple[asyncio.StreamReader, asyncio.StreamWriter]]: + ) -> AsyncGenerator[tuple[asyncio.StreamReader, asyncio.StreamWriter], None]: """Hold the lock for one exchange, closing the link if it fails part way""" async with self._lock: if self._streams is None: From 0ec23ab66ffd64eabe2af1901c29aac2bf9ec425 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 14:11:59 +0000 Subject: [PATCH 03/16] fastcs[serial] builtin serial connection --- docs/explanations/connections.md | 25 ++++ pyproject.toml | 10 +- src/fastcs/connections/__init__.py | 6 +- src/fastcs/connections/serial_connection.py | 133 +++++++++++++++----- tests/test_serial_connection.py | 47 +++++++ uv.lock | 10 +- 6 files changed, 195 insertions(+), 36 deletions(-) create mode 100644 docs/explanations/connections.md create mode 100644 tests/test_serial_connection.py diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md new file mode 100644 index 000000000..a7c8f766f --- /dev/null +++ b/docs/explanations/connections.md @@ -0,0 +1,25 @@ +# Connections + +A `Connection` is a link to a device. A controller takes its connections as constructor +arguments. FastCS opens them before constructing the controller, and closes them when +the application stops. + +## Built-in connections + +| Connection | Link | Install | +|---|---|---| +| `IPConnection` | TCP | included | +| `SerialConnection` | Serial port | `pip install "fastcs[serial]"` | + +Both exchange text messages that end with a terminator, `\r\n` by default: + +```python +connection = IPConnection("10.0.0.5", 4000, terminator="\r\n", timeout=5.0) + +await connection.write("R=5") # sends "R=5\r\n" +reply = await connection.query("R?") # sends "R?\r\n", returns the reply without "\r\n" +``` + +For binary protocols, `write_bytes` and `query_bytes` send raw bytes without a +terminator. If an exchange fails or takes longer than `timeout`, the link is closed and +later calls raise `DisconnectedError`. diff --git a/pyproject.toml b/pyproject.toml index d668f37f9..ea1b20ec6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,7 +17,6 @@ classifiers = [ ] description = "Control system agnostic framework for building Device support in Python that will work for both EPICS and Tango" dependencies = [ - "aioserial", "fastapi[standard]", "numpy", "pydantic", @@ -35,13 +34,20 @@ requires-python = ">=3.11" [project.optional-dependencies] demo = ["tickit~=0.4.3"] +serial = ["aioserial"] epicsca = ["pvi~=0.14.4", "softioc>=4.7.1"] epicspva = ["p4p", "pvi~=0.14.4"] epics = ["fastcs[epicsca]", "fastcs[epicspva]"] tango = ["pytango"] graphql = ["strawberry-graphql", "uvicorn[standard]>=0.12.0"] rest = ["fastapi[standard]", "numpy", "uvicorn[standard]>=0.12.0"] -all = ["fastcs[epics]", "fastcs[tango]", "fastcs[graphql]", "fastcs[rest]"] +all = [ + "fastcs[epics]", + "fastcs[tango]", + "fastcs[graphql]", + "fastcs[rest]", + "fastcs[serial]", +] [dependency-groups] dev = [ diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index e6d584c6f..950fe87cc 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -1,4 +1,8 @@ from .connection import Connection as Connection from .connection import DisconnectedError as DisconnectedError from .ip_connection import IPConnection as IPConnection -from .serial_connection import SerialConnection as SerialConnection + +try: + from .serial_connection import SerialConnection as SerialConnection +except ImportError: + pass diff --git a/src/fastcs/connections/serial_connection.py b/src/fastcs/connections/serial_connection.py index e719d1495..f60cfb799 100644 --- a/src/fastcs/connections/serial_connection.py +++ b/src/fastcs/connections/serial_connection.py @@ -1,59 +1,132 @@ import asyncio +from collections.abc import AsyncGenerator +from contextlib import asynccontextmanager import aioserial -from fastcs.connections.connection import Connection, IntrospectionT +from fastcs.connections.connection import Connection, DisconnectedError, IntrospectionT +from fastcs.tracer import Tracer -class NotOpenedError(Exception): - """If the serial stream is not opened.""" +class SerialConnection(Connection[IntrospectionT], Tracer): + """A serial link to a device that exchanges terminated messages. - pass + Example:: - -class SerialConnection(Connection[IntrospectionT]): - """A serial connection. + connection = SerialConnection("/dev/ttyUSB0", baud=9600) + await connection.write("R=5") + reply = await connection.query("R?") Args: port: The serial port to open baud: The baud rate + terminator: Added to the end of each message, and marks the end of each reply + encoding: The text encoding of messages and replies + timeout: Seconds to wait for each operation before closing the link """ - def __init__(self, port: str, baud: int = 115200): + def __init__( + self, + port: str, + baud: int = 115200, + terminator: str = "\r\n", + encoding: str = "utf-8", + timeout: float = 5.0, + ): + super().__init__() self.port = port self.baud = baud - self.__stream = None + self.terminator = terminator + self.encoding = encoding + self.timeout = timeout + self._stream: aioserial.AioSerial | None = None self._lock = asyncio.Lock() async def connect(self) -> None: - self.__stream = aioserial.AioSerial(port=self.port, baudrate=self.baud) + self._stream = aioserial.AioSerial(port=self.port, baudrate=self.baud) - @property - def _stream(self) -> aioserial.AioSerial: - if self.__stream is None: - raise NotOpenedError( - "Need to call connect() before using SerialConnection." - ) + async def write(self, message: str) -> None: + """Send a message, adding the terminator. - return self.__stream + Raises: + DisconnectedError: If the link isn't open + TimeoutError: If sending takes longer than ``timeout`` - async def send_command(self, message: bytes) -> None: - async with self._lock: - await self._send_message(message) + """ + data = f"{message}{self.terminator}".encode(self.encoding) + async with self._exchange() as stream: + await stream.write_async(data) - async def send_query(self, message: bytes, response_size: int) -> bytes: - async with self._lock: - await self._send_message(message) - return await self._receive_response(response_size) + async def query(self, message: str) -> str: + """Send a message and read the reply. + + Returns: + The reply, without its terminator + + Raises: + DisconnectedError: If the link isn't open + TimeoutError: If the reply takes longer than ``timeout`` + + """ + data = f"{message}{self.terminator}".encode(self.encoding) + terminator = self.terminator.encode(self.encoding) + async with self._exchange() as stream: + await stream.write_async(data) + reply = await stream.read_until_async(terminator) + + response = reply.removesuffix(terminator).decode(self.encoding) + self.log_event("Received query response", query=message, response=response) + return response + + async def write_bytes(self, data: bytes) -> None: + """Send raw bytes, without a terminator. - async def _send_message(self, message): - await self._stream.write_async(message) + Raises: + DisconnectedError: If the link isn't open + TimeoutError: If sending takes longer than ``timeout`` - async def _receive_response(self, size): - return await self._stream.read_async(size) + """ + async with self._exchange() as stream: + await stream.write_async(data) + + async def query_bytes(self, data: bytes, size: int) -> bytes: + """Send raw bytes and read a reply of a fixed size. + + Returns: + The reply, exactly ``size`` bytes long + + Raises: + DisconnectedError: If the link isn't open + TimeoutError: If the reply takes longer than ``timeout`` + + """ + async with self._exchange() as stream: + await stream.write_async(data) + return await stream.read_async(size) async def close(self) -> None: async with self._lock: - self._stream.close() - self.__stream = None + if self._stream is None: + return + + stream = self._stream + self._stream = None + stream.close() + + @asynccontextmanager + async def _exchange(self) -> AsyncGenerator[aioserial.AioSerial, None]: + """Hold the lock for one exchange, closing the link if it fails part way""" + async with self._lock: + if self._stream is None: + raise DisconnectedError(f"{self.port} is not connected") + + stream = self._stream + try: + async with asyncio.timeout(self.timeout): + yield stream + except BaseException: + # A late reply could be left in the stream and read by the next query + self._stream = None + stream.close() + raise diff --git a/tests/test_serial_connection.py b/tests/test_serial_connection.py new file mode 100644 index 000000000..7cfbec0e4 --- /dev/null +++ b/tests/test_serial_connection.py @@ -0,0 +1,47 @@ +import os +import threading + +import pytest +import pytest_asyncio + +from fastcs.connections import DisconnectedError, SerialConnection + + +def _reply_to_r(device: int): + buffer = b"" + while True: + try: + buffer += os.read(device, 1024) + except OSError: + return + + while b"\r\n" in buffer: + line, buffer = buffer.split(b"\r\n", 1) + if line == b"R?": + os.write(device, b"5\r\n") + + +@pytest_asyncio.fixture +async def connection(): + device, port = os.openpty() + threading.Thread(target=_reply_to_r, args=(device,), daemon=True).start() + connection = SerialConnection(os.ttyname(port), timeout=0.1) + await connection.connect() + yield connection + await connection.close() + os.close(port) + os.close(device) + + +@pytest.mark.asyncio +async def test_query_adds_and_strips_terminator(connection: SerialConnection): + assert await connection.query("R?") == "5" + + +@pytest.mark.asyncio +async def test_timeout_closes_connection(connection: SerialConnection): + with pytest.raises(TimeoutError): + await connection.query("NO_REPLY?") + + with pytest.raises(DisconnectedError): + await connection.write("R=5") diff --git a/uv.lock b/uv.lock index 115e5603b..0992e8e08 100644 --- a/uv.lock +++ b/uv.lock @@ -906,7 +906,6 @@ wheels = [ name = "fastcs" source = { editable = "." } dependencies = [ - { name = "aioserial" }, { name = "fastapi", extra = ["standard"] }, { name = "ipython" }, { name = "loguru" }, @@ -920,6 +919,7 @@ dependencies = [ [package.optional-dependencies] all = [ + { name = "aioserial" }, { name = "fastapi", extra = ["standard"] }, { name = "numpy" }, { name = "p4p" }, @@ -954,6 +954,9 @@ rest = [ { name = "numpy" }, { name = "uvicorn", extra = ["standard"] }, ] +serial = [ + { name = "aioserial" }, +] tango = [ { name = "pytango" }, ] @@ -989,7 +992,7 @@ dev = [ [package.metadata] requires-dist = [ - { name = "aioserial" }, + { name = "aioserial", marker = "extra == 'serial'" }, { name = "fastapi", extras = ["standard"] }, { name = "fastapi", extras = ["standard"], marker = "extra == 'rest'" }, { name = "fastcs", extras = ["epics"], marker = "extra == 'all'" }, @@ -997,6 +1000,7 @@ requires-dist = [ { name = "fastcs", extras = ["epicspva"], marker = "extra == 'epics'" }, { name = "fastcs", extras = ["graphql"], marker = "extra == 'all'" }, { name = "fastcs", extras = ["rest"], marker = "extra == 'all'" }, + { name = "fastcs", extras = ["serial"], marker = "extra == 'all'" }, { name = "fastcs", extras = ["tango"], marker = "extra == 'all'" }, { name = "ipython" }, { name = "loguru", specifier = "~=0.7" }, @@ -1017,7 +1021,7 @@ requires-dist = [ { name = "uvicorn", extras = ["standard"], marker = "extra == 'graphql'", specifier = ">=0.12.0" }, { name = "uvicorn", extras = ["standard"], marker = "extra == 'rest'", specifier = ">=0.12.0" }, ] -provides-extras = ["demo", "epicsca", "epicspva", "epics", "tango", "graphql", "rest", "all"] +provides-extras = ["demo", "serial", "epicsca", "epicspva", "epics", "tango", "graphql", "rest", "all"] [package.metadata.requires-dev] dev = [ From 4035f41c27353b89e682cae3a99d9959dbb39ede Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 14:20:23 +0000 Subject: [PATCH 04/16] fastcs[http] builtin HTTP connection --- docs/explanations/connections.md | 19 ++- pyproject.toml | 2 + src/fastcs/connections/__init__.py | 5 + src/fastcs/connections/http_connection.py | 178 ++++++++++++++++++++++ tests/test_http_connection.py | 64 ++++++++ uv.lock | 8 +- 6 files changed, 274 insertions(+), 2 deletions(-) create mode 100644 src/fastcs/connections/http_connection.py create mode 100644 tests/test_http_connection.py diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index a7c8f766f..be8ee0562 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -10,8 +10,10 @@ the application stops. |---|---|---| | `IPConnection` | TCP | included | | `SerialConnection` | Serial port | `pip install "fastcs[serial]"` | +| `HTTPConnection` | HTTP | `pip install "fastcs[http]"` | -Both exchange text messages that end with a terminator, `\r\n` by default: +`IPConnection` and `SerialConnection` exchange text messages that end with a +terminator, `\r\n` by default: ```python connection = IPConnection("10.0.0.5", 4000, terminator="\r\n", timeout=5.0) @@ -23,3 +25,18 @@ reply = await connection.query("R?") # sends "R?\r\n", returns the reply withou For binary protocols, `write_bytes` and `query_bytes` send raw bytes without a terminator. If an exchange fails or takes longer than `timeout`, the link is closed and later calls raise `DisconnectedError`. + +`HTTPConnection` talks to a device with a JSON API. `get`, `put`, `post` and `delete` +take a path relative to its `url`, send JSON, and return the parsed reply. An error +status raises `httpx.HTTPStatusError`. For replies that aren't JSON, `request` returns +the raw response: + +```python +connection = HTTPConnection("http://10.0.0.5:8000/api", timeout=5.0) + +await connection.put("/rate", json=5) +rate = await connection.get("/rate") +``` + +Like the other connections, it raises `TimeoutError` when the device doesn't answer in +time. It raises `ConnectionError` when the server can't be reached. diff --git a/pyproject.toml b/pyproject.toml index ea1b20ec6..80c1f36fa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,6 +35,7 @@ requires-python = ">=3.11" [project.optional-dependencies] demo = ["tickit~=0.4.3"] serial = ["aioserial"] +http = ["httpx"] epicsca = ["pvi~=0.14.4", "softioc>=4.7.1"] epicspva = ["p4p", "pvi~=0.14.4"] epics = ["fastcs[epicsca]", "fastcs[epicspva]"] @@ -47,6 +48,7 @@ all = [ "fastcs[graphql]", "fastcs[rest]", "fastcs[serial]", + "fastcs[http]", ] [dependency-groups] diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 950fe87cc..98baf902a 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -2,6 +2,11 @@ from .connection import DisconnectedError as DisconnectedError from .ip_connection import IPConnection as IPConnection +try: + from .http_connection import HTTPConnection as HTTPConnection +except ImportError: + pass + try: from .serial_connection import SerialConnection as SerialConnection except ImportError: diff --git a/src/fastcs/connections/http_connection.py b/src/fastcs/connections/http_connection.py new file mode 100644 index 000000000..75e258634 --- /dev/null +++ b/src/fastcs/connections/http_connection.py @@ -0,0 +1,178 @@ +from collections.abc import Generator +from contextlib import contextmanager +from typing import Any + +import httpx + +from fastcs.connections.connection import Connection, DisconnectedError, IntrospectionT +from fastcs.tracer import Tracer + + +class HTTPConnection(Connection[IntrospectionT], Tracer): + """An HTTP link to a device with a JSON API. + + Example:: + + connection = HTTPConnection("http://10.0.0.5:8000/api") + await connection.put("/rate", json=5) + rate = await connection.get("/rate") + + Args: + url: The base URL that request paths are relative to + timeout: Seconds to wait to connect, or for a response + headers: Headers to send with every request + + """ + + def __init__( + self, + url: str = "http://127.0.0.1:8080", + timeout: float = 5.0, + headers: dict[str, str] | None = None, + ): + super().__init__() + self.url = url + self.timeout = timeout + self.headers = headers or {} + self._client: httpx.AsyncClient | None = None + + async def connect(self) -> None: + """Create the client and check the server answers. + + Raises: + ConnectionError: If the server can't be reached + TimeoutError: If the server doesn't answer within ``timeout`` + + """ + client = httpx.AsyncClient( + base_url=self.url, timeout=self.timeout, headers=self.headers + ) + try: + # Any response, even an error status, shows the server is reachable + with _link_errors(f"GET {self.url}"): + await client.get("") + except BaseException: + await client.aclose() + raise + + self._client = client + + async def get(self, path: str, params: dict[str, Any] | None = None) -> Any: + """Send a GET request. + + Returns: + The parsed JSON reply, or ``None`` if the reply is empty + + Raises: + DisconnectedError: If the link isn't open + ConnectionError: If the server can't be reached + TimeoutError: If the reply takes longer than ``timeout`` + httpx.HTTPStatusError: If the reply has an error status + + """ + return _json(await self._send("GET", path, params=params)) + + async def put(self, path: str, json: Any = None) -> Any: + """Send a PUT request with a JSON body. + + Returns: + The parsed JSON reply, or ``None`` if the reply is empty + + Raises: + DisconnectedError: If the link isn't open + ConnectionError: If the server can't be reached + TimeoutError: If the reply takes longer than ``timeout`` + httpx.HTTPStatusError: If the reply has an error status + + """ + return _json(await self._send("PUT", path, json=json)) + + async def post(self, path: str, json: Any = None) -> Any: + """Send a POST request with a JSON body. + + Returns: + The parsed JSON reply, or ``None`` if the reply is empty + + Raises: + DisconnectedError: If the link isn't open + ConnectionError: If the server can't be reached + TimeoutError: If the reply takes longer than ``timeout`` + httpx.HTTPStatusError: If the reply has an error status + + """ + return _json(await self._send("POST", path, json=json)) + + async def delete(self, path: str) -> Any: + """Send a DELETE request. + + Returns: + The parsed JSON reply, or ``None`` if the reply is empty + + Raises: + DisconnectedError: If the link isn't open + ConnectionError: If the server can't be reached + TimeoutError: If the reply takes longer than ``timeout`` + httpx.HTTPStatusError: If the reply has an error status + + """ + return _json(await self._send("DELETE", path)) + + async def request(self, method: str, path: str, **kwargs: Any) -> httpx.Response: + """Send any request, for replies that aren't JSON. + + Example:: + + response = await connection.request("GET", "/image", params={"n": 1}) + image = response.content + + Args: + method: The HTTP method + path: The path, relative to ``url`` + kwargs: Passed to `httpx.AsyncClient.request` + + Returns: + The response, whatever its status + + Raises: + DisconnectedError: If the link isn't open + ConnectionError: If the server can't be reached + TimeoutError: If the reply takes longer than ``timeout`` + + """ + return await self._send(method, path, **kwargs) + + async def close(self) -> None: + if self._client is None: + return + + client = self._client + self._client = None + await client.aclose() + + async def _send(self, method: str, path: str, **kwargs: Any) -> httpx.Response: + if self._client is None: + raise DisconnectedError(f"{self.url} is not connected") + + with _link_errors(f"{method} {self.url}{path}"): + response = await self._client.request(method, path, **kwargs) + + self.log_event( + "Received response", method=method, path=path, status=response.status_code + ) + return response + + +@contextmanager +def _link_errors(request: str) -> Generator[None, None, None]: + """Raise httpx's link errors as the built-in types the other connections raise""" + try: + yield + except httpx.TimeoutException as e: + raise TimeoutError(f"{request} timed out") from e + except httpx.TransportError as e: + raise ConnectionError(f"{request} failed: {e}") from e + + +def _json(response: httpx.Response) -> Any: + response.raise_for_status() + return response.json() if response.content else None diff --git a/tests/test_http_connection.py b/tests/test_http_connection.py new file mode 100644 index 000000000..e3f3791b9 --- /dev/null +++ b/tests/test_http_connection.py @@ -0,0 +1,64 @@ +import json +import socket +import threading +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer + +import pytest +import pytest_asyncio + +from fastcs.connections import HTTPConnection + + +class _RateDevice(BaseHTTPRequestHandler): + rate = 0 + + def do_GET(self): + if self.path != "/rate": + self.send_error(404) + return + + self._reply(type(self).rate) + + def do_PUT(self): + body = self.rfile.read(int(self.headers["Content-Length"])) + type(self).rate = json.loads(body) + self._reply(None) + + def _reply(self, value): + body = b"" if value is None else json.dumps(value).encode() + self.send_response(200) + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def log_message(self, format, *args): + pass + + +@pytest_asyncio.fixture +async def connection(): + server = ThreadingHTTPServer(("127.0.0.1", 0), _RateDevice) + threading.Thread(target=server.serve_forever, daemon=True).start() + # The probe in connect() gets a 404 for "/", which still counts as reachable + connection = HTTPConnection(f"http://127.0.0.1:{server.server_port}", timeout=1) + await connection.connect() + yield connection + await connection.close() + server.shutdown() + server.server_close() + + +@pytest.mark.asyncio +async def test_put_then_get_json(connection: HTTPConnection): + await connection.put("/rate", json=5) + assert await connection.get("/rate") == 5 + + +@pytest.mark.asyncio +async def test_connect_to_closed_port_raises_connection_error(): + with socket.socket() as unused: + unused.bind(("127.0.0.1", 0)) + port = unused.getsockname()[1] + + with pytest.raises(ConnectionError): + await HTTPConnection(f"http://127.0.0.1:{port}").connect() diff --git a/uv.lock b/uv.lock index 0992e8e08..d48d49418 100644 --- a/uv.lock +++ b/uv.lock @@ -921,6 +921,7 @@ dependencies = [ all = [ { name = "aioserial" }, { name = "fastapi", extra = ["standard"] }, + { name = "httpx" }, { name = "numpy" }, { name = "p4p" }, { name = "pvi" }, @@ -949,6 +950,9 @@ graphql = [ { name = "strawberry-graphql" }, { name = "uvicorn", extra = ["standard"] }, ] +http = [ + { name = "httpx" }, +] rest = [ { name = "fastapi", extra = ["standard"] }, { name = "numpy" }, @@ -999,9 +1003,11 @@ requires-dist = [ { name = "fastcs", extras = ["epicsca"], marker = "extra == 'epics'" }, { name = "fastcs", extras = ["epicspva"], marker = "extra == 'epics'" }, { name = "fastcs", extras = ["graphql"], marker = "extra == 'all'" }, + { name = "fastcs", extras = ["http"], marker = "extra == 'all'" }, { name = "fastcs", extras = ["rest"], marker = "extra == 'all'" }, { name = "fastcs", extras = ["serial"], marker = "extra == 'all'" }, { name = "fastcs", extras = ["tango"], marker = "extra == 'all'" }, + { name = "httpx", marker = "extra == 'http'" }, { name = "ipython" }, { name = "loguru", specifier = "~=0.7" }, { name = "numpy" }, @@ -1021,7 +1027,7 @@ requires-dist = [ { name = "uvicorn", extras = ["standard"], marker = "extra == 'graphql'", specifier = ">=0.12.0" }, { name = "uvicorn", extras = ["standard"], marker = "extra == 'rest'", specifier = ">=0.12.0" }, ] -provides-extras = ["demo", "serial", "epicsca", "epicspva", "epics", "tango", "graphql", "rest", "all"] +provides-extras = ["demo", "serial", "http", "epicsca", "epicspva", "epics", "tango", "graphql", "rest", "all"] [package.metadata.requires-dev] dev = [ From 34646f9cbfc74aa5cc035559c332d21df1d0749b Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 14:43:41 +0000 Subject: [PATCH 05/16] add tests to broaden scope and achieve target patch coverage --- tests/test_http_connection.py | 35 ++++++++++++++++++++++++++++++++- tests/test_ip_connection.py | 7 +++++++ tests/test_serial_connection.py | 7 +++++++ 3 files changed, 48 insertions(+), 1 deletion(-) diff --git a/tests/test_http_connection.py b/tests/test_http_connection.py index e3f3791b9..d5ffb5d93 100644 --- a/tests/test_http_connection.py +++ b/tests/test_http_connection.py @@ -6,7 +6,7 @@ import pytest import pytest_asyncio -from fastcs.connections import HTTPConnection +from fastcs.connections import DisconnectedError, HTTPConnection class _RateDevice(BaseHTTPRequestHandler): @@ -24,6 +24,13 @@ def do_PUT(self): type(self).rate = json.loads(body) self._reply(None) + def do_POST(self): + self.do_PUT() + + def do_DELETE(self): + type(self).rate = 0 + self._reply(None) + def _reply(self, value): body = b"" if value is None else json.dumps(value).encode() self.send_response(200) @@ -37,6 +44,7 @@ def log_message(self, format, *args): @pytest_asyncio.fixture async def connection(): + _RateDevice.rate = 0 server = ThreadingHTTPServer(("127.0.0.1", 0), _RateDevice) threading.Thread(target=server.serve_forever, daemon=True).start() # The probe in connect() gets a 404 for "/", which still counts as reachable @@ -62,3 +70,28 @@ async def test_connect_to_closed_port_raises_connection_error(): with pytest.raises(ConnectionError): await HTTPConnection(f"http://127.0.0.1:{port}").connect() + + +@pytest.mark.asyncio +async def test_post_delete_and_request(connection: HTTPConnection): + await connection.post("/rate", json=7) + assert (await connection.request("GET", "/rate")).json() == 7 + + await connection.delete("/rate") + assert await connection.get("/rate") == 0 + + +@pytest.mark.asyncio +async def test_unanswered_and_unconnected_requests_raise(): + with socket.socket() as silent: + silent.bind(("127.0.0.1", 0)) + silent.listen() + connection = HTTPConnection( + f"http://127.0.0.1:{silent.getsockname()[1]}", timeout=0.1 + ) + with pytest.raises(TimeoutError): + await connection.connect() + + await connection.close() + with pytest.raises(DisconnectedError): + await connection.get("/rate") diff --git a/tests/test_ip_connection.py b/tests/test_ip_connection.py index 744171004..67dd1cb86 100644 --- a/tests/test_ip_connection.py +++ b/tests/test_ip_connection.py @@ -36,3 +36,10 @@ async def test_timeout_closes_connection(connection: IPConnection): with pytest.raises(DisconnectedError): await connection.write("R=5") + + +@pytest.mark.asyncio +async def test_write_and_bytes_methods(connection: IPConnection): + await connection.write("R=5") + await connection.write_bytes(b"R=6\r\n") + assert await connection.query_bytes(b"R?\r\n", 3) == b"5\r\n" diff --git a/tests/test_serial_connection.py b/tests/test_serial_connection.py index 7cfbec0e4..32ae3ccc4 100644 --- a/tests/test_serial_connection.py +++ b/tests/test_serial_connection.py @@ -45,3 +45,10 @@ async def test_timeout_closes_connection(connection: SerialConnection): with pytest.raises(DisconnectedError): await connection.write("R=5") + + +@pytest.mark.asyncio +async def test_write_and_bytes_methods(connection: SerialConnection): + await connection.write("R=5") + await connection.write_bytes(b"R=6\r\n") + assert await connection.query_bytes(b"R?\r\n", 3) == b"5\r\n" From c2a79aaf562ac7744b5cc193e6ee2e5453e0863b Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Wed, 11 Nov 2026 16:14:04 +0000 Subject: [PATCH 06/16] ignore httpx references in the docs build, as httpx has no intersphinx inventory Co-Authored-By: Claude Opus 5.5 --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 4c36118d1..84c699e23 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -110,6 +110,9 @@ ("py:obj", r"fastcs.*.DType_T"), (r"py:.*", r"fastcs\.demo.*"), (r"py:.*", r"tickit.*"), + # httpx doesn't have intersphinx mapping + (r"py:.*", r"httpx\..*"), + ("any", r"httpx\..*"), ("py:class", r"numpy.*"), ] From 63f31de5db277fc49f7fb29e3c50787128f895c3 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 11:39:45 +0000 Subject: [PATCH 07/16] add optional_dependency context helper, apply to connections --- src/fastcs/connections/__init__.py | 10 ++++------ src/fastcs/util.py | 25 +++++++++++++++++++++++++ tests/test_util.py | 15 ++++++++++++++- 3 files changed, 43 insertions(+), 7 deletions(-) diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 98baf902a..64a902171 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -1,13 +1,11 @@ +from fastcs.util import optional_dependency + from .connection import Connection as Connection from .connection import DisconnectedError as DisconnectedError from .ip_connection import IPConnection as IPConnection -try: +with optional_dependency("httpx"): from .http_connection import HTTPConnection as HTTPConnection -except ImportError: - pass -try: +with optional_dependency("aioserial"): from .serial_connection import SerialConnection as SerialConnection -except ImportError: - pass diff --git a/src/fastcs/util.py b/src/fastcs/util.py index 4044585e9..26cddf32f 100644 --- a/src/fastcs/util.py +++ b/src/fastcs/util.py @@ -1,4 +1,6 @@ import re +from collections.abc import Iterator +from contextlib import contextmanager from typing import TYPE_CHECKING, TypeVar if TYPE_CHECKING: @@ -18,3 +20,26 @@ def snake_to_pascal(name: str) -> str: if re.fullmatch(r"[a-z][a-z0-9]*(?:_[a-z0-9]+)*", name): name = re.sub(r"(?:^|_)([a-z0-9])", lambda match: match.group(1).upper(), name) return name + + +@contextmanager +def optional_dependency(*names: str) -> Iterator[None]: + """Skip the imports in the block if one of the given packages isn't installed. + + Example:: + + with optional_dependency("httpx"): + from .http_connection import HTTPConnection as HTTPConnection + + Args: + names: The packages that the block may be missing + + Raises: + ModuleNotFoundError: If a module other than the given packages is missing + + """ + try: + yield + except ModuleNotFoundError as e: + if e.name is None or e.name.split(".")[0] not in names: + raise diff --git a/tests/test_util.py b/tests/test_util.py index 5475af74a..40cf2ddc9 100644 --- a/tests/test_util.py +++ b/tests/test_util.py @@ -1,4 +1,6 @@ -from fastcs.util import snake_to_pascal +import pytest + +from fastcs.util import optional_dependency, snake_to_pascal def test_snake_to_pascal(): @@ -26,3 +28,14 @@ def test_snake_to_pascal(): assert snake_to_pascal(name10) == "Name_With_%_Invalid_&_Symbols_£_" assert snake_to_pascal(name11) == "ABCD" assert snake_to_pascal(name12) == "Test" + + +def test_optional_dependency_skips_listed_missing_package(): + with optional_dependency("missing_package"): + import missing_package.submodule # noqa: F401 + + +def test_optional_dependency_raises_for_other_missing_module(): + with pytest.raises(ModuleNotFoundError, match="other_missing_package"): + with optional_dependency("missing_package"): + import other_missing_package # noqa: F401 From 3611d2cbb27dcddd5eed83387d09dcb3a17665de Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 11:45:27 +0000 Subject: [PATCH 08/16] expand asyncio timeouts to http connection and add test --- src/fastcs/connections/http_connection.py | 7 +++++-- tests/test_http_connection.py | 24 +++++++++++++++++++++++ 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/src/fastcs/connections/http_connection.py b/src/fastcs/connections/http_connection.py index 75e258634..8ca5fb2d6 100644 --- a/src/fastcs/connections/http_connection.py +++ b/src/fastcs/connections/http_connection.py @@ -1,3 +1,4 @@ +import asyncio from collections.abc import Generator from contextlib import contextmanager from typing import Any @@ -50,7 +51,8 @@ async def connect(self) -> None: try: # Any response, even an error status, shows the server is reachable with _link_errors(f"GET {self.url}"): - await client.get("") + async with asyncio.timeout(self.timeout): + await client.get("") except BaseException: await client.aclose() raise @@ -154,7 +156,8 @@ async def _send(self, method: str, path: str, **kwargs: Any) -> httpx.Response: raise DisconnectedError(f"{self.url} is not connected") with _link_errors(f"{method} {self.url}{path}"): - response = await self._client.request(method, path, **kwargs) + async with asyncio.timeout(self.timeout): + response = await self._client.request(method, path, **kwargs) self.log_event( "Received response", method=method, path=path, status=response.status_code diff --git a/tests/test_http_connection.py b/tests/test_http_connection.py index d5ffb5d93..6f776ae1e 100644 --- a/tests/test_http_connection.py +++ b/tests/test_http_connection.py @@ -1,3 +1,4 @@ +import asyncio import json import socket import threading @@ -95,3 +96,26 @@ async def test_unanswered_and_unconnected_requests_raise(): await connection.close() with pytest.raises(DisconnectedError): await connection.get("/rate") + + +@pytest.mark.asyncio +async def test_slowly_dripped_reply_times_out(): + async def drip(reader: asyncio.StreamReader, writer: asyncio.StreamWriter): + await reader.readuntil(b"\r\n\r\n") + writer.write(b"HTTP/1.1 200 OK\r\n") + while True: + writer.write(b"X") + await writer.drain() + await asyncio.sleep(0.02) + + server = await asyncio.start_server(drip, "127.0.0.1", 0) + port = server.sockets[0].getsockname()[1] + connection = HTTPConnection(f"http://127.0.0.1:{port}", timeout=0.2) + + # Guard with asyncio.wait, which doesn't raise TimeoutError itself + task = asyncio.create_task(connection.connect()) + await asyncio.wait([task], timeout=2) + server.close() + + assert task.done() + assert isinstance(task.exception(), TimeoutError) From 266a9591037c8850b2716691d0a39e198112d7d2 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 11:59:45 +0000 Subject: [PATCH 09/16] add limits to IP and serial connections --- src/fastcs/connections/ip_connection.py | 15 +++++++++++++-- src/fastcs/connections/serial_connection.py | 10 +++++++++- tests/test_ip_connection.py | 19 ++++++++++++++++++- tests/test_serial_connection.py | 18 ++++++++++++++++++ 4 files changed, 58 insertions(+), 4 deletions(-) diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index 135c82a2f..7b9e4dba2 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -21,6 +21,7 @@ class IPConnection(Connection[IntrospectionT], Tracer): terminator: Added to the end of each message, and marks the end of each reply encoding: The text encoding of messages and replies timeout: Seconds to wait for each operation before closing the link + limit: Most bytes a reply can have, not counting its terminator """ @@ -31,6 +32,7 @@ def __init__( terminator: str = "\r\n", encoding: str = "utf-8", timeout: float = 5.0, + limit: int = 2**16, ): super().__init__() self.ip = ip @@ -38,12 +40,15 @@ def __init__( self.terminator = terminator self.encoding = encoding self.timeout = timeout + self.limit = limit self._streams: tuple[asyncio.StreamReader, asyncio.StreamWriter] | None = None self._lock = asyncio.Lock() async def connect(self) -> None: async with asyncio.timeout(self.timeout): - self._streams = await asyncio.open_connection(self.ip, self.port) + self._streams = await asyncio.open_connection( + self.ip, self.port, limit=self.limit + ) async def write(self, message: str) -> None: """Send a message, adding the terminator. @@ -67,6 +72,7 @@ async def query(self, message: str) -> str: Raises: DisconnectedError: If the link isn't open TimeoutError: If the reply takes longer than ``timeout`` + ValueError: If the reply is longer than ``limit`` """ data = f"{message}{self.terminator}".encode(self.encoding) @@ -74,7 +80,12 @@ async def query(self, message: str) -> str: async with self._exchange() as (reader, writer): writer.write(data) await writer.drain() - reply = await reader.readuntil(terminator) + try: + reply = await reader.readuntil(terminator) + except asyncio.LimitOverrunError as e: + raise ValueError( + f"{self.ip}:{self.port} reply is longer than {self.limit} bytes" + ) from e response = reply.removesuffix(terminator).decode(self.encoding) self.log_event("Received query response", query=message, response=response) diff --git a/src/fastcs/connections/serial_connection.py b/src/fastcs/connections/serial_connection.py index f60cfb799..119ab43b1 100644 --- a/src/fastcs/connections/serial_connection.py +++ b/src/fastcs/connections/serial_connection.py @@ -23,6 +23,7 @@ class SerialConnection(Connection[IntrospectionT], Tracer): terminator: Added to the end of each message, and marks the end of each reply encoding: The text encoding of messages and replies timeout: Seconds to wait for each operation before closing the link + limit: Most bytes a reply can have, not counting its terminator """ @@ -33,6 +34,7 @@ def __init__( terminator: str = "\r\n", encoding: str = "utf-8", timeout: float = 5.0, + limit: int = 2**16, ): super().__init__() self.port = port @@ -40,6 +42,7 @@ def __init__( self.terminator = terminator self.encoding = encoding self.timeout = timeout + self.limit = limit self._stream: aioserial.AioSerial | None = None self._lock = asyncio.Lock() @@ -67,13 +70,18 @@ async def query(self, message: str) -> str: Raises: DisconnectedError: If the link isn't open TimeoutError: If the reply takes longer than ``timeout`` + ValueError: If the reply is longer than ``limit`` """ data = f"{message}{self.terminator}".encode(self.encoding) terminator = self.terminator.encode(self.encoding) async with self._exchange() as stream: await stream.write_async(data) - reply = await stream.read_until_async(terminator) + reply = await stream.read_until_async( + terminator, size=self.limit + len(terminator) + ) + if not reply.endswith(terminator): + raise ValueError(f"{self.port} reply is longer than {self.limit} bytes") response = reply.removesuffix(terminator).decode(self.encoding) self.log_event("Received query response", query=message, response=response) diff --git a/tests/test_ip_connection.py b/tests/test_ip_connection.py index 67dd1cb86..b8e000d36 100644 --- a/tests/test_ip_connection.py +++ b/tests/test_ip_connection.py @@ -10,7 +10,9 @@ async def _reply_to_r(reader: asyncio.StreamReader, writer: asyncio.StreamWriter while line := await reader.readuntil(b"\r\n"): if line == b"R?\r\n": writer.write(b"5\r\n") - await writer.drain() + elif line == b"LONG?\r\n": + writer.write(b"12345\r\n") + await writer.drain() @pytest_asyncio.fixture @@ -43,3 +45,18 @@ async def test_write_and_bytes_methods(connection: IPConnection): await connection.write("R=5") await connection.write_bytes(b"R=6\r\n") assert await connection.query_bytes(b"R?\r\n", 3) == b"5\r\n" + + +@pytest.mark.asyncio +async def test_reply_longer_than_limit_raises_and_closes_connection(): + server = await asyncio.start_server(_reply_to_r, "127.0.0.1", 0) + port = server.sockets[0].getsockname()[1] + connection = IPConnection("127.0.0.1", port, timeout=0.1, limit=4) + await connection.connect() + + with pytest.raises(ValueError, match="longer than 4 bytes"): + await connection.query("LONG?") + with pytest.raises(DisconnectedError): + await connection.write("R=5") + + server.close() diff --git a/tests/test_serial_connection.py b/tests/test_serial_connection.py index 32ae3ccc4..42319f717 100644 --- a/tests/test_serial_connection.py +++ b/tests/test_serial_connection.py @@ -19,6 +19,8 @@ def _reply_to_r(device: int): line, buffer = buffer.split(b"\r\n", 1) if line == b"R?": os.write(device, b"5\r\n") + elif line == b"LONG?": + os.write(device, b"12345\r\n") @pytest_asyncio.fixture @@ -52,3 +54,19 @@ async def test_write_and_bytes_methods(connection: SerialConnection): await connection.write("R=5") await connection.write_bytes(b"R=6\r\n") assert await connection.query_bytes(b"R?\r\n", 3) == b"5\r\n" + + +@pytest.mark.asyncio +async def test_reply_longer_than_limit_raises_and_closes_connection(): + device, port = os.openpty() + threading.Thread(target=_reply_to_r, args=(device,), daemon=True).start() + connection = SerialConnection(os.ttyname(port), timeout=0.1, limit=4) + await connection.connect() + + with pytest.raises(ValueError, match="longer than 4 bytes"): + await connection.query("LONG?") + with pytest.raises(DisconnectedError): + await connection.write("R=5") + + os.close(port) + os.close(device) From e2f1ae13e0e58acae841d13811953aca225a245e Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 12:51:56 +0000 Subject: [PATCH 10/16] use Generator type to remove warning --- src/fastcs/util.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/fastcs/util.py b/src/fastcs/util.py index 26cddf32f..fee179c93 100644 --- a/src/fastcs/util.py +++ b/src/fastcs/util.py @@ -1,5 +1,5 @@ import re -from collections.abc import Iterator +from collections.abc import Generator from contextlib import contextmanager from typing import TYPE_CHECKING, TypeVar @@ -23,7 +23,7 @@ def snake_to_pascal(name: str) -> str: @contextmanager -def optional_dependency(*names: str) -> Iterator[None]: +def optional_dependency(*names: str) -> Generator[None, None, None]: """Skip the imports in the block if one of the given packages isn't installed. Example:: From caf6356a03f5a4efcf284dd617031b9486da2870 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Thu, 12 Nov 2026 13:24:11 +0000 Subject: [PATCH 11/16] natch ip and serial by making http close its own link after a link failure --- src/fastcs/connections/http_connection.py | 18 +++++++++++----- tests/test_http_connection.py | 26 +++++++++++++++++++---- 2 files changed, 35 insertions(+), 9 deletions(-) diff --git a/src/fastcs/connections/http_connection.py b/src/fastcs/connections/http_connection.py index 8ca5fb2d6..14abcd40e 100644 --- a/src/fastcs/connections/http_connection.py +++ b/src/fastcs/connections/http_connection.py @@ -20,7 +20,7 @@ class HTTPConnection(Connection[IntrospectionT], Tracer): Args: url: The base URL that request paths are relative to - timeout: Seconds to wait to connect, or for a response + timeout: Seconds to wait to connect, or for a response before closing the link headers: Headers to send with every request """ @@ -152,12 +152,20 @@ async def close(self) -> None: await client.aclose() async def _send(self, method: str, path: str, **kwargs: Any) -> httpx.Response: - if self._client is None: + client = self._client + if client is None: raise DisconnectedError(f"{self.url} is not connected") - with _link_errors(f"{method} {self.url}{path}"): - async with asyncio.timeout(self.timeout): - response = await self._client.request(method, path, **kwargs) + try: + with _link_errors(f"{method} {self.url}{path}"): + async with asyncio.timeout(self.timeout): + response = await client.request(method, path, **kwargs) + except (ConnectionError, TimeoutError): + # Close the link so later calls raise DisconnectedError + if self._client is client: + self._client = None + await client.aclose() + raise self.log_event( "Received response", method=method, path=path, status=response.status_code diff --git a/tests/test_http_connection.py b/tests/test_http_connection.py index 6f776ae1e..9248add8d 100644 --- a/tests/test_http_connection.py +++ b/tests/test_http_connection.py @@ -43,18 +43,23 @@ def log_message(self, format, *args): pass -@pytest_asyncio.fixture -async def connection(): +@pytest.fixture +def server(): _RateDevice.rate = 0 server = ThreadingHTTPServer(("127.0.0.1", 0), _RateDevice) threading.Thread(target=server.serve_forever, daemon=True).start() + yield server + server.shutdown() + server.server_close() + + +@pytest_asyncio.fixture +async def connection(server: ThreadingHTTPServer): # The probe in connect() gets a 404 for "/", which still counts as reachable connection = HTTPConnection(f"http://127.0.0.1:{server.server_port}", timeout=1) await connection.connect() yield connection await connection.close() - server.shutdown() - server.server_close() @pytest.mark.asyncio @@ -63,6 +68,19 @@ async def test_put_then_get_json(connection: HTTPConnection): assert await connection.get("/rate") == 5 +@pytest.mark.asyncio +async def test_link_failure_closes_connection( + server: ThreadingHTTPServer, connection: HTTPConnection +): + server.shutdown() + server.server_close() + + with pytest.raises(ConnectionError): + await connection.get("/rate") + with pytest.raises(DisconnectedError): + await connection.get("/rate") + + @pytest.mark.asyncio async def test_connect_to_closed_port_raises_connection_error(): with socket.socket() as unused: From f3544b59e096381907898a80644ffbb89d5e4892 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Fri, 13 Nov 2026 12:30:08 +0000 Subject: [PATCH 12/16] improve ip connection; connect guard, logging, required arguments --- docs/explanations/connections.md | 4 +- src/fastcs/connections/connection.py | 2 +- src/fastcs/connections/ip_connection.py | 52 +++++++++++++++++-------- tests/test_ip_connection.py | 28 +++++++++++++ tests/test_launch.py | 5 ++- 5 files changed, 72 insertions(+), 19 deletions(-) diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index be8ee0562..e55453bdf 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -24,7 +24,9 @@ reply = await connection.query("R?") # sends "R?\r\n", returns the reply withou For binary protocols, `write_bytes` and `query_bytes` send raw bytes without a terminator. If an exchange fails or takes longer than `timeout`, the link is closed and -later calls raise `DisconnectedError`. +later calls raise `DisconnectedError`. If the device closes the link, the exchange raises +`ConnectionError`, which `DisconnectedError` subclasses, so +`except (ConnectionError, TimeoutError)` catches any link failure. `HTTPConnection` talks to a device with a JSON API. `get`, `put`, `post` and `delete` take a path relative to its `url`, send JSON, and return the parsed reply. An error diff --git a/src/fastcs/connections/connection.py b/src/fastcs/connections/connection.py index 61d91c6a5..54dbefa0c 100644 --- a/src/fastcs/connections/connection.py +++ b/src/fastcs/connections/connection.py @@ -10,7 +10,7 @@ """What a `Connection`'s ``introspect`` returns, or ``None`` if it doesn't introspect""" -class DisconnectedError(Exception): +class DisconnectedError(ConnectionError): """Raised when using a connection whose link isn't open""" diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index 7b9e4dba2..8c9ad17dd 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -9,12 +9,6 @@ class IPConnection(Connection[IntrospectionT], Tracer): """A TCP link to a device that exchanges terminated messages. - Example:: - - connection = IPConnection("10.0.0.5", 4000) - await connection.write("R=5") - reply = await connection.query("R?") - Args: ip: The address to connect to port: The port to connect to @@ -27,8 +21,8 @@ class IPConnection(Connection[IntrospectionT], Tracer): def __init__( self, - ip: str = "127.0.0.1", - port: int = 25565, + ip: str, + port: int, terminator: str = "\r\n", encoding: str = "utf-8", timeout: float = 5.0, @@ -45,16 +39,28 @@ def __init__( self._lock = asyncio.Lock() async def connect(self) -> None: - async with asyncio.timeout(self.timeout): - self._streams = await asyncio.open_connection( - self.ip, self.port, limit=self.limit - ) + """Open the link. + + Raises: + RuntimeError: If the link is already open + TimeoutError: If opening takes longer than ``timeout`` + + """ + async with self._lock: + if self._streams is not None: + raise RuntimeError(f"{self.ip}:{self.port} is already connected") + + async with asyncio.timeout(self.timeout): + self._streams = await asyncio.open_connection( + self.ip, self.port, limit=self.limit + ) async def write(self, message: str) -> None: """Send a message, adding the terminator. Raises: DisconnectedError: If the link isn't open + ConnectionError: If the device closes the link TimeoutError: If sending takes longer than ``timeout`` """ @@ -63,6 +69,8 @@ async def write(self, message: str) -> None: writer.write(data) await writer.drain() + self.log_event("Sent message", message=message) + async def query(self, message: str) -> str: """Send a message and read the reply. @@ -71,8 +79,9 @@ async def query(self, message: str) -> str: Raises: DisconnectedError: If the link isn't open + ConnectionError: If the device closes the link TimeoutError: If the reply takes longer than ``timeout`` - ValueError: If the reply is longer than ``limit`` + ValueError: If the reply is longer than ``limit`` or can't be decoded """ data = f"{message}{self.terminator}".encode(self.encoding) @@ -96,6 +105,7 @@ async def write_bytes(self, data: bytes) -> None: Raises: DisconnectedError: If the link isn't open + ConnectionError: If the device closes the link TimeoutError: If sending takes longer than ``timeout`` """ @@ -103,6 +113,8 @@ async def write_bytes(self, data: bytes) -> None: writer.write(data) await writer.drain() + self.log_event("Sent bytes", data=data) + async def query_bytes(self, data: bytes, size: int) -> bytes: """Send raw bytes and read a reply of a fixed size. @@ -111,13 +123,17 @@ async def query_bytes(self, data: bytes, size: int) -> bytes: Raises: DisconnectedError: If the link isn't open + ConnectionError: If the device closes the link TimeoutError: If the reply takes longer than ``timeout`` """ async with self._exchange() as (reader, writer): writer.write(data) await writer.drain() - return await reader.readexactly(size) + reply = await reader.readexactly(size) + + self.log_event("Received query bytes response", query=data, response=reply) + return reply async def close(self) -> None: async with self._lock: @@ -129,7 +145,7 @@ async def close(self) -> None: writer.close() try: await writer.wait_closed() - except ConnectionResetError: + except ConnectionError: pass @asynccontextmanager @@ -145,8 +161,12 @@ async def _exchange( try: async with asyncio.timeout(self.timeout): yield reader, writer - except BaseException: + except BaseException as e: # A late reply could be left in the stream and read by the next query self._streams = None writer.close() + if isinstance(e, asyncio.IncompleteReadError): + raise ConnectionError( + f"{self.ip}:{self.port} closed the link" + ) from e raise diff --git a/tests/test_ip_connection.py b/tests/test_ip_connection.py index b8e000d36..18e623423 100644 --- a/tests/test_ip_connection.py +++ b/tests/test_ip_connection.py @@ -31,6 +31,14 @@ async def test_query_adds_and_strips_terminator(connection: IPConnection): assert await connection.query("R?") == "5" +@pytest.mark.asyncio +async def test_connect_when_connected_raises(connection: IPConnection): + with pytest.raises(RuntimeError, match="already connected"): + await connection.connect() + + assert await connection.query("R?") == "5" + + @pytest.mark.asyncio async def test_timeout_closes_connection(connection: IPConnection): with pytest.raises(TimeoutError): @@ -47,6 +55,26 @@ async def test_write_and_bytes_methods(connection: IPConnection): assert await connection.query_bytes(b"R?\r\n", 3) == b"5\r\n" +@pytest.mark.asyncio +async def test_device_hanging_up_raises_connection_error(): + async def hang_up(reader: asyncio.StreamReader, writer: asyncio.StreamWriter): + await reader.readuntil(b"\r\n") + writer.write(b"partial") + writer.close() + + server = await asyncio.start_server(hang_up, "127.0.0.1", 0) + port = server.sockets[0].getsockname()[1] + connection = IPConnection("127.0.0.1", port, timeout=0.1) + await connection.connect() + + with pytest.raises(ConnectionError, match="closed the link"): + await connection.query("R?") + with pytest.raises(DisconnectedError): + await connection.write("R=5") + + server.close() + + @pytest.mark.asyncio async def test_reply_longer_than_limit_raises_and_closes_connection(): server = await asyncio.start_server(_reply_to_r, "127.0.0.1", 0) diff --git a/tests/test_launch.py b/tests/test_launch.py index 4373764eb..2b48a0d06 100644 --- a/tests/test_launch.py +++ b/tests/test_launch.py @@ -381,7 +381,10 @@ def test_parametrised_and_no_settings_connections(): { "id": "one", "type": "tests.WithGenericConnections", - "connections": {"sensor": {}, "link": {}}, + "connections": { + "sensor": {"ip": "localhost", "port": 8000}, + "link": {}, + }, } ], "transport": [{"rest": {}}], From e9a3c4aac29151b9ad59530d21eaf4d54eb026af Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Fri, 13 Nov 2026 12:57:15 +0000 Subject: [PATCH 13/16] improve serial connection; all common settings, logging, exception handling --- docs/explanations/connections.md | 5 +- src/fastcs/connections/ip_connection.py | 6 ++ src/fastcs/connections/serial_connection.py | 76 ++++++++++++++++++--- tests/test_ip_connection.py | 5 ++ tests/test_serial_connection.py | 35 ++++++++++ 5 files changed, 114 insertions(+), 13 deletions(-) diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index e55453bdf..4a478456d 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -24,8 +24,9 @@ reply = await connection.query("R?") # sends "R?\r\n", returns the reply withou For binary protocols, `write_bytes` and `query_bytes` send raw bytes without a terminator. If an exchange fails or takes longer than `timeout`, the link is closed and -later calls raise `DisconnectedError`. If the device closes the link, the exchange raises -`ConnectionError`, which `DisconnectedError` subclasses, so +later calls raise `DisconnectedError`. If the link fails, such as the device closing the +socket or a serial adapter being unplugged, the exchange raises `ConnectionError`, which +`DisconnectedError` subclasses, so `except (ConnectionError, TimeoutError)` catches any link failure. `HTTPConnection` talks to a device with a JSON API. `get`, `put`, `post` and `delete` diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index 8c9ad17dd..572656af0 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -17,6 +17,9 @@ class IPConnection(Connection[IntrospectionT], Tracer): timeout: Seconds to wait for each operation before closing the link limit: Most bytes a reply can have, not counting its terminator + Raises: + ValueError: If ``terminator`` is empty + """ def __init__( @@ -28,6 +31,9 @@ def __init__( timeout: float = 5.0, limit: int = 2**16, ): + if not terminator: + raise ValueError("terminator must not be empty") + super().__init__() self.ip = ip self.port = port diff --git a/src/fastcs/connections/serial_connection.py b/src/fastcs/connections/serial_connection.py index 119ab43b1..367f1884f 100644 --- a/src/fastcs/connections/serial_connection.py +++ b/src/fastcs/connections/serial_connection.py @@ -1,8 +1,10 @@ import asyncio from collections.abc import AsyncGenerator from contextlib import asynccontextmanager +from typing import Literal import aioserial +import serial from fastcs.connections.connection import Connection, DisconnectedError, IntrospectionT from fastcs.tracer import Tracer @@ -11,34 +13,49 @@ class SerialConnection(Connection[IntrospectionT], Tracer): """A serial link to a device that exchanges terminated messages. - Example:: - - connection = SerialConnection("/dev/ttyUSB0", baud=9600) - await connection.write("R=5") - reply = await connection.query("R?") - Args: port: The serial port to open baud: The baud rate + bytesize: The number of data bits in each byte + parity: The parity check: none, even, odd, mark or space + stopbits: The number of stop bits + rtscts: Whether to use RTS/CTS hardware flow control + xonxoff: Whether to use XON/XOFF software flow control terminator: Added to the end of each message, and marks the end of each reply encoding: The text encoding of messages and replies timeout: Seconds to wait for each operation before closing the link limit: Most bytes a reply can have, not counting its terminator + Raises: + ValueError: If ``terminator`` is empty + """ def __init__( self, port: str, baud: int = 115200, + bytesize: Literal[5, 6, 7, 8] = 8, + parity: Literal["N", "E", "O", "M", "S"] = "N", + stopbits: Literal[1, 2] = 1, + rtscts: bool = False, + xonxoff: bool = False, terminator: str = "\r\n", encoding: str = "utf-8", timeout: float = 5.0, limit: int = 2**16, ): + if not terminator: + raise ValueError("terminator must not be empty") + super().__init__() self.port = port self.baud = baud + self.bytesize = bytesize + self.parity = parity + self.stopbits = stopbits + self.rtscts = rtscts + self.xonxoff = xonxoff self.terminator = terminator self.encoding = encoding self.timeout = timeout @@ -47,13 +64,35 @@ def __init__( self._lock = asyncio.Lock() async def connect(self) -> None: - self._stream = aioserial.AioSerial(port=self.port, baudrate=self.baud) + """Open the link. + + Raises: + RuntimeError: If the link is already open + serial.SerialException: If the port can't be opened, or another process + holds it + + """ + async with self._lock: + if self._stream is not None: + raise RuntimeError(f"{self.port} is already connected") + + self._stream = aioserial.AioSerial( + port=self.port, + baudrate=self.baud, + bytesize=self.bytesize, + parity=self.parity, + stopbits=self.stopbits, + rtscts=self.rtscts, + xonxoff=self.xonxoff, + exclusive=True, + ) async def write(self, message: str) -> None: """Send a message, adding the terminator. Raises: DisconnectedError: If the link isn't open + ConnectionError: If the port fails, such as an unplugged adapter TimeoutError: If sending takes longer than ``timeout`` """ @@ -61,6 +100,8 @@ async def write(self, message: str) -> None: async with self._exchange() as stream: await stream.write_async(data) + self.log_event("Sent message", message=message) + async def query(self, message: str) -> str: """Send a message and read the reply. @@ -69,8 +110,9 @@ async def query(self, message: str) -> str: Raises: DisconnectedError: If the link isn't open + ConnectionError: If the port fails, such as an unplugged adapter TimeoutError: If the reply takes longer than ``timeout`` - ValueError: If the reply is longer than ``limit`` + ValueError: If the reply is longer than ``limit`` or can't be decoded """ data = f"{message}{self.terminator}".encode(self.encoding) @@ -92,12 +134,15 @@ async def write_bytes(self, data: bytes) -> None: Raises: DisconnectedError: If the link isn't open + ConnectionError: If the port fails, such as an unplugged adapter TimeoutError: If sending takes longer than ``timeout`` """ async with self._exchange() as stream: await stream.write_async(data) + self.log_event("Sent bytes", data=data) + async def query_bytes(self, data: bytes, size: int) -> bytes: """Send raw bytes and read a reply of a fixed size. @@ -106,12 +151,16 @@ async def query_bytes(self, data: bytes, size: int) -> bytes: Raises: DisconnectedError: If the link isn't open + ConnectionError: If the port fails, such as an unplugged adapter TimeoutError: If the reply takes longer than ``timeout`` """ async with self._exchange() as stream: await stream.write_async(data) - return await stream.read_async(size) + reply = await stream.read_async(size) + + self.log_event("Received query bytes response", query=data, response=reply) + return reply async def close(self) -> None: async with self._lock: @@ -132,9 +181,14 @@ async def _exchange(self) -> AsyncGenerator[aioserial.AioSerial, None]: stream = self._stream try: async with asyncio.timeout(self.timeout): + # Discard anything left over, such as a late reply to an earlier + # query, so it isn't read as the reply to this one + stream.reset_input_buffer() yield stream - except BaseException: - # A late reply could be left in the stream and read by the next query + except BaseException as e: + # Close the link so later calls raise DisconnectedError self._stream = None stream.close() + if isinstance(e, serial.SerialException): + raise ConnectionError(f"{self.port} failed") from e raise diff --git a/tests/test_ip_connection.py b/tests/test_ip_connection.py index 18e623423..dff8ac1e3 100644 --- a/tests/test_ip_connection.py +++ b/tests/test_ip_connection.py @@ -88,3 +88,8 @@ async def test_reply_longer_than_limit_raises_and_closes_connection(): await connection.write("R=5") server.close() + + +def test_empty_terminator_raises(): + with pytest.raises(ValueError, match="terminator must not be empty"): + IPConnection("127.0.0.1", 0, terminator="") diff --git a/tests/test_serial_connection.py b/tests/test_serial_connection.py index 42319f717..a5fc91c0b 100644 --- a/tests/test_serial_connection.py +++ b/tests/test_serial_connection.py @@ -1,5 +1,6 @@ import os import threading +import time import pytest import pytest_asyncio @@ -40,6 +41,14 @@ async def test_query_adds_and_strips_terminator(connection: SerialConnection): assert await connection.query("R?") == "5" +@pytest.mark.asyncio +async def test_connect_when_connected_raises(connection: SerialConnection): + with pytest.raises(RuntimeError, match="already connected"): + await connection.connect() + + assert await connection.query("R?") == "5" + + @pytest.mark.asyncio async def test_timeout_closes_connection(connection: SerialConnection): with pytest.raises(TimeoutError): @@ -56,6 +65,27 @@ async def test_write_and_bytes_methods(connection: SerialConnection): assert await connection.query_bytes(b"R?\r\n", 3) == b"5\r\n" +@pytest.mark.asyncio +async def test_device_hanging_up_raises_connection_error(): + def hang_up(device: int): + os.read(device, 1024) + os.write(device, b"partial") + time.sleep(0.05) + os.close(device) + + device, port = os.openpty() + threading.Thread(target=hang_up, args=(device,), daemon=True).start() + connection = SerialConnection(os.ttyname(port), timeout=1) + await connection.connect() + + with pytest.raises(ConnectionError, match="failed"): + await connection.query("R?") + with pytest.raises(DisconnectedError): + await connection.write("R=5") + + os.close(port) + + @pytest.mark.asyncio async def test_reply_longer_than_limit_raises_and_closes_connection(): device, port = os.openpty() @@ -70,3 +100,8 @@ async def test_reply_longer_than_limit_raises_and_closes_connection(): os.close(port) os.close(device) + + +def test_empty_terminator_raises(): + with pytest.raises(ValueError, match="terminator must not be empty"): + SerialConnection("/dev/null", terminator="") From c09d034eb2272098249d3dbbc7be3ea22ddf59a1 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Fri, 13 Nov 2026 13:17:38 +0000 Subject: [PATCH 14/16] improve http connection; locks, logging, timeout and exception handling --- docs/explanations/connections.md | 4 +- src/fastcs/connections/http_connection.py | 79 ++++++++++++++--------- tests/test_http_connection.py | 13 ++++ 3 files changed, 63 insertions(+), 33 deletions(-) diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md index 4a478456d..3260120ed 100644 --- a/docs/explanations/connections.md +++ b/docs/explanations/connections.md @@ -42,4 +42,6 @@ rate = await connection.get("/rate") ``` Like the other connections, it raises `TimeoutError` when the device doesn't answer in -time. It raises `ConnectionError` when the server can't be reached. +time, but leaves the link open, as one slow request doesn't mean the server has gone. It +raises `ConnectionError` when the server can't be reached, and closes the link so later +calls raise `DisconnectedError`. diff --git a/src/fastcs/connections/http_connection.py b/src/fastcs/connections/http_connection.py index 14abcd40e..f7aea0219 100644 --- a/src/fastcs/connections/http_connection.py +++ b/src/fastcs/connections/http_connection.py @@ -1,4 +1,5 @@ import asyncio +import ssl from collections.abc import Generator from contextlib import contextmanager from typing import Any @@ -12,52 +13,65 @@ class HTTPConnection(Connection[IntrospectionT], Tracer): """An HTTP link to a device with a JSON API. - Example:: - - connection = HTTPConnection("http://10.0.0.5:8000/api") - await connection.put("/rate", json=5) - rate = await connection.get("/rate") - Args: url: The base URL that request paths are relative to - timeout: Seconds to wait to connect, or for a response before closing the link + timeout: Seconds to wait to connect, or for each response headers: Headers to send with every request + verify: Whether to check the server's TLS certificate, or a path to a CA + bundle to check it against """ def __init__( self, - url: str = "http://127.0.0.1:8080", + url: str, timeout: float = 5.0, headers: dict[str, str] | None = None, + verify: bool | str = True, ): super().__init__() self.url = url self.timeout = timeout self.headers = headers or {} + self.verify = verify self._client: httpx.AsyncClient | None = None + self._lock = asyncio.Lock() async def connect(self) -> None: """Create the client and check the server answers. Raises: + RuntimeError: If the link is already open ConnectionError: If the server can't be reached TimeoutError: If the server doesn't answer within ``timeout`` + FileNotFoundError: If the ``verify`` CA bundle doesn't exist """ - client = httpx.AsyncClient( - base_url=self.url, timeout=self.timeout, headers=self.headers - ) - try: - # Any response, even an error status, shows the server is reachable - with _link_errors(f"GET {self.url}"): - async with asyncio.timeout(self.timeout): - await client.get("") - except BaseException: - await client.aclose() - raise + async with self._lock: + if self._client is not None: + raise RuntimeError(f"{self.url} is already connected") + + verify = self.verify + if isinstance(verify, str): + verify = ssl.create_default_context(cafile=verify) + + client = httpx.AsyncClient( + base_url=self.url, + timeout=self.timeout, + headers=self.headers, + follow_redirects=True, + verify=verify, + ) + try: + # Any response, even an error status, shows the server is reachable + with _link_errors(f"GET {self.url}"): + async with asyncio.timeout(self.timeout): + await client.get("") + except BaseException: + await client.aclose() + raise - self._client = client + self._client = client async def get(self, path: str, params: dict[str, Any] | None = None) -> Any: """Send a GET request. @@ -70,6 +84,7 @@ async def get(self, path: str, params: dict[str, Any] | None = None) -> Any: ConnectionError: If the server can't be reached TimeoutError: If the reply takes longer than ``timeout`` httpx.HTTPStatusError: If the reply has an error status + ValueError: If the reply isn't valid JSON """ return _json(await self._send("GET", path, params=params)) @@ -85,6 +100,7 @@ async def put(self, path: str, json: Any = None) -> Any: ConnectionError: If the server can't be reached TimeoutError: If the reply takes longer than ``timeout`` httpx.HTTPStatusError: If the reply has an error status + ValueError: If the reply isn't valid JSON """ return _json(await self._send("PUT", path, json=json)) @@ -100,6 +116,7 @@ async def post(self, path: str, json: Any = None) -> Any: ConnectionError: If the server can't be reached TimeoutError: If the reply takes longer than ``timeout`` httpx.HTTPStatusError: If the reply has an error status + ValueError: If the reply isn't valid JSON """ return _json(await self._send("POST", path, json=json)) @@ -115,6 +132,7 @@ async def delete(self, path: str) -> Any: ConnectionError: If the server can't be reached TimeoutError: If the reply takes longer than ``timeout`` httpx.HTTPStatusError: If the reply has an error status + ValueError: If the reply isn't valid JSON """ return _json(await self._send("DELETE", path)) @@ -122,11 +140,6 @@ async def delete(self, path: str) -> Any: async def request(self, method: str, path: str, **kwargs: Any) -> httpx.Response: """Send any request, for replies that aren't JSON. - Example:: - - response = await connection.request("GET", "/image", params={"n": 1}) - image = response.content - Args: method: The HTTP method path: The path, relative to ``url`` @@ -144,12 +157,13 @@ async def request(self, method: str, path: str, **kwargs: Any) -> httpx.Response return await self._send(method, path, **kwargs) async def close(self) -> None: - if self._client is None: - return + async with self._lock: + if self._client is None: + return - client = self._client - self._client = None - await client.aclose() + client = self._client + self._client = None + await client.aclose() async def _send(self, method: str, path: str, **kwargs: Any) -> httpx.Response: client = self._client @@ -160,8 +174,9 @@ async def _send(self, method: str, path: str, **kwargs: Any) -> httpx.Response: with _link_errors(f"{method} {self.url}{path}"): async with asyncio.timeout(self.timeout): response = await client.request(method, path, **kwargs) - except (ConnectionError, TimeoutError): - # Close the link so later calls raise DisconnectedError + except ConnectionError: + # Close the link so later calls raise DisconnectedError. A timeout leaves + # it open, as a slow request doesn't mean the server has gone if self._client is client: self._client = None await client.aclose() diff --git a/tests/test_http_connection.py b/tests/test_http_connection.py index 9248add8d..e4155c93a 100644 --- a/tests/test_http_connection.py +++ b/tests/test_http_connection.py @@ -68,6 +68,12 @@ async def test_put_then_get_json(connection: HTTPConnection): assert await connection.get("/rate") == 5 +@pytest.mark.asyncio +async def test_connect_when_connected_raises(connection: HTTPConnection): + with pytest.raises(RuntimeError, match="already connected"): + await connection.connect() + + @pytest.mark.asyncio async def test_link_failure_closes_connection( server: ThreadingHTTPServer, connection: HTTPConnection @@ -137,3 +143,10 @@ async def drip(reader: asyncio.StreamReader, writer: asyncio.StreamWriter): assert task.done() assert isinstance(task.exception(), TimeoutError) + + +@pytest.mark.asyncio +async def test_missing_ca_bundle_raises(): + connection = HTTPConnection("https://127.0.0.1", verify="/no/such/bundle.pem") + with pytest.raises(FileNotFoundError): + await connection.connect() From 8bcc6cc29c614f0c7789de67b5011e02c0f8af0f Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Fri, 13 Nov 2026 13:23:41 +0000 Subject: [PATCH 15/16] docs fix for pyserial --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 84c699e23..ec941e432 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -113,6 +113,8 @@ # httpx doesn't have intersphinx mapping (r"py:.*", r"httpx\..*"), ("any", r"httpx\..*"), + # pyserial doesn't have intersphinx mapping + (r"py:.*", r"serial\..*"), ("py:class", r"numpy.*"), ] From 1b19b6b206fa42ae9f7c41b59887818970b1fe80 Mon Sep 17 00:00:00 2001 From: Tom Kane Date: Fri, 13 Nov 2026 14:04:56 +0000 Subject: [PATCH 16/16] improve optional dependency error, and docstring fix --- src/fastcs/connections/__init__.py | 22 ++++++++++++++++++++++ src/fastcs/connections/ip_connection.py | 1 + tests/test_http_connection.py | 10 ++++++++++ 3 files changed, 33 insertions(+) diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 64a902171..fa4c5653d 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -1,3 +1,5 @@ +from typing import NoReturn + from fastcs.util import optional_dependency from .connection import Connection as Connection @@ -9,3 +11,23 @@ with optional_dependency("aioserial"): from .serial_connection import SerialConnection as SerialConnection + +# The extra that installs each optional connection +_EXTRAS = {"HTTPConnection": "http", "SerialConnection": "serial"} + + +def __getattr__(name: str) -> NoReturn: + """Name the extra to install when an optional connection is missing. + + Raises: + ImportError: If ``name`` is an optional connection whose extra isn't installed + AttributeError: If ``name`` isn't in this module + + """ + if name in _EXTRAS: + extra = _EXTRAS[name] + raise ImportError( + f'{name} needs the {extra} extra: pip install "fastcs[{extra}]"' + ) + + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") diff --git a/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index 572656af0..587e0aa4b 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -49,6 +49,7 @@ async def connect(self) -> None: Raises: RuntimeError: If the link is already open + OSError: If the device can't be reached TimeoutError: If opening takes longer than ``timeout`` """ diff --git a/tests/test_http_connection.py b/tests/test_http_connection.py index e4155c93a..cd4ec88c2 100644 --- a/tests/test_http_connection.py +++ b/tests/test_http_connection.py @@ -7,6 +7,7 @@ import pytest import pytest_asyncio +import fastcs.connections from fastcs.connections import DisconnectedError, HTTPConnection @@ -150,3 +151,12 @@ async def test_missing_ca_bundle_raises(): connection = HTTPConnection("https://127.0.0.1", verify="/no/such/bundle.pem") with pytest.raises(FileNotFoundError): await connection.connect() + + +def test_missing_extra_names_it(monkeypatch: pytest.MonkeyPatch): + monkeypatch.delattr(fastcs.connections, "HTTPConnection") + with pytest.raises(ImportError, match=r"fastcs\[http\]"): + from fastcs.connections import HTTPConnection # noqa: F401 + + with pytest.raises(AttributeError): + fastcs.connections.NotAConnection # noqa: B018