plesty.lib.device.funcs

Function system for registering and dispatching device operations.

Attributes

`_FUNC_META_DTYPE_MAP`
`_DOC_ARG_SECTIONS`
`_DOC_RETURN_SECTIONS`
`_KNOWN_DOC_SECTIONS`
`_DOC_SECTION_RE`
`_DOC_ARG_RE`
`_PARAMS_REPR`
`_FRAMEWORK_DOC_MODULES`
`_STANDARD_METHOD_NAMES`

Classes

`FuncMeta`	Link a PLESTY operation to its device-protocol command.
`FuncParam`	Data class to hold function argument metadata.
`FuncOutput`	Data class to hold function output metadata.
`FuncDoc`	One documented operation, regardless of how it is implemented.
`FunctionSystem`	Dynamic operation-to-function adapter for TCP message-based APIs.

Functions

`_parse_google_docstring`(→ tuple[dict[str, str], str])	Parse a Google-style docstring into per-argument and return descriptions.
`_parse_arg_lines`(→ dict[str, str])	Parse the body lines of a Google `Args:` section into `{name: desc}`.
`_first_paragraph`(→ str)	Return the first non-empty paragraph of a docstring section, collapsed.
`_compact_repr`(→ str)	Return a size-bounded repr of value for log lines.

Module Contents

plesty.lib.device.funcs._FUNC_META_DTYPE_MAP: dict[str, type]

plesty.lib.device.funcs._DOC_ARG_SECTIONS = ('args', 'arguments', 'parameters')

plesty.lib.device.funcs._DOC_RETURN_SECTIONS = ('returns', 'return', 'yields')

plesty.lib.device.funcs._KNOWN_DOC_SECTIONS

plesty.lib.device.funcs._DOC_SECTION_RE

plesty.lib.device.funcs._DOC_ARG_RE

plesty.lib.device.funcs._parse_google_docstring(docstring: str) → tuple[dict[str, str], str]

Parse a Google-style docstring into per-argument and return descriptions.

Parameters:: docstring (str) – A normalized (dedented) docstring.
Returns:: A ({argument_name: description}, return_description) tuple. Both are empty when the docstring has no Args/Returns sections.
Return type:: tuple[dict[str, str], str]

plesty.lib.device.funcs._parse_arg_lines(lines: list[str]) → dict[str, str]

Parse the body lines of a Google Args: section into {name: desc}.

Parameters:: lines (list[str])
Return type:: dict[str, str]

plesty.lib.device.funcs._first_paragraph(lines: list[str]) → str

Return the first non-empty paragraph of a docstring section, collapsed.

Parameters:: lines (list[str])
Return type:: str

class plesty.lib.device.funcs.FuncMeta

Link a PLESTY operation to its device-protocol command.

FuncMeta carries the minimum information needed for a generic solver (e.g. SCPISolver) to dispatch a single-command, single-scalar-output operation without any hand-written dispatch logic. It is built automatically from a "command" field in schema_func.json and injected into the request dictionary by the FunctionSystem.

Complex operations that require multi-step exchanges or custom response parsing should omit "command" from their schema entry and implement the logic inside a custom OpSolver.

Variables:

name – Operation name as registered in the function schema.
command – Raw device command string to send (e.g. "MEAS:POW?").
output_key – Key under which the parsed value is returned in the response dictionary (e.g. "power").
output_dtype – Python type used to cast the raw string response. Defaults to float for scalar measurement operations.

name: str

command: str

output_key: str

output_dtype: type

class plesty.lib.device.funcs.FuncParam

Data class to hold function argument metadata.

name: str

dtype: Any

unit: str = ''

default: Any = None

required: bool = True

options: list[Any] | None = None

range: tuple[Any, Any] | None = None

shape: tuple[Any, Ellipsis] | None = None

item_dtype: Any = None

description: str = ''

class plesty.lib.device.funcs.FuncOutput

Data class to hold function output metadata.

name: str

dtype: Any

unit: str = ''

required: bool = True

code_mapping: dict[Any, str] | None = None

range: tuple[Any, Any] | None = None

shape: tuple[Any, Ellipsis] | None = None

item_dtype: Any = None

headers: list[plesty.lib.data.TableHeader] | None = None

description: str = ''

class plesty.lib.device.funcs.FuncDoc

One documented operation, regardless of how it is implemented.

Unifies schema-registered operations and @expose_to_api custom methods into a single shape so documentation renders them identically.

Variables:

name – Operation / method name.
source – "schema" for a registered operation, "custom" for an @expose_to_api (or public child) method.
description – Human-readable description (from the schema or docstring).
iparams – Input parameters.
oparams – Output values.
kind – What the operation does to the world (see OpKind); read when the module declared nothing.

name: str

source: str

description: str

iparams: list[FuncParam]

oparams: list[FuncOutput]

kind: plesty.lib.device.device_utils.OpKind

plesty.lib.device.funcs._PARAMS_REPR

plesty.lib.device.funcs._FRAMEWORK_DOC_MODULES

plesty.lib.device.funcs._STANDARD_METHOD_NAMES = ('connect', 'disconnect', 'identity', 'check_errors', 'check_operatability', 'write', 'query',...

plesty.lib.device.funcs._compact_repr(value: Any) → str

Return a size-bounded repr of value for log lines.

Parameters:: value (Any)
Return type:: str

class plesty.lib.device.funcs.FunctionSystem(op_schema=None, solver: Callable[[dict[str, Any]], dict[str, Any]] | None = None)

Dynamic operation-to-function adapter for TCP message-based APIs.

This class allows developers to register operations as Python callables, where: - iparams is a list of FuncParam objects describing input schema. - oparams is a list of FuncOutput objects describing output schema. - the runtime request format is {'op': <operation>, 'parameters': <dict>}.

Registered functions can be called with a parameter dictionary, keyword arguments, or positional arguments (mapped by iparams order). Each call returns a response dictionary from the configured executor.

Initialize the function system.

Parameters:

op_schema – Optional operation schema (path or dict) to register.
solver (Callable[[dict[str, Any]], dict[str, Any]] | None) – Callable used to send a message dictionary and return a response dictionary.

_functions: dict[str, Any]

_op_solver = None

bind_op_solver(solver: Callable[[dict[str, Any]], dict[str, Any]]) → None

Bind or replace the callable used to execute operation requests.

Parameters:: solver (Callable[[dict[str, Any]], dict[str, Any]]) – Callable receiving request dictionary and returning response dictionary.
Return type:: None

bind_op_response_parser(op_name: str, parser: plesty.lib.device.device_utils.ResponseParser) → None

Bind a response parser to a registered operation.

Parameters:

op_name (str) – Name of the registered operation.
parser (plesty.lib.device.device_utils.ResponseParser) – ResponseParser instance to apply to the operation’s raw response.

Return type:

None

register_func(func_name: str, iparams: list[FuncParam] | None = None, oparams: list[FuncOutput] | None = None, resp_parser: plesty.lib.device.device_utils.ResponseParser | None = None, func_meta: FuncMeta | None = None, **kwargs) → None

Register an operation as a callable function on this instance.

Parameters:

func_name (str) – Operation name and exported function name.
iparams (list[FuncParam] | None) – Input schema as [FuncParam(...), ...].
oparams (list[FuncOutput] | None) – Output schema as [FuncOutput(...), ...].
resp_parser (plesty.lib.device.device_utils.ResponseParser | None) – Optional parser applied to executor response.
func_meta (FuncMeta | None) – Optional FuncMeta built from a "command" field in the schema. When present it is injected into the request dictionary so that a generic solver can dispatch the operation without hand-written dispatch logic.
kwargs – Registration options for future extension. These options are stored as metadata and are not sent in runtime requests. description is read back by function_docs(), so an operation registered by hand documents itself the same way a schema-registered one does.

Return type:

None

_parse_iparams_from_schema(iparams_schema: Any) → list[FuncParam]

Parse operation input schema into FuncParam objects.

Parameters:: iparams_schema (Any)
Return type:: list[FuncParam]

_parse_oparams_from_schema(oparams_schema: Any) → list[FuncOutput]

Parse operation output schema into FuncOutput objects.

Parameters:: oparams_schema (Any)
Return type:: list[FuncOutput]

function_docs() → list[FuncDoc]

Return the device’s callable operations as a unified FuncDoc list.

Combines schema-registered operations (source="schema") with the device’s own @expose_to_api methods (source="custom"). Framework plumbing declared on the plesty base classes (connect, write, query, identity, …) is excluded — this is the device’s API surface, not the framework’s. Registered operations come first.

Returns:: One FuncDoc per documented operation.
Return type:: list[FuncDoc]

standard_method_docs() → list[FuncDoc]

Return the common device API (connect, write, query, …).

These framework methods are shared by every device and are documented as their own “standard methods” section, separate from the device’s own operations (function_docs()).

Returns:: One FuncDoc (source="standard") per available standard method, in a stable order.
Return type:: list[FuncDoc]

_method_doc(name: str, func: Any, source: str) → FuncDoc

Build a FuncDoc for a plain method from its signature/docstring.

Parameters:

name (str)
func (Any)
source (str)

Return type:

FuncDoc

register_from_op_schema(schema_path: str, resp_parsers: dict[str, plesty.lib.device.device_utils.ResponseParser] | None = None, **registration_options) → list[str]

Register multiple operations from a JSON schema file.

Expected schema format:

{
    "operation_name": {
        "iparams": {"arg_name": {"type": "float"}},
        "oparams": {"out_name": {"type": "str"}}
    }
}

Parameters:

schema_path (str) – Path to JSON schema file.
resp_parsers (dict[str, plesty.lib.device.device_utils.ResponseParser] | None) – Optional map {operation_name: ResponseParser}.
**registration_options – Additional options forwarded to register_func.

Returns:

Names of registered operations.

Return type:

list[str]

static _parse_func_meta(op_name: str, op_cfg: dict, oparams: list[FuncOutput]) → FuncMeta | None

Build a FuncMeta from a schema operation entry, or None.

Returns None when no "command" key is present, indicating the operation requires custom solver logic.

Parameters:

op_name (str)
op_cfg (dict)
oparams (list[FuncOutput])

Return type:

FuncMeta | None

_normalize_iparams(iparams: list[Any]) → list[FuncParam]

Normalize input schema into FuncParam objects.

Parameters:: iparams (list[Any])
Return type:: list[FuncParam]

_normalize_oparams(oparams: list[Any]) → list[FuncOutput]

Normalize output schema into FuncOutput objects.

Parameters:: oparams (list[Any])
Return type:: list[FuncOutput]

static _type_name(dtype: Any) → str

Return a human-readable type name.

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

static _annotation_name(annotation: Any) → str

Return a stable name for a function annotation.

Parameters:: annotation (Any)
Return type:: str

static _callable_description(func: Any) → str

Return a normalized docstring for a callable when available.

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

static _resolved_signature(func: Any) → inspect.Signature

Resolve a callable signature with evaluated type hints when possible.

Parameters:: func (Any)
Return type:: inspect.Signature

_signature_output_docs(signature: inspect.Signature, default_type: str | None = None) → list[dict[str, Any]]

Build summary output metadata from a function return annotation.

Parameters:

signature (inspect.Signature)
default_type (str | None)

Return type:

list[dict[str, Any]]

static _output_signature(op_doc: dict[str, Any]) → str

Render operation outputs for a one-line function signature.

Parameters:: op_doc (dict[str, Any])
Return type:: str

_collect_child_public_methods(existing_names: set[str]) → dict[str, dict[str, Any]]

Collect public methods defined on child classes and not registered as operations.

Parameters:: existing_names (set[str])
Return type:: dict[str, dict[str, Any]]

_collect_exposed_api_methods(existing_names: set[str]) → dict[str, dict[str, Any]]

Collect methods marked with expose_to_api and not already documented.

Parameters:: existing_names (set[str])
Return type:: dict[str, dict[str, Any]]

static _is_plesty_array_dtype(dtype: Any) → bool

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

static _is_plesty_table2d_dtype(dtype: Any) → bool

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

_parse_table_headers(headers_cfg: Any) → list[plesty.lib.data.TableHeader] | None

Parameters:: headers_cfg (Any)
Return type:: list[plesty.lib.data.TableHeader] | None

_cast_plesty_array(value: Any) → plesty.lib.data.PlestyArray

Parameters:: value (Any)
Return type:: plesty.lib.data.PlestyArray

_cast_table_value(value: Any, dtype: Any)

Parameters:

value (Any)
dtype (Any)

_cast_plesty_table2d(value: Any, output_meta: FuncOutput) → plesty.lib.data.PlestyTable2D

Parameters:

value (Any)
output_meta (FuncOutput)

Return type:

plesty.lib.data.PlestyTable2D

_build_operation_doc(func_name, iparams, oparams, resp_parser) → str

Build detailed user-facing documentation text for a registered operation.

Return type:: str

func_summary(style: str = 'short', include_title: bool = True, filename=None) → str | dict[str, dict[str, Any]]

Summarize all registered operations.

Parameters:

style (str) – One of short, md, dict, or google.
include_title (bool) – Whether to include a title header in the output.
filename – Optional path to save the summary text.

Returns:

Operation documentation.

Return type:

str | dict[str, dict[str, Any]]

Notes

The summary is built from registration metadata and can be used as user-facing documentation for available operations.

_normalize_args(func_name: str, iparams: list[FuncParam], args, kwargs) → dict[str, Any]

Normalize incoming call arguments into a single parameters dictionary.

Accepts one dictionary positional argument, keyword arguments, or positional arguments mapped by iparams order.

Parameters:

func_name (str)
iparams (list[FuncParam])

Return type:

dict[str, Any]

_validate_input(func_name: str, iparams: list[FuncParam], params: dict[str, Any]) → dict[str, Any]

Validate and cast input values based on registered iparams schema.

Raises:

KeyError – If unexpected keys are provided.
ValueError – If type casting fails.

Parameters:

func_name (str)
iparams (list[FuncParam])
params (dict[str, Any])

Return type:

dict[str, Any]

_validate_output(func_name: str, oparams: list[FuncOutput], response: dict[str, Any]) → dict[str, Any]

Validate and cast response fields against registered oparams schema.

Raises:

KeyError – If expected response keys are missing.
ValueError – If type casting fails.

Parameters:

func_name (str)
oparams (list[FuncOutput])
response (dict[str, Any])

Return type:

dict[str, Any]

_create_func(func_name, iparams, oparams): Create the executable operation function for a registered operation.