plesty.lib.device.params

Configuration parameter system for Plesty device models.

Attributes

_PARSER_KINDS

Classes

`AutoResponseParser`	A response parser that autocasts raw responses to the expected data type.
`RegexResponseParser`	A response parser that takes the value out of a reply carrying text around it.
`DelimitedResponseParser`	A response parser that keeps one field of a delimited reply.
`Command`	Represents a command that can be sent to the device.
`ConfigParameter`	Represents a single configuration parameter for a device.
`ConfigGroup`	Represents a group of configuration parameters for a device.
`ConfigSystem`	Manage configuration parameters, groups, and validation rules.

Functions

`_as_text`(→ str)	Return response as text so a pattern or a separator can be applied to it.
`register_parser_kind`(→ None)	Make factory available to schemas as `"parser": {"kind": name, ...}`.
`parser_kinds`(→ list[str])	Return the response parser kinds a schema can currently name.
`resolve_parser`(...)	Turn a schema `parser` value into a `ResponseParser` instance.

Module Contents

class plesty.lib.device.params.AutoResponseParser

Bases: plesty.lib.device.device_utils.ResponseParser

A response parser that autocasts raw responses to the expected data type.

__call__(response, param=None, separator=',', **kwargs)

Attempt to autocast a value to the specified data type.

Supported types include basic types (int, float, str, bool) and iterable types like List[int], Tuple[float], etc. For iterable types, if the input is a string, it will be split by the specified separator.

Parameters:

response – The raw response value to be cast.
param – The config parameter providing the target dtype.
separator – Separator for splitting string inputs for iterable types.
**kwargs – Additional keyword arguments (unused).

plesty.lib.device.params._as_text(response: Any, encoding: str) → str

Return response as text so a pattern or a separator can be applied to it.

Parameters:

response (Any) – The raw device reply.
encoding (str) – Codec used when the reply arrives as bytes, as it does over serial.

Return type:

str

class plesty.lib.device.params.RegexResponseParser(pattern: str, group: int | str = 1, encoding: str = 'utf-8')

Bases: plesty.lib.device.device_utils.ResponseParser

A response parser that takes the value out of a reply carrying text around it.

The captured text is handed to AutoResponseParser, so the parameter’s declared dtype still performs the conversion — the pattern only decides which characters are the value.

Parameters:

pattern (str) – Regular expression searched in the raw response.
group (int | str) – Capture group holding the value, by number or by name. Group 0 is the whole match.
encoding (str) – Codec used to decode a bytes response before matching.

Raises:

ValueError – If the pattern is invalid or names a group it does not define. Both are raised here, at registration, rather than on the first query.

Compile pattern and check group against it.

group = 1

encoding = 'utf-8'

_auto

parse(response, param=None, **kwargs) → Any

Return the captured text of response, cast to the parameter dtype.

Return type:: Any

class plesty.lib.device.params.DelimitedResponseParser(index: int = 0, separator: str = ',', encoding: str = 'utf-8')

Bases: plesty.lib.device.device_utils.ResponseParser

A response parser that keeps one field of a delimited reply.

AutoResponseParser already splits a reply when the parameter’s dtype is a list or a tuple. This parser covers the other case: the reply carries several fields and the parameter is a single one of them.

Parameters:

index (int) – Zero-based field to keep. Negative indices count from the end.
separator (str) – String the reply is split on.
encoding (str) – Codec used to decode a bytes response before splitting.

Raises:

ValueError – If the index is not an integer or the separator is empty.

Check the field selection before any reply arrives.

index = 0

separator = ','

encoding = 'utf-8'

_auto

parse(response, param=None, **kwargs) → Any

Return the selected field of response, cast to the parameter dtype.

Return type:: Any

plesty.lib.device.params._PARSER_KINDS: dict[str, Callable[Ellipsis, plesty.lib.device.device_utils.ResponseParser]]

plesty.lib.device.params.register_parser_kind(name: str, factory: Callable[Ellipsis, plesty.lib.device.device_utils.ResponseParser]) → None

Make factory available to schemas as "parser": {"kind": name, ...}.

A device whose reply the built-in kinds cannot describe — a binary frame, a reply keyed by mnemonic — registers its own parser once, and every parameter then names it from the schema. The decoding rule stays next to command and unit instead of being re-solved per parameter in the solver.

Parameters:

name (str) – Kind name as written in a schema.
factory (Callable[Ellipsis, plesty.lib.device.device_utils.ResponseParser]) – Callable returning a ResponseParser. Schema keys other than kind are passed to it as keyword arguments.

Raises:

ValueError – If name already names a different factory.

Return type:

None

plesty.lib.device.params.parser_kinds() → list[str]

Return the response parser kinds a schema can currently name.

Return type:: list[str]

plesty.lib.device.params.resolve_parser(parser: Any) → plesty.lib.device.device_utils.ResponseParser | None

Turn a schema parser value into a ResponseParser instance.

Accepts what a schema can hold — a kind name, or a mapping of a kind and its configuration — as well as a ResponseParser instance passed from Python, which is returned unchanged.

Parameters:

parser (Any) – None, a kind name, a {"kind": ..., ...} mapping, or a ResponseParser instance.

Returns:

The parser instance, or None when no parser was configured.

Raises:

ValueError – If the kind is unknown or its configuration is rejected.
TypeError – If the value is of a type a schema cannot resolve.

Return type:

plesty.lib.device.device_utils.ResponseParser | None

class plesty.lib.device.params.Command

Represents a command that can be sent to the device.

name: str

command: str

required_params: List[str] | None = None

optional_params: List[str] | None = None

mode: str = 'write'

description: str | None = None

class plesty.lib.device.params.ConfigParameter

Represents a single configuration parameter for a device.

name: str

default: Any = None

value: Any = None

dtype: type | Any = None

unit: str | None = None

read_only: bool = False

write_only: bool = False

min_value: float | int | None = None

max_value: float | int | None = None

options: list[Any] | None = None

command: str | Command | None = None

parser: plesty.lib.device.device_utils.ResponseParser | None = None

description: str | None = None

class plesty.lib.device.params.ConfigGroup

Represents a group of configuration parameters for a device.

name: str

parameters: Dict[str, ConfigParameter]

command_prefix: str = ''

allowed_commands: List[Command] = []

description: str | None = None

class plesty.lib.device.params.ConfigSystem(param_schema=None, solver=None)

Manage configuration parameters, groups, and validation rules.

Initialize with optional schema and command solver.

_config

auto_parser

_cmd_solver = None

static _parse_command(command: Any) → str | Command | None

Parse command field from schema.

Parameters:: command (Any)
Return type:: str | Command | None

_register_param_dict(params: dict[str, Any], group_name: str) → None

Register all parameters in a schema dictionary into the target group.

Parameters:

params (dict[str, Any])
group_name (str)

Return type:

None

register_params_from_schema(schema: str | dict[str, Any]) → list[str]

Register parameters and groups from a schema path or dictionary.

Supported schema shapes:

Flat parameters (registered to default group):

{
    "param_a": {
        "type": "float",
        "default": 1.0
    }
}

Group map:

{
    "group_a": {
        "description": "Example group",
        "command_prefix": "CFG",
        "allowed_commands": [
            {
                "name": "set_mode",
                "command": "MODE",
                "mode": "write"
            }
        ],
        "parameters": {
            "param_a": {
                "type": "float",
                "default": 1.0
            }
        }
    }
}

Wrapped group map under “groups”:

{
    "groups": {
        "group_a": {
            "parameters": {
                "param_a": {
                    "type": "float"
                }
            }
        }
    }
}

Returns:: Registered parameter keys.
Return type:: list[str]
Parameters:: schema (str | dict[str, Any])

Register one configuration parameter after validating constraints.

parser accepts what a schema can hold — a kind name such as "regex", or a {"kind": ..., ...} mapping — as well as a ResponseParser instance; it is resolved to an instance here.

Returns the registered ConfigParameter and raises if the key already exists in the group or the provided metadata is invalid.

Parameters:

key (str)
group (str)
default (Any)
dtype (type | Any)
unit (str | None)
read_only (bool)
write_only (bool)
min_value (float | int | None)
max_value (float | int | None)
options (list[Any] | None)
command (str | Command | None)
parser (Any)
description (str | None)

Return type:

ConfigParameter

_validate_config_param(param: ConfigParameter) → None

Check the validity of the parameter.

Parameters:: param (ConfigParameter)
Return type:: None

register_config_group(group_name: str, command_prefix: str = '', allowed_commands: List[Command] | None = None, parameters: Dict[str, ConfigParameter] | None = None, description: str | None = None) → ConfigGroup

Register a named group of related configuration parameters.

Returns the registered ConfigGroup and raises if the group already exists or if any provided parameter metadata is invalid.

Parameters:

group_name (str)
command_prefix (str)
allowed_commands (List[Command] | None)
parameters (Dict[str, ConfigParameter] | None)
description (str | None)

Return type:

ConfigGroup

_check_register_min_max(min_value: float | int | None, max_value: float | int | None) → None

Check the validity of min and max values for a numeric parameter.

Parameters:

min_value (float | int | None)
max_value (float | int | None)

Return type:

None

_check_type(param: ConfigParameter, value: Any) → None

Check if a value matches the expected data type for a parameter.

Parameters:

param (ConfigParameter)
value (Any)

Return type:

None

_check_in_range(param: ConfigParameter, value: float | int) → None

Check if a numeric value is within the allowed range for a parameter.

Parameters:

param (ConfigParameter)
value (float | int)

Return type:

None

_check_in_options(param: ConfigParameter, value: Any) → None

Check if a categorical value is within the allowed options for a parameter.

Parameters:

param (ConfigParameter)
value (Any)

Return type:

None

_group_prefix(group: str) → str

Return the external prefix used in full keys.

Parameters:: group (str)
Return type:: str

_to_full_key(group: str, key: str) → str

Convert internal group/key to public full_key format.

Parameters:

group (str)
key (str)

Return type:

str

_resolve_key(key: str, group: str = 'default') → tuple[str, str]

Resolve external key to (group_name, param_key).

Grouped parameters must use full_key format group_prefix.param_key.

Parameters:

key (str)
group (str)

Return type:

tuple[str, str]

get_config_list(group: str = 'default') → list[str]

Return registered configuration keys.

For grouped schemas, keys are returned in full_key format group_prefix.param_key.

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

get_group_list() → list[str]

Return a list of registered configuration group names.

Return type:: list[str]

get_group(group: str) → ConfigGroup

Retrieve a registered configuration group by name.

Parameters:: group (str)
Return type:: ConfigGroup

parameter_docs() → dict[str, list[ConfigParameter]]

Return the registered parameters grouped by configuration group.

Returns:: Mapping of group name to its ConfigParameter objects, for documentation rendering. Empty groups are omitted.
Return type:: dict[str, list[ConfigParameter]]

get_config(key: str, group: str = 'default') → ConfigParameter

Retrieve a registered configuration parameter by key.

Parameters:

key (str)
group (str)

Return type:

ConfigParameter

set_config_value(key: str, value: Any, group: str = 'default') → None

Set the value of a registered configuration parameter.

Parameters:

key (str)
value (Any)
group (str)

Return type:

None

set_config_min_max(key: str, min_value: float | int | None, max_value: float | int | None, group: str = 'default') → None

Set the minimum and maximum allowed values for a numeric configuration parameter.

Parameters:

key (str)
min_value (float | int | None)
max_value (float | int | None)
group (str)

Return type:

None

get_config_value(key: str, group: str = 'default') → Any

Get the current value of a registered configuration parameter.

Parameters:

key (str)
group (str)

Return type:

Any

check_write_config(key: str, value: Any, group: str = 'default') → None

Check if a value can be written to a configuration parameter.

Parameters:

key (str)
value (Any)
group (str)

Return type:

None

check_query_config(key: str, group: str = 'default') → None

Check if a configuration parameter can be queried.

Parameters:

key (str)
group (str)

Return type:

None

param_summary(constraints: bool = True, description: bool = False, style: str = 'short', include_title: bool = True, filename=None) → str

Return parameter summary in short, markdown, or Google-style format.

Parameters:

constraints (bool) – Include range/options metadata where available.
description (bool) – Include parameter descriptions.
style (str) – One of short, md, or google.
include_title (bool) – Whether to include a title header in the output.
filename – Optional output file path.

Returns:

Rendered summary text.

Return type:

str