plesty.lib.device.device_utils

Utility functions for device connectivity and configuration.

Attributes

`OP_KINDS`
`EXPOSE_MARKER`
`OP_KIND_MARKER`

Classes

`ResponseParser`	Parser to be used in the base device class. Once registered along with a config parameter,
`OpKind`	The class of an operation and, for motion, what the test needs to drive it.

Functions

`operatable`(→ Callable[Ellipsis, Any])	Decorator that checks device operatability before executing the wrapped function.
`error_check`(→ Callable[Ellipsis, Any])	Decorator that checks for device errors after executing the wrapped function.
`get_local_ip`(→ str)	Return the local IP address of this machine.
`op_kind_of`(→ OpKind)	Return the `OpKind` a method was exposed with (`read` when undeclared).
`expose_to_api`(→ Any)	Mark a device method so it is listed by the describe endpoint.

Module Contents

class plesty.lib.device.device_utils.ResponseParser

Parser to be used in the base device class. Once registered along with a config parameter, the parser will be called to parse the raw response from _query_() function of the device. The parsed result will be used to update the corresponding configuration parameter in the query() function.

__call__(response, param, **kwargs) → Any

Parse the raw response from the device and return a structured result.

Return type:: Any

abstractmethod parse(response, param, **kwargs) → Any

Alias for __call__, allowing explicit parsing calls.

Return type:: Any

plesty.lib.device.device_utils.operatable(func: Callable[Ellipsis, Any]) → Callable[Ellipsis, Any]

Decorator that checks device operatability before executing the wrapped function.

Parameters:: func (Callable[Ellipsis, Any])
Return type:: Callable[Ellipsis, Any]

plesty.lib.device.device_utils.error_check(func: Callable[Ellipsis, Any]) → Callable[Ellipsis, Any]

Decorator that checks for device errors after executing the wrapped function.

Parameters:: func (Callable[Ellipsis, Any])
Return type:: Callable[Ellipsis, Any]

plesty.lib.device.device_utils.get_local_ip() → str

Return the local IP address of this machine.

Return type:: str

plesty.lib.device.device_utils.OP_KINDS: tuple[str, Ellipsis] = ('read', 'motion', 'acquire', 'lifecycle', 'control', 'configure')

plesty.lib.device.device_utils.EXPOSE_MARKER = '__plesty_expose_in_api__'

plesty.lib.device.device_utils.OP_KIND_MARKER = '__plesty_op_kind__'

class plesty.lib.device.device_utils.OpKind

The class of an operation and, for motion, what the test needs to drive it.

Variables:

kind – One of OP_KINDS. read returns a value and changes nothing. motion moves a part whose position a parameter reports. acquire emits or exposes (a shutter, an exposure) and produces data. lifecycle is homing, reset, calibration — done once, never on repeat. control is stop/abort — meaningful only with a motion in flight. configure changes a setting that outlives the call.
position_key – Motion only — the configuration key that reports where the moving part is, in the same units the operation takes.
target – Motion only — the argument that receives the target. Defaults to the operation’s first required argument.
relative – Motion only — the target is a signed step from the current position rather than an absolute position.
step – Motion only — how far the field test may move the part, in position_key units. None leaves it to the test configuration.

kind: str = 'read'

position_key: str | None = None

target: str | None = None

relative: bool = False

step: float | None = None

__post_init__() → None

Reject a kind nothing knows how to handle.

Return type:: None

property acts: bool

Whether the operation changes the world rather than only reading it.

Return type:: bool

with_defaults(**fields: Any) → OpKind

Return a copy where every None field is filled from fields.

Parameters:: fields (Any)
Return type:: OpKind

to_dict() → dict[str, Any]

Serialise for a describe payload or a report.

Return type:: dict[str, Any]

classmethod from_options(options: dict[str, Any] | None) → OpKind

Build from registration options or a schema entry (kind, position_key, …).

Parameters:: options (dict[str, Any] | None) – A mapping that may carry the fields of this class. Unknown keys are ignored; a missing kind is read.
Return type:: OpKind

plesty.lib.device.device_utils.op_kind_of(func: Any) → OpKind

Return the OpKind a method was exposed with (read when undeclared).

Parameters:: func (Any)
Return type:: OpKind

plesty.lib.device.device_utils.expose_to_api(func: Any = None, *, kind: str = 'read', position_key: str | None = None, target: str | None = None, relative: bool = False, step: float | None = None) → Any

Mark a device method so it is listed by the describe endpoint.

Bare @expose_to_api marks a read. With arguments it also declares what the operation does, which the field test needs to call it unattended:

@expose_to_api(kind="motion", position_key="MO.Position")
def move_absolute(self, position: float) -> float: ...

@expose_to_api(kind="motion", position_key="MO.Position", relative=True)
def move_relative(self, step: float) -> float: ...

@expose_to_api(kind="lifecycle")
def home_stage(self) -> bool: ...

Parameters:

func (Any) – The method, when used without parentheses.
kind (str) – One of OP_KINDS.
position_key (str | None) – Motion — the parameter that reports the moving part’s position.
target (str | None) – Motion — the argument taking the target; the first required one by default.
relative (bool) – Motion — the target is a step from the current position.
step (float | None) – Motion — how far the field test may move, in position_key units.

Return type:

Any