plesty.lib.service.tcp_ip_client
================================

.. py:module:: plesty.lib.service.tcp_ip_client

.. autoapi-nested-parse::

   ZeroMQ-based TCP/IP client for remote device control.



Classes
-------

.. autoapisummary::

   plesty.lib.service.tcp_ip_client.DeviceTCPIPClient


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

.. py:class:: DeviceTCPIPClient(address='tcp://localhost:5555', timeout=5000, resources=None, client_id: str | None = None, connect_kwargs: dict | None = None)

   ZeroMQ-based client for remote device control.

   This client provides a transparent interface to a remote device server.
   Methods can be invoked as if the device were local.

   The server address it was opened with stays available as :attr:`address`.

   Features:
       - Standard query/write interface
       - Arbitrary remote function calls
       - Automatic method discovery and binding
       - Timeout support
       - Structured error handling

   Initialize the device client.

   :param address: Server address.
   :param timeout: Receive timeout in milliseconds.
   :param resources: Resource request as a string, flat collection, or nested dict tree.
   :param client_id: Optional stable client identity for server-side routing.
   :param connect_kwargs: Optional metadata sent during connect handshake.


   .. py:attribute:: ctx


   .. py:attribute:: socket


   .. py:attribute:: client_id
      :value: 'client-00000000000000000000000000000000'



   .. py:attribute:: address
      :value: 'tcp://localhost:5555'



   .. py:attribute:: resources


   .. py:attribute:: connect_kwargs


   .. py:attribute:: default_timeout
      :value: 5000



   .. py:attribute:: response_grace_ms
      :value: 1000



   .. py:attribute:: _connected
      :value: False



   .. py:attribute:: connection_info
      :value: None



   .. py:method:: set_default_timeout(timeout_ms: int) -> None

      Change the receive timeout used by requests without their own.

      :param timeout_ms: New default receive timeout in milliseconds.



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

      Connect to the server, discover methods, and bind them locally.



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

      Close the socket and context without waiting for undelivered messages.

      The handshake to an absent server sits in the DEALER's queue forever;
      with the default infinite LINGER, ``ctx.term()`` then blocks forever
      too — a connect to a dead server never returned, and no deadline could
      bound it. Linger 0 drops what could not be delivered.



   .. py:method:: _send(payload)

      Send a request to the server and wait for response.

      :param payload: Dictionary payload.

      :returns: Result from server.
      :rtype: Any

      :raises RuntimeError: If server returns an error.
      :raises TimeoutError: If no response is received.



   .. py:method:: connect_to_server() -> Any

      Send a handshake so the server can register client metadata.



   .. py:method:: disconnect_from_server() -> Any

      Release server-side allocations for this client.



   .. py:method:: _resolve_recv_timeout_ms(payload_timeout_s)

      Convert per-request operation timeout (seconds) into socket receive timeout (ms).

      A small grace window is added so the client still receives timeout/error
      responses sent by the server right after operation timeout is reached.



   .. py:method:: query(param: Any, timeout: Any = None) -> Any

      Query a device parameter.

      :param param: Parameter name.
      :param timeout: Optional timeout in seconds (server-side).

      :returns: Parameter value.
      :rtype: Any



   .. py:method:: write(param: Any, value: Any, timeout: Any = None) -> Any

      Write a device parameter.

      :param param: Parameter name.
      :param value: Value to set.
      :param timeout: Optional timeout in seconds (server-side).

      :returns: Result from device.
      :rtype: Any



   .. py:method:: call(func: Any, *args: Any, timeout: Any = None, **kwargs: Any) -> Any

      Call a remote device function.

      :param func: Function name.
      :param args: Positional arguments.
      :param timeout: Optional timeout in seconds (server-side).
      :param kwargs: Keyword arguments.

      :returns: Function result.
      :rtype: Any



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

      Retrieve available device methods from server.

      :returns: Device description.
      :rtype: dict



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

      Release server-side allocations and close local ZMQ resources.



   .. py:method:: __enter__()

      Enter the client context manager.



   .. py:method:: __exit__(exc_type, exc_value, traceback)

      Exit the client context manager, closing the connection.



   .. py:method:: _build_methods()

      Dynamically attach remote methods as local methods.



   .. py:method:: _make_proxy(name)

      Create a proxy method for a remote function.

      :param name: Function name.

      :returns: Proxy method.
      :rtype: callable