diff --git a/docs/conf.py b/docs/conf.py index 4c36118d1..ec941e432 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -110,6 +110,11 @@ ("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\..*"), + # pyserial doesn't have intersphinx mapping + (r"py:.*", r"serial\..*"), ("py:class", r"numpy.*"), ] diff --git a/docs/explanations/connections.md b/docs/explanations/connections.md new file mode 100644 index 000000000..3260120ed --- /dev/null +++ b/docs/explanations/connections.md @@ -0,0 +1,47 @@ +# 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]"` | +| `HTTPConnection` | HTTP | `pip install "fastcs[http]"` | + +`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) + +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`. 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` +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, 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/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/pyproject.toml b/pyproject.toml index d668f37f9..80c1f36fa 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,22 @@ 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]"] 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]", + "fastcs[http]", +] [dependency-groups] dev = [ diff --git a/src/fastcs/connections/__init__.py b/src/fastcs/connections/__init__.py index 1696c2a30..fa4c5653d 100644 --- a/src/fastcs/connections/__init__.py +++ b/src/fastcs/connections/__init__.py @@ -1,4 +1,33 @@ +from typing import NoReturn + +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 -from .ip_connection import StreamConnection as StreamConnection -from .serial_connection import SerialConnection as SerialConnection + +with optional_dependency("httpx"): + from .http_connection import HTTPConnection as HTTPConnection + +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/connection.py b/src/fastcs/connections/connection.py index 3ccc44b9a..54dbefa0c 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(ConnectionError): + """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/http_connection.py b/src/fastcs/connections/http_connection.py new file mode 100644 index 000000000..f7aea0219 --- /dev/null +++ b/src/fastcs/connections/http_connection.py @@ -0,0 +1,204 @@ +import asyncio +import ssl +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. + + Args: + url: The base URL that request paths are relative to + 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, + 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 + + """ + 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 + + 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 + ValueError: If the reply isn't valid JSON + + """ + 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 + ValueError: If the reply isn't valid JSON + + """ + 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 + ValueError: If the reply isn't valid JSON + + """ + 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 + ValueError: If the reply isn't valid JSON + + """ + 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. + + 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: + async with self._lock: + 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: + client = self._client + if client is None: + raise DisconnectedError(f"{self.url} is not connected") + + try: + with _link_errors(f"{method} {self.url}{path}"): + async with asyncio.timeout(self.timeout): + response = await client.request(method, path, **kwargs) + 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() + raise + + 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/src/fastcs/connections/ip_connection.py b/src/fastcs/connections/ip_connection.py index a690c2afa..587e0aa4b 100644 --- a/src/fastcs/connections/ip_connection.py +++ b/src/fastcs/connections/ip_connection.py @@ -1,95 +1,179 @@ import asyncio -from dataclasses import dataclass +from collections.abc import AsyncGenerator +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): - """For connecting to an ip using a `StreamConnection`. + """A TCP link to a device that exchanges terminated messages. 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 + limit: Most bytes a reply can have, not counting its terminator + + Raises: + ValueError: If ``terminator`` is empty """ - def __init__(self, ip: str = "127.0.0.1", port: int = 25565): + def __init__( + self, + ip: str, + port: int, + 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.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.limit = limit + 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: + """Open the link. + + Raises: + RuntimeError: If the link is already open + OSError: If the device can't be reached + 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`` + + """ + data = f"{message}{self.terminator}".encode(self.encoding) + async with self._exchange() as (_, writer): + 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. + + Returns: + The reply, without its terminator + + 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`` or can't be decoded + + """ + data = f"{message}{self.terminator}".encode(self.encoding) + terminator = self.terminator.encode(self.encoding) + async with self._exchange() as (reader, writer): + writer.write(data) + await writer.drain() + 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) + return response + + async def write_bytes(self, data: bytes) -> None: + """Send raw bytes, without a terminator. + + Raises: + DisconnectedError: If the link isn't open + ConnectionError: If the device closes the link + TimeoutError: If sending takes longer than ``timeout`` + + """ + async with self._exchange() as (_, writer): + 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. + + Returns: + The reply, exactly ``size`` bytes long + + 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() + 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: + if self._streams is None: + return + + _, writer = self._streams + self._streams = None + writer.close() try: - await connection.close() - except ConnectionResetError: + await writer.wait_closed() + except ConnectionError: pass - finally: - self.__connection = None + + @asynccontextmanager + async def _exchange( + self, + ) -> 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: + 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 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/src/fastcs/connections/serial_connection.py b/src/fastcs/connections/serial_connection.py index e719d1495..367f1884f 100644 --- a/src/fastcs/connections/serial_connection.py +++ b/src/fastcs/connections/serial_connection.py @@ -1,59 +1,194 @@ 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, IntrospectionT +from fastcs.connections.connection import Connection, DisconnectedError, IntrospectionT +from fastcs.tracer import Tracer -class NotOpenedError(Exception): - """If the serial stream is not opened.""" - - pass - - -class SerialConnection(Connection[IntrospectionT]): - """A serial connection. +class SerialConnection(Connection[IntrospectionT], Tracer): + """A serial link to a device that exchanges terminated messages. 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): + 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.__stream = None + self.bytesize = bytesize + self.parity = parity + self.stopbits = stopbits + self.rtscts = rtscts + self.xonxoff = xonxoff + self.terminator = terminator + self.encoding = encoding + self.timeout = timeout + self.limit = limit + 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) + """Open the link. - @property - def _stream(self) -> aioserial.AioSerial: - if self.__stream is None: - raise NotOpenedError( - "Need to call connect() before using SerialConnection." + 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, ) - return self.__stream + async def write(self, message: str) -> None: + """Send a message, adding the terminator. - async def send_command(self, message: bytes) -> None: - async with self._lock: - await self._send_message(message) + 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 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) + """ + data = f"{message}{self.terminator}".encode(self.encoding) + 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. + + Returns: + The reply, without its terminator + + 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`` or can't be decoded + + """ + 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, 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) + return response + + async def write_bytes(self, data: bytes) -> None: + """Send raw bytes, without a 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`` + + """ + async with self._exchange() as stream: + await stream.write_async(data) + + self.log_event("Sent bytes", data=data) - async def _send_message(self, message): - await self._stream.write_async(message) + async def query_bytes(self, data: bytes, size: int) -> bytes: + """Send raw bytes and read a reply of a fixed size. - async def _receive_response(self, size): - return await self._stream.read_async(size) + Returns: + The reply, exactly ``size`` bytes long + + 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) + 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: - 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): + # 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 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/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/src/fastcs/util.py b/src/fastcs/util.py index 4044585e9..fee179c93 100644 --- a/src/fastcs/util.py +++ b/src/fastcs/util.py @@ -1,4 +1,6 @@ import re +from collections.abc import Generator +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) -> Generator[None, None, 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_http_connection.py b/tests/test_http_connection.py new file mode 100644 index 000000000..cd4ec88c2 --- /dev/null +++ b/tests/test_http_connection.py @@ -0,0 +1,162 @@ +import asyncio +import json +import socket +import threading +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer + +import pytest +import pytest_asyncio + +import fastcs.connections +from fastcs.connections import DisconnectedError, 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 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) + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def log_message(self, format, *args): + pass + + +@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() + + +@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_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 +): + 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: + 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() + + +@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") + + +@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) + + +@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() + + +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 diff --git a/tests/test_ip_connection.py b/tests/test_ip_connection.py index 3770174f1..dff8ac1e3 100644 --- a/tests/test_ip_connection.py +++ b/tests/test_ip_connection.py @@ -1,52 +1,95 @@ -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") + elif line == b"LONG?\r\n": + writer.write(b"12345\r\n") + await writer.drain() + + +@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_query_adds_and_strips_terminator(connection: IPConnection): + assert await connection.query("R?") == "5" @pytest.mark.asyncio -async def test_close_when_not_connected(connection): - conn, mock_stream = connection - conn._IPConnection__connection = None +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" - await conn.close() - mock_stream.close.assert_not_awaited() - assert conn._IPConnection__connection is None +@pytest.mark.asyncio +async def test_timeout_closes_connection(connection: IPConnection): + with pytest.raises(TimeoutError): + await connection.query("NO_REPLY?") + + with pytest.raises(DisconnectedError): + await connection.write("R=5") @pytest.mark.asyncio -async def test_close_connected_and_connection_reset(connection): - conn, mock_stream = connection +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" - await conn.close() - mock_stream.close.assert_awaited_once() - assert conn._IPConnection__connection is None - conn._IPConnection__connection = mock_stream - mock_stream.close.side_effect = ConnectionResetError +@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) + port = server.sockets[0].getsockname()[1] + connection = IPConnection("127.0.0.1", port, timeout=0.1, limit=4) + await connection.connect() - await conn.close() - assert mock_stream.close.await_count == 2 - assert conn._IPConnection__connection is None + with pytest.raises(ValueError, match="longer than 4 bytes"): + await connection.query("LONG?") + with pytest.raises(DisconnectedError): + await connection.write("R=5") - # Other exceptions are propagated, but connection is reset - conn._IPConnection__connection = mock_stream - mock_stream.close.side_effect = OSError + server.close() - with pytest.raises(OSError): - await conn.close() - assert conn._IPConnection__connection is None +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_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": {}}], diff --git a/tests/test_serial_connection.py b/tests/test_serial_connection.py new file mode 100644 index 000000000..a5fc91c0b --- /dev/null +++ b/tests/test_serial_connection.py @@ -0,0 +1,107 @@ +import os +import threading +import time + +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") + elif line == b"LONG?": + os.write(device, b"12345\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_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): + await connection.query("NO_REPLY?") + + 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" + + +@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() + 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) + + +def test_empty_terminator_raises(): + with pytest.raises(ValueError, match="terminator must not be empty"): + SerialConnection("/dev/null", terminator="") 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 diff --git a/uv.lock b/uv.lock index 115e5603b..d48d49418 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,7 +919,9 @@ dependencies = [ [package.optional-dependencies] all = [ + { name = "aioserial" }, { name = "fastapi", extra = ["standard"] }, + { name = "httpx" }, { name = "numpy" }, { name = "p4p" }, { name = "pvi" }, @@ -949,11 +950,17 @@ graphql = [ { name = "strawberry-graphql" }, { name = "uvicorn", extra = ["standard"] }, ] +http = [ + { name = "httpx" }, +] rest = [ { name = "fastapi", extra = ["standard"] }, { name = "numpy" }, { name = "uvicorn", extra = ["standard"] }, ] +serial = [ + { name = "aioserial" }, +] tango = [ { name = "pytango" }, ] @@ -989,15 +996,18 @@ 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'" }, { 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" }, @@ -1017,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", "epicsca", "epicspva", "epics", "tango", "graphql", "rest", "all"] +provides-extras = ["demo", "serial", "http", "epicsca", "epicspva", "epics", "tango", "graphql", "rest", "all"] [package.metadata.requires-dev] dev = [