Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 55 additions & 2 deletions docs/explanations/connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,15 @@ class EigerConnection(Connection):
```

A class that sets `reconnect_attempts` must set `reconnect_period` too, or defining it
raises a `TypeError`.
raises a `TypeError`. In Python, set them on one connection with `set_reconnect`, which
returns the connection. `disconnect_after_timeouts` is optional, and keeps the class's
value if it's left out:

```python
connection = IPConnection("10.0.0.5", 4000).set_reconnect(
attempts=5, period=2.0, disconnect_after_timeouts=3
)
```

| Connection | `reconnect_attempts` | `reconnect_period` |
|---|---|---|
Expand All @@ -141,6 +149,51 @@ FastCS finds the controllers to mark down by looking for the connection on them,
and passes it to any sub controllers that need it, which store it too.
- Each controller stores at most one connection.
- Every connection a controller stores was opened by FastCS, from the top-level
controller's arguments.
controller's arguments or discovered for them.

FastCS raises a `ValueError` at startup if any of these is broken.

## Discovered connections

Some devices report where other links are, like Odin reporting the port of its meta
writer. `introspect()` can return a `ConnectionSpec` for each of these alongside the
description:

```python
from fastcs.connections import Connection, ConnectionSpec, Introspection


class OdinConnection(Connection[OdinIntrospection]):
async def introspect(self) -> Introspection[OdinIntrospection]:
info = OdinIntrospection(await self.get("/api/tree"))
meta = ConnectionSpec("meta", MetaWriterConnection, port=info.meta_port)
return Introspection(info, subconnections=[meta])
```

FastCS renames each one after the connection that discovered it, here `odin_meta`, and
passes it to the top-level controller's argument of that name, which is hinted
`X | None`:

```python
class EigerController(Controller):
def __init__(
self,
eiger: EigerConnection,
odin: OdinConnection,
odin_meta: MetaWriterConnection | None = None,
) -> None: ...
```

- It's opened after the connections that are given, and only if the controller takes
it. It can discover connections of its own, named the same way, e.g. `odin_meta_x`.
- An `odin_meta` block in `fastcs.yaml`, or an `odin_meta` argument in the
`ControllerSpec`, is used instead of the discovered one.
- It's independent of the connection that discovered it, so it only goes down when its
own IO fails. Set `depends_on` on its class if it needs its parent to be up first.
- It's opened after the connections that are given, so none of those can depend on
it. If a given connection's `depends_on` matches the type of a controller argument
that isn't given, FastCS raises a `ValueError` before opening anything.
- It uses its class's reconnect settings. To set others, give it a block in
`fastcs.yaml` instead.
- If a reconnect discovers a different spec for a connection the controller takes,
such as a new port, FastCS stops with an `IntrospectionMismatchError`.
6 changes: 3 additions & 3 deletions docs/snippets/dynamic.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
AttrRW,
AttrW,
)
from fastcs.connections import IPConnection
from fastcs.connections import Introspection, IPConnection
from fastcs.controllers import Controller, ControllerSpec
from fastcs.datatypes import Bool, DataType, Float, Int, String
from fastcs.launch import FastCS
Expand Down Expand Up @@ -67,10 +67,10 @@ class TemperatureIntrospection:


class TemperatureConnection(IPConnection[TemperatureIntrospection]):
async def introspect(self) -> TemperatureIntrospection:
async def introspect(self) -> Introspection[TemperatureIntrospection]:
api = json.loads(await self.query("API?"))
ramps = api.pop("Ramps")
return TemperatureIntrospection(parameters=api, ramps=ramps)
return Introspection(TemperatureIntrospection(parameters=api, ramps=ramps))


NumberT = TypeVar("NumberT", int, float)
Expand Down
9 changes: 5 additions & 4 deletions docs/tutorials/dynamic-drivers.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,11 @@ or a description for the parameter.

## Introspection

A `Connection` can describe the device it connects to by implementing `introspect`.
FastCS opens every connection and calls `introspect` before constructing any
controller, and stores what it returned as `connection.introspection`, so a controller
can use it in its `__init__`.
A `Connection` can describe the device it connects to by implementing `introspect`,
which returns the description wrapped in an `Introspection`. FastCS opens every
connection and calls `introspect` before constructing any controller, and stores the
description as `connection.introspection`, so a controller can use it in its
`__init__`.

Take the driver implementation from the previous tutorial and remove the statically
defined `Attributes` and creation of sub controllers in `__init__`. Then create them
Expand Down
8 changes: 5 additions & 3 deletions src/fastcs/connections/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,19 @@

from fastcs.util import optional_dependency

from .builtin.ip_connection import IPConnection as IPConnection
from .connection import Connection as Connection
from .connection import ConnectionState as ConnectionState
from .connection import DisconnectedError as DisconnectedError
from .connection import Introspection as Introspection
from .connection import disconnect_on as disconnect_on
from .ip_connection import IPConnection as IPConnection
from .connection_spec import ConnectionSpec as ConnectionSpec

with optional_dependency("httpx"):
from .http_connection import HTTPConnection as HTTPConnection
from .builtin.http_connection import HTTPConnection as HTTPConnection

with optional_dependency("aioserial"):
from .serial_connection import SerialConnection as SerialConnection
from .builtin.serial_connection import SerialConnection as SerialConnection

# The extra that installs each optional connection
_EXTRAS = {"HTTPConnection": "http", "SerialConnection": "serial"}
Expand Down
1 change: 1 addition & 0 deletions src/fastcs/connections/builtin/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
"""Connections that FastCS provides, re-exported from ``fastcs.connections``"""
120 changes: 114 additions & 6 deletions src/fastcs/connections/connection.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,54 @@
from abc import ABC, abstractmethod
from collections.abc import Callable, Coroutine, Mapping, Sequence
from contextvars import ContextVar
from typing import Any, ClassVar, Generic, cast, overload
from types import UnionType
from typing import (
TYPE_CHECKING,
Any,
ClassVar,
Generic,
Self,
Union,
cast,
get_args,
get_origin,
overload,
)

from pydantic import BaseModel
from typing_extensions import TypeVar

if TYPE_CHECKING:
from fastcs.connections.connection_spec import ConnectionSpec

IntrospectionT = TypeVar("IntrospectionT", default=None)
"""What a `Connection`'s ``introspect`` returns, or ``None`` if it doesn't introspect"""


@dataclasses.dataclass
class Introspection(Generic[IntrospectionT]):
"""What a `Connection`'s ``introspect`` returns.

Example::

async def introspect(self) -> Introspection[OdinIntrospection]:
info = OdinIntrospection(...)
meta = ConnectionSpec("meta", MetaConnection, port=info.meta_port)
return Introspection(info, subconnections=[meta])

Args:
value: The description of the device, available as
``connection.introspection``
subconnections: Other connections found on the device. Each is renamed
``<parent_name>_<_name>``, and opened if the controller takes an argument of
that name that isn't given another way.

"""

value: IntrospectionT
subconnections: list[ConnectionSpec] = dataclasses.field(default_factory=list)


class DisconnectedError(Exception):
"""Raised when using a connection whose link is down or closed"""

Expand Down Expand Up @@ -88,7 +127,7 @@ class Connection(ABC, Generic[IntrospectionT]):
Example::

class EigerConnection(Connection[EigerIntrospection]):
async def introspect(self) -> EigerIntrospection: ...
async def introspect(self) -> Introspection[EigerIntrospection]: ...
"""

# Connection type(s) in the same ControllerSpec to open before this one
Expand Down Expand Up @@ -129,9 +168,58 @@ def __init_subclass__(cls, **kwargs: Any) -> None:
"it must be an integer of at least 1"
)

def set_reconnect(
self,
*,
attempts: int | None,
period: float | None,
disconnect_after_timeouts: int | None = None,
) -> Self:
"""Set this connection's ``reconnect_attempts`` and ``reconnect_period``, and
optionally its ``disconnect_after_timeouts``, instead of using its class's.

Example::

odin = OdinConnection(url).set_reconnect(
attempts=10, period=2.0, disconnect_after_timeouts=3
)

Args:
attempts: How many times to try to reconnect. None or 0 means don't
period: How many seconds apart to try
disconnect_after_timeouts: How many timeouts in a row mean the link has
gone, or None to keep the class's

Returns:
This connection

Raises:
ValueError: If ``attempts`` is set without ``period``, or
``disconnect_after_timeouts`` is less than 1

"""
if attempts and period is None:
raise ValueError(
f"{type(self).__name__} sets reconnect attempts but not reconnect "
"period"
)
if disconnect_after_timeouts is not None and disconnect_after_timeouts < 1:
raise ValueError(
f"{type(self).__name__} sets disconnect_after_timeouts to "
f"{disconnect_after_timeouts}, but it must be at least 1"
)

self.reconnect_attempts = attempts
self.reconnect_period = period
if disconnect_after_timeouts is not None:
self.disconnect_after_timeouts = disconnect_after_timeouts

return self

@property
def introspection(self) -> IntrospectionT:
"""What ``introspect`` returned when the framework opened this connection.
"""The value of the `Introspection` that ``introspect`` returned when the
framework opened this connection.

Raises:
RuntimeError: If the framework hasn't opened this connection yet
Expand Down Expand Up @@ -162,14 +250,15 @@ def introspection_changed(self, introspection: IntrospectionT) -> bool:
async def connect(self) -> None:
"""Open the link, or raise. Called by the framework before construction."""

async def introspect(self) -> IntrospectionT:
async def introspect(self) -> Introspection[IntrospectionT]:
"""Describe the device. Called by the framework after ``connect``.

Returns:
The introspection, or ``None`` if this connection doesn't introspect
The introspection, whose value is ``None`` if this connection doesn't
introspect

"""
return cast(IntrospectionT, None)
return Introspection(cast(IntrospectionT, None))

@abstractmethod
async def close(self) -> None:
Expand Down Expand Up @@ -279,3 +368,22 @@ def _structure(value: Any) -> Any:
if isinstance(value, list | tuple):
return [_structure(item) for item in value]
return None


def _connection_hint(hint: Any) -> tuple[type[Connection] | None, bool]:
"""The connection class a controller argument's hint names, if any, and whether
it's optional, as in ``MetaConnection | None``"""
optional = False
if get_origin(hint) in (Union, UnionType):
members = [member for member in get_args(hint) if member is not type(None)]
if len(members) != 1:
return None, False

hint, optional = members[0], True

# A parametrised hint like IPConnection[Introspection] is checked by its class
hint = get_origin(hint) or hint
if isinstance(hint, type) and issubclass(hint, Connection):
return hint, optional

return None, False
83 changes: 83 additions & 0 deletions src/fastcs/connections/connection_spec.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
import copy
from collections.abc import Callable
from typing import Generic, ParamSpec, Self

from typing_extensions import TypeVar

from fastcs.connections.connection import Connection

P = ParamSpec("P")
ConnectionT = TypeVar("ConnectionT", bound=Connection)
"""The `Connection` that a `ConnectionSpec` constructs"""


class ConnectionSpec(Generic[P, ConnectionT]):
"""A deferred call that constructs a named connection.

Example::

# MetaConnection(port=5000), to fill the controller argument "meta"
ConnectionSpec("meta", MetaConnection, port=5000)

Args:
name: The name of the connection, which is the controller argument it fills
connection_class: The connection class, or any callable returning one
args: Positional arguments for ``connection_class``
kwargs: Keyword arguments for ``connection_class``

"""

def __init__(
self,
name: str,
connection_class: Callable[P, ConnectionT],
/,
*args: P.args,
**kwargs: P.kwargs,
) -> None:
self.name = name
self.connection_class = connection_class
self.args = args
self.kwargs = kwargs

def __eq__(self, other: object) -> bool:
if not isinstance(other, ConnectionSpec):
return NotImplemented

return self._fields() == other._fields()

def __repr__(self) -> str:
class_name = getattr(self.connection_class, "__name__", self.connection_class)
arguments = [
repr(self.name),
str(class_name),
*(repr(arg) for arg in self.args),
*(f"{key}={value!r}" for key, value in self.kwargs.items()),
]
return f"ConnectionSpec({', '.join(arguments)})"

def _fields(self) -> tuple:
return (self.name, self.connection_class, self.args, self.kwargs)

def with_parent(self, parent_name: str) -> Self:
"""A copy of this spec, with its name prefixed by that of the connection that
discovered it.

Example::

spec.with_parent("odin").name # "meta" -> "odin_meta"

Args:
parent_name: The name of the connection whose introspection returned this

Returns:
The renamed copy

"""
spec = copy.copy(self)
spec.name = f"{parent_name}_{self.name}"
return spec

def construct(self) -> ConnectionT:
"""Construct the connection"""
return self.connection_class(*self.args, **self.kwargs)
Loading
Loading