plesty.lib.solver.scpi
======================

.. py:module:: plesty.lib.solver.scpi

.. autoapi-nested-parse::

   SCPI command solver for Plesty device models.



Classes
-------

.. autoapisummary::

   plesty.lib.solver.scpi.SCPISolver


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

.. py:class:: SCPISolver(qfmt: str = '{cmd}?', wfmt: str = '{cmd} {value}', bfmt: str = '{cmd}? {bound}')

   Bases: :py:obj:`plesty.lib.solver.CmdSolver`


   Build SCPI command strings for parameter writes and queries, and dispatch
   simple function operations described by a
   :class:`~plesty.lib.device.funcs.FuncMeta`.

   The existing parameter interface (``get_write_cmd``, ``get_query_cmd``,
   ``get_param_min_cmd``, ``get_param_max_cmd``) is unchanged.  The new
   :meth:`solve_func` method handles operations whose entire protocol
   exchange is captured by a single SCPI command and a scalar response,
   as declared through the ``"command"`` field in ``schema_func.json``.

   Operations that require multi-step exchanges or custom response parsing
   return ``None`` from :meth:`solve_func` and must be handled by the
   device's :class:`~plesty.lib.solver.OpSolver`.

   Initialize the SCPISolver with optional command format strings.

   :param qfmt: Format string for query commands, default ``"{cmd}?"``.
   :param wfmt: Format string for write commands, default ``"{cmd} {value}"``.
   :param bfmt: Format string for limit queries, default ``"{cmd}? {bound}"``.
                SCPI asks for a limit by passing ``MIN``/``MAX`` as the query
                *parameter* (``CORR:WAV? MIN``), not by appending a node
                (``CORR:WAV:MIN?``) — an instrument does not recognise the
                latter, returns nothing, and the read times out. Override only
                for an instrument that genuinely implements a limit subnode.


   .. py:attribute:: qfmt
      :value: '{cmd}?'



   .. py:attribute:: wfmt
      :value: '{cmd} {value}'



   .. py:attribute:: bfmt
      :value: '{cmd}? {bound}'



   .. py:method:: get_write_cmd(cfg_param: plesty.lib.solver.ConfigParameter, value: Any) -> str | None

      Build a SCPI write command for the given parameter value.

      :param cfg_param: Parameter metadata containing a SCPI command base.
      :param value: Value to serialize into command payload.

      :returns: A formatted SCPI write command string, or ``None`` when no command
                is defined on ``cfg_param``.

      .. rubric:: Notes

      Supported value types are ``str``, ``int``, ``float``, ``bool``,
      ``list``, and ``tuple``. Booleans are converted to ``1``/``0`` and
      sequences are comma-joined.



   .. py:method:: get_query_cmd(cfg_param: plesty.lib.solver.ConfigParameter) -> str | None

      Build a SCPI query command (``?`` suffix) for a parameter.

      :param cfg_param: Parameter metadata containing a SCPI command base.

      :returns: Query command string like ``<CMD>?``, or ``None`` if undefined.



   .. py:method:: get_param_min_cmd(cfg_param: plesty.lib.solver.ConfigParameter) -> str | None

      Build a SCPI command to query the parameter minimum value.

      :param cfg_param: Parameter metadata containing a SCPI command base.

      :returns: Query command string like ``<CMD>? MIN``, or ``None`` if undefined.



   .. py:method:: get_param_max_cmd(cfg_param: plesty.lib.solver.ConfigParameter) -> str | None

      Build a SCPI command to query the parameter maximum value.

      :param cfg_param: Parameter metadata containing a SCPI command base.

      :returns: Query command string like ``<CMD>? MAX``, or ``None`` if undefined.



   .. py:method:: solve_func(op_name: str, send_fn: Callable[[str], Any], func_meta: FuncMeta | None) -> dict[str, Any] | None

      Dispatch a function operation described by a
      :class:`~plesty.lib.device.funcs.FuncMeta`.

      Sends the mapped SCPI command via ``send_fn``, strips the raw
      string response, casts it to ``func_meta.output_dtype``, and
      returns a single-key response dictionary.  Returns ``None`` when
      ``func_meta`` is ``None``, signalling that the caller must handle
      the operation through its own custom logic.

      :param op_name: PLESTY operation name (used only for error messages).
      :param send_fn: Callable that accepts a raw SCPI command string and
                      returns the device response (e.g. ``tm.send_command``).
      :param func_meta: :class:`~plesty.lib.device.funcs.FuncMeta` instance
                        injected by the :class:`~plesty.lib.device.funcs.FunctionSystem`
                        via the request dictionary, or ``None`` for custom operations.

      :returns: ``{output_key: cast_value}`` when ``func_meta`` is present,
                ``None`` otherwise.

      :raises ValueError: If the raw response cannot be cast to
          ``func_meta.output_dtype``.