plestylib.device.funcs
======================

.. py:module:: plestylib.device.funcs


Classes
-------

.. autoapisummary::

   plestylib.device.funcs.FuncParam
   plestylib.device.funcs.FuncOutput
   plestylib.device.funcs.FunctionSystem


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

.. py:class:: FuncParam

   Data class to hold function argument metadata.


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


   .. py:attribute:: dtype
      :type:  Any


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



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



   .. py:attribute:: required
      :type:  bool
      :value: True



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



   .. py:attribute:: range
      :type:  tuple[Any, Any]
      :value: None



   .. py:attribute:: shape
      :type:  tuple[Any, Ellipsis] | None
      :value: None



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



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



.. py:class:: FuncOutput

   Data class to hold function output metadata.


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


   .. py:attribute:: dtype
      :type:  Any


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



   .. py:attribute:: required
      :type:  bool
      :value: True



   .. py:attribute:: code_mapping
      :type:  dict[Any, str]
      :value: None



   .. py:attribute:: range
      :type:  tuple[Any, Any]
      :value: None



   .. py:attribute:: shape
      :type:  tuple[Any, Ellipsis] | None
      :value: None



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



   .. py:attribute:: headers
      :type:  list[plestylib.data.TableHeader] | None
      :value: None



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



.. py:class:: FunctionSystem(op_schema=None, solver: Callable[[dict[str, Any]], dict[str, Any]] = 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.

   :param solver: Callable used to send a message dictionary and
                  return a response dictionary.


   .. py:attribute:: _functions


   .. py:attribute:: _solver
      :value: None



   .. py:method:: bind_op_solver(solver: Callable[[dict[str, Any]], dict[str, Any]])

      Bind or replace the callable used to execute operation requests.

      :param solver: Callable receiving request dictionary and
                     returning response dictionary.



   .. py:method:: bind_op_response_parser(op_name: str, parser: plestylib.device.device_utils.ResponseParser)

      Bind a response parser to a registered operation.

      :param op_name: Name of the registered operation.
      :param parser: ResponseParser instance to apply to the operation's raw response.



   .. py:method:: register_func(func_name: str, iparams: list[FuncParam] = None, oparams: list[FuncOutput] = None, resp_parser: plestylib.device.device_utils.ResponseParser = None, **kwargs)

      Register an operation as a callable function on this instance.

      :param func_name: Operation name and exported function name.
      :param iparams: Input schema as ``[FuncParam(...), ...]``.
      :param oparams: Output schema as ``[FuncOutput(...), ...]``.
      :param resp_parser: Optional parser applied to executor response.
      :param kwargs: Registration options for future extension. These options
                     are stored as metadata and are not sent in runtime requests.



   .. py:method:: _parse_iparams_from_schema(iparams_schema: Any) -> list[FuncParam]

      Parse operation input schema into FuncParam objects.



   .. py:method:: _parse_oparams_from_schema(oparams_schema: Any) -> list[FuncOutput]

      Parse operation output schema into FuncOutput objects.



   .. py:method:: register_from_op_schema(schema_path: str, resp_parsers: dict[str, plestylib.device.device_utils.ResponseParser] = None, **registration_options) -> list[str]

      Register multiple operations from a JSON schema file.

      Expected schema format:

          .. code-block:: json

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

      :param schema_path: Path to JSON schema file.
      :param resp_parsers: Optional map {operation_name: ResponseParser}.
      :param \*\*registration_options: Additional options forwarded to register_func.

      :returns: Names of registered operations.
      :rtype: list[str]



   .. py:method:: _normalize_iparams(iparams: list[Any]) -> list[FuncParam]

      Normalize input schema into ``FuncParam`` objects.



   .. py:method:: _normalize_oparams(oparams: list[Any]) -> list[FuncOutput]

      Normalize output schema into ``FuncOutput`` objects.



   .. py:method:: _type_name(dtype: Any) -> str
      :staticmethod:


      Return a human-readable type name.



   .. py:method:: _is_plesty_array_dtype(dtype: Any) -> bool
      :staticmethod:



   .. py:method:: _is_plesty_table2d_dtype(dtype: Any) -> bool
      :staticmethod:



   .. py:method:: _parse_table_headers(headers_cfg: Any) -> list[plestylib.data.TableHeader] | None


   .. py:method:: _cast_plesty_array(value: Any) -> plestylib.data.PlestyArray


   .. py:method:: _cast_table_value(value: Any, dtype: Any)


   .. py:method:: _cast_plesty_table2d(value: Any, output_meta: FuncOutput) -> plestylib.data.PlestyTable2D


   .. py:method:: _build_operation_doc(func_name, iparams, oparams, resp_parser) -> str

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



   .. py:method:: func_summary(style: str = 'short', filename=None) -> str | dict[str, dict[str, Any]]

      Summarize all registered operations.

      :param style: If "short", return a brief summary.
                    If "md", return a detailed documentation in Markdown format.
                    If "dict", return a structured dictionary.
                    If "google", return a detailed documentation in Google style docstring format with function signatures.
      :param filename: Optional path to save the summary text.

      :returns: Operation documentation.
      :rtype: str | dict[str, dict[str, Any]]

      .. rubric:: Notes

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



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



   .. py:method:: _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.
      :raises ValueError: If type casting fails.



   .. py:method:: _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.
      :raises ValueError: If type casting fails.



   .. py:method:: _create_func(func_name, iparams, oparams)

      Create the executable operation function for a registered operation.



