plesty.lib.device.device_utils
==============================

.. py:module:: plesty.lib.device.device_utils

.. autoapi-nested-parse::

   Utility functions for device connectivity and configuration.



Attributes
----------

.. autoapisummary::

   plesty.lib.device.device_utils.OP_KINDS
   plesty.lib.device.device_utils.EXPOSE_MARKER
   plesty.lib.device.device_utils.OP_KIND_MARKER


Classes
-------

.. autoapisummary::

   plesty.lib.device.device_utils.ResponseParser
   plesty.lib.device.device_utils.OpKind


Functions
---------

.. autoapisummary::

   plesty.lib.device.device_utils.operatable
   plesty.lib.device.device_utils.error_check
   plesty.lib.device.device_utils.get_local_ip
   plesty.lib.device.device_utils.op_kind_of
   plesty.lib.device.device_utils.expose_to_api


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

.. py:class:: ResponseParser

   Parser to be used in the base device class. Once registered along with a config parameter,
   the parser will be called to parse the raw response from `_query_()` function of the device.
   The parsed result will be used to update the corresponding configuration parameter in the
   `query()` function.


   .. py:method:: __call__(response, param, **kwargs) -> Any

      Parse the raw response from the device and return a structured result.



   .. py:method:: parse(response, param, **kwargs) -> Any
      :abstractmethod:


      Alias for __call__, allowing explicit parsing calls.



.. py:function:: operatable(func: Callable[Ellipsis, Any]) -> Callable[Ellipsis, Any]

   Decorator that checks device operatability before executing the wrapped function.


.. py:function:: error_check(func: Callable[Ellipsis, Any]) -> Callable[Ellipsis, Any]

   Decorator that checks for device errors after executing the wrapped function.


.. py:function:: get_local_ip() -> str

   Return the local IP address of this machine.


.. py:data:: OP_KINDS
   :type:  tuple[str, Ellipsis]
   :value: ('read', 'motion', 'acquire', 'lifecycle', 'control', 'configure')


.. py:data:: EXPOSE_MARKER
   :value: '__plesty_expose_in_api__'


.. py:data:: OP_KIND_MARKER
   :value: '__plesty_op_kind__'


.. py:class:: OpKind

   The class of an operation and, for motion, what the test needs to drive it.

   :ivar kind: One of :data:`OP_KINDS`. ``read`` returns a value and changes
               nothing. ``motion`` moves a part whose position a parameter reports.
               ``acquire`` emits or exposes (a shutter, an exposure) and produces
               data. ``lifecycle`` is homing, reset, calibration — done once, never
               on repeat. ``control`` is stop/abort — meaningful only with a motion
               in flight. ``configure`` changes a setting that outlives the call.
   :ivar position_key: Motion only — the configuration key that reports where
                       the moving part is, in the same units the operation takes.
   :ivar target: Motion only — the argument that receives the target. Defaults
                 to the operation's first required argument.
   :ivar relative: Motion only — the target is a signed step from the current
                   position rather than an absolute position.
   :ivar step: Motion only — how far the field test may move the part, in
               ``position_key`` units. ``None`` leaves it to the test configuration.



   .. py:attribute:: kind
      :type:  str
      :value: 'read'



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



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



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



   .. py:attribute:: step
      :type:  float | None
      :value: None



   .. py:method:: __post_init__() -> None

      Reject a kind nothing knows how to handle.



   .. py:property:: acts
      :type: bool


      Whether the operation changes the world rather than only reading it.


   .. py:method:: with_defaults(**fields: Any) -> OpKind

      Return a copy where every ``None`` field is filled from *fields*.



   .. py:method:: to_dict() -> dict[str, Any]

      Serialise for a describe payload or a report.



   .. py:method:: from_options(options: dict[str, Any] | None) -> OpKind
      :classmethod:


      Build from registration options or a schema entry (``kind``, ``position_key``, …).

      :param options: A mapping that may carry the fields of this class. Unknown
                      keys are ignored; a missing ``kind`` is ``read``.



.. py:function:: op_kind_of(func: Any) -> OpKind

   Return the :class:`OpKind` a method was exposed with (``read`` when undeclared).


.. py:function:: expose_to_api(func: Any = None, *, kind: str = 'read', position_key: str | None = None, target: str | None = None, relative: bool = False, step: float | None = None) -> Any

   Mark a device method so it is listed by the describe endpoint.

   Bare ``@expose_to_api`` marks a ``read``. With arguments it also declares
   what the operation does, which the field test needs to call it unattended::

       @expose_to_api(kind="motion", position_key="MO.Position")
       def move_absolute(self, position: float) -> float: ...

       @expose_to_api(kind="motion", position_key="MO.Position", relative=True)
       def move_relative(self, step: float) -> float: ...

       @expose_to_api(kind="lifecycle")
       def home_stage(self) -> bool: ...

   :param func: The method, when used without parentheses.
   :param kind: One of :data:`OP_KINDS`.
   :param position_key: Motion — the parameter that reports the moving part's position.
   :param target: Motion — the argument taking the target; the first required one by default.
   :param relative: Motion — the target is a step from the current position.
   :param step: Motion — how far the field test may move, in ``position_key`` units.