plestylib.device.params
=======================

.. py:module:: plestylib.device.params


Classes
-------

.. autoapisummary::

   plestylib.device.params.AutoResponseParser
   plestylib.device.params.Command
   plestylib.device.params.ConfigParameter
   plestylib.device.params.ConfigGroup
   plestylib.device.params.ConfigSystem


Module Contents
---------------

.. py:class:: AutoResponseParser

   Bases: :py:obj:`plestylib.device.device_utils.ResponseParser`


   A response parser that attempts to autocast the raw response to the expected data type defined in the config parameter.


   .. py:method:: __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 and each element will
      be cast to the appropriate type.

      :param value: The value to be cast, which can be of any type.
      :param dtype: The target data type to cast the value to. This can be a basic type or an iterable type.
      :param separator: The separator to use when splitting string inputs for iterable types (default is ",").



.. py:class:: Command

   Represents a command that can be sent to the device.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: command
      :type:  str


   .. py:attribute:: required_params
      :type:  List[str] | None
      :value: None



   .. py:attribute:: optional_params
      :type:  List[str] | None
      :value: None



   .. py:attribute:: mode
      :type:  str
      :value: 'write'



   .. py:attribute:: description
      :type:  str | None
      :value: None



.. py:class:: ConfigParameter

   Represents a single configuration parameter for a device.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: default
      :type:  Any
      :value: None



   .. py:attribute:: value
      :type:  Any
      :value: None



   .. py:attribute:: dtype
      :type:  type | None
      :value: None



   .. py:attribute:: unit
      :type:  str | None
      :value: None



   .. py:attribute:: read_only
      :type:  bool
      :value: False



   .. py:attribute:: write_only
      :type:  bool
      :value: False



   .. py:attribute:: min_value
      :type:  float | int | None
      :value: None



   .. py:attribute:: max_value
      :type:  float | int | None
      :value: None



   .. py:attribute:: options
      :type:  list[Any] | None
      :value: None



   .. py:attribute:: command
      :type:  str | None
      :value: None



   .. py:attribute:: parser
      :type:  plestylib.device.device_utils.ResponseParser | None
      :value: None



   .. py:attribute:: description
      :type:  str | None
      :value: None



.. py:class:: ConfigGroup

   Represents a group of configuration parameters for a device.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: parameters
      :type:  Dict[str, ConfigParameter]


   .. py:attribute:: command_prefix
      :type:  str
      :value: ''



   .. py:attribute:: allowed_commands
      :type:  List[Command]
      :value: []



   .. py:attribute:: description
      :type:  str | None
      :value: None



.. py:class:: ConfigSystem(param_schema=None, solver=None)

   Manage configuration parameters, groups, and validation rules.


   .. py:attribute:: _config


   .. py:attribute:: auto_parser


   .. py:attribute:: solver
      :value: None



   .. py:method:: _parse_command(command: Any) -> str | Command | None
      :staticmethod:


      Parse command field from schema.



   .. py:method:: _register_param_dict(params: dict[str, Any], group_name: str) -> None

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



   .. py:method:: register_params_from_schema(schema: str | dict[str, Any]) -> list[str]

      Register parameters and groups from a schema path or dictionary.

      Supported schema shapes:

          1) Flat parameters (registered to default group):

          .. code-block:: json

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

          2) Group map:

          .. code-block:: json

              {
                  "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
                          }
                      }
                  }
              }

          3) Wrapped group map under "groups":

          .. code-block:: json

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

      :returns: Registered parameter keys.
      :rtype: list[str]



   .. py:method:: register_config(key: str, group: str = 'default', default: Any = None, dtype: type | None = 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: Any = None, description: str | None = None) -> ConfigParameter

      Register one configuration parameter after validating constraints.

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



   .. py:method:: _validate_config_param(param: ConfigParameter) -> None

      Check the validity of the parameter.



   .. py:method:: 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.



   .. py:method:: _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.



   .. py:method:: _check_type(param: ConfigParameter, value: Any) -> None

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



   .. py:method:: _check_in_range(param: ConfigParameter, value: float | int) -> None

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



   .. py:method:: _check_in_options(param: ConfigParameter, value: Any) -> None

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



   .. py:method:: get_config_list(group: str = 'default') -> list[str]

      Return a list of registered configuration parameter keys for a specific group.



   .. py:method:: get_group_list() -> list[str]

      Return a list of registered configuration group names.



   .. py:method:: get_group(group: str) -> ConfigGroup

      Retrieve a registered configuration group by name.



   .. py:method:: get_config(key: str, group: str = 'default') -> ConfigParameter

      Retrieve a registered configuration parameter by key.



   .. py:method:: set_config_value(key: str, value: Any, group: str = 'default') -> None

      Set the value of a registered configuration parameter.



   .. py:method:: 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.



   .. py:method:: get_config_value(key: str, group: str = 'default') -> Any

      Get the current value of a registered configuration parameter.



   .. py:method:: check_write_config(key: str, value: Any, group: str = 'default') -> None

      Check if a value can be written to a configuration parameter without actually writing it.



   .. py:method:: check_query_config(key: str, group: str = 'default') -> None

      Check if a configuration parameter can be queried.



   .. py:method:: param_summary(constraints: bool = True, description: bool = False) -> str

      Return a summary string of the device's current configuration.



