From 2e0e05648945fce931bec579073e62ac2deb83e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Wed, 2 Oct 2024 07:10:34 +0200 Subject: [PATCH 1/4] adds sio_client_kwargs as pydase.Client keyword argument --- src/pydase/client/client.py | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/src/pydase/client/client.py b/src/pydase/client/client.py index 6827edc..61e3291 100644 --- a/src/pydase/client/client.py +++ b/src/pydase/client/client.py @@ -2,7 +2,7 @@ import asyncio import logging import sys import threading -from typing import TYPE_CHECKING, TypedDict, cast +from typing import TYPE_CHECKING, Any, TypedDict, cast import socketio # type: ignore @@ -45,15 +45,35 @@ class Client: url: The URL of the pydase Socket.IO server. This should always contain the protocol and the hostname. - - Examples: - - - `wss://my-service.example.com` # for secure connections, use wss - - `ws://localhost:8001` block_until_connected: If set to True, the constructor will block until the connection to the service has been established. This is useful for ensuring the client is ready to use immediately after instantiation. Default is True. + sio_client_kwargs: + Additional keyword arguments passed to the underlying + [`AsyncClient`][socketio.AsyncClient]. This allows fine-tuning of the + client's behaviour (e.g., reconnection attempts or reconnection delay). + Default is an empty dictionary. + + Example: + The following example demonstrates a `Client` instance that connects to another + pydase service, while customising some of the connection settings for the + underlying [`AsyncClient`][socketio.AsyncClient]. + + ```python + pydase.Client(url="ws://localhost:8001", sio_client_kwargs={ + "reconnection_attempts": 2, + "reconnection_delay": 2, + "reconnection_delay_max": 8, + }) + ``` + + When connecting to a server over a secure connection (i.e., the server is using + SSL/TLS encryption), make sure that the `wss` protocol is used instead of `ws`: + + ```python + pydase.Client(url="wss://my-service.example.com") + ``` """ def __init__( @@ -61,9 +81,10 @@ class Client: *, url: str, block_until_connected: bool = True, + sio_client_kwargs: dict[str, Any] = {}, ): self._url = url - self._sio = socketio.AsyncClient() + self._sio = socketio.AsyncClient(**sio_client_kwargs) self._loop = asyncio.new_event_loop() self.proxy = ProxyClass(sio_client=self._sio, loop=self._loop) """A proxy object representing the remote service, facilitating interaction as From f2f330dbd942c6ca20568c0fc708eee59a87bb1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Wed, 2 Oct 2024 07:10:53 +0200 Subject: [PATCH 2/4] docs: adds python-socketio object inventory --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 8ce6546..b360f0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,7 @@ plugins: - https://docs.python.org/3/objects.inv - https://docs.pydantic.dev/latest/objects.inv - https://confz.readthedocs.io/en/latest/objects.inv + - https://python-socketio.readthedocs.io/en/stable/objects.inv options: show_source: true inherited_members: true From 5ec7a8b530906ba63f10f3bb616d18578cab7af9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Wed, 2 Oct 2024 07:27:13 +0200 Subject: [PATCH 3/4] docs: updates Python Client user guide --- docs/user-guide/interaction/Python Client.md | 68 ++++++++++++++------ 1 file changed, 47 insertions(+), 21 deletions(-) diff --git a/docs/user-guide/interaction/Python Client.md b/docs/user-guide/interaction/Python Client.md index a1865bd..2878ce4 100644 --- a/docs/user-guide/interaction/Python Client.md +++ b/docs/user-guide/interaction/Python Client.md @@ -1,60 +1,86 @@ # Python RPC Client -You can connect to the service using the `pydase.Client`. Below is an example of how to establish a connection to a service and interact with it: +The [`pydase.Client`][pydase.Client] allows you to connect to a remote `pydase` service using socket.io, facilitating interaction with the service as though it were running locally. + +## Basic Usage ```python import pydase -# Replace the hostname and port with the IP address and the port of the machine where -# the service is running, respectively +# Replace and with the appropriate values for your service client_proxy = pydase.Client(url="ws://:").proxy -# client_proxy = pydase.Client(url="wss://your-domain.ch").proxy # if your service uses ssl-encryption +# For SSL-encrypted services, use the wss protocol +# client_proxy = pydase.Client(url="wss://your-domain.ch").proxy # Interact with the service attributes as if they were local client_proxy.voltage = 5.0 print(client_proxy.voltage) # Expected output: 5.0 ``` -This example demonstrates setting and retrieving the `voltage` attribute through the client proxy. -The proxy acts as a local representative of the remote service, enabling straightforward interaction. +This example shows how to set and retrieve the `voltage` attribute through the client proxy. +The proxy acts as a local representation of the remote service, enabling intuitive interaction. -The proxy class dynamically synchronizes with the server's exposed attributes. This synchronization allows the proxy to be automatically updated with any attributes or methods that the server exposes, essentially mirroring the server's API. This dynamic updating enables users to interact with the remote service as if they were working with a local object. +The proxy class automatically synchronizes with the server's attributes and methods, keeping itself up-to-date with any changes. This dynamic synchronization essentially mirrors the server's API, making it feel like you're working with a local object. -## Context Manager +## Context Manager Support -You can also use the client as a context manager which automatically opens and closes the connection again: +You can also use the client within a context manager, which automatically handles connection management (i.e., opening and closing the connection): ```python import pydase with pydase.Client(url="ws://localhost:8001") as client: - client.proxy.() + client.proxy.my_method() ``` +Using the context manager ensures that connections are cleanly closed once the block of code finishes executing. ## Tab Completion Support -In interactive environments such as Python interpreters and Jupyter notebooks, the proxy class supports tab completion, which allows users to explore available methods and attributes. +In interactive environments like Python interpreters or Jupyter notebooks, the proxy supports tab completion. This allows users to explore available methods and attributes. -## Integration within Other Services +## Integrating the Client into Another Service -You can also integrate a client proxy within another service. Here's how you can set it up: +You can integrate a `pydase` client proxy within another service. Here's an example of how to set this up: ```python import pydase class MyService(pydase.DataService): - # Initialize the client without blocking the constructor - proxy = pydase.Client(url="ws://:", block_until_connected=False).proxy - # proxy = pydase.Client(url="wss://your-domain.ch", block_until_connected=False).proxy # communicating with ssl-encrypted service + proxy = pydase.Client( + url="ws://:", + block_until_connected=False + ).proxy + # For SSL-encrypted services, use the wss protocol + # proxy = pydase.Client( + # url="wss://your-domain.ch", + # block_until_connected=False + # ).proxy if __name__ == "__main__": service = MyService() - # Create a server that exposes this service; adjust the web_port as needed - server = pydase.Server(service, web_port=8002). run() + # Create a server that exposes this service + server = pydase.Server(service, web_port=8002).run() ``` -In this setup, the `MyService` class has a `proxy` attribute that connects to a `pydase` service located at `:8001`. -The `block_until_connected=False` argument allows the service to start up even if the initial connection attempt fails. -This configuration is particularly useful in distributed systems where services may start in any order. +In this example: +- The `MyService` class has a `proxy` attribute that connects to a `pydase` service at `:`. +- By setting `block_until_connected=False`, the service can start without waiting for the connection to succeed, which is particularly useful in distributed systems where services may initialize in any order. + +## Custom `socketio.AsyncClient` Connection Parameters + +You can also configure advanced connection options by passing additional arguments to the underlying [`AsyncClient`][socketio.AsyncClient] via `sio_client_kwargs`. This allows you to fine-tune reconnection behaviour, delays, and other settings: + +```python +client = pydase.Client( + url="ws://localhost:8001", + sio_client_kwargs={ + "reconnection_attempts": 3, + "reconnection_delay": 2, + "reconnection_delay_max": 10, + } +).proxy +``` + +In this setup, the client will attempt to reconnect three times, with an initial delay of 2 seconds (each successive attempt doubles this delay) and a maximum delay of 10 seconds between attempts. From 9eedf03c0149343f7cfde5e1ee84ab2a82ce627e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mose=20M=C3=BCller?= Date: Wed, 2 Oct 2024 09:18:32 +0200 Subject: [PATCH 4/4] adds reconnection method to proxy class which is called when the sio client does not reconnect --- src/pydase/client/client.py | 4 +- src/pydase/client/proxy_class.py | 13 +++- tests/client/test_reconnection.py | 107 ++++++++++++++++++++++++++++++ 3 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 tests/client/test_reconnection.py diff --git a/src/pydase/client/client.py b/src/pydase/client/client.py index 61e3291..29f0d68 100644 --- a/src/pydase/client/client.py +++ b/src/pydase/client/client.py @@ -86,7 +86,9 @@ class Client: self._url = url self._sio = socketio.AsyncClient(**sio_client_kwargs) self._loop = asyncio.new_event_loop() - self.proxy = ProxyClass(sio_client=self._sio, loop=self._loop) + self.proxy = ProxyClass( + sio_client=self._sio, loop=self._loop, reconnect=self.connect + ) """A proxy object representing the remote service, facilitating interaction as if it were local.""" self._thread = threading.Thread( diff --git a/src/pydase/client/proxy_class.py b/src/pydase/client/proxy_class.py index 5295823..422dd2d 100644 --- a/src/pydase/client/proxy_class.py +++ b/src/pydase/client/proxy_class.py @@ -1,5 +1,6 @@ import asyncio import logging +from collections.abc import Callable from copy import deepcopy from typing import TYPE_CHECKING, cast @@ -24,6 +25,8 @@ class ProxyClass(ProxyClassMixin, pydase.components.DeviceConnection): pydase service server. loop: The event loop in which the client operations are managed and executed. + reconnect: + The method that is called periodically when the client is not connected. This class is used to create a proxy object that behaves like a local representation of a remote pydase service, facilitating direct interaction as if it were local @@ -47,7 +50,10 @@ class ProxyClass(ProxyClassMixin, pydase.components.DeviceConnection): """ def __init__( - self, sio_client: socketio.AsyncClient, loop: asyncio.AbstractEventLoop + self, + sio_client: socketio.AsyncClient, + loop: asyncio.AbstractEventLoop, + reconnect: Callable[..., None], ) -> None: if TYPE_CHECKING: self._service_representation: None | SerializedObject = None @@ -56,6 +62,7 @@ class ProxyClass(ProxyClassMixin, pydase.components.DeviceConnection): pydase.components.DeviceConnection.__init__(self) self._initialise(sio_client=sio_client, loop=loop) object.__setattr__(self, "_service_representation", None) + self.reconnect = reconnect def serialize(self) -> SerializedObject: if self._service_representation is None: @@ -99,3 +106,7 @@ class ProxyClass(ProxyClassMixin, pydase.components.DeviceConnection): "readonly": readonly, "doc": doc, } + + def connect(self) -> None: + if not self._sio.reconnection or self._sio.reconnection_attempts > 0: + self.reconnect(block_until_connected=False) diff --git a/tests/client/test_reconnection.py b/tests/client/test_reconnection.py new file mode 100644 index 0000000..3ecce91 --- /dev/null +++ b/tests/client/test_reconnection.py @@ -0,0 +1,107 @@ +import threading +from collections.abc import Callable, Generator +from typing import Any + +import pydase +import pytest +import socketio.exceptions + + +@pytest.fixture(scope="function") +def pydase_restartable_server() -> ( + Generator[ + tuple[ + pydase.Server, + threading.Thread, + pydase.DataService, + Callable[ + [pydase.Server, threading.Thread, pydase.DataService], + tuple[pydase.Server, threading.Thread], + ], + ], + None, + Any, + ] +): + class MyService(pydase.DataService): + def __init__(self) -> None: + super().__init__() + self._name = "MyService" + self._my_property = 12.1 + + @property + def my_property(self) -> float: + return self._my_property + + @my_property.setter + def my_property(self, value: float) -> None: + self._my_property = value + + @property + def name(self) -> str: + return self._name + + service_instance = MyService() + server = pydase.Server(service_instance, web_port=9999) + thread = threading.Thread(target=server.run, daemon=True) + thread.start() + + def restart( + server: pydase.Server, + thread: threading.Thread, + service_instance: pydase.DataService, + ) -> tuple[pydase.Server, threading.Thread]: + server.handle_exit() + thread.join() + + server = pydase.Server(service_instance, web_port=9999) + new_thread = threading.Thread(target=server.run, daemon=True) + new_thread.start() + + return server, new_thread + + yield server, thread, service_instance, restart + + server.handle_exit() + thread.join() + + +def test_reconnection( + pydase_restartable_server: tuple[ + pydase.Server, + threading.Thread, + pydase.DataService, + Callable[ + [pydase.Server, threading.Thread, pydase.DataService], + tuple[pydase.Server, threading.Thread], + ], + ], +) -> None: + client = pydase.Client( + url="ws://localhost:9999", + sio_client_kwargs={ + "reconnection": False, + }, + ) + client_2 = pydase.Client( + url="ws://localhost:9999", + sio_client_kwargs={ + "reconnection_attempts": 1, + }, + ) + + server, thread, service_instance, restart = pydase_restartable_server + service_instance._name = "New service name" + + server, thread = restart(server, thread, service_instance) + + with pytest.raises(socketio.exceptions.BadNamespaceError): + client.proxy.name + client_2.proxy.name + + client.proxy.reconnect() + client_2.proxy.reconnect() + + # the service proxies successfully reconnect and get the new service name + assert client.proxy.name == "New service name" + assert client_2.proxy.name == "New service name"