plesty.lib.device.device_utils

Utility functions for device connectivity and configuration.

Attributes

`OP_KINDS`
`EXPOSE_MARKER`
`OP_KIND_MARKER`
`OP_BUDGET_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

`dtype_name`(→ str)	Return the wire name of a declared data type.
`_is_union`(→ bool)	Whether dtype is a union, written either way.
`jsonable`(→ Any)	Return value as something `json.dumps()` accepts.
`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.
`op_budget_of`(→ float \| None)	Return the seconds an operation declared it may take, or `None`.

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.dtype_name(dtype: Any) → str

Return the wire name of a declared data type.

A schema declares a type as a Python type, a typing construct, or already as a string. A caller on the far side of the device protocol has to switch on it, so it arrives as a name and never as a <class 'float'> repr.

A union names its members, float | None, and not the construct it was written with. __name__ on a typing construct is the construct’s own name from Python 3.10 on, so Optional[float] arrived as "Optional" and Union[int, str] as "Union": the member types were dropped, and a reader switching on the name could not tell a number from anything else. A schema written the modern way, float | None, was unaffected — it has no __name__ and fell through to str() — so which of two equivalent spellings a module used decided whether its parameter got a numeric editor.

Parameters:: dtype (Any) – The declared type, or None.
Returns:: The type’s name; "Any" when nothing was declared.
Return type:: str

plesty.lib.device.device_utils._is_union(dtype: Any) → bool

Whether dtype is a union, written either way.

Parameters:: dtype (Any)
Return type:: bool

plesty.lib.device.device_utils.jsonable(value: Any) → Any

Return value as something json.dumps() accepts.

Schema defaults, options and bounds are whatever the module declared — a numpy scalar, an enum member, a tuple. They cross the wire as documentation, so a value JSON has no form for is described rather than dropped: a reader learns what the default is even when it cannot be one.

Parameters:: value (Any) – The value to convert.
Returns:: The value unchanged when JSON already holds it, a list or dict when it is a container, else its str().
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__'

plesty.lib.device.device_utils.OP_BUDGET_MARKER = '__plesty_op_budget_s__'

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, budget_s: 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: ...

@expose_to_api(kind="acquire", budget_s=120.0)
def acquire(self) -> None: ...

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.
budget_s (float | None) – How long this operation may take, in seconds. Published by describe so a client waits that long instead of its own default. Declare it on anything that can outrun a few seconds: without it the caller picks a number knowing nothing about the instrument, and an operation that merely ran long is reported as failed while the device completes it.

Return type:

Any

plesty.lib.device.device_utils.op_budget_of(func: Any) → float | None

Return the seconds an operation declared it may take, or None.

Parameters:: func (Any)
Return type:: float | None